# ADR-013: Fold the forked substrate into `alkstore-sqlite` ## Status Accepted (2026-10-05, Phase 1 — operator review of the fork design; amends [ADR-012](012-forked-substrate-design.md) §1, superseding the `alkstore-substrate` crate identity; §3–§6 of ADR-012 are retained verbatim, §2 is retained with its enforcement re-sited per §2 below) ## Context ADR-011 fired the fork trigger; ADR-012 designed the fork and named the crate `alkstore-substrate` — a fourth, vendored, unpublished, path-dependency-only workspace crate below `alkstore-sqlite`. The design pillars (ADR-012 §2–§6) survived operator review intact. §1 did not: the operator flagged the naming and packaging for re-litigation, on two grounds — `alkstore-substrate` reads as a family-wide foundation crate in the family listing, which misdescribes what the code is, and since edits were coming regardless, the "keep the mechanical diff cheap" consideration that favored a separate fence was never going to pay out anyway. Re-litigation from the decided material: 1. **The substrate was never a foundation.** It is unpublished, has a path-dependency-only, exactly-one-consumer relationship (`alkstore-sqlite`), is SQLite-only machinery, and its storage surface was re-owned as `__alkstore_*` at fork time — it is not shared, not reusable by the Postgres engine, and not a layer anything else sits on. "Substrate" named the *ride relationship* correctly in ADR-003's original posture (`honker-rs as the SQLite substrate`); promoted to a crate name in the family listing alongside `alkstore`, `alkstore-sqlite`, and `alkstore-postgres`, it now falsely signals a general foundation layer that a Postgres-consuming reader might think they need. 2. **The mechanical-diff hope was already gone on day one.** The fork is born with port deltas (ADR-012 §4), table renames (ADR-011), dropped regions, family-standard porting, and — in any packaging — the re-derived half (new code, contract-derived names). No future point exists where a line-based diff against `/workspace/honker` stays mechanical. What survives is *cherry-pick* economics, and that is carried by ADR-012 §3's fidelity posture (keep the kept half's names), which is packaging-independent. 3. **The alksocks precedent is directly on point — twice.** (a) The alksocks review's F-1 defect escaped through exactly the seam this packaging creates: a vendored region governed by a *second, weaker* instruction set ("verbatim where kept" + an adjustments list) sitting next to the project's own conventions. The standalone vendored crate carries the same structural risk — "vendored lineage" is baked into its identity, and ADR-012 already had to negotiate exceptions to the family standard inside it. One codebase, one instruction set closes the seam. (b) alksocks' own resolution (ADR-013 there) retired the vendor framing and folded the forked core into the owning crate as a named module tree, keeping the reference checkout for behavioral differential testing — and that shape shipped on crates.io without provenance problems. 4. **The separate crate's advantages are weaker than they look, and the fold has a concrete bonus.** - *Compiler-enforced contract-blindness* (ADR-012 §2's strongest structural argument) becomes review-enforced under a fold: nothing stops substrate code inside `alkstore-sqlite` from importing alkstore core types that sit in a sibling dependency. This is the fold's one genuine loss, stated plainly and accepted — weighed against the misleading crate name, the dead wiring question, and the second-instruction-set seam, with the diff fence and the contract suite as the working guards. - *Dependency-graph hygiene*: ADR-012 §2's concern — "a vendored lineage crate must not acquire a dependency on our contract crate; the mirror inverts ADR-001" — becomes structurally impossible under a fold. There is no crate to carry the edge, and nothing depends on the folded code. - *License/provenance hygiene* ships fine in-tree: bundled license notice + module docs + the git-history fork line, the alksocks shape, proven. - *Bonus*: OQ-11 item (1) — the `bundled-sqlite` feature interplay of a substrate crate's rusqlite dependency with the engine crate's own — dissolves entirely. One crate, one rusqlite dependency. - *Restored shape*: ADR-001's split is three crates; ADR-011's "packaging follows ADR-001's split" line had been quietly stretched to four. The fold restores the decided shape. ## Decision ### 1. The fork lives inside `alkstore-sqlite` The forked honker-core machinery is **a bounded module subtree of `alkstore-sqlite`** — `alkstore-sqlite/src/substrate/` — mirroring upstream's module structure per ADR-012 §3's fidelity posture. There is no fourth crate; ADR-001's three-crate shape (`alkstore`, `alkstore-sqlite`, `alkstore-postgres`) stands unamended. The engine crate's public API surface carries nothing of the substrate (ADR-012 §2 and ADR-008 §6 unchanged — the contract is the returned trait; no substrate type or name reaches a consumer signature). The word "substrate" survives where it reads correctly — as engine-internal vocabulary for "the SQLite storage machinery this engine rides" (its origin, ADR-003's sense) — and stops being a crate name. Specs referencing "the substrate" after this ADR mean the module subtree, not a dependency. ### 2. ADR-012 §2–§6 are retained (§3–§6 verbatim; §2 re-sited) - **§2, contract-blind boundary**: retained in substance — the substrate module takes and returns primitives; the engine layer resolves contract semantics into primitive arguments exactly as ADR-012 §2 specifies — but its *enforcement site* moves from the crate graph to code discipline: the diff fence (lineage-relative diffs stay confined to the subtree), review, and the contract suite's equivalence pins, not Cargo. - **§3, fidelity posture**: retained verbatim — module structure and internal names of the kept half are upstream's; names are engine-internal either way, and cherry-pick economics (the posture's purpose) are packaging-independent. - **§4, port deltas**: retained verbatim (W-1 backoff, W-2 fallible spawn, panic-free watcher-fatal death, W-4 keep-RW, W-3 recorded). - **§5, bootstrap and schema machinery**: retained verbatim (append- column migrations; the `pragma_table_info` re-key of the duplicate- column race swallow; stamp columns via the re-derivation; no online rename migration; inert `_honker_*` orphans). - **§6, upstream tracking**: retained verbatim — deliberate cherry-picks recorded in the delta register, evaluated by port-cost logic; re-adoption keeps quality-read §7's bar. ### 3. Provenance and license, in-tree At fork-scaffold time `alkstore-sqlite` carries: - A **provenance register** recording upstream identity — `/workspace/honker` @ `f4e53c6`, MIT OR Apache-2.0 — and the delta list. Timing and initial contents are ADR-012 §1's (retained); location and format are this fold's to place — in-tree, beside the substrate subtree — and the exact format/granularity is OQ-11 item (2)'s. - The **dual license notice, bundled** in the substrate subtree (the alksocks `src/rfc1928/LICENSE` shape: upstream MIT + Apache text and copyright, preservation obligation perpetual, plus a fork-point statement and a modification note). Sublicensing is permitted by both licenses; the engine crate's license statement covers the whole crate. - **Git history is the fork-point record** — the scaffold commits are the provenance line, exactly as alksocks' extraction-commits window is. - `/workspace/honker` @ `f4e53c6` remains the **reference checkout** for cherry-pick candidates and differential testing; no dependency, no wiring. ### 4. OQ-11 reshaped OQ-11's item (1) — the Cargo-workspace layout and the `bundled-sqlite`/rusqlite interplay of a separate substrate crate — is **dissolved** by this fold; the provenance register is carried in-tree beside the substrate subtree (its location settles with the fold; its format/granularity remains OQ-11 item (2)). Items (2) (register format and delta-list granularity) and (3) (cherry-pick procedure in practice) remain, now scoped to the in-tree register. *(Resolved 2026-10-06 by [ADR-018](018-provenance-register-and-cherry-picks.md): the register is `src/substrate/PROVENANCE.md`; per-delta, category-tagged entries; the five-step cherry-pick procedure.)* ## Consequences **Positive** - The family listing is honest: three crates, and nothing in the crate table suggests a foundation layer shared across engines. - One codebase, one instruction set — the alksocks F-1 seam class (conventions-vs-fidelity gaps in a vendored region) is closed structurally rather than by vigilance. - The `bundled-sqlite`/rusqlite wiring question dissolves; the engine crate has exactly one rusqlite dependency. - ADR-001's decided shape stands unamended; the fork-scaffold task shrinks (no fourth crate to wire, version-coordinate, or gate). - Cherry-pick economics are unaffected: ADR-012 §3's fidelity posture is packaging-independent. **Negative (accepted)** - Contract-blindness is review-enforced, not compiler-enforced: substrate-module code could import alkstore core types that the sibling dependency makes available. The guards are the diff fence (lineage-relative diffs stay confined to the subtree), review, and the contract suite's equivalence pins. Assessed low-risk — the module's API takes primitives by design, and the code has no reason to reach upward. - Internal-name ambiguity ("substrate" the module vs. the retired crate name) — mitigated by this ADR being the naming record and by the specs' references resolving to the module subtree. ## References - [ADR-012](012-forked-substrate-design.md) — the fork design this ADR amends (§1 superseded; §3–§6 retained verbatim, §2 re-sited; this ADR does not reopen any retained question). - [ADR-011](011-sqlite-substrate-fork.md) — the fork decision and its scope register; packaging re-read under this ADR. - [ADR-001](001-crate-split.md) — the three-crate shape restored. - [ADR-003](003-sqlite-driver.md) — driver, seam, and watcher architecture; the origin of "substrate" as relationship vocabulary. - [ADR-008](008-contract-v1-pinning.md) §6 — the contract-is-the- returned-trait rule the fold preserves. - OQ-11 (`docs/architecture/open-questions.md`) — residue reshaped by §4 here. - alksocks `docs/architecture/decisions/011-inline-vendor.md` and `013-targeted-fork.md` (@ `/workspace/@alkdev/alksocks`) — the second-instruction-set finding (F-1) and the fold-into-owning-crate precedent this decision follows. - `docs/research/quality-read-honker-core.md` — the fork calculus and scope register. - [engine-sqlite.md](../engine-sqlite.md) — the engine spec this ADR's packaging realizes.