Rust Phase 2 Symbol-Library Reader/Writer Slice

Decision

A .kicad_sym byte buffer now has a source-backed Rust view that iterates ordered top-level symbol summaries and a focused writer for in_bom and on_board. The view retains selected spans and counts rather than a generic S-expression tree. The writer replaces an existing value or inserts an omitted default field while preserving every unrelated source byte.

Typed Surface

• Summaries expose name, inheritance, BOM/board flags, power state and kind, property count, subsymbol count, and direct pin count.
• Symbol and child spans are associated in one source-ordered pass. Individual strings and booleans are decoded only when iterated.
• One library root is mandatory. Symbol, metadata, subsymbol, pin, source-byte, depth, and output-byte bounds fail closed.
• Duplicate target names make edits ambiguous. Read ordering still reflects the source so callers can diagnose invalid libraries.

Contracts And Boundaries

TypeSpec owns read and edit requests/results plus the summary DTO. Generated JSON Schema, Rust, Python/msgspec, and TypeScript projections are committed. Browser operations accept source and request bytes as separate arrays. Reads return only DTO JSON; edits return metadata and the resulting KiCad bytes separately. Source/model failures use the structured diagnostic envelope and never return partial edited bytes.

Evidence And Retained Work

Rack L1_028 compares summaries with the Python object model and validates the generated strict contract. Native, host-adapter, and real wasm32 tests cover iteration, replacement, insertion, unknown-form retention, semantic reparse, stable second write, ambiguity, and resource limits.

This slice does not claim a complete owned symbol model. Properties, pins, graphical primitives, inheritance resolution, text shaping, and broad mutation will be promoted through consumer-driven vertical slices. Every promoted family must retain a corresponding semantic writer gate.