cursedbelt-server 1.0.0

package/dist/server/storage/transcodeJobs.js

@@ -0,0 +1,104 @@
+// The binary-server transcode API as a plain job client — submit, poll, and the two
+// derivative shapes the fleet actually asks for.
+//
+// It was already here, inlined inside `createBinaryServerProcessing`, but only reachable
+// through that module's two seams (`VideoProcessor` / `ImageDerivatives`), which are shaped
+// for the cursedbelt file CATALOGUE: they take a `MediaStore`, a `workDir`, an owner and a
+// catalogue id. An app that stores binaries some other way — apps/notes keys attachments by
+// sha256 through satellite-kit's binary-store and has no catalogue at all — could not reach
+// the pipeline without either adopting the catalogue or writing a second HTTP client.
+//
+// So the transport lives here and the catalogue seams are built on top of it. There is ONE
+// derivative pipeline in the fleet, and this is its entry point.
+//
+// ── Why binary-server rather than deriving locally ──────────────────────────────────────
+// Derivatives are made where the SOURCE BYTES already are. binary-server is the fleet's
+// binary store, it runs on a Mac with real CPU, disk, ffmpeg and (for HEIC) sips, and the
+// derived bytes land back in the same tenant beside their source. Pulling a multi-GB video
+// down to an app host to run ffmpeg there defeats the point, and the shared prod t3.micro
+// has neither the disk nor the ffmpeg to do it at all.
+//
+// ── Who may call it ─────────────────────────────────────────────────────────────────────
+// `/api/transcode` is server-to-server: it is gated on the shared internal secret AND, since
+// the 2026-08-05 delete-surface hardening, 404s outright from binary-server's public host.
+// A prod-hosted app therefore CANNOT drive it; the Mac side of an app must.
+const DEFAULT_POLL_MS = 1500;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+export function createTranscodeJobClient(cfg) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const sleep = cfg.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const pollMs = cfg.pollMs ?? DEFAULT_POLL_MS;
+    const timeoutMs = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const appKey = (key) => `${cfg.appId}/${key}`;
+    const headers = {
+        'content-type': 'application/json',
+        'x-internal-secret': cfg.internalSecret,
+    };
+    const submit = async (body) => {
+        const res = await fetchImpl(`${cfg.baseUrl}/api/transcode`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (res.status !== 202) {
+            throw new Error(`binary-server transcode submit: ${res.status} ${await res.text()}`);
+        }
+        const { jobId } = (await res.json());
+        return jobId;
+    };
+    const poll = async (jobId, onProgress) => {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const res = await fetchImpl(`${cfg.baseUrl}/api/transcode/${encodeURIComponent(jobId)}`, {
+                headers,
+            });
+            if (!res.ok)
+                throw new Error(`binary-server transcode poll: ${res.status}`);
+            const job = (await res.json());
+            if (job.status === 'ready' || job.status === 'failed')
+                return job;
+            if (typeof job.progress === 'number')
+                onProgress?.(job.progress);
+            if (Date.now() > deadline)
+                throw new Error(`binary-server transcode ${jobId}: timed out`);
+            await sleep(pollMs);
+        }
+    };
+    const imageThumbnail = async (opts) => {
+        const jobId = await submit({
+            strategy: 'image',
+            nodeId: opts.nodeId ?? opts.sourceKey,
+            sourceKey: appKey(opts.sourceKey),
+            // The image strategy reads `binaryKey` as the source it fetches; the two are the same
+            // object here because nothing is being replaced, only derived from.
+            binaryKey: appKey(opts.sourceKey),
+            posterKey: appKey(opts.thumbKey),
+            ...(opts.displayKey ? { displayKey: appKey(opts.displayKey) } : {}),
+        });
+        const job = await poll(jobId);
+        if (job.status !== 'ready')
+            return { hasThumbnail: false, hasDisplay: false };
+        return {
+            hasThumbnail: job.result?.hasThumbnail ?? false,
+            hasDisplay: job.result?.hasDisplay ?? false,
+        };
+    };
+    const videoPoster = async (opts) => {
+        const jobId = await submit({
+            strategy: 'library',
+            nodeId: opts.nodeId ?? opts.sourceKey,
+            sourceKey: appKey(opts.sourceKey),
+            binaryKey: appKey(opts.sourceKey),
+            posterKey: appKey(opts.posterKey),
+            posterOnly: true,
+        });
+        const job = await poll(jobId);
+        if (job.status !== 'ready')
+            return { hasPoster: false, durationSeconds: 0 };
+        return {
+            hasPoster: job.result?.hasPoster ?? false,
+            durationSeconds: job.result?.durationSeconds ?? 0,
+        };
+    };
+    return { appKey, submit, poll, imageThumbnail, videoPoster };
+}

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

