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

63.5 KB
Raw Blame
/**
 * Tests for the `pipeline` and `universe` sync categories added in PR
 * [extend-syncorchestrator-to-cover-pipeline-universe].
 *
 * Covers: snapshot shape, checksum stability across no-op reads, array-by-id
 * LWW merge for series/issues/universes, no-blob coverage (the sync is
 * record-level only — images and videos flow through the sharing system).
 */

import { describe, it, expect, beforeEach, afterAll, vi } from 'vitest';
import { writeFileSync, mkdirSync, readFileSync, rmSync, readdirSync, existsSync, statSync } from 'fs';
import { join } from 'path';
import { mockPathsDataRoot } from '../lib/mockPathsDataRoot.js';

const { tempRoot, makeProxy, cleanup } = mockPathsDataRoot({ prefix: 'portos-datasync-piuni-' });

vi.mock('../lib/fileUtils.js', async () => {
  const actual = await vi.importActual('../lib/fileUtils.js');
  return makeProxy(actual);
});

afterAll(cleanup);

const dataSync = await import('./dataSync.js');
// Derive the receiver's pipelineSeries version from the source of truth so this
// test doesn't false-fail every time the constant is bumped (it drifted red on
// the 10→11 bump). "Sender ahead" is always receiver + 1. Dynamic-imported after
// the vi.mock hoist so the static import doesn't disturb mock initialization.
const schemaVersionsMod = await import('../lib/schemaVersions.js');
const RECEIVER_PIPELINE_SERIES_V = schemaVersionsMod.PORTOS_SCHEMA_VERSIONS.pipelineSeries;
const SENDER_AHEAD_PIPELINE_SERIES_V = RECEIVER_PIPELINE_SERIES_V + 1;
const conflictJournal = await import('../lib/conflictJournal.js');
const { PORTOS_SCHEMA_VERSIONS } = await import('../lib/schemaVersions.js');

const SERIES_DIR = join(tempRoot, 'pipeline-series');
const ISSUES_DIR = join(tempRoot, 'pipeline-issues');
const UNIVERSES_DIR = join(tempRoot, 'universes');
const MEDIA_COLLECTIONS_DIR = join(tempRoot, 'media-collections');
const PEER_SUBS_PATH = join(tempRoot, 'sharing', 'peer_subscriptions.json');
const VIDEO_HISTORY_PATH = join(tempRoot, 'video-history.json');

// Write the outbound peer-subscription store that drives the per-peer
// snapshot exclude-set. Each row is `{ peerId, recordKind, recordId }`.
function writePeerSubs(rows) {
  mkdirSync(join(tempRoot, 'sharing'), { recursive: true });
  writeFileSync(PEER_SUBS_PATH, JSON.stringify({
    subscriptions: rows.map((r) => ({
      id: `peer-${r.recordKind}-${r.recordId}-${r.peerId}`,
      peerId: r.peerId,
      recordKind: r.recordKind,
      recordId: r.recordId,
      createdAt: '2026-05-25T00:00:00Z',
      updatedAt: '2026-05-25T00:00:00Z',
    })),
  }, null, 2));
}

function writeJSON(path, obj) {
  mkdirSync(tempRoot, { recursive: true });
  writeFileSync(path, JSON.stringify(obj, null, 2));
}

function readJSON(path) {
  return JSON.parse(readFileSync(path, 'utf-8'));
}

function writeCollectionState(dir, type, records) {
  mkdirSync(dir, { recursive: true });
  writeJSON(join(dir, 'index.json'), {
    schemaVersion: 1,
    type,
    updatedAt: '2026-05-17T09:00:00Z',
    config: {},
  });
  for (const record of records) {
    mkdirSync(join(dir, record.id), { recursive: true });
    writeJSON(join(dir, record.id, 'index.json'), record);
  }
}

function readCollectionState(dir) {
  if (!existsSync(dir)) return [];
  return readdirSync(dir, { withFileTypes: true })
    .filter((entry) => entry.isDirectory())
    .map((entry) => readJSON(join(dir, entry.name, 'index.json')));
}

// media-collections moved to the per-record collectionStore layout (migration
// 059); these adapters keep the `{ collections: [...] }`-shaped call sites below
// working against the split dir.
function writeMediaCollections({ collections = [] } = {}) {
  writeCollectionState(MEDIA_COLLECTIONS_DIR, 'mediaCollections', collections);
}
function readMediaCollections() {
  return { collections: readCollectionState(MEDIA_COLLECTIONS_DIR) };
}

const writeSeriesState = (series) => writeCollectionState(SERIES_DIR, 'pipelineSeries', series);
const writeIssueState = (issues) => writeCollectionState(ISSUES_DIR, 'pipelineIssues', issues);
const readSeriesState = () => readCollectionState(SERIES_DIR);
const readIssueState = () => readCollectionState(ISSUES_DIR);

// Write the universes split layout (migration 034's output): one
// `universes/<id>/index.json` per record + a type-level `universes/index.json`
// whose `config.runs` carries the cross-record runs[] log.
function writeUniverseState({ universes = [], runs = [] } = {}) {
  mkdirSync(UNIVERSES_DIR, { recursive: true });
  for (const u of universes) {
    const dir = join(UNIVERSES_DIR, u.id);
    mkdirSync(dir, { recursive: true });
    writeFileSync(join(dir, 'index.json'), JSON.stringify(u, null, 2));
  }
  writeFileSync(join(UNIVERSES_DIR, 'index.json'), JSON.stringify({
    schemaVersion: 5, type: 'universes', updatedAt: new Date().toISOString(),
    config: { runs },
  }, null, 2));
}

// Read it back as the legacy `{ universes, runs }` shape so existing
// assertions don't need rewiring.
function readUniverseState() {
  if (!existsSync(UNIVERSES_DIR)) return { universes: [], runs: [] };
  const entries = readdirSync(UNIVERSES_DIR);
  const universes = [];
  for (const name of entries) {
    if (name === 'index.json' || name.startsWith('.')) continue;
    const p = join(UNIVERSES_DIR, name, 'index.json');
    if (existsSync(p)) universes.push(JSON.parse(readFileSync(p, 'utf-8')));
  }
  const typeIdx = existsSync(join(UNIVERSES_DIR, 'index.json'))
    ? JSON.parse(readFileSync(join(UNIVERSES_DIR, 'index.json'), 'utf-8'))
    : null;
  const runs = typeIdx?.config?.runs || [];
  return { universes, runs };
}

beforeEach(() => {
  rmSync(tempRoot, { recursive: true, force: true });
  mkdirSync(tempRoot, { recursive: true });
});

