{"row":{"id":"ADR-016","title":"Cancellation model: future-drop primary, CancelCtx cooperative module","file":"adr-016-cancellation-model.md","status":"accepted","date":"2026-04-16","cites":14,"supersedes":[],"superseded_by":[],"layers":["L0.5"],"tags":["kernel","async","cancellation","forward-compat"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-016: Cancellation model: future-drop primary, CancelCtx cooperative module","id":"adr-016-cancellation-model-future-drop-primary-cancelctx-cooperative-module"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The kernel today has exactly one cancellation mechanism — "},{"k":"code","text":"ShellCancel"},{"k":"text","text":" — and it\nis intentionally narrow."}]},{"k":"p","inline":[{"k":"text","text":"Design decision #9 in "},{"k":"code","text":"crates/nika-kernel-core/src/io/process.rs:9-11"},{"k":"text","text":" states:\n\"cancel is a "},{"k":"code","text":"fn cancel(&self, id)"},{"k":"text","text":" method, not a "},{"k":"code","text":"CancellationToken"},{"k":"text","text":" field on\n"},{"k":"code","text":"ShellCommand"},{"k":"text","text":". This keeps "},{"k":"code","text":"tokio-util"},{"k":"text","text":" out of "},{"k":"code","text":"nika-kernel"},{"k":"text","text":".\" The trait method\nitself is "},{"k":"code","text":"ShellCancel::cancel(&self, id: &str)"},{"k":"text","text":" at\n"},{"k":"code","text":"crates/nika-kernel-core/src/io/process.rs:156-159"},{"k":"text","text":" and exists for subprocess\nmanagement (kill the child by id), not for cooperative task cancellation."}]},{"k":"p","inline":[{"k":"text","text":"No other cancellation mechanism existed before Wave 2:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"InferRequest"},{"k":"text","text":" ("},{"k":"code","text":"crates/nika-kernel-ai/src/provider.rs:197-220"},{"k":"text","text":", 11 fields\npre-S1-B) had no cancel field."}],[{"k":"code","text":"ContextCompressor::compress"},{"k":"text","text":"\n("},{"k":"code","text":"crates/nika-kernel-ai/src/context.rs:48-58"},{"k":"text","text":") takes "},{"k":"code","text":"messages"},{"k":"text","text":" and\n"},{"k":"code","text":"policy"},{"k":"text","text":" only — no cancel parameter."}],[{"k":"code","text":"MemoryStore::recall"},{"k":"text","text":" ("},{"k":"code","text":"crates/nika-kernel-ai/src/memory.rs:275-279"},{"k":"text","text":") is\npurely query in / hits out."}]]},{"k":"p","inline":[{"k":"text","text":"For v0.95 (DAG executor, multi-step agent loops, streaming inference) we need\ncooperative cancellation that propagates through a tree of in-flight tasks.\nTokio's "},{"k":"code","text":"select!"},{"k":"text","text":" plus future-drop already covers single futures, but agent\nloops and streams must check a cancellation flag between iterations to flush\npartial work cleanly."}]},{"k":"p","inline":[{"k":"text","text":"The kernel sits at L0.5 and must remain runtime-agnostic. Today's\n"},{"k":"code","text":"crates/nika-kernel/Cargo.toml:18-26"},{"k":"text","text":" lists only "},{"k":"code","text":"nika-error"},{"k":"text","text":",\n"},{"k":"code","text":"trait-variant"},{"k":"text","text":", "},{"k":"code","text":"thiserror"},{"k":"text","text":", "},{"k":"code","text":"miette"},{"k":"text","text":", "},{"k":"code","text":"serde"},{"k":"text","text":", "},{"k":"code","text":"serde_json"},{"k":"text","text":", "},{"k":"code","text":"bytes"},{"k":"text","text":",\n"},{"k":"code","text":"futures-core"},{"k":"text","text":". Adding "},{"k":"code","text":"tokio"},{"k":"text","text":" or "},{"k":"code","text":"tokio-util"},{"k":"text","text":" here would violate the layer\ncontract ("},{"k":"code","text":"scripts/ci/check-layering.sh"},{"k":"text","text":")."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Cancellation is layered, not unified."},{"k":"text","text":" Three coexisting mechanisms, each\nsolving a different problem:"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Primary: future drop."},{"k":"text","text":" Dropping a task's future stops its work.\n"},{"k":"code","text":"tokio::select!"},{"k":"text","text":" and "},{"k":"code","text":"tokio::time::timeout"},{"k":"text","text":" are the day-to-day tools.\nNo new API is needed for the common case."}],[{"k":"strong","text":"Cooperative: `CancelCtx`"},{"k":"text","text":" (new in S1-B,\n"},{"k":"code","text":"crates/nika-kernel-core/src/cancel.rs:35-67"},{"k":"text","text":"). "},{"k":"code","text":"Arc<AtomicBool>"},{"k":"text","text":"-backed\ntoken that all clones share. "},{"k":"code","text":"cancel()"},{"k":"text","text":" flips the flag; long-running\nloops poll "},{"k":"code","text":"is_cancelled()"},{"k":"text","text":" between iterations. Reserved field\n"},{"k":"code","text":"InferRequest.cancel: Option<CancelCtx>"},{"k":"text","text":" is pre-planted at v0.81 so\nfuture activation is purely additive ("},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" ratchet)."}],[{"k":"strong","text":"Process management: `ShellCancel`"},{"k":"text","text":" (existing,\n"},{"k":"code","text":"crates/nika-kernel-core/src/io/process.rs:156-159"},{"k":"text","text":"). Kill-by-id for\nsubprocesses. Stays as-is — different problem class."}]]},{"k":"p","inline":[{"k":"code","text":"CancelCtx"},{"k":"text","text":" deliberately uses "},{"k":"code","text":"std::sync::atomic::AtomicBool"},{"k":"text","text":" (no "},{"k":"code","text":"tokio"},{"k":"text","text":",\nno "},{"k":"code","text":"tokio-util"},{"k":"text","text":"). v0.95 may "},{"k":"em","text":"internally"},{"k":"text","text":" wrap a\n"},{"k":"code","text":"tokio_util::CancellationToken"},{"k":"text","text":" if we need richer behavior (timeout-as-cancel,\nparent-child trees), but the public API of "},{"k":"code","text":"CancelCtx"},{"k":"text","text":" will not change."}]},{"k":"p","inline":[{"k":"text","text":"Two explicit cancel traits planned for v0.95: "},{"k":"code","text":"Cancellable"},{"k":"text","text":" (poll-style check)\nand "},{"k":"code","text":"CancelPropagator"},{"k":"text","text":" (tree-wide propagation). Both will be defined when the\nDAG executor lands; defining them now would lock in shape choices we have not\nbenchmarked."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Pre-planting "},{"k":"code","text":"InferRequest.cancel"},{"k":"text","text":" at v0.81 turns \"wire cancellation\" into a\nzero-breaking-change activation later (Pattern 2, ROI 6.7x per ADR-007)."}],[{"k":"text","text":"Kernel stays free of "},{"k":"code","text":"tokio-util"},{"k":"text","text":" — "},{"k":"code","text":"cargo deny"},{"k":"text","text":" continues to enforce L0.5\npurity."}],[{"k":"code","text":"CancelCtx"},{"k":"text","text":" is testable in isolation today ("},{"k":"code","text":"crates/nika-kernel-core/src/cancel.rs"},{"k":"text","text":"\nships with 6 unit tests including clone-state propagation and Send+Sync)."}],[{"k":"text","text":"Three orthogonal mechanisms keep mental model clean: drop = default,\ncooperative = loops, process = subprocess."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Two cancellation idioms (drop vs cooperative) means contributors must learn\nwhen to use which. Mitigated by docs in "},{"k":"code","text":"cancel.rs"},{"k":"text","text":" module header."}],[{"k":"code","text":"CancelCtx"},{"k":"text","text":" does not propagate timeouts. v0.95 must layer\n"},{"k":"code","text":"tokio::time::timeout"},{"k":"text","text":" on top, not replace it."}],[{"k":"text","text":"Pre-planted "},{"k":"code","text":"Option<CancelCtx>"},{"k":"text","text":" field is dead weight until v0.95 — accepted\ncost, ~16 bytes per "},{"k":"code","text":"InferRequest"},{"k":"text","text":"."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ShellCancel's id-based signature stays unchanged. It is not migrated to\n"},{"k":"code","text":"CancelCtx"},{"k":"text","text":" because subprocess management is a different problem (the OS\nkills, not cooperative checking)."}]]},{"k":"h","depth":2,"text":"Evidence / Affected code","id":"evidence--affected-code"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-kernel-core/src/cancel.rs:35-67"},{"k":"text","text":" — "},{"k":"code","text":"CancelCtx"},{"k":"text","text":" struct + impl\n(Wave 2 / S1-B)."}],[{"k":"code","text":"crates/nika-kernel-core/src/cancel.rs:78-128"},{"k":"text","text":" — 6 unit tests, including\nclone-state propagation, idempotent cancel, Send+Sync."}],[{"k":"code","text":"crates/nika-kernel-ai/src/provider.rs:21"},{"k":"text","text":" — "},{"k":"code","text":"use crate::cancel::CancelCtx;"}],[{"k":"code","text":"crates/nika-kernel-ai/src/provider.rs"},{"k":"text","text":" — "},{"k":"code","text":"InferRequest.cancel: Option<CancelCtx>"},{"k":"text","text":" reserved field (S1-B)."}],[{"k":"code","text":"crates/nika-kernel-core/src/io/process.rs:9-11"},{"k":"text","text":" — design decision #9 rationale\n(no "},{"k":"code","text":"tokio-util"},{"k":"text","text":" in kernel)."}],[{"k":"code","text":"crates/nika-kernel-core/src/io/process.rs:156-159"},{"k":"text","text":" —\n"},{"k":"code","text":"ShellCancel::cancel(&self, id: &str)"},{"k":"text","text":" method."}],[{"k":"code","text":"crates/nika-kernel/Cargo.toml:18-26"},{"k":"text","text":" — kernel deps (no tokio, no\ntokio-util)."}],[{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":" — Pattern 1 (kernel traits\nupfront), Pattern 2 ("},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":")."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A -- `tokio_util::CancellationToken` directly in kernel","id":"alt-a----tokio_utilcancellationtoken-directly-in-kernel"},{"k":"p","inline":[{"k":"text","text":"Use "},{"k":"code","text":"CancellationToken"},{"k":"text","text":" as the public type in "},{"k":"code","text":"InferRequest.cancel"},{"k":"text","text":".\nRejected: pulls "},{"k":"code","text":"tokio-util"},{"k":"text","text":" into L0.5. Kernel must remain\nruntime-agnostic; "},{"k":"code","text":"CancellationToken"},{"k":"text","text":" is not "},{"k":"code","text":"no_std"},{"k":"text","text":" compatible and\nblocks future WASM compilation of kernel types. Wrapping it inside a\nprivate "},{"k":"code","text":"CancelCtx"},{"k":"text","text":" is an option for v0.95 — that keeps the public API\nruntime-agnostic."}]},{"k":"h","depth":3,"text":"Alt B -- No cancellation field until v0.95","id":"alt-b----no-cancellation-field-until-v095"},{"k":"p","inline":[{"k":"text","text":"Add "},{"k":"code","text":"cancel"},{"k":"text","text":" only when the DAG executor needs it.\nRejected: even with "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" we must update every call site\nthat builds "},{"k":"code","text":"InferRequest"},{"k":"text","text":". Pre-planting the "},{"k":"code","text":"Option<CancelCtx>"},{"k":"text","text":" is\n~16 bytes and zero ergonomic cost (constructor sets "},{"k":"code","text":"None"},{"k":"text","text":"). ROI 6.7x\nper ADR-007's calculation."}]},{"k":"h","depth":3,"text":"Alt C -- Cancel as a method on `ProviderInfer`","id":"alt-c----cancel-as-a-method-on-providerinfer"},{"k":"p","inline":[{"k":"text","text":"Expose "},{"k":"code","text":"provider.cancel(request_id)"},{"k":"text","text":" instead of a field on the request.\nRejected: providers do not own request lifetimes; the runtime does. A\nfield on the DTO lets the runtime cancel without round-tripping through\nthe provider trait, and it composes (a workflow can hand the same\n"},{"k":"code","text":"CancelCtx"},{"k":"text","text":" to many providers in parallel)."}]},{"k":"h","depth":3,"text":"Alt D -- Single global cancel signal","id":"alt-d----single-global-cancel-signal"},{"k":"p","inline":[{"k":"text","text":"Process-wide cancellation flag (e.g., on receipt of SIGINT).\nRejected: too coarse. We need per-task and per-DAG-subtree cancellation\nso the user can cancel one branch of a workflow without killing the rest."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-006 — kernel ISP trait design. ADR-016 adds "},{"k":"code","text":"CancelCtx"},{"k":"text","text":" as a\ndata type, not a kernel trait, so it does not extend ADR-006's trait\nlist."}],[{"k":"text","text":"ADR-007 — forward-compat invariants. The pre-planted "},{"k":"code","text":"cancel"},{"k":"text","text":" field is\nPattern 2 ("},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":") applied to a v0.95 hook."}],[{"k":"text","text":"ADR-014 — sealed kernel traits. "},{"k":"code","text":"CancelCtx"},{"k":"text","text":" is a struct, not a trait,\nso sealing does not apply."}],[{"k":"text","text":"ADR-018 — runtime + sync primitives (chooses tokio rt + parking_lot).\nADR-016 explicitly does not depend on the runtime choice."}],[{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":" — Pattern 1, Pattern 2."}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"Follow-ups:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"v0.95 DAG executor: define "},{"k":"code","text":"Cancellable"},{"k":"text","text":" (poll-check trait) and\n"},{"k":"code","text":"CancelPropagator"},{"k":"text","text":" (tree-wide propagation trait)."}],[{"k":"text","text":"v0.95 may wrap "},{"k":"code","text":"tokio_util::CancellationToken"},{"k":"text","text":" inside "},{"k":"code","text":"CancelCtx"},{"k":"text","text":" —\ndecision deferred until benchmarks show whether the wrap is worth the\nadded dep."}],[{"k":"text","text":"Document the \"drop vs cooperative\" choice in the agent self-serve\ndocs (Phase E)."}]]}]

