pond AGENTS.md

Pond - project instructions

<comment_instructions>

1. Minimalism: Write comments only when the why of the code is not obvious from the code itself. Never explain the what.
2. Self-Documenting Code: Choose clear, descriptive names for variables, functions, and classes so that comments become redundant.
3. Banned Comments: DO NOT include:
   • Trivial explanations (e.g., # Loop through users).
   • "TODO" notes or author tags unless explicitly requested.
   • Autogenerated file headers or boilerplate comments.
4. Formatting: Place comments on the same line as simple logic or directly above complex blocks. Keep explanations strictly under two sentences. </comment_instructions>

Commands

• Build: cargo build
• Test: cargo test
• Lint: cargo clippy -- -D warnings
• Format: cargo fmt --check (use cargo fmt to fix)
• Lockfile is enforced in CI with --locked; locally, plain commands are fine. If Cargo.lock changes unexpectedly, git status will show it.

Tests

PLACEMENT RULE - read before writing any test. A test lives next to the code it exercises. If it tests one module's behavior - even when it goes through a Store or handler call - it is a UNIT test and belongs in #[cfg(test)] mod tests at the bottom of that src/... file. tests/integration/ is ONLY for genuine cross-module integration: multiple subsystems wired end to end (e.g. ingest -> search -> get over a fixture corpus). A Store-level, single-module, or pure-helper test in tests/integration/ is in the WRONG place - move it to src/. When in doubt, default to a unit test in src/.

• Layout (all crate paths are under packages/pond/): unit tests live in #[cfg(test)] mod tests next to the code they test (packages/pond/src/...). All integration tests are bundled into one binary at packages/pond/tests/integration.rs, with each suite as a module under packages/pond/tests/integration/<name>.rs and pulled in via #[path = ...] mod <name>;. Keep new integration suites in this folder and add a matching #[path] line - never drop a loose tests/foo.rs next to integration.rs (it would compile as a second binary and re-link the whole crate).
• Adapter-specific integration tests go in packages/pond/tests/integration/adapter/<adapter>.rs (mirroring packages/pond/src/adapter/<adapter>.rs), not in concern-level files; keep cross-adapter interop (e.g. the foreign-restore matrix) in packages/pond/tests/integration/adapter/mod.rs, the seam analog of packages/pond/src/adapter/mod.rs.
• Run everything: cargo test.
• Run one integration suite: cargo test --test integration -- <module>:: (e.g. ... -- search::).
• Run one unit-test module: cargo test --lib <module>:: (e.g. ... --lib sessions::tests::).
• Run one test by name: cargo test <name> (substring match across all binaries; add -- --exact to require a full match).