describe('dataSync — universe category', () => {
  it('is registered alongside the other categories', () => {
    const cats = dataSync.getSupportedCategories();
    expect(cats).toContain('universe');
    expect(cats).toContain('pipeline');
    expect(cats).toContain('goals'); // sanity
  });

  it('snapshot returns just `universes` (not `runs`)', async () => {
    writeUniverseState({
      universes: [{ id: 'u1', name: 'Salt', updatedAt: '2026-05-17T10:00:00Z' }],
      runs: [{ id: 'r1', logs: ['ephemeral'] }]
    });
    const snap = await dataSync.getSnapshot('universe');
    expect(snap.data.universes).toHaveLength(1);
    expect(snap.data.universes[0].id).toBe('u1');
    expect(snap.data.runs).toBeUndefined();
    expect(snap.checksum).toBeTruthy();
  });

  it('snapshot envelope carries portosMeta { portosVersion, schemaVersions } so receivers can gate', async () => {
    const snap = await dataSync.getSnapshot('universe');
    expect(snap.portosMeta).toBeDefined();
    expect(typeof snap.portosMeta.portosVersion).toBe('string');
    expect(snap.portosMeta.schemaVersions.universes).toBe(14);
  });

  it('applyRemote rejects when sender schemaVersions are AHEAD of local code', async () => {
    writeUniverseState({ universes: [], runs: [] });
    const result = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-new', name: 'Foundry', updatedAt: '2026-05-17T10:00:00Z' }],
    }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 15 } } });
    expect(result.applied).toBe(false);
    expect(result.count).toBe(0);
    expect(result.blockedBySchema).toBeDefined();
    expect(result.blockedBySchema.ahead).toEqual([
      { category: 'universes', senderV: 15, receiverV: 14 },
    ]);
    expect(result.blockedBySchema.senderPortosVersion).toBe('99.0.0');
    // Nothing was written.
    expect(readUniverseState().universes).toEqual([]);
  });

  it('applyRemote falls through when sender is BEHIND (sanitizer backfills)', async () => {
    writeUniverseState({ universes: [], runs: [] });
    const result = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-old', name: 'Legacy', createdAt: '2026-05-17T09:00:00Z', updatedAt: '2026-05-17T10:00:00Z' }],
    }, { portosMeta: { portosVersion: '2.6.0', schemaVersions: { universes: 4 } } });
    expect(result.applied).toBe(true);
    expect(result.count).toBe(1);
  });

  it('applyRemote threads senderSchemaVersions so a behind sender cannot LWW-strip moodBoardId (#4188)', async () => {
    writeUniverseState({
      universes: [{ id: 'u-mb', name: 'Linked', moodBoardId: 'mb-local', createdAt: '2026-05-17T09:00:00Z', updatedAt: '2026-05-17T10:00:00Z' }],
      runs: [],
    });
    // A v8 (pre-moodBoardId) sender edits another field with a newer timestamp.
    const behind = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-mb', name: 'Renamed By Old Peer', createdAt: '2026-05-17T09:00:00Z', updatedAt: '2026-05-17T11:00:00Z' }],
    }, { portosMeta: { portosVersion: '2.6.0', schemaVersions: { universes: 8 } } });
    expect(behind.applied).toBe(true);
    let persisted = readUniverseState();
    expect(persisted.universes[0].name).toBe('Renamed By Old Peer');
    expect(persisted.universes[0].moodBoardId).toBe('mb-local');
    // A v9-aware sender omitting the field IS an explicit clear.
    const clear = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-mb', name: 'Cleared By New Peer', createdAt: '2026-05-17T09:00:00Z', updatedAt: '2026-05-17T12:00:00Z' }],
    }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 9 } } });
    expect(clear.applied).toBe(true);
    persisted = readUniverseState();
    expect('moodBoardId' in persisted.universes[0]).toBe(false);
  });

  it('preserves durable sheet intent through old-peer sync and accepts current-peer supersession', async () => {
    const first = '11111111-1111-4111-8111-111111111111';
    const next = '22222222-2222-4222-8222-222222222222';
    const base = { id: 'u-sheet', name: 'Example', createdAt: '2026-05-17T09:00:00Z' };
    writeUniverseState({ universes: [{ ...base, updatedAt: '2026-05-17T10:00:00Z',
      characters: [{ id: 'character-1', name: 'Example', referenceSheetRequests: { standard: first } }],
    }], runs: [] });
    const behind = await dataSync.applyRemote('universe', { universes: [{ ...base,
      updatedAt: '2026-05-17T11:00:00Z', characters: [{ id: 'character-1', name: 'Peer edit' }],
    }] }, { portosMeta: { schemaVersions: { universes: 12 } } });
    expect(behind.applied).toBe(true);
    expect(readUniverseState().universes[0].characters[0].referenceSheetRequests).toEqual({ standard: first });
    const current = await dataSync.applyRemote('universe', { universes: [{ ...base,
      updatedAt: '2026-05-17T12:00:00Z', characters: [{ id: 'character-1', name: 'Peer edit', referenceSheetRequests: { standard: next } }],
    }] }, { portosMeta: { schemaVersions: { universes: 13 } } });
    expect(current.applied).toBe(true);
    expect(readUniverseState().universes[0].characters[0].referenceSheetRequests).toEqual({ standard: next });
  });

  // Catches an older peer's unrelated canon edit stripping alternate ages/looks.
  it('keeps character and place forms when a pre-forms peer wins LWW', async () => {
    const base = { id: 'u-forms', name: 'Example', createdAt: '2026-05-17T09:00:00Z' };
    const kid = { id: 'form-kid', label: 'Age 7', age: '7', description: 'yellow raincoat' };
    writeUniverseState({ universes: [{ ...base, updatedAt: '2026-05-17T10:00:00Z',
      characters: [{ id: 'character-1', name: 'Example', forms: [kid] }],
      places: [{ id: 'place-1', name: 'Harbor', forms: [{ ...kid, id: 'form-ruin', label: 'Ruined' }] }],
    }], runs: [] });
    const behind = await dataSync.applyRemote('universe', { universes: [{ ...base, updatedAt: '2026-05-17T11:00:00Z',
      characters: [{ id: 'character-1', name: 'Peer edit' }], places: [{ id: 'place-1', name: 'Harbor' }],
    }] }, { portosMeta: { schemaVersions: { universes: 13 } } });
    expect(behind.applied).toBe(true);
    const [universe] = readUniverseState().universes;
    expect(universe.characters[0].forms).toEqual([kid]);
    expect(universe.places[0].forms[0].label).toBe('Ruined');
  });

  it('applyRemote falls through for legacy senders that send NO portosMeta at all', async () => {
    writeUniverseState({ universes: [], runs: [] });
    const result = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-legacy', name: 'Pre-Versioning', createdAt: '2026-05-17T09:00:00Z', updatedAt: '2026-05-17T10:00:00Z' }],
    });
    expect(result.applied).toBe(true);
  });

  it('snapshot checksum is stable across reads when state is unchanged', async () => {
    writeUniverseState({ universes: [{ id: 'u1', updatedAt: '2026-05-17T10:00:00Z' }] });
    const a = await dataSync.getSnapshot('universe');
    const b = await dataSync.getSnapshot('universe');
    expect(a.checksum).toBe(b.checksum);
  });

  it('snapshot handles a missing file gracefully', async () => {
    const snap = await dataSync.getSnapshot('universe');
    expect(snap.data.universes).toEqual([]);
    expect(snap.checksum).toBeTruthy();
  });

  it('applyRemote inserts a new universe', async () => {
    writeUniverseState({ universes: [], runs: [] });
    const result = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-new', name: 'Foundry', updatedAt: '2026-05-17T10:00:00Z' }]
    });
    expect(result.applied).toBe(true);
    expect(result.count).toBe(1);
    const persisted = readUniverseState();
    expect(persisted.universes).toHaveLength(1);
    expect(persisted.universes[0].id).toBe('u-new');
    // Local-only `runs` must survive the merge.
    expect(persisted.runs).toEqual([]);
  });

  it('applyRemote LWW: newer remote wins, older remote is dropped', async () => {
    writeUniverseState({
      universes: [{ id: 'u1', name: 'Old', updatedAt: '2026-05-17T10:00:00Z' }]
    });
    const result = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u1', name: 'New', updatedAt: '2026-05-17T11:00:00Z' }]
    });
    expect(result.applied).toBe(true);
    expect(readUniverseState().universes[0].name).toBe('New');

    // Replay older — should NOT clobber.
    const replay = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u1', name: 'Old', updatedAt: '2026-05-17T10:00:00Z' }]
    });
    expect(replay.applied).toBe(false);
    expect(readUniverseState().universes[0].name).toBe('New');
  });

  it('applyRemote preserves local-only `runs[]` when only universes change', async () => {
    // Runs need a valid shape — `sanitizeRun` requires id + universeId since
    // the merge now routes through the service-level entry point that
    // sanitizes every read.
    const localRun = {
      id: 'r1', universeId: 'u-local', collectionId: null,
      jobIds: [], promptCount: 0, createdAt: '2026-05-17T09:00:00Z',
    };
    writeUniverseState({ universes: [], runs: [localRun] });
    await dataSync.applyRemote('universe', {
      universes: [{ id: 'u1', name: 'A', createdAt: '2026-05-17T09:00:00Z', updatedAt: '2026-05-17T10:00:00Z' }]
    });
    const persisted = readUniverseState();
    expect(persisted.runs).toHaveLength(1);
    expect(persisted.runs[0].id).toBe('r1');
    expect(persisted.runs[0].universeId).toBe('u-local');
  });
});

