{"row":{"id":"ADR-100","title":"Trace retention — bounded by default, never silently, never a pending gate","file":"adr-100-trace-retention.md","status":"accepted","date":"2026-07-05","cites":2,"supersedes":[],"superseded_by":[],"layers":["L2","L4"],"tags":["trace","retention","gc","resume"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-100 — Trace retention · bounded by default, never silently, never a pending gate","id":"adr-100--trace-retention--bounded-by-default-never-silently-never-a-pending-gate"},{"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/trace-retention"},{"k":"text","text":" arc: the D1 policy (keep-10 per workflow ·\n30d age cap · 256MB budget · the paused + newest-per-workflow\nabsolute exemptions) · D2 opportunistic GC at "},{"k":"code","text":"nika run"},{"k":"text","text":" start\n(fail-open · exactly ONE stderr line · "},{"k":"code","text":"--no-gc"},{"k":"text","text":") · D3\n"},{"k":"code","text":"nika trace ls"},{"k":"text","text":" (age · size · workflow · state · the ★\nresume-candidate marker) + "},{"k":"code","text":"nika trace rm"},{"k":"text","text":" (paused refuses without\n"},{"k":"code","text":"--force"},{"k":"text","text":" and names the task) · D4 knobs on the "},{"k":"code","text":"NIKA_TRACE_*"},{"k":"text","text":" env\nfamily, reported by "},{"k":"code","text":"nika doctor"},{"k":"text","text":" · the 4 conformance fixtures as\nengine tests ("},{"k":"code","text":"crates/nika-cli/src/verbs/trace/{retention,manage}.rs"},{"k":"text","text":")."}],[{"k":"strong","text":"Surface"},{"k":"text","text":": CLI + runtime housekeeping ONLY. Zero envelope change ·\nzero new YAML."}],[{"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); this copy registers the number in the\nshared Nika ADR series (the engine "},{"k":"code","text":"docs/adr/"},{"k":"text","text":" registry is the\nseries' index)."}]]},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"code","text":".nika/traces/"},{"k":"text","text":" grows without bound: every "},{"k":"code","text":"nika run"},{"k":"text","text":" appends one NDJSON\njournal and nothing ever removes one (verified 2026-07-05 · zero\nretention/GC language anywhere in spec v1). This was tolerable when a\ntrace was a debugging artifact. Since ADR-099 a trace is "},{"k":"strong","text":"three things\nat once"},{"k":"text","text":":"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"an observability record ("},{"k":"code","text":"nika trace show|replay"},{"k":"text","text":" and the round-7\ncomprehension surfaces),"}],[{"k":"strong","text":"the checkpoint"},{"k":"text","text":" ("},{"k":"code","text":"--resume"},{"k":"text","text":" folds it · deleting a trace deletes\nresumability),"}],[{"k":"strong","text":"a pending human gate"},{"k":"text","text":" when its last state is "},{"k":"code","text":"workflow_paused"},{"k":"text","text":" —\ndeleting THAT trace silently destroys an unanswered approval."}]]},{"k":"p","inline":[{"k":"text","text":"Unbounded growth is a real cost (traces carry full task outputs since\nADR-099 rehydration — multi-MB per run on payload-heavy workflows), but\nnaive GC would violate the resume and pause contracts. The legacy engine\nhad trace auto-GC; v1 must get the bounded-but-safe version."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"h","depth":3,"text":"D1 · Retention policy (defaults · engine-enforced)","id":"d1--retention-policy-defaults--engine-enforced"},{"k":"p","inline":[{"k":"text","text":"Per workflow (keyed by workflow name within a project's "},{"k":"code","text":".nika/traces/"},{"k":"text","text":"):"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Rule · Default · Rationale"}],[{"k":"text","text":"keep the last **N** completed-run traces · `10` · the observability window"}],[{"k":"text","text":"age cap · `30d` · stale traces exit even under N"}],[{"k":"text","text":"project total size budget · `256MB` · the hard stop"}]]},{"k":"p","inline":[{"k":"strong","text":"Absolute exemptions — never collected regardless of any cap:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"a trace whose last workflow state is "},{"k":"code","text":"paused"},{"k":"text","text":" (a pending gate is an\nOBLIGATION, not garbage) — it ages out only once answered or explicitly\nremoved with "},{"k":"code","text":"nika trace rm"},{"k":"text","text":","}],[{"k":"text","text":"the most recent trace of each workflow (the standing resume candidate)."}]]},{"k":"h","depth":3,"text":"D2 · When GC runs","id":"d2--when-gc-runs"},{"k":"p","inline":[{"k":"text","text":"Opportunistically at "},{"k":"code","text":"nika run"},{"k":"text","text":" start (maintenance rides usage — no\ndaemon, no cron, the Nextflow/cargo school). A collection that removes\nanything prints exactly ONE line to stderr:"}]},{"k":"code","lang":"text","text":"trace gc · removed 3 (2 aged · 1 over-budget) · kept 12 · 41MB"},{"k":"p","inline":[{"k":"text","text":"Silent deletion is forbidden (the anti-hidden-magic invariant). "},{"k":"code","text":"--no-gc"},{"k":"text","text":"\nskips collection for that invocation."}]},{"k":"h","depth":3,"text":"D3 · The explicit surface","id":"d3--the-explicit-surface"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika trace ls"},{"k":"text","text":" — traces with age · size · workflow · terminal state\n("},{"k":"code","text":"completed"},{"k":"text","text":"/"},{"k":"code","text":"failed"},{"k":"text","text":"/"},{"k":"strong","text":"`paused`"},{"k":"text","text":") · the resume-candidate marker."}],[{"k":"code","text":"nika trace rm <trace>|--older-than <dur>|--all"},{"k":"text","text":" — explicit removal ·\nremoving a "},{"k":"code","text":"paused"},{"k":"text","text":" trace requires "},{"k":"code","text":"--force"},{"k":"text","text":" and says what it destroys\n("},{"k":"code","text":"this trace carries an unanswered prompt for task <id>"},{"k":"text","text":")."}]]},{"k":"h","depth":3,"text":"D4 · Configuration","id":"d4--configuration"},{"k":"p","inline":[{"k":"text","text":"The three knobs ride the engine's existing config surface ("},{"k":"code","text":"nika doctor"},{"k":"text","text":"\nreports the active values). Config names and wiring are the\nimplementation arc's to fix; the DEFAULTS above are the spec contract."}]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"No GC (status quo)"},{"k":"text","text":" — rejected: unbounded disk on every real user ·\nthe docs would have to teach manual cleanup of a dir the tool owns."}],[{"k":"strong","text":"A `nika trace gc` verb only (fully manual)"},{"k":"text","text":" — rejected: nobody runs\nmaintenance verbs · bounded-by-default is the 2026 baseline · the\nexplicit surface exists IN ADDITION (D3)."}],[{"k":"strong","text":"GC daemon / background thread"},{"k":"text","text":" — rejected: no daemon is a v1\nidentity trait · opportunistic-at-run is sufficient and testable."}],[{"k":"strong","text":"Content-addressed dedup of outputs before GC"},{"k":"text","text":" — deferred: real\n(outputs repeat across runs) but it is a storage-format change ·\nretention must not wait for it."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Disk is bounded by default; resume and pause contracts survive GC by\nconstruction (the exemptions are the contract)."}],[{"k":"code","text":"--resume"},{"k":"text","text":" against a collected trace keeps its ADR-099 behavior\n(readable error · nothing skips) — retention adds the "},{"k":"code","text":"trace ls"},{"k":"text","text":"\nsurface to SEE what is resumable."}],[{"k":"text","text":"Traces stop being an unbounded liability in CI (the size budget is the\ncap that matters there)."}]]},{"k":"h","depth":2,"text":"Conformance sketch (ships with the implementation)","id":"conformance-sketch-ships-with-the-implementation"},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"paused-survives"},{"k":"text","text":" · a "},{"k":"code","text":"workflow_paused"},{"k":"text","text":" trace older than every cap\nsurvives GC · "},{"k":"code","text":"trace ls"},{"k":"text","text":" marks it "},{"k":"code","text":"paused"},{"k":"text","text":"."}],[{"k":"strong","text":"resume-candidate-survives"},{"k":"text","text":" · the newest trace of a workflow\nsurvives even when over-budget alone."}],[{"k":"strong","text":"visible-collection"},{"k":"text","text":" · an over-N history collects oldest-first ·\nexactly one stderr line reports it · "},{"k":"code","text":"--no-gc"},{"k":"text","text":" leaves it intact."}],[{"k":"strong","text":"forced-removal-speaks"},{"k":"text","text":" · "},{"k":"code","text":"trace rm"},{"k":"text","text":" on a paused trace refuses\nwithout "},{"k":"code","text":"--force"},{"k":"text","text":" and names the unanswered task."}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Interplay with idempotency keys (the §Persistence deferral) is\nunchanged — retention never re-runs anything by itself."}],[{"k":"text","text":"The engine index registration + "},{"k":"code","text":"nika trace ls|rm"},{"k":"text","text":" land with the\nimplementation arc."}]]}]

