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

310 KB
Raw Blame
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { mkdir, rm, writeFile, readFile } from 'fs/promises';
import { join } from 'path';
import { tmpdir } from 'os';

// We test peerSync.js by stubbing the external dependencies:
//   - getPeers from services/instances, getInstanceId from services/instanceIdentity
//   - merge*FromSync + getUniverse + getSeries + issue lookup/list helpers
//   - peerFetch (network)
// All other logic (subscription store, asset manifest, diff, cursor advance)
// runs against the real on-disk paths via the tmpdir-redirect pattern below.

vi.mock('./peerPushAuthorization.js', () => ({ authorizeIncomingPush: vi.fn().mockResolvedValue({}) }));
import { authorizeIncomingPush } from './peerPushAuthorization.js';

import { PATHS } from '../../lib/fileUtils.js';
import { RECORD_KIND_SCHEMA_CATEGORIES, PORTOS_SCHEMA_VERSIONS, NON_RECORD_SCHEMA_CATEGORIES } from '../../lib/schemaVersions.js';

// instances.js / instanceIdentity.js mocks: align with mockNoPeers() /
// mockTestIdentity() (#6836 split identity out of instances.js) while keeping
// vi.fn() wrappers so per-test overrides via vi.mocked(getPeers)
// .mockResolvedValue([...]) still work. A plain mockNoPeers()/mockTestIdentity()
// call would return static functions that vi.mocked() cannot spy on — so we
// construct vi.fn() variants here and match the same defaults.
vi.mock('../instances.js', () => ({
  DEFAULT_SYNC_CATEGORIES: {},
  getPeers: vi.fn().mockResolvedValue([]),
  enqueueReciprocalSync: vi.fn().mockResolvedValue({ ok: true }),
}));

vi.mock('../instanceIdentity.js', () => ({
  UNKNOWN_INSTANCE_ID: 'unknown',
  getInstanceId: vi.fn().mockResolvedValue('test-instance'),
}));

vi.mock('../universeBuilder.js', async () => ({
  getUniverse: vi.fn(),
  mergeUniversesFromSync: vi.fn(),
  listUniverses: vi.fn(),
}));

vi.mock('../pipeline/series.js', async () => ({
  getSeries: vi.fn(),
  mergeSeriesFromSync: vi.fn(),
  listSeries: vi.fn(),
  SERIES_ID_RE: /^ser-[A-Za-z0-9-]+$/,
}));

vi.mock('../pipeline/issues.js', async () => ({
  getIssue: vi.fn(),
  listAllIssues: vi.fn(),
  listIssues: vi.fn(),
  listIssuesForSeries: vi.fn(),
  mergeIssuesFromSync: vi.fn(),
}));

// manuscriptReview is dynamic-imported inside the series push/receive helpers;
// mock both entry points so the review bundle path is exercisable.
vi.mock('../pipeline/manuscriptReview.js', async () => ({
  getReview: vi.fn(),
  mergeReviewFromSync: vi.fn(),
}));

// reverseOutline is dynamic-imported inside the series push/receive helpers (and
// statically by exporter.js, which peerSync.js imports) — mock both entry points
// so the outline bundle path is exercisable without loading the arcPlanner graph.
vi.mock('../pipeline/reverseOutline.js', async () => ({
  getStoredOutline: vi.fn(),
  mergeOutlineFromSync: vi.fn(),
}));

vi.mock('../mediaCollections.js', async () => ({
  getCollection: vi.fn(),
  listCollections: vi.fn(),
  findCollectionByUniverseId: vi.fn(),
  findCollectionBySeriesId: vi.fn(),
  mergeMediaCollectionsFromSync: vi.fn(),
}));

// #1566 — the media-library sweep dynamic-imports this to rebuild the derived
// media_assets index after bytes land. Mock it to a no-op spy so the sweep tests
// don't touch Postgres and can assert the reconcile fired.
vi.mock('../mediaAssetIndex/index.js', () => ({
  reconcileMediaAssets: vi.fn().mockResolvedValue({ ok: true, skippedPrune: [] }),
}));

