jx12n 3bcfb3c576 feat: Bazel build, crate docs/ai-lookup, docker images, and engine hardening

- 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

2026-06-07 18:29:38 -06:00

3.3 KiB

Raw Blame History

Contributing to tidalDB

Quick Start

tidalDB is the tidaldb crate at tidal/ in this Cargo workspace. Run cargo commands from the workspace root, targeting this crate with -p tidaldb.

# From the workspace root:

# Confirm the engine compiles and all tests pass
cargo test -p tidaldb

# Confirm doc tests and examples compile and run
cargo test -p tidaldb --doc
cargo test -p tidaldb --examples

Run Samples Checklist

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

# Doc tests (default features)
cargo test -p tidaldb --doc

# Doc tests with optional features
cargo test -p tidaldb --doc --features test-utils,metrics

# All four examples compile and run
cargo run -p tidaldb --example quickstart
cargo run -p tidaldb --example cli_embedding
cargo run -p tidaldb --example axum_embedding   # Ctrl+C to stop
cargo run -p tidaldb --example actix_embedding  # 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 -p tidaldb -- --check
cargo clippy -p tidaldb -- -D warnings
cargo test -p tidaldb --lib

Run the complete gate manually:

cargo fmt -p tidaldb
cargo clippy -p tidaldb -- -D warnings
cargo test -p tidaldb
cargo bench -p tidaldb --no-run   # ensure benches compile

Project Layout

tidalDB is the tidaldb crate at tidal/ in this Cargo workspace. Companion crates tidal-net, tidal-server, and tidalctl are workspace siblings at the repository root.

tidal/
  src/            Flat module layout (engine source)
    cohort/       Cohort-scoped signal aggregation
    db/           TidalDb handle, builder, config, metrics
    entities/     Item / User / Creator entity model
    load/         Bulk load / ingest paths
    query/        RETRIEVE / SEARCH / SUGGEST parser, planner, executor
    ranking/      Profile engine, signal scoring, diversity enforcement
    replication/  WAL-stream replication (cluster mode)
    schema/       Schema builder, validation, signal/profile defs, error types
    session/      Session + agent context, policies
    signals/      Signal ledger, decay, velocity, windowed counters, checkpoint
    storage/      StorageEngine trait, fjall backend, key encoding
    testing/      Shared test harness + fixtures
    text/         Tantivy full-text indexing
    wal/          Write-ahead log, group commit, crash recovery
  benches/        Criterion benchmarks
  examples/       Embedding guides (quickstart, axum, actix, cli)
  tests/          Integration and crash-property tests
  docker/         cluster / standalone / deploy Dockerfiles
  site/           Marketing site (Next.js)
  docs/           Specs, API, guides, research, runbooks, ops, planning

Coding Standards

See docs/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

3.3 KiB Raw Blame History