A run rebuilds what it tests, and leaves a receipt saying what it covered

The danger is not that the suite breaks. It is that nobody notices it
stopped running (novox/hq 04-ISSUES/005). The harness this replaces had
not built for two and a half months and nothing said so — and this suite
needs a hypervisor, so it inherits exactly that: it runs when somebody
remembers, and remembering is not a mechanism.

So running, recording, and rebuilding are one act:

- the host binary, control-plane image and builder are rebuilt from
  source first. The last two both parse manifests; building one and not
  the other left a binary eleven hours old refusing a field the mesh had
  just renamed, found by a full run.
- a receipt lands in XDG state — outside git, because the question is
  whether *this machine* has run it, and a receipt in git would be a
  claim about everybody's machine made by whoever committed last.
- `last-run` judges it and exits non-zero when it no longer counts.

Three faults found by running the thing rather than reading it, each now
held by a test confirmed to fail without it:

- counted() passed every test while parsing nothing. The runner colours
  its summary even into a pipe; the fixtures were clean text that had
  been imagined rather than captured. A fixture that agrees with the
  mistake proves the mistake.
- a receipt for `suite test/lastrun.test.ts` was indistinguishable from
  one for the real thing — 005's own symptom, rebuilt inside its remedy.
  The receipt now records what ran.
- a tree with uncommitted work reported the bare commit, claiming
  coverage of code nobody can check out. Nothing else could tell: the
  hash is identical either way.

Proven on real machines: 22/22, against all three repositories.
This commit is contained in:
2026-08-31 15:02:19 +02:00
parent e1317c9a69
commit 033ad7ec69
11 changed files with 762 additions and 15 deletions
+29 -2
View File
@@ -235,13 +235,35 @@ This repository carries implementation. It does not carry decisions.
No build step — Node strips the types.
```
npm test the declaration layer and the diagram, offline, 49 tests
npm run test:integration real scenarios against a real hypervisor, 14 tests
npm test the declaration layer and the diagram, offline
npm run test:integration real scenarios against a real hypervisor
npm run typecheck source and tests both — a test that does not compile is a test
that silently never ran
npm run check typecheck + both suites — this is the gate
npm run last-run when this machine last ran the suite, and whether that still counts
```
**The integration suite rebuilds what it tests, and leaves a receipt saying it ran.**
It needs a hypervisor, so it cannot run on every push — which means it runs when somebody
remembers, and *remembering is not a mechanism*. The harness this replaces had not built for two
and a half months and nothing said so (`novox/hq` 04-ISSUES/005). So:
- **Before the run**, the host binary, the control-plane image and the builder are rebuilt from
source. The last two both parse manifests; building one and not the other is how a rename gets
tested against an eleven-hour-old binary.
- **After the run**, a receipt is written to XDG state — outside the repository, because the
question is *has this machine run it*, and a receipt in git would be a claim about everybody's
machine made by whoever committed last.
- `last-run` judges it and exits non-zero when it no longer counts: old, failed, taken against
commits the repositories have moved past, taken against a tree with uncommitted work, or a run
that never included the end-to-end file.
**A receipt that says nothing about something is not a receipt that clears it.**
`suite <paths>` runs something narrower, and the receipt records that it did — a green run of the
unit tests must not be readable as coverage of the pipeline. `--no-build` skips the rebuild, for
iterating on a test rather than on the code under it.
**A test names the decision it defends** (`novox/hq` ADR 0017). A decision with no test is one
that will quietly stop being true, and nobody learns that from a document:
@@ -257,6 +279,11 @@ that will quietly stop being true, and nobody learns that from a document:
| the live diagram distinguishes scenery from a node | ADR 0016 |
| the live diagram draws what exists, never what was asked for | the diagram design |
| a picture nobody can open is not a picture | the diagram design |
| a run that raised no machines is not end-to-end coverage | 04-ISSUES/005 |
| a run whose result could not be read writes nothing | 04-ISSUES/005 |
| the control plane's image and builder are always built together | 04-ISSUES/005 |
| every repository the receipt claims was built by the run | 04-ISSUES/005 |
| a run against uncommitted work does not cover the commit | 04-ISSUES/005 |
**Mocking the hypervisor is forbidden.** A fake would assert that the fake behaves as expected,
which is the shape of test this project exists to stop shipping. Integration tests skip with a