cursedbelt-server 4.18.1 → 4.19.1

package/docs/engagement.md

@@ -0,0 +1,47 @@
+# Engagement — product analytics, and which side of the gate a receiver mounts on
+
+`cursedbelt-server/engagement` is the server half (recorder, store, policy, summary); the beacon
+is the browser half in the design system's tier. Four apps copied `src/kit/engagement/` and cited
+a feedback-kit standard for its mount-order rule; neither existed here until 2026-09-23 (tasks
+280 and 324). This page is that rule and the privacy promise it serves.
+
+## 1. The privacy promise is three structural rules (`src/server/engagement/policy.ts`)
+
+1. **A place is an allowlisted id, never a path.** The allowlist is the app's own
+   `routes.manifest.json`; anything a client claims that is not on it records as `other`.
+2. **Some apps are excluded by name, in the library** (`ENGAGEMENT_EXCLUDED_APPS` — the vault).
+   No environment variable can turn an excluded app back on.
+3. **Counts and clocks only.** One row per (user, place, UTC day); there is no event log, so a
+   timeline of a household's private apps cannot be reconstructed from the store.
+
+The user key comes ONLY from the app's `resolveUser(c)` — never from the request body — so the
+beacon cannot be used to write somebody else's history.
+
+## 2. Mount order — the decision four apps had to agree on
+
+| receiver | its credential | mounts |
+|---|---|---|
+| the engagement recorder (`POST <mount>/view`) | none of its own — it needs the SESSION's user | **AFTER** the session gate |
+| a sync receiver (a feed another machine pushes into) | its own bearer | **BEFORE** the session gate |
+
+The two are mirror images for one reason: **a door mounts on the side of the gate that supplies
+the identity it trusts.** The recorder trusts the session, so the gate must have run and put the
+user where `resolveUser` reads it; mounted before, every view is a 401 and nothing records. A
+sync receiver trusts its bearer and has no session at all; mounted after, the gate refuses the
+machine before its own check can run, and the feed goes silently dark.
+
+## 3. What the app keeps
+
+Its `routes.manifest.json` and the test that proves it parses. `engagementPlacesFor` returns `[]`
+for anything it cannot read — deliberately silent, so telemetry never takes a boot down — which
+degrades the allowlist to nothing while the board keeps rendering. Only the app can prove its own
+manifest parses (`apps/roms/routes.manifest.test.ts` is the pattern).
+
+## 4. Where the data lives
+
+`engagement.sqlite` beside the app's own database (`readEngagementEnv` resolves it with
+`cursedbelt-server/satellite-config`'s `resolveAppDataDir`), or nowhere: a test runner, an
+excluded app, `SATELLITE_ENGAGEMENT=0` or an unresolvable data directory each turn recording OFF
+and say why, and the app still boots.
+
+Cite this page from an app as `cursedbelt-server/docs/engagement.md`.

package/docs/notifications.md

