iridium-db 0.4.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
75
76
77
78
79
80
81
82
83
84

# Iridium Performance Release Notes (Template)

Release date: `<YYYY-MM-DD>`  
Commit: `3029fdc`  

## Summary

This release delivers optimization and performance hardening across:

- Cost-based planning maturity with stats lifecycle and heuristic fallback.
- Runtime hot-path kernel improvements with correctness parity coverage.
- True p95/p99 observability and SLO automation.
- Mixed-workload tuning with soak, failure-injection, and concurrent stress validation.
- Release-readiness gates and operator runbooks.

## Highlights

- Planner:
  - CBO mode selection based on stats freshness/version.
  - Deterministic fallback to heuristic mode when stats are stale/missing.
- Runtime:
  - Batched cosine scoring path with Zig hook support.
  - Query execution tuning knobs:
    - `IR_QUERY_MORSEL_SIZE`
    - `IR_QUERY_PARALLEL_WORKERS`
    - `IR_QUERY_SCAN_LIMIT_MULTIPLIER`
    - `IR_QUERY_SCAN_MIN`
- Observability:
  - True p95/p99 latency estimation.
  - Prometheus and CLI metrics expose p99.
  - SLO and release gates scripted for reproducible checks.

## Validation Snapshot (From `artifacts/release_gate_report.json`)

- `alpha_ready`: `true`
- `beta_ready`: `true`
- `overall_pass`: `true`
- `soak_p95_micros`: `2469`
- `soak_p99_micros`: `2499`
- `concurrent_p95_micros`: `2182`
- `concurrent_p99_micros`: `2240`
- `concurrent_ingest_p50_eps`: `75276.01`
- `mixed_burst_ingest_eps`: `282852.09`
- `tuning_best_config`: `default`
- `tuning_best_burst_query_p99`: `2006`

## Recommended Runtime Baseline

- `IR_QUERY_MORSEL_SIZE=256`
- `IR_QUERY_PARALLEL_WORKERS=0`
- `IR_QUERY_SCAN_LIMIT_MULTIPLIER=64`
- `IR_QUERY_SCAN_MIN=512`

## Reproducibility

Run in order from repo root:

1. `bash scripts/mixed_workload_matrix.sh`
2. `bash scripts/soak_failure_check.sh`
3. `bash scripts/concurrent_stress.sh`
4. `bash scripts/tuning_sweep.sh`
5. `bash scripts/release_gate.sh`

References:

- `docs/performance/performance_runbook.md`
- `docs/performance/closeout.md`
- `docs/performance/ship_checklist.md`

## Known Risks / Follow-ups

- Harnesses are single-node local runs; production validation on target hardware is still required.
- Release gate parsing relies on shell JSON extraction conventions and should be kept in sync with artifact schema.

## Changelog Entries (Fill Before Publish)

- Added:
  - `<item>`
- Changed:
  - `<item>`
- Fixed:
  - `<item>`
- Deprecated/Removed:
  - `<item or N/A>`