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

alkstore-sqlite/src/lib.rs

@@ -1 +1 @@
-
+mod substrate;

alkstore-sqlite/src/substrate/LICENSE

@@ -0,0 +1,226 @@
+The files under this `src/substrate/` directory are forked from
+honker-core (https://github.com/russellromney/honker) and are carried
+in-tree by alkstore-sqlite (fork per ADR-011,
+docs/architecture/decisions/011-sqlite-substrate-fork.md;
+fold into the engine crate per ADR-013,
+docs/architecture/decisions/013-fold-substrate-into-sqlite.md).
+Fork point: honker-core @ f4e53c6 (full hash
+f4e53c6b83ad2d6979c04098d576db024ce7e98d, package
+node-v0.5.1-10-gf4e53c6); /workspace/honker is the read-only
+reference checkout, kept for cherry-pick candidates and differential
+testing (no dependency, no wiring).
+
+Upstream is dual-licensed MIT OR Apache-2.0; both license texts below
+are preserved per their terms. Upstream code carries no per-file
+license headers — this bundled notice is the license obligation's
+carrier. The provenance register (PROVENANCE.md, this directory)
+records the fork point and every deliberate divergence from the
+lineage, per ADR-018
+(docs/architecture/decisions/018-provenance-register-and-cherry-picks.md).
+
+Modifications after the fork point are Copyright (c) 2026 the
+alkstore developers, licensed under the crate's license (MIT OR
+Apache-2.0, per alkstore-sqlite's Cargo.toml); the upstream notices
+below are preserved in full.
+
+---
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+---
+
+MIT License
+
+Copyright (c) 2026 Russell Romney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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.

alkstore-sqlite/src/substrate/mod.rs

@@ -0,0 +1,40 @@
+//! The substrate: the SQLite storage machinery forked from honker-core
+//! (dual-licensed MIT OR Apache-2.0, third-party upstream —
+//! github.com/russellromney/honker), carried in-tree as a bounded
+//! module subtree of `alkstore-sqlite` per
+//! ADR-013 (docs/architecture/decisions/013-fold-substrate-into-sqlite.md).
+//!
+//! Fork point: honker-core @ `f4e53c6` (`/workspace/honker`, package
+//! `node-v0.5.1-10-gf4e53c6`; full commit
+//! `f4e53c6b83ad2d6979c04098d576db024ce7e98d`). The reference checkout
+//! remains the source for cherry-pick candidates and differential
+//! testing — no dependency, no wiring (ADR-012 §6).
+//!
+//! Boundary (ADR-012 §2): this module is contract-blind storage
+//! machinery. It depends on nothing of ours — no `alkstore` core
+//! types, no contract traits, no error taxonomy. Its API takes and
+//! returns primitives; the engine layer above resolves contract
+//! semantics into primitive arguments and maps substrate outcomes into
+//! the contract taxonomy. Nothing here is re-exported through the
+//! engine crate's public API. The fork point, every deliberate
+//! divergence, and any future cherry-pick are recorded in the
+//! provenance register (`PROVENANCE.md`, this directory; ADR-018).
+//!
+//! Fidelity posture (ADR-012 §3): where scope *keeps* upstream
+//! machinery, upstream's module structure and internal function names
+//! survive — lineage tokens included — so future cherry-picks from the
+//! upstream fix train stay diffable. The re-derived half (the queue
+//! ops) is new code with contract-derived names.
+//!
+//! Runtime posture (ADR-012 §4): the substrate stays sync. The bridged
+//! seam at the engine layer remains the async story.
+//!
+//! License: upstream MIT OR Apache-2.0 — the bundled notice (`LICENSE`,
+//! this directory) is the preservation obligation's carrier;
+//! provenance register: [`PROVENANCE.md`](PROVENANCE.md).
+//!
+//! Scaffold state: this module is intentionally empty of machinery.
+//! The port tasks (`fork-port-connection-watcher`,
+//! `fork-rederive-queue-ops`) land the forked lineage and the
+//! re-derived queue ops here; the register and the license notice are
+//! already in place so the ports land into a finished frame.