Skip to content

F27.1 — A keys artifact kind

State Closed
Parent E27
Iteration Release 11
Start Date 2026-11-20
Closed Date 2026-11-20
Predecessors —
Source owner 2026-11-19

Stories: 2 Closed

Story State Depends on
S27.1.1 — ArtifactKind.KEYS plans, diffs and applies Closed (2026-11-20) —
S27.1.2 — Prepare rn-forge-commons 0.10.1 Closed (2026-11-20) S27.1.1

rn_forge.commons.generation gains ArtifactKind.KEYS: the generator owns a set of dotted key paths inside a JSON or TOML file whose other keys belong to someone else. Plan, diff and apply classify and write those paths, and only those paths, with the same staging, backup and rollback as every other kind. rn-forge-commons 0.10.1 releases it.

Context

A tool that configures another application, such as a coding agent's settings.json or a config.toml, must set a few keys in a file the application also rewrites. Neither existing kind fits that file:

  • managed hashes the whole file. So any key the application adds is drift, and a stale entry plans the whole file's delete (generation/plan.py:106-107, apply.py:64-67).
  • block needs comment markers, which JSON has none of.

Building this outside commons would mean every consumer re-classifying commons' plan, intercepting stale entries before apply deletes the file, and keeping the owned-path list in a second state store that apply's rollback does not restore. Hence a kind in the engine.

Design

Release. The change is additive, so under ADR-0004 it is a patch: rn-forge-commons 0.10.0 to 0.10.1. Every dependent's <0.11 ceiling already admits it, so no dependent is released with it.

Model, in generation/artifacts.py:

  • ArtifactKind.KEYS = "keys", documented as "The generator owns named key paths inside a JSON or TOML document another program also writes."
  • Artifact gains keys: Mapping[str, Any] | None = None, which maps a dotted key path to its value.
    • Paths use the DictUtils dotted form, with \. escaping a literal dot.
    • A value is any JSON- or TOML-serialisable value, and is owned whole: a list or a table is one value, compared and written as a unit.
  • __post_init__ raises ValueError naming the path when:
    • the kind is KEYS but keys is None or empty, or the kind is not KEYS and keys is set;
    • a KEYS artifact has non-empty content;
    • a KEYS artifact's path suffix does not resolve to ConfigFormat.JSON or ConfigFormat.TOML.
  • Artifact.key for a keys artifact is its path. So a file has at most one keys artifact, and a keys and a whole-file artifact on one path already fail plan's duplicate-key check.
  • The Action.INSERT and Action.REMOVE docstrings widen to cover owned keys as well as a block.
  • Canonical values: json.dumps(values, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str) of the {path: value} mapping. content_hash for a keys artifact is ContentHash.of that string.
  • StateEntry gains key_paths: tuple[str, ...] | None = None. to_entry for a keys artifact records content_hash and key_paths, the artifact's paths sorted. from_dict reads the field when present, and a state file without it loads as before.

Classification, in generation/plan.py. "Disk values" means the values the file currently holds at the recorded key_paths, read with DocumentUtils.read (a plain mapping), in canonical form. A path absent on disk is left out.

File Entry Disk values vs entry hash Action
absent none — create: a file holding only the owned keys
absent present — missing (blocking)
present none — insert: the owned keys are set and other keys left as they are, without --force
present present, not keys — conflict (blocking): forcing it sets the owned keys and leaves the rest
present present differ drift (blocking)
present present equal unchanged if the entry hash and key paths equal the artifact's, else update
  • A stale keys entry, one the render no longer produces:
    • File absent: forget.
    • Disk values equal the entry hash: remove.
    • Otherwise: drift, with intent remove. It never plans delete.
  • diff for a keys change is the unified diff of the whole file's text, before and after the change is rendered. diff gains a keyword entries: Mapping[str, StateEntry] | None = None, the previous state, so a dropped path shows as removed; a call without it behaves as today.

Apply, in generation/apply.py:

  • _compose refuses a path claimed both by a keys change and by any other change (in practice a block). It raises AppException in the same form as today's whole-and-block check.
  • A new _render_keys(root, change, previous) reads the file with DocumentUtils.read_document (round-trip: TOML keeps comments and order), or starts from an empty mapping when the file is absent. It then:
    • sets every owned path, creating missing intermediate tables;
    • deletes every path in the previous entry's key_paths that the artifact no longer owns. For remove, that is all of them.
    • prunes any table left empty by a deletion;
    • raises AppException naming the path when an intermediate segment on disk is not a table. It returns the text.
  • The text comes from a new DocumentUtils.serialize_document(path, document) -> str: the text write_document would write. write_document is refactored to call it. JSON keeps today's _json_document form: two-space indent, sorted keys, trailing newline. Key order is not preserved, and values are.
  • A file is never deleted by a keys change. Removing every owned key leaves whatever remains, {} included.

