docs(#4671): lock the config-resolution and CLI-encoding design — Phase 0 of #4633 (#4829)

Browse Source

* docs(#4671): lock the config-resolution and CLI-encoding design

Amend ADR-1411 in place with the design contract for epic #4633: one
per-key resolution owner that returns the producing layer, two declared
configuration families with no precedence invented between them, one
parser and one encoder at the config-get boundary, a round-trip property
scoped to what raw output can actually carry, and the migration census,
child boundaries and anti-divergence guard spec.

Every claim about current behaviour was reproduced on next at c9a5cc3e1
in a hermetic fixture. Two corrections to the epic's framing: #4382 is
not a separate double-encoding defect (a present array already emits a
real JSON array — its own repro uses --default, the same defect as
#4262), and --default is already correct under --raw, so the disagreement
is confined to the JSON arm.

Docs-only. No runtime code, configuration behaviour or generated
artifact changes; every absorbed symptom stays live until the code
children land.

Closes #4671

* docs(#4671): close the migration-census gap and rule Decision 4

Review found the Decision-5 census missing model-resolver.cts's
projectExplicitlySetsOmit() (a workstream->root precedence walk, same
class as the six listed Family A implementations) and flagged init.cts's
readConfigJsonBoolean/readConfigJsonValue as a plausible second gap
(single-layer reads, same class as the listed single-layer readers).
Verified init.cts directly: confirmed real, added.

Decision 4 asked for an explicit maintainer ruling on raw-mode losslessness.
Ruled: freeze --raw as documented (display/shell-interpolation contract,
lossy for non-scalars). A lossless --raw stays out of scope, its own
future issue.

* docs(#4671): qualify config resolution guarantees

Distinguish correct classification from precedence guarantees and freeze raw as lossy output.

---------

Co-authored-by: Tom Boucher <trekkie@nomorestars.com>

...

This commit is contained in:

Michel Moreira

2026-09-23 18:30:26 -03:00

committed by GitHub

parent 6486647626

commit 17bf25a3d2

2 changed files with 272 additions and 1 deletions

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download Patch File Download Diff File Expand all files Collapse all files

2

CONTEXT.md

File diff suppressed because one or more lines are too long