@@ -0,0 +1,43 @@
+# Notifications — the bell and inbox contract
+
+`cursedbelt-server/notifications` (routes, SSE hub, migration) over the engine in
+`cwip/notifications` is the code, and `cursedbelt/react/notifications` is the client. This page
+is the contract a producer in any app is agreeing to. Written 2026-09-23 (task 324); `family`
+cited it four times before it existed.
+
+## 1. A notification is a row before it is an event
+
+Delivery (SSE) is a cache of who is listening; the poll transport is the backstop and is not
+optional. Nothing is lost to a closed laptop.
+
+## 2. Coalesce what RECURS — never coalesce what is individually ACTIONABLE
+
+A `groupKey` folds repeats into one row with a count, and it is enforced by the database (a
+partial unique index on `(user_id, group_key) WHERE group_key IS NOT NULL AND done = 0`), not
+by a debounce, so it holds under concurrent producers.
+
+The rule for choosing one:
+
+- **Give it a `groupKey`** when the twentieth instance tells the reader nothing the first did:
+  "a sync failed", "new comments on this thread", "a backup is overdue". One row, a count, one
+  thing to go and look at.
+- **Give it NO `groupKey`** when each instance is its own thing to go and look at: two
+  relatives shared with the same person are two people to open (`apps/family/src/server/shares.ts`,
+  `shareNotificationDraft`), two uploads that need review are two reviews. Coalescing those
+  hides work behind a number.
+
+When in doubt, do not coalesce: an extra row costs a glance, a swallowed one costs the thing
+the notification was for.
+
+## 3. The routes address the session's user and nothing else
+
+There is no route that notifies somebody else. Producing is server-side code calling
+`center.notify*`; the mounted routes list, read and mark the CURRENT user's rows.
+
+## 4. A notification is written once and read later — so it names nothing the reader may not see
+
+It is not filtered by the reader's scope at read time and cannot be. Put what is safe for the
+recipient in the title and body, and let the LINK carry them to the thing, where every normal
+read filter applies (`family`'s share notification does not name the relative for this reason).
+
+Cite this page from an app as `cursedbelt-server/docs/notifications.md`.

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.1",
+	"version": "4.19.1",
 	"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,10 @@
 	},
 	"files": [
 		"dist",
-		"src"
+		"src",
+		"docs",
+		"README.md",
+		"!src/server/typetests"
 	],
 	"exports": {
 		".": {
@@ -67,6 +70,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 +100,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 +112,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 +166,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 +202,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 +226,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 +262,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 +289,7 @@
 	},
 	"dependencies": {
 		"cursedbelt-core": "^2.1.1",
+		"cursedops": "^0.5.2",
 		"cwip": "^4.6.0",
 		"jose": "^6.2.3"
 	},
@@ -290,7 +330,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

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'bun:test';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import pkg from '../package.json';
+import { MAY_DRAG, MAY_NEED_BUN } from './subpathReach.js';
 
 /**
  * A public subpath must not STATICALLY drag anything its consumers cannot have — an
@@ -99,53 +100,6 @@ import pkg from '../package.json';
 
 const REPO = fileURLToPath(new URL('..', import.meta.url));
 
-/**
- * The subpaths whose whole PURPOSE is the optional peer they pull, mapped to what they are
- * allowed to pull and why. An entry here is a promise that the peer is the point of the
- * subpath — not a place to park a new drag.
- *
- * 🔴 Measured 2026-09-18: these three are the ONLY subpaths in the map that reach an
- * optional peer. Everything else is clean, which is what makes this list an allowlist
- * rather than a baseline — it can only shrink.
- */
-const MAY_DRAG: Record<string, readonly string[]> = {
-	// The whole-package barrel. It exists to re-export everything, so it necessarily reaches
-	// what the specific subpaths reach. An app importing `cursedbelt-server` whole is asking
-	// 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'],
-	// The job queue is plainjob. Nothing else here is.
-	'./jobs': ['plainjob'],
-};
-
-/**
- * The subpaths whose whole PURPOSE is a bun-specific runtime, mapped to the builtins they
- * are allowed to reach. Everything NOT listed here must be importable on `workerd`, which
- * is the property the D1 seam exists to deliver.
- *
- * 🔴 Measured 2026-09-18 after the `./d1/backup-local` split: these five are the ONLY
- * subpaths in the map that reach a bun builtin at all. Like {@link MAY_DRAG} it is an
- * allowlist, not a baseline — it can only shrink, and an entry that stops being true is a
- * failure rather than a tidy-up.
- */
-const MAY_NEED_BUN: Record<string, readonly string[]> = {
-	// The whole-package barrel — it re-exports everything, including the Mac-hosted halves.
-	// An app importing `cursedbelt-server` whole is a Bun server by construction; an app
-	// importing `cursedbelt-server/d1` is not, and that is the distinction this protects.
-	'.': ['bun:sqlite'],
-	// The local backup IS `VACUUM INTO` against a live `bun:sqlite` handle. Split out of
-	// `./d1` on 2026-09-18 precisely so the seam itself stops paying for it — see the header.
-	'./d1/backup-local': ['bun:sqlite'],
-	// The guard's revocation store is a `bun:sqlite` table, and `./guard` mounts it.
-	'./guard': ['bun:sqlite'],
-	'./guard/revocations': ['bun:sqlite'],
-	// `./sqlite` is the bun:sqlite tier. Naming it is the point of the subpath.
-	'./sqlite': ['bun:sqlite'],
-};
-
 const OPTIONAL_PEERS = new Set(
 	Object.entries(
 		(pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> }).peerDependenciesMeta ?? {},

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/readmeInstallTable.spec.ts

@@ -0,0 +1,48 @@
+/**
+ * README.md's "What you install" table is what an importing app reads (task 104) — so it is held
+ * to the same data the bundler check proves (`subpathReach.ts`), row for row, in both directions.
+ */
+import { describe, expect, it } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { MAY_DRAG, MAY_NEED_BUN } from './subpathReach.js';
+
+const README = readFileSync(fileURLToPath(new URL('../README.md', import.meta.url)), 'utf8');
+
+/** `| \`./x\` | \`a\`, \`b\` | — |` → { './x': { peers: [a, b], bun: [] } } */
+function tableRows(): Map<string, { peers: string[]; bun: string[] }> {
+  const section = README.split('## What you install')[1]?.split('\n## ')[0] ?? '';
+  const rows = new Map<string, { peers: string[]; bun: string[] }>();
+  for (const line of section.split('\n')) {
+    const cells = line.split('|').map((c) => c.trim());
+    const subpath = /^`(\.[^`]*)`$/.exec(cells[1] ?? '')?.[1];
+    if (!subpath) continue;
+    const named = (cell: string | undefined) => [...(cell ?? '').matchAll(/`([^`]+)`/g)].map((m) => m[1] as string).sort();
+    rows.set(subpath, { peers: named(cells[2]), bun: named(cells[3]) });
+  }
+  return rows;
+}
+
+describe('README install table', () => {
+  const rows = tableRows();
+  const expected = new Set([...Object.keys(MAY_DRAG), ...Object.keys(MAY_NEED_BUN)]);
+
+  it('has a row for every subpath that reaches an optional peer or a bun builtin — and no other', () => {
+    expect(rows.size).toBeGreaterThan(0);
+    expect([...rows.keys()].sort()).toEqual([...expected].sort());
+  });
+
+  it('names exactly what each subpath reaches', () => {
+    for (const subpath of expected) {
+      expect({ subpath, ...rows.get(subpath) }).toEqual({
+        subpath,
+        peers: [...(MAY_DRAG[subpath] ?? [])].sort(),
+        bun: [...(MAY_NEED_BUN[subpath] ?? [])].sort(),
+      });
+    }
+  });
+
+  it('warns that the root export is a barrel', () => {
+    expect(README).toContain('The root export is a BARREL');
+  });
+});

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';