# Golden fixtures

The golden suite runs on a **synthetic cluster corpus** — nothing here is
recorded from a real cluster. Inputs live in code:

- `tests/engine/synthetic/cluster-spec.ts` — hand-authored cluster specs
  (`synthetic-aws`, `synthetic-azure`) with deliberately encoded edge cases
  (cross-AZ nodegroups, RS hash folding, templated vmalert instances, HPA
  renamed targets, PVC size via each source path, pricing gaps, a
  label-less node, a non-running pod, ...). Every number is chosen so the
  pipeline outputs are hand-computable; the arithmetic is asserted in
  `tests/engine/synthetic.spec.ts`.
- `tests/engine/synthetic/build-payloads.ts` — compiles a spec into the exact
  query → payload map the engine issues. Query strings and the vmcluster
  workload set are derived from the engine's own exported constants and
  classifiers, so builder/engine drift is structurally impossible; a
  two-way assertion (built keys === consumed keys) catches rot in either
  direction.

Only the six golden artifacts live on disk, under
`tests/fixtures/<region>/`: `resolve.json`, `inventory.json`,
`pricing_coverage.json`, `workloads.json`, `scenarios.json`,
`report-model.json`.

```bash
npm run goldens              # check: diff engine output vs goldens, exit 1 on drift
npm run goldens -- --force   # rewrite goldens with current output
```

The goldens are byte-stable (JSON 2-space, trailing newline, insertion
order). `tests/engine/goldens.spec.ts` runs the same pipeline in CI and
compares with a rel 1e-9 float tolerance and exact key-set equality, so a
golden whose keys drifted fails even when the numbers match.

## Adding or changing a PromQL query

The engine's query constants are pinned by literal in
`tests/engine/synthetic.spec.ts`. Changing or adding a query:

1. Update the engine constant.
2. The pinned-literal test and the two-way consumption test fail — add or
   adjust the builder case in `build-payloads.ts` (and the pinned literal).
3. Re-run the suite; hand-verify any changed assertion arithmetic in
   `synthetic.spec.ts`.
4. `npm run goldens -- --force` and review the diff.

No dataplane access is ever required to evolve the corpus.