Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

93.0 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterAll } from 'vitest';
import { mkdtempSync, rmSync, mkdirSync } from 'fs';
import { writeFile, mkdir, readFile } from 'fs/promises';
import { tmpdir } from 'os';
import { join } from 'path';
import { mockNoPeerSync } from '../lib/mockPathsDataRoot.js';

// Real per-suite tmpdir backing the per-record media-collections/ layout that
// migration 059 produces. The fileUtils mock below overrides PATHS.data so the
// service + collectionStore land here instead of the real ./data; everything
// else (atomicWrite/readJSONFile/ensureDir) uses the real impl so the store's
// readdir/lstat/rm operate against a real fs tree.
const TEST_DATA_ROOT = mkdtempSync(join(tmpdir(), 'media-collections-test-'));
const COLLECTIONS_DIR = join(TEST_DATA_ROOT, 'media-collections');
const writeCounter = vi.hoisted(() => ({ baseHash: 0 }));

vi.mock('../lib/fileUtils.js', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    PATHS: { ...actual.PATHS, data: TEST_DATA_ROOT },
    atomicWrite: async (path, data) => {
      if (typeof path === 'string' && path.endsWith('sync_base_hashes.json')) writeCounter.baseHash += 1;
      return actual.atomicWrite(path, data);
    },
  };
});

// Suppress the fire-and-forget dynamic import so tests don't load the real
// peerSync module graph (which reads the live peer registry and imports
// universe/series services).
vi.mock('./sharing/peerSync.js', () => mockNoPeerSync());

let uuidCounter = 0;
vi.mock('crypto', async () => {
  const actual = await vi.importActual('crypto');
  return { ...actual, randomUUID: () => `uuid-${++uuidCounter}` };
});

const svc = await import('./mediaCollections.js');
const cj = await import('../lib/conflictJournal.js');
const { sanitizeRecordForWire } = await import('../lib/syncWire.js');

// Wipe + recreate the collections dir before every test so each starts clean.
// The empty dir means collectionStore's readdir is the source of truth and its
// process-local knownIds fallback never leaks ids across tests.
//
// Also wipe the conflict-journal + base-hash side store and reset the
// conflictJournal in-memory base-hash cache: mergeMediaCollectionsFromSync now
// seeds/advances per-collection base hashes, and that Map is module-level — so
// without a reset a base hash seeded by an earlier test's insert would bleed
// into a later test that reuses the same collection id and spuriously trip the
// 3-way divergence detector (base==null is the correct first-merge state).
function resetStore() {
  rmSync(COLLECTIONS_DIR, { recursive: true, force: true });
  rmSync(join(TEST_DATA_ROOT, 'sharing'), { recursive: true, force: true });
  rmSync(join(TEST_DATA_ROOT, 'conflict-journal'), { recursive: true, force: true });
  mkdirSync(COLLECTIONS_DIR, { recursive: true });
  cj.__resetBaseHashCacheForTests();
  writeCounter.baseHash = 0;
  uuidCounter = 0;
}

// Seed per-record files exactly as migration 059 would (one dir per record +
// a type-level index.json). Takes the same `{ collections: [...] }` shape the
// suite previously handed to the monolithic file store.
async function seedState({ collections = [] } = {}) {
  await mkdir(COLLECTIONS_DIR, { recursive: true });
  for (const c of collections) {
    const recDir = join(COLLECTIONS_DIR, c.id);
    await mkdir(recDir, { recursive: true });
    await writeFile(join(recDir, 'index.json'), JSON.stringify(c, null, 2));
  }
  await writeFile(join(COLLECTIONS_DIR, 'index.json'), JSON.stringify({
    schemaVersion: 1, type: 'mediaCollections', updatedAt: new Date().toISOString(), config: {},
  }, null, 2));
}

// Read the raw persisted record (pre-sanitize) for storage-level assertions.
async function readStored(id) {
  const raw = await readFile(join(COLLECTIONS_DIR, id, 'index.json'), 'utf-8').catch(() => null);
  return raw ? JSON.parse(raw) : null;
}

afterAll(() => {
  rmSync(TEST_DATA_ROOT, { recursive: true, force: true });
});

beforeEach(() => resetStore());

