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:
1 parent
2d855b9546
commit
43a135c453
8 files changed
+2751
-30
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user