ADR-012: forked-substrate design — contract-blind boundary, fidelity posture, port deltas

Follow-through on OQ-06/ADR-011: pin the fork's structural decisions
(alkstore-substrate as a vendored path-dep crate, contract-blind API
boundary with contract formulas computed engine-side and pinned
equivalent by the contract suite, keep-the-kept-half API fidelity for
cheap cherry-picks, the W-1/W-2/dead-man's-switch/W-4 port deltas
decided per item, bootstrap re-keying off error-string matching, no
rename migration, deliberate upstream tracking).

Consistency sweep across the doc set for the fork: annotate ADR-003/
005/009/010 and core-contract for superseded ownership facts, fix
schedule-storage table naming (ADR-009 §5, queues.md), re-key ADR-010
§6's notifications hygiene to the at-attach cap the fork scope
realizes, add OQ-11 (scaffold-time residue), and complete both ADR
indexes. Independent review: 0 critical, warnings addressed.
This commit is contained in:
glm-5.3-flash committed 2026-10-05 05:00:55 +00:00
1 parent befbe2e714
commit 2949612e2c
18 files changed
+491 -117

No files matched your search

+57 -19
View File
@@ -14,12 +14,16 @@ everything else hangs off); **OQ-09 + OQ-05 resolved** (2026-10-05,
[ADR-010](decisions/010-queue-semantics-depth.md) — the queue semantics
track and the scheduler collapse/guarantee row); **OQ-06 resolved**
(2026-10-05, [ADR-011](decisions/011-sqlite-substrate-fork.md) — the
fork trigger fired on the published-artifact facts). Next: OQ-08
(rides the now-pinned trait shape and the ADR-011 substrate fork),
OQ-10 (versioning discipline for contract extensions; note ADR-011
changes its substrate-side facts for SQLite — the forked crate is
versioned in the family workspace, so the engine/core contract pairing
is what the discipline must track).
fork trigger fired on the published-artifact facts); **the fork
design follow-through** (2026-10-05,
[ADR-012](decisions/012-forked-substrate-design.md) — substrate
boundaries, fidelity posture, port deltas; its substrate-side residue
is OQ-11). Next: OQ-08 (rides the now-pinned trait shape and the
ADR-011 substrate fork), OQ-10 (versioning discipline for contract
extensions; note ADR-011 changes its substrate-side facts for SQLite —
the forked crate is versioned in this repository's Cargo workspace, so
the engine/core contract pairing is what the discipline must track), and
OQ-11 (fork follow-through items — substrate-side, non-consumer-facing).
Resolved questions stay listed with their resolution; they are not
deleted.
@@ -152,7 +156,11 @@ narrowed to the pinning work its own record already scoped.)*
**stands** (delete-on-ack; pg-boss's completed-row model is result
storage under another name). (8) Table layout — pg engine-owned
schema (`alkstore` default), queues are rows not tables; SQLite
rides `_honker_*`. No new error variants (ADR-008 §5's rule).
rides `_honker_*`. *(Item 8's SQLite half superseded 2026-10-05:
the `_honker_*` family is re-owned as `__alkstore_*` by the fork —
[ADR-011](decisions/011-sqlite-substrate-fork.md), designed per
[ADR-012](decisions/012-forked-substrate-design.md).)* No new error
variants (ADR-008 §5's rule).
- **Cross-references**: OQ-09, OQ-06.
### OQ-09: Is the scheduler a first-class mechanism, or queues + `schedule()`? — **RESOLVED**
@@ -225,15 +233,15 @@ narrowed to the pinning work its own record already scoped.)*
- **Resolution**: open. The pg engine is natively multi-host (POC #2
verified — no single-host assumption to remove); SQLite is
single-machine by nature (file-backed, NFS-two-writers unsupported —
honker's honesty posture, inherited). The unified surface must not
pretend SQLite is multi-host. Options: per-engine capability flags
(`Store::capabilities()`), a documented deployment matrix only
([deployment.md](deployment.md) carries the facts), or compile-time
knowledge only
(a consumer choosing the SQLite engine knows). Rides the now-pinned
contract shape ([ADR-008](decisions/008-contract-v1-pinning.md)):
the trait constrains where capability differences can surface.
- **Cross-references**: OQ-04, [ADR-006](decisions/006-wake-and-delivery-contract.md).
honker's honesty posture, inherited by the forked substrate). The
unified surface must not pretend SQLite is multi-host. Options:
per-engine capability flags (`Store::capabilities()`), a documented
deployment matrix only ([deployment.md](deployment.md) carries the
facts), or compile-time knowledge only (a consumer choosing the
SQLite engine knows). Rides the now-pinned contract shape
([ADR-008](decisions/008-contract-v1-pinning.md)): the trait
constrains where capability differences can surface.
- **Cross-references**: OQ-04, [ADR-006](decisions/006-wake-and-delivery-contract.md), [ADR-012](decisions/012-forked-substrate-design.md) (the substrate inherits the honesty posture).
### OQ-10: How do engine crates track core-contract version changes?
@@ -251,8 +259,38 @@ narrowed to the pinning work its own record already scoped.)*
- **Cross-references**: OQ-04 (the contract being versioned — now
including its first post-v1 extensions, ADR-009/ADR-010), OQ-02.
### OQ-11: Forked-substrate follow-through — scaffold, provenance register, and cherry-pick discipline
- **Origin**: [ADR-012](decisions/012-forked-substrate-design.md)
(the fork design; substrate-side residue), [ADR-011](decisions/011-sqlite-substrate-fork.md)
- **Status**: open
- **Priority**: medium (nothing consumer-facing rides on it; it
resolves within the fork-scaffold task, which it does not gate)
- **Resolution**: open. ADR-012 fixed the *design* (contract-blind
boundary, fidelity posture, port deltas, bootstrap machinery,
upstream-tracking stance) and also pinned the provenance register's
location, timing, and initial contents (§1). The residue is: (1) the
exact Cargo-workspace layout and build wiring of
`alkstore-substrate` in this repository (crate location, feature
gating of the `bundled-sqlite` interplay with the engine crate's own
rusqlite dependency); (2) the provenance register's *format and
delta-list granularity* (per-commit entries vs per-delta-class;
whether cherry-pick records append at adoption time — location,
timing, and initial contents are ADR-012 §1's, not re-opened here);
(3) the cherry-pick *procedure* in practice — how a candidate
upstream fix is evaluated, applied, and recorded so ADR-012 §6's
deliberate-work posture stays auditable. These resolve *within* the
fork-scaffold task (its opening section), not before it and not as a
gate on writing it; the scaffold's build wiring depends on (1)'s
outcome.
- **Cross-references**: OQ-08 (the contract surface the engine maps
the substrate under), OQ-10 (the substrate is a crate in this
repository's Cargo workspace — its versioning interacts with the
discipline), ADR-011, ADR-012.
## Deferred / Blocked
None currently. Every open OQ above is actionable Phase 1 architecture
work (capability-surface shape, versioning discipline) with its
evidence base complete — no external arrivals are being waited on.
None currently. Every open OQ above is actionable Phase 1 work
(capability-surface shape, versioning discipline, fork-scaffold
follow-through) with its evidence base complete — no external arrivals
are being waited on.