Fork scaffold: substrate subtree, provenance register, dual-license notice (ADR-011/012/013/018, task fork-substrate-scaffold)

alkstore-sqlite/src/substrate/PROVENANCE.md

@@ -0,0 +1,100 @@
+# PROVENANCE — the substrate fork's register
+
+The provenance register for the `src/substrate/` module subtree of
+`alkstore-sqlite` — per
+[ADR-018](../../../docs/architecture/decisions/018-provenance-register-and-cherry-picks.md)
+(format and procedure), [ADR-011](../../../docs/architecture/decisions/011-sqlite-substrate-fork.md)
+(the fork decision), [ADR-012](../../../docs/architecture/decisions/012-forked-substrate-design.md)
+(the fork design), and
+[ADR-013](../../../docs/architecture/decisions/013-fold-substrate-into-sqlite.md)
+(the fold into the engine crate).
+
+This file records: what lineage this code is, what has been changed
+relative to that lineage, and how each change arrived. It is the audit
+trail review works from; it is not itself a guard and not a decision
+record — the ADRs remain the decisions of record. Entries are
+append-only (amendment only to correct the record — a wrong path, a
+mis-cited hash — never to change the story; a superseded delta is a
+new entry citing the one it supersedes).
+
+## 1. Upstream identity
+
+- **Upstream project**: honker (the SQLite queue / notify library),
+  https://github.com/russellromney/honker — substrate package
+  `honker-core`.
+- **Fork point**: the reference checkout `/workspace/honker` @
+  `f4e53c6` (full hash
+  `f4e53c6b83ad2d6979c04098d576db024ce7e98d`, dated 2026-10-02;
+  `git describe` → package `node-v0.5.1-10-gf4e53c6`). The fork point
+  is deliberately *past* the published release: it carries the
+  unreleased fix train (issue #133's savepoint hardening of the
+  DELETE→INSERT dead-letter paths, the `claimed_at` addition, and
+  related hardening) that the published crates.io artifact (0.5.0,
+  2026-08-23) does not.
+- **Published-release lineage**: honker-core 0.5.0 (2026-08-23) on
+  crates.io; the fork continues from the repository lineage, not the
+  published tag.
+- **License**: MIT OR Apache-2.0 (upstream's dual license, carried
+  upstream as `LICENSE-MIT` / `LICENSE-APACHE`; bundled in-tree as
+  `src/substrate/LICENSE`, this directory — the preservation
+  obligation's carrier). Sublicensing is permitted by both licenses;
+  the engine crate's license statement covers the whole crate.
+- **Fork-point statement**: the scaffold commits — this subtree's
+  landing in alkstore's git history — are the provenance line, the
+  alksocks extraction-commit-window shape. Everything in the subtree
+  before the first port commit is lineage; every divergence is
+  register-addressable below.
+- **Inherited lineage facts**: the fork point itself carries upstream
+  changes we inherited verbatim and therefore do *not* list as deltas
+  — the fix train above (`4881f27`, `3ab43aa`, `claimed_at` et al.)
+  is upstream code, recorded here under upstream identity, not in the
+  delta register.
+- **Reference checkout**: `/workspace/honker` @ `f4e53c6` remains the
+  standing reference for cherry-pick candidates and differential
+  testing — no dependency, no wiring (ADR-012 §6).
+
+## 2. Delta register
+
+Per [ADR-018] §2: one entry per distinct delta, category-tagged —
+never one per commit (git history is the per-commit record; this
+register is the semantic index over it). Each entry pins five fields:
+**Category** / **What** / **Where** / **Why** / **Lineage**.
+
+Categories: `port delta` (kept-half adaptation), `re-derivation` (new
+contract-v1 code), `drop` (not ported), `hygiene`
+(family-standard porting), `cherry-pick` (adopted upstream lineage).
+
+The entries below are the initial entries fixed by the retained
+records (ADR-011's scope register, ADR-012 §4–§5) as
+**pre-declared checklist rows** — they name deltas the port tasks will
+make. `fork-provenance-and-floor` completes/verifies them against the
+actual ported tree at gate time (paths finalized, any port-surfaced
+adaptation appended). Cherry-picks: empty at scaffold, append-only
+forever.
+
+| ID | Category | What | Where | Why | Lineage |
+|----|----------|------|-------|-----|---------|
+| D-01 | drop | `cron.rs` (cron-string scheduling) not ported | — | ADR-009 rejects cron strings (scheduler collapse; §3) | ours |
+| D-02 | drop | experimental watcher backends (`kernel-watcher`, `shm-fast-path`) and their optional deps (`notify`, `memmap2`, `libc`, `file-id`) not ported | — | ADR-011 scope (drop); quality-read §6; cuts optional deps | ours |
+| D-03 | drop | rate-limit and result tables (cut-flags) not ported | — | ADR-002 cut-flags; ADR-011 scope (drop) | ours |
+| D-04 | drop | superseded queue functions not ported | — | ADR-011 scope (drop); the queue half is re-derived (see R-01) | ours |
+| D-05 | port delta | W-1 — bounded reconnect backoff in the watcher loop (a vanished db file no longer produces ~1000 open attempts/sec) | watcher machinery (`run_poll_loop` region) | ADR-012 §4; quality-read W-1 | ours |
+| D-06 | port delta | W-2 — watcher spawn becomes fallible; a store whose watcher could not start fails at open time | watcher machinery (`spawn_with_config` region) | ADR-012 §4; quality-read W-2 | ours |
+| D-07 | port delta | dead-man's switch — the db-file-identity-change panic replaced by a deliberate watcher-fatal death (log the precise diagnostic, exit through the ordinary death path); `WatcherDeathGuard`'s death-closes-subscribers behavior unchanged | `stat_identity` / `WatcherDeathGuard` region | ADR-012 §4 (family no-panics standard; observable semantics unchanged) | ours |
+| D-08 | port delta | W-4 — watcher connection opens RW: deliberate inheritance, keep RW | `run_poll_loop` region | ADR-012 §4 (keep-RW recorded; not actionable as a change — recorded where the read put it) | ours |
+| D-09 | port delta | W-3 — `data_version` u32 wrap: recorded, no action | watcher machinery (notes) | ADR-012 §4 (not actionable — recorded) | ours |
+| D-10 | port delta | table family renamed `_honker_*` → `__alkstore_*` across the storage surface; no online rename migration (fresh bootstrap only; leftover `_honker_*` orphans are inert and untouched) | bootstrap / schema + all queue-op SQL + notify table | ADR-011 (naming); ADR-010 §8 (pre-authorization); ADR-008 §4 (storage-internal); ADR-012 §5 | ours |
+| D-11 | port delta | bootstrap race swallow re-keyed — on `ALTER TABLE` duplicate-column failure, verify via `pragma_table_info` (present ⇒ benign race swallowed; absent ⇒ propagate); upstream's error-string matching not inherited | bootstrap / schema machinery | ADR-012 §5; quality-read §4 (schema brittleness) | ours |
+| D-12 | re-derivation | queue ops re-derived on contract v1 (new code, contract-derived names): enqueue + per-job option stamping; single-statement claim with per-row visibility from stamps; savepoint-guarded retry/fail/dead-letter; both-states no-stranded-rows `sweep_expired` with retention deletion; dead-visible `get_job`; scheduler tick with `@every` boundary math; stamp columns + `claimed_at` added to the schema | queue-op modules (new) + schema (stamp columns) | ADR-011 scope (re-derive); ADR-010 §3a/§5/§1; quality-read D-1–D-3, D-5–D-7 | ours |
+| D-13 | hygiene | the substrate stays sync — family porting is the discipline deltas, not an asyncification port; the bridged seam at the engine layer is the async story | whole subtree | ADR-012 §4; ADR-003 (seam) | ours |
+| D-14 | hygiene | no panics in library code (see D-07 for the one substantive instance), no `unwrap()`/`expect()` outside tests | whole subtree | AGENTS.md code conventions; ADR-011 (family standard) | ours |
+| D-15 | hygiene | no comments in code (doc comments fine) — ported upstream comments elided | whole subtree | AGENTS.md code conventions; ADR-011 (family standard) | ours |
+| D-16 | port delta | notify machinery — `notify()` scalar + notifications table kept with engine-internal hygiene, plus at-attach pruning cap implementing ADR-010 §6 | notify machinery (`attach_notify` region) | ADR-011 scope; ADR-010 §6 | ours |
+
+### Cherry-picks
+
+Empty at scaffold. Entries land here at adoption time (never swept),
+one per adopted upstream change, category `cherry-pick`, following
+[ADR-018] §3's five-step procedure; each cites the upstream commit
+hash(es) in its Lineage field and lands in the same commit as the
+applied change, plus one changelog line in the engine crate.