{"row":{"id":"ADR-132","title":"Identity, idempotency and protocol: what a duplicate human action yields, and the resident's writer stamp","file":"adr-132-identity-idempotency-protocol.md","status":"accepted","date":"2026-09-04","cites":7,"supersedes":[],"superseded_by":[],"layers":["L4"],"tags":["architecture","one-door","idempotency","protocol"],"room":true},"pin":{"release_tag":"v0.118.7","commit":"f3a31a6ee00766e4b010379c535bca994631d637"}}

[{"k":"h","depth":1,"text":"ADR-132: Identity, idempotency and protocol","id":"adr-132-identity-idempotency-and-protocol"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"A remote surface retries. The one-door program asked what a duplicate\nhuman action yields on every door, and what protects a resident's\ndurable stores across an engine upgrade (#1352: an "},{"k":"code","text":"npm update"},{"k":"text","text":" left a\n0.117 resident firing schedules while a 0.118 SDK did manual runs, and\nnothing said so). This ADR records the audit of what is already law on\n"},{"k":"code","text":"main"},{"k":"text","text":", and decides the one gap it found."}]},{"k":"h","depth":2,"text":"What is already law (MAIN · audited 2026-09-04)","id":"what-is-already-law-main--audited-2026-09-04"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"action · identity · a duplicate yields · where"}],[{"k":"text","text":"a gate answer on `--resume` · the approval ticket (`content_hash` · `run_nonce` · `step` · `minted_at_ms` · `ttl_seconds`) journaled on the pause frame, its digest claimed once under `\u0024HOME/.nika/approval-claims` (per user, across projects; the digest carries the run nonce) · a settled gate: « this gate already settled · a decided gate stays decided » (ENV) · an expired ticket: the gate re-mints and asks again · a cross-run replay: refused `NIKA-SEC-010` · a consumed ticket: `approval.replayed` `NIKA-SEC-010` · `nika-dap::resume` · `nika-runtime::approval` · `resume_setup.rs` (the durable claim root)"}],[{"k":"text","text":"a session consent · the change set's witnesses (the bytes previewed) · after the file changed on disk: « changed since this preview — nothing was applied » · twice: « nothing is pending » · `nika-session::change` · `runtime::consent`"}],[{"k":"text","text":"a session gate answer · the pending gate · twice: « no run is waiting for an answer » · `runtime::answer_gate`"}],[{"k":"text","text":"a job cancel · the job's status transition · on a settled job: the record, unchanged (200) · a lost race: the current record · `nika-serve` `route::cancel_job`"}],[{"k":"text","text":"a job submission · `Idempotency-Key` + the request digest · the same bytes: the existing job (200) · other bytes: 409 · `JobStore::create_or_replay`"}],[{"k":"text","text":"a schedule apply · the schedule revision + an ETag precondition · the same draft: `Unchanged` · a stale revision: precondition failed · `ScheduleStore::apply`"}],[{"k":"text","text":"an event stream reconnect · the per-job `sequence` + `Last-Event-ID` · replays only persisted events after that sequence · heartbeats are cursor-neutral · `nika-serve` `sse` · the OpenAPI"}],[{"k":"text","text":"an SDK against a resident · `machineProtocolVersion` on `/health` · an incompatible generation: the SDK refuses before any request · `nika-client` `engine-identity.ts`"}]]},{"k":"p","inline":[{"k":"text","text":"The wave-7 gauntlet's reading « the TTL has no reader » was true of the\n0.117.1 it measured and false on "},{"k":"code","text":"main"},{"k":"text","text":" since wave 7.f: the book judges\nthe ticket's nonce, freshness and consumption. Nothing here is built\ntwice."}]},{"k":"h","depth":2,"text":"Decision (the gap)","id":"decision-the-gap"},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"The writer's stamp."},{"k":"text","text":" Both resident stores ("},{"k":"code","text":"jobs/state.json"},{"k":"text","text":" ·\n"},{"k":"code","text":"schedules/state.json"},{"k":"text","text":") carry "},{"k":"code","text":"writer: {engine_version, machine_protocol_version}"},{"k":"text","text":". The RESIDENT stamps them once it holds\nthe server lease ("},{"k":"code","text":"WriterStamp"},{"k":"text","text":" · "},{"k":"code","text":"nika-serve::writer"},{"k":"text","text":"); opening a\nstore never stamps it (the freeze audit of 2026-09-04 moved the stamp\nafter the lease: a second start that loses the lease never rewrites\nthe live resident's writer). A store from before the stamp carries\nnone and is served, then stamped by the next resident."}],[{"k":"strong","text":"Fail closed on a newer protocol."},{"k":"text","text":" A store last written by an engine\nspeaking a NEWER machine protocol refuses to open\n("},{"k":"code","text":"WrittenByNewerEngine"},{"k":"text","text":", naming both engines): its state is not ours\nto reinterpret. An older writer on the same protocol is served."}],[{"k":"strong","text":"The resident line."},{"k":"text","text":" "},{"k":"code","text":"nika doctor"},{"k":"text","text":" reads the stamps beside the\nserver lease ("},{"k":"code","text":"nika-serve::resident::inspect"},{"k":"text","text":" · a non-blocking shared\n"},{"k":"code","text":"flock"},{"k":"text","text":" on "},{"k":"code","text":"jobs/server.lock"},{"k":"text","text":": held → alive) and says whether the\nrunning resident is this binary: "},{"k":"code","text":"✔ alive · engine X (this binary)"},{"k":"text","text":" ·\n"},{"k":"code","text":"⚠ alive · engine X — this binary is Y: restart the resident"},{"k":"text","text":" ·\n"},{"k":"code","text":"✖ alive · newer than this binary"},{"k":"text","text":" · "},{"k":"code","text":"not running · stores last written by X"},{"k":"text","text":". The host renders ("},{"k":"code","text":"doctor::run_with"},{"k":"text","text":"), the binary\nobserves: "},{"k":"code","text":"nika-cli-host"},{"k":"text","text":" never depends on "},{"k":"code","text":"nika-serve"},{"k":"text","text":"."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Positive: a resident-vs-binary skew is a doctor line, not a silent\ndrift; a newer engine's state is never reinterpreted; every duplicate\nhuman action already yields a semantic reply on every door."}],[{"k":"text","text":"Negative: two fields on the stores' wire, additive for a 0.118 reader;\na 0.117 binary refuses a stamped store as unreadable\n("},{"k":"code","text":"deny_unknown_fields"},{"k":"text","text":" · « state is not valid JSON ») and cannot name\nthe newer writer, so a downgrade is a hard stop said as corruption; one\nmore doctor line when a store exists. The stamp is the WIRE clock\n("},{"k":"code","text":"machine_protocol_version"},{"k":"text","text":"); the stores' own format is "},{"k":"code","text":"version"},{"k":"text","text":"\ninside each file (jobs 3 · schedules 1), judged separately."}],[{"k":"text","text":"Follow-ups: the session's replies as typed outcomes (ADR-133)."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Refusing any version skew at open: rejected — an older writer on the\nsame protocol is exactly the upgrade path; the stamp refreshes."}],[{"k":"text","text":"A resident-side check of the SDK's version: rejected — the SDK\npre-flights "},{"k":"code","text":"/health"},{"k":"text","text":" already (one handshake, client-side)."}]]}]

