cursedbelt-server 1.0.0

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

@@ -0,0 +1,106 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { derivePasswordSetKey, generateUserSalt, openMeta } from '../../private-media/crypto';
+import type { PrivateIndex } from '../../private-media/index-store';
+import { createDiskStore } from '../diskStore';
+import type { MediaCtx } from '../types';
+import { createSqliteFileCatalogue } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { PrivateFileCatalogue } from './types';
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 't1' };
+const stream = (s: string) =>
+  new Response(new TextEncoder().encode(s)).body as ReadableStream<Uint8Array>;
+const OWNER = CTX.userId; // private owner axis = userId (matches mountPrivateRoutes)
+
+// Seal/reveal/deniability is ffmpeg-independent: the descriptor is sealed regardless of transcode
+// success, so these run everywhere. (Content-key unwrap needs a real transcode → ffmpeg-gated e2e.)
+describe('FileCatalogue private media — ingest + PrivateIndex view + deniability', () => {
+  let db: Database;
+  let root: string;
+  let cat: PrivateFileCatalogue;
+  let index: PrivateIndex;
+  const salt = generateUserSalt();
+  const keyA = derivePasswordSetKey('alpha-pass', salt);
+  const keyB = derivePasswordSetKey('bravo-pass', salt);
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-priv-'));
+    let clock = 1;
+    // owner = userId so private rows + mountPrivateRoutes agree on the scope.
+    cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'w'),
+      owner: (c) => c.userId,
+      now: () => ++clock,
+    });
+    index = cat.asPrivateIndex();
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('ingests private rows under two disjoint passwords', async () => {
+    await cat.ingestPrivate(
+      CTX,
+      { name: 'secret-a.mp4', mime: 'video/mp4', body: stream('a-bytes'), tags: ['setA'] },
+      { setKey: keyA, keyMode: 'deniable' },
+    );
+    await cat.ingestPrivate(
+      CTX,
+      { name: 'secret-b.mp4', mime: 'video/mp4', body: stream('b-bytes'), tags: ['setB'] },
+      { setKey: keyB, keyMode: 'deniable' },
+    );
+    expect((await index.list(OWNER)).length).toBe(2);
+  });
+
+  test('a set key reveals only its own items (deniability) via the index envelopes', () => {
+    const reveal = async (key: Buffer) => {
+      const names: string[] = [];
+      for (const item of await index.list(OWNER)) {
+        const meta = openMeta<{ name: string }>(key, item.sealedMeta);
+        if (meta) names.push(meta.name);
+      }
+      return names.sort();
+    };
+    return Promise.all([
+      reveal(keyA),
+      reveal(keyB),
+      reveal(derivePasswordSetKey('nope', salt)),
+    ]).then(([a, b, wrong]) => {
+      expect(a).toEqual(['secret-a.mp4']);
+      expect(b).toEqual(['secret-b.mp4']);
+      expect(wrong).toEqual([]); // an unused password shows nothing — no hint the sets exist
+    });
+  });
+
+  test('the clear index exposes no set identifier or key mode difference', async () => {
+    // Both rows are keyMode 'deniable' here; the public projection (toPublic) that the /index route
+    // returns strips keyMode entirely — asserted by mountPrivateRoutes' own tests. Here we just
+    // confirm the raw items carry the wrapped key + sealed meta (opaque without a key).
+    for (const item of await index.list(OWNER)) {
+      expect(item.sealedMeta.length).toBeGreaterThan(0);
+      expect(openMeta(Buffer.alloc(32), item.sealedMeta)).toBeNull(); // a random key opens nothing
+    }
+  });
+
+  test('index.remove drops the row', async () => {
+    const items = await index.list(OWNER);
+    await index.remove(OWNER, items[0].id);
+    expect((await index.list(OWNER)).length).toBe(1);
+    expect(await index.get(OWNER, items[0].id)).toBeNull();
+  });
+
+  test('private rows never appear in the public feed', async () => {
+    const publicCat = cat as unknown as { list: (c: MediaCtx) => Promise<{ items: unknown[] }> };
+    expect((await publicCat.list(CTX)).items).toEqual([]);
+  });
+});

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

