Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0108

ADR-0108: The AST toolkit stays host-side — the volks codedirector consumes it through a contracts protocol injection seam (N-V4)

field	value
Status	Accepted — Accepted (ruling, Mohamed, 2026-10-18, on the ratify-plan prompt, verbatim: "Ratify and implement all of it")
Date	2026-10-18
Register	factory (`docs/adr`, 4-digit ids)
Source	`docs/adr/0108-the-ast-toolkit-stays-host-side-the-volks-codedirector-consumes-it-through-a-contracts-protocol-injection-seam.md` — permalink at `6a496a109` (unchanged on master since that commit)
Wiki register entry	ADR-0108 (wiki status: Accepted)

← ADR-0107 · ADR-0109 →

The record

Status: Accepted (ruling, Mohamed, 2026-10-18, on the ratify-plan prompt, verbatim: "Ratify and implement all of it") · Date: 2026-10-18

Context

agents.volks.codedirector.implementation (591 frozen LOC) was stopped because it imports scripts.serialize_codebase_ast (gate0_construction_smoke, generate_skeleton_modules) in addition to the repo-root hack shared with architect/codedirector. The AST toolkit is the host/root code-intelligence engine — 13,797 LOC of serializer/daemon/CLI over the whole root tree, not a component of the packages graph; lifting it would drag the root's tests, daemons and CLI into a component package for two function calls.

Mohamed directed (2026-10-18) that the missing features be implemented until done; this ADR is the N-V4 ruling the plan proposes for the toolkit half of the knot.

Decision (proposed)

scripts.serialize_codebase_ast is NOT lifted into the packages tree. The two functions the codedirector needs are consumed through an injection seam: orchestrata-contracts gains a small protocol (AstToolkitProtocol — gate0_construction_smoke and generate_skeleton_modules signatures, REQ-116-9xx), importable in the volks venv; codedirector.implementation lands retargeted to the protocol (TYPE_CHECKING import), and the HOST wires the real toolkit at runtime — the host already owns the toolkit, so no new runtime exists. Signature parity holds (the frozen fixture pins declared params, which the protocol mirrors). The function-scope import orchestrata_ultimate repo-root hacks become the landed packages' own root resolution (the ORCHESTRATA_ROOT pattern already shipped in orchestrata_volks/drivers/claude_code_driver.py).

Alternatives rejected

Lift the full 13.8K-LOC toolkit as a package: drags the host's code-intelligence engine (daemons, CLI, tests, warm caches) into the components graph for two call sites — the wrong boundary (ADR-0008 transcription ≠ correctness; ADR-0103 clean target).
Copy the two functions into volks: forks the toolkit's implementation — two truths for one function, the exact duplication the lift exists to kill.

Consequences

The components graph gains one small contracts protocol + real tests; the toolkit stays single-sourced in the host.
codedirector.implementation is fully landed; its parity claims (REQ-125-060) un-hold.
The host's wiring site (where the protocol meets the real toolkit) is recorded as owed wiring work with the packet.

Provenance

Frozen measurement (this repo, 2026-10-18): serialize_codebase_ast 13,797 LOC; the two call sites from the lander's stopped-importer record; D-V7 injection-seam decision lineage in packages/volks/design/decisions.md.
Mohamed's directive 2026-10-18 ("implement the missing features until done"); plan: plans/tools-family-implementation-plan.md.

Also mentioned: ADR-0008, ADR-0103

Rulings cited

None.

Specs cited

None (or no spec page exists for the ones named).