leteo: Instructions file for Codex

Working on Leteo

Local-first persistent memory for coding agents: one Rust binary over one SQLite database.

Everything written into this repository is in English — code, comments, commit messages, tests, and documents — whatever language the conversation about it happens in.

Building and testing

cargo fmt --all
cargo clippy --all-targets
cargo test              # unit tests, plus the integration tests in tests/
cargo build --release

All three must be clean before a commit. cargo test --lib alone is not enough: it skips tests/, which is where the surface-level guards live.

Rules that have cost this codebase real bugs

1. No test touches a real store. Unit and integration tests create a temporary database. tests/repository_guards.rs fails the build on an absolute .db path, a home_dir() join, or a data directory used near anything that opens a store. Exploratory work against a copy is fine; a scheduled test against the user's database is not.
2. Fix the sibling too. Nearly every defect found here has had one: the prompt was bounded and the summary next to it was not; four of six tools carried a memory's caveats; one of four replicated write paths was redacted. After fixing something, look for the field, path, or surface beside it.
3. A rule lives in one place. Types, review windows, hook event names, index names, trigger names — each is one list that the behaviour and its tests both read. A hand-written second copy is how policy kept a review window that nothing could ever fire. One exception, licensed and written down rather than left to look like the defect: a released migration may freeze a copy of what it needs, because it must give every database the same answer whenever it happens to run. There are two: migration 18's frozen table and the baseline's three SQL literals.
4. A limit that is published is the limit that is applied.
5. Say what could not be done. An empty answer, a busy store, a check that could not run — each says which it is. Reporting the nearest named state instead is how a healthy store gets called corrupt.
6. A guard is verified by breaking what it claims to protect. A test that passed the first time it ran may be watching nothing. Break exactly the behaviour its own sentence names, confirm it fails, and restore — git diff of that file must come back empty. Breaking something near it is worse than not checking: the intersection in engram.rs was "verified" by reversing two sides that produce the same set, which passed, and the comment explaining why the order mattered was wrong. Six guards of one session were put through this afterwards; all six failed as they should, and the checking is what makes that sentence worth writing.
7. Measure before claiming. Timing does not transfer between SQLite builds; ranking does; query construction does not transfer at all. A benchmark that does not go through this binary's own query builder measures something else.