Out of scope: YAML, a keys artifact that shares a file with a block, and appending to a list rather than owning it whole.

S27.1.1 — ArtifactKind.KEYS plans, diffs and applies

State: Closed (2026-11-20)

Acceptance:

Tests go in packages/rn-forge-commons/tests/generation/test_generation.py, in a new class TestKeys after TestSeveralBlocksInOneFile. Use the file's run/store helpers and a keys(path, values) helper beside managed and block. Each is named test_s27_1_1_<n>_<what>, and each fails before the build.

  1. JSON and TOML, both parametrized: from an absent file, apply creates it holding exactly the owned keys. A second plan is unchanged.
  2. An existing file with no entry plans insert. Apply sets the owned keys, and every unowned key keeps its value. A TOML fixture with comments outside the owned tables keeps them byte for byte.
  3. A key added by hand outside the owned paths after apply plans unchanged.
  4. An owned value changed by hand plans drift. Apply refuses it without force. With the path forced, the file is backed up and the owned value restored.
  5. A list value appended to by hand plans drift: lists compare whole.
  6. A render that drops one owned path plans update. Apply removes that key, prunes a table left empty, and records the remaining key_paths.
  7. A render with no keys artifact for the file plans remove, never delete. Apply strips every owned key and keeps the file and its unowned keys.
  8. The file deleted after apply plans missing.
  9. Artifact validation: a missing or empty keys, content set, keys on another kind, and a .yaml path each raise ValueError naming the path.
  10. A keys change and a block change on one path raise the _compose AppException. A keys and a managed artifact on one path raise plan's duplicate-key AppException.
  11. A managed entry at the path of a new keys artifact plans conflict. Forced, apply sets the owned keys and keeps the others.
  12. An owned path through a non-table on disk raises AppException naming the path. Rollback leaves the file and state as they were.
  13. A state file written before this change, whose entries have no key_paths, loads and plans exactly as before (TestStateEntryParsing).
  14. diff of a keys update, given the entries, shows the changed owned value, a dropped path removed, and the file's other lines as context.

tests/fs/test_documents.py: serialize_document returns exactly what write_document writes, for TOML, YAML and JSON.

Docs:

  • packages/rn-forge-commons/docs/guides/generation.md gains a "Key paths in a shared file" section, with one worked JSON example.
  • docs/reference/generation.md lists ArtifactKind.KEYS, Artifact.keys and StateEntry.key_paths.
  • CHANGELOG.md [Unreleased] → ### Added names the kind and DocumentUtils.serialize_document.

Outcome: render_keys in generation/artifacts.py serves both diff and apply; key paths split with DictUtils' own _split_key_path.

S27.1.2 — Prepare rn-forge-commons 0.10.1

State: Closed (2026-11-20) · Depends on: S27.1.1

Acceptance:

  • packages/rn-forge-commons/pyproject.toml version = "0.10.1".
  • CHANGELOG.md has a [0.10.1] heading, dated with the merge day, holding the [Unreleased] entries.
  • rn-forge-devops requirements passes with no dependent's ceiling changed. Every rn-forge-commons range in the workspace still reads <0.11.
  • After the release merge, the rn-forge-commons-v0.10.1 tag exists on the remote, and rn-forge-commons==0.10.1 installs from PyPI into a clean environment, where ArtifactKind.KEYS imports.

Acceptance

set -euo pipefail

PYTEST_ADDOPTS='tests/generation/test_generation.py tests/fs/test_documents.py' \
  task test PACKAGE_DIRS=packages/rn-forge-commons   # S27.1.1: the fourteen cases, serialize_document
rg -q 'Key paths in a shared file' packages/rn-forge-commons/docs/guides/generation.md   # S27.1.1: guide section
rg -q '^version = "0.10.1"' packages/rn-forge-commons/pyproject.toml                     # S27.1.2: version
rg -q '^## \[0\.10\.1\]' packages/rn-forge-commons/CHANGELOG.md                          # S27.1.2: changelog heading

Not scriptable:

  • S27.1.2: the tag on the remote and the clean PyPI install, run after the release merge.