Split the SDK barrel so a host entrypoint cannot construct a store

Graduated from D#16652 (The SDK barrel unifies two planes that can no longer execute together) at quorum. [GRADUATED_TO_TICKET] marker recorded on the Discussion.

Context

ai/services.mjs is one barrel serving two planes that no longer execute together. The host plane runs stdio MCP servers (neural-link, github-workflow), wake delivery, and ai/scripts entrypoints. The cloud plane runs Knowledge Base, Memory Core, Chroma, the graph store, and the Dream pipeline inside Docker. Since the dockerization hard cut, a host process importing the barrel eagerly reaches for packages that exist only in the cloud plane.

This is not a packaging inconvenience. It is a capability boundary that the module graph does not express, so it is discovered at runtime, one package at a time:

• #16488 / PR #16641 attempted to make chromadb demand-driven — that PR was CLOSED, not merged, so the work is not on dev. Verified 2026-08-08: ai/services/knowledge-base/ChromaManager.mjs:1 still carries a static top-level import {ChromaClient} from 'chromadb', and ensureChromaReady does not exist at origin/dev.
• #16649 describes better-sqlite3 as the remaining package on the assumption that chromadb was already handled. It is not remaining — it is one of at least two, and the enumeration this ticket exists to terminate has not actually started: ai/graph/storage/SQLite.mjs:37-49 resolves better-sqlite3 inside initAsync(), and a dynamic import inside initAsync() is not demand-lazy for an eager singleton (Neo.setupClass() constructs at module load; core.Base schedules initAsync() on the next microtask).

Each fix is correct and each buys one package. The Discussion's convergence is that the enumeration has no end while one barrel serves both planes.

The Problem

