---
id: fuzz-parser-exposure
name: Parser exposure — `#[doc(hidden)]` narrow surface for the three `@every` parsers + boundary arithmetic
status: pending
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 — **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):

- **alkstore-sqlite**: `#[doc(hidden)] pub use` of
  `parse_every_interval` (`Result<i64, String>`) and `skip_forward`
  from `substrate::queue_ops`.
- **alkstore-postgres**: `parse_every_interval` (`Result<i64>` →
  `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`.
- **alkstore-mem**: same shape as pg (`scheduler.rs`'s parser +
  `skip_forward`).

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.

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 empty (lineage
      fidelity preserved — the exposure is engine-side only)
- [ ] 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)
- 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