@@ -0,0 +1,131 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import { createSqliteFileCatalogue } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue } from './types';
+
+// recoverProcessing (ported from ca's recoverOnBoot): a restart mid-transcode leaves video rows
+// stuck in processing/pending; public rows get re-kicked (source persists), private rows are failed.
+describe('FileCatalogue.recoverProcessing', () => {
+  let db: Database;
+  let root: string;
+  let cat: FileCatalogue;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-recover-'));
+    cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'w'),
+    });
+    // Simulate two rows a crash left mid-transcode: one public, one private.
+    const insert = db.query(
+      `INSERT INTO files (id, owner, name, mime, size, file_type, is_private, processing_status, processing_progress, storage_backend, created_at, updated_at)
+       VALUES ($id, 'u1', $name, 'video/mp4', 10, 'video', $priv, 'processing', 40, 'disk', 1, 1)`,
+    );
+    insert.run({ $id: 'pub1', $name: 'a.mp4', $priv: 0 });
+    insert.run({ $id: 'prv1', $name: '', $priv: 1 });
+  });
+  afterAll(async () => {
+    await Bun.sleep(150); // let the re-kicked public job settle before closing the db
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('re-queues stuck public videos and fails stuck private ones', () => {
+    const res = cat.recoverProcessing();
+    expect(res.requeued).toBe(1); // pub1 re-kicked
+    expect(res.failed).toBe(1); // prv1 can't be re-kicked at boot → failed
+
+    const status = (id: string) =>
+      db
+        .query<{ processing_status: string }, { $id: string }>(
+          'SELECT processing_status FROM files WHERE id = $id',
+        )
+        .get({ $id: id })?.processing_status;
+    expect(status('prv1')).toBe('failed');
+    // pub1 was re-kicked (its final status is settled by the async pipeline; here we just assert it
+    // left the recover call counted as requeued, not failed).
+  });
+
+  test('re-kick bumps processing_attempts', () => {
+    const attempts = db
+      .query<{ processing_attempts: number }, { $id: string }>(
+        'SELECT processing_attempts FROM files WHERE id = $id',
+      )
+      .get({ $id: 'pub1' })?.processing_attempts;
+    expect(attempts).toBe(1);
+  });
+});
+
+// The boot-loop guard: when the transcode itself keeps killing the process (ffmpeg OOM →
+// restart → re-kick), the attempt cap must land the row on `failed` instead of re-kicking forever.
+describe('FileCatalogue.recoverProcessing attempt cap', () => {
+  test('marks a public video failed once processing_attempts reaches the cap', async () => {
+    const db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    const root = await mkdtemp(path.join(tmpdir(), 'fc-recover-cap-'));
+    const cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'w'),
+      maxProcessingAttempts: 2,
+    });
+    db.query(
+      `INSERT INTO files (id, owner, name, mime, size, file_type, is_private, processing_status, processing_progress, storage_backend, processing_attempts, created_at, updated_at)
+       VALUES ('loop1', 'u1', 'l.mp4', 'video/mp4', 10, 'video', 0, 'processing', 40, 'disk', 2, 1, 1)`,
+    ).run();
+
+    const res = cat.recoverProcessing();
+    expect(res.requeued).toBe(0);
+    expect(res.failed).toBe(1);
+    const row = db
+      .query<{ processing_status: string }, []>(
+        `SELECT processing_status FROM files WHERE id = 'loop1'`,
+      )
+      .get();
+    expect(row?.processing_status).toBe('failed');
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+});
+
+// transcodeVideos: false — the memory-constrained-host mode: no ffmpeg, videos go straight to
+// ready and play raw. Recovery under this mode must not re-enter the transcode pipeline either.
+describe('FileCatalogue transcodeVideos: false', () => {
+  test('video rows go ready with no derivatives and no attempt bump', async () => {
+    const db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    const root = await mkdtemp(path.join(tmpdir(), 'fc-notranscode-'));
+    const cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'w'),
+      transcodeVideos: false,
+    });
+    db.query(
+      `INSERT INTO files (id, owner, name, mime, size, file_type, is_private, processing_status, processing_progress, storage_backend, created_at, updated_at)
+       VALUES ('raw1', 'u1', 'r.mp4', 'video/mp4', 10, 'video', 0, 'processing', 40, 'disk', 1, 1)`,
+    ).run();
+
+    const res = cat.recoverProcessing();
+    expect(res.requeued).toBe(1); // counted as requeued, but the "kick" resolves synchronously
+    const row = db
+      .query<{ processing_status: string; processing_attempts: number; has_hls: number }, []>(
+        `SELECT processing_status, processing_attempts, has_hls FROM files WHERE id = 'raw1'`,
+      )
+      .get();
+    expect(row?.processing_status).toBe('ready');
+    expect(row?.processing_attempts).toBe(0);
+    expect(row?.has_hls).toBe(0);
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+});

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