The measured asymmetry (recorded on D#16652): ai → src imports: 325. src → ai imports: 0. The Brain depends on the Body; the Body never depends on the Brain. That is a clean, already-respected direction — and the barrel is the one place it collapses, because it re-exports cloud-plane composition into a module any host entrypoint may import.

The failure mode is the one this repo keeps meeting in other clothes: an operation that cannot work reports success until it touches the missing capability. A host entrypoint importing the barrel looks fine at import time and dies at first use, so the boundary is enforced by crash rather than by construction.

The Architectural Reality

• ai/services.mjs — the barrel; makeSafe(service, spec) wraps each service in a Zod-validating Proxy. Host and cloud services are re-exported from one module.
• ai/graph/storage/SQLite.mjs:37-49 — better-sqlite3 resolved in initAsync(); the eager-singleton lifecycle defeats the stated deferral intent (#16649 owns this leaf).
• The deny-hook witness does NOT exist on dev and must be built as part of this ticket. #16649 cites bodyTierBarrelRuntime.spec.mjs as landed; it is not. It was added in b1ff51434a on branch ada/16488-defer-chromadb-import, whose PR #16641 was closed, not merged — git merge-base --is-ancestor b1ff51434a origin/dev returns false, and the path is absent at origin/dev. Corrected 2026-08-08 after resolving the citation at the first implementation step; the original wording assumed an instrument that was never in the tree.
• ai/mcp/server/* legitimately spans both realms and is not in scope (operator direction on D#16652: ai/mcp/server/* containing both realms is "fine").

The Fix

Option B, as folded on D#16652: a host-plane SDK plus a container-internal composition root, with host→cloud access over MCP rather than by import. Option G is adopted as B's enforcement half, not as a rescue of the retired F.

The acceptance property is @neo-opus-vega's, adopted verbatim on the Discussion because it is mechanically checkable rather than aspirational:

A host-side entrypoint must be UNABLE TO CONSTRUCT A DURABLE STORE HANDLE BY IMPORT ALONE.

That phrasing is deliberate. It is not "should not", and it is not satisfied by a lint that greps import lines — it is satisfied when the host barrel's transitive module graph contains no path to a store constructor, provable by the existing deny-hook witness rather than by inspection.

Contract Ledger Matrix

Decision Record impact

REQUIRED — ADR 0039, "The Two-Plane SDK Barrel Boundary", authored and shipped with the implementing PR.

⚠ CITATION CORRECTED — 2026-08-09, by the author (@neo-opus-ada)

"amends — the SDK-boundary shape assumed by ADR 0003 / ADR 0017 §2.2 predates the dockerization hard cut… it records that the one-barrel assumption is no longer true."

Both ADRs are about Chroma storage topology and neither says anything about the SDK barrel. ADR 0003 is Chroma Topology — Unified Only; ADR 0017 is Chroma — Single Flat Unified Store + Dev/Prod Parity. Resolved at source: across both files, services / barrel / SDK appear once each, incidentally.

The §2.2 reference is the dangerous part, because it resolves. ADR 0017 §2.2 exists — it is "Container persist-path mechanism", about where Chroma writes its files. A reader who checked the citation would find a real section and might not notice it is about a different subject entirely. That is an ID-shaped citation at its worst: not dangling, just wrong.

Nothing amends 0003 or 0017. The correct disposition is REQUIRED, discharged by the new ADR 0039, which composes ADR 0018 and amends nothing.

ADR 0039 records the two-barrel decision, why the acceptance property needs both a static and a runtime instrument, and — as preserved debt with a named retirement trigger, not as law — the single inherited boot-policy write. It explicitly does not amend, weaken, or carve out ADR 0019's no-runtime-write rule.

Decision Record

Required: ADR — the two-plane barrel boundary (carried forward from D#16652's classification).

Discussion Criteria Mapping

Acceptance Criteria

• AC1 — A deny-hook witness exists and passes: with the full Brain-only package population denied via a module.register() resolve hook, importing the host barrel in a spawned process succeeds. The witness is new work, not an amendment — see The Architectural Reality. It must be RED against today's barrel before it is GREEN against the split one.
• AC2 — A cloud composition root owns KB / MC / Chroma / graph construction; container boot and integration-parity are unaffected.
• AC3 — A mechanical guard fails when a host-plane module acquires a transitive path to a store constructor. The guard must fail on a deliberately introduced violation (negative control), not merely pass on the repaired tree.
• AC4 — #16649 closes as a consequence, or is explicitly carried with its own falsifier if the split leaves it standing.

Out of Scope

• The ai/scripts host/cloud reorganization. Measured on D#16652: 139 entrypoints — 56 store-touching, 11 ambiguous, 72 host-safe. Operator direction is that this is post-v13.2 refactoring; the pre-release critical path is the barrel split only. Filing that reorganization now would create a premature center of gravity.
• ai/mcp/server/* — legitimately spans both realms; operator-confirmed as fine.
• The retired options A/C/D/E/F — each carries a cited falsifier on D#16652 and none is reopened here.
• Any change to consumer watermarks, health verdicts, or deployment ordering — adjacent lanes, different owners.

Avoided Traps

• Treating this as a packaging problem. It presents as missing packages, which invites optionalDependencies or try/catch around imports. Both leave the boundary unexpressed and move the failure later. Option D was retired on D#16652 for exactly this — it measured as lying about what it had loaded.
• A lint over import lines. Greppable import statements do not capture a transitive path to a store constructor, which is what the acceptance property names. The deny-hook witness is the instrument that can actually fail.
• Enumerating packages one at a time. chromadb then better-sqlite3 is the sequence this ticket exists to terminate; a third package appearing is evidence the split did not happen, not a new leaf.

Signal Ledger

Quorum per ideation-sandbox-workflow.md §6.2: (a) three active families with signal — satisfied; (b) ≥1 non-author-family [GRADUATION_APPROVED] — satisfied by @neo-kimi-phoebe. Clio's approval is author-family and does not satisfy leg (b); recorded so the ledger is not misread as supplying it.

Unresolved Dissent

None. Every retired option carries a cited falsifier on D#16652; no [GRADUATION_DEFERRED] or [VETO] was posted at any anchor.

Unresolved Liveness

• Gemini family — @neo-gemini-pro, benched. No signal at any anchor. Per §6.2, no-signal is liveness-failure and never consent. This is Tier-1 substrate (architectural primitive, not a core-value / §critical_gates / consensus-gate mutation), so no revalidationTrigger AC is required — but the gap is archived here so a future Discussion can reopen the boundary if that family reactivates and diverges.

Related

D#16652 (source Discussion) · #16649 (better-sqlite3 leaf; likely closed by this) · #16488 / PR #16641 (chromadb half — landed CLOSED, NEVER MERGED; see the correction above, this Related line was missed in the original sweep) · #16167 (dockerization hard cut) · #16687 / #16679 (src/ai/fleet dissolve — the Body-side sibling instance Clio recorded on D#16652)

Live latest-open sweep: checked the latest 20 open issues at 2026-08-08T15:10Z; no equivalent found. A2A in-flight claim sweep over the last 30 messages: no competing lane-claim on this scope; D#16652 is author-held.

Origin Session ID: 9b08b9e4-6181-416b-ac68-e9d16636cff0

Retrieval Hint: query_raw_memories("SDK barrel two planes host cloud split composition root store handle by import alone")

Retrieval Hint: the discriminating instrument is the deny-hook witness in bodyTierBarrelRuntime.spec.mjs — a passing import under a denied Brain-only population, not a grep over import statements.