CLAUDE.md@crates/orbit-store git:20261029.62200d4A

Immutable. This exact content never changes and is served at /api/v1/blob/2210f24871fa749b.

# orbit-store

All durable Orbit state that is not a search index. Depends only on `orbit-types` and `orbit-common`; knows nothing of runtimes, commands, or transports. Policy and authorization are `orbit-core`'s; the vector schema is `orbit-search`'s.

- Internal direction is enforced by `scripts/check-dependency-direction.sh` (`make ci-fast`): `contracts` (traits/params/projections; no impls, no `rusqlite`) ← `fs` (locks, path safety, atomic writes, YAML) ← `driver/file` | `driver/sqlite` (never import each other) ← `repository` (live invariants that join drivers) / `workflow` (one-shot import/export/reindex/repair/upgrade) ← `compose` (construction). Retired paths (`src/backend`, `src/file`, `src/sqlite`, `src/task_migration`) must not reappear.
- A live write spanning both drivers joins in `repository/`, never in a driver. A one-shot data movement is a `workflow`, never a side effect of opening a store.
- New capability → trait in `contracts`, one impl in one driver, constructor in `compose`. Shared mechanics → `fs`. Concrete construction and migration access stay in composition/bootstrap/`maintenance`.
- Adding a store migration entry also changes the existing handwritten adoption-ledger expectation in `tests/store/migration_freeze/ledger.rs` (`legacy_db_adopts_versioned_ledger`, the independently handwritten `(migration.vNNNN, stable name)` inventory asserted through `Store::open`): declare and update that exact fixture alongside the registry entry, preserving its independent assertion (never derive it from the migration registry), the frozen `SHIPPED_V1_SCHEMA` and the per-prefix schema goldens. A migration-body-only change with no new ledger entry adds no such fixture change.
- SQLite migrations are append-only: never renumber or edit a shipped entry in `driver/sqlite/migration/ledger/registry.rs` or the task registry's own `driver/sqlite/task_registry/ledger.rs`. Shipped bodies and their shape-defining helpers are frozen: each version owns private code, sharing only schema-neutral `migration/introspect.rs` primitives. Version-stamped data backfills may use current domain code. Behavior-preserving extraction into private copies is allowed; changing a shipped shape requires a new entry. The per-prefix schema goldens (store and task registry) are checked by `make goldens` and regenerated by `make goldens UPDATE=1`. The automation, review and local-pull feature registries are frozen in `migration/feature_ledgers/`, which v49 (`absorb_feature_ledgers`) ran to completion; a change to a feature table is a store ledger entry, and no feature code creates or alters tables.
- Crate-root `tests/` holds integration tests through the public `compose`, `contracts`, `maintenance` and `workflow` surfaces; each test runs its fixture in an isolated child process. Admitted unit tests stay in sibling `tests/` dirs; the direction guardrail excludes `**/tests/**`, so their fixtures may cross layers.