# 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.