3bcfb3c576
- Add BUILD.bazel across tidal, tidal-net, tidal-server, tidalctl for bzlmod build - Add tidal/ crate docs (README, CHANGELOG, CONTRIBUTING, AGENTS, CLAUDE, API, ARCHITECTURE) and ai-lookup reference - Add docker standalone/cluster/deploy images, compose, and prometheus config - Harden WAL (batch format, writer, dedup, diagnostics), text syncer/collectors, and vector registry - Expand tidalctl CLI and tests; restructure WAL/visibility integration test suites - Refine tidal-net transport/client/server and tidal-server cluster/scatter-gather
65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
# Milestone 0 · Embeddable Runtime (Overview)
|
|
|
|
Milestone 0 proves that tidalDB can run entirely in-process with zero-configuration defaults, deterministic file layout, and tooling support. Engineers can `cargo add tidaldb`, open an ephemeral database, and run doctested samples before touching the harder ranking work.
|
|
|
|
## Objective
|
|
|
|
Ship the runtime shell that every later milestone depends on: builder/config API, sandboxed paths, WAL/metrics plumbing, CLI inspection, and living documentation.
|
|
|
|
## Deliverables
|
|
|
|
- `TidalDb::builder()` with `ephemeral()` and `single_process()` shortcuts, eager path validation, deterministic shutdown hooks, and temp-directory helpers used by doctests/integration tests.
|
|
- Tooling + diagnostics: `tidalctl` CLI (`status`, `paths`) and optional `/metrics` + `/healthz` endpoints that read the same files as the embedded process.
|
|
- Samples + docs: quick start code, doctests, Axum/Actix embedding examples, CONTRIBUTING checklist updates.
|
|
|
|
## Phase Breakdown
|
|
|
|
1. **Phase 1 — Embeddable Runtime Skeleton**
|
|
- Config + builder API with temp dirs, sandboxed layout, shutdown hooks.
|
|
- Deterministic path helper reused everywhere.
|
|
2. **Phase 2 — Tooling & Diagnostics**
|
|
- `tidalctl` surface plus metrics exporters sharing the same path helpers.
|
|
- Health probes expose WAL sequence, config hash, uptime.
|
|
3. **Phase 3 — Samples & Docs**
|
|
- Quick-start doctest stays green in CI.
|
|
- Embedding examples for Axum/Actix/CLI + CONTRIBUTING updates.
|
|
|
|
Each phase has task files under `docs/planning/milestone-0/phase-*`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Builder defaults require zero manual config; paths validated up-front.
|
|
- Shutdown drains background workers and surfaces errors.
|
|
- Temp-directory helper cleans up automatically unless `preserve()` is called.
|
|
- `tidalctl status --path <dir>` prints WAL seq, storage layout, config snapshot.
|
|
- Metrics endpoint (optional) exposes uptime, WAL queue depth, build hash.
|
|
- Docs + samples compile via `cargo test --doc`; doctests fail CI if stale.
|
|
|
|
## Dependencies & Unblocks
|
|
|
|
- **Depends on:** None — foundational.
|
|
- **Unblocks:** Every milestone that needs storage paths, WAL writers, doctests, or CLI inspection (M1 onward).
|
|
|
|
## UAT Snapshot
|
|
|
|
```
|
|
let db = TidalDb::builder().ephemeral().with_temp_dir().open().unwrap();
|
|
db.health_check();
|
|
tidalctl status --path <dir>;
|
|
cargo test --doc;
|
|
```
|
|
|
|
All commands succeed without hand configuration.
|
|
|
|
## Research / Reference Notes
|
|
|
|
- `docs/research/tidaldb_signal_ledger.md` — running-score math informs future phases; builder must not block that work.
|
|
- `docs/research/tidaldb_wal.md` — dictates WAL layout and diagnostics exposed by tooling.
|
|
|
|
## Risks & Mitigations
|
|
|
|
- **Risk:** Temp directories linger on CI failures.
|
|
**Mitigation:** `TempTidalHome::drop` best-effort cleanup + `preserve()` flag for debugging.
|
|
- **Risk:** Tooling diverges from runtime paths.
|
|
**Mitigation:** `Paths` helper shared between runtime, CLI, and docs.
|