Refuse to overwrite the audit trail with whatever the API still remembers

analytics/runs returned 150 runs on 2026-09-07. Paginated identically with the
same credential on 2026-09-09, it returned 2, both from that morning. The 150
executions of 09-06/07 are gone from the API. Nothing in the response says so:
no retention field, no truncation flag, no total, and pagination terminates
normally, so exhaustion and expiry are indistinguishable.

audit.mjs regenerated in place, which is what its own file header told you to do.
Running it today silently replaced the 150-row ledger with a 1-row one and exited
0. That happened here; the file came back because it was committed. A shrinking
rewrite is now a refusal that names both counts and points at the explorer, and
--prune exists for when the loss is genuinely intended.

The evidence itself does not depend on the endpoint. Every row carries a
transaction hash and those are on Sepolia permanently. What the endpoint owns is
convenience, and it turns out not to own durability.

A second-order effect worth stating: a failed run has no transactionHashes, so it
contributes no row at all. The losing half of this morning's deliberate race,
yhak2pfniragtz0x8we15 / Error(GS026), is invisible in the receipts even while
still inside the retention window. The ledger that records what executed
structurally cannot record what did not - which is the argument for
docs/outcomes-*.jsonl in one sentence, arrived at from the opposite direction.

Filed as DX-8. Also corrected: 80 -> 87 tests in the submission description, the
third stale count of the day.

Author: edycutjong

DX-REPORT.md

@@ -284,3 +284,36 @@ demo. Asking the organiser in Discord before restructuring.
   `staging` before it may be filed**: `check-and-execute` cannot address a member of a
   tuple-returning read (observed in production 2026-08-08, 25+ days stale as of this
   writing).
+
+---
+
+## DX-8 · `analytics/runs` silently ages history out, and it is the audit trail
+
+**Severity:** high — it makes an execution ledger unreproducible, with no signal that it happened.
+**Date:** 2026-09-09
+
+`GET /api/analytics/runs` is the only machine-readable record of what KeeperHub executed, and this
+project treats it as exactly that: `scripts/audit.mjs` paginates it to `nextCursor` exhaustion and
+renders the result as the audit trail.
+
+On 2026-09-07 that call returned **150 runs** for this org. On 2026-09-09, paginated identically
+with the same credential, it returned **2** — both from that morning. The 150 executions of
+2026-09-06/07 were gone. Nothing in the response distinguishes "you have 2 runs" from "you have 2
+runs left": there is no retention field, no truncation flag, no `total`, and the pagination
+terminates normally.
+
+The consequence is worse than a missing feature. A regenerate-in-place — the documented workflow
+for this kind of artifact, and what our own file header instructed — **silently replaces a 150-row
+audit trail with a 2-row one and exits 0.** We hit exactly that and recovered only because the file
+was committed. `audit.mjs` now refuses to shrink the file without an explicit `--prune`.
+
+A second-order effect worth naming: a run that fails has no `transactionHashes`, so it contributes
+no row at all. The losing half of a deliberate race (`yhak2pfniragtz0x8we15`, `Error(GS026)`) is
+invisible in the receipts even while it is still inside the retention window. The endpoint that
+records what executed structurally cannot record what did not.
+
+**Suggested fix:** state the retention period in the docs and return it in the response; add a
+`total` or an explicit `truncated` flag so a client can tell exhaustion from expiry; and expose
+failed runs with enough identity to be counted even without a transaction hash. If retention is
+plan-dependent, say which plan buys what — this is the one endpoint whose whole value is that it
+remembers.

README.md

