cursedbelt-server 1.0.0

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

@@ -0,0 +1,255 @@
+import type { GalleryMedia, GalleryPhoto } from 'cursedbelt-core/media';
+import { isBrowserRenderableImage } from '../imageThumbnail';
+import type { MediaUrls } from '../sources';
+import type { MediaCtx, MediaGallerySource, MediaSource, PhotoSource } from '../types';
+import type { FileUrls } from './fileRoutes';
+import type { FileCatalogue, FileRecord, FileToPlayable } from './types';
+
+/** Build the image→GalleryPhoto mapper shared by the photo source and the mixed media source.
+ * The primary image is served by the file byte route (fileUrls); the grid thumbnail + HEIC
+ * display derivative by the type-agnostic poster route (mediaUrls) when ingest produced one. */
+function createFileToPhoto(cfg: {
+  id: string;
+  fileUrls: FileUrls;
+  mediaUrls: MediaUrls;
+}): (ctx: MediaCtx, file: FileRecord) => Promise<GalleryPhoto | null> {
+  return async (ctx, file) => {
+    if (file.fileType !== 'image') return null;
+    const { url } = await cfg.fileUrls.build(ctx, file.id, file.mime);
+    const media = file.hasThumbnail ? await cfg.mediaUrls.build(ctx, cfg.id, file.id) : null;
+    const thumbnailUrl = media?.posterUrl;
+    const displayUrl = media && !isBrowserRenderableImage(file.mime) ? media.displayUrl : undefined;
+    return {
+      id: file.id,
+      type: 'image',
+      url,
+      thumbnailUrl,
+      displayUrl,
+      name: file.name,
+      sizeBytes: file.size,
+      mimeType: file.mime,
+      tags: file.tags,
+      createdAt: file.createdAt,
+      favorite: file.favorite,
+    };
+  };
+}
+
+// ── FileCatalogue → media seam ────────────────────────────────────────────────────
+// The catalogue is the ONE source of truth for a user's binaries. The video gallery is not a
+// separate store — it is a video-filtered VIEW over the catalogue. These two adapters are the
+// seam: `createFileToPlayable` turns a video FileRecord into the player's PlayableVideo (URLs
+// baked server-side via the shared token/serve infra), and `createCatalogueVideoSource` exposes
+// the catalogue as a `MediaSource` so the existing `mountMediaRoutes` + gallery serve it
+// unchanged. Because the serve routes address bytes by (owner, videoId) through the shared
+// keyspace, a catalogue video is served by the same routes regardless of `sourceId`.
+
+/** Resolve a video FileRecord to a PlayableVideo with tokenised URLs. Non-video ⇒ null. */
+export function createFileToPlayable(urls: MediaUrls, sourceId: string): FileToPlayable {
+  return async (ctx, file) => {
+    if (file.fileType !== 'video') return null;
+    const u = await urls.build(ctx, sourceId, file.id);
+    return {
+      id: file.id,
+      name: file.name,
+      streamUrl: u.streamUrl,
+      hlsUrl: file.hasHls ? u.hlsUrl : undefined,
+      posterUrl: file.hasThumbnail ? u.posterUrl : undefined,
+      vttUrl: file.hasSprites ? u.vttUrl : undefined,
+      spriteUrl: file.hasSprites ? u.spriteUrl : undefined,
+      durationSeconds: file.durationSeconds,
+      tags: file.tags,
+      processingStatus: file.processingStatus,
+      processingProgress: file.processingProgress,
+    };
+  };
+}
+
+/** Expose a FileCatalogue as a video-only `MediaSource` — the gallery is a view, not a store. */
+export function createCatalogueVideoSource(cfg: {
+  id: string;
+  title: string;
+  catalogue: FileCatalogue;
+  urls: MediaUrls;
+}): MediaSource {
+  const toPlayable = createFileToPlayable(cfg.urls, cfg.id);
+  return {
+    id: cfg.id,
+    title: cfg.title,
+
+    async list(ctx, opts) {
+      const page = await cfg.catalogue.list(ctx, {
+        type: 'video',
+        tag: opts.tag,
+        query: opts.query,
+        cursor: opts.cursor,
+        limit: opts.limit,
+        sort: opts.sort,
+      });
+      const items = await Promise.all(page.items.map((f) => toPlayable(ctx, f)));
+      return { items: items.filter((v) => v !== null), nextCursor: page.nextCursor };
+    },
+
+    async resolve(ctx, videoId) {
+      const file = await cfg.catalogue.get(ctx, videoId);
+      return file ? toPlayable(ctx, file) : null;
+    },
+
+    async tags(ctx) {
+      return (await cfg.catalogue.tagFacets(ctx)).map((f) => f.tag);
+    },
+
+    async ingest(ctx, upload) {
+      const file = await cfg.catalogue.ingest(ctx, upload);
+      const playable = await toPlayable(ctx, file);
+      if (!playable) throw new Error('gallery ingest expects a video file');
+      return playable;
+    },
+
+    async remove(ctx, videoId) {
+      await cfg.catalogue.trash(ctx, videoId);
+    },
+
+    async recordView(ctx, videoId) {
+      await cfg.catalogue.recordView(ctx, videoId);
+    },
+  };
+}
+
+// ── Photo view ────────────────────────────────────────────────────────────────────
+// The photo gallery is the image-filtered sibling of the video view: same catalogue, same
+// token/serve infra. The primary image is served by the file byte route (fileUrls) and the grid
+// thumbnail by the type-agnostic poster route (mediaUrls) when the ingest thumbnailer produced
+// one — so a PhotoSource needs BOTH URL builders.
+
+/** Expose a FileCatalogue as an image-only `PhotoSource` — a view, not a store. */
+export function createCataloguePhotoSource(cfg: {
+  id: string;
+  title: string;
+  catalogue: FileCatalogue;
+  fileUrls: FileUrls;
+  mediaUrls: MediaUrls;
+}): PhotoSource {
+  const toPhoto = createFileToPhoto(cfg);
+
+  return {
+    id: cfg.id,
+    title: cfg.title,
+
+    async list(ctx, opts) {
+      const page = await cfg.catalogue.list(ctx, {
+        type: 'image',
+        tag: opts.tag,
+        query: opts.query,
+        cursor: opts.cursor,
+        limit: opts.limit,
+        sort: opts.sort,
+      });
+      const items = await Promise.all(page.items.map((f) => toPhoto(ctx, f)));
+      return { items: items.filter((p) => p !== null), nextCursor: page.nextCursor };
+    },
+
+    async resolve(ctx, photoId) {
+      const file = await cfg.catalogue.get(ctx, photoId);
+      return file ? toPhoto(ctx, file) : null;
+    },
+
+    async tags(ctx) {
+      return (await cfg.catalogue.tagFacets(ctx)).map((f) => f.tag);
+    },
+
+    async ingest(ctx, upload) {
+      if (!upload.mime.startsWith('image/')) {
+        throw new Error('photo ingest expects an image file');
+      }
+      const file = await cfg.catalogue.ingest(ctx, upload);
+      const photo = await toPhoto(ctx, file);
+      if (!photo) throw new Error('photo ingest expects an image file');
+      return photo;
+    },
+
+    async remove(ctx, photoId) {
+      await cfg.catalogue.trash(ctx, photoId);
+    },
+
+    async recordView(ctx, photoId) {
+      await cfg.catalogue.recordView(ctx, photoId);
+    },
+  };
+}
+
+// ── Mixed media view ───────────────────────────────────────────────────────────────
+// A combined gallery lists BOTH photos and videos from the one catalogue. This adapter
+// reuses the same two mappers (`createFileToPlayable`, `createFileToPhoto`) so a mixed
+// item renders identically to its single-type sibling — it just tags each with
+// `mediaKind` for the UI to pick a tile/stage. It needs BOTH URL builders (video streams
+// + image bytes/poster). A `kind` filter maps to the catalogue's `type`; `all` lists
+// untyped and keeps only image|video (dropping docs/audio the mixed gallery can't show).
+
+/** Expose a FileCatalogue as a `MediaGallerySource` — photos + videos in one feed.
+ * Videos are tokenised under `videoSourceId` (must match the registered video source so
+ * `mountMediaRoutes` serves their streams); photo posters/thumbnails under this source's `id`. */
+export function createCatalogueMediaSource(cfg: {
+  id: string;
+  title: string;
+  catalogue: FileCatalogue;
+  urls: MediaUrls;
+  fileUrls: FileUrls;
+  /** SourceId the video stream tokens are minted under. Default `id`. */
+  videoSourceId?: string;
+}): MediaGallerySource {
+  const toPlayable = createFileToPlayable(cfg.urls, cfg.videoSourceId ?? cfg.id);
+  const toPhoto = createFileToPhoto({ id: cfg.id, fileUrls: cfg.fileUrls, mediaUrls: cfg.urls });
+
+  const toMedia = async (ctx: MediaCtx, file: FileRecord): Promise<GalleryMedia | null> => {
+    if (file.fileType === 'video') {
+      const v = await toPlayable(ctx, file);
+      return v ? { ...v, mediaKind: 'video' } : null;
+    }
+    if (file.fileType === 'image') {
+      const p = await toPhoto(ctx, file);
+      return p ? { ...p, mediaKind: 'photo' } : null;
+    }
+    return null;
+  };
+
+  return {
+    id: cfg.id,
+    title: cfg.title,
+
+    async list(ctx, opts) {
+      // `all` ⇒ no catalogue type filter, then drop non-image/video below.
+      const type = opts.kind === 'image' ? 'image' : opts.kind === 'video' ? 'video' : undefined;
+      const page = await cfg.catalogue.list(ctx, {
+        type,
+        tag: opts.tag,
+        query: opts.query,
+        cursor: opts.cursor,
+        limit: opts.limit,
+        sort: opts.sort,
+      });
+      const items = await Promise.all(page.items.map((f) => toMedia(ctx, f)));
+      return {
+        items: items.filter((m): m is GalleryMedia => m !== null),
+        nextCursor: page.nextCursor,
+      };
+    },
+
+    async resolve(ctx, itemId) {
+      const file = await cfg.catalogue.get(ctx, itemId);
+      return file ? toMedia(ctx, file) : null;
+    },
+
+    async tags(ctx) {
+      return (await cfg.catalogue.tagFacets(ctx)).map((f) => f.tag);
+    },
+
+    async remove(ctx, itemId) {
+      await cfg.catalogue.trash(ctx, itemId);
+    },
+
+    async recordView(ctx, itemId) {
+      await cfg.catalogue.recordView(ctx, itemId);
+    },
+  };
+}

