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:
managedhashes the whole file. So any key the application adds isdrift, and a stale entry plans the whole file'sdelete(generation/plan.py:106-107,apply.py:64-67).blockneeds 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."Artifactgainskeys: Mapping[str, Any] | None = None, which maps a dotted key path to its value.- Paths use the
DictUtilsdotted 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.
- Paths use the
__post_init__raisesValueErrornaming the path when:- the kind is
KEYSbutkeysisNoneor empty, or the kind is notKEYSandkeysis set; - a
KEYSartifact has non-emptycontent; - a
KEYSartifact's path suffix does not resolve toConfigFormat.JSONorConfigFormat.TOML.
- the kind is
Artifact.keyfor 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 failplan's duplicate-key check.- The
Action.INSERTandAction.REMOVEdocstrings 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_hashfor a keys artifact isContentHash.ofthat string. StateEntrygainskey_paths: tuple[str, ...] | None = None.to_entryfor a keys artifact recordscontent_hashandkey_paths, the artifact's paths sorted.from_dictreads 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 intentremove. It never plansdelete.
- File absent:
difffor a keys change is the unified diff of the whole file's text, before and after the change is rendered.diffgains a keywordentries: 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:
_composerefuses a path claimed both by a keys change and by any other change (in practice a block). It raisesAppExceptionin the same form as today's whole-and-block check.- A new
_render_keys(root, change, previous)reads the file withDocumentUtils.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_pathsthat the artifact no longer owns. Forremove, that is all of them. - prunes any table left empty by a deletion;
- raises
AppExceptionnaming 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 textwrite_documentwould write.write_documentis refactored to call it. JSON keeps today's_json_documentform: 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.
- JSON and TOML, both parametrized: from an absent file, apply creates it
holding exactly the owned keys. A second plan is
unchanged. - 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. - A key added by hand outside the owned paths after apply plans
unchanged. - 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. - A list value appended to by hand plans
drift: lists compare whole. - A render that drops one owned path plans
update. Apply removes that key, prunes a table left empty, and records the remainingkey_paths. - A render with no keys artifact for the file plans
remove, neverdelete. Apply strips every owned key and keeps the file and its unowned keys. - The file deleted after apply plans
missing. Artifactvalidation: a missing or emptykeys,contentset,keyson another kind, and a.yamlpath each raiseValueErrornaming the path.- A keys change and a block change on one path raise the
_composeAppException. A keys and a managed artifact on one path raiseplan's duplicate-keyAppException. - A
managedentry at the path of a new keys artifact plansconflict. Forced, apply sets the owned keys and keeps the others. - An owned path through a non-table on disk raises
AppExceptionnaming the path. Rollback leaves the file and state as they were. - A state file written before this change, whose entries have no
key_paths, loads and plans exactly as before (TestStateEntryParsing). diffof a keysupdate, 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.mdgains a "Key paths in a shared file" section, with one worked JSON example.docs/reference/generation.mdlistsArtifactKind.KEYS,Artifact.keysandStateEntry.key_paths.CHANGELOG.md[Unreleased]→### Addednames the kind andDocumentUtils.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.tomlversion = "0.10.1".CHANGELOG.mdhas a[0.10.1]heading, dated with the merge day, holding the[Unreleased]entries.rn-forge-devops requirementspasses with no dependent's ceiling changed. Everyrn-forge-commonsrange in the workspace still reads<0.11.- After the release merge, the
rn-forge-commons-v0.10.1tag exists on the remote, andrn-forge-commons==0.10.1installs from PyPI into a clean environment, whereArtifactKind.KEYSimports.
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.