# Iridium
Iridium is the product repository for the Iridium storage engine and its external-facing documentation.
## What Lives Here
- Rust workspace source in `src/`
- integration tests and benchmarks in `tests/` and `benches/`
- Zig kernels in `zig/`
- Python SDK in `sdk/python/`
- product and API documentation in `docs/`
- user-facing use cases and benchmark harnesses in `usecases/`
- product verification scripts in `scripts/`
## Governance
Handshake-protocol governance, planning artifacts, and cross-agent coordination live in the sibling repository `../iridium-dev`.
Use `../iridium-dev` for:
- `overview/`
- `context/`
- `plans/`
- agent instructions and coordination templates
## Changelog
- Product-facing change history lives in `CHANGELOG.md`.
## Basic Verification
- `cargo test --workspace`
- `cargo clippy --workspace --all-targets`
- `cargo bench --bench vector_ann`
- `cargo run --quiet --bin ir -- service-report --listen 127.0.0.1:7001`
- `cargo run --quiet --bin ir -- service-validate --listen 127.0.0.1:7001 --telemetry-endpoint stdout --tls operator-optional --admin-token local-dev`
- `python3 scripts/service_candidate_report.py --report-dir artifacts`
- `python3 scripts/service_lifecycle_report.py --report-dir artifacts`
- `python3 scripts/service_compatibility_report.py --report-dir artifacts`
- `python3 scripts/service_install_report.py --report-dir artifacts`
- `python3 scripts/integrated_harness_report.py --report-dir artifacts`
- `python3 scripts/flagship_release_report.py --report-dir artifacts`
- `python3 scripts/appliance_profile_report.py --report-dir artifacts`
- `python3 scripts/appliance_lifecycle_report.py --report-dir artifacts`
- `python3 scripts/appliance_release_closeout.py --report-dir artifacts`
- `bash scripts/acceptance_gate.sh`
- `python3 scripts/retrieval_quality_gate.py --work-dir /tmp/iridium-retrieval-quality`
- `python3 scripts/durability_report.py --report-dir artifacts`
- `python3 scripts/phase1_handoff_manifest.py --artifact-dir artifacts`
## Embedded Evaluator
- Acceptance artifacts: `artifacts/acceptance_gate_report.json`, `artifacts/acceptance_gate_report.md`, `artifacts/acceptance_alloy_contract.json`
- Retrieval-quality artifacts: `artifacts/retrieval_quality_gate_report.json`, `artifacts/retrieval_quality_gate_report.md`, `artifacts/retrieval_quality_gate_alloy_contract.json`
These are canonical embedded quality-evidence artifacts for the deterministic fixture and are distinct from performance/benchmark outputs.
- Durability artifacts: `artifacts/durability_verification_report.json`, `artifacts/durability_verification_report.md`, `artifacts/durability_verification_alloy_contract.json`
- Strontium handoff artifacts: `artifacts/durability_verification_restart_requery_evidence.json`, `artifacts/durability_verification_scenario_pack.json`, `artifacts/durability_verification_reproduction.md`, `artifacts/durability_verification_trace_summary.json`
- Rhodium cache-transition artifacts: `artifacts/rhodium_cache_evaluator_report.json`, `artifacts/rhodium_cache_evaluator_report.md`
- Phase 1 RC handoff manifest: `artifacts/phase1_embedded_rc_handoff.json`, `artifacts/phase1_embedded_rc_handoff.md`
## Service Candidate
- `cargo run --quiet --bin ir -- service-report --listen 127.0.0.1:7001` prints the shared Sprint 4 service contract surface for the first single-node service candidate path.
- `cargo run --quiet --bin ir -- service-validate --listen 127.0.0.1:7001 --telemetry-endpoint stdout --tls operator-optional --admin-token local-dev` validates the first service candidate config surface.
- `cargo run --quiet --bin ir -- service-serve --listen 127.0.0.1:7001 --telemetry-endpoint stdout --tls operator-optional --admin-token local-dev --max-requests 16` serves the minimal Sprint 4 remote surface.
- `python3 scripts/service_candidate_report.py --report-dir artifacts` writes the machine-readable and Markdown service contract/validation report pair.
- `python3 scripts/service_lifecycle_report.py --report-dir artifacts` seeds a local fixture, runs the service candidate path, exercises health/query/admin routes, and writes lifecycle/status evidence artifacts.
- `python3 scripts/service_compatibility_report.py --report-dir artifacts` packages the service contract, lifecycle evidence, and service-backed retrieval-quality proof into the Sprint 5 compatibility artifact set.
- `python3 scripts/service_install_report.py --report-dir artifacts` packages the Sprint 5 install/release view with deploy profile, support band, install inputs, and release outputs.
- `python3 scripts/integrated_harness_report.py --report-dir artifacts` packages the Sprint 6 integrated ingest/query/restart/recovery harness path and its topology assumptions.
- `python3 scripts/flagship_release_report.py --report-dir artifacts` packages the Sprint 7 flagship release-facing execution evidence and packaging handoff artifacts.
- `python3 scripts/appliance_profile_report.py --report-dir artifacts` packages the Sprint 8 appliance-profile execution, backup/restore, diagnostics, and handoff artifacts.
- `python3 scripts/appliance_lifecycle_report.py --report-dir artifacts` packages the Sprint 8 appliance lifecycle, upgrade continuity, support snapshot, and support-boundary handoff artifacts.
- `python3 scripts/appliance_release_closeout.py --report-dir artifacts` packages the Sprint 9 appliance release-closeout decision and consolidated packet artifacts.
- Single-node operator runbook: `docs/service_single_node.md`
- Install/package guide: `docs/service_install.md`
- Reference topology assumptions: `docs/reference_topology.md`
- Flagship release packaging note: `docs/flagship_reference_stack.md`
- Appliance profile note: `docs/appliance_profile.md`
- Appliance lifecycle note: `docs/appliance_lifecycle.md`
- Appliance release closeout note: `docs/appliance_release_closeout.md`
- Minimal remote endpoints:
- `GET /livez`
- `GET /readyz`
- `GET /metrics`
- `GET /v1/query?q=...`
- `GET /admin/status` with `Authorization: Bearer <token>` when `--admin-token` is set
- `GET /admin/lifecycle?action=status|stop` with `Authorization: Bearer <token>` when `--admin-token` is set
- Service candidate artifacts:
- `artifacts/service_candidate_report.json`
- `artifacts/service_candidate_report.md`
- `artifacts/service_lifecycle_report.json`
- `artifacts/service_lifecycle_report.md`
- `artifacts/service_compatibility_report.json`
- `artifacts/service_compatibility_report.md`
- `artifacts/service_install_report.json`
- `artifacts/service_install_report.md`
- `artifacts/integrated_harness_report.json`
- `artifacts/integrated_harness_report.md`
- `artifacts/flagship_release_report.json`
- `artifacts/flagship_release_report.md`
- `artifacts/flagship_release_handoff.json`
- `artifacts/flagship_release_handoff.md`
- `artifacts/appliance_profile_report.json`
- `artifacts/appliance_profile_report.md`
- `artifacts/appliance_profile_handoff.json`
- `artifacts/appliance_profile_handoff.md`
- `artifacts/appliance_diagnostics_manifest.json`
- `artifacts/appliance_lifecycle_report.json`
- `artifacts/appliance_lifecycle_report.md`
- `artifacts/appliance_lifecycle_handoff.json`
- `artifacts/appliance_lifecycle_handoff.md`
- `artifacts/appliance_support_snapshot.json`
- `artifacts/appliance_release_closeout_report.json`
- `artifacts/appliance_release_closeout_report.md`
- `artifacts/appliance_release_closeout_packet.json`
- `artifacts/appliance_release_closeout_packet.md`
- `artifacts/retrieval_quality_service_report.json`
- `artifacts/retrieval_quality_service_report.md`