ADR-100

Trace retention — bounded by default, never silently, never a pending gate

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

ADR-100 — Trace retention · bounded by default, never silently, never a pending gate #

Status: Accepted (2026-07-05) — implemented by the engine feat/trace-retention arc: the D1 policy (keep-10 per workflow · 30d age cap · 256MB budget · the paused + newest-per-workflow absolute exemptions) · D2 opportunistic GC at nika run start (fail-open · exactly ONE stderr line · --no-gc) · D3 nika trace ls (age · size · workflow · state · the ★ resume-candidate marker) + nika trace rm (paused refuses without --force and names the task) · D4 knobs on the NIKA_TRACE_* env family, reported by nika doctor · the 4 conformance fixtures as engine tests (crates/nika-cli/src/verbs/trace/{retention,manage}.rs).
Surface: CLI + runtime housekeeping ONLY. Zero envelope change · zero new YAML.
Home: the CANONICAL prose lives in the nika-spec repo's adr/ (language-surface decisions); this copy registers the number in the shared Nika ADR series (the engine docs/adr/ registry is the series' index).

Context #

.nika/traces/ grows without bound: every nika run appends one NDJSON journal and nothing ever removes one (verified 2026-07-05 · zero retention/GC language anywhere in spec v1). This was tolerable when a trace was a debugging artifact. Since ADR-099 a trace is three things at once:

