alkdev/alkstore
6
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fuzzing decision: adopted as wave 7, release readiness renumbered to wave 8

Browse Source 
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.
This commit is contained in:
glm-5.3-flash committed 2026-10-10 14:02:50 +00:00
1 parent 7e8bfde12d
commit 62cddade00
3 files changed
+467 -39
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/plans/implementation.md
+100 -36
View File
@@ -1,10 +1,10 @@
---
status: draft
last_updated: 2026-10-10 (wave 6 implemented and reviewed — the mem
engine landed, the suite's third column green under the current-thread
flavor, the wasm32 gate clean, the wave-6 gate passed with three
inline edge-domain fixes; Findings 2–3 and the flake watch carry to
wave 7.)
last_updated: 2026-10-10 (the fuzzing decision resolved: adopted and
inserted as wave 7 per docs/research/fuzzing.md; release readiness
renumbered to wave 8. Waves 1–6 implemented + reviewed; the wave-6
gate passed with three inline edge-domain fixes, and Findings 2–3 and
the flake watch carry to the wave-8 pre-release pass.)
---
# alkstore — Implementation plan
@@ -27,14 +27,19 @@ boundaries.
## The waves
Dependency logic in one line: core → (substrate fork ∥ postgres
engine) → sqlite engine → contract suite → mem engine → release
readiness. The substrate fork is contract-blind (ADR-012 §2), so it
needs only the workspace scaffold from wave 1; the Postgres engine
engine) → sqlite engine → contract suite → mem engine → fuzzing →
release readiness. The substrate fork is contract-blind (ADR-012 §2),
so it needs only the workspace scaffold from wave 1; the Postgres engine
needs only the core crate. Waves 2 and 4 are therefore independent of
each other and could run in either order (or in parallel, if agents
are ever available in parallel). The mem engine (wave 6) needs the
core crate plus the finished suite (wave 5) — born pinned, per
[ADR-024](../architecture/decisions/024-mem-engine.md).
[ADR-024](../architecture/decisions/024-mem-engine.md). The fuzzing
wave (wave 7) needs the mem engine finished (its campaigns precede the
release freeze; the targets ride in-process surfaces — core payloads,
the three per-engine parsers, name validation — see
[docs/research/fuzzing.md](../research/fuzzing.md)), and release
readiness is wave 8.
| Wave | Contents | Depends on | Status |
|---|---|---|---|
@@ -44,7 +49,8 @@ core crate plus the finished suite (wave 5) — born pinned, per
| 4 | [Postgres engine](#wave-4--postgres-engine): schema bootstrap, pool/open, listener/forwarder, all mechanisms, tx seam, pg backlog column | wave 1 | implemented + reviewed (2026-10-08) |
| 5 | [Contract suite](#wave-5--contract-suite): the cross-engine equivalence properties (core-contract.md §Verification backlog), version-stamped per ADR-017 | waves 3 + 4 | implemented + reviewed (2026-10-10) |
| 6 | [Mem engine](#wave-6--mem-engine): separate `alkstore-mem` crate, full contract v1 over in-memory mechanisms (tx overlay, queue/scheduler/streams/locks/wakes), the suite's third factory column (born pinned), wasm32 compile-clean acceptance | waves 1 + 5 | implemented + reviewed (2026-10-10) |
| 7 | [Release readiness](#wave-7--release-readiness): crate docs, deployment matrix final pass, README (written last, honestly), publish prep; fuzzing decision | wave 6 | not yet decomposed |
| [7](#wave-7--fuzzing) | [Fuzzing](#wave-7--fuzzing): the `fuzz/` sidecar workspace (cargo-fuzz targets over the payload codec, the three `@every` parsers, name validation), committed seed corpora + the corpus-replay gate, detached campaigns | wave 6 | decided (2026-10-10, `docs/research/fuzzing.md`), not yet decomposed |
| [8](#wave-8--release-readiness) | [Release readiness](#wave-8--release-readiness): crate docs, deployment matrix final pass, README (written last, honestly), publish prep | wave 7 | not yet decomposed |
## Wave 1 — Foundations
@@ -106,7 +112,7 @@ shaped this wave's task set:
wiring (the constructor task).
- **Staying put as ordered**: M-1's retention-failure test and N-5's
panic probe → wave 5's contract-suite rows; N-1's growth-posture
review → wave 7.
review → wave 8.
## Wave 4 — Postgres engine
@@ -260,7 +266,8 @@ tier (no durability, single-process, ephemeral by design, never
fleet-valid), adopted for the wasm/sandbox and downstream-adapter
economics the consumer inventory's engine-tier row records
(operator-authority, 2026-10-10 — the row-first gate satisfied before
this wave was assumed). Release readiness moved to wave 7.
this wave was assumed). Release readiness moved to wave 7, and again
to wave 8 when the fuzzing wave inserted at 7 (2026-10-10).
The wave's shape mirrors the engine waves' rhythm: constructor + tx
overlay → mechanisms in parallel → scheduler/outbox → suite
@@ -311,7 +318,7 @@ ADR-024), and the mem factory's suite wiring.
Riding the window: review 003's Finding 1 (the pg scheduler
transient-error retry loop, MEDIUM — engine-side, small,
mem-independent); Findings 2–3 follow their park recommendation into
wave 7's pre-release pass.
the pre-release pass (now wave 8).
**Wave 6's task set** (the decomposition, 2026-10-10 — the pg wave's
rhythm: foundations → seam → mechanisms in parallel → scheduler/outbox
@@ -356,21 +363,63 @@ the mechanisms; the mechanisms are mutually parallel. The suite pre-task
and the Findings-1 rider are independent of the mem chain entirely and
can run any time in the window (the rider must close before the gate).
## Wave 7 — Release readiness
## Wave 7 — Fuzzing
The original wave 6, renumbered when the mem engine inserted at wave
6 ([ADR-024](../architecture/decisions/024-mem-engine.md)): crate
**Decided 2026-10-10, before release readiness decomposed** — the
plan's one decided-at-implementation deferral is discharged here rather
than folded into the release pass: adoption (the family pattern per
alkcall/alktunnels/alksocks/alktty), inserted as this wave with release
readiness renumbered to wave 8, so campaigns run before the release
freeze. The rationale, target inventory, invariants, campaign posture,
and inherited tooling are written up in
[docs/research/fuzzing.md](../research/fuzzing.md) — this section
carries only the plan-level shape.
Scope (wave 1 of the doc's two-wave framing; `mem_opseq` is the
deferred wave 2, post-release): the `fuzz/` sidecar workspace laid out
per the upstream pattern — nightly pinned inside `fuzz/` only, the
stable-toolchain `fuzz/shared` crate whose corpus replay is the fuzz
gate (`cargo test --manifest-path fuzz/shared/Cargo.toml`), the
detached runner copied from alksocks — and three targets:
`payload_codec` (core payload encode/decode invariants),
`every_parse` (the three per-engine `@every` parsers, driven
differentially — the wave-6 overflow-finding class), and
`name_validation`. Campaigns run detached per target.
Named design points the decomposition resolves (each already sketched
in the doc): §3.2's parser-exposure decision — the three parsers are
`pub(crate)`, the family posture prefers already-`pub` surfaces, and
the doc leans (b) `#[doc(hidden)]`-style narrow exposure (the
`Job::from_row` precedent) with a public-`schedule()` companion;
the AGENTS.md posture flip (already done at adoption — the no-fuzzing
line now records the decision; the corpus-replay gate joins the
verification list only when the wave lands); and the
workspace/publish-exclusion verification. Committed crash-input seeds
promote into the corpus
(the alksocks seed-900/901 posture); grown corpora stay gitignored.
## Wave 8 — Release readiness
The original wave 6, renumbered twice: wave 7 when the mem engine
inserted at wave 6 ([ADR-024](../architecture/decisions/024-mem-engine.md)),
wave 8 when the fuzzing wave inserted at 7 (2026-10-10, the section
above): crate
docs, the deployment matrix final pass (across all three engines now),
the crate README (written last, honestly), publish prep, N-1's
growth-posture review — and the **fuzzing decision** (the
alksocks/alktty/alktunnels pattern), the one remaining
decided-at-implementation deferral. Decomposes after wave 6's review
growth-posture review. Decomposes after wave 7's review
gate, with review 003's Findings 2–3 riding the pre-release pass, and
the wave-5 gate's flake-watch flag carried
(`tasks/review-wave-5.md` §Notes 6 — the two unreproducible pg row
failures; if either reproduces, a dedicated investigative session
before any postulate-and-fix).
Historical note for records written before this second renumber
(review 001/002/003, the wave-3..6 task files): their "wave 7"
references to the release pass mean what is now wave 8; per the
family's renumber-annotation precedent (`tasks/review-wave-5.md`'s
ADR-024 annotations), affected records get swept (or annotated) when
wave 8 decomposes — history is not rewritten in place.
## Decided points
- **Contract-suite layout — option (a)**: a small internal
@@ -393,17 +442,21 @@ before any postulate-and-fix).
([ADR-024](../architecture/decisions/024-mem-engine.md))** — a
separate `alkstore-mem` crate, full contract v1, honest-ephemeral
posture, wasm32 compile-clean acceptance; wave 6, with release
readiness renumbered to wave 7. The deferral discharged: its
readiness renumbered to wave 7 (later 8 — see the fuzzing decision
below). The deferral discharged: its
collapse condition ("implementation time") was reached early via
the consumer pause + the wasm/sandbox motivation, with the row-first
gate satisfied by the consumer inventory's engine-tier row
(operator-authority, 2026-10-10).
- **Fuzzing adoption** (the alksocks/alktty/alktunnels pattern):
remains the one decided-at-implementation deferral, recorded here
so it surfaces as an explicit decision point in wave 7 (per
AGENTS.md's no-fuzzing posture, revisit only if a task or ADR
introduces it). Renumbered from wave 6 together with the mem
decision's move.
- **Fuzzing adoption** (the alkcall/alktunnels/alksocks/alktty
pattern): **decided 2026-10-10, before wave 8 decomposed — adopted,
inserted as wave 7** (release readiness renumbered to wave 8). The
deferral is discharged: the rationale, target inventory, invariants,
and campaign posture live in `docs/research/fuzzing.md`; the
decomposition resolves the named design points (parser exposure,
gate wiring, publish exclusion). AGENTS.md's no-fuzzing posture line
flipped at adoption; the corpus-replay gate joins the verification
list when the wave lands.
## Review gates
@@ -428,6 +481,13 @@ decomposes. Specific gates:
(harness pre-task disposed), the engine's own mechanism tests, and
the `engine-mem.md` spec read against the pinned ADR-024 text —
the gate that flips the mem spec toward `stable`.
- **Wave 7 review** — the fuzz wave's gate: the targets' campaigns run
clean via the detached runner (or their findings fixed and promoted
to seeds), the corpus-replay gate green on stable, the seeds
committed per the corpus policy, the harness-model findings
(if any) documented in the research doc's implementation log, and
the named design points (parser exposure, publish exclusion)
audited as resolved.
## Review rounds so far
@@ -439,7 +499,7 @@ decomposes. Specific gates:
`docs/reviews/001-waves-1-2-general-review.md`) — M-1 fixed
inline (sweep savepoint scope); M-2/N-2/N-4/N-6 resolved as ADR-023
pre-decomposition; lint removal + suite adds folded into waves 3/5;
N-1 recorded for release readiness (now wave 7).
N-1 recorded for release readiness (now wave 8).
- **Wave 3 review gate** (`review-wave-3`) — engine-vs-contract
conformance code-read clean; two findings fixed inline (the
`open_writer_connection` boundary move out of `substrate/mod.rs`;
@@ -507,15 +567,17 @@ decomposes. Specific gates:
three-way arithmetic equivalence green (backoff curve, opts
resolution on all three columns); the wasm32 acceptance items
verified (compile-clean, tokio sync+time subset, no blocking calls,
flavor enforced); the rider's arms verified (Finding 1 discharged;
Findings 2–3 confirmed still parked for wave 7). Three edge-domain
flavor enforced); the rider's arms verified (Finding 1 discharged;
Findings 2–3 confirmed still parked for the release pass — wave 8
since this renumber). Three edge-domain
fixes landed inline at the gate: the stream cursor read's `i64::MAX`
overflow (`Bound::Excluded`), `trim_to`'s `i64::MAX` horizon
endpoint (`Bound::Included`), and the scheduler register path
aligning with SQLite on rejecting a parseable interval whose first
boundary overflows (`InvalidSpec`). Unpinned contract-adjacent
observations recorded in the task's Notes for the wave-7 pre-release
pass: the multi-thread publish-to-wake ordering tolerance (same
observations recorded in the task's Notes for the pre-release pass
(wave 8 since this renumber): the multi-thread publish-to-wake
ordering tolerance (same
shape implied for the SQL engines; nothing pins wake-fire order vs
offset order), the `heartbeat(extend)`/`save_offset`/
`EventReceiver::try_recv`-closed classifications missing from the
@@ -531,11 +593,13 @@ decomposes. Specific gates:
- **Wave-5 residue decomposition** (2026-10-10) — the wave-5 review's
outstanding items audited post-gate: the one recorded "for a later
task" gap (scheduler fire-wake latency parity) decomposed as
`pg-fix-scheduler-fire-wake` (pre-wave-6, standalone); the flake-watch
flag carried into the wave-7 section above; review 003's Finding 1
already decomposed (`pg-fix-scheduler-tick-seam`, the wave-6 rider)
and Findings 2–3 already parked to wave 7. See the Wave 7 section for
the watch carriage.
`pg-fix-scheduler-fire-wake` (pre-wave-6, standalone); the flake-watch
flag carried into the release-readiness section above (now wave 8);
review 003's Finding 1
already decomposed (`pg-fix-scheduler-tick-seam`, the wave-6 rider)
and Findings 2–3 already parked to the release pass. See the
Wave 8 section for
the watch carriage.
- **Wave-5 residue closure** (2026-10-10) — the remaining
"recorded for a later task" item landed: `pg-fix-scheduler-fire-wake`
closed the scheduler fire-wake latency-parity gap (the tick's