cursedbelt-server 4.18.0 → 4.19.0

package/docs/retention.md

@@ -0,0 +1,81 @@
+# Retention — the fleet standard
+
+`cursedbelt-server/retention` is the code; this page is the contract every app that deletes
+old rows is agreeing to. Four apps cited a `docs/retention.md` for two generations and it did
+not exist here until 2026-09-23 (task 324). Where this page and the code disagree, the code
+wins and this page is the bug.
+
+## 1. Retention is OPT-IN, and by CATEGORY — never by table
+
+A resource can be swept only if it declares a `RetentionCategory`
+(`src/server/retention/policy.ts`, `RETENTION_CATEGORIES`). Every category describes one kind
+of data: **a record that exists so a human can find out what happened, and whose loss costs
+nothing but hindsight** — `audit-log`, `event-log`, `run-log`, `transcript`, `metric`, `cache`,
+`replica-mirror`, `queue-result`, `scratch-artifact`, and the one exception, `archived-history`.
+
+Why by category rather than by table:
+
+- **Long-term data is protected by ABSENCE.** There is no category that can describe a note, a
+  setting, a password, a save state, a playlist or a vault entry. "Should this table have a
+  policy?" is answered by whether an honest category exists, not by somebody's judgement on
+  the day — and a new table is safe by default, because it is not swept until it is declared.
+- **The number is the category's, not the app's.** Every deleting category defaults to the
+  owner's two-week standard or shorter. A deleting category that wanted a longer default would
+  be describing data that belongs to the user — the case this vocabulary refuses to express.
+- **The owner, not the app, moves the number.** An app publishes what it owns
+  (`publishRetention`); overrides are read from one file the station edits
+  (`writeRetentionOverride`); both the station's view and every sweep resolve the policy with
+  the same function (`resolveRetentionPolicy`), so the screen can never promise a date the
+  sweeper does not keep.
+
+## 2. `archived-history` is the only category allowed a longer window
+
+It keeps a bounded window on the instance and writes everything older to a verified,
+append-only archive BEFORE a row is deleted. `archivesBeforeDelete` is a property of the
+category: the plain-delete targets in `src/server/retention/target.ts` refuse a declaration
+that carries it, and the archiving target refuses to delete a row it cannot prove it archived.
+
+## 3. Two floors that hold even when a policy is wrong
+
+- `floorItems` — no policy, however mis-set, can empty a resource.
+- `RETENTION_MIN_DAYS` / `RETENTION_MAX_DAYS` bound every override.
+
+## 4. Declaring nothing is a legitimate answer
+
+An audit of destructive actions that writes a handful of rows a month is right to declare no
+category and say so in a comment — a 14-day cutoff must not reach an audit trail of production
+deletions. Opting in is a decision about the data, not a checkbox every table ticks.
+
+## 5. Anything that grows without bound and is NOT sweepable is a design bug
+
+If a resource grows for ever and no category fits it, the answer is not a longer retention —
+it is that the thing should not be accumulating.
+
+## 6. A threshold is tuned against the CORPUS, never against the story
+
+`apps/music/scripts/backup.ts:172-190` records the failure: a refusal keyed on "a catalogue
+with tracks and no organizing work must be a stage database" was written from the story, and
+the live corpus at cutover (5,391 tracks, 0 playlists, 0 tags) would have tripped it nightly on
+a healthy library. Before a retention or refusal number ships, measure it against what the app
+actually holds, and write the measurement beside the number.
+
+## Adopting it
+
+```ts
+import { createRetentionSweeper, createSqliteTableTarget } from "cursedbelt-server/retention";
+
+createRetentionSweeper({
+  app: "myapp",
+  targets: [
+    createSqliteTableTarget({
+      db, table: "events", timeColumn: "at",
+      declaration: { app: "myapp", id: "events", label: "Event log", category: "event-log",
+        unit: "rows", location: "myapp.sqlite · events",
+        consequence: "Who did what, for hindsight. Losing it costs no data." },
+    }),
+  ],
+}).start();
+```
+
+Cite this page from an app as `cursedbelt-server/docs/retention.md` — with the package prefix,
+because a bare `docs/retention.md` is a promise about the citing app's own `docs/`.