an observability record (nika trace show|replay and the round-7 comprehension surfaces),
the checkpoint (--resume folds it · deleting a trace deletes resumability),
a pending human gate when its last state is workflow_paused — deleting THAT trace silently destroys an unanswered approval.

Unbounded growth is a real cost (traces carry full task outputs since ADR-099 rehydration — multi-MB per run on payload-heavy workflows), but naive GC would violate the resume and pause contracts. The legacy engine had trace auto-GC; v1 must get the bounded-but-safe version.

Decision #

D1 · Retention policy (defaults · engine-enforced) #

Per workflow (keyed by workflow name within a project's .nika/traces/):

Rule · Default · Rationale
keep the last **N** completed-run traces · `10` · the observability window
age cap · `30d` · stale traces exit even under N
project total size budget · `256MB` · the hard stop

Absolute exemptions — never collected regardless of any cap:

a trace whose last workflow state is paused (a pending gate is an OBLIGATION, not garbage) — it ages out only once answered or explicitly removed with nika trace rm,
the most recent trace of each workflow (the standing resume candidate).

D2 · When GC runs #

Opportunistically at nika run start (maintenance rides usage — no daemon, no cron, the Nextflow/cargo school). A collection that removes anything prints exactly ONE line to stderr:

text

1trace gc · removed 3 (2 aged · 1 over-budget) · kept 12 · 41MB

Silent deletion is forbidden (the anti-hidden-magic invariant). --no-gc skips collection for that invocation.

D3 · The explicit surface #

nika trace ls — traces with age · size · workflow · terminal state (completed/failed/`paused`) · the resume-candidate marker.
nika trace rm <trace>|--older-than <dur>|--all — explicit removal · removing a paused trace requires --force and says what it destroys (this trace carries an unanswered prompt for task <id>).

D4 · Configuration #

The three knobs ride the engine's existing config surface (nika doctor reports the active values). Config names and wiring are the implementation arc's to fix; the DEFAULTS above are the spec contract.

Alternatives considered #

No GC (status quo) — rejected: unbounded disk on every real user · the docs would have to teach manual cleanup of a dir the tool owns.
A `nika trace gc` verb only (fully manual) — rejected: nobody runs maintenance verbs · bounded-by-default is the 2026 baseline · the explicit surface exists IN ADDITION (D3).
GC daemon / background thread — rejected: no daemon is a v1 identity trait · opportunistic-at-run is sufficient and testable.
Content-addressed dedup of outputs before GC — deferred: real (outputs repeat across runs) but it is a storage-format change · retention must not wait for it.

Consequences #

Disk is bounded by default; resume and pause contracts survive GC by construction (the exemptions are the contract).
--resume against a collected trace keeps its ADR-099 behavior (readable error · nothing skips) — retention adds the trace ls surface to SEE what is resumable.
Traces stop being an unbounded liability in CI (the size budget is the cap that matters there).

Conformance sketch (ships with the implementation) #

paused-survives · a workflow_paused trace older than every cap survives GC · trace ls marks it paused.
resume-candidate-survives · the newest trace of a workflow survives even when over-budget alone.
visible-collection · an over-N history collects oldest-first · exactly one stderr line reports it · --no-gc leaves it intact.
forced-removal-speaks · trace rm on a paused trace refuses without --force and names the unanswered task.

Notes #

Interplay with idempotency keys (the §Persistence deferral) is unchanged — retention never re-runs anything by itself.
The engine index registration + nika trace ls|rm land with the implementation arc.

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

Every decision, with its status This one in the repo