Fork port: connection architecture + watcher machinery into the substrate (ADR-011/012 §3–§5, task fork-port-connection-watcher)

Kept half of the honker-core fork lands in
alkstore-sqlite/src/substrate/ as schema.rs / watcher.rs / ops.rs
(register D-17): PRAGMA/WAL open posture + set_journal_mode_wal retry,
Writer, Readers, the polling watcher family (SharedUpdateWatcher,
WatcherDeathGuard, stat_identity dead-man's switch), in_savepoint/
UnwindUndo mutation discipline, REAL-coercion arg helpers, notify
scalar + notifications table with the ADR-010 §6 at-attach pruning
cap, stream functions, lock functions.

Port deltas (ADR-012 §4): W-1 bounded reconnect backoff
(MAX_RECONNECT_TICKS=100), W-2 fallible watcher spawn (Result; engine
maps to Database at open in wave 3), dead-man's-switch panic replaced
by log-and-exit through the ordinary death path — death still closes
every subscriber (pinned by test, join now Ok). Table family
_honker_* -> __alkstore_* (D-10); duplicate-column race swallow
re-keyed to pragma_table_info (D-11); scheduler cron_expr -> spec;
fresh-only bootstrap, append-column migrations kept, column-order
equality pinned. Drops confirmed absent: cron, kernel/shm backends,
rate-limit/result tables, superseded queue functions (D-01..D-04).
file-id retained for the kept dead-man's switch (D-18).

43 engine-crate tests green (adapted inherited suites + delta tests +
cross-mechanism pressure); cargo build/clippy -D warnings/fmt clean.
PROVENANCE.md register updated to the landed state (D-01..D-20).
This commit is contained in:
glm-5.3-flash committed 2026-10-08 03:25:48 +00:00
1 parent 2d855b9546
commit 43a135c453
8 files changed
+2751 -30

No files matched your search

+108 -9
View File
@@ -1,7 +1,7 @@
---
id: fork-port-connection-watcher
name: Fork port — connection architecture + watcher machinery
status: pending
status: completed
depends_on: [fork-substrate-scaffold]
scope: broad
risk: medium
@@ -73,17 +73,17 @@ is not separately testable through a public seam).
## Acceptance Criteria
- [ ] Kept machinery ported with upstream names/structure preserved;
- [x] Kept machinery ported with upstream names/structure preserved;
diff vs. lineage reviewable (the wave-2 review checks this)
- [ ] Three watcher deltas applied; dead-man's switch exits without
- [x] Three watcher deltas applied; dead-man's switch exits without
panicking; `WatcherDeathGuard` still closes all subscribers
- [ ] Dropped machinery absent (no cron, no experimental watchers, no
- [x] Dropped machinery absent (no cron, no experimental watchers, no
rate-limit/result tables, no superseded queue functions)
- [ ] Table family is `__alkstore_*`; bootstrap fresh-only; race
- [x] Table family is `__alkstore_*`; bootstrap fresh-only; race
swallow re-keyed to `pragma_table_info`
- [ ] Inherited test suites green (adapted); watcher-death-closes-
- [x] Inherited test suites green (adapted); watcher-death-closes-
subscribers test present
- [ ] Substrate is sync (no tokio imports); no panics/`unwrap()` in
- [x] Substrate is sync (no tokio imports); no panics/`unwrap()` in
library code; clippy `-D warnings`, fmt clean
## References
@@ -95,8 +95,107 @@ is not separately testable through a public seam).
## Notes
> To be filled by implementation agent
- **Module layout**: the lineage's two files (`lib.rs` ~4k lines,
`honker_ops.rs` ~3.3k) map to three substrate modules in upstream's
order — `schema.rs` (pragmas/open, notify, bootstrap, `Writer`,
`Readers`), `watcher.rs` (the polling watcher family),
`ops.rs` (savepoint discipline, arg coercion, stream/lock ops, the
scalar-function attachments). Upstream names preserved on the kept
body; the mapping is register entry D-17 (the flat 4k `lib.rs`
doesn't fit the module-per-file standard; the ADR-013 fold makes the
module file the unit).
- **`file-id` retained** (D-18): the task's drop list names it among the
experimental backends' optional deps, but it drives the *kept*
dead-man's switch (`stat_identity`) — the kept-half scope wins for
this dep; target-gated `cfg(any(unix, windows))` exactly as upstream
carries it.
- **W-1 shape**: bounded reconnect backoff as a tick-counter
(`MAX_RECONNECT_TICKS` = 100 poll ticks between attempts → ≤10
open attempts/sec at the default 1 ms cadence, vs the lineage's
~1000/sec). Implemented inside `run_poll_loop`; the open step is a
parameter (default = the real open) so the test drives the loop
directly with a counting open.
- **W-2 shape**: `SharedUpdateWatcher::new*` and `UpdateWatcher::spawn*`
return `Result<_, String>` (upstream's spawn used `.expect(...)`).
The thread-build step is isolated in `UpdateWatcher::spawn_thread`
with a test-reachable stack-size knob so the `Err` path is provable
(an oversized stack reservation fails reliably; a nonexistent db path
does NOT fail thread spawn — baseline capture inside the loop is a
retry path, not a spawn failure). The engine maps the String into the
taxonomy's `Database` in wave 3.
- **Dead-man's switch delta**: identity mismatch logs the precise
diagnostic (upstream's panic message text, repointed) and `return`s
through the ordinary death path; the death-closes-subscribers test
additionally asserts `join()` is now `Ok` (the lineage's returned
the panic payload).
- **Bootstrap**: the scheduler's `cron_expr` column is carried as
`spec` in `__alkstore_scheduler_tasks` (the storage the scheduler
collapse lands in; cron strings are rejected at the engine layer —
ADR-009; naming is storage-internal so the column rename is
registration D-10's surface). The three append-column migrations
stay (enabled/max_attempts/claimed_at — the schema D-12's stamps
extend); the duplicate-column race swallow is re-keyed to
`pragma_table_info` exactly per ADR-012 §5.
- **Bootstrap schema scope**: the bootstrap carries the full
`__alkstore_*` family including the live/dead table shapes the
re-derivation extends — the tables must exist for the engine's
`alkstore_bootstrap()` to be total even before wave 3 wires the
queue ops; the re-derivation task alters/extends as its SQL needs.
- **Notify at-attach cap (D-16)**: `NOTIFY_ATTACH_MAX_ROWS` = 10_000,
oldest-first trim below the cap on every attach — replacing
upstream's "no pruning" posture per ADR-010 §6 (the fix for
unbounded notifications growth must not become a caller's chore).
- **Test scope boundary**: honker's queue-op suites (savepoint
dead-letter paths, claim pressure, `claimed_at` transitions,
scheduler) test the *re-derivation's* machinery — they are
`fork-rederive-queue-ops`'s floor, not this task's. This task
inherits: PRAGMA/WAL open posture (incl. the concurrent-open race
suite), watcher lifecycle + failure handling (fan-out, unsubscribe,
subscriber prune, death signal, all four journal modes, checkpoint,
stat identity, XOR-fold unit tests), savepoint machinery tests
(rollback-failure reporting, panic unwinding, scalar-path frames),
arg-coercion tests (driven through a probe scalar function — the
queue-function shape they exist for is re-derived next), notify
tests, lock tests, a new stream-ops suite, and a cross-mechanism
pressure test (streams+notify+locks, 5 producers) — the pressure
shape minus queue ops. Added: the W-1 backoff-bound test, the W-2
spawn-failure test, the panic-free death test, the
column-order-equality migration test, the legacy-orphan-inertness
test. 43 tests green.
- **Port state**: the substrate compiles as engine-crate modules and
is test-covered, but nothing re-exports through the engine's public
API yet — wave 3 wires `open` + the trait impl (`mod.rs` carries
`#![allow(dead_code)]` marked as lift-on-wiring).
## Summary
> To be filled on completion
The kept half of the honker-core fork landed in
`alkstore-sqlite/src/substrate/` as `schema.rs` + `watcher.rs` +
`ops.rs` (~1k lines ported machinery + adapted inherited suites, 43
tests): PRAGMA/WAL open posture with `set_journal_mode_wal` retry
(+ the concurrent-open race suite), `Writer`, `Readers` (incl. the
open-failure capacity-leak test), the polling watcher +
`SharedUpdateWatcher` + `WatcherDeathGuard` + `stat_identity`
dead-man's switch (all four journal modes + checkpoint + fan-out +
prune suites), `in_savepoint`/`UnwindUndo` (+ panic-discipline
tests), REAL-coercion arg helpers (+ coercion tests), the notify
scalar + table (now with the ADR-010 §6 at-attach pruning cap), the
stream functions (+ read/publish/offset suite), and the lock functions
(+ grant/refuse/renew/release suites). Deltas: W-1 bounded reconnect
backoff (tick-counting, test-pinned at ≤ 2 attempts in a 2.6 s window
vs the lineage's ~260), W-2 fallible watcher spawn (Result, mapped
error names the watcher), the dead-man's-switch panic replaced by
log-and-exit (join is Ok; death still closes every subscriber — the
adapted death-signal test pins both), `_honker_*` → `__alkstore_*`
(legacy tables pinned inert by test), duplicate-column race swallow
re-keyed to `pragma_table_info`, scheduler `cron_expr` → `spec`,
fresh-only bootstrap with append-column migrations (column-order
equality pinned). Dropped fully: cron, kernel/shm watcher backends,
rate-limit/result tables, superseded queue functions (the pressure
suite's queue half moved to the re-derivation task). `file-id` kept
(dead-man's-switch dep; register D-18 corrects D-02's enumeration).
PROVENANCE.md register updated to the landed state (D-01..D-20).
Verified: `cargo build`, `cargo test` (workspace; 43 sqlite-crate
tests green), `cargo clippy --all-targets -- -D warnings`, `cargo fmt
--check` all clean. Subtree stays sync (zero tokio); no
panics/unwrap/expect outside tests.