1---2name: rust-development3description: Implement or refactor Rust in this repository. Use when writing new modules, modifying existing source files, or adding features to the chaotic_semantic_memory crate.4---56# Rust Development78## Workflow91. Read @AGENTS.md constraints.102. Read the target file and its neighbors before editing.113. Follow the patterns in `reference/codebase-patterns.md`.124. Run `scripts/validate.sh` after changes.135. Verify LOC: every `.rs` file in `src/` AND `crates/` must be ≤ 500 lines.146. Run `cargo deny check` if Cargo.lock was modified (supply chain audit).1516## Module Map1718| File | Purpose | LOC |19|---|---|---|20| `src/lib.rs` | Crate root + prelude | ~63 |21| `src/error.rs` | `MemoryError` enum, `Result` alias | ~32 |22| `src/hyperdim.rs` | `HVec10240` (10240-bit vectors), bundle, bind, similarity | ~404 |23| `src/reservoir.rs` | Sparse ESN, `ChaoticReservoir`, spectral radius | ~469 |24| `src/singularity.rs` | `Concept`, `Singularity` store, similarity search | ~484 |25| `src/persistence.rs` | libSQL persistence, batch ops, per-op connections | ~500 |26| `src/framework.rs` | `ChaoticSemanticFramework`, builder, lifecycle | ~496 |27| `src/encoder.rs` | `TextEncoder`, deterministic text-to-hypervector | ~500 |28| `src/semantic_bridge.rs` | `CanonicalConcept`, `ConceptGraph`, `ScoreBreakdown` | ~400 |29| `src/bridge_retrieval.rs` | Bridge retrieval pipeline with expansion | ~387 |30| `src/bridge_persistence.rs` | Bridge persistence layer | ~300 |31| `src/retrieval/bm25.rs` | BM25 keyword search index | ~300 |32| `src/retrieval/hybrid.rs` | Hybrid BM25/HDC score fusion | ~200 |33| `src/wasm.rs` | WASM bindings (cfg-gated) | ~435 |34| `src/cli/` | CLI commands (inject, probe, query, index-*) | various |3536## Key Conventions37- All public APIs return `Result<T, MemoryError>`.38- Tokio async for I/O (`persistence.rs`, `framework.rs`).39- Rayon for CPU parallelism, always behind `#[cfg(not(target_arch = "wasm32"))]`.40- libsql only (never `turso-client`).41- Reservoir spectral radius must stay in `[0.9, 1.1]`.42- `rand::rngs::StdRng` with `SeedableRng` for reproducibility in reservoir/tests.43- No magic numbers in production logic: use named constants and configurable env/config parameters for tunables.44- **LOC gate applies to `crates/` too** — workspace crate source files at `crates/*/src/*.rs` have the same ≤ 500 LOC limit.45- **When adding a new workspace crate scope**, also add it to `commitlint.config.cjs` scope-enum.4647## When Adding a New Module48- Add `pub mod name;` to `lib.rs`.49- Re-export key types in the `prelude` module if they're part of the public API.50- Add cfg gate if it uses Rayon or threading.51- If the file grows past ~400 LOC, proactively split (extract types, tests, or trait impls).
d-o-hub