ADR-132

Identity, idempotency and protocol: what a duplicate human action yields, and the resident's writer stamp

accepted · 2026-09-04 · L4 · cites 7

ADR-132: Identity, idempotency and protocol #

Context #

A remote surface retries. The one-door program asked what a duplicate human action yields on every door, and what protects a resident's durable stores across an engine upgrade (#1352: an npm update left a 0.117 resident firing schedules while a 0.118 SDK did manual runs, and nothing said so). This ADR records the audit of what is already law on main, and decides the one gap it found.

What is already law (MAIN · audited 2026-09-04) #

action · identity · a duplicate yields · where
a gate answer on `--resume` · the approval ticket (`content_hash` · `run_nonce` · `step` · `minted_at_ms` · `ttl_seconds`) journaled on the pause frame, its digest claimed once under `$HOME/.nika/approval-claims` (per user, across projects; the digest carries the run nonce) · a settled gate: « this gate already settled · a decided gate stays decided » (ENV) · an expired ticket: the gate re-mints and asks again · a cross-run replay: refused `NIKA-SEC-010` · a consumed ticket: `approval.replayed` `NIKA-SEC-010` · `nika-dap::resume` · `nika-runtime::approval` · `resume_setup.rs` (the durable claim root)
a session consent · the change set's witnesses (the bytes previewed) · after the file changed on disk: « changed since this preview — nothing was applied » · twice: « nothing is pending » · `nika-session::change` · `runtime::consent`
a session gate answer · the pending gate · twice: « no run is waiting for an answer » · `runtime::answer_gate`
a job cancel · the job's status transition · on a settled job: the record, unchanged (200) · a lost race: the current record · `nika-serve` `route::cancel_job`
a job submission · `Idempotency-Key` + the request digest · the same bytes: the existing job (200) · other bytes: 409 · `JobStore::create_or_replay`
a schedule apply · the schedule revision + an ETag precondition · the same draft: `Unchanged` · a stale revision: precondition failed · `ScheduleStore::apply`
an event stream reconnect · the per-job `sequence` + `Last-Event-ID` · replays only persisted events after that sequence · heartbeats are cursor-neutral · `nika-serve` `sse` · the OpenAPI
an SDK against a resident · `machineProtocolVersion` on `/health` · an incompatible generation: the SDK refuses before any request · `nika-client` `engine-identity.ts`

