--- id: fuzz-parser-exposure name: Parser exposure — `#[doc(hidden)]` narrow surface for the three `@every` parsers + boundary arithmetic status: completed depends_on: [] scope: narrow risk: low impact: component level: implementation tags: [wave-7, fuzzing] --- ## Description The §3.2 exposure design point, resolved by this decomposition: **option (b)** — a `#[doc(hidden)]` narrow exposure mirroring the existing `Job::from_row` / `Schedule::new` constructor precedent — with **(a)** (the public-`schedule()` path) as the in-suite companion, no new suite rows. Option (c) (a `fuzzing` feature flag) is rejected per the family's no-`#[cfg(fuzzing)]` experience. Rationale: the fast byte-level differential target the upstream docs favor needs direct parser access; the parsers are engine-internal test surfaces, not contract surface (ADR-017 §3's consumer-read policy governs core types, not these); and the `#[doc(hidden)]` precedent already exists in-repo for exactly this shape of narrow, undocumented-but-public access. What gets exposed, per engine — `#[doc(hidden)] pub use` re-exports at the engine crate root: - **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`) 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 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 pin (already green, three-way); the `every_parse` target may optionally drive `schedule()` for register-path posture seeds, but the byte-level differential runs on the exposed functions. ## Acceptance Criteria - [x] 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 - [x] `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`) untouched; a PROVENANCE.md delta entry records the change *(amended at implementation, 2026-10-10 — `mod.rs` was in this list, but a second mechanical constraint forced one facade line there: see Notes. No lineage-body file was touched.)* - [x] pg/mem `scheduler.rs` diffs are visibility-only (two keywords each: parser → `pub`, `skip_forward` → `pub`) plus nothing else - [x] 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) - [x] No behavior change: workspace gates green (`cargo build`, `cargo test`, clippy `-D warnings`, fmt); the engines' own scheduler/parser test suites untouched and green - [x] `cargo check --target wasm32-unknown-unknown -p alkstore-mem` still clean (visibility widening is wasm-neutral, pinned anyway) ## References - 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 — 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) - alkstore/src/job.rs (`Job::from_row` — the in-repo doc-hidden precedent) ## Notes Decisions of record the implementation made that the description didn't pin: - **Second mechanical amendment — `mod.rs` could not stay untouched.** Widening `queue_ops.rs`'s two functions to `pub` is necessary but not sufficient: `lib.rs` cannot name the path `substrate::queue_ops::…` at all — `mod substrate` is private *to `substrate`'s subtree* for `queue_ops` purposes, so a through-the-path re-export fails E0603, and `skip_forward` had **no `mod.rs` export** whatsoever (it was not in the `pub(crate) use` list). The only route is the facade: `mod.rs` gained `pub use queue_ops::{parse_every_interval, skip_forward};` (one line; `parse_every_interval` moved out of the `pub(crate)` list into it — a duplicate binding would be E0252), compile-probed clean. This remains visibility-only — zero logic, zero signatures, zero names; lineage body (`watcher.rs`/`connection.rs`/`ops.rs`/ `schema.rs`) untouched; containment holds (`mod substrate` private). - **`mod.rs`'s boundary-doc sentence amended.** "Nothing here is re-exported through the engine crate's public API" would have become stale the moment the facade landed; the sentence now names this sole exception inline, and the full story is registered as **PROVENANCE.md D-37** (category `re-derivation`, per this task's amendment). - **Reachability pin (criterion 4): compile-level test.** Each engine gained `src/fuzz_surface_tests.rs` (`#[cfg(test)]`, declared in `lib.rs`) — `doc_hidden_reexports_reach_the_crate_root` drives both re-exports through the crate-root path (one accept case + one `skip_forward` assertion each). Compile of the `pub use` itself is the E0364-class pin; the true external-crate consumption arrives with `fuzz-target-every-parse`'s build (its `shared` crate path-depends on all three engines). Neither engine's existing suite files were touched — the pin is a separate module. - **Semver note (recorded per the description):** doc-hidden `pub` items are still public API — removal is technically breaking; the same commitment core's four `#[doc(hidden)]` constructors made, bounded to a fuzz/test purpose. ## Summary Landed (2026-10-10): the `#[doc(hidden)]` narrow fuzz/test surface for the three engines — `parse_every_interval` + `skip_forward` re-exported from each crate root with the one-line fuzz/test-only doc note (`Job::from_row` doc-posture style). - **alkstore-sqlite**: `substrate/queue_ops.rs` two keywords widened to `pub`; `substrate/mod.rs` gained the facade `pub use` line + the boundary-doc exception sentence; `substrate/PROVENANCE.md` D-37 registered; `lib.rs` `#[doc(hidden)] pub use substrate::…` ×2. - **alkstore-postgres / alkstore-mem**: `scheduler.rs` two keywords each widened to `pub`; `lib.rs` `#[doc(hidden)] pub use scheduler::…` ×2. No provenance concern (engine-owned files). - **Reachability pins**: `src/fuzz_surface_tests.rs` ×3 — one test per engine driving both crate-root re-exports. Verified: `cargo build` clean; `cargo test` green (all suites; the three new pins pass; no engine suite touched); `cargo clippy --all-targets -- -D warnings` clean; `cargo fmt --check` clean; `cargo check --target wasm32-unknown-unknown -p alkstore-mem` clean. Diff audited against the (twice-amended) criteria: engine `scheduler.rs`/`queue_ops.rs` diffs are visibility keywords only.