@@ -0,0 +1,154 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import type { MediaCtx } from '../types';
+import { createSqliteFileCatalogue } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue, FileSort } from './types';
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 'sorter' };
+
+describe('FileCatalogue — sort orders + pagination', () => {
+  let db: Database;
+  let root: string;
+  let cat: FileCatalogue;
+  let clock = 5000;
+
+  // Names/sizes chosen so each sort produces a DIFFERENT order, with a duplicate size to
+  // exercise the id tie-break. Bodies of length n ⇒ size n.
+  const FILES: Array<{ name: string; size: number }> = [
+    { name: 'delta.png', size: 10 },
+    { name: 'alpha.png', size: 30 },
+    { name: 'echo.png', size: 20 },
+    { name: 'bravo.png', size: 20 }, // duplicate size — tie-break path
+    { name: 'charlie.png', size: 50 },
+  ];
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-sort-'));
+    cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'work'),
+      now: () => ++clock,
+    });
+    for (const f of FILES) {
+      const body = new Response('x'.repeat(f.size)).body as ReadableStream<Uint8Array>;
+      await cat.ingest(CTX, { name: f.name, mime: 'image/png', body });
+    }
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test("default / 'recent' sorts newest-first (unchanged behavior)", async () => {
+    const expected = [...FILES].reverse().map((f) => f.name); // insertion order reversed
+    expect((await cat.list(CTX)).items.map((f) => f.name)).toEqual(expected);
+    expect((await cat.list(CTX, { sort: 'recent' })).items.map((f) => f.name)).toEqual(expected);
+  });
+
+  test("'oldest' sorts oldest-first (insertion order)", async () => {
+    const page = await cat.list(CTX, { sort: 'oldest' });
+    expect(page.items.map((f) => f.name)).toEqual(FILES.map((f) => f.name));
+  });
+
+  test("'name' sorts A→Z", async () => {
+    const page = await cat.list(CTX, { sort: 'name' });
+    expect(page.items.map((f) => f.name)).toEqual([
+      'alpha.png',
+      'bravo.png',
+      'charlie.png',
+      'delta.png',
+      'echo.png',
+    ]);
+  });
+
+  test("'size' sorts largest-first", async () => {
+    const page = await cat.list(CTX, { sort: 'size' });
+    expect(page.items.map((f) => f.size)).toEqual([50, 30, 20, 20, 10]);
+    expect(page.items[0].name).toBe('charlie.png');
+  });
+
+  // Walk the whole pool page-by-page under a sort; assert no gaps, no repeats, and that the
+  // concatenated pages equal the single-page order.
+  const paginate = async (sort: FileSort, limit: number): Promise<string[]> => {
+    const all: string[] = [];
+    const seen = new Set<string>();
+    let cursor: string | undefined;
+    let guard = 0;
+    do {
+      const page = await cat.list(CTX, { sort, limit, cursor });
+      for (const f of page.items) {
+        expect(seen.has(f.id)).toBe(false); // no repeats across pages
+        seen.add(f.id);
+        all.push(f.name);
+      }
+      cursor = page.nextCursor;
+      guard++;
+    } while (cursor && guard < 10);
+    return all;
+  };
+
+  test.each([
+    'recent',
+    'oldest',
+    'name',
+    'size',
+  ] as const)("cursor pagination under sort '%s' walks the pool without gaps or repeats", async (sort) => {
+    const whole = (await cat.list(CTX, { sort })).items.map((f) => f.name);
+    const paged = await paginate(sort, 2);
+    expect(paged).toEqual(whole); // page-by-page equals the one-shot order
+    expect(paged.length).toBe(FILES.length);
+  });
+
+  test('size pagination splits the duplicate-size pair across pages correctly (tie-break)', async () => {
+    // limit 3 puts the boundary INSIDE the size=20 duplicate pair.
+    const p1 = await cat.list(CTX, { sort: 'size', limit: 3 });
+    expect(p1.items.map((f) => f.size)).toEqual([50, 30, 20]);
+    expect(p1.nextCursor).toBeDefined();
+    const p2 = await cat.list(CTX, { sort: 'size', limit: 3, cursor: p1.nextCursor });
+    expect(p2.items.map((f) => f.size)).toEqual([20, 10]);
+    // The two size-20 files are different files.
+    expect(p1.items[2].id).not.toBe(p2.items[0].id);
+  });
+
+  test('a name containing the cursor separator paginates safely', async () => {
+    const CTX2: MediaCtx = { userId: 'u2', tenantId: 'sorter2' };
+    const mk = (name: string) =>
+      cat.ingest(CTX2, {
+        name,
+        mime: 'image/png',
+        body: new Response('x').body as ReadableStream<Uint8Array>,
+      });
+    await mk('a|weird|name.png');
+    await mk('b|also|weird.png');
+    await mk('c.png');
+    const p1 = await cat.list(CTX2, { sort: 'name', limit: 1 });
+    expect(p1.items[0].name).toBe('a|weird|name.png');
+    const p2 = await cat.list(CTX2, { sort: 'name', limit: 1, cursor: p1.nextCursor });
+    expect(p2.items[0].name).toBe('b|also|weird.png');
+    const p3 = await cat.list(CTX2, { sort: 'name', limit: 1, cursor: p2.nextCursor });
+    expect(p3.items[0].name).toBe('c.png');
+  });
+
+  test('sort composes with filters (collection + sort)', async () => {
+    const coll = await cat.createCollection(CTX, { name: 'SortColl' });
+    const all = await cat.list(CTX);
+    await cat.addToCollection(
+      CTX,
+      coll.id,
+      all.items.slice(0, 3).map((f) => f.id),
+    );
+    const page = await cat.list(CTX, { collectionId: coll.id, sort: 'name' });
+    const names = page.items.map((f) => f.name);
+    expect(names).toEqual([...names].sort());
+    expect(names.length).toBe(3);
+  });
+});

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

