This page is the engine’s construction record. In the 0.124 line, work
stays focused on maintenance, security and the media capabilities
workflows need; no new crate admissions are planned, and contributions
focus on fixes
(CONTRIBUTING).
Cargo.toml
under [workspace.metadata.diamond] wip, and some of those ship in the
binary.
Canonical source: ADR-003,
the gate table in CONTRIBUTING.md,
and the checker
scripts/ci/check-crate-gates.sh.At v: crates admitted ·
pre-admission ().The 12 gates
1
Gate 1: SPEC
A crate spec exists at
docs/crate-specs/<crate>.md. It declares:
purpose, layer (L0/L0.5/L1/L2/L3/L4), LOC budget, public API surface,
security axes, tracked ADRs. No code before spec.2
Gate 2: TDD
Tests written before implementation. The commit history shows
RED before GREEN: failing tests on one commit, minimal
implementation on the next. Reviewed in gate 11.
3
Gate 3: IMPL
Minimal implementation. Compiles with
cargo build --workspace.
Every test green with cargo test --workspace --lib. No # TEMP
without a removal plan. No #[allow(dead_code)]. Size walls (ADR-154):
2,500 lines per file and 25,000 production lines per crate, with
warnings at 1,500 and 15,000.4
Gate 4: CLIPPY 0
cargo clippy --workspace --all-targets -- -D warnings: zero warnings.
unwrap_used = "deny" enforced workspace-wide. Zero .unwrap() /
.expect( in src/ outside #[cfg(test)].5
Gate 5: MUTATION ≥ 90%
cargo mutants -p <crate>: at least 90% of mutants killed. Catches
untested branches, “happy path only” tests, dead clauses. Data-heavy
crates (e.g., nika-catalog) may use 85% with justification in spec.6
Gate 6: PROPERTY
Property tests via
proptest for any crate touching: security,
parsers, encoding, taint propagation, capability resolution. Regression
seeds checked into proptest-regressions/.7
Gate 7: BENCHMARKS
benches/ directory with criterion if the crate is on a hot path
(parsers, catalog lookup, template resolution). Waivable for pure-types
crates with justification in spec.8
Gate 8: DOCS
cargo doc --no-deps --document-private-items: zero warnings. All
public items documented. #[doc(hidden)] used sparingly and with reason.9
Gate 9: CANARY E2E
A
.nika canary workflow (check-crate-gates.sh looks for
tests/canary/<crate>.nika) exercises the crate end-to-end against the
rest of the workspace. The checker reports the gate as skipped when no
canary exists; it is waivable for L0 foundation crates with no runtime
surface.10
Gate 10: PARITY LEGACY
Golden test comparing output against the legacy v0.79.3 implementation,
read from the
brouillon branch (git show brouillon:<path>). Flags
behavior drift from v0.79 for conscious review.11
Gate 11: REVIEW SWARM
Three independent reviewers read the change in parallel. Every P0 and P1
finding must be fixed before merge.
12
Gate 12: ATOMIC COMMIT
Single commit. Message:
Why twelve
Each gate catches a failure mode seen in production Rust codebases at
scale. Dropping any one means accepting a known regression vector.
Exemptions
A gate is genuinely not applicable for some crate types:benches/for a pure-types crate with no hot path.- Canary E2E for L0 foundation (nothing to execute end-to-end).
- PARITY for crates with no v0.79 counterpart (Diamond-original code).
docs/crate-specs/<crate>.md with a
1-paragraph justification. They are not defaults. They are deliberate.
Admission cadence
During the Diamond rewrite, crates were admitted one at a time, one atomic, bisectable commit each, with per-admission alpha tags on the 0.8x train. That cadence is historical: public releases are tagged engine versions (today ), not per-crate alphas.See also
Layer registry
The layers and the mechanical sort test for a new crate.
Forward-compat invariants
The public-API contract every admitted crate honors.
L0 foundation decisions
The early decisions that shaped L0, and what became of them.
Constellation
The map of admitted and pre-admission crates.