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)
2.8 KiB
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 |
| Vision / use cases / sequences / architecture | ../VISION.md, ../USE_CASES.md, ../SEQUENCE.md, ../ARCHITECTURE.md |
| API / quickstart / coding standards / lessons | ../API.md, ../QUICKSTART.md, ../CODING_GUIDELINES.md, ../thoughts.md |
| Component specs (00–14), research, planning, ops, runbooks | ../docs/ |
| Domain concept reference | ../ai-lookup/index.md |
| Milestone history + known gaps | ../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):
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.