@@ -214,8 +214,12 @@ The graph is generated, never hand-drawn: `sync.mjs` injects [`src/assemble.mjs`
 **verbatim** into the Code node, so the function the tests run offline and the function the canvas
 runs on-chain cannot drift apart. That is the whole reason the decision surface is pure.
 
-Seven reproducible findings came out of building against it, dated as they were hit and filed
-upstream — see [`DX-REPORT.md`](DX-REPORT.md).
+Eight reproducible findings came out of building against it, dated as they were hit and filed
+upstream — see [`DX-REPORT.md`](DX-REPORT.md). The latest is the sharpest: **`analytics/runs` ages
+history out with no signal**, so the endpoint this project treats as the audit trail returned 150
+runs on 09-07 and 2 on 09-09. `audit.mjs` now refuses to shrink `docs/receipts-*.json` without
+`--prune`, because a regenerate-in-place would have destroyed a ledger the API can no longer
+reproduce. The transaction hashes on disk remain verifiable on the explorer regardless.
 
 ---
 ## 🕳️ The gap that would have silently disarmed a security guard
@@ -462,7 +466,7 @@ refusing correctly is a success, not an error.
 | [`contracts/`](contracts/) | `MockUSDC.sol`, the testnet stand-in, and [`contracts/test/`](contracts/test/) — 22 tests at 100% coverage on every metric, dependency-free |
 | [`test/`](test/) | 87 tests: unit fixtures, the live-response regression file, manifest/roster invariants, and the coverage-gap suite ([`COVERAGE.md`](test/COVERAGE.md)) |
 | [`survey/`](survey/) | The 1,299-Safe measurement: collectors, 1.3 MB of raw responses, and `rederive.py`, which asserts all 24 published figures offline |
-| [`DX-REPORT.md`](DX-REPORT.md) | Seven reproducible KeeperHub findings, dated as they were hit |
+| [`DX-REPORT.md`](DX-REPORT.md) | Eight reproducible KeeperHub findings, dated as they were hit |
 | [`workflows/`](workflows/) | Generated `gavel-drain` graph, 11 nodes (1 trigger + 10 actions), 10 edges |
 | [`docs/rehearsal-11155111.md`](docs/rehearsal-11155111.md) | Rehearsal log. Labelled NOT EVIDENCE |
 | [`docs/outcomes-11155111.jsonl`](docs/outcomes-11155111.jsonl) | Every decision gavel made on that chain, refusals included. Append-only JSON Lines |

scripts/audit.mjs

@@ -22,6 +22,7 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename } from 'node:path';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -118,8 +119,35 @@ function table(list) {
 }
 
 mkdirSync(join(ROOT, 'docs'), { recursive: true });
-writeFileSync(join(ROOT, 'docs', `receipts-${chainId}.json`), JSON.stringify({
-  $comment: 'Generated by scripts/audit.mjs from KeeperHub execution rows. Do not hand-edit — regenerate.',
+const receiptsPath = join(ROOT, 'docs', `receipts-${chainId}.json`);
+
+// KeeperHub's analytics/runs does NOT keep history indefinitely. On 2026-09-09 it
+// returned 2 runs for this org; the 150 rows recorded on 2026-09-06/07 were gone.
+// Nothing in the API says so, and the naive regenerate-in-place this file used to
+// do would have silently replaced a 150-row audit trail with a 2-row one and
+// reported success. The rows are not recoverable from the API afterwards.
+//
+// So a shrinking rewrite is now a REFUSAL, not a write. The evidence itself
+// survives independently of this endpoint -- every row carries a transaction hash
+// and those are on the explorer permanently -- but the file must not be quietly
+// truncated to match whatever the API is willing to remember today.
+let previous = null;
+try { previous = JSON.parse(readFileSync(receiptsPath, 'utf8')); } catch { /* first run */ }
+if (previous && rows.length < (previous.count ?? 0) && !flags.prune) {
+  console.error(`\n  REFUSING TO SHRINK ${basename(receiptsPath)}`);
+  console.error(`  on disk ${previous.count} row(s) · analytics/runs returned ${rows.length}`);
+  console.error(`  KeeperHub does not retain run history indefinitely, so this is expected to`);
+  console.error(`  happen as rows age out — and overwriting would destroy an audit trail the API`);
+  console.error(`  can no longer reproduce. Every row on disk carries a tx hash; verify those on`);
+  console.error(`  the explorer instead.`);
+  console.error(`\n  If the loss is genuinely intended: re-run with --prune\n`);
+  process.exit(1);
+}
+
+writeFileSync(receiptsPath, JSON.stringify({
+  $comment: 'Generated by scripts/audit.mjs from KeeperHub execution rows. Do not hand-edit — regenerate. '
+    + 'A regenerate can only ever ADD rows: analytics/runs ages history out, and audit.mjs refuses to '
+    + 'shrink this file without --prune.',
   chainId, chainName: chain.name, receiptsEligible: chain.receiptsEligible,
   generatedAt: new Date().toISOString(), count: rows.length, rows,
 }, null, 2) + '\n');