cursedbelt-server 4.18.0 → 4.19.0

package/dist/server/satellite/door.js

@@ -0,0 +1,149 @@
+/**
+ * `cursedbelt-server/satellite-door` — the PURE half of the satellite configuration contract:
+ * who an instance is (a release, a stage, a test runner, a production build) and who it opens
+ * for. No `node:*` import, no `process` read unless one exists, no package — so a Cloudflare
+ * Worker's door imports the SAME rules its Mac twin does.
+ *
+ * ## Why this is here, since 4.19.0 (task 281)
+ *
+ * Nine apps held an `appConfig.ts` in five versions (measured 2026-09-23: `roms`, `family`,
+ * `music`, `collections` and `auth` on one 445-line lineage; `vault` a trimmed fork of it;
+ * `flix`, `station` and `patterns` a second lineage). The divergence was not taste — it was
+ * protection lost in one copy and kept in another: `vault`, `flix` and `station` lost the stage
+ * identity override, so a stage of any of them would have signed in against PRODUCTION auth;
+ * `station` admitted its extra e-mails on its deployed release; lineage B could not tell an
+ * `APP_RELEASE=0` scratch boot from a release. The rules below are the union, decided once.
+ *
+ * And the Workers needed them without the Node half: `music`'s Worker imported the whole
+ * `appConfig.ts` to reach two pure functions, dragging `node:fs` and the data-dir chain into
+ * its bundle, while `collections` split a `doorConstants.ts` out by hand to avoid the same.
+ * This leaf is that split, once. `./satellite-config` is the Bun/Node half and re-exports all
+ * of this, so a Mac-side caller needs one import.
+ *
+ * 🔴 **This file imports NOTHING.** `src/leafSubpathsImportNothing.spec.ts` proves it in a
+ * fixture with no packages resolvable; an import that survives transpilation turns that red.
+ *
+ * 🔴 It knows the fleet's ZONE (`cursedalchemy.com`) and its accounts app's ports, as the
+ * binary-store client already does — mechanism of this fleet, not of any app. It does NOT
+ * know the owner: `ownerEmail` is always passed in.
+ */
+/** The accounts app (`apps/auth`) in production. */
+export const PROD_AUTH_URL = "https://auth.cursedalchemy.com";
+/** The accounts app's dev shell. */
+export const DEV_AUTH_URL = "http://localhost:3309";
+/**
+ * The LOCAL accounts door a stage signs in against — loopback, never the public hostname, so a
+ * stage's test sign-ins never write a row into the owner's real accounts registry.
+ */
+export const LOCAL_AUTH_URL = "http://127.0.0.1:3309";
+/** `APP_STAGE_IDENTITY=local` — the marker a stage boots with. */
+export const STAGE_IDENTITY_ENV = "APP_STAGE_IDENTITY";
+/** The one directory under the state root that is fixtures by construction. */
+export const TEST_SCRATCH_DIR_NAME = "test-scratch.noindex";
+/**
+ * Every marker that means "a test runner is in charge". A spec that spawns a REAL server strips
+ * exactly these ({@link withoutTestRuntimeMarkers}), so a fourth marker added here is stripped by
+ * everyone for free.
+ */
+export const TEST_RUNTIME_ENV_KEYS = ["NODE_ENV", "BUN_TEST", "SATELLITE_TEST_RUNTIME"];
+/** `process.env` where there is one; `{}` in a Worker, which has none. */
+const ambientEnv = () => globalThis.process?.env ?? {};
+/** Is this instance a stage whose identity must stay LOCAL? */
+export function stageIdentityIsLocal(env = ambientEnv()) {
+    return env[STAGE_IDENTITY_ENV]?.trim().toLowerCase() === "local";
+}
+/**
+ * Is this origin an ephemeral STAGE — `<app>-stage.cursedalchemy.com`?
+ *
+ * Derived from the hostname, never configured: a `-stage` name in the fleet's own zone cannot be
+ * typed into existence (only `stage up` creates the record, behind one Access application), so a
+ * production release cannot acquire one by a typo in a secrets file.
+ */
+export function isStageOrigin(publicUrl) {
+    try {
+        return new URL(publicUrl).hostname.endsWith("-stage.cursedalchemy.com");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is a test runner in charge? The three markers, and `SATELLITE_TEST_RUNTIME` because the React
+ * preloads force `NODE_ENV=development` and erase Bun's own `test`.
+ */
+export function isTestRuntime(env = ambientEnv()) {
+    return env.NODE_ENV === "test" || Boolean(env.BUN_TEST) || env.SATELLITE_TEST_RUNTIME === "1";
+}
+/** A copy of `env` with every test-runtime marker removed — what a spec hands a REAL server it spawns. */
+export function withoutTestRuntimeMarkers(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        if (TEST_RUNTIME_ENV_KEYS.includes(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * IS THIS A RELEASE? One question, one variable.
+ *
+ * `APP_RELEASE` is stamped by the deploy and by nothing else; `0`/`false` is an explicit no (a
+ * stage plan and a floor test both rely on that — lineage B ignored it and could not). Without
+ * the stamp it falls back to `APP_DATA_DIR`, minus the test-scratch tree, because a release
+ * shipped before the stamp existed must still answer yes: flipping it to no would open the smoke
+ * extras on the open internet. The fallback retires itself as each app redeploys.
+ */
+export function isRelease(env = ambientEnv()) {
+    const explicit = env.APP_RELEASE?.trim();
+    if (explicit)
+        return explicit !== "0" && explicit.toLowerCase() !== "false";
+    const appDataDir = env.APP_DATA_DIR?.trim() ?? "";
+    return Boolean(appDataDir) && !appDataDir.includes(TEST_SCRATCH_DIR_NAME);
+}
+/**
+ * Is this a DEV runtime? Vite's `import.meta.env.DEV` when a bundle carries it, else
+ * `NODE_ENV !== "production"` of the env given (or the ambient one).
+ */
+export function isDevRuntime(env) {
+    if (env === undefined) {
+        const viteDev = import.meta.env?.DEV;
+        if (typeof viteDev === "boolean")
+            return viteDev;
+    }
+    return (env ?? ambientEnv()).NODE_ENV !== "production";
+}
+/** The inverse of {@link isDevRuntime} — what `assertSatelliteUsable`'s refusal keys on with `deployed`. */
+export function isProductionRuntime(env) {
+    return !isDevRuntime(env);
+}
+/** `a@x, ,b@x` → `["a@x", "b@x"]`. The one parse for every `*_EXTRA_ALLOWED_EMAILS`. */
+export function parseEmailList(raw) {
+    return (raw ?? "")
+        .split(",")
+        .map((email) => email.trim())
+        .filter((email) => email.length > 0);
+}
+/**
+ * May extra accounts widen the door on THIS instance? Only off a release, or on a stage.
+ *
+ * 🔴 Keyed on `deployed`, not on the origin and not on loopback: a gate's artifact smoke runs the
+ * PRODUCTION build on `127.0.0.1`, so `live` is true there and the origin falls back to the prod
+ * hostname — keying on either would leave the extras inert in the one place they exist to work.
+ * Derived rather than configured: a boolean meaning "let someone else in" is one typo from true
+ * in production.
+ */
+export function extraEmailsApply(config) {
+    if (!config.deployed)
+        return true;
+    return isStageOrigin(config.publicUrl ?? "");
+}
+/**
+ * The addresses this instance opens for, owner first — what an owner-only app hands its SSO
+ * consumer's `allowedEmails`. One function, so the server, `/healthz` and the tests cannot
+ * disagree about the answer.
+ */
+export function allowedEmailsFor(config) {
+    return extraEmailsApply(config) ? [config.ownerEmail, ...config.extraAllowedEmails] : [config.ownerEmail];
+}

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

@@ -322,6 +322,24 @@ export declare const DELETE_TOKEN_TTL_SECONDS = 120;
 /** register-app prints the key as base64(PKCS8 PEM); env files sometimes carry
  *  raw PEM or PEM with literal `\n` sequences. Accept all three. */
 export declare function normalizePrivateKeyPem(raw: string): string;
+/**
+ * A short, stable, PUBLIC identifier for a tenant's signing key — the first 16 hex of sha256
+ * over the public half's SPKI DER. `""` for an unset key, `"unreadable"` for one that does not
+ * parse; never throws.
+ *
+ * 🔴 Why it exists. A wrong or stale `FILE_TOKEN_PRIVATE_KEY` is the failure that hides best:
+ * every list renders, `/healthz` is 200, and only the file bytes 403 — and the assertion that
+ * would catch it ("a file URL serves bytes") needs a signed-in session a deploy smoke does not
+ * have. So an instance publishes this digest on `/healthz` and the smoke derives the same digest
+ * from the key the deploying machine holds; the two are compared with no session anywhere.
+ *
+ * Safe to publish: a truncated hash of the PUBLIC half, which binary-server's tenant registry
+ * already holds. It was `fileTokenKeyId` in four apps' `src/server/config.ts` (music first, then
+ * family, roms and collections), byte-identical, until 4.19.0 (task 321). Lives here because it
+ * is `node:crypto` over the same key {@link createBinaryStore} signs with — and so it runs in a
+ * Worker under `nodejs_compat` exactly as the store does.
+ */
+export declare function fileTokenKeyId(privateKeyPem: string): string;
 export declare function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore;
 /**
  * Which binary-server TENANT this process is — the app's own key, unless the environment

package/dist/server/storage/binaryStore.js

@@ -40,7 +40,7 @@
  * import specifier (`cursedbelt/server/storage`, the pre-split package name) — no
  * behavioural difference in any of the three, so nothing was dropped to land the union.
  */
-import { createPrivateKey, sign as cryptoSign } from 'node:crypto';
+import { createHash, createPrivateKey, createPublicKey, sign as cryptoSign } from 'node:crypto';
 /*
  * ── The process-wide repeat register (§ the repeat-key counter) ───────────────
  *
@@ -196,6 +196,37 @@ export function normalizePrivateKeyPem(raw) {
     }
     return decoded;
 }
+/**
+ * A short, stable, PUBLIC identifier for a tenant's signing key — the first 16 hex of sha256
+ * over the public half's SPKI DER. `""` for an unset key, `"unreadable"` for one that does not
+ * parse; never throws.
+ *
+ * 🔴 Why it exists. A wrong or stale `FILE_TOKEN_PRIVATE_KEY` is the failure that hides best:
+ * every list renders, `/healthz` is 200, and only the file bytes 403 — and the assertion that
+ * would catch it ("a file URL serves bytes") needs a signed-in session a deploy smoke does not
+ * have. So an instance publishes this digest on `/healthz` and the smoke derives the same digest
+ * from the key the deploying machine holds; the two are compared with no session anywhere.
+ *
+ * Safe to publish: a truncated hash of the PUBLIC half, which binary-server's tenant registry
+ * already holds. It was `fileTokenKeyId` in four apps' `src/server/config.ts` (music first, then
+ * family, roms and collections), byte-identical, until 4.19.0 (task 321). Lives here because it
+ * is `node:crypto` over the same key {@link createBinaryStore} signs with — and so it runs in a
+ * Worker under `nodejs_compat` exactly as the store does.
+ */
+export function fileTokenKeyId(privateKeyPem) {
+    if (!privateKeyPem.trim())
+        return '';
+    try {
+        const spki = createPublicKey(createPrivateKey(normalizePrivateKeyPem(privateKeyPem))).export({
+            type: 'spki',
+            format: 'der',
+        });
+        return createHash('sha256').update(spki).digest('hex').slice(0, 16);
+    }
+    catch {
+        return 'unreadable';
+    }
+}
 const base64url = (bytes) => Buffer.from(bytes).toString('base64url');
 /** Keys may contain `/` as a real separator; each SEGMENT is percent-encoded
  *  because the server decodes the whole path before matching it to the token. */

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

@@ -0,0 +1,253 @@
+/**
+ * ── `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";
+/**
+ * ── 🔴 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 declare const webImageKeyFor: (key: string) => string;
+/**
+ * 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 declare const isUnviewableStill: (mime: string | null | undefined, fileName?: string | null) => boolean;
+/**
+ * ── 🔴 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 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 declare 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 declare const MAX_SCRUB_VTT_BYTES: number;
+/**
+ * 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 declare const rewriteScrubVtt: (vtt: string, spriteUrl: string) => string;
+/** Just enough of `BinaryStore` to resolve a derivative — so this module needs no store type. */
+export interface DerivativeProbe {
+    meta(key: string): Promise<unknown | null>;
+}
+export interface VideoPlayback {
+    /**
+     * The faststart remux, when binary-server has finished writing it. Absent means play the
+     * original and say why — never fail.
+     */
+    streamUrl?: string;
+    /** `"processing"` exactly when the remux is not there yet. */
+    processingStatus?: "processing";
+    /** True when a scrub track exists, so the caller can advertise its own proxy route. */
+    scrubReady: boolean;
+    /**
+     * The HLS master playlist, when a ladder exists — cursedbelt's `VideoPlayer` PREFERS this
+     * over {@link streamUrl}.
+     *
+     * 🔴 Absent is the NORMAL state and must stay cheap. Only some videos will ever have a
+     * ladder (it is a re-encode, unlike the faststart stream copy), so a consumer treats this
+     * exactly like every other derivative here: present means use it, absent means fall back,
+     * never an error.
+     *
+     * What it buys, given Range already works: a progressive MP4 cannot ADAPT. A weak
+     * connection stalls on a 23 Mbps master instead of dropping a rung, and each segment is a
+     * small object that caches whole at the edge rather than needing the big-object segment
+     * machinery.
+     */
+    hlsUrl?: string;
+}
+/**
+ * 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 declare function resolveVideoPlayback(store: DerivativeProbe, sourceKey: string, signStream: (key: string) => Promise<string>, 
+/**
+ * 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?: (prefix: string) => Promise<string>): Promise<VideoPlayback>;