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

2.7 KiB

Raw Blame History

Contributing to tidalDB

Quick Start

# Clone the repo
git clone https://github.com/orchard9/tidaldb && cd tidaldb

# Confirm the engine compiles and all tests pass
cargo test --manifest-path tidal/Cargo.toml

# Confirm doc tests and examples compile and run
cargo test --doc --manifest-path tidal/Cargo.toml
cargo test --examples --manifest-path tidal/Cargo.toml

Run Samples Checklist

Before opening a PR that touches public API or examples, verify all samples still work:

# Doc tests (default features)
cargo test --doc --manifest-path tidal/Cargo.toml

# Doc tests with optional features
cargo test --doc --manifest-path tidal/Cargo.toml --features test-utils,metrics

# All four examples compile and run
cargo run --example quickstart       --manifest-path tidal/Cargo.toml
cargo run --example cli_embedding    --manifest-path tidal/Cargo.toml
cargo run --example axum_embedding   --manifest-path tidal/Cargo.toml  # Ctrl+C to stop
cargo run --example actix_embedding  --manifest-path tidal/Cargo.toml  # Ctrl+C to stop

Expected output for quickstart:

build:   dev
uptime:  0.000s
health:  ok
tidalDB opened, verified, and closed. M0 complete.

Full Quality Gate

The pre-commit hook enforces these automatically on staged Rust files:

cargo fmt   --manifest-path tidal/Cargo.toml -- --check
cargo clippy --manifest-path tidal/Cargo.toml -- -D warnings
cargo test  --manifest-path tidal/Cargo.toml --lib

Run the complete gate manually:

cargo fmt     --manifest-path tidal/Cargo.toml
cargo clippy  --manifest-path tidal/Cargo.toml -- -D warnings
cargo test    --manifest-path tidal/Cargo.toml
cargo bench   --manifest-path tidal/Cargo.toml --no-run   # ensure benches compile

Project Layout

tidal/          Rust database engine
  src/
    db/         TidalDb handle, builder, config, metrics
    schema/     Types, validation, error types
    signals/    Signal ledger, decay, windowed counters, checkpoint
    storage/    StorageEngine trait, fjall backend, key encoding
    wal/        Write-ahead log, group commit, crash recovery
  benches/      Criterion benchmarks
  examples/     Embedding guides (quickstart, axum, actix, cli)
  tests/        Integration and property tests
site/           Marketing site (Next.js)
docs/           Research and planning documents

Coding Standards

See CODING_GUIDELINES.md for the full engineering standards.

Key rules:

Result<T, LumenError> everywhere — no panics on recoverable failures
#![forbid(unsafe_code)] — relaxed only at explicit FFI boundaries with // SAFETY: comment
Property tests for invariants, criterion benchmarks for performance claims
cargo clippy -D warnings must pass with zero warnings

2.7 KiB Raw Blame History