ADR-016

Cancellation model: future-drop primary, CancelCtx cooperative module

accepted · 2026-04-16 · L0.5 · cites 14

ADR-016: Cancellation model: future-drop primary, CancelCtx cooperative module #

Context #

The kernel today has exactly one cancellation mechanism — ShellCancel — and it is intentionally narrow.

Design decision #9 in crates/nika-kernel-core/src/io/process.rs:9-11 states: "cancel is a fn cancel(&self, id) method, not a CancellationToken field on ShellCommand. This keeps tokio-util out of nika-kernel." The trait method itself is ShellCancel::cancel(&self, id: &str) at crates/nika-kernel-core/src/io/process.rs:156-159 and exists for subprocess management (kill the child by id), not for cooperative task cancellation.

No other cancellation mechanism existed before Wave 2:

InferRequest (crates/nika-kernel-ai/src/provider.rs:197-220, 11 fields pre-S1-B) had no cancel field.
ContextCompressor::compress (crates/nika-kernel-ai/src/context.rs:48-58) takes messages and policy only — no cancel parameter.
MemoryStore::recall (crates/nika-kernel-ai/src/memory.rs:275-279) is purely query in / hits out.

For v0.95 (DAG executor, multi-step agent loops, streaming inference) we need cooperative cancellation that propagates through a tree of in-flight tasks. Tokio's select! plus future-drop already covers single futures, but agent loops and streams must check a cancellation flag between iterations to flush partial work cleanly.

