cursedbelt-server 1.0.0

package/src/server/storage/transcodeJobs.ts

@@ -0,0 +1,171 @@
+// 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.
+
+export type TranscodeJobStatus = 'pending' | 'processing' | 'ready' | 'failed';
+
+export type TranscodeJobResult = {
+  durationSeconds?: number;
+  hasHls?: boolean;
+  hasPoster?: boolean;
+  hasSprite?: boolean;
+  hasThumbnail?: boolean;
+  hasDisplay?: boolean;
+};
+
+export type TranscodeJobStatusBody = {
+  status: TranscodeJobStatus;
+  progress?: number;
+  error?: string;
+  result?: TranscodeJobResult;
+};
+
+export type TranscodeJobClientConfig = {
+  /** e.g. 'https://binary-server.cursedalchemy.com' — same value as the byte store's baseUrl. */
+  baseUrl: string;
+  /** App namespace (path + token scope), e.g. 'notes'. Keys are sent app-scoped. */
+  appId: string;
+  /** Shared server-to-server secret (x-internal-secret). */
+  internalSecret: string;
+  /** Poll cadence while a job runs. */
+  pollMs?: number;
+  /** Give up after this long (the job keeps running server-side; the caller just stops waiting). */
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+  /** Injectable clock/sleep for tests. */
+  sleep?: (ms: number) => Promise<void>;
+};
+
+export type TranscodeJobClient = {
+  /** Prefix a bare key with this client's app namespace, as the API expects. */
+  appKey: (key: string) => string;
+  submit: (body: Record<string, unknown>) => Promise<string>;
+  poll: (jobId: string, onProgress?: (pct: number) => void) => Promise<TranscodeJobStatusBody>;
+  /**
+   * Still-image derivatives: a width-bounded JPEG thumbnail at `thumbKey`, plus — only for
+   * formats browsers cannot render (HEIC/HEIF) — a full-size display JPEG at `displayKey`.
+   * Keys are bare (this client scopes them).
+   */
+  imageThumbnail: (opts: {
+    sourceKey: string;
+    thumbKey: string;
+    displayKey?: string;
+    /** Job label in binary-server's queue; defaults to the source key. */
+    nodeId?: string;
+  }) => Promise<{ hasThumbnail: boolean; hasDisplay: boolean }>;
+  /**
+   * A video's poster frame ONLY — no ladder, no HLS, no sprite sheet. `posterOnly` collapses
+   * the library strategy to probe + poster, which is what a grid tile needs and is an order
+   * of magnitude cheaper than a transcode nobody asked for.
+   */
+  videoPoster: (opts: {
+    sourceKey: string;
+    posterKey: string;
+    nodeId?: string;
+  }) => Promise<{ hasPoster: boolean; durationSeconds: number }>;
+};
+
+const DEFAULT_POLL_MS = 1500;
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+export function createTranscodeJobClient(cfg: TranscodeJobClientConfig): TranscodeJobClient {
+  const fetchImpl = cfg.fetchImpl ?? fetch;
+  const sleep = cfg.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+  const pollMs = cfg.pollMs ?? DEFAULT_POLL_MS;
+  const timeoutMs = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const appKey = (key: string) => `${cfg.appId}/${key}`;
+  const headers = {
+    'content-type': 'application/json',
+    'x-internal-secret': cfg.internalSecret,
+  };
+
+  const submit = async (body: Record<string, unknown>): Promise<string> => {
+    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()) as { jobId: string };
+    return jobId;
+  };
+
+  const poll = async (
+    jobId: string,
+    onProgress?: (pct: number) => void,
+  ): Promise<TranscodeJobStatusBody> => {
+    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()) as TranscodeJobStatusBody;
+      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: TranscodeJobClient['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: TranscodeJobClient['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/src/server/storage/types.ts

@@ -0,0 +1,230 @@
+// 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.
+
+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>;
+}
+
+// ── binary-server file tokens ─────────────────────────────────────────────────────
+// Declared HERE rather than beside the adapter that uses them (`binaryServerStore.ts`, which
+// re-exports them for compatibility) because these three are the shapes a consumer needs
+// WITHOUT the adapter: apps/collections' `binaryStore.ts` mints its own tokens and imports
+// `FileTokenClaims` alone.
+
+/**
+ * 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 };
+
+// ── 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: string, id: string) => `source/${owner}/${id}`;
+export const fsMp4Key = (owner: string, id: string) => `fs/${owner}/${id}.mp4`;
+export const fsHlsPrefix = (owner: string, id: string) => `hls/${owner}/${id}`;
+export const fsHlsMasterKey = (owner: string, id: string) => `hls/${owner}/${id}/master.m3u8`;
+export const fsHlsFileKey = (owner: string, id: string, rel: string) => `hls/${owner}/${id}/${rel}`;
+export const fsPosterKey = (owner: string, id: string) => `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: string, id: string) => `fs/${owner}/${id}-display.jpg`;
+export const fsSpriteKey = (owner: string, id: string) => `fs/${owner}/${id}-sprites.jpg`;
+export const fsVttKey = (owner: string, id: string) => `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: string, id: string) => `pfs/${owner}/${id}`;
+export const privateHlsPrefix = (owner: string, id: string) => `pfs/${owner}/${id}/hls`;
+export const privateHlsMasterKey = (owner: string, id: string) =>
+  `pfs/${owner}/${id}/hls/master.m3u8`;
+export const privateHlsFileKey = (owner: string, id: string, rel: string) =>
+  `pfs/${owner}/${id}/hls/${rel}`;
+export const privatePosterKey = (owner: string, id: string) => `pfs/${owner}/${id}/poster.enc`;
+export const privateSourceKey = (owner: string, id: string) => `pfs/${owner}/${id}/source.enc`;

package/src/server/storage/videoDerivativeKeys.spec.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  DERIVATIVE_SUFFIXES,
+  hlsMasterKeyFor,
+  hlsPrefixFor,
+  isDerivativeKey,
+  posterKeyFor,
+  spriteKeyFor,
+  spriteVttKeyFor,
+  VIDEO_KEY_GENERATION,
+  videoGenerationTag,
+  webPlayableKeyFor,
+} from './videoDerivativeKeys';
+
+/**
+ * The derivative NAME contract, pinned because three repos depend on it agreeing:
+ * binary-server writes these names, satellite-kit re-exports them, and this package mints the
+ * tokens that authorize them. A rename that looks harmless here is a silent no-preview
+ * everywhere else — the absence of an object is the "not ready yet" state, so a consumer
+ * asking for the wrong name cannot tell the difference between "renamed" and "still building".
+ */
+describe('video derivative keys', () => {
+  const key = 'real/media/9295c424-8e55-445b-b4e4-1e7587394dfc';
+
+  it('names each derivative after its source', () => {
+    expect(webPlayableKeyFor(key)).toBe(`${key}.web.mp4`);
+    expect(spriteKeyFor(key)).toBe(`${key}.sprite.jpg`);
+    expect(spriteVttKeyFor(key)).toBe(`${key}.sprite.vtt`);
+    expect(posterKeyFor(key)).toBe(`${key}.thumb.jpg`);
+  });
+
+  it('🔴 puts the whole HLS ladder in ONE container', () => {
+    // binary-server co-locates a container's subtree under one shard and removes it
+    // atomically. Segments under sibling keys would be neither, and half a ladder is worse
+    // than none: the master keeps advertising rungs whose segments 404, which a player
+    // retries rather than falls back from.
+    expect(hlsPrefixFor(key)).toBe(`${key}.hls/`);
+    expect(hlsMasterKeyFor(key)).toBe(`${key}.hls/master.m3u8`);
+    expect(hlsMasterKeyFor(key).startsWith(hlsPrefixFor(key))).toBe(true);
+  });
+
+  it('the prefix ends in a slash, so a token for it cannot match a sibling key', () => {
+    // `${key}.hls` without the slash is a prefix of `${key}.hlsomething` too. The trailing
+    // slash is what keeps a prefix-scoped token confined to the tree it was minted for.
+    expect(hlsPrefixFor(key).endsWith('/')).toBe(true);
+  });
+
+  describe('isDerivativeKey', () => {
+    it('recognises every suffix it publishes', () => {
+      for (const suffix of DERIVATIVE_SUFFIXES)
+        expect(isDerivativeKey(`${key}${suffix}`)).toBe(true);
+    });
+
+    it('🔴 recognises objects INSIDE an HLS tree, which carry no derivative suffix', () => {
+      // Miss these and the sweep treats a segment as a video needing a remux, then derives
+      // from that, forever. None of them ends in a name from DERIVATIVE_SUFFIXES.
+      expect(isDerivativeKey(`${key}.hls/master.m3u8`)).toBe(true);
+      expect(isDerivativeKey(`${key}.hls/720/index.m3u8`)).toBe(true);
+      expect(isDerivativeKey(`${key}.hls/720/000.ts`)).toBe(true);
+    });
+
+    it('leaves an uploaded original alone', () => {
+      expect(isDerivativeKey(key)).toBe(false);
+      expect(isDerivativeKey('file/holiday.mp4')).toBe(false);
+      // A name that merely mentions one of the words is not a derivative.
+      expect(isDerivativeKey('file/sprite-collection.mov')).toBe(false);
+    });
+  });
+});
+
+/**
+ * ── 🔴 THE READER SIDE OF THE ENCODER GENERATION ────────────────────────────────────────
+ *
+ * binary-server writes these names; this module computes them; `notes`, `collections` and
+ * `family` read them through `@satellites/satellite-kit/video-derivatives`. Since 2026-09-09
+ * a video derivative's name carries the encoder generation that built it, so that a re-encode
+ * lands at a NEW address and an `immutable` cache lifetime is safe — `immutable` cannot be
+ * revoked for a copy already in somebody's browser.
+ *
+ * These tests pin the two things that make the three-repo contract hold.
+ */
+describe("the encoder generation in a video derivative's name", () => {
+	it("🔴 generation 1 is UNTAGGED — these are the names every stored object already has", () => {
+		// If this changes, every derivative binary-server holds becomes unreachable from every
+		// app at once, and the whole library re-encodes to produce byte-identical output.
+		expect(webPlayableKeyFor("v/clip.mov")).toBe("v/clip.mov.web.mp4");
+		expect(webPlayableKeyFor("v/clip.mov", 1)).toBe("v/clip.mov.web.mp4");
+		expect(hlsMasterKeyFor("v/clip.mov")).toBe("v/clip.mov.hls/master.m3u8");
+		expect(hlsPrefixFor("v/clip.mov")).toBe("v/clip.mov.hls/");
+		expect(videoGenerationTag(1)).toBe("");
+	});
+
+	it("🔴 matches binary-server's VIDEO_ENCODER_GENERATION, which is 1", () => {
+		// The two constants live in different repos and neither can import the other.
+		// binary-server's encoderGeneration.spec.ts goes red when its number changes and
+		// names THIS file; this is the other end of that wire.
+		expect(VIDEO_KEY_GENERATION).toBe(1);
+	});
+
+	it("a bump gives the new bytes a new address", () => {
+		expect(webPlayableKeyFor("v/clip.mov", 2)).toBe("v/clip.mov.g2.web.mp4");
+		expect(hlsMasterKeyFor("v/clip.mov", 2)).toBe("v/clip.mov.g2.hls/master.m3u8");
+	});
+
+	it("🔴 a tagged derivative is still recognised as a derivative", () => {
+		// Miss this and a sweep treats clip.g2.web.mp4 as a source and derives from it for ever.
+		expect(isDerivativeKey("v/clip.mov.g2.web.mp4")).toBe(true);
+		expect(isDerivativeKey("v/clip.mov.g2.hls/720/000.ts")).toBe(true);
+		expect(isDerivativeKey("v/clip.mov")).toBe(false);
+		expect(isDerivativeKey("v/holiday.g2.mov")).toBe(false);
+	});
+});