cursedbelt 2.7.0 → 3.0.0

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

@@ -1,1326 +0,0 @@
-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 });
-        },
-      };
-    },
-  };
-}