describe('mediaCollections service', () => {

  it('listCollections returns [] for fresh state', async () => {
    expect(await svc.listCollections()).toEqual([]);
  });

  it('createCollection persists a new collection', async () => {
    const c = await svc.createCollection({ name: 'Project A' });
    expect(c.id).toBe('uuid-1');
    expect(c.name).toBe('Project A');
    expect(c.items).toEqual([]);
    expect(c.coverKey).toBeNull();
    const all = await svc.listCollections();
    expect(all).toHaveLength(1);
  });

  it('listCollectionIds returns every collection id, including tombstoned ones', async () => {
    const a = await svc.createCollection({ name: 'A' });
    const b = await svc.createCollection({ name: 'B' });
    await svc.deleteCollection(b.id);
    // A directory listing, not a hydrate+filter — tombstoneGc's
    // ALL_ID_LISTERS.mediaCollection needs every id, live or not.
    expect((await svc.listCollectionIds()).sort()).toEqual([a.id, b.id].sort());
  });

  it('addItem rejects duplicate (same kind+ref)', async () => {
    const c = await svc.createCollection({ name: 'A' });
    await svc.addItem(c.id, { kind: 'image', ref: 'foo.png' });
    await expect(svc.addItem(c.id, { kind: 'image', ref: 'foo.png' }))
      .rejects.toMatchObject({ code: svc.ERR_DUPLICATE });
  });

  it('addItem rejects refs with true path-traversal segments (but allows .. inside a basename)', async () => {
    // Mirrors sanitizeItem's path-traversal rejection on the write boundary.
    // Reject path SEPARATORS and exact `.`/`..` path segments — NOT every
    // ref containing the substring `..`. Legitimate gallery filenames like
    // `my..render.png` round-trip through reads + peer sync and must be
    // addable through the API too.
    const c = await svc.createCollection({ name: 'A' });
    for (const ref of ['../etc/passwd', 'subdir/file.png', 'a\\b.png', '..', '.']) {
      await expect(svc.addItem(c.id, { kind: 'image', ref }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    }
    // And the inverse: refs with `..` in the basename SHOULD succeed.
    await expect(svc.addItem(c.id, { kind: 'image', ref: 'foo..bar.png' }))
      .resolves.toBeTruthy();
  });

  it('bulkUpdateCollectionItems rejects path-traversal refs up-front', async () => {
    const c = await svc.createCollection({ name: 'A' });
    await expect(svc.bulkUpdateCollectionItems(c.id, {
      add: [{ kind: 'image', ref: '../etc/passwd' }],
    })).rejects.toMatchObject({ code: svc.ERR_VALIDATION });
  });

  it('many-to-many: same item can live in multiple collections', async () => {
    const a = await svc.createCollection({ name: 'A' });
    const b = await svc.createCollection({ name: 'B' });
    await svc.addItem(a.id, { kind: 'video', ref: 'vid-1' });
    await svc.addItem(b.id, { kind: 'video', ref: 'vid-1' });
    const all = await svc.listCollections();
    expect(all[0].items).toHaveLength(1);
    expect(all[1].items).toHaveLength(1);
  });

  it('removeItem clears coverKey when the cover is removed', async () => {
    const c = await svc.createCollection({ name: 'A' });
    await svc.addItem(c.id, { kind: 'image', ref: 'cover.png' });
    await svc.updateCollection(c.id, { coverKey: 'image:cover.png' });
    const after = await svc.removeItem(c.id, 'image:cover.png');
    expect(after.coverKey).toBeNull();
  });

  it('updateCollection rejects coverKey not in items', async () => {
    const c = await svc.createCollection({ name: 'A' });
    await expect(svc.updateCollection(c.id, { coverKey: 'image:missing.png' }))
      .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
  });

  it('deleteCollection soft-deletes: absent from live list, present with deleted===true in includeDeleted list', async () => {
    const c = await svc.createCollection({ name: 'A' });
    await svc.deleteCollection(c.id);
    expect(await svc.listCollections()).toEqual([]);
    const all = await svc.listCollections({ includeDeleted: true });
    expect(all).toHaveLength(1);
    expect(all[0].deleted).toBe(true);
    expect(all[0].id).toBe(c.id);
  });

  it('write mutators map a malformed id to ERR_NOT_FOUND (not a raw store error → 500)', async () => {
    // A path-param id that fails the store allowlist (e.g. "has space",
    // "../escape") must surface as a clean NOT_FOUND — the same result the
    // pre-split scan gave — instead of throwing an uncoded error from
    // queueRecordWrite that the route mapper would turn into a 500.
    for (const bad of ['has space', '../escape', 'a/b']) {
      await expect(svc.addItem(bad, { kind: 'image', ref: 'x.png' }))
        .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
      await expect(svc.updateCollection(bad, { description: 'x' }))
        .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
      await expect(svc.deleteCollection(bad))
        .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
      await expect(svc.removeItem(bad, 'image:x.png'))
        .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
      await expect(svc.bulkUpdateCollectionItems(bad, { add: [{ kind: 'image', ref: 'x.png' }] }))
        .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
    }
  });

  it('deleteCollection clears coverKey on the persisted tombstone (no dangling cover in the wire record)', async () => {
    const c = await svc.createCollection({ name: 'WithCover' });
    await svc.addItem(c.id, { kind: 'image', ref: 'cover.png' });
    await svc.updateCollection(c.id, { coverKey: 'image:cover.png' });
    await svc.deleteCollection(c.id);
    // Assert on the PERSISTED record — listCollections' sanitizer would null a
    // dangling coverKey on read regardless, so inspect storage directly.
    const stored = await readStored(c.id);
    expect(stored.deleted).toBe(true);
    expect(stored.items).toEqual([]);
    expect(stored.coverKey).toBeNull();
  });

  it('deleteCollection emits recordDeleted for mediaCollection and receivable via recordEvents', async () => {
    const { recordEvents } = await import('./sharing/recordEvents.js');
    const deletedEvts = [];
    const handler = (evt) => deletedEvts.push(evt);
    recordEvents.on('deleted', handler);
    try {
      const c = await svc.createCollection({ name: 'B' });
      await svc.deleteCollection(c.id);
      expect(deletedEvts).toContainEqual(expect.objectContaining({ recordKind: 'mediaCollection', recordId: c.id }));
    } finally {
      recordEvents.off('deleted', handler);
    }
  });

  it('updateCollection throws ERR_NOT_FOUND on a soft-deleted collection', async () => {
    const c = await svc.createCollection({ name: 'Live' });
    await svc.deleteCollection(c.id);
    await expect(svc.updateCollection(c.id, { name: 'Revived' }))
      .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
  });

  it('item mutators (addItem/removeItem/bulkUpdateCollectionItems) throw ERR_NOT_FOUND on a tombstone', async () => {
    const c = await svc.createCollection({ name: 'Live' });
    await svc.addItem(c.id, { kind: 'image', ref: 'keep.png' });
    await svc.deleteCollection(c.id);
    // All three behave as not-found after soft-delete (no tombstone resurrection).
    await expect(svc.addItem(c.id, { kind: 'image', ref: 'new.png' }))
      .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
    await expect(svc.removeItem(c.id, 'image:keep.png'))
      .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
    await expect(svc.bulkUpdateCollectionItems(c.id, { add: [{ kind: 'image', ref: 'b.png' }] }))
      .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
  });

  it('deleteCollection is idempotent on an already-tombstoned record (no re-stamp, no re-emit)', async () => {
    const { recordEvents } = await import('./sharing/recordEvents.js');
    const c = await svc.createCollection({ name: 'DoubleDelete' });
    await svc.deleteCollection(c.id);
    const firstDeletedAt = (await svc.listCollections({ includeDeleted: true })).find((x) => x.id === c.id).deletedAt;
    await new Promise((r) => setTimeout(r, 5)); // ensure a later timestamp WOULD differ if re-stamped
    const deletedEvts = [];
    const handler = (evt) => deletedEvts.push(evt);
    recordEvents.on('deleted', handler);
    try {
      const res = await svc.deleteCollection(c.id);
      expect(res).toEqual({ id: c.id });
      const afterSecond = (await svc.listCollections({ includeDeleted: true })).find((x) => x.id === c.id);
      expect(afterSecond.deletedAt).toBe(firstDeletedAt); // not re-stamped
      expect(deletedEvts).toEqual([]);                    // not re-emitted
    } finally {
      recordEvents.off('deleted', handler);
    }
  });

  it('deleteCollection emits recordUpdated on the universe when the deleted collection was linked', async () => {
    const events = [];
    const { recordEvents } = await import('./sharing/recordEvents.js');
    const listener = (evt) => events.push(evt);
    recordEvents.on('updated', listener);
    try {
      const linked = await svc.findOrCreateUniverseCollection({
        universeId: 'u-1', universeName: 'Foo',
      });
      events.length = 0; // ignore the create-time emit
      await svc.deleteCollection(linked.id);
      expect(events).toContainEqual(expect.objectContaining({ recordKind: 'universe', recordId: 'u-1' }));
    } finally {
      recordEvents.off('updated', listener);
    }
  });

  it('deleteCollection does NOT emit when the deleted collection was unlinked', async () => {
    const events = [];
    const { recordEvents } = await import('./sharing/recordEvents.js');
    const listener = (evt) => events.push(evt);
    recordEvents.on('updated', listener);
    try {
      const c = await svc.createCollection({ name: 'Orphan' });
      events.length = 0;
      await svc.deleteCollection(c.id);
      expect(events).toEqual([]);
    } finally {
      recordEvents.off('updated', listener);
    }
  });

  it('findOrCreateCollectionByName returns the existing collection on case-insensitive match', async () => {
    const a = await svc.createCollection({ name: 'World: Foo' });
    const reused = await svc.findOrCreateCollectionByName({ name: '  world: foo  ' });
    expect(reused.id).toBe(a.id);
    expect(await svc.listCollections()).toHaveLength(1);
  });

  it('findOrCreateCollectionByName creates a new collection when no name matches', async () => {
    await svc.createCollection({ name: 'World: Foo' });
    const created = await svc.findOrCreateCollectionByName({
      name: 'World: Bar',
      description: 'desc',
    });
    expect(created.name).toBe('World: Bar');
    expect(created.description).toBe('desc');
    expect(await svc.listCollections()).toHaveLength(2);
  });

  it('findOrCreateCollectionByName validates name like createCollection', async () => {
    await expect(svc.findOrCreateCollectionByName({ name: '   ' }))
      .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
  });

  describe('bulkUpdateCollectionItems', () => {
    it('applies adds and removes in one write', async () => {
      const c = await svc.createCollection({ name: 'A' });
      await svc.addItem(c.id, { kind: 'image', ref: 'keep.png' });
      await svc.addItem(c.id, { kind: 'image', ref: 'drop.png' });
      const result = await svc.bulkUpdateCollectionItems(c.id, {
        add: [{ kind: 'image', ref: 'new1.png' }, { kind: 'video', ref: 'v1' }],
        remove: ['image:drop.png'],
      });
      expect(result.added).toBe(2);
      expect(result.removed).toBe(1);
      const refs = result.collection.items.map((it) => it.ref).sort();
      expect(refs).toEqual(['keep.png', 'new1.png', 'v1']);
    });

    it('is idempotent — re-adding an existing item is a no-op (not an error)', async () => {
      const c = await svc.createCollection({ name: 'A' });
      await svc.addItem(c.id, { kind: 'image', ref: 'foo.png' });
      const result = await svc.bulkUpdateCollectionItems(c.id, {
        add: [{ kind: 'image', ref: 'foo.png' }, { kind: 'image', ref: 'bar.png' }],
      });
      expect(result.added).toBe(1);
      expect(result.collection.items).toHaveLength(2);
    });

    it('silently ignores remove keys that aren\'t present', async () => {
      const c = await svc.createCollection({ name: 'A' });
      await svc.addItem(c.id, { kind: 'image', ref: 'foo.png' });
      const result = await svc.bulkUpdateCollectionItems(c.id, {
        remove: ['image:foo.png', 'image:ghost.png'],
      });
      expect(result.removed).toBe(1);
    });

    it('drops the cover when the cover item is removed', async () => {
      const c = await svc.createCollection({ name: 'A' });
      await svc.addItem(c.id, { kind: 'image', ref: 'cover.png' });
      await svc.updateCollection(c.id, { coverKey: 'image:cover.png' });
      const result = await svc.bulkUpdateCollectionItems(c.id, {
        remove: ['image:cover.png'],
      });
      expect(result.collection.coverKey).toBeNull();
    });

    it('rejects invalid item.kind without applying any partial mutation', async () => {
      const c = await svc.createCollection({ name: 'A' });
      await svc.addItem(c.id, { kind: 'image', ref: 'existing.png' });
      await expect(svc.bulkUpdateCollectionItems(c.id, {
        add: [{ kind: 'image', ref: 'ok.png' }, { kind: 'bogus', ref: 'bad.png' }],
        remove: ['image:existing.png'],
      })).rejects.toMatchObject({ code: svc.ERR_VALIDATION });
      const after = await svc.getCollection(c.id);
      expect(after.items.map((it) => it.ref)).toEqual(['existing.png']);
    });

    it('rejects when the collection would exceed ITEMS_MAX after the merge', async () => {
      const c = await svc.createCollection({ name: 'A' });
      // Seed a collection that's already at capacity via a hand-set file
      // (faster than calling addItem 5000 times).
      const all = await svc.listCollections();
      const fat = { ...all[0], items: Array.from({ length: svc.ITEMS_MAX }, (_, i) => ({
        kind: 'image', ref: `r${i}.png`, addedAt: new Date().toISOString(),
      })) };
      await seedState({ collections: [fat] });
      await expect(svc.bulkUpdateCollectionItems(c.id, {
        add: [{ kind: 'image', ref: 'overflow.png' }],
      })).rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    });

    it('throws ERR_NOT_FOUND for unknown collection id', async () => {
      await expect(svc.bulkUpdateCollectionItems('ghost', { add: [{ kind: 'image', ref: 'a.png' }] }))
        .rejects.toMatchObject({ code: svc.ERR_NOT_FOUND });
    });

    it('rejects non-array add or remove', async () => {
      const c = await svc.createCollection({ name: 'A' });
      await expect(svc.bulkUpdateCollectionItems(c.id, { add: 'not-array' }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
      await expect(svc.bulkUpdateCollectionItems(c.id, { remove: 'not-array' }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    });
  });

  describe('universe-linked collections', () => {
    it('updateCollection rejects a name change when the collection is universe-linked', async () => {
      const linked = await svc.findOrCreateCollectionByName({
        name: 'Universe: Foo', universeId: 'u-1',
      });
      await expect(svc.updateCollection(linked.id, { name: 'Renamed' }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
      // Other patches (coverKey, description) still go through.
      const updated = await svc.updateCollection(linked.id, { description: 'new desc' });
      expect(updated.description).toBe('new desc');
    });

    it('updateCollection allows a same-name PATCH (no-op) on universe-linked collections', async () => {
      const linked = await svc.findOrCreateCollectionByName({
        name: 'Universe: Foo', universeId: 'u-1',
      });
      const result = await svc.updateCollection(linked.id, { name: linked.name });
      expect(result.name).toBe('Universe: Foo');
    });

    it('universeCollectionNameFor produces the canonical "Universe: <name>" string and truncates', () => {
      expect(svc.universeCollectionNameFor('Foo')).toBe('Universe: Foo');
      const long = 'x'.repeat(200);
      expect(svc.universeCollectionNameFor(long).length).toBe(svc.NAME_MAX_LENGTH);
    });

    it('findCollectionByUniverseId locates the linked collection (or returns null)', async () => {
      expect(await svc.findCollectionByUniverseId('u-ghost')).toBeNull();
      const linked = await svc.findOrCreateCollectionByName({
        name: 'Universe: Foo', universeId: 'u-1',
      });
      const found = await svc.findCollectionByUniverseId('u-1');
      expect(found?.id).toBe(linked.id);
    });

    it('findCollectionByUniverseId falls back to the scan for a legacy record at a random id', async () => {
      // A pre-migration-038 collection carries the universeId at a random id,
      // so the deterministic loadOne fast-path misses it — the full scan must
      // still resolve it.
      const now = new Date().toISOString();
      await seedState({ collections: [
        { id: 'uuid-legacy', name: 'Universe: Foo', description: '', coverKey: null, universeId: 'u-1', items: [], createdAt: now, updatedAt: now },
      ] });
      const found = await svc.findCollectionByUniverseId('u-1');
      expect(found?.id).toBe('uuid-legacy');
    });

    it('findCollectionByUniverseId skips a tombstone at the deterministic id and finds the live legacy record', async () => {
      // A tombstone sitting at uc-<id> must not shadow a still-live collection
      // carrying the same universeId at a random id (fast-path excludes
      // deleted, fallback scan finds the live one).
      const now = new Date().toISOString();
      await seedState({ collections: [
        { id: 'uc-u-1', name: 'Universe: Foo', description: '', coverKey: null, universeId: 'u-1', items: [], createdAt: now, updatedAt: now, deleted: true, deletedAt: now },
        { id: 'uuid-live', name: 'Universe: Foo', description: '', coverKey: null, universeId: 'u-1', items: [], createdAt: now, updatedAt: now },
      ] });
      const found = await svc.findCollectionByUniverseId('u-1');
      expect(found?.id).toBe('uuid-live');
    });

    it('findCollectionByUniverseId prefers the canonical deterministic id when a live random-id duplicate also carries the stamp', async () => {
      // A transient duplicate — e.g. an unconverged peer pushed a random-id
      // copy while a converged canonical copy already exists. The fast path
      // deterministically returns the canonical uc-<id> record (the converged
      // cross-machine identity) rather than whichever the directory scan
      // happened to list first (the old loadAll order was filesystem-dependent,
      // so this also removes a source of non-determinism). Items union-merge on
      // sync, so the random-id duplicate is reconciled without loss.
      const now = new Date().toISOString();
      await seedState({ collections: [
        { id: 'uc-u-1', name: 'Universe: Foo', description: '', coverKey: null, universeId: 'u-1', items: [], createdAt: now, updatedAt: now },
        { id: 'uuid-dupe', name: 'Universe: Foo', description: '', coverKey: null, universeId: 'u-1', items: [], createdAt: now, updatedAt: now },
      ] });
      const found = await svc.findCollectionByUniverseId('u-1');
      expect(found?.id).toBe('uc-u-1');
    });

    it('renameCollectionForUniverse cascades a new name onto the linked collection', async () => {
      const linked = await svc.findOrCreateCollectionByName({
        name: 'Universe: Foo', universeId: 'u-1',
      });
      const updated = await svc.renameCollectionForUniverse('u-1', 'Bar');
      expect(updated.id).toBe(linked.id);
      expect(updated.name).toBe('Universe: Bar');
      const fresh = await svc.getCollection(linked.id);
      expect(fresh.name).toBe('Universe: Bar');
    });

    it('renameCollectionForUniverse is a no-op when no linked collection exists', async () => {
      const result = await svc.renameCollectionForUniverse('u-nope', 'Bar');
      expect(result).toBeNull();
    });

    it('renameCollectionForUniverse no-ops when the name already matches', async () => {
      const linked = await svc.findOrCreateCollectionByName({
        name: 'Universe: Foo', universeId: 'u-1',
      });
      const result = await svc.renameCollectionForUniverse('u-1', 'Foo');
      expect(result.name).toBe(linked.name);
      expect(result.updatedAt).toBe(linked.updatedAt);
    });

    it('renameCollectionForUniverse updates ALL matching collections (handles hand-edited duplicates)', async () => {
      // Two linked collections with the same universeId — could happen from
      // a pre-serialization race or a hand-edited file. Both must be
      // renamed; otherwise the straggler stays rename-locked under the
      // stale name.
      const a = await svc.findOrCreateCollectionByName({
        name: 'Universe: OldName', universeId: 'u-1',
      });
      await seedState({
        collections: [
          a,
          { ...a, id: 'dup-id', name: 'Universe: OldName' },
        ],
      });
      await svc.renameCollectionForUniverse('u-1', 'NewName');
      const all = await svc.listCollections();
      const linked = all.filter((c) => c.universeId === 'u-1');
      expect(linked).toHaveLength(2);
      expect(linked.map((c) => c.name).sort()).toEqual([
        'Universe: NewName', 'Universe: NewName',
      ]);
    });

    it('unlinkCollectionsForUniverse clears the universeId on linked collections (preserves items)', async () => {
      const linked = await svc.findOrCreateCollectionByName({
        name: 'Universe: Foo', universeId: 'u-1',
      });
      await svc.addItem(linked.id, { kind: 'image', ref: 'art.png' });
      const cleared = await svc.unlinkCollectionsForUniverse('u-1');
      expect(cleared).toEqual([linked.id]);
      const fresh = await svc.getCollection(linked.id);
      expect(fresh.universeId).toBeNull();
      expect(fresh.items).toHaveLength(1);
      // Lock released — renames now succeed.
      const renamed = await svc.updateCollection(linked.id, { name: 'Orphan Bucket' });
      expect(renamed.name).toBe('Orphan Bucket');
    });

    it('unlinkCollectionsForUniverse is a no-op when no collection is linked', async () => {
      expect(await svc.unlinkCollectionsForUniverse('ghost')).toEqual([]);
      expect(await svc.unlinkCollectionsForUniverse(null)).toEqual([]);
    });

    it('unlinkCollectionsForUniverse preserves updatedAt (cascade side-effect, not a user edit)', async () => {
      // The bump would let the unlinked bucket out-race its own tombstone on a
      // peer during a universe merge — see unlinkCollectionsForUniverse's note.
      await seedState({
        collections: [{
          id: 'uc-u1', name: 'Universe: Foo', description: '', coverKey: null,
          universeId: 'u-1', seriesId: null,
          items: [{ kind: 'image', ref: 'art.png', addedAt: '2026-05-26T13:00:00.000Z' }],
          createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-26T13:00:00.000Z',
        }],
      });
      await svc.unlinkCollectionsForUniverse('u-1');
      const fresh = (await svc.listCollections()).find(c => c.id === 'uc-u1');
      expect(fresh.universeId).toBeNull();
      expect(fresh.updatedAt).toBe('2026-05-26T13:00:00.000Z');
      expect(fresh.items).toHaveLength(1);
    });

    describe('findOrCreateUniverseCollection', () => {
      it('mints a DETERMINISTIC id (uc-<universeId>) so federated peers converge, not a random UUID', async () => {
        const c = await svc.findOrCreateUniverseCollection({ universeId: 'u-1', universeName: 'Foo' });
        expect(c.id).toBe('uc-u-1');
        expect(svc.linkedCollectionId({ universeId: 'u-1' })).toBe('uc-u-1');
        // Series mirror.
        const s = await svc.findOrCreateSeriesCollection({ seriesId: 's-9', seriesName: 'Bar' });
        expect(s.id).toBe('sc-s-9');
      });

      it('findOrCreateCollectionByName canonicalizes the id when backfilling a universe link onto an orphan', async () => {
        const orphan = await svc.findOrCreateCollectionByName({ name: 'Universe: Legacy' });
        expect(orphan.id).not.toMatch(/^uc-/); // standalone → random id
        // Referencing it WITH a universeId must adopt the deterministic id, not
        // keep the random one (which couldn't converge across peers).
        const linked = await svc.findOrCreateCollectionByName({ name: 'Universe: Legacy', universeId: 'u-legacy' });
        expect(linked.id).toBe('uc-u-legacy');
        expect(linked.universeId).toBe('u-legacy');
        const all = await svc.listCollections();
        expect(all.filter((c) => c.name === 'Universe: Legacy')).toHaveLength(1);
        expect(all.some((c) => c.id === orphan.id)).toBe(false); // old random id gone
      });

      it('backfill prefers an existing live canonical collection over promoting a same-named orphan', async () => {
        // Universe already has its canonical collection (with items)…
        const canonical = await svc.findOrCreateUniverseCollection({ universeId: 'u-x', universeName: 'X' });
        await svc.addItem(canonical.id, { kind: 'image', ref: 'keep.png' });
        // …plus a same-named orphan. A name-first backfill must NOT clobber the
        // canonical record's items — it returns the canonical one.
        const result = await svc.findOrCreateCollectionByName({ name: 'Universe: X', universeId: 'u-x' });
        expect(result.id).toBe('uc-u-x');
        expect(result.items.map((i) => i.ref)).toContain('keep.png');
      });

      it('findOrCreateCollectionByName slices an overlong universeId for both the id and the stored field', async () => {
        // An overlong owner id must yield the same canonical id the universeId-first
        // path computes (it slices to UNIVERSE_ID_MAX=80) — otherwise the backfill/
        // create here and findOrCreateUniverseCollection would diverge and duplicate.
        const overlong = 'u-' + 'x'.repeat(200);
        const sliced = overlong.slice(0, 80);
        const c = await svc.findOrCreateCollectionByName({ name: 'Universe: Big', universeId: overlong });
        expect(c.id).toBe(`uc-${sliced}`);
        expect(c.universeId).toBe(sliced);
        expect(svc.linkedCollectionId({ universeId: overlong })).toBe(`uc-${sliced}`);
      });

      it('findOrCreateCollectionByName trims a padded universeId so it converges (no uc- u1 -style ids)', async () => {
        // A padded id must normalize to the same canonical id an unpadded caller
        // gets — the presence guard and the slice operate on the trimmed value.
        const c = await svc.findOrCreateCollectionByName({ name: 'Universe: Padded', universeId: '  u-pad  ' });
        expect(c.id).toBe('uc-u-pad');
        expect(c.universeId).toBe('u-pad');
      });

      it('revives the deterministic id after delete instead of duplicating it (tombstone reclaim)', async () => {
        const c = await svc.findOrCreateUniverseCollection({ universeId: 'u-1', universeName: 'Foo' });
        await svc.addItem(c.id, { kind: 'image', ref: 'x.png' });
        await svc.deleteCollection(c.id); // tombstone at uc-u-1
        const revived = await svc.findOrCreateUniverseCollection({ universeId: 'u-1', universeName: 'Foo' });
        expect(revived.id).toBe('uc-u-1');
        expect(revived.deleted).toBeFalsy();
        // Exactly one live collection at the deterministic id — the tombstone was
        // reclaimed, not left to shadow the fresh record in listCollections' dedup.
        const live = await svc.listCollections();
        expect(live.filter((x) => x.id === 'uc-u-1')).toHaveLength(1);
      });

      it('returns the existing universeId-linked collection on second call', async () => {
        const first = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'Foo',
        });
        const second = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'Foo',
        });
        expect(second.id).toBe(first.id);
        expect(await svc.listCollections()).toHaveLength(1);
      });

      it('does NOT adopt an unlinked same-name collection — creates a fresh stamped bucket', async () => {
        // The unlinked legacy bucket might be (a) a true pre-link legacy
        // collection OR (b) an orphan left behind by deleteUniverse. We
        // can't tell them apart, and adopting (b) would silently mix the
        // deleted universe's renders into the new same-named universe.
        const legacy = await svc.createCollection({ name: 'Universe: Foo' });
        const linked = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'Foo',
        });
        expect(linked.id).not.toBe(legacy.id);
        expect(linked.universeId).toBe('u-1');
        // Both collections exist independently.
        expect(await svc.listCollections()).toHaveLength(2);
      });

      it('does NOT re-adopt a post-deleteUniverse orphan when a new same-named universe arrives', async () => {
        // Stand in for the deleteUniverse flow: link, fill, then unlink.
        const first = await svc.findOrCreateUniverseCollection({
          universeId: 'u-A', universeName: 'Cosmos',
        });
        await svc.addItem(first.id, { kind: 'image', ref: 'oldA.png' });
        await svc.unlinkCollectionsForUniverse('u-A');
        // A brand-new universe with the same display name renders for the
        // first time. The orphan still carries the canonical name, but
        // must NOT be adopted — otherwise oldA.png would silently appear
        // in the new universe's bucket.
        const fresh = await svc.findOrCreateUniverseCollection({
          universeId: 'u-B', universeName: 'Cosmos',
        });
        expect(fresh.id).not.toBe(first.id);
        expect(fresh.universeId).toBe('u-B');
        expect(fresh.items).toEqual([]);
        // The orphan kept its items — user can manually relink or rename.
        const orphan = await svc.getCollection(first.id);
        expect(orphan.universeId).toBeNull();
        expect(orphan.items.map((it) => it.ref)).toEqual(['oldA.png']);
      });

      it('refuses to adopt a same-name collection already linked to a different universe', async () => {
        const owned = await svc.findOrCreateUniverseCollection({
          universeId: 'u-A', universeName: 'Twin',
        });
        const own = await svc.findOrCreateUniverseCollection({
          universeId: 'u-B', universeName: 'Twin',
        });
        expect(own.id).not.toBe(owned.id);
        expect(own.universeId).toBe('u-B');
        expect(await svc.listCollections()).toHaveLength(2);
      });

      it('survives a universe rename — same universeId still resolves to the linked bucket', async () => {
        const first = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'OldName',
        });
        const reuse = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'NewName',
        });
        expect(reuse.id).toBe(first.id);
      });

      it('does NOT reconcile a drifted name on universeId-match path', async () => {
        // The caller-supplied universeName can be stale (a snapshot taken
        // before this call entered the write tail), so reconciling here
        // could revert a concurrent rename cascade. The cascade itself
        // (renameCollectionForUniverse) is the canonical path for name
        // updates; a stale name from a failed cascade survives until the
        // user re-triggers it.
        const first = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'NewName',
        });
        const current = await svc.listCollections();
        current[0] = { ...current[0], name: 'Universe: SomeOtherName' };
        await seedState({ collections: current });
        const found = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'NewName',
        });
        expect(found.id).toBe(first.id);
        // The drifted name is preserved — caller doesn't get to reconcile.
        expect(found.name).toBe('Universe: SomeOtherName');
      });

      it('serializes concurrent first-time filings (no race-induced duplicate or orphan)', async () => {
        // Same-universe race: cover + back-cover for the first time.
        await Promise.all([
          svc.findOrCreateUniverseCollection({ universeId: 'u-1', universeName: 'Race' }),
          svc.findOrCreateUniverseCollection({ universeId: 'u-1', universeName: 'Race' }),
        ]);
        const linked = await svc.findCollectionByUniverseId('u-1');
        expect(linked).not.toBeNull();
        expect(await svc.listCollections()).toHaveLength(1);
      });

      it('serializes concurrent first-time filings for two universes that share a display name', async () => {
        // Both universes named "Twin" but with different ids. Without the
        // mutex, both first-time creates would observe pre-create state and
        // the second writeAll would clobber the first.
        await Promise.all([
          svc.findOrCreateUniverseCollection({ universeId: 'u-A', universeName: 'Twin' }),
          svc.findOrCreateUniverseCollection({ universeId: 'u-B', universeName: 'Twin' }),
        ]);
        const a = await svc.findCollectionByUniverseId('u-A');
        const b = await svc.findCollectionByUniverseId('u-B');
        expect(a).not.toBeNull();
        expect(b).not.toBeNull();
        expect(a.id).not.toBe(b.id);
        expect(await svc.listCollections()).toHaveLength(2);
      });

      it('requires universeId and universeName', async () => {
        await expect(svc.findOrCreateUniverseCollection({ universeName: 'X' }))
          .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
        await expect(svc.findOrCreateUniverseCollection({ universeId: 'u-1' }))
          .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
      });

      it('normalizes an overlong universeId once — lookup and storage agree (no duplicate-on-retry)', async () => {
        // Caller passes a universeId longer than UNIVERSE_ID_MAX (80).
        // Without the normalize-once fix, the create path slices for
        // storage but the lookup compares the raw value — so the second
        // call wouldn't find the row it just created and would mint a
        // duplicate.
        const overlong = 'u-' + 'x'.repeat(200);
        const first = await svc.findOrCreateUniverseCollection({
          universeId: overlong, universeName: 'Foo',
        });
        const second = await svc.findOrCreateUniverseCollection({
          universeId: overlong, universeName: 'Foo',
        });
        expect(second.id).toBe(first.id);
        expect(await svc.listCollections()).toHaveLength(1);
        // The stamped id is the sliced value, not the raw overlong input.
        expect(first.universeId.length).toBeLessThanOrEqual(80);
      });
    });

    describe('cross-path write serialization', () => {
      it('addItem racing unlinkCollectionsForUniverse — neither drops items', async () => {
        // Two completely different write paths racing on the same file.
        // Without the file-level write tail, unlink's stale snapshot would
        // clobber the in-flight addItem that completed first.
        const linked = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'Foo',
        });
        await Promise.all([
          svc.addItem(linked.id, { kind: 'image', ref: 'race-1.png' }),
          svc.unlinkCollectionsForUniverse('u-1'),
          svc.addItem(linked.id, { kind: 'image', ref: 'race-2.png' }),
        ]);
        const fresh = await svc.getCollection(linked.id);
        const refs = fresh.items.map((it) => it.ref).sort();
        expect(refs).toEqual(['race-1.png', 'race-2.png']);
      });

      it('rename + addItem from two paths — both end states persist', async () => {
        const linked = await svc.findOrCreateUniverseCollection({
          universeId: 'u-1', universeName: 'Old',
        });
        await Promise.all([
          svc.addItem(linked.id, { kind: 'image', ref: 'cover.png' }),
          svc.renameCollectionForUniverse('u-1', 'New'),
        ]);
        const fresh = await svc.getCollection(linked.id);
        expect(fresh.name).toBe('Universe: New');
        expect(fresh.items.map((it) => it.ref)).toEqual(['cover.png']);
      });
    });
  });

  describe('series-linked collections', () => {
    it('updateCollection rejects a name change when the collection is series-linked', async () => {
      const linked = await svc.findOrCreateSeriesCollection({
        seriesId: 'ser-1', seriesName: 'Foo',
      });
      await expect(svc.updateCollection(linked.id, { name: 'Renamed' }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    });

    it('seriesCollectionNameFor produces the canonical "Series: <name>" string and truncates', () => {
      expect(svc.seriesCollectionNameFor('Foo')).toBe('Series: Foo');
      const long = 'x'.repeat(200);
      expect(svc.seriesCollectionNameFor(long).length).toBe(svc.NAME_MAX_LENGTH);
    });

    it('findCollectionBySeriesId locates the linked collection (or returns null)', async () => {
      expect(await svc.findCollectionBySeriesId('ser-ghost')).toBeNull();
      const linked = await svc.findOrCreateSeriesCollection({
        seriesId: 'ser-1', seriesName: 'Foo',
      });
      const found = await svc.findCollectionBySeriesId('ser-1');
      expect(found?.id).toBe(linked.id);
    });

    it('findCollectionBySeriesId falls back to the scan for a legacy record at a random id', async () => {
      const now = new Date().toISOString();
      await seedState({ collections: [
        { id: 'uuid-legacy', name: 'Series: Foo', description: '', coverKey: null, seriesId: 'ser-1', items: [], createdAt: now, updatedAt: now },
      ] });
      const found = await svc.findCollectionBySeriesId('ser-1');
      expect(found?.id).toBe('uuid-legacy');
    });

    it('findOrCreateSeriesCollection adopts a legacy series record at a random id instead of duplicating', async () => {
      // The deterministic loadOne fast-path misses a pre-migration-038 record,
      // so the full scan must still find + reuse it rather than minting a new
      // sc-<id> collection.
      const now = new Date().toISOString();
      await seedState({ collections: [
        { id: 'uuid-legacy', name: 'Series: Foo', description: '', coverKey: null, seriesId: 'ser-1', items: [], createdAt: now, updatedAt: now },
      ] });
      const got = await svc.findOrCreateSeriesCollection({ seriesId: 'ser-1', seriesName: 'Foo' });
      expect(got.id).toBe('uuid-legacy');
    });

    it('findOrCreateSeriesCollection returns the existing series-linked collection on second call', async () => {
      const first = await svc.findOrCreateSeriesCollection({
        seriesId: 'ser-1', seriesName: 'Foo',
      });
      const second = await svc.findOrCreateSeriesCollection({
        seriesId: 'ser-1', seriesName: 'Foo',
      });
      expect(second.id).toBe(first.id);
      expect(await svc.listCollections()).toHaveLength(1);
    });

    it('findOrCreateSeriesCollection requires both seriesId and seriesName', async () => {
      await expect(svc.findOrCreateSeriesCollection({ seriesName: 'X' }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
      await expect(svc.findOrCreateSeriesCollection({ seriesId: 'ser-1' }))
        .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    });

    it('renameCollectionForSeries cascades a new name onto the linked collection', async () => {
      const linked = await svc.findOrCreateSeriesCollection({
        seriesId: 'ser-1', seriesName: 'Foo',
      });
      const updated = await svc.renameCollectionForSeries('ser-1', 'Bar');
      expect(updated.id).toBe(linked.id);
      expect(updated.name).toBe('Series: Bar');
    });

    it('unlinkCollectionsForSeries clears the seriesId (preserves items)', async () => {
      const linked = await svc.findOrCreateSeriesCollection({
        seriesId: 'ser-1', seriesName: 'Foo',
      });
      await svc.addItem(linked.id, { kind: 'image', ref: 'cover.png' });
      const cleared = await svc.unlinkCollectionsForSeries('ser-1');
      expect(cleared).toEqual([linked.id]);
      const fresh = await svc.getCollection(linked.id);
      expect(fresh.seriesId).toBeNull();
      expect(fresh.items).toHaveLength(1);
      // Lock released — renames now succeed.
      const renamed = await svc.updateCollection(linked.id, { name: 'Orphan' });
      expect(renamed.name).toBe('Orphan');
    });

    it('unlinkCollectionsForSeries preserves updatedAt (cascade side-effect, not a user edit)', async () => {
      await seedState({
        collections: [{
          id: 'sc-ser1', name: 'Series: Foo', description: '', coverKey: null,
          universeId: null, seriesId: 'ser-1',
          items: [{ kind: 'image', ref: 'cover.png', addedAt: '2026-05-26T13:00:00.000Z' }],
          createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-26T13:00:00.000Z',
        }],
      });
      await svc.unlinkCollectionsForSeries('ser-1');
      const fresh = (await svc.listCollections()).find(c => c.id === 'sc-ser1');
      expect(fresh.seriesId).toBeNull();
      expect(fresh.updatedAt).toBe('2026-05-26T13:00:00.000Z');
      expect(fresh.items).toHaveLength(1);
    });

    it('addItem on a series-linked collection emits recordUpdated("series", seriesId)', async () => {
      const events = [];
      const { recordEvents } = await import('./sharing/recordEvents.js');
      const listener = (evt) => events.push(evt);
      recordEvents.on('updated', listener);
      try {
        const linked = await svc.findOrCreateSeriesCollection({
          seriesId: 'ser-1', seriesName: 'Foo',
        });
        events.length = 0;
        await svc.addItem(linked.id, { kind: 'image', ref: 'x.png' });
        expect(events).toContainEqual(expect.objectContaining({ recordKind: 'series', recordId: 'ser-1' }));
      } finally {
        recordEvents.off('updated', listener);
      }
    });

    it('deleteCollection emits recordUpdated("series", seriesId) when the deleted collection was series-linked', async () => {
      const events = [];
      const { recordEvents } = await import('./sharing/recordEvents.js');
      const listener = (evt) => events.push(evt);
      recordEvents.on('updated', listener);
      try {
        const linked = await svc.findOrCreateSeriesCollection({
          seriesId: 'ser-1', seriesName: 'Foo',
        });
        events.length = 0;
        await svc.deleteCollection(linked.id);
        expect(events).toContainEqual(expect.objectContaining({ recordKind: 'series', recordId: 'ser-1' }));
      } finally {
        recordEvents.off('updated', listener);
      }
    });

    it('sanitizer drops seriesId when universeId is also set (universeId wins)', async () => {
      await seedState({
        collections: [{
          id: 'c1', name: 'Mixed', items: [],
          universeId: 'u-1', seriesId: 'ser-1',
          createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z',
        }],
      });
      const [c] = await svc.listCollections();
      expect(c.universeId).toBe('u-1');
      expect(c.seriesId).toBeNull();
    });
  });

  it('sanitizes hand-edited JSON with bogus items', async () => {
    await seedState({
      collections: [
        { id: 'c1', name: 'OK', items: [
          { kind: 'image', ref: 'a.png' },
          { kind: 'image', ref: 'a.png' }, // duplicate -> dropped
          { kind: 'bogus', ref: 'b.png' }, // invalid kind -> dropped
          { ref: 'no-kind' },              // missing kind -> dropped
        ], coverKey: 'image:missing' },    // dangling cover -> nulled
      ],
    });
    const all = await svc.listCollections();
    expect(all[0].items).toHaveLength(1);
    expect(all[0].coverKey).toBeNull();
  });
});

describe('mergeMediaCollectionsFromSync', () => {
  it('returns {applied:false,count:0} for empty / non-array input', async () => {
    expect(await svc.mergeMediaCollectionsFromSync(null)).toEqual({ applied: false, count: 0 });
    expect(await svc.mergeMediaCollectionsFromSync('nope')).toEqual({ applied: false, count: 0 });
    expect(await svc.mergeMediaCollectionsFromSync([])).toEqual({ applied: false, count: 0 });
  });

  it('applies a multi-record batch (bounded fan-out) — all distinct ids land, count is exact', async () => {
    // The parallelized snapshot-apply path: a batch larger than the concurrency
    // bound, mixing inserts with a no-op (identical to an existing record, which
    // must NOT count as changed). Confirms every distinct id is written and the
    // returned count reflects only the records that actually changed.
    await seedState({
      collections: [{
        id: 'c-existing', name: 'Existing', description: '', coverKey: null,
        universeId: null, seriesId: null,
        items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-22T00:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z',
      }],
    });
    const remotes = [];
    for (let i = 0; i < 12; i++) {
      remotes.push({
        id: `c-batch-${i}`, name: `Batch ${i}`, description: '', coverKey: null,
        universeId: null, seriesId: null,
        items: [{ kind: 'image', ref: `b${i}.png`, addedAt: '2026-05-22T01:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T01:00:00Z',
      });
    }
    // A remote identical to the existing record → merges to no change.
    remotes.push({
      id: 'c-existing', name: 'Existing', description: '', coverKey: null,
      universeId: null, seriesId: null,
      items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-22T00:00:00Z' }],
      createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z',
    });

    const result = await svc.mergeMediaCollectionsFromSync(remotes);
    expect(result).toEqual({ applied: true, count: 12 }); // 12 new, the identical one no-ops
    const ids = (await svc.listCollections()).map((c) => c.id).sort();
    expect(ids).toContain('c-existing');
    for (let i = 0; i < 12; i++) expect(ids).toContain(`c-batch-${i}`);
  });

  it('rethrows after the whole batch settles + still flushes when a worker fails', async () => {
    // Error-handling contract for the parallel fan-out: if one record's write
    // throws, the call must reject (throw-on-failure preserved) — but only AFTER
    // every other in-flight worker settles, so no write leaks into the
    // background past the rejection, and the base-hash flush still runs for the
    // records that DID complete.
    const store = svc.mediaCollectionStore();
    const realSave = store.saveOneNow.bind(store);
    const saveSpy = vi.spyOn(store, 'saveOneNow').mockImplementation((id, rec) => {
      if (id === 'c-boom') return Promise.reject(new Error('disk full'));
      return realSave(id, rec);
    });
    const mk = (id) => ({
      id, name: id, description: '', coverKey: null, universeId: null, seriesId: null,
      items: [{ kind: 'image', ref: `${id}.png`, addedAt: '2026-05-22T01:00:00Z' }],
      createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T01:00:00Z',
    });
    const remotes = ['c-ok-1', 'c-ok-2', 'c-boom', 'c-ok-3'].map(mk);

    await expect(svc.mergeMediaCollectionsFromSync(remotes)).rejects.toThrow('disk full');
    saveSpy.mockRestore();

    // The non-failing records all persisted (no early abort skipped them) and
    // each carries a seeded base hash (the flush ran despite the throw).
    const persisted = new Set((await svc.listCollections()).map((c) => c.id));
    for (const id of ['c-ok-1', 'c-ok-2', 'c-ok-3']) {
      expect(persisted.has(id)).toBe(true);
      expect(await cj.getSyncBaseHash('mediaCollection', id)).not.toBeNull();
    }
    expect(persisted.has('c-boom')).toBe(false);
    expect(await cj.getSyncBaseHash('mediaCollection', 'c-boom')).toBeNull();
  });

  it('inserts a previously-unseen collection', async () => {
    const remote = {
      id: 'c-remote',
      name: 'From Peer',
      description: '',
      coverKey: null,
      universeId: 'u-1',
      seriesId: null,
      items: [{ kind: 'image', ref: 'peer.png', addedAt: '2026-05-22T01:00:00Z' }],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '2026-05-22T01:00:00Z',
    };
    const result = await svc.mergeMediaCollectionsFromSync([remote]);
    expect(result).toEqual({ applied: true, count: 1 });
    const all = await svc.listCollections();
    expect(all).toHaveLength(1);
    expect(all[0].id).toBe('c-remote');
    expect(all[0].items).toHaveLength(1);
    expect(all[0].items[0].ref).toBe('peer.png');
  });

  it('unions concurrently added items by kind:ref so neither side loses one', async () => {
    await seedState({
      collections: [{
        id: 'c1',
        name: 'A',
        description: '',
        coverKey: null,
        universeId: null,
        seriesId: null,
        items: [
          { kind: 'image', ref: 'local-only.png', addedAt: '2026-05-22T01:00:00Z' },
          { kind: 'image', ref: 'shared.png', addedAt: '2026-05-22T01:00:00Z' },
        ],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-22T01:00:00Z',
      }],
    });
    const remote = {
      id: 'c1',
      name: 'A',
      description: '',
      coverKey: null,
      universeId: null,
      seriesId: null,
      items: [
        { kind: 'image', ref: 'remote-only.png', addedAt: '2026-05-22T02:00:00Z' },
        { kind: 'image', ref: 'shared.png', addedAt: '2026-05-22T02:00:00Z' },
      ],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '2026-05-22T02:00:00Z',
    };
    const result = await svc.mergeMediaCollectionsFromSync([remote]);
    expect(result.applied).toBe(true);
    const all = await svc.listCollections();
    const refs = all[0].items.map(i => i.ref).sort();
    expect(refs).toEqual(['local-only.png', 'remote-only.png', 'shared.png']);
    // Shared item keeps the EARLIER addedAt (sync replay shouldn't bump it)
    const shared = all[0].items.find(i => i.ref === 'shared.png');
    expect(shared.addedAt).toBe('2026-05-22T01:00:00Z');
  });

  it('LWW: newer remote wins on top-level scalars (name, description, coverKey)', async () => {
    await seedState({
      collections: [{
        id: 'c1',
        name: 'Old Name',
        description: 'old',
        coverKey: null,
        universeId: null,
        seriesId: null,
        items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-22T01:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-22T01:00:00Z',
      }],
    });
    const remote = {
      id: 'c1',
      name: 'New Name',
      description: 'new',
      coverKey: 'image:a.png',
      universeId: null,
      seriesId: null,
      items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-22T01:00:00Z' }],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '2026-05-22T03:00:00Z',
    };
    await svc.mergeMediaCollectionsFromSync([remote]);
    const [merged] = await svc.listCollections();
    expect(merged.name).toBe('New Name');
    expect(merged.description).toBe('new');
    expect(merged.coverKey).toBe('image:a.png');
    expect(merged.updatedAt).toBe('2026-05-22T03:00:00Z');
  });

  it('LWW: older remote loses on scalars, but items still union', async () => {
    await seedState({
      collections: [{
        id: 'c1',
        name: 'Local',
        description: 'local',
        coverKey: null,
        universeId: null,
        seriesId: null,
        items: [{ kind: 'image', ref: 'local.png', addedAt: '2026-05-22T02:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-22T03:00:00Z',
      }],
    });
    const remote = {
      id: 'c1',
      name: 'Remote',
      description: 'remote',
      coverKey: null,
      universeId: null,
      seriesId: null,
      items: [{ kind: 'image', ref: 'remote.png', addedAt: '2026-05-22T01:00:00Z' }],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '2026-05-22T01:00:00Z',
    };
    await svc.mergeMediaCollectionsFromSync([remote]);
    const [merged] = await svc.listCollections();
    // Newer local wins on scalars
    expect(merged.name).toBe('Local');
    expect(merged.description).toBe('local');
    expect(merged.updatedAt).toBe('2026-05-22T03:00:00Z');
    // But items still union — that's the entire point of the merge
    expect(merged.items.map(i => i.ref).sort()).toEqual(['local.png', 'remote.png']);
  });

  it('universe-merge cascade race: an unlink does not out-race the collection tombstone', async () => {
    // Repro of the real peer bug. A universe merge tombstones the loser auto-
    // collection (with the merge-time updatedAt) AND tombstones the loser
    // universe. On the receiving peer the UNIVERSE tombstone's cascade
    // (unlinkCollectionsForUniverse) lands first and nulls the collection's
    // universeId. If that unlink bumped updatedAt to "now", the collection's
    // own (older) tombstone would then lose LWW and a live duplicate would
    // survive. Because the cascade unlink preserves updatedAt, the tombstone
    // still wins and converges to deleted.
    await seedState({
      collections: [{
        id: 'uc-loser',
        name: 'Universe: Clandestiny',
        description: '',
        coverKey: null,
        universeId: 'u-loser',
        seriesId: null,
        items: [{ kind: 'image', ref: 'folded.png', addedAt: '2026-05-26T13:00:00.000Z' }],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-26T13:00:00.000Z', // last real edit, BEFORE the merge
      }],
    });
    // 1. Universe tombstone cascade hits the receiver first.
    await svc.unlinkCollectionsForUniverse('u-loser');
    const afterUnlink = (await svc.listCollections()).find(c => c.id === 'uc-loser');
    expect(afterUnlink.universeId).toBeNull();
    expect(afterUnlink.updatedAt).toBe('2026-05-26T13:00:00.000Z'); // NOT bumped
    // 2. The collection's own tombstone (merge-time, newer than the last edit) arrives.
    await svc.mergeMediaCollectionsFromSync([{
      id: 'uc-loser',
      name: 'Universe: Clandestiny',
      description: '',
      coverKey: null,
      universeId: null,
      seriesId: null,
      items: [],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '2026-05-26T13:31:33.807Z',
      deleted: true,
      deletedAt: '2026-05-26T13:31:33.807Z',
    }]);
    // No live duplicate left behind.
    expect((await svc.listCollections()).some(c => c.id === 'uc-loser')).toBe(false);
    const tomb = (await svc.listCollections({ includeDeleted: true })).find(c => c.id === 'uc-loser');
    expect(tomb.deleted).toBe(true);
    expect(tomb.items).toEqual([]);
  });

  it('reports count:0 when nothing actually changes (no-op no-op)', async () => {
    await seedState({
      collections: [{
        id: 'c1',
        name: 'A',
        description: '',
        coverKey: null,
        universeId: null,
        seriesId: null,
        items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-22T01:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-22T01:00:00Z',
      }],
    });
    const same = {
      id: 'c1',
      name: 'A',
      description: '',
      coverKey: null,
      universeId: null,
      seriesId: null,
      items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-22T01:00:00Z' }],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '2026-05-22T01:00:00Z',
    };
    const result = await svc.mergeMediaCollectionsFromSync([same]);
    expect(result).toEqual({ applied: false, count: 0 });
  });

  it('drops dangling coverKey that points at an item missing post-union', async () => {
    await seedState({
      collections: [{
        id: 'c1',
        name: 'A',
        description: '',
        coverKey: null,
        universeId: null,
        seriesId: null,
        items: [{ kind: 'image', ref: 'local.png', addedAt: '2026-05-22T01:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-22T01:00:00Z',
      }],
    });
    const remote = {
      id: 'c1',
      name: 'A',
      description: '',
      coverKey: 'image:nope.png', // points at an item that doesn't exist
      universeId: null,
      seriesId: null,
      items: [{ kind: 'image', ref: 'remote.png', addedAt: '2026-05-22T02:00:00Z' }],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '2026-05-22T03:00:00Z',
    };
    await svc.mergeMediaCollectionsFromSync([remote]);
    const [merged] = await svc.listCollections();
    expect(merged.coverKey).toBeNull();
  });

  it('skips records that fail sanitization (missing id, empty name)', async () => {
    const result = await svc.mergeMediaCollectionsFromSync([
      { name: 'no-id', items: [] },
      { id: 'has-id', name: '', items: [] },
      { id: 'good', name: 'Real', description: '', coverKey: null, universeId: null, seriesId: null, items: [], createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z' },
    ]);
    expect(result).toEqual({ applied: true, count: 1 });
    const all = await svc.listCollections();
    expect(all).toHaveLength(1);
    expect(all[0].id).toBe('good');
  });

  it('skips a record whose id is not a valid store path-segment WITHOUT aborting the batch', async () => {
    // A malformed/peer-supplied id like '../../escape' can't be persisted (the
    // store's id allowlist would throw inside queueRecordWrite). sanitizeCollection
    // must drop it at the boundary so the valid records in the same batch still merge.
    const result = await svc.mergeMediaCollectionsFromSync([
      { id: '../../escape', name: 'Evil', description: '', coverKey: null, universeId: null, seriesId: null, items: [], createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z' },
      { id: 'has space', name: 'Spacey', items: [], createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z' },
      { id: 'valid-after-bad', name: 'Survivor', description: '', coverKey: null, universeId: null, seriesId: null, items: [], createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z' },
    ]);
    expect(result).toEqual({ applied: true, count: 1 });
    const all = await svc.listCollections({ includeDeleted: true });
    expect(all.map((c) => c.id)).toEqual(['valid-after-bad']);
  });

  it('rejects items whose ref contains path-traversal tokens', async () => {
    // Defense in depth — a peer can push a collection containing a ref
    // like '../etc/passwd' via the linkedCollection field. sanitizeItem
    // must drop these BEFORE they hit disk so the sender-side
    // buildAssetManifestForCollection (and any future downstream consumer)
    // never sees an unsafe ref.
    const result = await svc.mergeMediaCollectionsFromSync([{
      id: 'c-evil',
      name: 'Evil',
      description: '',
      coverKey: null,
      universeId: null,
      seriesId: null,
      items: [
        { kind: 'image', ref: '../etc/passwd', addedAt: '2026-05-22T01:00:00Z' },
        { kind: 'image', ref: 'subdir/file.png', addedAt: '2026-05-22T01:00:00Z' },
        { kind: 'image', ref: 'C:\\Windows\\System32', addedAt: '2026-05-22T01:00:00Z' },
        { kind: 'image', ref: 'real.png', addedAt: '2026-05-22T01:00:00Z' },
      ],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '2026-05-22T01:00:00Z',
    }]);
    expect(result.applied).toBe(true);
    const [merged] = await svc.listCollections();
    // Only the safe ref survived sanitization
    expect(merged.items).toHaveLength(1);
    expect(merged.items[0].ref).toBe('real.png');
  });

  it('compares collection updatedAt as parsed milliseconds (not lexicographic)', async () => {
    // Same hazard as the addedAt case: sanitizeCollection accepts any
    // Date.parse-able string for `updatedAt`, so a non-ISO but valid
    // timestamp could compare incorrectly as a string and flip LWW the
    // wrong way. The slash-format timestamp here ('05/22/2026 18:00 UTC')
    // sorts BEFORE the ISO timestamp lexicographically ('0' < '2'), but
    // it's actually LATER in real time — so remote should win.
    await seedState({
      collections: [{
        id: 'c1', name: 'Local', description: 'local', coverKey: null,
        universeId: null, seriesId: null,
        items: [],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-22T10:00:00Z',
      }],
    });
    await svc.mergeMediaCollectionsFromSync([{
      id: 'c1', name: 'Remote', description: 'remote', coverKey: null,
      universeId: null, seriesId: null,
      items: [],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: '05/22/2026 18:00:00 UTC',
    }]);
    const [merged] = await svc.listCollections();
    // Numeric compare: 18:00 > 10:00 → remote wins → name flips to "Remote"
    expect(merged.name).toBe('Remote');
    expect(merged.description).toBe('remote');
  });

  it('LWW: unparseable updatedAt never overrides a valid one', async () => {
    // Defense in depth — a hand-edit or corrupted record shipping a
    // garbage `updatedAt` shouldn't be able to claim "newer" than a valid
    // local record and overwrite its scalars.
    await seedState({
      collections: [{
        id: 'c1', name: 'Local', description: 'local', coverKey: null,
        universeId: null, seriesId: null,
        items: [],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-22T03:00:00Z',
      }],
    });
    await svc.mergeMediaCollectionsFromSync([{
      id: 'c1', name: 'Remote', description: 'remote', coverKey: null,
      universeId: null, seriesId: null,
      items: [],
      createdAt: '2026-05-22T00:00:00Z',
      updatedAt: 'not a real timestamp',
    }]);
    const [merged] = await svc.listCollections();
    expect(merged.name).toBe('Local');
    expect(merged.description).toBe('local');
  });

  it('preserves deleted + deletedAt through sync merge', async () => {
    await svc.mergeMediaCollectionsFromSync([{
      id: 'c1', name: 'C1', items: [],
      deleted: true, deletedAt: '2026-05-23T00:00:00.000Z',
      updatedAt: '2026-05-23T00:00:00.000Z',
    }]);
    const live = await svc.listCollections();
    expect(live.find((c) => c.id === 'c1')).toBeUndefined();
    const all = await svc.listCollections({ includeDeleted: true });
    const c = all.find((x) => x.id === 'c1');
    expect(c?.deleted).toBe(true);
    expect(c?.deletedAt).toBe('2026-05-23T00:00:00.000Z');
  });

  it('a newer remote tombstone deletes a local live collection', async () => {
    const c = await svc.createCollection({ name: 'WillDie' });
    const tombstone = {
      id: c.id,
      name: 'WillDie',
      description: '',
      coverKey: null,
      universeId: null,
      seriesId: null,
      items: [],
      createdAt: c.createdAt,
      updatedAt: '2099-01-01T00:00:00.000Z',
      deleted: true,
      deletedAt: '2099-01-01T00:00:00.000Z',
    };
    await svc.mergeMediaCollectionsFromSync([tombstone]);
    expect(await svc.listCollections()).toEqual([]);
    const all = await svc.listCollections({ includeDeleted: true });
    const found = all.find((x) => x.id === c.id);
    expect(found?.deleted).toBe(true);
  });

  it('an older remote tombstone does NOT delete a newer local collection', async () => {
    const c = await svc.createCollection({ name: 'Survivor' });
    const tombstone = {
      id: c.id,
      name: 'Survivor',
      description: '',
      coverKey: null,
      universeId: null,
      seriesId: null,
      items: [],
      createdAt: c.createdAt,
      updatedAt: '2000-01-01T00:00:00.000Z',
      deleted: true,
      deletedAt: '2000-01-01T00:00:00.000Z',
    };
    await svc.mergeMediaCollectionsFromSync([tombstone]);
    const live = await svc.listCollections();
    expect(live.find((x) => x.id === c.id)).toBeTruthy();
    expect(live.find((x) => x.id === c.id)?.deleted).toBeFalsy();
  });

  it('a remote tombstone for an unknown id is recorded as a tombstone (no resurrection)', async () => {
    const tombstone = {
      id: 'ghost-id',
      name: 'Ghost',
      description: '',
      coverKey: null,
      universeId: null,
      seriesId: null,
      items: [],
      createdAt: '2026-05-23T00:00:00.000Z',
      updatedAt: '2026-05-23T00:00:00.000Z',
      deleted: true,
      deletedAt: '2026-05-23T00:00:00.000Z',
    };
    await svc.mergeMediaCollectionsFromSync([tombstone]);
    expect(await svc.listCollections()).toEqual([]);
    const all = await svc.listCollections({ includeDeleted: true });
    const found = all.find((x) => x.id === 'ghost-id');
    expect(found?.deleted).toBe(true);
  });

  it('a tombstone missing deletedAt falls back to updatedAt (not the older createdAt)', async () => {
    // A hand-edited / legacy tombstone may carry deleted:true with no explicit
    // deletedAt. The effective deletion time should align with the most-recent
    // timestamp (updatedAt), not createdAt — otherwise LWW + GC see it as far
    // older than it really is.
    await seedState({
      collections: [{
        id: 'c1', name: 'Gone', description: '', coverKey: null,
        universeId: null, seriesId: null, items: [],
        createdAt: '2026-01-01T00:00:00.000Z',
        updatedAt: '2026-05-22T03:00:00.000Z',
        deleted: true,
        // deletedAt intentionally omitted
      }],
    });
    const [c] = await svc.listCollections({ includeDeleted: true });
    expect(c.deleted).toBe(true);
    expect(c.deletedAt).toBe('2026-05-22T03:00:00.000Z');
  });

  it('compares addedAt as parsed milliseconds (not lexicographic) when picking the earlier item', async () => {
    // sanitizeItem accepts any Date.parse-able string, not strictly ISO-8601.
    // Lexicographic compare would order "05/22/2026 ..." AFTER "2026-..." (the
    // digit '0' sorts before '2'), but as parsed timestamps the slash-format
    // is actually EARLIER here. Numeric compare keeps "earlier wins" honest
    // across formats.
    await seedState({
      collections: [{
        id: 'c1', name: 'A', description: '', coverKey: null,
        universeId: null, seriesId: null,
        items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-22T10:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T01:00:00Z',
      }],
    });
    await svc.mergeMediaCollectionsFromSync([{
      id: 'c1', name: 'A', description: '', coverKey: null,
      universeId: null, seriesId: null,
      items: [{ kind: 'image', ref: 'a.png', addedAt: '05/22/2026 08:00:00 UTC' }],
      createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T02:00:00Z',
    }]);
    const [merged] = await svc.listCollections();
    // The 08:00 slash-format timestamp is earlier than 10:00 ISO; numeric
    // compare picks it. Lexicographic compare would have picked the ISO one.
    expect(Date.parse(merged.items[0].addedAt)).toBe(Date.parse('05/22/2026 08:00:00 UTC'));
  });
});

describe('mergeMediaCollectionsFromSync — conflict journal', () => {
  const baseColl = (over = {}) => ({
    id: 'c1', name: 'Bucket', description: 'd', coverKey: null,
    universeId: null, seriesId: null,
    items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-01T00:00:00Z' }],
    createdAt: '2026-05-01T00:00:00Z', updatedAt: '2026-05-01T00:00:00Z', ...over,
  });
  const journalEntries = () => cj.conflictJournalStore().loadAll();

  it('seeds a base hash on first insert (new record) so a future divergence is detectable', async () => {
    await svc.mergeMediaCollectionsFromSync([baseColl()]);
    expect(await cj.getSyncBaseHash('mediaCollection', 'c1'))
      .toBe(cj.contentHashForRecord('mediaCollection', baseColl()));
    expect(await journalEntries()).toHaveLength(0);
  });

  it('item-only divergence does NOT journal (concurrent adds union-merge, never lost)', async () => {
    // Establish a shared base, then both sides add different items only.
    await svc.mergeMediaCollectionsFromSync([baseColl()]);
    // Local adds an item directly on disk; remote arrives with a different item.
    await seedState({ collections: [baseColl({
      items: [
        { kind: 'image', ref: 'a.png', addedAt: '2026-05-01T00:00:00Z' },
        { kind: 'image', ref: 'local.png', addedAt: '2026-05-02T00:00:00Z' },
      ],
      updatedAt: '2026-05-02T00:00:00Z',
    })] });
    const before = (await journalEntries()).length;
    await svc.mergeMediaCollectionsFromSync([baseColl({
      items: [
        { kind: 'image', ref: 'a.png', addedAt: '2026-05-01T00:00:00Z' },
        { kind: 'image', ref: 'remote.png', addedAt: '2026-05-03T00:00:00Z' },
      ],
      updatedAt: '2026-05-03T00:00:00Z',
    })]);
    expect((await journalEntries()).length).toBe(before);
    // ...and both items survived the union (the whole reason scalars-only is safe).
    const [merged] = await svc.listCollections();
    expect(merged.items.map((i) => i.ref).sort()).toEqual(['a.png', 'local.png', 'remote.png']);
  });

  it('journals when a newer remote overwrites a diverged local scalar (name)', async () => {
    await svc.mergeMediaCollectionsFromSync([baseColl()]);          // seed base
    await seedState({ collections: [baseColl({ name: 'LOCAL rename', updatedAt: '2026-05-02T00:00:00Z' })] });
    await svc.mergeMediaCollectionsFromSync([baseColl({ name: 'REMOTE rename', updatedAt: '2026-05-03T00:00:00Z' })]);
    const entries = await journalEntries();
    expect(entries).toHaveLength(1);
    expect(entries[0]).toMatchObject({ recordKind: 'mediaCollection', recordId: 'c1', status: 'pending' });
    expect(entries[0].localSnapshot.name).toBe('LOCAL rename');
    // Remote won LWW; local archived.
    const [merged] = await svc.listCollections();
    expect(merged.name).toBe('REMOTE rename');
  });

  it('does NOT journal when local wins LWW (its scalars are kept, nothing lost)', async () => {
    await svc.mergeMediaCollectionsFromSync([baseColl()]);          // seed base
    await seedState({ collections: [baseColl({ name: 'LOCAL rename', updatedAt: '2026-05-05T00:00:00Z' })] });
    // Older remote — local wins; no overwrite, no journal.
    await svc.mergeMediaCollectionsFromSync([baseColl({ name: 'REMOTE rename', updatedAt: '2026-05-03T00:00:00Z' })]);
    expect(await journalEntries()).toHaveLength(0);
    const [merged] = await svc.listCollections();
    expect(merged.name).toBe('LOCAL rename');
  });
});

describe('item removal records (#12433)', () => {
  const T0 = '2026-05-01T00:00:00.000Z';
  const coll = (over = {}) => ({
    id: 'c1', name: 'Bucket', description: '', coverKey: null, universeId: null, seriesId: null,
    items: [
      { kind: 'image', ref: 'keep.png', addedAt: T0 },
      { kind: 'image', ref: 'gone.png', addedAt: T0 },
    ],
    createdAt: T0, updatedAt: T0, ...over,
  });
  const refs = async () => (await svc.getCollection('c1')).items.map((i) => i.ref).sort();

  it('a removal sticks when merging with a peer that still holds the item', async () => {
    await seedState({ collections: [coll()] });
    await svc.removeItem('c1', 'image:gone.png');
    // The peer never saw the removal (or is a v1 peer that strips removal
    // records): it still lists the item at its original addedAt.
    await svc.mergeMediaCollectionsFromSync([coll({ updatedAt: '2026-05-02T00:00:00.000Z' })]);
    expect(await refs()).toEqual(['keep.png']);
    // The record crosses the wire, so the other side drops its copy in turn.
    const wire = sanitizeRecordForWire('mediaCollection', await svc.getCollection('c1'));
    expect(Object.keys(wire.removedItems)).toEqual(['image:gone.png']);
    await svc.deleteCollection('c1');
    await svc.mergeMediaCollectionsFromSync([coll({ id: 'c2' })]);
    await svc.mergeMediaCollectionsFromSync([{ ...wire, id: 'c2' }]);
    expect((await svc.getCollection('c2')).items.map((i) => i.ref)).toEqual(['keep.png']);
  });

  it('a gallery delete sticks in every collection that held the item', async () => {
    await seedState({ collections: [coll(), coll({ id: 'c2' })] });
    expect(await svc.removeItemFromAllCollections('image', 'gone.png')).toBe(2);
    await svc.mergeMediaCollectionsFromSync([coll(), coll({ id: 'c2' })]);
    for (const c of await svc.listCollections()) expect(c.items.map((i) => i.ref)).toEqual(['keep.png']);
  });

  it('a re-add after the removal wins, and a stale copy cannot drag it back under the removal', async () => {
    await seedState({ collections: [coll()] });
    await svc.removeItem('c1', 'image:gone.png');
    const { removedItems } = await svc.getCollection('c1');
    await svc.addItem('c1', { kind: 'image', ref: 'gone.png' });
    // Stale peer copy at the original addedAt, then a peer that only knows the removal.
    await svc.mergeMediaCollectionsFromSync([coll()]);
    await svc.mergeMediaCollectionsFromSync([coll({ items: [coll().items[0]], removedItems })]);
    const merged = await svc.getCollection('c1');
    expect(merged.items.map((i) => i.ref).sort()).toEqual(['gone.png', 'keep.png']);
    const readded = merged.items.find((i) => i.ref === 'gone.png');
    expect(Date.parse(readded.addedAt)).toBeGreaterThan(Date.parse(removedItems['image:gone.png']));
  });

  it('a removal wins only over copies that predate it — a newer remote add survives', async () => {
    await seedState({ collections: [coll({ removedItems: { 'image:gone.png': '2026-05-02T00:00:00.000Z' } })] });
    expect(await refs()).toEqual(['keep.png']);
    await svc.mergeMediaCollectionsFromSync([coll({
      items: [{ kind: 'image', ref: 'gone.png', addedAt: '2026-05-03T00:00:00.000Z' }],
    })]);
    expect(await refs()).toEqual(['gone.png', 'keep.png']);
  });

  it('drops malformed peer-supplied removal records instead of persisting them', async () => {
    await svc.mergeMediaCollectionsFromSync([coll({
      removedItems: {
        'image:../../etc/passwd': '2026-05-02T00:00:00.000Z',
        'audio:x.mp3': '2026-05-02T00:00:00.000Z',
        'image:bad-date.png': 'not a date',
        'image:gone.png': '2026-05-02T00:00:00.000Z',
      },
    })]);
    expect((await svc.getCollection('c1')).removedItems).toEqual({ 'image:gone.png': '2026-05-02T00:00:00.000Z' });
    expect(await refs()).toEqual(['keep.png']);
  });

  it('pruneCollectionItemRemovals drops only records older than the cutoff, without bumping updatedAt', async () => {
    await seedState({ collections: [coll({
      items: [],
      removedItems: { 'image:old.png': '2026-05-01T00:00:00.000Z', 'image:new.png': '2026-05-09T00:00:00.000Z' },
    })] });
    expect(await svc.pruneCollectionItemRemovals(Date.parse('2026-05-05T00:00:00.000Z'))).toEqual({ pruned: 1 });
    const pruned = await svc.getCollection('c1');
    expect(pruned.removedItems).toEqual({ 'image:new.png': '2026-05-09T00:00:00.000Z' });
    expect(pruned.updatedAt).toBe(T0);
  });
});

describe('createCollection — event emission', () => {
  it('emits a mediaCollection updated event with the created record id', async () => {
    const { recordEvents } = await import('./sharing/recordEvents.js');
    const updatedEvts = [];
    const handler = (evt) => updatedEvts.push(evt);
    recordEvents.on('updated', handler);
    try {
      const c = await svc.createCollection({ name: 'New' });
      expect(updatedEvts).toContainEqual(
        expect.objectContaining({ recordKind: 'mediaCollection', recordId: c.id }),
      );
    } finally {
      recordEvents.off('updated', handler);
    }
  });
});

describe('findOrCreate* — announces new collections to the sync pipeline', () => {
  // A newly-created universe/series-linked (or named) collection must emit a
  // mediaCollection 'updated' event so a peer with mediaCollections syncing
  // enabled (but universe/series sync off) still receives it via per-record sync.
  // It must NOT re-announce on a find-existing hit (would churn every render).
  const collectMediaUpdateIds = async (fn) => {
    const { recordEvents } = await import('./sharing/recordEvents.js');
    const ids = [];
    const handler = (evt) => { if (evt.recordKind === 'mediaCollection') ids.push(evt.recordId); };
    recordEvents.on('updated', handler);
    try { await fn(); } finally { recordEvents.off('updated', handler); }
    return ids;
  };

  it('findOrCreateUniverseCollection announces on create, stays quiet on find-existing', async () => {
    const created = await collectMediaUpdateIds(() =>
      svc.findOrCreateUniverseCollection({ universeId: 'u1', universeName: 'Iron Veil' }));
    const c = await svc.findCollectionByUniverseId('u1');
    expect(created).toEqual([c.id]);
    const again = await collectMediaUpdateIds(() =>
      svc.findOrCreateUniverseCollection({ universeId: 'u1', universeName: 'Iron Veil' }));
    expect(again).toEqual([]);
  });

  it('findOrCreateSeriesCollection announces on create, stays quiet on find-existing', async () => {
    const created = await collectMediaUpdateIds(() =>
      svc.findOrCreateSeriesCollection({ seriesId: 's1', seriesName: 'Salt Run' }));
    expect(created).toHaveLength(1);
    const again = await collectMediaUpdateIds(() =>
      svc.findOrCreateSeriesCollection({ seriesId: 's1', seriesName: 'Salt Run' }));
    expect(again).toEqual([]);
  });

  it('findOrCreateCollectionByName announces on create, stays quiet on find-existing', async () => {
    const created = await collectMediaUpdateIds(() =>
      svc.findOrCreateCollectionByName({ name: 'Loose Bucket' }));
    expect(created).toHaveLength(1);
    const again = await collectMediaUpdateIds(() =>
      svc.findOrCreateCollectionByName({ name: 'Loose Bucket' }));
    expect(again).toEqual([]);
  });
});

describe('mutators — mediaCollection updated emission (standalone per-record sync)', () => {
  // A standalone collection (no universe/series link) reaches a directly-
  // subscribed peer ONLY through the per-record mediaCollection push pipeline,
  // so every content mutator must emit a mediaCollection 'updated' event or the
  // edit silently never propagates.
  const collectMediaUpdates = async (fn) => {
    const { recordEvents } = await import('./sharing/recordEvents.js');
    const ids = [];
    const handler = (evt) => { if (evt.recordKind === 'mediaCollection') ids.push(evt.recordId); };
    recordEvents.on('updated', handler);
    try {
      await fn();
    } finally {
      recordEvents.off('updated', handler);
    }
    return ids;
  };

  it('updateCollection emits a mediaCollection updated event', async () => {
    const c = await svc.createCollection({ name: 'Standalone' });
    const ids = await collectMediaUpdates(() => svc.updateCollection(c.id, { description: 'changed' }));
    expect(ids).toContain(c.id);
  });

  it('addItem emits a mediaCollection updated event', async () => {
    const c = await svc.createCollection({ name: 'Standalone' });
    const ids = await collectMediaUpdates(() => svc.addItem(c.id, { kind: 'image', ref: 'x.png' }));
    expect(ids).toContain(c.id);
  });

  it('removeItem emits a mediaCollection updated event', async () => {
    const c = await svc.createCollection({ name: 'Standalone' });
    await svc.addItem(c.id, { kind: 'image', ref: 'x.png' });
    const ids = await collectMediaUpdates(() => svc.removeItem(c.id, 'image:x.png'));
    expect(ids).toContain(c.id);
  });

  it('bulkUpdateCollectionItems emits a mediaCollection updated event when items change', async () => {
    const c = await svc.createCollection({ name: 'Standalone' });
    const ids = await collectMediaUpdates(() =>
      svc.bulkUpdateCollectionItems(c.id, { add: [{ kind: 'image', ref: 'y.png' }] }),
    );
    expect(ids).toContain(c.id);
  });
});

describe('pruneTombstonedCollections', () => {
  it('prunes tombstoned collections older than the cutoff and returns the count', async () => {
    // Create a live collection and soft-delete it with an old timestamp by
    // injecting the tombstone directly into the file store.
    const c = await svc.createCollection({ name: 'ToDelete' });
    const oldTs = new Date(Date.now() - 48 * 60 * 60 * 1000).toISOString();
    // Re-seed the record as a tombstone carrying an old deletedAt.
    const stored = await readStored(c.id);
    await seedState({ collections: [{ ...stored, deleted: true, deletedAt: oldTs, updatedAt: oldTs, items: [] }] });

    // Seed a base hash so we can confirm the prune evicts it.
    await cj.setSyncBaseHash('mediaCollection', c.id, cj.contentHashForRecord('mediaCollection', stored));
    expect(await cj.getSyncBaseHash('mediaCollection', c.id)).not.toBeNull();

    const result = await svc.pruneTombstonedCollections(Date.now());
    expect(result).toEqual({ pruned: 1 });
    expect(await svc.listCollections({ includeDeleted: true })).toHaveLength(0);
    // The conflict-journal base hash is evicted so the side store doesn't leak.
    expect(await cj.getSyncBaseHash('mediaCollection', c.id)).toBeNull();
  });

  it('prunes a multi-candidate batch (bounded fan-out) — only the old tombstones, exact count', async () => {
    // The parallelized GC sweep: more candidates than the concurrency bound,
    // interleaved with a live record and a too-recent tombstone that must survive.
    const oldTs = new Date(Date.now() - 48 * 60 * 60 * 1000).toISOString();
    const futureTs = new Date(Date.now() + 60 * 1000).toISOString();
    const collections = [];
    for (let i = 0; i < 10; i++) {
      collections.push({
        id: `c-old-${i}`, name: `Old ${i}`, description: '', coverKey: null,
        universeId: null, seriesId: null, items: [],
        createdAt: oldTs, updatedAt: oldTs, deleted: true, deletedAt: oldTs,
      });
    }
    collections.push({
      id: 'c-live', name: 'Live', description: '', coverKey: null,
      universeId: null, seriesId: null, items: [],
      createdAt: oldTs, updatedAt: oldTs, deleted: false, deletedAt: null,
    });
    collections.push({
      id: 'c-recent', name: 'RecentDelete', description: '', coverKey: null,
      universeId: null, seriesId: null, items: [],
      createdAt: oldTs, updatedAt: futureTs, deleted: true, deletedAt: futureTs,
    });
    await seedState({ collections });
    for (let i = 0; i < 10; i++) {
      await cj.setSyncBaseHash('mediaCollection', `c-old-${i}`, `hash-old-${i}`);
    }
    await cj.flushBaseHashes();
    writeCounter.baseHash = 0;

    const result = await svc.pruneTombstonedCollections(Date.now());
    expect(result).toEqual({ pruned: 10 }); // 10 old tombstones; live + recent survive
    expect(writeCounter.baseHash).toBe(1);
    const surviving = (await svc.listCollections({ includeDeleted: true })).map((c) => c.id).sort();
    expect(surviving).toEqual(['c-live', 'c-recent']);
    cj.__resetBaseHashCacheForTests();
    for (let i = 0; i < 10; i++) {
      expect(await cj.getSyncBaseHash('mediaCollection', `c-old-${i}`)).toBeNull();
    }
  });

  it('does NOT prune a live collection', async () => {
    await svc.createCollection({ name: 'Live' });
    const result = await svc.pruneTombstonedCollections(Date.now());
    expect(result).toEqual({ pruned: 0 });
    expect(await svc.listCollections()).toHaveLength(1);
  });

  it('does NOT prune a tombstone newer than the cutoff', async () => {
    const c = await svc.createCollection({ name: 'RecentDelete' });
    // Re-seed as a tombstone with a future timestamp (simulating a delete that just happened).
    const futureTs = new Date(Date.now() + 60 * 1000).toISOString();
    const stored = await readStored(c.id);
    await seedState({ collections: [{ ...stored, deleted: true, deletedAt: futureTs, updatedAt: futureTs, items: [] }] });

    // Cut-off is now; the tombstone's deletedAt is in the future → not pruned.
    const result = await svc.pruneTombstonedCollections(Date.now());
    expect(result).toEqual({ pruned: 0 });
    const all = await svc.listCollections({ includeDeleted: true });
    expect(all).toHaveLength(1);
    expect(all[0].deleted).toBe(true);
  });

  it('returns { pruned: 0 } without touching the file when cutoff is not a finite number', async () => {
    await svc.createCollection({ name: 'A' });
    expect(await svc.pruneTombstonedCollections(NaN)).toEqual({ pruned: 0 });
    expect(await svc.pruneTombstonedCollections(Infinity)).toEqual({ pruned: 0 });
  });
});

// Provenance stamp (#3311) — the server records whether a collection was minted
// by a machine flow or by the user, so the grid stops reverse-engineering it
// from name/description/id markers.
describe('source provenance', () => {
  it('createCollection defaults to user and accepts an explicit auto stamp', async () => {
    const byUser = await svc.createCollection({ name: 'Concept Art' });
    expect(byUser.source).toBe('user');
    expect((await readStored(byUser.id)).source).toBe('user');

    const byMachine = await svc.createCollection({ name: 'Writers Room: Example Work', source: 'auto' });
    expect(byMachine.source).toBe('auto');
    expect((await svc.getCollection(byMachine.id)).source).toBe('auto');
  });

  it('createCollection rejects an unknown source rather than persisting it', async () => {
    await expect(svc.createCollection({ name: 'A', source: 'robot' }))
      .rejects.toMatchObject({ code: svc.ERR_VALIDATION });
    expect(await svc.listCollections()).toEqual([]);
  });

  it('stamps auto on the universe- and series-linked render buckets', async () => {
    const uc = await svc.findOrCreateUniverseCollection({ universeId: 'universe-1', universeName: 'Example Universe' });
    const sc = await svc.findOrCreateSeriesCollection({ seriesId: 'series-1', seriesName: 'Example Series' });
    expect(uc.source).toBe('auto');
    expect(sc.source).toBe('auto');
  });

  it('leaves a legacy record UNSTAMPED rather than defaulting it to user', async () => {
    // Absent is a third state: the client falls back to its marker heuristic for
    // these. Defaulting them to 'user' here would mislabel every pre-#3311
    // auto-created bucket as user-made on a peer that never ran migration 220.
    await seedState({
      collections: [{
        id: 'c-legacy', name: 'Universe: Example Universe', description: '', coverKey: null,
        universeId: null, seriesId: null, items: [],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z',
      }],
    });
    const [legacy] = await svc.listCollections();
    expect('source' in legacy).toBe(false);
  });

  it('drops a garbage stamp instead of persisting it', async () => {
    await seedState({
      collections: [{
        id: 'c-bogus', name: 'Bogus', description: '', coverKey: null, source: 'robot',
        universeId: null, seriesId: null, items: [],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z',
      }],
    });
    expect('source' in (await svc.getCollection('c-bogus'))).toBe(false);
  });

  it('is correctable via updateCollection WITHOUT advancing the LWW clock', async () => {
    // The migration classifies from markers a user could in principle have
    // typed (an `Auto-…` description), so a wrong stamp must be fixable. And
    // because the field never reaches a peer, fixing it must not bump
    // `updatedAt` — that would out-race a peer's real edit for a change no peer
    // can even see.
    const seeded = '2026-05-22T00:00:00Z';
    await seedState({
      collections: [{
        id: 'c-fix', name: 'Renders', description: '', coverKey: null,
        universeId: null, seriesId: null, source: 'auto', items: [],
        createdAt: seeded, updatedAt: seeded,
      }],
    });
    const fixed = await svc.updateCollection('c-fix', { source: 'user' });
    expect(fixed.source).toBe('user');
    expect(fixed.updatedAt).toBe(seeded);
    // A patch that DOES touch wire-visible state still bumps it.
    const renamed = await svc.updateCollection('c-fix', { name: 'Renders 2', source: 'auto' });
    expect(renamed.source).toBe('auto');
    expect(renamed.updatedAt).not.toBe(seeded);
  });

  it('survives an edit and rides through the tombstone', async () => {
    const c = await svc.createCollection({ name: 'Writers Room: Example Work', source: 'auto' });
    expect((await svc.updateCollection(c.id, { description: 'edited' })).source).toBe('auto');
    await svc.deleteCollection(c.id);
    expect((await svc.getCollection(c.id, { includeDeleted: true })).source).toBe('auto');
  });

  it('merge keeps the local stamp when a peer sends the record without one', async () => {
    // The cross-install case: `source` never crosses the wire (sanitizeRecordForWire
    // strips it), so every remote record arrives unstamped. Its (newer) scalars
    // win LWW, but they must not erase local provenance.
    const c = await svc.createCollection({ name: 'Writers Room: Example Work', source: 'auto' });
    const result = await svc.mergeMediaCollectionsFromSync([{
      id: c.id, name: 'Writers Room: Renamed', description: '', coverKey: null,
      universeId: null, seriesId: null, items: [],
      createdAt: c.createdAt, updatedAt: '2099-01-01T00:00:00Z',
    }]);
    expect(result.applied).toBe(true);
    const merged = await svc.getCollection(c.id);
    expect(merged.name).toBe('Writers Room: Renamed');
    expect(merged.source).toBe('auto');
  });

  it('merge inserts a stamp that an offline export/import bundle legitimately carries', async () => {
    // Peer sync always strips `source`, but the merge also backs the import
    // path — a record that does arrive stamped is inserted verbatim.
    await svc.mergeMediaCollectionsFromSync([{
      id: 'c-remote', name: 'Concept Art', description: '', coverKey: null,
      universeId: null, seriesId: null, items: [], source: 'user',
      createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z',
    }]);
    expect((await svc.getCollection('c-remote')).source).toBe('user');
  });

  it('removeItemFromAllCollections drops the item everywhere, bumps updatedAt, and spares other items', async () => {
    const a = await svc.createCollection({ name: 'A' });
    const b = await svc.createCollection({ name: 'B' });
    const c = await svc.createCollection({ name: 'C' });
    await svc.bulkUpdateCollectionItems(a.id, { add: [{ kind: 'image', ref: 'gone.png' }, { kind: 'image', ref: 'keep.png' }] });
    await svc.bulkUpdateCollectionItems(b.id, { add: [{ kind: 'image', ref: 'gone.png' }, { kind: 'video', ref: 'gone.png' }] });
    await svc.bulkUpdateCollectionItems(c.id, { add: [{ kind: 'image', ref: 'keep.png' }] });
    const cBefore = await readStored(c.id);
    await svc.updateCollection(a.id, { coverKey: 'image:gone.png' });

    expect(await svc.removeItemFromAllCollections('image', 'gone.png')).toBe(2);

    const aAfter = await readStored(a.id);
    expect(aAfter.items.map((i) => i.ref)).toEqual(['keep.png']);
    expect(aAfter.coverKey).toBeNull();
    expect((await readStored(b.id)).items).toEqual([expect.objectContaining({ kind: 'video', ref: 'gone.png' })]);
    expect(await readStored(c.id)).toEqual(cBefore);
    expect(await svc.removeItemFromAllCollections('image', 'gone.png')).toBe(0);
  });
});