{"row":{"id":"ADR-099","title":"Durable-lite run resume — the trace IS the checkpoint","file":"adr-099-durable-lite-run-resume.md","status":"accepted","date":"2026-07-05","cites":3,"supersedes":[],"superseded_by":[],"layers":["L2","L4"],"tags":["resume","durability","trace","cache-hit"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-099 — Durable-lite run resume · the trace IS the checkpoint","id":"adr-099--durable-lite-run-resume--the-trace-is-the-checkpoint"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Status"},{"k":"text","text":": Accepted (2026-07-05) — implemented by the engine\n"},{"k":"code","text":"feat/resume-impl"},{"k":"text","text":" arc: "},{"k":"code","text":"nika-runtime"},{"k":"text","text":" resume keys (JCS + blake3) +\nthe "},{"k":"code","text":"--resume"},{"k":"text","text":" skip fold + the pause rider · "},{"k":"code","text":"nika-cli run --resume"},{"k":"text","text":"\n/ "},{"k":"code","text":"--from"},{"k":"text","text":" / "},{"k":"code","text":"--answer"},{"k":"text","text":" · "},{"k":"code","text":"EventKind::{TaskCacheHit, WorkflowPaused}"},{"k":"text","text":"\n· exit code "},{"k":"code","text":"4"},{"k":"text","text":" ("},{"k":"code","text":"paused"},{"k":"text","text":") · the 3 conformance fixtures as engine\ne2e tests ("},{"k":"code","text":"crates/nika-cli/tests/resume_e2e.rs"},{"k":"text","text":")."}],[{"k":"strong","text":"Surface"},{"k":"text","text":": CLI + trace/event vocabulary ONLY. Zero envelope change ·\nzero new YAML · the 4-verbs and "},{"k":"code","text":"nika: v1"},{"k":"text","text":" locks are untouched."}],[{"k":"strong","text":"Home"},{"k":"text","text":": the CANONICAL prose lives in the "},{"k":"code","text":"nika-spec"},{"k":"text","text":" repo's "},{"k":"code","text":"adr/"},{"k":"text","text":"\n(language-surface decisions — the relative spec links below resolve\nTHERE); this copy registers the number in the shared Nika ADR series\n(the engine "},{"k":"code","text":"docs/adr/"},{"k":"text","text":" registry is the series' index)."}]]},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Durability is the largest capability gap the spec names about itself.\n"},{"k":"link","text":"08-out-of-scope","href":"../spec/08-out-of-scope.md"},{"k":"text","text":" holds four interlocking\ndeferrals: §Persistence defers workflow checkpointing/resumption (with a\n"},{"k":"code","text":"checkpoint:"},{"k":"text","text":"-block sketch), §Idempotency defers step dedup \"together\nwith the durable-execution waypoint\", H1 states plainly that "},{"k":"strong","text":"crash =\nre-run from the top"},{"k":"text","text":", and H5 admits the human gate's pause-state is\n"},{"k":"strong","text":"live"},{"k":"text","text":" (\"the run keeps a process while blocked · durable pauses arrive\nwith H1\"). Across the 2026 workflow-runner landscape, crash-resume and\nthe durable human gate are the two most-asked-for capabilities this\nclass of tool gets measured on — Nextflow's "},{"k":"code","text":"-resume"},{"k":"text","text":" (content-addressed\ntask skip) is that ecosystem's single most-loved feature, and it taxes\nauthors with nothing."}]},{"k":"p","inline":[{"k":"text","text":"Meanwhile the checkpoint artifact already exists. A conformant Runtime\nengine MUST emit the workflow event stream\n("},{"k":"link","text":"07 §Runtime-4","href":"../spec/07-conformance.md#level-2--runtime-conformance"},{"k":"text","text":"):\n"},{"k":"code","text":"task.completed"},{"k":"text","text":" records carry per-task outcome, and the reference\nengine journals every run as an NDJSON trace ("},{"k":"code","text":"crates/nika-event/src/kind.rs"},{"k":"text","text":"\nserializes the kinds snake_case: "},{"k":"code","text":"task_completed"},{"k":"text","text":" · and pre-reserves\n"},{"k":"code","text":"checkpoint_written"},{"k":"text","text":", \"a durable run state snapshot\"). What is missing\nis not a new runtime — it is a "},{"k":"strong","text":"reader"},{"k":"text","text":"."}]},{"k":"p","inline":[{"k":"text","text":"The trap to avoid is equally documented: Temporal-class durable\nexecution buys resume by imposing replay-determinism constraints on\nworkflow authors (code must be deterministic · side effects must be\nwrapped · histories version with the code). That tax is the single most\nhated property of the durable-execution class, and this spec's whole\nposture (audit-before-run · no hidden magic · the engine owns the how)\nforbids exporting it to authors."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"`nika run wf.nika.yaml --resume <trace>` re-executes a workflow,\nskipping every task whose identity matches a completed record in the\ngiven trace."},{"k":"text","text":" The trace is the run's own NDJSON journal — no second\nstore, no new artifact, no daemon."}]},{"k":"h","depth":3,"text":"1 · The skip rule — content-addressed · two hashes · both MUST match","id":"1--the-skip-rule--content-addressed--two-hashes--both-must-match"},{"k":"p","inline":[{"k":"text","text":"A task is skippable iff the trace holds a "},{"k":"code","text":"task.completed"},{"k":"text","text":" record whose"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"task-definition hash"},{"k":"text","text":" — a canonical serialization of the task's\nbehavior-bearing fields (the verb body · "},{"k":"code","text":"with:"},{"k":"text","text":" · "},{"k":"code","text":"output:"},{"k":"text","text":" ·\n"},{"k":"code","text":"retry:"},{"k":"text","text":" / "},{"k":"code","text":"on_error:"},{"k":"text","text":" / "},{"k":"code","text":"on_finally:"},{"k":"text","text":" · "},{"k":"code","text":"when:"},{"k":"text","text":" · "},{"k":"code","text":"for_each:"},{"k":"text","text":") —\nmatches the task as now written, AND"}],[{"k":"strong","text":"resolved-input hash"},{"k":"text","text":" — the values its "},{"k":"code","text":"\u0024{{ }}"},{"k":"text","text":" references resolved\nto at execution time (upstream outputs · "},{"k":"code","text":"vars"},{"k":"text","text":" · "},{"k":"code","text":"with"},{"k":"text","text":" · "},{"k":"code","text":"env"},{"k":"text","text":") —\nmatches the values the resumed run resolves."}]]},{"k":"p","inline":[{"k":"text","text":"Edit a prompt → that task re-runs. Change a var an early task consumes →\nit re-runs, and the mismatch cascades through resolved-input hashes\nexactly as far as the data actually flows — untouched siblings still\nskip. "},{"k":"code","text":"for_each"},{"k":"text","text":" tasks record per-iteration (the item participates in\nthe input hash), so a partially-completed fan-out resumes at the\niteration level."}]},{"k":"p","inline":[{"k":"strong","text":"Secrets participate by declared reference identity (name · declared\nsource path), never by value"},{"k":"text","text":" — masking is normative\n("},{"k":"link","text":"01 §envelope MUSTs","href":"../spec/01-envelope.md"},{"k":"text","text":") and a trace MUST NOT\ncarry secret-derived material, including value hashes (a hash of a\nlow-entropy secret is an oracle). Stated limit: a rotated secret does\nNOT invalidate the cache — force the affected node with "},{"k":"code","text":"--from"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"2 · The skip is VISIBLE — `task.cache_hit` · never silent","id":"2--the-skip-is-visible--taskcache_hit--never-silent"},{"k":"p","inline":[{"k":"text","text":"Each skipped task emits a "},{"k":"strong","text":"`task.cache_hit`"},{"k":"text","text":" event (additive to the\n"},{"k":"link","text":"07 §Runtime-4","href":"../spec/07-conformance.md#level-2--runtime-conformance"},{"k":"text","text":"\nevent set · reference-engine trace kind "},{"k":"code","text":"task_cache_hit"},{"k":"text","text":") carrying\n"},{"k":"code","text":"task_id"},{"k":"text","text":" + a reference to the matched trace record. The task's output\nis rehydrated from the record; downstream tasks observe "},{"k":"code","text":"status: success"},{"k":"text","text":" and the bound output exactly as if it had run live. The task\nstate enum stays CLOSED ("},{"k":"link","text":"03 §task states","href":"../spec/03-dag.md#task-states"},{"k":"text","text":"\n· no new state): the cache/live distinction rides the event stream and\nthe run report, never the "},{"k":"code","text":"\u0024{{ }}"},{"k":"text","text":" surface. Anti-hidden-magic is the\ndesign line — a resumed run's console and trace say "},{"k":"code","text":"cache_hit"},{"k":"text","text":" per\nskipped task, loudly."}]},{"k":"h","depth":3,"text":"3 · `--from <task_id>` — the manual override","id":"3----from-task_id--the-manual-override"},{"k":"p","inline":[{"k":"text","text":"Forces re-execution from a node: the named task and its transitive\ndownstream re-run even on hash match (tasks upstream of it may still\ncache-hit). An unknown task id is refused pre-run (the same contract as\n"},{"k":"code","text":"nika run --var"},{"k":"text","text":" unknown-key refusal). This is the lever for \"the world\nchanged in a way the hashes cannot see\" (rotated secret · external\nstate · an "},{"k":"code","text":"infer:"},{"k":"text","text":" output you want re-rolled)."}]},{"k":"h","depth":3,"text":"4 · Non-deterministic tasks replay their recorded output","id":"4--non-deterministic-tasks-replay-their-recorded-output"},{"k":"p","inline":[{"k":"text","text":"An "},{"k":"code","text":"infer:"},{"k":"text","text":"/"},{"k":"code","text":"agent:"},{"k":"text","text":" task that hash-matches replays the recorded output\n— that is the point (crash-resume without re-spending tokens).\nDeterminism is never the author's problem: there are no replay rules,\nno \"workflow versioning\", no side-effect wrappers. A task that does not\nhash-match simply re-runs live, side effects included (see Non-goals)."}]},{"k":"h","depth":3,"text":"Rider — the durable human gate (`nika:prompt` pause)","id":"rider--the-durable-human-gate-nikaprompt-pause"},{"k":"p","inline":[{"k":"text","text":"Today's normative non-interactive contract\n("},{"k":"link","text":"stdlib §nika:prompt","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":"): with "},{"k":"code","text":"default:"},{"k":"text","text":"\nthe engine MUST answer with it; without, it MUST fail\n"},{"k":"code","text":"NIKA-BUILTIN-PROMPT-001"},{"k":"text","text":" — never hang. The rider occupies "},{"k":"strong","text":"exactly\nthat failure branch"},{"k":"text","text":", changing nothing else:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Under a non-interactive surface ("},{"k":"code","text":"--json"},{"k":"text","text":" · "},{"k":"code","text":"nika serve"},{"k":"text","text":"), a blocking\n"},{"k":"code","text":"nika:prompt"},{"k":"text","text":" with no usable "},{"k":"code","text":"default:"},{"k":"text","text":" journals a "},{"k":"strong","text":"`workflow.paused`"},{"k":"text","text":"\nevent (trace kind "},{"k":"code","text":"workflow_paused"},{"k":"text","text":") carrying the prompt payload\n("},{"k":"code","text":"task_id"},{"k":"text","text":" · "},{"k":"code","text":"mode"},{"k":"text","text":" · "},{"k":"code","text":"message"},{"k":"text","text":" · "},{"k":"code","text":"choices"},{"k":"text","text":" · secret-masked like every\njournal surface) and "},{"k":"strong","text":"exits cleanly"},{"k":"text","text":" with run state "},{"k":"code","text":"paused"},{"k":"text","text":" instead\nof failing."}],[{"k":"strong","text":"`--resume <trace>` re-arms the prompt"},{"k":"text","text":": completed upstream work\ncache-hits, the run continues AT the prompt — interactively it asks;\nresumed non-interactively with an answer supplied (CLI arg · serve\nwebhook payload — delivery ergonomics are the engine's) it binds it;\nresumed non-interactively with no answer it pauses again\n(idempotent · a paused trace can be resumed any number of times)."}],[{"k":"text","text":"This resolves H5's noted limitation (\"pause-state is live · durable\npauses arrive with H1\") with "},{"k":"strong","text":"zero new syntax"},{"k":"text","text":" — \"ONE construct · a\ntool under "},{"k":"code","text":"invoke:"},{"k":"text","text":" · forever\" stays exactly as locked."}]]},{"k":"p","inline":[{"k":"text","text":"The one spec-surface delta this rider needs: the run-report/event\nvocabulary gains "},{"k":"strong","text":"`paused`"},{"k":"text","text":" as an additive workflow-state value\n("},{"k":"link","text":"05 §workflow-level semantics","href":"../spec/05-errors.md#workflow-level-error-semantics"},{"k":"text","text":")\nplus the two events above. Like "},{"k":"code","text":"pending"},{"k":"text","text":"/"},{"k":"code","text":"running"},{"k":"text","text":", "},{"k":"code","text":"paused"},{"k":"text","text":" exists in\nrun reports and events, never inside "},{"k":"code","text":"\u0024{{ }}"},{"k":"text","text":"."}]},{"k":"h","depth":2,"text":"Non-goals","id":"non-goals"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"No author-facing determinism constraints"},{"k":"text","text":" (Temporal-style replay\nrules). Side-effectful tasks re-run whenever their hashes mismatch —\ndurability is the engine's problem, never the author's. An author who\nneeds a side effect to be exactly-once under resume marks the node\nwith "},{"k":"code","text":"--from"},{"k":"text","text":" discipline or makes the tool idempotent via its own\nargs (today's H1 guidance · unchanged)."}],[{"k":"strong","text":"Idempotency keys stay deferred"},{"k":"text","text":" — the NEXT deferral in this ladder\n("},{"k":"link","text":"08 §idempotency","href":"../spec/08-out-of-scope.md#idempotency-keys--step-deduplication"},{"k":"text","text":").\nResume shrinks the re-run window (completed work never re-fires) but\na crash mid-side-effect can still double-fire on re-run; at-least-once\ndedup remains the full durable-execution waypoint's job."}],[{"k":"strong","text":"No envelope/syntax change."},{"k":"text","text":" The "},{"k":"code","text":"checkpoint:"},{"k":"text","text":"-block sketch in\n"},{"k":"link","text":"08 §Persistence","href":"../spec/08-out-of-scope.md#workflow-checkpointing--resumption"},{"k":"text","text":"\nREMAINS deferred exactly as written: a workflow never declares\npersistence. This ADR is CLI flags + trace/event vocabulary."}],[{"k":"strong","text":"No daemon."},{"k":"text","text":" "},{"k":"code","text":"--resume"},{"k":"text","text":" is a reader of a file. No supervisor · no\nrun-store service · no background process · no wake-on-event (durable\ntimers ride a later design)."}],[{"k":"strong","text":"Not general memoization."},{"k":"text","text":" "},{"k":"code","text":"task.cache_hit"},{"k":"text","text":" fires only under\n"},{"k":"code","text":"--resume"},{"k":"text","text":"; a fresh "},{"k":"code","text":"nika run"},{"k":"text","text":" executes every task. The H17\n"},{"k":"code","text":"cache_key:"},{"k":"text","text":" field stays deferred on its own terms."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Crash-resume · re-run-from-a-node · no-token-re-spend land behind ONE\nflag, riding an artifact every Runtime-conformant engine already emits."}],[{"k":"text","text":"The durable human gate closes the biggest practitioner ask with zero\nnew syntax and zero change to answered-prompt behavior (the pause path\noccupies only what is a hard error today — strictly additive)."}],[{"k":"text","text":"Sovereignty intact: the trace is a local NDJSON file · grep-able ·\nportable · no vendor run store, no cloud dependency."}],[{"k":"text","text":"The determinism tax is structurally refused, not just avoided: there\nis no replay engine to feed, so no replay rules can ever leak to\nauthors."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The "},{"k":"code","text":"task.completed"},{"k":"text","text":" record fields resume reads (definition hash ·\ninput hash · output) become a compatibility surface: they MUST evolve\nadditively, and an engine facing a trace it cannot read MUST say so\nand re-run fully — never guess a partial skip."}],[{"k":"text","text":"Secrets-by-name hashing means a rotated secret silently cache-hits;\nthe limit is documented and "},{"k":"code","text":"--from"},{"k":"text","text":" is the override, but it is a\nreal sharp edge to teach."}],[{"k":"code","text":"paused"},{"k":"text","text":" is one more workflow-state value every run-report consumer\nmust render."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Resume conformance is behavioral-tier — it lands with the runtime\nfixtures, post-announce\n("},{"k":"link","text":"07 §suite status","href":"../spec/07-conformance.md#suite-status--v01-honest"},{"k":"text","text":")."}],[{"k":"text","text":"Another engine MAY keep a different trace file layout: the\nconformance contract binds the EVENTS and the skip/pause semantics,\nnot the bytes of the journal."}]]},{"k":"h","depth":2,"text":"Conformance sketch — 3 fixtures · `tests/runtime/resume/`","id":"conformance-sketch--3-fixtures--testsruntimeresume"},{"k":"p","inline":[{"k":"text","text":"Behavioral-tier shape per\n"},{"k":"link","text":"conformance/tests/runtime/README.md","href":"../conformance/tests/runtime/README.md"},{"k":"text","text":"\n("},{"k":"code","text":"input.nika.yaml"},{"k":"text","text":" + "},{"k":"code","text":"run.json"},{"k":"text","text":" + "},{"k":"code","text":"expected-run.json"},{"k":"text","text":" · "},{"k":"code","text":"mock/echo"},{"k":"text","text":") ·\nresume fixtures add the two-phase invocation (run → interrupt → resume)\nto the runner protocol:"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"(a) `001-kill-midrun-resume-completes-remainder`"},{"k":"text","text":" — first\ninvocation is interrupted after task "},{"k":"code","text":"a"},{"k":"text","text":" completes; the resumed run\nMUST cache-hit "},{"k":"code","text":"a"},{"k":"text","text":" ("},{"k":"code","text":"events_include: [\"task.cache_hit:a\"]"},{"k":"text","text":"), execute\nonly the remainder live, and end "},{"k":"code","text":"workflow_state: success"},{"k":"text","text":" with\noutputs identical to an uninterrupted run."}],[{"k":"strong","text":"(b) `002-input-change-rehashes-and-reruns`"},{"k":"text","text":" — same trace, one\n"},{"k":"code","text":"vars"},{"k":"text","text":" value changed in "},{"k":"code","text":"run.json"},{"k":"text","text":": the consuming task's\nresolved-input hash mismatches → it re-runs (no "},{"k":"code","text":"task.cache_hit"},{"k":"text","text":" for\nit) · an untouched sibling branch still cache-hits."}],[{"k":"strong","text":"(c) `003-paused-prompt-rearms`"},{"k":"text","text":" — a non-interactive run hits a\ndefault-less "},{"k":"code","text":"nika:prompt"},{"k":"text","text":" → exits "},{"k":"code","text":"workflow_state: paused"},{"k":"text","text":", trace\ncarries "},{"k":"code","text":"workflow.paused"},{"k":"text","text":" with the prompt payload; resumed with an\nanswer supplied → upstream cache-hits, the prompt binds, the run\ncompletes; resumed without one → it pauses again (idempotent)."}]]},{"k":"h","depth":2,"text":"Evidence / Affected surfaces","id":"evidence--affected-surfaces"},{"k":"list","ordered":false,"items":[[{"k":"link","text":"`spec/08-out-of-scope.md`","href":"../spec/08-out-of-scope.md"},{"k":"text","text":" — §Persistence\ncheckpointing (the deferral this ADR lifts at the durable-lite tier) ·\n§Idempotency (the next deferral) · H1 · H5 · H17 (amended this arc)."}],[{"k":"link","text":"`stdlib/builtins-v0.1.md`","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":" §"},{"k":"code","text":"nika:prompt"},{"k":"text","text":"\n— the "},{"k":"code","text":"NIKA-BUILTIN-PROMPT-001"},{"k":"text","text":" branch the rider occupies."}],[{"k":"link","text":"`spec/07-conformance.md`","href":"../spec/07-conformance.md"},{"k":"text","text":" §Runtime-4 —\nthe event vocabulary "},{"k":"code","text":"task.cache_hit"},{"k":"text","text":" / "},{"k":"code","text":"workflow.paused"},{"k":"text","text":" extend\nadditively."}],[{"k":"text","text":"Reference engine "},{"k":"code","text":"crates/nika-event/src/kind.rs"},{"k":"text","text":" — snake_case trace\nkinds ("},{"k":"code","text":"task_completed"},{"k":"text","text":") + the pre-reserved "},{"k":"code","text":"checkpoint_written"},{"k":"text","text":"\n(\"durable run state snapshot\"): the seam was planted before the design."}],[{"k":"text","text":"External poles · Nextflow "},{"k":"code","text":"-resume"},{"k":"text","text":" (the adopted shape ·\ncontent-addressed task skip · zero author tax) · Temporal workflow\ndeterminism constraints (the rejected shape · the tax this ADR\nstructurally refuses)."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — full durable-execution runtime (Temporal-class)","id":"alt-a--full-durable-execution-runtime-temporal-class"},{"k":"p","inline":[{"k":"text","text":"Event-sourced replay: re-execute workflow code against recorded\nhistories, requiring deterministic authorship, wrapped side effects,\nand code-version pinning. Rejected — it exports the runtime's problem\nto every author forever, contradicts the no-hidden-magic spine, and\nbuys nothing this design does not already deliver for a finite DAG\nwhose journal carries every task boundary."}]},{"k":"h","depth":3,"text":"Alt B — sqlite checkpoint store","id":"alt-b--sqlite-checkpoint-store"},{"k":"p","inline":[{"k":"text","text":"A dedicated "},{"k":"code","text":"checkpoints.db"},{"k":"text","text":" beside the trace (the shape the old 08\nsketch reserved). Rejected for v1 — a second stateful artifact to\ncreate, locate, version, and explain, duplicating data the NDJSON trace\nalready journals. One artifact · plain text · portable. An engine MAY\nlater keep an internal index (sqlite or otherwise) as a pure\noptimization — invisible to this contract."}]},{"k":"h","depth":3,"text":"Alt C — do nothing","id":"alt-c--do-nothing"},{"k":"p","inline":[{"k":"text","text":"Rejected — crash-resume and the durable human gate are the top two\npractitioner asks of this tool class, and H5's live-pause limitation is\nflagged in the spec's own text. Waiting for the full durable-execution\nwaypoint gates the 90% capability on the 10% problem (idempotent\ndelivery) that finite single-run DAGs mostly do not have."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"link","text":"`spec/08-out-of-scope.md`","href":"../spec/08-out-of-scope.md"},{"k":"text","text":" §Persistence ·\n§Idempotency · H1 · H5 · H17"}],[{"k":"link","text":"`spec/07-conformance.md`","href":"../spec/07-conformance.md"},{"k":"text","text":" §Runtime\nconformance · §suite status"}],[{"k":"link","text":"`spec/03-dag.md`","href":"../spec/03-dag.md"},{"k":"text","text":" §task states (closed enum ·\nunchanged) · "},{"k":"link","text":"`spec/05-errors.md`","href":"../spec/05-errors.md"},{"k":"text","text":"\n§workflow-level semantics ("},{"k":"code","text":"paused"},{"k":"text","text":" additive)"}],[{"k":"link","text":"`stdlib/builtins-v0.1.md`","href":"../stdlib/builtins-v0.1.md"},{"k":"text","text":" §"},{"k":"code","text":"nika:prompt"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Registration"},{"k":"text","text":" · DONE (this file · the "},{"k":"code","text":"feat/resume-impl"},{"k":"text","text":" arc) —\nADR-099 is registered in the engine "},{"k":"code","text":"docs/adr/"},{"k":"text","text":" index (the series\nregistry)."}],[{"k":"strong","text":"Status flip"},{"k":"text","text":" · DONE · "},{"k":"code","text":"proposed → accepted"},{"k":"text","text":" with the engine\nimplementation; the behavioral fixtures of the Conformance sketch\nship as "},{"k":"code","text":"crates/nika-cli/tests/resume_e2e.rs"},{"k":"text","text":". (The spec-repo copy's\nfrontmatter flip is a spec-repo commit — tracked there.)"}],[{"k":"strong","text":"Revisit trigger"},{"k":"text","text":" · if implementation shows secrets-by-name hashing\nis too blunt (rotated-secret staleness bites in practice), a keyed\ncommitment (HMAC under an engine-local key · never a bare hash)\nre-opens HERE first — the trace-carries-no-secret-material invariant\nis not negotiable."}]]}]

ADR-099

Durable-lite run resume — the trace IS the checkpoint

accepted · 2026-07-05 · L2 L4 · cites 3

ADR-099 — Durable-lite run resume · the trace IS the checkpoint #

Status: Accepted (2026-07-05) — implemented by the engine feat/resume-impl arc: nika-runtime resume keys (JCS + blake3) + the --resume skip fold + the pause rider · nika-cli run --resume / --from / --answer · EventKind::{TaskCacheHit, WorkflowPaused} · exit code 4 (paused) · the 3 conformance fixtures as engine e2e tests (crates/nika-cli/tests/resume_e2e.rs).
Surface: CLI + trace/event vocabulary ONLY. Zero envelope change · zero new YAML · the 4-verbs and nika: v1 locks are untouched.
Home: the CANONICAL prose lives in the nika-spec repo's adr/ (language-surface decisions — the relative spec links below resolve THERE); this copy registers the number in the shared Nika ADR series (the engine docs/adr/ registry is the series' index).

Context #

Durability is the largest capability gap the spec names about itself. 08-out-of-scope holds four interlocking deferrals: §Persistence defers workflow checkpointing/resumption (with a checkpoint:-block sketch), §Idempotency defers step dedup "together with the durable-execution waypoint", H1 states plainly that crash = re-run from the top, and H5 admits the human gate's pause-state is live ("the run keeps a process while blocked · durable pauses arrive with H1"). Across the 2026 workflow-runner landscape, crash-resume and the durable human gate are the two most-asked-for capabilities this class of tool gets measured on — Nextflow's -resume (content-addressed task skip) is that ecosystem's single most-loved feature, and it taxes authors with nothing.

Meanwhile the checkpoint artifact already exists. A conformant Runtime engine MUST emit the workflow event stream (07 §Runtime-4): task.completed records carry per-task outcome, and the reference engine journals every run as an NDJSON trace (crates/nika-event/src/kind.rs serializes the kinds snake_case: task_completed · and pre-reserves checkpoint_written, "a durable run state snapshot"). What is missing is not a new runtime — it is a reader.

The trap to avoid is equally documented: Temporal-class durable execution buys resume by imposing replay-determinism constraints on workflow authors (code must be deterministic · side effects must be wrapped · histories version with the code). That tax is the single most hated property of the durable-execution class, and this spec's whole posture (audit-before-run · no hidden magic · the engine owns the how) forbids exporting it to authors.

Decision #

`nika run wf.nika.yaml --resume <trace>` re-executes a workflow, skipping every task whose identity matches a completed record in the given trace. The trace is the run's own NDJSON journal — no second store, no new artifact, no daemon.

1 · The skip rule — content-addressed · two hashes · both MUST match #

A task is skippable iff the trace holds a task.completed record whose

task-definition hash — a canonical serialization of the task's behavior-bearing fields (the verb body · with: · output: · retry: / on_error: / on_finally: · when: · for_each:) — matches the task as now written, AND
resolved-input hash — the values its ${{ }} references resolved to at execution time (upstream outputs · vars · with · env) — matches the values the resumed run resolves.

Edit a prompt → that task re-runs. Change a var an early task consumes → it re-runs, and the mismatch cascades through resolved-input hashes exactly as far as the data actually flows — untouched siblings still skip. for_each tasks record per-iteration (the item participates in the input hash), so a partially-completed fan-out resumes at the iteration level.

Secrets participate by declared reference identity (name · declared source path), never by value — masking is normative (01 §envelope MUSTs) and a trace MUST NOT carry secret-derived material, including value hashes (a hash of a low-entropy secret is an oracle). Stated limit: a rotated secret does NOT invalidate the cache — force the affected node with --from.

2 · The skip is VISIBLE — `task.cache_hit` · never silent #

Each skipped task emits a `task.cache_hit` event (additive to the 07 §Runtime-4 event set · reference-engine trace kind task_cache_hit) carrying task_id + a reference to the matched trace record. The task's output is rehydrated from the record; downstream tasks observe status: success and the bound output exactly as if it had run live. The task state enum stays CLOSED (03 §task states · no new state): the cache/live distinction rides the event stream and the run report, never the ${{ }} surface. Anti-hidden-magic is the design line — a resumed run's console and trace say cache_hit per skipped task, loudly.

3 · `--from <task_id>` — the manual override #

Forces re-execution from a node: the named task and its transitive downstream re-run even on hash match (tasks upstream of it may still cache-hit). An unknown task id is refused pre-run (the same contract as nika run --var unknown-key refusal). This is the lever for "the world changed in a way the hashes cannot see" (rotated secret · external state · an infer: output you want re-rolled).

4 · Non-deterministic tasks replay their recorded output #

An infer:/agent: task that hash-matches replays the recorded output — that is the point (crash-resume without re-spending tokens). Determinism is never the author's problem: there are no replay rules, no "workflow versioning", no side-effect wrappers. A task that does not hash-match simply re-runs live, side effects included (see Non-goals).

Rider — the durable human gate (`nika:prompt` pause) #

Today's normative non-interactive contract (stdlib §nika:prompt): with default: the engine MUST answer with it; without, it MUST fail NIKA-BUILTIN-PROMPT-001 — never hang. The rider occupies exactly that failure branch, changing nothing else:

Under a non-interactive surface (--json · nika serve), a blocking nika:prompt with no usable default: journals a `workflow.paused` event (trace kind workflow_paused) carrying the prompt payload (task_id · mode · message · choices · secret-masked like every journal surface) and exits cleanly with run state paused instead of failing.
`--resume <trace>` re-arms the prompt: completed upstream work cache-hits, the run continues AT the prompt — interactively it asks; resumed non-interactively with an answer supplied (CLI arg · serve webhook payload — delivery ergonomics are the engine's) it binds it; resumed non-interactively with no answer it pauses again (idempotent · a paused trace can be resumed any number of times).
This resolves H5's noted limitation ("pause-state is live · durable pauses arrive with H1") with zero new syntax — "ONE construct · a tool under invoke: · forever" stays exactly as locked.

The one spec-surface delta this rider needs: the run-report/event vocabulary gains `paused` as an additive workflow-state value (05 §workflow-level semantics) plus the two events above. Like pending/running, paused exists in run reports and events, never inside ${{ }}.

Non-goals #

No author-facing determinism constraints (Temporal-style replay rules). Side-effectful tasks re-run whenever their hashes mismatch — durability is the engine's problem, never the author's. An author who needs a side effect to be exactly-once under resume marks the node with --from discipline or makes the tool idempotent via its own args (today's H1 guidance · unchanged).
Idempotency keys stay deferred — the NEXT deferral in this ladder (08 §idempotency). Resume shrinks the re-run window (completed work never re-fires) but a crash mid-side-effect can still double-fire on re-run; at-least-once dedup remains the full durable-execution waypoint's job.
No envelope/syntax change. The checkpoint:-block sketch in 08 §Persistence REMAINS deferred exactly as written: a workflow never declares persistence. This ADR is CLI flags + trace/event vocabulary.
No daemon. --resume is a reader of a file. No supervisor · no run-store service · no background process · no wake-on-event (durable timers ride a later design).
Not general memoization. task.cache_hit fires only under --resume; a fresh nika run executes every task. The H17 cache_key: field stays deferred on its own terms.

Consequences #

Positive #

Crash-resume · re-run-from-a-node · no-token-re-spend land behind ONE flag, riding an artifact every Runtime-conformant engine already emits.
The durable human gate closes the biggest practitioner ask with zero new syntax and zero change to answered-prompt behavior (the pause path occupies only what is a hard error today — strictly additive).
Sovereignty intact: the trace is a local NDJSON file · grep-able · portable · no vendor run store, no cloud dependency.
The determinism tax is structurally refused, not just avoided: there is no replay engine to feed, so no replay rules can ever leak to authors.

Negative #

The task.completed record fields resume reads (definition hash · input hash · output) become a compatibility surface: they MUST evolve additively, and an engine facing a trace it cannot read MUST say so and re-run fully — never guess a partial skip.
Secrets-by-name hashing means a rotated secret silently cache-hits; the limit is documented and --from is the override, but it is a real sharp edge to teach.
paused is one more workflow-state value every run-report consumer must render.

Neutral #

Resume conformance is behavioral-tier — it lands with the runtime fixtures, post-announce (07 §suite status).
Another engine MAY keep a different trace file layout: the conformance contract binds the EVENTS and the skip/pause semantics, not the bytes of the journal.

Conformance sketch — 3 fixtures · `tests/runtime/resume/` #

Behavioral-tier shape per conformance/tests/runtime/README.md (input.nika.yaml + run.json + expected-run.json · mock/echo) · resume fixtures add the two-phase invocation (run → interrupt → resume) to the runner protocol:

(a) `001-kill-midrun-resume-completes-remainder` — first invocation is interrupted after task a completes; the resumed run MUST cache-hit a (events_include: ["task.cache_hit:a"]), execute only the remainder live, and end workflow_state: success with outputs identical to an uninterrupted run.
(b) `002-input-change-rehashes-and-reruns` — same trace, one vars value changed in run.json: the consuming task's resolved-input hash mismatches → it re-runs (no task.cache_hit for it) · an untouched sibling branch still cache-hits.
(c) `003-paused-prompt-rearms` — a non-interactive run hits a default-less nika:prompt → exits workflow_state: paused, trace carries workflow.paused with the prompt payload; resumed with an answer supplied → upstream cache-hits, the prompt binds, the run completes; resumed without one → it pauses again (idempotent).

Evidence / Affected surfaces #

`spec/08-out-of-scope.md` — §Persistence checkpointing (the deferral this ADR lifts at the durable-lite tier) · §Idempotency (the next deferral) · H1 · H5 · H17 (amended this arc).
`stdlib/builtins-v0.1.md` §nika:prompt — the NIKA-BUILTIN-PROMPT-001 branch the rider occupies.
`spec/07-conformance.md` §Runtime-4 — the event vocabulary task.cache_hit / workflow.paused extend additively.
Reference engine crates/nika-event/src/kind.rs — snake_case trace kinds (task_completed) + the pre-reserved checkpoint_written ("durable run state snapshot"): the seam was planted before the design.
External poles · Nextflow -resume (the adopted shape · content-addressed task skip · zero author tax) · Temporal workflow determinism constraints (the rejected shape · the tax this ADR structurally refuses).

Alternatives considered #

Alt A — full durable-execution runtime (Temporal-class) #

Event-sourced replay: re-execute workflow code against recorded histories, requiring deterministic authorship, wrapped side effects, and code-version pinning. Rejected — it exports the runtime's problem to every author forever, contradicts the no-hidden-magic spine, and buys nothing this design does not already deliver for a finite DAG whose journal carries every task boundary.

Alt B — sqlite checkpoint store #

A dedicated checkpoints.db beside the trace (the shape the old 08 sketch reserved). Rejected for v1 — a second stateful artifact to create, locate, version, and explain, duplicating data the NDJSON trace already journals. One artifact · plain text · portable. An engine MAY later keep an internal index (sqlite or otherwise) as a pure optimization — invisible to this contract.

Alt C — do nothing #

Rejected — crash-resume and the durable human gate are the top two practitioner asks of this tool class, and H5's live-pause limitation is flagged in the spec's own text. Waiting for the full durable-execution waypoint gates the 90% capability on the 10% problem (idempotent delivery) that finite single-run DAGs mostly do not have.

`spec/08-out-of-scope.md` §Persistence · §Idempotency · H1 · H5 · H17
`spec/07-conformance.md` §Runtime conformance · §suite status
`spec/03-dag.md` §task states (closed enum · unchanged) · `spec/05-errors.md` §workflow-level semantics (paused additive)
`stdlib/builtins-v0.1.md` §nika:prompt

Notes #

Registration · DONE (this file · the feat/resume-impl arc) — ADR-099 is registered in the engine docs/adr/ index (the series registry).
Status flip · DONE · proposed → accepted with the engine implementation; the behavioral fixtures of the Conformance sketch ship as crates/nika-cli/tests/resume_e2e.rs. (The spec-repo copy's frontmatter flip is a spec-repo commit — tracked there.)
Revisit trigger · if implementation shows secrets-by-name hashing is too blunt (rotated-secret staleness bites in practice), a keyed commitment (HMAC under an engine-local key · never a bare hash) re-opens HERE first — the trace-carries-no-secret-material invariant is not negotiable.

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

Every decision, with its status This one in the repo