package/src/server/storage/files/catalogue.media-host.spec.ts

@@ -0,0 +1,184 @@
+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 {
+  cryptBlobStream,
+  derivePasswordSetKey,
+  generateUserSalt,
+  openMeta,
+  unwrapContentKey,
+} from '../../private-media/crypto';
+import { createDiskStore } from '../diskStore';
+import { fsPosterKey, type MediaCtx, type MediaStore, privateSourceKey } from '../types';
+import { createSqliteFileCatalogue, fileBinaryKey } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue, PrivateFileCatalogue } from './types';
+import { bytesStream } from 'cursedbelt-core/testing';
+
+// New media-host capabilities: private NON-video blobs (photos), in-place byte replacement
+// (the editor's "overwrite original"), and ingest-time image thumbnails.
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 't1' };
+const OWNER = CTX.userId;
+const stream = bytesStream;
+const drain = async (s: ReadableStream<Uint8Array>): Promise<Uint8Array> =>
+  new Uint8Array(await new Response(s).arrayBuffer());
+
+let db: Database;
+let root: string;
+let store: MediaStore;
+let cat: FileCatalogue & PrivateFileCatalogue;
+
+beforeAll(async () => {
+  db = new Database(':memory:');
+  runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+  root = await mkdtemp(path.join(tmpdir(), 'fc-host-'));
+  store = createDiskStore(root);
+  let clock = 1;
+  cat = createSqliteFileCatalogue({
+    db,
+    store,
+    workDir: path.join(root, 'w'),
+    owner: (c) => c.userId,
+    now: () => ++clock,
+  });
+});
+afterAll(async () => {
+  db.close();
+  await rm(root, { recursive: true, force: true });
+});
+
+describe('private blob ingest (non-video)', () => {
+  const salt = generateUserSalt();
+  const setKey = derivePasswordSetKey('photo-pass', salt);
+  const plaintext = new TextEncoder().encode('these are secret photo bytes — not for the feed');
+  let id: string;
+
+  test('ingests an image as a ready, encrypted blob (no ffmpeg involved)', async () => {
+    const item = await cat.ingestPrivate(
+      CTX,
+      { name: 'secret.jpg', mime: 'image/jpeg', body: stream(plaintext), tags: ['hidden'] },
+      { setKey, keyMode: 'deniable' },
+    );
+    id = item.id;
+    expect(item.processingStatus).toBe('ready');
+    expect(item.size).toBe(plaintext.byteLength);
+    expect(item.hasHls).toBe(false);
+  });
+
+  test('stored bytes are ciphertext; the wrapped content key decrypts them', async () => {
+    const stored = await store.get(privateSourceKey(OWNER, id));
+    expect(stored).not.toBeNull();
+    expect(stored?.byteLength).toBe(plaintext.byteLength); // CTR is length-preserving
+    expect(Buffer.from(stored as Uint8Array).equals(Buffer.from(plaintext))).toBe(false);
+
+    const item = await cat.asPrivateIndex().get(OWNER, id);
+    const content = unwrapContentKey(setKey, item?.wrappedContentKey ?? '');
+    expect(content).not.toBeNull();
+    const decrypted = await drain(
+      cryptBlobStream(content as NonNullable<typeof content>, stream(stored as Uint8Array)),
+    );
+    expect(Buffer.from(decrypted).equals(Buffer.from(plaintext))).toBe(true);
+  });
+
+  test('the sealed descriptor reveals name/mime/tags to its set key only', async () => {
+    const item = await cat.asPrivateIndex().get(OWNER, id);
+    const meta = openMeta<{ name: string; mime: string; tags: string[] }>(
+      setKey,
+      item?.sealedMeta ?? '',
+    );
+    expect(meta).toEqual({ name: 'secret.jpg', mime: 'image/jpeg', tags: ['hidden'] });
+    expect(openMeta(derivePasswordSetKey('wrong', salt), item?.sealedMeta ?? '')).toBeNull();
+  });
+
+  test('index.remove wipes the ciphertext blob too', async () => {
+    await cat.asPrivateIndex().remove(OWNER, id);
+    expect(await store.get(privateSourceKey(OWNER, id))).toBeNull();
+  });
+});
+
+describe('replaceContent — overwrite bytes, keep identity', () => {
+  let id: string;
+  let collectionId: string;
+
+  test('setup: ingest a tagged, collected, favorited doc', async () => {
+    const rec = await cat.ingest(CTX, {
+      name: 'notes.txt',
+      mime: 'text/plain',
+      body: stream('v1 bytes'),
+      tags: ['keep-me'],
+    });
+    id = rec.id;
+    const coll = await cat.createCollection(CTX, { name: 'Stuff' });
+    collectionId = coll.id;
+    await cat.addToCollection(CTX, collectionId, [id]);
+    await cat.setFavorite(CTX, id, true);
+  });
+
+  test('replaces bytes + re-derives mime/size/type while identity survives', async () => {
+    const updated = await cat.replaceContent(CTX, id, {
+      mime: 'application/pdf',
+      body: stream('v2 much longer replacement bytes'),
+      name: 'notes.pdf',
+    });
+    expect(updated?.id).toBe(id);
+    expect(updated?.name).toBe('notes.pdf');
+    expect(updated?.mime).toBe('application/pdf');
+    expect(updated?.fileType).toBe('doc');
+    expect(updated?.size).toBe('v2 much longer replacement bytes'.length);
+    expect(updated?.tags).toEqual(['keep-me']);
+    expect(updated?.favorite).toBe(true);
+    expect(updated?.collectionIds).toContain(collectionId);
+
+    const bytes = await store.get(fileBinaryKey(OWNER, id));
+    expect(new TextDecoder().decode(bytes as Uint8Array)).toBe('v2 much longer replacement bytes');
+  });
+
+  test('unknown id → null; private rows refuse replacement', async () => {
+    expect(await cat.replaceContent(CTX, 'nope', { mime: 'text/plain', body: stream('x') })).toBe(
+      null,
+    );
+    const salt = generateUserSalt();
+    const priv = await cat.ingestPrivate(
+      CTX,
+      { name: 'p.jpg', mime: 'image/jpeg', body: stream('p') },
+      { setKey: derivePasswordSetKey('pw', salt), keyMode: 'deniable' },
+    );
+    expect(
+      cat.replaceContent(CTX, priv.id, { mime: 'image/jpeg', body: stream('q') }),
+    ).rejects.toThrow(/private/);
+  });
+});
+
+describe('image ingest thumbnails (sharp)', () => {
+  test('an ingested image grows a poster-key thumbnail + has_thumbnail flips', async () => {
+    // A real encoded image, generated by the same optional peer the thumbnailer uses.
+    const sharp = (await import('sharp')).default;
+    const png = await sharp({
+      create: { width: 64, height: 48, channels: 3, background: { r: 200, g: 40, b: 40 } },
+    })
+      .png()
+      .toBuffer();
+
+    const rec = await cat.ingest(CTX, {
+      name: 'photo.png',
+      mime: 'image/png',
+      body: stream(new Uint8Array(png)),
+    });
+    expect(rec.processingStatus).toBe('ready'); // images are ready immediately; thumb is async
+
+    // The thumbnailer is fire-and-forget — poll briefly.
+    let thumbed = false;
+    for (let i = 0; i < 40 && !thumbed; i++) {
+      await new Promise((r) => setTimeout(r, 50));
+      thumbed = (await cat.get(CTX, rec.id))?.hasThumbnail ?? false;
+    }
+    expect(thumbed).toBe(true);
+    const poster = await store.get(fsPosterKey(OWNER, rec.id));
+    expect(poster).not.toBeNull();
+    expect((poster as Uint8Array).byteLength).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,157 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, 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, type SqliteFileCatalogueOptions } from './catalogue';
+import { FILE_CATALOGUE_MIGRATIONS } from './migrations';
+import type { FileCatalogue } from './types';
+
+// Task #475 — the seeded `random` order and the view-tracked `lastViewed` order. Both are
+// cursor-paginated like every other sort; `random` folds its shuffle seed into the cursor so a
+// visit reshuffles but paginates stably, and `lastViewed` orders by recorded watch-opens.
+
+const CTX: MediaCtx = { userId: 'u1', tenantId: 'orderings' };
+const NAMES = ['a.png', 'b.png', 'c.png', 'd.png', 'e.png', 'f.png', 'g.png', 'h.png'];
+
+describe('FileCatalogue — random + lastViewed orderings', () => {
+  let db: Database;
+  let root: string;
+  let clock: number;
+
+  const mkCatalogue = async (
+    extra?: Partial<SqliteFileCatalogueOptions>,
+  ): Promise<FileCatalogue> => {
+    const cat = createSqliteFileCatalogue({
+      db,
+      store: createDiskStore(root),
+      workDir: path.join(root, 'work'),
+      now: () => ++clock,
+      ...extra,
+    });
+    for (const name of NAMES) {
+      const body = new Response('x').body as ReadableStream<Uint8Array>;
+      await cat.ingest(CTX, { name, mime: 'image/png', body });
+    }
+    return cat;
+  };
+
+  // Walk the whole pool page-by-page under a sort; assert no gaps, no repeats.
+  const paginate = async (cat: FileCatalogue, sort: 'random' | 'lastViewed', limit: number) => {
+    const order: 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);
+        seen.add(f.id);
+        order.push(f.id);
+      }
+      cursor = page.nextCursor;
+      guard++;
+    } while (cursor && guard < 20);
+    return order;
+  };
+
+  beforeEach(async () => {
+    db = new Database(':memory:');
+    runMigrations(db, FILE_CATALOGUE_MIGRATIONS);
+    root = await mkdtemp(path.join(tmpdir(), 'fc-ord-'));
+    clock = 5000;
+  });
+  afterEach(async () => {
+    db.close();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  test("'random' is a full permutation of the pool (no gaps, no repeats)", async () => {
+    const cat = await mkCatalogue({ randomSeed: () => 12345 });
+    const oneShot = (await cat.list(CTX, { sort: 'random' })).items.map((f) => f.id);
+    expect(new Set(oneShot).size).toBe(NAMES.length);
+    // A fixed seed makes the shuffle deterministic, so paginated == one-shot.
+    const paged = await paginate(cat, 'random', 3);
+    expect(paged).toEqual(oneShot);
+    expect(paged.length).toBe(NAMES.length);
+  });
+
+  test("'random' pagination is stable across pages under one seed (cursor carries it)", async () => {
+    // The default (random) seed differs per first-page call, so we must thread the cursor: page 2
+    // recovers the seed from page 1's cursor and continues the SAME shuffle.
+    const cat = await mkCatalogue();
+    const p1 = await cat.list(CTX, { sort: 'random', limit: 3 });
+    expect(p1.nextCursor).toBeDefined();
+    const p2 = await cat.list(CTX, { sort: 'random', limit: 3, cursor: p1.nextCursor });
+    const p3 = await cat.list(CTX, { sort: 'random', limit: 3, cursor: p2.nextCursor });
+    const walked = [...p1.items, ...p2.items, ...p3.items].map((f) => f.id);
+    expect(new Set(walked).size).toBe(NAMES.length); // no repeats across the whole walk
+  });
+
+  test("'random' reshuffles between visits (different seed ⇒ different order)", async () => {
+    let seed = 1;
+    const cat = await mkCatalogue({ randomSeed: () => seed });
+    const first = (await cat.list(CTX, { sort: 'random' })).items.map((f) => f.id);
+    seed = 999999;
+    const second = (await cat.list(CTX, { sort: 'random' })).items.map((f) => f.id);
+    // Same set of files, but the order should differ under a different seed.
+    expect(new Set(first)).toEqual(new Set(second));
+    expect(second).not.toEqual(first);
+  });
+
+  test("'lastViewed' orders most-recently-viewed first, never-viewed last", async () => {
+    const cat = await mkCatalogue();
+    const all = (await cat.list(CTX)).items; // recent order
+    // View three files in a deliberate sequence; leave the rest unviewed.
+    const [x, y, z] = [all[5], all[2], all[7]];
+    await cat.recordView(CTX, x.id); // oldest view
+    await cat.recordView(CTX, y.id);
+    await cat.recordView(CTX, z.id); // newest view
+    const ordered = (await cat.list(CTX, { sort: 'lastViewed' })).items;
+    // Viewed files come first, newest-view first.
+    expect(ordered.slice(0, 3).map((f) => f.id)).toEqual([z.id, y.id, x.id]);
+    // The remaining five (never viewed) fill the tail.
+    expect(ordered.length).toBe(NAMES.length);
+    const tail = new Set(ordered.slice(3).map((f) => f.id));
+    expect(tail.has(x.id)).toBe(false);
+    expect(tail.size).toBe(NAMES.length - 3);
+  });
+
+  test("re-viewing a file moves it to the front of 'lastViewed' and paginates without gaps", async () => {
+    const cat = await mkCatalogue();
+    const all = (await cat.list(CTX)).items;
+    await cat.recordView(CTX, all[0].id);
+    await cat.recordView(CTX, all[1].id);
+    await cat.recordView(CTX, all[0].id); // bump all[0] back to the front
+    const ordered = (await cat.list(CTX, { sort: 'lastViewed' })).items;
+    expect(ordered[0].id).toBe(all[0].id);
+    // Full-pool pagination under lastViewed has no gaps/repeats and equals the one-shot order.
+    const paged = await paginate(cat, 'lastViewed', 3);
+    expect(paged).toEqual(ordered.map((f) => f.id));
+  });
+
+  test('recordView is owner-scoped — a foreign id records nothing', async () => {
+    const cat = await mkCatalogue();
+    const other: MediaCtx = { userId: 'u2', tenantId: 'someone-else' };
+    // Recording against an id that isn't the caller's must not create a view row.
+    await cat.recordView(CTX, 'no-such-file');
+    await cat.recordView(other, (await cat.list(CTX)).items[0].id);
+    // Nothing viewed for CTX ⇒ lastViewed degenerates to the id tie-break, still a full pool.
+    const ordered = (await cat.list(CTX, { sort: 'lastViewed' })).items;
+    expect(ordered.length).toBe(NAMES.length);
+  });
+
+  test("a deleted file drops its view row (no orphan skews 'lastViewed')", async () => {
+    const cat = await mkCatalogue();
+    const all = (await cat.list(CTX)).items;
+    await cat.recordView(CTX, all[0].id);
+    await cat.remove(CTX, all[0].id);
+    const rows = db
+      .query<{ n: number }, [string]>(`SELECT COUNT(*) AS n FROM file_views WHERE file_id = ?`)
+      .get(all[0].id);
+    expect(rows?.n).toBe(0);
+  });
+});