@@ -0,0 +1,133 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import type { MediaCtx } from '../types';
+import { fsPosterKey } from '../types';
+import { createSqliteFileCatalogue, fileBinaryKey } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue } from './types';
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 't1' };
+const bytes = (s: string) => new TextEncoder().encode(s);
+const stream = (s: string) => new Response(bytes(s)).body as ReadableStream<Uint8Array>;
+
+describe('FileCatalogue (SQLite)', () => {
+  let db: Database;
+  let root: string;
+  let cat: FileCatalogue;
+  let store: ReturnType<typeof createDiskStore>;
+  let clock = 1000;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-store-'));
+    store = createDiskStore(root);
+    cat = createSqliteFileCatalogue({
+      db,
+      store,
+      workDir: path.join(root, 'work'),
+      now: () => ++clock, // deterministic, increasing createdAt
+    });
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const ingest = (name: string, mime: string, tags: string[] = []) =>
+    cat.ingest(CTX, { name, mime, body: stream(`bytes-of-${name}`), tags });
+
+  test('ingests non-video files as ready, classifies + tags them', async () => {
+    const a = await ingest('a.png', 'image/png', ['photo']);
+    expect(a.fileType).toBe('image');
+    expect(a.processingStatus).toBe('ready');
+    expect(a.tags).toEqual(['photo']);
+    expect(a.size).toBe(bytes('bytes-of-a.png').length);
+
+    await ingest('b.pdf', 'application/pdf', ['work']);
+    await ingest('c.jpg', 'image/jpeg', ['photo', 'work']);
+  });
+
+  test('lists newest-first with smart-view + tag + query filters', async () => {
+    const all = await cat.list(CTX);
+    expect(all.items.map((f) => f.name)).toEqual(['c.jpg', 'b.pdf', 'a.png']); // newest first
+
+    expect((await cat.list(CTX, { type: 'image' })).items.map((f) => f.name)).toEqual([
+      'c.jpg',
+      'a.png',
+    ]);
+    expect((await cat.list(CTX, { type: 'doc' })).items.map((f) => f.name)).toEqual(['b.pdf']);
+    expect((await cat.list(CTX, { tag: 'photo' })).items.map((f) => f.name)).toEqual([
+      'c.jpg',
+      'a.png',
+    ]);
+    expect((await cat.list(CTX, { query: 'b.' })).items.map((f) => f.name)).toEqual(['b.pdf']);
+  });
+
+  test('tagFacets counts tags across the pool', async () => {
+    const facets = await cat.tagFacets(CTX);
+    expect(facets).toContainEqual({ tag: 'photo', count: 2 });
+    expect(facets).toContainEqual({ tag: 'work', count: 2 });
+  });
+
+  test('cursor pagination walks the whole pool without gaps or repeats', async () => {
+    const seen = new Set<string>();
+    let cursor: string | undefined;
+    let pages = 0;
+    do {
+      const page = await cat.list(CTX, { limit: 2, cursor });
+      for (const f of page.items) {
+        expect(seen.has(f.id)).toBe(false); // no repeats
+        seen.add(f.id);
+      }
+      cursor = page.nextCursor;
+      pages++;
+    } while (cursor && pages < 10);
+    expect(seen.size).toBe(3); // all files, paged 2 at a time
+    expect(pages).toBe(2);
+  });
+
+  test('get + update (rename + retag) + remove', async () => {
+    const { items } = await cat.list(CTX, { type: 'doc' });
+    const id = items[0].id;
+    expect((await cat.get(CTX, id))?.name).toBe('b.pdf');
+
+    const updated = await cat.update(CTX, id, { name: 'renamed.pdf', tags: ['archive'] });
+    expect(updated?.name).toBe('renamed.pdf');
+    expect(updated?.tags).toEqual(['archive']);
+    expect((await cat.tagFacets(CTX)).find((f) => f.tag === 'work')?.count).toBe(1); // 'work' dropped from b
+
+    await cat.remove(CTX, id);
+    expect(await cat.get(CTX, id)).toBeNull();
+    expect((await cat.list(CTX)).items.length).toBe(2);
+  });
+
+  test('remove deletes an image’s binary AND its poster thumbnail from the store', async () => {
+    const img = await ingest('orphan.png', 'image/png');
+    const owner = CTX.tenantId; // catalogue's default ownerOf
+    // Simulate the thumbnail the async kickImageThumbnail pipeline writes.
+    await store.put(fsPosterKey(owner, img.id), bytes('thumb'), 'image/jpeg');
+    expect(await store.stat(fileBinaryKey(owner, img.id))).not.toBeNull();
+
+    await cat.remove(CTX, img.id);
+    expect(await cat.get(CTX, img.id)).toBeNull();
+    expect(await store.stat(fileBinaryKey(owner, img.id))).toBeNull();
+    expect(await store.stat(fsPosterKey(owner, img.id))).toBeNull(); // was orphaned before the fix
+  });
+
+  test('one tenant never sees another tenant’s files', async () => {
+    await cat.ingest(
+      { userId: 'u2', tenantId: 't2' },
+      { name: 'other.png', mime: 'image/png', body: stream('x') },
+    );
+    expect((await cat.list(CTX)).items.every((f) => f.name !== 'other.png')).toBe(true);
+    expect((await cat.list({ userId: 'u2', tenantId: 't2' })).items.map((f) => f.name)).toEqual([
+      'other.png',
+    ]);
+  });
+});

