alkstore/tasks/fuzz-parser-exposure.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
fuzz-parser-exposure	Parser exposure — `#[doc(hidden)]` narrow surface for the three `@every` parsers + boundary arithmetic	pending		narrow	low	component	implementation	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<i64, String>) and skip_forward from substrate::queue_ops, widened to pub in place and re-exported from lib.rs.
• alkstore-postgres: parse_every_interval (Result<i64> → 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

• 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 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)
• No behavior change: workspace gates green (cargo build, cargo test, clippy -D warnings, fmt); the engines' own scheduler/parser test suites untouched and green
• 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

To be filled by implementation agent

Summary

To be filled on completion