docs/research/fuzzing.md (new) — the adoption record and campaign plan,
inheriting the alkcall/alktunnels/alksocks/alktty pattern wholesale:
fuzz/ sidecar workspace with nightly pinned inside fuzz/ only, stable
fuzz/shared corpus replay as the fuzz gate, detached campaigns. Wave-1
targets: payload_codec, every_parse (three-way differential over the
per-engine parsers), name_validation; mem_opseq deferred post-release.
Named design points for decomposition: pub(crate) parser exposure
(lean: doc(hidden), the Job::from_row precedent), AGENTS.md gate
flip, workspace/publish exclusion.
docs/plans/implementation.md — wave 7 inserted (fuzzing; decided
2026-10-10, not yet decomposed), release readiness moved to wave 8,
dependency line + wave table + decided points + review-gate list
updated, forward 'wave 7' references re-pointed with a historical note
for pre-renumber records.
AGENTS.md — no-fuzzing posture flipped to adopted; corpus-replay gate
joins the verification list when wave 7 lands.
The born-pinned gate audited the mem engine against the contract and
ADR-024: the conformance read clean in mechanism substance (queue
state machine, scheduler collapse, outbox, streams, locks, clock,
validation, tx overlay, wake substrate — incl. a full guard-order and
panic-hygiene audit); the suite's third column read row-by-row and
25/25 green under the per-test current-thread flavor (24 engine-shared
rows + mem's payload_too_large non-occurrence arm + the factory-shape
test); three-way arithmetic equivalence green on all columns; the
wasm32 acceptance items verified (compile-clean, tokio sync+time,
no blocking, flavor enforced); the rider's two arms verified (Finding
1 discharged; Findings 2-3 stay parked for wave 7); workspace gates,
taskgraph validate green.
Three edge-domain fixes landed inline: the stream cursor read's
i64::MAX overflow (Bound::Excluded), trim_to's i64::MAX horizon
endpoint (Bound::Included), and the scheduler register path now
rejecting a parseable interval whose first boundary overflows with
InvalidSpec — the one engine-vs-engine divergence the read found,
aligned into the class-1 window — plus a pinning test and scaffold-
residue doc/comment cleanups (clock allows, tx per-stream wake
comment, wakes/stream module docs). Recorded findings with
dispositions in the task's Notes for the wave-7 pre-release pass:
the multi-thread publish-to-wake ordering tolerance, the heartbeat/
save_offset/EventReceiver-try_recv ADR-023 §2 classification gaps,
and the mem arithmetic being a suite-pinned transplant.
Verified: cargo build; cargo test --workspace green (mem 101 lib +
25 suite, sqlite 191+25, pg 124+25+9 server-less, core 25, harness 3);
clippy --all-targets -D warnings clean; fmt clean; taskgraph validate
(61 tasks). Gate record: tasks/review-wave-6.md (Notes + Summary),
implementation.md wave-6 row + review-rounds entry.
Row-first gate: consumer-inventory.md gains an engine-tier section — the mem-engine need recorded operator-authority, dated 2026-10-10 (wasm32 sandboxing across the alk protocol family + downstream ffi/napi/python-adapter economics; rusqlite/tokio-postgres structurally out on wasm, so mem is the only triad member the sandbox can carry).
ADR-024 (decisions/024-mem-engine.md) pins the decision set: (1) separate `alkstore-mem` crate — discharges and amends ADR-001 §4 (superseded in part: full contract-v1 engine, not an "implementation convenience"; annotation on ADR-001 §4 + Status, class-1 window still open); (2) honest-ephemeral posture — no durability, single-process, ephemeral by design, never fleet-valid (ADR-010 §3's shared-pool predicate fails structurally), riding ADR-016's carriers unchanged (identity + docs + matrix); (3) full contract v1 tier with the asymmetry classification — `PayloadTooLarge` never produced (SQLite arm), no reconnection concept (reconnect-wake/watcher rows absent from mem's per-engine column), receiver close at engine drop, wake coalescing N/A; (4) `MemStore::new()` engine-native constructor — the one documented exception to the open-prose, core-contract.md Store concept amended; shared-instance (two opens → one engine) rejected with the ADR-016 §4-style re-entry gate (consumer-inventory row), register stays closed; (5) wasm32 — compile-clean for wasm32-unknown-unknown plus the suite's mem column green on host under a current-thread runtime flavor are wave-6 acceptance items; on-target suite execution scoped out with a named collapse condition (wasm-bindgen-test adapter crate) — a scope decision, not a pending-client hedge; (6) mem is not a core dev-dependency — core's doc examples stay mock-based, ADR-001 §4's doctest posture declines.
engine-mem.md (draft): the in-process mapping — guarded per-mechanism state (no pool, no schema bootstrap, no forwarder, no spawn_blocking seam), the tx overlay (staged *_tx effects merged atomically at commit; read-your-own-writes easy, drop-=-rollback trivial; wake-at-commit structural — the seam pg needed pg-fix-tx-wake for, mem pins from birth via the existing tx-commit-atomicity rows), ADR-012 §2 third owner of the curve/opts/@every arithmetic (three-way equivalence, ADR-022's StoreFactory reused verbatim — born pinned).
deployment.md: host-semantics row (single-process, ephemeral, never fleet-valid, wasm32-clean), mem connection-budget subsection (none — nothing to budget), durability-knobs row (the honest row is the absence), toolchain row (wasm32 subset + current-thread-clean, acceptance-cited). README/overview: engine-mem.md row, ADR-024 row, family table entry (alkstore-mem, no driver deps), current-state updated to the implementation phase with engine specs' stable statuses reflected.
implementation.md: wave table gains wave 6 (mem engine, depends waves 1 + 5) and renumbers release readiness to wave 7 (fuzzing decision — the one remaining decided-at-implementation deferral — rides wave 7); wave-6 section records the born-pinned posture, acceptance items, the one suite-harness pre-task (past_stamp_sleep blocking sleep → async sleep, review 003's properties.rs:1683 note), and the window riders (review 003 Finding 1: the pg transient-fault seam, MEDIUM, rides wave 6; Findings 2–3 follow their park into wave 7's pre-release); wave-6 review gate defined; Decided points updated (mem discharged, fuzzing renumbered); stale wave-6 references swept across review docs and the landed tasks' notes (release-readiness items renumbered or annotated).
Docs-only change; verified by cross-reference audit (all ADR/OQ/anchor references resolve, residual wave-6 mentions are correct under the new numbering or carry dated annotations).
- forwarder.rs's ListenerConnection doc corrected: NoTls is hardwired on
every connection path (pooled, listener, reconnect) — the pooled path
never rode the consumer's Config sslmode (a sslmode=require DSN fails
at connect); grep-audited no other in-crate doc repeats the claim
- PgOpts doc carries the corrected one-line TLS pointer (engine-crate-
docs posture, ADR-016 §2)
- deployment.md: new 'TLS posture (v1)' subsection (NoTls everywhere,
sslmode=require DSN fails at connect, topology-level confidentiality
is the v1 substitute, TLS a post-v1 deployment concern) and a new
'Consumer-obligation notes on engine options' section carrying the
QueueOpts trusted-as-given note with code-verified per-field symptoms
(max_attempts <= 0: never claimed, dead-lettered at the next claim
call's pre-claim sweep; negative visibility: instantly-reclaimable
claims; negative retention: every dead row at the next sweep_expired)
plus the PgOpts::max_size 0-guard counter-case; frontmatter advanced
- alkstore/src/opts.rs: QueueOpts struct doc mirrors the
consumer-obligation note (ADR-023 §2 scoping: the domain table covers
trait-surface arguments, not consumer-constructed constants)
- cross-file doc sweep over the fix batch's touched files (forwarder,
tx, scheduler, store) found no further doc-behavior mismatch
- gates: cargo build / clippy --all-targets -D warnings / fmt --check
all green (doc-only, no test touched)
Operator review of ADR-012's fork design re-litigated §1's crate
identity. alkstore-substrate misdescribed what the code is (unpublished,
path-dep-only, one consumer, SQLite-only — not a family-wide substrate);
the mechanical-diff hope was gone at fork time regardless (port deltas,
renames, re-derived half); and the alksocks F-1 lesson applies — a
vendored region under a second, weaker instruction set is a defect seam.
The fork folds into alkstore-sqlite as a bounded module subtree
(src/substrate/); ADR-012 §3–§6 retained verbatim, §2 retained with its
enforcement re-sited from the crate graph to diff fence + review +
contract-suite equivalence pins. OQ-11 item (1) dissolved.
Follow-through on OQ-06/ADR-011: pin the fork's structural decisions
(alkstore-substrate as a vendored path-dep crate, contract-blind API
boundary with contract formulas computed engine-side and pinned
equivalent by the contract suite, keep-the-kept-half API fidelity for
cheap cherry-picks, the W-1/W-2/dead-man's-switch/W-4 port deltas
decided per item, bootstrap re-keying off error-string matching, no
rename migration, deliberate upstream tracking).
Consistency sweep across the doc set for the fork: annotate ADR-003/
005/009/010 and core-contract for superseded ownership facts, fix
schedule-storage table naming (ADR-009 §5, queues.md), re-key ADR-010
§6's notifications hygiene to the at-attach cap the fork scope
realizes, add OQ-11 (scaffold-time residue), and complete both ADR
indexes. Independent review: 0 critical, warnings addressed.
Quality read of honker-core's watcher/transactional core cross-checked
against the published crates.io artifact: the core itself is clean
(Writer/Readers, polling-watcher failure handling, WatcherDeathGuard
all verified), but published 0.5.0 predates upstream's unreleased fix
train carrying the issue-#133 savepoint hardening (silent job loss in
the dead-letter paths) and five .ok() error swallows — and ADR-010's
queue depth requires engine-owned queue SQL in any posture. Resolution:
fork honker-core at the reference revision, inherit the clean machinery
and test suites, re-derive queue ops on contract v1, rename tables to
__alkstore_*.
- docs/research/quality-read-honker-core.md — full evidence
- docs/architecture/decisions/011-sqlite-substrate-fork.md — decision
- OQ-06 resolved in open-questions.md; ADR-003/005/008, engine-sqlite,
queues, README annotated for consistency
- Convergence section added: the assembled recommendation (shape,
engines, contract starting shape, ownership, scope) in one place
- OQ register given consistent status lines (resolved / open —
<work-type> / open); OQ-ST-03 deduplicated (two duplicate
resolution paragraphs collapsed), OQ-ST-07's stale extraction
residue removed, OQ-ST-08 absorbs POC #2's pg multi-host input
- Front-matter changelog compressed; interface finding promoted to
a real heading (anchors were informal § prose references)
- Driver-conflict section updated to resolved state, corrections
folded; Phase 0 plan renumbered and marked final state
- Scope: no content decisions changed — restructure only
Review pass in this repo: contract suite re-verified (11/11 pass under
--test-threads=1 against the harness server; default parallel runs
interfere across tests via the shared db/channels engine_for_test
harness — each test spawns its own listener on poc:q/s/n and truncates
shared tables, so parallel tests receive each other's notifications and
race truncates). Recorded as a harness caveat in the findings with the
Phase 1 note (per-test namespaces), NOT as a contract failure — every
test passes in isolation. Findings invocation note + artifacts section
updated; phase-0 frontmatter carries the verification qualifier.
OQ-ST-03 closure text already folded by the POC session stands.
Findings: unified surface holds on tokio-postgres with the transactional
property intact (in-tx NOTIFY is commit-atomic; rollback drops all);
LISTEN wake beats poll 5-16x at p50 with 300/300 isolated delivery;
pooled-LISTEN discard (deadpool#360) verified and pinned as our own test;
postgres-notify 0.3.8 evaluated and passed over (lazy reconnect, no
initial-connect script, unquoted identifier LISTENs) in favor of the
~90-line hand-rolled forwarder with test-pinned pitfalls. sqlx PgListener
fallback retired unfired.
Two claims verified independently before folding: (1) deadpool-postgres
discards async notifications — upstream deadpool-rs/deadpool#360 (open,
Oct 2024) confirms the pool's connect task awaits the connection to
completion, dropping what only poll_message exposes; pooled LISTEN is
lost at recycle. The dedicated non-pooled LISTEN connection is now
upstream-verified required, not spec-preferred. (2) postgres-notify
0.3.8 exists as described (MIT, tokio-postgres, auto-reconnect with
backoff+jitter, multi-channel subscribe_notify, connect_script hook)
— admitted as sub-module L's second arm (hand-rolled forwarder vs
turnkey listener substrate), with in-probe verification required:
docs don't explicitly promise subscription restoration across
reconnect; connect_script is the mechanism; single-maintainer posture
recorded. New property test pinned: pooled-LISTEN-discard assertion
(our own evidence for the #360 behavior, flips if upstream fixes).
Probe 5 updated to budget accounting (listener conn outside the pool).
Completes OQ-ST-03: one driver posture (tokio-postgres + deadpool, the
POC #5/#7-validated stack) with three sub-modules — L (LISTEN plumbing:
dedicated connection, multi-channel, payload boundary), T (tx-seam over
the pool: caller-owned tx handle vs closure-scoped, both implemented
and compared — direct OQ-ST-04 input), W (wake-vs-poll parity, LISTEN
reconnect + the replay hole honesty). Property tests are the POC #1
suite's pg twin; seam probe mirrors the POC #1 workload for the
cross-engine relative claim. Gate: commit-atomicity via in-tx NOTIFY
(load-bearing), exactly-once claim, seam costs, LISTEN robustness -
failure names the sqlx PgListener fallback posture. Out of scope:
queue semantics depth (OQ-ST-05), pgboss-rs code adoption, multi-host
stress (OQ-ST-08). Register row added, plan updated (POC #2 running
closes OQ-ST-03).
Findings (poc-sqlite-posture-findings.md, run in a parallel session;
tests re-verified in this session — 4 passing): all three of Arm A's
gate conditions fired in its favor — bridged rusqlite ~2x sqlx
native-async at p50 (B's premise measured false), honker-core's
inherited watcher tighter than a re-derived one (p50 1.40 vs 2.15 ms,
max 29 vs 172 ms, battle-tested failure handling), and the .so runtime
dependency is packaging cost with no compensating advantage.
Transactional property holds identically on both (SQLite's property,
not the posture's). Constraints recorded: honker-core 0.5.0 pins
rusqlite ^0.40.1 (rustc >=1.99); mixed rusqlite+sqlx binaries need a
vendored libsqlite3-sys patch (OQ-ST-02's per-engine-crate split keeps
the engine binary single-driver). Fixed the findings' test-count
discrepancy (4 tests, verified running). Phase-0: OQ-ST-03 SQLite half
resolved (pg half remains), OQ-ST-04/05/06 carry POC input, register
row gains findings link + status, plan step 2 split into done/next,
frontmatter updated, POC crate added to references.
glm-5.3-flash