{"row":{"id":"ADR-120","title":"descend the shared service execution driver out of nika-runtime","file":"adr-120-service-execution-driver-split.md","status":"accepted","date":"2026-08-23","cites":0,"supersedes":[],"superseded_by":[],"layers":["L3","L4"],"tags":["architecture","runtime","execution","crate-size"],"room":true},"pin":{"release_tag":"v0.114.0","commit":"b1154df75255ee3538c7e1848e85f6d3abb54349"}}

[{"k":"h","depth":1,"text":"ADR-120: descend the shared service execution driver out of `nika-runtime`","id":"adr-120-descend-the-shared-service-execution-driver-out-of-nika-runtime"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"W06 adds one shared driver that joins descriptor-rooted, owned-byte admission\nfrom "},{"k":"code","text":"nika-execution"},{"k":"text","text":" to the production composition already owned by\n"},{"k":"code","text":"nika-runtime"},{"k":"text","text":". The local CLI and future service adapter must use this same\ndriver so nested workflows, permits, closure digests, redaction, and effect\nconstruction cannot drift between interfaces."}]},{"k":"p","inline":[{"k":"text","text":"Keeping that driver inside "},{"k":"code","text":"nika-runtime"},{"k":"text","text":" raised the crate from 14,931 to\n16,024 production lines. "},{"k":"code","text":"scripts/ci/check-crate-size.sh"},{"k":"text","text":" enforces a hard\n15,000-line budget. Hiding source from the counter, weakening the ceiling,\ncompressing the implementation, or dropping tests would preserve the wrong\nboundary rather than fix it. ADR-108 and the later "},{"k":"code","text":"nika-secret"},{"k":"text","text":" descent\nestablish the workspace precedent: when a coherent concern fills a crate,\nmove the concern into the lowest honest Diamond layer."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"Create the WIP L3 crate "},{"k":"strong","text":"`nika-service-execution`"},{"k":"text","text":" and move the W06 driver\nand its focused tests there as one unit."}]},{"k":"p","inline":[{"k":"text","text":"The new crate depends on the two L3 peers whose contracts it joins:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-execution"},{"k":"text","text":" owns immutable snapshot admission and the sealed\n"},{"k":"code","text":"ExecutionContext"},{"k":"text","text":" pairing;"}],[{"k":"code","text":"nika-runtime"},{"k":"text","text":" owns generic DAG execution and production composition."}]]},{"k":"p","inline":[{"k":"code","text":"nika-runtime"},{"k":"text","text":" no longer depends on "},{"k":"code","text":"nika-execution"},{"k":"text","text":" or the driver's\n"},{"k":"code","text":"tempfile"},{"k":"text","text":" test dependency. It exposes one narrow additional seam,\n"},{"k":"code","text":"compose::service_runtime"},{"k":"text","text":", beside "},{"k":"code","text":"production_runtime"},{"k":"text","text":"; the driver remains\nthe only owner of its service-safe surface and metadata-only result types.\n"},{"k":"code","text":"nika-cli"},{"k":"text","text":" imports the moved driver from "},{"k":"code","text":"nika-service-execution"},{"k":"text","text":". No HTTP,\nlistener, authentication, job-store, SDK, or "},{"k":"code","text":"nika-serve"},{"k":"text","text":" code enters this\nsplit."}]},{"k":"p","inline":[{"k":"text","text":"The moved public types intentionally leave the "},{"k":"code","text":"nika_runtime"},{"k":"text","text":" namespace and\nlive under "},{"k":"code","text":"nika_service_execution"},{"k":"text","text":". Both crates are internal, unpublished\nworkspace crates, and every current consumer is updated in the same commit.\nThe regenerated "},{"k":"code","text":"nika-runtime/public-api.txt"},{"k":"text","text":" records the removal and the one\nnew composer seam explicitly."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-runtime"},{"k":"text","text":" returns below the hard production-LOC ceiling without an\nexemption or behavioral deletion."}],[{"k":"text","text":"Local CLI/ARM and future remote execution keep one production driver and\none child-composition implementation."}],[{"k":"text","text":"Snapshot admission remains absent from the generic runtime crate."}],[{"k":"text","text":"The service result remains redacted and metadata-only; the move adds no\ntransport surface."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The workspace gains a seventieth crate and one same-layer L3 dependency."}],[{"k":"text","text":"The internal Rust namespace changes for the eight moved driver types."}],[{"k":"code","text":"service_runtime"},{"k":"text","text":" becomes public so a sibling crate can consume the narrow\nproduction seam; its public baseline must remain floored."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-service-execution"},{"k":"text","text":" lands WIP and is not published independently."}],[{"k":"code","text":"Cargo.lock"},{"k":"text","text":", the Diamond layer registry, and the CLI dependency graph gain\nthe new member."}],[{"k":"text","text":"The split changes ownership, not execution semantics."}]]},{"k":"h","depth":2,"text":"Required evidence","id":"required-evidence"},{"k":"list","ordered":true,"items":[[{"k":"code","text":"scripts/ci/check-crate-size.sh"},{"k":"text","text":" passes with every crate below 15,000\nproduction lines."}],[{"k":"code","text":"scripts/ci/check-layering.sh"},{"k":"text","text":" accepts all 70 workspace crates."}],[{"k":"code","text":"cargo check --workspace --locked"},{"k":"text","text":" passes with the regenerated lockfile."}],[{"k":"text","text":"Focused library tests pass for "},{"k":"code","text":"nika-cli"},{"k":"text","text":", "},{"k":"code","text":"nika-runtime"},{"k":"text","text":",\n"},{"k":"code","text":"nika-execution"},{"k":"text","text":", and "},{"k":"code","text":"nika-service-execution"},{"k":"text","text":"."}],[{"k":"text","text":"Workspace all-target clippy passes with warnings denied, and workspace\nformatting is clean."}],[{"k":"code","text":"nika-runtime/public-api.txt"},{"k":"text","text":" is regenerated deterministically and contains\n"},{"k":"code","text":"compose::service_runtime"},{"k":"text","text":" but none of the moved driver types."}],[{"k":"text","text":"The CLI extinction fixture reads the new crate and continues to reject a\nsecond execution/composition path."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Shrink or exempt `nika-runtime`","id":"shrink-or-exempt-nika-runtime"},{"k":"p","inline":[{"k":"text","text":"Rejected. The 1,024-line excess is a real architectural boundary signal. An\nexemption, test deletion, "},{"k":"code","text":"cfg"},{"k":"text","text":" trick, or compressed implementation would make\nthe maintainability gate dishonest."}]},{"k":"h","depth":3,"text":"Put the driver in `nika-execution`","id":"put-the-driver-in-nika-execution"},{"k":"p","inline":[{"k":"text","text":"Rejected. The driver consumes "},{"k":"code","text":"nika-runtime"},{"k":"text","text":" composition; making\n"},{"k":"code","text":"nika-execution"},{"k":"text","text":" depend on runtime would invert the admission boundary and\ncreate a cycle with the pre-existing runtime-to-execution edge."}]},{"k":"h","depth":3,"text":"Put the driver in an L4 interface crate","id":"put-the-driver-in-an-l4-interface-crate"},{"k":"p","inline":[{"k":"text","text":"Rejected. CLI, ARM, and Serve must share it. An interface-owned driver would\nmake one interface canonical and force the others to depend sideways on an\nadapter rather than on a shared L3 implementation."}]}]

ADR-120

descend the shared service execution driver out of nika-runtime

accepted · 2026-08-23 · L3 L4

ADR-120: descend the shared service execution driver out of `nika-runtime` #

Context #

W06 adds one shared driver that joins descriptor-rooted, owned-byte admission from nika-execution to the production composition already owned by nika-runtime. The local CLI and future service adapter must use this same driver so nested workflows, permits, closure digests, redaction, and effect construction cannot drift between interfaces.

Keeping that driver inside nika-runtime raised the crate from 14,931 to 16,024 production lines. scripts/ci/check-crate-size.sh enforces a hard 15,000-line budget. Hiding source from the counter, weakening the ceiling, compressing the implementation, or dropping tests would preserve the wrong boundary rather than fix it. ADR-108 and the later nika-secret descent establish the workspace precedent: when a coherent concern fills a crate, move the concern into the lowest honest Diamond layer.

Decision #

Create the WIP L3 crate `nika-service-execution` and move the W06 driver and its focused tests there as one unit.

The new crate depends on the two L3 peers whose contracts it joins:

nika-execution owns immutable snapshot admission and the sealed ExecutionContext pairing;
nika-runtime owns generic DAG execution and production composition.

nika-runtime no longer depends on nika-execution or the driver's tempfile test dependency. It exposes one narrow additional seam, compose::service_runtime, beside production_runtime; the driver remains the only owner of its service-safe surface and metadata-only result types. nika-cli imports the moved driver from nika-service-execution. No HTTP, listener, authentication, job-store, SDK, or nika-serve code enters this split.

The moved public types intentionally leave the nika_runtime namespace and live under nika_service_execution. Both crates are internal, unpublished workspace crates, and every current consumer is updated in the same commit. The regenerated nika-runtime/public-api.txt records the removal and the one new composer seam explicitly.

Consequences #

Positive #

nika-runtime returns below the hard production-LOC ceiling without an exemption or behavioral deletion.
Local CLI/ARM and future remote execution keep one production driver and one child-composition implementation.
Snapshot admission remains absent from the generic runtime crate.
The service result remains redacted and metadata-only; the move adds no transport surface.

Negative #

The workspace gains a seventieth crate and one same-layer L3 dependency.
The internal Rust namespace changes for the eight moved driver types.
service_runtime becomes public so a sibling crate can consume the narrow production seam; its public baseline must remain floored.

Neutral #

nika-service-execution lands WIP and is not published independently.
Cargo.lock, the Diamond layer registry, and the CLI dependency graph gain the new member.
The split changes ownership, not execution semantics.

Required evidence #

scripts/ci/check-crate-size.sh passes with every crate below 15,000 production lines.
scripts/ci/check-layering.sh accepts all 70 workspace crates.
cargo check --workspace --locked passes with the regenerated lockfile.
Focused library tests pass for nika-cli, nika-runtime, nika-execution, and nika-service-execution.
Workspace all-target clippy passes with warnings denied, and workspace formatting is clean.
nika-runtime/public-api.txt is regenerated deterministically and contains compose::service_runtime but none of the moved driver types.
The CLI extinction fixture reads the new crate and continues to reject a second execution/composition path.

Alternatives considered #

Shrink or exempt `nika-runtime` #

Rejected. The 1,024-line excess is a real architectural boundary signal. An exemption, test deletion, cfg trick, or compressed implementation would make the maintainability gate dishonest.

Put the driver in `nika-execution` #

Rejected. The driver consumes nika-runtime composition; making nika-execution depend on runtime would invert the admission boundary and create a cycle with the pre-existing runtime-to-execution edge.

Put the driver in an L4 interface crate #

Rejected. CLI, ARM, and Serve must share it. An interface-owned driver would make one interface canonical and force the others to depend sideways on an adapter rather than on a shared L3 implementation.

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

Every decision, with its status This one in the repo