cursedbelt 0.0.0 → 2.3.0

package/src/server/storage/files/catalogue.ts

@@ -0,0 +1,1326 @@
+import type { Database } from 'bun:sqlite';
+import type { Dirent } from 'node:fs';
+import { mkdir, readdir, rm, stat as fsStat } from 'node:fs/promises';
+import path from 'node:path';
+import type { ProcessingStatus } from '../../../core/media';
+import { renderImage } from '../../media-bun/image';
+import { sealMeta } from '../../private-media/crypto';
+import type { PrivateIndex, PrivateItem } from '../../private-media/index-store';
+import { processPrivateBlob, processPrivateVideo } from '../../private-media/pipeline';
+import { ffmpegImageThumbnail, isBrowserRenderableImage } from '../imageThumbnail';
+import {
+  fsDisplayKey,
+  fsHlsPrefix,
+  fsMp4Key,
+  fsPosterKey,
+  fsSourceKey,
+  fsSpriteKey,
+  fsVttKey,
+  type MediaCtx,
+  type MediaStore,
+  privateFsKey,
+} from '../types';
+import { type ProcessOptions, type ProcessResult, processVideo } from '../videoProcessor';
+import { mimeByExt } from './mimeByExt';
+import {
+  type CollectionVisibility,
+  classifyFileType,
+  type FileCatalogue,
+  type FileCollection,
+  type FilePage,
+  type FileRecord,
+  type FileType,
+  type ListFilesOptions,
+  type PrivateFileCatalogue,
+  type TagFacet,
+} from './types';
+
+/** Swappable video ingest→derivatives implementation. The default runs ffmpeg
+ * locally ({@link processVideo}); a remote backend (binary-server) delegates
+ * the heavy work to the storage host instead — see binaryServerProcessing. */
+export type VideoProcessor = (opts: ProcessOptions) => Promise<ProcessResult>;
+
+/** Everything an image-derivative implementation needs to produce the grid
+ * thumbnail (posterKey, 512px JPEG) and — for formats browsers can't render —
+ * the full-size display JPEG (displayKey). */
+export type ImageDerivativesOptions = {
+  store: MediaStore;
+  workDir: string;
+  owner: string;
+  id: string;
+  mime: string;
+  /** Storage key of the uploaded original. */
+  binaryKey: string;
+  /** Where the 512px grid thumbnail JPEG goes. */
+  posterKey: string;
+  /** Where the full-size browser-safe JPEG goes (only when `needsDisplay`). */
+  displayKey: string;
+  /** True when the original's format isn't browser-renderable (HEIC/HEIF). */
+  needsDisplay: boolean;
+};
+
+/** Swappable image thumbnail/display derivative implementation (local sharp/
+ * ffmpeg by default; remote binary-server job when the bytes live there). */
+export type ImageDerivatives = (opts: ImageDerivativesOptions) => Promise<{ hasThumbnail: boolean }>;
+
+/** Sealed descriptor payload (encrypted under the set key) — the private counterpart to the
+ * plaintext name/tags a public row stores in the clear. */
+type SealedDescriptor = { name: string; mime: string; tags: string[] };
+
+// Stream an upload body to a local plaintext file (staged for the private pipeline; wiped after).
+// Bun.write(dest, new Response(stream)) hangs in Bun 1.3.x — pump via a FileSink instead.
+async function streamToFile(body: ReadableStream<Uint8Array>, dest: string): Promise<number> {
+  await mkdir(path.dirname(dest), { recursive: true });
+  const sink = Bun.file(dest).writer();
+  const reader = body.getReader();
+  let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      sink.write(value);
+    }
+  } finally {
+    await sink.end();
+  }
+  return size;
+}
+
+// The general primary binary for a NON-video file (images/docs/…) lives here; video files store a
+// raw source (fsSourceKey) + derived mp4/HLS/poster/sprite via the shared video keyspace.
+export const fileBinaryKey = (owner: string, id: string) => `fs/${owner}/${id}`;
+
+/** Where a file's uploaded bytes must land for `registerUploaded` to find them: a video's raw
+ * source (fed to the transcode), else the primary binary. The chunked-upload path targets this key
+ * so an out-of-band upload lands exactly where the catalogue + serve routes expect it. */
+export const catalogueUploadKey = (owner: string, id: string, mime: string): string =>
+  mime.startsWith('video/') ? fsSourceKey(owner, id) : fileBinaryKey(owner, id);
+
+type Row = {
+  id: string;
+  owner: string;
+  name: string;
+  mime: string;
+  size: number;
+  file_type: string;
+  is_private: number;
+  has_thumbnail: number;
+  has_hls: number;
+  has_sprites: number;
+  duration: number | null;
+  processing_status: string;
+  processing_progress: number;
+  created_at: number;
+  updated_at: number;
+  rand_key: number;
+  trashed_at: number | null;
+  /** Present only under the `lastViewed` sort — the coalesced last-viewed timestamp selected
+   * alongside `f.*` so the cursor key can be extracted without a second lookup. */
+  view_key?: number;
+};
+
+/** A private row carries the sealed envelope + wrapped key + wrap mode alongside the base row. */
+type PrivateRow = Row & { enc_name: string; enc_dek: string; enc_key_type: string };
+
+type CollectionRow = {
+  id: string;
+  owner: string;
+  name: string;
+  kind: string;
+  visibility: string;
+  created_at: number;
+  updated_at: number;
+};
+
+const b64 = (s: string) => Buffer.from(s).toString('base64url');
+const unb64 = (s: string) => Buffer.from(s, 'base64url').toString();
+
+// Sort-aware keyset pagination. The cursor encodes (optional shuffle seed, sort key, id tie-break);
+// the key is inner-b64'd so a file NAME containing '|' can't break parsing. The `random` sort mints
+// a seed on the first page and threads it here so every subsequent page reshuffles identically. A
+// cursor is only meaningful under the sort that minted it (the caller passes the same `sort` on
+// every page). Segment order is `seed|b64(key)|id` — b64(key) and a UUID id never contain '|', and
+// seed is a bare integer, so a 3-way split is unambiguous.
+const encodeCursor = (key: string | number, id: string, seed?: number) =>
+  b64(`${seed ?? ''}|${b64(String(key))}|${id}`);
+function decodeCursor(c: string): { seed?: number; key: string; id: string } | null {
+  try {
+    const [seed, k, id] = unb64(c).split('|');
+    if (!id) return null;
+    return { seed: seed === '' ? undefined : Number(seed), key: unb64(k), id };
+  } catch {
+    return null;
+  }
+}
+
+/** A sort's SQL: total order (sort key + id tie-break), the matching keyset predicate, the
+ * cursor-key extractor, and any extra FROM join / selected column it needs. */
+type SortSpec = {
+  orderBy: string;
+  keysetWhere: string;
+  key: (r: Row) => string | number;
+  numericKey: boolean;
+  /** Extra join appended to the FROM (e.g. the file_views LEFT JOIN for `lastViewed`). */
+  join?: string;
+  /** Extra selected expression appended after `f.*` (e.g. the coalesced view timestamp). */
+  selectExtra?: string;
+  /** Extra bound params the order/keyset expressions reference (e.g. the `random` remap coeffs). */
+  params?: Record<string, number>;
+};
+
+// The seeded `random` remap uses modular arithmetic under a Mersenne prime (2^31 - 1). rand_key and
+// the derived coefficients are all < 2^31, so `rand_key * mul + add` stays < 2^62 — exact in both
+// SQLite's signed-64-bit integer math and JS BigInt (the two must agree for keyset boundaries).
+const RANDOM_MOD = 2147483647;
+
+/** Derive the `random` sort spec for a given session seed: order by the seed-remapped rand_key
+ * (ties broken by id). The remap `(rand_key * mul + add) mod P` reshuffles per seed while staying a
+ * stable total order, so keyset pagination holds as long as the cursor carries the same seed. */
+function randomSortSpec(seed: number): SortSpec {
+  const mul = (seed % (RANDOM_MOD - 1)) + 1; // [1, P-1] — nonzero mod P
+  const add = seed % RANDOM_MOD; // [0, P-1]
+  const expr = '((f.rand_key * $rmul + $radd) % $rmod)';
+  return {
+    orderBy: `${expr} ASC, f.id ASC`,
+    keysetWhere: `(${expr} > $curKey OR (${expr} = $curKey AND f.id > $curId))`,
+    key: (r) => Number((BigInt(r.rand_key) * BigInt(mul) + BigInt(add)) % BigInt(RANDOM_MOD)),
+    numericKey: true,
+    params: { $rmul: mul, $radd: add, $rmod: RANDOM_MOD },
+  };
+}
+
+/** The `lastViewed` sort: most-recently-opened first, never-viewed files (no ledger row) last via
+ * COALESCE(...,0), ties broken by id. LEFT JOIN keeps files with no view. */
+const LAST_VIEWED_SPEC: SortSpec = {
+  join: 'LEFT JOIN file_views v ON v.file_id = f.id',
+  selectExtra: 'COALESCE(v.viewed_at, 0) AS view_key',
+  orderBy: 'COALESCE(v.viewed_at, 0) DESC, f.id DESC',
+  keysetWhere:
+    '(COALESCE(v.viewed_at, 0) < $curKey OR (COALESCE(v.viewed_at, 0) = $curKey AND f.id < $curId))',
+  key: (r) => r.view_key ?? 0,
+  numericKey: true,
+};
+
+/** Per-sort SQL for the STATIC (parameter-free) orders. `recent` = newest first; `oldest` = oldest
+ * first; `name` = A→Z; `size` = largest first. `random` / `lastViewed` are built per-request above. */
+const SORT_SPECS: Record<'recent' | 'oldest' | 'name' | 'size', SortSpec> = {
+  recent: {
+    orderBy: 'f.created_at DESC, f.id DESC',
+    keysetWhere: '(f.created_at < $curKey OR (f.created_at = $curKey AND f.id < $curId))',
+    key: (r) => r.created_at,
+    numericKey: true,
+  },
+  oldest: {
+    orderBy: 'f.created_at ASC, f.id ASC',
+    keysetWhere: '(f.created_at > $curKey OR (f.created_at = $curKey AND f.id > $curId))',
+    key: (r) => r.created_at,
+    numericKey: true,
+  },
+  name: {
+    orderBy: 'f.name ASC, f.id ASC',
+    keysetWhere: '(f.name > $curKey OR (f.name = $curKey AND f.id > $curId))',
+    key: (r) => r.name,
+    numericKey: false,
+  },
+  size: {
+    orderBy: 'f.size DESC, f.id DESC',
+    keysetWhere: '(f.size < $curKey OR (f.size = $curKey AND f.id < $curId))',
+    key: (r) => r.size,
+    numericKey: true,
+  },
+};
+
+export type SqliteFileCatalogueOptions = {
+  db: Database;
+  store: MediaStore;
+  /** ffmpeg scratch dir for video processing. */
+  workDir: string;
+  /** HLS ladder heights for video ingest. */
+  ladderHeights?: number[];
+  /** Max transcode kicks per file (initial + recoverProcessing re-kicks) before the row is marked
+   * failed instead of re-kicked. Guards against a boot loop where the transcode itself kills the
+   * process (e.g. ffmpeg OOM on a small host) and every restart re-kicks the same job. Default 3. */
+  maxProcessingAttempts?: number;
+  /** Transcode uploaded videos into derivatives (faststart MP4 + HLS + poster + sprites).
+   * `false` skips ffmpeg entirely and marks videos ready to play raw (progressive Range) — the
+   * same graceful path as ffmpeg-unavailable. `'poster'` is the memory-constrained middle ground:
+   * skip the heavy HLS/re-encode ladder but still extract a cheap single-frame poster (grid gets
+   * thumbnails; raw source plays). Set `false`/`'poster'` on hosts where a full transcode can OOM
+   * the process. Default true. */
+  transcodeVideos?: boolean | 'poster';
+  /** Owner keyspace segment. Defaults to tenantId (a tenant-shared library). */
+  owner?: (ctx: MediaCtx) => string;
+  /** Injectable clock (tests). */
+  now?: () => number;
+  /** Per-row shuffle key generator for the `random` sort (a non-negative 31-bit int). Injectable
+   * for deterministic tests; defaults to a random 31-bit value per inserted file. */
+  randKey?: () => number;
+  /** Session shuffle-seed minter for the `random` sort's first page (a non-negative 31-bit int).
+   * Injectable for deterministic tests; defaults to a random 31-bit value. */
+  randomSeed?: () => number;
+  /** Video ingest→derivatives implementation (default: local ffmpeg via
+   * {@link processVideo}). Inject a remote one when the byte store is remote. */
+  videoProcessor?: VideoProcessor;
+  /** Image thumbnail/display derivative implementation (default: local sharp
+   * with ffmpeg fallback). Inject a remote one when the byte store is remote. */
+  imageDerivatives?: ImageDerivatives;
+};
+
+export function createSqliteFileCatalogue(
+  opts: SqliteFileCatalogueOptions,
+): FileCatalogue & PrivateFileCatalogue {
+  const { db, store, workDir } = opts;
+  const ownerOf = opts.owner ?? ((c: MediaCtx) => c.tenantId);
+  const now = opts.now ?? (() => Date.now());
+  const rand31 = () => Math.floor(Math.random() * RANDOM_MOD);
+  const randKey = opts.randKey ?? rand31;
+  const randomSeed = opts.randomSeed ?? rand31;
+
+  const insertFile = db.query(
+    `INSERT INTO files (id, owner, name, mime, size, file_type, is_private, processing_status, processing_progress, storage_backend, rand_key, created_at, updated_at)
+     VALUES ($id, $owner, $name, $mime, $size, $type, 0, $status, $progress, 'disk', $rand, $now, $now)`,
+  );
+  const insertTag = db.query(
+    `INSERT OR IGNORE INTO file_tags (file_id, tag, owner, is_private) VALUES ($file, $tag, $owner, 0)`,
+  );
+  const deleteTags = db.query(`DELETE FROM file_tags WHERE file_id = $file`);
+  const getRow = db.query<Row, { $id: string; $owner: string }>(
+    `SELECT * FROM files WHERE id = $id AND owner = $owner`,
+  );
+  const deleteFile = db.query(`DELETE FROM files WHERE id = $id AND owner = $owner`);
+  const trashFile = db.query(
+    `UPDATE files SET trashed_at = $now, updated_at = $now WHERE id = $id AND owner = $owner AND trashed_at IS NULL`,
+  );
+  const restoreFile = db.query(
+    `UPDATE files SET trashed_at = NULL, updated_at = $now WHERE id = $id AND owner = $owner`,
+  );
+  const setProcessing = db.query(
+    `UPDATE files SET processing_status = $status, processing_progress = $progress, updated_at = $now WHERE id = $id`,
+  );
+  const bumpProcessingAttempts = db.query(
+    `UPDATE files SET processing_attempts = processing_attempts + 1 WHERE id = $id`,
+  );
+  const maxProcessingAttempts = opts.maxProcessingAttempts ?? 3;
+  const setProcessed = db.query(
+    `UPDATE files SET processing_status = $status, processing_progress = 100, has_hls = $hls,
+       has_thumbnail = $thumb, has_sprites = $sprites, duration = $duration, updated_at = $now WHERE id = $id`,
+  );
+  const setMeta = db.query(
+    `UPDATE files SET name = $name, updated_at = $now WHERE id = $id AND owner = $owner`,
+  );
+  const setThumbnail = db.query(
+    `UPDATE files SET has_thumbnail = $thumb, updated_at = $now WHERE id = $id AND owner = $owner`,
+  );
+  // replaceContent: new bytes under the SAME id — identity (tags/collections/views) survives,
+  // byte-derived columns reset and re-derive.
+  const replaceMeta = db.query(
+    `UPDATE files SET name = $name, mime = $mime, size = $size, file_type = $type,
+       processing_status = $status, processing_progress = $progress,
+       has_hls = 0, has_thumbnail = 0, has_sprites = 0, duration = NULL, updated_at = $now
+     WHERE id = $id AND owner = $owner AND is_private = 0`,
+  );
+
+  // Private (encrypted) rows: name/tags are sealed in enc_name (sealedMeta); the wrapped AES-128
+  // content key is in enc_dek; enc_key_type records the wrap mode. is_private = 1 keeps them out of
+  // the public feed. These rows are surfaced to `mountPrivateRoutes` via `asPrivateIndex()`.
+  const insertPrivate = db.query(
+    `INSERT INTO files (id, owner, name, mime, size, file_type, is_private, has_hls, duration,
+       processing_status, processing_progress, storage_backend, enc_name, enc_dek, enc_key_type, rand_key, created_at, updated_at)
+     VALUES ($id, $owner, '', '', $size, $type, 1, 0, NULL, $status, $progress, 'disk', $sealed, $wrapped, $mode, $rand, $now, $now)`,
+  );
+  const finishPrivate = db.query(
+    `UPDATE files SET processing_status = $status, processing_progress = $progress, has_hls = $hls,
+       duration = $duration, size = $size, enc_name = $sealed, enc_dek = $wrapped, updated_at = $now WHERE id = $id`,
+  );
+  const getPrivateRow = db.query<PrivateRow, { $id: string; $owner: string }>(
+    `SELECT * FROM files WHERE id = $id AND owner = $owner AND is_private = 1`,
+  );
+  const listPrivateFullRows = db.query<PrivateRow, { $owner: string }>(
+    `SELECT * FROM files WHERE owner = $owner AND is_private = 1 ORDER BY created_at DESC, id DESC`,
+  );
+  const updatePrivateRow = db.query(
+    `UPDATE files SET size = $size, processing_status = $status, enc_name = $sealed, enc_dek = $wrapped,
+       enc_key_type = $mode, updated_at = $now WHERE id = $id AND owner = $owner AND is_private = 1`,
+  );
+  const deletePrivateRow = db.query(
+    `DELETE FROM files WHERE id = $id AND owner = $owner AND is_private = 1`,
+  );
+
+  // ── Collection prepared statements ───────────────────────────────────────────────
+  const insertCollection = db.query<
+    CollectionRow,
+    {
+      $id: string;
+      $owner: string;
+      $name: string;
+      $kind: string;
+      $visibility: string;
+      $now: number;
+    }
+  >(
+    `INSERT INTO file_collections (id, owner, name, kind, visibility, created_at, updated_at)
+     VALUES ($id, $owner, $name, $kind, $visibility, $now, $now)
+     RETURNING *`,
+  );
+  const getCollection = db.query<CollectionRow, { $id: string; $owner: string }>(
+    `SELECT * FROM file_collections WHERE id = $id AND owner = $owner`,
+  );
+  const getFavoritesCollection = db.query<CollectionRow, { $owner: string }>(
+    `SELECT * FROM file_collections WHERE owner = $owner AND kind = 'favorites'`,
+  );
+  const updateCollectionRow = db.query(
+    `UPDATE file_collections SET name = $name, visibility = $visibility, updated_at = $now
+     WHERE id = $id AND owner = $owner`,
+  );
+  const deleteCollection = db.query(
+    `DELETE FROM file_collections WHERE id = $id AND owner = $owner AND kind != 'favorites'`,
+  );
+  const deleteCollectionMembers = db.query(
+    `DELETE FROM file_collection_files WHERE collection_id = $id`,
+  );
+  // Membership manipulation — owner is enforced by joining against files.owner so a tenant can
+  // only add their own files.
+  const insertMember = db.query(
+    `INSERT OR IGNORE INTO file_collection_files (collection_id, file_id, owner, added_at)
+     SELECT $cid, f.id, f.owner, $now FROM files f
+     WHERE f.id = $fid AND f.owner = $owner`,
+  );
+  const deleteMember = db.query(
+    `DELETE FROM file_collection_files
+     WHERE collection_id = $cid AND file_id = $fid AND owner = $owner`,
+  );
+  // Remove all membership rows for a given file (used when the file itself is deleted).
+  const deleteFileMemberships = db.query(
+    `DELETE FROM file_collection_files WHERE file_id = $file AND owner = $owner`,
+  );
+
+  // View-event ledger: upsert the last-viewed timestamp + bump the count. The SELECT-from-files
+  // gate means a view can only be recorded for one of the caller's OWN files (unknown/other-owner
+  // ids insert nothing). Powers the `lastViewed` sort.
+  const recordViewStmt = db.query(
+    `INSERT INTO file_views (file_id, owner, viewed_at, view_count)
+     SELECT f.id, f.owner, $now, 1 FROM files f WHERE f.id = $id AND f.owner = $owner
+     ON CONFLICT(file_id) DO UPDATE SET viewed_at = excluded.viewed_at, view_count = view_count + 1`,
+  );
+  const deleteFileViews = db.query(`DELETE FROM file_views WHERE file_id = $file`);
+
+  const rowToPrivateItem = (r: PrivateRow, owner: string): PrivateItem => ({
+    id: r.id,
+    owner,
+    sizeBytes: r.size,
+    createdAt: r.created_at,
+    status: r.processing_status as ProcessingStatus,
+    keyMode: (r.enc_key_type || 'deniable') as PrivateItem['keyMode'],
+    wrappedContentKey: r.enc_dek,
+    sealedMeta: r.enc_name,
+  });
+
+  const tagsFor = (ids: string[]): Map<string, string[]> => {
+    const map = new Map<string, string[]>();
+    if (ids.length === 0) return map;
+    const placeholders = ids.map(() => '?').join(',');
+    const rows = db
+      .query<{ file_id: string; tag: string }, string[]>(
+        `SELECT file_id, tag FROM file_tags WHERE file_id IN (${placeholders}) ORDER BY tag`,
+      )
+      .all(...ids);
+    for (const r of rows) {
+      const list = map.get(r.file_id) ?? [];
+      list.push(r.tag);
+      map.set(r.file_id, list);
+    }
+    return map;
+  };
+
+  /** Batch-fetch collection memberships for a page of file ids. Returns a map of file_id →
+   * collection_ids[], and a separate Set of favorited file_ids (by their Favorites collection). */
+  const collectionsFor = (
+    owner: string,
+    fileIds: string[],
+  ): { collMap: Map<string, string[]>; favSet: Set<string> } => {
+    const collMap = new Map<string, string[]>();
+    const favSet = new Set<string>();
+    if (fileIds.length === 0) return { collMap, favSet };
+    const placeholders = fileIds.map(() => '?').join(',');
+    const rows = db
+      .query<{ file_id: string; collection_id: string; kind: string }, string[]>(
+        `SELECT fcf.file_id, fcf.collection_id, fc.kind
+         FROM file_collection_files fcf
+         JOIN file_collections fc ON fc.id = fcf.collection_id
+         WHERE fcf.file_id IN (${placeholders}) AND fcf.owner = ?`,
+      )
+      .all(...fileIds, owner);
+    for (const r of rows) {
+      const list = collMap.get(r.file_id) ?? [];
+      list.push(r.collection_id);
+      collMap.set(r.file_id, list);
+      if (r.kind === 'favorites') favSet.add(r.file_id);
+    }
+    return { collMap, favSet };
+  };
+
+  const rowToRecord = (
+    row: Row,
+    tags: string[],
+    collectionIds: string[],
+    favorite: boolean,
+  ): FileRecord => ({
+    id: row.id,
+    name: row.name,
+    mime: row.mime,
+    size: row.size,
+    fileType: row.file_type as FileType,
+    tags,
+    isPrivate: row.is_private === 1,
+    hasThumbnail: row.has_thumbnail === 1,
+    hasHls: row.has_hls === 1,
+    hasSprites: row.has_sprites === 1,
+    durationSeconds: row.duration ?? undefined,
+    processingStatus: row.processing_status as ProcessingStatus,
+    processingProgress: row.processing_progress,
+    favorite,
+    collectionIds,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    trashedAt: row.trashed_at ?? undefined,
+  });
+
+  const collectionRowToRecord = (row: CollectionRow, fileCount: number): FileCollection => ({
+    id: row.id,
+    name: row.name,
+    kind: row.kind as FileCollection['kind'],
+    visibility: row.visibility as CollectionVisibility,
+    fileCount,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  });
+
+  // A background job can outlive this catalogue's Database — a host shutting down mid-transcode,
+  // or a test teardown that closed the db after its settle timeout. The job's late progress/result
+  // writes must not crash the process (the rows they'd update are gone with the closed db, and
+  // recoverProcessing re-kicks anything left 'processing' on the next boot) — drop exactly the
+  // finalized/closed-statement failure, surface everything else.
+  const lateWrite = (write: () => void): void => {
+    try {
+      write();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (/finalized|closed/i.test(message)) return;
+      throw err;
+    }
+  };
+
+  // Fire-and-forget the transcode for a public video whose source sits at fsSourceKey; the row's
+  // processing columns flip to ready/failed when it finishes. Reused by ingest, registerUploaded,
+  // and recoverProcessing (re-kick after a restart lost an in-flight job).
+  // Returns a promise that resolves when the derivatives finish, so callers that must NOT run
+  // ffmpeg jobs concurrently (backfill on a memory-constrained host) can await + serialize. Normal
+  // ingest ignores the return value (fire-and-forget).
+  const kickVideoProcessing = (owner: string, id: string): Promise<void> => {
+    if (opts.transcodeVideos === false) {
+      // No derivatives at all: the raw source plays progressively, matching the ffmpeg-unavailable
+      // path. The strictest memory guard — not even a poster frame is decoded.
+      setProcessed.run({
+        $id: id,
+        $status: 'ready',
+        $hls: 0,
+        $thumb: 0,
+        $sprites: 0,
+        $duration: null,
+        $now: now(),
+      });
+      return Promise.resolve();
+    }
+    // transcodeVideos:'poster' = the memory-constrained-host sweet spot (2026-07-04 OOM guard). We
+    // skip the heavy HLS/re-encode ladder that OOM'd the box, but STILL extract a cheap single-frame
+    // poster so the grid keeps thumbnails and the player shows no "optimization failed" badge.
+    const posterOnly = opts.transcodeVideos === 'poster';
+    bumpProcessingAttempts.run({ $id: id });
+    return (opts.videoProcessor ?? processVideo)({
+      store,
+      workDir,
+      owner,
+      id,
+      sourceKey: fsSourceKey(owner, id),
+      ladderHeights: opts.ladderHeights,
+      posterOnly,
+      onProgress: (status, pct) =>
+        lateWrite(() =>
+          setProcessing.run({ $id: id, $status: status, $progress: pct, $now: now() }),
+        ),
+    }).then((res) => {
+      lateWrite(() =>
+        setProcessed.run({
+          $id: id,
+          $status: res.status,
+          $hls: res.hasHls ? 1 : 0,
+          $thumb: res.hasPoster ? 1 : 0,
+          $sprites: res.hasSprite ? 1 : 0,
+          $duration: res.durationSeconds || null,
+          $now: now(),
+        }),
+      );
+    });
+  };
+
+  // The local image-derivative implementation: sharp first (fast path), ffmpeg fallback for
+  // formats sharp's prebuilt binary can't decode (notably HEIC/HEVC iPhone photos). Browsers
+  // can't render HEIC either, so the JPEG poster is what the grid AND any <img> fallback display;
+  // non-renderable formats additionally get a full-size display JPEG for the lightbox.
+  const localImageDerivatives: ImageDerivatives = async (args) => {
+    const bytes = await args.store.get(args.binaryKey);
+    if (!bytes) return { hasThumbnail: false };
+    let thumb: Uint8Array | null = null;
+    try {
+      thumb = new Uint8Array(
+        await renderImage({
+          input: bytes,
+          operations: [{ type: 'resize', width: 512 }], // width-only ⇒ aspect preserved
+          output: { format: 'jpeg', quality: 78 },
+        }),
+      );
+    } catch {
+      thumb = await ffmpegImageThumbnail(bytes, args.workDir, args.id);
+    }
+    if (!thumb) return { hasThumbnail: false }; // both paths failed; leave has_thumbnail 0
+    await args.store.put(args.posterKey, thumb, 'image/jpeg');
+    // Write the display derivative BEFORE the caller flips has_thumbnail (the photo source only
+    // advertises the display URL once the poster flag is set — this ordering keeps it ready).
+    if (args.needsDisplay) {
+      const display = await ffmpegImageThumbnail(bytes, args.workDir, `${args.id}-display`, 2048);
+      if (display) await args.store.put(args.displayKey, display, 'image/jpeg');
+    }
+    return { hasThumbnail: true };
+  };
+
+  // Fire-and-forget a grid thumbnail for an image at the shared poster key (the poster serve
+  // route is type-agnostic). Best-effort: a failed derivative keeps has_thumbnail 0 and the UI
+  // falls back to the full image. Returns a promise so the backfill can serialize image jobs
+  // (mirrors kickVideoProcessing); normal ingest ignores it (fire-and-forget).
+  const kickImageThumbnail = (owner: string, id: string, mime: string): Promise<void> =>
+    (async () => {
+      const { hasThumbnail } = await (opts.imageDerivatives ?? localImageDerivatives)({
+        store,
+        workDir,
+        owner,
+        id,
+        mime,
+        binaryKey: fileBinaryKey(owner, id),
+        posterKey: fsPosterKey(owner, id),
+        displayKey: fsDisplayKey(owner, id),
+        needsDisplay: !isBrowserRenderableImage(mime),
+      });
+      if (!hasThumbnail) return;
+      setThumbnail.run({ $id: id, $owner: owner, $thumb: 1, $now: now() });
+    })().catch(() => {});
+
+  // Insert a public row + kick background processing (video transcode / image thumbnail). Shared
+  // by ingest (bytes stored here) and registerUploaded (bytes already at the key, e.g. a chunked
+  // upload direct to binary-server).
+  const finalizePublicRow = (
+    owner: string,
+    id: string,
+    meta: { name: string; mime: string; tags?: string[] },
+    size: number,
+    ts: number,
+  ): FileRecord => {
+    const isVideo = meta.mime.startsWith('video/');
+    db.transaction(() => {
+      insertFile.run({
+        $id: id,
+        $owner: owner,
+        $name: meta.name,
+        $mime: meta.mime,
+        $size: size,
+        $type: classifyFileType(meta.mime),
+        $status: isVideo ? 'processing' : 'ready',
+        $progress: isVideo ? 0 : 100,
+        $rand: randKey(),
+        $now: ts,
+      });
+      for (const tag of meta.tags ?? []) insertTag.run({ $file: id, $tag: tag, $owner: owner });
+    })();
+    if (isVideo) void kickVideoProcessing(owner, id);
+    else if (meta.mime.startsWith('image/')) void kickImageThumbnail(owner, id, meta.mime);
+    // Freshly ingested file has no collections yet.
+    return rowToRecord(getRow.get({ $id: id, $owner: owner }) as Row, meta.tags ?? [], [], false);
+  };
+
+  /** Lazily get-or-create the owner's Favorites collection. */
+  const getOrCreateFavorites = (owner: string, ts: number): CollectionRow => {
+    const existing = getFavoritesCollection.get({ $owner: owner });
+    if (existing) return existing;
+    const id = crypto.randomUUID();
+    const rows = insertCollection.all({
+      $id: id,
+      $owner: owner,
+      $name: 'Favorites',
+      $kind: 'favorites',
+      $visibility: 'normal',
+      $now: ts,
+    });
+    return rows[0] as CollectionRow;
+  };
+
+  const statsByType = db.query<{ file_type: string; n: number; bytes: number | null }, { $owner: string }>(
+    `SELECT file_type, COUNT(*) AS n, SUM(size) AS bytes FROM files
+     WHERE owner = $owner AND is_private = 0 GROUP BY file_type`,
+  );
+  const statsPrivate = db.query<{ n: number; bytes: number | null }, { $owner: string }>(
+    `SELECT COUNT(*) AS n, SUM(size) AS bytes FROM files WHERE owner = $owner AND is_private = 1`,
+  );
+  const statsStatus = db.query<{ processing_status: string; n: number }, { $owner: string }>(
+    `SELECT processing_status, COUNT(*) AS n FROM files
+     WHERE owner = $owner GROUP BY processing_status`,
+  );
+
+  return {
+    async stats(ctx) {
+      const owner = ownerOf(ctx);
+      const byType: Partial<Record<FileType, number>> = {};
+      let files = 0;
+      let bytes = 0;
+      for (const row of statsByType.all({ $owner: owner })) {
+        byType[row.file_type as FileType] = row.n;
+        files += row.n;
+        bytes += row.bytes ?? 0;
+      }
+      const priv = statsPrivate.get({ $owner: owner });
+      let processing = 0;
+      let failed = 0;
+      for (const row of statsStatus.all({ $owner: owner })) {
+        if (row.processing_status === 'processing' || row.processing_status === 'pending')
+          processing += row.n;
+        if (row.processing_status === 'failed') failed += row.n;
+      }
+      return {
+        files,
+        bytes,
+        byType,
+        privateItems: priv?.n ?? 0,
+        privateBytes: priv?.bytes ?? 0,
+        processing,
+        failed,
+      };
+    },
+    async list(ctx, options: ListFilesOptions = {}) {
+      const owner = ownerOf(ctx);
+      const limit = Math.min(options.limit ?? 40, 200);
+      const params: Record<string, string | number> = { $owner: owner, $limit: limit + 1 };
+      const where: string[] = [
+        'f.owner = $owner',
+        'f.is_private = 0',
+        options.trashedOnly ? 'f.trashed_at IS NOT NULL' : 'f.trashed_at IS NULL',
+      ];
+      let from = 'files f';
+
+      if (options.type) {
+        where.push('f.file_type = $type');
+        params.$type = options.type;
+      }
+      if (options.query) {
+        where.push('f.name LIKE $q');
+        params.$q = `%${options.query}%`;
+      }
+      if (options.tag) {
+        from = 'files f JOIN file_tags t ON t.file_id = f.id AND t.tag = $tag';
+        params.$tag = options.tag;
+      }
+      if (options.collectionId) {
+        // Unlock-gated collection: return empty page unless caller opts in.
+        const coll = db
+          .query<{ visibility: string }, { $id: string; $owner: string }>(
+            `SELECT visibility FROM file_collections WHERE id = $id AND owner = $owner`,
+          )
+          .get({ $id: options.collectionId, $owner: owner });
+        if (coll?.visibility === 'unlock' && !options.includeUnlockable) {
+          return { items: [] };
+        }
+        from = `files f JOIN file_collection_files fcf ON fcf.file_id = f.id AND fcf.collection_id = $cid`;
+        params.$cid = options.collectionId;
+      } else if (options.favorite) {
+        // Filter to files in the owner's Favorites collection.
+        const fav = getFavoritesCollection.get({ $owner: owner });
+        if (!fav) return { items: [] };
+        // Unlock-gated favorites: also respect the gate.
+        if (fav.visibility === 'unlock' && !options.includeUnlockable) return { items: [] };
+        from = `files f JOIN file_collection_files fcf ON fcf.file_id = f.id AND fcf.collection_id = $cid`;
+        params.$cid = fav.id;
+      }
+      const sort = options.sort ?? 'recent';
+      const cur = options.cursor ? decodeCursor(options.cursor) : null;
+      // `random` mints a shuffle seed on the first page and threads it through the cursor so every
+      // page reshuffles identically; `lastViewed` joins the view ledger; the rest are static specs.
+      let seed: number | undefined;
+      let spec: SortSpec;
+      if (sort === 'random') {
+        seed = cur?.seed ?? randomSeed();
+        spec = randomSortSpec(seed);
+      } else if (sort === 'lastViewed') {
+        spec = LAST_VIEWED_SPEC;
+      } else {
+        spec = SORT_SPECS[sort];
+      }
+      if (spec.join) from = `${from} ${spec.join}`;
+      if (spec.params) Object.assign(params, spec.params);
+      if (cur) {
+        where.push(spec.keysetWhere);
+        params.$curKey = spec.numericKey ? Number(cur.key) : cur.key;
+        params.$curId = cur.id;
+      }
+      const selectExtra = spec.selectExtra ? `, ${spec.selectExtra}` : '';
+
+      const rows = db
+        .query<Row, typeof params>(
+          `SELECT f.*${selectExtra} FROM ${from} WHERE ${where.join(' AND ')}
+           ORDER BY ${spec.orderBy} LIMIT $limit`,
+        )
+        .all(params);
+
+      const hasMore = rows.length > limit;
+      const page = hasMore ? rows.slice(0, limit) : rows;
+      const tags = tagsFor(page.map((r) => r.id));
+      const { collMap, favSet } = collectionsFor(
+        owner,
+        page.map((r) => r.id),
+      );
+      const result: FilePage = {
+        items: page.map((r) =>
+          rowToRecord(r, tags.get(r.id) ?? [], collMap.get(r.id) ?? [], favSet.has(r.id)),
+        ),
+      };
+      if (hasMore) {
+        const last = page[page.length - 1];
+        result.nextCursor = encodeCursor(spec.key(last), last.id, seed);
+      }
+      return result;
+    },
+
+    async get(ctx, id) {
+      const owner = ownerOf(ctx);
+      const row = getRow.get({ $id: id, $owner: owner });
+      if (!row) return null;
+      const { collMap, favSet } = collectionsFor(owner, [id]);
+      return rowToRecord(row, tagsFor([id]).get(id) ?? [], collMap.get(id) ?? [], favSet.has(id));
+    },
+
+    async tagFacets(ctx) {
+      const rows = db
+        .query<TagFacet, { $owner: string }>(
+          `SELECT tag, COUNT(*) as count FROM file_tags WHERE owner = $owner AND is_private = 0
+           GROUP BY tag ORDER BY count DESC, tag ASC`,
+        )
+        .all({ $owner: ownerOf(ctx) });
+      return rows;
+    },
+
+    async ingest(ctx, upload) {
+      const owner = ownerOf(ctx);
+      const id = crypto.randomUUID();
+      const isVideo = upload.mime.startsWith('video/');
+      // Video → stage the source for processing; other → store the primary binary directly.
+      const key = isVideo ? fsSourceKey(owner, id) : fileBinaryKey(owner, id);
+      await store.putStream(key, upload.body, upload.mime, { contentLength: upload.size });
+      const size = (await store.stat(key))?.size ?? upload.size ?? 0;
+      return finalizePublicRow(owner, id, upload, size, now());
+    },
+
+    async registerUploaded(ctx, upload) {
+      // Bytes were uploaded out-of-band (a chunked upload direct to binary-server) and already sit
+      // at the catalogue's key (fsSourceKey for video, fileBinaryKey otherwise). Just create the
+      // row + kick processing — no re-store. The caller owns having placed the bytes correctly.
+      return finalizePublicRow(ownerOf(ctx), upload.id, upload, upload.size, now());
+    },
+
+    async update(ctx, id, patch) {
+      const owner = ownerOf(ctx);
+      const row = getRow.get({ $id: id, $owner: owner });
+      if (!row) return null;
+      db.transaction(() => {
+        if (patch.name !== undefined)
+          setMeta.run({ $id: id, $owner: owner, $name: patch.name, $now: now() });
+        if (patch.tags !== undefined) {
+          deleteTags.run({ $file: id });
+          for (const tag of patch.tags) insertTag.run({ $file: id, $tag: tag, $owner: owner });
+        }
+      })();
+      const updated = getRow.get({ $id: id, $owner: owner }) as Row;
+      const { collMap, favSet } = collectionsFor(owner, [id]);
+      return rowToRecord(
+        updated,
+        tagsFor([id]).get(id) ?? [],
+        collMap.get(id) ?? [],
+        favSet.has(id),
+      );
+    },
+
+    async replaceContent(ctx, id, upload) {
+      const owner = ownerOf(ctx);
+      const row = getRow.get({ $id: id, $owner: owner });
+      if (!row) return null;
+      if (row.is_private === 1) {
+        throw new Error('replaceContent: private files cannot be replaced in place');
+      }
+      const isVideo = upload.mime.startsWith('video/');
+      // Store the new bytes FIRST — a failed write leaves the old row + bytes fully intact.
+      const key = isVideo ? fsSourceKey(owner, id) : fileBinaryKey(owner, id);
+      await store.putStream(key, upload.body, upload.mime, { contentLength: upload.size });
+      const size = (await store.stat(key))?.size ?? upload.size ?? 0;
+      // Wipe stale derivatives + the other-kind primary (all best-effort/idempotent), keeping the
+      // key the new bytes just landed at.
+      await Promise.all([
+        isVideo ? store.remove(fileBinaryKey(owner, id)) : store.remove(fsSourceKey(owner, id)),
+        store.remove(fsMp4Key(owner, id)),
+        store.remove(fsPosterKey(owner, id)),
+        store.remove(fsSpriteKey(owner, id)),
+        store.remove(fsVttKey(owner, id)),
+        store.removePrefix(fsHlsPrefix(owner, id)),
+      ]);
+      replaceMeta.run({
+        $id: id,
+        $owner: owner,
+        $name: upload.name ?? row.name,
+        $mime: upload.mime,
+        $size: size,
+        $type: classifyFileType(upload.mime),
+        $status: isVideo ? 'processing' : 'ready',
+        $progress: isVideo ? 0 : 100,
+        $now: now(),
+      });
+      if (isVideo) void kickVideoProcessing(owner, id);
+      else if (upload.mime.startsWith('image/')) void kickImageThumbnail(owner, id, upload.mime);
+      const updated = getRow.get({ $id: id, $owner: owner }) as Row;
+      const { collMap, favSet } = collectionsFor(owner, [id]);
+      return rowToRecord(
+        updated,
+        tagsFor([id]).get(id) ?? [],
+        collMap.get(id) ?? [],
+        favSet.has(id),
+      );
+    },
+
+    async remove(ctx, id) {
+      const owner = ownerOf(ctx);
+      // Remove every key this id can have — removes are idempotent, and images have a
+      // poster too (kickImageThumbnail writes fsPosterKey), so no video-only branching:
+      // branching here is what used to orphan image thumbnails on disk.
+      await Promise.all([
+        store.remove(fileBinaryKey(owner, id)),
+        store.remove(fsSourceKey(owner, id)),
+        store.remove(fsMp4Key(owner, id)),
+        store.remove(fsPosterKey(owner, id)),
+        store.remove(fsSpriteKey(owner, id)),
+        store.remove(fsVttKey(owner, id)),
+        store.removePrefix(fsHlsPrefix(owner, id)),
+      ]);
+      db.transaction(() => {
+        deleteTags.run({ $file: id });
+        deleteFileMemberships.run({ $file: id, $owner: owner });
+        deleteFileViews.run({ $file: id });
+        deleteFile.run({ $id: id, $owner: owner });
+      })();
+    },
+
+    async trash(ctx, id) {
+      trashFile.run({ $id: id, $owner: ownerOf(ctx), $now: now() });
+    },
+
+    async restore(ctx, id) {
+      restoreFile.run({ $id: id, $owner: ownerOf(ctx), $now: now() });
+    },
+
+    async importFromPath(ctx, absPath, importOpts) {
+      const owner = ownerOf(ctx);
+      const extraTags = importOpts?.tags ?? [];
+      const imported: FileRecord[] = [];
+      const skipped: { path: string; reason: string }[] = [];
+
+      const importOne = async (filePath: string, folderTag?: string): Promise<void> => {
+        let st: Awaited<ReturnType<typeof fsStat>>;
+        try {
+          st = await fsStat(filePath);
+        } catch (err) {
+          skipped.push({ path: filePath, reason: err instanceof Error ? err.message : String(err) });
+          return;
+        }
+        if (!st.isFile()) return; // symlinks/devices/etc. — directories are handled by the caller
+        const name = path.basename(filePath);
+        const mime = mimeByExt(name);
+        const tags = folderTag ? [...extraTags, folderTag] : extraTags;
+        try {
+          const id = crypto.randomUUID();
+          const isVideo = mime.startsWith('video/');
+          const key = isVideo ? fsSourceKey(owner, id) : fileBinaryKey(owner, id);
+          await store.putStream(key, Bun.file(filePath).stream(), mime, {
+            contentLength: st.size,
+          });
+          const size = (await store.stat(key))?.size ?? st.size;
+          imported.push(finalizePublicRow(owner, id, { name, mime, tags }, size, now()));
+        } catch (err) {
+          skipped.push({ path: filePath, reason: err instanceof Error ? err.message : String(err) });
+        }
+      };
+
+      let rootStat: Awaited<ReturnType<typeof fsStat>>;
+      try {
+        rootStat = await fsStat(absPath);
+      } catch (err) {
+        return {
+          imported: [],
+          skipped: [{ path: absPath, reason: err instanceof Error ? err.message : String(err) }],
+        };
+      }
+
+      if (rootStat.isFile()) {
+        await importOne(absPath);
+        return { imported, skipped };
+      }
+
+      // Directory: recurse, tagging each file with its immediate containing folder name so the
+      // origin structure survives as a (flat) tag facet rather than a tree the catalogue doesn't
+      // model. The top-level directory itself is NOT used as a tag (it's just the import root).
+      const walk = async (dir: string, isRoot: boolean): Promise<void> => {
+        let entries: Dirent[];
+        try {
+          entries = await readdir(dir, { withFileTypes: true, encoding: 'utf8' });
+        } catch (err) {
+          skipped.push({ path: dir, reason: err instanceof Error ? err.message : String(err) });
+          return;
+        }
+        const folderTag = isRoot ? undefined : path.basename(dir);
+        for (const entry of entries) {
+          const entryPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) await walk(entryPath, false);
+          else if (entry.isFile()) await importOne(entryPath, folderTag);
+        }
+      };
+      await walk(absPath, true);
+      return { imported, skipped };
+    },
+
+    recoverProcessing() {
+      // A restart mid-transcode leaves a row stuck in `processing`/`pending` — the in-process
+      // job is gone. For PUBLIC videos the source still sits at fsSourceKey, so re-kick the pipeline.
+      // PRIVATE rows can't be re-kicked at boot (the set key isn't available) — video or blob alike,
+      // mark them failed; the user re-unlocks + re-uploads. Public non-video rows are `ready` at
+      // insert and never appear here. (Ported from ca's recoverOnBoot; our jobs are in-process,
+      // so recovery is app-invoked at startup rather than a persistent queue.)
+      // Re-kicks are CAPPED at maxProcessingAttempts total kicks: if the transcode itself is what
+      // keeps killing the process (2026-07-04 prod outage: ffmpeg OOM on a 1GB host → systemd
+      // restart → unconditional re-kick → OOM again, forever), the row must land on `failed`
+      // instead of holding the whole service down.
+      const stuck = db
+        .query<{ id: string; owner: string; is_private: number; processing_attempts: number }, []>(
+          `SELECT id, owner, is_private, processing_attempts FROM files
+           WHERE (file_type = 'video' OR is_private = 1)
+             AND processing_status IN ('pending', 'processing')`,
+        )
+        .all();
+      let requeued = 0;
+      let failed = 0;
+      for (const r of stuck) {
+        if (r.is_private === 1 || r.processing_attempts >= maxProcessingAttempts) {
+          setProcessing.run({ $id: r.id, $status: 'failed', $progress: 0, $now: now() });
+          failed++;
+        } else {
+          void kickVideoProcessing(r.owner, r.id);
+          requeued++;
+        }
+      }
+      return { requeued, failed };
+    },
+
+    // Backfill grid thumbnails for PUBLIC video rows that finished (ready/failed) without a poster —
+    // e.g. rows that landed while transcodeVideos was off entirely, or that failed a full transcode
+    // before the poster step. Re-kicks the (now poster-capable) pipeline; the attempts counter is
+    // reset first so the maxProcessingAttempts cap doesn't pre-empt a fresh, cheaper poster-only run.
+    backfillVideoPosters(): { requeued: number } {
+      const missing = db
+        .query<{ id: string; owner: string }, []>(
+          `SELECT id, owner FROM files
+           WHERE file_type = 'video' AND is_private = 0 AND has_thumbnail = 0
+             AND processing_status IN ('ready', 'failed')`,
+        )
+        .all();
+      // Serialize: on the memory-constrained hosts this exists for, running every poster extract
+      // at once could spike RAM. Chain them so at most one ffmpeg job is live at a time.
+      void missing.reduce(async (prev, r) => {
+        await prev;
+        db.query(`UPDATE files SET processing_attempts = 0 WHERE id = $id`).run({ $id: r.id });
+        await kickVideoProcessing(r.owner, r.id).catch(() => {});
+      }, Promise.resolve());
+      return { requeued: missing.length };
+    },
+
+    // Backfill grid thumbnails for PUBLIC image rows with no poster — e.g. HEIC/HEVC iPhone photos
+    // whose sharp thumbnail silently failed before the ffmpeg fallback existed. Re-kicks the (now
+    // HEIC-capable) image pipeline, serialized so at most one ffmpeg decode runs at a time.
+    backfillImageThumbnails(): { requeued: number } {
+      // Candidates: images with no poster (has_thumbnail = 0), plus every browser-incompatible
+      // image (HEIC) — the latter may have a poster from before the display derivative existed but
+      // still lack the full-size display JPEG. The loop skips any HEIC whose display is already
+      // present, so a warm boot re-runs nothing.
+      const candidates = db
+        .query<{ id: string; owner: string; mime: string; has_thumbnail: number }, []>(
+          `SELECT id, owner, mime, has_thumbnail FROM files
+           WHERE file_type = 'image' AND is_private = 0
+             AND (has_thumbnail = 0 OR mime IN ('image/heic', 'image/heif'))`,
+        )
+        .all();
+      void candidates.reduce(async (prev, r) => {
+        await prev;
+        if (
+          r.has_thumbnail === 1 &&
+          !isBrowserRenderableImage(r.mime) &&
+          (await store.stat(fsDisplayKey(r.owner, r.id)))
+        )
+          return; // already fully derived — nothing to do
+        await kickImageThumbnail(r.owner, r.id, r.mime).catch(() => {});
+      }, Promise.resolve());
+      return { requeued: candidates.length };
+    },
+
+    // ── Collections ──────────────────────────────────────────────────────────────
+
+    async listCollections(ctx, opts2 = {}) {
+      const owner = ownerOf(ctx);
+      const visFilter = opts2.includeUnlockable ? '' : `AND fc.visibility != 'unlock'`;
+      const rows = db
+        .query<CollectionRow & { file_count: number }, { $owner: string }>(
+          `SELECT fc.*, COUNT(fcf.file_id) as file_count
+           FROM file_collections fc
+           LEFT JOIN file_collection_files fcf ON fcf.collection_id = fc.id
+           WHERE fc.owner = $owner ${visFilter}
+           GROUP BY fc.id
+           ORDER BY fc.kind DESC, fc.name ASC`,
+        )
+        .all({ $owner: owner });
+      return rows.map((r) => collectionRowToRecord(r, r.file_count));
+    },
+
+    async createCollection(ctx, input) {
+      const owner = ownerOf(ctx);
+      const name = input.name.trim();
+      if (!name) throw new Error('Collection name must not be empty');
+      const id = crypto.randomUUID();
+      const rows = insertCollection.all({
+        $id: id,
+        $owner: owner,
+        $name: name,
+        $kind: 'custom',
+        $visibility: input.visibility ?? 'normal',
+        $now: now(),
+      });
+      return collectionRowToRecord(rows[0] as CollectionRow, 0);
+    },
+
+    async updateCollection(ctx, id, patch) {
+      const owner = ownerOf(ctx);
+      const existing = getCollection.get({ $id: id, $owner: owner });
+      if (!existing) return null;
+      const newName = patch.name !== undefined ? patch.name.trim() : existing.name;
+      if (patch.name !== undefined && !newName)
+        throw new Error('Collection name must not be empty');
+      updateCollectionRow.run({
+        $id: id,
+        $owner: owner,
+        $name: newName,
+        $visibility: patch.visibility ?? existing.visibility,
+        $now: now(),
+      });
+      const updated = getCollection.get({ $id: id, $owner: owner }) as CollectionRow;
+      const count =
+        db
+          .query<{ c: number }, { $id: string }>(
+            `SELECT COUNT(*) as c FROM file_collection_files WHERE collection_id = $id`,
+          )
+          .get({ $id: id })?.c ?? 0;
+      return collectionRowToRecord(updated, count);
+    },
+
+    async removeCollection(ctx, id) {
+      const owner = ownerOf(ctx);
+      const existing = getCollection.get({ $id: id, $owner: owner });
+      if (!existing) return;
+      if (existing.kind === 'favorites')
+        throw new Error('The Favorites collection cannot be removed');
+      db.transaction(() => {
+        deleteCollectionMembers.run({ $id: id });
+        deleteCollection.run({ $id: id, $owner: owner });
+      })();
+    },
+
+    async addToCollection(ctx, collectionId, fileIds) {
+      const owner = ownerOf(ctx);
+      if (fileIds.length === 0) return;
+      const ts = now();
+      db.transaction(() => {
+        for (const fid of fileIds) {
+          insertMember.run({ $cid: collectionId, $fid: fid, $owner: owner, $now: ts });
+        }
+      })();
+    },
+
+    async removeFromCollection(ctx, collectionId, fileIds) {
+      const owner = ownerOf(ctx);
+      if (fileIds.length === 0) return;
+      db.transaction(() => {
+        for (const fid of fileIds) {
+          deleteMember.run({ $cid: collectionId, $fid: fid, $owner: owner });
+        }
+      })();
+    },
+
+    async setFavorite(ctx, fileId, favorite) {
+      const owner = ownerOf(ctx);
+      const ts = now();
+      const fav = getOrCreateFavorites(owner, ts);
+      if (favorite) {
+        insertMember.run({ $cid: fav.id, $fid: fileId, $owner: owner, $now: ts });
+      } else {
+        deleteMember.run({ $cid: fav.id, $fid: fileId, $owner: owner });
+      }
+    },
+
+    async recordView(ctx, fileId) {
+      // Upsert-gated to the caller's own files; unknown/other-owner ids record nothing.
+      recordViewStmt.run({ $id: fileId, $owner: ownerOf(ctx), $now: now() });
+    },
+
+    async ingestPrivate(ctx, upload, cfg) {
+      const owner = ownerOf(ctx);
+      const id = crypto.randomUUID();
+      const ts = now();
+      // Seal the descriptor NOW — sealing is independent of the transcode (only the wrapped content
+      // KEY needs the pipeline). Storing enc_name at insert means a try-a-password reveal matches the
+      // item immediately, before its HLS finishes encrypting (no seal race).
+      const descriptor: SealedDescriptor = {
+        name: upload.name,
+        mime: upload.mime,
+        tags: upload.tags ?? [],
+      };
+      const sealed = sealMeta(cfg.setKey, descriptor);
+      const isVideo = upload.mime.startsWith('video/');
+      insertPrivate.run({
+        $id: id,
+        $owner: owner,
+        $size: 0,
+        $type: classifyFileType(upload.mime),
+        $mode: cfg.keyMode,
+        $status: 'processing',
+        $progress: 0,
+        $sealed: sealed,
+        $wrapped: '',
+        $rand: randKey(),
+        $now: ts,
+      });
+
+      // Stage plaintext to a scratch file, then encrypt: video → AES-128 HLS ladder; anything
+      // else (photo/doc/audio) → one AES-128-CTR blob at privateSourceKey. Plaintext is never
+      // persisted either way. We MUST await: the wrapped key is produced by the pipeline and
+      // there is nothing to serve without it.
+      const srcPath = path.join(workDir, 'ingest', `${owner}-${id}.src`);
+      let size = 0;
+      try {
+        size = await streamToFile(upload.body, srcPath);
+        const res = isVideo
+          ? await processPrivateVideo({
+              store,
+              workDir,
+              owner,
+              id,
+              sourcePath: srcPath,
+              setKey: cfg.setKey,
+              ladderHeights: opts.ladderHeights,
+              onProgress: (status, pct) =>
+                setProcessing.run({ $id: id, $status: status, $progress: pct, $now: now() }),
+            })
+          : {
+              ...(await processPrivateBlob({
+                store,
+                owner,
+                id,
+                sourcePath: srcPath,
+                setKey: cfg.setKey,
+              })),
+              durationSeconds: 0,
+              hasHls: false,
+            };
+        finishPrivate.run({
+          $id: id,
+          $status: res.status,
+          $progress: res.status === 'ready' ? 100 : 0,
+          $hls: res.hasHls ? 1 : 0,
+          $duration: res.durationSeconds || null,
+          $size: size,
+          $sealed: sealed,
+          $wrapped: res.wrappedContentKey ?? '',
+          $now: now(),
+        });
+      } finally {
+        await rm(srcPath, { force: true }).catch(() => {});
+      }
+
+      const row = getRow.get({ $id: id, $owner: owner }) as Row;
+      return {
+        id,
+        size,
+        createdAt: ts,
+        processingStatus: row.processing_status as ProcessingStatus,
+        processingProgress: row.processing_progress,
+        hasHls: row.has_hls === 1,
+      };
+    },
+
+    asPrivateIndex(): PrivateIndex {
+      // A PrivateIndex view over the catalogue's private rows — the seam mountPrivateRoutes reads.
+      // `owner` here is the private owner axis the routes pass (a userId), matching how ingestPrivate
+      // stored the row (both go through the files.owner column).
+      return {
+        async add(item) {
+          insertPrivate.run({
+            $id: item.id,
+            $owner: item.owner,
+            $size: item.sizeBytes,
+            // External index writers predate blob items and only ever added videos.
+            $type: 'video',
+            $mode: item.keyMode,
+            $status: item.status,
+            $progress: item.status === 'ready' ? 100 : 0,
+            $sealed: item.sealedMeta,
+            $wrapped: item.wrappedContentKey,
+            $rand: randKey(),
+            $now: now(),
+          });
+        },
+        async get(owner, id) {
+          const row = getPrivateRow.get({ $id: id, $owner: owner });
+          return row ? rowToPrivateItem(row, owner) : null;
+        },
+        async list(owner) {
+          return listPrivateFullRows.all({ $owner: owner }).map((r) => rowToPrivateItem(r, owner));
+        },
+        async update(owner, id, patch) {
+          const cur = getPrivateRow.get({ $id: id, $owner: owner });
+          if (!cur) return;
+          const merged = { ...rowToPrivateItem(cur, owner), ...patch };
+          updatePrivateRow.run({
+            $id: id,
+            $owner: owner,
+            $size: merged.sizeBytes,
+            $status: merged.status,
+            $sealed: merged.sealedMeta,
+            $wrapped: merged.wrappedContentKey,
+            $mode: merged.keyMode,
+            $now: now(),
+          });
+        },
+        async remove(owner, id) {
+          await store.removePrefix(privateFsKey(owner, id));
+          deletePrivateRow.run({ $id: id, $owner: owner });
+        },
+      };
+    },
+  };
+}