iridium-db 0.2.0

A high-performance vector-graph hybrid storage and indexing engine
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
73
74

# Performance Closeout

Date: 2026-03-01  

## Acceptance Criteria Mapping

1. CBO improves plan quality measurably on skewed/mixed workloads and remains within planning latency budgets.
   - Status: Met.
   - Evidence:
     - Planner stats lifecycle + mode fallback landed (CBO/heuristic selection + stats versioning).
     - Tests: `explain_uses_cbo_when_fresh_stats_available`, `explain_falls_back_to_heuristic_when_stats_are_stale`.
     - Artifacts and implementation tracked under the corresponding maintainability and performance reports in governance history.

2. Hot-path kernels meet correctness parity and deliver benchmarked latency/throughput gains.
   - Status: Met.
   - Evidence:
     - Batched cosine kernel path with Zig hook integrated.
     - Parity test: `cosine_batch_kernel_matches_scalar_scores`.
     - Runtime knob sweep artifacts:
       - `artifacts/tuning_sweep_report.json`
       - Recommended config: `default` (`morsel=256`, `workers=0`, `scan_mult=64`) with best burst p99.

3. p95/p99 telemetry is accurate, actionable, and tied to automated regression thresholds.
   - Status: Met.
   - Evidence:
     - True percentile estimator implemented for p95/p99.
     - Prometheus export and CLI metrics include p99.
     - Regression gate automation:
       - `scripts/slo_gate.sh`
       - `scripts/release_gate.sh`
     - Gate artifacts:
       - `artifacts/slo_gate_report.json`
       - `artifacts/release_gate_report.json`

4. Mixed ingest/query workloads sustain target throughput with stable tail latency.
   - Status: Met.
   - Evidence:
     - Mixed workload matrix:
       - `artifacts/mixed_workload_report.json`
     - Soak + failure injection:
       - `artifacts/soak_failure_report.json`
       - `failure_injection.recover_failures = 0`
     - Concurrent stress:
       - `artifacts/concurrent_stress_report.json`
     - All corresponding SLO/overall checks pass.

5. Benchmark and runbook artifacts are complete and reproducible for external users.
   - Status: Met.
   - Evidence:
     - Scripts:
       - `mixed_workload_matrix.sh`
       - `soak_failure_check.sh`
       - `concurrent_stress.sh`
       - `tuning_sweep.sh`
       - `release_gate.sh`
     - Runbook:
       - `docs/performance/performance_runbook.md`
     - User-facing entrypoint:
       - `README.md` performance testing section.

## Rollout Decision

- Alpha readiness: Pass (`artifacts/release_gate_report.json`)
- Beta readiness: Pass (`artifacts/release_gate_report.json`)
- Recommended runtime query config:
  - `IR_QUERY_MORSEL_SIZE=256`
  - `IR_QUERY_PARALLEL_WORKERS=0`
  - `IR_QUERY_SCAN_LIMIT_MULTIPLIER=64`
  - `IR_QUERY_SCAN_MIN=512`

## Residual Risks

- Current harnesses are local single-node workloads; production rollout should re-run gates on target hardware profiles.
- Release thresholds are currently implemented through shell-based parsers over JSON; if schema evolves, parser maintenance is required.