---
name: smith-style
description: "Use before writing or reviewing production Smith Rust."
---

# Smith Style

Load before writing or reviewing production Smith Rust.
Follow [.system/RULES.md](../../../.system/RULES.md) as binding project policy.

## Implemented mechanics

`cargo x check` owns production Clippy bounds and project architecture checks.
`.config/clippy.toml` owns prohibited unbounded std and Smith helper APIs.

## Author guidance
Use `assert!` only for internal invariants, with an assumption-naming message.
Return `Result` for expected state, including invalid input, corruption, EOF, and exceeded bounds.
Pair encode and decode invariants where both sides own them.
Use compile-time assertions for fixed wire widths and constant relationships.
Keep complementary runtime checks when they guard live internal state.
Never make allocator accounting abort because accounting must remain non-allocating, non-locking, and non-aborting.
Name every resource limit with units at its ownership boundary.
Bound bytes, items, channels, queues, loops, retries, recursion, depth, resident state, and allocation attempts.
Make bounded reads report EOF separately from an exceeded limit.
Return an explicit limit result rather than silently truncating input or output.
Use bounded channels with named capacities.
Add each new Smith-owned unbounded helper to `.config/clippy.toml` before use.
Keep each third-party crate name in one facade module and expose Smith-shaped types rather than dependency-shaped APIs.
Keep facade dependencies independent so a facade never leaks its dependency into unrelated modules.
Keep `.config/clippy.toml` disallowed-methods limited to actually unbounded APIs and state each reason.
A finite iterator over validated resident input already has that input's bound.
Name and test recursion depth when recursion is necessary.
Use fixed wire widths and encode them explicitly rather than Rust memory layout.
Use precise nouns and verbs.
Do not abbreviate Smith declarations unless the abbreviation is an established domain term.
Put qualifiers and units last.
Keep index, count, size, length, offset, capacity, and limit distinct.
Assert only O(1) internal facts near codecs, stores, allocators, and comparable internal boundaries.
Keep unsafe opt-ins narrow and retain their stated safety invariant.
For hot paths, measure a floor doing only unavoidable work first.
Keep hot loops contiguous, allocation-free after setup, and shaped for accessed fields rather than object names.
Judge each implementation-to-floor gap from task difficulty and record it per task.
Never impose a magic performance multiplier.
Keep scope smallest, conditions shallow, options explicit at call sites, return types simple, and control separate from data.
Use newtypes where same-typed parameters could mix up.
Order files from public types through behavior to tests.
Comment why and how, not syntax.
Preserve zeroed reserved and padding bytes.
Make each test name its behavior goal and use explicit signals plus deadlines instead of sleeps, polling, or retries.
Run [Compress](../compress/SKILL.md) then [Deslop](../deslop/SKILL.md) after production changes.

## Mechanical naming gate

`cargo x arch` scans authored production declarations for banned abbreviation segments and `max_` | `min_` qualifiers.
It covers declaration heads, parameters, struct fields, enum variants, and `let` bindings after existing literal/comment/test-item sanitization.
It ignores paths, uses, literals, comments, macro invocation lines, macro expansion, raw identifiers, complex patterns, nested block comments, and cfg forms other than `cfg(test)`.