diff --git a/docs/plans/implementation.md b/docs/plans/implementation.md index 1fd5edf..e480476 100644 --- a/docs/plans/implementation.md +++ b/docs/plans/implementation.md @@ -410,9 +410,16 @@ gate wiring → review gate): - `fuzz-parser-exposure` — §3.2's design point, resolved: **option (b)**, `#[doc(hidden)]` narrow re-exports of the three `parse_every_interval` implementations + the three `skip_forward` - boundary functions at each engine crate root (substrate untouched — - lineage fidelity), with (a) as the recorded in-suite companion and - (c) rejected per the family's no-`#[cfg(fuzzing)]` experience. + boundary functions at each engine crate root, with (a) as the + recorded in-suite companion and (c) rejected per the family's + no-`#[cfg(fuzzing)]` experience. Amended at implementation + (2026-10-10, user-confirmed): `pub use` requires item-level `pub` + (E0364 — the original "substrate untouched" criterion was + unsatisfiable), so the substrate delta is visibility-only — two + keywords in the *re-derived* `queue_ops.rs` (which + `substrate/mod.rs` itself classifies as owned contract-v1 code, not + lineage body), registered as a PROVENANCE.md delta entry; the + lineage body stays untouched. - `fuzz-target-payload-codec` — the §3.1 target (core payload encode/decode invariants: no-panic, the typed-failure partition, deep-input loudness, Value + typed round-trips) + its seeds. diff --git a/tasks/fuzz-parser-exposure.md b/tasks/fuzz-parser-exposure.md index ddc45fd..5954732 100644 --- a/tasks/fuzz-parser-exposure.md +++ b/tasks/fuzz-parser-exposure.md @@ -24,27 +24,46 @@ the parsers are engine-internal test surfaces, not contract surface the `#[doc(hidden)]` precedent already exists in-repo for exactly this shape of narrow, undocumented-but-public access. -What gets exposed, per engine — **at the engine crate root only; -substrate files untouched** (the SQLite parser and its `skip_forward` -live in the lineage-governed `substrate/queue_ops.rs`, ADR-012 §3 — the -exposure is a re-export in the engine's `lib.rs`, never a substrate -edit): +What gets exposed, per engine — `#[doc(hidden)] pub use` re-exports at +the engine crate root: -- **alkstore-sqlite**: `#[doc(hidden)] pub use` of - `parse_every_interval` (`Result`) and `skip_forward` - from `substrate::queue_ops`. +- **alkstore-sqlite**: `parse_every_interval` (`Result`) + and `skip_forward` from `substrate::queue_ops`, widened to `pub` in + place and re-exported from `lib.rs`. - **alkstore-postgres**: `parse_every_interval` (`Result` → - `InvalidSpec`, currently `pub(crate)`) and `skip_forward` (currently - private) widened to `pub(crate)` as needed and `#[doc(hidden)] pub - use`-re-exported from `lib.rs`. + `InvalidSpec`) and `skip_forward` from `scheduler.rs`, widened to + `pub` in place and re-exported from `lib.rs`. - **alkstore-mem**: same shape as pg (`scheduler.rs`'s parser + `skip_forward`). +**The mechanical constraint this task was decomposed against (resolved +2026-10-10 with the user — do not re-derive):** `pub use` re-exports +require the item itself to carry `pub` — `pub(crate)` and module-private +items fail with E0364/E0603 (compile-probed). The decomposition's +original "substrate files untouched" criterion was therefore +unsatisfiable for SQLite and was amended: the substrate delta is +**visibility-only** (`pub(crate)`→`pub` on the parser, private→`pub` on +`skip_forward` — two keywords in `queue_ops.rs`), which is legitimate +because `substrate/mod.rs` itself classifies `queue_ops.rs` as *the +re-derived half — owned contract-v1 code, not lineage body*; the +ADR-012 §3 lineage-fidelity discipline governs the ported honker body +(`watcher.rs`, `connection.rs`, …), untouched here. Containment holds: +`mod substrate` is private (`lib.rs`), so `pub` items inside leak +nothing until re-exported. The delta **must** be recorded as a +PROVENANCE.md register entry (the D-31 one-line-delta precedent — +category `re-derivation`-adjacent; a visibility-only delta on +re-derived code, registered so the story stays complete). pg/mem widen +to `pub` (not `pub(crate)`) for the same E0364 reason — their +`scheduler.rs` files are engine-owned, no provenance concern. + Doc posture: each re-export carries a one-line doc note marking it a fuzz/test-only surface (not contract surface, not consumer API, no stability guarantee) — the `Job::from_row` precedent's doc style. No engine behavior changes; no parser logic moves; the diff is visibility -plus re-exports. +keywords plus re-exports. The semver note is recorded, not hidden: +doc-hidden `pub` items are still public API (removal is technically +breaking) — the same commitment the four core `#[doc(hidden)]` +constructors already made, bounded here to a fuzz/test purpose. The **(a) companion** is recorded, not built: the public `schedule()` path against the mem and SQLite factories remains the suite's behavioral @@ -57,8 +76,13 @@ differential runs on the exposed functions. - [ ] All three engines re-export their `parse_every_interval` and `skip_forward` from the crate root, `#[doc(hidden)]`, with the fuzz/test-only doc note -- [ ] `alkstore-sqlite/src/substrate/**` diff is empty (lineage - fidelity preserved — the exposure is engine-side only) +- [ ] `alkstore-sqlite/src/substrate/**` diff is **visibility-only**: + exactly the two keywords in `queue_ops.rs` (`parse_every_interval` + → `pub`, `skip_forward` → `pub`); the lineage body + (`watcher.rs`, `connection.rs`, `ops.rs`, `schema.rs`, `mod.rs`) + untouched; a PROVENANCE.md delta entry records the change +- [ ] pg/mem `scheduler.rs` diffs are visibility-only (two keywords + each: parser → `pub`, `skip_forward` → `pub`) plus nothing else - [ ] The re-exports are reachable from an external crate (pinned by a compile-level test or the `fuzz-target-every-parse` build itself; record which) @@ -73,7 +97,13 @@ differential runs on the exposed functions. - docs/research/fuzzing.md §3.2 (the design point this resolves — options (a)/(b)/(c) and the lean) - docs/architecture/decisions/012-forked-substrate-design.md §2–§3 - (one-owner parsers; substrate lineage fidelity) + (one-owner parsers; substrate lineage fidelity — and its boundary: + the re-derived half is alkstore-owned) +- alkstore-sqlite/src/substrate/mod.rs (the module doc's own + classification: `queue_ops.rs` is "owned contract-v1 code, not + lineage body") +- alkstore-sqlite/src/substrate/PROVENANCE.md (the delta register the + visibility delta is recorded in; D-31 — the one-line-delta precedent) - docs/architecture/decisions/017-contract-versioning.md §3 (the `#[doc(hidden)]` precedent's policy boundary — engine-internal surfaces sit outside it) diff --git a/tasks/review-wave-7.md b/tasks/review-wave-7.md index 2718172..d9bd4c9 100644 --- a/tasks/review-wave-7.md +++ b/tasks/review-wave-7.md @@ -32,8 +32,11 @@ the fuzz wave as landed: diff); grown corpora + artifacts gitignored; nothing campaign-generated leaked into git. 4. **Named design points audited as resolved** (the plan's wave-7 - list): §3.2's parser exposure (option (b) landed, substrate diff - empty, the (a)-companion disposition recorded); the AGENTS.md + list): §3.2's parser exposure (option (b) landed; the substrate + delta visibility-only and confined to the re-derived `queue_ops.rs` + with its PROVENANCE.md entry — the amended criterion, per the + E0364 resolution recorded in `fuzz-parser-exposure.md`; the + (a)-companion disposition recorded); the AGENTS.md verification-list flip (gate line present, fuzzing paragraph truthful); the workspace/publish-exclusion mechanism (`exclude = ["fuzz"]` on the root workspace table — the *verification* that no