package/docs/skipped-tests.md

@@ -0,0 +1,19 @@
+# Skipped tests — what each one is waiting for
+
+`src/skippedTestsAreAnswered.spec.ts` keeps this table honest in both directions:
+every file with a skip site must have a row here, and a row whose file has stopped
+carrying one goes red until it is removed. Inherited from `cursedbelt` at the
+2026-09-15 split (task 148) — rows below are the ones whose files moved here.
+
+| file | waiting for |
+| --- | --- |
+| `src/server/search/pgSearchProvider.pg.test.ts` | 24 | 22 | 2026-09-13 |
+| `src/server/storage/transcode.integration.spec.ts` | 7 | 5 | 2026-09-13 |
+| `src/server/storage/binaryServerProcessing.integration.spec.ts` | 4 | 2 | 2026-09-13 |
+| `src/server/storage/chunked.integration.spec.ts` | 3 | 1 | 2026-09-13 |
+| `src/server/media-bun/image.spec.ts` | the optional `sharp` peer | no |
+| `src/server/media-bun/video.spec.ts` | `ffmpeg` + `ffprobe` on `PATH` | no |
+| `src/server/storage/imageThumbnail.spec.ts` | `ffmpeg` on `PATH` | no |
+| `src/server/storage/videoProcessor.posterOnly.spec.ts` | `ffmpeg` on `PATH` | no |
+| `src/server/storage/files/adapter.photo.display.spec.ts` | `ffmpeg` on `PATH` | no |
+| `src/server/storage/fileUploadClient-chunked.integration.spec.ts` | a real `binary-server` checkout — set `BINARY_SERVER_DIR`. No default by design: a published package must not go looking in one machine's directory layout, and `binary-server` has not been re-homed into this generation, so it skips on every host today. Moved here from `cursedbelt` at the 2026-09-15 split, with the storage internals it drives. |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.18.0",
+	"version": "4.19.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -28,7 +28,8 @@
 	},
 	"files": [
 		"dist",
-		"src"
+		"src",
+		"docs"
 	],
 	"exports": {
 		".": {
@@ -67,6 +68,12 @@
 			"source": "./src/server/storage/binaryStore.ts",
 			"import": "./dist/server/storage/binaryStore.js"
 		},
+		"./binary-store/upload-session": {
+			"types": "./dist/server/storage/uploadSession.d.ts",
+			"bun": "./src/server/storage/uploadSession.ts",
+			"source": "./src/server/storage/uploadSession.ts",
+			"import": "./dist/server/storage/uploadSession.js"
+		},
 		"./binary-store/testing": {
 			"types": "./dist/server/storage/binaryStoreFake.d.ts",
 			"bun": "./src/server/storage/binaryStoreFake.ts",
@@ -91,12 +98,6 @@
 			"source": "./src/server/d1/localBackup.ts",
 			"import": "./dist/server/_bunOnly.js"
 		},
-		"./d1/kysely": {
-			"types": "./dist/server/d1/kysely.d.ts",
-			"bun": "./src/server/d1/kysely.ts",
-			"source": "./src/server/d1/kysely.ts",
-			"import": "./dist/server/d1/kysely.js"
-		},
 		"./d1/testing": {
 			"types": "./dist/server/d1/fakeD1.d.ts",
 			"bun": "./src/server/d1/fakeD1.ts",
@@ -109,6 +110,12 @@
 			"source": "./src/server/dropzone/index.ts",
 			"import": "./dist/server/dropzone/index.js"
 		},
+		"./engagement": {
+			"types": "./dist/server/engagement/index.d.ts",
+			"bun": "./src/server/engagement/index.ts",
+			"source": "./src/server/engagement/index.ts",
+			"import": "./dist/server/_bunOnly.js"
+		},
 		"./errors": {
 			"types": "./dist/server/errors.d.ts",
 			"bun": "./src/server/errors.ts",
@@ -157,6 +164,12 @@
 			"source": "./src/server/auth/loginThrottle.ts",
 			"import": "./dist/server/auth/loginThrottle.js"
 		},
+		"./maps-budget": {
+			"types": "./dist/server/maps-budget/mapsBudget.d.ts",
+			"bun": "./src/server/maps-budget/mapsBudget.ts",
+			"source": "./src/server/maps-budget/mapsBudget.ts",
+			"import": "./dist/server/maps-budget/mapsBudget.js"
+		},
 		"./master-lock": {
 			"types": "./dist/server/master-lock/index.d.ts",
 			"bun": "./src/server/master-lock/index.ts",
@@ -187,6 +200,12 @@
 			"source": "./src/server/net/outboundGuard.ts",
 			"import": "./dist/server/net/outboundGuard.js"
 		},
+		"./password": {
+			"types": "./dist/server/auth/passwordCost.d.ts",
+			"bun": "./src/server/auth/passwordCost.ts",
+			"source": "./src/server/auth/passwordCost.ts",
+			"import": "./dist/server/_bunOnly.js"
+		},
 		"./notifications": {
 			"types": "./dist/server/notifications/index.d.ts",
 			"bun": "./src/server/notifications/index.ts",
@@ -205,6 +224,18 @@
 			"source": "./src/server/retention/index.ts",
 			"import": "./dist/server/retention/index.js"
 		},
+		"./satellite-config": {
+			"types": "./dist/server/satellite/config.d.ts",
+			"bun": "./src/server/satellite/config.ts",
+			"source": "./src/server/satellite/config.ts",
+			"import": "./dist/server/_bunOnly.js"
+		},
+		"./satellite-door": {
+			"types": "./dist/server/satellite/door.d.ts",
+			"bun": "./src/server/satellite/door.ts",
+			"source": "./src/server/satellite/door.ts",
+			"import": "./dist/server/satellite/door.js"
+		},
 		"./search": {
 			"types": "./dist/server/search/index.d.ts",
 			"bun": "./src/server/search/index.ts",
@@ -229,6 +260,12 @@
 			"source": "./src/server/storage/index.ts",
 			"import": "./dist/server/storage/index.js"
 		},
+		"./storage/derivatives": {
+			"types": "./dist/server/storage/derivatives.d.ts",
+			"bun": "./src/server/storage/derivatives.ts",
+			"source": "./src/server/storage/derivatives.ts",
+			"import": "./dist/server/storage/derivatives.js"
+		},
 		"./storage/types": {
 			"types": "./dist/server/storage/types.d.ts",
 			"bun": "./src/server/storage/types.ts",
@@ -250,6 +287,7 @@
 	},
 	"dependencies": {
 		"cursedbelt-core": "^2.1.1",
+		"cursedops": "^0.4.0",
 		"cwip": "^4.6.0",
 		"jose": "^6.2.3"
 	},
@@ -290,7 +328,6 @@
 		"@types/bun": "^1.3.14",
 		"@types/node": "^24",
 		"cursedbelt": "^4.5.0",
-		"cursedops": "^0.2.7",
 		"hono": "4.12.28",
 		"kysely": "^0.28.17",
 		"kysely-bun-sqlite": "^0.4.0",

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -114,9 +114,8 @@ const MAY_DRAG: Record<string, readonly string[]> = {
 	// for that; an app importing `cursedbelt-server/d1` is not, and that is the distinction
 	// this spec protects.
 	'.': ['kysely', 'kysely-bun-sqlite', 'otplib', 'plainjob'],
-	// `createD1Kysely` IS the kysely adapter. Split out of `./d1` on 2026-09-18 precisely so
-	// the seam itself stops paying for it — see the header.
-	'./d1/kysely': ['kysely'],
+	// `./d1/kysely` (`createD1Kysely`) was here until 4.19.0, when it was removed: no file in
+	// the generation had ever imported it (task 472's census), so the allowance went with it.
 	// The job queue is plainjob. Nothing else here is.
 	'./jobs': ['plainjob'],
 };
@@ -144,6 +143,9 @@ const MAY_NEED_BUN: Record<string, readonly string[]> = {
 	'./guard/revocations': ['bun:sqlite'],
 	// `./sqlite` is the bun:sqlite tier. Naming it is the point of the subpath.
 	'./sqlite': ['bun:sqlite'],
+	// The engagement store IS `engagement.sqlite` on the Mac (4.19.0, task 280) — the recorder
+	// runs where the app's own database is. A Worker app records nothing until it has a D1 store.
+	'./engagement': ['bun:sqlite'],
 };
 
 const OPTIONAL_PEERS = new Set(

package/src/leafSubpathsImportNothing.spec.ts

@@ -161,6 +161,50 @@ const LEAVES = [
      */
     evaluates: 'createGoogleTokenMinter',
   },
+  {
+    subpath: './maps-budget',
+    /**
+     * The Google Maps spend ceiling (4.19.0, task 345) — copied into `family` and `station`
+     * under two different file names. The store is injected, so the module needs nothing.
+     */
+    evaluates: 'createMapsBudget',
+  },
+  {
+    subpath: './binary-store/upload-session',
+    /**
+     * The direct-upload mint (4.19.0, task 343). Its one import is `import type` of the
+     * `BinaryStore` interface, which is erased — so it keeps `./binary-store`'s promise.
+     */
+    evaluates: 'createUploadSession',
+  },
+  {
+    subpath: './storage/derivatives',
+    /**
+     * How an app READS binary-server's derivatives (4.19.0, task 344). Collections serves it
+     * from a Worker, so it may reach nothing at all — except the key contract it re-exports,
+     * which is itself import-free and is copied beside it rather than excused.
+     */
+    evaluates: 'resolveVideoPlayback',
+    siblings: ['src/server/storage/videoDerivativeKeys.ts'],
+  },
+  {
+    subpath: './satellite-door',
+    /**
+     * The pure half of the satellite config contract (4.19.0, task 281) — what a Worker's door
+     * imports INSTEAD of the Node half. `music`'s Worker dragged `node:fs` and the whole data-dir
+     * chain into its bundle to reach two of these functions; this leaf is why it no longer must.
+     */
+    evaluates: 'allowedEmailsFor',
+  },
+  {
+    subpath: './password',
+    /**
+     * The argon2id cost decision (4.19.0, task 321). It shares its test-runtime predicate with
+     * `./satellite-door` rather than copying it, and that sibling is itself import-free.
+     */
+    evaluates: 'argon2Cost',
+    siblings: ['src/server/satellite/door.ts'],
+  },
 ] as const;
 
 /**
@@ -269,6 +313,11 @@ const run = async (): Promise<Record<string, Outcome>> => {
     // copy made through it can land in a mock the spawned child cannot see. Same trap as
     // publishShape.spec.ts.
     await Bun.write(`${pkgDir}/${source}`, Bun.file(`${REPO}/${source}`));
+    // A leaf that re-exports an import-free sibling ships with exactly that sibling and no
+    // other — so the sibling is held to the same promise rather than excused from it.
+    for (const sibling of 'siblings' in leaf ? leaf.siblings : []) {
+      await Bun.write(`${pkgDir}/${sibling}`, Bun.file(`${REPO}/${sibling}`));
+    }
     targets.push({ name: leaf.subpath, specifier: `${pkg.name}/${leaf.subpath.slice(2)}` });
   }
   await Bun.write(`${pkgDir}/${CONTROL}`, Bun.file(`${REPO}/${CONTROL}`));

package/src/server/activity/index.ts

@@ -10,7 +10,8 @@
  *
  * ── Retention ───────────────────────────────────────────────────────────────
  * This package never deletes an event. An app whose stream is high-volume opts
- * into the fleet standard (`cursedbelt-server/retention`, in this package) by
+ * into the fleet standard (`cursedbelt-server/retention`; the contract is
+ * `docs/retention.md` in this package, and this stream's own is `docs/activity.md`) by
  * declaring the table, which puts the number under the owner's control in the
  * station rather than in a constant here:
  *

package/src/server/auth/passwordCost.spec.ts

@@ -0,0 +1,42 @@
+/**
+ * The KDF cost decision — and the one direction it may never move by accident.
+ *
+ * 🔴 The failure worth a test is a PRODUCTION process paying test cost: a weakened argon2id on
+ * the owner's real password hash, silently. So the production path is asserted against an env
+ * with every marker absent, not merely "whatever this runner has".
+ */
+import { describe, expect, it } from 'bun:test';
+import { TEST_RUNTIME_ENV_KEYS } from '../satellite/door.js';
+import { argon2Cost, hashSecret, PRODUCTION_ARGON2, TEST_ARGON2, verifySecret } from './passwordCost.js';
+
+describe('argon2Cost', () => {
+  it('🔴 a process with NO test marker pays production cost', () => {
+    expect(argon2Cost({ NODE_ENV: 'production' })).toBe(PRODUCTION_ARGON2);
+    expect(argon2Cost({})).toBe(PRODUCTION_ARGON2);
+  });
+
+  it('each marker the data-dir guard trusts lowers the cost — and nothing else does', () => {
+    expect(argon2Cost({ NODE_ENV: 'test' })).toBe(TEST_ARGON2);
+    expect(argon2Cost({ BUN_TEST: '1' })).toBe(TEST_ARGON2);
+    expect(argon2Cost({ SATELLITE_TEST_RUNTIME: '1' })).toBe(TEST_ARGON2);
+    expect(argon2Cost({ NODE_ENV: 'development' })).toBe(PRODUCTION_ARGON2);
+    expect(TEST_RUNTIME_ENV_KEYS).toEqual(['NODE_ENV', 'BUN_TEST', 'SATELLITE_TEST_RUNTIME']);
+  });
+
+  it('never changes the ALGORITHM, so a hash made under either cost verifies under either', async () => {
+    expect(TEST_ARGON2.algorithm).toBe('argon2id');
+    expect(PRODUCTION_ARGON2.algorithm).toBe('argon2id');
+    const cheap = await Bun.password.hash('correct horse', TEST_ARGON2);
+    expect(await verifySecret('correct horse', cheap)).toBe(true);
+    expect(await verifySecret('wrong horse', cheap)).toBe(false);
+  });
+});
+
+describe('hashSecret / verifySecret', () => {
+  it('round-trips, and a malformed stored hash is `false` — never a throw', async () => {
+    const hash = await hashSecret('s3cret-enough');
+    expect(hash.startsWith('$argon2id$')).toBe(true);
+    expect(await verifySecret('s3cret-enough', hash)).toBe(true);
+    expect(await verifySecret('s3cret-enough', 'not-a-phc-string')).toBe(false);
+  });
+});

package/src/server/auth/passwordCost.ts

@@ -0,0 +1,87 @@
+/**
+ * HOW EXPENSIVE ARGON2ID SHOULD BE IN THIS PROCESS — production's cost, unless a test
+ * runner is in charge.
+ *
+ * ## The measurement (2026-09-09)
+ *
+ * Argon2id is slow ON PURPOSE: one hash costs ~66 ms on this Mac, and that slowness IS
+ * the security property. It is also the wrong price to pay six hundred times in a unit
+ * test whose assertion is *"a wrong password is refused"* — that asserts the comparison,
+ * never the cost of the KDF.
+ *
+ * `apps/auth`'s own suite, measured both ways with nothing else changed:
+ *
+ *     production cost   52.85 s
+ *     test cost          7.32 s
+ *
+ * Eighty-six per cent of what was, that morning, the largest single workspace in
+ * `verify:scoped` — paid by every agent on every branch touching auth or any shared
+ * package, and again on every union gate.
+ *
+ * ## Why this is safe to key on the test runtime, stated plainly
+ *
+ * A weakened KDF is the most dangerous thing this module could do, so the argument has
+ * to be better than "the flag is only set in tests".
+ *
+ * `TEST_RUNTIME_ENV_KEYS` is the fleet's existing answer to *"is a test runner in
+ * charge"*, and `app-data` **already refuses to open the owner's real database** when it
+ * is true. A process carrying one of these markers therefore has no production data to
+ * write a weak hash into — it is the same claim, load-bearing in the same direction,
+ * decided in one place. If that guarantee ever weakens, it weakens for the database
+ * first, which is the louder failure.
+ *
+ * The ALGORITHM never changes. Only `memoryCost`/`timeCost` move, argon2 encodes its own
+ * parameters into the hash, and verification is therefore identical — so a stored hash
+ * made under either cost verifies under either cost.
+ *
+ * ## `cursedbelt-server/password`, since 4.19.0 (task 321)
+
+It was `src/kit/passwordCost.ts` in `auth`, `collections`, `patterns` and `vault` — four copies of
+a security-relevant cost decision, one of them (`vault`) already carrying a `verifySecret` the
+others lacked. The test-runtime rule it keys on is `./satellite-door`'s `isTestRuntime`, the same
+predicate that refuses a test the owner's real database, so the two can never disagree about
+whether a runner is in charge. It is not in `cursedauth` because that package has no
+dependencies and this decision must share its predicate, not copy it.
+
+## Why it lives in one place and not in each app
+ *
+ * Five call sites hashed at production cost when this was written — `apps/auth`,
+ * `apps/collections` (×2), `apps/patterns`, `apps/vault` — and a per-app copy of a
+ * security-relevant cost decision is how four of them end up agreeing and the fifth does
+ * not. One module, one test, one place to read.
+ */
+import { isTestRuntime } from "../satellite/door.js";
+
+/** Production: the runtime's own argon2id defaults, with nothing pinned by hand. */
+export const PRODUCTION_ARGON2: Bun.Password.Argon2Algorithm = { algorithm: "argon2id" };
+
+/** The floor argon2id accepts — free, and still argon2id. */
+export const TEST_ARGON2: Bun.Password.Argon2Algorithm = {
+	algorithm: "argon2id",
+	memoryCost: 8,
+	timeCost: 1,
+};
+
+/**
+ * Which cost this process should pay. Takes `env` explicitly so the failure path is
+ * drivable: a check that can only be run under the runner it is deciding about is a
+ * check nobody can prove.
+ */
+export function argon2Cost(env: NodeJS.ProcessEnv = process.env): Bun.Password.Argon2Algorithm {
+	return isTestRuntime(env) ? TEST_ARGON2 : PRODUCTION_ARGON2;
+}
+
+/**
+ * Hash a secret at the right cost for this process. The one call every app should use;
+ * a bare `Bun.password.hash(x, "argon2id")` pays production's cost in every test.
+ */
+export const hashSecret = (secret: string): Promise<string> =>
+	Bun.password.hash(secret, argon2Cost());
+
+/**
+ * Verify a secret against a stored argon2id PHC string — `false`, never a throw, on anything
+ * malformed. `Bun.password` on the Mac; on the Worker the same global is `worker/password.ts`'s
+ * pure-JS shim, which reproduces Bun's hashes byte for byte, so every stored verifier keeps working.
+ */
+export const verifySecret = (secret: string, hash: string): Promise<boolean> =>
+	Bun.password.verify(secret, hash).catch(() => false);

package/src/server/bench/index.ts

@@ -80,3 +80,16 @@ export {
   type RouteCpuStats,
 } from './recorder.js';
 export { BENCH_ORIGIN, type BenchCase, runCpuBench, type RunCpuBenchOpts } from './runBench.js';
+export {
+  parseTailLines,
+  type RecordTailTracesOpts,
+  recordTailTraces,
+  routeMatcher,
+  TAIL_CPU_SOURCE,
+  type TailRecordResult,
+  type TailTraceLike,
+  type TailTrafficRate,
+  tailCpuClock,
+  tailTrafficRate,
+  UNMATCHED_ROUTE,
+} from './tail.js';

package/src/server/bench/tail.spec.ts

@@ -0,0 +1,126 @@
+/**
+ * The tail reading — proven in both directions against the SAME assertion the local proxy uses,
+ * because a real reader that could not go red would be worse than the proxy it replaces.
+ */
+import { describe, expect, it } from 'bun:test';
+import { checkCpuBudgets } from './assert.js';
+import { createCpuRecorder } from './recorder.js';
+import {
+  parseTailLines,
+  recordTailTraces,
+  routeMatcher,
+  tailCpuClock,
+  tailTrafficRate,
+  type TailTraceLike,
+  UNMATCHED_ROUTE,
+} from './tail.js';
+import { processCpuClock } from './cpuClock.js';
+
+const BUDGETS = {
+  routes: {
+    'GET /api/items/:id': 5,
+    'GET /api/items/recent': 2,
+    'POST /api/upload': { exempt: true as const, reason: 'hashing is the work' },
+    '/healthz': 1,
+  },
+};
+
+const trace = (method: string, path: string, cpuTime: number | undefined, at = 0): TailTraceLike => ({
+  cpuTime,
+  eventTimestamp: at,
+  scriptName: 'collections',
+  event: { request: { method, url: `https://collections.example${path}` } },
+});
+
+const many = (n: number, make: (i: number) => TailTraceLike): TailTraceLike[] => Array.from({ length: n }, (_, i) => make(i));
+
+describe('routeMatcher', () => {
+  it('the most literal pattern wins, and the method must agree', () => {
+    const match = routeMatcher(Object.keys(BUDGETS.routes));
+    expect(match('GET', '/api/items/recent')).toBe('/api/items/recent');
+    expect(match('GET', '/api/items/abc123')).toBe('/api/items/:id');
+    expect(match('POST', '/api/items/abc123')).toBeNull();
+    expect(match('HEAD', '/healthz')).toBe('/healthz');
+    expect(match('GET', '/api/items/a/b')).toBeNull();
+  });
+});
+
+describe('recordTailTraces', () => {
+  it('stamps the report proxy:false with the tail as its source', () => {
+    const recorder = createCpuRecorder({ clock: tailCpuClock(), config: BUDGETS });
+    recordTailTraces(recorder, many(30, (i) => trace('GET', `/api/items/${i}`, 1 + (i % 3))));
+    const report = recorder.report();
+    expect(report.proxy).toBe(false);
+    expect(report.source).toBe('tail-worker cpuTime');
+    expect(report.routes.map((r) => r.key)).toEqual(['GET /api/items/:id']);
+  });
+
+  it('🔴 refuses a PROXY recorder — real numbers may not be labelled a proxy, nor the reverse', () => {
+    const recorder = createCpuRecorder({ clock: processCpuClock(), config: BUDGETS });
+    expect(() => recordTailTraces(recorder, [])).toThrow(/is a PROXY/);
+  });
+
+  it('🔴 a trace with no cpuTime is skipped and counted — never recorded as a zero', () => {
+    const recorder = createCpuRecorder({ clock: tailCpuClock(), config: BUDGETS });
+    const result = recordTailTraces(recorder, [
+      trace('GET', '/healthz', undefined),
+      { cpuTime: 3, event: null },
+      trace('GET', '/nope/1', 2),
+    ]);
+    expect(result).toMatchObject({ recorded: 1, noCpuTime: 1, notFetch: 1, unmatched: 1, unmatchedPaths: ['GET /nope/1'] });
+    expect(recorder.report().routes[0]?.route).toBe(UNMATCHED_ROUTE);
+  });
+
+  it('a tail recorder mounted as middleware fails loudly instead of measuring nothing', () => {
+    expect(() => tailCpuClock().start()).toThrow(/FED by recordTailTraces/);
+  });
+});
+
+describe('the SAME assertion, fed by the tail', () => {
+  it('passes a window whose readings move and sit under budget', () => {
+    const recorder = createCpuRecorder({ clock: tailCpuClock(), config: BUDGETS });
+    recordTailTraces(recorder, many(40, (i) => trace('GET', `/api/items/${i}`, i % 4)));
+    expect(checkCpuBudgets(recorder.report(), { requireDeclared: true }).filter((v) => v.fails)).toEqual([]);
+  });
+
+  it('🔴 goes RED on a route over its budget, and names it', () => {
+    const recorder = createCpuRecorder({ clock: tailCpuClock(), config: BUDGETS });
+    recordTailTraces(recorder, many(40, (i) => trace('GET', '/api/items/recent', 3 + (i % 2))));
+    const failing = checkCpuBudgets(recorder.report(), { requireDeclared: true }).filter((v) => v.fails);
+    expect(failing.map((v) => v.kind)).toEqual(['over-budget']);
+    expect(failing[0]?.key).toBe('GET /api/items/recent');
+  });
+
+  it('🔴 goes RED on traffic no declared route covers, under requireDeclared', () => {
+    const recorder = createCpuRecorder({ clock: tailCpuClock(), config: BUDGETS });
+    recordTailTraces(recorder, many(40, (i) => trace('GET', `/undeclared/${i}`, 1 + (i % 2))));
+    const kinds = checkCpuBudgets(recorder.report(), { requireDeclared: true }).filter((v) => v.fails).map((v) => v.kind);
+    expect(kinds).toContain('undeclared');
+  });
+
+  it('🔴 a window where EVERY reading is 0 is still refused as degenerate', () => {
+    const recorder = createCpuRecorder({ clock: tailCpuClock(), config: BUDGETS });
+    recordTailTraces(recorder, many(40, (i) => trace('GET', `/api/items/${i}`, 0)));
+    expect(checkCpuBudgets(recorder.report()).map((v) => v.kind)).toEqual(['degenerate']);
+  });
+});
+
+describe('parseTailLines and tailTrafficRate', () => {
+  it('reads `wrangler tail --format json`, skipping its banner and any partial line', () => {
+    const text = [
+      'Successfully created tail, expires at …',
+      JSON.stringify(trace('GET', '/healthz', 1, 1_000)),
+      '{"cpuTime": 2, "event": {"request": {"url": "https://x/healthz", "me',
+      '',
+      JSON.stringify(trace('GET', '/healthz', 2, 2_000)),
+    ].join('\n');
+    expect(parseTailLines(text).map((t) => t.cpuTime)).toEqual([1, 2]);
+  });
+
+  it('scales a window to requests/day — and refuses to scale one shorter than an hour', () => {
+    const hour = 3_600_000;
+    const two = [trace('GET', '/healthz', 1, 0), trace('GET', '/healthz', 1, 2 * hour), { cpuTime: 5 }];
+    expect(tailTrafficRate(two).requestsPerDay).toBe(24);
+    expect(Number.isNaN(tailTrafficRate([trace('GET', '/a', 1, 0), trace('GET', '/a', 1, 60_000)]).requestsPerDay)).toBe(true);
+  });
+});