cursedbelt-server 4.18.1 → 4.19.0

package/dist/server/storage/uploadSession.js

@@ -0,0 +1,74 @@
+/**
+ * Server-side half of the direct-to-binary-server upload: mint a session an app can hand to
+ * a browser.
+ *
+ * 🔴 SERVER ONLY — this reaches the tenant's private key through {@link BinaryStore}. The
+ * browser half (`uploadDirect`, in the React design system's tier) imports nothing from here.
+ *
+ * ── `cursedbelt-server/binary-store/upload-session`, since 4.19.0 (task 343) ──────────────
+ * It was `src/kit/directUploadSession.ts` in `collections` and `family`, and the two copies
+ * had already forked the way copies of a wire format do: `collections`' mint declared the
+ * source length as `sz` and `family`'s did not, so a wrong `tc` in `family` could still store a
+ * short object indexed `active` — the 2026-08-13 loss `collections` had already paid for. This
+ * is the `collections` body. It is a leaf of its own rather than part of `./binary-store`
+ * because that entry's promise is ONE file that costs `node:crypto` and nothing else, and the
+ * fixture proving it copies only that file; this one's only import is a TYPE, so it keeps the
+ * same promise at zero runtime cost.
+ *
+ * The token this produces is a capability: it authorizes writing ONE key for a bounded time,
+ * and nothing else. It cannot read, cannot delete, cannot touch another key, and cannot touch
+ * another tenant (binary-server resolves the app from the token's issuer and requires the
+ * request path to match the claim). So handing it to a page is safe in the way handing over a
+ * signed download URL is safe — which the fleet already does for media reads.
+ */
+/** Bytes per part. 16 MiB matches what `putLarge` has used in production since 2026-08-08:
+ *  comfortably under the Cloudflare Tunnel's ~100 MB request wall with room for retries, and
+ *  large enough that a 10 GB upload is ~640 requests rather than tens of thousands. */
+export const DIRECT_UPLOAD_CHUNK_BYTES = 16 * 1024 * 1024;
+/**
+ * How long a session token stays valid.
+ *
+ * 🔴 Deliberately hours, not the 10 minutes `UPLOAD_TOKEN_TTL_SECONDS` gives a server-to-server
+ * upload. A 10 GB file on a home upstream is a multi-hour transfer, and a token that expires
+ * mid-way turns it into a failed one. Six hours covers the realistic worst case; beyond that
+ * the browser re-mints for the same `sid` (see `refreshToken` in the browser half), so a paused
+ * overnight upload still resumes without widening this window.
+ *
+ * The exposure a longer TTL buys is small and bounded: write access to one key the app just
+ * allocated for this upload, which the app has not yet shown to anyone.
+ */
+export const DIRECT_UPLOAD_TOKEN_TTL_SECONDS = 6 * 60 * 60;
+/**
+ * Mint an upload session for one file.
+ *
+ * `totalChunks` is derived from `sizeBytes` here, on the server, and baked into the token as
+ * `tc` — that is what makes it authoritative. binary-server assembles when `tc` parts have
+ * arrived, so a client cannot claim a file is complete early by lying about its length; the
+ * worst it can do is describe its own file wrongly and fail its own upload.
+ */
+export async function createUploadSession(store, opts) {
+    const chunkBytes = opts.chunkBytes ?? DIRECT_UPLOAD_CHUNK_BYTES;
+    if (!Number.isFinite(opts.sizeBytes) || opts.sizeBytes < 0) {
+        throw new Error(`createUploadSession: bad sizeBytes ${opts.sizeBytes}`);
+    }
+    const totalChunks = Math.max(1, Math.ceil(opts.sizeBytes / chunkBytes));
+    const sid = opts.sid ?? crypto.randomUUID();
+    const path = `${store.appId}/${opts.key}`;
+    // 🔴 The source length rides along with the count, because a count is NOT a length: `tc` is
+    // arithmetic over a chunk size the client chose, so the server can derive neither from the
+    // other. With `sz` on the token bs compares staged and assembled bytes against it and answers
+    // 422, so a wrong `tc` can only cost a refused upload rather than a short object indexed
+    // `active`. It is the same number `tc` was derived from two lines up, so declaring it costs
+    // nothing; the caller states a real length (`POST /api/uploads` refuses `sizeBytes <= 0`
+    // outright), and a stated length is the only thing this can be — never a placeholder, because
+    // a `sz` that does not match the bytes refuses every assemble.
+    const token = await store.signToken({ k: path, sid, tc: totalChunks, sz: opts.sizeBytes, uid: opts.ownerId }, opts.ttlSeconds ?? DIRECT_UPLOAD_TOKEN_TTL_SECONDS);
+    return {
+        baseUrl: opts.baseUrl.replace(/\/+$/, ""),
+        path,
+        token,
+        sid,
+        totalChunks,
+        chunkBytes,
+    };
+}

package/docs/THE-DEV-DEPENDENCY-CYCLE.md

