ADR-018: substrate provenance register + cherry-pick procedure (OQ-11 resolved — Phase 1 question set closed)
This commit is contained in:
glm-5.3-flash committed
1 parent
eba77909a7
commit
c49befd195
7 files changed
+382
-45
No files matched your search
+10
-10
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-10-06 (ADR-017; OQ-10 resolved)
|
||||
last_updated: 2026-10-06 (ADR-018; OQ-11 resolved — question set closed)
|
||||
---
|
||||
|
||||
# alkstore — Architecture
|
||||
@@ -52,17 +52,15 @@ pending architecture review and OQ resolution.
|
||||
| [015](decisions/015-streams-depth.md) | Streams depth — carried-metadata keys, global-FIFO ordering row, `StreamEvent` shape, `publish_with_key_tx`, `trim_to` | Accepted |
|
||||
| [016](decisions/016-deployment-honesty.md) | Deployment honesty — no runtime capability surface; compile-time engine identity + documented matrix | Accepted |
|
||||
| [017](decisions/017-contract-versioning.md) | Contract versioning — core crate's semver is the contract version; change classes, pairing carriers, lockstep duties | Accepted |
|
||||
| [018](decisions/018-provenance-register-and-cherry-picks.md) | Substrate provenance register and cherry-pick procedure — `PROVENANCE.md` in-tree, per-delta category-tagged entries, five-step adoption discipline | Accepted |
|
||||
|
||||
## Open Questions
|
||||
|
||||
Tracked in [open-questions.md](open-questions.md) (OQ-01..NN; the
|
||||
Phase 0 register's OQ-ST-01..08 promote one-to-one — OQ-NN mirrors
|
||||
OQ-ST-NN — with new Phase 1 questions appended after). Open, in
|
||||
suggested resolution order:
|
||||
|
||||
- **OQ-11** (medium): forked-substrate follow-through (provenance
|
||||
register format, cherry-pick procedure; item (1) dissolved by
|
||||
[ADR-013](decisions/013-fold-substrate-into-sqlite.md)).
|
||||
OQ-ST-NN — with new Phase 1 questions appended after). **The open
|
||||
question set is empty** — all thirteen OQs are resolved (2026-10-04
|
||||
through 2026-10-06, ADR-001 through ADR-018).
|
||||
|
||||
Resolved (kept with resolutions): OQ-01 (feature scope), OQ-02
|
||||
(crate split), OQ-03 (drivers), OQ-07 (extension surface cut),
|
||||
@@ -79,10 +77,12 @@ scheduler guarantee row pinned), ~~OQ-05~~ (queue semantics depth —
|
||||
[ADR-014](decisions/014-outbox-tx-enqueue.md)), ~~OQ-12~~ (streams
|
||||
depth — [ADR-015](decisions/015-streams-depth.md)), ~~OQ-10~~
|
||||
(contract versioning —
|
||||
[ADR-017](decisions/017-contract-versioning.md)).
|
||||
[ADR-017](decisions/017-contract-versioning.md)), ~~OQ-11~~
|
||||
(fork follow-through — provenance register + cherry-pick procedure,
|
||||
[ADR-018](decisions/018-provenance-register-and-cherry-picks.md)).
|
||||
|
||||
No deferred OQs: all open questions are actionable Phase 1 work with
|
||||
complete evidence bases.
|
||||
No deferred OQs. With the question set closed, Phase 1 moves to
|
||||
architecture review closure and the implementation-phase gates.
|
||||
|
||||
## Document Lifecycle
|
||||
|
||||
|
||||
@@ -240,7 +240,10 @@ owned, tested, contract-ahead fork on maintenance, not on novelty.
|
||||
- OQ-06 (`docs/architecture/open-questions.md`) — the resolved
|
||||
assessment this ADR follow-throughs; OQ-11 — the scaffold-time
|
||||
residue this ADR leaves (workspace wiring, register format,
|
||||
cherry-pick procedure).
|
||||
cherry-pick procedure) — since resolved:
|
||||
[ADR-013](013-fold-substrate-into-sqlite.md) (item 1, dissolved)
|
||||
and [ADR-018](018-provenance-register-and-cherry-picks.md) (items
|
||||
2–3, the register and the procedure).
|
||||
|
||||
[ADR-001]: 001-crate-split.md
|
||||
[ADR-003]: 003-sqlite-driver.md
|
||||
|
||||
@@ -153,6 +153,10 @@ 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
|
||||
|
||||
|
||||
@@ -139,6 +139,7 @@ duty — that is what makes them non-events).
|
||||
clean. Core bumps its major (pre-1.0: its `0.y`).
|
||||
4. **Non-events** — engine-internal changes (engine opts, derived
|
||||
names, substrate cherry-picks per OQ-11's procedure —
|
||||
[ADR-018](018-provenance-register-and-cherry-picks.md), resolved:
|
||||
contract-blind by ADR-012 §2, so they cannot be contract events
|
||||
by construction); and doc clarifications *only* where a correct
|
||||
implementation could not have behaved differently before them
|
||||
@@ -333,6 +334,7 @@ number *must* encode the contract version (its manifest pin does,
|
||||
rejection that narrowed this discipline's scope (no descriptor to
|
||||
version); its three-carriers pattern (§4).
|
||||
- OQ-11 — the fork-scaffold residue whose cherry-pick procedure
|
||||
governs the substrate-side non-events (class 4).
|
||||
governs the substrate-side non-events (class 4) — resolved by
|
||||
[ADR-018](018-provenance-register-and-cherry-picks.md) (2026-10-06).
|
||||
- `docs/research/consumer-inventory.md` — the row-first gate on
|
||||
extensions (class 2/§2's closing rule).
|
||||
@@ -0,0 +1,298 @@
|
||||
# ADR-018: Substrate provenance register and cherry-pick procedure
|
||||
|
||||
## Status
|
||||
|
||||
Accepted (2026-10-06, Phase 1 — OQ-11's resolution, items (2) and (3);
|
||||
item (1) dissolved by [ADR-013](013-fold-substrate-into-sqlite.md) §4.
|
||||
Fills in the register's format and the cherry-pick procedure the prior
|
||||
records point at: [ADR-012](012-forked-substrate-design.md) §1/§6,
|
||||
[ADR-013](013-fold-substrate-into-sqlite.md) §3/§4,
|
||||
[ADR-017](017-contract-versioning.md) §2 class 4)
|
||||
|
||||
## Context
|
||||
|
||||
[ADR-011] fired the fork; [ADR-012] designed it (fidelity posture,
|
||||
contract-blind boundary, port deltas, upstream-tracking stance);
|
||||
[ADR-013] folded it into `alkstore-sqlite` as the `src/substrate/`
|
||||
module subtree. Every one of those records pinned the *existence* of a
|
||||
provenance register — its location (in-tree, beside the subtree), its
|
||||
timing (fork-scaffold), and its initial contents (upstream identity +
|
||||
the delta list) — and deferred two questions to OQ-11:
|
||||
|
||||
- **(2) The register's format and delta-list granularity.** ADR-012 §1
|
||||
named a delta list but not its shape: are port deltas recorded
|
||||
per-commit or per-delta-class? Does each future cherry-pick get its
|
||||
own entry, and does that entry land at adoption time or in a
|
||||
deferred sweep?
|
||||
- **(3) The cherry-pick procedure in practice.** ADR-012 §6 said
|
||||
adoption is deliberate and recorded; ADR-017 §2 class 4 said
|
||||
cherry-picks are non-events because ADR-012 §2's contract-blind
|
||||
boundary makes them structurally un-contract-side. Neither says
|
||||
*how* a candidate is evaluated, applied, or recorded so the
|
||||
deliberate-work posture stays auditable — and ADR-013's fold moved
|
||||
the boundary's enforcement from the crate graph to review
|
||||
discipline (its accepted negative consequence), which makes the
|
||||
audit trail the record that review works from rather than an
|
||||
optional artifact.
|
||||
|
||||
Much of the shape is already fixed by the retained records, and this
|
||||
ADR composes with it rather than re-deciding it:
|
||||
|
||||
- **The register is a second ledger — for the substrate, not the
|
||||
contract.** ADR-017 §1 rejected a parallel contract-version ledger
|
||||
under the one-normative-owner rule; the substrate is the
|
||||
complementary case: it is *not* a contract artifact, its changes are
|
||||
class-4 non-events ([ADR-017] §2.4), and its semver carrier (the
|
||||
engine crate's changelog) has no *versioning* reason to mention
|
||||
them — the semver does not move for them. Upstream lineage is a
|
||||
fact the contract machinery cannot carry — the register is its
|
||||
single normative home.
|
||||
- **The alksocks precedent supplies the in-tree shape.** alksocks'
|
||||
ADR-013 there (the targeted fork) folded the forked core into
|
||||
`src/rfc1928/` with a bundled module-level `LICENSE` notice, module
|
||||
docs carrying the fork-point statement, and git history as the
|
||||
fork-point record — and that shape shipped on crates.io without
|
||||
provenance problems ([ADR-013]'s context cites it twice). The
|
||||
distinction this ADR must add: alksocks' fold *retired* the vendor
|
||||
framing — upstream is quiet, and a future fix "arrives as a
|
||||
hand-port" with no register apparatus. The honker fork is the other
|
||||
case: its fix stream is *alive* (the #80/#133 train is what fired
|
||||
the fork), and ADR-012 §6 commits to deliberate cherry-picks.
|
||||
Recurrent adoption needs a durable ledger; a one-shot extraction
|
||||
does not. Both are the same posture — the record apparatus scales
|
||||
with the upstream's activity.
|
||||
- **The known defect class is named in the evidence base already.**
|
||||
`quality-read-honker-core.md` §3 (D-1..D-7) is the re-derivation
|
||||
work's rationale-of-record — its entries feed the re-derivation
|
||||
delta entries' Why fields; the fix train the fork point *inherits*
|
||||
(`4881f27`, `3ab43aa`, `claimed_at` et al. at `f4e53c6`) is
|
||||
upstream lineage, recorded under upstream identity, not a delta of
|
||||
ours. The scaffold work is formatting, not gathering.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. The provenance register: `alkstore-sqlite/src/substrate/PROVENANCE.md`
|
||||
|
||||
The provenance register is a **single Markdown file inside the
|
||||
substrate subtree** — `alkstore-sqlite/src/substrate/PROVENANCE.md` —
|
||||
per the ADR-017 §1 altitude: it is substrate lineage, so it lives with
|
||||
the substrate; the fold's "in-tree, beside the substrate subtree"
|
||||
placement ([ADR-013] §3) names the directory, this ADR names the
|
||||
file. (ADR-012 §1's `provenance.md`-at-the-crate-root named the
|
||||
pre-fold crate-root location; superseded with that §1. The uppercase
|
||||
filename follows the family precedent for standing-in-tree notices —
|
||||
the alksocks bundled `LICENSE` inside its forked module.)
|
||||
|
||||
The register **carries two sections**:
|
||||
|
||||
1. **Upstream identity** (ADR-012 §1's initial contents): the fork
|
||||
source — upstream project, `/workspace/honker` reference checkout @
|
||||
`f4e53c6` (package `node-v0.5.1-10-gf4e53c6`), published-release
|
||||
lineage (0.5.0, 2026-08-23), license **MIT OR Apache-2.0** — and
|
||||
the fork-point statement: the scaffold commits are the provenance
|
||||
line in git history, exactly alksocks' extraction-commit-window
|
||||
shape. This section is also where inherited lineage facts live
|
||||
(the fix train the fork point carries — `4881f27`, `3ab43aa`,
|
||||
`claimed_at` et al. — is upstream code we inherited, not a delta
|
||||
of ours).
|
||||
2. **The delta register** — §2's format; every divergence from
|
||||
lineage lands here *including cherry-picks* (their category is
|
||||
`cherry-pick`; §3's procedure writes to this section — there is
|
||||
no separate cherry-pick ledger). The scaffold's port deltas
|
||||
([ADR-012] §4, ADR-011's scope register) are its initial entries;
|
||||
cherry-picks are empty at scaffold, append-only forever.
|
||||
|
||||
The register is **not** itself a guard — the contract-blind
|
||||
boundary's guards remain the diff fence, review, and the contract
|
||||
suite ([ADR-013] §2's re-sited enforcement); the register is the
|
||||
audit trail review works from. It records: what lineage this is,
|
||||
what we have already changed, and how each change arrived. Its duty
|
||||
is completeness, not authority — the ADRs remain the decisions of
|
||||
record.
|
||||
|
||||
### 2. Delta register format: one entry per delta, tagged by category — never per commit
|
||||
|
||||
**Per-delta, category-tagged** — one entry per distinct delta, each
|
||||
carrying its category tag — never one per commit. Granularity the
|
||||
evidence dictates: the fork's divergence arrives in bursts (the
|
||||
scaffold adds the port deltas at once; a future upstream fix train
|
||||
lands as several commits, one category), and a
|
||||
per-commit register would grow into a duplicate of the git log — a
|
||||
second ledger for the same fact, the drift ADR-017 §1 rejects. The
|
||||
git history of this repository *is* the per-commit record; the
|
||||
register is the semantic index over it.
|
||||
|
||||
Each entry pins **five fields**:
|
||||
|
||||
- **Category** — one of the standing classes (kept-half port delta /
|
||||
re-derivation / drop / hygiene / cherry-pick), so the entry says at
|
||||
a glance which slice of the scope register the change touches.
|
||||
- **What** — the delta in one or two sentences (the read's W-numbers
|
||||
and D-numbers are admissible identifiers — e.g. "W-1 reconnect
|
||||
backoff applied").
|
||||
- **Where** — the module path(s) in the subtree the delta touches.
|
||||
- **Why** — the deciding record (ADR + section, quality-read finding,
|
||||
or the cherry-picked upstream issue/commit hash pair — see §3).
|
||||
- **Lineage** — for cherry-picks: the upstream commit hash(es) the
|
||||
delta carries (the `4881f27`/`3ab43aa` pattern the evidence uses);
|
||||
for born deltas (port deltas, re-derivations): "ours" — no upstream
|
||||
counterpart exists.
|
||||
|
||||
The **initial entries at scaffold** are fixed by the retained
|
||||
records, not re-litigated: the ADR-011 scope register's keep /
|
||||
re-derive / drop tripartition as three class entries, the three
|
||||
watcher deltas of ADR-012 §4 (W-1, W-2, the dead-man's-switch
|
||||
re-death; W-3's not-actionable and W-4's keep-RW recorded where the
|
||||
read put them), the `__alkstore_*` rename, and the port discipline
|
||||
deltas (sync substrate, no-panics/no-unwrap hygiene). Nothing here
|
||||
makes new decisions — the register's section 2 simply carries what
|
||||
ADR-011 §3 and ADR-012 §3–§5 already decided, in the format this ADR
|
||||
pins, and the scaffold task inherits the list as its checklist.
|
||||
|
||||
Subsequent entries append only. Amending an existing entry is
|
||||
permitted solely to *correct the record* (a wrong path, a mis-cited
|
||||
hash) — never to change the register's story; a superseded delta is a
|
||||
new entry that cites the one it supersedes.
|
||||
|
||||
### 3. The cherry-pick procedure: five steps, one record
|
||||
|
||||
When upstream (honker-core proper — the reference checkout's lineage)
|
||||
ships a fix relevant to the kept half, adoption runs this procedure,
|
||||
whose steps make the ADR-012 §6 deliberate-work posture auditable —
|
||||
each step leaves a checkable artifact:
|
||||
|
||||
1. **Candidate identification (notice duty).** Since no ambient
|
||||
tracking exists ([ADR-012] §6), a candidate arrives by deliberate
|
||||
review of the reference checkout / upstream history when a reason
|
||||
exists (a defect observed in our fork — first stop, upstream's fix
|
||||
train; a fresh upstream release announcement; a routine periodic
|
||||
sweep at whatever cadence future maintenance wants, or none).
|
||||
The procedure does *not* create a sweep duty — it says that if a
|
||||
candidate arrives by any route, the following steps apply.
|
||||
2. **Evaluation against the port-cost logic** ([ADR-012] §6): does
|
||||
the upstream fix touch kept-half machinery that still tracks its
|
||||
lineage? Does it beat our owned, tested, contract-ahead fork on
|
||||
maintenance rather than novelty (quality-read §7's re-adoption
|
||||
bar's spirit, applied per-fix)? A fix for a defect class in the
|
||||
re-derived machinery (the queue ops — D-1–D-3, D-5–D-7's fix
|
||||
classes; D-4's `lock_acquire` sits in the *kept* half and stays
|
||||
cherry-pick-eligible) is *not adoptable* — it
|
||||
evaluates against machinery that no longer tracks upstream, and
|
||||
the correct response to an observed defect in re-derived code is
|
||||
an owned fix under the fork's own test discipline.
|
||||
3. **Application** — hand-application of the upstream change against
|
||||
the kept half, preserving ADR-012 §3's fidelity posture (module
|
||||
structure and internal names survive the application where the
|
||||
surrounding code does; mechanical token renames stay banned), plus
|
||||
the family deltas the substrate always carries (no panics, no
|
||||
`unwrap()` outside tests — the port applies exactly this
|
||||
discipline to the inherited fixes). The application is verified
|
||||
against the inherited suites and the contract suite's substrate
|
||||
rows — the fork's version of alksocks' differential-suite guard,
|
||||
which is what makes "the cherry-pick preserved the inherited
|
||||
semantics" a testable claim rather than an assertion.
|
||||
4. **Record** — one delta-register entry (fields §2 pins;
|
||||
category `cherry-pick`, lineage = the upstream commit hashes,
|
||||
why = the evaluation's reasoning and outcome) **plus one line in
|
||||
the engine crate's changelog** — not a versioning event
|
||||
([ADR-017] §2 class 4: the engine's semver does not move for it),
|
||||
but a *changelog-visible* entry citing the register, so a reader
|
||||
auditing the crate's history between versions finds the substrate
|
||||
change without needing to know the register exists. This is the
|
||||
fold's answer to the crate-graph signal the standalone
|
||||
`alkstore-substrate` crate's version bumps would have carried.
|
||||
5. **Commit** — the cherry-pick commit message names the upstream
|
||||
commit hash(es); the register entry cites the commit. Git history
|
||||
and the register cross-link, and the fork point stays linear: every
|
||||
lineage-relative change from scaffold onward is
|
||||
register-entry-addressable by commit.
|
||||
|
||||
**Recording timing: at adoption, not swept.** The register entry and
|
||||
changelog line land in the same commit as the applied change; there
|
||||
is no deferred-registration window in which the delta exists but the
|
||||
record does not. Keeping it that way is what makes the audit trail
|
||||
trustworthy without enforcement tooling.
|
||||
|
||||
**When a cherry-pick would touch the re-derived half or cross the
|
||||
contract boundary**: it is *not* a cherry-pick, it is a fork change —
|
||||
an owned edit, evaluated by the engine's own review discipline, and
|
||||
(if it moves contract-visible semantics) classified under ADR-017's
|
||||
taxonomy like any engine change. The register records it as a born
|
||||
delta / maintenance entry, never as lineage adoption. The boundary
|
||||
between the two record types *is* ADR-012 §2's contract-blind
|
||||
boundary showing up in the maintenance posture.
|
||||
|
||||
### 4. What this does not decide
|
||||
|
||||
- **Sweep cadence** — deliberately unset; ADR-012 §6's no-ambient
|
||||
posture governs (adoption is triggered, never scheduled).
|
||||
- **Re-adoption of upstream as a dependency** — quality-read §7's
|
||||
bar, unchanged and untouched here.
|
||||
- **The scaffold task itself** — the register's initial contents and
|
||||
the scaffold work items are the fork-scaffold task's body, now
|
||||
without open questions; per the OQ's own scoping, this resolution
|
||||
gates nothing and precedes no task.
|
||||
|
||||
## Consequences
|
||||
|
||||
**Positive**
|
||||
|
||||
- OQ-11's residue resolves without new machinery: the register is one
|
||||
Markdown file whose two sections mirror the decided facts (identity,
|
||||
deltas — cherry-picks riding the delta register as tagged entries),
|
||||
the procedure is five steps of
|
||||
discipline already implied by retained records, and the class-4
|
||||
non-event status of substrate changes now has a paper trail.
|
||||
- The audit posture scales: scaffold-time deltas and future
|
||||
cherry-picks land in the same section in the same format, so a
|
||||
reader of the subtree in
|
||||
year three finds one register answering "what is this code, what
|
||||
differs from its lineage, and why."
|
||||
- The engine crate's changelog gains substrate visibility without
|
||||
gaining versioning noise — the one-line entries carry no semver
|
||||
movement and cannot be mistaken for contract events.
|
||||
|
||||
**Negative (accepted)**
|
||||
|
||||
- The register is maintained by discipline, not tooling — nothing
|
||||
enforces that a substrate edit added a register entry beyond the
|
||||
diff fence and review (the same accepted-enforcement weakness
|
||||
ADR-013 §2 stated for contract-blindness; its answer here is the
|
||||
same: low-risk because the boundary is structural and the file is
|
||||
adjacent).
|
||||
- The changelog-line duty adds one small standing obligation to every
|
||||
cherry-pick; skipping it is a process defect, not a caught one.
|
||||
|
||||
## References
|
||||
|
||||
- OQ-11 (`docs/architecture/open-questions.md`) — this ADR's
|
||||
resolution; items (2)/§2 and (3)/§3, item (1) dissolved by
|
||||
[ADR-013] §4.
|
||||
- [ADR-011](011-sqlite-substrate-fork.md) — the fork decision and its
|
||||
scope register (the initial delta entries' content).
|
||||
- [ADR-012](012-forked-substrate-design.md) — §1/§6 (the register's
|
||||
naming and the upstream-tracking stance), §2 (the boundary that
|
||||
splits cherry-picks from fork changes), §3 (the fidelity posture
|
||||
the application step preserves), §4 (the port deltas).
|
||||
- [ADR-013](013-fold-substrate-into-sqlite.md) — the fold (§3's
|
||||
in-tree placement; §4's reshaping of this OQ); its re-sited
|
||||
enforcement is the audit gap this register fills.
|
||||
- [ADR-017](017-contract-versioning.md) — §1 (the one-normative-
|
||||
owner rule this register's scope respects), §2 class 4 (substrate
|
||||
cherry-picks as non-events — the classification this procedure
|
||||
gives a paper trail), §4.2 (the version-stamped suite the
|
||||
application step verifies against).
|
||||
- `docs/research/quality-read-honker-core.md` — the fork calculus,
|
||||
the defect register (D-1..D-7), the W-1..W-4 notes, §7's
|
||||
re-adoption bar; the hash-citation pattern (`4881f27`, `3ab43aa`)
|
||||
§2's lineage field adopts.
|
||||
- alksocks `docs/architecture/decisions/011-inline-vendor.md` and
|
||||
`013-targeted-fork.md` (@ `/workspace/@alkdev/alksocks`) — the
|
||||
in-tree LICENSE/module-docs/git-history provenance shape, and the
|
||||
quiet-upstream contrast (no register apparatus needed there) that
|
||||
scopes why this ADR adds one.
|
||||
|
||||
[ADR-011]: 011-sqlite-substrate-fork.md
|
||||
[ADR-012]: 012-forked-substrate-design.md
|
||||
[ADR-013]: 013-fold-substrate-into-sqlite.md
|
||||
[ADR-017]: 017-contract-versioning.md
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-10-06
|
||||
last_updated: 2026-10-06 (OQ-11 resolved — ADR-018)
|
||||
---
|
||||
|
||||
# SQLite engine
|
||||
@@ -131,6 +131,8 @@ family is `__alkstore_*` (ADR-010 §8's naming authorization).
|
||||
| [014](decisions/014-outbox-tx-enqueue.md) | Outbox tx enqueue | `outbox_enqueue_tx` on `TxHandle`; derivation engine-side through the writer-slot lease |
|
||||
| [015](decisions/015-streams-depth.md) | Streams depth | key = carried metadata (the inherited nullable column); global-FIFO ordering; `trim_to` as a writer-lease delete; event shape already the substrate's |
|
||||
| [016](decisions/016-deployment-honesty.md) | Deployment honesty | no runtime capability surface; single-host posture stated by crate identity + docs; this engine never produces `PayloadTooLarge` (pinned in the contract suite) |
|
||||
| [017](decisions/017-contract-versioning.md) | Contract versioning | engine pins core `alkstore = "1.y"` in its manifest; substrate cherry-picks are class-4 non-events; adoption duties per its §5 |
|
||||
| [018](decisions/018-provenance-register-and-cherry-picks.md) | Substrate provenance | `src/substrate/PROVENANCE.md` (identity, delta register — cherry-picks as tagged entries); cherry-picks recorded at adoption, non-versioning |
|
||||
|
||||
## Open Questions
|
||||
|
||||
@@ -159,6 +161,11 @@ Resolved: **OQ-09** (scheduler collapse —
|
||||
[ADR-009](decisions/009-scheduler-collapse.md)), **OQ-05** (queue
|
||||
semantics depth — [ADR-010](decisions/010-queue-semantics-depth.md)),
|
||||
**OQ-12** (streams depth — [ADR-015](decisions/015-streams-depth.md)),
|
||||
and **OQ-08** (capability surface — none, by default ever;
|
||||
[ADR-016](decisions/016-deployment-honesty.md)),
|
||||
**OQ-08** (capability surface — none, by default ever;
|
||||
[ADR-016](decisions/016-deployment-honesty.md)), **OQ-10** (contract
|
||||
versioning — [ADR-017](decisions/017-contract-versioning.md)), and
|
||||
**OQ-11**
|
||||
(fork follow-through — the substrate's provenance register and the
|
||||
cherry-pick procedure;
|
||||
[ADR-018](decisions/018-provenance-register-and-cherry-picks.md)),
|
||||
2026-10-05/06.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-10-06 (OQ-10 resolved)
|
||||
last_updated: 2026-10-06 (OQ-11 resolved — Phase 1 question set closed)
|
||||
---
|
||||
|
||||
# alkstore — Open Questions
|
||||
@@ -34,9 +34,14 @@ identity + the documented deployment matrix); **OQ-10 resolved**
|
||||
(2026-10-06, [ADR-017](decisions/017-contract-versioning.md) — the
|
||||
core crate's semver is the contract version; four change classes
|
||||
with amend-in-place terminating at first release; the pairing
|
||||
tracked by manifest pin + version-stamped contract suite + docs).
|
||||
Next: **OQ-11** (fork follow-through items — substrate-side,
|
||||
non-consumer-facing).
|
||||
tracked by manifest pin + version-stamped contract suite + docs);
|
||||
**OQ-11 resolved** (2026-10-06,
|
||||
[ADR-018](decisions/018-provenance-register-and-cherry-picks.md) —
|
||||
`PROVENANCE.md` in the substrate subtree; per-delta category-tagged
|
||||
entries;
|
||||
five-step cherry-pick procedure recorded at adoption). **The Phase 1
|
||||
question set is closed** — no open OQs remain; Phase 1 moves to
|
||||
architecture review and the implementation-phase gates.
|
||||
|
||||
Resolved questions stay listed with their resolution; they are not
|
||||
deleted.
|
||||
@@ -241,35 +246,52 @@ narrowed to the pinning work its own record already scoped.)*
|
||||
[ADR-011](decisions/011-sqlite-substrate-fork.md); ADR-005's posture
|
||||
calculus applied, not renegotiated.
|
||||
|
||||
### OQ-11: Forked-substrate follow-through — scaffold, provenance register, and cherry-pick discipline
|
||||
### OQ-11: Forked-substrate follow-through — scaffold, provenance register, and cherry-pick discipline — **RESOLVED**
|
||||
|
||||
- **Origin**: [ADR-012](decisions/012-forked-substrate-design.md)
|
||||
(the fork design; substrate-side residue), [ADR-011](decisions/011-sqlite-substrate-fork.md),
|
||||
[ADR-013](decisions/013-fold-substrate-into-sqlite.md)
|
||||
- **Status**: open (reshaped 2026-10-05 by
|
||||
[ADR-013](decisions/013-fold-substrate-into-sqlite.md) — item (1)
|
||||
dissolved)
|
||||
- **Status**: resolved (2026-10-06, Phase 1 —
|
||||
[ADR-018](decisions/018-provenance-register-and-cherry-picks.md);
|
||||
item (1) dissolved 2026-10-05 by
|
||||
[ADR-013](decisions/013-fold-substrate-into-sqlite.md))
|
||||
- **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, as carried in-tree by
|
||||
ADR-013). The residue is: (1) **dissolved** by the fold
|
||||
([ADR-013](decisions/013-fold-substrate-into-sqlite.md)) — there is
|
||||
no separate substrate crate to wire; the engine crate carries one
|
||||
rusqlite dependency and no `bundled-sqlite` interplay question;
|
||||
(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 — the register
|
||||
lives in-tree beside the substrate subtree per
|
||||
[ADR-013](decisions/013-fold-substrate-into-sqlite.md) §3; its
|
||||
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.
|
||||
- **Resolution**: Pinned by
|
||||
[ADR-018](decisions/018-provenance-register-and-cherry-picks.md):
|
||||
(1) **dissolved** by the fold
|
||||
([ADR-013](decisions/013-fold-substrate-into-sqlite.md) §4) — no
|
||||
separate substrate crate, no wiring question. (2) **Register
|
||||
format/granularity**: a single in-tree file,
|
||||
`alkstore-sqlite/src/substrate/PROVENANCE.md` (the ADR-013
|
||||
placement, the file named;
|
||||
timing and initial contents stay ADR-012 §1's as carried in-tree),
|
||||
carrying two sections — upstream identity, and the delta register
|
||||
(cherry-picks ride it as `cherry-pick`-category entries; no
|
||||
separate log). The delta register is
|
||||
**per-delta, category-tagged, not per-commit** (this repo's git
|
||||
history is the
|
||||
per-commit record; a per-commit register would duplicate it), each
|
||||
entry pinning category / what / where / why / lineage (upstream
|
||||
commit hashes for cherry-picks, "ours" for born deltas). The
|
||||
initial entries are fixed by ADR-011's scope register and ADR-012
|
||||
§3–§5 — the register formats them, decides nothing new. (3)
|
||||
**Cherry-pick procedure**: five steps — notice (no ambient sweep;
|
||||
triggered candidate arrival), evaluation against ADR-012 §6's
|
||||
port-cost logic (fixes for re-derived-half classes are *not
|
||||
adoptable* — the correct response there is an owned fix), hand
|
||||
application preserving ADR-012 §3's fidelity posture and verified
|
||||
against the inherited suites + contract suite, record **at
|
||||
adoption** (register entry + one engine-changelog line citing the
|
||||
register — visible but non-versioning per
|
||||
[ADR-017](decisions/017-contract-versioning.md) §2 class 4), and a
|
||||
commit whose message names the upstream hash(es), cross-linking
|
||||
git history and register. A change touching the re-derived half or
|
||||
crossing the contract boundary is *not* a cherry-pick — it is an
|
||||
owned fork change under the engine's own discipline and, if
|
||||
contract-visible, ADR-017's taxonomy; ADR-012 §2's boundary is
|
||||
what splits the two record types. Its content lands as the
|
||||
fork-scaffold task's opening section; gates nothing.
|
||||
- **Cross-references**: OQ-08 (the contract surface the engine maps
|
||||
the substrate under), OQ-10 (the engine's versioning discipline
|
||||
now carries the fold's provenance duties in-tree — and its
|
||||
@@ -492,6 +514,7 @@ narrowed to the pinning work its own record already scoped.)*
|
||||
|
||||
## Deferred / Blocked
|
||||
|
||||
None currently. The one remaining open OQ above (OQ-11) is
|
||||
actionable Phase 1 work (fork-scaffold follow-through) with its
|
||||
evidence base complete — no external arrivals are being waited on.
|
||||
None. **The open question set is empty** — every OQ above is resolved
|
||||
(2026-10-04 through 2026-10-06, ADR-001 through ADR-018). Phase 1's
|
||||
remaining work is architecture review closure and the implementation
|
||||
phase's gates; no external arrivals are being waited on.
|
||||
Reference in new issue
Block a user