# tidaldb crate

This is the **`tidaldb` engine crate** — the embeddable database at `tidal/` within the
standalone tidalDB workspace. It is one crate among workspace siblings (`tidal-net/`,
`tidal-server/`, `tidalctl/`); it does **not** carry its own copy of the project docs.

## Canonical docs live at the workspace root — not here

There is exactly one documentation home: the repository root and `docs/`. Do **not**
re-create a `tidal/docs/`, `tidal/ai-lookup/`, `tidal/site/`, or `tidal/README.md`
— those were a stale mirror and were consolidated away. Read and edit the canonical files:

| For… | Read |
|------|------|
| Project instructions, structure, agents, skills, rules | [`../CLAUDE.md`](../CLAUDE.md) |
| Vision / use cases / sequences / architecture | [`../VISION.md`](../VISION.md), [`../USE_CASES.md`](../USE_CASES.md), [`../SEQUENCE.md`](../SEQUENCE.md), [`../ARCHITECTURE.md`](../ARCHITECTURE.md) |
| API / quickstart / coding standards / lessons | [`../API.md`](../API.md), [`../QUICKSTART.md`](../QUICKSTART.md), [`../CODING_GUIDELINES.md`](../CODING_GUIDELINES.md), [`../thoughts.md`](../thoughts.md) |
| Component specs (00–14), research, planning, ops, runbooks | [`../docs/`](../docs/) |
| Domain concept reference | [`../ai-lookup/index.md`](../ai-lookup/index.md) |
| Milestone history + known gaps | [`../CHANGELOG.md`](../CHANGELOG.md) |

## Crate-local layout (`tidal/src/`, flat module layout)

| Module | Responsibility |
|--------|----------------|
| `cohort/` | Cohort-scoped signal aggregation |
| `db/` | Top-level `TidalDb` + builder |
| `entities/` | Item / User / Creator entity model |
| `load/` | Bulk load / ingest paths |
| `query/` | Query parser, planner, executor (RETRIEVE/SEARCH/SUGGEST) |
| `ranking/` | Profile engine, signal scoring, diversity enforcement |
| `replication/` | WAL-stream replication for cluster mode |
| `schema/` | Schema builder, validation, signal/profile defs |
| `session/` | Session + agent context, policies |
| `signals/` | Signal types, decay, velocity, windowed aggregation |
| `storage/` | Entity store, signal ledger, inverted index, HNSW |
| `testing/` | Shared test harness + fixtures |
| `text/` | Tantivy full-text indexing |
| `wal/` | Write-ahead log + crash recovery |

`benches/`, `examples/` (quickstart, axum_embedding, actix_embedding, cli_embedding),
`tests/` (integration + crash-property), and `docker/` (cluster / standalone / deploy)
round out the crate.

## Build & test (workspace-aware)

Run cargo from the **workspace root**, targeting this crate with `-p tidaldb`
(equivalently `--manifest-path tidal/Cargo.toml`):

```bash
cargo test  -p tidaldb            # unit + integration
cargo clippy -p tidaldb -D warnings
cargo fmt
```

**Tests must be fast.** Slow or hanging tests are bugs — fix the root cause, never leave them hanging.