cursedbelt-server 4.18.0 → 4.19.0

package/dist/server/storage/derivatives.js

@@ -0,0 +1,266 @@
+/**
+ * ── `cursedbelt-server/storage/derivatives` — how an app READS what binary-server derives ──
+ *
+ * Since 4.19.0 (task 344). The key NAMES already lived here (`./videoDerivativeKeys.ts`, on the
+ * owner's 2026-08-14 ruling — *"Make it in cb because many apps may move to cloudflare and share
+ * the logic"*); what was still copied into `collections` and `family` as `src/kit/imageDerivatives.ts`
+ * and `src/kit/videoDerivatives.ts` was the READING strategy built on them — the part with the
+ * judgement in it. The video copy had already forked (three import lines and a doc comment, benign
+ * by accident), and the HEIC rule below decides whether a photograph appears AT ALL, which may not
+ * exist in two places.
+ *
+ * 🔴 Store-agnostic throughout: every function takes the caller's own store or signer, so nothing
+ * here can reach across tenants — each app is its own binary-server tenant and must stay unable to
+ * resolve another's objects.
+ *
+ * The key names are RE-EXPORTED from here, so a consumer changes one import specifier and not
+ * every call site. This file imports only `./videoDerivativeKeys.ts`, which imports nothing, so it
+ * mounts unchanged inside a Worker (`src/leafSubpathsImportNothing.spec.ts` proves it).
+ */
+export { hlsMasterKeyFor, hlsPrefixFor, posterKeyFor, spriteKeyFor, spriteVttKeyFor, webPlayableKeyFor, } from "./videoDerivativeKeys.js";
+import { hlsMasterKeyFor, hlsPrefixFor, spriteVttKeyFor, webPlayableKeyFor, } from "./videoDerivativeKeys.js";
+// ── STILL images ───────────────────────────────────────────────────────────────────────────
+/**
+ * ── 🔴 The STILL-image derivatives binary-server writes, and how an app READS them ───
+ *
+ * The sibling of `videoDerivatives.ts`, and it exists for a different reason worth being
+ * explicit about. A video's remux is about SPEED — the original plays, eventually. A still's
+ * `.web.jpg` is, for a large and growing share of the fleet's photographs, about the picture
+ * appearing AT ALL.
+ *
+ * ── The report that produced this file (owner, 2026-08-14) ───────────────────────────
+ * *"determine why a full album shows up with no thumbnails and videos and images not
+ * working"* — `family.cursedalchemy.com` → Keepsakes, one album of 85 items drawn as a wall
+ * of file names with a torn-page glyph on every tile, and the album's own cover blank.
+ *
+ * Nothing was missing and nothing had failed. Measured that day against real prod: every one
+ * of those rows answered `/api/sources/:id/file` with **HTTP 200 and
+ * `Content-Type: image/heic`**. `apps/family` served the bytes the family uploaded, exactly
+ * as designed — and **no browser except Safari can decode HEIC**, so a correct 200 rendered
+ * as a broken image in Chrome and Firefox. Every iPhone in the household shoots HEIC by
+ * default; 86 of the tenant's 182 stored stills were HEIC.
+ *
+ * binary-server had already done its half. It classes `heic`/`heif`/`tiff`/`x-adobe-dng` as
+ * UNVIEWABLE and exempts them from its "too small to bother" floor precisely because for
+ * those *"the derivative is not a saving — it is the only copy anything can display"*. All
+ * 86 had both a `.web.jpg` and a `.thumb.jpg` sitting beside them. The app simply never asked
+ * for either.
+ *
+ * ── 🔴 The two rules a consumer needs ────────────────────────────────────────────────
+ *
+ *  1. **A picture on a SCREEN is `webImageKeyFor(key)` when that object exists**, and the
+ *     original only when it does not. This is not merely an optimization: for an unviewable
+ *     original it is the difference between a photograph and a broken image.
+ *  2. **A picture on a DOWNLOAD is always the original.** A person asking for their own file
+ *     must get the file they gave us — full resolution, original container, original
+ *     metadata. A re-encode handed over as "your photograph" is a quiet, permanent loss on
+ *     the one road where the family expects the archive to be an archive.
+ *
+ * The tile picture is `posterKeyFor` (below, with the video rules) — `<key>.thumb.jpg`, deliberately
+ * the SAME name a video's still gets, so a grid has one rule for everything it draws. It is
+ * not duplicated.
+ *
+ * ── 🔴 Absence is "not ready yet", and it CANNOT be probed per row ───────────────────
+ * As everywhere in this contract, a derivative is found by computing its name — so the object
+ * being absent IS the not-ready state, with no webhook, no job id and no column. That is
+ * cheap for the ONE item a person opened and ruinous for a grid: probing per tile is a
+ * network round trip per row, over a Cloudflare Tunnel, from a `MemoryMax=300M` box. So a
+ * consumer must never probe to build a list. It offers the derived tile URL for every row and
+ * lets the `<img>` fall back to the full picture on error — `cursedbelt/react/media-gallery`'s
+ * `ThumbImg` does exactly this, for exactly this reason.
+ */
+/**
+ * The web-optimized still: bounded dimensions, re-encoded for size, and for HEIC/TIFF/RAW the
+ * only copy a browser can draw.
+ *
+ * 🔴 `.jpg`, and it is binary-server's key that this must match byte for byte
+ * (`src/media/derivativeKeys.ts` → `webImageKeyFor`). The extension is baked into the name and
+ * the name is what a consumer computes without asking, so changing the container on either
+ * side means an app confidently addressing bytes that are not there — which fails as a 404 on
+ * a picture, i.e. silently and only in a browser.
+ */
+export const webImageKeyFor = (key) => `${key}.web.jpg`;
+/**
+ * True when NO browser can draw the original, so `webImageKeyFor` is not an optimization but
+ * the only copy that can appear on a screen.
+ *
+ * 🔴 This mirrors binary-server's own `isUnviewableOriginal`
+ * (`src/media/imageKinds.ts` → `/^image\/(x-adobe-dng|tiff|heic|heif)$/`), and the two must
+ * agree: bs uses it to decide which stills are EXEMPT from its "too small to bother" size
+ * floor — *"the derivative is not a saving, it is the only copy anything can display"* — so a
+ * consumer that classes a mime differently either offers a derivative bs never built (a
+ * broken picture) or serves an original nothing decodes (the same broken picture, with the
+ * fix sitting unused in storage). binary-server may import it from here; until it does, the regex is the seam, and it is
+ * three words long.
+ *
+ * 🔴 The NAME is checked too, and that is not belt-and-braces. `File.type` is empty for a
+ * `.DNG` in every browser tested and often for an iPhone `.MOV`/`.HEIC`, so an app's catalog
+ * frequently holds `application/octet-stream` for exactly the files this predicate exists to
+ * catch — the same reason binary-server sniffs the first 4 KB rather than trusting the mime
+ * it was handed.
+ */
+export const isUnviewableStill = (mime, fileName) => {
+    const bare = (mime ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+    if (/^image\/(x-adobe-dng|tiff|heic|heif)(-sequence)?$/.test(bare))
+        return true;
+    const extension = (fileName ?? "").toLowerCase().match(/\.([a-z0-9]+)$/)?.[1] ?? "";
+    return ["dng", "tif", "tiff", "heic", "heif"].includes(extension);
+};
+// ── VIDEO ──────────────────────────────────────────────────────────────────────────────────
+/**
+ * ── 🔴 The video derivatives binary-server writes, and how an app READS them ─────────
+ *
+ * binary-server remuxes every uploaded video into a browser-playable sibling and samples a
+ * scrub-preview sprite sheet + track, naming each result after the source object. **That
+ * naming is the whole contract**: a consumer finds a derivative by computing its key and
+ * asking `/meta` whether it exists yet, so there is no webhook, no job id, no schema column
+ * and nothing to reconcile. The absence of the object is the "not ready yet" state, and it
+ * answers itself.
+ *
+ * Why it matters at all, measured on the owner's own 90 MB upload (2026-08-13): a phone
+ * MP4/MOV stores its `moov` index at the END of the file — that clip's began at byte
+ * 90,305,514 of 90,339,606 — and a browser cannot decode frame one until it has that index,
+ * so it downloads the whole file first. That is the "videos stay on a spinner for minutes"
+ * report. The derivative is a `-movflags +faststart` remux with the index at byte 32, and for
+ * h264+aac sources (which is what phones produce) it is a STREAM COPY: same pictures, no
+ * re-encode, nothing lost. It also drops the junk tracks iPhones attach — that clip's original
+ * carried an unknown audio stream and five data streams, which is a second, independent reason
+ * a browser refuses a `.mov`.
+ *
+ * 🔴 These are DERIVED, never stored on the row. A `web_key` column would let an app's catalog
+ * disagree with what binary-server actually holds — and the catalog lives on prod-ec2 while
+ * the bytes live on the Mac, so the two would drift the first time either side was restored
+ * from a backup.
+ *
+ * ── Why this was a SHARED module and not one app's ───────────────────────────────────
+ * The record, because it explains the shape this file still has. It was
+ * `@satellites/satellite-kit/video-derivatives`; `collections` is the only app in this
+ * generation that has it, and it is copied here rather than re-inlined into `storage.ts`.
+ *
+ * It was `apps/collections/src/server/storage.ts` first, and it worked, so `apps/family`
+ * shipped video with none of it: no faststart stream, no scrub previews, no processing state
+ * — the owner's 2026-08-13 note ("the ffmpeg processing, awesome scrubbing … should all be
+ * possible" in family, with collections named as the example to copy). A key contract shared
+ * with ANOTHER REPO is exactly the thing that must not be re-typed per app: a second copy of
+ * `${key}.web.mp4` is a silent no-preview the day binary-server renames anything.
+ *
+ * 🔴 What is shared here is the STRATEGY, never the media. Nothing in this module reaches
+ * across tenants — every function takes the caller's own store, and each app is its own
+ * binary-server tenant with its own signing key. family must never be able to resolve a
+ * collections object and vice versa; keeping this module store-agnostic is what keeps that
+ * true while the two apps share one pipeline.
+ */
+/**
+ * The single still a gallery draws on a tile — binary-server's `.thumb.jpg`.
+ *
+ * ── 🔴 Why this is here, from the owner's report (2026-08-14) ────────────────────────
+ * *"videos are not showing with thumbnails in the family app keepsakes"*, with a screenshot
+ * of one album: eleven photographs with tiles and three videos — 129, 282 and 633 MB — drawn
+ * as a grey play triangle.
+ *
+ * Nothing was broken. binary-server's `runPoster` had always existed and was reachable only
+ * from its `library` strategy, while `family` and `collections` both submit `faststart`,
+ * which minted a remux and sprites and no still. With no picture to show, the gallery fell
+ * back to asking the BROWSER to decode the clip's own first frame — which works on a small
+ * file and does not happen at all on a 633 MB one over a home connection, because the browser
+ * must fetch and demux the front of the container first and quietly gives up.
+ *
+ * 🔴 **The sprite sheet is not a substitute and was rejected as one.** It is a GRID of frames,
+ * so drawing it on a tile shows a contact sheet, and using one cell means every consumer
+ * carries the VTT's geometry in order to crop it — a second, subtler copy of exactly the
+ * cross-repo duplication this module exists to prevent.
+ *
+ * 🔴 **The same name a still photograph's thumbnail gets, deliberately.** A consumer then has
+ * ONE rule — *the tile for anything is `<key>.thumb.jpg`, and its absence means not ready* —
+ * rather than one rule per media kind, and `.thumb.jpg` was already in binary-server's
+ * `DERIVATIVE_SUFFIXES`, so nothing about the key contract, the sweep's backlog arithmetic or
+ * the duplicate scan changes. A video and a photograph are different things to a person and
+ * the same thing to a grid.
+ */
+/* The definition moved to cursedbelt with the rest of the contract (re-exported above);
+ * the reasoning above is kept here because it is the report that produced the name. */
+/**
+ * The relative sprite name binary-server writes into every VTT cue, which a consumer rewrites
+ * into a signed URL when it serves the track.
+ *
+ * 🔴 A literal shared with another repo and enforced by nothing but this comment. It is
+ * `buildSpriteVtt`'s `spriteName` default in binary-server's `ffmpegJobs.ts`. If that default
+ * ever changes, scrub previews go blank silently — a cue pointing at a name nothing serves
+ * produces no error, no console warning and no visible failure except an empty thumbnail
+ * strip. Each consumer's scrub-route test asserts a real binary-server-shaped VTT is
+ * rewritten, so the pin is behavioral rather than a hope.
+ */
+export const SPRITE_VTT_PLACEHOLDER = "sprites.jpg";
+/**
+ * The largest scrub track an app will proxy. A VTT is one text cue per sampled frame and
+ * binary-server caps a sheet at a few hundred tiles, so an honest one is under 20 KB; this is
+ * a tripwire against proxying something that is not a VTT at all, on a box with
+ * `MemoryMax=300M`.
+ */
+export const MAX_SCRUB_VTT_BYTES = 256 * 1024;
+/**
+ * Rewrite a binary-server scrub track so its cues point at a signed sprite URL.
+ *
+ * 🔴 The reference is replaced WHOLESALE rather than prefixed: a signed URL carries a query
+ * string, and a cue's `#xywh=` fragment must stay after it. Prefixing produces
+ * `…/sprite.jpg?token=…#xywh=0,0,160,90` only by accident of ordering, and gets it wrong the
+ * moment the signer appends a parameter.
+ */
+export const rewriteScrubVtt = (vtt, spriteUrl) => vtt.replaceAll(SPRITE_VTT_PLACEHOLDER, spriteUrl);
+/**
+ * Resolve what a video can offer RIGHT NOW: the faststart stream if it is ready, and whether
+ * a scrub track exists.
+ *
+ * 🔴 Best-effort throughout, deliberately. binary-server being slow, down, or out of disk must
+ * degrade this to "here are the original bytes", never break opening a file — a probe that
+ * throws would turn a working (if slow) video into a broken one, which is strictly worse than
+ * the problem the derivative exists to solve. An absent derivative is a NORMAL state.
+ *
+ * The signer is injected rather than taken as a store + options bag: the two consumers mint
+ * URLs under different privacy rules (collections signs a private item with a short,
+ * non-stable window; family signs by kind), and that decision must stay at the call site
+ * where the row's privacy is known.
+ */
+export async function resolveVideoPlayback(store, sourceKey, signStream, 
+/**
+ * Signs a PREFIX-scoped token for an HLS tree, when the caller can serve one.
+ *
+ * Separate from `signStream` because it mints a different claim (`p`, not `k`): one token
+ * has to authorize the master playlist AND every rung index AND every segment under it,
+ * and re-signing per segment would mean a round trip to the app for each one. Optional so
+ * a consumer that has not wired the HLS route yet keeps working unchanged — it simply
+ * never advertises a ladder.
+ */
+signHlsTree) {
+    const webKey = webPlayableKeyFor(sourceKey);
+    const webMeta = await store.meta(webKey).catch(() => null);
+    const scrubMeta = await store.meta(spriteVttKeyFor(sourceKey)).catch(() => null);
+    const scrubReady = scrubMeta !== null && scrubMeta !== undefined;
+    if (!webMeta)
+        return { processingStatus: "processing", scrubReady };
+    const streamUrl = await signStream(webKey).catch(() => null);
+    // A signable derivative that would not sign is the credentials being wrong, which is the
+    // same answer as "not ready": play the original.
+    if (!streamUrl)
+        return { processingStatus: "processing", scrubReady };
+    /*
+     * 🔴 The ladder is probed by its MASTER, and the master is written LAST.
+     *
+     * binary-server stores every rung and every segment before `master.m3u8`, so the master's
+     * presence is the one honest "the whole ladder is there" signal. Probing the prefix, or a
+     * rung, would advertise a half-written ladder — and that fails far worse than no ladder at
+     * all: a player handed a master whose segments 404 RETRIES them rather than falling back,
+     * so the video stalls instead of playing the progressive copy it could have used.
+     *
+     * Everything here stays best-effort. No ladder is the normal case (it is a re-encode, so
+     * most videos will never have one) and a failed probe or an unsignable prefix simply means
+     * `streamUrl` is what the player gets — the state it has always been in.
+     */
+    const hlsUrl = signHlsTree
+        ? await store
+            .meta(hlsMasterKeyFor(sourceKey))
+            .then((master) => (master ? signHlsTree(hlsPrefixFor(sourceKey)) : null))
+            .catch(() => null)
+        : null;
+    return hlsUrl ? { streamUrl, hlsUrl, scrubReady } : { streamUrl, scrubReady };
+}

package/dist/server/storage/uploadSession.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+import type { BinaryStore } from "./binaryStore.js";
+/** 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 declare const DIRECT_UPLOAD_CHUNK_BYTES: number;
+/**
+ * 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 declare const DIRECT_UPLOAD_TOKEN_TTL_SECONDS: number;
+/** The descriptor handed to the browser. Mirrors `UploadSession` in `directUpload.ts` —
+ *  they are the two ends of one wire format, so change them together. */
+export interface UploadSessionDescriptor {
+    baseUrl: string;
+    path: string;
+    token: string;
+    sid: string;
+    totalChunks: number;
+    chunkBytes: number;
+}
+export interface CreateUploadSessionOptions {
+    /** App-relative destination key (NOT app-prefixed — the store adds that). */
+    key: string;
+    /** Exact byte length of the file being uploaded. */
+    sizeBytes: number;
+    /** binary-server's public base URL, as the browser must reach it. */
+    baseUrl: string;
+    /** Owner recorded on the stored object (`uid` claim). */
+    ownerId?: string;
+    /** Reuse an existing session id to RESUME — the same `sid` addresses the same staged
+     *  parts, so re-minting a token never orphans partial work. */
+    sid?: string;
+    chunkBytes?: number;
+    ttlSeconds?: number;
+}
+/**
+ * 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 declare function createUploadSession(store: BinaryStore, opts: CreateUploadSessionOptions): Promise<UploadSessionDescriptor>;

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`.