# Contributing to tidalDB

## Quick Start

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

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

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

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