glm-5.3-flash
49743c690e
docs/plans/implementation.md records the wave structure (core -> substrate fork || pg engine -> sqlite engine -> contract suite -> release), the decided points (contract-suite layout = option (a), engine-tests vs equivalence-suite split, no CI, mem-engine/fuzzing deferrals surfaced), and the review-gate rhythm. Wave 1 (foundations): workspace scaffold, core errors/validation, value types, trait surface, contract-suite scaffold (+ADR-022), review gate. Wave 2 (substrate fork): fork scaffold/provenance, connection+watcher port, queue-op re-derivation on contract v1, provenance/floor close, review gate.
102 lines
4.3 KiB
Markdown
102 lines
4.3 KiB
Markdown
---
|
|
id: fork-port-connection-watcher
|
|
name: Fork port — connection architecture + watcher machinery
|
|
status: pending
|
|
depends_on: [fork-substrate-scaffold]
|
|
scope: broad
|
|
risk: medium
|
|
impact: component
|
|
level: implementation
|
|
tags: [wave-2, substrate]
|
|
---
|
|
|
|
## Description
|
|
|
|
Port the connection/watcher half of honker-core into
|
|
`alkstore-sqlite/src/substrate/` — the machinery the quality read
|
|
verified clean and ADR-011 §scope inherits near-verbatim. Source:
|
|
`/workspace/honker/honker-core/src/` @ `f4e53c6` (`lib.rs` ~4k lines,
|
|
`shm_watcher.rs`, `kernel_watcher.rs`).
|
|
|
|
**Port (the kept half, ADR-011 / quality-read §6):** the PRAGMA/WAL
|
|
open posture + `set_journal_mode_wal` retry logic; `Writer`; `Readers`;
|
|
the polling watcher + `SharedUpdateWatcher` + `WatcherDeathGuard` +
|
|
`stat_identity` dead-man's switch; the `in_savepoint` /
|
|
`UnwindUndo` mutation-discipline machinery; the REAL-coercion arg
|
|
helpers; the notify scalar + notifications table; stream functions;
|
|
lock functions.
|
|
|
|
**Port deltas (ADR-012 §4 — the only deliberate behavior changes):**
|
|
|
|
- W-1: bounded reconnect backoff in the watcher loop (no ~1000
|
|
open-attempts/sec on a vanished db file).
|
|
- W-2: watcher spawn becomes fallible; callers (the engine, wave 3)
|
|
surface the failure at open time.
|
|
- Dead-man's switch: the db-file-identity-change panic is replaced by
|
|
a deliberate watcher-fatal death (log the precise diagnostic, exit
|
|
through the ordinary death path); `WatcherDeathGuard`'s
|
|
death-closes-subscribers behavior unchanged.
|
|
|
|
**Drops (do not port):** `cron.rs`; the `kernel-watcher` /
|
|
`shm-fast-path` experimental watcher backends and their optional deps
|
|
(`notify`, `memmap2`, `libc`); the rate-limit and result tables; the
|
|
superseded queue functions (the queue half is re-derived in a separate
|
|
task).
|
|
|
|
**Table naming:** `_honker_*` → `__alkstore_*` across the ported
|
|
storage surface (ADR-011; ADR-010 §8 authorization). No online
|
|
migration machinery — fresh bootstrap only (ADR-012 §5).
|
|
|
|
**Fidelity posture (ADR-012 §3):** keep upstream's module structure and
|
|
internal function names for the kept half, including lineage tokens
|
|
(`Writer`, `run_poll_loop`, `in_savepoint`). Renames confined to the
|
|
table family and the hygiene deltas. The port is mechanical where
|
|
possible — the diff against the lineage must stay reviewable.
|
|
|
|
**Discipline deltas (family standard, ADR-012 §4):** no comments in
|
|
code (doc comments on the substrate's internal public surface fine),
|
|
no panics in library code (the dead-man's-switch delta is the big
|
|
one), no `unwrap()`/`expect()` outside tests. The substrate stays sync
|
|
— no tokio, no asyncification.
|
|
|
|
**Bootstrap re-keying (ADR-012 §5):** the fork owns the bootstrap;
|
|
append-column migrations stay; the duplicate-column race swallow is
|
|
re-keyed to `pragma_table_info` verification (present ⇒ benign race,
|
|
absent ⇒ propagate) — upstream's error-string matching is not
|
|
inherited.
|
|
|
|
**Tests (the floor, ADR-011):** inherit honker-core's suites for the
|
|
ported machinery — PRAGMA/WAL, watcher lifecycle + failure handling,
|
|
savepoint + multiprocess pressure — adapted to the new table names and
|
|
the three port deltas. These run as engine-crate tests (the substrate
|
|
is not separately testable through a public seam).
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] 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
|
|
panicking; `WatcherDeathGuard` still closes all subscribers
|
|
- [ ] 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
|
|
swallow re-keyed to `pragma_table_info`
|
|
- [ ] Inherited test suites green (adapted); watcher-death-closes-
|
|
subscribers test present
|
|
- [ ] Substrate is sync (no tokio imports); no panics/`unwrap()` in
|
|
library code; clippy `-D warnings`, fmt clean
|
|
|
|
## References
|
|
|
|
- docs/architecture/decisions/011-sqlite-substrate-fork.md (scope register)
|
|
- docs/architecture/decisions/012-forked-substrate-design.md §3–§5
|
|
- docs/research/quality-read-honker-core.md §6 (the fork scope), §2 (watcher verdict)
|
|
- /workspace/honker @ f4e53c6 (the lineage)
|
|
|
|
## Notes
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |