review-wave-8 — the pre-release gate passes: one contract-observable divergence found and fixed (pg's negative-seed GREATEST clamp + offsets CHECK contradicted ADR-023 §2's stored-checkpoint annotation; raw seed now, window open until first publish); the close-out's registered suite-duty follow-up discharged (negative heartbeat(extend) leg in job_handle_validity_predicate, negative save_offset seed leg in receiver_close_and_save_arms — stamped, uniform, green on all three columns vs the live harness server); the class-1 termination of record landed in ADR-017 §2 (no undisposed candidate remains; the window closes permanently at the first cargo publish); release-facing spec set flipped stable with dated gate annotations (core-contract, overview, queues, deployment current, the architecture README — Current State through wave 8, engine-mem's table row corrected); implementation.md records updated; N-1/Findings 2–3/flake/publish-prep audits recorded; all gates re-run green incl. fuzz replay, wasm32, doc gate

This commit is contained in:
glm-5.3-flash committed 2026-10-11 08:58:58 +00:00
1 parent 4a7520c817
commit 5385f6bee3
12 files changed
+479 -72

No files matched your search

+84 -2
View File
@@ -1324,7 +1324,10 @@ pub async fn backoff_curve_equivalence(factory: &dyn StoreFactory) {
/// Contract stamp: ADR-021 §5 (receiver error/close arms — /// Contract stamp: ADR-021 §5 (receiver error/close arms —
/// `Database`-only `Err`, terminal `None` close, SQLite closes on /// `Database`-only `Err`, terminal `None` close, SQLite closes on
/// watcher death); ADR-019 §6 (save composition — monotone, forms /// watcher death); ADR-019 §6 (save composition — monotone, forms
/// interleave); ADR-008 §8 (explicit saves only). /// interleave); ADR-008 §8 (explicit saves only); ADR-023 §2
/// (annotated 2026-10-11 — the boundary/offset row's totality covers
/// `save_offset`: a negative seed is stored as the checkpoint, this
/// row's negative-leg pins).
pub async fn receiver_close_and_save_arms(factory: &dyn StoreFactory) { pub async fn receiver_close_and_save_arms(factory: &dyn StoreFactory) {
let store = factory.open().await.expect("factory opens a store"); let store = factory.open().await.expect("factory opens a store");
@@ -1416,6 +1419,38 @@ pub async fn receiver_close_and_save_arms(factory: &dyn StoreFactory) {
"the receiver form never regresses the direct form's save" "the receiver form never regresses the direct form's save"
); );
// Boundary-total save (ADR-023 §2, annotated 2026-10-11): a
// negative offset is stored as the checkpoint — the argument is
// total, no clamping, no rejection — and reads anchored there
// resume forward identically (every event offset lies above the
// negative anchor, so the anchored read yields the log from the
// start). Fresh consumer, so this leg also pins the *seed* case —
// the only arm where a clamping realization would diverge.
stream.save_offset("c2", -5).await.unwrap();
assert_eq!(
store
.stream("events")
.await
.unwrap()
.get_offset("c2")
.await
.unwrap(),
-5,
"a negative seed is stored as the checkpoint (totality, no clamp)"
);
let resumed = store
.stream("events")
.await
.unwrap()
.read_from_consumer("c2", 10)
.await
.unwrap();
assert_eq!(
resumed.iter().map(|e| e.offset).collect::<Vec<_>>(),
vec![o1, o2],
"reads anchored at the negative checkpoint resume forward: the log from the start"
);
// Terminal close on disposal (this engine's documented close // Terminal close on disposal (this engine's documented close
// cause: the watcher's death guard clears the feed — ADR-021 §5's // cause: the watcher's death guard clears the feed — ADR-021 §5's
// SQLite arm; the store handle dropping is the disposal). // SQLite arm; the store handle dropping is the disposal).
@@ -1770,7 +1805,10 @@ async fn past_stamp_sleep(millis: u64) {
/// (delete-on-ack; `ack_batch`'s per-id predicate, partial success /// (delete-on-ack; `ack_batch`'s per-id predicate, partial success
/// ordinary); ADR-010 §4 (the engine-default strings); ADR-019 §3 /// ordinary); ADR-010 §4 (the engine-default strings); ADR-019 §3
/// (the claim handle's op surface — one-shot consumables, repeatable /// (the claim handle's op surface — one-shot consumables, repeatable
/// heartbeat); ADR-008 §5 (refusals are `false`, never errors). /// heartbeat); ADR-008 §5 (refusals are `false`, never errors);
/// ADR-023 §2 (annotated 2026-10-11 — the boundary/offset row's
/// totality covers `heartbeat(extend)`: a negative extension is the
/// relative-instant void this row's negative-extend leg pins).
pub async fn job_handle_validity_predicate(factory: &dyn StoreFactory) { pub async fn job_handle_validity_predicate(factory: &dyn StoreFactory) {
let store = factory.open().await.expect("factory opens a store"); let store = factory.open().await.expect("factory opens a store");
@@ -1818,6 +1856,50 @@ pub async fn job_handle_validity_predicate(factory: &dyn StoreFactory) {
"delete-on-ack completed work leaves no row" "delete-on-ack completed work leaves no row"
); );
// Boundary-total heartbeat (ADR-023 §2, annotated 2026-10-11): a
// negative extension is a relative instant — the renewed deadline
// `now + extend` sits in the past, voiding the claim through the
// validity predicate on the *next* op, never an error. The
// heartbeat itself reports the successful renewal (`true`) while
// the row was processing and unexpired at call time; the voided
// claim then refuses all handle ops (ack here) and the row
// survives as processing. Six-hundred-second margin: fully past,
// deterministic without a sleep. Own queue: the voided row is
// expired-processing (re-claimable), and this row's later legs
// assert claim FIFO on their queues.
let voidq = store
.queue("voided", alkstore::QueueOpts::default())
.await
.unwrap();
let voided_id = voidq
.enqueue(json!({"leg": "negative-extend"}), EnqueueOpts::default())
.await
.unwrap();
let voided = voidq
.claim_one("w1")
.await
.unwrap()
.expect("the ready row claims");
assert_eq!(voided.job().id, voided_id);
assert!(
voided.heartbeat(-600).await.unwrap(),
"a negative extension lands while the claim is unexpired (totality)"
);
assert!(
!voided.ack().await.unwrap(),
"the negative extension voided the claim: ack refuses through the validity predicate"
);
assert_eq!(
voidq
.get_job(voided_id)
.await
.unwrap()
.expect("the voided row was not deleted or dead-lettered")
.state,
JobState::Processing,
"the voided claim's row survives as processing (re-claimable by the queue)"
);
// Lapse legs: one claim per refusal op, all stamped with the 1 s // Lapse legs: one claim per refusal op, all stamped with the 1 s
// visibility, one tolerance sleep past every deadline at once. // visibility, one tolerance sleep past every deadline at once.
let ack_refused = fast let ack_refused = fast
+4 -3
View File
@@ -298,12 +298,13 @@ CREATE INDEX IF NOT EXISTS {events_read_idx} ON {events} (stream, id);
-- Offsets table: (stream, consumer) → offset, the monotone -- Offsets table: (stream, consumer) → offset, the monotone
-- checkpoint upsert target (the streams task's SQL owns the -- checkpoint upsert target (the streams task's SQL owns the
-- monotonicity rule, GREATEST-guarded upsert, one owner). The -- monotonicity rule, WHERE-guarded upsert, one owner). The boundary
-- non-negative CHECK bounds the domain (cursors start at 0). -- argument is total (ADR-023 §2): no domain CHECK — a negative seed
-- is stored raw, reads anchor at it and resume forward identically.
CREATE TABLE IF NOT EXISTS {offsets} ( CREATE TABLE IF NOT EXISTS {offsets} (
stream TEXT NOT NULL, stream TEXT NOT NULL,
consumer TEXT NOT NULL, consumer TEXT NOT NULL,
\"offset\" BIGINT NOT NULL DEFAULT 0 CHECK (\"offset\" >= 0), \"offset\" BIGINT NOT NULL DEFAULT 0,
PRIMARY KEY (stream, consumer) PRIMARY KEY (stream, consumer)
); );
+16 -11
View File
@@ -28,9 +28,13 @@
//! stored checkpoint (absent consumer = 0, ADR-019 §1). //! stored checkpoint (absent consumer = 0, ADR-019 §1).
//! - `save_offset` / `get_offset` — the monotone upsert (a save below //! - `save_offset` / `get_offset` — the monotone upsert (a save below
//! the stored checkpoint is a silent no-op — one owner of the //! the stored checkpoint is a silent no-op — one owner of the
//! monotonicity rule, the `GREATEST`-clamped + `WHERE`-guarded //! monotonicity rule, the `WHERE`-guarded upsert `save_offset_tx`
//! upsert `save_offset_tx` also rides) and the checkpoint read. //! also rides) and the checkpoint read. The boundary argument is
//! Both save forms' `Err` arm carries `Database` only (ADR-021 §5). //! total per ADR-023 §2's 2026-10-11 annotation: any `i64` is
//! well-defined, a negative seed is stored raw as the checkpoint
//! (no clamping — the offsets column's `DEFAULT 0` is not a domain
//! bound; reads anchored there resume forward identically), and
//! both save forms' `Err` arm carries `Database` only (ADR-021 §5).
//! - `trim_to(horizon)` — `DELETE … WHERE id <= horizon` on a pool //! - `trim_to(horizon)` — `DELETE … WHERE id <= horizon` on a pool
//! connection (wakes nothing — ADR-015 §5's posture; the boundary //! connection (wakes nothing — ADR-015 §5's posture; the boundary
//! argument is total per ADR-023 §2: a negative horizon deletes //! argument is total per ADR-023 §2: a negative horizon deletes
@@ -371,13 +375,14 @@ async fn stream_get_offset(pool: &Pool, schema: &str, stream: &str, consumer: &s
} }
/// The monotone checkpoint save (one owner of the monotonicity rule — /// The monotone checkpoint save (one owner of the monotonicity rule —
/// the same GREATEST-clamped, WHERE-guarded upsert `save_offset_tx` /// the same `WHERE`-guarded upsert `save_offset_tx` rides; a save
/// rides; a save at-or-below the stored checkpoint updates nothing, /// at-or-below the stored checkpoint updates nothing, ADR-019 §6).
/// ADR-019 §6). First save seeds the checkpoint, clamped at 0 (the /// The boundary argument is total per ADR-023 §2's 2026-10-11
/// offsets table's non-negative domain CHECK would abort a negative /// annotation: any `i64` is well-defined — a negative first save
/// seed; the clamp preserves both the domain and the monotone rule — /// seeds the checkpoint raw (the monotone guard `EXCLUDED > o`
/// a negative save at-or-below the stored checkpoint is the same /// treats every pre-existing row as the below-checkpoint no-op arm;
/// silent no-op a 0-save is). /// reads anchored at a negative checkpoint resume forward
/// identically).
async fn stream_save_offset( async fn stream_save_offset(
pool: &Pool, pool: &Pool,
schema: &str, schema: &str,
@@ -390,7 +395,7 @@ async fn stream_save_offset(
conn.execute( conn.execute(
&format!( &format!(
"INSERT INTO {offsets} AS o (stream, consumer, \"offset\") "INSERT INTO {offsets} AS o (stream, consumer, \"offset\")
VALUES ($1, $2, GREATEST($3::bigint, 0)) VALUES ($1, $2, $3::bigint)
ON CONFLICT (stream, consumer) DO UPDATE ON CONFLICT (stream, consumer) DO UPDATE
SET \"offset\" = EXCLUDED.\"offset\" SET \"offset\" = EXCLUDED.\"offset\"
WHERE EXCLUDED.\"offset\" > o.\"offset\"" WHERE EXCLUDED.\"offset\" > o.\"offset\""
+26 -16
View File
@@ -1,8 +1,9 @@
--- ---
status: draft status: stable
last_updated: "2026-10-10 (ADR-024: the mem engine adopted as a third last_updated: "2026-10-11 (the wave-8 review gate passed — pre-release
engine — engine-mem.md added, ADR table row, index updated for the freeze: the release-facing spec set flipped stable, Current State
implementation phase)" refreshed through wave 8; the class-1 window's dispositions complete,
the window terminates at first publish)"
--- ---
# alkstore — Architecture # alkstore — Architecture
@@ -14,29 +15,38 @@ engine native underneath (see [overview.md](overview.md)).
## Current State ## Current State
**Phase 1 (Implementation) — waves 1–5 implemented and reviewed.** **Phase 1 (Implementation) — waves 1–8 implemented and reviewed; the
pre-release gate passed (2026-10-11).**
Phase 0 is complete (`docs/research/phase-0.md`): both POCs ran and Phase 0 is complete (`docs/research/phase-0.md`): both POCs ran and
passed, the scope inventory is confirmed, and the crate split, passed, the scope inventory is confirmed, and the crate split,
drivers, and ownership postures are decided. All open questions are drivers, and ownership postures are decided. All open questions are
resolved (through ADR-023), and the engine specs flipped `stable` at resolved (through ADR-023), and the engine specs flipped `stable` at
the wave-5 review gate. Waves 1–5 (core, substrate fork, SQLite the wave-5 review gate, the mem spec at wave 6. Waves 1–7 (core,
engine, Postgres engine, contract suite) are implemented and reviewed substrate fork, SQLite engine, Postgres engine, contract suite, mem
per `docs/plans/implementation.md`. The mem engine was adopted as a engine, fuzzing) are implemented and reviewed; wave 8 (release
third engine by [ADR-024](decisions/024-mem-engine.md) (2026-10-10, readiness: crate docs, the deployment matrix's final pass, the
wave 6 — release readiness renumbered to wave 7). README, publish prep — with N-1's growth-posture acceptance, review
003 Findings 2–3, the flake investigation, and the class-1 window's
last dispositions riding it) passed its review gate on 2026-10-11.
ADR-024 adopted the mem engine as a third engine (2026-10-10,
[ADR-024](decisions/024-mem-engine.md)). The class-1 amend-in-place
window ([ADR-017](decisions/017-contract-versioning.md) §2)
dispositions are complete; the window terminates permanently at the
first `cargo publish` of `alkstore` — the gate's blessing covers
publishing.
## Architecture Documents ## Architecture Documents
| Doc | Status | Purpose | Key OQs | | Doc | Status | Purpose | Key OQs |
|---|---|---|---| |---|---|---|---|
| [overview.md](overview.md) | draft | Crate family, feature surface, non-goals, evidence base | — | | [overview.md](overview.md) | stable | Crate family, feature surface, non-goals, evidence base | — |
| [core-contract.md](core-contract.md) | draft | The unified trait surface, delivery guarantees, tx seam | OQ-10 (resolved) | | [core-contract.md](core-contract.md) | stable | The unified trait surface, delivery guarantees, tx seam | OQ-10 (resolved) |
| [engine-sqlite.md](engine-sqlite.md) | stable | SQLite engine: forked-substrate/rusqlite mapping | OQ-06 (resolved), OQ-12 (resolved), OQ-13 (resolved) | | [engine-sqlite.md](engine-sqlite.md) | stable | SQLite engine: forked-substrate/rusqlite mapping | OQ-06 (resolved), OQ-12 (resolved), OQ-13 (resolved) |
| [engine-postgres.md](engine-postgres.md) | stable | Postgres engine: tokio-postgres/LISTEN mapping | OQ-08 (resolved), OQ-12 (resolved), OQ-13 (resolved) | | [engine-postgres.md](engine-postgres.md) | stable | Postgres engine: tokio-postgres/LISTEN mapping | OQ-08 (resolved), OQ-12 (resolved), OQ-13 (resolved) |
| [engine-mem.md](engine-mem.md) | draft | Mem engine: in-process ephemeral mapping of the contract ([ADR-024](decisions/024-mem-engine.md)) | — | | [engine-mem.md](engine-mem.md) | stable | Mem engine: in-process ephemeral mapping of the contract ([ADR-024](decisions/024-mem-engine.md)) | — |
| [queues.md](queues.md) | draft | Queue/scheduler/outbox semantics depth (resolved: ADR-009/ADR-010) | OQ-05 (resolved), OQ-09 (resolved), OQ-06 (resolved) | | [queues.md](queues.md) | stable | Queue/scheduler/outbox semantics depth (resolved: ADR-009/ADR-010) | OQ-05 (resolved), OQ-09 (resolved), OQ-06 (resolved) |
| [deployment.md](deployment.md) | draft | Host semantics, connection budgets, knobs, matrix | OQ-08 (resolved) | | [deployment.md](deployment.md) | stable | Host semantics, connection budgets, knobs, matrix | OQ-08 (resolved) |
| [open-questions.md](open-questions.md) | draft | OQ tracker (promoted from OQ-ST register) | — | | [open-questions.md](open-questions.md) | draft | OQ tracker (promoted from OQ-ST register) — the register's own lifecycle; the question set is closed | — |
## Architecture Decision Records ## Architecture Decision Records
+11 -4
View File
@@ -1,6 +1,11 @@
--- ---
status: draft status: stable
last_updated: "2026-10-11 (the pre-release class-1 close-out pass — the publish→wake ordering tolerance recorded; ADR-023 §2's `heartbeat(extend)`/`save_offset` classifications; `EventReceiver::try_recv`'s closed shape; `get_job`'s id-global prose)" last_updated: "2026-10-11 (the pre-release class-1 close-out pass — the
publish→wake ordering tolerance recorded; ADR-023 §2's
`heartbeat(extend)`/`save_offset` classifications;
`EventReceiver::try_recv`'s closed shape; `get_job`'s id-global prose —
then wave-8 gate: flipped stable with the close-out pass's suite legs
landed; the contract text freezes at the gate, ADR-017 §2)"
--- ---
# Core contract # Core contract
@@ -792,8 +797,10 @@ before the engine specs are called `stable`:
totality over non-positive values covers `heartbeat(extend)`'s totality over non-positive values covers `heartbeat(extend)`'s
relative-deadline argument and `save_offset`'s offset — both relative-deadline argument and `save_offset`'s offset — both
classified 2026-10-11 by the close-out pass, the ADR-023 §2 classified 2026-10-11 by the close-out pass, the ADR-023 §2
annotation; their suite rows are the follow-up that annotation; their suite legs landed at the wave-8 gate in
classification implies). `job_handle_validity_predicate` and
`receiver_close_and_save_arms`, uniformly green on all three
engines).
- **`encode_payload` typed failure** - **`encode_payload` typed failure**
([ADR-023](decisions/023-fourth-review-round.md) §1) — the helper ([ADR-023](decisions/023-fourth-review-round.md) §1) — the helper
returns `Result<Vec<u8>, Error::Codec>`; enqueue/publish store and returns `Result<Vec<u8>, Error::Codec>`; enqueue/publish store and
@@ -128,7 +128,16 @@ duty — that is what makes them non-events).
extensions*, fall in this class in fact — nothing was released extensions*, fall in this class in fact — nothing was released
when they were made, so their additions ship inside the initial when they were made, so their additions ship inside the initial
contract v1 text (the initial release carries ADR-008 through contract v1 text (the initial release carries ADR-008 through
ADR-017 whole). ADR-017 whole). *(Termination of record, 2026-10-11 — the wave-8
review gate: the pre-release class-1 close-out pass landed every
recorded disposition (the publish→wake ordering tolerance; the
ADR-023 §2 `heartbeat(extend)`/`save_offset` classifications; the
`EventReceiver::try_recv` closed shape; the `get_job` prose; the
mem-arithmetic no-action) and the gate audited that **no
undisposed class-1 candidate remains**. The class terminates
permanently at the core crate's first `cargo publish` — the 0.1.0
release this gate blesses, per §1's amendment; from that publish
on, contract changes are classes 2–4 only.)*
2. **Additive extension** (the ADR-009/010 *shape*, applied 2. **Additive extension** (the ADR-009/010 *shape*, applied
post-release) — a new trait method, a new type, a new error post-release) — a new trait method, a new type, a new error
variant, a new field on a consumer-read value type (§3's variant, a new field on a consumer-read value type (§3's
+4 -3
View File
@@ -1,7 +1,8 @@
--- ---
status: draft status: stable
last_updated: "2026-10-10 (ADR-024 — the mem engine joins the crate last_updated: "2026-10-11 (wave-8 gate: flipped stable — the family
family as `alkstore-mem`; family/ADR tables updated)" picture frozen with the shipped thing; no further surface under
development)"
--- ---
# alkstore — Overview # alkstore — Overview
+5 -2
View File
@@ -1,6 +1,9 @@
--- ---
status: draft status: stable
last_updated: "2026-10-11 (close-out pass: the reads sentence now says the uniform shapes — get_job id-global on the handle, get_job_tx queue-filtered)" last_updated: "2026-10-11 (the reads sentence now says the uniform
shapes — get_job id-global on the handle, get_job_tx queue-filtered;
wave-8 gate: flipped stable, the release-facing semantic depth frozen
with the contract)"
--- ---
# Queues, scheduler, outbox — semantics depth # Queues, scheduler, outbox — semantics depth
+36 -7
View File
@@ -1,10 +1,9 @@
--- ---
status: draft status: draft
last_updated: "2026-10-10 (wave 8 decomposed — the release-readiness last_updated: "2026-10-11 (wave 8 implemented + reviewed — the release
task set: seven independent entry tasks incl. the frontmatter cleanup gate passed: the class-1 window's dispositions complete, the suite's
and the renumber sweep, then matrix → README → publish prep → gate. registered boundary-legs follow-up landed, all gates re-run green;
Waves 1–7 implemented + reviewed; Findings 2–3, the fired flake-watch implementation complete pending the user's manual `cargo publish`.)"
trigger, and the class-1 window's last dispositions ride wave 8.)"
--- ---
# alkstore — Implementation plan # alkstore — Implementation plan
@@ -50,7 +49,7 @@ readiness is wave 8.
| 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) | | 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) | | 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](#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 | implemented + reviewed (2026-10-10) | | [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 | implemented + reviewed (2026-10-10) |
| [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 | decomposed (2026-10-10) | | [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 | implemented + reviewed (2026-10-11) |
## Wave 1 — Foundations ## Wave 1 — Foundations
@@ -757,4 +756,34 @@ decomposes. Specific gates:
recommendation: **wave 5 decomposes after the two HIGH fixes land** recommendation: **wave 5 decomposes after the two HIGH fixes land**
(the suite's wake-driven rows would otherwise inherit a hang-shaped (the suite's wake-driven rows would otherwise inherit a hang-shaped
false failure); 3–7 may trail into wave 5's window if the false failure); 3–7 may trail into wave 5's window if the
fix-batch gate judges them wake-independent. fix-batch gate judges them wake-independent.- **Wave-8 review gate** (`review-wave-8`, 2026-10-11) — the
pre-release gate passed: the docs honesty audit clean (README trace
list spot-read true, the deployment matrix's rows read true as
implemented, crate-doc posture claims consistent with the matrix,
the env-boundary grep re-run current); the contract-window closure
audited — all five wave-6 dispositions verified landed with dated
citations, **the class-1 termination of record landed in ADR-017
§2** (the window closes permanently at the first `cargo publish` of
`alkstore`; no undisposed class-1 candidate remains); the
close-out's registered suite-duty follow-up audited and **landed at
the gate** — one divergence found: pg's negative-seed clamp
(`GREATEST(offset, 0)` + the offsets-table `CHECK`) contradicted
ADR-023 §2's "a negative is stored as the checkpoint" annotation on
`get_offset`, fixed engine-side (raw seed, no CHECK), with the
negative-`heartbeat(extend)` and negative-`save_offset` suite legs
landed in `job_handle_validity_predicate` /
`receiver_close_and_save_arms` (stamped, uniform, green on all
three columns); N-1's conscious acceptance and Findings 2–3's
landed/parked dispositions audited as decisions of record; the
flake outcome audited (lock row root-caused harness-model,
test-side fixed, watch retired; the trim row and the new
stream-ordering observation stay watch-flagged — no live engine
bug, not blocking); publish-prep evidence re-verified this gate
session (fresh package listing + exclusion re-run, no leakage); the
frontmatter sweep + renumber spot-checks re-run green; all gates
re-run green including the fuzz replay, wasm32, and the doc gate;
the release-facing spec set (core-contract.md, overview.md,
queues.md, deployment.md, the architecture README) flipped
`stable`. Implementation complete pending the user's manual
`cargo publish` (the checklist of record is in
`tasks/release-publish-prep.md`).
+6 -6
View File
@@ -62,16 +62,16 @@ accumulation.
## Acceptance Criteria ## Acceptance Criteria
- [ ] Item 1 decided with the user (documented-tolerance vs ADR - [x] Item 1 decided with the user (documented-tolerance vs ADR
amendment), landed in the chosen home, decision recorded amendment), landed in the chosen home, decision recorded
- [ ] ADR-023 §2 table carries the `heartbeat(extend)` and - [x] ADR-023 §2 table carries the `heartbeat(extend)` and
`save_offset` classifications (or the task records why a `save_offset` classifications (or the task records why a
different home was chosen) different home was chosen)
- [ ] `EventReceiver::try_recv`'s closed shape pinned in contract text - [x] `EventReceiver::try_recv`'s closed shape pinned in contract text
- [ ] core-contract.md's `get_job` prose matches the uniform - [x] core-contract.md's `get_job` prose matches the uniform
id-global/`get_job_tx`-filtered behavior id-global/`get_job_tx`-filtered behavior
- [ ] The mem-arithmetic observation's disposition recorded - [x] The mem-arithmetic observation's disposition recorded
- [ ] Every landed amendment dated + cited; affected suite stamps - [x] Every landed amendment dated + cited; affected suite stamps
checked for accumulation; `taskgraph validate` + workspace gates checked for accumulation; `taskgraph validate` + workspace gates
green (docs-only changes expected — code changes only if the green (docs-only changes expected — code changes only if the
user opts to amend wake-ordering into an enforced guarantee, user opts to amend wake-ordering into an enforced guarantee,
+6 -6
View File
@@ -49,15 +49,15 @@ are the wave's other doc-shaped tasks for exactly that reason.
## Acceptance Criteria ## Acceptance Criteria
- [ ] Root `README.md` exists: family table, per-engine honest - [x] Root `README.md` exists: family table, per-engine honest
postures, compile-checked usage sketch, suite pointer, license postures, compile-checked usage sketch, suite pointer, license
note; no aspirational/unshipped claims note; no aspirational/unshipped claims
- [ ] `LICENSE-MIT` + `LICENSE-APACHE` at the root (MIT + Apache-2.0 - [x] `LICENSE-MIT` + `LICENSE-APACHE` at the root (MIT + Apache-2.0
canonical texts); ADR-018's in-tree substrate notice untouched canonical texts); ADR-018's in-tree substrate notice untouched
- [ ] `CHANGELOG.md` seeded with the 0.1.0 entry - [x] `CHANGELOG.md` seeded with the 0.1.0 entry
- [ ] The per-crate readme wiring decided + landed - [x] The per-crate readme wiring decided + landed
- [ ] Every README claim traceable to a spec (the trace list in Notes) - [x] Every README claim traceable to a spec (the trace list in Notes)
- [ ] Workspace gates green (docs-only expected) - [x] Workspace gates green (docs-only expected)
## References ## References
+271 -11
View File
@@ -1,7 +1,7 @@
--- ---
id: review-wave-8 id: review-wave-8
name: Review gate — wave 8 (release readiness) name: Review gate — wave 8 (release readiness)
status: pending status: completed
depends_on: [docs-frontmatter-cleanup, release-renumber-sweep, release-crate-docs, release-contract-window-close, release-n1-growth-posture, release-findings-2-3-disposition, release-flake-investigation, release-deployment-matrix, release-readme, release-publish-prep] depends_on: [docs-frontmatter-cleanup, release-renumber-sweep, release-crate-docs, release-contract-window-close, release-n1-growth-posture, release-findings-2-3-disposition, release-flake-investigation, release-deployment-matrix, release-readme, release-publish-prep]
scope: broad scope: broad
risk: low risk: low
@@ -59,19 +59,19 @@ pre-release gate). Audit the release-readiness pass as landed:
## Acceptance Criteria ## Acceptance Criteria
- [ ] Docs honesty audit recorded (README traces, matrix rows, crate - [x] Docs honesty audit recorded (README traces, matrix rows, crate
docs, env boundary) docs, env boundary)
- [ ] Contract-window closure audited; the class-1 termination record - [x] Contract-window closure audited; the class-1 termination record
landed; no undisposed class-1 candidate remains landed; no undisposed class-1 candidate remains
- [ ] N-1 + Findings 2–3 dispositions audited as decisions of record - [x] N-1 + Findings 2–3 dispositions audited as decisions of record
- [ ] Flake-watch outcome audited; any follow-up task's blocking - [x] Flake-watch outcome audited; any follow-up task's blocking
status stated explicitly status stated explicitly
- [ ] Publish-prep audit recorded (package evidence + exclusion - [x] Publish-prep audit recorded (package evidence + exclusion
re-run + checklist complete) re-run + checklist complete)
- [ ] Frontmatter parse sweep + renumber-sweep spot-check green - [x] Frontmatter parse sweep + renumber-sweep spot-check green
- [ ] All gates re-run green this session (incl. fuzz replay + wasm + - [x] All gates re-run green this session (incl. fuzz replay + wasm +
doc gates) doc gates)
- [ ] Spec flips + records landed; `implementation.md` updated; task - [x] Spec flips + records landed; `implementation.md` updated; task
files audited files audited
## References ## References
@@ -87,8 +87,268 @@ pre-release gate). Audit the release-readiness pass as landed:
## Notes ## Notes
> To be filled by implementation agent Gate verdict: **passed**. One finding found and fixed at the gate (a
pg engine divergence from the close-out pass's ADR-023 §2
annotation); no blocker, no major live defect. Every audit item was
re-verified by this session's own runs/reads, not by trusting the
implementing tasks' self-reports.
### 1. Docs honesty audit — recorded
- **README**: the trace list (`release-readme` §Notes) spot-read —
the seven-mechanism list against core-contract.md §Mechanism
contracts, the engine posture lines against deployment.md §Host
semantics + §TLS posture, mem's wasm/ephemeral lines against
ADR-024 §2/§5, the license note against the workspace `license`
field + ADR-018. Every claim has a spec source; the usage sketch
was compile-checked and executed from a scratch crate with path
deps (the mem round-trip mirrors the lib-doc doctest `cargo test`
re-verifies — green in this session's run). No aspirational or
unshipped claims found.
- **Deployment matrix**: rows read true as implemented across the
three engines (the full text of
`release-deployment-matrix`'s five corrections — the consumer-side
FULL claim false-as-implemented, the three-guard list, the NFS
re-citation, the unsourced mem latency number replaced — present
in the final text; the env-boundary §Configuration boundary
sentence present; no internal task/wave pointers remain in the
release-facing text — re-read this session). Spot-checks against
code: `synchronous = NORMAL` at bootstrap, `poll_interval` 1 ms
default, `NoTls` on every pg path, `max_size` 0 rejected — all
match the text.
- **Crate docs**: the four published crates' lib-doc posture claims
read against deployment.md/the engine specs — the sqlite
single-host/one-host-cross-process, pg's `max_size + 1` budget +
NoTls v1, mem's honest-ephemeral/wasm identity all consistent with
the matrix. Doc gate green (`RUSTDOCFLAGS="-D warnings" cargo doc
--no-deps`, zero warnings this session).
- **Env boundary**: the grep re-run this session — 40 `env::var`
reads, all inside the pg test modules' DSN plumbing; production
paths env-free. The matrix's "grep re-verified across the
workspace at release" sentence is current.
### 2. Contract-window closure audit — recorded
- All five wave-6 recorded observations verified disposed with dated
in-place citations: the publish→wake ordering tolerance
(core-contract.md streams tolerance paragraph + the
delivery-guarantee obligations bullet + ADR-015 §4's companion
annotation; the user declined the enforced-guarantee amendment —
the documented-tolerance posture was the user's call, recorded in
the task's Notes); the ADR-023 §2 `heartbeat(extend)`/`save_offset`
classifications (boundary/offset row annotated, core-contract
numeric-domain paragraph mirrored); the `EventReceiver::try_recv`
closed shape (ADR-021 §5 dated annotation); the `get_job` prose
(core-contract + queues.md now say the uniform id-global /
tx-filtered split); the mem-arithmetic no-action disposition (task
Notes, explicit).
- **The registered suite-duty follow-up — audited, and landed at the
gate** (the close-out pass deferred it to "the review-wave-8 gate
owns the audit"): no suite leg pinned the two new classifications.
In the audit read of pg's implementation, a real divergence
surfaced: **pg's negative-seed clamp contradicted the ADR-023 §2
annotation** — pg's offsets-table `CHECK ("offset" >= 0)` + the
`GREATEST($3, 0)` upsert clamped a fresh consumer's negative
`save_offset` to 0, where SQLite and mem store the raw negative
and the annotation pins "a negative is stored as the checkpoint"
(`get_offset` observable: −5 vs 0, the only read that
distinguishes; below-checkpoint saves, monotone no-ops, and
reads-resume-forward were uniform). Per AGENTS.md's ADR-wins
discipline, **the pg code was fixed**: raw seed, CHECK dropped,
doc comments updated (the window is open until first publish —
legal; no published consumer exists). Suite legs then landed:
the negative-`heartbeat(extend)` leg in
`job_handle_validity_predicate` (heartbeat lands `true` while
unexpired; the voided claim refuses ack through the validity
predicate; the row survives as processing) and the
negative-`save_offset` seed leg in `receiver_close_and_save_arms`
(fresh-consumer seed stored raw; `read_from_consumer` resumes
forward from the anchor) — both stamped with the ADR-023 §2
(annotated 2026-10-11) accumulation per `version_stamp.rs`
convention; green on all three columns against the live pg server
(and core-contract.md's numeric-domain backlog row updated to
name the landed legs). The close-out task's "code read verified
the uniform shapes" claim was right on acceptance/monotonicity
and wrong on the stored seed value through pg's clamp — corrected
here.
- **The class-1 termination record landed**: ADR-017 §2's class-1
bullet now carries the dated termination-of-record annotation
(2026-10-11, the wave-8 gate): the close-out pass landed every
recorded disposition, the gate audited no undisposed class-1
candidate remains (grep across docs/tasks for parked window
candidates — none; the surviving "class-1 window open/open at
time of writing" phrases are historical ADR texts), and the
class terminates permanently at the core crate's first
`cargo publish` — the 0.1.0 release this gate blesses (§1's
2026-10-11 amendment; contract changes thereafter are classes
2–4 only).
### 3. N-1 + Findings 2–3 dispositions — audited as decisions of record
- **N-1**: the conscious acceptance is a decision of record with a
per-engine, per-path rationale table (`deployment.md` §Growth
postures), made against the implemented engines' code (the task's
re-read verified each path: sweep-on-call-only retention, the
at-attach-only prune, consumer-invoked `trim_to`; mem's
process-lifetime-bounded postures recorded structurally). The
notify prune-cadence note landed in engine-sqlite.md
§Notifications-table hygiene, anchored and linked from the
matrix. Not a shrug; recorded and folded.
- **Findings 2–3**: 2(a) and 3 landed as seam tests (the pg
generation-top LISTEN-pause arm with the exactly-one-wake
differentiator, replay-proofed both ways; the SQLite
rollback-fault two-drop-arm test via the `rollback_fault` seam),
and 2(b) + the defensive arms' parked dispositions are recorded
with current line refs, reach reasons, and the tested-elsewhere
coverage each overlaps — the inventory reads closed, not
re-derivable. Gates green per the task's record; both engines'
suites green this session.
### 4. Flake-watch outcome — audited
- The fired lock-row trigger was investigated per the ledger's
prescription (instrumentation first — the tee-before-filter
capture procedure demonstrated on a deliberately-failing probe;
the conditions matrix run, 48+ rounds; the second-precision
arithmetic read against `lock.rs`/`resolution.rs` with the
delay-only argument confirmed for the lapse legs and corrected
for the contention leg; mechanism probes + natural repro captured,
2/30 loaded solo runs, exact message at the exact site).
Disposition: **reproduced; root cause harness-model** — the row's
contention leg wrote `ttl = 1` into a live-TTL assertion
second-precision stamps collapse below a second; the engine acted
per ADR-008 §7 at every step. Fixed test-side in-session (the
two-leg row: long-TTL exclusion leg, short-TTL lapse leg);
30/30 loaded verification green; the three columns green.
**No live engine bug — nothing blocks the release blessing.**
- Post-investigation watch posture: the lock row's flag **retires**;
the trim row stays watch-flagged (no repro in this session's
rounds) and one new single-occurrence observation
(`row_stream_ordering_equivalence` under 8-CPU-burner synthetic
load — a drain-window scheduling lottery, message captured,
no ordering violation) is recorded in the ledger dated
2026-10-11. Their stated status: watch continues, no ride-along
fix, instrumentation first; neither reproduces under dev/gate
conditions. Recorded; not blocking.
### 5. Publish-prep audit — recorded
- **Package evidence, fresh this session**: `cargo package -p
alkstore` — packaged 30 files + verification build green; the
`.crate` inspection shows LICENSE-MIT/LICENSE-APACHE at the
tarball root, README, normalized manifest, no stray paths. The
engines' registry-side verification remains correctly blocked
pre-core-publish (re-captured this session with `--allow-dirty`:
`no matching package named 'alkstore' found … searched: crates.io
index`); their evidence stands on the reconstructed exact-list
trees of record (all green, the publish-shaped manifests).
- **Exclusion verification re-run this session**: fresh
`cargo package --list` for all four crates — alkstore 30 files,
sqlite 36, postgres 31, mem 23; zero `fuzz/`/sidecar/corpora paths
or `alkstore-fuzz-shared` references in any list; the engine
packages' `src/fuzz_surface_tests.rs` + `tests/contract_suite.rs`
riders are the documented crate-internal probe tests and dev-dep
suite target, not sidecar leakage; the suite appears in no
`[dependencies]`; the workspace `exclude = ["fuzz"]` holds.
- **Substrate packaging**: `src/substrate/PROVENANCE.md` +
`src/substrate/LICENSE` confirmed in the alkstore-sqlite list;
the crate README documents the carriers.
- **Path-dep bounds + metadata**: `alkstore = { version = "0.1",
path = … }` verified on all three engines + the suite dep;
descriptions/readmes wired per crate; keywords/categories landed;
homepage/documentation omitted per family precedent; ADR-017 §1's
0.1.0 amendment dated + cited. **The manual publish checklist of
record is complete** (`release-publish-prep` §Notes — core first,
then engines, gates → package → eyeball → publish, tag v0.1.0);
publishing is the user's post-gate action. The one mechanical
note: run the checklist from the committed, clean tree (cargo
package refuses dirty trees).
### 6. Frontmatter + records hygiene — re-run green
- The PyYAML parse sweep re-run exactly as recorded
(`docs-frontmatter-cleanup`'s command, both globs): **0 failures**
across `docs/**/*.md` + `tasks/*.md`.
- The renumber sweep spot-check: re-grepped `wave 7|wave-7` across
`docs/reviews/` + `tasks/` — every non-fuzz hit carries its
wave-8 annotation (001 header, 002 security bullet, 003 echo +
trail, review-wave-5's three sites, review-wave-6's three,
review-wave-4's gate record, pg-fix-scheduler-fire-wake's ledger
note); genuine fuzz-wave/review-7 references intact;
`taskgraph validate` green (79 tasks).
### 7. All gates re-run green this session
- `cargo build` — clean.
- `cargo test --workspace` — all green server-less (core 25 + 1
lib-test target, suite harness 3, mem 102 lib + 25 suite + 1
doctest, sqlite 193 + 25, pg 127 lib (SKIP posture) + 25 + 9).
- Live pg column against the harness server (`pglo-poc`): **127 +
25 + 9, all green** (this session, post-fix — the run that verified
the pg seed-divergence fix and the new suite legs).
- `cargo clippy --all-targets -- -D warnings` — clean.
- `cargo fmt --check` — clean.
- Fuzz corpus replay (`cargo test --manifest-path
fuzz/shared/Cargo.toml`) — 6/6 green.
- `cargo check --target wasm32-unknown-unknown -p alkstore-mem` —
clean.
- Doc gate (`RUSTDOCFLAGS="-D warnings" cargo doc --no-deps`) — zero
warnings.
### 8. Spec flips + records — landed this gate
- Flipped `stable` with dated gate annotations: **core-contract.md,
overview.md, queues.md, deployment.md** (already `stable` from the
matrix pass — annotation current), **the architecture README**.
The engine specs' engine-mem.md row in the README's doc table
corrected (it still read `draft`; the wave-6 gate flipped the
spec). `open-questions.md` stays `draft` deliberately — it is the
OQ *tracker*, whose lifecycle is separate from the spec set
(noted in the README table's row); the doc set this gate freezes
is the release-facing spec set.
- `docs/architecture/README.md`: Current State refreshed (waves 1–8,
the pre-release gate passed, the window's termination stated).
- `implementation.md`: wave-8 row → implemented + reviewed
(2026-10-11); frontmatter annotation updated; the review-rounds
entry appended.
- Task files audited: all ten wave-8 dependencies `completed` with
Notes/Summary filled; two of their AC checklists
(`release-contract-window-close`, `release-readme`) were left
unticked despite the work + records being complete — ticked at
this gate; no placeholder residue remains in the wave-8 task set.
### Findings summary
| # | Severity | Finding | Disposition |
|---|---|---|---|
| 1 | LOW (contract-observable) | pg's negative-seed clamp (`GREATEST(offset, 0)` + the offsets CHECK) diverged from ADR-023 §2's 2026-10-11 "a negative is stored as the checkpoint" annotation on `get_offset` | Fixed engine-side at the gate (raw seed, CHECK dropped; window open until first publish); suite legs landed uniformly (three columns green); backlog row updated |
| 2 | INFO | The close-out pass's "uniform shapes" verification missed the clamp (acceptance was verified; the stored seed value was not) | Corrected by the fix above; recorded here for the record's honesty |
| 3 | INFO | The 2026-10-11 `row_stream_ordering_equivalence` load observation (from `release-flake-investigation` §F6) | Watch-flagged in the ledger, carries post-release; no ride-along fix, instrumentation first; single occurrence under synthetic load beyond dev/gate conditions — not blocking |
## Summary ## Summary
> To be filled on completion Gate passed 2026-10-11. The pre-release pass audited clean on every
axis and one contract-observable divergence surfaced and was fixed:
pg's negative-seed clamp contradicted the ADR-023 §2 close-out
annotation, resolved engine-side (raw seed, no CHECK), with the
registered suite-duty follow-up discharged — the
negative-`heartbeat(extend)` and negative-`save_offset` legs landed,
stamped, and green on all three columns (pg verified against the
live harness server). The class-1 termination of record landed in
ADR-017 §2: every recorded disposition is dated + cited, no
undisposed candidate remains, and the window terminates permanently
at the core crate's first `cargo publish` — the 0.1.0 this gate
blesses. N-1's acceptance and Findings 2–3's dispositions are
decisions of record; the flake investigation's outcome is a
harness-model root cause, test-side fixed, watch retired, with the
remaining watch items recorded and non-blocking. Publish prep
verified fresh (package evidence, exclusion re-run clean, the
manual checklist of record standing); the frontmatter and renumber
hygiene sweeps re-ran green; all gates re-run green this session
(build, workspace tests, live-pg suite, clippy, fmt, fuzz replay,
wasm32, doc gate). The release-facing spec set — core-contract.md,
overview.md, queues.md, deployment.md, the architecture README — is
flipped `stable`; `engine-mem.md`'s README-table row corrected to
match its wave-6 flip; `implementation.md`'s records updated;
`open-questions.md` stays the draft tracker by intent. Implementation
is complete; the release itself is the user's manual publish session.