The wave-7 gauntlet's reading « the TTL has no reader » was true of the 0.117.1 it measured and false on main since wave 7.f: the book judges the ticket's nonce, freshness and consumption. Nothing here is built twice.

Decision (the gap) #

The writer's stamp. Both resident stores (jobs/state.json · schedules/state.json) carry writer: {engine_version, machine_protocol_version}. The RESIDENT stamps them once it holds the server lease (WriterStamp · nika-serve::writer); opening a store never stamps it (the freeze audit of 2026-09-04 moved the stamp after the lease: a second start that loses the lease never rewrites the live resident's writer). A store from before the stamp carries none and is served, then stamped by the next resident.
Fail closed on a newer protocol. A store last written by an engine speaking a NEWER machine protocol refuses to open (WrittenByNewerEngine, naming both engines): its state is not ours to reinterpret. An older writer on the same protocol is served.
The resident line. nika doctor reads the stamps beside the server lease (nika-serve::resident::inspect · a non-blocking shared flock on jobs/server.lock: held → alive) and says whether the running resident is this binary: ✔ alive · engine X (this binary) · ⚠ alive · engine X — this binary is Y: restart the resident · ✖ alive · newer than this binary · not running · stores last written by X. The host renders (doctor::run_with), the binary observes: nika-cli-host never depends on nika-serve.

Consequences #

Positive: a resident-vs-binary skew is a doctor line, not a silent drift; a newer engine's state is never reinterpreted; every duplicate human action already yields a semantic reply on every door.
Negative: two fields on the stores' wire, additive for a 0.118 reader; a 0.117 binary refuses a stamped store as unreadable (deny_unknown_fields · « state is not valid JSON ») and cannot name the newer writer, so a downgrade is a hard stop said as corruption; one more doctor line when a store exists. The stamp is the WIRE clock (machine_protocol_version); the stores' own format is version inside each file (jobs 3 · schedules 1), judged separately.
Follow-ups: the session's replies as typed outcomes (ADR-133).

Alternatives considered #

Refusing any version skew at open: rejected — an older writer on the same protocol is exactly the upgrade path; the stamp refreshes.
A resident-side check of the SDK's version: rejected — the SDK pre-flights /health already (one handshake, client-side).

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

Every decision, with its status This one in the repo