{"row":{"id":"ADR-013","title":"Loom-based concurrency verification for L0.5 and L3","file":"adr-013-loom-concurrency-verification.md","status":"accepted","date":"2026-04-14","cites":3,"supersedes":[],"superseded_by":[],"layers":["L0.5","L3"],"tags":["testing","concurrency","loom","verification"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-013: Loom-based concurrency verification for L0.5 + L3","id":"adr-013-loom-based-concurrency-verification-for-l05--l3"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Diamond has "},{"k":"code","text":"unsafe_code = \"forbid\""},{"k":"text","text":" workspace-wide — no raw "},{"k":"code","text":"unsafe"},{"k":"text","text":" blocks. This catches one class of UB. It does "},{"k":"strong","text":"not"},{"k":"text","text":" catch concurrency bugs in safe-Rust primitives: a deadlock between two "},{"k":"code","text":"parking_lot::RwLock"},{"k":"text","text":"s, a missed wakeup on a "},{"k":"code","text":"tokio::sync::Notify"},{"k":"text","text":", a lost message on an "},{"k":"code","text":"mpsc::channel"},{"k":"text","text":" under selective receive."}]},{"k":"p","inline":[{"k":"text","text":"Tokio itself uses Loom (model-checks all possible interleavings of "},{"k":"code","text":"Atomic*"},{"k":"text","text":", "},{"k":"code","text":"Mutex"},{"k":"text","text":", "},{"k":"code","text":"mpsc"},{"k":"text","text":", etc.) as the "},{"k":"strong","text":"only"},{"k":"text","text":" reliable way to catch these bugs in its scheduler. Nika-runtime (Phase 3) will have channels, cancellation tokens, and a task graph — the exact territory where Loom has caught real bugs at tokio, crossbeam, parking_lot."}]},{"k":"p","inline":[{"k":"text","text":"The SOTA audit recommends landing the harness pattern "},{"k":"strong","text":"now"},{"k":"text","text":" in "},{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":" (which already uses tokio channels for test mocks) so that when "},{"k":"code","text":"nika-runtime"},{"k":"text","text":" ships, Loom is muscle memory."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":" gains a "},{"k":"code","text":"tests/loom/"},{"k":"text","text":" directory with at least one demo test proving the pattern (a 2-thread mock channel drain)."}],[{"k":"code","text":"[dev-dependencies]"},{"k":"text","text":" gains "},{"k":"code","text":"loom = \"0.7\""},{"k":"text","text":" behind a "},{"k":"code","text":"loom"},{"k":"text","text":" cfg flag."}],[{"k":"text","text":"CI workflow "},{"k":"code","text":"diamond-ci.yml"},{"k":"text","text":" adds a weekly (not per-PR — too slow) Loom job:"},{"k":"text","text":"loom:\n  schedule: cron: '0 4 * * 1'\n  run: RUSTFLAGS=\"--cfg loom\" cargo test --lib --test 'loom_*' -p nika-kernel-mock"}],[{"k":"strong","text":"Every"},{"k":"text","text":" future crate with concurrent primitives ("},{"k":"code","text":"nika-runtime"},{"k":"text","text":" with scheduler, "},{"k":"code","text":"nika-daemon"},{"k":"text","text":" with IPC, "},{"k":"code","text":"nika-mcp"},{"k":"text","text":" with stdio sessions) MUST ship Loom tests for the primitive at admission. Codified as invariant #29."}],[{"k":"text","text":"Loom failures block release tags ("},{"k":"code","text":"git tag v0.X.0"},{"k":"text","text":" gated on Loom green)."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Catches concurrency bugs proptest cannot reach (interleaving enumeration, not property generation)."}],[{"k":"text","text":"Aligns Diamond with tokio-scheduler-grade quality."}],[{"k":"text","text":"Forces concurrent primitive authors to design for testability (Loom hates over-coupled primitives)."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Loom is slow. 2-thread tests take ~10s; 3-thread ~10 minutes. Hence weekly, not per-PR."}],[{"k":"text","text":"Requires a "},{"k":"code","text":"--cfg loom"},{"k":"text","text":" parallel build of the crate — some dep tree duplication."}],[{"k":"text","text":"Learning curve for Loom semantics (atomic orderings, spuriousness)."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Shuttle (AWS, PCT-based, faster than Loom) is complementary. Revisit in Phase 4 when "},{"k":"code","text":"nika-runtime"},{"k":"text","text":" has >3-thread state spaces that exceed Loom's reach."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"tokio's "},{"k":"code","text":"mpsc"},{"k":"text","text":" Loom tests: "},{"k":"code","text":"tokio-stream/tests/"}],[{"k":"text","text":"crossbeam's "},{"k":"code","text":"loom_*"},{"k":"text","text":" modules"}],[{"k":"code","text":"nika-kernel-mock/src/"},{"k":"text","text":" — already uses tokio channels for test fixtures (direct beneficiary)"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — Proptest only","id":"alt-a--proptest-only"},{"k":"p","inline":[{"k":"text","text":"Rejected — proptest cannot enumerate interleavings."}]},{"k":"h","depth":3,"text":"Alt B — Shuttle only","id":"alt-b--shuttle-only"},{"k":"p","inline":[{"k":"text","text":"Rejected for now — Loom is more mature (AWS Shuttle is production but smaller community)."}]},{"k":"h","depth":3,"text":"Alt C — No concurrency verification","id":"alt-c--no-concurrency-verification"},{"k":"p","inline":[{"k":"text","text":"Rejected — it is 2026 and we are building a workflow engine. Inexcusable."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-006 — kernel ISP traits (Loom validates trait "},{"k":"em","text":"impls"},{"k":"text","text":", not traits themselves)"}],[{"k":"text","text":"Shadow zone #4 — L1 taint runtime (will need Loom when resolved)"}],[{"k":"text","text":"Invariant #29 — \"every crate with concurrent primitives ships Loom tests\" (added to "},{"k":"code","text":"nika-invariants.md"},{"k":"text","text":")"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"If weekly Loom run takes > 30 minutes, switch the Loom job to nightly-only and Shuttle per-PR. Both tools pay their keep at this tier of quality."}]}]

ADR-013

Loom-based concurrency verification for L0.5 and L3

accepted · 2026-04-14 · L0.5 L3 · cites 3

ADR-013: Loom-based concurrency verification for L0.5 + L3 #

Context #

Diamond has unsafe_code = "forbid" workspace-wide — no raw unsafe blocks. This catches one class of UB. It does not catch concurrency bugs in safe-Rust primitives: a deadlock between two parking_lot::RwLocks, a missed wakeup on a tokio::sync::Notify, a lost message on an mpsc::channel under selective receive.

Tokio itself uses Loom (model-checks all possible interleavings of Atomic*, Mutex, mpsc, etc.) as the only reliable way to catch these bugs in its scheduler. Nika-runtime (Phase 3) will have channels, cancellation tokens, and a task graph — the exact territory where Loom has caught real bugs at tokio, crossbeam, parking_lot.

The SOTA audit recommends landing the harness pattern now in nika-kernel-mock (which already uses tokio channels for test mocks) so that when nika-runtime ships, Loom is muscle memory.

Decision #

nika-kernel-mock gains a tests/loom/ directory with at least one demo test proving the pattern (a 2-thread mock channel drain).
[dev-dependencies] gains loom = "0.7" behind a loom cfg flag.
CI workflow diamond-ci.yml adds a weekly (not per-PR — too slow) Loom job:loom: schedule: cron: '0 4 * * 1' run: RUSTFLAGS="--cfg loom" cargo test --lib --test 'loom_*' -p nika-kernel-mock
Every future crate with concurrent primitives (nika-runtime with scheduler, nika-daemon with IPC, nika-mcp with stdio sessions) MUST ship Loom tests for the primitive at admission. Codified as invariant #29.
Loom failures block release tags (git tag v0.X.0 gated on Loom green).

Consequences #

Positive #

Catches concurrency bugs proptest cannot reach (interleaving enumeration, not property generation).
Aligns Diamond with tokio-scheduler-grade quality.
Forces concurrent primitive authors to design for testability (Loom hates over-coupled primitives).

Negative #

Loom is slow. 2-thread tests take ~10s; 3-thread ~10 minutes. Hence weekly, not per-PR.
Requires a --cfg loom parallel build of the crate — some dep tree duplication.
Learning curve for Loom semantics (atomic orderings, spuriousness).

Neutral #

Shuttle (AWS, PCT-based, faster than Loom) is complementary. Revisit in Phase 4 when nika-runtime has >3-thread state spaces that exceed Loom's reach.

Evidence #

tokio's mpsc Loom tests: tokio-stream/tests/
crossbeam's loom_* modules
nika-kernel-mock/src/ — already uses tokio channels for test fixtures (direct beneficiary)

Alternatives considered #

Alt A — Proptest only #

Rejected — proptest cannot enumerate interleavings.

Alt B — Shuttle only #

Rejected for now — Loom is more mature (AWS Shuttle is production but smaller community).

Alt C — No concurrency verification #

Rejected — it is 2026 and we are building a workflow engine. Inexcusable.

ADR-006 — kernel ISP traits (Loom validates trait impls, not traits themselves)
Shadow zone #4 — L1 taint runtime (will need Loom when resolved)
Invariant #29 — "every crate with concurrent primitives ships Loom tests" (added to nika-invariants.md)

Notes #

If weekly Loom run takes > 30 minutes, switch the Loom job to nightly-only and Shuttle per-PR. Both tools pay their keep at this tier of quality.

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

Every decision, with its status This one in the repo