vi.mock('../artists/index.js', async () => {
  const imageBasename = (url) => {
    if (typeof url !== 'string' || !url.trim()) return null;
    if (/^(https?:|data:|blob:)/i.test(url)) return null;
    const prefix = '/data/images/';
    const value = url.startsWith(prefix) ? url.slice(prefix.length) : url;
    if (value.startsWith('/')) return null;
    return value.split(/[?#]/)[0].split('/').pop() || null;
  };
  return {
    getArtist: vi.fn(),
    listArtists: vi.fn(),
    mergeArtistsFromSync: vi.fn(),
    portraitImageFilename: vi.fn(imageBasename),
  };
});

vi.mock('../albums/index.js', async () => {
  const imageBasename = (url) => {
    if (typeof url !== 'string' || !url.trim()) return null;
    if (/^(https?:|data:|blob:)/i.test(url)) return null;
    const prefix = '/data/images/';
    const value = url.startsWith(prefix) ? url.slice(prefix.length) : url;
    if (value.startsWith('/')) return null;
    return value.split(/[?#]/)[0].split('/').pop() || null;
  };
  return {
    getAlbum: vi.fn(),
    listAlbums: vi.fn(),
    mergeAlbumsFromSync: vi.fn(),
    coverImageFilename: vi.fn(imageBasename),
  };
});

vi.mock('../tracks/index.js', async () => ({
  getTrack: vi.fn(),
  listTracks: vi.fn(),
  mergeTracksFromSync: vi.fn(),
  trackAudioFilename: vi.fn((name) => {
    if (typeof name !== 'string' || !name.trim()) return null;
    const value = name.trim();
    return value.includes('/') || value.includes('\\') || value.includes('..') ? null : value;
  }),
}));

vi.mock('../musicVideo/projects.js', async () => ({
  getProject: vi.fn(),
  listProjects: vi.fn(),
  mergeProjectsFromSync: vi.fn(),
}));

// #1964 — getFullSyncCoverageForPeer walks EVERY PEER_SUBSCRIBABLE_KIND and
// calls listRecordsForKind for each. These four backends were previously left
// unmocked, so on a developer machine with a populated `portos` Postgres the
// coverage `total` counted REAL author / CD-project / mood-board / writers-room
// rows instead of the fixture — the order-dependent flake tracked in #1964
// (`expected 3 to be 1`). Partially mock them (spread the real module via
// importOriginal so the merge/get/tombstone/asset surface other sharing modules
// import stays intact) and override ONLY the DB-reading list functions, so
// coverage is driven purely by the per-test fixture, hermetic regardless of
// suite order or DB contents.
vi.mock('../authors/index.js', async (importOriginal) => ({
  ...(await importOriginal()),
  listAuthors: vi.fn().mockResolvedValue([]),
  // #6843: getAuthor/mergeAuthorsFromSync stubbed (not spread from the real
  // module) so the all-kinds parity suite can drive/assert push+receive for
  // this kind the same way universe/series/etc. already are, without hitting
  // the real file-backed store.
  getAuthor: vi.fn(),
  mergeAuthorsFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
}));
vi.mock('../creativeDirector/local.js', async (importOriginal) => ({
  ...(await importOriginal()),
  listProjects: vi.fn().mockResolvedValue([]),
  getProject: vi.fn(),
  mergeProjectsFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
}));
vi.mock('../moodBoard/index.js', async (importOriginal) => ({
  ...(await importOriginal()),
  listBoards: vi.fn().mockResolvedValue([]),
  getBoard: vi.fn(),
  mergeBoardsFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
}));
vi.mock('../fableLoom/index.js', () => ({
  getLoom: vi.fn(),
  listLooms: vi.fn().mockResolvedValue([]),
  mergeLoomsFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
}));
vi.mock('../writersRoom/bibleSync.js', async (importOriginal) => ({
  ...(await importOriginal()),
  diffWorkBibleManifest: vi.fn().mockResolvedValue([]),
}));
vi.mock('../writersRoom/sync.js', async (importOriginal) => ({
  ...(await importOriginal()),
  listWorksForSync: vi.fn().mockResolvedValue([]),
  listFoldersForSync: vi.fn().mockResolvedValue([]),
  listExercisesForSync: vi.fn().mockResolvedValue([]),
  getWorkForSync: vi.fn(),
  mergeWorksFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
  getFolderForSync: vi.fn(),
  mergeFoldersFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
  getExerciseForSync: vi.fn(),
  mergeExercisesFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
}));
// #2686: commissionFeedback is a per-record store peerSync's getFullSyncCoverageForPeer
// iterates via PEER_SUBSCRIBABLE_KINDS. Mock the lister so the zero-records
// coverage assertions don't read the real (dev-Postgres) backend.
vi.mock('../creativeCommissions/feedbackStore.js', async (importOriginal) => ({
  ...(await importOriginal()),
  listCommissionFeedbackForSync: vi.fn().mockResolvedValue([]),
  getCommissionFeedbackForSync: vi.fn(),
  mergeCommissionFeedbackFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
}));
vi.mock('../creativeCommissions/store.js', async (importOriginal) => ({
  ...(await importOriginal()),
  listCommissionsForSync: vi.fn().mockResolvedValue([]),
  getCommissionForSync: vi.fn(),
  mergeCommissionsFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
}));
vi.mock('../storyboards/index.js', () => ({
  listStoryboardsForSync: vi.fn().mockResolvedValue([]),
  listStoryboardIdsForSync: vi.fn().mockResolvedValue([]),
  getStoryboardForSync: vi.fn(),
  mergeStoryboardsFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
  pruneTombstonedStoryboards: vi.fn().mockResolvedValue({ pruned: 0 }),
}));
vi.mock('../decks.js', () => ({
  listDecksForSync: vi.fn().mockResolvedValue([]),
  listDeckIdsForSync: vi.fn().mockResolvedValue([]),
  getDeckForSync: vi.fn(),
  mergeDecksFromSync: vi.fn().mockResolvedValue({ applied: true, count: 1 }),
  pruneTombstonedDecks: vi.fn().mockResolvedValue({ pruned: 0, ids: [] }),
}));

vi.mock('../../lib/peerHttpClient.js', async (importOriginal) => ({
  peerFetch: vi.fn(),
  readPeerBody: (await importOriginal()).readPeerBody,
  peerSocketOptions: {},
}));

// Catalog bundle deps are dynamic-imported inside the universe push/apply
// helpers; mock the backend + DB + sync so the bundle path is exercisable
// without Postgres. Default backend is non-postgres so existing tests see no
// bundle; the catalog-bundle suite overrides getBackendName per-test.
vi.mock('../memoryBackend.js', async () => ({
  getBackendName: vi.fn(() => 'file'),
}));
vi.mock('../catalogDB.js', async () => ({
  getCatalogBundleForRef: vi.fn(),
  getLocalIngredientRefOwnership: vi.fn(),
}));
vi.mock('../catalogSync.js', async () => ({
  applyRemoteChanges: vi.fn(),
}));

import {
  PEER_SUBSCRIBABLE_KINDS,
  listPeerSubscriptions,
  findPeerSubscription,
  getOutboundCoverageForPeer,
  getFullSyncCoverageForPeer,
  subscribePeer,
  unsubscribePeer,
  unsubscribeAllForPeer,
  unsubscribeAllForRecord,
  pruneOrphanedPeerSubscriptions,
  pushRecordToPeer,
  applyIncomingPush,
  diffAssetManifestAgainstLocal,
  buildAssetManifest,
  assetIntegrityForRecord,
  collectCollectionAssetReferences,
  autoSubscribeRecordToAllPeers,
  autoSubscribePeerToAllRecords,
  retryPendingPushesForPeer,
  forcePushRecord,
  getRecordPayloadForPeer,
  pullRecordFromPeer,
  syncNowForPeer,
  collectSubscriptionsForUpdate,
  triggerPushForRecord,
  buildMediaLibraryManifest,
  libraryKindsExcludedByPatterns,
  syncMediaLibraryFromPeer,
  syncMediaLibraryWithAllPeers,
  peerSyncEvents,
  __resetForTests,
  __drainForTests,
  installPeerSyncListener,
  uninstallPeerSyncListener,
} from './peerSync.js';

import { buildPushPayload, __resetPushFailureLogForTests } from './peerSyncPush.js';
import { DEBOUNCE_MS } from './peerSyncShared.js';
import { ENVELOPE_EXTENSIONS, ENVELOPE_PENDING_KEYS } from './peerSyncShared.js';
import { getPeers } from '../instances.js';
import { getInstanceId } from '../instanceIdentity.js';
import { getUniverse, mergeUniversesFromSync, listUniverses } from '../universeBuilder.js';
import { getSeries, mergeSeriesFromSync, listSeries } from '../pipeline/series.js';
import { getIssue, listAllIssues, listIssues, listIssuesForSeries, mergeIssuesFromSync } from '../pipeline/issues.js';
import { getReview, mergeReviewFromSync } from '../pipeline/manuscriptReview.js';
import { getStoredOutline, mergeOutlineFromSync } from '../pipeline/reverseOutline.js';
import {
  getCollection,
  listCollections,
  findCollectionByUniverseId,
  findCollectionBySeriesId,
  mergeMediaCollectionsFromSync,
} from '../mediaCollections.js';
import { getArtist, listArtists, mergeArtistsFromSync } from '../artists/index.js';
import { getAlbum, listAlbums, mergeAlbumsFromSync } from '../albums/index.js';
import { getTrack, listTracks, mergeTracksFromSync } from '../tracks/index.js';
import {
  getProject as getMusicVideoProject,
  listProjects as listMusicVideoProjects,
  mergeProjectsFromSync as mergeMusicVideoProjectsFromSync,
} from '../musicVideo/projects.js';
// #1964 — list backends the full-sync coverage path reads; imported so the
// beforeEach can reset each to an empty fixture (see the partial mocks above).
// get*/merge*FromSync for these 8 kinds (#6843) drive the all-kinds parity
// suite below the same way the fully-mocked kinds above already do.
import { listAuthors, getAuthor, mergeAuthorsFromSync } from '../authors/index.js';
import {
  listProjects as listCreativeDirectorProjects,
  getProject as getCreativeDirectorProject,
  mergeProjectsFromSync as mergeCreativeDirectorProjectsFromSync,
} from '../creativeDirector/local.js';
import { listBoards, getBoard, mergeBoardsFromSync } from '../moodBoard/index.js';
import { getLoom, listLooms, mergeLoomsFromSync } from '../fableLoom/index.js';
import {
  listWorksForSync, getWorkForSync, mergeWorksFromSync,
  listFoldersForSync, getFolderForSync, mergeFoldersFromSync,
  listExercisesForSync, getExerciseForSync, mergeExercisesFromSync,
} from '../writersRoom/sync.js';
import { diffWorkBibleManifest } from '../writersRoom/bibleSync.js';
import { listCommissionFeedbackForSync, getCommissionFeedbackForSync, mergeCommissionFeedbackFromSync } from '../creativeCommissions/feedbackStore.js';
import { listCommissionsForSync, getCommissionForSync, mergeCommissionsFromSync } from '../creativeCommissions/store.js';
import { getDeckForSync, mergeDecksFromSync } from '../decks.js';
import { getStoryboardForSync, mergeStoryboardsFromSync } from '../storyboards/index.js';
import { peerFetch } from '../../lib/peerHttpClient.js';
import { RESPONSE_TOO_LARGE } from '../../lib/httpClient.js';
import { reconcileMediaAssets } from '../mediaAssetIndex/index.js';
import { getBackendName } from '../memoryBackend.js';
import { getCatalogBundleForRef, getLocalIngredientRefOwnership } from '../catalogDB.js';
import { applyRemoteChanges as applyCatalogRemoteChanges } from '../catalogSync.js';
import { listCursors, __drainForTests as __drainCursors } from './peerTombstoneCursors.js';
import { contentHashForRecord, __resetBaseHashCacheForTests } from '../../lib/conflictJournal.js';

// A chunked body with no Content-Length that never ends; only the streaming
// cap in readPeerBody can stop it.
const endlessChunkedRes = () => {
  const chunk = new Uint8Array(8 * 1024 * 1024);
  return new Response(new ReadableStream({ pull(controller) { controller.enqueue(chunk); } }));
};

let originalDataPath;
let originalImagesPath;
let originalImageRefsPath;
let originalVideosPath;
let originalMusicPath;
let tmp;

beforeEach(async () => {
  vi.mocked(authorizeIncomingPush).mockResolvedValue({});
  // Capture EVERY PATHS field we (or any test in this file) might mutate so
  // the afterEach restoration is total. The sha-mismatch-for-all-kinds test
  // points PATHS.imageRefs / PATHS.videos at the per-test tmpdir; without
  // restoring them here, later tests in unrelated files inherit the deleted
  // tmpdir and get ENOENT on real asset reads.
  originalDataPath = PATHS.data;
  originalImagesPath = PATHS.images;
  originalImageRefsPath = PATHS.imageRefs;
  originalVideosPath = PATHS.videos;
  originalMusicPath = PATHS.music;
  tmp = join(tmpdir(), `portos-peer-sync-${Date.now()}-${Math.random()}`);
  await mkdir(join(tmp, 'sharing'), { recursive: true });
  await mkdir(join(tmp, 'images'), { recursive: true });
  await mkdir(join(tmp, 'music'), { recursive: true });
  PATHS.data = tmp;
  PATHS.images = join(tmp, 'images');
  PATHS.music = join(tmp, 'music');

  // Reset mocks. The default peer fixture INTENTIONALLY INVERTS production
  // defaults: `addPeer` in instances.js creates peers with `syncEnabled:
  // false`, every `syncCategories.*` false, and `directions: ['outbound']`
  // (the user has to explicitly opt them in via the Instances page).
  // Tests in this file pre-enable everything so the new outbound/category
  // gates in pushRecordToPeer don't short-circuit the broader push-pipeline
  // assertions. Tests that exercise the gating paths explicitly override
  // these mocks with the relevant flag flipped off.
  vi.mocked(getInstanceId).mockResolvedValue('local-instance');
  vi.mocked(getPeers).mockResolvedValue([
    {
      instanceId: 'peer-a', name: 'Peer A', host: null, address: '10.0.0.2', port: 5555,
      enabled: true, syncEnabled: true,
      directions: ['outbound', 'inbound'],
      syncCategories: { universe: true, pipeline: true },
    },
    {
      instanceId: 'peer-b-inbound-only', name: 'Peer B', host: null, address: '10.0.0.3', port: 5555,
      enabled: true, syncEnabled: true,
      directions: ['inbound'],
      syncCategories: { universe: true, pipeline: true },
    },
  ]);
  vi.mocked(peerFetch).mockReset();
  vi.mocked(mergeUniversesFromSync).mockResolvedValue({ applied: true, count: 1 });
  vi.mocked(mergeSeriesFromSync).mockResolvedValue({ applied: true, count: 1 });
  vi.mocked(mergeIssuesFromSync).mockResolvedValue({ applied: true, count: 1 });
  // Default getUniverse / getSeries / issue-service mocks to resolved promises
  // so any callsite that doesn't override (e.g. the receiver-side
  // `isLocalRecordEphemeral` lookup in maybeCreateReverseSubscription)
  // doesn't blow up on `.catch` against a `vi.fn()` non-Promise return.
  // The real service functions are `async` so they always
  // return Promises; production code can assume this, but the test mock
  // has to match, including listIssuesForSeries so a buildPushPayload path
  // that bundles child issues doesn't choke on an un-overridden mock.
  vi.mocked(listUniverses).mockReset().mockResolvedValue([]);
  vi.mocked(listSeries).mockReset().mockResolvedValue([]);
  vi.mocked(getUniverse).mockReset().mockResolvedValue(undefined);
  vi.mocked(getSeries).mockReset().mockResolvedValue(undefined);
  vi.mocked(getIssue).mockReset().mockResolvedValue(undefined);
  vi.mocked(listAllIssues).mockReset().mockResolvedValue([]);
  vi.mocked(listIssues).mockReset().mockResolvedValue([]);
  vi.mocked(listIssuesForSeries).mockReset().mockResolvedValue([]);
  // Default: no manuscript review for any series. Tests that exercise the
  // review-bundle path override getReview per-call.
  vi.mocked(getReview).mockReset().mockResolvedValue({ schemaVersion: 1, comments: [] });
  vi.mocked(mergeReviewFromSync).mockReset().mockResolvedValue({ schemaVersion: 1, comments: [] });
  // Default: no stored reverse outline for any series. Tests that exercise the
  // outline-bundle path override getStoredOutline per-call.
  vi.mocked(getStoredOutline).mockReset().mockResolvedValue(null);
  vi.mocked(mergeOutlineFromSync).mockReset().mockResolvedValue(null);
  // Default: no linked collection for any record. Tests that exercise the
  // bundle path override these per-call.
  vi.mocked(getCollection).mockReset().mockRejectedValue(Object.assign(new Error('Collection not found'), { code: 'NOT_FOUND' }));
  vi.mocked(listCollections).mockReset().mockResolvedValue([]);
  vi.mocked(findCollectionByUniverseId).mockReset().mockResolvedValue(null);
  vi.mocked(findCollectionBySeriesId).mockReset().mockResolvedValue(null);
  vi.mocked(mergeMediaCollectionsFromSync).mockReset().mockResolvedValue({ applied: false, count: 0 });
  vi.mocked(getArtist).mockReset().mockResolvedValue(null);
  vi.mocked(listArtists).mockReset().mockResolvedValue([]);
  vi.mocked(mergeArtistsFromSync).mockReset().mockResolvedValue({ applied: true, count: 1 });
  vi.mocked(getAlbum).mockReset().mockResolvedValue(null);
  vi.mocked(listAlbums).mockReset().mockResolvedValue([]);
  vi.mocked(mergeAlbumsFromSync).mockReset().mockResolvedValue({ applied: true, count: 1 });
  vi.mocked(getTrack).mockReset().mockResolvedValue(null);
  vi.mocked(listTracks).mockReset().mockResolvedValue([]);
  vi.mocked(mergeTracksFromSync).mockReset().mockResolvedValue({ applied: true, count: 1 });
  vi.mocked(getMusicVideoProject).mockReset().mockResolvedValue(null);
  vi.mocked(listMusicVideoProjects).mockReset().mockResolvedValue([]);
  vi.mocked(mergeMusicVideoProjectsFromSync).mockReset().mockResolvedValue({ applied: true, count: 1 });
  // #1964 — default the remaining coverage list backends to empty so the full-
  // sync coverage `total` is fixture-driven, never leaking real Postgres rows.
  vi.mocked(listAuthors).mockReset().mockResolvedValue([]);
  vi.mocked(listCreativeDirectorProjects).mockReset().mockResolvedValue([]);
  vi.mocked(listBoards).mockReset().mockResolvedValue([]);
  vi.mocked(getLoom).mockReset().mockResolvedValue(null);
  vi.mocked(listLooms).mockReset().mockResolvedValue([]);
  vi.mocked(mergeLoomsFromSync).mockReset().mockResolvedValue({ applied: true, count: 1 });
  vi.mocked(listWorksForSync).mockReset().mockResolvedValue([]);
  vi.mocked(listFoldersForSync).mockReset().mockResolvedValue([]);
  vi.mocked(listExercisesForSync).mockReset().mockResolvedValue([]);
  vi.mocked(listCommissionFeedbackForSync).mockReset().mockResolvedValue([]);
  vi.mocked(listCommissionsForSync).mockReset().mockResolvedValue([]);
  // Catalog bundle defaults: non-postgres backend (no bundle), empty DB read,
  // no-op apply. The catalog-bundle suite overrides these per-test.
  vi.mocked(getBackendName).mockReset().mockReturnValue('file');
  vi.mocked(getLocalIngredientRefOwnership).mockReset().mockResolvedValue({ existing: new Set(), linked: new Set() });
  vi.mocked(getCatalogBundleForRef).mockReset().mockResolvedValue({ ingredients: [], refs: [] });
  vi.mocked(applyCatalogRemoteChanges).mockReset().mockResolvedValue({ errors: [] });

  // The conflict-journal base-hash side store caches `_baseHashes` against the
  // first PATHS.data it loaded; reset it so each test's fresh tmpdir starts
  // with an empty map (and stamps from a prior test don't bleed in).
  __resetBaseHashCacheForTests();

  await __resetForTests();
});

afterEach(async () => {
  try {
    // The peer-sync drain owns every fire-and-forget push/listener promise;
    // cursor writes are serialized on a separate tail. One deterministic pass
    // replaces the former fixed sleeps and prevents late writes racing rm.
    await __drainForTests();
    await __drainCursors();
    await __resetForTests();
    await rm(tmp, { recursive: true, force: true });
  } finally {
    // Restore shared PATHS even when teardown itself fails so one test cannot
    // leak its temporary data root into the rest of the suite.
    PATHS.data = originalDataPath;
    PATHS.images = originalImagesPath;
    PATHS.imageRefs = originalImageRefsPath;
    PATHS.videos = originalVideosPath;
    PATHS.music = originalMusicPath;
  }
});

// A receiver whose strict schema predates `key`: the 400 Zod emits for an
// unrecognized envelope key.
const legacyRejectsKey = (key) => {
  const rejection = { ok: false, status: 400, json: async () => ({
    code: 'VALIDATION_ERROR',
    message: 'Validation failed',
    context: { details: [{ path: '', message: `Unrecognized key(s) in object: '${key}'` }] },
  }) };
  rejection.clone = () => rejection;
  return rejection;
};
const acceptsPush = (body = {}) => ({ ok: true, status: 200, json: async () => body });
// A legacy peer for `key`: rejects every push carrying it, accepts the
// stripped retry.
const mockPeerRejecting = (key) => {
  vi.mocked(peerFetch).mockImplementation(async (_url, init) => (
    key in JSON.parse(init.body) ? legacyRejectsKey(key) : acceptsPush()
  ));
};
// The default peer fixture carries no musicVideoProjects category; music-video
// pushes need this opt-in or peerHasCategory short-circuits them.
const enableMusicVideoPeer = () => {
  vi.mocked(getPeers).mockResolvedValue([{
    instanceId: 'peer-a', name: 'Peer A', host: null, address: '10.0.0.2', port: 5555,
    enabled: true, syncEnabled: true, directions: ['outbound', 'inbound'],
    syncCategories: { musicVideoProjects: true },
  }]);
};
const sampleOutline = (generatedAt = '2026-06-02T00:00:00Z') => ({
  schemaVersion: 1, status: 'complete', generatedAt,
  plotlines: [{ id: 'a', label: 'A', kind: 'main' }],
  scenes: [{ id: 'scene-001', sequence: 0, summary: 'opening', plotlineId: 'a' }],
});

describe('peerSync', () => {
  describe('PEER_SUBSCRIBABLE_KINDS', () => {
    it('lists every record kind handled by the peer-sync pipeline', () => {
      // Exact equality (not toContain) so an accidental add/remove/reorder is
      // caught — this list is canonical and its order can affect iteration
      // elsewhere (e.g. syncNow's per-kind backfill). Issues piggyback on series
      // subscriptions; direct issue subs are intentionally rejected (Stage 2).
      expect(PEER_SUBSCRIBABLE_KINDS).toEqual(['universe', 'series', 'mediaCollection', 'author', 'artist', 'album', 'track', 'creativeDirectorProject', 'moodBoard', 'fableLoom', 'writersRoomWork', 'writersRoomFolder', 'writersRoomExercise', 'musicVideoProject', 'commissionFeedback', 'creativeCommission', 'deck', 'storyboard']);
    });
  });

  describe('subscribePeer', () => {
    it('creates a subscription, initializes the tombstone cursor, and schedules a push', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      const sub = await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      expect(sub.id).toBe('peer-universe-u1-peer-a');
      expect(sub.peerId).toBe('peer-a');
      expect(sub.adoptedFromReverse).toBe(false);
      // Cursor initialized
      const cursors = await listCursors();
      expect(cursors['peer-a']).toBeDefined();
      expect(cursors['peer-a'].subscribedSince).toBeGreaterThan(0);
    });

    it('refuses to subscribe over an unreadable list and preserves its bytes', async () => {
      const file = join(PATHS.data, 'sharing', 'peer_subscriptions.json');
      await writeFile(file, '{"subscriptions":');
      const before = await readFile(file);

      await expect(subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' }))
        .rejects.toMatchObject({ code: 'UNREADABLE_STORE', status: 500 });
      expect(await readFile(file)).toEqual(before);
    });

    it('is idempotent — re-subscribing returns the existing record without duplicating', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      const first = await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      const second = await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      expect(first.id).toBe(second.id);
      // `created` distinguishes the first insert from the idempotent re-hit so
      // auto-subscribe helpers can suppress duplicate "🔗 auto-subscribed" logs.
      expect(first.created).toBe(true);
      expect(second.created).toBe(false);
      const all = await listPeerSubscriptions();
      expect(all).toHaveLength(1);
    });

    it('drains a non-blocking initial push before teardown', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
      let resolveFetch;
      vi.mocked(peerFetch).mockImplementation(() => new Promise((resolve) => {
        resolveFetch = resolve;
      }));

      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await vi.waitFor(() => expect(peerFetch).toHaveBeenCalledTimes(1));

      let drained = false;
      const drain = __drainForTests().then(() => { drained = true; });
      await Promise.resolve();
      expect(drained).toBe(false);

      resolveFetch({ ok: true, json: async () => ({ missingAssets: [] }) });
      await drain;

      const persisted = await findPeerSubscription('peer-a', 'universe', 'u1');
      expect(persisted.lastPushedAt).toBeTruthy();
    });

    it('does NOT re-push on idempotent re-subscribe (existing sub keeps its lastPushedAt)', async () => {
      // Regression: subscribePeer used to fire pushRecordToPeer fire-and-
      // forget on every call, even when the sub already existed. For the
      // auto-subscribe paths that walk N records, that meant N
      // buildAssetManifest sha-passes for already-pushed records — wasted
      // work, since lastPushedHash short-circuits the wire I/O anyway.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      // subscribePeer registers the fire-and-forget initial push BEFORE it
      // resolves, so the drain is a deterministic barrier for it. A fixed 10ms
      // sleep was not: on a contended Windows CI runner the push chain had not
      // reached peerFetch yet and this asserted 0 > 0.
      await __drainForTests();
      // First subscribe DID push.
      expect(vi.mocked(peerFetch).mock.calls.length).toBeGreaterThan(0);
      vi.mocked(peerFetch).mockClear();
      // Second subscribe is idempotent — no push should fire.
      const second = await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await __drainForTests();
      expect(second.created).toBe(false);
      expect(vi.mocked(peerFetch)).not.toHaveBeenCalled();
    });

    it('rejects invalid kind', async () => {
      await expect(
        subscribePeer({ peerId: 'peer-a', recordKind: 'issue', recordId: 'i1' }),
      ).rejects.toThrow(/subscribable kinds/);
    });

    it('rejects missing peerId / recordId', async () => {
      await expect(
        subscribePeer({ peerId: '', recordKind: 'universe', recordId: 'u1' }),
      ).rejects.toThrow(/required/);
      await expect(
        subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: '' }),
      ).rejects.toThrow(/required/);
    });

    it('does NOT push when adoptedFromReverse=true (avoids ping-pong with the peer that just pushed us)', async () => {
      // Regression: receiver auto-creates a reverse sub on each incoming push.
      // If that reverse sub triggered an initial push, we'd ping-pong forever.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      await subscribePeer(
        { peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' },
        { adoptedFromReverse: true },
      );
      // peerFetch may have been called for some other reason, but NOT from
      // this code path. Drain rather than sleep: a negative assertion has to
      // outlast any push that WOULD have been scheduled, and the drain does
      // that deterministically instead of betting on a 10ms budget.
      await __drainForTests();
      expect(peerFetch).not.toHaveBeenCalled();
    });
  });

  describe('getOutboundCoverageForPeer', () => {
    beforeEach(() => {
      // No push side effects — we only assert on the returned coverage map.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Ser', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(getCollection).mockResolvedValue({ id: 'c1', name: 'Col', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(listIssues).mockResolvedValue([]);
      vi.mocked(findCollectionByUniverseId).mockResolvedValue(null);
      vi.mocked(findCollectionBySeriesId).mockResolvedValue(null);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
    });

    it('groups outbound subs by snapshot category (series → pipeline)', async () => {
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'mediaCollection', recordId: 'c1' });
      const cov = await getOutboundCoverageForPeer('peer-a');
      expect([...cov.universe]).toEqual(['u1']);
      // series rolls into the pipeline category (series + child issues bundle).
      expect([...cov.pipeline]).toEqual(['ser-1']);
      expect([...cov.mediaCollections]).toEqual(['c1']);
    });

    it('only reports subs for the named peer (per-peer isolation)', async () => {
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await subscribePeer({ peerId: 'peer-b', recordKind: 'universe', recordId: 'u1' });
      const covA = await getOutboundCoverageForPeer('peer-a');
      const covB = await getOutboundCoverageForPeer('peer-b');
      expect([...covA.universe]).toEqual(['u1']);
      expect([...covB.universe]).toEqual(['u1']);
      const covC = await getOutboundCoverageForPeer('peer-c');
      expect(covC.universe.size).toBe(0);
    });

    it('returns empty coverage for a missing/blank peerId', async () => {
      const cov = await getOutboundCoverageForPeer('');
      expect(cov.universe.size + cov.pipeline.size + cov.mediaCollections.size).toBe(0);
    });
  });

  describe('getFullSyncCoverageForPeer', () => {
    beforeEach(() => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'U1' });
      vi.mocked(listIssues).mockResolvedValue([]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
    });

    it('reports fully-mirrored with zero total when there are no local records', async () => {
      // All listers default to [] in the suite-level beforeEach.
      const cov = await getFullSyncCoverageForPeer('peer-a');
      expect(cov).toMatchObject({ total: 0, confirmed: 0, pending: 0, fullyMirrored: true, available: true, partial: false, failedReads: [] });
    });

    // An inventory failure must survive both lazy and direct lister boundaries.
    it('marks failed inventories unavailable even when the remaining subset is confirmed', async () => {
      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
      // Inventory failures log to stderr (#7943); both streams are checked so
      // the redaction contract can't be satisfied by moving the leak elsewhere.
      const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
      vi.mocked(listUniverses).mockRejectedValue(new Error('private database details'));
      vi.mocked(listAuthors).mockRejectedValue(new Error('private author contents'));
      vi.mocked(listSeries).mockResolvedValue([{ id: 'ser-1' }]);
      await writeFile(join(tmp, 'sharing', 'peer_subscriptions.json'), JSON.stringify({
        subscriptions: [{ id: 'sub-s1', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1', lastConfirmedPushedAt: Date.now() }],
      }));
      const cov = await getFullSyncCoverageForPeer('peer-a');
      expect(cov).toMatchObject({ available: false, partial: true, fullyMirrored: false, total: 1, confirmed: 1, pending: 0 });
      expect(cov.failedReads).toEqual([
        { kind: 'universe', operation: 'records' },
        { kind: 'author', operation: 'records' },
      ]);
      expect(cov.byKind.universe).toMatchObject({ partial: true });
      expect(JSON.stringify(cov)).not.toContain('private');
      expect([...log.mock.calls, ...errorLog.mock.calls].flat().join(' ')).not.toContain('private');
      expect(errorLog.mock.calls.filter(([message]) => message.includes('coverage unavailable'))).toHaveLength(2);
      log.mockRestore();
      errorLog.mockRestore();
    });

    it('reports unavailable when subscription storage cannot be read, including empty inventories', async () => {
      await writeFile(join(tmp, 'sharing', 'peer_subscriptions.json'), 'invalid private JSON');
      const cov = await getFullSyncCoverageForPeer('peer-a');
      expect(cov).toMatchObject({ available: false, partial: true, fullyMirrored: false, total: 0, pending: 0 });
      expect(cov.failedReads).toEqual(PEER_SUBSCRIBABLE_KINDS.map(kind => ({ kind, operation: 'subscriptions' })));
      expect(JSON.stringify(cov)).not.toContain('private');
    });

    it('counts a record with no subscription as pending (real ID diff, not cursors)', async () => {
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }, { id: 'u2' }]);
      const cov = await getFullSyncCoverageForPeer('peer-a');
      expect(cov.total).toBe(2);
      expect(cov.confirmed).toBe(0);
      expect(cov.pending).toBe(2);
      expect(cov.fullyMirrored).toBe(false);
      expect(cov.byKind.universe).toEqual({ total: 2, confirmed: 0, pending: 2 });
    });

    it('counts a confirmed-pushed subscription as mirrored', async () => {
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      // peerHasCategory gate is bypassed here — forcePushRecord drives the push
      // directly. Register the peer so forcePushRecord finds it.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', name: 'A', enabled: true, syncEnabled: true, fullSync: true, syncCategories: {} },
      ]);
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      // Deterministically push + confirm so lastConfirmedPushedAt is stamped
      // (the subscribe's initial push is fire-and-forget; awaiting forcePushRecord
      // avoids a drain-timing flake).
      await forcePushRecord('peer-a', 'universe', 'u1');
      const cov = await getFullSyncCoverageForPeer('peer-a');
      expect(cov.total).toBe(1);
      expect(cov.confirmed).toBe(1);
      expect(cov.pending).toBe(0);
      expect(cov.fullyMirrored).toBe(true);
    });

    it('counts a record edited AFTER its last confirmed push as pending (stale content)', async () => {
      // Record confirmed once, then edited (updatedAt in the future relative to
      // the confirm time) — the peer has stale content, so it's not mirrored.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', name: 'A', enabled: true, syncEnabled: true, fullSync: true, syncCategories: {} },
      ]);
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await forcePushRecord('peer-a', 'universe', 'u1'); // stamps lastConfirmedPushedAt ≈ now
      // Now the record reports an edit far in the future relative to the confirm.
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1', updatedAt: '2999-01-01T00:00:00Z' }]);
      const cov = await getFullSyncCoverageForPeer('peer-a');
      expect(cov.total).toBe(1);
      expect(cov.confirmed).toBe(0);
      expect(cov.pending).toBe(1);
      expect(cov.fullyMirrored).toBe(false);
    });

    it('a created-but-unconfirmed subscription still counts as pending', async () => {
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      // Push FAILS — the sub is created but never confirmed-delivered.
      vi.mocked(peerFetch).mockRejectedValue(new Error('offline'));
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' }).catch(() => {});
      await __drainForTests();
      const cov = await getFullSyncCoverageForPeer('peer-a');
      expect(cov.total).toBe(1);
      expect(cov.confirmed).toBe(0);
      expect(cov.pending).toBe(1);
      expect(cov.fullyMirrored).toBe(false);
    });

    it('returns empty coverage for a blank peerId', async () => {
      const cov = await getFullSyncCoverageForPeer('');
      expect(cov).toMatchObject({ total: 0, fullyMirrored: true });
    });
  });

  describe('unsubscribePeer', () => {
    it('removes the subscription and the peer cursor when no other subs remain for that peer', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      const sub = await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await unsubscribePeer(sub.id);
      const cursors = await listCursors();
      expect(cursors['peer-a']).toBeUndefined();
    });

    it('keeps the peer cursor when other subscriptions to the same peer remain', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Bar' });
      vi.mocked(listIssues).mockResolvedValue([]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      const sub1 = await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      await unsubscribePeer(sub1.id);
      const cursors = await listCursors();
      expect(cursors['peer-a']).toBeDefined();
    });

    it('throws ERR_NOT_FOUND for unknown id', async () => {
      await expect(unsubscribePeer('peer-universe-x-peer-a')).rejects.toMatchObject({
        code: 'PEER_SYNC_SUBSCRIPTION_NOT_FOUND',
      });
    });
  });

  describe('unsubscribeAllForPeer', () => {
    it('removes every subscription targeting a peer', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1' });
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1' });
      vi.mocked(listIssues).mockResolvedValue([]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      const result = await unsubscribeAllForPeer('peer-a');
      expect(result.removed).toHaveLength(2);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).toBeNull();
    });
  });

  describe('unsubscribeAllForRecord', () => {
    it('removes every subscription for a record across all peers', async () => {
      // updateUniverse({ ephemeral: true }) fires this — when a record
      // transitions ephemeral, every per-peer sub for that record must go
      // away so the orphan-row state never materializes.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await subscribePeer({ peerId: 'peer-b-inbound-only', recordKind: 'universe', recordId: 'u1' });
      // Different record on peer-a — must survive the unsubscribe.
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u-other' });
      const result = await unsubscribeAllForRecord('universe', 'u1');
      expect(result.removed).toHaveLength(2);
      expect(result.failed).toEqual([]);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).toBeNull();
      expect(await findPeerSubscription('peer-b-inbound-only', 'universe', 'u1')).toBeNull();
      // Untouched: u-other on peer-a.
      expect(await findPeerSubscription('peer-a', 'universe', 'u-other')).not.toBeNull();
    });

    it('reports per-sub success vs failure separately when unsubscribePeer throws', async () => {
      // Regression guard against the "always push to removed" bug: a sub
      // whose unsubscribe call throws (concurrent teardown, malformed id)
      // must NOT appear in `removed`. Callers reading `removed.length`
      // need an honest count.
      //
      // We force the failure path by racing two `unsubscribeAllForRecord`
      // calls in parallel. `listPeerSubscriptions` is NOT inside the state
      // lock, so the two calls can race: each takes its own snapshot, and
      // whichever `unsubscribePeer` lands second for a given sub hits
      // ERR_NOT_FOUND and routes that id to `failed` instead of `removed`.
      //
      // The EXACT split depends on interleaving (whether the second call
      // snapshots before or after the first call's removals land), so this
      // asserts the INVARIANTS that must hold under every interleaving
      // rather than a single timing-specific outcome (the latter flaked in
      // CI — see #1200): each sub is removed exactly once total, no id is
      // ever in both `removed` and `failed` of the SAME call, and a
      // `failed` id always coincides with the other call having `removed`
      // it (a failure only happens because the racing call already won).
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      const sub1 = await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      const sub2 = await subscribePeer({ peerId: 'peer-b-inbound-only', recordKind: 'universe', recordId: 'u1' });
      const [resultA, resultB] = await Promise.all([
        unsubscribeAllForRecord('universe', 'u1'),
        unsubscribeAllForRecord('universe', 'u1'),
      ]);

      const removedA = new Set(resultA.removed);
      const removedB = new Set(resultB.removed);
      const failedA = new Set(resultA.failed);
      const failedB = new Set(resultB.failed);

      // Each sub is removed exactly once across the two calls — never zero
      // (it must come out) and never twice (the lock serializes the actual
      // removal, so only one call legitimately removes it).
      for (const id of [sub1.id, sub2.id]) {
        const removedCount = (removedA.has(id) ? 1 : 0) + (removedB.has(id) ? 1 : 0);
        expect(removedCount, `sub ${id} removed exactly once`).toBe(1);
      }

      // The honest-accounting guard: within a single call, an id is never
      // reported as BOTH removed and failed.
      for (const [removed, failed] of [[removedA, failedA], [removedB, failedB]]) {
        for (const id of removed) expect(failed.has(id)).toBe(false);
      }

      // Any `failed` id is one the OTHER call removed — a failure only
      // arises because the racing call already won that sub (never a
      // spurious failure for a sub nobody removed).
      for (const id of failedA) expect(removedB.has(id)).toBe(true);
      for (const id of failedB) expect(removedA.has(id)).toBe(true);

      // Both subs are actually gone from disk regardless of who won.
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).toBeNull();
      expect(await findPeerSubscription('peer-b-inbound-only', 'universe', 'u1')).toBeNull();
    });

    it('returns {removed: [], failed: []} for invalid arguments', async () => {
      expect(await unsubscribeAllForRecord('', 'u1')).toEqual({ removed: [], failed: [] });
      expect(await unsubscribeAllForRecord('universe', '')).toEqual({ removed: [], failed: [] });
      expect(await unsubscribeAllForRecord('bogus', 'u1')).toEqual({ removed: [], failed: [] });
    });
  });

  describe('pruneOrphanedPeerSubscriptions', () => {
    beforeEach(() => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1' });
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1' });
      vi.mocked(listIssues).mockResolvedValue([]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
    });

    it('drops subs whose record no longer resolves and keeps the rest', async () => {
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u-gone' });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u-live' });
      await subscribePeer({ peerId: 'peer-b', recordKind: 'series', recordId: 's-gone' });
      // Resolver: only u-live still exists.
      const live = new Set(['universe:u-live']);
      const res = await pruneOrphanedPeerSubscriptions(async (kind, id) => live.has(`${kind}:${id}`));
      expect(res.pruned).toBe(2);
      expect(await findPeerSubscription('peer-a', 'universe', 'u-gone')).toBeNull();
      expect(await findPeerSubscription('peer-b', 'series', 's-gone')).toBeNull();
      // u-live survives.
      expect(await findPeerSubscription('peer-a', 'universe', 'u-live')).not.toBeNull();
    });

    it('keeps a sub whose resolver throws (conservative — never a false strip)', async () => {
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      const res = await pruneOrphanedPeerSubscriptions(async () => { throw new Error('listing blew up'); });
      expect(res.pruned).toBe(0);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).not.toBeNull();
    });

    it('returns {pruned:0, removed:[]} for a non-function resolver', async () => {
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      expect(await pruneOrphanedPeerSubscriptions(undefined)).toEqual({ pruned: 0, removed: [] });
      // The sub is untouched.
      expect(await listPeerSubscriptions()).toHaveLength(1);
    });

    it('drops the tombstone cursor when the peer’s last sub was an orphan', async () => {
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u-gone' });
      let cursors = await listCursors();
      expect(cursors['peer-a']).toBeDefined();
      await pruneOrphanedPeerSubscriptions(async () => false); // everything orphaned
      cursors = await listCursors();
      expect(cursors['peer-a']).toBeUndefined();
    });
  });

  describe('autoSubscribeRecordToAllPeers', () => {
    beforeEach(() => {
      // Default these so the push triggered by subscribePeer doesn't 500
      // when the underlying buildPushPayload runs.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1' });
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1' });
      vi.mocked(listIssues).mockResolvedValue([]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
    });

    it('is registered with the recordEvents subscription adapter at module load', async () => {
      // Domain services (universeBuilder/series/mediaCollections/instances)
      // reach these functions only through the adapter — this pins the
      // module-scope registerSubscriptionAdapter(...) call that wires it.
      const adapter = await import('./recordEvents.js');
      vi.mocked(getPeers).mockResolvedValue([]);
      // Registered → the real implementation's no-peers [] (an unregistered
      // adapter would resolve to undefined instead).
      await expect(adapter.autoSubscribeRecordToAllPeers('universe', 'u1')).resolves.toEqual([]);
    });

    it('subscribes the record to every peer with the matching category enabled', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', name: 'A', enabled: true, syncCategories: { universe: true } },
        { instanceId: 'peer-b', name: 'B', enabled: true, syncCategories: { universe: true } },
        { instanceId: 'peer-c', name: 'C', enabled: true, syncCategories: { universe: false } },
      ]);
      const created = await autoSubscribeRecordToAllPeers('universe', 'u1');
      expect(created.map(c => c.peerId).sort()).toEqual(['peer-a', 'peer-b']);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).not.toBeNull();
      expect(await findPeerSubscription('peer-c', 'universe', 'u1')).toBeNull();
    });

    it('skips disabled peers and inbound-only peers', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', name: 'A', enabled: false, syncCategories: { universe: true } },
        { instanceId: 'peer-b', name: 'B', enabled: true, syncCategories: { universe: true }, directions: ['inbound'] },
        { instanceId: 'peer-c', name: 'C', enabled: true, syncCategories: { universe: true }, directions: ['outbound'] },
      ]);
      const created = await autoSubscribeRecordToAllPeers('universe', 'u1');
      expect(created.map(c => c.peerId)).toEqual(['peer-c']);
    });

    it('skips peers with syncEnabled=false (global toggle off)', async () => {
      // Regression guard: the per-category bit is necessary but not sufficient
      // — `syncEnabled` is the global "sync this peer at all" toggle. Without
      // this check, a peer the user silenced would still be auto-subscribed
      // and pushed to from createUniverse / createSeries.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', enabled: true, syncEnabled: false, syncCategories: { universe: true } },
        { instanceId: 'peer-b', enabled: true, syncEnabled: true, syncCategories: { universe: true } },
      ]);
      const created = await autoSubscribeRecordToAllPeers('universe', 'u1');
      expect(created.map(c => c.peerId)).toEqual(['peer-b']);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).toBeNull();
    });

    it('maps series records to the pipeline category', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', enabled: true, syncCategories: { universe: true, pipeline: false } },
        { instanceId: 'peer-b', enabled: true, syncCategories: { universe: false, pipeline: true } },
      ]);
      const created = await autoSubscribeRecordToAllPeers('series', 'ser-1');
      expect(created.map(c => c.peerId)).toEqual(['peer-b']);
    });

    it('returns [] for invalid arguments', async () => {
      expect(await autoSubscribeRecordToAllPeers('bogus', 'x')).toEqual([]);
      expect(await autoSubscribeRecordToAllPeers('universe', '')).toEqual([]);
    });

    it('returns [] on re-run — only newly-created subs are reported', async () => {
      // Idempotent re-subscribe must not re-log "🔗 auto-subscribed" or
      // re-count existing subs as freshly created. This pins the
      // `subscribePeer().created` plumbing.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', name: 'A', enabled: true, syncCategories: { universe: true } },
      ]);
      const first = await autoSubscribeRecordToAllPeers('universe', 'u1');
      expect(first.map(c => c.peerId)).toEqual(['peer-a']);
      const second = await autoSubscribeRecordToAllPeers('universe', 'u1');
      expect(second).toEqual([]);
    });

    it('persists the base hash synchronously (awaitInitialPush coalesces the flush)', async () => {
      // Regression for the flush-coalesce wrap: the fan-out wraps its loop in
      // withBaseHashFlushBatch and passes awaitInitialPush, so every peer's
      // initial-push base-hash stamp lands BEFORE the helper returns — no
      // drain needed. Under the old fire-and-forget path the push hadn't even
      // started yet, so the file wouldn't carry the stamp here.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'U1' });
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', name: 'A', enabled: true, syncCategories: { universe: true } },
        { instanceId: 'peer-b', name: 'B', enabled: true, syncCategories: { universe: true } },
      ]);
      const created = await autoSubscribeRecordToAllPeers('universe', 'u1');
      expect(created.map(c => c.peerId).sort()).toEqual(['peer-a', 'peer-b']);
      // Assert against the FILE, not getSyncBaseHash() — the latter reads the
      // in-memory map and would pass even if the terminal flush never wrote. A
      // present-on-disk entry proves the batch's coalesced write actually ran
      // inside the awaited fan-out (no drain).
      // On-disk entries are `{ h, v }` (#2912 — the hash-fields version travels
      // with the hash it was computed under); `.h` is the plain hash string.
      const onDisk = JSON.parse(await readFile(join(tmp, 'sharing', 'sync_base_hashes.json'), 'utf8'));
      expect(onDisk['universe:u1'].h).toBe(contentHashForRecord('universe', { id: 'u1', name: 'U1' }));
    });
  });

  describe('autoSubscribePeerToAllRecords', () => {
    beforeEach(() => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1' });
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1' });
      vi.mocked(listIssues).mockResolvedValue([]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      // Default: peer is registered + outbound-capable + has both categories
      // enabled. Individual tests override to verify the gating paths.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', name: 'A', enabled: true, syncCategories: { universe: true, pipeline: true } },
      ]);
    });

    it('subscribes every local non-deleted universe to the peer', async () => {
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }, { id: 'u2' }]);
      const created = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(created.map(c => c.recordId).sort()).toEqual(['u1', 'u2']);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).not.toBeNull();
      expect(await findPeerSubscription('peer-a', 'universe', 'u2')).not.toBeNull();
    });

    it('subscribes every local non-deleted series to the peer', async () => {
      vi.mocked(listSeries).mockResolvedValue([{ id: 'ser-1' }, { id: 'ser-2' }]);
      const created = await autoSubscribePeerToAllRecords('peer-a', 'series');
      expect(created.map(c => c.recordId).sort()).toEqual(['ser-1', 'ser-2']);
    });

    it('backfills every local FableLoom when its category is enabled', async () => {
      vi.mocked(getPeers).mockResolvedValue([{
        instanceId: 'peer-a',
        name: 'A',
        enabled: true,
        syncEnabled: true,
        directions: ['outbound'],
        syncCategories: { fableLoom: true },
      }]);
      vi.mocked(listLooms).mockResolvedValue([{ id: 'loom-1' }, { id: 'loom-2' }]);
      vi.mocked(getLoom).mockImplementation(async (id) => ({
        id, name: `Story ${id}`, episodes: [], updatedAt: '2026-01-01T00:00:00.000Z',
      }));

      const created = await autoSubscribePeerToAllRecords('peer-a', 'fableLoom');

      expect(created.map((sub) => sub.recordId).sort()).toEqual(['loom-1', 'loom-2']);
      expect(await findPeerSubscription('peer-a', 'fableLoom', 'loom-1')).not.toBeNull();
    });

    it('returns [] when the peer is disabled', async () => {
      // Guard against backfill pushing to a peer the user has explicitly
      // disabled — the category bit can be stale even after `enabled: false`.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', enabled: false, syncCategories: { universe: true } },
      ]);
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      const created = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(created).toEqual([]);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).toBeNull();
    });

    it('returns [] when syncEnabled is false (global toggle off)', async () => {
      // Mirrors the autoSubscribeRecordToAllPeers test — both helpers go
      // through `peerAllowsOutbound` which now consults syncEnabled.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', enabled: true, syncEnabled: false, syncCategories: { universe: true } },
      ]);
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      const created = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(created).toEqual([]);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).toBeNull();
    });

    it('returns [] when the peer is inbound-only', async () => {
      // Inbound-only peers must not get outbound subscriptions — that would
      // trigger pushes in violation of the peer's configured directions.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', enabled: true, directions: ['inbound'], syncCategories: { universe: true } },
      ]);
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      const created = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(created).toEqual([]);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).toBeNull();
    });

    it('returns [] when the matching category is no longer enabled', async () => {
      // Race window: caller saw false→true flip, then the user toggled back
      // to false before this helper ran. Re-check protects against that.
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', enabled: true, syncCategories: { universe: false } },
      ]);
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      const created = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(created).toEqual([]);
    });

    it('returns [] when the peer id is unknown', async () => {
      vi.mocked(getPeers).mockResolvedValue([]);
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      const created = await autoSubscribePeerToAllRecords('peer-ghost', 'universe');
      expect(created).toEqual([]);
    });

    it('a full-sync peer subscribes records even when the matching category bit is off', async () => {
      // fullSync implies every category — so the back-subscribe sweep covers a
      // kind whose individual syncCategories bit was never turned on (and any
      // future kind, with no per-peer change).
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'peer-a', enabled: true, syncEnabled: true, fullSync: true, syncCategories: { universe: false } },
      ]);
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      const created = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(created.map(c => c.recordId)).toEqual(['u1']);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).not.toBeNull();
    });

    it('returns [] on re-run — only newly-created subs are reported', async () => {
      // `subscribePeer` is idempotent; the helper must not double-count
      // existing subs as freshly created on the second invocation.
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      const first = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(first.map(c => c.recordId)).toEqual(['u1']);
      const second = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(second).toEqual([]);
    });

    it('backfills existing music records for their category toggles', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        {
          instanceId: 'peer-a', name: 'A', enabled: true, syncEnabled: true, directions: ['outbound'],
          syncCategories: { artists: true, albums: true, tracks: true },
        },
      ]);
      vi.mocked(listArtists).mockResolvedValue([{ id: 'artist-1', name: 'Nova' }]);
      vi.mocked(listAlbums).mockResolvedValue([{ id: 'album-1', title: 'Debut' }]);
      vi.mocked(listTracks).mockResolvedValue([{ id: 'track-1', title: 'Intro' }]);
      vi.mocked(getArtist).mockImplementation(async (id) => ({ id, name: 'Nova' }));
      vi.mocked(getAlbum).mockImplementation(async (id) => ({ id, title: 'Debut' }));
      vi.mocked(getTrack).mockImplementation(async (id) => ({ id, title: 'Intro' }));
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });

      const artists = await autoSubscribePeerToAllRecords('peer-a', 'artist');
      const albums = await autoSubscribePeerToAllRecords('peer-a', 'album');
      const tracks = await autoSubscribePeerToAllRecords('peer-a', 'track');

      expect(artists.map(c => c.recordId)).toEqual(['artist-1']);
      expect(albums.map(c => c.recordId)).toEqual(['album-1']);
      expect(tracks.map(c => c.recordId)).toEqual(['track-1']);
      expect(await findPeerSubscription('peer-a', 'artist', 'artist-1')).not.toBeNull();
      expect(await findPeerSubscription('peer-a', 'album', 'album-1')).not.toBeNull();
      expect(await findPeerSubscription('peer-a', 'track', 'track-1')).not.toBeNull();
    });

    it('returns [] for invalid arguments', async () => {
      expect(await autoSubscribePeerToAllRecords('', 'universe')).toEqual([]);
      expect(await autoSubscribePeerToAllRecords('peer-a', 'bogus')).toEqual([]);
    });

    it('persists every record base hash synchronously (awaitInitialPush coalesces the flush)', async () => {
      // Backfill subscribes N records to one peer; awaitInitialPush keeps each
      // record's stamp inside the flush batch so all N are persisted by the
      // time the helper returns — without per-record flushes and without a
      // post-hoc drain.
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1', name: 'U1' }, { id: 'u2', name: 'U2' }]);
      vi.mocked(getUniverse).mockImplementation(async (id) => ({ id, name: id.toUpperCase() }));
      const created = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(created.map(c => c.recordId).sort()).toEqual(['u1', 'u2']);
      // Both records' stamps are in the single on-disk file — read it directly
      // (not getSyncBaseHash's in-memory map) so the assertion proves the
      // coalesced terminal flush wrote all N stamps before the helper returned.
      // On-disk entries are `{ h, v }` (#2912) — `.h` is the plain hash string.
      const onDisk = JSON.parse(await readFile(join(tmp, 'sharing', 'sync_base_hashes.json'), 'utf8'));
      expect(onDisk['universe:u1'].h).toBe(contentHashForRecord('universe', { id: 'u1', name: 'U1' }));
      expect(onDisk['universe:u2'].h).toBe(contentHashForRecord('universe', { id: 'u2', name: 'U2' }));
    });

    it('drops ephemeral records before computing the set-diff', async () => {
      // Ephemeral universes/series are local-only — backfill must not
      // create subscriptions for them, even when every other gate passes.
      // Without the filter, the sub would be created and a later push would
      // simply short-circuit via sanitizeRecordForWire — but the row would
      // still live in peer_subscriptions.json forever, confusing unsubscribe-all.
      vi.mocked(listUniverses).mockResolvedValue([
        { id: 'live' },
        { id: 'scratch', ephemeral: true },
      ]);
      const created = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(created.map(c => c.recordId)).toEqual(['live']);
      expect(await findPeerSubscription('peer-a', 'universe', 'scratch')).toBeNull();
    });

    it('short-circuits the for-loop when every record is already subscribed', async () => {
      // Regression: peer:online fires this helper on every online
      // transition. Without the pre-computed set-diff, a steady-state peer
      // with all records already subscribed would still iterate N records
      // and pay N subscribePeer readState calls per online transition.
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }, { id: 'u2' }]);
      await autoSubscribePeerToAllRecords('peer-a', 'universe');
      // Deterministically settle the fire-and-forget initial pushes (their
      // peerFetch fires a tick after subscribe returns) so they don't leak past
      // a fixed sleep into the assertion window below — the CI flake this fixes.
      await __drainForTests();
      vi.mocked(peerFetch).mockClear();
      // Re-run on steady state — no push should fire because the set-diff
      // is empty and the for-loop body never runs.
      const second = await autoSubscribePeerToAllRecords('peer-a', 'universe');
      expect(second).toEqual([]);
      expect(vi.mocked(peerFetch)).not.toHaveBeenCalled();
    });

    it('continues peer-online backfill after a kind inventory fails, logging the peer and cause', async () => {
      const log = vi.spyOn(console, 'log').mockImplementation(() => {});
      const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
      const { instanceEvents } = await import('../instanceEvents.js');
      const { installPeerSyncListener } = await import('./peerSync.js');
      installPeerSyncListener();
      vi.mocked(listUniverses).mockRejectedValue(new Error('private inventory details'));
      vi.mocked(listSeries).mockResolvedValue([{ id: 'ser-1' }]);
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      instanceEvents.emit('peer:online', {
        instanceId: 'peer-a', enabled: true, syncEnabled: true,
        directions: ['outbound'], syncCategories: { universe: true, pipeline: true },
      });
      await __drainForTests();
      expect(await findPeerSubscription('peer-a', 'series', 'ser-1')).not.toBeNull();
      const logged = errorLog.mock.calls.flat().join(' ');
      expect(logged).toContain('backfill inventory unavailable for universe → A');
      expect(logged).toContain('private inventory details');
      log.mockRestore();
      errorLog.mockRestore();
    });

    it('converges from peer:online when the toggle fired before instanceId was known', async () => {
      // Regression for the addPeer→toggle→probe ordering: addPeer creates
      // a peer with instanceId=null. The user can flip syncCategories on
      // before the first probe lands, in which case instances.updatePeer's
      // inline backfill silently no-ops (no instanceId to subscribe to).
      // The peer:online listener (wired in installPeerSyncListener) must
      // re-run autoSubscribePeerToAllRecords once the probe assigns the
      // instanceId, otherwise the user's intent is lost forever.
      const { instanceEvents } = await import('../instanceEvents.js');
      const { installPeerSyncListener } = await import('./peerSync.js');
      installPeerSyncListener();
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      // Emit peer:online with a peer that has universe-sync turned on but
      // was never seen by the inline backfill (the test never called
      // updatePeer — that's the point).
      instanceEvents.emit('peer:online', {
        instanceId: 'peer-a',
        name: 'A',
        enabled: true,
        syncEnabled: true,
        directions: ['outbound'],
        syncCategories: { universe: true },
      });
      // Poll for the listener's fire-and-forget IIFE to persist the subscription;
      // a fixed sleep races the write queue on slower CI runners.
      await vi.waitFor(async () => {
        expect(await findPeerSubscription('peer-a', 'universe', 'u1')).not.toBeNull();
      });
    });

    it('reciprocates a full-sync peer on peer:online (mirror requested once identity is known)', async () => {
      // A peer added via defaultPeerFullSync (or toggled before its first probe)
      // has fullSync:true but no instanceId, so updatePeer couldn't reciprocate.
      // peer:online must request the mutual mirror now.
      const { instanceEvents } = await import('../instanceEvents.js');
      const { installPeerSyncListener } = await import('./peerSync.js');
      const { enqueueReciprocalSync } = await import('../instances.js');
      vi.mocked(enqueueReciprocalSync).mockClear();
      installPeerSyncListener();
      vi.mocked(listUniverses).mockResolvedValue([]);
      instanceEvents.emit('peer:online', {
        id: 'local-1',
        instanceId: 'peer-a',
        name: 'A',
        enabled: true,
        syncEnabled: true,
        directions: ['outbound'],
        fullSync: true,
        syncCategories: {},
      });
      // Poll until the async handler resolves peer identity and enqueues the
      // mirror — a fixed sleep raced the call on a loaded CI runner (#1860).
      await vi.waitFor(() =>
        expect(vi.mocked(enqueueReciprocalSync)).toHaveBeenCalledWith('local-1')
      );
    });

    it('does NOT reciprocate a non-full-sync peer on peer:online (preserves prior behavior)', async () => {
      const { instanceEvents } = await import('../instanceEvents.js');
      const { installPeerSyncListener } = await import('./peerSync.js');
      const { enqueueReciprocalSync } = await import('../instances.js');
      vi.mocked(enqueueReciprocalSync).mockClear();
      installPeerSyncListener();
      vi.mocked(listUniverses).mockResolvedValue([]);
      // Emit the non-full-sync subject first, then a full-sync *barrier* peer.
      // Both run the same async handler pipeline (backfill → retryPending →
      // fullSync check), and the barrier — emitted second and doing equal-or-
      // more work — only calls enqueueReciprocalSync as its final step. So once
      // the barrier's reciprocal call lands, the subject's handler has provably
      // reached and *skipped* its own fullSync check. This replaces a fixed
      // sleep that could false-pass merely because the absent call was slow.
      instanceEvents.emit('peer:online', {
        id: 'local-2',
        instanceId: 'peer-b',
        name: 'B',
        enabled: true,
        syncEnabled: true,
        directions: ['outbound'],
        syncCategories: { universe: true },
      });
      instanceEvents.emit('peer:online', {
        id: 'local-barrier',
        instanceId: 'peer-barrier',
        name: 'Barrier',
        enabled: true,
        syncEnabled: true,
        directions: ['outbound'],
        fullSync: true,
        syncCategories: {},
      });
      await vi.waitFor(() =>
        expect(vi.mocked(enqueueReciprocalSync)).toHaveBeenCalledWith('local-barrier')
      );
      expect(vi.mocked(enqueueReciprocalSync)).not.toHaveBeenCalledWith('local-2');
    });
  });

  describe('retryPendingPushesForPeer', () => {
    beforeEach(() => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1' });
      vi.mocked(listIssues).mockResolvedValue([]);
    });

    it('re-pushes subs with lastPushedAt=null and walks all subs on subsequent retries (hash short-circuits unchanged ones)', async () => {
      // Create a sub with the initial push FAILING — leaves lastPushedAt=null.
      vi.mocked(peerFetch).mockResolvedValueOnce(null);
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      // Wait for the fire-and-forget initial push to settle so the persisted
      // lastPushedAt is final before we re-check it. Deterministic drain, not a
      // fixed sleep — the assertion below is a negative (lastPushedAt stayed
      // null), which vi.waitFor cannot poll for.
      await __drainForTests();
      const stale = await findPeerSubscription('peer-a', 'universe', 'u1');
      expect(stale.lastPushedAt).toBeNull();
      // Peer comes back — retry must succeed and stamp lastPushedAt.
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      const result = await retryPendingPushesForPeer('peer-a');
      expect(result.walked).toBe(1);
      expect(result.pushed).toBe(1); // network call landed
      const updated = await findPeerSubscription('peer-a', 'universe', 'u1');
      expect(updated.lastPushedAt).toBeTruthy();
      // Subsequent retry now walks every sub regardless of lastPushedAt
      // (the lastPushedHash short-circuit inside pushRecordToPeer is what
      // skips the actual HTTP call for unchanged records). This is the
      // mechanism that lets out-of-band file edits (e.g., a cleanup script
      // that wrote tombstones directly to disk) re-propagate via peer:online
      // without needing a per-record edit. A server restart reaches this path
      // too: instances.js emits peer:online on the first probe of each peer per
      // process even when the persisted status was already online (#11750; see
      // the boot-convergence test below).
      vi.mocked(peerFetch).mockClear();
      const second = await retryPendingPushesForPeer('peer-a');
      expect(second.walked).toBe(1); // walked, not skipped by the helper
      expect(second.pushed).toBe(0); // hash short-circuited, no HTTP call
      // The hash short-circuit inside pushRecordToPeer prevents the actual
      // HTTP call because the record content is unchanged since the first push.
      expect(vi.mocked(peerFetch)).not.toHaveBeenCalled();
    });

    it('boot convergence: the first peer:online after a restart pushes an edit stranded by the restart exactly once, a converged peer costs zero HTTP calls (#11750)', async () => {
      const { instanceEvents } = await import('../instanceEvents.js');
      const { installPeerSyncListener } = await import('./peerSync.js');
      installPeerSyncListener();
      const peer = {
        id: 'local-a', instanceId: 'peer-a', enabled: true, syncEnabled: true, status: 'online',
        directions: ['outbound'], syncCategories: { universe: true },
      };
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      await __drainForTests();

      // Converged peer: the boot-time event walks the sub but sends nothing.
      vi.mocked(peerFetch).mockClear();
      instanceEvents.emit('peer:online', peer);
      await __drainForTests();
      expect(vi.mocked(peerFetch)).not.toHaveBeenCalled();

      // The record changed after the last push but the debounce never fired
      // (the process restarted); the first boot event delivers it once.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Edited just before restart' });
      instanceEvents.emit('peer:online', peer);
      await __drainForTests();
      const pushCalls = () => vi.mocked(peerFetch).mock.calls.length;
      expect(pushCalls()).toBeGreaterThan(0);

      // A repeat event with the record unchanged since that push sends nothing.
      const afterFirst = pushCalls();
      instanceEvents.emit('peer:online', peer);
      await __drainForTests();
      expect(pushCalls()).toBe(afterFirst);
    });

    it('shutdown mid-walk stops pushing the remaining subscriptions and logs nothing (#12585)', async () => {
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1' }, { id: 'u2' }, { id: 'u3' }]);
      vi.mocked(getUniverse).mockImplementation(async (id) => ({ id }));
      // Initial pushes fail so every sub is still unpushed when the walk starts.
      vi.mocked(peerFetch).mockResolvedValue(null);
      for (const id of ['u1', 'u2', 'u3']) await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: id });
      await __drainForTests();

      // Shutdown lands while the first retry push is in flight; the later pushes
      // would hit a closed pool in production.
      vi.mocked(peerFetch).mockReset();
      vi.mocked(peerFetch).mockImplementation(async () => {
        uninstallPeerSyncListener();
        return { ok: true, json: async () => ({ missingAssets: [] }) };
      });
      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        const result = await retryPendingPushesForPeer('peer-a');
        expect(vi.mocked(peerFetch)).toHaveBeenCalledTimes(1);
        expect(result.pushed).toBe(1);
        // A walk that starts after shutdown does nothing at all.
        expect(await retryPendingPushesForPeer('peer-a')).toEqual({ walked: 0, pushed: 0 });
        expect(vi.mocked(peerFetch)).toHaveBeenCalledTimes(1);
        expect(errorSpy).not.toHaveBeenCalled();
        expect(warnSpy).not.toHaveBeenCalled();
      } finally {
        errorSpy.mockRestore();
        warnSpy.mockRestore();
      }
    });

    it('returns {walked: 0, pushed: 0} when the peer has no subscriptions', async () => {
      const result = await retryPendingPushesForPeer('peer-without-subs');
      expect(result).toEqual({ walked: 0, pushed: 0 });
    });

    it('returns {walked: 0, pushed: 0} for invalid peerId', async () => {
      expect(await retryPendingPushesForPeer('')).toEqual({ walked: 0, pushed: 0 });
      expect(await retryPendingPushesForPeer(null)).toEqual({ walked: 0, pushed: 0 });
    });
  });

  describe('scheduled push retry while the peer stays online', () => {
    const MINUTE = 60_000;
    const BACKOFF = [MINUTE, 5 * MINUTE, 15 * MINUTE, 30 * MINUTE];
    const examplePeer = (status) => ({
      instanceId: 'peer-a',
      name: 'Example Peer',
      host: null,
      address: '192.0.2.10',
      port: 5555,
      enabled: true,
      syncEnabled: true,
      status,
      directions: ['outbound', 'inbound'],
      syncCategories: { universe: true, pipeline: true },
    });
    const httpStatus = (status, body = { error: 'no' }) => {
      const res = { ok: false, status, json: async () => body };
      res.clone = () => res;
      return res;
    };
    const settled = () => ({ ok: true, status: 200, json: async () => ({ missingAssets: [] }) });

    beforeEach(() => {
      vi.mocked(getPeers).mockResolvedValue([examplePeer('online')]);
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
    });

    afterEach(() => {
      vi.useRealTimers();
    });

    async function subscribed(recordId = 'u1') {
      return subscribePeer(
        { peerId: 'peer-a', recordKind: 'universe', recordId },
        { adoptedFromReverse: true },
      );
    }

    async function advance(ms) {
      await vi.advanceTimersByTimeAsync(ms);
      await __drainForTests();
    }

    async function withFakeTimers(run) {
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
      try {
        await run();
      } finally {
        vi.useRealTimers();
      }
    }

    it('delivers a network failure on the scheduled retry without a peer:online event', async () => {
      await withFakeTimers(async () => {
        const sub = await subscribed();
        vi.mocked(peerFetch)
          .mockRejectedValueOnce(new Error('ECONNRESET'))
          .mockResolvedValue(settled());
        expect(await pushRecordToPeer(sub)).toMatchObject({ pushed: false, reason: 'network' });
        expect(peerFetch).toHaveBeenCalledTimes(1);

        await advance(MINUTE - 1);
        expect(peerFetch).toHaveBeenCalledTimes(1);
        await advance(1);

        expect(peerFetch).toHaveBeenCalledTimes(2);
        expect((await findPeerSubscription('peer-a', 'universe', 'u1')).lastPushedAt).toBeTruthy();
        await advance(30 * MINUTE);
        expect(peerFetch).toHaveBeenCalledTimes(2);
      });
    });

    it.each([500, 408, 429])('retries HTTP %s on the same schedule', async (status) => {
      await withFakeTimers(async () => {
        const sub = await subscribed();
        vi.mocked(peerFetch)
          .mockResolvedValueOnce(httpStatus(status, { error: 'unavailable' }))
          .mockResolvedValue(settled());
        expect(await pushRecordToPeer(sub)).toMatchObject({ pushed: false, reason: `http-${status}` });
        await advance(MINUTE);
        expect(peerFetch).toHaveBeenCalledTimes(2);
        expect((await pushRecordToPeer(await findPeerSubscription('peer-a', 'universe', 'u1'))).reason).toBe('unchanged');
      });
    });

    it('does not retry a 400 or a schema 409', async () => {
      await withFakeTimers(async () => {
        const rejected = await subscribed('u-400');
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u-400', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
        vi.mocked(peerFetch).mockResolvedValue(httpStatus(400, { error: 'bad record' }));
        expect(await pushRecordToPeer(rejected)).toMatchObject({ pushed: false, reason: 'http-400' });

        vi.mocked(getUniverse).mockResolvedValue({ id: 'u-409', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
        const blocked = await subscribed('u-409');
        vi.mocked(peerFetch).mockResolvedValue(httpStatus(409, {
          code: 'PEER_SYNC_SCHEMA_VERSION_AHEAD',
          context: {
            details: {
              ahead: [{ category: 'universes', senderV: 5, receiverV: 4 }],
              behind: [],
              receiverPortosVersion: '0.0.0',
            },
          },
        }));
        expect(await pushRecordToPeer(blocked)).toMatchObject({ pushed: false, reason: 'peer-schema-behind' });

        await advance(MINUTE);
        await advance(30 * MINUTE);
        expect(peerFetch).toHaveBeenCalledTimes(2);
      });
    });

    it('backs off through 5 min and 15 min to the 30 min cap', async () => {
      await withFakeTimers(async () => {
        const sub = await subscribed();
        vi.mocked(peerFetch).mockRejectedValue(new Error('ECONNRESET'));
        await pushRecordToPeer(sub);
        for (const delay of BACKOFF) {
          const before = vi.mocked(peerFetch).mock.calls.length;
          await advance(delay - 1);
          expect(vi.mocked(peerFetch).mock.calls.length).toBe(before);
          await advance(1);
          expect(vi.mocked(peerFetch).mock.calls.length).toBe(before + 1);
        }
        const atCap = vi.mocked(peerFetch).mock.calls.length;
        await advance(15 * MINUTE);
        expect(vi.mocked(peerFetch).mock.calls.length).toBe(atCap);
        await advance(15 * MINUTE);
        expect(vi.mocked(peerFetch).mock.calls.length).toBe(atCap + 1);
      });
    });

    it('a landed push cancels further retries for that peer', async () => {
      await withFakeTimers(async () => {
        const sub = await subscribed();
        vi.mocked(peerFetch)
          .mockRejectedValueOnce(new Error('ECONNRESET'))
          .mockResolvedValue(settled());
        await pushRecordToPeer(sub);
        expect(await pushRecordToPeer(await findPeerSubscription('peer-a', 'universe', 'u1'))).toMatchObject({ pushed: true });
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Edited after delivery', updatedAt: '2026-01-02T00:00:00Z' });
        vi.mocked(peerFetch).mockClear();
        await advance(MINUTE);
        await advance(30 * MINUTE);
        expect(peerFetch).not.toHaveBeenCalled();
      });
    });

    it('skips the retry tick while the peer is offline', async () => {
      await withFakeTimers(async () => {
        const sub = await subscribed();
        vi.mocked(peerFetch).mockRejectedValue(new Error('ECONNRESET'));
        await pushRecordToPeer(sub);
        vi.mocked(getPeers).mockResolvedValue([examplePeer('offline')]);
        await advance(MINUTE);
        await advance(30 * MINUTE);
        expect(peerFetch).toHaveBeenCalledTimes(1);
      });
    });

    it('skips the retry tick while a walk for that peer is already running', async () => {
      await withFakeTimers(async () => {
        const sub = await subscribed();
        vi.mocked(peerFetch).mockRejectedValueOnce(new Error('ECONNRESET'));
        await pushRecordToPeer(sub);
        vi.mocked(peerFetch).mockClear();

        let resolveFetch = () => {};
        let markFetchEntered = () => {};
        const fetchEntered = new Promise((resolve) => { markFetchEntered = resolve; });
        vi.mocked(peerFetch).mockImplementation(() => {
          markFetchEntered();
          return new Promise((resolve) => {
            resolveFetch = () => resolve(settled());
          });
        });
        const walk = retryPendingPushesForPeer('peer-a');
        // The walk reads subscriptions from disk before calling the peer, so wait on the walk
        // itself rather than a fixed turn count; a walk that settles without reaching peerFetch fails here.
        const walkEnded = walk.then((result) => ({ result }), (error) => ({ error }));
        const outcome = await Promise.race([fetchEntered.then(() => 'entered'), walkEnded]);
        if (outcome !== 'entered') {
          throw new Error(`retry walk settled without calling peerFetch: ${JSON.stringify(outcome.error?.message ?? outcome.result)}`);
        }
        expect(peerFetch).toHaveBeenCalledTimes(1);
        expect(await retryPendingPushesForPeer('peer-a')).toEqual({ walked: 0, pushed: 0, skipped: 'in-flight' });

        await advance(MINUTE);
        expect(peerFetch).toHaveBeenCalledTimes(1);
        resolveFetch();
        await walk;
      });
    });

    it('retries a missing-asset response without a new edit', async () => {
      await withFakeTimers(async () => {
        const sub = await subscribed();
        vi.mocked(peerFetch).mockResolvedValue({
          ok: true,
          status: 200,
          json: async () => ({ missingAssets: [{ filename: 'example.png' }] }),
        });
        const first = await pushRecordToPeer(sub);
        expect(first.pushed).toBe(true);
        expect(first.missingAssets).toHaveLength(1);
        expect((await findPeerSubscription('peer-a', 'universe', 'u1')).lastPushedHash).toBeFalsy();
        vi.mocked(peerFetch).mockClear();

        await advance(MINUTE - 1);
        expect(peerFetch).not.toHaveBeenCalled();
        await advance(1);
        expect(peerFetch).toHaveBeenCalledTimes(1);
        const body = JSON.parse(vi.mocked(peerFetch).mock.calls[0][1].body);
        expect(body.record.id).toBe('u1');
      });
    });

    it('uninstall cancels a pending retry', async () => {
      await withFakeTimers(async () => {
        const sub = await subscribed();
        vi.mocked(peerFetch).mockRejectedValue(new Error('ECONNRESET'));
        await pushRecordToPeer(sub);
        uninstallPeerSyncListener();
        installPeerSyncListener();
        await advance(MINUTE);
        await advance(30 * MINUTE);
        expect(peerFetch).toHaveBeenCalledTimes(1);
      });
    });
  });

  describe('forcePushRecord', () => {
    beforeEach(() => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Forced', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(listIssues).mockResolvedValue([]);
      vi.mocked(findCollectionByUniverseId).mockResolvedValue(null);
    });

    it('pushes even when existing sub lastPushedHash matches (bypasses unchanged short-circuit)', async () => {
      // First subscribe + initial push — record gets a lastPushedHash.
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
      // Poll for the fire-and-forget initial push to persist its hash. A fixed
      // sleep OR a single writeTail drain (__drainForTests) is racy in slower CI
      // because the push's peerFetch + persistPushDeliveryEvidence chain may not have even
      // started when we read — vi.waitFor retries the real condition deterministically.
      let sub;
      await vi.waitFor(async () => {
        sub = await findPeerSubscription('peer-a', 'universe', 'u1');
        expect(sub?.lastPushedHash).toBeTruthy();
      });
      expect(sub.lastPushedHash).toBeTruthy(); // hash was recorded

      // Clear the mock call count — we care only about calls from forcePushRecord.
      vi.mocked(peerFetch).mockClear();
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });

      // forcePushRecord MUST hit the network despite the hash being unchanged.
      const result = await forcePushRecord('peer-a', 'universe', 'u1');
      expect(result.pushed).toBe(true);
      expect(vi.mocked(peerFetch)).toHaveBeenCalledTimes(1);
      expect(vi.mocked(peerFetch)).toHaveBeenCalledWith(
        expect.stringContaining('/api/peer-sync/push'),
        expect.objectContaining({ method: 'POST' }),
        expect.objectContaining({ instanceId: 'peer-a' }),
      );
    });

    it('creates a subscription and pushes when no sub existed yet', async () => {
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });

      const result = await forcePushRecord('peer-a', 'universe', 'u1');
      expect(result.pushed).toBe(true);

      // Subscription should now exist.
      const sub = await findPeerSubscription('peer-a', 'universe', 'u1');
      expect(sub).not.toBeNull();
    });
  });

  describe('getRecordPayloadForPeer', () => {
    it('returns a push-payload for an existing universe', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
      const payload = await getRecordPayloadForPeer('universe', 'u1');
      expect(payload).toMatchObject({ kind: 'universe', record: { id: 'u1' } });
      expect(Array.isArray(payload.assetManifest)).toBe(true);
    });

    it('returns null when the record does not exist locally', async () => {
      vi.mocked(getUniverse).mockResolvedValue(undefined);
      expect(await getRecordPayloadForPeer('universe', 'ghost')).toBeNull();
    });

    it('returns null (no unknown-sourced payload) when self-identity is unknown', async () => {
      // Without the guard this would emit a payload with sourceInstanceId='unknown'
      // that the puller's applyIncomingPush rejects — or 500 on a read failure.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(getInstanceId).mockResolvedValueOnce('unknown');
      expect(await getRecordPayloadForPeer('universe', 'u1')).toBeNull();
    });

    it('returns null when self-identity read fails', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(getInstanceId).mockRejectedValueOnce(new Error('instances.json unreadable'));
      expect(await getRecordPayloadForPeer('universe', 'u1')).toBeNull();
    });
  });

  describe('pullRecordFromPeer', () => {
    it('peer-not-found when the peer is unknown', async () => {
      vi.mocked(getPeers).mockResolvedValue([]);
      expect(await pullRecordFromPeer('nope', 'universe', 'u1')).toEqual({ pulled: false, reason: 'peer-not-found' });
    });

    it('peer-unreachable when the fetch fails', async () => {
      vi.mocked(peerFetch).mockRejectedValue(new Error('ECONNREFUSED'));
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u1')).toEqual({ pulled: false, reason: 'peer-unreachable' });
    });

    it('not-on-peer on a 404 from the peer', async () => {
      vi.mocked(peerFetch).mockResolvedValue({ ok: false, status: 404 });
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u1')).toEqual({ pulled: false, reason: 'not-on-peer' });
    });

    it('invalid-payload when the peer returns a malformed body', async () => {
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, status: 200, json: async () => ({ junk: true }) });
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u1')).toEqual({ pulled: false, reason: 'invalid-payload' });
    });

    it('applies a valid payload and reports missingAssets count', async () => {
      vi.mocked(peerFetch).mockResolvedValue({
        ok: true,
        status: 200,
        json: async () => ({ kind: 'universe', record: { id: 'u-pull' }, assetManifest: [], sourceInstanceId: 'peer-a' }),
      });
      const result = await pullRecordFromPeer('peer-a', 'universe', 'u-pull');
      expect(result.pulled).toBe(true);
      expect(typeof result.missingAssets).toBe('number');
    });

    it('invalid-payload when sourceInstanceId does not match the contacted peer', async () => {
      // We fetched from peer-a, but the payload claims to originate from someone
      // else — applying it would bind our reverse-subscription/asset-pull to a
      // peer we never contacted. Reject rather than trust the self-reported origin.
      vi.mocked(peerFetch).mockResolvedValue({
        ok: true,
        status: 200,
        json: async () => ({ kind: 'universe', record: { id: 'u-pull' }, assetManifest: [], sourceInstanceId: 'peer-b' }),
      });
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u-pull'))
        .toEqual({ pulled: false, reason: 'invalid-payload' });
    });

    it('payload-too-large when the peer declares a Content-Length over the cap', async () => {
      vi.mocked(peerFetch).mockResolvedValue({
        ok: true,
        status: 200,
        headers: { get: (h) => (h.toLowerCase() === 'content-length' ? String(64 * 1024 * 1024) : null) },
        json: async () => ({ kind: 'universe', record: { id: 'u-pull' }, assetManifest: [], sourceInstanceId: 'peer-a' }),
      });
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u-pull'))
        .toEqual({ pulled: false, reason: 'payload-too-large' });
    });

    it('payload-too-large when a chunked body with no Content-Length streams past the cap', async () => {
      vi.mocked(peerFetch).mockResolvedValue(endlessChunkedRes());
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u-pull'))
        .toEqual({ pulled: false, reason: 'payload-too-large' });
    });

    it('payload-too-large (not peer-unreachable) when the HTTPS shim trips the maxBytes cap', async () => {
      // The shim rejects with a RESPONSE_TOO_LARGE-coded Error — must map to
      // payload-too-large, consistent with the Content-Length path, not be
      // misread as offline.
      vi.mocked(peerFetch).mockRejectedValue(
        Object.assign(new Error('Response body exceeded maxBytes 16777216 (got 99999999)'), { code: RESPONSE_TOO_LARGE })
      );
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u-pull'))
        .toEqual({ pulled: false, reason: 'payload-too-large' });
    });

    it('peer-unreachable for an uncoded transport error that merely says "exceed"', async () => {
      // Discrimination is on err.code, not on message prose: an unrelated
      // transport failure whose text happens to contain "exceed" must stay
      // peer-unreachable rather than being reported as an oversize payload.
      vi.mocked(peerFetch).mockRejectedValue(new Error('socket hang up: retries exceeded'));
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u-pull'))
        .toEqual({ pulled: false, reason: 'peer-unreachable' });
    });

    it('invalid-payload when the returned record is not the one we requested', async () => {
      // Asked for universe/u-pull but the peer returned a different record id —
      // applying it would merge unexpected data under the requested key.
      vi.mocked(peerFetch).mockResolvedValue({
        ok: true,
        status: 200,
        json: async () => ({ kind: 'universe', record: { id: 'some-other-id' }, assetManifest: [], sourceInstanceId: 'peer-a' }),
      });
      expect(await pullRecordFromPeer('peer-a', 'universe', 'u-pull'))
        .toEqual({ pulled: false, reason: 'invalid-payload' });
    });
  });

  describe('syncNowForPeer', () => {
    it('returns {ok:false} when the peer has no instanceId', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: null, name: 'No ID Peer', enabled: true, syncEnabled: true },
      ]);
      const result = await syncNowForPeer('no-such-peer');
      expect(result).toEqual({ ok: false });
    });

    it('returns {ok:false} when the peer is not found', async () => {
      const result = await syncNowForPeer('ghost-peer');
      expect(result).toEqual({ ok: false });
    });

    it('calls backfill+retry for a peer with enabled categories and returns {ok:true}', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        {
          instanceId: 'peer-a', name: 'Peer A', host: null, address: '10.0.0.2', port: 5555,
          enabled: true, syncEnabled: true,
          directions: ['outbound', 'inbound'],
          syncCategories: { universe: true, pipeline: false, mediaCollections: false },
        },
      ]);
      vi.mocked(listUniverses).mockResolvedValue([{ id: 'u1', name: 'Universe 1' }]);
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Universe 1', updatedAt: '2026-01-01T00:00:00Z' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });

      const result = await syncNowForPeer('peer-a');
      expect(result).toEqual({ ok: true });
    });
  });

  describe('buildAssetManifest', () => {
    it('hashes direct image filenames via the sidecar cache', async () => {
      await writeFile(join(PATHS.images, 'asset-1.png'), Buffer.from('image bytes'));
      const record = {
        id: 'u1',
        characters: [{ imageRefs: ['asset-1.png'] }],
      };
      const manifest = await buildAssetManifest(record);
      expect(manifest).toHaveLength(1);
      expect(manifest[0].filename).toBe('asset-1.png');
      expect(manifest[0].kind).toBe('image');
      expect(manifest[0].sha256).toMatch(/^[a-f0-9]{64}$/);
    });

    it('skips assets whose file is missing (sender cant ship bytes it doesnt have)', async () => {
      // Regression: a null-hash entry would make every receiver diff
      // report this as "missing" even though the sender cant fulfill the
      // pull, producing a permanent "asset pending" badge in the UI.
      const record = { id: 'u1', characters: [{ imageRefs: ['ghost.png'] }] };
      const manifest = await buildAssetManifest(record);
      expect(manifest).toEqual([]);
    });

    it('returns an empty manifest for records with no asset refs', async () => {
      const manifest = await buildAssetManifest({ id: 'u1', name: 'Bare' });
      expect(manifest).toEqual([]);
    });

    it('includes sidecarSha256 in the manifest entry when sidecar is present', async () => {
      await writeFile(join(PATHS.images, 'with-sidecar.png'), Buffer.from('image bytes'));
      await writeFile(join(PATHS.images, 'with-sidecar.metadata.json'), Buffer.from(JSON.stringify({ prompt: 'a cat' })));
      const record = { id: 'u1', characters: [{ imageRefs: ['with-sidecar.png'] }] };
      const manifest = await buildAssetManifest(record);
      expect(manifest).toHaveLength(1);
      expect(manifest[0].sidecarSha256).toMatch(/^[a-f0-9]{64}$/);
    });

    it('omits sidecarSha256 from the manifest entry when no sidecar exists', async () => {
      await writeFile(join(PATHS.images, 'no-sidecar.png'), Buffer.from('image bytes'));
      const record = { id: 'u1', characters: [{ imageRefs: ['no-sidecar.png'] }] };
      const manifest = await buildAssetManifest(record);
      expect(manifest).toHaveLength(1);
      expect(manifest[0]).not.toHaveProperty('sidecarSha256');
    });

    it('summarizes missing image sidecars for integrity without another asset walk', async () => {
      await writeFile(join(PATHS.images, 'missing-meta.png'), Buffer.from('image bytes'));
      const record = { id: 'u1', characters: [{ imageRefs: ['missing-meta.png'] }] };
      const summary = await assetIntegrityForRecord('universe', record);
      expect(summary.assetHashes).toHaveLength(1);
      expect(summary.metadataMissing).toBe(true);
    });

    it('includes live child issue assets in a series integrity summary', async () => {
      await writeFile(join(PATHS.images, 'issue-panel.png'), Buffer.from('issue image bytes'));
      vi.mocked(listIssuesForSeries).mockResolvedValue([
        { id: 'i1', seriesId: 'ser-1', stages: { storyboards: { panels: [{ imageRefs: ['issue-panel.png'] }] } } },
      ]);
      const summary = await assetIntegrityForRecord('series', { id: 'ser-1', name: 'Series' });
      expect(summary.assetHashes).toHaveLength(1);
      expect(summary.metadataMissing).toBe(true);
    });
  });

  describe('diffAssetManifestAgainstLocal', () => {
    it('returns assets we dont have on disk', async () => {
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'ghost.png', kind: 'image', sha256: 'a'.repeat(64) },
      ]);
      expect(missing).toHaveLength(1);
      expect(missing[0].filename).toBe('ghost.png');
    });

    it('skips assets we already have with matching sha', async () => {
      await writeFile(join(PATHS.images, 'have.png'), Buffer.from('hello world'));
      // "hello world" sha256
      const local = 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9';
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'have.png', kind: 'image', sha256: local },
      ]);
      expect(missing).toEqual([]);
    });

    it('reports assets with mismatched sha as missing (peer has newer bytes)', async () => {
      await writeFile(join(PATHS.images, 'stale.png'), Buffer.from('old bytes'));
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'stale.png', kind: 'image', sha256: 'b'.repeat(64) },
      ]);
      expect(missing).toHaveLength(1);
    });

    it('ignores malformed manifest entries silently', async () => {
      const missing = await diffAssetManifestAgainstLocal([
        null,
        'not-an-object',
        { filename: '', kind: 'image' },
        { filename: 'foo.png', kind: 'mystery' },
      ]);
      expect(missing).toEqual([]);
    });

    it('strips junk fields from echoed missingAssets entries (no untrusted round-trip)', async () => {
      // Regression: the diff originally pushed the raw peer-supplied entry
      // into the missing list, so a malicious peer could amplify response
      // size or smuggle prototype-pollution attempts by attaching extra
      // fields. The receiver MUST project to {filename, kind, sha256?} only.
      const evil = {
        filename: 'absent.png',
        kind: 'image',
        sha256: 'a'.repeat(64),
        __proto__: { polluted: true },
        gigantic: 'x'.repeat(10000),
        nested: { evil: true },
      };
      const missing = await diffAssetManifestAgainstLocal([evil]);
      expect(missing).toHaveLength(1);
      expect(Object.keys(missing[0]).sort()).toEqual(['filename', 'kind', 'sha256']);
      expect(missing[0].gigantic).toBeUndefined();
      expect(missing[0].nested).toBeUndefined();
    });

    it('rejects path-traversal filenames silently (cant be used to probe local FS)', async () => {
      // Regression: a malicious peer sending `../../etc/passwd` (or backslash
      // variants on Windows checkouts) would otherwise let us join arbitrary
      // paths and reveal whether they exist via the missing/present split.
      const missing = await diffAssetManifestAgainstLocal([
        { filename: '../../etc/passwd', kind: 'image', sha256: 'a'.repeat(64) },
        { filename: '..\\windows\\system32\\config', kind: 'image' },
        { filename: 'sub/dir/asset.png', kind: 'image' },
        { filename: '/etc/hosts', kind: 'image' },
      ]);
      expect(missing).toEqual([]);
    });

    it('reports sha-mismatched videos AND image-refs as missing (not just images)', async () => {
      // Regression: stage 2 originally only sha-checked the 'image' kind,
      // letting an image-ref / video drift silently when bytes diverged
      // under the same filename — the snapshot-sync fallback was the only
      // thing that would catch it 60s later.
      await mkdir(join(tmp, 'image-refs'), { recursive: true });
      await mkdir(join(tmp, 'videos'), { recursive: true });
      // Re-route PATHS by writing into the locations the resolver uses.
      const localImageRefBytes = Buffer.from('local image-ref bytes');
      const localVideoBytes = Buffer.from('local video bytes');
      const { PATHS: livePaths } = await import('../../lib/fileUtils.js');
      livePaths.imageRefs = join(tmp, 'image-refs');
      livePaths.videos = join(tmp, 'videos');
      const { writeFile: writeFileFs } = await import('fs/promises');
      await writeFileFs(join(livePaths.imageRefs, 'ref.png'), localImageRefBytes);
      await writeFileFs(join(livePaths.videos, 'clip.mp4'), localVideoBytes);
      const remoteFakeSha = 'f'.repeat(64);
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'ref.png', kind: 'image-ref', sha256: remoteFakeSha },
        { filename: 'clip.mp4', kind: 'video', sha256: remoteFakeSha },
      ]);
      expect(missing).toHaveLength(2);
      expect(missing.map((m) => m.filename).sort()).toEqual(['clip.mp4', 'ref.png']);
    });

    it('returns image entry as missing when image hash matches but sidecar is absent', async () => {
      // The image file is already present and hash-matches; BUT the sender
      // carries a sidecarSha256 and we have no local sidecar. The diff must
      // still include the entry so the worker pulls the sidecar.
      const imageBytes = Buffer.from('hello world');
      await writeFile(join(PATHS.images, 'nosidecar.png'), imageBytes);
      // Actual sha256 of "hello world"
      const imageHash = 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9';
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'nosidecar.png', kind: 'image', sha256: imageHash, sidecarSha256: 'a'.repeat(64) },
      ]);
      expect(missing).toHaveLength(1);
      expect(missing[0].filename).toBe('nosidecar.png');
      expect(missing[0].sidecarSha256).toBe('a'.repeat(64));
    });

    it('does NOT return an image as missing when image hash matches and sidecar gen-params match', async () => {
      // Both image and sidecar are present; the gen-params are identical — no pull needed.
      const imageBytes = Buffer.from('hello world');
      await writeFile(join(PATHS.images, 'fullmatch.png'), imageBytes);
      await writeFile(join(PATHS.images, 'fullmatch.metadata.json'), Buffer.from(JSON.stringify({ prompt: 'cat' })));
      const imageHash = 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9';
      const { sidecarGenParamsHash } = await import('../../lib/assetHash.js');
      // The sender advertises the gen-params hash (NOT the raw-file hash).
      const senderSidecarHash = sidecarGenParamsHash({ prompt: 'cat' });
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'fullmatch.png', kind: 'image', sha256: imageHash, sidecarSha256: senderSidecarHash },
      ]);
      expect(missing).toEqual([]);
    });

    it('CONVERGENCE: image NOT re-flagged when gen-params match but the sha256 cache block differs', async () => {
      // CRITICAL regression for the churn bug. Two machines with byte-identical
      // gen-params but different per-machine `sha256` cache blocks (mtimeMs/size
      // differ) must NOT perpetually re-pull. The sidecar hash is computed over
      // gen-params ONLY (sha256 cache stripped), so it converges regardless of
      // the local cache block.
      const imageBytes = Buffer.from('hello world');
      await writeFile(join(PATHS.images, 'converge.png'), imageBytes);
      // Local sidecar: SAME gen-params, but a DIFFERENT sha256 cache block than
      // whatever the sender stamped (simulates the receiver re-stamping its own
      // local image mtime+size after a prior pull).
      await writeFile(join(PATHS.images, 'converge.metadata.json'), Buffer.from(JSON.stringify({
        prompt: 'a wizard', model: 'flux', steps: 30,
        sha256: { value: 'c'.repeat(64), mtimeMs: 111111, size: 222 },
      })));
      const imageHash = 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9';
      const { sidecarGenParamsHash } = await import('../../lib/assetHash.js');
      // The SENDER computes the gen-params hash over its OWN sidecar, which has
      // the SAME gen-params but a DIFFERENT sha256 cache block (different mtime/size).
      const senderSidecarHash = sidecarGenParamsHash({
        prompt: 'a wizard', model: 'flux', steps: 30,
        sha256: { value: 'd'.repeat(64), mtimeMs: 999999, size: 888 },
      });
      // The receiver computes its local gen-params hash the same way.
      const localSidecarHash = sidecarGenParamsHash({
        prompt: 'a wizard', model: 'flux', steps: 30,
        sha256: { value: 'c'.repeat(64), mtimeMs: 111111, size: 222 },
      });
      // The two MUST be equal despite differing cache blocks — proves convergence.
      expect(senderSidecarHash).toBe(localSidecarHash);
      // And the diff must NOT flag the image as missing (no re-pull churn).
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'converge.png', kind: 'image', sha256: imageHash, sidecarSha256: senderSidecarHash },
      ]);
      expect(missing).toEqual([]);
    });

    it('CONVERGENCE: key-order differences across machines do not break the gen-params hash', async () => {
      const { sidecarGenParamsHash } = await import('../../lib/assetHash.js');
      const a = sidecarGenParamsHash({ prompt: 'x', model: 'flux', steps: 30 });
      const b = sidecarGenParamsHash({ steps: 30, prompt: 'x', model: 'flux' });
      expect(a).toBe(b);
    });

    it('returns image entry as missing when sidecar hash differs (peer has updated metadata)', async () => {
      const imageBytes = Buffer.from('hello world');
      const sidecarBytes = Buffer.from(JSON.stringify({ prompt: 'old prompt' }));
      await writeFile(join(PATHS.images, 'staleside.png'), imageBytes);
      await writeFile(join(PATHS.images, 'staleside.metadata.json'), sidecarBytes);
      const imageHash = 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9';
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'staleside.png', kind: 'image', sha256: imageHash, sidecarSha256: 'b'.repeat(64) },
      ]);
      expect(missing).toHaveLength(1);
      expect(missing[0].filename).toBe('staleside.png');
    });

    it('preserves sidecarSha256 in the sanitized missing entry (no untrusted round-trip loss)', async () => {
      const missing = await diffAssetManifestAgainstLocal([
        { filename: 'absent.png', kind: 'image', sha256: 'a'.repeat(64), sidecarSha256: 'b'.repeat(64) },
      ]);
      expect(missing).toHaveLength(1);
      expect(missing[0].sidecarSha256).toBe('b'.repeat(64));
      // Junk fields still stripped.
      expect(missing[0]).not.toHaveProperty('gigantic');
    });
  });

  describe('pushRecordToPeer', () => {
    it('refuses to push when our instance id is unknown', async () => {
      vi.mocked(getInstanceId).mockResolvedValue('unknown');
      const result = await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      expect(result.pushed).toBe(false);
      expect(result.reason).toBe('unknown-local-instance');
      expect(peerFetch).not.toHaveBeenCalled();
    });

    it('refuses to push when the target peer is missing from the registry', async () => {
      const result = await pushRecordToPeer({
        id: 's', peerId: 'peer-ghost', recordKind: 'universe', recordId: 'u1',
      });
      expect(result.pushed).toBe(false);
      expect(result.reason).toBe('peer-not-found');
    });

    it('refuses to push to a peer with syncEnabled=false (stale sub does not outlive the user toggle)', async () => {
      // Regression: an existing subscription is not a license to keep pushing
      // after the user has globally silenced the peer. Without this gate,
      // every subsequent edit would still leak across the wire.
      vi.mocked(getPeers).mockResolvedValue([
        {
          instanceId: 'peer-a', name: 'Peer A',
          enabled: true, syncEnabled: false,
          directions: ['outbound'],
          syncCategories: { universe: true },
        },
      ]);
      const result = await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      expect(result.pushed).toBe(false);
      expect(result.reason).toBe('peer-disallows-outbound');
      expect(peerFetch).not.toHaveBeenCalled();
    });

    it('refuses to push to a peer that has been switched to inbound-only', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        {
          instanceId: 'peer-a', name: 'Peer A',
          enabled: true, syncEnabled: true,
          directions: ['inbound'],
          syncCategories: { universe: true },
        },
      ]);
      const result = await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      expect(result.pushed).toBe(false);
      expect(result.reason).toBe('peer-disallows-outbound');
    });

    it('refuses to push when the matching category has been toggled off', async () => {
      // Stale sub on a universe but the user later toggled `syncCategories.universe`
      // back off — stop pushing universes to this peer.
      vi.mocked(getPeers).mockResolvedValue([
        {
          instanceId: 'peer-a', name: 'Peer A',
          enabled: true, syncEnabled: true,
          directions: ['outbound'],
          syncCategories: { universe: false, pipeline: true },
        },
      ]);
      const result = await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      expect(result.pushed).toBe(false);
      expect(result.reason).toBe('category-disabled');
    });

    it('returns record-not-found when the record id no longer exists', async () => {
      vi.mocked(getUniverse).mockResolvedValue(null);
      const result = await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'gone',
      });
      expect(result.pushed).toBe(false);
      expect(result.reason).toBe('record-not-found');
    });

    // #11455 — a store read FAILURE must not read as "record does not exist"
    // or ship a truncated payload that then advances lastPushedHash.
    describe('push read failures (#11455)', () => {
      const notFound = () => Object.assign(new Error('gone'), { code: 'PIPELINE_SERIES_NOT_FOUND' });
      const dbDown = () => Object.assign(new Error('connection refused'), { code: 'ECONNREFUSED' });

      it('maps a not-found loader error to record-not-found with no network call', async () => {
        vi.mocked(getUniverse).mockRejectedValue(Object.assign(new Error('nope'), { code: 'NOT_FOUND' }));
        const result = await pushRecordToPeer({
          id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'gone',
        });
        expect(result).toMatchObject({ pushed: false, reason: 'record-not-found' });
        expect(peerFetch).not.toHaveBeenCalled();
      });

      it('rejects, posts nothing and keeps lastPushedHash when the loader fails for another reason', async () => {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
        await subscribePeer({ peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' });
        let sub;
        await vi.waitFor(async () => {
          sub = await findPeerSubscription('peer-a', 'universe', 'u1');
          expect(sub?.lastPushedHash).toBeTruthy();
        });
        const priorHash = sub.lastPushedHash;
        vi.mocked(peerFetch).mockClear();
        vi.mocked(getUniverse).mockRejectedValue(dbDown());
        await expect(pushRecordToPeer(sub)).rejects.toThrow('connection refused');
        expect(peerFetch).not.toHaveBeenCalled();
        expect((await findPeerSubscription('peer-a', 'universe', 'u1')).lastPushedHash).toBe(priorHash);
      });

      it('series push: a failing listIssuesForSeries rejects instead of pushing issues: []', async () => {
        vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
        vi.mocked(listIssuesForSeries).mockRejectedValue(dbDown());
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1',
        }, { adoptedFromReverse: true });
        await expect(pushRecordToPeer(sub)).rejects.toThrow('connection refused');
        expect(peerFetch).not.toHaveBeenCalled();
        expect((await findPeerSubscription('peer-a', 'series', 'ser-1')).lastPushedHash).toBeFalsy();
      });

      it('series push: a failing review read rejects, but a not-found review is simply omitted', async () => {
        vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
        vi.mocked(getReview).mockRejectedValue(dbDown());
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1',
        }, { adoptedFromReverse: true });
        await expect(pushRecordToPeer(sub)).rejects.toThrow('connection refused');
        expect(peerFetch).not.toHaveBeenCalled();
        vi.mocked(getReview).mockRejectedValue(notFound());
        vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
        const ok = await pushRecordToPeer(sub);
        expect(ok.pushed).toBe(true);
      });

      it('debounced push logs the failure with the subscription id', async () => {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        vi.mocked(getUniverse).mockRejectedValue(dbDown());
        const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
        vi.useFakeTimers({ toFake: ['setTimeout'] });
        try {
          await triggerPushForRecord('universe', 'u1');
          await vi.advanceTimersByTimeAsync(DEBOUNCE_MS + 1);
        } finally {
          vi.useRealTimers();
        }
        await vi.waitFor(() => {
          expect(errSpy.mock.calls.some(([msg]) => String(msg).includes(`scheduled push failed for ${sub.id}`)
            && String(msg).includes('connection refused'))).toBe(true);
        });
        errSpy.mockRestore();
        expect(peerFetch).not.toHaveBeenCalled();
      });
    });

    it('short-circuits when the record hashes match the last push (no-op edits dont round-trip)', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      // Subscribe with adoptedFromReverse=true to suppress the auto-push so
      // we control timing explicitly — relying on a sleep to drain the
      // fire-and-forget push is flaky on slower CI runners.
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' },
        { adoptedFromReverse: true },
      );
      const first = await pushRecordToPeer(sub);
      expect(first.pushed).toBe(true);
      expect(first.hash).toBeTruthy();
      vi.mocked(peerFetch).mockClear();
      const refreshed = await findPeerSubscription('peer-a', 'universe', 'u1');
      const result = await pushRecordToPeer(refreshed);
      expect(result.pushed).toBe(false);
      expect(result.reason).toBe('unchanged');
      expect(peerFetch).not.toHaveBeenCalled();
    });

    it('persists ackedDeletesUpTo from the peer response to the tombstone cursor', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(peerFetch).mockResolvedValue({
        ok: true,
        json: async () => ({ missingAssets: [], ackedDeletesUpTo: 5000 }),
      });
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' },
        { adoptedFromReverse: true },
      );
      await pushRecordToPeer(sub);
      const cursors = await listCursors();
      expect(cursors['peer-a'].lastAckedDeleteAt).toBe(5000);
    });

    it('stamps the per-record lastConfirmedPushedAt on a confirmed push (per-record tombstone-ack clamp)', async () => {
      // The per-peer cursor advances to the MAX deletedAt across all pushes;
      // the per-record water-mark must additionally record THIS record's
      // confirmed delivery so tombstoneGc won't prune its tombstone before
      // its own (delete-)push lands. See tombstoneGc.minConfirmedPushedAtForKind.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      const before = Date.now();
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' },
        { adoptedFromReverse: true },
      );
      expect(sub.lastConfirmedPushedAt).toBeNull(); // not set until a push lands
      await pushRecordToPeer(sub);
      const refreshed = await findPeerSubscription('peer-a', 'universe', 'u1');
      expect(refreshed.lastConfirmedPushedAt).toBeGreaterThanOrEqual(before);
    });

    it('does NOT advance lastConfirmedPushedAt on a failed push (no false confirmation)', async () => {
      // A network failure must leave the per-record water-mark untouched —
      // otherwise GC would treat an undelivered record's tombstone as safe.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' },
        { adoptedFromReverse: true },
      );
      await pushRecordToPeer(sub); // first push confirms
      const afterFirst = await findPeerSubscription('peer-a', 'universe', 'u1');
      const stamped = afterFirst.lastConfirmedPushedAt;
      expect(stamped).toBeTruthy();
      // Now a later push to the SAME sub fails at the network — content must
      // differ so the unchanged-hash short-circuit doesn't skip the wire.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Bar' });
      vi.mocked(peerFetch).mockRejectedValue(new Error('ECONNREFUSED'));
      const result = await pushRecordToPeer({ ...afterFirst });
      expect(result.pushed).toBe(false);
      const afterFail = await findPeerSubscription('peer-a', 'universe', 'u1');
      expect(afterFail.lastConfirmedPushedAt).toBe(stamped); // unchanged
    });

    it('stamps lastConfirmedPushedAt at payload-snapshot time, so a live push answered after the delete stays below deletedAt (#11772)', async () => {
      // A push that read the record while live and whose response lands after
      // the user deleted it only proves the peer holds the LIVE state. Stamping
      // the floor at response time would lift it past the tombstone and let
      // tombstoneGc prune a deletion the peer never received.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      let releaseFetch;
      vi.mocked(peerFetch).mockImplementation(() => new Promise((resolve) => {
        releaseFetch = () => resolve({ ok: true, json: async () => ({ missingAssets: [] }) });
      }));
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' },
        { adoptedFromReverse: true },
      );
      const inFlight = pushRecordToPeer(sub);
      await vi.waitFor(() => expect(releaseFetch).toBeTypeOf('function'));
      await new Promise((r) => setTimeout(r, 5));
      const deletedAt = Date.now();
      await new Promise((r) => setTimeout(r, 5));
      releaseFetch();
      expect((await inFlight).pushed).toBe(true);
      const refreshed = await findPeerSubscription('peer-a', 'universe', 'u1');
      expect(refreshed.lastConfirmedPushedAt).toBeLessThan(deletedAt);
      // The human-facing "last pushed" time still reports the response.
      expect(Date.parse(refreshed.lastPushedAt)).toBeGreaterThan(deletedAt);
    });

    it('handles a network-level failure without throwing (returns pushed:false)', async () => {
      // The once-per-cause ledger would swallow the line if an earlier test already logged this cause.
      __resetPushFailureLogForTests();
      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
      try {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        vi.mocked(peerFetch).mockRejectedValue(new Error('ECONNREFUSED'));
        const result = await pushRecordToPeer({
          id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        });
        expect(result.pushed).toBe(false);
        expect(result.reason).toBe('network');
        // An asleep or offline peer is routine: stdout, not stderr.
        expect(logSpy.mock.calls.some(([line]) => /peerSync: push universe\/u1 .* unreachable/.test(line))).toBe(true);
        expect(warnSpy).not.toHaveBeenCalled();
      } finally {
        logSpy.mockRestore();
        warnSpy.mockRestore();
      }
    });

    it('logs a rejected push once per peer and cause, then logs recovery', async () => {
      // Every automatic caller discards the result, so this line is the only
      // trace that an edit never reached the peer.
      __resetPushFailureLogForTests();
      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
      try {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        vi.mocked(peerFetch).mockResolvedValue({ ok: false, status: 401, json: async () => ({ error: 'Authentication required', code: 'AUTH_REQUIRED' }) });
        const sub = { id: 's1', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' };
        expect(await pushRecordToPeer(sub)).toMatchObject({ pushed: false, reason: 'http-401' });
        await pushRecordToPeer({ ...sub, id: 's2', recordId: 'u2' });
        const failures = errorSpy.mock.calls.map(([line]) => line).filter((line) => line.includes('peerSync: push'));
        expect(failures).toHaveLength(1);
        expect(failures[0]).toMatch(/universe\/u1 \(sub s1\).*rejected with http-401: AUTH_REQUIRED: Authentication required/);

        vi.mocked(peerFetch).mockResolvedValue({ ok: true, status: 200, json: async () => ({}) });
        expect((await pushRecordToPeer(sub)).pushed).toBe(true);
        expect(logSpy.mock.calls.some(([line]) => /pushes to .* landing again after http-401/.test(line))).toBe(true);
      } finally {
        errorSpy.mockRestore();
        logSpy.mockRestore();
      }
    });

    it('does NOT short-circuit when the parent series record is identical but a bundled issue changed', async () => {
      // Regression: simplePayloadHash originally hashed only payload.record,
      // so a series push where only an issue field changed (a common case —
      // every panel edit propagates as an issue update under a series sub)
      // would collapse to reason: 'unchanged' and never propagate.
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(listIssuesForSeries).mockResolvedValueOnce([
        { id: 'i1', seriesId: 'ser-1', number: 1, title: 'First' },
      ]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' },
        { adoptedFromReverse: true },
      );
      const first = await pushRecordToPeer(sub);
      expect(first.pushed).toBe(true);

      // Series record identical, but child issue title changed → MUST re-push.
      vi.mocked(listIssuesForSeries).mockResolvedValueOnce([
        { id: 'i1', seriesId: 'ser-1', number: 1, title: 'Revised' },
      ]);
      vi.mocked(peerFetch).mockClear();
      const refreshed = await findPeerSubscription('peer-a', 'series', 'ser-1');
      const second = await pushRecordToPeer(refreshed);
      expect(second.pushed).toBe(true);
      expect(second.reason).not.toBe('unchanged');
      expect(peerFetch).toHaveBeenCalledTimes(1);
    });

    it('bundles child issues with a series push', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(listIssuesForSeries).mockResolvedValue([
        { id: 'i1', seriesId: 'ser-1', number: 1 },
        { id: 'i1001', seriesId: 'ser-1', number: 1001 },
      ]);
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1',
      });
      expect(captured.kind).toBe('series');
      expect(captured.issues).toHaveLength(2);
      expect(captured.issues.map((i) => i.id)).toEqual(['i1', 'i1001']);
      expect(listIssuesForSeries).toHaveBeenCalledWith('ser-1', { includeDeleted: true });
    });

    it('bundles the manuscript review with a series push so review-only edits propagate', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(getReview).mockResolvedValue({
        schemaVersion: 1,
        comments: [{ id: 'mrc-1', problem: 'pacing', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }],
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({ id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      expect(captured.kind).toBe('series');
      expect(captured.manuscriptReview).toBeTruthy();
      expect(captured.manuscriptReview.comments).toHaveLength(1);
      expect(captured.manuscriptReview.comments[0].id).toBe('mrc-1');
    });

    it('omits the manuscriptReview key when the series has an empty review', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(getReview).mockResolvedValue({ schemaVersion: 1, comments: [] });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({ id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      expect(captured.manuscriptReview).toBeUndefined();
    });

    it('does not fetch a review for a tombstone series push', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series', deleted: true, deletedAt: '2026-06-02T00:00:00Z', updatedAt: '2026-06-02T00:00:00Z' });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({ id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      expect(captured.manuscriptReview).toBeUndefined();
      expect(vi.mocked(getReview)).not.toHaveBeenCalled();
    });

    it('bundles the reverse outline with a series push so regenerate-only edits propagate', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(getStoredOutline).mockResolvedValue({
        seriesId: 'ser-1', schemaVersion: 1, status: 'complete', generatedAt: '2026-06-02T00:00:00Z',
        plotlines: [{ id: 'a', label: 'A-plot', kind: 'main', color: '#3b82f6' }],
        scenes: [{ id: 'scene-001', sequence: 0, summary: 'opening', plotlineId: 'a' }],
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({ id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      expect(captured.reverseOutline).toBeTruthy();
      expect(captured.reverseOutline.scenes).toHaveLength(1);
      expect(captured.reverseOutline.generatedAt).toBe('2026-06-02T00:00:00Z');
    });

    it('omits the reverseOutline key when no complete outline exists', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      // A never-generated / in-progress outline (status !== 'complete') is not shipped.
      vi.mocked(getStoredOutline).mockResolvedValue({ seriesId: 'ser-1', schemaVersion: 1, status: 'none', plotlines: [], scenes: [] });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({ id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      expect(captured.reverseOutline).toBeUndefined();
    });

    it('does not fetch an outline for a tombstone series push', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series', deleted: true, deletedAt: '2026-06-02T00:00:00Z', updatedAt: '2026-06-02T00:00:00Z' });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({ id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' });
      expect(captured.reverseOutline).toBeUndefined();
      expect(vi.mocked(getStoredOutline)).not.toHaveBeenCalled();
    });

    it('re-pushes when only the manuscript review changes (series record byte-identical)', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(getReview)
        .mockResolvedValueOnce({
          schemaVersion: 1,
          comments: [{ id: 'mrc-1', problem: 'pacing', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }],
        })
        .mockResolvedValueOnce({
          // A comment status flip bumps updatedAt → review (and thus hash) changes.
          schemaVersion: 1,
          comments: [{ id: 'mrc-1', problem: 'pacing', status: 'accepted', updatedAt: '2026-06-02T01:00:00Z' }],
        });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1' },
        { adoptedFromReverse: true },
      );
      const first = await pushRecordToPeer(sub);
      expect(first.pushed).toBe(true);

      vi.mocked(peerFetch).mockClear();
      const refreshed = await findPeerSubscription('peer-a', 'series', 'ser-1');
      const second = await pushRecordToPeer(refreshed);
      expect(second.pushed).toBe(true);
      expect(second.reason).not.toBe('unchanged');
      expect(peerFetch).toHaveBeenCalledTimes(1);
    });

    it('bundles the linked media collection with a universe push so collection-only edits propagate', async () => {
      // Regression: collection items[] adds emit recordEvents.updated('universe', id)
      // but the universe record content itself doesn't change, so the
      // lastPushedHash short-circuit treated the push as 'unchanged' and the
      // receiver's collection diverged permanently. Including the linked
      // collection in both the payload AND the hash defeats the short-circuit.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Universe' });
      vi.mocked(findCollectionByUniverseId).mockResolvedValueOnce({
        id: 'col-1',
        name: 'Universe: U',
        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',
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      expect(captured.kind).toBe('universe');
      expect(captured.linkedCollection).toBeTruthy();
      expect(captured.linkedCollection.id).toBe('col-1');
      expect(captured.linkedCollection.items).toHaveLength(1);
    });

    it('strips the local-only provenance stamp from a bundled linkedCollection', async () => {
      // #3311: `source` is per-install and must not cross the wire in ANY
      // transport. The standalone mediaCollection push goes through
      // sanitizeRecordForWire; the bundled copy has to as well, or the two
      // forms of the same record disagree and an upgraded peer's collection
      // checksum drifts from a not-yet-upgraded one's.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Universe' });
      vi.mocked(findCollectionByUniverseId).mockResolvedValueOnce({
        id: 'col-1',
        name: 'Universe: U',
        description: '',
        coverKey: null,
        universeId: 'u1',
        seriesId: null,
        source: 'auto',
        items: [],
        createdAt: '2026-05-22T00:00:00Z',
        updatedAt: '2026-05-22T01:00:00Z',
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      expect(captured.linkedCollection.id).toBe('col-1');
      expect(captured.linkedCollection.source).toBeUndefined();
    });

    it('re-pushes when only the linked collection items change (universe record byte-identical)', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Universe' });
      vi.mocked(findCollectionByUniverseId)
        .mockResolvedValueOnce({
          id: 'col-1', name: 'Universe: U', 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',
        })
        .mockResolvedValueOnce({
          id: 'col-1', name: 'Universe: U', description: '', coverKey: null,
          universeId: 'u1', seriesId: null,
          items: [
            { kind: 'image', ref: 'a.png', addedAt: '2026-05-22T01:00:00Z' },
            { kind: 'image', ref: 'b.png', addedAt: '2026-05-22T02:00:00Z' },
          ],
          createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T02:00:00Z',
        });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'universe', recordId: 'u1' },
        { adoptedFromReverse: true },
      );
      const first = await pushRecordToPeer(sub);
      expect(first.pushed).toBe(true);

      vi.mocked(peerFetch).mockClear();
      const refreshed = await findPeerSubscription('peer-a', 'universe', 'u1');
      const second = await pushRecordToPeer(refreshed);
      expect(second.pushed).toBe(true);
      expect(second.reason).not.toBe('unchanged');
      expect(peerFetch).toHaveBeenCalledTimes(1);
    });

    it('appends .mp4 when a collection video item ref is a bare id (no extension)', async () => {
      // Regression: video collection items store the bare id (e.g. a UUID),
      // while the on-disk file is `<id>.mp4`. Without the append, the file
      // would never be found, no manifest entry would be emitted, and the
      // receiver would never pull the video bytes.
      PATHS.videos = join(tmp, 'videos');
      await mkdir(PATHS.videos, { recursive: true });
      await writeFile(join(PATHS.videos, 'vid-abc.mp4'), 'fake mp4 bytes');

      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Universe' });
      vi.mocked(findCollectionByUniverseId).mockResolvedValueOnce({
        id: 'col-1', name: 'Universe: U', description: '', coverKey: null,
        universeId: 'u1', seriesId: null,
        items: [{ kind: 'video', ref: 'vid-abc', addedAt: '2026-05-22T01:00:00Z' }],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T01:00:00Z',
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      const videoEntries = captured.assetManifest.filter(a => a.kind === 'video');
      expect(videoEntries).toHaveLength(1);
      // The .mp4 must have been appended to the bare id when constructing the manifest entry.
      expect(videoEntries[0].filename).toBe('vid-abc.mp4');
    });

    it('does NOT bundle a linked collection when the universe is a tombstone', async () => {
      vi.mocked(getUniverse).mockResolvedValue({
        id: 'u1', name: 'Gone', deleted: true, deletedAt: '2026-05-22T03:00:00Z',
      });
      // If buildPushPayload still called findCollectionByUniverseId for a
      // tombstoned record, we'd see this mock invoked. Guard against the
      // bundle path firing for soft-deletes.
      vi.mocked(findCollectionByUniverseId).mockResolvedValue({
        id: 'col-1', name: 'Universe: U', description: '', coverKey: null,
        universeId: 'u1', seriesId: null, items: [],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T01:00:00Z',
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      expect(captured.kind).toBe('universe');
      expect(captured.linkedCollection).toBeUndefined();
      expect(captured.assetManifest).toEqual([]);
    });

    it('drops ephemeral child issues from both the bundled issues AND the asset manifest', async () => {
      // Regression: an earlier version filtered ephemeral issues out of
      // `sanitizedIssues` but still walked the unfiltered `childIssues`
      // when building the asset manifest, leaking the ephemeral issue's
      // image / video filenames onto the wire. The receiver would then
      // background-fetch those bytes — defeating the "local-only" intent
      // of ephemeral.
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(listIssuesForSeries).mockResolvedValue([
        // Live issue with a referenced image.
        {
          id: 'i1', seriesId: 'ser-1', number: 1,
          stages: { storyboards: { scenes: [{ imageJobId: 'job-live' }] } },
        },
        // Ephemeral issue — must NOT leak its image into the manifest.
        {
          id: 'i2', seriesId: 'ser-1', number: 2, ephemeral: true,
          stages: { storyboards: { scenes: [{ imageJobId: 'job-secret' }] } },
        },
      ]);
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1',
      });
      // Sanitized issues: only the live one.
      expect(captured.issues).toHaveLength(1);
      expect(captured.issues[0].id).toBe('i1');
      // Asset manifest entries (if any) must not reference the ephemeral
      // issue's assets. The manifest can be empty if buildAssetManifest
      // didn't find any concrete filenames in the live issue's stages
      // (which is the case here — imageJobId references aren't yet
      // resolved to filenames in Stage 2's manifest builder). The
      // critical invariant is that NOTHING from the ephemeral issue
      // appears.
      const manifestFilenames = (captured.assetManifest || []).map(a => a.filename);
      expect(manifestFilenames.some(f => /secret/i.test(f))).toBe(false);
    });

    it('ships an empty asset manifest for tombstone pushes (deleted universe)', async () => {
      // Tombstone pushes carry deleted=true + deletedAt so the receiver
      // can converge its delete. They must NOT also ship asset filenames
      // — the receiver would diff them as `missing`, schedule pulls, and
      // download bytes for a record it's about to orphan. Privacy-
      // sensitive (a record deleted to get its assets off-peer would
      // still leak the bytes via this path) and wasteful.
      vi.mocked(getUniverse).mockResolvedValue({
        id: 'u1', name: 'Doomed', deleted: true, deletedAt: '2026-01-01T00:00:00Z',
        // Force a referenced image filename that would otherwise hash into
        // the manifest. The buildAssetManifest path skips entries whose
        // file isn't readable, so a definitely-not-present filename is
        // the cleanest "would have been emitted if not for the deleted
        // gate" probe.
        worldOverview: { sceneImageFilename: 'sentinel-doomed-asset.png' },
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 'sub-tomb', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
      });
      // Tombstone arrives — sanitizer keeps deleted records on the wire.
      expect(captured.record.id).toBe('u1');
      expect(captured.record.deleted).toBe(true);
      // But the manifest is empty — no pull-trigger for the receiver.
      expect(captured.assetManifest).toEqual([]);
    });

    it('ships FableLoom tombstones without scene assets', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        {
          instanceId: 'peer-a', name: 'Peer A', host: null, address: '192.0.2.10', port: 5555,
          enabled: true, syncEnabled: true,
          directions: ['outbound', 'inbound'],
          syncCategories: { fableLoom: true },
        },
      ]);
      vi.mocked(getLoom).mockResolvedValue({
        id: 'loom-tomb',
        name: 'Example Loom',
        episodes: [{ scenes: [{ imageUrl: '/data/images/doomed.png', videoHistoryId: 'doomed' }] }],
        updatedAt: '2026-01-01T00:00:00Z',
        deleted: true,
        deletedAt: '2026-01-01T00:00:00Z',
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });

      await pushRecordToPeer({
        id: 'sub-loom', peerId: 'peer-a', recordKind: 'fableLoom', recordId: 'loom-tomb',
      });

      expect(captured.kind).toBe('fableLoom');
      expect(captured.record).toMatchObject({ id: 'loom-tomb', deleted: true });
      expect(captured.assetManifest).toEqual([]);
    });

    it('drops deleted child issues from the asset manifest input', async () => {
      // Deleted issues' tombstones must still ride along in `issues` (so
      // the receiver's delete cascade runs), but their asset filenames
      // must NOT appear in the manifest — the receiver would otherwise
      // pull bytes for issues it's about to orphan.
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(listIssuesForSeries).mockResolvedValue([
        // Live issue (no manifest leak — buildAssetManifest doesn't yet
        // resolve imageJobId → filename, that's a Stage 3 thing).
        { id: 'i1', seriesId: 'ser-1', number: 1 },
        // Deleted issue with a sentinel filename that would surface
        // through buildAssetManifest's directVideoFilenames path if it
        // were fed to the manifest builder.
        {
          id: 'i2', seriesId: 'ser-1', number: 2,
          deleted: true, deletedAt: '2026-01-01T00:00:00Z',
        },
      ]);
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 's', peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1',
      });
      // Both issues' tombstones/wire-records propagate.
      expect(captured.issues.map(i => i.id).sort()).toEqual(['i1', 'i2']);
      const deletedIssue = captured.issues.find(i => i.id === 'i2');
      expect(deletedIssue.deleted).toBe(true);
      // Manifest is empty (or at least carries nothing from i2). Stage-2
      // manifest builder doesn't emit filenames for these stage shapes,
      // so the manifest is empty in practice — but the invariant we're
      // guarding is that deleted issues NEVER contribute manifest entries
      // even when their stages happen to reference concrete assets.
      const manifestFilenames = (captured.assetManifest || []).map(a => a.filename);
      expect(manifestFilenames).toEqual([]);
    });

    // --- Standalone mediaCollection push payload --------------------------
    // A peer subscribed directly to a mediaCollection record (NOT via a
    // universe/series's linkedCollection bundle). The peer must have the
    // `mediaCollections` syncCategory enabled or the push gate short-circuits.
    const enableCollectionPeer = () => {
      vi.mocked(getPeers).mockResolvedValue([
        {
          instanceId: 'peer-a', name: 'Peer A', host: null, address: '10.0.0.2', port: 5555,
          enabled: true, syncEnabled: true,
          directions: ['outbound', 'inbound'],
          syncCategories: { universe: true, pipeline: true, mediaCollections: true },
        },
      ]);
    };

    it('emits BOTH image and video manifest entries for a live mediaCollection push', async () => {
      // Regression (Bug 2): video collection items store the bare videoId; the
      // on-disk file is `<id>.mp4`. The standalone push manifest builder must
      // append `.mp4` (same as the linkedCollection bundle path) or every
      // collection video is silently dropped and receivers never pull bytes.
      enableCollectionPeer();
      PATHS.videos = join(tmp, 'videos');
      await mkdir(PATHS.videos, { recursive: true });
      await writeFile(join(PATHS.images, 'pic.png'), Buffer.from('image bytes'));
      await writeFile(join(PATHS.videos, 'vid-xyz.mp4'), Buffer.from('mp4 bytes'));

      vi.mocked(getCollection).mockResolvedValue({
        id: 'col-9', name: 'Standalone', description: '', coverKey: null,
        universeId: null, seriesId: null,
        items: [
          { kind: 'image', ref: 'pic.png', addedAt: '2026-05-22T01:00:00Z' },
          { kind: 'video', ref: 'vid-xyz', addedAt: '2026-05-22T02:00:00Z' },
        ],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T02:00:00Z',
        deleted: false, deletedAt: null,
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 'sub-col', peerId: 'peer-a', recordKind: 'mediaCollection', recordId: 'col-9',
      });
      expect(captured.kind).toBe('mediaCollection');
      expect(captured.record.id).toBe('col-9');
      const imageEntries = captured.assetManifest.filter(a => a.kind === 'image');
      const videoEntries = captured.assetManifest.filter(a => a.kind === 'video');
      expect(imageEntries.map(a => a.filename)).toEqual(['pic.png']);
      // The .mp4 must have been appended to the bare videoId.
      expect(videoEntries.map(a => a.filename)).toEqual(['vid-xyz.mp4']);
    });

    it('ships an empty asset manifest for a tombstone mediaCollection push', async () => {
      enableCollectionPeer();
      PATHS.videos = join(tmp, 'videos');
      await mkdir(PATHS.videos, { recursive: true });
      // Real files on disk would otherwise hash into the manifest — the
      // deleted gate must skip the manifest builder entirely.
      await writeFile(join(PATHS.images, 'doomed.png'), Buffer.from('bytes'));
      await writeFile(join(PATHS.videos, 'vid-doom.mp4'), Buffer.from('bytes'));

      vi.mocked(getCollection).mockResolvedValue({
        id: 'col-tomb', name: 'Doomed', description: '', coverKey: null,
        universeId: null, seriesId: null,
        items: [
          { kind: 'image', ref: 'doomed.png', addedAt: '2026-05-22T01:00:00Z' },
          { kind: 'video', ref: 'vid-doom', addedAt: '2026-05-22T02:00:00Z' },
        ],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T03:00:00Z',
        deleted: true, deletedAt: '2026-05-22T03:00:00Z',
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 'sub-tomb', peerId: 'peer-a', recordKind: 'mediaCollection', recordId: 'col-tomb',
      });
      expect(captured.record.id).toBe('col-tomb');
      expect(captured.record.deleted).toBe(true);
      expect(captured.assetManifest).toEqual([]);
    });

    it('emits image and music asset manifests for music record pushes', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        {
          instanceId: 'peer-a', name: 'Peer A', host: null, address: '10.0.0.2', port: 5555,
          enabled: true, syncEnabled: true, directions: ['outbound', 'inbound'],
          syncCategories: { artists: true, albums: true, tracks: true },
        },
      ]);
      await writeFile(join(PATHS.images, 'artist.png'), Buffer.from('artist portrait'));
      await writeFile(join(PATHS.images, 'album.png'), Buffer.from('album cover'));
      await writeFile(join(PATHS.music, 'song.mp3'), Buffer.from('track audio'));
      vi.mocked(getArtist).mockResolvedValue({
        id: 'artist-1', name: 'Nova', portraitImageUrl: '/data/images/artist.png',
        updatedAt: '2026-06-01T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(getAlbum).mockResolvedValue({
        id: 'album-1', title: 'Debut', coverImageUrl: '/data/images/album.png',
        updatedAt: '2026-06-01T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(getTrack).mockResolvedValue({
        id: 'track-1', title: 'Intro', audioFilename: 'song.mp3',
        updatedAt: '2026-06-01T00:00:00Z', deleted: false, deletedAt: null,
      });
      const captured = [];
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured.push(JSON.parse(opts.body));
        return { ok: true, json: async () => ({ missingAssets: [] }) };
      });

      await pushRecordToPeer({ id: 'sub-artist', peerId: 'peer-a', recordKind: 'artist', recordId: 'artist-1' });
      await pushRecordToPeer({ id: 'sub-album', peerId: 'peer-a', recordKind: 'album', recordId: 'album-1' });
      await pushRecordToPeer({ id: 'sub-track', peerId: 'peer-a', recordKind: 'track', recordId: 'track-1' });

      expect(captured.map(p => p.kind)).toEqual(['artist', 'album', 'track']);
      expect(captured[0].assetManifest).toEqual([expect.objectContaining({ kind: 'image', filename: 'artist.png' })]);
      expect(captured[1].assetManifest).toEqual([expect.objectContaining({ kind: 'image', filename: 'album.png' })]);
      expect(captured[2].assetManifest).toEqual([expect.objectContaining({ kind: 'music', filename: 'song.mp3' })]);
    });

    // --- Music Video project media federation (#1772) ---
    it('bundles uploaded audio + rendered scene clips + reference-frame stills for a music video project push', async () => {
      // #1772: the project record federated but shipped an empty manifest, so a
      // selectively-subscribed peer never received the referenced media. Audio
      // rides as a `music` entry (PATHS.music); each scene's videoHistoryId
      // resolves through video-history.json to its `<filename>` under PATHS.videos;
      // each scene's referenceImageId (#1760 Phase 1b) rides as a sidecar-aware
      // `image` entry (a gallery basename under PATHS.images).
      enableMusicVideoPeer();
      PATHS.videos = join(tmp, 'videos');
      await mkdir(PATHS.videos, { recursive: true });
      await mkdir(PATHS.images, { recursive: true });
      await writeFile(join(PATHS.music, 'mv-song.mp3'), Buffer.from('audio bytes'));
      await writeFile(join(PATHS.videos, 'scene-one.mp4'), Buffer.from('clip one'));
      await writeFile(join(PATHS.videos, 'scene-two.webm'), Buffer.from('clip two'));
      await writeFile(join(PATHS.images, 'ref-x.png'), Buffer.from('frame bytes'));
      // video-history.json maps each videoHistoryId → its on-disk basename.
      await writeFile(join(tmp, 'video-history.json'), JSON.stringify([
        { id: 'vh-1', filename: 'scene-one.mp4' },
        { id: 'vh-2', filename: 'scene-two.webm' },
      ]));
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-1', name: 'My Video', mode: 'director', trackId: null,
        uploadedAudioFilename: 'mv-song.mp3',
        scenes: [
          { sceneId: 's-1', order: 0, videoHistoryId: 'vh-1', referenceImageId: 'ref-x.png' },
          { sceneId: 's-2', order: 1, videoHistoryId: 'vh-2', referenceImageId: null },
          { sceneId: 's-3', order: 2, videoHistoryId: null, referenceImageId: null },
        ],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({ missingAssets: [] }) };
      });
      await pushRecordToPeer({
        id: 'sub-mv', peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-1',
      });
      expect(captured.kind).toBe('musicVideoProject');
      expect(captured.record.id).toBe('mv-1');
      const byKind = (k) => captured.assetManifest.filter(a => a.kind === k).map(a => a.filename).sort();
      expect(byKind('music')).toEqual(['mv-song.mp3']);
      expect(byKind('video')).toEqual(['scene-one.mp4', 'scene-two.webm']);
      // referenceImageId (Phase 1b) now ships as a gallery `image` asset so the
      // peer renders the thumbnail instead of a dangling /data/images/ reference.
      expect(byKind('image')).toEqual(['ref-x.png']);
    });

    it('bundles the linked track record + its master audio for a track-linked project (#1858)', async () => {
      // The create-UI path stores trackId with uploadedAudioFilename: null. A
      // peer subscribed to musicVideoProjects ONLY (no Tracks category) needs
      // both the audio BYTES (manifest) and the track RECORD (linkedTrack) — the
      // receiver's resolveMasterAudioPath() looks the track up by id first.
      enableMusicVideoPeer();
      await writeFile(join(PATHS.music, 'linked.mp3'), Buffer.from('linked track audio'));
      vi.mocked(getTrack).mockResolvedValue({
        id: 'track-7', title: 'Anthem', audioFilename: 'linked.mp3',
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-3', name: 'Linked', mode: 'director', trackId: 'track-7',
        uploadedAudioFilename: null, scenes: [],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({ missingAssets: [] }) };
      });
      await pushRecordToPeer({
        id: 'sub-mv3', peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-3',
      });
      expect(captured.assetManifest.filter(a => a.kind === 'music').map(a => a.filename)).toEqual(['linked.mp3']);
      expect(captured.linkedTrack?.id).toBe('track-7');
      expect(captured.linkedTrack?.audioFilename).toBe('linked.mp3');
    });

    it('bundles a tombstone linkedTrack when the linked track is deleted (#1858)', async () => {
      // A track delete fans out to its linked projects; the project push must
      // carry the track tombstone so a Music-Videos-only peer converges instead
      // of keeping stale audio. No audio bytes ride for a deleted track.
      enableMusicVideoPeer();
      vi.mocked(getTrack).mockResolvedValue({
        id: 'track-8', title: 'Gone', audioFilename: 'gone.mp3',
        updatedAt: '2026-06-29T00:00:00Z', deleted: true, deletedAt: '2026-06-29T00:00:00Z',
      });
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-5', name: 'Linked-deleted', mode: 'director', trackId: 'track-8',
        uploadedAudioFilename: null, scenes: [],
        updatedAt: '2026-06-29T00:00:00Z', deleted: false, deletedAt: null,
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({ missingAssets: [] }) };
      });
      await pushRecordToPeer({
        id: 'sub-mv5', peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-5',
      });
      expect(captured.linkedTrack?.id).toBe('track-8');
      expect(captured.linkedTrack?.deleted).toBe(true);
      expect(captured.assetManifest.filter(a => a.kind === 'music')).toEqual([]);
    });

    it('stamps lastConfirmedTrackBundleAtMs on a confirmed push whose bundled track merge succeeded (#1922)', async () => {
      // tombstoneGc's `track` cutoff reads this bundle-specific floor off
      // musicVideoProject subscription rows (a peer with no `track`
      // subscription of its own would otherwise be invisible to track GC).
      enableMusicVideoPeer();
      vi.mocked(getTrack).mockResolvedValue({
        id: 'track-10', title: 'Bundled', audioFilename: 'linked.mp3',
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-10', name: 'Bundled', mode: 'director', trackId: 'track-10',
        uploadedAudioFilename: null, scenes: [],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      const before = Date.now();
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-10' },
        { adoptedFromReverse: true },
      );
      expect(sub.lastConfirmedTrackBundleAtMs).toBeNull();
      await pushRecordToPeer(sub);
      const refreshed = await findPeerSubscription('peer-a', 'musicVideoProject', 'mv-10');
      expect(refreshed.lastConfirmedTrackBundleAtMs).toBeGreaterThanOrEqual(before);
    });

    it('does NOT stamp lastConfirmedTrackBundleAtMs when the bundled track merge failed on the receiver (#1922)', async () => {
      // trackSyncPending means the receiver applied the project but the
      // bundled track merge threw — the peer never actually got the track,
      // so the bundle-specific floor must stay unset (the generic
      // lastConfirmedPushedAt still advances; that's a separate water-mark
      // for the project record itself, not the bundled track).
      enableMusicVideoPeer();
      vi.mocked(getTrack).mockResolvedValue({
        id: 'track-11', title: 'Pending', audioFilename: 'linked.mp3',
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-11', name: 'Pending', mode: 'director', trackId: 'track-11',
        uploadedAudioFilename: null, scenes: [],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(peerFetch).mockResolvedValue({
        ok: true,
        json: async () => ({ missingAssets: [], trackSyncPending: true }),
      });
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-11' },
        { adoptedFromReverse: true },
      );
      await pushRecordToPeer(sub);
      const refreshed = await findPeerSubscription('peer-a', 'musicVideoProject', 'mv-11');
      expect(refreshed.lastConfirmedTrackBundleAtMs).toBeNull();
      expect(refreshed.lastConfirmedPushedAt).toBeTruthy();
    });

    it('does NOT stamp lastConfirmedTrackBundleAtMs when the project still has a trackId but the sender omitted linkedTrack (#1922)', async () => {
      // Regression (codex review round 3): a project can still carry a
      // `trackId` while buildPushPayload's own getTrack() lookup transiently
      // returns null/throws, so `linkedTrack` is omitted from the payload
      // entirely. The receiver never sees a linkedTrack key, so it can't
      // report trackSyncPending either — `!trackSyncPending` alone would
      // wrongly look "confirmed". A track is still owed (trackId is set), so
      // the bundle floor must stay unstamped until a future push actually
      // ships the track.
      enableMusicVideoPeer();
      vi.mocked(getTrack).mockResolvedValue(null); // transient lookup failure
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-12', name: 'Lookup failed', mode: 'director', trackId: 'track-12',
        uploadedAudioFilename: null, scenes: [],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-12' },
        { adoptedFromReverse: true },
      );
      await pushRecordToPeer(sub);
      const refreshed = await findPeerSubscription('peer-a', 'musicVideoProject', 'mv-12');
      expect(refreshed.lastConfirmedTrackBundleAtMs).toBeNull();
      expect(refreshed.lastConfirmedPushedAt).toBeTruthy();
    });

    it('DOES stamp lastConfirmedTrackBundleAtMs when the project has no trackId at all (nothing owed)', async () => {
      enableMusicVideoPeer();
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-13', name: 'No track', mode: 'director', trackId: null,
        uploadedAudioFilename: 'upload.mp3', scenes: [],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      const before = Date.now();
      const sub = await subscribePeer(
        { peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-13' },
        { adoptedFromReverse: true },
      );
      await pushRecordToPeer(sub);
      const refreshed = await findPeerSubscription('peer-a', 'musicVideoProject', 'mv-13');
      expect(refreshed.lastConfirmedTrackBundleAtMs).toBeGreaterThanOrEqual(before);
    });

    it('omits linkedTrack when the project has no linked track', async () => {
      enableMusicVideoPeer();
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-4', name: 'Upload only', mode: 'director', trackId: null,
        uploadedAudioFilename: null, scenes: [],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({ missingAssets: [] }) };
      });
      await pushRecordToPeer({
        id: 'sub-mv4', peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-4',
      });
      expect(captured.kind).toBe('musicVideoProject');
      expect('linkedTrack' in captured).toBe(false);
    });

    it('falls back to the <id>.mp4 convention when a scene clip has no video-history row', async () => {
      // The metadata row may not have synced yet; the bare-id + .mp4 convention
      // (collectionVideoRefToFilename) still resolves the bytes. A wrong guess is
      // harmless — a missing file is skipped, never shipped.
      enableMusicVideoPeer();
      PATHS.videos = join(tmp, 'videos');
      await mkdir(PATHS.videos, { recursive: true });
      await writeFile(join(PATHS.videos, 'vh-orphan.mp4'), Buffer.from('orphan clip'));
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-2', name: 'No Rows', mode: 'director', trackId: null,
        uploadedAudioFilename: null,
        scenes: [{ sceneId: 's-1', order: 0, videoHistoryId: 'vh-orphan', referenceImageId: null }],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({ missingAssets: [] }) };
      });
      await pushRecordToPeer({
        id: 'sub-mv2', peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-2',
      });
      expect(captured.assetManifest).toEqual([expect.objectContaining({ kind: 'video', filename: 'vh-orphan.mp4' })]);
    });

    it('ships an empty asset manifest for a tombstone music video project push', async () => {
      enableMusicVideoPeer();
      PATHS.videos = join(tmp, 'videos');
      await mkdir(PATHS.videos, { recursive: true });
      // Real files on disk would otherwise hash in — the deleted gate must skip
      // the manifest builder entirely.
      await writeFile(join(PATHS.music, 'doomed.mp3'), Buffer.from('bytes'));
      await writeFile(join(PATHS.videos, 'doomed.mp4'), Buffer.from('bytes'));
      await writeFile(join(tmp, 'video-history.json'), JSON.stringify([{ id: 'vh-d', filename: 'doomed.mp4' }]));
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-tomb', name: 'Doomed', mode: 'director', trackId: null,
        uploadedAudioFilename: 'doomed.mp3',
        scenes: [{ sceneId: 's-1', order: 0, videoHistoryId: 'vh-d', referenceImageId: null }],
        updatedAt: '2026-06-28T03:00:00Z', deleted: true, deletedAt: '2026-06-28T03:00:00Z',
      });
      let captured = null;
      vi.mocked(peerFetch).mockImplementation(async (_url, opts) => {
        captured = JSON.parse(opts.body);
        return { ok: true, json: async () => ({}) };
      });
      await pushRecordToPeer({
        id: 'sub-mvt', peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-tomb',
      });
      expect(captured.record.id).toBe('mv-tomb');
      expect(captured.record.deleted).toBe(true);
      expect(captured.assetManifest).toEqual([]);
    });
  });

  describe('collectSubscriptionsForUpdate', () => {
    it('resolves a tail issue directly when finding its parent-series subscription', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'series-tail', title: 'Long series' });
      vi.mocked(getIssue).mockResolvedValue({ id: 'issue-1001', seriesId: 'series-tail' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'series', recordId: 'series-tail' });
      await __drainForTests();

      const subs = await collectSubscriptionsForUpdate('issue', 'issue-1001');

      expect(getIssue).toHaveBeenCalledWith('issue-1001', { includeDeleted: true });
      expect(listIssues).not.toHaveBeenCalled();
      expect(subs.some((sub) => sub.recordKind === 'series' && sub.recordId === 'series-tail')).toBe(true);
    });

    // Regression: mediaCollections.js emits emitRecordUpdated('mediaCollection',…)
    // on every edit/delete, but the push pipeline only acted on it if
    // collectSubscriptionsForUpdate returns the direct subs. Omitting the
    // mediaCollection branch made those emits inert (edits never auto-pushed).
    it('returns direct mediaCollection subscriptions (so edits/deletes auto-push)', async () => {
      vi.mocked(getPeers).mockResolvedValue([{
        instanceId: 'peer-a', name: 'Peer A', host: null, address: '10.0.0.2', port: 5555,
        enabled: true, syncEnabled: true, directions: ['outbound', 'inbound'],
        syncCategories: { universe: true, pipeline: true, mediaCollections: true },
      }]);
      vi.mocked(getCollection).mockResolvedValue({
        id: 'col-7', name: 'Standalone', description: '', coverKey: null,
        universeId: null, seriesId: null, items: [],
        createdAt: '2026-05-22T00:00:00Z', updatedAt: '2026-05-22T00:00:00Z',
        deleted: false, deletedAt: null,
      });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'mediaCollection', recordId: 'col-7' });
      await __drainForTests();

      const subs = await collectSubscriptionsForUpdate('mediaCollection', 'col-7');
      expect(subs.map((s) => s.recordId)).toContain('col-7');
      expect(subs.every((s) => s.recordKind === 'mediaCollection')).toBe(true);
    });

    it('fans a track update out to music-video projects that link it (#1858)', async () => {
      vi.mocked(getPeers).mockResolvedValue([{
        instanceId: 'peer-a', name: 'Peer A', host: null, address: '10.0.0.2', port: 5555,
        enabled: true, syncEnabled: true, directions: ['outbound', 'inbound'],
        syncCategories: { musicVideoProjects: true },
      }]);
      vi.mocked(getMusicVideoProject).mockResolvedValue({
        id: 'mv-link', name: 'Linked', mode: 'director', trackId: 'track-7',
        uploadedAudioFilename: null, scenes: [],
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      });
      vi.mocked(listMusicVideoProjects).mockResolvedValue([
        { id: 'mv-link', trackId: 'track-7' },
        { id: 'mv-other', trackId: 'track-99' },
      ]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ missingAssets: [] }) });
      await subscribePeer({ peerId: 'peer-a', recordKind: 'musicVideoProject', recordId: 'mv-link' });
      await __drainForTests();

      const subs = await collectSubscriptionsForUpdate('track', 'track-7');
      expect(subs.some((s) => s.recordKind === 'musicVideoProject' && s.recordId === 'mv-link')).toBe(true);
      // A project linking a DIFFERENT track is not fanned out.
      expect(subs.some((s) => s.recordId === 'mv-other')).toBe(false);
    });

    it('returns [] for a kind with no direct/parent subscription path', async () => {
      expect(await collectSubscriptionsForUpdate('image', 'whatever')).toEqual([]);
    });
  });

  describe('applyIncomingPush', () => {
    it('rejects payloads without a known kind', async () => {
      await expect(applyIncomingPush({ kind: 'mystery', record: { id: 'x' }, sourceInstanceId: 'peer-a' }))
        .rejects.toThrow(/unknown kind/);
    });

    it('rejects pushes from sourceInstanceId="unknown"', async () => {
      // The sender's instance id is the identity we hang the cursor on.
      // Accepting an "unknown" sourceInstanceId would poison the cursor
      // table with a synthetic key that never gets cleaned up.
      await expect(applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1' },
        sourceInstanceId: 'unknown',
      })).rejects.toThrow(/sourceInstanceId required/);
    });

    it('rejects payloads with a missing/malformed record', async () => {
      await expect(applyIncomingPush({
        kind: 'universe',
        record: 'not-an-object',
        sourceInstanceId: 'peer-a',
      })).rejects.toThrow(/object with a string id/);
    });

    it('dispatches universe pushes through mergeUniversesFromSync', async () => {
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', name: 'Foo', deleted: false, deletedAt: null },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeUniversesFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'u1' })],
        { source: { via: 'peer-push', peerId: 'peer-a' }, senderSchemaVersions: {} },
      );
    });

    it('dispatches FableLoom pushes through the story merge path', async () => {
      await applyIncomingPush({
        kind: 'fableLoom',
        record: { id: 'loom-1', name: 'Example Story', episodes: [] },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeLoomsFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'loom-1' })],
        { source: { via: 'peer-push', peerId: 'peer-a' }, senderSchemaVersions: {} },
      );
    });

    it('dispatches music pushes through their merge entry points', async () => {
      await applyIncomingPush({
        kind: 'artist',
        record: { id: 'artist-1', name: 'Nova', deleted: false, deletedAt: null },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      await applyIncomingPush({
        kind: 'album',
        record: { id: 'album-1', title: 'Debut', deleted: false, deletedAt: null },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      await applyIncomingPush({
        kind: 'track',
        record: { id: 'track-1', title: 'Intro', deleted: false, deletedAt: null },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });

      // The record-kind table (#6843) passes senderSchemaVersions to every
      // merger uniformly (harmless for these three, which ignore it) — assert
      // via objectContaining rather than pinning its full shape.
      expect(mergeArtistsFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'artist-1' })],
        expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-a' } }),
      );
      expect(mergeAlbumsFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'album-1' })],
        expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-a' } }),
      );
      expect(mergeTracksFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'track-1' })],
        expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-a' } }),
      );
    });

    it('routes a bundled linkedCollection through mergeMediaCollectionsFromSync', async () => {
      const linkedCollection = {
        id: 'col-1', name: 'Universe: U', universeId: 'u1', items: [
          { kind: 'image', ref: 'a.png', addedAt: '2026-05-22T01:00:00Z' },
        ],
      };
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', name: 'Foo', deleted: false, deletedAt: null },
        linkedCollection,
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeMediaCollectionsFromSync).toHaveBeenCalledWith(
        [linkedCollection],
        { source: { via: 'peer-push', peerId: 'peer-a' } },
      );
    });

    it('skips mergeMediaCollectionsFromSync when no linkedCollection is bundled', async () => {
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', deleted: false, deletedAt: null },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();
    });

    it('routes a bundled linkedTrack through mergeTracksFromSync on a music-video push (#1858)', async () => {
      const linkedTrack = {
        id: 'track-9', title: 'Anthem', audioFilename: 'linked.mp3',
        updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
      };
      await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-1', name: 'Linked', trackId: 'track-9', deleted: false, deletedAt: null },
        linkedTrack,
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      // The project's own merge goes through the record-kind table (#6843),
      // which passes senderSchemaVersions uniformly (harmless — ignored).
      // The linkedTrack merge is a hand-written hook that still calls with
      // exactly `{ source }`, unchanged.
      expect(mergeMusicVideoProjectsFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'mv-1' })],
        expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-a' } }),
      );
      expect(mergeTracksFromSync).toHaveBeenCalledWith(
        [linkedTrack],
        { source: { via: 'peer-push', peerId: 'peer-a' } },
      );
    });

    it('skips linkedTrack merge when none is bundled or the project is a tombstone', async () => {
      await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-2', trackId: 'track-9', deleted: false, deletedAt: null },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeTracksFromSync).not.toHaveBeenCalled();
      await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-3', trackId: 'track-9', deleted: true, deletedAt: '2026-06-29T00:00:00Z' },
        linkedTrack: { id: 'track-9', audioFilename: 'linked.mp3' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeTracksFromSync).not.toHaveBeenCalled();
    });

    it('refuses a linkedTrack whose id does not match the project trackId (#1858)', async () => {
      await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-5', trackId: 'track-A', deleted: false, deletedAt: null },
        linkedTrack: { id: 'track-SMUGGLED', audioFilename: 'x.mp3' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeTracksFromSync).not.toHaveBeenCalled();
    });

    it('routes a bundled manuscriptReview through mergeReviewFromSync on a series push', async () => {
      const manuscriptReview = {
        schemaVersion: 1,
        comments: [{ id: 'mrc-1', problem: 'pacing', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }],
      };
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', name: 'S', deleted: false, deletedAt: null },
        issues: [],
        manuscriptReview,
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeReviewFromSync).toHaveBeenCalledWith('ser-1', manuscriptReview);
    });

    it('skips mergeReviewFromSync when no manuscriptReview is bundled', async () => {
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', name: 'S', deleted: false, deletedAt: null },
        issues: [],
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeReviewFromSync).not.toHaveBeenCalled();
    });

    it('refuses to merge manuscriptReview when the incoming series record is a tombstone', async () => {
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', deleted: true, deletedAt: '2026-06-02T00:00:00Z', updatedAt: '2026-06-02T00:00:00Z' },
        issues: [],
        manuscriptReview: { schemaVersion: 1, comments: [{ id: 'mrc-1', problem: 'x', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }] },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeReviewFromSync).not.toHaveBeenCalled();
    });

    it('skips mergeReviewFromSync when the LOCAL series is ephemeral', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', ephemeral: true });
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', name: 'S', deleted: false, deletedAt: null },
        issues: [],
        manuscriptReview: { schemaVersion: 1, comments: [{ id: 'mrc-1', problem: 'x', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }] },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeReviewFromSync).not.toHaveBeenCalled();
    });

    it('routes a bundled reverseOutline through mergeOutlineFromSync on a series push', async () => {
      const reverseOutline = sampleOutline();
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', name: 'S', deleted: false, deletedAt: null },
        issues: [],
        reverseOutline,
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeOutlineFromSync).toHaveBeenCalledWith('ser-1', reverseOutline);
    });

    it('skips mergeOutlineFromSync when no reverseOutline is bundled', async () => {
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', name: 'S', deleted: false, deletedAt: null },
        issues: [],
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeOutlineFromSync).not.toHaveBeenCalled();
    });

    it('refuses to merge reverseOutline when the incoming series record is a tombstone', async () => {
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', deleted: true, deletedAt: '2026-06-02T00:00:00Z', updatedAt: '2026-06-02T00:00:00Z' },
        issues: [],
        reverseOutline: sampleOutline(),
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeOutlineFromSync).not.toHaveBeenCalled();
    });

    it('skips mergeOutlineFromSync when the LOCAL series is ephemeral', async () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', ephemeral: true });
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', name: 'S', deleted: false, deletedAt: null },
        issues: [],
        reverseOutline: sampleOutline(),
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeOutlineFromSync).not.toHaveBeenCalled();
    });

    it('skips mergeReviewFromSync without a retry flag when the series id is malformed (security: #8355)', async () => {
      // A series id containing `../` or not matching the required "ser-" prefix
      // must not trigger a merge that could write files outside the series directory.
      const manuscriptReview = { schemaVersion: 1, comments: [{ id: 'mrc-1', problem: 'x', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }] };
      const result = await applyIncomingPush({
        kind: 'series',
        record: { id: '../../../etc/passwd', name: 'S', deleted: false, deletedAt: null },
        issues: [],
        manuscriptReview,
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeReviewFromSync).not.toHaveBeenCalled();
      // An invalid id can never become valid — a pending flag would make the
      // sender withhold its hash and resend forever.
      expect(result.reviewSyncPending).toBeUndefined();
    });

    it('skips mergeOutlineFromSync without a retry flag when the series id is malformed (security: #8355)', async () => {
      // A series id not matching the required "ser-" prefix pattern must not
      // trigger a merge that could write files outside the series directory.
      const reverseOutline = sampleOutline();
      const result = await applyIncomingPush({
        kind: 'series',
        record: { id: 'evil/../../etc/passwd', name: 'S', deleted: false, deletedAt: null },
        issues: [],
        reverseOutline,
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeOutlineFromSync).not.toHaveBeenCalled();
      expect(result.outlineSyncPending).toBeUndefined();
    });

    it('refuses to merge linkedCollection when the incoming record is a tombstone', async () => {
      // Defense in depth: the sender's buildPushPayload already skips the
      // bundle for tombstones, but a buggy or malicious peer could send
      // one anyway. Receiving a collection during a delete propagation
      // would resurrect collection state for a record being torn down.
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', deleted: true, deletedAt: '2026-05-22T03:00:00Z' },
        linkedCollection: { id: 'col-1', name: 'Universe: U', items: [] },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();
    });

    it('refuses to merge linkedCollection when it is not a plain object (array, primitive)', async () => {
      // Wrapping a non-plain-object in `[...]` and passing to the merge
      // function would just produce a no-op (sanitizeCollection drops
      // non-objects), but skipping early keeps the trust posture clean
      // and the failure mode obvious.
      for (const bogus of [[], ['a'], 'string', 42, true]) {
        vi.mocked(mergeMediaCollectionsFromSync).mockClear();
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', deleted: false, deletedAt: null },
          linkedCollection: bogus,
          assetManifest: [],
          sourceInstanceId: 'peer-a',
        });
        expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();
      }
    });

    describe('bundled companion records are bound to the pushed record (#12427)', () => {
      const live = { deleted: false, deletedAt: null };
      const SOURCE = { source: { via: 'peer-push', peerId: 'peer-a' } };

      it.each([
        ['universe', 'universeId', 'u1'],
        ['series', 'seriesId', 'ser-1'],
      ])('merges a %s linkedCollection only when its %s is the pushed record', async (kind, field, id) => {
        const bound = { id: 'col-bound', name: 'Bound', [field]: id, items: [] };
        await applyIncomingPush({ kind, record: { id, ...live }, linkedCollection: bound, assetManifest: [], sourceInstanceId: 'peer-a' });
        expect(mergeMediaCollectionsFromSync).toHaveBeenCalledWith([bound], SOURCE);

        vi.mocked(mergeMediaCollectionsFromSync).mockClear();
        const foreign = { id: 'col-foreign', name: 'Other', [field]: 'someone-else', items: [] };
        const unlinked = { id: 'col-unlinked', name: 'Loose', items: [] };
        for (const linkedCollection of [foreign, unlinked]) {
          await applyIncomingPush({ kind, record: { id, ...live }, linkedCollection, assetManifest: [], sourceInstanceId: 'peer-a' });
        }
        expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();
      });

      it('refuses a linkedCollection that would re-parent a local collection linked elsewhere', async () => {
        vi.mocked(getCollection).mockResolvedValue({ id: 'col-victim', universeId: 'u-other', items: [] });
        await applyIncomingPush({
          kind: 'universe', record: { id: 'u1', ...live },
          linkedCollection: { id: 'col-victim', universeId: 'u1', items: [] },
          assetManifest: [], sourceInstanceId: 'peer-a',
        });
        expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();

        vi.mocked(getCollection).mockResolvedValue({ id: 'col-mine', universeId: 'u1', items: [] });
        await applyIncomingPush({
          kind: 'universe', record: { id: 'u1', ...live },
          linkedCollection: { id: 'col-mine', universeId: 'u1', items: [] },
          assetManifest: [], sourceInstanceId: 'peer-a',
        });
        expect(mergeMediaCollectionsFromSync).toHaveBeenCalledTimes(1);
      });

      it('refuses a linkedCollection whose local owner is another category or cannot be verified', async () => {
        const incoming = { id: 'col-x', universeId: 'shared-id', items: [] };
        const push = () => applyIncomingPush({
          kind: 'universe', record: { id: 'shared-id', ...live }, linkedCollection: incoming, assetManifest: [], sourceInstanceId: 'peer-a',
        });
        // Same id, different parent kind (a series parent named like this universe).
        vi.mocked(getCollection).mockResolvedValue({ id: 'col-x', seriesId: 'shared-id', items: [] });
        await push();
        // A storage failure is not "no local collection".
        vi.mocked(getCollection).mockRejectedValue(new Error('db unavailable'));
        await push();
        expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();
      });

      it('refuses a linkedCollection on a kind that has no collection parent', async () => {
        await applyIncomingPush({
          kind: 'musicVideoProject', record: { id: 'mv-1', ...live },
          linkedCollection: { id: 'col-1', universeId: 'mv-1', items: [] },
          assetManifest: [], sourceInstanceId: 'peer-a',
        });
        expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();
      });

      it('upserts only catalog refs for the pushed record and the ingredients those refs name', async () => {
        vi.mocked(getBackendName).mockReturnValue('postgres');
        const ref = (ingredientId, refId, refKind = 'universe') => ({ ingredientId, refKind, refId, role: 'canon-character', createdAt: '2026-01-02T00:00:00Z' });
        const ing = (id) => ({ id, type: 'character', name: id, updatedAt: '2026-01-02T00:00:00Z' });
        await applyIncomingPush({
          kind: 'universe', record: { id: 'u1', ...live }, assetManifest: [],
          catalogBundle: {
            ingredients: [ing('cat-mine'), ing('cat-other'), ing('cat-unreferenced')],
            refs: [ref('cat-mine', 'u1'), ref('cat-other', 'u-other'), ref('cat-mine', 'u1', 'series')],
          },
          sourceInstanceId: 'peer-a', portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS } },
        });
        expect(applyCatalogRemoteChanges).toHaveBeenCalledTimes(1);
        const arg = vi.mocked(applyCatalogRemoteChanges).mock.calls[0][0];
        expect(arg.refs).toEqual([ref('cat-mine', 'u1')]);
        expect(arg.ingredients).toEqual([ing('cat-mine')]);
      });

      it('applies nothing when no catalog ref belongs to the pushed record', async () => {
        vi.mocked(getBackendName).mockReturnValue('postgres');
        await applyIncomingPush({
          kind: 'universe', record: { id: 'u1', ...live }, assetManifest: [],
          catalogBundle: {
            ingredients: [{ id: 'cat-other', type: 'character', name: 'Other', updatedAt: '2026-01-02T00:00:00Z' }],
            refs: [{ ingredientId: 'cat-other', refKind: 'universe', refId: 'u-other', role: 'canon-character', createdAt: '2026-01-02T00:00:00Z' }],
          },
          sourceInstanceId: 'peer-a', portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS } },
        });
        expect(applyCatalogRemoteChanges).not.toHaveBeenCalled();
      });

      describe('bundled catalog ingredients owned by another record (#12466)', () => {
        const ing = (id) => ({ id, type: 'character', name: id, updatedAt: '2026-01-02T00:00:00Z' });
        const ref = (ingredientId) => ({ ingredientId, refKind: 'universe', refId: 'u1', role: 'canon-character', createdAt: '2026-01-02T00:00:00Z' });
        const pushBundle = (catalogBundle) => applyIncomingPush({
          kind: 'universe', record: { id: 'u1', ...live }, assetManifest: [], catalogBundle,
          sourceInstanceId: 'peer-a', portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS } },
        });
        const ownership = (existing, linked = []) => ({ existing: new Set(existing), linked: new Set(linked) });

        beforeEach(() => {
          vi.mocked(getBackendName).mockReturnValue('postgres');
        });

        it('drops an existing ingredient another record owns, with its forged ref, and merges the rest', async () => {
          vi.mocked(getLocalIngredientRefOwnership).mockResolvedValue(ownership(['cat-victim', 'cat-mine'], ['cat-mine']));
          await pushBundle({
            ingredients: [ing('cat-victim'), ing('cat-mine'), ing('cat-new')],
            refs: [ref('cat-victim'), ref('cat-mine'), ref('cat-new')],
          });
          expect(getLocalIngredientRefOwnership).toHaveBeenCalledWith(['cat-victim', 'cat-mine', 'cat-new'], 'universe', 'u1');
          const arg = vi.mocked(applyCatalogRemoteChanges).mock.calls[0][0];
          expect(arg.ingredients).toEqual([ing('cat-mine'), ing('cat-new')]);
          expect(arg.refs).toEqual([ref('cat-mine'), ref('cat-new')]);
        });

        it('applies nothing when the only ingredient belongs to another record, even with no bundled row', async () => {
          vi.mocked(getLocalIngredientRefOwnership).mockResolvedValue(ownership(['cat-victim']));
          await pushBundle({ ingredients: [], refs: [ref('cat-victim')] });
          expect(applyCatalogRemoteChanges).not.toHaveBeenCalled();
        });

        it('fails closed when the local ownership lookup throws', async () => {
          vi.mocked(getLocalIngredientRefOwnership).mockRejectedValue(new Error('db unavailable'));
          await pushBundle({ ingredients: [ing('cat-new')], refs: [ref('cat-new')] });
          expect(applyCatalogRemoteChanges).not.toHaveBeenCalled();
        });
      });

      it('never lets a music-video push overwrite an existing local track, linked by the project or not (#12466)', async () => {
        const linkedTrack = { id: 'track-victim', title: 'Hijacked', ...live };
        const push = (record) => applyIncomingPush({
          kind: 'musicVideoProject', record: { ...record, ...live }, linkedTrack, assetManifest: [], sourceInstanceId: 'peer-a',
        });
        vi.mocked(getTrack).mockResolvedValue({ id: 'track-victim', title: 'Mine' });

        // First push points the project at the victim track; the second finds
        // that link already stored locally — neither may overwrite the track.
        await push({ id: 'mv-new', trackId: 'track-victim' });
        vi.mocked(getMusicVideoProject).mockResolvedValue({ id: 'mv-new', trackId: 'track-victim' });
        await push({ id: 'mv-new', trackId: 'track-victim' });
        expect(mergeTracksFromSync).not.toHaveBeenCalled();
      });

      it('merges a linkedTrack that does not exist locally yet', async () => {
        const linkedTrack = { id: 'track-new', title: 'Fresh', ...live };
        await applyIncomingPush({
          kind: 'musicVideoProject', record: { id: 'mv-fresh', trackId: 'track-new', ...live },
          linkedTrack, assetManifest: [], sourceInstanceId: 'peer-a',
        });
        expect(mergeTracksFromSync).toHaveBeenCalledWith([linkedTrack], SOURCE);
      });

      it('withholds the sender hash when the local track lookup fails, without failing the push', async () => {
        vi.mocked(getTrack).mockRejectedValue(new Error('db unavailable'));
        const result = await applyIncomingPush({
          kind: 'musicVideoProject', record: { id: 'mv-err', trackId: 'track-new', ...live },
          linkedTrack: { id: 'track-new', title: 'Fresh', ...live }, assetManifest: [], sourceInstanceId: 'peer-a',
        });
        expect(mergeTracksFromSync).not.toHaveBeenCalled();
        expect(result.trackSyncPending).toBe(true);
      });
    });

    it('dispatches series pushes through mergeSeriesFromSync AND mergeIssuesFromSync for bundled issues', async () => {
      await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', deleted: false, deletedAt: null },
        issues: [{ id: 'i1', seriesId: 'ser-1', deleted: false, deletedAt: null }],
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      // Goes through the record-kind table (#6843), which passes
      // senderSchemaVersions uniformly (harmless for series — ignored).
      expect(mergeSeriesFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'ser-1' })],
        expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-a' } }),
      );
      expect(mergeIssuesFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'i1' })],
        { source: { via: 'peer-push', peerId: 'peer-a' }, senderSchemaVersions: {} },
      );
    });

    it('never pulls assets for an asset-less kind, even if the payload invents image references', async () => {
      await writeFile(join(PATHS.images, 'protected.png'), 'local image');
      const result = await applyIncomingPush({
        kind: 'commissionFeedback',
        record: { id: 'feedback-1', imageRefs: ['protected.png'] },
        assetManifest: [{ filename: 'protected.png', kind: 'image', sha256: 'a'.repeat(64) }],
        sourceInstanceId: 'peer-a',
      });
      expect(result.missingAssets).toEqual([]);
      expect(await readFile(join(PATHS.images, 'protected.png'), 'utf8')).toBe('local image');
    });

    it.each([false, true])('scopes a manifest to its record and replaces existing bytes only on an applied merge (%s)', async (applied) => {
      await writeFile(join(PATHS.images, 'existing.png'), 'local image');
      await writeFile(join(PATHS.images, 'existing.metadata.json'), '{"prompt":"local prompt"}');
      vi.mocked(mergeUniversesFromSync).mockResolvedValue({ applied, count: applied ? 1 : 0 });
      const manifest = ['missing.png', 'existing.png', 'unrelated.png'].map((filename) => ({
        filename, kind: 'image', sha256: 'a'.repeat(64), sidecarSha256: 'b'.repeat(64),
      }));
      const result = await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', imageRefs: ['missing.png', 'existing.png'] },
        assetManifest: manifest,
        sourceInstanceId: 'peer-a',
      });
      expect(result.missingAssets).toEqual(applied ? manifest.slice(0, 2) : manifest.slice(0, 1));
      expect(await readFile(join(PATHS.images, 'existing.png'), 'utf8')).toBe('local image');
      if (!applied) {
        expect(await readFile(join(PATHS.images, 'existing.metadata.json'), 'utf8')).toBe('{"prompt":"local prompt"}');
      }
    });

    it('admits only referenced series, child-issue and linked-collection assets', async () => {
      const manifest = [
        { kind: 'image', filename: 'series.png' },
        { kind: 'image', filename: 'issue.png' },
        { kind: 'video', filename: 'collection-clip.mp4' },
        { kind: 'image', filename: 'private.png' },
        { kind: 'image', filename: 'deleted.png' },
        { kind: 'image', filename: 'unrelated.png' },
      ];
      const result = await applyIncomingPush({
        kind: 'series', record: { id: 'ser-1', imageRefs: ['series.png'] },
        issues: [
          { id: 'issue-1', seriesId: 'ser-1', imageRefs: ['issue.png'] },
          { id: 'issue-2', seriesId: 'ser-1', ephemeral: true, imageRefs: ['private.png'] },
          { id: 'issue-3', seriesId: 'ser-1', deleted: true, imageRefs: ['deleted.png'] },
        ],
        linkedCollection: { id: 'collection-1', seriesId: 'ser-1', items: [{ kind: 'video', ref: 'collection-clip' }] },
        assetManifest: manifest, sourceInstanceId: 'peer-a',
      });
      expect(result.missingAssets).toEqual(manifest.slice(0, 3));
    });

    it('admits track render history, deck and storyboard images but drops other asset kinds', async () => {
      for (const [kind, record, own] of [
        ['track', { id: 'track-1', audioFilename: 'active.mp3', renders: [{ audioFilename: 'older.mp3' }] },
          [{ kind: 'music', filename: 'active.mp3' }, { kind: 'music', filename: 'older.mp3' }]],
        ['deck', { id: 'deck-1', cards: [{ primaryImageRef: 'card.png', imageRefs: ['render.png'] }], samples: [{ imageRef: 'style.png' }] },
          ['card.png', 'render.png', 'style.png'].map((filename) => ({ kind: 'image', filename }))],
        ['storyboard', { id: 'sb-1', beats: [{ panels: [{ takes: [{ image: 'panel.png' }, { sketchKey: 'sketch:abc' }] }] }] },
          [{ kind: 'image', filename: 'panel.png' }]],
      ]) {
        const result = await applyIncomingPush({ kind, record, sourceInstanceId: 'peer-a',
          assetManifest: [...own, { kind: 'audio', filename: 'unrelated.mp3' }] });
        expect(result.missingAssets).toEqual(own);
      }
    });

    it('reports missing assets in the response', async () => {
      const result = await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', imageRefs: ['absent.png'] },
        assetManifest: [{ filename: 'absent.png', kind: 'image', sha256: 'a'.repeat(64) }],
        sourceInstanceId: 'peer-a',
      });
      expect(result.missingAssets).toHaveLength(1);
    });

    it('never schedules a navigable peer asset from an incoming push', async () => {
      const result = await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', imageRefs: ['peer.html', 'peer.svg', 'peer.png'], videoPath: 'clip.ogv' },
        assetManifest: [
          { filename: 'peer.html', kind: 'image', sha256: 'a'.repeat(64) },
          { filename: 'peer.svg', kind: 'image', sha256: 'b'.repeat(64) },
          { filename: 'peer.png', kind: 'image', sha256: 'c'.repeat(64) },
            { filename: 'clip.ogv', kind: 'video', sha256: 'e'.repeat(64) },
        ],
        sourceInstanceId: 'peer-a',
      });
      expect(result.missingAssets).toEqual([
        { filename: 'peer.png', kind: 'image', sha256: 'c'.repeat(64) },
        { filename: 'clip.ogv', kind: 'video', sha256: 'e'.repeat(64) },
      ]);
      expect(await readFile(join(PATHS.images, 'peer.html')).catch(() => null)).toBeNull();
      expect(await readFile(join(PATHS.images, 'peer.svg')).catch(() => null)).toBeNull();
    });

    it('returns ackedDeletesUpTo for the sender (does NOT advance the local cursor on receive)', async () => {
      // Cursors track "what peer X has acked of OUR local deletions" so
      // tombstoneGc can prune our local tombstones once every subscribed
      // peer has confirmed receipt. Advancing the cursor for sourceInstanceId
      // on receive would mis-credit the sender's tombstones as our own pushed-
      // and-acked ones, letting GC prune local tombstones the sender never
      // saw — and resurrecting them on the sender's next push.
      const result = await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', deleted: true, deletedAt: '2026-01-01T00:00:00Z' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(result.ackedDeletesUpTo).toBe(Date.parse('2026-01-01T00:00:00Z'));
      const cursors = await listCursors();
      expect(cursors['peer-a']).toBeUndefined();
    });

    it('returns the MAX deletedAt across record + bundled issues so the sender can ack all in one round-trip', async () => {
      // Regression: if only `record.deletedAt` is returned, a series push
      // bundling multiple tombstoned issues would only ack the series'
      // own deletion time — newer issue tombstones in the same push would
      // never be acknowledged until a separate push lands.
      const result = await applyIncomingPush({
        kind: 'series',
        record: { id: 'ser-1', deleted: true, deletedAt: '2026-01-01T00:00:00Z' },
        issues: [
          { id: 'i1', deleted: true, deletedAt: '2026-03-01T00:00:00Z' },
          { id: 'i2', deleted: false },
        ],
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(result.ackedDeletesUpTo).toBe(Date.parse('2026-03-01T00:00:00Z'));
    });

    it('folds a bundled linkedTrack tombstone into ackedDeletesUpTo (#1922)', async () => {
      // Regression: a musicVideoProjects-only peer has no independent `track`
      // subscription, so the bundled linkedTrack tombstone (#1858) was the
      // ONLY way it could ever ack a track delete. Before this fix,
      // computeAckedDeletesFromPayload ignored `linkedTrack` entirely, so the
      // sender's track-tombstone GC cohort never waited on this peer at all.
      const result = await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-12', trackId: 'track-12', deleted: false, deletedAt: null },
        linkedTrack: { id: 'track-12', deleted: true, deletedAt: '2026-04-01T00:00:00Z' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(result.ackedDeletesUpTo).toBe(Date.parse('2026-04-01T00:00:00Z'));
    });

    it('does NOT fold a LIVE bundled linkedTrack into ackedDeletesUpTo (only tombstones count)', async () => {
      const result = await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-13', trackId: 'track-13', deleted: false, deletedAt: null },
        linkedTrack: { id: 'track-13', deleted: false, deletedAt: null },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(result.ackedDeletesUpTo).toBe(0);
    });

    it('does NOT fold a mismatched-id linkedTrack tombstone into ackedDeletesUpTo (merge gate refused it, never applied)', async () => {
      // Regression (codex review round 3 on #1922): the merge gate refuses a
      // linkedTrack whose id doesn't match the project's trackId (anti-
      // smuggling guard), so mergeTracksFromSync never runs. Folding its
      // deletedAt into ackedDeletesUpTo anyway would tell the sender "applied"
      // for a tombstone this receiver never actually merged.
      const result = await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-14', trackId: 'track-A', deleted: false, deletedAt: null },
        linkedTrack: { id: 'track-SMUGGLED', deleted: true, deletedAt: '2026-04-02T00:00:00Z' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeTracksFromSync).not.toHaveBeenCalled();
      expect(result.ackedDeletesUpTo).toBe(0);
    });

    it('does NOT fold a bundled linkedTrack tombstone into ackedDeletesUpTo when its merge fails (trackSyncPending)', async () => {
      // Regression (codex review round 3 on #1922): a thrown merge means the
      // receiver did NOT actually apply the tombstone — acking it anyway would
      // let the sender's cursor advance past a deletion that still needs a
      // retry (the exact failure mode #1922 closes for the success path).
      vi.mocked(mergeTracksFromSync).mockRejectedValueOnce(new Error('disk full'));
      const result = await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-15', trackId: 'track-15', deleted: false, deletedAt: null },
        linkedTrack: { id: 'track-15', deleted: true, deletedAt: '2026-04-03T00:00:00Z' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(result.trackSyncPending).toBe(true);
      expect(result.ackedDeletesUpTo).toBe(0);
    });

    it('folds a bundled linkedTrack tombstone into ackedDeletesUpTo even when the local record LOOKS ephemeral-shaped (#6843: musicVideoProject has no ephemeral concept)', async () => {
      // Historical: applyIncomingPush used to probe getMusicVideoProject for a
      // local `ephemeral` flag (added by #1858) and skip the bundled track
      // merge when set. The store never actually sets that flag on this kind
      // (musicVideo/projectsLogic.js: "no ephemeral flag") — the check always
      // evaluated false in production, and classifyLocalRecord already
      // documented the kind as having no ephemeral concept. #6843 collapsed
      // the dead check via the record-kind table's `hasEphemeral: false` and
      // this asserts the fix: an `ephemeral: true`-shaped local record (which
      // could previously only be reached by a mock like this one, never by
      // real data) does NOT suppress the linkedTrack merge or its ack.
      vi.mocked(getMusicVideoProject).mockResolvedValueOnce({ id: 'mv-16', ephemeral: true });
      const result = await applyIncomingPush({
        kind: 'musicVideoProject',
        record: { id: 'mv-16', trackId: 'track-16', deleted: false, deletedAt: null },
        linkedTrack: { id: 'track-16', deleted: true, deletedAt: '2026-04-04T00:00:00Z' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(mergeTracksFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'track-16' })],
        { source: { via: 'peer-push', peerId: 'peer-a' } },
      );
      expect(result.ackedDeletesUpTo).toBe(Date.parse('2026-04-04T00:00:00Z'));
    });

    it('auto-creates a reverse subscription back to the sender', async () => {
      // The merge path actually landed the record locally, so the
      // classifyLocalRecord('universe', 'u1') call inside
      // maybeCreateReverseSubscription will find a syncable record on
      // disk. Mock the lookup explicitly — the tri-state gate refuses
      // 'missing' to avoid orphan reverse-subs (e.g. for records the
      // sanitizer dropped at the merge boundary).
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      const sub = await findPeerSubscription('peer-a', 'universe', 'u1');
      expect(sub).not.toBeNull();
      expect(sub.adoptedFromReverse).toBe(true);
    });

    it('does NOT create a reverse subscription when the local record is missing (merge dropped it)', async () => {
      // Regression: classifyLocalRecord must hard-stop on 'missing'.
      // Previously the gate only checked `ephemeral === true`, so a
      // record the sanitizer dropped during merge (missing name, schema
      // mismatch, etc.) would still get an orphan reverse-sub that fires
      // pushes against a nonexistent local record forever.
      vi.mocked(getUniverse).mockResolvedValue(undefined);
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u-dropped' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      const sub = await findPeerSubscription('peer-a', 'universe', 'u-dropped');
      expect(sub).toBeNull();
    });

    it('does NOT create a reverse subscription when the sender peer is configured as inbound-only', async () => {
      // peer-b-inbound-only has directions: ['inbound']. The user explicitly
      // told this instance not to push back to them — auto-creating a
      // reverse subscription would override that intent.
      const result = await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1' },
        assetManifest: [],
        sourceInstanceId: 'peer-b-inbound-only',
      });
      expect(result.reverseSubscriptionCreated).toBe(false);
      const sub = await findPeerSubscription('peer-b-inbound-only', 'universe', 'u1');
      expect(sub).toBeNull();
    });

    it('does NOT create a reverse subscription when the local record is ephemeral', async () => {
      // The user marked u1 local-only; the merge already refused the
      // inbound edit (see mergeUniversesFromSync local-ephemeral guard).
      // Creating a reverse sub here would accumulate an orphan row in
      // peer_subscriptions.json that burns asset-manifest sha-passes on
      // every future edit and never sends bytes.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', ephemeral: true });
      const result = await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(result.reverseSubscriptionCreated).toBe(false);
      expect(await findPeerSubscription('peer-a', 'universe', 'u1')).toBeNull();
    });

    it('does NOT duplicate a reverse subscription on subsequent pushes', async () => {
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', updatedAt: '2026-01-02T00:00:00Z' },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      const all = await listPeerSubscriptions({ peerId: 'peer-a' });
      expect(all).toHaveLength(1);
    });

    it('emits peerSyncEvents "subscription-created" ONLY when a reverse sub is genuinely created', async () => {
      // The Instances UI listens on the relayed `peerSync:subscription:created`
      // socket event to re-fetch a peer's subs without a manual reload. It must
      // fire exactly once — on the first push that creates the reverse sub —
      // and NOT on every subsequent push to the same (already-subscribed) record.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      const events = [];
      const handler = (payload) => events.push(payload);
      peerSyncEvents.on('subscription-created', handler);
      try {
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
        });
        // Second push — sub already exists, so no new event.
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', updatedAt: '2026-01-02T00:00:00Z' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
        });
      } finally {
        peerSyncEvents.off('subscription-created', handler);
      }
      expect(events).toHaveLength(1);
      expect(events[0]).toMatchObject({
        peerId: 'peer-a',
        recordKind: 'universe',
        recordId: 'u1',
      });
      expect(typeof events[0].subId).toBe('string');
    });

    it('does NOT emit "subscription-created" when the reverse-sub gate refuses (inbound-only peer)', async () => {
      // No reverse sub is created for an inbound-only peer, so the UI signal
      // must stay silent — emitting on every push would trigger needless
      // peerSubs refetches across all cards.
      vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
      const events = [];
      const handler = (payload) => events.push(payload);
      peerSyncEvents.on('subscription-created', handler);
      try {
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1' },
          assetManifest: [],
          sourceInstanceId: 'peer-b-inbound-only',
        });
      } finally {
        peerSyncEvents.off('subscription-created', handler);
      }
      expect(events).toHaveLength(0);
    });
  });

  // -------------------------------------------------------------------------
  // CATALOG BUNDLE — universe push carries referenced catalog ingredients +
  // refs (catalog-bundled-universe-push). Assembly is gated on Postgres +
  // non-tombstone + non-empty; the receiver applies via catalogSync.
  // -------------------------------------------------------------------------
  describe('catalog bundle (universe push)', () => {
    const liveUniverse = { id: 'u1', name: 'Foo', updatedAt: '2026-01-01T00:00:00Z', deleted: false, deletedAt: null };

    it('bundles catalog ingredients + refs into a live universe push (Postgres)', async () => {
      vi.mocked(getBackendName).mockReturnValue('postgres');
      vi.mocked(getUniverse).mockResolvedValue(liveUniverse);
      vi.mocked(getCatalogBundleForRef).mockResolvedValue({
        ingredients: [{ id: 'cat-chr-1', type: 'character', name: 'Hero', updatedAt: '2026-01-02T00:00:00Z' }],
        refs: [{ ingredientId: 'cat-chr-1', refKind: 'universe', refId: 'u1', role: 'canon-character', createdAt: '2026-01-02T00:00:00Z' }],
      });

      const payload = await getRecordPayloadForPeer('universe', 'u1');

      expect(getCatalogBundleForRef).toHaveBeenCalledWith('universe', 'u1');
      expect(payload.catalogBundle).toBeDefined();
      expect(payload.catalogBundle.ingredients).toHaveLength(1);
      expect(payload.catalogBundle.ingredients[0].id).toBe('cat-chr-1');
      expect(payload.catalogBundle.refs[0].refId).toBe('u1');
    });

    it('omits the bundle on a non-Postgres install (nothing to bundle)', async () => {
      vi.mocked(getBackendName).mockReturnValue('file');
      vi.mocked(getUniverse).mockResolvedValue(liveUniverse);

      const payload = await getRecordPayloadForPeer('universe', 'u1');

      expect(getCatalogBundleForRef).not.toHaveBeenCalled();
      expect(payload.catalogBundle).toBeUndefined();
    });

    it('omits the bundle on a tombstone (deleted) universe push', async () => {
      vi.mocked(getBackendName).mockReturnValue('postgres');
      vi.mocked(getUniverse).mockResolvedValue({ ...liveUniverse, deleted: true, deletedAt: '2026-03-01T00:00:00Z' });

      const payload = await getRecordPayloadForPeer('universe', 'u1');

      expect(getCatalogBundleForRef).not.toHaveBeenCalled();
      expect(payload.catalogBundle).toBeUndefined();
    });

    it('omits the bundle key when the universe has no catalog rows', async () => {
      vi.mocked(getBackendName).mockReturnValue('postgres');
      vi.mocked(getUniverse).mockResolvedValue(liveUniverse);
      vi.mocked(getCatalogBundleForRef).mockResolvedValue({ ingredients: [], refs: [] });

      const payload = await getRecordPayloadForPeer('universe', 'u1');

      expect(payload.catalogBundle).toBeUndefined();
    });

    it('does NOT bundle catalog rows on a series push (only universe)', async () => {
      vi.mocked(getBackendName).mockReturnValue('postgres');
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Ser', updatedAt: '2026-01-01T00:00:00Z', deleted: false, deletedAt: null });
      vi.mocked(listIssues).mockResolvedValue([]);

      const payload = await getRecordPayloadForPeer('series', 'ser-1');

      expect(getCatalogBundleForRef).not.toHaveBeenCalled();
      expect(payload.catalogBundle).toBeUndefined();
    });

    it('receiver applies a bundled catalog payload via catalogSync', async () => {
      vi.mocked(getBackendName).mockReturnValue('postgres');
      const catalogBundle = {
        ingredients: [{ id: 'cat-chr-1', type: 'character', name: 'Hero', updatedAt: '2026-01-02T00:00:00Z' }],
        refs: [{ ingredientId: 'cat-chr-1', refKind: 'universe', refId: 'u1', role: 'canon-character', createdAt: '2026-01-02T00:00:00Z' }],
      };
      const portosMeta = { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS } };

      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', name: 'Foo', deleted: false, deletedAt: null },
        assetManifest: [],
        catalogBundle,
        sourceInstanceId: 'peer-a',
        portosMeta,
      });

      expect(applyCatalogRemoteChanges).toHaveBeenCalledTimes(1);
      const arg = vi.mocked(applyCatalogRemoteChanges).mock.calls[0][0];
      expect(arg.ingredients).toEqual(catalogBundle.ingredients);
      expect(arg.refs).toEqual(catalogBundle.refs);
      // portosMeta forwarded so applyRemoteChanges can run its own gate.
      expect(arg.portosMeta).toEqual(portosMeta);
    });

    it('receiver skips the bundle on a tombstone universe push', async () => {
      vi.mocked(getBackendName).mockReturnValue('postgres');
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', name: 'Foo', deleted: true, deletedAt: '2026-03-01T00:00:00Z' },
        assetManifest: [],
        catalogBundle: { ingredients: [{ id: 'cat-chr-1', type: 'character', name: 'Hero', updatedAt: '2026-01-02T00:00:00Z' }], refs: [] },
        sourceInstanceId: 'peer-a',
        portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS } },
      });

      expect(applyCatalogRemoteChanges).not.toHaveBeenCalled();
    });

    it('receiver rejects a universe push whose bundle ingredient is schema-ahead on catalog', async () => {
      vi.mocked(getBackendName).mockReturnValue('postgres');
      await expect(applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', name: 'Foo', deleted: false, deletedAt: null },
        assetManifest: [],
        catalogBundle: { ingredients: [{ id: 'cat-chr-1', type: 'character', name: 'Hero', updatedAt: '2026-01-02T00:00:00Z' }], refs: [] },
        sourceInstanceId: 'peer-a',
        portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS, catalog: PORTOS_SCHEMA_VERSIONS.catalog + 1 }, portosVersion: '99.0.0' },
      })).rejects.toThrow(/schema is ahead/);
      // Gated before merge — bundle apply never runs.
      expect(applyCatalogRemoteChanges).not.toHaveBeenCalled();
    });

    it.each([PORTOS_SCHEMA_VERSIONS.catalog - 1, undefined])(
      'rejects catalog version %s before merging the owning universe or its bundle', async (catalog) => {
        vi.mocked(getBackendName).mockReturnValue('postgres');
        vi.mocked(mergeUniversesFromSync).mockClear();
        const schemaVersions = { ...PORTOS_SCHEMA_VERSIONS, catalog };
        await expect(applyIncomingPush({
          kind: 'universe', record: liveUniverse, assetManifest: [], sourceInstanceId: 'peer-a',
          catalogBundle: { ingredients: [{ id: 'example-object', type: 'object', payload: { name: 'Edited on peer' } }] },
          portosMeta: { schemaVersions },
        })).rejects.toMatchObject({
          code: 'PEER_SYNC_SCHEMA_VERSION_AHEAD',
          details: { ahead: [], behind: [{ category: 'catalog', senderV: catalog ?? 0, receiverV: PORTOS_SCHEMA_VERSIONS.catalog }] },
        });
        expect(mergeUniversesFromSync).not.toHaveBeenCalled();
        expect(applyCatalogRemoteChanges).not.toHaveBeenCalled();
      },
    );

    // #3926: the gate used to key on `ingredients` alone, so any bundle whose
    // live rows sat in another block (`refs` today; `relations`/`tags`/`media`/
    // `catalogTypes` from catalog v4–v8) slipped past it and got applied on a
    // receiver that can't interpret the newer shape.
    it.each([
      ['relations', { ingredients: [], refs: [], relations: [{ fromIngredientId: 'cat-chr-1', toIngredientId: 'cat-chr-2', kind: 'ally-of', updatedAt: '2026-01-02T00:00:00Z' }] }],
      ['tags', { ingredients: [], refs: [], tags: [{ id: 'cat-tag-1', label: 'Protagonists', parentId: null, updatedAt: '2026-01-02T00:00:00Z' }] }],
      ['media', { ingredients: [], media: [{ ingredientId: 'cat-chr-1', mediaKey: 'img-1', mediaType: 'image', updatedAt: '2026-01-02T00:00:00Z' }] }],
      ['refs', { ingredients: [], refs: [{ ingredientId: 'cat-chr-1', refKind: 'universe', refId: 'u1', role: 'canon-character', createdAt: '2026-01-02T00:00:00Z' }] }],
      // A block this receiver's catalog version doesn't know about yet must
      // gate too — that is precisely the payload the gate protects against.
      ['an unknown future block', { ingredients: [], refs: [], someFutureBlock: [{ id: 'x1', updatedAt: '2026-01-02T00:00:00Z' }] }],
    ])('receiver rejects a bundle whose only live rows are %s when the sender is schema-ahead on catalog', async (_label, catalogBundle) => {
      vi.mocked(getBackendName).mockReturnValue('postgres');
      const rejection = await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', name: 'Foo', deleted: false, deletedAt: null },
        assetManifest: [],
        catalogBundle,
        sourceInstanceId: 'peer-a',
        portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS, catalog: PORTOS_SCHEMA_VERSIONS.catalog + 1 }, portosVersion: '99.0.0' },
      }).catch((err) => err);
      expect(rejection.code).toBe('PEER_SYNC_SCHEMA_VERSION_AHEAD');
      expect(rejection.details.ahead).toEqual([
        { category: 'catalog', senderV: PORTOS_SCHEMA_VERSIONS.catalog + 1, receiverV: PORTOS_SCHEMA_VERSIONS.catalog },
      ]);
      expect(applyCatalogRemoteChanges).not.toHaveBeenCalled();
    });

    it('receiver applies an ingredient-free bundle when the sender is NOT schema-ahead', async () => {
      // The widened gate must not turn into a blanket rejection: an
      // equal-version sender's relations-only bundle still applies.
      vi.mocked(getBackendName).mockReturnValue('postgres');
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', name: 'Foo', deleted: false, deletedAt: null },
        assetManifest: [],
        catalogBundle: {
          ingredients: [],
          refs: [{ ingredientId: 'cat-chr-1', refKind: 'universe', refId: 'u1', role: 'canon-character', createdAt: '2026-01-02T00:00:00Z' }],
          relations: [{ fromIngredientId: 'cat-chr-1', toIngredientId: 'cat-chr-2', kind: 'ally-of', updatedAt: '2026-01-02T00:00:00Z' }],
        },
        sourceInstanceId: 'peer-a',
        portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS } },
      });
      expect(applyCatalogRemoteChanges).toHaveBeenCalledTimes(1);
    });

    it.each([PORTOS_SCHEMA_VERSIONS.catalog + 1, PORTOS_SCHEMA_VERSIONS.catalog - 1, undefined])('receiver does NOT gate a tombstone-only bundle at catalog version %s', async (catalog) => {
      // Tombstone rows are id+deleted+deletedAt+updatedAt at every catalog
      // version, so they stay exempt — otherwise federated catalog deletes
      // would stall the moment one peer upgrades ahead.
      vi.mocked(getBackendName).mockReturnValue('postgres');
      await applyIncomingPush({
        kind: 'universe',
        record: { id: 'u1', name: 'Foo', deleted: false, deletedAt: null },
        assetManifest: [],
        catalogBundle: {
          ingredients: [{ id: 'cat-chr-1', deleted: true, deletedAt: '2026-03-01T00:00:00Z', updatedAt: '2026-03-01T00:00:00Z' }],
          refs: [{ ingredientId: 'cat-chr-1', refKind: 'universe', refId: 'u1', role: 'canon-character', deleted: true, deletedAt: '2026-03-01T00:00:00Z', updatedAt: '2026-03-01T00:00:00Z' }],
          relations: [{ id: 'cat-rel-1', deleted: true, deletedAt: '2026-03-01T00:00:00Z', updatedAt: '2026-03-01T00:00:00Z' }],
        },
        sourceInstanceId: 'peer-a',
        portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS, catalog }, portosVersion: '99.0.0' },
      });
      expect(applyCatalogRemoteChanges).toHaveBeenCalledTimes(1);
    });
  });

  // -------------------------------------------------------------------------
  // SCHEMA-VERSION GATING — sender side (handle 409 / cooldown / clear)
  // + receiver side (reject when sender ahead / pass through legacy + behind)
  // -------------------------------------------------------------------------
  describe('schema-version gating', () => {
    beforeEach(() => {
      // Earlier tests in this file accumulate calls on the merge mocks (the
      // file's outer beforeEach does mockResolvedValue but not mockClear).
      // Clear history so `expect(...).not.toHaveBeenCalled()` reflects only
      // calls made in the current test.
      vi.mocked(mergeUniversesFromSync).mockClear();
      vi.mocked(mergeSeriesFromSync).mockClear();
      vi.mocked(mergeIssuesFromSync).mockClear();
      vi.mocked(mergeMediaCollectionsFromSync).mockClear();
      vi.mocked(mergeMusicVideoProjectsFromSync).mockClear();
      vi.mocked(mergeTracksFromSync).mockClear();
    });

    // Fixtures derive from the live table so a schema bump can't silently turn
    // an "ahead"/"equal" sender into a "behind" one and disarm the gate.
    const versionsAhead = (bumps) => ({
      ...PORTOS_SCHEMA_VERSIONS,
      ...Object.fromEntries(Object.entries(bumps).map(([cat, n]) => [cat, PORTOS_SCHEMA_VERSIONS[cat] + n])),
    });

    describe('receiver — applyIncomingPush', () => {
      it('rejects when sender schemaVersions.universes is AHEAD of local code', async () => {
        // A push from a sender one universes version ahead of local code must NOT touch local state.
        const rejection = await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', name: 'Foo' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '99.0.0', schemaVersions: versionsAhead({ universes: 1 }) },
        }).catch((err) => err);
        expect(rejection.code).toBe('PEER_SYNC_SCHEMA_VERSION_AHEAD');
        expect(rejection.details.ahead).toEqual([{ category: 'universes', senderV: PORTOS_SCHEMA_VERSIONS.universes + 1, receiverV: PORTOS_SCHEMA_VERSIONS.universes }]);
        expect(rejection.details.senderPortosVersion).toBe('99.0.0');
        // Receiver MUST stamp its OWN PortOS version so the sender can show
        // the user "peer X is on PortOS vY" — without this, the sender would
        // fall back to its own version (the one it sent) and mislabel the
        // peer in the SchemaGapBadge.
        expect(typeof rejection.details.receiverPortosVersion).toBe('string');
        expect(rejection.details.receiverPortosVersion.length).toBeGreaterThan(0);
        // mergeUniversesFromSync MUST NOT have been called — the gate runs
        // before the merge dispatch.
        expect(mergeUniversesFromSync).not.toHaveBeenCalled();
      });

      it('passes through when sender schemaVersions are EQUAL to local', async () => {
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', name: 'Foo' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '2.7.0', schemaVersions: { ...PORTOS_SCHEMA_VERSIONS } },
        });
        expect(mergeUniversesFromSync).toHaveBeenCalledWith(
          [expect.objectContaining({ id: 'u1' })],
          { source: { via: 'peer-push', peerId: 'peer-a' }, senderSchemaVersions: { ...PORTOS_SCHEMA_VERSIONS } },
        );
      });

      it('passes through when sender is BEHIND local (sanitizer handles the backfill)', async () => {
        // Older peer pushes a v4-shape universe. Receiver is on v6 but the
        // record-shape sanitizer can backfill, so we apply rather than reject.
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', name: 'Foo' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '2.6.0', schemaVersions: { universes: 4 } },
        });
        expect(mergeUniversesFromSync).toHaveBeenCalledWith(
          [expect.objectContaining({ id: 'u1' })],
          { source: { via: 'peer-push', peerId: 'peer-a' }, senderSchemaVersions: { universes: 4 } },
        );
      });

      it('passes through legacy peers that send NO portosMeta at all', async () => {
        // Backwards compat — pre-this-PR peers don't know to include the
        // envelope. The comparator treats absent sender versions as 0, which
        // either matches (receiver also 0 for the category) or surfaces as
        // "behind" (which we DON'T gate on).
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', name: 'Foo' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
        });
        expect(mergeUniversesFromSync).toHaveBeenCalled();
      });

      // ---- per-category gate: cross-key isolation -------------------------
      // The sender stamps its full schemaVersions map. A push must only be
      // gated on the categories THIS record actually writes.
      it('does NOT reject a universe push when the sender is ahead on mediaCollections only', async () => {
        // universes is equal; the sender bumped an unrelated category. The old
        // whole-payload gate would have rejected this universe push.
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', name: 'Foo' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '99.0.0', schemaVersions: versionsAhead({ mediaCollections: 1 }) },
        });
        expect(mergeUniversesFromSync).toHaveBeenCalledWith(
          [expect.objectContaining({ id: 'u1' })],
          { source: { via: 'peer-push', peerId: 'peer-a' }, senderSchemaVersions: versionsAhead({ mediaCollections: 1 }) },
        );
      });

      it('does NOT reject a series push with NO bundled issues when the sender is ahead on pipelineIssues only', async () => {
        // No issues ride along, so pipelineIssues is not a transferred category.
        await applyIncomingPush({
          kind: 'series',
          record: { id: 'ser-1', name: 'Foo' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '99.0.0', schemaVersions: versionsAhead({ pipelineIssues: 1 }) },
        });
        expect(mergeSeriesFromSync).toHaveBeenCalled();
        expect(mergeIssuesFromSync).not.toHaveBeenCalled();
      });

      it('DOES reject a series push WITH bundled issues when the sender is ahead on pipelineIssues', async () => {
        // Issues are being transferred, so a pipelineIssues ahead-mismatch must
        // gate the push — otherwise the receiver merges issues it can't parse.
        const rejection = await applyIncomingPush({
          kind: 'series',
          record: { id: 'ser-1', name: 'Foo' },
          issues: [{ id: 'i1', seriesId: 'ser-1', deleted: false, deletedAt: null }],
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '99.0.0', schemaVersions: versionsAhead({ pipelineIssues: 1 }) },
        }).catch((err) => err);
        expect(rejection.code).toBe('PEER_SYNC_SCHEMA_VERSION_AHEAD');
        expect(rejection.details.ahead).toEqual([{ category: 'pipelineIssues', senderV: PORTOS_SCHEMA_VERSIONS.pipelineIssues + 1, receiverV: PORTOS_SCHEMA_VERSIONS.pipelineIssues }]);
        expect(mergeSeriesFromSync).not.toHaveBeenCalled();
        expect(mergeIssuesFromSync).not.toHaveBeenCalled();
      });

      it('DOES reject a universe push WITH a bundled linkedCollection when the sender is ahead on mediaCollections', async () => {
        // The linked collection is a transferred category, so a mediaCollections
        // ahead-mismatch must gate even though universes is equal.
        const rejection = await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', name: 'Foo' },
          linkedCollection: { id: 'col-1', name: 'Universe: U', items: [] },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '99.0.0', schemaVersions: versionsAhead({ mediaCollections: 1 }) },
        }).catch((err) => err);
        expect(rejection.code).toBe('PEER_SYNC_SCHEMA_VERSION_AHEAD');
        expect(rejection.details.ahead).toEqual([{ category: 'mediaCollections', senderV: PORTOS_SCHEMA_VERSIONS.mediaCollections + 1, receiverV: PORTOS_SCHEMA_VERSIONS.mediaCollections }]);
        expect(mergeUniversesFromSync).not.toHaveBeenCalled();
        expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();
      });

      it('DOES reject a music-video push WITH a live linkedTrack when the sender is ahead on tracks', async () => {
        const rejection = await applyIncomingPush({
          kind: 'musicVideoProject',
          record: { id: 'mv-1', trackId: 'track-1', deleted: false, deletedAt: null },
          linkedTrack: { id: 'track-1', title: 'Linked', deleted: false, deletedAt: null },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: {
            portosVersion: '99.0.0',
            schemaVersions: { ...PORTOS_SCHEMA_VERSIONS, tracks: PORTOS_SCHEMA_VERSIONS.tracks + 1 },
          },
        }).catch((err) => err);
        expect(rejection.code).toBe('PEER_SYNC_SCHEMA_VERSION_AHEAD');
        expect(rejection.details.ahead).toEqual([
          { category: 'tracks', senderV: PORTOS_SCHEMA_VERSIONS.tracks + 1, receiverV: PORTOS_SCHEMA_VERSIONS.tracks },
        ]);
        expect(mergeMusicVideoProjectsFromSync).not.toHaveBeenCalled();
        expect(mergeTracksFromSync).not.toHaveBeenCalled();
      });

      it.each([
        ['is a tombstone', { id: 'track-1', deleted: true, deletedAt: '2026-06-29T00:00:00Z' }],
        ['does not match the project trackId', { id: 'other-track', title: 'Unbound', deleted: false, deletedAt: null }],
      ])('does NOT gate a bundled linkedTrack that %s when the sender is ahead on tracks', async (_label, linkedTrack) => {
        await applyIncomingPush({
          kind: 'musicVideoProject',
          record: { id: 'mv-1', trackId: 'track-1', deleted: false, deletedAt: null },
          linkedTrack,
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: {
            portosVersion: '99.0.0',
            schemaVersions: { ...PORTOS_SCHEMA_VERSIONS, tracks: PORTOS_SCHEMA_VERSIONS.tracks + 1 },
          },
        });
        // Goes through the record-kind table (#6843), which passes
        // senderSchemaVersions uniformly (harmless for musicVideoProject —
        // ignored).
        expect(mergeMusicVideoProjectsFromSync).toHaveBeenCalledWith(
          [expect.objectContaining({ id: 'mv-1' })],
          expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-a' } }),
        );
      });

      // ---- tombstone-aware per-category scoping --------------------------
      it('does NOT reject a pure tombstone push even when the sender is ahead on that record kind (delete converges)', async () => {
        // A tombstone carries only id+deleted+deletedAt+updatedAt — safe at any
        // schema version. Gating it would strand federated deletes when one peer
        // upgrades ahead. The merge still runs (the delete must land).
        await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', deleted: true, deletedAt: '2026-05-22T03:00:00Z' },
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '99.0.0', schemaVersions: versionsAhead({ universes: 1 }) },
        });
        expect(mergeUniversesFromSync).toHaveBeenCalledWith(
          [expect.objectContaining({ id: 'u1', deleted: true })],
          { source: { via: 'peer-push', peerId: 'peer-a' }, senderSchemaVersions: versionsAhead({ universes: 1 }) },
        );
      });

      it('DOES reject a deleted-series push that bundles a LIVE issue when the sender is ahead on pipelineIssues', async () => {
        // deleteSeries does not cascade-tombstone child issues, and the push
        // bundles every child — so a deleted series can carry full-shape LIVE
        // issues. The series tombstone alone is safe, but the live issues are
        // NOT; gate pipelineIssues so they can't corrupt an older receiver.
        const rejection = await applyIncomingPush({
          kind: 'series',
          record: { id: 'ser-1', deleted: true, deletedAt: '2026-05-22T03:00:00Z' },
          issues: [{ id: 'i1', seriesId: 'ser-1', deleted: false, deletedAt: null }],
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '99.0.0', schemaVersions: versionsAhead({ pipelineIssues: 1 }) },
        }).catch((err) => err);
        expect(rejection.code).toBe('PEER_SYNC_SCHEMA_VERSION_AHEAD');
        expect(rejection.details.ahead).toEqual([{ category: 'pipelineIssues', senderV: PORTOS_SCHEMA_VERSIONS.pipelineIssues + 1, receiverV: PORTOS_SCHEMA_VERSIONS.pipelineIssues }]);
        expect(mergeSeriesFromSync).not.toHaveBeenCalled();
        expect(mergeIssuesFromSync).not.toHaveBeenCalled();
      });

      it('does NOT reject a deleted-series push whose bundled issues are ALL tombstones (cascade delete converges)', async () => {
        // Series tombstone + issue tombstones only — no live record in any
        // category, so nothing gates and the whole delete cascade converges
        // even though the sender is ahead on both pipelineSeries and pipelineIssues.
        await applyIncomingPush({
          kind: 'series',
          record: { id: 'ser-1', deleted: true, deletedAt: '2026-05-22T03:00:00Z' },
          issues: [{ id: 'i1', seriesId: 'ser-1', deleted: true, deletedAt: '2026-05-22T03:00:00Z' }],
          assetManifest: [],
          sourceInstanceId: 'peer-a',
          portosMeta: { portosVersion: '99.0.0', schemaVersions: versionsAhead({ pipelineSeries: 1, pipelineIssues: 1 }) },
        });
        expect(mergeSeriesFromSync).toHaveBeenCalled();
        expect(mergeIssuesFromSync).toHaveBeenCalledWith(
          [expect.objectContaining({ id: 'i1', deleted: true })],
          {
            source: { via: 'peer-push', peerId: 'peer-a' },
            senderSchemaVersions: versionsAhead({ pipelineSeries: 1, pipelineIssues: 1 }),
          },
        );
      });
    });

    describe('gate-map completeness (fail-open guard)', () => {
      it('every PEER_SUBSCRIBABLE_KIND resolves to a schema-category mapping', () => {
        // A new push kind that writes a versioned layout must be added to
        // RECORD_KIND_SCHEMA_CATEGORIES, or its push would bypass the gate
        // entirely (silent cross-install corruption). `mediaCollection` maps
        // via the same key; series issues are unioned at the call site.
        for (const kind of PEER_SUBSCRIBABLE_KINDS) {
          expect(Array.isArray(RECORD_KIND_SCHEMA_CATEGORIES[kind])).toBe(true);
          expect(RECORD_KIND_SCHEMA_CATEGORIES[kind].length).toBeGreaterThan(0);
        }
      });

      it('every versioned PORTOS_SCHEMA_VERSIONS key is reachable from a record kind', () => {
        // So a newly-versioned category can't ship without being wired into the
        // per-category gate (which would leave its transfers ungated). The only
        // exemptions are categories explicitly declared as non-record (pull-gated
        // elsewhere) via NON_RECORD_SCHEMA_CATEGORIES — e.g. mediaLibrary (#1566).
        const covered = new Set(Object.values(RECORD_KIND_SCHEMA_CATEGORIES).flat());
        for (const key of Object.keys(PORTOS_SCHEMA_VERSIONS)) {
          if (NON_RECORD_SCHEMA_CATEGORIES.has(key)) continue;
          expect(covered.has(key)).toBe(true);
        }
      });

      it('keeps the Tribe graph + universe render-runs + activity timeline + operator-action ledger intentionally OUT of the sync graph (#1724, #2150, #5594)', () => {
        // ADR 2026-06-26: tribe_* and universe_runs are deliberately machine-local.
        // - Tribe is relationship-graph data (mirrors the deliberate "memory_links
        //   are instance-local" policy in memorySync.js) and is coupled to
        //   machine-local calendar-account refs on touchpoints.
        // - universe_runs is a regenerable render cache under a 200-row GLOBAL cap
        //   that two producers would mutually evict; the durable universe record
        //   already federates.
        // - human_activity_events (#2150) is coupled to per-machine accounts and OS
        //   databases; only DERIVED summaries (Brain journals, digital-twin) federate,
        //   never the raw events. Same machine-local boundary per the ADR.
        // - user_action_events (#5594) is the operator-action ledger: what ONE human
        //   did on ONE machine, with task prompts and settings diffs attached. PII
        //   must not ride the federation layer at all (ADR
        //   2026-08-08-privacy-records-machine-local), and a peer has no use for a
        //   record of a button someone pressed on another install.
        // This guard pins that decision: federating any of them later is a conscious
        // act — wire the kind AND update this assertion + the ADR together.
        const localOnlyKinds = ['tribe', 'tribePerson', 'tribeTouchpoint', 'tribeMemoryLink', 'tribeIdentity', 'universeRun', 'humanActivityEvent', 'userActionEvent'];
        for (const kind of localOnlyKinds) {
          expect(PEER_SUBSCRIBABLE_KINDS).not.toContain(kind);
          expect(RECORD_KIND_SCHEMA_CATEGORIES[kind]).toBeUndefined();
        }
        const localOnlyCategories = ['tribe', 'tribePeople', 'tribeTouchpoints', 'tribeMemoryLinks', 'tribeIdentities', 'universeRuns', 'humanActivityEvents', 'userActionEvents'];
        for (const category of localOnlyCategories) {
          expect(PORTOS_SCHEMA_VERSIONS[category]).toBeUndefined();
          expect(NON_RECORD_SCHEMA_CATEGORIES.has(category)).toBe(false);
        }
      });
    });

    describe('sender — pushRecordToPeer', () => {
      it('stamps portosMeta on the outbound push payload', async () => {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({}) });
        await pushRecordToPeer({
          id: 's-meta', peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        });
        const call = vi.mocked(peerFetch).mock.calls.at(-1);
        expect(call).toBeDefined();
        const body = JSON.parse(call[1].body);
        expect(body.portosMeta).toBeDefined();
        expect(body.portosMeta.schemaVersions.universes).toBe(14);
        expect(typeof body.portosMeta.portosVersion).toBe('string');
      });

      it('records a blockedBySchema marker on the subscription when the peer responds 409', async () => {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        // Receiver claims it's on universes:4 + PortOS 2.5.0; sender is at 5.
        // `receiverPortosVersion` is the rejecting peer's version — that's
        // the label the sender persists as `peerPortosVersion`.
        vi.mocked(peerFetch).mockResolvedValue({
          ok: false,
          status: 409,
          json: async () => ({
            error: 'sender schema is ahead',
            code: 'PEER_SYNC_SCHEMA_VERSION_AHEAD',
            context: {
              details: {
                ahead: [{ category: 'universes', senderV: 5, receiverV: 4 }],
                behind: [],
                senderPortosVersion: '3.0.0',
                receiverPortosVersion: '2.5.0',
                receiverSchemaVersions: { universes: 4 },
              },
            },
          }),
        });
        // Subscribe first so we have a sub record to assert against.
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        const result = await pushRecordToPeer(sub);
        expect(result.pushed).toBe(false);
        expect(result.reason).toBe('peer-schema-behind');
        expect(result.blockedBySchema).toBe(true);
        // Block persisted on the subscription.
        const after = await findPeerSubscription('peer-a', 'universe', 'u1');
        expect(after.blockedBySchema).toBeDefined();
        expect(after.blockedBySchema.ahead).toEqual([{ category: 'universes', senderV: 5, receiverV: 4 }]);
        expect(after.blockedBySchema.peerPortosVersion).toBe('2.5.0');
        expect(typeof after.blockedBySchema.detectedAt).toBe('string');
        // lastPushedHash must NOT have advanced — the record didn't land.
        expect(after.lastPushedHash).toBeFalsy();
      });

      it('short-circuits subsequent pushes for blocked subs within the cooldown window', async () => {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        // First push gets the 409.
        vi.mocked(peerFetch).mockResolvedValue({
          ok: false,
          status: 409,
          json: async () => ({
            code: 'PEER_SYNC_SCHEMA_VERSION_AHEAD',
            context: {
              details: {
                ahead: [{ category: 'universes', senderV: 5, receiverV: 4 }],
                senderPortosVersion: '2.5.0',
              },
            },
          }),
        });
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        await pushRecordToPeer(sub);
        const fetchCallsAfterFirst = vi.mocked(peerFetch).mock.calls.length;
        // Re-load the sub with the persisted block, then push again with NO
        // bypass — should not hit the network.
        const blocked = await findPeerSubscription('peer-a', 'universe', 'u1');
        const result = await pushRecordToPeer(blocked);
        expect(result.pushed).toBe(false);
        expect(result.reason).toBe('peer-schema-behind-cooldown');
        expect(vi.mocked(peerFetch).mock.calls.length).toBe(fetchCallsAfterFirst);
      });

      it('bypasses the schema cooldown for tombstone pushes so deletes converge immediately', async () => {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        vi.mocked(peerFetch).mockResolvedValueOnce({
          ok: false,
          status: 409,
          json: async () => ({
            code: 'PEER_SYNC_SCHEMA_VERSION_AHEAD',
            context: {
              details: { ahead: [{ category: 'universes', senderV: 5, receiverV: 4 }] },
            },
          }),
        });
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        await pushRecordToPeer(sub);
        const blocked = await findPeerSubscription('peer-a', 'universe', 'u1');
        vi.mocked(getUniverse).mockResolvedValue({
          id: 'u1',
          name: 'Foo',
          deleted: true,
          deletedAt: '2026-05-23T00:00:00.000Z',
          updatedAt: '2026-05-23T00:00:00.000Z',
        });
        vi.mocked(peerFetch).mockResolvedValueOnce({ ok: true, json: async () => ({ missingAssets: [] }) });

        const result = await pushRecordToPeer(blocked);

        expect(result.pushed).toBe(true);
        const body = JSON.parse(vi.mocked(peerFetch).mock.calls.at(-1)[1].body);
        expect(body.record.deleted).toBe(true);
        expect(body.assetManifest).toEqual([]);
      });

      it('bypassSchemaCooldown=true re-probes regardless of recent block', async () => {
        // Simulates the peer:online path: retryPendingPushesForPeer passes
        // bypassSchemaCooldown so the next probe actually hits the wire even
        // if a recent 409 set the cooldown.
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        vi.mocked(peerFetch).mockResolvedValue({
          ok: false, status: 409,
          json: async () => ({
            code: 'PEER_SYNC_SCHEMA_VERSION_AHEAD',
            context: { details: { ahead: [{ category: 'universes', senderV: 5, receiverV: 4 }] } },
          }),
        });
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        await pushRecordToPeer(sub);
        const callsAfterFirst = vi.mocked(peerFetch).mock.calls.length;
        const blocked = await findPeerSubscription('peer-a', 'universe', 'u1');
        await pushRecordToPeer(blocked, { bypassSchemaCooldown: true });
        expect(vi.mocked(peerFetch).mock.calls.length).toBe(callsAfterFirst + 1);
      });

      it('clears blockedBySchema once a subsequent push succeeds (peer upgraded)', async () => {
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        // First push: 409.
        vi.mocked(peerFetch).mockResolvedValueOnce({
          ok: false, status: 409,
          json: async () => ({
            code: 'PEER_SYNC_SCHEMA_VERSION_AHEAD',
            context: { details: { ahead: [{ category: 'universes', senderV: 5, receiverV: 4 }], senderPortosVersion: '2.5.0' } },
          }),
        });
        // Second push: peer upgraded, accepts.
        vi.mocked(peerFetch).mockResolvedValueOnce({ ok: true, json: async () => ({}) });
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        await pushRecordToPeer(sub);
        expect((await findPeerSubscription('peer-a', 'universe', 'u1')).blockedBySchema).toBeDefined();
        // Bypass cooldown to simulate a peer:online retry.
        const blocked = await findPeerSubscription('peer-a', 'universe', 'u1');
        await pushRecordToPeer(blocked, { bypassSchemaCooldown: true });
        const cleared = await findPeerSubscription('peer-a', 'universe', 'u1');
        expect(cleared.blockedBySchema).toBeUndefined();
        expect(cleared.lastPushedHash).toBeTruthy(); // succeeded → hash recorded
      });

      // #3928 — the legacy-stripped water-mark. Withholding `lastPushedHash`
      // after a strip (pinned per row in 'envelope extensions (#6844)') is what
      // keeps the stripped key deliverable, but on its own it made EVERY
      // subsequent cycle re-run the 400 + stripped-retry pair forever.
      // `lastPushedLegacyHash` records the full payload hash we delivered in
      // stripped form so an unchanged record settles; these two cases cover
      // what moves it again.
      it('re-pushes when the bundled review actually changes after a stripped push (#3928)', async () => {
        vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
        vi.mocked(listIssuesForSeries).mockResolvedValue([{ id: 'i1', seriesId: 'ser-1', number: 1 }]);
        vi.mocked(getReview).mockResolvedValue({
          schemaVersion: 1,
          comments: [{ id: 'mrc-1', problem: 'pacing', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }],
        });
        mockPeerRejecting('manuscriptReview');
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1',
        }, { adoptedFromReverse: true });
        const first = await pushRecordToPeer(sub);
        const callsAfterFirst = vi.mocked(peerFetch).mock.calls.length;
        // The user resolves the comment — the review content moved, so the
        // water-mark must NOT hold the push back.
        vi.mocked(getReview).mockResolvedValue({
          schemaVersion: 1,
          comments: [{ id: 'mrc-1', problem: 'pacing', status: 'resolved', updatedAt: '2026-06-03T00:00:00Z' }],
        });
        const second = await pushRecordToPeer(await findPeerSubscription('peer-a', 'series', 'ser-1'));
        expect(second.pushed).toBe(true);
        expect(second.hash).not.toBe(first.hash);
        expect(vi.mocked(peerFetch).mock.calls.length).toBe(callsAfterFirst + 2);
        const refreshed = await findPeerSubscription('peer-a', 'series', 'ser-1');
        expect(refreshed.lastPushedLegacyHash).toBe(second.hash);
      });

      it('re-attempts the full push on a peer:online re-probe even when the legacy hash matches (#3928)', async () => {
        vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
        vi.mocked(listIssuesForSeries).mockResolvedValue([{ id: 'i1', seriesId: 'ser-1', number: 1 }]);
        vi.mocked(getReview).mockResolvedValue({
          schemaVersion: 1,
          comments: [{ id: 'mrc-1', problem: 'pacing', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }],
        });
        mockPeerRejecting('manuscriptReview');
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'series', recordId: 'ser-1',
        }, { adoptedFromReverse: true });
        await pushRecordToPeer(sub);
        // The peer upgraded and came back online — it now accepts the review.
        vi.mocked(peerFetch).mockImplementation(async () => ({ ok: true, status: 200, json: async () => ({}) }));
        const upgraded = await pushRecordToPeer(
          await findPeerSubscription('peer-a', 'series', 'ser-1'),
          { bypassSchemaCooldown: true },
        );
        expect(upgraded.pushed).toBe(true);
        const payload = JSON.parse(vi.mocked(peerFetch).mock.calls.at(-1)[1].body);
        expect(payload.manuscriptReview).toBeDefined();
        // Fully delivered → the normal hash takes over and the legacy
        // water-mark clears.
        const refreshed = await findPeerSubscription('peer-a', 'series', 'ser-1');
        expect(refreshed.lastPushedHash).toBe(upgraded.hash);
        expect(refreshed.lastPushedLegacyHash).toBeFalsy();
      });

      it('does NOT retry on a 400 whose validation error is unrelated to portosMeta', async () => {
        // The retry is keyed on the `portosMeta` mention in the validation
        // details — any other 400 (oversized field, unknown record key, etc.)
        // is a genuine bug we want to surface, not silently retry.
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        const errBody = { ok: false, status: 400, json: async () => ({
          code: 'VALIDATION_ERROR',
          message: 'Validation failed',
          context: { details: [{ path: 'record.name', message: 'String too long' }] },
        }) };
        errBody.clone = () => errBody;
        vi.mocked(peerFetch).mockResolvedValueOnce(errBody);
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        const result = await pushRecordToPeer(sub);
        expect(result.pushed).toBe(false);
        expect(result.reason).toBe('http-400');
        // Only ONE call — no retry.
        expect(vi.mocked(peerFetch).mock.calls.length).toBe(1);
      });

      it('records a peer-pre-feature blockedBySchema marker when a peer rejects an unknown record kind (400 invalid discriminator)', async () => {
        // A peer on an older PortOS whose `peerSyncPushSchema` discriminated
        // union has no arm for this record kind (authors / mediaCollection when
        // they first landed) rejects the push at Zod with a generic 400 whose
        // offending field is the `kind` discriminator — BEFORE its version gate
        // (the 409 path) ever runs. The sender must NOT treat this as a bare
        // http-400 (which churns silently); it routes the sub into an empty-gap
        // schema-version block so the SchemaGapBadge surfaces "peer needs to
        // update" and the edit-push cooldown engages, exactly like the 409 path.
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        const errBody = { ok: false, status: 400, json: async () => ({
          code: 'VALIDATION_ERROR',
          message: 'Validation failed',
          context: { details: [{ path: 'kind', message: "Invalid discriminator value. Expected 'universe' | 'series'" }] },
        }) };
        errBody.clone = () => errBody;
        vi.mocked(peerFetch).mockResolvedValueOnce(errBody);
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
        const result = await pushRecordToPeer(sub);
        // A peer that is merely behind is handled by the persisted block: stdout, not stderr.
        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("doesn't recognize the 'universe' record kind"));
        expect(warnSpy).not.toHaveBeenCalled();
        logSpy.mockRestore();
        warnSpy.mockRestore();
        expect(result.pushed).toBe(false);
        expect(result.reason).toBe('peer-schema-behind');
        expect(result.blockedBySchema).toBe(true);
        // No retry — the kind itself is unrecognized, so re-sending changes nothing.
        expect(vi.mocked(peerFetch).mock.calls.length).toBe(1);
        // Block persisted with the pre-feature marker + an empty gap (the peer
        // 400'd before sending any schemaVersions to populate ahead/behind).
        const after = await findPeerSubscription('peer-a', 'universe', 'u1');
        expect(after.blockedBySchema).toBeDefined();
        expect(after.blockedBySchema.reason).toBe('peer-pre-feature');
        expect(after.blockedBySchema.ahead).toEqual([]);
        expect(after.blockedBySchema.behind).toEqual([]);
        expect(after.blockedBySchema.peerPortosVersion).toBeNull();
        expect(typeof after.blockedBySchema.detectedAt).toBe('string');
        // lastPushedHash must NOT have advanced — the record didn't land.
        expect(after.lastPushedHash).toBeFalsy();
      });

      it('engages the push cooldown after a pre-feature block so the next edit-push short-circuits', async () => {
        // The pre-feature block must behave like the 409 block: a subsequent
        // push (no bypass) short-circuits on the cooldown instead of re-probing
        // the peer on every local edit.
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        const errBody = { ok: false, status: 400, json: async () => ({
          code: 'VALIDATION_ERROR',
          message: 'Validation failed',
          context: { details: [{ path: 'kind', message: 'Invalid discriminator value. Expected ...' }] },
        }) };
        errBody.clone = () => errBody;
        vi.mocked(peerFetch).mockResolvedValue(errBody);
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        await pushRecordToPeer(sub);
        const callsAfterFirst = vi.mocked(peerFetch).mock.calls.length;
        const blocked = await findPeerSubscription('peer-a', 'universe', 'u1');
        const result = await pushRecordToPeer(blocked);
        expect(result.reason).toBe('peer-schema-behind-cooldown');
        expect(vi.mocked(peerFetch).mock.calls.length).toBe(callsAfterFirst);
      });

      it('does NOT misclassify a non-discriminator field 400 as a pre-feature block', async () => {
        // Guard: only a `kind`-path discriminator/enum error is the unknown-kind
        // signal. A 400 on any other field (oversized record, etc.) stays a
        // genuine http-400 — not a silently-swallowed schema block.
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
        const errBody = { ok: false, status: 400, json: async () => ({
          code: 'VALIDATION_ERROR',
          message: 'Validation failed',
          context: { details: [{ path: 'record.name', message: 'String too long' }] },
        }) };
        errBody.clone = () => errBody;
        vi.mocked(peerFetch).mockResolvedValueOnce(errBody);
        const sub = await subscribePeer({
          peerId: 'peer-a', recordKind: 'universe', recordId: 'u1',
        }, { adoptedFromReverse: true });
        const result = await pushRecordToPeer(sub);
        expect(result.reason).toBe('http-400');
        const after = await findPeerSubscription('peer-a', 'universe', 'u1');
        expect(after.blockedBySchema).toBeUndefined();
      });
    });
  });

  // -------------------------------------------------------------------------
  // #6844 — the optional envelope keys share ONE strip / pending / withhold
  // lifecycle, declared once in ENVELOPE_EXTENSIONS. Every case below is driven
  // off that table so a row added later is exercised on both sides of the wire
  // without a hand-written twin of each flag.
  describe('envelope extensions (#6844)', () => {
    const SIDECARS = ENVELOPE_EXTENSIONS.filter((e) => e.pendingKey);
    const SELF_RECONCILING = ENVELOPE_EXTENSIONS.filter((e) => !e.pendingKey);
    const PENDING_KEYS = Object.values(ENVELOPE_PENDING_KEYS);

    const armSeries = () => {
      vi.mocked(getSeries).mockResolvedValue({ id: 'ser-1', name: 'Series' });
      vi.mocked(listIssuesForSeries).mockResolvedValue([{ id: 'i1', seriesId: 'ser-1', number: 1 }]);
    };
    // How the sender comes to carry each key on the wire. Every table row MUST
    // have a carrier (guarded below) — that is what makes this suite grow with
    // the table instead of silently skipping a new extension.
    const CARRIERS = {
      portosMeta: {
        recordKind: 'universe', recordId: 'u1',
        arm: async () => { vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' }); },
      },
      catalogBundle: {
        recordKind: 'universe', recordId: 'u1',
        arm: async () => {
          vi.mocked(getBackendName).mockReturnValue('postgres');
          vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', name: 'Foo' });
          vi.mocked(getCatalogBundleForRef).mockResolvedValue({
            ingredients: [{ id: 'cat-chr-1', type: 'character', name: 'Hero', updatedAt: '2026-01-02T00:00:00Z' }],
            refs: [{ ingredientId: 'cat-chr-1', refKind: 'universe', refId: 'u1', role: 'canon-character', createdAt: '2026-01-02T00:00:00Z' }],
          });
        },
      },
      manuscriptReview: {
        recordKind: 'series', recordId: 'ser-1',
        arm: async () => {
          armSeries();
          vi.mocked(getReview).mockResolvedValue({
            schemaVersion: 1,
            comments: [{ id: 'mrc-1', problem: 'pacing', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }],
          });
        },
      },
      reverseOutline: {
        recordKind: 'series', recordId: 'ser-1',
        arm: async () => {
          armSeries();
          vi.mocked(getStoredOutline).mockResolvedValue({
            seriesId: 'ser-1', schemaVersion: 1, status: 'complete', generatedAt: '2026-06-02T00:00:00Z',
            plotlines: [{ id: 'a', label: 'A', kind: 'main', color: '#3b82f6' }],
            scenes: [{ id: 'scene-001', sequence: 0, summary: 'opening', plotlineId: 'a' }],
          });
        },
      },
      bibleManifest: {
        recordKind: 'writersRoomWork', recordId: 'wr-work-aaaa',
        arm: async () => {
          vi.mocked(getPeers).mockResolvedValue([{
            instanceId: 'peer-a', name: 'Peer A', address: '192.0.2.10', port: 5555,
            enabled: true, syncEnabled: true, directions: ['outbound', 'inbound'], syncCategories: { writersRoomWorks: true },
          }]);
          vi.mocked(getWorkForSync).mockResolvedValue({ id: 'wr-work-aaaa', title: 'Example work', drafts: [] });
          const dir = join(PATHS.data, 'writers-room', 'works', 'wr-work-aaaa');
          await mkdir(dir, { recursive: true });
          await writeFile(join(dir, 'characters.json'), JSON.stringify({ characters: [], updatedAt: '2026-06-02T00:00:00Z' }));
        },
      },
      linkedTrack: {
        recordKind: 'musicVideoProject', recordId: 'mv-1',
        arm: async () => {
          enableMusicVideoPeer();
          vi.mocked(getTrack).mockResolvedValue({
            id: 'track-1', title: 'Anthem', audioFilename: 'linked.mp3',
            updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
          });
          vi.mocked(getMusicVideoProject).mockResolvedValue({
            id: 'mv-1', name: 'Linked', mode: 'director', trackId: 'track-1',
            uploadedAudioFilename: null, scenes: [],
            updatedAt: '2026-06-28T00:00:00Z', deleted: false, deletedAt: null,
          });
        },
      },
    };
    const claim = ({ recordKind, recordId }) => subscribePeer(
      { peerId: 'peer-a', recordKind, recordId },
      { adoptedFromReverse: true },
    );
    const refresh = ({ recordKind, recordId }) => findPeerSubscription('peer-a', recordKind, recordId);
    const payloadOf = (call) => JSON.parse(call[1].body);

    it('re-pushes a bible-only edit even when the work record is unchanged', async () => {
      const carrier = CARRIERS.bibleManifest;
      await carrier.arm();
      vi.mocked(peerFetch).mockResolvedValue(acceptsPush());
      await pushRecordToPeer(await claim(carrier));
      vi.mocked(peerFetch).mockClear();
      const file = join(PATHS.data, 'writers-room', 'works', carrier.recordId, 'characters.json');
      await writeFile(file, JSON.stringify({ characters: [{ name: 'New cast member' }], updatedAt: '2026-06-03T00:00:00Z' }));
      expect((await pushRecordToPeer(await refresh(carrier))).pushed).toBe(true);
      expect(payloadOf(vi.mocked(peerFetch).mock.calls[0]).bibleManifest).toHaveLength(1);
      // A corrupt optional sibling must not hold the work and its prose hostage.
      vi.mocked(peerFetch).mockClear();
      await writeFile(file, '{');
      expect((await pushRecordToPeer(await refresh(carrier))).pushed).toBe(true);
      const withoutBible = payloadOf(vi.mocked(peerFetch).mock.calls[0]);
      expect(withoutBible.record.id).toBe(carrier.recordId);
      expect(withoutBible).not.toHaveProperty('bibleManifest');
    });

    it('pins the wire vocabulary older peers depend on', () => {
      // Older senders and receivers read exactly these names off the wire — a
      // rename here is a cross-version break, not a refactor.
      const byKey = (rows) => [...rows].sort((a, b) => a[0].localeCompare(b[0]));
      expect(byKey(ENVELOPE_EXTENSIONS.map(({ key, pendingKey }) => [key, pendingKey]))).toEqual(byKey([
        ['portosMeta', null],
        ['catalogBundle', null],
        ['manuscriptReview', 'reviewSyncPending'],
        ['reverseOutline', 'outlineSyncPending'],
        ['linkedTrack', 'trackSyncPending'],
        ['bibleManifest', 'bibleSyncPending'],
      ]));
    });

    it('has a sender-side carrier for every table row (a new extension must be exercised here)', () => {
      expect(Object.keys(CARRIERS).sort()).toEqual(ENVELOPE_EXTENSIONS.map((e) => e.key).sort());
    });

    describe.each(ENVELOPE_EXTENSIONS)('$key — strip', ({ key }) => {
      it('is dropped — and only it — on the one retry a legacy peer\'s strict-schema 400 earns', async () => {
        const carrier = CARRIERS[key];
        await carrier.arm();
        mockPeerRejecting(key);
        const result = await pushRecordToPeer(await claim(carrier));
        expect(result.pushed).toBe(true);
        const calls = vi.mocked(peerFetch).mock.calls;
        expect(calls).toHaveLength(2);
        const first = payloadOf(calls[0]);
        const retry = payloadOf(calls[1]);
        expect(first[key]).toBeDefined();
        // Surgical: the retry is the first push minus exactly this key — the
        // record, bundled issues, sourceInstanceId and every other extension
        // survive, so a peer that supports portosMeta but not this key keeps
        // its version-gate handshake.
        const rest = { ...first };
        delete rest[key];
        expect(retry).toEqual(rest);
      });
    });

    it('drops every key a single 400 names in one retry (Zod lists all unrecognized keys in one issue)', async () => {
      const carrier = CARRIERS.catalogBundle; // carries portosMeta AND catalogBundle
      await carrier.arm();
      const rejectsBoth = legacyRejectsKey('portosMeta');
      rejectsBoth.json = async () => ({
        code: 'VALIDATION_ERROR',
        message: 'Validation failed',
        context: { details: [{ path: '', message: "Unrecognized key(s) in object: 'portosMeta', 'catalogBundle'" }] },
      });
      vi.mocked(peerFetch).mockResolvedValueOnce(rejectsBoth).mockResolvedValueOnce(acceptsPush());
      const result = await pushRecordToPeer(await claim(carrier));
      expect(result.pushed).toBe(true);
      const calls = vi.mocked(peerFetch).mock.calls;
      expect(calls).toHaveLength(2);
      const first = payloadOf(calls[0]);
      const retry = payloadOf(calls[1]);
      expect(first.portosMeta).toBeDefined();
      expect(first.catalogBundle).toBeDefined();
      expect(retry.portosMeta).toBeUndefined();
      expect(retry.catalogBundle).toBeUndefined();
      expect(retry.record.id).toBe(carrier.recordId);
    });

    describe.each(SIDECARS)('$key — no independent cycle ($pendingKey)', ({ key, pendingKey }) => {
      it('withholds lastPushedHash and water-marks lastPushedLegacyHash after a stripped push (#3928)', async () => {
        const carrier = CARRIERS[key];
        await carrier.arm();
        mockPeerRejecting(key);
        const result = await pushRecordToPeer(await claim(carrier));
        expect(result.pushed).toBe(true);
        const refreshed = await refresh(carrier);
        expect(refreshed.lastPushedHash).toBeFalsy();
        expect(refreshed.lastPushedLegacyHash).toBe(result.hash);
        // An unchanged record settles instead of re-running the 400 + retry pair.
        const second = await pushRecordToPeer(refreshed);
        expect(second.reason).toBe('unchanged-legacy-stripped');
        expect(vi.mocked(peerFetch).mock.calls).toHaveLength(2);
      });

      it('withholds the hash WITHOUT a legacy water-mark when the receiver reports it pending (transient merge failure)', async () => {
        const carrier = CARRIERS[key];
        await carrier.arm();
        vi.mocked(peerFetch).mockResolvedValue(acceptsPush({ [pendingKey]: true }));
        const result = await pushRecordToPeer(await claim(carrier));
        expect(result.pushed).toBe(true);
        expect(vi.mocked(peerFetch).mock.calls).toHaveLength(1);
        const refreshed = await refresh(carrier);
        expect(refreshed.lastPushedHash).toBeFalsy();
        expect(refreshed.lastPushedLegacyHash).toBeFalsy();
        // The next cycle must genuinely re-push, not short-circuit.
        vi.mocked(peerFetch).mockClear();
        vi.mocked(peerFetch).mockResolvedValue(acceptsPush());
        const second = await pushRecordToPeer(refreshed);
        expect(second.pushed).toBe(true);
        expect(vi.mocked(peerFetch).mock.calls).toHaveLength(1);
      });
    });

    describe.each(SELF_RECONCILING)('$key — own reconciliation cycle', ({ key }) => {
      it('saves lastPushedHash normally after a stripped push (nothing is owed through this hash)', async () => {
        const carrier = CARRIERS[key];
        await carrier.arm();
        mockPeerRejecting(key);
        const result = await pushRecordToPeer(await claim(carrier));
        expect(result.pushed).toBe(true);
        const refreshed = await refresh(carrier);
        expect(refreshed.lastPushedHash).toBe(result.hash);
        expect(refreshed.lastPushedLegacyHash).toBeFalsy();
        const second = await pushRecordToPeer(refreshed);
        expect(second.reason).toBe('unchanged');
      });
    });

    it('leaves the bundled-track GC floor unstamped when linkedTrack was stripped for a legacy peer (#1922)', async () => {
      // The project landed (its own confirmed floor advances) but the peer
      // never got the track, so the bundle-specific floor tombstoneGc's
      // `track` cutoff reads off musicVideoProject rows must stay unset.
      const carrier = CARRIERS.linkedTrack;
      await carrier.arm();
      mockPeerRejecting('linkedTrack');
      const sub = await claim(carrier);
      expect(sub.lastConfirmedTrackBundleAtMs).toBeNull();
      const result = await pushRecordToPeer(sub);
      expect(result.pushed).toBe(true);
      const refreshed = await refresh(carrier);
      expect(refreshed.lastConfirmedPushedAt).toBeTruthy();
      expect(refreshed.lastConfirmedTrackBundleAtMs).toBeNull();
    });

    describe('receiver — applyIncomingPush', () => {
      // How each sidecar reaches the receiver, and the merge that can throw.
      const RECEIVE_CARRIERS = {
        bibleManifest: {
          merge: diffWorkBibleManifest,
          payload: () => ({
            kind: 'writersRoomWork', record: { id: 'wr-work-aaaa', drafts: [] },
            bibleManifest: [{ workId: 'wr-work-aaaa', kind: 'character', sha256: 'a'.repeat(64), updatedAt: '2026-06-02T00:00:00Z' }],
            assetManifest: [], sourceInstanceId: 'peer-a',
          }),
        },
        manuscriptReview: {
          merge: mergeReviewFromSync,
          payload: () => ({
            kind: 'series',
            record: { id: 'ser-1', name: 'S', deleted: false, deletedAt: null },
            issues: [],
            manuscriptReview: { schemaVersion: 1, comments: [{ id: 'mrc-1', problem: 'x', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }] },
            assetManifest: [],
            sourceInstanceId: 'peer-a',
          }),
        },
        reverseOutline: {
          merge: mergeOutlineFromSync,
          payload: () => ({
            kind: 'series',
            record: { id: 'ser-1', name: 'S', deleted: false, deletedAt: null },
            issues: [],
            reverseOutline: sampleOutline(),
            assetManifest: [],
            sourceInstanceId: 'peer-a',
          }),
        },
        linkedTrack: {
          merge: mergeTracksFromSync,
          payload: () => ({
            kind: 'musicVideoProject',
            record: { id: 'mv-9', trackId: 'track-9', deleted: false, deletedAt: null },
            linkedTrack: { id: 'track-9', audioFilename: 'linked.mp3' },
            assetManifest: [],
            sourceInstanceId: 'peer-a',
          }),
        },
      };

      it('scopes bible pulls to the pushed work and keeps pending pulls retryable', async () => {
        const payload = RECEIVE_CARRIERS.bibleManifest.payload();
        const own = payload.bibleManifest[0];
        payload.bibleManifest.push({ ...own, workId: 'wr-work-bbbb' });
        // No peer fetch in this test: diff returns a pending target with no registered peer.
        vi.mocked(diffWorkBibleManifest).mockResolvedValueOnce([own]);
        const result = await applyIncomingPush(payload);
        expect(vi.mocked(diffWorkBibleManifest)).toHaveBeenLastCalledWith([own], expect.any(Object));
        expect(result.bibleSyncPending).toBe(true);
        payload.bibleManifest = undefined;
        await applyIncomingPush(payload);
        expect(vi.mocked(diffWorkBibleManifest)).toHaveBeenLastCalledWith([], expect.any(Object));
      });

      it('a tombstone writersRoomWork push diffs and pulls no draft bodies or bibles', async () => {
        const payload = RECEIVE_CARRIERS.bibleManifest.payload();
        payload.record = { id: 'wr-work-aaaa', deleted: true, deletedAt: '2026-06-02T00:00:00Z' };
        payload.draftBodyManifest = [{ workId: 'wr-work-aaaa', draftId: 'd1', sha256: 'b'.repeat(64), updatedAt: '2026-06-02T00:00:00Z' }];
        vi.mocked(diffWorkBibleManifest).mockClear();
        const result = await applyIncomingPush(payload);
        expect(diffWorkBibleManifest).not.toHaveBeenCalled();
        expect(result).not.toHaveProperty('missingDraftBodies');
        expect(result).not.toHaveProperty('bibleSyncPending');
      });

      it('a local-ephemeral universe push merges no bundle, reports no assets and creates no reverse subscription', async () => {
        vi.mocked(getBackendName).mockReturnValue('postgres');
        vi.mocked(getUniverse).mockResolvedValue({ id: 'u1', ephemeral: true });
        vi.mocked(mergeMediaCollectionsFromSync).mockClear();
        const result = await applyIncomingPush({
          kind: 'universe',
          record: { id: 'u1', name: 'Foo', deleted: false, deletedAt: null },
          linkedCollection: { id: 'col-1', name: 'Universe: U', items: [{ kind: 'image', ref: 'private.png' }] },
          catalogBundle: { ingredients: [{ id: 'cat-chr-1', type: 'character', name: 'Hero', updatedAt: '2026-01-02T00:00:00Z' }], refs: [] },
          assetManifest: [{ kind: 'image', filename: 'private.png', size: 1, sha256: 'c'.repeat(64) }],
          sourceInstanceId: 'peer-a',
          portosMeta: { schemaVersions: { ...PORTOS_SCHEMA_VERSIONS } },
        });
        expect(mergeMediaCollectionsFromSync).not.toHaveBeenCalled();
        expect(applyCatalogRemoteChanges).not.toHaveBeenCalled();
        expect(result.missingAssets).toEqual([]);
        expect(result.reverseSubscriptionCreated).toBe(false);
      });

      it('has a receiver-side carrier for every sidecar row', () => {
        expect(Object.keys(RECEIVE_CARRIERS).sort()).toEqual(SIDECARS.map((e) => e.key).sort());
      });

      it.each(SIDECARS)('raises exactly $pendingKey when the bundled $key merge throws, and no flag when it succeeds', async ({ key, pendingKey }) => {
        const { merge, payload } = RECEIVE_CARRIERS[key];
        const clean = await applyIncomingPush(payload());
        for (const flag of PENDING_KEYS) expect(clean).not.toHaveProperty(flag);
        vi.mocked(merge).mockRejectedValueOnce(new Error('disk full'));
        const failed = await applyIncomingPush(payload());
        expect(failed[pendingKey]).toBe(true);
        for (const flag of PENDING_KEYS) {
          if (flag !== pendingKey) expect(failed).not.toHaveProperty(flag);
        }
      });
    });
  });

  // -------------------------------------------------------------------------
  // mediaCollection push + receiver
  // -------------------------------------------------------------------------
  describe('collectCollectionAssetReferences', () => {
    it('maps items to image/video refs with an empty directImageRefFilenames', () => {
      const refs = collectCollectionAssetReferences({ items: [
        { kind: 'image', ref: 'a.png' },
        { kind: 'video', ref: 'vid123' },
        { kind: 'image', ref: 'b.png' },
      ] });
      expect(refs.directImageFilenames).toEqual(['a.png', 'b.png']);
      expect(refs.directVideoFilenames).toEqual(['vid123']);
      expect(refs.directImageRefFilenames).toEqual([]);
    });

    it('returns empty arrays for a collection with no items', () => {
      const refs = collectCollectionAssetReferences({ items: [] });
      expect(refs.directImageFilenames).toEqual([]);
      expect(refs.directVideoFilenames).toEqual([]);
      expect(refs.directImageRefFilenames).toEqual([]);
    });

    it('returns empty arrays for null/undefined input', () => {
      expect(collectCollectionAssetReferences(null).directImageFilenames).toEqual([]);
      expect(collectCollectionAssetReferences(undefined).directImageFilenames).toEqual([]);
    });
  });

  describe('applyIncomingPush — mediaCollection', () => {
    it('applies an incoming mediaCollection push into local collections', async () => {
      // Use the real mergeMediaCollectionsFromSync via importActual so the
      // write lands in the tmpdir and listCollections can confirm persistence.
      const real = await vi.importActual('../mediaCollections.js');
      vi.mocked(mergeMediaCollectionsFromSync).mockImplementationOnce(real.mergeMediaCollectionsFromSync);
      vi.mocked(listCollections).mockImplementationOnce(real.listCollections);

      await applyIncomingPush({
        kind: 'mediaCollection',
        record: { id: 'col-x', name: 'Synced', items: [], updatedAt: '2026-05-23T00:00:00.000Z' },
        assetManifest: [],
        sourceInstanceId: 'peer-abc',
      });

      // Goes through the record-kind table (#6843), which passes
      // senderSchemaVersions uniformly (harmless for mediaCollection — ignored).
      expect(mergeMediaCollectionsFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'col-x', name: 'Synced' })],
        expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-abc' } }),
      );

      // Confirm the record landed on disk via the real listCollections.
      const all = await real.listCollections();
      const found = all.find((c) => c.id === 'col-x');
      expect(found).toBeDefined();
      expect(found.name).toBe('Synced');
    });

    it('host-mode peer: indexes collection bytes as peer-hosted instead of pulling them', async () => {
      vi.mocked(getPeers).mockResolvedValue([{ id: 'p-host', instanceId: 'peer-host', name: 'Host', mediaSyncMode: 'host' }]);
      const record = { id: 'col-h', name: 'Hosted', items: [{ kind: 'image', ref: 'hosted-only.png' }], updatedAt: '2026-05-23T00:00:00.000Z' };
      const result = await applyIncomingPush({
        kind: 'mediaCollection',
        record,
        assetManifest: [{ kind: 'image', filename: 'hosted-only.png', sha256: 'a'.repeat(64) }],
        sourceInstanceId: 'peer-host',
      });
      // Nothing left to copy → the sender is not told bytes are "still syncing".
      expect(result.missingAssets).toEqual([]);
      expect(peerFetch).not.toHaveBeenCalledWith(expect.stringContaining('/data/images/hosted-only.png'), expect.anything(), expect.anything());
      const { resolveMediaLocations } = await import('../peerHostedMedia.js');
      expect((await resolveMediaLocations([{ kind: 'image', ref: 'hosted-only.png' }]))[0])
        .toMatchObject({ location: 'remote', hostPeerId: 'peer-host' });
    });

    it('copy-mode peer (default): the same push still reports the asset as missing to copy', async () => {
      vi.mocked(getPeers).mockResolvedValue([{ id: 'p-copy', instanceId: 'peer-copy', name: 'Copy' }]);
      const result = await applyIncomingPush({
        kind: 'mediaCollection',
        record: { id: 'col-c', name: 'Copied', items: [{ kind: 'image', ref: 'copied.png' }], updatedAt: '2026-05-23T00:00:00.000Z' },
        assetManifest: [{ kind: 'image', filename: 'copied.png', sha256: 'b'.repeat(64) }],
        sourceInstanceId: 'peer-copy',
      });
      expect(result.missingAssets).toHaveLength(1);
    });

    it('routes a mediaCollection push through mergeMediaCollectionsFromSync (mock assertion)', async () => {
      await applyIncomingPush({
        kind: 'mediaCollection',
        record: { id: 'col-y', name: 'Test', items: [], updatedAt: '2026-05-23T00:00:00.000Z' },
        assetManifest: [],
        sourceInstanceId: 'peer-abc',
      });
      expect(mergeMediaCollectionsFromSync).toHaveBeenCalledWith(
        [expect.objectContaining({ id: 'col-y' })],
        expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-abc' } }),
      );
    });

    it('auto-creates a reverse subscription back to the sender for a syncable local collection', async () => {
      // Regression (Bug 1): classifyLocalRecord had no mediaCollection branch,
      // so it returned 'missing' and maybeCreateReverseSubscription's
      // `localState !== 'syncable'` guard never bootstrapped bidirectional
      // collection sync. The merge landed the record locally, so the
      // classifyLocalRecord lookup must resolve it as 'syncable'.
      vi.mocked(getCollection).mockResolvedValue({
        id: 'col-rev', name: 'Synced', items: [], updatedAt: '2026-05-23T00:00:00.000Z',
        deleted: false, deletedAt: null,
      });
      const result = await applyIncomingPush({
        kind: 'mediaCollection',
        record: { id: 'col-rev', name: 'Synced', items: [] },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(result.reverseSubscriptionCreated).toBe(true);
      const sub = await findPeerSubscription('peer-a', 'mediaCollection', 'col-rev');
      expect(sub).not.toBeNull();
      expect(sub.adoptedFromReverse).toBe(true);
    });

    it('does NOT create a reverse subscription when the local collection is missing (merge dropped it)', async () => {
      // The default getCollection mock rejects (NOT_FOUND) → classifyLocalRecord
      // returns 'missing' → no orphan reverse-sub.
      const result = await applyIncomingPush({
        kind: 'mediaCollection',
        record: { id: 'col-gone', name: 'Gone', items: [] },
        assetManifest: [],
        sourceInstanceId: 'peer-a',
      });
      expect(result.reverseSubscriptionCreated).toBe(false);
      const sub = await findPeerSubscription('peer-a', 'mediaCollection', 'col-gone');
      expect(sub).toBeNull();
    });
  });

  describe('peerSyncPushSchema — mediaCollection validation', () => {
    it('accepts a valid mediaCollection push payload', async () => {
      const { peerSyncPushSchema } = await import('../../lib/validation.js');
      expect(() => peerSyncPushSchema.parse({
        kind: 'mediaCollection',
        record: { id: 'col-x', name: 'My Collection', items: [] },
        assetManifest: [],
        sourceInstanceId: 'peer-abc',
      })).not.toThrow();
    });

    it('rejects a mediaCollection push payload missing sourceInstanceId', async () => {
      const { peerSyncPushSchema } = await import('../../lib/validation.js');
      expect(() => peerSyncPushSchema.parse({
        kind: 'mediaCollection',
        record: { id: 'col-x' },
        assetManifest: [],
      })).toThrow();
    });

    it('accepts music push payloads and music asset manifests', async () => {
      const { peerSyncPushSchema } = await import('../../lib/validation.js');
      for (const kind of ['artist', 'album', 'track']) {
        expect(() => peerSyncPushSchema.parse({
          kind,
          record: { id: `${kind}-1` },
          assetManifest: [{ filename: 'song.mp3', kind: 'music', sha256: 'a'.repeat(64) }],
          sourceInstanceId: 'peer-abc',
        })).not.toThrow();
      }
    });
  });
});

