@mmnto/pack-rust-architecture

Baseline architectural lessons for Rust + Bevy ECS consumers. ADR-097 Stage 1 pilot under the @mmnto scope (sister to @mmnto/pack-agent-security).

Status

ADR-097 Stage 1 alpha pilot. 8 lessons in 4 tiers, sourced from mmnto-ai/liquid-city PR #134's review cycle (6 lessons via totem review-learn extraction) plus 2 hand-authored seeds for Bucket B1 + B2 territory that didn't surface from automated extraction. Compilation to compiled-rules.json runs in the totem CLI workspace; the lessons/ directory holds source-of-truth markdown for human review and re-compile.

Coverage

The pack targets Rust + Bevy ECS consumers. Rules split across four tiers:

| Tier | Count | Universality | Examples | | ----------------------- | ----- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Numeric safety | 3 | Any Rust + linalg/grid code | Float-to-int overflow → DoS guards; linvel.norm() → f32::INFINITY finiteness checks; runtime+const-assert pairing for tuning constants | | Compile-time discipline | 1 | Any Rust | Float arithmetic methods (.floor(), .ceil(), .sqrt(), etc.) are non-const; rewrite as direct ops + cast | | Bevy ECS | 3 | Bevy consumers | Local<Vec<T>> hot-path allocation pattern; schedule edges as producer-consumer contracts; multi-archetype determinism fixtures | | Testing discipline | 1 | Any test-fixture parity work | Test world builders mirror production install order |

Each lesson is self-contained markdown with citation anchors back to the genesis evidence (PR / round-number / file-path), enabling consumers to drill into the underlying CR/GCA review threads where the architectural invariant was originally surfaced.

Lesson manifest

| Hash | Tier | Title | | ----------------- | ----------------------- | ------------------------------------------------------------------- | | lesson-2d305b47 | Numeric safety | linvel.norm() overflow despite finite components | | lesson-d020574f | Numeric safety | Float stride loop-bound overflow / DoS | | lesson-c79543ba | Numeric safety | Tuning constants need declaration-site const-asserts | | lesson-de45dee2 | Compile-time discipline | Float arithmetic methods are unavailable in Rust const-eval | | lesson-8cefba95 | Bevy ECS | Bevy hot-path: Local<Vec<T>> instead of per-tick collect | | lesson-b25f0c4a | Bevy ECS | Bevy schedule edges encode producer-consumer contracts | | lesson-691fbb72 | Bevy ECS | Determinism test must use 2+ archetypes for sort to be load-bearing | | lesson-9bc7ac4a | Testing discipline | Test world builders must install resources/map in production order |

Coverage boundaries (honest framing)

This pack is a baseline, not a comprehensive Rust + Bevy lint suite. The 8 lessons capture the highest-signal architectural invariants surfaced by one consumer's review cycles (slice-6 spawn dispersion + vehicle-agent collision in mmnto-ai/liquid-city). A Rust consumer with no Bevy footprint will find ~50% direct applicability (the 4 Rust-universal lessons); a Rust + Bevy consumer with determinism requirements will find ~100% applicability.

Install

Add to totem.config.ts:

extends: [
  '@mmnto/pack-rust-architecture',
],

Plus pnpm add -D -w @mmnto/pack-rust-architecture per ADR-085 Layer 1 adoption.

Substrate gap (v0.1)

This pack is the first non-trivial consumer of the ADR-097 § 10 Pack v0.1 substrate, and as such it surfaces a known gap in the substrate that v0.1 papers over with a side-channel:

PackRegistrationAPI.registerLanguage(extension, lang, wasmLoader) wires the web-tree-sitter side of the engine — loadGrammar (ast-classifier.ts), ast-query.ts (code-element extraction), ast-gate.ts (lite-build dispatch), and the lite-build wasm-shim. The runtime hot path for ast-grep rule matching, however, is @ast-grep/napi, which has its own registerDynamicLanguage API that the substrate does not surface. At @ast-grep/[email protected] only Lang.Html, Lang.JavaScript, Lang.Tsx, Lang.Css, and Lang.TypeScript are built-in; non-built-in languages are unreachable from parse(name, source) until registerDynamicLanguage is called with the parser binding (e.g., from @ast-grep/lang-rust).

v0.1 workaround (this pack): register.cjs invokes napi.registerDynamicLanguage({ rust }) directly, alongside the substrate's api.registerLanguage('.rs', 'rust', wasmLoader) call. The pack imports @ast-grep/lang-rust (parser binding) and @ast-grep/napi (the engine's napi instance) directly. The dual registration ensures Rust ast-grep rules dispatch correctly through both paths.

Visible debt: This side-channel is documented as time-boxed precedent in mmnto-ai/totem#1774, gated on N≥2 pack consumers before the API shape locks. Once a second non-trivial pack lands, registerNapiLanguage will be lifted into PackRegistrationAPI and this pack will migrate to the API-driven path. Future packs that copy the side-channel pattern should link back to that ticket so the visible-debt tally stays accurate.

Provenance

• Initial corpus: PR mmnto-ai/liquid-city#134 review cycle (R1-R11 across 12.4h, 11 review rounds, 39 inline comments).
• Extraction tooling: totem review-learn (Sonnet 4.6 LLM, ~30s per cycle, ~10k tokens).
• Manual seeding: Lessons de45dee2 (B1) and b25f0c4a (B2) hand-authored for Rust const-eval limits and Bevy schedule-edge invariants that didn't surface from automated extraction. Cited evidence: PRs mmnto-ai/liquid-city#132 R1 (B1) and mmnto-ai/liquid-city#125 R6 + mmnto-ai/liquid-city#134 task 5 (B2).
• Curation: lc-Claude (LC lane) selected the 8-lesson active set per universality × architectural-invariant × enforceability scoring; dev-Gemini (synthesis lane) confirmed the selection.
• Audit trail: audits/internal/2026-04-30-ecosystem-churn-diagnosis.md (totem-strategy disk) holds the cross-agent diagnostic thread that produced this pack.

License

MIT. Same as the Totem monorepo.