@@ -0,0 +1,193 @@
+import type { ProcessingStatus } from 'cursedbelt-core/media';
+/** Identity/tenant context threaded from an app's auth into every store/source call, so keys
+ * namespace per-owner and one tenant can never read another's media. */
+export type MediaCtx = {
+    userId: string;
+    tenantId: string;
+};
+/**
+ * The byte-storage adapter. The caller owns the key namespace (see keyspace helpers). One
+ * interface, many backends. Web-standard streams throughout (Bun/Hono) — the stream hands
+ * straight to a `Response` body with no node-stream conversion.
+ */
+export interface MediaStore {
+    /** Store bytes under an opaque key. */
+    put(key: string, bytes: Uint8Array, mime: string): Promise<void>;
+    /** Stream a body to storage without buffering it — for multi-GB writes (a transcode source,
+     * HLS segments) where a Uint8Array would be a full heap copy. */
+    putStream(key: string, body: ReadableStream<Uint8Array>, mime: string, opts?: {
+        contentLength?: number;
+    }): Promise<void>;
+    /** Read bytes back, or null if the key is gone. */
+    get(key: string): Promise<Uint8Array | null>;
+    /** Best-effort delete; must not throw if the key is already absent. */
+    remove(key: string): Promise<void>;
+    /** Recursively delete everything under a key prefix (an HLS tree, a user's media). */
+    removePrefix(prefix: string): Promise<void>;
+    /** Total byte size of a stored object, or null if gone. Answers Range requests without
+     * reading the whole object first. */
+    stat(key: string): Promise<{
+        size: number;
+    } | null>;
+    /** A web stream for the inclusive byte range [start, end], or the whole object when `range`
+     * is omitted; null if gone. Serves 206 Partial Content for seeking. */
+    getRange(key: string, range?: {
+        start: number;
+        end: number;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+    } | null>;
+    /** Absolute on-disk path for a key if this backend is local — lets ffmpeg read the source
+     * directly. null/absent for remote backends (the pipeline downloads the source first). */
+    localPath?(key: string): Promise<string | null>;
+    /** For a user-facing download, some backends (binary-server) prefer redirecting the browser
+     * to a signed edge URL instead of proxying bytes. Returns the URL, or null to fall back. */
+    redirectUrl?(key: string, opts: {
+        mime: string;
+        filename?: string;
+    }): Promise<string | null>;
+}
+/**
+ * Claims binary-server verifies (see binary-server/src/tokens.ts). This is the ONE
+ * canonical shape for a binary-server file token across the fleet: cursedbelt's
+ * injected-signer `createBinaryServerStore` and `@satellites/satellite-kit`'s
+ * self-signing `createBinaryStore` both mint tokens against the SAME binary-server, so
+ * the claim set must never drift — satellite-kit imports this exact type rather than
+ * redeclaring it, so a token one side signs is always shaped for the other to read. The
+ * app's signer turns these into an RS256 JWT.
+ */
+export type FileTokenClaims = {
+    /** Exact authorized path, app-prefixed: `<app>/<key>`. */
+    k?: string;
+    /** Authorized path prefix, app-prefixed (container trees, e.g. an HLS tree). */
+    p?: string;
+    /** Acting user/app id — audit trail on binary-server's events, never authz. */
+    uid?: string;
+    /** Chunk-session id (must match across every chunk of one upload). */
+    sid?: string;
+    /** Chunk index (0-based). */
+    ci?: number;
+    /** Total chunk count. */
+    tc?: number;
+    /** Download filename → Content-Disposition. */
+    fn?: string;
+    dl?: 'inline' | 'attachment';
+    /** Per-op scope. A DELETE against binary-server requires a token carrying `op: 'delete'`
+     *  (in addition to the internal secret) — a plain read/download token can never be replayed
+     *  as a delete, and the token's issuer + `k`/`p` tenant-scope the delete. Owner ruling #10. */
+    op?: 'delete';
+};
+export type FileTokenSigner = (claims: FileTokenClaims) => Promise<string>;
+export type BinaryServerConfig = {
+    /** e.g. 'https://binary-server.cursedalchemy.com'. */
+    baseUrl: string;
+    /** App namespace (path + token scope), e.g. 'cursedalchemy'. */
+    appId: string;
+    /** App-provided RS256 signer (app holds the private key). */
+    signFileToken: FileTokenSigner;
+    /** Shared secret for internal ops (delete). Sent as x-internal-secret. */
+    internalSecret?: string;
+};
+/** A source of videos for a gallery/catalogue. Apps implement this differently (a disk folder,
+ * a binary-server app, ca's Files tree + private set). Consumers are source-agnostic. */
+export interface MediaSource {
+    id: string;
+    title: string;
+    list(ctx: MediaCtx, opts: {
+        cursor?: string;
+        tag?: string;
+        query?: string;
+        limit?: number;
+        /** Listing order (backend maps to its own sorts; default newest-first). `random` is a
+         * seeded shuffle (stable across its own pagination); `lastViewed` orders by watch-open
+         * recency. A cursor is only valid under the sort that minted it. */
+        sort?: 'recent' | 'oldest' | 'name' | 'size' | 'random' | 'lastViewed';
+    }): Promise<{
+        items: import('cursedbelt-core/media').PlayableVideo[];
+        nextCursor?: string;
+    }>;
+    resolve(ctx: MediaCtx, videoId: string): Promise<import('cursedbelt-core/media').PlayableVideo | null>;
+    tags?(ctx: MediaCtx): Promise<string[]>;
+    ingest?(ctx: MediaCtx, upload: {
+        name: string;
+        mime: string;
+        body: ReadableStream<Uint8Array>;
+        size?: number;
+    }): Promise<import('cursedbelt-core/media').PlayableVideo>;
+    remove?(ctx: MediaCtx, videoId: string): Promise<void>;
+    /** Record a watch-open of a video — the signal the `lastViewed` sort orders by. Optional: a
+     * read-only source (a disk folder) has nothing to record. */
+    recordView?(ctx: MediaCtx, videoId: string): Promise<void>;
+}
+/** A source of photos for an image gallery — the image sibling of {@link MediaSource}. Same
+ * shape (cursor listing, tag facets, ingest, view ledger), photo-typed items. */
+export interface PhotoSource {
+    id: string;
+    title: string;
+    list(ctx: MediaCtx, opts: {
+        cursor?: string;
+        tag?: string;
+        query?: string;
+        limit?: number;
+        sort?: 'recent' | 'oldest' | 'name' | 'size' | 'random' | 'lastViewed';
+    }): Promise<{
+        items: import('cursedbelt-core/media').GalleryPhoto[];
+        nextCursor?: string;
+    }>;
+    resolve(ctx: MediaCtx, photoId: string): Promise<import('cursedbelt-core/media').GalleryPhoto | null>;
+    tags?(ctx: MediaCtx): Promise<string[]>;
+    ingest?(ctx: MediaCtx, upload: {
+        name: string;
+        mime: string;
+        body: ReadableStream<Uint8Array>;
+        size?: number;
+        tags?: string[];
+    }): Promise<import('cursedbelt-core/media').GalleryPhoto>;
+    remove?(ctx: MediaCtx, photoId: string): Promise<void>;
+    recordView?(ctx: MediaCtx, photoId: string): Promise<void>;
+}
+/** A source of MIXED media (photos + videos) for a combined gallery — the union of
+ * {@link MediaSource} and {@link PhotoSource} over ONE catalogue. `list`/`resolve`
+ * yield `GalleryMedia` (a `mediaKind`-tagged photo|video), and a `kind` filter narrows
+ * to just photos or just videos. Same cursor/tag/sort listing contract as its siblings. */
+export interface MediaGallerySource {
+    id: string;
+    title: string;
+    list(ctx: MediaCtx, opts: {
+        /** Narrow the mixed feed — `all` (default) lists photos + videos. */
+        kind?: import('cursedbelt-core/media').MediaKindFilter;
+        cursor?: string;
+        tag?: string;
+        query?: string;
+        limit?: number;
+        sort?: 'recent' | 'oldest' | 'name' | 'size' | 'random' | 'lastViewed';
+    }): Promise<{
+        items: import('cursedbelt-core/media').GalleryMedia[];
+        nextCursor?: string;
+    }>;
+    resolve(ctx: MediaCtx, itemId: string): Promise<import('cursedbelt-core/media').GalleryMedia | null>;
+    tags?(ctx: MediaCtx): Promise<string[]>;
+    remove?(ctx: MediaCtx, itemId: string): Promise<void>;
+    recordView?(ctx: MediaCtx, itemId: string): Promise<void>;
+}
+export type { ProcessingStatus };
+export declare const fsSourceKey: (owner: string, id: string) => string;
+export declare const fsMp4Key: (owner: string, id: string) => string;
+export declare const fsHlsPrefix: (owner: string, id: string) => string;
+export declare const fsHlsMasterKey: (owner: string, id: string) => string;
+export declare const fsHlsFileKey: (owner: string, id: string, rel: string) => string;
+export declare const fsPosterKey: (owner: string, id: string) => string;
+/** Full-size browser-safe JPEG derivative for images the browser can't render natively (HEIC/HEIF).
+ * The lightbox's full-view URL points here instead of the raw original. */
+export declare const fsDisplayKey: (owner: string, id: string) => string;
+export declare const fsSpriteKey: (owner: string, id: string) => string;
+export declare const fsVttKey: (owner: string, id: string) => string;
+/** Private (encrypted) namespace — the private-media layer stores ciphertext here. The HLS
+ * segments under it are AES-128-encrypted at rest (the player fetches the content key via the
+ * gated key route and decrypts); a distinct keyspace from public `hls/` so the two never collide. */
+export declare const privateFsKey: (owner: string, id: string) => string;
+export declare const privateHlsPrefix: (owner: string, id: string) => string;
+export declare const privateHlsMasterKey: (owner: string, id: string) => string;
+export declare const privateHlsFileKey: (owner: string, id: string, rel: string) => string;
+export declare const privatePosterKey: (owner: string, id: string) => string;
+export declare const privateSourceKey: (owner: string, id: string) => string;

package/dist/server/storage/types.js

@@ -0,0 +1,41 @@
+// cursedbelt-server/storage — the byte-storage layer cursedbelt's media pipeline was
+// missing. `server/media` (media-bun) owns the codec/pixel work; this owns *where the bytes
+// live and how they're served*: a backend-agnostic MediaStore (disk / binary-server / S3), a
+// Range→Response helper for seekable <video>, path-embedded stream tokens (so a media element
+// with no Bearer can still be authorized), a source registry, and the ingest→derivatives
+// pipeline glue. Ported/generalised from ca's proven media stack; the app maps its own records
+// to a MediaSource. Pairs with the `PlayableVideo` contract in `cursedbelt-core/media`.
+//
+// 🔴 THIS FILE IS A PUBLISHED LEAF — `cursedbelt-server/storage/types` — AND IT MUST STAY
+// IMPORT-FREE AT RUNTIME. `src/leafSubpathsImportNothing.spec.ts` imports it in a fixture with
+// no packages resolvable at all and fails if it throws, so an `import` here that survives
+// transpilation (anything that is not `import type`) turns that spec red rather than turning
+// up in a consumer's install. The subpath exists because `./server/storage`'s own index is a
+// barrel: it reaches `streamToken` → `auth/jwt` → jose, the whole SQLite file catalogue under
+// `files/`, and a lazily-imported `sharp` — while an app that wants only the SHAPE of a file
+// token (apps/collections wanted exactly `FileTokenClaims`, a type TypeScript erases) was made
+// to install a one-time-password library to get it. Add types here freely; add a value import
+// here never.
+// ── Keyspace helpers ──────────────────────────────────────────────────────────────
+// One source of truth for every storage key. Sources + serve routes + the pipeline all
+// address bytes through these, so a key layout is never hand-spelled twice.
+export const fsSourceKey = (owner, id) => `source/${owner}/${id}`;
+export const fsMp4Key = (owner, id) => `fs/${owner}/${id}.mp4`;
+export const fsHlsPrefix = (owner, id) => `hls/${owner}/${id}`;
+export const fsHlsMasterKey = (owner, id) => `hls/${owner}/${id}/master.m3u8`;
+export const fsHlsFileKey = (owner, id, rel) => `hls/${owner}/${id}/${rel}`;
+export const fsPosterKey = (owner, id) => `fs/${owner}/${id}-poster.jpg`;
+/** Full-size browser-safe JPEG derivative for images the browser can't render natively (HEIC/HEIF).
+ * The lightbox's full-view URL points here instead of the raw original. */
+export const fsDisplayKey = (owner, id) => `fs/${owner}/${id}-display.jpg`;
+export const fsSpriteKey = (owner, id) => `fs/${owner}/${id}-sprites.jpg`;
+export const fsVttKey = (owner, id) => `fs/${owner}/${id}-sprites.vtt`;
+/** Private (encrypted) namespace — the private-media layer stores ciphertext here. The HLS
+ * segments under it are AES-128-encrypted at rest (the player fetches the content key via the
+ * gated key route and decrypts); a distinct keyspace from public `hls/` so the two never collide. */
+export const privateFsKey = (owner, id) => `pfs/${owner}/${id}`;
+export const privateHlsPrefix = (owner, id) => `pfs/${owner}/${id}/hls`;
+export const privateHlsMasterKey = (owner, id) => `pfs/${owner}/${id}/hls/master.m3u8`;
+export const privateHlsFileKey = (owner, id, rel) => `pfs/${owner}/${id}/hls/${rel}`;
+export const privatePosterKey = (owner, id) => `pfs/${owner}/${id}/poster.enc`;
+export const privateSourceKey = (owner, id) => `pfs/${owner}/${id}/source.enc`;

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

@@ -0,0 +1,127 @@
+/**
+ * ── The NAMES of every video derivative binary-server writes ────────────────────────────
+ *
+ * A derivative's key is COMPUTED from its source's, never bookkept. A consumer finds one by
+ * deriving the name 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 these live in cursedbelt ─────────────────────────────────────────────────────
+ * Owner, 2026-08-14: *"Make it in cb because many apps may move to cloudflare and share the
+ * logic."* This contract is the seam between three repos that must never disagree —
+ * binary-server WRITES these names, `@satellites/satellite-kit` re-exports them for the
+ * satellite apps, and cursedbelt's own `binaryServerStore` mints the tokens that authorize
+ * them. A second hand-typed `${key}.web.mp4` anywhere in that triangle is a silent
+ * no-preview the day binary-server renames anything, and that has already happened once:
+ * `apps/collections` had the contract and `apps/family` shipped video without it, so family
+ * had no faststart stream, no scrub previews and no processing state at all.
+ *
+ * 🔴 What is shared here is the STRATEGY, never the media. Nothing in this module can resolve
+ * a stored object — every function is a pure string transform over a key the caller already
+ * holds. Each app is its own binary-server tenant with its own signing key, so family cannot
+ * reach a collections object through anything here, and that must stay true.
+ *
+ * ── 🔴 This is NOT the `fs*` keyspace in `./types.ts`, and they must not be merged ───────
+ * `fsHlsMasterKey(owner, id)` → `hls/<owner>/<id>/master.m3u8` and its siblings address the
+ * FileCatalogue: a caller that holds an owner and an item id, whose derivatives live in their
+ * own top-level namespaces. This module addresses a caller that holds a binary-server KEY and
+ * derives sibling names from it, which is what makes "ask /meta for a name you computed" work
+ * with no catalogue at all.
+ *
+ * Two consumers, two shapes, both correct:
+ *   · `fs*` — cursedbelt's own FileCatalogue / the `library` transcode strategy.
+ *   · this module — binary-server's derivative convention, used by the satellite apps.
+ *
+ * Collapsing either into the other renames objects that already exist in the store, and a
+ * renamed derivative is indistinguishable from an unbuilt one (absence is the "not ready"
+ * state) — so the visible result is every video in the fleet losing its previews at once,
+ * silently, with the rebuild costing hours of ffmpeg.
+ */
+/**
+ * The browser-playable remux: the same pictures with the index at the front.
+ *
+ * A phone MP4/MOV stores its `moov` index at the END, and a browser cannot decode frame one
+ * until it has that index — so it downloads the whole file first. Measured on the owner's
+ * 90,339,606-byte upload (2026-08-13): the index began at byte 90,305,514, 99.96% of the way
+ * in. That is the "videos stay on a spinner for minutes" report, and no amount of Range
+ * support, caching or edge tuning fixes it. A `+faststart` remux is a STREAM COPY for
+ * h264+aac sources, which is what phones produce: no re-encode, nothing lost.
+ */
+/**
+ * ── 🔴 THE ENCODER GENERATION IN THE NAME (2026-09-09) ──────────────────────────────────
+ *
+ * binary-server rebuilds every video derivative when its encoder improves, and a rebuild
+ * used to write **the same filename with different bytes**. That silently cancels out an
+ * `immutable` cache lifetime — a browser told `immutable` never re-checks, for a year, and
+ * **that cannot be revoked for a copy already on somebody's phone**. So the owner's decision
+ * (A, 2026-09-09) is that new bytes get a new address: `clip.web.mp4` → `clip.g2.web.mp4`.
+ *
+ * 🔴 **Generation 1 is UNTAGGED and always will be.** Every derivative in the store today is
+ * at the untagged name; tagging generation 1 would orphan all of them and re-encode the
+ * whole library for byte-identical output. Untagged is not a legacy case — it IS generation
+ * one.
+ *
+ * 🔴 **This constant must match binary-server's `VIDEO_ENCODER_GENERATION`**
+ * (`src/media/encoderGeneration.ts`). They are in different repos and neither can import the
+ * other, so binary-server carries a test that goes RED the moment somebody bumps its number,
+ * naming this file. If you are here because of that test: bump this in the same commit, and
+ * remember that `notes`, `collections` and `family` all reach these names through
+ * `@satellites/satellite-kit/video-derivatives`. Getting it wrong is not an error anywhere —
+ * it is a 404 that reads as "no preview available", on every video.
+ */
+export declare const VIDEO_KEY_GENERATION = 1;
+/** The generation tag a derivative's name carries. Empty for generation 1 — see above. */
+export declare const videoGenerationTag: (generation?: number) => string;
+export declare const webPlayableKeyFor: (key: string, generation?: number) => string;
+/** The scrub-preview sprite sheet — tiled frames from across the clip, as one JPEG. */
+export declare const spriteKeyFor: (key: string) => string;
+/** The WebVTT mapping a playhead position onto a tile of {@link spriteKeyFor}. */
+export declare const spriteVttKeyFor: (key: string) => string;
+/**
+ * The single still a gallery draws on a tile.
+ *
+ * Deliberately the SAME name a still photograph's thumbnail gets, so a consumer has one rule
+ * — *the tile for anything is `<key>.thumb.jpg`, and its absence means not ready* — rather
+ * than one rule per media kind. The sprite sheet is not a substitute: it is a GRID, 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.
+ */
+export declare const posterKeyFor: (key: string) => string;
+/**
+ * ── The HLS tree: `<key>.hls/` ──────────────────────────────────────────────────────────
+ *
+ * 🔴 ONE container, and the trailing name is load-bearing. binary-server's `storage.ts`
+ * co-locates a container's whole subtree under a single shard and `removeContainer()` wipes it
+ * atomically — so a ladder that is one container is deleted, migrated and reconciled as one
+ * thing. Segments scattered under sibling keys would be none of those, and orphaning half a
+ * ladder is worse than having none: the master would keep advertising rungs whose segments
+ * 404, which a player retries rather than falls back from.
+ *
+ * 🔴 Why HLS at all, now that Range works. The Range bug (an edge Worker answering 200 + the
+ * whole 209 MB to a ranged read) was fixed 2026-08-14 and is NOT what this is for. A single
+ * progressive MP4, however well served, cannot ADAPT: a weak cell connection stalls on a
+ * 23 Mbps master instead of dropping to a lower rung. Each segment is also a small object that
+ * caches WHOLE at the edge, which sidesteps both the 512 MiB single-entry ceiling and the
+ * segment-assembly machinery that exists to work around it for big films.
+ */
+export declare const hlsPrefixFor: (key: string, generation?: number) => string;
+/**
+ * The playlist a player is pointed at — the one object whose presence means "the ladder is
+ * ready". It is written LAST, after every rung, so a consumer that finds it can trust that
+ * what it names exists. Absence is normal and means "play the faststart remux".
+ */
+export declare const hlsMasterKeyFor: (key: string, generation?: number) => string;
+/**
+ * Every derivative suffix, for the "is this key itself a derivative" question.
+ *
+ * 🔴 Load-bearing in three directions, each of which has already cost something:
+ *  1. A derivative must never become the source of another, or a sweep builds
+ *     `clip.web.mp4.web.mp4` and then `…web.mp4.web.mp4.web.mp4`, forever.
+ *  2. A sweep must not count a derivative as work still owed, or the backlog is permanently
+ *     non-empty and ffmpeg re-runs on every pass.
+ *  3. A duplicate scan must not propose a file against its own derivative. They share a title
+ *     by construction, so every video would pair with its own remux and a review queue would
+ *     contain nothing else.
+ */
+export declare const DERIVATIVE_SUFFIXES: readonly [".web.mp4", ".sprite.jpg", ".sprite.vtt", ".thumb.jpg", ".web.jpg"];
+export declare const isDerivativeKey: (key: string) => boolean;

package/dist/server/storage/videoDerivativeKeys.js

@@ -0,0 +1,149 @@
+/**
+ * ── The NAMES of every video derivative binary-server writes ────────────────────────────
+ *
+ * A derivative's key is COMPUTED from its source's, never bookkept. A consumer finds one by
+ * deriving the name 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 these live in cursedbelt ─────────────────────────────────────────────────────
+ * Owner, 2026-08-14: *"Make it in cb because many apps may move to cloudflare and share the
+ * logic."* This contract is the seam between three repos that must never disagree —
+ * binary-server WRITES these names, `@satellites/satellite-kit` re-exports them for the
+ * satellite apps, and cursedbelt's own `binaryServerStore` mints the tokens that authorize
+ * them. A second hand-typed `${key}.web.mp4` anywhere in that triangle is a silent
+ * no-preview the day binary-server renames anything, and that has already happened once:
+ * `apps/collections` had the contract and `apps/family` shipped video without it, so family
+ * had no faststart stream, no scrub previews and no processing state at all.
+ *
+ * 🔴 What is shared here is the STRATEGY, never the media. Nothing in this module can resolve
+ * a stored object — every function is a pure string transform over a key the caller already
+ * holds. Each app is its own binary-server tenant with its own signing key, so family cannot
+ * reach a collections object through anything here, and that must stay true.
+ *
+ * ── 🔴 This is NOT the `fs*` keyspace in `./types.ts`, and they must not be merged ───────
+ * `fsHlsMasterKey(owner, id)` → `hls/<owner>/<id>/master.m3u8` and its siblings address the
+ * FileCatalogue: a caller that holds an owner and an item id, whose derivatives live in their
+ * own top-level namespaces. This module addresses a caller that holds a binary-server KEY and
+ * derives sibling names from it, which is what makes "ask /meta for a name you computed" work
+ * with no catalogue at all.
+ *
+ * Two consumers, two shapes, both correct:
+ *   · `fs*` — cursedbelt's own FileCatalogue / the `library` transcode strategy.
+ *   · this module — binary-server's derivative convention, used by the satellite apps.
+ *
+ * Collapsing either into the other renames objects that already exist in the store, and a
+ * renamed derivative is indistinguishable from an unbuilt one (absence is the "not ready"
+ * state) — so the visible result is every video in the fleet losing its previews at once,
+ * silently, with the rebuild costing hours of ffmpeg.
+ */
+/**
+ * The browser-playable remux: the same pictures with the index at the front.
+ *
+ * A phone MP4/MOV stores its `moov` index at the END, and a browser cannot decode frame one
+ * until it has that index — so it downloads the whole file first. Measured on the owner's
+ * 90,339,606-byte upload (2026-08-13): the index began at byte 90,305,514, 99.96% of the way
+ * in. That is the "videos stay on a spinner for minutes" report, and no amount of Range
+ * support, caching or edge tuning fixes it. A `+faststart` remux is a STREAM COPY for
+ * h264+aac sources, which is what phones produce: no re-encode, nothing lost.
+ */
+/**
+ * ── 🔴 THE ENCODER GENERATION IN THE NAME (2026-09-09) ──────────────────────────────────
+ *
+ * binary-server rebuilds every video derivative when its encoder improves, and a rebuild
+ * used to write **the same filename with different bytes**. That silently cancels out an
+ * `immutable` cache lifetime — a browser told `immutable` never re-checks, for a year, and
+ * **that cannot be revoked for a copy already on somebody's phone**. So the owner's decision
+ * (A, 2026-09-09) is that new bytes get a new address: `clip.web.mp4` → `clip.g2.web.mp4`.
+ *
+ * 🔴 **Generation 1 is UNTAGGED and always will be.** Every derivative in the store today is
+ * at the untagged name; tagging generation 1 would orphan all of them and re-encode the
+ * whole library for byte-identical output. Untagged is not a legacy case — it IS generation
+ * one.
+ *
+ * 🔴 **This constant must match binary-server's `VIDEO_ENCODER_GENERATION`**
+ * (`src/media/encoderGeneration.ts`). They are in different repos and neither can import the
+ * other, so binary-server carries a test that goes RED the moment somebody bumps its number,
+ * naming this file. If you are here because of that test: bump this in the same commit, and
+ * remember that `notes`, `collections` and `family` all reach these names through
+ * `@satellites/satellite-kit/video-derivatives`. Getting it wrong is not an error anywhere —
+ * it is a 404 that reads as "no preview available", on every video.
+ */
+export const VIDEO_KEY_GENERATION = 1;
+/** The generation tag a derivative's name carries. Empty for generation 1 — see above. */
+export const videoGenerationTag = (generation = VIDEO_KEY_GENERATION) => generation <= 1 ? "" : `.g${generation}`;
+export const webPlayableKeyFor = (key, generation = VIDEO_KEY_GENERATION) => `${key}${videoGenerationTag(generation)}.web.mp4`;
+/** The scrub-preview sprite sheet — tiled frames from across the clip, as one JPEG. */
+export const spriteKeyFor = (key) => `${key}.sprite.jpg`;
+/** The WebVTT mapping a playhead position onto a tile of {@link spriteKeyFor}. */
+export const spriteVttKeyFor = (key) => `${key}.sprite.vtt`;
+/**
+ * The single still a gallery draws on a tile.
+ *
+ * Deliberately the SAME name a still photograph's thumbnail gets, so a consumer has one rule
+ * — *the tile for anything is `<key>.thumb.jpg`, and its absence means not ready* — rather
+ * than one rule per media kind. The sprite sheet is not a substitute: it is a GRID, 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.
+ */
+export const posterKeyFor = (key) => `${key}.thumb.jpg`;
+/**
+ * ── The HLS tree: `<key>.hls/` ──────────────────────────────────────────────────────────
+ *
+ * 🔴 ONE container, and the trailing name is load-bearing. binary-server's `storage.ts`
+ * co-locates a container's whole subtree under a single shard and `removeContainer()` wipes it
+ * atomically — so a ladder that is one container is deleted, migrated and reconciled as one
+ * thing. Segments scattered under sibling keys would be none of those, and orphaning half a
+ * ladder is worse than having none: the master would keep advertising rungs whose segments
+ * 404, which a player retries rather than falls back from.
+ *
+ * 🔴 Why HLS at all, now that Range works. The Range bug (an edge Worker answering 200 + the
+ * whole 209 MB to a ranged read) was fixed 2026-08-14 and is NOT what this is for. A single
+ * progressive MP4, however well served, cannot ADAPT: a weak cell connection stalls on a
+ * 23 Mbps master instead of dropping to a lower rung. Each segment is also a small object that
+ * caches WHOLE at the edge, which sidesteps both the 512 MiB single-entry ceiling and the
+ * segment-assembly machinery that exists to work around it for big films.
+ */
+export const hlsPrefixFor = (key, generation = VIDEO_KEY_GENERATION) => `${key}${videoGenerationTag(generation)}.hls/`;
+/**
+ * The playlist a player is pointed at — the one object whose presence means "the ladder is
+ * ready". It is written LAST, after every rung, so a consumer that finds it can trust that
+ * what it names exists. Absence is normal and means "play the faststart remux".
+ */
+export const hlsMasterKeyFor = (key, generation = VIDEO_KEY_GENERATION) => `${hlsPrefixFor(key, generation)}master.m3u8`;
+/**
+ * Every derivative suffix, for the "is this key itself a derivative" question.
+ *
+ * 🔴 Load-bearing in three directions, each of which has already cost something:
+ *  1. A derivative must never become the source of another, or a sweep builds
+ *     `clip.web.mp4.web.mp4` and then `…web.mp4.web.mp4.web.mp4`, forever.
+ *  2. A sweep must not count a derivative as work still owed, or the backlog is permanently
+ *     non-empty and ffmpeg re-runs on every pass.
+ *  3. A duplicate scan must not propose a file against its own derivative. They share a title
+ *     by construction, so every video would pair with its own remux and a review queue would
+ *     contain nothing else.
+ */
+export const DERIVATIVE_SUFFIXES = [
+    ".web.mp4",
+    ".sprite.jpg",
+    ".sprite.vtt",
+    ".thumb.jpg",
+    ".web.jpg",
+];
+/**
+ * Is this key something binary-server DERIVED rather than something a person uploaded?
+ *
+ * The HLS tree is matched by its container segment rather than a suffix, because every object
+ * inside it (`master.m3u8`, `720/index.m3u8`, `720/000.ts`) is a derivative and none of them
+ * ends in a name from the list above.
+ */
+const DERIVATIVE_RE = new RegExp(
+// 🔴 The optional `.g<N>` is the encoder generation a video derivative's name carries
+// (see VIDEO_KEY_GENERATION above). Without it, `clip.g2.web.mp4` reads as a SOURCE — and
+// then a sweep derives `clip.g2.web.mp4.web.mp4` from it, for ever. Built from the suffix
+// list rather than written out, so the two cannot drift apart.
+`(?:\\.g\\d+)?(?:${DERIVATIVE_SUFFIXES.map((x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})$`);
+export const isDerivativeKey = (key) => DERIVATIVE_RE.test(key) ||
+    key.includes(".hls/") ||
+    /-thumb\.(jpg|webp|png)$/.test(key) ||
+    /\.shot\.\d+\.jpg$/.test(key);

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

@@ -0,0 +1,30 @@
+import type { ProcessingStatus } from 'cursedbelt-core/media';
+import { type MediaStore } from './types';
+export type ProcessProgress = (status: ProcessingStatus, pct: number) => void;
+export type ProcessResult = {
+    status: ProcessingStatus;
+    durationSeconds: number;
+    hasHls: boolean;
+    hasSprite: boolean;
+    hasPoster: boolean;
+};
+export type ProcessOptions = {
+    store: MediaStore;
+    /** Scratch directory for ffmpeg inputs/outputs (cleaned up afterwards). */
+    workDir: string;
+    owner: string;
+    id: string;
+    /** Storage key of the already-persisted raw source. */
+    sourceKey: string;
+    /** HLS rung heights to attempt (clamped to the source height; never upscaled). */
+    ladderHeights?: number[];
+    /**
+     * Poster-only mode for memory-constrained hosts: probe duration + extract a single-frame
+     * poster (cheap, ~tens of MB peak) and skip the heavy re-encode/HLS/sprite work that OOM'd
+     * the 1GB prod box (2026-07-04). The raw source still plays progressively; this only buys a
+     * grid thumbnail + duration. Best-effort — a failed poster still lands the row `ready`.
+     */
+    posterOnly?: boolean;
+    onProgress?: ProcessProgress;
+};
+export declare function processVideo(opts: ProcessOptions): Promise<ProcessResult>;