package/src/server/storage/files/catalogue.trash-import.spec.ts

@@ -0,0 +1,125 @@
+import { Database } from 'bun:sqlite';
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runMigrations } from '../../migration/runner';
+import { createDiskStore } from '../diskStore';
+import type { MediaCtx } from '../types';
+import { createSqliteFileCatalogue } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue } from './types';
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 't1' };
+const bytes = (s: string) => new TextEncoder().encode(s);
+const stream = (s: string) => new Response(bytes(s)).body as ReadableStream<Uint8Array>;
+
+describe('FileCatalogue trash (soft-delete)', () => {
+  let db: Database;
+  let root: string;
+  let cat: FileCatalogue;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-trash-'));
+    cat = createSqliteFileCatalogue({ db, store: createDiskStore(root), workDir: path.join(root, 'work') });
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test('trash hides a file from list() but keeps its row + bytes', async () => {
+    const f = await cat.ingest(CTX, { name: 'a.png', mime: 'image/png', body: stream('a') });
+    await cat.trash(CTX, f.id);
+
+    expect((await cat.list(CTX)).items.some((r) => r.id === f.id)).toBe(false);
+    const row = await cat.get(CTX, f.id);
+    expect(row?.trashedAt).toBeGreaterThan(0);
+  });
+
+  test('trashedOnly lists exactly the trashed set', async () => {
+    const live = await cat.ingest(CTX, { name: 'live.png', mime: 'image/png', body: stream('l') });
+    const gone = await cat.ingest(CTX, { name: 'gone.png', mime: 'image/png', body: stream('g') });
+    await cat.trash(CTX, gone.id);
+
+    const trashPage = await cat.list(CTX, { trashedOnly: true });
+    expect(trashPage.items.map((r) => r.id)).toContain(gone.id);
+    expect(trashPage.items.map((r) => r.id)).not.toContain(live.id);
+  });
+
+  test('restore undoes trash — the file reappears in list()', async () => {
+    const f = await cat.ingest(CTX, { name: 'b.png', mime: 'image/png', body: stream('b') });
+    await cat.trash(CTX, f.id);
+    await cat.restore(CTX, f.id);
+
+    expect((await cat.list(CTX)).items.some((r) => r.id === f.id)).toBe(true);
+    expect((await cat.get(CTX, f.id))?.trashedAt).toBeUndefined();
+  });
+
+  test('remove() is still a real hard-delete, independent of trash', async () => {
+    const f = await cat.ingest(CTX, { name: 'c.png', mime: 'image/png', body: stream('c') });
+    await cat.trash(CTX, f.id);
+    await cat.remove(CTX, f.id);
+    expect(await cat.get(CTX, f.id)).toBeNull();
+  });
+});
+
+describe('FileCatalogue.importFromPath (local-disk import)', () => {
+  let db: Database;
+  let root: string;
+  let importRoot: string;
+  let cat: FileCatalogue;
+
+  beforeAll(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-import-store-'));
+    importRoot = await mkdtemp(path.join(tmpdir(), 'fc-import-src-'));
+    cat = createSqliteFileCatalogue({ db, store: createDiskStore(root), workDir: path.join(root, 'work') });
+  });
+  afterAll(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+    await rm(importRoot, { recursive: true, force: true });
+  });
+
+  test('imports a single file', async () => {
+    const filePath = path.join(importRoot, 'single.jpg');
+    await writeFile(filePath, bytes('single-file-bytes'));
+
+    const { imported, skipped } = await cat.importFromPath(CTX, filePath);
+    expect(skipped).toEqual([]);
+    expect(imported).toHaveLength(1);
+    expect(imported[0].name).toBe('single.jpg');
+    expect(imported[0].mime).toBe('image/jpeg');
+    expect(imported[0].fileType).toBe('image');
+  });
+
+  test('imports a mixed-media folder recursively, tagging by containing folder', async () => {
+    const folder = path.join(importRoot, 'vacation');
+    const sub = path.join(folder, 'day1');
+    await mkdir(sub, { recursive: true });
+    await writeFile(path.join(folder, 'cover.png'), bytes('cover'));
+    await writeFile(path.join(sub, 'clip.mp4'), bytes('clip'));
+
+    const { imported, skipped } = await cat.importFromPath(CTX, folder, { tags: ['import-batch'] });
+    expect(skipped).toEqual([]);
+    expect(imported).toHaveLength(2);
+
+    const cover = imported.find((f) => f.name === 'cover.png');
+    const clip = imported.find((f) => f.name === 'clip.mp4');
+    expect(cover?.fileType).toBe('image');
+    expect(cover?.tags).toEqual(['import-batch']); // top-level entries get no folder tag
+    expect(clip?.fileType).toBe('video');
+    expect(clip?.tags).toEqual(['import-batch', 'day1']);
+  });
+
+  test('reports a missing path as skipped, not a throw', async () => {
+    const { imported, skipped } = await cat.importFromPath(CTX, path.join(importRoot, 'nope.png'));
+    expect(imported).toEqual([]);
+    expect(skipped).toHaveLength(1);
+    expect(skipped[0].path).toContain('nope.png');
+  });
+});