ad4134e280
- Eliminate the tidal/ self-contained doc mirror; docs now have two canonical homes (root *.md and docs/), with planning/specs/research/reviews moved up - Remove stale .agents/skills and .ai mirrors; canonicalize skills under .claude/ - Add pre-commit hook + scripts/check-docs.sh doc-guard + scripts/install-hooks.sh - Implement M0-M10 seven-dimension review findings across engine, net, server, and tidalctl (durability, replication, query, WAL, storage, CLI hardening)
57 lines
2.8 KiB
Markdown
57 lines
2.8 KiB
Markdown
# 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.
|