cursedbelt-server 4.19.0 → 4.19.1

package/README.md

@@ -0,0 +1,61 @@
+# cursedbelt-server
+
+The server tier of the cursedbelt split: Hono on Bun, the D1 seam a Worker crosses, the
+binary-server client, the guard, and the fleet standards (retention, activity, notifications,
+engagement). `cursedbelt-core` is below it, the React design system `cursedbelt` above it.
+
+```sh
+bun add cursedbelt-server
+```
+
+## 🔴 The root export is a BARREL — import the leaf
+
+`import … from "cursedbelt-server"` re-exports everything, so it reaches every optional peer and
+`bun:sqlite` at once (the table below). An app that wants one function pays for all of them, and
+on a Worker `wrangler deploy` fails to bundle it. Import the subpath that owns the symbol —
+`cursedbelt-server/login-throttle`, `cursedbelt-server/binary-store`, `cursedbelt-server/d1` —
+never the root. `package.json` `exports` is the list of subpaths.
+
+Why this stays prose: which symbol an app WANTS is decided in the app, and a repo's gate proves
+that repo — so the barrel-importer grep belongs to the generation's tools, not to this package.
+
+## What you install
+
+Most subpaths need nothing beyond `hono` (and `zod` where they validate). These are the only
+ones that statically reach an OPTIONAL peer, or a bun builtin a Worker does not have. The table
+is checked: `src/readmeInstallTable.spec.ts` fails when it disagrees with `src/subpathReach.ts`,
+and `src/barrelsReachNoOptionalPeer.spec.ts` fails when that disagrees with what a bundler
+actually keeps.
+
+| subpath | optional peers it imports | bun builtins it needs |
+|---|---|---|
+| `.` | `kysely`, `kysely-bun-sqlite`, `otplib`, `plainjob` | `bun:sqlite` |
+| `./jobs` | `plainjob` | — |
+| `./d1/backup-local` | — | `bun:sqlite` |
+| `./guard` | — | `bun:sqlite` |
+| `./guard/revocations` | — | `bun:sqlite` |
+| `./sqlite` | — | `bun:sqlite` |
+| `./engagement` | — | `bun:sqlite` |
+
+`sharp` and `@node-rs/argon2` are loaded lazily (`await import()`), so a missing one breaks only
+the feature that asks for it, not the build.
+
+## 🔴 `Bun.serve`'s `websocket` selects an OVERLOAD
+
+It is not an optional field. An options object whose `websocket` may be `undefined` — a
+conditional value or a conditional spread — matches no overload, and TypeScript reports an error
+about the whole options object rather than the one field. Use `serveBun(app, { websocket })`,
+which takes it as a genuinely optional field and makes the two concrete calls itself.
+`src/server/serveBunOverload.spec.ts` runs `tsc` on the trap and goes red when bun's types change.
+
+## Standards
+
+`docs/retention.md`, `docs/activity.md`, `docs/notifications.md`, `docs/engagement.md` — the
+contracts every app that uses those modules is agreeing to. Cite them from an app with the
+package prefix (`cursedbelt-server/docs/retention.md`).
+
+## Verifying
+
+```sh
+cd "$FORGE/libs/cursedbelt-server" && bun run verify
+```

package/dist/subpathReach.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What each public subpath of this package REACHES that a consumer may not have — the optional
+ * peers it imports statically, and the bun builtins it needs.
+ *
+ * Two specs read these tables and neither may drift from the other:
+ *   · `barrelsReachNoOptionalPeer.spec.ts` bundles every subpath and fails when one reaches
+ *     something its row does not list, or a row lists something it no longer reaches;
+ *   · `readmeInstallTable.spec.ts` fails when README.md's "What you install" table disagrees
+ *     with these rows — the table an importing app actually reads (task 104).
+ * Not exported from package.json: this is the check's data, not an API.
+ */
+/**
+ * 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.
+ */
+export declare const MAY_DRAG: Record<string, readonly string[]>;
+/**
+ * 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.
+ */
+export declare const MAY_NEED_BUN: Record<string, readonly string[]>;

package/dist/subpathReach.js

