# Integration Matrix Gate

Release gate that exercises the PROJECT.md matrix (chainfire → flaredb → plasmavmc → creditservice → nightlight).

## Release hook
- Run this matrix **before any release cut** (tag/publish). Command: `nix develop -c ./scripts/integration-matrix.sh`.
- After a green run, copy logs from `.cccc/work/integration-matrix/<timestamp>/` to `docs/evidence/integration-matrix-<timestamp>/` and reference the path in release notes.
- If KVM is unavailable, use `SKIP_PLASMA=1` only as a temporary measure; restore full run once nested KVM is enabled.
- Defaults: script now auto-creates a tiny qcow2 in `LOG_DIR` and picks `qemu-system-x86_64` from PATH; set `PLASMA_E2E=1` to run PlasmaVMC ignored e2e once qcow/QEMU is available.

## Prerequisites
- Cluster services reachable (ChainFire, FlareDB, PlasmaVMC, CreditService, NightLight).
- Nested KVM available for PlasmaVMC tests; run `sudo scripts/nested-kvm-check.sh` on hosts.
- `cargo` toolchain present on the runner.
- For PlasmaVMC e2e (once qcow is provided): set `PLASMAVMC_QEMU_PATH` and `PLASMAVMC_QCOW2_PATH` to enable QEMU-backed tests; the script will set best-effort defaults if unset.

## How to run
```
# Dry run (prints commands, no tests)
DRY_RUN=1 scripts/integration-matrix.sh

# Full run (all legs)
scripts/integration-matrix.sh

# Skip PlasmaVMC leg if KVM unavailable
SKIP_PLASMA=1 scripts/integration-matrix.sh

# PlasmaVMC ignored e2e (requires QEMU + qcow; defaults auto-provisioned if available)
PLASMA_E2E=1 scripts/integration-matrix.sh
```

Logs are written to `.cccc/work/integration-matrix/<timestamp>/` by default; override with `LOG_DIR=...` if needed.

## What it covers
1) chainfire → flaredb: Raft+Gossip cluster write/read with failover path (cargo tests).
2) flaredb → plasmavmc: VM metadata durability across leader switch (cargo tests).
3) plasmavmc → creditservice: Admission Control CAS/rollback under contention (cargo tests).
4) creditservice → nightlight: Metrics feeding billing/alerts (cargo tests).
5) end-to-end (future harness): tenant loop with FiberLB/FlashDNS once approved; runs will emit junit/json artifacts to `.cccc/work/results/`.

## Notes
- Use `DRY_RUN=1` on CI to verify wiring without requiring KVM.
- If nested KVM is disabled, enable via NixOS (`boot.extraModprobeConfig = "options kvm-intel nested=1";` or kvm-amd) and reboot once. Refer to `scripts/nested-kvm-check.sh` for the exact snippet.