vorn: Skill for Claude Code

Rust idioms for Vorn

Written for the pinned toolchain (packages/core/rust-toolchain.toml) and for a terminal core where every byte a shell prints passes through this code. When a rule here and the surrounding code disagree, match the surrounding code and raise it in the PR.

Types and data

• Model states as enums, not flags plus Options. If two fields are only valid together, they belong in one variant.
• Newtypes for units that must not mix: byte offsets, record numbers, epochs, UTF-16 lengths, columns. struct Rseq(u64) costs nothing and makes a swapped argument a compile error.
• Strings: take &str (or &[u8] for terminal bytes, which are not UTF-8 guaranteed), return String only when the caller needs ownership. Cow<'_, str> when a function usually returns its input unchanged.
• Collections: Vec by default; VecDeque for rings; HashMap for lookups; BTreeMap when order matters or for deterministic output in tests and serialization. Derive Hash, Eq, PartialEq together, never by hand unless the semantics differ.
• Conversions through From/TryFrom, not ad hoc to_x() helpers. Use TryFrom whenever the conversion can lose information (usize to u32 on the wire is the usual one).
• Derive Debug on every public type; derive Clone, Default, Copy only when they are cheap and meaningful.

Errors

• Library crates return Result<T, CrateError> with an error enum per crate (implement std::error::Error and Display, by hand or with thiserror if it is already in the tree). The message says what failed and with which input, in the words the TypeScript used when parity matters.
• ? to propagate, with From impls between layers. No Box<dyn Error> in a library's public API.
• unwrap()/expect() only for invariants the code itself establishes, with expect("why this cannot fail"). Never on input from a PTY, a file, the network or a client.
• Panics never cross FFI.