rimz: Instructions file for Codex

AGENTS.md

Invariant. RimZ routes attention: it surfaces which agent needs you and takes you straight to its pane, where you answer in the agent's own UI.

How to read this contract

This file carries two kinds of statement, and they earn different deference.

Invariants are load-bearing: a product promise, an architectural boundary that a cargo xtask invariants grep enforces, or a durability rule. Breaking one breaks the build or the product. Each section below says which of its statements are invariants. Change one deliberately, in its own commit, with the doc and the gate moving together.

Everything else is a default: the choice that has been right most of the time here. Follow it absent better information. Depart from it when the work in front of you argues otherwise, and say why in the PR or hand-off. A default that keeps losing is a bug in this file, so fix the file.

Match the size of the change to the size of the ask. A refactor you noticed on the way becomes a note unless it blocks you. When this map and the territory disagree, the code is what ships: follow the code, then fix the map in the same change.

Engineering principles

The house style is explicit Rust, and rust-conventions.md is its authority: typed IDs across module boundaries, structured parsers over ad-hoc string work, state machines where a bool would drift, typed Result errors at library boundaries. unwrap, expect, and panics belong in tests, build scripts, and provably impossible states; leave a comment naming why the state is impossible.

Unsafe code is denied; two sites are admitted, each annotated with #[expect(unsafe_code, reason = "...")]: the exported jemalloc configuration in crates/rimz/src/main.rs, and the bench-only counting allocator in crates/rimz/benches/fleet.rs, which the shipped binary never links. A third site is a design decision.

An event or timing fix is proven at the consumer's decision point. A change that removes a later event's power to clear a state first checks whether each producer can deliver the state's opener after its own closer (separate child processes per event, unchained sends, no timestamp on the envelope), since the removed path was what made that reorder harmless. That the producer emitted, or that a timestamp is fresh, is not evidence that the consumer saw it in time. Work placed between a decision and the action it gates (a helper process, a lock, a network call) makes the decision stale by that work's duration: read the decision again after the work, or say why it cannot have changed. When that later read can only defer the action, check it before the work as well, or every deferral repeats the work. A stamp another rule compares with is taken at the instant that rule means. It is also keyed on the state that rule reads: a stamp set on a raw status misses the rows a consumer partitions by their displayed status (a clean turn end parked on background work is raw running and displays as success). A floor that must expire with an existing cadence takes that cadence's own stamp, passed in, not a fresh now() after the pass's work, or it outlasts the cadence and skips the next due pass. A freshness stamp checked against later triggers is taken before the request it covers, or a trigger that lands during the request is absorbed. A refresh an event triggers reads its inputs at the instant the trigger fires, so a limit stated for it says what that read finds then and what next moves the trigger: an answer read too early sticks until that next move. A fix that changes which clock stamps a value audits every comparison against that value for its behaviour at ties, since a stamp that used to trail another may now equal it. A rule that orders two stamps, or compares a row stamp with one copied earlier from the same row, first lists every fold branch that writes or carries each (rg -n -U '<field>\s*=' crates/rimz/src) and evaluates any derived stamp, such as last_request_at(), on the row before and after each branch. A re-registration at rest, or a compaction close with no open bracket, moves turn_started_at without closing a request; a compaction that closes its bracket at rest stamps both turn stamps at the close; and a prompt into a row parked on background work moves neither turn stamp until its Stop. A refactor that moves time reads onto an injected clock keeps every read that followed a lock, I/O, or spawn after that work, and converts between clocks at the present, never at construction. A state a polling consumer reads stays published for at least one of that consumer's read intervals (its backstop tick plus one pass), or the consumer can miss it entirely; a design that withdraws such a state names that interval beside the rule that withdraws it. A state that changes with time alone (no event) reaches a reader that sleeps on a stored retry time only if that time is computed from the change's instant: message::deliver::evaluate_when_condition sets retry_at to the instant an auto-reviewed permission becomes visible, plus the dwell. A wake or deadline moved onto a record field first lists every writer of that field (rg -n -U '<field>\s*=' crates/rimz/src) and checks that the record still arms a wake after each writer that leaves it in the armed state.