cursedbelt-server 1.0.0

package/dist/server/storage/files/catalogue.js

@@ -0,0 +1,1033 @@
+import { mkdir, readdir, rm, stat as fsStat } from 'node:fs/promises';
+import path from 'node:path';
+import { renderImage } from '../../media-bun/image';
+import { sealMeta } from '../../private-media/crypto';
+import { processPrivateBlob, processPrivateVideo } from '../../private-media/pipeline';
+import { ffmpegImageThumbnail, isBrowserRenderableImage } from '../imageThumbnail';
+import { fsDisplayKey, fsHlsPrefix, fsMp4Key, fsPosterKey, fsSourceKey, fsSpriteKey, fsVttKey, privateFsKey, } from '../types';
+import { processVideo } from '../videoProcessor';
+import { mimeByExt } from './mimeByExt';
+import { classifyFileType, } from './types';
+// 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, dest) {
+    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, id) => `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, id, mime) => mime.startsWith('video/') ? fsSourceKey(owner, id) : fileBinaryKey(owner, id);
+const b64 = (s) => Buffer.from(s).toString('base64url');
+const unb64 = (s) => 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, id, seed) => b64(`${seed ?? ''}|${b64(String(key))}|${id}`);
+function decodeCursor(c) {
+    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;
+    }
+}
+// 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) {
+    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 = {
+    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 = {
+    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 function createSqliteFileCatalogue(opts) {
+    const { db, store, workDir } = opts;
+    const ownerOf = opts.owner ?? ((c) => 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(`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(`SELECT * FROM files WHERE id = $id AND owner = $owner AND is_private = 1`);
+    const listPrivateFullRows = db.query(`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(`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(`SELECT * FROM file_collections WHERE id = $id AND owner = $owner`);
+    const getFavoritesCollection = db.query(`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, owner) => ({
+        id: r.id,
+        owner,
+        sizeBytes: r.size,
+        createdAt: r.created_at,
+        status: r.processing_status,
+        keyMode: (r.enc_key_type || 'deniable'),
+        wrappedContentKey: r.enc_dek,
+        sealedMeta: r.enc_name,
+    });
+    const tagsFor = (ids) => {
+        const map = new Map();
+        if (ids.length === 0)
+            return map;
+        const placeholders = ids.map(() => '?').join(',');
+        const rows = db
+            .query(`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, fileIds) => {
+        const collMap = new Map();
+        const favSet = new Set();
+        if (fileIds.length === 0)
+            return { collMap, favSet };
+        const placeholders = fileIds.map(() => '?').join(',');
+        const rows = db
+            .query(`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, tags, collectionIds, favorite) => ({
+        id: row.id,
+        name: row.name,
+        mime: row.mime,
+        size: row.size,
+        fileType: row.file_type,
+        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,
+        processingProgress: row.processing_progress,
+        favorite,
+        collectionIds,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        trashedAt: row.trashed_at ?? undefined,
+    });
+    const collectionRowToRecord = (row, fileCount) => ({
+        id: row.id,
+        name: row.name,
+        kind: row.kind,
+        visibility: row.visibility,
+        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) => {
+        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, id) => {
+        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 = async (args) => {
+        const bytes = await args.store.get(args.binaryKey);
+        if (!bytes)
+            return { hasThumbnail: false };
+        let thumb = 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, id, mime) => (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, id, meta, size, ts) => {
+        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 }), meta.tags ?? [], [], false);
+    };
+    /** Lazily get-or-create the owner's Favorites collection. */
+    const getOrCreateFavorites = (owner, ts) => {
+        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];
+    };
+    const statsByType = db.query(`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(`SELECT COUNT(*) AS n, SUM(size) AS bytes FROM files WHERE owner = $owner AND is_private = 1`);
+    const statsStatus = db.query(`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 = {};
+            let files = 0;
+            let bytes = 0;
+            for (const row of statsByType.all({ $owner: owner })) {
+                byType[row.file_type] = 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 = {}) {
+            const owner = ownerOf(ctx);
+            const limit = Math.min(options.limit ?? 40, 200);
+            const params = { $owner: owner, $limit: limit + 1 };
+            const where = [
+                '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(`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;
+            let spec;
+            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(`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 = {
+                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(`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 });
+            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 });
+            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 = [];
+            const skipped = [];
+            const importOne = async (filePath, folderTag) => {
+                let st;
+                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;
+            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, isRoot) => {
+                let entries;
+                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(`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() {
+            const missing = db
+                .query(`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() {
+            // 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(`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(`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], 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 });
+            const count = db
+                .query(`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 = {
+                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 });
+            return {
+                id,
+                size,
+                createdAt: ts,
+                processingStatus: row.processing_status,
+                processingProgress: row.processing_progress,
+                hasHls: row.has_hls === 1,
+            };
+        },
+        asPrivateIndex() {
+            // 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 });
+                },
+            };
+        },
+    };
+}