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

```bash
# 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:

```bash
# 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:

```bash
cargo fmt -p tidaldb -- --check
cargo clippy -p tidaldb -- -D warnings
cargo test -p tidaldb --lib
```

Run the complete gate manually:

```bash
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](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