{"row":{"id":"ADR-113","title":"The envelope's identity moves onto `nika:` — the version slot dies, losslessly","file":"adr-113-envelope-identity-on-nika.md","status":"accepted","date":"2026-08-13","cites":2,"supersedes":[],"superseded_by":[],"layers":["L0","L4"],"tags":["envelope","grammar","parser","flag-day"],"room":true},"pin":{"release_tag":"v0.109.2","commit":"1da35b6859a8f54cd09cfed7ca0e35d1f40fe590"}}

[{"k":"h","depth":1,"text":"ADR-113: The envelope's identity moves onto `nika:`","id":"adr-113-the-envelopes-identity-moves-onto-nika"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"code","text":"nika-spec"},{"k":"text","text":" executed its envelope nuke on 2026-08-12 ("},{"k":"code","text":"d20b139"},{"k":"text","text":" · « l enveloppe\npasse de 13 cles a 9, nika porte l identite »). The engine had not followed."}]},{"k":"p","inline":[{"k":"text","text":"The gap was invisible because the engine is judged at a pinned spec commit\n("},{"k":"code","text":"SPEC_PIN"},{"k":"text","text":", consumed by "},{"k":"code","text":"diamond-ci.yml"},{"k":"text","text":"). At the time of writing that pin sat\n"},{"k":"strong","text":"44 commits behind"},{"k":"text","text":" "},{"k":"code","text":"nika-spec"},{"k":"text","text":" "},{"k":"code","text":"main"},{"k":"text","text":", so CI was green against a spec that\npredates the change. Pointing the conformance battery at the CURRENT spec made\nthe real state visible:"}]},{"k":"code","lang":"text","text":"NIKA_SPEC_DIR=<spec@main> cargo nextest run -p nika-check\n  → 4 suites failed · 172 diagnostic emissions · 172 of them NIKA-PARSE-003"},{"k":"p","inline":[{"k":"text","text":"Every one of 145 named fixtures died on the "},{"k":"code","text":"nika:"},{"k":"text","text":" line, before the engine\ncould reach the construct the fixture actually tests. One defect masked the\nentire next layer."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"code","text":"nika:"},{"k":"text","text":" carries BOTH the mark and the name. The KEY says "},{"k":"em","text":"this is a Nika file"},{"k":"text","text":";\nthe VALUE is the file's kebab-case id ("},{"k":"code","text":"^[a-z][a-z0-9-]*\u0024"},{"k":"text","text":")."}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"parse_nika_version"},{"k":"text","text":" → "},{"k":"code","text":"parse_nika_id"},{"k":"text","text":". The shape is judged on the NODE, not\nthrough "},{"k":"code","text":"get_scalar"},{"k":"text","text":": a mapping or sequence would otherwise read as ABSENT and\nthe id would go quietly missing instead of loudly wrong."}],[{"k":"code","text":"SchemaError::BadNikaVersion"},{"k":"text","text":" → "},{"k":"code","text":"BadNikaId"},{"k":"text","text":". "},{"k":"code","text":"NIKA-PARSE-003"},{"k":"text","text":" survives by\nchanging MEANING, and its CATEGORY moves with it — "},{"k":"code","text":"parse_error"},{"k":"text","text":" →\n"},{"k":"code","text":"validation_error"},{"k":"text","text":". Judging a version marker was the file's entry contract;\njudging a name is a spec-rule violation in well-formed input. The document\nparses; the name is wrong. (Spec fixture "},{"k":"code","text":"envelope/003-nika-id-bad-shape"},{"k":"text","text":"\npins the category, and it is what caught this.)"}],[{"k":"code","text":"workflow:"},{"k":"text","text":" and top-level "},{"k":"code","text":"description:"},{"k":"text","text":" leave "},{"k":"code","text":"TOP_LEVEL_KEYS"},{"k":"text","text":" and refuse as\nunknown keys ("},{"k":"code","text":"NIKA-PARSE-005"},{"k":"text","text":"). "},{"k":"code","text":"RawWorkflow.workflow"},{"k":"text","text":" now holds the value of\n"},{"k":"code","text":"nika:"},{"k":"text","text":" — so the ~5 downstream readers of the workflow id changed by zero\nlines."}],[{"k":"code","text":"NIKA-PARSE-004"},{"k":"text","text":" ("},{"k":"code","text":"BadWorkflowId"},{"k":"text","text":"), "},{"k":"code","text":"NIKA-PARSE-020"},{"k":"text","text":" ("},{"k":"code","text":"W1WorkflowScalar"},{"k":"text","text":") and\n"},{"k":"code","text":"NIKA-PARSE-021"},{"k":"text","text":" ("},{"k":"code","text":"W1TopLevelDescription"},{"k":"text","text":") are RETIRED. No retired code is\never reused (SSOT-2 B.22). "},{"k":"code","text":"SchemaVersion"},{"k":"text","text":" is deleted: a field with one legal\nvalue for the whole lifetime of the contract was never a version."}]]},{"k":"h","depth":3,"text":"W1's envelope half is retired with it","id":"w1s-envelope-half-is-retired-with-it"},{"k":"p","inline":[{"k":"code","text":"nika-migrate"},{"k":"text","text":"'s W1 codemod migrated "},{"k":"code","text":"workflow: <scalar>"},{"k":"text","text":" INTO\n"},{"k":"code","text":"workflow: { id, description }"},{"k":"text","text":" — precisely the object the parser now refuses.\nA repair whose output its own checker rejects is worse than no repair, so that\nhalf is removed and its "},{"k":"code","text":"--fix"},{"k":"text","text":" ladder arms with it. "},{"k":"strong","text":"The tasks half is\nuntouched"},{"k":"text","text":" (sequence → map · "},{"k":"code","text":"- id:"},{"k":"text","text":" → the key). The identity codemod is\nfollow-up work, and it must DEMOTE the "},{"k":"code","text":"description:"},{"k":"text","text":" prose (to a comment),\nnever silently drop it."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"p","inline":[{"k":"text","text":"Measured, not asserted:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"before · after"}],[{"k":"text","text":"conformance emissions (spec@main) · 172 · **16**"}],[{"k":"text","text":"`nika-check` suites failing · 4 · **3**"}],[{"k":"text","text":"workspace `--lib` · 5757 run · **5747 pass / 4 fail**"}]]},{"k":"p","inline":[{"k":"text","text":"The 16 remaining emissions are the next layer, now visible and small:\n"},{"k":"code","text":"group:"},{"k":"text","text":" ×7 · "},{"k":"code","text":"lift:"},{"k":"text","text":" ×2 · "},{"k":"code","text":"extract:"},{"k":"text","text":" ×1 · "},{"k":"code","text":"for_each"},{"k":"text","text":" block ×2 · "},{"k":"code","text":"unwind"},{"k":"text","text":" ×1 ·\nplus two unrelated. "},{"k":"strong","text":"`group:` was not in any plan"},{"k":"text","text":" — it arrived with spec\n"},{"k":"code","text":"450b476"},{"k":"text","text":" and only surfaced once the envelope stopped masking it."}]},{"k":"h","depth":3,"text":"The pack is all-or-nothing (the sequencing constraint this uncovered)","id":"the-pack-is-all-or-nothing-the-sequencing-constraint-this-uncovered"},{"k":"p","inline":[{"k":"text","text":"The 4 remaining workspace failures are all consumers of the VENDORED spec pack\n("},{"k":"code","text":"crates/nika-pack/pack/"},{"k":"text","text":"). "},{"k":"code","text":"scripts/sync-pack.sh"},{"k":"text","text":" moves whole directories with\n"},{"k":"code","text":"rsync --delete"},{"k":"text","text":", and the spec's pack uses "},{"k":"code","text":"lift:"},{"k":"text","text":" (2 files), "},{"k":"code","text":"extract:"},{"k":"text","text":" (9),\n"},{"k":"code","text":"max_parallel"},{"k":"text","text":"/"},{"k":"code","text":"fail_fast"},{"k":"text","text":" under "},{"k":"code","text":"for_each"},{"k":"text","text":" (9/8). So the pack can only resync\nonce the engine speaks the WHOLE new grammar."}]},{"k":"p","inline":[{"k":"strong","text":"Consequence: LOT 2's slices cannot each land green on their own."},{"k":"text","text":" The parser\nwork slices cleanly; the pack does not. This is a correction to the plan, found\nby measurement."}]},{"k":"h","depth":3,"text":"A second reader of `description:`","id":"a-second-reader-of-description"},{"k":"p","inline":[{"k":"text","text":"The spec's tombstone justified killing "},{"k":"code","text":"description:"},{"k":"text","text":" with « one consumer across\nfive reading surfaces ». There is a second: "},{"k":"code","text":"nika-onboard"},{"k":"text","text":"'s intent router\nindexes the description line ("},{"k":"code","text":"intent.rs:594"},{"k":"text","text":"), and the routing fixtures score\nagainst that exact wording — the query "},{"k":"code","text":"chase unpaid invoices"},{"k":"text","text":" IS\n"},{"k":"code","text":"invoice-chaser"},{"k":"text","text":"'s description. When the pack resyncs, routing quality drops and\n3 tests go red. Recorded here rather than patched silently."}]}]

ADR-113

The envelope's identity moves onto `nika:` — the version slot dies, losslessly

accepted · 2026-08-13 · L0 L4 · cites 2

ADR-113: The envelope's identity moves onto `nika:` #

Context #

nika-spec executed its envelope nuke on 2026-08-12 (d20b139 · « l enveloppe passe de 13 cles a 9, nika porte l identite »). The engine had not followed.

The gap was invisible because the engine is judged at a pinned spec commit (SPEC_PIN, consumed by diamond-ci.yml). At the time of writing that pin sat 44 commits behind nika-spec main, so CI was green against a spec that predates the change. Pointing the conformance battery at the CURRENT spec made the real state visible:

text

1NIKA_SPEC_DIR=<spec@main> cargo nextest run -p nika-check2  → 4 suites failed · 172 diagnostic emissions · 172 of them NIKA-PARSE-003

Every one of 145 named fixtures died on the nika: line, before the engine could reach the construct the fixture actually tests. One defect masked the entire next layer.

Decision #

nika: carries BOTH the mark and the name. The KEY says this is a Nika file; the VALUE is the file's kebab-case id (^[a-z][a-z0-9-]*$).

parse_nika_version → parse_nika_id. The shape is judged on the NODE, not through get_scalar: a mapping or sequence would otherwise read as ABSENT and the id would go quietly missing instead of loudly wrong.
SchemaError::BadNikaVersion → BadNikaId. NIKA-PARSE-003 survives by changing MEANING, and its CATEGORY moves with it — parse_error → validation_error. Judging a version marker was the file's entry contract; judging a name is a spec-rule violation in well-formed input. The document parses; the name is wrong. (Spec fixture envelope/003-nika-id-bad-shape pins the category, and it is what caught this.)
workflow: and top-level description: leave TOP_LEVEL_KEYS and refuse as unknown keys (NIKA-PARSE-005). RawWorkflow.workflow now holds the value of nika: — so the ~5 downstream readers of the workflow id changed by zero lines.
NIKA-PARSE-004 (BadWorkflowId), NIKA-PARSE-020 (W1WorkflowScalar) and NIKA-PARSE-021 (W1TopLevelDescription) are RETIRED. No retired code is ever reused (SSOT-2 B.22). SchemaVersion is deleted: a field with one legal value for the whole lifetime of the contract was never a version.

W1's envelope half is retired with it #

nika-migrate's W1 codemod migrated workflow: <scalar> INTO workflow: { id, description } — precisely the object the parser now refuses. A repair whose output its own checker rejects is worse than no repair, so that half is removed and its --fix ladder arms with it. The tasks half is untouched (sequence → map · - id: → the key). The identity codemod is follow-up work, and it must DEMOTE the description: prose (to a comment), never silently drop it.

Consequences #

Measured, not asserted:

before · after
conformance emissions (spec@main) · 172 · **16**
`nika-check` suites failing · 4 · **3**
workspace `--lib` · 5757 run · **5747 pass / 4 fail**

The 16 remaining emissions are the next layer, now visible and small: group: ×7 · lift: ×2 · extract: ×1 · for_each block ×2 · unwind ×1 · plus two unrelated. `group:` was not in any plan — it arrived with spec 450b476 and only surfaced once the envelope stopped masking it.

The pack is all-or-nothing (the sequencing constraint this uncovered) #

The 4 remaining workspace failures are all consumers of the VENDORED spec pack (crates/nika-pack/pack/). scripts/sync-pack.sh moves whole directories with rsync --delete, and the spec's pack uses lift: (2 files), extract: (9), max_parallel/fail_fast under for_each (9/8). So the pack can only resync once the engine speaks the WHOLE new grammar.

Consequence: LOT 2's slices cannot each land green on their own. The parser work slices cleanly; the pack does not. This is a correction to the plan, found by measurement.

A second reader of `description:` #

The spec's tombstone justified killing description: with « one consumer across five reading surfaces ». There is a second: nika-onboard's intent router indexes the description line (intent.rs:594), and the routing fixtures score against that exact wording — the query chase unpaid invoices IS invoice-chaser's description. When the pack resyncs, routing quality drops and 3 tests go red. Recorded here rather than patched silently.

read at v0.109.2 · the decision record ships with the engine

Every decision, with its status This one in the repo