KiCad Monkey Rust Workspace Standard

This proposal records the provisional Rust hygiene boundary for the parser-first port tracked by GitHub issue 59. It is reviewed again at the parser, first typed boundary, and downstream cutover gates.

Workspace And Toolchain

Rust source lives under src/rs/ in the polyglot repository.
The root Cargo workspace uses edition 2024 and resolver 3.
Workspace metadata, lint policy, and release profiles are centralized.
Package-owned kicad-monkey-* crates use the same YYYY.M.D calendar-version format as the Python distribution. Downstream applications pin an exact Git commit until a Cargo publication and tagging policy is separately accepted.
Cargo.lock is committed and signoff commands use --locked.
rust-toolchain.toml pins the reviewed Rust 1.98.0 toolchain with rustfmt and Clippy; CI uses the same version.

Cargo manifests retain Rust 1.95 as the declared MSRV. Repository formatting and lint evidence uses the separately pinned Rust 1.98.0 toolchain so local and CI diagnostics are deterministic.

L0 Crate Boundaries

kicad-monkey-core owns dependency-free KiCad syntax, structural indexing, selection, mutation, and write-back.
kicad-monkey-contracts contains committed Rust types generated from TypeSpec JSON Schema through Typify.
kicad-monkey-wasm is a thin browser adapter over the core and generated contracts.
kicad-monkey-codegen is build tooling only and never enters parser or browser runtime dependency graphs.

Whole-buffer scans borrow UTF-8 source. Native stream scans retain only their structural stack and selected metadata, then use exact byte ranges to seek and read requested forms. A reusable structural index owns form metadata but never owns or duplicates the source file.

Safety Boundary

Package-owned crates set unsafe_code = "forbid". The current parser has no unsafe exception. A future exception is allowed only when profiling or a required external ABI proves that a safe design cannot meet the contract. It requires an ADR, a minimal isolated crate or module, documented invariants, focused tests, and architecture-review approval.

Untrusted KiCad input must return structured errors rather than panic. Parsers enforce explicit source, depth, node, decoded-string, and output limits. The core does not depend on ambient filesystem or process state.

Dependency Policy

Prefer package-owned implementations for small, format-specific behavior when the code is easier to audit, test, and maintain than another public dependency. Do not recreate mature general-purpose standards or infrastructure merely to avoid dependencies.

The first S-expression core remains dependency-free.
Serde is the expected default for generated contract serialization.
RustCrypto sha2 and unicode-casefold provide the mature SHA-256 and Unicode full-case-fold primitives behind the package-owned compiled-graph identity allocator; canonicalization, selector policy, UUID formatting, and failure semantics remain in-house.
HarfRust plus the reviewed ttf-parser/Skrifa outline stack implement complex font behavior behind package-owned APIs.
Geometer remains the external process/WASM boundary for promoted generic planar kernels.
Third-party APIs stay behind package-owned types and operation contracts.

Each dependency is reviewed for behavior parity, maintenance, license, supply-chain posture, native/WASM support, compile cost, binary size, and performance. Crate selection remains reversible until its parity slice is promoted.

Contract Authority

Authored contracts live under src/tsp/kicad_monkey/. TypeSpec emits closed JSON Schemas under contracts/generated/schema/; the package code generator then produces strict Serde Rust types. Generated files are committed for consumers and are checked for drift through Rack.

Large KiCad inputs and outputs are separate byte buffers, not base64 or JSON arrays. Operation envelopes contain selectors, limits, spans, and diagnostics. This is the required shape for native, Python, and browser adapters as those boundaries are promoted.

Required Validation

The 2026.8.12 standard adds syntax-aware structural limits: at most seven parameters, 100 production-function lines, 150 test-function lines, 1,000 file lines, cyclomatic complexity 10, and nesting depth four. Existing parser and plotter debt is captured in the checked-in rust-hygiene-baseline.json; the ratchet rejects new entries or increases. Clippy uses the same reviewed thresholds, and every local allowance requires a written reason.

cargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --locked
cargo test --doc --workspace --locked
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --locked
npm run check:typespec
cargo run --package kicad-monkey-codegen --locked -- --check
cargo test --package kicad-monkey-wasm --target wasm32-unknown-unknown --locked

Bootstrap the browser test host with npm ci, rustup target add wasm32-unknown-unknown, and the lock-compatible cargo install wasm-bindgen-cli --version 0.2.127 --locked. CI must install these tools explicitly; a missing runner is a failed promoted gate, not a skipped browser test.

Package tests remain orchestrated by Rack. L0_044 owns the locked native Rust suite, L0_045 owns shared Python/Rust vectors, L0_046 owns parity-registry, generation, quality, and executable WASM checks, and L0_047 records comparative release-mode measurements. Performance thresholds are ratified by the L0 parser architecture review rather than inferred from one workstation.