describe('media-library federation (#1566)', () => {
  let origAudio;
  let origVideos;

  beforeEach(async () => {
    // The suite beforeEach redirects PATHS.data/images/music to `tmp` and
    // restores videos in its afterEach; redirect videos + audio (not created
    // there) into the same per-test tmpdir so manifest builds see ONLY fixtures.
    origAudio = PATHS.audio;
    origVideos = PATHS.videos;
    PATHS.videos = join(tmp, 'videos');
    PATHS.audio = join(tmp, 'audio');
    await mkdir(PATHS.videos, { recursive: true });
    await mkdir(PATHS.audio, { recursive: true });
    vi.mocked(reconcileMediaAssets).mockClear();
  });

  afterEach(() => {
    PATHS.audio = origAudio;
    PATHS.videos = origVideos;
  });

  describe('libraryKindsExcludedByPatterns (honors backup excludes)', () => {
    it('flags a kind whose whole dir is excluded — anchored, trailing-slash, and glob forms', () => {
      expect([...libraryKindsExcludedByPatterns(['/music/'])]).toEqual(['music']);
      expect([...libraryKindsExcludedByPatterns(['/videos/**'])]).toEqual(['video']);
      expect([...libraryKindsExcludedByPatterns(['images'])]).toEqual(['image']);
      expect([...libraryKindsExcludedByPatterns(['/audio'])]).toEqual(['audio']);
    });

    it('ignores excludes that do not name a whole media dir', () => {
      expect(libraryKindsExcludedByPatterns(['/loras/*.safetensors', '/repos/']).size).toBe(0);
      expect(libraryKindsExcludedByPatterns([]).size).toBe(0);
      expect(libraryKindsExcludedByPatterns(undefined).size).toBe(0);
    });
  });

  describe('buildMediaLibraryManifest', () => {
    it('walks all media dirs, hashes files, skips image sidecars, and is deterministic', async () => {
      await writeFile(join(PATHS.images, 'a.png'), 'img-a');
      await writeFile(join(PATHS.images, 'a.png.metadata.json'), JSON.stringify({ prompt: 'x' }));
      await writeFile(join(PATHS.videos, 'v.mp4'), 'vid');
      await writeFile(join(PATHS.audio, 's.wav'), 'aud');
      await writeFile(join(PATHS.music, 'm.mp3'), 'mus');

      const m1 = await buildMediaLibraryManifest();
      const kinds = m1.assets.map((e) => `${e.kind}:${e.filename}`).sort();
      expect(kinds).toEqual(['audio:s.wav', 'image:a.png', 'music:m.mp3', 'video:v.mp4']);
      // sidecar json is metadata, not advertised as its own asset
      expect(m1.assets.find((e) => e.filename.endsWith('.json'))).toBeUndefined();
      // every entry carries a 64-hex sha256
      expect(m1.assets.every((e) => /^[a-f0-9]{64}$/.test(e.sha256))).toBe(true);
      expect(m1.schemaVersion).toBe(PORTOS_SCHEMA_VERSIONS.mediaLibrary);
      expect(/^[a-f0-9]{64}$/.test(m1.manifestHash)).toBe(true);
      // deterministic hash across rebuilds of the same library
      const m2 = await buildMediaLibraryManifest();
      expect(m2.manifestHash).toBe(m1.manifestHash);
    });

    it('changes manifestHash when the library changes', async () => {
      await writeFile(join(PATHS.audio, 's.wav'), 'aud');
      const before = (await buildMediaLibraryManifest()).manifestHash;
      await writeFile(join(PATHS.audio, 't.wav'), 'aud2');
      const after = (await buildMediaLibraryManifest()).manifestHash;
      expect(after).not.toBe(before);
    });

    it('returns an empty manifest when the library is empty', async () => {
      const m = await buildMediaLibraryManifest();
      expect(m.assets).toEqual([]);
    });

    it('re-hash cache invalidates when a flat asset changes in place (size differs)', async () => {
      const p = join(PATHS.audio, 's.wav');
      await writeFile(p, 'short');
      const first = (await buildMediaLibraryManifest()).assets.find((e) => e.filename === 's.wav').sha256;
      // Overwrite with different-length content → (mtime,size) cache key changes.
      await writeFile(p, 'a much longer payload than before');
      const second = (await buildMediaLibraryManifest()).assets.find((e) => e.filename === 's.wav').sha256;
      expect(second).not.toBe(first);
    });
  });

  describe('syncMediaLibraryFromPeer', () => {
    const mkPeer = (id, extra = {}) => ({
      instanceId: id, name: id, host: null, address: '10.0.0.9', port: 5555,
      enabled: true, fullSync: true, ...extra,
    });

    it('no-ops for a non-full-sync peer and never hits the network', async () => {
      const res = await syncMediaLibraryFromPeer(mkPeer('fs-nofs', { fullSync: false }));
      expect(res.skipped).toBe('not-fullsync');
      expect(peerFetch).not.toHaveBeenCalled();
    });

    it('gently skips a peer whose manifest schema is ahead of local (no pull, no reconcile)', async () => {
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({
        schemaVersion: PORTOS_SCHEMA_VERSIONS.mediaLibrary + 1,
        manifestHash: 'a'.repeat(64), assets: [],
      }) });
      const res = await syncMediaLibraryFromPeer(mkPeer('fs-ahead'));
      expect(res.skipped).toBe('schema-ahead');
      expect(reconcileMediaAssets).not.toHaveBeenCalled();
    });

    it('skips an unreachable peer and an invalid manifest', async () => {
      vi.mocked(peerFetch).mockResolvedValue({ ok: false });
      expect((await syncMediaLibraryFromPeer(mkPeer('fs-down'))).skipped).toBe('unreachable');
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({ bogus: true }) });
      expect((await syncMediaLibraryFromPeer(mkPeer('fs-bad'))).skipped).toBe('invalid');
    });

    it('pulls nothing when assets already exist locally, then short-circuits on unchanged hash', async () => {
      // The peer's manifest == our OWN library (write files, build manifest, feed
      // it back) so diffAssetManifestAgainstLocal finds everything present.
      await writeFile(join(PATHS.audio, 's.wav'), 'aud');
      await writeFile(join(PATHS.images, 'a.png'), 'img');
      const localManifest = await buildMediaLibraryManifest();
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => localManifest });

      const peer = mkPeer('fs-present');
      const res1 = await syncMediaLibraryFromPeer(peer);
      expect(res1.pulled).toBe(0);
      expect(res1.skipped).toBeUndefined();
      expect(reconcileMediaAssets).not.toHaveBeenCalled(); // nothing pulled → no reconcile

      const res2 = await syncMediaLibraryFromPeer(peer);
      expect(res2.skipped).toBe('unchanged');
    });

    it('does NOT record the manifestHash when a byte pull fails — the next tick retries', async () => {
      const peer = mkPeer('fs-diverge');
      // pullMissingAssetsFromPeer re-resolves the peer via getPeers — include it.
      vi.mocked(getPeers).mockResolvedValue([peer]);
      const manifest = {
        schemaVersion: PORTOS_SCHEMA_VERSIONS.mediaLibrary,
        manifestHash: 'b'.repeat(64),
        assets: [{ filename: 'remote.wav', kind: 'audio', sha256: 'c'.repeat(64) }],
      };
      vi.mocked(peerFetch).mockImplementation(async (url) => {
        if (String(url).endsWith('/library-manifest')) return { ok: true, json: async () => manifest };
        return { ok: false }; // byte pull fails → nothing lands on disk
      });
      const res = await syncMediaLibraryFromPeer(peer);
      // The asset URL was requested...
      const urls = vi.mocked(peerFetch).mock.calls.map((c) => String(c[0]));
      expect(urls.some((u) => u.includes('/data/audio/remote.wav'))).toBe(true);
      // ...but nothing landed (re-diff still sees it missing), so pulled=0,
      // no reconcile, and the hash is NOT recorded.
      expect(res.pulled).toBe(0);
      expect(res.missing).toBe(1);
      expect(reconcileMediaAssets).not.toHaveBeenCalled();
      // Second call must re-diff (NOT short-circuit on an 'unchanged' hash).
      const res2 = await syncMediaLibraryFromPeer(peer);
      expect(res2.skipped).not.toBe('unchanged');
    });

    it('skips a manifest whose Content-Length exceeds the cap (unbounded-body guard for HTTP peers)', async () => {
      vi.mocked(peerFetch).mockResolvedValue({
        ok: true,
        headers: new Headers({ 'content-length': String(64 * 1024 * 1024) }), // > 32MB cap
        json: async () => ({ schemaVersion: PORTOS_SCHEMA_VERSIONS.mediaLibrary, manifestHash: 'a'.repeat(64), assets: [] }),
      });
      const res = await syncMediaLibraryFromPeer(mkPeer('fs-huge'));
      expect(res.skipped).toBe('too-large');
    });

    it('skips a chunked manifest with no Content-Length that streams past the cap', async () => {
      vi.mocked(peerFetch).mockResolvedValue(endlessChunkedRes());
      const res = await syncMediaLibraryFromPeer(mkPeer('fs-chunked'));
      expect(res.skipped).toBe('too-large');
    });

    it('forces a re-diff after repeated unchanged ticks so a local file loss self-heals', async () => {
      const peer = mkPeer('fs-selfheal');
      vi.mocked(getPeers).mockResolvedValue([peer]);
      const bytes = Buffer.from('heal-bytes');
      const manifest = {
        schemaVersion: PORTOS_SCHEMA_VERSIONS.mediaLibrary,
        manifestHash: 'f0'.repeat(32),
        assets: [{ filename: 'heal.wav', kind: 'audio' }], // existence-only diff
      };
      vi.mocked(peerFetch).mockImplementation(async (url) => {
        if (String(url).endsWith('/library-manifest')) return { ok: true, json: async () => manifest };
        return {
          ok: true,
          headers: new Headers({ 'content-length': String(bytes.length) }),
          arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
        };
      });
      // First sweep lands the file and records the manifestHash.
      expect((await syncMediaLibraryFromPeer(peer)).pulled).toBe(1);
      // Simulate local loss after the hash was recorded.
      await rm(join(PATHS.audio, 'heal.wav'), { force: true });
      // Unchanged ticks short-circuit until the periodic forced re-diff fires and
      // re-pulls the lost file (proves self-heal without a restart).
      let healed = false;
      for (let i = 0; i < 12; i++) {
        const r = await syncMediaLibraryFromPeer(peer);
        if (r.skipped !== 'unchanged') { healed = true; break; }
      }
      expect(healed).toBe(true);
    });

    it('records the manifestHash + reconciles once missing bytes actually land', async () => {
      const peer = mkPeer('fs-success');
      vi.mocked(getPeers).mockResolvedValue([peer]);
      // No sha256 on the entry → diff is existence-only, so once the byte pull
      // writes the file the re-diff sees it present (no hash to mismatch).
      const manifest = {
        schemaVersion: PORTOS_SCHEMA_VERSIONS.mediaLibrary,
        manifestHash: 'e'.repeat(64),
        assets: [{ filename: 'land.wav', kind: 'audio' }],
      };
      const bytes = Buffer.from('audio-bytes-that-landed');
      vi.mocked(peerFetch).mockImplementation(async (url) => {
        if (String(url).endsWith('/library-manifest')) return { ok: true, json: async () => manifest };
        // Asset byte fetch — a Response-like the cap-checker accepts.
        return {
          ok: true,
          headers: new Headers({ 'content-length': String(bytes.length) }),
          arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
        };
      });
      const res1 = await syncMediaLibraryFromPeer(peer);
      expect(res1.pulled).toBe(1);
      expect(res1.missing).toBe(0);
      expect(reconcileMediaAssets).toHaveBeenCalled();
      // Hash recorded → second call short-circuits as unchanged.
      const res2 = await syncMediaLibraryFromPeer(peer);
      expect(res2.skipped).toBe('unchanged');
    });
  });

  describe('syncMediaLibraryWithAllPeers', () => {
    it('sweeps only full-sync, enabled peers that have an instanceId', async () => {
      vi.mocked(getPeers).mockResolvedValue([
        { instanceId: 'fs1', address: '10.0.0.4', port: 5555, enabled: true, fullSync: true },
        { instanceId: 'partial', address: '10.0.0.5', port: 5555, enabled: true, fullSync: false },
        { instanceId: 'disabled', address: '10.0.0.6', port: 5555, enabled: false, fullSync: true },
        { instanceId: null, address: '10.0.0.7', port: 5555, enabled: true, fullSync: true },
      ]);
      vi.mocked(peerFetch).mockResolvedValue({ ok: true, json: async () => ({
        schemaVersion: PORTOS_SCHEMA_VERSIONS.mediaLibrary, manifestHash: 'd'.repeat(64), assets: [],
      }) });
      await syncMediaLibraryWithAllPeers();
      const manifestUrls = vi.mocked(peerFetch).mock.calls
        .map((c) => String(c[0])).filter((u) => u.endsWith('/library-manifest'));
      expect(manifestUrls).toHaveLength(1);
      expect(manifestUrls[0]).toContain('10.0.0.4');
    });
  });

  // #6843 — the per-kind record-kind table (recordKinds.js) collapsed six
  // hand-mirrored kind === '...' ladders (isSubscriptionRecordTombstone,
  // buildPushPayload, classifyLocalRecord, applyIncomingPush's ephemeral
  // lookup + merge dispatch, refusedFromCutoffs) to one lookup each. Before
  // that table, only 4 of the 16 subscribable kinds were exercised through
  // buildPushPayload/applyIncomingPush by this file (universe, series,
  // musicVideoProject, mediaCollection) — the other 12 kinds' ladder arms
  // were untested, which is exactly the gap that let classifyLocalRecord ship
  // with no fableLoom arm (always 'missing', so an inbound fableLoom push
  // could never auto-create a reverse subscription) and applyIncomingPush
  // carry a dead musicVideoProject ephemeral probe. This suite drives EVERY
  // PEER_SUBSCRIBABLE_KINDS entry through both boundaries so a future kind
  // that's added to the table but wired wrong fails here instead of shipping
  // silently — the exact failure mode the issue documents.
  describe('all-kinds parity (#6843)', () => {
    // One row per PEER_SUBSCRIBABLE_KINDS entry: the (already-imported,
    // already-mocked) getter + merger this kind's descriptor wraps, and a
    // minimal record shape sanitizeRecordForWire accepts for it (id +
    // deleted/deletedAt is sufficient for every kind — see syncWire.js: the
    // only universal requirements are a plain object with a non-blank id and
    // not `ephemeral === true` while live).
    const ALL_KINDS_FIXTURES = {
      universe: { get: getUniverse, merge: mergeUniversesFromSync },
      series: { get: getSeries, merge: mergeSeriesFromSync },
      mediaCollection: { get: getCollection, merge: mergeMediaCollectionsFromSync },
      author: { get: getAuthor, merge: mergeAuthorsFromSync },
      artist: { get: getArtist, merge: mergeArtistsFromSync },
      album: { get: getAlbum, merge: mergeAlbumsFromSync },
      track: { get: getTrack, merge: mergeTracksFromSync },
      creativeDirectorProject: { get: getCreativeDirectorProject, merge: mergeCreativeDirectorProjectsFromSync },
      moodBoard: { get: getBoard, merge: mergeBoardsFromSync },
      fableLoom: { get: getLoom, merge: mergeLoomsFromSync },
      writersRoomWork: { get: getWorkForSync, merge: mergeWorksFromSync },
      writersRoomFolder: { get: getFolderForSync, merge: mergeFoldersFromSync },
      writersRoomExercise: { get: getExerciseForSync, merge: mergeExercisesFromSync },
      musicVideoProject: { get: getMusicVideoProject, merge: mergeMusicVideoProjectsFromSync },
      commissionFeedback: { get: getCommissionFeedbackForSync, merge: mergeCommissionFeedbackFromSync },
      creativeCommission: { get: getCommissionForSync, merge: mergeCommissionsFromSync },
      deck: { get: getDeckForSync, merge: mergeDecksFromSync },
      storyboard: { get: getStoryboardForSync, merge: mergeStoryboardsFromSync },
    };

    it('every PEER_SUBSCRIBABLE_KINDS entry has a test fixture (guards the parity suite itself against a silently-skipped kind)', () => {
      expect(Object.keys(ALL_KINDS_FIXTURES).sort()).toEqual([...PEER_SUBSCRIBABLE_KINDS].sort());
    });

    it.each(PEER_SUBSCRIBABLE_KINDS)('buildPushPayload(%s): a live record pushes a populated envelope, a tombstone pushes assetManifest:[]', async (kind) => {
      const { get } = ALL_KINDS_FIXTURES[kind];
      const liveRecord = { id: `ak-live-${kind}`, name: 'AK', title: 'AK', deleted: false, deletedAt: null };
      vi.mocked(get).mockResolvedValueOnce(liveRecord);
      const liveResult = await buildPushPayload({ recordKind: kind, recordId: liveRecord.id }, 'src-instance');
      expect(liveResult.kind).toBe(kind);
      expect(liveResult.record.id).toBe(liveRecord.id);
      expect(Array.isArray(liveResult.assetManifest)).toBe(true);

      const tombstone = { id: `ak-tomb-${kind}`, deleted: true, deletedAt: '2026-05-01T00:00:00Z' };
      vi.mocked(get).mockResolvedValueOnce(tombstone);
      const tombResult = await buildPushPayload({ recordKind: kind, recordId: tombstone.id }, 'src-instance');
      expect(tombResult.record.deleted).toBe(true);
      expect(tombResult.assetManifest).toEqual([]);
    });

    it.each(PEER_SUBSCRIBABLE_KINDS)('applyIncomingPush(%s): merges the incoming record through this kind\'s own merger with a { source } envelope', async (kind) => {
      const { get, merge } = ALL_KINDS_FIXTURES[kind];
      vi.mocked(merge).mockClear();
      const record = { id: `ak-merge-${kind}`, name: 'AK', deleted: false, deletedAt: null };
      // Satisfies universe/series' local-ephemeral lookup (the only two kinds
      // that read `desc.load` before merging) — a non-ephemeral local match.
      vi.mocked(get).mockResolvedValue(record);
      await applyIncomingPush({ kind, record, assetManifest: [], sourceInstanceId: 'peer-a' });
      expect(merge).toHaveBeenCalledWith(
        [expect.objectContaining({ id: record.id })],
        expect.objectContaining({ source: { via: 'peer-push', peerId: 'peer-a' } }),
      );
    });

    it.each(PEER_SUBSCRIBABLE_KINDS)('applyIncomingPush(%s): reverse-subscribes when the local record is present, refuses when it is missing (classifyLocalRecord)', async (kind) => {
      const { get } = ALL_KINDS_FIXTURES[kind];

      const presentRecord = { id: `ak-present-${kind}`, name: 'AK', deleted: false, deletedAt: null };
      vi.mocked(get).mockResolvedValue(presentRecord);
      const presentResult = await applyIncomingPush({
        kind, record: presentRecord, assetManifest: [], sourceInstanceId: 'peer-a',
      });
      expect(presentResult.reverseSubscriptionCreated).toBe(true);

      const missingRecord = { id: `ak-missing-${kind}`, name: 'AK', deleted: false, deletedAt: null };
      vi.mocked(get).mockResolvedValue(undefined);
      const missingResult = await applyIncomingPush({
        kind, record: missingRecord, assetManifest: [], sourceInstanceId: 'peer-a',
      });
      expect(missingResult.reverseSubscriptionCreated).toBe(false);
    });
  });
});


