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:
1 parent
befbe2e714
commit
2949612e2c
18 files changed
+491
-117
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user