test(7/7): mutation testing, and the gaps it exposed

.github/workflows/ci.yml

@@ -24,3 +24,26 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check
+
+  mutation:
+    # Mutation testing grades the suite rather than the code: it rewrites the
+    # source and asks whether any test notices. Scoped to the promotion gate and
+    # the rewrite guard, it runs in about a minute, so it runs on every pull
+    # request rather than on a schedule nobody reads.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run test:mutation
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: mutation-report
+          path: test/output/mutation
+          if-no-files-found: ignore

.gitignore

@@ -2,6 +2,8 @@ node_modules/
 dist/
 coverage/
 test/output/
+.stryker-tmp/
+reports/
 *.tsbuildinfo
 .env
 .agentv/

docs/testing.md

@@ -17,6 +17,7 @@ land, never lower them to get a build green.
 | Contract | `test/contract.test.ts` | A provider implementation that satisfies the types but not the contract |
 | Chaos | `test/chaos.test.ts` | A dependency failing, hanging, or racing — and the damage that leaves behind |
 | Behavior | `test/behavior.test.ts` | A documented promise that stopped being true even though every unit still passes |
+| Mutation | `stryker.config.json` | A test that runs the code without actually pinning its decisions |
 | Characterization | `test/characterization*.test.ts` | A change to anything this library *generates* — rewritten source, emitted instrumentation, prompts, CLI output, the export surface |
 
 ## Running