describe('dataSync — conflict-journal source attribution (snapshot path)', () => {
  // The snapshot apply path (syncOrchestrator → dataSync.applyRemote → the
  // service merge fns) must stamp journaled conflicts with `via: 'snapshot'`
  // and the source peer's id. Before [conflict-source-attribution] the param
  // was dropped, so the Conflicts tab showed `via: sync (peerId: null)` and
  // couldn't say which peer collided.
  const journalDir = () => join(tempRoot, 'conflict-journal');
  const readJournalEntries = () => {
    if (!existsSync(journalDir())) return [];
    return readdirSync(journalDir(), { withFileTypes: true })
      .filter((e) => e.isDirectory())
      .map((e) => readJSON(join(journalDir(), e.name, 'index.json')));
  };
  // Seed local + a divergent base so the incoming remote is a true 3-way
  // conflict (local ≠ base, remote ≠ base, remote ≠ local) and the merge
  // journals before overwriting. Remote `updatedAt` is newer so it wins LWW.
  async function seedConflict(id) {
    writeUniverseState({
      universes: [{ id, name: 'Local Edit', updatedAt: '2026-05-17T10:00:00Z' }],
    });
    await conflictJournal.setSyncBaseHash('universe', id, `base-hash-${id}-distinct`);
    await conflictJournal.flushBaseHashes();
  }

  beforeEach(() => {
    // The base-hash cache is module-level; reset it so the wiped temp root
    // doesn't bleed seeds across tests.
    conflictJournal.__resetBaseHashCacheForTests();
  });

  it('records via:snapshot + the source peerId when the orchestrator passes one', async () => {
    await seedConflict('u-attr');
    const result = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-attr', name: 'Remote Edit', updatedAt: '2026-05-18T10:00:00Z' }],
    }, { peerId: 'peer-zeta' });
    expect(result.applied).toBe(true);

    const entries = readJournalEntries();
    expect(entries).toHaveLength(1);
    expect(entries[0].recordKind).toBe('universe');
    expect(entries[0].recordId).toBe('u-attr');
    expect(entries[0].source).toEqual({ via: 'snapshot', peerId: 'peer-zeta' });
  });

  it('defaults peerId to null (not undefined) when the caller omits it — manual REST apply', async () => {
    await seedConflict('u-anon');
    await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-anon', name: 'Remote Edit', updatedAt: '2026-05-18T10:00:00Z' }],
    });
    const entries = readJournalEntries();
    expect(entries).toHaveLength(1);
    expect(entries[0].source).toEqual({ via: 'snapshot', peerId: null });
  });
});

describe('dataSync — pipeline category', () => {
  it('snapshot bundles series + issues from their respective files', async () => {
    writeSeriesState([{ id: 'ser-1', name: 'A', updatedAt: '2026-05-17T10:00:00Z' }]);
    writeIssueState([{ id: 'iss-1', seriesId: 'ser-1', title: 'One', updatedAt: '2026-05-17T10:00:00Z' }]);
    const snap = await dataSync.getSnapshot('pipeline');
    expect(snap.data.series).toHaveLength(1);
    expect(snap.data.issues).toHaveLength(1);
    expect(snap.data.issues[0].seriesId).toBe('ser-1');
  });

  it('snapshot tolerates missing files', async () => {
    const snap = await dataSync.getSnapshot('pipeline');
    expect(snap.data.series).toEqual([]);
    expect(snap.data.issues).toEqual([]);
  });

  it('applyRemote merges series + issues; count reports records actually changed', async () => {
    writeSeriesState([{ id: 'ser-1', name: 'Old', updatedAt: '2026-05-17T10:00:00Z' }]);
    writeIssueState([]);

    const result = await dataSync.applyRemote('pipeline', {
      series: [
        { id: 'ser-1', name: 'New', updatedAt: '2026-05-17T11:00:00Z' },
        { id: 'ser-2', name: 'Foundry', updatedAt: '2026-05-17T10:00:00Z' }
      ],
      issues: [
        { id: 'iss-1', seriesId: 'ser-2', title: 'Pilot', updatedAt: '2026-05-17T10:00:00Z' }
      ]
    });
    expect(result.applied).toBe(true);
    // `count` is records actually changed/added this cycle, NOT total post-
    // merge records (which would over-report when callers sum across cycles
    // or categories). Two series updated/added + one issue added = 3.
    expect(result.count).toBe(3);
    // Per-side breakdown surfaced for telemetry that wants to distinguish them.
    expect(result.seriesChanged).toBe(2);
    expect(result.issuesChanged).toBe(1);

    const persistedSeries = readSeriesState();
    expect(persistedSeries).toHaveLength(2);
    expect(persistedSeries.find(s => s.id === 'ser-1').name).toBe('New'); // LWW
    expect(persistedSeries.find(s => s.id === 'ser-2').name).toBe('Foundry');

    const persistedIssues = readIssueState();
    expect(persistedIssues).toHaveLength(1);
    expect(persistedIssues[0].seriesId).toBe('ser-2');
  });

  it('applyRemote count reports only the changed side when only series differs', async () => {
    writeSeriesState([{ id: 'ser-1', name: 'Old', updatedAt: '2026-05-17T10:00:00Z' }]);
    // Local issues exist but won't change — sync must not inflate count to
    // include them (the pre-fix bug counted total post-merge issues).
    writeIssueState([{ id: 'iss-1', seriesId: 'ser-1', title: 'Local', updatedAt: '2026-05-17T10:00:00Z' }]);

    const result = await dataSync.applyRemote('pipeline', {
      series: [{ id: 'ser-1', name: 'New', updatedAt: '2026-05-17T11:00:00Z' }],
      issues: [{ id: 'iss-1', seriesId: 'ser-1', title: 'Stale', updatedAt: '2026-05-17T09:00:00Z' }], // older, skipped
    });
    expect(result.applied).toBe(true);
    expect(result.count).toBe(1); // one series change; issues side unchanged
    expect(result.seriesChanged).toBe(1);
    expect(result.issuesChanged).toBe(0);
  });

  it('applyRemote is a no-op when nothing is newer', async () => {
    writeSeriesState([{ id: 'ser-1', name: 'Old', updatedAt: '2026-05-17T10:00:00Z' }]);
    writeIssueState([{ id: 'iss-1', seriesId: 'ser-1', title: 'Local', updatedAt: '2026-05-17T10:00:00Z' }]);

    const before = readSeriesState();
    const result = await dataSync.applyRemote('pipeline', {
      series: [{ id: 'ser-1', updatedAt: '2026-05-17T10:00:00Z' }], // same ts
      issues: [{ id: 'iss-1', updatedAt: '2026-05-17T09:00:00Z' }]  // older
    });
    expect(result.applied).toBe(false);
    expect(result.count).toBe(0);
    expect(readSeriesState()).toEqual(before);
  });

  it('applyRemote skips writes for unchanged sides (writes only what differs)', async () => {
    writeSeriesState([{ id: 'ser-1', name: 'Old', updatedAt: '2026-05-17T10:00:00Z' }]);
    writeIssueState([]);

    // Only issues change. Use a valid issue payload (id + seriesId + title)
    // since the merge now routes through sanitizeIssue.
    await dataSync.applyRemote('pipeline', {
      series: [{ id: 'ser-1', updatedAt: '2026-05-17T09:00:00Z' }], // older → skipped
      issues: [{ id: 'iss-new', seriesId: 'ser-1', title: 'New Issue', updatedAt: '2026-05-17T11:00:00Z' }]
    });

    // Series file untouched (no incidental rewrite that could clobber a
    // concurrent write outside the sync orchestrator).
    expect(readSeriesState()[0].updatedAt).toBe('2026-05-17T10:00:00Z');
    expect(readIssueState()).toHaveLength(1);
  });
});

describe('dataSync — getChecksum cache', () => {
  it('returns the same checksum across consecutive calls and matches getSnapshot', async () => {
    writeUniverseState({
      universes: [{ id: 'u1', name: 'A', createdAt: '2026-05-17T09:00:00Z', updatedAt: '2026-05-17T10:00:00Z' }],
    });
    const c1 = await dataSync.getChecksum('universe');
    const c2 = await dataSync.getChecksum('universe');
    const snap = await dataSync.getSnapshot('universe');
    expect(c1.checksum).toBe(c2.checksum);
    expect(c1.checksum).toBe(snap.checksum);
  });

  it('invalidates the cache after applyRemote bumps the underlying file mtime', async () => {
    writeUniverseState({
      universes: [{ id: 'u1', name: 'A', createdAt: '2026-05-17T09:00:00Z', updatedAt: '2026-05-17T10:00:00Z' }],
    });
    const before = await dataSync.getChecksum('universe');
    await dataSync.applyRemote('universe', {
      universes: [{ id: 'u1', name: 'B', updatedAt: '2026-05-17T11:00:00Z' }],
    });
    const after = await dataSync.getChecksum('universe');
    expect(after.checksum).not.toBe(before.checksum);
    expect(after.checksum).toBe((await dataSync.getSnapshot('universe')).checksum);
  });

  it('reflects an out-of-band file mutation (pipeline series changes outside this service)', async () => {
    writeSeriesState([{ id: 'ser-1', name: 'Old', updatedAt: '2026-05-17T10:00:00Z' }]);
    writeIssueState([]);
    const before = await dataSync.getChecksum('pipeline');
    // Force a different mtime — vitest can run faster than the FS's ms tick,
    // so wait long enough that the mtime is guaranteed to advance.
    await new Promise((r) => setTimeout(r, 5));
    writeSeriesState([{ id: 'ser-1', name: 'New', updatedAt: '2026-05-17T11:00:00Z' }]);
    const after = await dataSync.getChecksum('pipeline');
    expect(after.checksum).not.toBe(before.checksum);
  });
});

