Rust S-Expression L0 Architecture Review

Decision

The Rust L0 S-expression foundation is approved for the next parser-only corpus phase. Typed KiCad source-model expansion remains gated on the L1 semantic pass-through evidence and the remaining Phase 1 promotion items below.

Reviewed Boundary

• Borrowed byte-offset lexer and bounded generic tree parsing.
• Deterministic build and generic token-preserving formatting.
• Structural spans, path/head/depth selectors, pruning, and reusable indexes.
• Chunk-safe native stream scans and seeked partial form reads.
• Generic mutation and source-preserving patch primitives.
• TypeSpec-governed scan/build envelopes and generated strict Rust DTOs.
• Native and executable browser-WASM byte operation paths.

Review Corrections

The review found and closed these implementation issues before approval:

• Reusable indexed selection changed from quadratic ancestor searches to bounded path checks.
• Inline quote atoms now retain Python/KiCad builder behavior and have a shared parity vector.
• Streaming scans now match Unicode-whitespace and whole-line-comment behavior across chunk boundaries.
• Public partial reads reject inverted ranges instead of converting them to empty reads.
• Decoded-string limits are enforced while decoding without first allocating the complete decoded payload.

Evidence

• Rack L0_foundation: 47 of 47 subtests and 1,445 tests pass.
• Rust property evidence: 2,000 generated semantic round trips and 1,000 malformed variants.
• Streaming equivalence: every chunk size from 1 through 17 over CRLF, Unicode, comments, escapes, and quoted delimiters.
• WASM: a real Node-hosted wasm-bindgen-test executes bytes in to canonical bytes out.
• The unoptimized-by-wasm-opt release WASM artifact is approximately 258 KiB.
• On the frozen 2,108,903-byte synthetic PCB workload, repeated observed Rust speedups were approximately 22x scan, 32-35x parse, and 9-11x build versus Python.

Promotion Gates Retained

1. Ratify performance floors only after package-corpus small/medium/large cases add peak-memory, streaming-select, source-patch, and WASM transfer measurements. The current synthetic benchmark is evidence, not a release threshold.
2. Add the handwritten semantic validator for the TypeSpec Node union before exposing the build-operation envelope. The generated shape intentionally cannot express all kind/payload exclusivity rules.
3. Generate Python and TypeScript projections from the same TypeSpec authority before those language adapters become public. No handwritten competing DTO is permitted in the interim.

Phase 1 Performance Watchlist

• Both structural scanners preserve source ordering with a final selected span sort. Selection is therefore O(n + k log k), where k is the selected-form count. Corpus measurements must report this cost separately for select-everything workloads before the sort is removed or replaced.
• Frames clone complete paths and stored spans own their paths, so memory follows the sum of selected path depths rather than only form count. Deep corpus files must be included in peak-memory evidence.
• Path-restricted scans compare eligible forms against every requested path. Workloads with many paths belong in the corpus gate. If profiling shows material cost, parent-indexed spans plus interned head IDs or a selector trie are the preferred investigation directions.

These observations do not block the L1 parser-only corpus phase. The configured depth and resource bounds remain required while the costs are measured.

Next Authorized Slice

Run the parser-only L1 corpus gate across promoted KiCad suffixes. Require parse, deterministic build, reparse, semantic equality, and byte-stable second output. This review does not authorize typed PCB, schematic, rendering, or downstream pcb_a0 expansion yet.