overgraph 0.7.0

An absurdly fast embedded graph database. Pure Rust, sub-microsecond reads.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# Benchmark Runner Contract

This document defines the Phase 17 benchmark runner and regression-check contract.

## Commands
- Rust: `scripts/bench/run-rust.sh --profile small --warmup 20 --iters 80`
- Node.js: `scripts/bench/run-node.sh --profile small --warmup 20 --iters 80`
- Python: `scripts/bench/run-python.sh --profile small --warmup 20 --iters 80`

Common optional flags:
- `--output-root <path>` (default: `docs/04-quality/reports`)
- `--run-id <id>`
- `--dry-run`
- `--timeout-seconds <n>`
- `--warmup <n>`
- `--iters <n>`
- `--scenario-set <all|query>` (default: `all`; `query` runs only Phase 23 query scenarios)
- `--allow-legacy-rust-criterion-parse` (opt-in fallback for old Criterion text output)

## Output Layout

Each command creates one run directory:

`docs/04-quality/reports/<timestamp>-<platform>-<lang>-<profile>/`

Files:
- `manifest.json`: machine and runtime metadata, profile details, run identity
- `<lang>.json`: language run result metadata, status, command, duration
- `<lang>.stdout.log`: raw command stdout
- `<lang>.stderr.log`: raw command stderr
- `summary.md`: human-readable summary

## Current Harness Stage
- Rust: `core-benchmark-v1-parity` (runs `src/bin/benchmark_harness.rs` with shared scenario contract)
- Node.js: `connector-benchmark-v3-parity` (shared-profile + shared scenario-contract harness)
- Python: `connector-benchmark-v2-parity` (shared-profile + shared scenario-contract harness)
- Phase 20b adds Criterion `write_txn/*` microbenches for explicit 4/16/64-intent commits, a 16-intent implicit batch comparator, and a same-key conflict-heavy workload. Connector benchmark harnesses should mirror this with ordered `stage(operations)` arrays for Node.js and Python.
- Phase 23 adds `query_ops` Criterion microbenchmarks and shared query-only parity scenarios:
  - `S-QUERY-001` / `query_node_ids_intersected_predicates`
  - `S-QUERY-002` / `query_nodes_intersected_predicates_hydrated`
  Run only the cross-language Phase 23 matrix with:
  `scripts/bench/run-rust.sh --scenario-set query --profile small --warmup 20 --iters 80`
  plus the matching Node.js and Python wrapper commands.

Shared parity contract:
- `docs/04-quality/workloads/scenario-contract.json`

Cross-language parity validator:
- `python3 tools/bench/validate_parity.py --rust <rust.json> --node <node.json> --python <python.json>`

## Baseline Comparison Command

```bash
python3 tools/bench/compare_baseline.py \
  --baseline <baseline-json-or-run-dir> \
  --candidate <candidate-json-or-run-dir> \
  --allowlist docs/04-quality/regression-allowlist.json \
  --warn-threshold-pct 10 \
  --fail-threshold-pct 20 \
  --report-md /tmp/compare.md \
  --report-json /tmp/compare.json
```

Guardrails enforced by `compare_baseline.py`:
- baseline/candidate language must match
- baseline/candidate profile must match
- baseline/candidate harness stage must match
- at least one shared scenario ID must exist

## Notes
- CI automation is defined in `.github/workflows/benchmarks.yml` (manual + nightly).
- Runtime code is frozen for this offline phase window; runner and benchmark assets are allowed.