describe('dataSync — mediaCollections category', () => {
  it('is registered alongside the other categories', () => {
    expect(dataSync.getSupportedCategories()).toContain('mediaCollections');
  });

  it('snapshot returns sanitized collections array', async () => {
    writeMediaCollections({
      collections: [{
        id: 'c1',
        name: 'Universe: Echoes',
        description: '',
        coverKey: null,
        universeId: 'u1',
        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 snap = await dataSync.getSnapshot('mediaCollections');
    expect(snap.data.collections).toHaveLength(1);
    expect(snap.data.collections[0].id).toBe('c1');
    expect(snap.checksum).toBeTruthy();
  });

  it('snapshot checksum is stable across reads when state is unchanged', async () => {
    writeMediaCollections({
      collections: [{
        id: 'c1', name: 'A', description: '', coverKey: null, universeId: null, seriesId: null,
        items: [], createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z',
      }],
    });
    const a = await dataSync.getSnapshot('mediaCollections');
    const b = await dataSync.getSnapshot('mediaCollections');
    expect(a.checksum).toBe(b.checksum);
  });

  it('snapshot handles a missing file gracefully', async () => {
    const snap = await dataSync.getSnapshot('mediaCollections');
    expect(snap.data.collections).toEqual([]);
    expect(snap.checksum).toBeTruthy();
  });

  it('applyRemote inserts a new collection', async () => {
    writeMediaCollections({ collections: [] });
    const result = await dataSync.applyRemote('mediaCollections', {
      collections: [{
        id: 'c-new', name: 'Universe: New', description: '', coverKey: null,
        universeId: 'u-new', seriesId: null,
        items: [{ kind: 'image', ref: 'new.png', addedAt: '2026-05-22T01:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T01:00:00Z',
      }],
    });
    expect(result.applied).toBe(true);
    expect(result.count).toBe(1);
    const persisted = readMediaCollections();
    expect(persisted.collections).toHaveLength(1);
    expect(persisted.collections[0].id).toBe('c-new');
  });

  it('applyRemote unions items by kind:ref — never loses a render', async () => {
    writeMediaCollections({
      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',
      }],
    });
    await dataSync.applyRemote('mediaCollections', {
      collections: [{
        id: 'c1', name: 'A', description: '', coverKey: null, 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-22T02:00:00Z',
      }],
    });
    const persisted = readMediaCollections();
    const refs = persisted.collections[0].items.map(i => i.ref).sort();
    expect(refs).toEqual(['local.png', 'remote.png']);
  });

  it('checksum changes after applyRemote bumps file mtime', async () => {
    writeMediaCollections({
      collections: [{
        id: 'c1', name: 'A', description: '', coverKey: null, universeId: null, seriesId: null,
        items: [], createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T01:00:00Z',
      }],
    });
    const before = await dataSync.getChecksum('mediaCollections');
    await dataSync.applyRemote('mediaCollections', {
      collections: [{
        id: 'c1', name: 'A', description: '', coverKey: null, universeId: null, seriesId: null,
        items: [{ kind: 'image', ref: 'a.png', addedAt: '2026-05-22T02:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T02:00:00Z',
      }],
    });
    const after = await dataSync.getChecksum('mediaCollections');
    expect(after.checksum).not.toBe(before.checksum);
  });

  it('snapshot checksum is order-insensitive for collections and items', async () => {
    // Regression: two peers can hold identical sets but write them to disk
    // in different orders (insertion-order persistence). Without
    // canonicalization in getMediaCollectionsSnapshot, their checksums
    // diverge permanently and the UI reads "behind" forever even though
    // they're converged.
    writeMediaCollections({
      collections: [
        {
          id: 'c-b', name: 'B', description: '', coverKey: null, universeId: null, seriesId: null,
          items: [
            { kind: 'image', ref: 'z.png', addedAt: '2026-05-22T03:00:00Z' },
            { kind: 'image', ref: 'a.png', addedAt: '2026-05-22T01:00:00Z' },
          ],
          createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T03:00:00Z',
        },
        {
          id: 'c-a', name: 'A', description: '', coverKey: null, universeId: null, seriesId: null,
          items: [
            { kind: 'video', ref: 'v1', addedAt: '2026-05-22T02:00:00Z' },
            { kind: 'image', ref: 'x.png', addedAt: '2026-05-22T01:00:00Z' },
          ],
          createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T02:00:00Z',
        },
      ],
    });
    const a = await dataSync.getSnapshot('mediaCollections');

    // Same SET, reversed order at every level.
    await new Promise((r) => setTimeout(r, 5)); // ensure mtime changes
    writeMediaCollections({
      collections: [
        {
          id: 'c-a', name: 'A', description: '', coverKey: null, universeId: null, seriesId: null,
          items: [
            { kind: 'image', ref: 'x.png', addedAt: '2026-05-22T01:00:00Z' },
            { kind: 'video', ref: 'v1', addedAt: '2026-05-22T02:00:00Z' },
          ],
          createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T02:00:00Z',
        },
        {
          id: 'c-b', name: 'B', description: '', coverKey: null, universeId: null, seriesId: null,
          items: [
            { kind: 'image', ref: 'a.png', addedAt: '2026-05-22T01:00:00Z' },
            { kind: 'image', ref: 'z.png', addedAt: '2026-05-22T03:00:00Z' },
          ],
          createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T03:00:00Z',
        },
      ],
    });
    const b = await dataSync.getSnapshot('mediaCollections');
    expect(b.checksum).toBe(a.checksum);
  });
});

// ---------------------------------------------------------------------------
// Per-peer snapshot scoping (`forPeerId`) — the Item A / Item B fix.
//
// When the requesting peer is passed via `forPeerId`, the source EXCLUDES the
// records it already pushes that peer per-record (the records THIS instance
// has outbound subscriptions for to that peer) — leaving un-subscribed records
// and torn-down-sub tombstones to ride the snapshot. With NO forPeerId, the
// snapshot is the full category (legacy behavior).
// ---------------------------------------------------------------------------
describe('dataSync — per-peer snapshot scoping (forPeerId exclude-set)', () => {
  it('universe: excludes the requesting peer\'s subscribed ids, keeps un-subscribed (partial-subscription gap)', async () => {
    writeUniverseState({
      universes: [
        { id: 'u-a', name: 'A', updatedAt: '2026-05-25T10:00:00Z' },
        { id: 'u-b', name: 'B', updatedAt: '2026-05-25T10:00:00Z' },
        { id: 'u-d', name: 'D', updatedAt: '2026-05-25T10:00:00Z' }, // never subscribed
      ],
    });
    // We push u-a + u-b to peer-A per-record; u-d has no sub.
    writePeerSubs([
      { peerId: 'peer-A', recordKind: 'universe', recordId: 'u-a' },
      { peerId: 'peer-A', recordKind: 'universe', recordId: 'u-b' },
    ]);
    const scoped = await dataSync.getSnapshot('universe', { forPeerId: 'peer-A' });
    const ids = scoped.data.universes.map((u) => u.id).sort();
    // Subscribed records excluded; the un-subscribed one still rides.
    expect(ids).toEqual(['u-d']);

    // No forPeerId → full snapshot (legacy / all-or-none common case).
    const full = await dataSync.getSnapshot('universe');
    expect(full.data.universes.map((u) => u.id).sort()).toEqual(['u-a', 'u-b', 'u-d']);
  });

  it('universe: a tombstone for a torn-down sub rides the snapshot (ephemeralize-then-delete, Item B)', async () => {
    // u-x was shared, then marked ephemeral (sub torn down), then deleted →
    // the record is now a tombstone on disk and has NO peer subscription. It
    // must ride the snapshot so the peer converges the delete.
    writeUniverseState({
      universes: [
        { id: 'u-x', name: 'Gone', ephemeral: true, deleted: true, deletedAt: '2026-05-25T11:00:00Z', updatedAt: '2026-05-25T11:00:00Z' },
        { id: 'u-y', name: 'Live', updatedAt: '2026-05-25T10:00:00Z' },
      ],
    });
    // peer-A still subscribes to u-y only (u-x's sub was removed on ephemeralize).
    writePeerSubs([{ peerId: 'peer-A', recordKind: 'universe', recordId: 'u-y' }]);
    const scoped = await dataSync.getSnapshot('universe', { forPeerId: 'peer-A' });
    const byId = Object.fromEntries(scoped.data.universes.map((u) => [u.id, u]));
    // u-y excluded (covered per-record); u-x tombstone present so the delete converges.
    expect(byId['u-y']).toBeUndefined();
    expect(byId['u-x']).toBeDefined();
    expect(byId['u-x'].deleted).toBe(true);
  });

  it('pipeline: excluding a subscribed series ALSO drops its child issues; un-subscribed series + issues ride', async () => {
    writeSeriesState([
      { id: 'ser-sub', name: 'Subbed', updatedAt: '2026-05-25T10:00:00Z' },
      { id: 'ser-free', name: 'Free', updatedAt: '2026-05-25T10:00:00Z' },
    ]);
    writeIssueState([
      { id: 'iss-1', seriesId: 'ser-sub', title: 'child of subbed', updatedAt: '2026-05-25T10:00:00Z' },
      { id: 'iss-2', seriesId: 'ser-free', title: 'child of free', updatedAt: '2026-05-25T10:00:00Z' },
    ]);
    // series → pipeline category; we push ser-sub (+ its issues) per-record.
    writePeerSubs([{ peerId: 'peer-A', recordKind: 'series', recordId: 'ser-sub' }]);
    const scoped = await dataSync.getSnapshot('pipeline', { forPeerId: 'peer-A' });
    expect(scoped.data.series.map((s) => s.id)).toEqual(['ser-free']);
    // iss-1 (child of the excluded series) dropped; iss-2 (free series) rides.
    expect(scoped.data.issues.map((i) => i.id)).toEqual(['iss-2']);
  });

  it('mediaCollections: excludes the requesting peer\'s subscribed collection ids', async () => {
    writeMediaCollections({
      collections: [
        { id: 'col-sub', name: 'Subbed', description: '', coverKey: null, universeId: null, seriesId: null, items: [], createdAt: '2026-05-25T00:00:00Z', updatedAt: '2026-05-25T01:00:00Z' },
        { id: 'col-free', name: 'Free', description: '', coverKey: null, universeId: null, seriesId: null, items: [], createdAt: '2026-05-25T00:00:00Z', updatedAt: '2026-05-25T01:00:00Z' },
      ],
    });
    writePeerSubs([{ peerId: 'peer-A', recordKind: 'mediaCollection', recordId: 'col-sub' }]);
    const scoped = await dataSync.getSnapshot('mediaCollections', { forPeerId: 'peer-A' });
    expect(scoped.data.collections.map((c) => c.id)).toEqual(['col-free']);
  });

  it('subscriptions to a DIFFERENT peer do not scope this peer\'s snapshot (per-peer isolation)', async () => {
    writeUniverseState({
      universes: [{ id: 'u-a', name: 'A', updatedAt: '2026-05-25T10:00:00Z' }],
    });
    // u-a is subscribed to peer-B, but peer-A pulls — peer-A must still get u-a.
    writePeerSubs([{ peerId: 'peer-B', recordKind: 'universe', recordId: 'u-a' }]);
    const scopedForA = await dataSync.getSnapshot('universe', { forPeerId: 'peer-A' });
    expect(scopedForA.data.universes.map((u) => u.id)).toEqual(['u-a']);
    const scopedForB = await dataSync.getSnapshot('universe', { forPeerId: 'peer-B' });
    expect(scopedForB.data.universes.map((u) => u.id)).toEqual([]);
  });

  it('checksum is per-peer: a peer\'s scoped checksum differs once any of its subs exclude a record', async () => {
    // Single universe so the (un-canonicalized) universe snapshot order can't
    // perturb the comparison — a peer that excludes the only record gets an
    // empty snapshot whose checksum necessarily differs from the 1-record one.
    // `createdAt` is set explicitly: without it, sanitizeTemplate backfills
    // `createdAt: now` on every read, making the snapshot non-deterministic
    // across calls (the comparison below relies on byte-stable snapshots).
    writeUniverseState({
      universes: [{ id: 'u-a', name: 'A', createdAt: '2026-05-25T09:00:00Z', updatedAt: '2026-05-25T10:00:00Z' }],
    });
    writePeerSubs([{ peerId: 'peer-A', recordKind: 'universe', recordId: 'u-a' }]);
    const full = await dataSync.getChecksum('universe');
    const scopedA = await dataSync.getChecksum('universe', { forPeerId: 'peer-A' });
    // peer-A's scoped checksum (u-a excluded → empty) differs from the full one.
    expect(scopedA.checksum).not.toBe(full.checksum);
    // A peer with NO subs excludes nothing → its scoped snapshot ids match the
    // full set (checksum equality would also assert ordering, which the
    // universe snapshot doesn't canonicalize — assert on content instead).
    const scopedC = await dataSync.getSnapshot('universe', { forPeerId: 'peer-C' });
    expect(scopedC.data.universes.map((u) => u.id)).toEqual(['u-a']);
  });

  it('checksum cache invalidates when a subscription changes even though no record file moved', async () => {
    // One universe so the empty-vs-present checksum comparison is unambiguous.
    // Explicit `createdAt` keeps the snapshot byte-stable across reads (see the
    // sanitizeTemplate backfill note in the previous test).
    writeUniverseState({
      universes: [{ id: 'u-a', name: 'A', createdAt: '2026-05-25T09:00:00Z', updatedAt: '2026-05-25T10:00:00Z' }],
    });
    writePeerSubs([{ peerId: 'peer-A', recordKind: 'universe', recordId: 'u-a' }]);
    const before = await dataSync.getChecksum('universe', { forPeerId: 'peer-A' });
    // Tear down the sub (ephemeralize-then-delete teardown) — no record file
    // moves, but the exclude-set shrinks so the scoped snapshot now includes
    // u-a again. PEER_SUBSCRIPTIONS_FILE is in CHECKSUM_PATHS, so the cache
    // must invalidate (otherwise the stale empty-snapshot checksum is served).
    await new Promise((r) => setTimeout(r, 5)); // distinct mtime for the subs file
    writePeerSubs([]);
    const after = await dataSync.getChecksum('universe', { forPeerId: 'peer-A' });
    expect(after.checksum).not.toBe(before.checksum);
    // And it now matches the full snapshot (nothing excluded).
    const full = await dataSync.getChecksum('universe');
    expect(after.checksum).toBe(full.checksum);
  });
});

describe('dataSync — videoHistory category', () => {
  const row = (id, overrides = {}) => ({
    id,
    prompt: `prompt ${id}`,
    filename: `${id}.mp4`,
    thumbnail: `${id}.jpg`,
    createdAt: '2026-05-22T00:00:00Z',
    ...overrides,
  });

  it('is registered alongside the other categories', () => {
    expect(dataSync.getSupportedCategories()).toContain('videoHistory');
  });

  it('snapshot returns the videos array under a stable key', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('v1'), row('v2')]);
    const snap = await dataSync.getSnapshot('videoHistory');
    expect(snap.data.videos).toHaveLength(2);
    expect(snap.data.videos.map((v) => v.id).sort()).toEqual(['v1', 'v2']);
    expect(snap.checksum).toBeTruthy();
  });

  it('snapshot handles a missing file gracefully', async () => {
    const snap = await dataSync.getSnapshot('videoHistory');
    expect(snap.data.videos).toEqual([]);
    expect(snap.checksum).toBeTruthy();
  });

  it('snapshot includes hidden rows but strips the hidden flag (hide stays local, checksums converge)', async () => {
    // `hidden` is local-only visibility. The row CONTENT must still ride the wire
    // (so the checksum is hide-state-independent and peers converge), but the
    // `hidden` flag itself must be stripped so it doesn't propagate.
    writeJSON(VIDEO_HISTORY_PATH, [row('v1'), row('v-hidden', { hidden: true }), row('v2')]);
    const snap = await dataSync.getSnapshot('videoHistory');
    expect(snap.data.videos.map((v) => v.id).sort()).toEqual(['v1', 'v-hidden', 'v2'].sort());
    expect(snap.data.videos.every((v) => !('hidden' in v))).toBe(true);
  });

  it('snapshot checksum is identical whether or not a row is hidden (convergence across divergent hide-state)', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('v1'), row('v2')]);
    const visible = await dataSync.getSnapshot('videoHistory');
    await new Promise((r) => setTimeout(r, 5)); // ensure mtime changes
    writeJSON(VIDEO_HISTORY_PATH, [row('v1'), row('v2', { hidden: true })]);
    const oneHidden = await dataSync.getSnapshot('videoHistory');
    // Two peers that disagree only on v2's hidden flag compute the SAME checksum.
    expect(oneHidden.checksum).toBe(visible.checksum);
  });

  it('applying a remote (hidden-stripped) row does not unhide a locally-hidden row', async () => {
    // The immutable-createdAt LWW merge keeps the existing local row on a tie, so
    // a peer's visible copy of a row the user hid locally must not undo the hide.
    writeJSON(VIDEO_HISTORY_PATH, [row('v1', { hidden: true })]);
    await dataSync.applyRemote('videoHistory', { videos: [row('v1')] }); // remote has no hidden flag
    const persisted = readJSON(VIDEO_HISTORY_PATH);
    expect(persisted.find((v) => v.id === 'v1')?.hidden).toBe(true);
  });

  it('snapshot excludes id-less rows so checksums converge (apply side drops them too)', async () => {
    // An id-less local row can't be merged by applyVideoHistoryRemote, so it
    // MUST be kept off the wire snapshot/checksum — otherwise a receiver that
    // drops it recomputes a different checksum and the peers re-download forever.
    writeJSON(VIDEO_HISTORY_PATH, [row('v1'), { prompt: 'legacy no-id', filename: 'legacy.mp4' }, row('v2')]);
    const snap = await dataSync.getSnapshot('videoHistory');
    expect(snap.data.videos.map((v) => v.id)).toEqual(['v1', 'v2']);
    // Convergence: a fresh receiver applies the wire snapshot onto an empty
    // store, then recomputes its OWN snapshot checksum — it must equal the
    // sender's. If an id-less row had leaked onto the wire, the receiver (which
    // drops it on apply) would compute a different checksum and never converge.
    writeJSON(VIDEO_HISTORY_PATH, []);
    const applied = await dataSync.applyRemote('videoHistory', snap.data);
    expect(applied.applied).toBe(true);
    const receiverSnap = await dataSync.getSnapshot('videoHistory');
    expect(receiverSnap.checksum).toBe(snap.checksum);
  });

  it('snapshot checksum is order-insensitive (rows sorted by id on the wire)', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('v-b'), row('v-a')]);
    const a = await dataSync.getSnapshot('videoHistory');
    await new Promise((r) => setTimeout(r, 5)); // ensure mtime changes
    writeJSON(VIDEO_HISTORY_PATH, [row('v-a'), row('v-b')]);
    const b = await dataSync.getSnapshot('videoHistory');
    expect(b.checksum).toBe(a.checksum);
  });

  it('applyRemote inserts new rows (union by id)', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('v1')]);
    const result = await dataSync.applyRemote('videoHistory', {
      videos: [row('v2')],
    });
    expect(result.applied).toBe(true);
    expect(result.count).toBe(1);
    const persisted = readJSON(VIDEO_HISTORY_PATH);
    expect(persisted.map((v) => v.id).sort()).toEqual(['v1', 'v2']);
  });

  it('applyRemote keeps local rows the remote does not carry (no data loss)', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('local-only'), row('shared')]);
    await dataSync.applyRemote('videoHistory', {
      videos: [row('shared'), row('remote-only')],
    });
    const persisted = readJSON(VIDEO_HISTORY_PATH);
    expect(persisted.map((v) => v.id).sort()).toEqual(['local-only', 'remote-only', 'shared']);
  });

  describe('serialization with local history writers (#9814)', () => {
    const ids = () => readJSON(VIDEO_HISTORY_PATH).map((v) => v.id).sort();
    // A local completion that is mid-flight (holding the queue) when the
    // inbound snapshot arrives; `release()` lets it finish.
    async function startPausedLocalCompletion(history) {
      let release;
      const gate = new Promise((r) => { release = r; });
      let entered;
      const started = new Promise((r) => { entered = r; });
      const done = history.mutateVideoHistory(async (list) => {
        entered();
        await gate;
        return [row('local-done'), ...list];
      });
      await started;
      return { release, done };
    }

    it('keeps base, local and remote rows when a snapshot lands while a completion is in flight', async () => {
      const history = await import('./videoGen/history.js');
      writeJSON(VIDEO_HISTORY_PATH, [row('base')]);
      const local = await startPausedLocalCompletion(history);
      const apply = dataSync.applyRemote('videoHistory', { videos: [row('remote')] });
      local.release();
      await Promise.all([local.done, apply]);
      expect(ids()).toEqual(['base', 'local-done', 'remote']);
    });

    it('keeps all rows when the completion is queued behind the snapshot', async () => {
      const history = await import('./videoGen/history.js');
      writeJSON(VIDEO_HISTORY_PATH, [row('base')]);
      const apply = dataSync.applyRemote('videoHistory', { videos: [row('remote')] });
      const local = history.mutateVideoHistory((list) => [row('local-done'), ...list]);
      await Promise.all([apply, local]);
      expect(ids()).toEqual(['base', 'local-done', 'remote']);
    });

    it('keeps both peers\' unique rows when two snapshots apply concurrently', async () => {
      writeJSON(VIDEO_HISTORY_PATH, [row('base')]);
      await Promise.all([
        dataSync.applyRemote('videoHistory', { videos: [row('peer-a')] }),
        dataSync.applyRemote('videoHistory', { videos: [row('peer-b')] }),
      ]);
      expect(ids()).toEqual(['base', 'peer-a', 'peer-b']);
    });

    it('replay is a no-op: no write, count 0, hidden and id-less rows preserved', async () => {
      const idless = { prompt: 'legacy no-id', filename: 'legacy.mp4' };
      writeJSON(VIDEO_HISTORY_PATH, [row('v1', { hidden: true }), idless]);
      const before = readFileSync(VIDEO_HISTORY_PATH, 'utf-8');
      const mtimeBefore = statSync(VIDEO_HISTORY_PATH).mtimeMs;
      await new Promise((r) => setTimeout(r, 10));
      const result = await dataSync.applyRemote('videoHistory', { videos: [row('v1')] });
      expect(result).toEqual({ applied: false, count: 0 });
      expect(statSync(VIDEO_HISTORY_PATH).mtimeMs).toBe(mtimeBefore);
      expect(readFileSync(VIDEO_HISTORY_PATH, 'utf-8')).toBe(before);
    });

    it('a rejected mutation leaves the queue usable and history intact', async () => {
      const history = await import('./videoGen/history.js');
      writeJSON(VIDEO_HISTORY_PATH, [row('base')]);
      await expect(history.mutateVideoHistory(() => { throw new Error('boom'); })).rejects.toThrow('boom');
      expect(ids()).toEqual(['base']);
      const result = await dataSync.applyRemote('videoHistory', { videos: [row('remote')] });
      expect(result.applied).toBe(true);
      expect(ids()).toEqual(['base', 'remote']);
    });
  });

  it('applyRemote LWW: newer remote createdAt wins for the same id', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('v1', { createdAt: '2026-05-22T00:00:00Z', prompt: 'old' })]);
    await dataSync.applyRemote('videoHistory', {
      videos: [row('v1', { createdAt: '2026-05-22T05:00:00Z', prompt: 'new' })],
    });
    const persisted = readJSON(VIDEO_HISTORY_PATH);
    expect(persisted).toHaveLength(1);
    expect(persisted[0].prompt).toBe('new');
  });

  it('applyRemote is a no-op when nothing is newer or new', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('v1')]);
    const result = await dataSync.applyRemote('videoHistory', { videos: [row('v1')] });
    expect(result.applied).toBe(false);
    expect(result.count).toBe(0);
  });

  it('applyRemote skips rows without a string id (cannot clobber real rows)', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('v1')]);
    const result = await dataSync.applyRemote('videoHistory', {
      videos: [{ prompt: 'no id', filename: 'x.mp4', createdAt: '2026-05-22T09:00:00Z' }],
    });
    expect(result.applied).toBe(false);
    const persisted = readJSON(VIDEO_HISTORY_PATH);
    expect(persisted.map((v) => v.id)).toEqual(['v1']);
  });

  it('applyRemote preserves an id-less LOCAL row instead of dropping it', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [{ prompt: 'legacy', filename: 'legacy.mp4' }]);
    await dataSync.applyRemote('videoHistory', { videos: [row('v-new')] });
    const persisted = readJSON(VIDEO_HISTORY_PATH);
    expect(persisted.some((v) => v.prompt === 'legacy')).toBe(true);
    expect(persisted.some((v) => v.id === 'v-new')).toBe(true);
  });

  it('checksum changes after applyRemote mutates the file', async () => {
    writeJSON(VIDEO_HISTORY_PATH, [row('v1')]);
    const before = await dataSync.getChecksum('videoHistory');
    await dataSync.applyRemote('videoHistory', { videos: [row('v2')] });
    const after = await dataSync.getChecksum('videoHistory');
    expect(after.checksum).not.toBe(before.checksum);
  });
});

