6fdaa1584b
- m0p3: CONTRIBUTING.md with run-samples checklist, all 4 examples (quickstart, cli_embedding, axum_embedding, actix_embedding), doc-test coverage for every public API surface - m1p5: TidalDb public API — write_item, signal, read_decay_score, read_windowed_count, read_velocity; StorageBox enum routing memory vs fjall; WalSender/WalHandleWriter bridge; WAL replay on open - Periodic checkpoint: 30s background thread for persistent+schema mode; FjallBackend::Clone (O(1), fjall::Keyspace is ref-counted); graceful shutdown via Arc<AtomicBool> + join before final checkpoint - ROADMAP.md: M0 and M1 fully marked COMPLETE (341 tests passing) - Milestone 2 planning scaffolding added under docs/planning/milestone-2/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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.
|