@@ -0,0 +1,58 @@
+/**
+ * What each public subpath of this package REACHES that a consumer may not have — the optional
+ * peers it imports statically, and the bun builtins it needs.
+ *
+ * Two specs read these tables and neither may drift from the other:
+ *   · `barrelsReachNoOptionalPeer.spec.ts` bundles every subpath and fails when one reaches
+ *     something its row does not list, or a row lists something it no longer reaches;
+ *   · `readmeInstallTable.spec.ts` fails when README.md's "What you install" table disagrees
+ *     with these rows — the table an importing app actually reads (task 104).
+ * Not exported from package.json: this is the check's data, not an API.
+ */
+/**
+ * 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.
+ */
+export const MAY_DRAG = {
+    // 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'],
+    // `./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'],
+};
+/**
+ * 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.
+ */
+export const MAY_NEED_BUN = {
+    // 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'],
+    // 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'],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.19.0",
+	"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.",
@@ -29,7 +29,9 @@
 	"files": [
 		"dist",
 		"src",
-		"docs"
+		"docs",
+		"README.md",
+		"!src/server/typetests"
 	],
 	"exports": {
 		".": {
@@ -287,7 +289,7 @@
 	},
 	"dependencies": {
 		"cursedbelt-core": "^2.1.1",
-		"cursedops": "^0.4.0",
+		"cursedops": "^0.5.2",
 		"cwip": "^4.6.0",
 		"jose": "^6.2.3"
 	},

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,55 +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'],
-	// `./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'],
-};
-
-/**
- * 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'],
-	// 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(
 	Object.entries(
 		(pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> }).peerDependenciesMeta ?? {},

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

@@ -0,0 +1,52 @@
+/**
+ * Task 104, trap 3 — `Bun.serve`'s `websocket` selects an OVERLOAD; it is not an optional field.
+ *
+ * A compiler fact, so its honest carrier is the compiler: `typetests/serveBunOverload.ts` holds the
+ * trap under `@ts-expect-error` and the seam (`serveBun`) without one, and this spec runs `tsc` on
+ * it. Two ways it goes red, both meaningful:
+ *
+ *   · bun's types stop rejecting a maybe-undefined `websocket` → the `@ts-expect-error` is UNUSED
+ *     and tsc fails: the trap is gone, so the note in README.md and the fixture can go too;
+ *   · `serveBun` stops accepting an optional `websocket` → the seam line fails: the one thing an
+ *     app is told to use instead has itself grown the trap.
+ *
+ * The second half proves the first can fire: the same fixture with the directives stripped must
+ * fail with TS2345 on exactly the two trap lines.
+ */
+import { describe, expect, it } from 'bun:test';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const DIR = fileURLToPath(new URL('./typetests/', import.meta.url));
+const TSC = fileURLToPath(new URL('../../node_modules/typescript/bin/tsc', import.meta.url));
+
+const tsc = (project: string) => {
+  const run = Bun.spawnSync(['bun', TSC, '-p', project], { stdout: 'pipe', stderr: 'pipe' });
+  return { code: run.exitCode, out: `${run.stdout.toString()}${run.stderr.toString()}` };
+};
+
+describe("Bun.serve's websocket overload", () => {
+  it('the trap is still live in bun’s types, and serveBun is the seam that never meets it', () => {
+    const run = tsc(`${DIR}tsconfig.json`);
+    expect(run.out).toBe('');
+    expect(run.code).toBe(0);
+  }, 60_000);
+
+  it('🔴 without the directives the SAME lines fail — so the check above can go red', () => {
+    const source = readFileSync(`${DIR}serveBunOverload.ts`, 'utf8').replace(/^\s*\/\/ @ts-expect-error.*$/gm, '');
+    const file = `${DIR}serveBunOverload.stripped.ts`;
+    const project = `${DIR}tsconfig.stripped.json`;
+    writeFileSync(file, source);
+    writeFileSync(project, JSON.stringify({ extends: './tsconfig.json', include: ['serveBunOverload.stripped.ts'] }));
+    try {
+      const run = tsc(project);
+      expect(run.code).not.toBe(0);
+      const errors = run.out.split('\n').filter((line) => line.includes('error TS'));
+      expect(errors).toHaveLength(2);
+      for (const line of errors) expect(line).toContain('TS2345');
+    } finally {
+      rmSync(file, { force: true });
+      rmSync(project, { force: true });
+    }
+  }, 60_000);
+});

package/src/subpathReach.ts

@@ -0,0 +1,61 @@
+/**
+ * What each public subpath of this package REACHES that a consumer may not have — the optional
+ * peers it imports statically, and the bun builtins it needs.
+ *
+ * Two specs read these tables and neither may drift from the other:
+ *   · `barrelsReachNoOptionalPeer.spec.ts` bundles every subpath and fails when one reaches
+ *     something its row does not list, or a row lists something it no longer reaches;
+ *   · `readmeInstallTable.spec.ts` fails when README.md's "What you install" table disagrees
+ *     with these rows — the table an importing app actually reads (task 104).
+ * Not exported from package.json: this is the check's data, not an API.
+ */
+
+/**
+ * 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.
+ */
+export 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'],
+	// `./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'],
+};
+
+/**
+ * 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.
+ */
+export 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'],
+	// 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'],
+};
+