describe('dataSync — storyBuilder category (#730)', () => {
  const STORY_BUILDER_DIR = join(tempRoot, 'story-builder');
  const session = (id, overrides = {}) => ({
    id,
    title: `Session ${id}`,
    intakeMode: 'seed',
    seedIdea: '',
    universeId: null,
    seriesId: null,
    currentStep: 'idea',
    steps: {},
    llm: { provider: null, model: null },
    sync: true,
    syncedHashes: {},
    origin: null,
    createdAt: '2026-05-22T00:00:00Z',
    updatedAt: '2026-05-22T00:00:00Z',
    ...overrides,
  });
  const writeSessions = (sessions) => writeCollectionState(STORY_BUILDER_DIR, 'storyBuilder', sessions);
  const readSessions = () => readCollectionState(STORY_BUILDER_DIR);

  it('is registered alongside the other categories', () => {
    expect(dataSync.getSupportedCategories()).toContain('storyBuilder');
  });

  it('snapshot includes ONLY sync:true sessions — local-only sessions never cross the wire', async () => {
    writeSessions([session('stb-synced'), session('stb-local', { sync: false })]);
    const snap = await dataSync.getSnapshot('storyBuilder');
    expect(snap.data.sessions.map((s) => s.id)).toEqual(['stb-synced']);
    expect(snap.checksum).toBeTruthy();
  });

  it('snapshot checksum is identical whether or not a local-only session exists (convergence)', async () => {
    writeSessions([session('stb-synced')]);
    const a = await dataSync.getSnapshot('storyBuilder');
    await new Promise((r) => setTimeout(r, 5));
    writeSessions([session('stb-synced'), session('stb-local', { sync: false })]);
    const b = await dataSync.getSnapshot('storyBuilder');
    expect(b.checksum).toBe(a.checksum);
  });

  it('applyRemote inserts a new synced session (union by id)', async () => {
    writeSessions([session('stb-a')]);
    const result = await dataSync.applyRemote('storyBuilder', {
      sessions: [session('stb-b')],
    });
    expect(result.applied).toBe(true);
    expect(readSessions().map((s) => s.id).sort()).toEqual(['stb-a', 'stb-b']);
  });

  it('applyRemote LWW: newer remote wins for the same id', async () => {
    writeSessions([session('stb-a', { title: 'old', updatedAt: '2026-05-22T00:00:00Z' })]);
    await dataSync.applyRemote('storyBuilder', {
      sessions: [session('stb-a', { title: 'new', updatedAt: '2026-05-22T05:00:00Z' })],
    });
    expect(readSessions().find((s) => s.id === 'stb-a').title).toBe('new');
  });

  it('applyRemote refuses to overwrite a LOCAL session the user turned local-only', async () => {
    writeSessions([session('stb-a', { sync: false, title: 'local wins' })]);
    const result = await dataSync.applyRemote('storyBuilder', {
      sessions: [session('stb-a', { title: 'peer wins?', updatedAt: '2030-01-01T00:00:00Z' })],
    });
    expect(result.applied).toBe(false);
    const got = readSessions().find((s) => s.id === 'stb-a');
    expect(got.sync).toBe(false);
    expect(got.title).toBe('local wins');
  });

  it('round-trips: a fresh receiver applying the wire snapshot recomputes the same checksum', async () => {
    writeSessions([session('stb-a'), session('stb-b'), session('stb-local', { sync: false })]);
    const snap = await dataSync.getSnapshot('storyBuilder');
    // Fresh receiver: empty store, apply, recompute.
    rmSync(STORY_BUILDER_DIR, { recursive: true, force: true });
    writeSessions([]);
    const applied = await dataSync.applyRemote('storyBuilder', snap.data);
    expect(applied.applied).toBe(true);
    const receiverSnap = await dataSync.getSnapshot('storyBuilder');
    expect(receiverSnap.checksum).toBe(snap.checksum);
  });

  it('does NOT block a storyBuilder snapshot when the sender is ahead on universes (per-category gate)', async () => {
    writeSessions([]);
    const result = await dataSync.applyRemote('storyBuilder', {
      sessions: [session('stb-a')],
    }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 6, storyBuilder: 1 } } });
    expect(result.blockedBySchema).toBeUndefined();
    expect(result.applied).toBe(true);
  });

  it('STILL blocks a storyBuilder snapshot when the sender is ahead on storyBuilder', async () => {
    writeSessions([]);
    const result = await dataSync.applyRemote('storyBuilder', {
      sessions: [session('stb-a')],
    }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { storyBuilder: 2 } } });
    expect(result.applied).toBe(false);
    expect(result.blockedBySchema).toBeDefined();
    expect(result.blockedBySchema.ahead).toEqual([
      { category: 'storyBuilder', senderV: 2, receiverV: 1 },
    ]);
    expect(readSessions()).toEqual([]);
  });
});

