diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 5126b79..963d7bc 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -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 diff --git a/docs/architecture/decisions/012-forked-substrate-design.md b/docs/architecture/decisions/012-forked-substrate-design.md index 09e25d9..75458f3 100644 --- a/docs/architecture/decisions/012-forked-substrate-design.md +++ b/docs/architecture/decisions/012-forked-substrate-design.md @@ -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 diff --git a/docs/architecture/decisions/013-fold-substrate-into-sqlite.md b/docs/architecture/decisions/013-fold-substrate-into-sqlite.md index b36a87e..1b6f5a9 100644 --- a/docs/architecture/decisions/013-fold-substrate-into-sqlite.md +++ b/docs/architecture/decisions/013-fold-substrate-into-sqlite.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 diff --git a/docs/architecture/decisions/017-contract-versioning.md b/docs/architecture/decisions/017-contract-versioning.md index cbb5f84..1a4a343 100644 --- a/docs/architecture/decisions/017-contract-versioning.md +++ b/docs/architecture/decisions/017-contract-versioning.md @@ -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). diff --git a/docs/architecture/decisions/018-provenance-register-and-cherry-picks.md b/docs/architecture/decisions/018-provenance-register-and-cherry-picks.md new file mode 100644 index 0000000..a9b0d38 --- /dev/null +++ b/docs/architecture/decisions/018-provenance-register-and-cherry-picks.md @@ -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 \ No newline at end of file diff --git a/docs/architecture/engine-sqlite.md b/docs/architecture/engine-sqlite.md index f20ab44..ef5c3ed 100644 --- a/docs/architecture/engine-sqlite.md +++ b/docs/architecture/engine-sqlite.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. \ No newline at end of file diff --git a/docs/architecture/open-questions.md b/docs/architecture/open-questions.md index b9ae0e7..1eb1926 100644 --- a/docs/architecture/open-questions.md +++ b/docs/architecture/open-questions.md @@ -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.