Fountain-Store.git · AGENTS.md

revision 7a29ac8c61f5eb84ed2dad3f9f58081ca6bee2e9 · complete file

# AGENTS

## Purpose
Define non-negotiable behavioral constraints and routing for work in this repo.

## Behavioral Invariants (must not break)
- Pure Swift only (standard library + Foundation). No FFI or C/Obj-C/C++/SQLite.
- Single writer (actor); many readers via MVCC snapshots.
- ACID batch commits: append to WAL, fsync, apply to memtable, flush to SSTables.
- Atomic manifest updates (write-then-rename); crash-safe recovery.
- Secondary index updates occur in the same batch as base writes.
- Deterministic tests; include crash/recovery simulation points.

## Design Defaults (preferred unless requirements say otherwise)
- Sorted memtable (start with ordered array; optimize later).
- Leveled compaction; per-SSTable Bloom filters for fast negative lookups.
- JSON as initial codec; keep codec interfaces pluggable.
- Background compaction actor with backpressure when debt is high.

## Validation and Correction Expectations
- Block CRC for WAL and SSTable data blocks.
- Bloom false-positive sampling during tests.
- Manifest monotonicity and reference integrity (only tables in manifest are live).
- Replay last WAL segment when manifest is behind.
- Quarantine orphaned SSTables not referenced by the manifest.
- Periodic index verification; rebuild index when mismatch exceeds threshold.

## Quality Bar
- Unit tests for touched areas pass.
- No data loss across power-cut simulations.
- Public API (FountainStore, Collection, Index, Snapshot) remains stable unless explicitly planned.

## Workflow Expectations
- Small, reviewable commits with descriptive messages.
- Keep `docs/` updated when public API changes.
- Annotate crash points with `// CRASH_POINT(id: ...)` when added.

## Routing
- For multi-step or high-risk work, follow `PLANS.md`.
- Procedural steps belong in `.codex/skills/` (for example build/test commands).
- Product status and roadmap live in `docs/PROJECT_STATUS.md` and `docs/LEGACY/ROADMAP.md`.
- Code layout: `Sources/` for implementation, `Tests/` for tests, `docs/` for documentation.