describe('dataSync — per-category schema gate (cross-key isolation)', () => {
  // A sender always stamps its FULL schemaVersions map (buildPortosMeta spreads
  // PORTOS_SCHEMA_VERSIONS). The old whole-payload gate rejected EVERY category
  // when the sender was ahead on ANY one of them. These tests pin the new
  // per-category behavior: an ahead-mismatch only gates the category whose
  // storage layout that snapshot actually writes.
  const aheadOnUniverses = {
    portosVersion: '99.0.0',
    schemaVersions: { universes: 6, pipelineSeries: 1, pipelineIssues: 1, mediaCollections: 1 },
  };

  it('does NOT block a videoHistory snapshot when the sender is ahead on universes', async () => {
    // videoHistory has no versioned storage layout, so it must keep syncing
    // even from a sender on a newer universes layout. This is the exact latent
    // bug the per-category gate fixes (the old union gate rejected it).
    writeJSON(VIDEO_HISTORY_PATH, []);
    const result = await dataSync.applyRemote('videoHistory', {
      videos: [{ id: 'v1', prompt: 'p', filename: 'v1.mp4', createdAt: '2026-05-22T00:00:00Z' }],
    }, { portosMeta: aheadOnUniverses });
    expect(result.blockedBySchema).toBeUndefined();
    expect(result.applied).toBe(true);
  });

  it('does NOT block a pipeline snapshot when the sender is ahead on universes', async () => {
    writeSeriesState([]);
    writeIssueState([]);
    const result = await dataSync.applyRemote('pipeline', {
      series: [{ id: 'ser-1', name: 'Foundry', updatedAt: '2026-05-17T11:00:00Z' }],
      issues: [],
    }, { portosMeta: aheadOnUniverses });
    expect(result.blockedBySchema).toBeUndefined();
    expect(result.applied).toBe(true);
    expect(readSeriesState().find((s) => s.id === 'ser-1')).toBeTruthy();
  });

  it('does NOT block a mediaCollections snapshot when the sender is ahead on universes', async () => {
    writeMediaCollections({ collections: [] });
    const result = await dataSync.applyRemote('mediaCollections', {
      collections: [{
        id: 'c-new', name: 'New', description: '', coverKey: null, universeId: null, seriesId: null,
        items: [], createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T01:00:00Z',
      }],
    }, { portosMeta: aheadOnUniverses });
    expect(result.blockedBySchema).toBeUndefined();
    expect(result.applied).toBe(true);
  });

  it('does NOT block a universe snapshot when the sender is ahead on mediaCollections only', async () => {
    writeUniverseState({ universes: [], runs: [] });
    const result = await dataSync.applyRemote('universe', {
      universes: [{ id: 'u-new', name: 'Foundry', updatedAt: '2026-05-17T10:00:00Z' }],
    }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 5, mediaCollections: PORTOS_SCHEMA_VERSIONS.mediaCollections + 1 } } });
    expect(result.blockedBySchema).toBeUndefined();
    expect(result.applied).toBe(true);
  });

  it('STILL blocks a pipeline snapshot when the sender is ahead on pipelineSeries (relevant category)', async () => {
    writeSeriesState([]);
    writeIssueState([]);
    const result = await dataSync.applyRemote('pipeline', {
      series: [{ id: 'ser-1', name: 'Foundry', updatedAt: '2026-05-17T11:00:00Z' }],
      issues: [],
    }, { portosMeta: { portosVersion: '99.0.0', schemaVersions: { universes: 5, pipelineSeries: SENDER_AHEAD_PIPELINE_SERIES_V, pipelineIssues: 1, mediaCollections: 1 } } });
    expect(result.applied).toBe(false);
    expect(result.blockedBySchema).toBeDefined();
    // The reported gap is scoped to the relevant category — NOT mis-attributed.
    expect(result.blockedBySchema.ahead).toEqual([
      { category: 'pipelineSeries', senderV: SENDER_AHEAD_PIPELINE_SERIES_V, receiverV: RECEIVER_PIPELINE_SERIES_V },
    ]);
    expect(readSeriesState()).toEqual([]); // nothing written
  });

  // ---- gate-map completeness (fail-open guard) -------------------------
  it('every snapshot category has a deliberate schema-key mapping', () => {
    // No `|| []` fallthrough surprises: a future category must be mapped
    // explicitly (even to []) so the gate decision for it is intentional.
    const map = dataSync.getSnapshotCategorySchemaKeys();
    for (const category of dataSync.getSupportedCategories()) {
      expect(Array.isArray(map[category])).toBe(true);
    }
  });

  it('every versioned PORTOS_SCHEMA_VERSIONS key is reachable from some snapshot category', () => {
    // A newly-versioned category can't ship without being wired into the
    // per-category snapshot gate — otherwise its snapshot transfer is ungated.
    //
    // EXCEPTION: a few keys move via dedicated out-of-band sync endpoints
    // (Postgres-backed federation), not the file-snapshot transfer. Those
    // are gated at their own apply path with `compareSchemaVersions` and
    // need not appear in the snapshot map. List them here so the coverage
    // assertion stays honest about what the snapshot map IS and ISN'T
    // responsible for.
    const OUT_OF_BAND_SYNC_KEYS = new Set([
      // Memory current-row pull negotiates version metadata at /api/memory/sync;
      // memorySync rejects future versions, and history never enters snapshots.
      'memoryHistory',
      // Peer credential handshake version (#8356), advertised in health details; never a data category.
      'peerAuth',
      // Numeric PortOS quality uses its version-validated read-through endpoint, never snapshot writes.
      'appQuality',
      // catalog → in-process applyRemoteChanges (server/services/catalogSync.js)
      'catalog',
      // authors → per-record peer-push only (no 60s file-snapshot category).
      // Gated at applyIncomingPush via compareSchemaVersions / RECORD_KIND_SCHEMA_CATEGORIES.author.
      'authors',
      // music records → per-record peer-push only (no 60s file-snapshot category).
      // Gated at applyIncomingPush via compareSchemaVersions / RECORD_KIND_SCHEMA_CATEGORIES.
      'artists',
      'albums',
      'tracks',
      // Creative Director projects (#1564) → per-record peer-push only (no 60s
      // file-snapshot category). Gated at applyIncomingPush via
      // compareSchemaVersions / RECORD_KIND_SCHEMA_CATEGORIES.creativeDirectorProject.
      'creativeDirectorProjects',
      // Mood boards (#1564) → per-record peer-push only (no 60s file-snapshot
      // category). Gated at applyIncomingPush via compareSchemaVersions /
      // RECORD_KIND_SCHEMA_CATEGORIES.moodBoard.
      'moodBoards',
      // Writers Room works (#1565) → per-record peer-push only (no 60s
      // file-snapshot category; the .md prose bodies ride a dedicated body
      // manifest). Gated at applyIncomingPush via compareSchemaVersions /
      // RECORD_KIND_SCHEMA_CATEGORIES.writersRoomWork.
      'writersRoomWorks',
      // Writers Room folders + exercises (#1645) → per-record peer-push only (no
      // 60s file-snapshot category; both are body-less). Gated at
      // applyIncomingPush via compareSchemaVersions /
      // RECORD_KIND_SCHEMA_CATEGORIES.writersRoomFolder / .writersRoomExercise.
      'writersRoomFolders',
      'writersRoomExercises',
      // Music Video projects (#1770) → per-record peer-push only (no 60s
      // file-snapshot category). Gated at applyIncomingPush via
      // compareSchemaVersions / RECORD_KIND_SCHEMA_CATEGORIES.musicVideoProject.
      'musicVideoProjects',
      // Creative Commission feedback (#2686) → per-record peer-push only (no 60s
      // file-snapshot category). Gated at applyIncomingPush via
      // compareSchemaVersions / RECORD_KIND_SCHEMA_CATEGORIES.commissionFeedback.
      'commissionFeedback',
      // Creative Commission brief (#2686) → per-record peer-push only (no 60s
      // file-snapshot category). Gated at applyIncomingPush via
      // compareSchemaVersions / RECORD_KIND_SCHEMA_CATEGORIES.creativeCommission.
      'creativeCommissions',
      // Card decks (#decks) → per-record peer-push only (no 60s file-snapshot
      // category; the deck ships its card roster inside its own record). Gated
      // at applyIncomingPush via compareSchemaVersions /
      // RECORD_KIND_SCHEMA_CATEGORIES.deck.
      'decks',
      // Storyboards → per-record peer-push only (no 60s file-snapshot category;
      // the board carries its beats/panels/takes). Gated at applyIncomingPush
      // via compareSchemaVersions / RECORD_KIND_SCHEMA_CATEGORIES.storyboard.
      'storyboards',
      // FableLoom stories → per-record peer-push only (no 60s snapshot
      // category). Gated at applyIncomingPush via compareSchemaVersions /
      // RECORD_KIND_SCHEMA_CATEGORIES.fableLoom.
      'fableLoom',
      // Standalone media library (#1566) → its own receiver-pull endpoint
      // (GET /api/peer-sync/library-manifest), NOT the file-snapshot transfer.
      // Versioned for the manifest envelope and gated by syncMediaLibraryFromPeer's
      // gentle skip-if-ahead; declared non-record in NON_RECORD_SCHEMA_CATEGORIES.
      'mediaLibrary',
      // Completed-agent CoS history (#1650) → its own receiver-pull endpoint
      // (GET /api/peer-sync/cos-history-manifest), NOT the file-snapshot transfer.
      // Versioned for the manifest envelope and gated by syncCosHistoryFromPeer's
      // gentle skip-if-ahead; declared non-record in NON_RECORD_SCHEMA_CATEGORIES.
      'cosHistory',
      // Live CoS task list + claim metadata (#1712) → its own receiver-pull
      // endpoint (GET /api/peer-sync/cos-tasks) with a claim-aware per-task merge,
      // NOT the file-snapshot transfer. Versioned for the payload envelope and
      // gated by syncCosTasksFromPeer's gentle skip-if-ahead; declared non-record
      // in NON_RECORD_SCHEMA_CATEGORIES.
      'cosTasks',
      // Promoted Eidoverse foundations (#7455) → its own receiver-pull endpoint
      // (GET /api/peer-sync/eidoverse-foundations), NOT the file-snapshot
      // transfer — the ledger is machine-local and only the promote envelope
      // ever crosses. Versioned for that envelope's transport wrapper and gated
      // by syncEidoverseFoundationsFromPeer's gentle skip-if-ahead; declared
      // non-record in NON_RECORD_SCHEMA_CATEGORIES.
      'eidoverseFoundations',
    ]);
    const covered = new Set(Object.values(dataSync.getSnapshotCategorySchemaKeys()).flat());
    for (const key of Object.keys(PORTOS_SCHEMA_VERSIONS)) {
      if (OUT_OF_BAND_SYNC_KEYS.has(key)) continue;
      expect(covered.has(key)).toBe(true);
    }
  });
});