describe('inbound peer admission before record writes', () => {
  const secret = 'synthetic-pair-secret-32-characters-long';
  const payload = () => ({ kind: 'universe', record: { id: 'u-admission', name: 'Example Universe' }, sourceInstanceId: 'peer-a', assetManifest: [] });
  const admitted = () => ({ id: 'configured-peer', instanceId: 'peer-a', syncSecret: secret, enabled: true,
    syncEnabled: true, directions: ['inbound', 'outbound'], syncCategories: { universe: true } });
  beforeEach(async () => {
    const real = await vi.importActual('./peerPushAuthorization.js');
    vi.mocked(authorizeIncomingPush).mockImplementation(real.authorizeIncomingPush);
    vi.mocked(getPeers).mockResolvedValue([admitted()]);
  });
  it.each([
    ['unknown', null, secret, 'peer-a'],
    ['announcement-only', { ...admitted(), syncSecret: undefined }, secret, 'peer-a'],
    ['missing proof', admitted(), undefined, 'peer-a'],
    ['wrong proof', admitted(), 'another-synthetic-secret-32-characters', 'peer-a'],
    ['forged source', admitted(), secret, 'peer-other'],
    ['disabled', { ...admitted(), enabled: false }, secret, 'peer-a'],
    ['sync off', { ...admitted(), syncEnabled: false, fullSync: true }, secret, 'peer-a'],
    ['outbound only', { ...admitted(), directions: ['outbound'] }, secret, 'peer-a'],
    ['category denied', { ...admitted(), syncCategories: { universe: false } }, secret, 'peer-a'],
  ])('rejects %s before merges, asset requests, or reverse subscriptions', async (_name, peer, peerToken, sourceInstanceId) => {
    vi.mocked(getPeers).mockResolvedValue(peer ? [peer] : []);
    await expect(applyIncomingPush({ ...payload(), sourceInstanceId }, { peerToken })).rejects.toMatchObject({ status: expect.any(Number) });
    expect(mergeUniversesFromSync).not.toHaveBeenCalled();
    expect(mergeIssuesFromSync).not.toHaveBeenCalled();
    expect(peerFetch).not.toHaveBeenCalled();
    expect(await listPeerSubscriptions()).toEqual([]);
  });
  it('accepts a locally admitted peer and permitted category', async () => {
    await applyIncomingPush(payload(), { peerToken: secret });
    expect(mergeUniversesFromSync).toHaveBeenCalled();
  });
  it('preserves explicit pulls while enforcing their configured peer consent', async () => {
    await applyIncomingPush(payload(), { pullPeerId: 'configured-peer' });
    expect(mergeUniversesFromSync).toHaveBeenCalled();
    vi.mocked(getPeers).mockResolvedValue([{ ...admitted(), syncEnabled: false }]);
    await expect(applyIncomingPush(payload(), { pullPeerId: 'configured-peer' })).rejects.toMatchObject({ status: 403 });
  });
});