The kernel sits at L0.5 and must remain runtime-agnostic. Today's crates/nika-kernel/Cargo.toml:18-26 lists only nika-error, trait-variant, thiserror, miette, serde, serde_json, bytes, futures-core. Adding tokio or tokio-util here would violate the layer contract (scripts/ci/check-layering.sh).

Decision #

Cancellation is layered, not unified. Three coexisting mechanisms, each solving a different problem:

Primary: future drop. Dropping a task's future stops its work. tokio::select! and tokio::time::timeout are the day-to-day tools. No new API is needed for the common case.
Cooperative: `CancelCtx` (new in S1-B, crates/nika-kernel-core/src/cancel.rs:35-67). Arc<AtomicBool>-backed token that all clones share. cancel() flips the flag; long-running loops poll is_cancelled() between iterations. Reserved field InferRequest.cancel: Option<CancelCtx> is pre-planted at v0.81 so future activation is purely additive (#[non_exhaustive] ratchet).
Process management: `ShellCancel` (existing, crates/nika-kernel-core/src/io/process.rs:156-159). Kill-by-id for subprocesses. Stays as-is — different problem class.

CancelCtx deliberately uses std::sync::atomic::AtomicBool (no tokio, no tokio-util). v0.95 may internally wrap a tokio_util::CancellationToken if we need richer behavior (timeout-as-cancel, parent-child trees), but the public API of CancelCtx will not change.

Two explicit cancel traits planned for v0.95: Cancellable (poll-style check) and CancelPropagator (tree-wide propagation). Both will be defined when the DAG executor lands; defining them now would lock in shape choices we have not benchmarked.

Consequences #

Positive #

Pre-planting InferRequest.cancel at v0.81 turns "wire cancellation" into a zero-breaking-change activation later (Pattern 2, ROI 6.7x per ADR-007).
Kernel stays free of tokio-util — cargo deny continues to enforce L0.5 purity.
CancelCtx is testable in isolation today (crates/nika-kernel-core/src/cancel.rs ships with 6 unit tests including clone-state propagation and Send+Sync).
Three orthogonal mechanisms keep mental model clean: drop = default, cooperative = loops, process = subprocess.

Negative #

Two cancellation idioms (drop vs cooperative) means contributors must learn when to use which. Mitigated by docs in cancel.rs module header.
CancelCtx does not propagate timeouts. v0.95 must layer tokio::time::timeout on top, not replace it.
Pre-planted Option<CancelCtx> field is dead weight until v0.95 — accepted cost, ~16 bytes per InferRequest.

Neutral #

ShellCancel's id-based signature stays unchanged. It is not migrated to CancelCtx because subprocess management is a different problem (the OS kills, not cooperative checking).

Evidence / Affected code #

crates/nika-kernel-core/src/cancel.rs:35-67 — CancelCtx struct + impl (Wave 2 / S1-B).
crates/nika-kernel-core/src/cancel.rs:78-128 — 6 unit tests, including clone-state propagation, idempotent cancel, Send+Sync.
crates/nika-kernel-ai/src/provider.rs:21 — use crate::cancel::CancelCtx;
crates/nika-kernel-ai/src/provider.rs — InferRequest.cancel: Option<CancelCtx> reserved field (S1-B).
crates/nika-kernel-core/src/io/process.rs:9-11 — design decision #9 rationale (no tokio-util in kernel).
crates/nika-kernel-core/src/io/process.rs:156-159 — ShellCancel::cancel(&self, id: &str) method.
crates/nika-kernel/Cargo.toml:18-26 — kernel deps (no tokio, no tokio-util).
docs/architecture/forward-compat-invariants.md — Pattern 1 (kernel traits upfront), Pattern 2 (#[non_exhaustive]).

Alternatives considered #

Alt A -- `tokio_util::CancellationToken` directly in kernel #

Use CancellationToken as the public type in InferRequest.cancel. Rejected: pulls tokio-util into L0.5. Kernel must remain runtime-agnostic; CancellationToken is not no_std compatible and blocks future WASM compilation of kernel types. Wrapping it inside a private CancelCtx is an option for v0.95 — that keeps the public API runtime-agnostic.

Alt B -- No cancellation field until v0.95 #

Add cancel only when the DAG executor needs it. Rejected: even with #[non_exhaustive] we must update every call site that builds InferRequest. Pre-planting the Option<CancelCtx> is ~16 bytes and zero ergonomic cost (constructor sets None). ROI 6.7x per ADR-007's calculation.

Alt C -- Cancel as a method on `ProviderInfer` #

Expose provider.cancel(request_id) instead of a field on the request. Rejected: providers do not own request lifetimes; the runtime does. A field on the DTO lets the runtime cancel without round-tripping through the provider trait, and it composes (a workflow can hand the same CancelCtx to many providers in parallel).

Alt D -- Single global cancel signal #

Process-wide cancellation flag (e.g., on receipt of SIGINT). Rejected: too coarse. We need per-task and per-DAG-subtree cancellation so the user can cancel one branch of a workflow without killing the rest.

ADR-006 — kernel ISP trait design. ADR-016 adds CancelCtx as a data type, not a kernel trait, so it does not extend ADR-006's trait list.
ADR-007 — forward-compat invariants. The pre-planted cancel field is Pattern 2 (#[non_exhaustive]) applied to a v0.95 hook.
ADR-014 — sealed kernel traits. CancelCtx is a struct, not a trait, so sealing does not apply.
ADR-018 — runtime + sync primitives (chooses tokio rt + parking_lot). ADR-016 explicitly does not depend on the runtime choice.
docs/architecture/forward-compat-invariants.md — Pattern 1, Pattern 2.

Notes #

Follow-ups:

v0.95 DAG executor: define Cancellable (poll-check trait) and CancelPropagator (tree-wide propagation trait).
v0.95 may wrap tokio_util::CancellationToken inside CancelCtx — decision deferred until benchmarks show whether the wrap is worth the added dep.
Document the "drop vs cooperative" choice in the agent self-serve docs (Phase E).

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

Every decision, with its status This one in the repo