@@ -0,0 +1,55 @@
+# 🔴 `cursedbelt` is a devDependency of this package, and `cursedbelt` devDepends on this one
+
+A cycle, deliberately, and only in `devDependencies`. Written down because the next person
+to see it will assume it is a mistake, and because it has one consequence that bites.
+
+## Why it exists
+
+Two integration specs prove the chunked-upload protocol end to end:
+
+- `src/server/storage/fileUploadClient.integration.spec.ts`
+- `src/server/storage/fileUploadClient-chunked.integration.spec.ts`
+
+Their subject is **this** package's server internals — `diskStore`, `streamToken`,
+`files/catalogue`, `files/fileRoutes` — none of which are exported, and none of which
+should be: widening the public surface so a test can reach it is how a surface rots.
+So the specs must live here.
+
+But the thing that DRIVES that protocol is the React-side upload client, which lives in
+`cursedbelt` (`cursedbelt/react/media/upload-client`). Hence the dev-only edge.
+
+The alternative was to move the specs into `cursedbelt` and export four server internals
+to make them reachable. That trades a dev-only cycle for a permanent public promise, which
+is the worse trade.
+
+## What is NOT circular
+
+**Runtime dependencies are acyclic and must stay that way.**
+
+    cwip  →  cursedbelt-core  →  cursedbelt-server
+                             ↘   cursedbelt (react)
+                                          ↘  cursedbelt-cc
+
+`cursedbelt-server` does not depend on `cursedbelt` at runtime, and `cursedbelt` does not
+depend on `cursedbelt-server` at runtime. If either ever does, this file is no longer
+describing a devDependency cycle — it is describing a bug.
+
+## 🔴 The consequence: publish order
+
+`prepublishOnly` runs the full `verify`, and `verify` runs these specs, which resolve
+`cursedbelt` from the registry. So **a version of this package whose specs need a not-yet-
+published `cursedbelt` cannot publish until that `cursedbelt` is live.** The two packages
+cannot be bumped in lockstep in one pass.
+
+The order that works, and the one the 2026-09-15 split used:
+
+1. `cursedbelt-core` (depends on neither)
+2. `cursedbelt-server` against the CURRENT published `cursedbelt`
+3. `cursedbelt` against the just-published `cursedbelt-server`
+4. `cursedbelt-cc` last — it depends on all three
+
+If you need a `cursedbelt-server` change and a `cursedbelt` change that depend on each
+other, ship them as two rounds of that order, not one. And remember `tools/publish-libs.sh`
+polls the registry because npm answers a publish with 202 and serves it minutes later — a
+timeout there is not a failure, and `curl -sI https://registry.npmjs.org/<pkg>/<version>`
+is the one command that settles it.

package/docs/activity.md

@@ -0,0 +1,43 @@
+# Activity — the ONE audit stream
+
+`cursedbelt-server/activity` (storage + query) over `cursedbelt-core/activity` (the pure
+vocabulary) is the code; this page is the contract. Written 2026-09-23 (task 324) because
+`apps/roms/src/server/routes.ts` asserted a rule "`cursedbelt-server/activity` is explicit
+about" that no document stated.
+
+## 1. One stream per app, append-only, never deleted by this package
+
+Who did what, to which record, when, and how it went — one table
+(`ACTIVITY_EVENTS_TABLE`), written through `createActivityLog`. This package never deletes an
+event. A high-volume stream opts into [retention](retention.md) as `event-log`; a low-volume
+audit of destructive actions is right to declare nothing (retention §4).
+
+## 2. The three outcomes, and why a refusal is `denied` — never `error`
+
+`ACTIVITY_OUTCOMES` is `ok`, `denied`, `error`, and the line between the last two is the whole
+value of the column:
+
+| outcome | means | who acts on it |
+|---|---|---|
+| `ok` | it happened | nobody |
+| `denied` | the app **correctly refused** — a policy, a permission, a quota, a validation said no | the person who was refused, or the owner deciding the policy |
+| `error` | the app **failed** to do what it meant to do | whoever maintains the app |
+
+A refusal recorded as `error` makes the app look broken exactly when it worked, and buries its
+real failures under correct behaviour; a failure recorded as `denied` hides a bug as a policy.
+`roms` records BOTH halves of an upload for this reason: an accepted one puts a file on the
+owner's storage under his name, and a refused one — `denied` — is the row that answers "I tried
+to add that game weeks ago".
+
+## 3. A resource is `(app, kind, id)`
+
+Identical to `cursedbelt-core/sharing`'s `ShareResource`, so a resource passes from one
+primitive to the other with no translation (`activityFromShareEvent`). `app` is on every row so
+a merge across apps stays labelled.
+
+## 4. Describing an event is the library's job
+
+`describeActivityEvent` / `describeActivityResource` produce the sentence a reader sees. An app
+that writes its own sentence for the same event creates a second wording that drifts.
+
+Cite this page from an app as `cursedbelt-server/docs/activity.md`.

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.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);
+  });
+});