jordan/tidaldb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
39ada28c6e
tidaldb/docs/planning/milestone-0
History
jordan 6fdaa1584b feat: complete M1 signal engine — m0p3 samples/docs, m1p5 TidalDb API, examples, and periodic checkpoint 
- 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>
2026-02-20 22:45:10 -07:00
..
phase-1 feat: M0p1 runtime skeleton, M0p2 tooling & diagnostics, m1p4 signal ledger 2026-02-20 20:32:00 -07:00
phase-2 feat: M0p1 runtime skeleton, M0p2 tooling & diagnostics, m1p4 signal ledger 2026-02-20 20:32:00 -07:00
phase-3 feat: M0p1 runtime skeleton, M0p2 tooling & diagnostics, m1p4 signal ledger 2026-02-20 20:32:00 -07:00
README.md feat: complete M1 signal engine — m0p3 samples/docs, m1p5 TidalDb API, examples, and periodic checkpoint 2026-02-20 22:45:10 -07:00

README.md

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.