cursedbelt-server 1.0.0

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

@@ -0,0 +1,163 @@
+// Schema for the FileCatalogue. Runs through cursedbelt's migration runner (idempotent, recorded
+// in `_migrations`). Improves on ca's fs_nodes: the smart-view `file_type` is stored + indexed
+// (not re-derived per list), tags live in an indexed junction (fast facets, not a JSON scan),
+// processing state is typed columns (not an opaque blob), and a storage-operations ledger backs
+// durable cross-boundary (binary-server/S3) ops. Flat — no parent_id tree.
+export const FILE_CATALOGUE_MIGRATIONS = [
+    {
+        name: '0001_file_catalogue',
+        up(db) {
+            db.run(`
+        CREATE TABLE IF NOT EXISTS files (
+          id                  TEXT PRIMARY KEY,
+          owner               TEXT NOT NULL,
+          name                TEXT NOT NULL DEFAULT '',
+          mime                TEXT NOT NULL DEFAULT '',
+          size                INTEGER NOT NULL DEFAULT 0,
+          file_type           TEXT NOT NULL DEFAULT 'other',
+          is_private          INTEGER NOT NULL DEFAULT 0,
+          has_thumbnail       INTEGER NOT NULL DEFAULT 0,
+          has_hls             INTEGER NOT NULL DEFAULT 0,
+          has_sprites         INTEGER NOT NULL DEFAULT 0,
+          duration            REAL,
+          processing_status   TEXT NOT NULL DEFAULT 'ready',
+          processing_progress INTEGER NOT NULL DEFAULT 100,
+          storage_backend     TEXT NOT NULL DEFAULT 'disk',
+          enc_name            TEXT NOT NULL DEFAULT '',
+          enc_dek             TEXT NOT NULL DEFAULT '',
+          enc_key_type        TEXT NOT NULL DEFAULT '',
+          created_at          INTEGER NOT NULL,
+          updated_at          INTEGER NOT NULL
+        )
+      `);
+            // Listing is cursor-keyed on (created_at, id); these cover the flat feed + smart-view filter.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_files_owner_created ON files(owner, created_at DESC, id DESC)`);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_files_owner_type_created ON files(owner, file_type, created_at DESC, id DESC)`);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_files_owner_private ON files(owner, is_private)`);
+            // Tags as a junction (indexed) — single-tag filter + facet counts are index lookups, not a
+            // full-table JSON parse (ca's weakness). `owner` denormalized so facet queries stay covering.
+            db.run(`
+        CREATE TABLE IF NOT EXISTS file_tags (
+          file_id TEXT NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+          tag     TEXT NOT NULL,
+          owner   TEXT NOT NULL,
+          is_private INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (file_id, tag)
+        )
+      `);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_file_tags_owner_tag ON file_tags(owner, tag)`);
+            // Durable ledger for cross-boundary storage ops (binary-server/S3 put/delete) — the
+            // reconciler heals `pending` rows the server never got an ack for.
+            db.run(`
+        CREATE TABLE IF NOT EXISTS storage_operations (
+          op_id      TEXT PRIMARY KEY,
+          owner      TEXT NOT NULL,
+          file_id    TEXT,
+          action     TEXT NOT NULL,
+          key        TEXT NOT NULL,
+          backend    TEXT NOT NULL,
+          status     TEXT NOT NULL DEFAULT 'pending',
+          attempts   INTEGER NOT NULL DEFAULT 0,
+          error      TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )
+      `);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_storage_ops_status ON storage_operations(status, created_at)`);
+        },
+    },
+    {
+        name: '0002_file_collections',
+        up(db) {
+            // Collections (Apple-Photos-style groupings). kind='favorites' is a system singleton per owner;
+            // kind='custom' are user-defined. visibility='unlock' hides the collection unless explicitly
+            // requested (like a private shelf). Membership is in file_collection_files; files are never
+            // deleted by removing a collection.
+            db.run(`
+        CREATE TABLE IF NOT EXISTS file_collections (
+          id         TEXT PRIMARY KEY,
+          owner      TEXT NOT NULL,
+          name       TEXT NOT NULL,
+          kind       TEXT NOT NULL DEFAULT 'custom',
+          visibility TEXT NOT NULL DEFAULT 'normal',
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )
+      `);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_file_collections_owner ON file_collections(owner, name)`);
+            // Unique partial index: at most one 'favorites' collection per owner.
+            db.run(`CREATE UNIQUE INDEX IF NOT EXISTS idx_file_collections_owner_favorites
+         ON file_collections(owner) WHERE kind = 'favorites'`);
+            // Junction: which files belong to which collection. owner is denormalized so membership
+            // queries can stay covering without a join back to files. Foreign-key cascades are declared
+            // but SQLite's FK pragma may be off at runtime, so catalogue.remove() explicitly cleans
+            // file_collection_files rows (matching the file_tags pattern).
+            db.run(`
+        CREATE TABLE IF NOT EXISTS file_collection_files (
+          collection_id TEXT NOT NULL REFERENCES file_collections(id) ON DELETE CASCADE,
+          file_id       TEXT NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+          owner         TEXT NOT NULL,
+          added_at      INTEGER NOT NULL,
+          PRIMARY KEY (collection_id, file_id)
+        )
+      `);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_fcf_owner_file ON file_collection_files(owner, file_id)`);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_fcf_collection ON file_collection_files(collection_id, added_at DESC)`);
+        },
+    },
+    {
+        name: '0003_file_sort_indexes',
+        up(db) {
+            // Keyset pagination under the `name` / `size` sorts stays an index walk, mirroring
+            // idx_files_owner_created for the default `recent` sort.
+            db.run(`CREATE INDEX IF NOT EXISTS idx_files_owner_name ON files(owner, name ASC, id ASC)`);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_files_owner_size ON files(owner, size DESC, id DESC)`);
+        },
+    },
+    {
+        name: '0004_file_random_and_views',
+        up(db) {
+            // Per-row stable random key backing the seeded `random` gallery order. A session mints a
+            // seed (folded into the cursor); the sort key is `rand_key` remapped by that seed, so the
+            // order is a stable total order for keyset pagination while each visit reshuffles. ADD COLUMN
+            // can't take a non-constant DEFAULT, so seed existing rows here; new rows set it at insert.
+            db.run(`ALTER TABLE files ADD COLUMN rand_key INTEGER NOT NULL DEFAULT 0`);
+            // random() is a 64-bit int; mask to a non-negative 31-bit value so the seeded remap
+            // (rand_key * mul + add) stays well inside SQLite's signed-64-bit integer range.
+            db.run(`UPDATE files SET rand_key = (random() & 2147483647)`);
+            // View-event ledger: last-viewed timestamp + count per file, powering the `lastViewed` sort.
+            // One row per file (upserted on each open). owner is denormalized so the sort's join stays
+            // owner-scoped. FK cascade is declared but the pragma may be off, so catalogue.remove() also
+            // cleans these rows explicitly (matching the file_tags / file_collection_files pattern).
+            db.run(`
+        CREATE TABLE IF NOT EXISTS file_views (
+          file_id    TEXT PRIMARY KEY REFERENCES files(id) ON DELETE CASCADE,
+          owner      TEXT NOT NULL,
+          viewed_at  INTEGER NOT NULL,
+          view_count INTEGER NOT NULL DEFAULT 0
+        )
+      `);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_file_views_owner_viewed ON file_views(owner, viewed_at DESC)`);
+        },
+    },
+    {
+        name: '0005_processing_attempts',
+        up(db) {
+            // Counts transcode kicks per file so recoverProcessing can stop re-kicking a job that
+            // keeps dying (e.g. ffmpeg OOM-killed on a small host → service restart → re-kick loop).
+            db.run(`ALTER TABLE files ADD COLUMN processing_attempts INTEGER NOT NULL DEFAULT 0`);
+        },
+    },
+    {
+        name: '0006_file_trash',
+        up(db) {
+            // Trash-first delete: `trash()` sets trashed_at instead of dropping the row, so a mistaken
+            // delete is recoverable via `restore()`. `remove()` stays the PERMANENT hard-delete — now a
+            // deliberate second action (typically only invoked on an already-trashed row) rather than the
+            // primary delete path. `list()` excludes trashed rows by default (NULL check stays an index
+            // hit); pass `trashedOnly` to browse the trash bin itself.
+            db.run(`ALTER TABLE files ADD COLUMN trashed_at INTEGER`);
+            db.run(`CREATE INDEX IF NOT EXISTS idx_files_owner_trashed ON files(owner, trashed_at)`);
+        },
+    },
+];

package/dist/server/storage/files/mimeByExt.d.ts

@@ -0,0 +1 @@
+export declare function mimeByExt(name: string): string;

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

@@ -0,0 +1,13 @@
+import { mimeForFilename } from 'cwip/string';
+// Ext → mime for local-disk import (catalogue.importFromPath) — the catalogue needs SOME mime
+// to classify + serve a file that never passed through a browser's upload Content-Type.
+//
+// The table itself moved DOWN to `cwip/string`'s `fileKind` (2026-07-31): the viewer UI and the
+// notes ingest pipeline need the same knowledge, and cwip is the only layer all three can read
+// from. This wrapper stays so existing server call sites keep working; it is now one line, and
+// the lookup it delegates to is a superset of what used to live here (code, data, archive and
+// markup types the old table lacked). Unknown still falls back to 'application/octet-stream',
+// which `classifyFileType` maps to 'other' — importable, just without image/video processing.
+export function mimeByExt(name) {
+    return mimeForFilename(name);
+}

package/dist/server/storage/files/stack.d.ts

@@ -0,0 +1,136 @@
+import type { Database } from 'bun:sqlite';
+import type { Context, Hono } from 'hono';
+import { type UnlockPasswordPolicy, type UnlockService } from '../../private-media/unlock';
+import { type MediaUrls, SourceRegistry } from '../sources';
+import { type StreamTokenService } from '../streamToken';
+import type { MediaCtx, MediaGallerySource, MediaSource, MediaStore, PhotoSource } from '../types';
+import { type SqliteFileCatalogueOptions } from './catalogue';
+import { type ChunkedUploadService, type MintChunkUpload } from './chunkedUpload';
+import { type FileUrls } from './fileRoutes';
+import type { FileCatalogue, PrivateFileCatalogue } from './types';
+export interface FilesStackOptions {
+    /** The catalogue database. The stack runs FILE_CATALOGUE_MIGRATIONS on it itself. */
+    db: Database;
+    /** Byte backend (disk / binary-server / s3) — the swappable piece. */
+    store: MediaStore;
+    /** ffmpeg scratch dir for video processing. */
+    workDir: string;
+    /** Secret for the stream-token service (path-embedded byte-route auth). */
+    streamSecret: string;
+    /** Owner keyspace segment. Defaults to the userId (files + private are personal) — note the
+     * bare primitives default to tenantId; the stack picks the personal axis so every URL/route
+     * agrees with the private layer's per-user owner. */
+    owner?: (ctx: MediaCtx) => string;
+    /** Registered video-source id (also the media-token sourceId). Default 'files'. */
+    sourceId?: string;
+    /** Video source display title. Default 'Files'. */
+    sourceTitle?: string;
+    /** Registered photo-source id (the image-filtered view; also its media-token sourceId).
+     * Default 'photos'. */
+    photoSourceId?: string;
+    /** Photo source display title. Default 'Photos'. */
+    photoSourceTitle?: string;
+    /** Video byte-route mount + URL base (path-only). Default '/_media'. */
+    mediaBasePath?: string;
+    /** General file byte/upload route mount + URL base (path-only). Default '/_files'. */
+    filesBasePath?: string;
+    /** PUBLIC base for browser media URLs when it differs from the mount path — a split-origin
+     * deploy (SPA on the apex, API on a subdomain) passes the absolute origin+path here
+     * ('https://api.example.com/_media') while `mediaBasePath` stays the path-only mount. */
+    mediaPublicBase?: string;
+    /** PUBLIC base for browser file URLs (split-origin counterpart of `filesBasePath`). */
+    filesPublicBase?: string;
+    /** Private (encrypted) route mount. Default '/_private'. */
+    privateBasePath?: string;
+    /** HLS ladder heights for video ingest (createSqliteFileCatalogue passthrough). */
+    ladderHeights?: SqliteFileCatalogueOptions['ladderHeights'];
+    /** Cap on transcode kicks per file before it's marked failed (createSqliteFileCatalogue
+     * passthrough) — the boot-loop guard. Default 3. */
+    maxProcessingAttempts?: SqliteFileCatalogueOptions['maxProcessingAttempts'];
+    /** Transcode uploaded videos (createSqliteFileCatalogue passthrough). `false` ⇒ videos play
+     * raw, no ffmpeg — for memory-constrained hosts. Default true. */
+    transcodeVideos?: SqliteFileCatalogueOptions['transcodeVideos'];
+    /** Video ingest→derivatives implementation (createSqliteFileCatalogue passthrough) — inject
+     * a remote one (binary-server) when the byte store is remote. Default: local ffmpeg. */
+    videoProcessor?: SqliteFileCatalogueOptions['videoProcessor'];
+    /** Image thumbnail/display derivative implementation (createSqliteFileCatalogue passthrough).
+     * Default: local sharp with ffmpeg fallback. */
+    imageDerivatives?: SqliteFileCatalogueOptions['imageDerivatives'];
+    /** Enables the private (encrypted) stack: unlock service + /_private routes + private uploads.
+     * Omit ⇒ `unlock` is null and mount() wires only the public routes. `passwordPolicy` sets what
+     * a supplied password MEANS (derive = deniable sets, the default; gate = verify against the
+     * app's accounts + recoverable server-key sets — see UnlockPasswordPolicy). */
+    privateMedia?: {
+        serverSecret: string;
+        unlockSecret: string;
+        passwordPolicy?: UnlockPasswordPolicy;
+    };
+    /** Re-kick transcodes a restart left stuck (catalogue.recoverProcessing) at build time.
+     * Default true. */
+    recoverProcessing?: boolean;
+    /** Backfill grid thumbnails at build time for finished PUBLIC rows missing a poster — videos
+     * (landed while transcodeVideos was off / failed before the poster step) AND images (e.g. HEIC
+     * whose sharp thumbnail failed before the ffmpeg fallback). Default false. */
+    backfillPosters?: boolean;
+    /** Wire LARGE-file chunked uploads (direct-to-backend). Give the backend-specific per-chunk URL
+     * minter (for binary-server: a signed `${base}/upload-chunk/${app}/${key}?token=`) and the stack
+     * builds the ChunkedUploadService over its own catalogue + a storage-ops ledger on `db`, then
+     * mount() auto-wires the /upload-init, /upload-complete, /upload-abort routes. Omit ⇒ chunked is
+     * off and clients fall back to the streamed single PUT (disk-only deploys). */
+    chunkedUpload?: {
+        mintChunkUpload: MintChunkUpload;
+        /** Byte-backend label recorded on each ledger op. Default 'binary'. */
+        backend?: string;
+        /** Per-chunk size. Default DEFAULT_UPLOAD_CHUNK_SIZE (8 MiB), always < MAX_SINGLE_UPLOAD_BYTES. */
+        chunkSize?: number;
+    };
+}
+/** The auth seams `mount()` needs from the host — the only pieces the stack cannot own. */
+export interface FilesStackMountAuth {
+    /** Session auth for uploads + listings (same guard mountMediaRoutes/mountFileRoutes take).
+     * Return a MediaCtx to allow, null to reject. */
+    authorizeUpload: (c: Context) => Promise<MediaCtx | null> | MediaCtx | null;
+    /** Session auth for the private layer → {userId, userSalt}. REQUIRED when `privateMedia` is
+     * configured (mount() throws otherwise); ignored when it isn't. */
+    authorizePrivate?: (c: Context) => Promise<{
+        userId: string;
+        userSalt: string;
+    } | null>;
+    /** Wire large-file chunked uploads (mountFileRoutes' `chunked` passthrough). */
+    mintChunkUpload?: ChunkedUploadService;
+    /** Private-upload password header (default 'x-private-password'). */
+    passwordHeader?: string;
+    /** Private-upload unlock-token header (default 'x-unlock-token'). */
+    tokenHeader?: string;
+}
+/**
+ * The assembled stack. `catalogue` / `fileUrls` / `mediaUrls` / `videoSource` are intentionally
+ * named so a cursedshell host can pass the stack straight into `createFilesPlugin(stack)`
+ * structurally, and `{ registry }` into `createGalleryPlugin` — the stack does not (and must
+ * not, layering) import cursedshell.
+ */
+export interface FilesStack {
+    catalogue: FileCatalogue & PrivateFileCatalogue;
+    token: StreamTokenService;
+    mediaUrls: MediaUrls;
+    fileUrls: FileUrls;
+    videoSource: MediaSource;
+    /** The image-filtered sibling view (photo gallery data source). */
+    photoSource: PhotoSource;
+    /** The MIXED view — photos + videos in one feed (media gallery data source). */
+    mediaSource: MediaGallerySource;
+    registry: SourceRegistry;
+    /** Null unless `privateMedia` was configured. */
+    unlock: UnlockService | null;
+    /** The large-file chunked-upload service, or null unless `chunkedUpload` was configured. mount()
+     * auto-wires it into the file routes; exposed for observability (pending()) + tests. */
+    chunked: ChunkedUploadService | null;
+    /**
+     * Mount every byte/upload route the stack owns onto a Hono app: mountMediaRoutes
+     * (mediaBasePath) + mountFileRoutes (filesBasePath, incl. privateUpload when unlock exists) +
+     * mountPrivateRoutes (privateBasePath, when unlock exists). Auth stays host-injected.
+     */
+    mount(app: Hono, auth: FilesStackMountAuth): void;
+}
+/** Assemble the whole files/media server stack from one options bag. See {@link FilesStack}. */
+export declare function createFilesStack(opts: FilesStackOptions): FilesStack;

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

@@ -0,0 +1,132 @@
+import { runMigrations } from '../../migration/runner';
+import { mountPrivateRoutes } from '../../private-media/mountPrivateRoutes';
+import { createUnlockService, } from '../../private-media/unlock';
+import { mountMediaRoutes } from '../mountMediaRoutes';
+import { createMediaUrls, SourceRegistry } from '../sources';
+import { createStreamTokenService } from '../streamToken';
+import { createCatalogueMediaSource, createCataloguePhotoSource, createCatalogueVideoSource, } from './adapter';
+import { createSqliteFileCatalogue } from './catalogue';
+import { createChunkedUploadService, } from './chunkedUpload';
+import { createFileUrls, mountFileRoutes } from './fileRoutes';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import { createStorageOpsLedger } from './storageOps';
+/** Assemble the whole files/media server stack from one options bag. See {@link FilesStack}. */
+export function createFilesStack(opts) {
+    const owner = opts.owner ?? ((c) => c.userId);
+    const sourceId = opts.sourceId ?? 'files';
+    const mediaBasePath = opts.mediaBasePath ?? '/_media';
+    const filesBasePath = opts.filesBasePath ?? '/_files';
+    const { db, store, workDir } = opts;
+    const token = createStreamTokenService({ secret: opts.streamSecret });
+    const mediaUrls = createMediaUrls({
+        baseUrl: opts.mediaPublicBase ?? mediaBasePath,
+        token,
+        owner,
+    });
+    const fileUrls = createFileUrls({ baseUrl: opts.filesPublicBase ?? filesBasePath, token, owner });
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    const catalogue = createSqliteFileCatalogue({
+        db,
+        store,
+        workDir,
+        owner,
+        ladderHeights: opts.ladderHeights,
+        maxProcessingAttempts: opts.maxProcessingAttempts,
+        transcodeVideos: opts.transcodeVideos,
+        videoProcessor: opts.videoProcessor,
+        imageDerivatives: opts.imageDerivatives,
+    });
+    if (opts.recoverProcessing !== false)
+        catalogue.recoverProcessing();
+    if (opts.backfillPosters) {
+        catalogue.backfillVideoPosters();
+        catalogue.backfillImageThumbnails();
+    }
+    const videoSource = createCatalogueVideoSource({
+        id: sourceId,
+        title: opts.sourceTitle ?? 'Files',
+        catalogue,
+        urls: mediaUrls,
+    });
+    const photoSource = createCataloguePhotoSource({
+        id: opts.photoSourceId ?? 'photos',
+        title: opts.photoSourceTitle ?? 'Photos',
+        catalogue,
+        fileUrls,
+        mediaUrls,
+    });
+    const mediaSource = createCatalogueMediaSource({
+        id: opts.photoSourceId ?? 'photos',
+        title: 'Media',
+        catalogue,
+        urls: mediaUrls,
+        fileUrls,
+        // Videos in the mixed feed stream through the registered video source's routes.
+        videoSourceId: sourceId,
+    });
+    const registry = new SourceRegistry().register(videoSource);
+    const unlock = opts.privateMedia ? createUnlockService(opts.privateMedia) : null;
+    const chunked = opts.chunkedUpload
+        ? createChunkedUploadService({
+            catalogue,
+            ledger: createStorageOpsLedger(db),
+            backend: opts.chunkedUpload.backend ?? 'binary',
+            mintChunkUpload: opts.chunkedUpload.mintChunkUpload,
+            chunkSize: opts.chunkedUpload.chunkSize,
+            owner,
+        })
+        : null;
+    return {
+        catalogue,
+        token,
+        mediaUrls,
+        fileUrls,
+        videoSource,
+        photoSource,
+        mediaSource,
+        registry,
+        unlock,
+        chunked,
+        mount(app, auth) {
+            if (unlock && !auth.authorizePrivate) {
+                throw new Error('createFilesStack: privateMedia is configured but mount() got no authorizePrivate — ' +
+                    'the private routes need a session→{userId, userSalt} resolver.');
+            }
+            mountMediaRoutes(app, {
+                store,
+                token,
+                basePath: mediaBasePath,
+                registry,
+                authorizeUpload: auth.authorizeUpload,
+            });
+            mountFileRoutes(app, {
+                store,
+                token,
+                basePath: filesBasePath,
+                catalogue,
+                authorizeUpload: auth.authorizeUpload,
+                // Prefer a mount-time override, else the service the stack built from `chunkedUpload` opts.
+                chunked: auth.mintChunkUpload ?? chunked ?? undefined,
+                privateUpload: unlock && auth.authorizePrivate
+                    ? {
+                        unlock,
+                        authorize: auth.authorizePrivate,
+                        passwordHeader: auth.passwordHeader,
+                        tokenHeader: auth.tokenHeader,
+                        passwordPolicy: opts.privateMedia?.passwordPolicy,
+                    }
+                    : undefined,
+            });
+            if (unlock && auth.authorizePrivate) {
+                mountPrivateRoutes(app, {
+                    store,
+                    index: catalogue.asPrivateIndex(),
+                    unlock,
+                    basePath: opts.privateBasePath,
+                    authorize: auth.authorizePrivate,
+                    passwordPolicy: opts.privateMedia?.passwordPolicy,
+                });
+            }
+        },
+    };
+}

package/dist/server/storage/files/storageOps.d.ts

@@ -0,0 +1,54 @@
+import type { Database } from 'bun:sqlite';
+import type { MediaStore } from '../types';
+export type StorageAction = 'upload' | 'delete' | 'delete_prefix';
+export type StorageOpStatus = 'pending' | 'done' | 'failed';
+export type StorageOpRow = {
+    opId: string;
+    owner: string;
+    fileId: string | null;
+    action: StorageAction;
+    key: string;
+    backend: string;
+    status: StorageOpStatus;
+    attempts: number;
+    error: string | null;
+    createdAt: number;
+    updatedAt: number;
+};
+export interface StorageOpsLedger {
+    /** Record a pending op and return its id (caller may pass one, e.g. to share with binary-server
+     * as `x-op-id`; otherwise a uuid is minted). */
+    record(op: {
+        owner: string;
+        fileId?: string | null;
+        action: StorageAction;
+        key: string;
+        backend: string;
+        opId?: string;
+    }): string;
+    markDone(opId: string): void;
+    markFailed(opId: string, error: string): void;
+    get(opId: string): StorageOpRow | null;
+    /** Ops still needing work: `pending`, or `failed` under the attempt cap, created before `before`
+     * (default: everything). Oldest first. */
+    outstanding(opts?: {
+        maxAttempts?: number;
+        before?: number;
+    }): StorageOpRow[];
+}
+export declare function createStorageOpsLedger(db: Database, now?: () => number): StorageOpsLedger;
+export declare function createLedgeredDeletes(store: MediaStore, ledger: StorageOpsLedger, backend: string): Pick<MediaStore, 'remove' | 'removePrefix'> & {
+    removeFor(owner: string, fileId: string | null, key: string): Promise<void>;
+    removePrefixFor(owner: string, fileId: string | null, prefix: string): Promise<void>;
+};
+export interface StorageReconciler {
+    /** Re-drive every outstanding op to completion (idempotent). Returns how many healed vs. still
+     * failing. Safe to call on boot and on an interval. */
+    reconcile(opts?: {
+        maxAttempts?: number;
+    }): Promise<{
+        healed: number;
+        failed: number;
+    }>;
+}
+export declare function createStorageReconciler(store: MediaStore, ledger: StorageOpsLedger): StorageReconciler;

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

@@ -0,0 +1,110 @@
+const toRow = (r) => ({
+    opId: r.op_id,
+    owner: r.owner,
+    fileId: r.file_id,
+    action: r.action,
+    key: r.key,
+    backend: r.backend,
+    status: r.status,
+    attempts: r.attempts,
+    error: r.error,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+});
+export function createStorageOpsLedger(db, now = () => Date.now()) {
+    const insert = db.query(`INSERT INTO storage_operations (op_id, owner, file_id, action, key, backend, status, attempts, created_at, updated_at)
+     VALUES ($op, $owner, $file, $action, $key, $backend, 'pending', 0, $now, $now)`);
+    // MONOTONIC terminal state: once an op is `done` it can never flip back (a duplicate completion
+    // webhook racing the reconciler, or a late failure, must not corrupt a settled success). `failed`
+    // is NOT terminal — the reconciler retries a failed delete and can heal it to `done`, or bump its
+    // attempts — so both writes guard only against overwriting `done`. (Ported from ca's resolveOp
+    // `CASE WHEN status='pending'` invariant, adapted to our two-writer model.)
+    const setDone = db.query(`UPDATE storage_operations SET status = 'done', updated_at = $now WHERE op_id = $op AND status != 'done'`);
+    const setFailed = db.query(`UPDATE storage_operations SET status = 'failed', attempts = attempts + 1, error = $error, updated_at = $now WHERE op_id = $op AND status != 'done'`);
+    const getOne = db.query(`SELECT * FROM storage_operations WHERE op_id = $op`);
+    return {
+        record(op) {
+            const opId = op.opId ?? crypto.randomUUID();
+            insert.run({
+                $op: opId,
+                $owner: op.owner,
+                $file: op.fileId ?? null,
+                $action: op.action,
+                $key: op.key,
+                $backend: op.backend,
+                $now: now(),
+            });
+            return opId;
+        },
+        markDone(opId) {
+            setDone.run({ $op: opId, $now: now() });
+        },
+        markFailed(opId, error) {
+            setFailed.run({ $op: opId, $error: error.slice(0, 500), $now: now() });
+        },
+        get(opId) {
+            const r = getOne.get({ $op: opId });
+            return r ? toRow(r) : null;
+        },
+        outstanding(opts = {}) {
+            const maxAttempts = opts.maxAttempts ?? 5;
+            const before = opts.before ?? now() + 1;
+            return db
+                .query(`SELECT * FROM storage_operations
+           WHERE status != 'done' AND attempts < $max AND created_at < $before
+           ORDER BY created_at ASC`)
+                .all({ $max: maxAttempts, $before: before })
+                .map(toRow);
+        },
+    };
+}
+// Wrap a MediaStore so DELETE / DELETE-PREFIX are ledgered: a `pending` row is written first, the
+// op attempted, then marked `done`; a failure marks it `failed` and rethrows (the row survives for
+// the reconciler). Reads/writes pass straight through — only the leak-prone deletes are logged.
+export function createLedgeredDeletes(store, ledger, backend) {
+    const run = async (action, owner, fileId, key, exec) => {
+        const opId = ledger.record({ owner, fileId, action, key, backend });
+        try {
+            await exec();
+            ledger.markDone(opId);
+        }
+        catch (e) {
+            ledger.markFailed(opId, e instanceof Error ? e.message : String(e));
+            throw e;
+        }
+    };
+    return {
+        remove: (key) => run('delete', '', null, key, () => store.remove(key)),
+        removePrefix: (prefix) => run('delete_prefix', '', null, prefix, () => store.removePrefix(prefix)),
+        removeFor: (owner, fileId, key) => run('delete', owner, fileId, key, () => store.remove(key)),
+        removePrefixFor: (owner, fileId, prefix) => run('delete_prefix', owner, fileId, prefix, () => store.removePrefix(prefix)),
+    };
+}
+export function createStorageReconciler(store, ledger) {
+    return {
+        async reconcile(opts = {}) {
+            let healed = 0;
+            let failed = 0;
+            for (const op of ledger.outstanding({ maxAttempts: opts.maxAttempts })) {
+                // Only DELETES are re-driven by re-issuing the store call (idempotent). An 'upload' op is
+                // healed by its completion webhook (or an app-level check against binary-server's own event
+                // ledger) — re-issuing store.remove here would wrongly delete the just-uploaded bytes.
+                if (op.action === 'upload')
+                    continue;
+                try {
+                    if (op.action === 'delete')
+                        await store.remove(op.key);
+                    else
+                        await store.removePrefix(op.key);
+                    ledger.markDone(op.opId);
+                    healed++;
+                }
+                catch (e) {
+                    ledger.markFailed(op.opId, e instanceof Error ? e.message : String(e));
+                    failed++;
+                }
+            }
+            return { healed, failed };
+        },
+    };
+}