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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* End-to-end sharing round-trip test.
*
* Exercises: register bucket → export series (records + assets + manifest) →
* delete locally → processManifest (auto-merge) → verify the series reappears
* with its original id, origin metadata, and asset blobs intact. Also verifies
* the LWW re-merge path: re-export with newer updatedAt, re-process, confirm
* local record updated and `overridden` populated.
*/
import { describe, it as vitestIt, expect, beforeEach, afterEach, afterAll, vi } from 'vitest';
import { mkdtempSync, rmSync, writeFileSync, existsSync, mkdirSync, readFileSync, statSync, utimesSync, symlinkSync, truncateSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { createHash } from 'crypto';
import { ASSET_PULL_MAX_BYTES, SIDECAR_MAX_BYTES } from './assetLimits.js';
import { makePathsProxy, mockNoPeerSync, mockNoPeers, mockTestIdentity, ownTestBodies } from '../../lib/mockPathsDataRoot.js';
const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=', 'base64');
const pngBytes = label => Buffer.concat([PNG, Buffer.from(label)]);
const fileUtilsMock = vi.hoisted(() => ({
atomicWrite: vi.fn(), realAtomicWrite: null,
}));
function sha256Hex(buf) {
return createHash('sha256').update(buf).digest('hex');
}
// Universe builder evaluates `join(PATHS.data, …)` at module-top, so PATHS
// must point at a real dir from the very first import. Allocate a single
// root up-front; per-test setup wipes + reseeds inside it.
const tempData = mkdtempSync(join(tmpdir(), 'portos-sharing-roundtrip-data-'));
let tempBucket;
const tempBuckets = new Set();
const owned = ownTestBodies(vitestIt);
const it = owned.it;
// Vitest cancellation ends its wait for a body, not the body's I/O. Settle
// fixture-owned import/export work before retiring any bucket (#12178).
async function cleanupBuckets() {
try {
await owned.drain();
} finally {
for (const bucket of tempBuckets) rmSync(bucket, { recursive: true, force: true });
tempBuckets.clear();
}
}
// makePathsProxy, not a hand-rolled one: this suite listed `data`/`images`/
// `videos` by hand, so `PATHS.imageRefs` — added later — still resolved to the
// install's live `data/image-refs`, and the importer's copyAssetsLocally
// created it and copied bundled reference sheets there on every run (#6176).
// The shared helper re-roots EVERY member that lives under `data/`, so a member
// added tomorrow is covered without touching this file.
vi.mock('../../lib/fileUtils.js', async () =>
makePathsProxy(await vi.importActual('../../lib/fileUtils.js'), {
dataRoot: tempData,
overrides: { atomicWrite: fileUtilsMock.atomicWrite },
}));
const fileUtilsActual = await vi.importActual('../../lib/fileUtils.js');
fileUtilsMock.realAtomicWrite = fileUtilsActual.atomicWrite;
fileUtilsMock.atomicWrite.mockImplementation((...args) => fileUtilsMock.realAtomicWrite(...args));
// Stub instanceIdentity.getInstanceId so the exporter doesn't try to read the
// real identity.json. Returns a fixed id for assertions.
vi.mock('../instances.js', () => mockNoPeers());
vi.mock('../instanceIdentity.js', () => mockTestIdentity({
getInstanceId: () => Promise.resolve('test-instance-id'),
}));
vi.mock('./peerSync.js', () => mockNoPeerSync());
// Stub mediaJobQueue.getJob — exporter uses it for full-fidelity gen
// metadata on each shared imageJobId. Returns null so the exporter falls
// through to direct asset copy via imageRefs.
// importArchivedJobs is the importer's only write path into the queue; the
// media-job import test points it at the real queue to pin the persisted file.
const mediaQueue = vi.hoisted(() => ({ actual: null }));
vi.mock('../mediaJobQueue/index.js', () => ({
getJob: () => null,
importArchivedJobs: (...args) => mediaQueue.actual.importArchivedJobs(...args),
}));
const buckets = await import('./buckets.js');
const exporter = await import('./exporter.js');
const importer = await import('./importer.js');
const series = await import('../pipeline/series.js');
const issues = await import('../pipeline/issues.js');
const universeSvc = await import('../universeBuilder.js');
const manuscriptReview = await import('../pipeline/manuscriptReview.js');
const reverseOutline = await import('../pipeline/reverseOutline.js');
// Seed a stored reverse outline directly (generateReverseOutline needs an LLM).
// Writes the sibling doc at the same path reverseOutline.js reads/writes.
function seedOutline(seriesId, generatedAt = '2026-06-02T00:00:00Z', summary = 'Opening beat') {
const dir = series.seriesStore().recordDir(seriesId);
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, 'reverse-outline.json'), JSON.stringify({
seriesId, schemaVersion: 1, status: 'complete', generatedAt,
plotlines: [{ id: 'A', label: 'A-plot', kind: 'main', color: '#3b82f6' }],
scenes: [{ id: 'scene-001', sequence: 0, summary, plotlineId: 'A', issueId: 'iss-1', issueTitle: 'One', issueNumber: 1 }],
}));
}
// Rewrite a manifest's senderInstanceId on disk so the importer sees it as
// coming from a remote peer. The mocked `getInstanceId` returns the same
// id for both producer and consumer in these tests, but in production
// instance A publishes and instance B imports — `processManifest` now
// short-circuits self-authored manifests, so the round-trip tests must
// flip the sender to simulate a peer.
function simulateRemoteSender(bucketPath, filename, peerId = 'remote-peer-id') {
const p = join(bucketPath, 'manifests', filename);
const m = JSON.parse(readFileSync(p, 'utf-8'));
m.senderInstanceId = peerId;
writeFileSync(p, JSON.stringify(m, null, 2));
}
describe('sharing round-trip', () => {
beforeEach(() => {
fileUtilsMock.atomicWrite.mockClear();
fileUtilsMock.atomicWrite.mockImplementation((...args) => fileUtilsMock.realAtomicWrite(...args));
// Wipe and re-seed the temp data dir + a fake asset for each test.
rmSync(tempData, { recursive: true, force: true });
mkdirSync(tempData, { recursive: true });
mkdirSync(join(tempData, 'images'), { recursive: true });
mkdirSync(join(tempData, 'videos'), { recursive: true });
writeFileSync(join(tempData, 'images', 'fakeasset.png'), pngBytes('PNGSTUB'));
tempBucket = mkdtempSync(join(tmpdir(), 'portos-sharing-roundtrip-bucket-'));
tempBuckets.add(tempBucket);
});
afterEach(cleanupBuckets);
// tempData is minted once (module scope) and reused across every test in
// this file — beforeEach only wipes-and-recreates it, so the LAST test's
// root is never removed. Clean it once here (#9032).
afterAll(async () => {
try {
await cleanupBuckets();
} finally {
rmSync(tempData, { recursive: true, force: true });
}
});
function writeAssetManifest(assetRefs, id = 'asset-ingress') {
const filename = `${id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify({
id, senderInstanceId: 'example-peer', kind: 'media', recordIds: [], assetRefs,
}));
return filename;
}
for (const mode of ['auto-merge', 'inbox']) {
it(`imports verified v1/v2 images, reference sheets and videos through ${mode}`, async () => {
const bucket = await buckets.createBucket({ name: 'Verified assets', path: tempBucket, mode });
const mp4 = Buffer.from('000000186674797069736f6d0000020069736f6d6d703432', 'hex');
const refs = [];
for (const version of [1, 2]) {
for (const kind of ['image', 'image-ref', 'video']) {
const ref = `${kind}-v${version}.${kind === 'video' ? 'mp4' : 'png'}`;
const bytes = kind === 'video' ? mp4 : pngBytes(ref);
const hash = version === 2 ? sha256Hex(bytes) : undefined;
const dir = join(tempBucket, 'assets', hash ? 'blobs' : kind === 'video' ? 'videos' : 'images');
mkdirSync(dir, { recursive: true });
const source = join(dir, hash || ref);
writeFileSync(source, bytes);
if (kind !== 'video') writeFileSync(hash ? `${source}.metadata.json` : join(dir, buckets.imageSidecarName(ref)), '{"prompt":"example"}');
refs.push({ kind, ref, ...(hash ? { hash } : {}) });
}
}
const filename = writeAssetManifest(refs);
expect(await importer.processManifest(bucket.id, filename)).toMatchObject({ processed: true });
if (mode === 'inbox') {
// Force promotion to publish again, rather than merely use existing files.
for (const dir of ['images', 'image-refs', 'videos']) rmSync(join(tempData, dir), { recursive: true, force: true });
await importer.promoteInboxItem(bucket.id, 'asset-ingress');
expect(await importer.listInbox(bucket.id)).toEqual([]);
}
for (const { kind, ref } of refs) {
const dir = join(tempData, kind === 'video' ? 'videos' : kind === 'image-ref' ? 'image-refs' : 'images');
expect(readFileSync(join(dir, ref))).toEqual(kind === 'video' ? mp4 : pngBytes(ref));
if (kind !== 'video') expect(JSON.parse(readFileSync(join(dir, buckets.imageSidecarName(ref)), 'utf8'))).toEqual({ prompt: 'example' });
}
});
}
for (const scenario of [
'v2 symlink', 'legacy symlink', 'blobs directory symlink', 'assets directory symlink',
'internal directory symlink', 'nonregular blob',
'hash mismatch', 'video playlist', 'image playlist', 'reference non-image',
'sidecar symlink', 'sidecar playlist', 'oversized blob', 'oversized sidecar',
]) {
it(`defers ${scenario} without publishing unverified bytes`, async () => {
const bucket = await buckets.createBucket({ name: 'Untrusted assets', path: tempBucket, mode: 'auto-merge' });
const kind = scenario === 'video playlist' ? 'video' : scenario === 'reference non-image' ? 'image-ref' : 'image';
const ref = { kind, ref: 'untrusted.png' };
const good = pngBytes('verified');
const hash = sha256Hex(good);
const legacy = scenario === 'legacy symlink';
if (!legacy) ref.hash = hash;
const dir = join(tempBucket, 'assets', legacy ? 'images' : 'blobs');
mkdirSync(dir, { recursive: true });
let source = join(dir, legacy ? ref.ref : hash);
writeFileSync(source, good);
const outside = join(tempData, 'outside.png');
writeFileSync(outside, good);
if (scenario === 'v2 symlink' || legacy) {
rmSync(source);
symlinkSync(outside, source, 'file');
} else if (scenario.endsWith('directory symlink')) {
const original = scenario === 'assets directory symlink' ? join(tempBucket, 'assets') : dir;
const outsideDir = join(scenario === 'internal directory symlink' ? tempBucket : tempData, 'outside-dir');
mkdirSync(outsideDir);
if (scenario === 'assets directory symlink') mkdirSync(join(outsideDir, 'blobs'));
writeFileSync(join(outsideDir, scenario === 'assets directory symlink' ? 'blobs' : '', hash), good);
rmSync(original, { recursive: true });
symlinkSync(outsideDir, original, process.platform === 'win32' ? 'junction' : 'dir');
} else if (scenario === 'nonregular blob') {
rmSync(source);
mkdirSync(source);
} else if (scenario === 'hash mismatch') {
writeFileSync(source, pngBytes('different'));
} else if (scenario === 'video playlist' || scenario === 'image playlist' || scenario === 'reference non-image') {
const bytes = Buffer.from(scenario === 'reference non-image' ? 'not an image' : '#EXTM3U\n#EXT-X-TARGETDURATION:10\nexample.ts\n');
ref.hash = sha256Hex(bytes);
source = join(dir, ref.hash);
writeFileSync(source, bytes);
} else if (scenario === 'sidecar symlink') {
symlinkSync(outside, `${source}.metadata.json`, 'file');
} else if (scenario === 'sidecar playlist') {
writeFileSync(`${source}.metadata.json`, 'ffconcat version 1.0\nfile example.mp4\n');
} else if (scenario.startsWith('oversized')) {
const oversized = scenario === 'oversized sidecar' ? `${source}.metadata.json` : source;
writeFileSync(oversized, '');
truncateSync(oversized, (scenario === 'oversized sidecar' ? SIDECAR_MAX_BYTES : ASSET_PULL_MAX_BYTES) + 1);
}
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
try {
const result = await importer.processManifest(bucket.id, writeAssetManifest([ref]));
expect(result).toMatchObject({ processed: true, pending: true, outcome: { pendingAssets: [{ kind, ref: ref.ref }] } });
const targetDir = join(tempData, kind === 'video' ? 'videos' : kind === 'image-ref' ? 'image-refs' : 'images');
expect(existsSync(join(targetDir, ref.ref))).toBe(false);
expect(existsSync(join(targetDir, buckets.imageSidecarName(ref.ref)))).toBe(false);
expect(warn.mock.calls.filter(([line]) => line.startsWith('⚠️ sharing.importer: refused asset'))).toEqual([
[`⚠️ sharing.importer: refused asset ${kind}/${JSON.stringify(ref.ref)}`],
]);
} finally {
warn.mockRestore();
}
});
}
it('publishes the verified buffer when the bucket path changes before publication', async () => {
const bucket = await buckets.createBucket({ name: 'Publication race', path: tempBucket, mode: 'auto-merge' });
const ref = { kind: 'image', ref: 'verified-race.png', hash: sha256Hex(PNG) };
const source = buckets.bucketBlobPath(tempBucket, ref.hash);
mkdirSync(join(tempBucket, 'assets', 'blobs'), { recursive: true });
writeFileSync(source, PNG);
const target = join(tempData, 'images', ref.ref);
let replaced = false;
fileUtilsMock.atomicWrite.mockImplementation((path, ...args) => {
if (path.startsWith(join(tempData, 'images', '.sharing-'))) {
replaced = true;
rmSync(source);
symlinkSync(join(tempData, 'outside.png'), source, 'file');
writeFileSync(join(tempData, 'outside.png'), 'unverified replacement');
}
return fileUtilsMock.realAtomicWrite(path, ...args);
});
expect(await importer.processManifest(bucket.id, writeAssetManifest([ref]))).toMatchObject({ processed: true });
expect(replaced).toBe(true);
expect(readFileSync(target)).toEqual(PNG);
});
it('leaves no final or temporary file after a failed publication, then imports on retry', async () => {
const bucket = await buckets.createBucket({ name: 'Publication failure', path: tempBucket, mode: 'auto-merge' });
const ref = { kind: 'image', ref: 'retry.png', hash: sha256Hex(PNG) };
mkdirSync(join(tempBucket, 'assets', 'blobs'), { recursive: true });
writeFileSync(buckets.bucketBlobPath(tempBucket, ref.hash), PNG);
const filename = writeAssetManifest([ref]);
const imageDir = join(tempData, 'images');
fileUtilsMock.atomicWrite.mockImplementation(async (path, ...args) => {
if (path.startsWith(join(imageDir, '.sharing-'))) {
await fileUtilsMock.realAtomicWrite(path, 'partial bytes');
throw Object.assign(new Error('simulated disk full'), { code: 'ENOSPC' });
}
return fileUtilsMock.realAtomicWrite(path, ...args);
});
await expect(importer.processManifest(bucket.id, filename)).rejects.toThrow('simulated disk full');
expect(existsSync(join(imageDir, ref.ref))).toBe(false);
const { readdirSync } = await import('fs');
expect(readdirSync(imageDir).filter(name => name.startsWith('.sharing-'))).toEqual([]);
fileUtilsMock.atomicWrite.mockImplementation((...args) => fileUtilsMock.realAtomicWrite(...args));
await importer.processManifest(bucket.id, filename);
expect(readFileSync(join(imageDir, ref.ref))).toEqual(PNG);
});
it('preserves a destination created while verified bytes are being staged', async () => {
const bucket = await buckets.createBucket({ name: 'Concurrent publication', path: tempBucket, mode: 'auto-merge' });
const ref = { kind: 'image', ref: 'existing.png', hash: sha256Hex(PNG) };
mkdirSync(join(tempBucket, 'assets', 'blobs'), { recursive: true });
writeFileSync(buckets.bucketBlobPath(tempBucket, ref.hash), PNG);
const target = join(tempData, 'images', ref.ref);
const existing = pngBytes('existing');
fileUtilsMock.atomicWrite.mockImplementation((path, ...args) => {
if (path.startsWith(join(tempData, 'images', '.sharing-'))) writeFileSync(target, existing);
return fileUtilsMock.realAtomicWrite(path, ...args);
});
await importer.processManifest(bucket.id, writeAssetManifest([ref]));
expect(readFileSync(target)).toEqual(existing);
});
it('revalidates bucket bytes during promotion even when a local file already exists', async () => {
const bucket = await buckets.createBucket({ name: 'Inbox integrity', path: tempBucket, mode: 'inbox' });
const ref = { kind: 'image', ref: 'promote.png' };
const dir = join(tempBucket, 'assets', 'images');
mkdirSync(dir, { recursive: true });
writeFileSync(join(dir, ref.ref), PNG);
await importer.processManifest(bucket.id, writeAssetManifest([ref]));
writeFileSync(join(dir, ref.ref), '#EXTM3U\nexample.ts\n');
await expect(importer.promoteInboxItem(bucket.id, 'asset-ingress')).rejects.toMatchObject({
code: 'SHARING_ASSETS_PENDING', missingAssets: [ref],
});
expect(readFileSync(join(tempData, 'images', ref.ref))).toEqual(PNG);
expect(await importer.listInbox(bucket.id)).toHaveLength(1);
writeFileSync(join(dir, ref.ref), PNG);
await importer.promoteInboxItem(bucket.id, 'asset-ingress');
expect(await importer.listInbox(bucket.id)).toEqual([]);
});
it('preserves local video holds while importing bundled media-job records', async () => {
const bucket = await buckets.createBucket({ name: 'Example Bucket', path: tempBucket, mode: 'inbox' });
const local = { id: 'retained-local', kind: 'video', status: 'completed', completedAt: new Date().toISOString(), params: { prompt: 'local' } };
const videoHolds = [{ id: '00000000-0000-4000-8000-000000000001', modelId: 'example-video', runtime: 'mlx_video',
classification: 'runtimeerror', cause: 'shader failed', heldAt: '2026-09-05T00:00:00.000Z' }];
const file = join(tempData, 'media-jobs.json');
writeFileSync(file, JSON.stringify({ jobs: [local], videoHolds }));
const incoming = { id: '00000000-0000-4000-8000-000000000002', kind: 'video', status: 'completed',
completedAt: '2026-01-01T00:00:00.000Z', params: { prompt: 'bundled' }, result: { filename: 'bundled.mp4' } };
mkdirSync(join(tempBucket, 'records', 'media'), { recursive: true });
writeFileSync(join(tempBucket, 'records', 'media', `${incoming.id}.json`), JSON.stringify(incoming));
writeFileSync(join(tempBucket, 'manifests', 'example-media.json'), JSON.stringify({
id: 'example-manifest', senderInstanceId: 'example-peer', kind: 'media', recordIds: [incoming.id], assetRefs: [],
}));
const queue = await vi.importActual('../mediaJobQueue/index.js');
mediaQueue.actual = queue;
await queue.initMediaJobQueue();
try {
expect((await importer.processManifest(bucket.id, 'example-media.json')).processed).toBe(true);
// Visible without a restart, and older than the queue's 24h trim yet kept.
expect(queue.getJob(incoming.id)).toMatchObject({ params: { prompt: 'bundled' }, result: { filename: 'bundled.mp4' } });
const saved = JSON.parse(readFileSync(file, 'utf8'));
expect(saved.jobs.map((j) => j.id).sort()).toEqual([local.id, incoming.id].sort());
expect(saved.videoHolds).toEqual(videoHolds);
} finally {
await queue.__resetForTests();
}
});
it('merges bundled media-job records only as completed re-render metadata under the id they were read by', async () => {
const bucket = await buckets.createBucket({ name: 'Example Bucket', path: tempBucket, mode: 'inbox' });
const file = join(tempData, 'media-jobs.json');
writeFileSync(file, JSON.stringify({ jobs: [] }));
const id = (n) => `00000000-0000-4000-8000-00000000001${n}`;
// The queue replays a persisted `queued` record at boot; a bucket record
// must never schedule work here, rename itself, or pick a non-media kind.
const records = {
[id(1)]: { id: id(1), kind: 'image', status: 'queued', params: { mode: 'codex', prompt: 'example' } },
[id(2)]: { id: '../../escaped', kind: 'image', status: 'completed', params: {} },
[id(3)]: { id: id(3), kind: 'training', status: 'completed', params: { runId: 'example' } },
[id(4)]: { id: id(4), kind: 'image', status: 'completed', completedAt: '2026-09-05T00:00:00.000Z',
durabilityPending: { status: 'completed' }, cancelRequested: true,
params: { prompt: 'example' }, result: { filename: `${id(4)}.png` } },
};
mkdirSync(join(tempBucket, 'records', 'media'), { recursive: true });
for (const [recordId, record] of Object.entries(records)) {
writeFileSync(join(tempBucket, 'records', 'media', `${recordId}.json`), JSON.stringify(record));
}
writeFileSync(join(tempBucket, 'manifests', 'example-media.json'), JSON.stringify({
id: 'example-manifest', senderInstanceId: 'example-peer', kind: 'media', recordIds: Object.keys(records), assetRefs: [],
}));
const queue = await vi.importActual('../mediaJobQueue/index.js');
mediaQueue.actual = queue;
await queue.initMediaJobQueue();
try {
await importer.processManifest(bucket.id, 'example-media.json');
expect(JSON.parse(readFileSync(file, 'utf8')).jobs).toEqual([{
id: id(4), kind: 'image', owner: null, status: 'completed', completedAt: '2026-09-05T00:00:00.000Z',
params: { prompt: 'example' }, result: { filename: `${id(4)}.png` }, imported: true,
}]);
} finally {
await queue.__resetForTests();
}
});
it('names an exported media record by its job id, never by an imported sidecar id', async () => {
const bucket = await buckets.createBucket({ name: 'Example Bucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const mediaCollections = await import('../mediaCollections.js');
const u = await universeBuilder.createUniverse({ name: 'Example Universe' });
// Sidecars land in data/images verbatim from bucket imports and peer pulls.
writeFileSync(join(tempData, 'images', 'shared-job.png'), pngBytes('SHARED'));
writeFileSync(join(tempData, 'images', 'shared-job.metadata.json'), JSON.stringify({
id: '../../../escaped-record', prompt: 'example', filename: 'shared-job.png',
}));
const collection = await mediaCollections.findOrCreateCollectionByName({
name: `Universe: ${u.name}`, description: 'Linked', universeId: u.id,
});
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'shared-job.png' });
await exporter.exportUniverse(u.id, bucket.id);
expect(existsSync(join(tempBucket, '..', 'escaped-record.json'))).toBe(false);
const record = JSON.parse(readFileSync(join(tempBucket, 'records', 'media', 'shared-job.json'), 'utf8'));
expect(record).toMatchObject({ id: 'shared-job', params: { prompt: 'example' } });
});
it('exports a series, processes the manifest as inbox, then promotes — id + origin preserved', async () => {
const bucket = await buckets.createBucket({ name: 'Test', path: tempBucket, mode: 'inbox' });
// Author a series + an issue locally. Phase B.4: canon lives on the
// linked universe — seed a universe with the character + imageRef so
// the exporter (which walks linked-universe canon) finds the asset.
const uni = await universeSvc.createUniverse({
name: 'Salt Universe',
characters: [{ name: 'Vex', imageRefs: ['fakeasset.png'] }],
});
const s = await series.createSeries({
name: 'Salt Run', logline: 'A foundry city goes silent.', premise: 'The only survivor is a child.',
universeId: uni.id,
});
const iss = await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
// Export.
const exp = await exporter.exportSeries(s.id, bucket.id);
expect(exp.manifestId).toBeTruthy();
expect(exp.recordCount).toBe(3); // series + issue + universe
expect(exp.assetCount).toBeGreaterThanOrEqual(1);
// Verify the bucket layout. v2 stores blobs content-addressed.
expect(existsSync(join(tempBucket, 'manifests', exp.filename))).toBe(true);
expect(existsSync(join(tempBucket, 'records', 'series', `${s.id}.json`))).toBe(true);
expect(existsSync(join(tempBucket, 'records', 'issues', `${iss.id}.json`))).toBe(true);
const fakeHash = sha256Hex(pngBytes('PNGSTUB'));
expect(existsSync(join(tempBucket, 'assets', 'blobs', fakeHash))).toBe(true);
// Process as inbox (the bucket mode is 'inbox'). The manifest should
// queue, not auto-apply.
simulateRemoteSender(tempBucket, exp.filename);
const result = await importer.processManifest(bucket.id, exp.filename);
expect(result.processed).toBe(true);
expect(result.outcome.mode).toBe('inbox');
expect(result.outcome.queued).toBe(true);
// Inbox should have one item.
const inbox = await importer.listInbox(bucket.id);
expect(inbox).toHaveLength(1);
expect(inbox[0].source).toBeTruthy();
// Delete the local series + issue, then promote — the promote path runs
// the auto-merge logic with insertWithId, so ids round-trip.
await series.deleteSeries(s.id);
await issues.deleteIssue(iss.id);
await importer.promoteInboxItem(bucket.id, exp.manifestId);
const restored = await series.getSeries(s.id);
expect(restored.id).toBe(s.id);
expect(restored.name).toBe('Salt Run');
expect(restored.origin).toMatchObject({
bucketId: bucket.id,
manifestId: exp.manifestId,
});
expect(restored.origin.source).toBeTruthy();
const restoredIssue = await issues.getIssue(iss.id);
expect(restoredIssue.id).toBe(iss.id);
expect(restoredIssue.seriesId).toBe(s.id);
expect(restoredIssue.origin).toBeTruthy();
// Asset blob should be back in data/images.
expect(existsSync(join(tempData, 'images', 'fakeasset.png'))).toBe(true);
// Inbox should be empty after promotion.
expect(await importer.listInbox(bucket.id)).toEqual([]);
});
it('auto-merge mode applies records immediately and reports overridden on re-export', async () => {
const bucket = await buckets.createBucket({ name: 'AutoBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Test Series', logline: 'A' });
const exp = await exporter.exportSeries(s.id, bucket.id);
// Drop the local series, then process — auto-merge inserts under preserved id.
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const r1 = await importer.processManifest(bucket.id, exp.filename);
expect(r1.outcome.mode).toBe('auto-merge');
expect(r1.outcome.applied).toBeGreaterThan(0);
expect(r1.outcome.overridden).toEqual([]);
const restored = await series.getSeries(s.id);
expect(restored.id).toBe(s.id);
// Modify the local series so the next export carries a NEWER updatedAt.
await new Promise((r) => setTimeout(r, 5));
await series.updateSeries(s.id, { name: 'Test Series (renamed)' });
// Re-export — manifest carries the newer record.
const exp2 = await exporter.exportSeries(s.id, bucket.id);
// Roll the local copy backwards by a millisecond so the *remote* is newer.
await new Promise((r) => setTimeout(r, 5));
await series.updateSeries(s.id, { name: 'Test Series (renamed)' });
// Force the local updatedAt to be older than the manifest so LWW triggers override.
// (Easiest: mutate the on-disk JSON directly to set an old updatedAt.)
const statePath = join(tempData, 'pipeline-series', s.id, 'index.json');
const state = JSON.parse(readFileSync(statePath, 'utf-8'));
state.updatedAt = '2020-01-01T00:00:00.000Z';
writeFileSync(statePath, JSON.stringify(state, null, 2));
// Process the new manifest — should LWW-override.
simulateRemoteSender(tempBucket, exp2.filename);
const r2 = await importer.processManifest(bucket.id, exp2.filename);
expect(r2.outcome.mode).toBe('auto-merge');
expect(r2.outcome.overridden).toHaveLength(1);
expect(r2.outcome.overridden[0]).toMatchObject({ kind: 'series', id: s.id });
const afterOverride = await series.getSeries(s.id);
expect(afterOverride.name).toBe('Test Series (renamed)');
});
it('round-trips the manuscript review (Finish-the-draft comments) with a series export/import', async () => {
const bucket = await buckets.createBucket({ name: 'ReviewBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Review Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
// Author a review comment (the "Finish the draft" pass output).
await manuscriptReview.seedReviewFromFindings(s.id, [
{ problem: 'Act II sags', severity: 'medium', anchorQuote: 'the long road', issueNumber: 1 },
]);
const before = await manuscriptReview.getReview(s.id);
expect(before.comments).toHaveLength(1);
const exp = await exporter.exportSeries(s.id, bucket.id);
// The review rides under records/reviews/<seriesId>.json, NOT in recordIds.
expect(existsSync(join(tempBucket, 'records', 'reviews', `${s.id}.json`))).toBe(true);
// Drop the local series (removes its folder + review file), then import.
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
await importer.processManifest(bucket.id, exp.filename);
const restored = await manuscriptReview.getReview(s.id);
expect(restored.comments).toHaveLength(1);
expect(restored.comments[0].problem).toBe('Act II sags');
});
it('skips writing a review file when the series has no review comments', async () => {
const bucket = await buckets.createBucket({ name: 'NoReviewBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Empty Review Series', logline: 'A' });
await exporter.exportSeries(s.id, bucket.id);
expect(existsSync(join(tempBucket, 'records', 'reviews', `${s.id}.json`))).toBe(false);
});
it('round-trips the reverse outline with a series export/import', async () => {
const bucket = await buckets.createBucket({ name: 'OutlineBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Outline Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
seedOutline(s.id);
expect((await reverseOutline.getStoredOutline(s.id)).status).toBe('complete');
const exp = await exporter.exportSeries(s.id, bucket.id);
// The outline rides under records/outlines/<seriesId>.json, NOT in recordIds.
expect(existsSync(join(tempBucket, 'records', 'outlines', `${s.id}.json`))).toBe(true);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
await importer.processManifest(bucket.id, exp.filename);
const restored = await reverseOutline.getStoredOutline(s.id);
expect(restored.status).toBe('complete');
expect(restored.scenes[0].summary).toBe('Opening beat');
expect(restored.scenes[0].issueId).toBe('iss-1');
});
it('skips writing an outline file when the series has no complete outline', async () => {
const bucket = await buckets.createBucket({ name: 'NoOutlineBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'No Outline Series', logline: 'A' });
await exporter.exportSeries(s.id, bucket.id);
expect(existsSync(join(tempBucket, 'records', 'outlines', `${s.id}.json`))).toBe(false);
});
it('keeps a manifest pending when a declared outline file has not synced yet (out-of-order delivery)', async () => {
const bucket = await buckets.createBucket({ name: 'OutlineLagBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Outline Lag Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
seedOutline(s.id);
const exp = await exporter.exportSeries(s.id, bucket.id);
const outlineFile = join(tempBucket, 'records', 'outlines', `${s.id}.json`);
expect(existsSync(outlineFile)).toBe(true);
// Manifest + series arrive before the outline file (cloud relay reorders).
const stashed = readFileSync(outlineFile, 'utf-8');
rmSync(outlineFile);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const r1 = await importer.processManifest(bucket.id, exp.filename);
expect(r1.pending).toBe(true);
expect(r1.outcome.pendingOutlines).toContain(s.id);
writeFileSync(outlineFile, stashed);
const r2 = await importer.processManifest(bucket.id, exp.filename);
expect(r2.pending).toBeFalsy();
expect((await reverseOutline.getStoredOutline(s.id)).status).toBe('complete');
});
it('keeps a manifest retryable when the bundled outline merge fails (no silent drop)', async () => {
const bucket = await buckets.createBucket({ name: 'OutlineFailBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Outline Fail Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
seedOutline(s.id);
const exp = await exporter.exportSeries(s.id, bucket.id);
await series.deleteSeries(s.id);
const spy = vi.spyOn(reverseOutline, 'mergeOutlineFromSync').mockRejectedValueOnce(new Error('disk full'));
simulateRemoteSender(tempBucket, exp.filename);
const r1 = await importer.processManifest(bucket.id, exp.filename);
expect(r1.pending).toBe(true);
expect(r1.outcome.pendingOutlineMergeFailures).toContain(s.id);
spy.mockRestore();
const r2 = await importer.processManifest(bucket.id, exp.filename);
expect(r2.pending).toBeFalsy();
expect((await reverseOutline.getStoredOutline(s.id)).status).toBe('complete');
});
it('keeps a manifest pending when a declared review file has not synced yet (out-of-order delivery)', async () => {
const bucket = await buckets.createBucket({ name: 'ReviewLagBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Review Lag Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
await manuscriptReview.seedReviewFromFindings(s.id, [
{ problem: 'Act II sags', severity: 'medium', anchorQuote: 'the road', issueNumber: 1 },
]);
const exp = await exporter.exportSeries(s.id, bucket.id);
const reviewFile = join(tempBucket, 'records', 'reviews', `${s.id}.json`);
expect(existsSync(reviewFile)).toBe(true);
// Simulate the manifest + series arriving before the review file (cloud
// relay delivers files out of order): stash the review file aside.
const stashed = readFileSync(reviewFile, 'utf-8');
rmSync(reviewFile);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const r1 = await importer.processManifest(bucket.id, exp.filename);
// The manifest declared the review (reviewRefs), so the importer must wait
// — NOT markProcessed and drop it.
expect(r1.pending).toBe(true);
expect(r1.outcome.pendingReviews).toContain(s.id);
// The review file lands → reprocess → it merges.
writeFileSync(reviewFile, stashed);
const r2 = await importer.processManifest(bucket.id, exp.filename);
expect(r2.pending).toBeFalsy();
const restored = await manuscriptReview.getReview(s.id);
expect(restored.comments).toHaveLength(1);
});
it('ignores a stale review file the manifest did not declare (no resurrection of cleared comments)', async () => {
const bucket = await buckets.createBucket({ name: 'StaleReviewBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Stale Review Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
// Export with NO review → manifest declares reviewRefs: [] and writes no file.
const exp = await exporter.exportSeries(s.id, bucket.id);
// Simulate a lingering stale review file from an earlier export (the
// exporter writes but never deletes review files).
mkdirSync(join(tempBucket, 'records', 'reviews'), { recursive: true });
writeFileSync(
join(tempBucket, 'records', 'reviews', `${s.id}.json`),
JSON.stringify({ schemaVersion: 1, comments: [{ id: 'mrc-stale', problem: 'old note', status: 'open', updatedAt: '2026-06-02T00:00:00Z' }] }),
);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
await importer.processManifest(bucket.id, exp.filename);
// The manifest declared no review, so the lingering file must NOT be merged.
const after = await manuscriptReview.getReview(s.id);
expect(after.comments).toHaveLength(0);
});
it('keeps a manifest pending when a declared review file is present but unparseable', async () => {
const bucket = await buckets.createBucket({ name: 'CorruptReviewBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Corrupt Review Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
await manuscriptReview.seedReviewFromFindings(s.id, [
{ problem: 'Act II sags', severity: 'medium', anchorQuote: 'the road', issueNumber: 1 },
]);
const exp = await exporter.exportSeries(s.id, bucket.id);
const reviewFile = join(tempBucket, 'records', 'reviews', `${s.id}.json`);
const good = readFileSync(reviewFile, 'utf-8');
// Simulate a half-synced (truncated) file: present on disk but not valid JSON.
writeFileSync(reviewFile, good.slice(0, Math.floor(good.length / 2)));
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const r1 = await importer.processManifest(bucket.id, exp.filename);
expect(r1.pending).toBe(true);
expect(r1.outcome.pendingReviews).toContain(s.id);
// The full file finishes syncing → reprocess → it merges.
writeFileSync(reviewFile, good);
const r2 = await importer.processManifest(bucket.id, exp.filename);
expect(r2.pending).toBeFalsy();
expect((await manuscriptReview.getReview(s.id)).comments).toHaveLength(1);
});
it('promoteInboxItem keeps the inbox row when the bundled review merge fails', async () => {
const bucket = await buckets.createBucket({ name: 'PromoteFailBucket', path: tempBucket, mode: 'inbox' });
const s = await series.createSeries({ name: 'Promote Fail Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
await manuscriptReview.seedReviewFromFindings(s.id, [
{ problem: 'Act II sags', severity: 'medium', anchorQuote: 'the road', issueNumber: 1 },
]);
const exp = await exporter.exportSeries(s.id, bucket.id);
simulateRemoteSender(tempBucket, exp.filename);
await importer.processManifest(bucket.id, exp.filename); // queues to inbox
expect(await importer.listInbox(bucket.id)).toHaveLength(1);
// Force a transient review-merge failure during the manual promote.
const spy = vi.spyOn(manuscriptReview, 'mergeReviewFromSync').mockRejectedValueOnce(new Error('disk full'));
await expect(importer.promoteInboxItem(bucket.id, exp.manifestId)).rejects.toMatchObject({
code: 'SHARING_REVIEW_MERGE_FAILED',
});
spy.mockRestore();
// Inbox row preserved so the user can re-promote.
expect(await importer.listInbox(bucket.id)).toHaveLength(1);
// Re-promote now succeeds and the review lands.
await importer.promoteInboxItem(bucket.id, exp.manifestId);
expect((await manuscriptReview.getReview(s.id)).comments).toHaveLength(1);
});
it('promoteInboxItem keeps the inbox row when the bundled outline merge fails', async () => {
const bucket = await buckets.createBucket({ name: 'PromoteOutlineFailBucket', path: tempBucket, mode: 'inbox' });
const s = await series.createSeries({ name: 'Promote Outline Fail Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
seedOutline(s.id);
const exp = await exporter.exportSeries(s.id, bucket.id);
simulateRemoteSender(tempBucket, exp.filename);
await importer.processManifest(bucket.id, exp.filename); // queues to inbox
expect(await importer.listInbox(bucket.id)).toHaveLength(1);
// Force a transient outline-merge failure during the manual promote.
const spy = vi.spyOn(reverseOutline, 'mergeOutlineFromSync').mockRejectedValueOnce(new Error('disk full'));
await expect(importer.promoteInboxItem(bucket.id, exp.manifestId)).rejects.toMatchObject({
code: 'SHARING_OUTLINE_MERGE_FAILED',
});
spy.mockRestore();
// Inbox row preserved so the user can re-promote.
expect(await importer.listInbox(bucket.id)).toHaveLength(1);
// Re-promote now succeeds and the outline lands.
await importer.promoteInboxItem(bucket.id, exp.manifestId);
expect((await reverseOutline.getStoredOutline(s.id)).status).toBe('complete');
});
it('keeps a manifest retryable when the bundled review merge fails (no silent drop)', async () => {
const bucket = await buckets.createBucket({ name: 'ReviewFailBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Review Fail Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
await manuscriptReview.seedReviewFromFindings(s.id, [
{ problem: 'Act II sags', severity: 'medium', anchorQuote: 'the road', issueNumber: 1 },
]);
const exp = await exporter.exportSeries(s.id, bucket.id);
await series.deleteSeries(s.id);
// Force a transient review-merge failure on the FIRST import attempt.
const spy = vi.spyOn(manuscriptReview, 'mergeReviewFromSync').mockRejectedValueOnce(new Error('disk full'));
simulateRemoteSender(tempBucket, exp.filename);
const r1 = await importer.processManifest(bucket.id, exp.filename);
// Manifest stays pending (cursor un-advanced) so the watcher retries —
// the review is NOT silently dropped.
expect(r1.pending).toBe(true);
expect(r1.outcome.pendingReviewMergeFailures).toContain(s.id);
spy.mockRestore();
// Re-process (manifest was kept retryable) — now the review lands.
const r2 = await importer.processManifest(bucket.id, exp.filename);
expect(r2.pending).toBeFalsy();
const restored = await manuscriptReview.getReview(s.id);
expect(restored.comments).toHaveLength(1);
});
it('a remote orphan series (universeId null) preserves the local universe link instead of aborting the import', async () => {
const bucket = await buckets.createBucket({ name: 'OrphanLinkBucket', path: tempBucket, mode: 'auto-merge' });
const u = await universeSvc.createUniverse({ name: 'Linked Universe' });
const s = await series.createSeries({ name: 'Linked Series', universeId: u.id });
const exp = await exporter.exportSeries(s.id, bucket.id);
// Rewrite the exported series record to look like an ORPHAN (no universeId)
// with a newer updatedAt — mimics an older/cleared peer. Before the fix this
// tripped updateSeries's "cannot unlink" guard and threw, aborting the whole
// manifest import; now the importer preserves the local link.
const seriesRecPath = join(tempBucket, 'records', 'series', `${s.id}.json`);
const rec = JSON.parse(readFileSync(seriesRecPath, 'utf-8'));
rec.universeId = null;
rec.updatedAt = '2999-01-01T00:00:00.000Z';
writeFileSync(seriesRecPath, JSON.stringify(rec, null, 2));
simulateRemoteSender(tempBucket, exp.filename);
const r = await importer.processManifest(bucket.id, exp.filename);
expect(r.processed).toBe(true);
expect(r.outcome.recordImportFailures).toBeFalsy();
// Link preserved (not unlinked), and the series survived the import.
const after = await series.getSeries(s.id);
expect(after.universeId).toBe(u.id);
});
it('seeds a conflict-journal base hash when a series is first imported (so its first divergence is journaled)', async () => {
const bucket = await buckets.createBucket({ name: 'BaseSeedBucket', path: tempBucket, mode: 'auto-merge' });
const u = await universeSvc.createUniverse({ name: 'Seed Universe' });
const s = await series.createSeries({ name: 'Seed Series', universeId: u.id });
const exp = await exporter.exportSeries(s.id, bucket.id);
// Drop the local copy so the import is a fresh INSERT (the branch that
// previously skipped base-hash seeding).
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
await importer.processManifest(bucket.id, exp.filename);
const baseHashPath = join(tempData, 'sharing', 'sync_base_hashes.json');
const baseHashes = JSON.parse(readFileSync(baseHashPath, 'utf-8'));
expect(baseHashes[`series:${s.id}`]).toBeTruthy();
});
it('re-importing the same manifest is a no-op (cursor dedup)', async () => {
const bucket = await buckets.createBucket({ name: 'D', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'X' });
const exp = await exporter.exportSeries(s.id, bucket.id);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const r1 = await importer.processManifest(bucket.id, exp.filename);
expect(r1.processed).toBe(true);
const r2 = await importer.processManifest(bucket.id, exp.filename);
expect(r2.skipped).toBe(true);
expect(r2.reason).toBe('already-processed');
});
it('universe export bundles the linked collection — recipient gains the items', async () => {
const bucket = await buckets.createBucket({ name: 'CollabBucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const mediaCollections = await import('../mediaCollections.js');
const u = await universeBuilder.createUniverse({ name: 'Linked Universe' });
// Pretend universe-builder rendered two images and filed them into a
// collection. Each item.ref points at a real file in tempData/images
// (we seeded 'fakeasset.png' in beforeEach, but for variety, add another).
const fs = await import('fs');
fs.writeFileSync(join(tempData, 'images', 'second.png'), pngBytes('PNG2'));
const collection = await mediaCollections.findOrCreateCollectionByName({
name: `Universe: ${u.name}`, description: 'Linked', universeId: u.id,
});
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'fakeasset.png' });
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'second.png' });
// Export the universe — manifest should carry the collection payload
// and assets should land in the bucket.
const exp = await exporter.exportUniverse(u.id, bucket.id);
expect(exp.assetCount).toBeGreaterThanOrEqual(2);
const manifestFile = exp.filename;
const manifest = JSON.parse(fs.readFileSync(join(tempBucket, 'manifests', manifestFile), 'utf-8'));
expect(manifest.collection).toMatchObject({ universeId: u.id });
expect(manifest.collection.items).toHaveLength(2);
expect(fs.existsSync(join(tempBucket, 'assets', 'blobs', sha256Hex(pngBytes('PNG2'))))).toBe(true);
// Drop the local collection + universe, then re-process: the importer
// should recreate both, find-or-create the local collection by
// universeId, and merge the items in.
await mediaCollections.deleteCollection(collection.id);
await universeBuilder.deleteUniverse(u.id);
expect((await mediaCollections.listCollections()).find((c) => c.universeId === u.id)).toBeUndefined();
simulateRemoteSender(tempBucket, manifestFile);
const r = await importer.processManifest(bucket.id, manifestFile);
expect(r.processed).toBe(true);
expect(r.outcome.collectionItemsAdded).toBe(2);
const localCollections = await mediaCollections.listCollections();
const restoredCollection = localCollections.find((c) => c.universeId === u.id);
expect(restoredCollection).toBeTruthy();
expect(restoredCollection.items.map((i) => i.ref).sort()).toEqual(['fakeasset.png', 'second.png']);
// Asset blobs are back in the local data/images pool.
expect(fs.existsSync(join(tempData, 'images', 'second.png'))).toBe(true);
});
it('series export bundles the per-series collection when the series has no universe', async () => {
// A series without a universeId — covers auto-file into a per-series
// "Series: <name>" collection (mediaCollections.seriesId stamp) and the
// exporter must bundle that into manifest.collection so the recipient
// sees the same covers alongside the series record.
const bucket = await buckets.createBucket({ name: 'SeriesCollBucket', path: tempBucket, mode: 'auto-merge' });
const mediaCollections = await import('../mediaCollections.js');
const s = await series.createSeries({ name: 'Indie Saga', logline: 'L' });
const fs = await import('fs');
fs.writeFileSync(join(tempData, 'images', 'cover-a.png'), pngBytes('COVA'));
fs.writeFileSync(join(tempData, 'images', 'cover-b.png'), pngBytes('COVB'));
const collection = await mediaCollections.findOrCreateSeriesCollection({
seriesId: s.id, seriesName: s.name,
});
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'cover-a.png' });
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'cover-b.png' });
// Export — manifest must carry the seriesId-keyed collection payload.
const exp = await exporter.exportSeries(s.id, bucket.id);
const manifest = JSON.parse(fs.readFileSync(join(tempBucket, 'manifests', exp.filename), 'utf-8'));
expect(manifest.collection).toMatchObject({ seriesId: s.id });
expect(manifest.collection.universeId).toBeUndefined();
expect(manifest.collection.items.map((i) => i.ref).sort()).toEqual(['cover-a.png', 'cover-b.png']);
expect(fs.existsSync(join(tempBucket, 'assets', 'blobs', sha256Hex(pngBytes('COVA'))))).toBe(true);
expect(fs.existsSync(join(tempBucket, 'assets', 'blobs', sha256Hex(pngBytes('COVB'))))).toBe(true);
// Drop the local collection + series, then re-process: importer
// restores the series and find-or-creates the local per-series
// collection by seriesId, unioning the items in.
await mediaCollections.deleteCollection(collection.id);
await series.deleteSeries(s.id);
expect((await mediaCollections.listCollections()).find((c) => c.seriesId === s.id)).toBeUndefined();
simulateRemoteSender(tempBucket, exp.filename);
const r = await importer.processManifest(bucket.id, exp.filename);
expect(r.processed).toBe(true);
expect(r.outcome.collectionItemsAdded).toBe(2);
const localCollections = await mediaCollections.listCollections();
const restored = localCollections.find((c) => c.seriesId === s.id);
expect(restored).toBeTruthy();
expect(restored.name).toBe('Series: Indie Saga');
expect(restored.items.map((i) => i.ref).sort()).toEqual(['cover-a.png', 'cover-b.png']);
// Asset blobs are back in the local data/images pool.
expect(fs.existsSync(join(tempData, 'images', 'cover-a.png'))).toBe(true);
expect(fs.existsSync(join(tempData, 'images', 'cover-b.png'))).toBe(true);
});
it('series export prefers the universe-linked collection when both exist', async () => {
// A series can in principle be linked to a universe (universe-owned
// collection) AND have a stray per-series collection (e.g. from a
// prior universeless phase). The exporter prefers the universe one
// since it represents the canonical bucket for that universe.
const bucket = await buckets.createBucket({ name: 'BothBucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const mediaCollections = await import('../mediaCollections.js');
const u = await universeBuilder.createUniverse({ name: 'Linked' });
const s = await series.createSeries({ name: 'Series', universeId: u.id });
const fs = await import('fs');
fs.writeFileSync(join(tempData, 'images', 'uni.png'), pngBytes('UNI'));
fs.writeFileSync(join(tempData, 'images', 'ser.png'), pngBytes('SER'));
const uniColl = await mediaCollections.findOrCreateUniverseCollection({
universeId: u.id, universeName: u.name,
});
await mediaCollections.addItem(uniColl.id, { kind: 'image', ref: 'uni.png' });
const serColl = await mediaCollections.findOrCreateSeriesCollection({
seriesId: s.id, seriesName: s.name,
});
await mediaCollections.addItem(serColl.id, { kind: 'image', ref: 'ser.png' });
const exp = await exporter.exportSeries(s.id, bucket.id);
const manifest = JSON.parse(fs.readFileSync(join(tempBucket, 'manifests', exp.filename), 'utf-8'));
expect(manifest.collection).toMatchObject({ universeId: u.id });
expect(manifest.collection.items.map((i) => i.ref)).toEqual(['uni.png']);
});
it('linked series never falls through to a stray seriesId-stamped collection', async () => {
// A series can be linked to a universe AND have a stray per-series
// collection from a prior universeless phase (or an orphan after
// `unlinkCollectionsForUniverse` recovery). When the universe-linked
// collection happens to be absent at export time (mid-migration, or
// a manual deletion), the exporter must NOT silently fall back to the
// stale seriesId-stamped collection — linked series export under the
// universe-collection contract or no collection payload at all.
const bucket = await buckets.createBucket({ name: 'LinkedNoUniColl', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const mediaCollections = await import('../mediaCollections.js');
const u = await universeBuilder.createUniverse({ name: 'CanonOnly' });
const s = await series.createSeries({ name: 'Bound', universeId: u.id });
const fs = await import('fs');
fs.writeFileSync(join(tempData, 'images', 'stale.png'), pngBytes('STALE'));
// Stamp a seriesId collection directly (simulating a leftover from a
// prior universeless phase). No universe collection exists.
const serColl = await mediaCollections.findOrCreateSeriesCollection({
seriesId: s.id, seriesName: s.name,
});
await mediaCollections.addItem(serColl.id, { kind: 'image', ref: 'stale.png' });
expect(await mediaCollections.findCollectionByUniverseId(u.id)).toBeNull();
const exp = await exporter.exportSeries(s.id, bucket.id);
const manifest = JSON.parse(fs.readFileSync(join(tempBucket, 'manifests', exp.filename), 'utf-8'));
// No collection payload — the stale seriesId bucket was correctly ignored.
expect(manifest.collection).toBeNull();
});
it('series collection import re-routes to the universe collection when the local series is now universe-linked', async () => {
// Peer's manifest was produced when the series was universeless (so it
// carries `collection.seriesId`), but the local series has since been
// linked to a universe. Importer must NOT mint a fresh seriesId-stamped
// collection — that would leave a rename-locked stale per-series bucket
// attached to a linked series, breaking the contract the exporter and
// cover filer enforce. Re-route the payload into the universe collection.
const bucket = await buckets.createBucket({ name: 'StaleSeriesPayload', path: tempBucket, mode: 'auto-merge' });
const mediaCollections = await import('../mediaCollections.js');
const universeBuilder = await import('../universeBuilder.js');
const fs = await import('fs');
// Sender side: universeless series + per-series collection with one cover.
const s = await series.createSeries({ name: 'WillLink', logline: 'L' });
fs.writeFileSync(join(tempData, 'images', 'stale-cover.png'), pngBytes('STALE'));
const senderColl = await mediaCollections.findOrCreateSeriesCollection({
seriesId: s.id, seriesName: s.name,
});
await mediaCollections.addItem(senderColl.id, { kind: 'image', ref: 'stale-cover.png' });
const exp = await exporter.exportSeries(s.id, bucket.id);
// Now (still on the sender — same env, simpler test setup) link the
// series to a universe and drop the per-series collection. The "local"
// state from the importer's perspective is: linked series, no per-series
// collection. Recipient re-applies the manifest.
const u = await universeBuilder.createUniverse({ name: 'NewCanon' });
await series.updateSeries(s.id, { universeId: u.id });
await mediaCollections.deleteCollection(senderColl.id);
simulateRemoteSender(tempBucket, exp.filename);
const r = await importer.processManifest(bucket.id, exp.filename);
expect(r.processed).toBe(true);
expect(r.outcome.collectionItemsAdded).toBe(1);
// The cover landed in the UNIVERSE collection, not a new seriesId bucket.
const universeColl = await mediaCollections.findCollectionByUniverseId(u.id);
expect(universeColl).toBeTruthy();
expect(universeColl.items.map((i) => i.ref)).toEqual(['stale-cover.png']);
// No seriesId-stamped collection exists for the now-linked series.
expect(await mediaCollections.findCollectionBySeriesId(s.id)).toBeNull();
});
it('series collection import defers when the local series is missing', async () => {
// Mirrors the universe-pending case: the manifest references a
// seriesId we haven't imported locally. The cursor must stay
// un-advanced so a later sync of the series unblocks the merge.
const bucket = await buckets.createBucket({ name: 'DeferBucket', path: tempBucket, mode: 'auto-merge' });
const mediaCollections = await import('../mediaCollections.js');
const s = await series.createSeries({ name: 'Will Vanish' });
const fs = await import('fs');
fs.writeFileSync(join(tempData, 'images', 'late-cover.png'), pngBytes('LATE'));
const collection = await mediaCollections.findOrCreateSeriesCollection({
seriesId: s.id, seriesName: s.name,
});
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'late-cover.png' });
const exp = await exporter.exportSeries(s.id, bucket.id);
// Delete the series locally so the importer sees an orphaned payload.
await mediaCollections.deleteCollection(collection.id);
await series.deleteSeries(s.id);
// Also drop the series record from the bucket so insertSeriesWithId
// doesn't restore it — this isolates the "collection waits on series"
// case rather than "round-trip restores everything."
fs.rmSync(join(tempBucket, 'records', 'series', `${s.id}.json`), { force: true });
simulateRemoteSender(tempBucket, exp.filename);
const r = await importer.processManifest(bucket.id, exp.filename);
expect(r.pending).toBe(true);
expect(r.outcome.pendingCollectionSeries).toBe(s.id);
});
it('universe export ignores a same-named unlinked collection (universeId-only routing)', async () => {
// Round-9 review caught that the exporter's old "fall back to name
// match" path could pick up a post-deleteUniverse orphan and ship it
// out under a new same-named universe. The runtime fallback is gone;
// the upgrade path for genuinely-legacy installs is migration 021
// (which runs at boot, before any exporter call). This test pins the
// new contract.
const bucket = await buckets.createBucket({ name: 'LegacyBucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const mediaCollections = await import('../mediaCollections.js');
const u = await universeBuilder.createUniverse({ name: 'Post-Epoc' });
const fs = await import('fs');
fs.writeFileSync(join(tempData, 'images', 'legacy.png'), pngBytes('PNG'));
// Unlinked collection with the conventional name — exporter must NOT
// adopt this for the universe.
const orphan = await mediaCollections.createCollection({
name: `Universe: ${u.name}`,
description: 'Legacy unlinked collection',
});
await mediaCollections.addItem(orphan.id, { kind: 'image', ref: 'legacy.png' });
const exp = await exporter.exportUniverse(u.id, bucket.id);
const manifest = JSON.parse(fs.readFileSync(join(tempBucket, 'manifests', exp.filename), 'utf-8'));
// No collection payload in the manifest — the universe had no
// universeId-linked collection.
expect(manifest.collection).toBeFalsy();
});
it('keeps universe manifests retryable while Drive assets are still syncing', async () => {
const bucket = await buckets.createBucket({ name: 'SlowDriveBucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const mediaCollections = await import('../mediaCollections.js');
const { readCursor, hasBeenProcessed } = await import('./manifest.js');
const u = await universeBuilder.createUniverse({ name: 'Slow Sync Universe' });
const fs = await import('fs');
fs.writeFileSync(join(tempData, 'images', 'late.png'), pngBytes('LATEPNG'));
const collection = await mediaCollections.findOrCreateCollectionByName({
name: `Universe: ${u.name}`, description: 'Linked', universeId: u.id,
});
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'fakeasset.png' });
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'late.png' });
const exp = await exporter.exportUniverse(u.id, bucket.id);
const lateHash = sha256Hex(pngBytes('LATEPNG'));
fs.rmSync(join(tempBucket, 'assets', 'blobs', lateHash), { force: true });
fs.rmSync(join(tempData, 'images', 'late.png'), { force: true });
await mediaCollections.deleteCollection(collection.id);
await universeBuilder.deleteUniverse(u.id);
simulateRemoteSender(tempBucket, exp.filename);
const first = await importer.processManifest(bucket.id, exp.filename);
expect(first.pending).toBe(true);
expect(first.outcome.pendingAssets).toEqual([{ kind: 'image', ref: 'late.png' }]);
expect(first.outcome.collectionItemsAdded).toBe(1);
expect(first.outcome.collectionItemsDeferred).toBe(1);
let restoredCollection = (await mediaCollections.listCollections()).find((c) => c.universeId === u.id);
expect(restoredCollection.items.map((i) => i.ref)).toEqual(['fakeasset.png']);
let cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(false);
fs.writeFileSync(join(tempBucket, 'assets', 'blobs', lateHash), pngBytes('LATEPNG'));
const retry = await importer.processBacklog(bucket.id);
expect(retry.processed).toBe(1);
restoredCollection = (await mediaCollections.listCollections()).find((c) => c.universeId === u.id);
expect(restoredCollection.items.map((i) => i.ref).sort()).toEqual(['fakeasset.png', 'late.png']);
expect(fs.existsSync(join(tempData, 'images', 'late.png'))).toBe(true);
cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(true);
});
it('keeps universe manifests retryable while the record JSON itself is still syncing', async () => {
const bucket = await buckets.createBucket({ name: 'SlowRecordBucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const { readCursor, hasBeenProcessed } = await import('./manifest.js');
const u = await universeBuilder.createUniverse({ name: 'Late Record Universe' });
const exp = await exporter.exportUniverse(u.id, bucket.id);
simulateRemoteSender(tempBucket, exp.filename);
// Simulate Drive delivering the manifest before the record JSON syncs.
const fs = await import('fs');
const recordPath = join(tempBucket, 'records', 'universes', `${u.id}.json`);
const recordSnapshot = fs.readFileSync(recordPath);
fs.rmSync(recordPath, { force: true });
await universeBuilder.deleteUniverse(u.id);
const first = await importer.processManifest(bucket.id, exp.filename);
expect(first.pending).toBe(true);
expect(first.outcome.pendingRecords).toEqual([u.id]);
let cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(false);
await expect(universeBuilder.getUniverse(u.id)).rejects.toThrow();
// Record JSON finally syncs — retry should insert + mark processed.
fs.writeFileSync(recordPath, recordSnapshot);
const retry = await importer.processBacklog(bucket.id);
expect(retry.processed).toBe(1);
const restored = await universeBuilder.getUniverse(u.id);
expect(restored.name).toBe('Late Record Universe');
cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(true);
});
it('keeps a manifest retryable (does not advance the cursor) when a record insert fails unexpectedly', async () => {
// A non-duplicate insert failure (disk error, transient fs error) must NOT
// advance the cursor — otherwise the manifest is marked processed and the
// record is silently dropped. It must stay pending and retry.
const bucket = await buckets.createBucket({ name: 'InsertFailBucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const { readCursor, hasBeenProcessed } = await import('./manifest.js');
const u = await universeBuilder.createUniverse({ name: 'Fails To Insert Once' });
const exp = await exporter.exportUniverse(u.id, bucket.id);
simulateRemoteSender(tempBucket, exp.filename);
await universeBuilder.deleteUniverse(u.id);
// Force the first insert to throw a non-duplicate error (not a *_DUPLICATE).
const spy = vi.spyOn(universeBuilder, 'insertUniverseWithId')
.mockRejectedValueOnce(new Error('simulated transient disk failure'));
const first = await importer.processManifest(bucket.id, exp.filename);
expect(first.pending).toBe(true);
expect(first.outcome.pendingRecordImportFailures).toEqual([`universe:${u.id}`]);
let cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(false);
await expect(universeBuilder.getUniverse(u.id)).rejects.toThrow();
// Insert succeeds on retry → manifest finally marked processed.
spy.mockRestore();
const retry = await importer.processBacklog(bucket.id);
expect(retry.processed).toBe(1);
const restored = await universeBuilder.getUniverse(u.id);
expect(restored.name).toBe('Fails To Insert Once');
cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(true);
});
it('keeps series manifests retryable while issue record files are still syncing', async () => {
const bucket = await buckets.createBucket({ name: 'SlowIssueSync', path: tempBucket, mode: 'auto-merge' });
const { readCursor, hasBeenProcessed } = await import('./manifest.js');
const s = await series.createSeries({ name: 'Drifts a Bit Late' });
const issA = await issues.createIssue({ seriesId: s.id, title: 'Arrives on Time' });
const issB = await issues.createIssue({ seriesId: s.id, title: 'Arrives Later' });
const exp = await exporter.exportSeries(s.id, bucket.id);
expect(exp.recordCount).toBe(3); // series + 2 issues
// Simulate Drive having synced the manifest + series + issA but not yet issB.
const fs = await import('fs');
const issBPath = join(tempBucket, 'records', 'issues', `${issB.id}.json`);
expect(fs.existsSync(issBPath)).toBe(true);
fs.rmSync(issBPath, { force: true });
// Drop local copies so the importer has to insert from the bucket.
await issues.deleteIssue(issA.id);
await issues.deleteIssue(issB.id);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const first = await importer.processManifest(bucket.id, exp.filename);
expect(first.pending).toBe(true);
expect(first.outcome.pendingRecords).toEqual([issB.id]);
expect(first.outcome.pendingAssets).toBeUndefined();
// The records that DID arrive should be applied — the late one stays absent.
const restoredA = await issues.getIssue(issA.id);
expect(restoredA.title).toBe('Arrives on Time');
await expect(issues.getIssue(issB.id)).rejects.toMatchObject({ code: 'PIPELINE_ISSUE_NOT_FOUND' });
let cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(false);
// Late-arriving record file → backlog retry completes the import.
fs.writeFileSync(issBPath, JSON.stringify({
id: issB.id, seriesId: s.id, title: 'Arrives Later', number: 2,
status: 'draft', stages: {},
createdAt: issB.createdAt, updatedAt: issB.updatedAt,
}));
const retry = await importer.processBacklog(bucket.id);
expect(retry.processed).toBe(1);
const restoredB = await issues.getIssue(issB.id);
expect(restoredB.title).toBe('Arrives Later');
cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(true);
});
it('createIssue emits recordUpdated so series subscriptions re-export', async () => {
const { recordEvents } = await import('./recordEvents.js');
const s = await series.createSeries({ name: 'Emits On Create' });
const events = [];
const onUpdated = (p) => events.push(p);
recordEvents.on('updated', onUpdated);
try {
const iss = await issues.createIssue({ seriesId: s.id, title: 'First Issue' });
expect(events).toContainEqual({ recordKind: 'series', recordId: s.id });
expect(iss.seriesId).toBe(s.id);
} finally {
recordEvents.off('updated', onUpdated);
}
});
it('subscription round-trip: subscribe → mutate → re-export onto same filename → unsubscribe → unshared event', async () => {
const { subscribe, unsubscribe, subscriptionFilename, __resetForTests } = await import('./subscriptions.js');
const { sharingEvents } = await import('./importer.js');
__resetForTests();
const bucket = await buckets.createBucket({ name: 'SubBucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'Sub Universe' });
// Subscribe — first export writes a deterministic-named file.
const sub = await subscribe({ bucketId: bucket.id, recordKind: 'universe', recordId: u.id });
const filename = subscriptionFilename({ ...sub, senderInstanceId: 'test-instance-id' });
const filePath = join(tempBucket, 'manifests', filename);
const fs = await import('fs');
expect(fs.existsSync(filePath)).toBe(true);
const first = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
expect(first.subscription).toMatchObject({ recordKind: 'universe', recordId: u.id });
const firstManifestId = first.id;
// Mutate the universe — emit fires recordEvents which schedules a re-export.
// For the test, bypass the 3s debounce by calling subscribe again (idempotent).
await universeBuilder.updateUniverse(u.id, { starterPrompt: 'updated prompt' });
await subscribe({ bucketId: bucket.id, recordKind: 'universe', recordId: u.id }); // forces immediate re-export
const second = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
expect(second.id).not.toBe(firstManifestId);
// Importer's cursor logic dedups by manifest id, so a re-import of the
// updated file is recognized as new content.
const r1 = await importer.processManifest(bucket.id, filename);
expect(r1.processed || r1.skipped).toBeTruthy();
// Unsubscribe — deletes the file. Watcher's `unlink` calls handleUnshare
// (here we invoke it directly since chokidar is not running in tests).
const events = [];
const onUnshared = (p) => events.push(p);
sharingEvents.on('unshared', onUnshared);
await unsubscribe(sub.id);
expect(fs.existsSync(filePath)).toBe(false);
await importer.handleUnshare(bucket.id, filename);
sharingEvents.off('unshared', onUnshared);
expect(events).toHaveLength(1);
expect(events[0]).toMatchObject({ bucketId: bucket.id, manifestFilename: filename });
// Local imported universe should NOT have been removed — unshare doesn't
// reverse the import on the recipient. The universe still exists locally.
const stillThere = await universeBuilder.getUniverse(u.id);
expect(stillThere.id).toBe(u.id);
});
it('inbox dedup keeps newer per-sender row when older legacy file processes after it (upgrade scenario)', async () => {
// During the v1→v2 upgrade a bucket may briefly hold both the new
// `sub-<kind>-<id>-<sender>.json` and the legacy `sub-<kind>-<id>.json`
// for the same sender. Lexicographic backlog order visits the new file
// (with `-`) before the legacy file (with `.`), so without a freshness
// gate the older legacy manifest would clobber the newer inbox row.
const bucket = await buckets.createBucket({ name: 'UpgradeBucket', path: tempBucket, mode: 'inbox' });
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'U-upgrade' });
const manifestsDir = join(tempBucket, 'manifests');
mkdirSync(manifestsDir, { recursive: true });
// Hand-craft both manifests for the same (universe, sender) pair. The
// legacy file is OLDER (5 minutes earlier) and uses the pre-v2 name.
// The per-sender file is NEWER and uses the v2 name.
const olderTs = '2026-01-01T00:00:00.000Z';
const newerTs = '2026-01-01T00:05:00.000Z';
const baseManifest = {
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
kind: 'universe',
subscription: { recordKind: 'universe', recordId: u.id },
senderInstanceId: 'remote-peer-id',
source: 'remote peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [u.id],
assetRefs: [],
collection: null,
note: null,
};
const legacyName = `sub-universe-${u.id}.json`;
const perSenderName = `sub-universe-${u.id}-remote-peer-id.json`;
writeFileSync(join(manifestsDir, legacyName), JSON.stringify({
...baseManifest, id: 'mfst-legacy-old', createdAt: olderTs,
}));
writeFileSync(join(manifestsDir, perSenderName), JSON.stringify({
...baseManifest, id: 'mfst-per-sender-new', createdAt: newerTs,
}));
// Sanity: lex-sort puts the per-sender file first, legacy after — this is
// the order the importer's backlog scan walks the directory in.
expect([legacyName, perSenderName].sort()).toEqual([perSenderName, legacyName]);
// Mirror records/ so processManifest can locate the universe payload.
mkdirSync(join(tempBucket, 'records', 'universes'), { recursive: true });
writeFileSync(
join(tempBucket, 'records', 'universes', `${u.id}.json`),
JSON.stringify({ ...u, updatedAt: newerTs }),
);
const r1 = await importer.processManifest(bucket.id, perSenderName);
expect(r1.processed).toBe(true);
const r2 = await importer.processManifest(bucket.id, legacyName);
// The older legacy manifest should NOT replace the newer inbox row.
expect(r2.outcome?.queued).toBe(false);
expect(r2.outcome?.reason).toBe('inbox-has-newer');
const finalInbox = await importer.listInbox(bucket.id);
expect(finalInbox).toHaveLength(1);
expect(finalInbox[0].manifestId).toBe('mfst-per-sender-new');
expect(finalInbox[0].createdAt).toBe(newerTs);
});
it('adopts an imported universe subscription so the source bucket is selected for sharing', async () => {
const { listSubscriptions, subscriptionFilename, __resetForTests } = await import('./subscriptions.js');
__resetForTests();
const bucket = await buckets.createBucket({ name: 'CollabBucket', path: tempBucket, mode: 'auto-merge' });
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'Shared Universe' });
const exp = await exporter.exportUniverse(u.id, bucket.id, {
subscription: { recordKind: 'universe', recordId: u.id },
});
expect(exp.filename).toBe(subscriptionFilename({
recordKind: 'universe', recordId: u.id, senderInstanceId: 'test-instance-id',
}));
await universeBuilder.deleteUniverse(u.id);
expect(await listSubscriptions({ recordKind: 'universe', recordId: u.id })).toEqual([]);
simulateRemoteSender(tempBucket, exp.filename);
const result = await importer.processManifest(bucket.id, exp.filename);
expect(result.processed).toBe(true);
expect(result.outcome.adoptedSubscription).toMatchObject({
bucketId: bucket.id,
recordKind: 'universe',
recordId: u.id,
});
const restored = await universeBuilder.getUniverse(u.id);
expect(restored.id).toBe(u.id);
const subs = await listSubscriptions({ recordKind: 'universe', recordId: u.id });
expect(subs).toHaveLength(1);
expect(subs[0]).toMatchObject({
bucketId: bucket.id,
recordKind: 'universe',
recordId: u.id,
adoptedFromImport: true,
lastManifestId: exp.manifestId,
});
expect(subs[0].lastExportedAt).toBe(null);
});
it('skips self-authored manifests on import and prunes pre-existing self-authored inbox items', async () => {
const { sharingEvents } = await import('./importer.js');
const bucket = await buckets.createBucket({ name: 'SelfBucket', path: tempBucket, mode: 'inbox' });
// Author + export a series locally — the manifest is dropped into our own bucket.
const s = await series.createSeries({ name: 'Mine', logline: 'Local-only' });
const exp = await exporter.exportSeries(s.id, bucket.id);
expect(exp.manifestId).toBeTruthy();
// The watcher would now pick the manifest up. Process it manually and
// verify it never enters the inbox — `senderInstanceId === localInstanceId`.
const res = await importer.processManifest(bucket.id, exp.filename);
expect(res.skipped).toBe(true);
expect(res.reason).toBe('self-authored');
expect(await importer.listInbox(bucket.id)).toEqual([]);
// Second pass is the cursor's already-processed branch.
const replay = await importer.processManifest(bucket.id, exp.filename);
expect(replay.skipped).toBe(true);
expect(replay.reason).toBe('already-processed');
// Pre-fix bug: simulate a stale inbox entry from before the filter existed
// (no senderInstanceId field). processBacklog should backfill from the
// manifest file on disk and prune it.
const fs = await import('fs');
const inboxFile = join(tempData, 'sharing', 'inbox', `${bucket.id}.json`);
mkdirSync(join(tempData, 'sharing', 'inbox'), { recursive: true });
fs.writeFileSync(inboxFile, JSON.stringify({ items: [{
manifestId: exp.manifestId,
manifestFilename: exp.filename,
kind: 'series',
subscription: null,
source: 'antic',
sourceBio: null,
createdAt: new Date().toISOString(),
receivedAt: new Date().toISOString(),
recordIds: [s.id],
assetCount: 0,
}] }));
const updates = [];
const onUpdate = (p) => updates.push(p);
sharingEvents.on('inbox-updated', onUpdate);
await importer.processBacklog(bucket.id);
sharingEvents.off('inbox-updated', onUpdate);
expect(await importer.listInbox(bucket.id)).toEqual([]);
expect(updates).toHaveLength(1);
expect(updates[0]).toMatchObject({ bucketId: bucket.id });
});
it('processBacklog prunes orphaned inbox items whose manifest file is no longer in the bucket', async () => {
const { sharingEvents } = await import('./importer.js');
const bucket = await buckets.createBucket({ name: 'OrphanBucket', path: tempBucket, mode: 'inbox' });
const fs = await import('fs');
const inboxFile = join(tempData, 'sharing', 'inbox', `${bucket.id}.json`);
mkdirSync(join(tempData, 'sharing', 'inbox'), { recursive: true });
fs.writeFileSync(inboxFile, JSON.stringify({ items: [{
manifestId: 'orphan-mid',
manifestFilename: 'this-file-was-deleted-from-the-bucket.json',
kind: 'universe',
subscription: null,
source: 'remote-peer',
sourceBio: null,
senderInstanceId: 'some-other-peer',
createdAt: new Date().toISOString(),
receivedAt: new Date().toISOString(),
recordIds: ['u-orphan'],
assetCount: 0,
}] }));
const updates = [];
const onUpdate = (p) => updates.push(p);
sharingEvents.on('inbox-updated', onUpdate);
await importer.processBacklog(bucket.id);
sharingEvents.off('inbox-updated', onUpdate);
expect(await importer.listInbox(bucket.id)).toEqual([]);
expect(updates).toHaveLength(1);
});
// Rotation-orphan cull — peer reincarnates with a new senderInstanceId
// (factory reset, new device), and the old identity's inbox row would
// otherwise persist forever. Cull when same source + same record, but
// different senderInstanceId, AND the existing row is older than 30 days.
it('culls a rotation-orphan inbox row when the same source re-shares from a new senderInstanceId after 30+ days', async () => {
const bucket = await buckets.createBucket({ name: 'RotateBucket', path: tempBucket, mode: 'inbox' });
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'Shared Universe' });
// Pre-seed the inbox with a stale row from peer "Adam's old laptop"
// (senderInstanceId inst-OLD) — same source as the incoming manifest,
// same record, 60 days old.
const sixtyDaysAgo = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000).toISOString();
const fs = await import('fs');
const inboxFile = join(tempData, 'sharing', 'inbox', `${bucket.id}.json`);
mkdirSync(join(tempData, 'sharing', 'inbox'), { recursive: true });
fs.writeFileSync(inboxFile, JSON.stringify({ items: [{
manifestId: 'stale-mfst',
manifestFilename: `sub-universe-${u.id}-inst-OLD.json`,
kind: 'universe',
subscription: { recordKind: 'universe', recordId: u.id },
source: 'remote-peer',
sourceBio: null,
senderInstanceId: 'inst-OLD',
createdAt: sixtyDaysAgo,
receivedAt: sixtyDaysAgo,
recordIds: [u.id],
assetCount: 0,
}] }));
// Now export from the SAME source name but a fresh senderInstanceId.
const exp = await exporter.exportUniverse(u.id, bucket.id, {
subscription: { recordKind: 'universe', recordId: u.id },
});
simulateRemoteSender(tempBucket, exp.filename, 'inst-NEW');
// The exporter stamps `source` from the bucket's display name resolver;
// override on disk to match the pre-seeded row's source so the cull fires.
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const m = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
m.source = 'remote-peer';
fs.writeFileSync(manifestPath, JSON.stringify(m));
await importer.processManifest(bucket.id, exp.filename);
const after = await importer.listInbox(bucket.id);
expect(after).toHaveLength(1);
expect(after[0].senderInstanceId).toBe('inst-NEW');
expect(after[0].manifestId).not.toBe('stale-mfst');
});
it('preserves a same-source-different-sender row that is younger than the rotation cull window', async () => {
const bucket = await buckets.createBucket({ name: 'FreshSourceBucket', path: tempBucket, mode: 'inbox' });
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'Co-shared Universe' });
// Same source name, different senderInstanceId, only 2 days old —
// could plausibly be a second device of the same user (both named
// "MacBook") rather than a rotation orphan. Preserve it.
const twoDaysAgo = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString();
const fs = await import('fs');
const inboxFile = join(tempData, 'sharing', 'inbox', `${bucket.id}.json`);
mkdirSync(join(tempData, 'sharing', 'inbox'), { recursive: true });
fs.writeFileSync(inboxFile, JSON.stringify({ items: [{
manifestId: 'fresh-other',
manifestFilename: `sub-universe-${u.id}-inst-OTHER.json`,
kind: 'universe',
subscription: { recordKind: 'universe', recordId: u.id },
source: 'shared-name',
sourceBio: null,
senderInstanceId: 'inst-OTHER',
createdAt: twoDaysAgo,
receivedAt: twoDaysAgo,
recordIds: [u.id],
assetCount: 0,
}] }));
const exp = await exporter.exportUniverse(u.id, bucket.id, {
subscription: { recordKind: 'universe', recordId: u.id },
});
simulateRemoteSender(tempBucket, exp.filename, 'inst-ME');
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const m = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
m.source = 'shared-name';
fs.writeFileSync(manifestPath, JSON.stringify(m));
await importer.processManifest(bucket.id, exp.filename);
const after = await importer.listInbox(bucket.id);
// Both rows should remain — fresh peer + new arrival.
expect(after).toHaveLength(2);
const senders = after.map((r) => r.senderInstanceId).sort();
expect(senders).toEqual(['inst-ME', 'inst-OTHER']);
});
it('persists a rotation-orphan cull even when the freshness gate forces an early inbox-has-newer return', async () => {
// Regression: the cull mutates inbox.items before the freshness gate
// runs. If an older manifest from the same sender arrives after the
// newer one is already in the inbox, the freshness gate short-circuits
// with `inbox-has-newer` — the cull removals on the OTHER (rotated)
// sender's row must still be persisted, otherwise the orphan survives
// until the next non-stale arrival.
const bucket = await buckets.createBucket({ name: 'RotateAndStaleBucket', path: tempBucket, mode: 'inbox' });
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'Multi-state Universe' });
const sixtyDaysAgo = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000).toISOString();
const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
const fs = await import('fs');
const inboxFile = join(tempData, 'sharing', 'inbox', `${bucket.id}.json`);
mkdirSync(join(tempData, 'sharing', 'inbox'), { recursive: true });
fs.writeFileSync(inboxFile, JSON.stringify({ items: [
// Rotation orphan — different sender, same source, 60 days old.
// Must be culled by the incoming manifest.
{
manifestId: 'rotation-orphan',
manifestFilename: `sub-universe-${u.id}-inst-OLD.json`,
kind: 'universe',
subscription: { recordKind: 'universe', recordId: u.id },
source: 'remote-peer',
sourceBio: null,
senderInstanceId: 'inst-OLD',
createdAt: sixtyDaysAgo,
receivedAt: sixtyDaysAgo,
recordIds: [u.id],
assetCount: 0,
},
// Same-sender row newer than the incoming manifest below — triggers
// the freshness gate's `inbox-has-newer` early return.
{
manifestId: 'fresh-newer',
manifestFilename: `sub-universe-${u.id}-inst-NEW.json`,
kind: 'universe',
subscription: { recordKind: 'universe', recordId: u.id },
source: 'remote-peer',
sourceBio: null,
senderInstanceId: 'inst-NEW',
createdAt: yesterday,
receivedAt: yesterday,
recordIds: [u.id],
assetCount: 0,
},
] }));
// Synthesize an OLDER manifest from the same fresh sender so the
// freshness gate fires (existing.createdAt > manifest.createdAt).
const exp = await exporter.exportUniverse(u.id, bucket.id, {
subscription: { recordKind: 'universe', recordId: u.id },
});
simulateRemoteSender(tempBucket, exp.filename, 'inst-NEW');
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const m = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
m.source = 'remote-peer';
// Older than the pre-seeded `fresh-newer` row.
const twoDaysAgo = new Date(Date.now() - 2 * 24 * 60 * 60 * 1000).toISOString();
m.createdAt = twoDaysAgo;
fs.writeFileSync(manifestPath, JSON.stringify(m));
const outcome = await importer.processManifest(bucket.id, exp.filename);
expect(outcome.outcome?.queued).toBe(false);
expect(outcome.outcome?.reason).toBe('inbox-has-newer');
// Despite the early return, the cull must have persisted: only the
// newer same-sender row remains.
const after = await importer.listInbox(bucket.id);
expect(after).toHaveLength(1);
expect(after[0].manifestId).toBe('fresh-newer');
expect(after[0].senderInstanceId).toBe('inst-NEW');
});
it('preserves a different-source row even when older than the rotation cull window', async () => {
const bucket = await buckets.createBucket({ name: 'OtherSourceBucket', path: tempBucket, mode: 'inbox' });
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'Public Universe' });
// Different source name, different senderInstanceId — definitely a
// different peer, regardless of age. Preserve.
const sixtyDaysAgo = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000).toISOString();
const fs = await import('fs');
const inboxFile = join(tempData, 'sharing', 'inbox', `${bucket.id}.json`);
mkdirSync(join(tempData, 'sharing', 'inbox'), { recursive: true });
fs.writeFileSync(inboxFile, JSON.stringify({ items: [{
manifestId: 'different-peer',
manifestFilename: `sub-universe-${u.id}-inst-PEER-B.json`,
kind: 'universe',
subscription: { recordKind: 'universe', recordId: u.id },
source: 'peer-bob',
sourceBio: null,
senderInstanceId: 'inst-PEER-B',
createdAt: sixtyDaysAgo,
receivedAt: sixtyDaysAgo,
recordIds: [u.id],
assetCount: 0,
}] }));
const exp = await exporter.exportUniverse(u.id, bucket.id, {
subscription: { recordKind: 'universe', recordId: u.id },
});
simulateRemoteSender(tempBucket, exp.filename, 'inst-PEER-A');
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const m = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
m.source = 'peer-alice';
fs.writeFileSync(manifestPath, JSON.stringify(m));
await importer.processManifest(bucket.id, exp.filename);
const after = await importer.listInbox(bucket.id);
expect(after).toHaveLength(2);
const sources = after.map((r) => r.source).sort();
expect(sources).toEqual(['peer-alice', 'peer-bob']);
});
it('content-addressed blob is shared when two manifests reference identical bytes under different filenames', async () => {
const bucket = await buckets.createBucket({ name: 'DedupBucket', path: tempBucket, mode: 'auto-merge' });
const fs = await import('fs');
const universeBuilder = await import('../universeBuilder.js');
const mediaCollections = await import('../mediaCollections.js');
// Two distinct filenames, identical bytes.
const sharedBytes = pngBytes('SHARED-PNG-PAYLOAD');
fs.writeFileSync(join(tempData, 'images', 'alpha.png'), sharedBytes);
fs.writeFileSync(join(tempData, 'images', 'beta.png'), sharedBytes);
const hash = sha256Hex(sharedBytes);
// Universe A references alpha.png.
const uniA = await universeBuilder.createUniverse({ name: 'UA' });
const collA = await mediaCollections.findOrCreateCollectionByName({
name: `Universe: ${uniA.name}`, description: '', universeId: uniA.id,
});
await mediaCollections.addItem(collA.id, { kind: 'image', ref: 'alpha.png' });
const expA = await exporter.exportUniverse(uniA.id, bucket.id);
// Universe B references beta.png — same bytes, different filename.
const uniB = await universeBuilder.createUniverse({ name: 'UB' });
const collB = await mediaCollections.findOrCreateCollectionByName({
name: `Universe: ${uniB.name}`, description: '', universeId: uniB.id,
});
await mediaCollections.addItem(collB.id, { kind: 'image', ref: 'beta.png' });
const expB = await exporter.exportUniverse(uniB.id, bucket.id);
// Both manifests point at the same blob path; only one on-disk blob file exists
// (the dotfile `.index.json` is the per-bucket source→hash cache, not a blob).
expect(fs.existsSync(join(tempBucket, 'assets', 'blobs', hash))).toBe(true);
// Filter out: dotfiles (.index.json source-hash cache) AND .metadata.json
// sidecars (which mirror the source-side sidecars created by the new
// cross-transport SHA-256 cache in lib/assetHash.js). The point of the
// assertion is "only ONE actual blob exists for two manifests that share
// bytes" — the sidecar is provenance metadata, not a duplicate blob.
const blobs = fs.readdirSync(join(tempBucket, 'assets', 'blobs'))
.filter((f) => !f.startsWith('.') && !f.endsWith('.metadata.json'));
expect(blobs).toEqual([hash]);
// Each manifest's assetRef carries the hash + its own original filename.
const mA = JSON.parse(fs.readFileSync(join(tempBucket, 'manifests', expA.filename), 'utf-8'));
const mB = JSON.parse(fs.readFileSync(join(tempBucket, 'manifests', expB.filename), 'utf-8'));
expect(mA.assetRefs).toContainEqual({ kind: 'image', ref: 'alpha.png', hash });
expect(mB.assetRefs).toContainEqual({ kind: 'image', ref: 'beta.png', hash });
// Import path: each manifest restores its filename in the local data dir.
fs.rmSync(join(tempData, 'images', 'alpha.png'), { force: true });
fs.rmSync(join(tempData, 'images', 'beta.png'), { force: true });
await mediaCollections.deleteCollection(collA.id);
await mediaCollections.deleteCollection(collB.id);
await universeBuilder.deleteUniverse(uniA.id);
await universeBuilder.deleteUniverse(uniB.id);
simulateRemoteSender(tempBucket, expA.filename);
simulateRemoteSender(tempBucket, expB.filename);
await importer.processManifest(bucket.id, expA.filename);
await importer.processManifest(bucket.id, expB.filename);
expect(fs.existsSync(join(tempData, 'images', 'alpha.png'))).toBe(true);
expect(fs.existsSync(join(tempData, 'images', 'beta.png'))).toBe(true);
expect(fs.readFileSync(join(tempData, 'images', 'alpha.png'))).toEqual(sharedBytes);
expect(fs.readFileSync(join(tempData, 'images', 'beta.png'))).toEqual(sharedBytes);
});
it('importer rejects manifest asset refs whose hash is not a 64-char hex string (path-traversal guard)', async () => {
const bucket = await buckets.createBucket({ name: 'HostileBucket', path: tempBucket, mode: 'auto-merge' });
const fs = await import('fs');
const { SHARING_SCHEMA_VERSION } = await import('./version.js');
// Plant a file outside the blob dir that a path-traversal attempt would target.
const secretsDir = mkdtempSync(join(tmpdir(), 'portos-sharing-hostile-secret-'));
const secretPath = join(secretsDir, 'secret.txt');
fs.writeFileSync(secretPath, 'SECRET-CONTENT-DO-NOT-LEAK');
// Compute the traversal that would escape <bucket>/assets/blobs/ and
// land on the planted secret. Use forward slashes — path.join normalizes.
const rel = ['..', '..', '..', '..', '..', '..', '..', '..', '..'].join('/')
+ secretPath.replace(/\\/g, '/');
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'Hostile Universe' });
fs.mkdirSync(join(tempBucket, 'records', 'universes'), { recursive: true });
fs.writeFileSync(join(tempBucket, 'records', 'universes', `${u.id}.json`), JSON.stringify({
...u,
origin: {
bucketId: bucket.id, bucketName: bucket.name,
source: 'hostile-peer', sourceBio: null,
manifestId: 'mfst-hostile', importedAt: new Date().toISOString(),
},
}));
await universeBuilder.deleteUniverse(u.id);
// Hostile manifest: hash is a relative path traversing out of the blob dir.
const hostileManifest = {
id: 'mfst-hostile',
schemaVersion: SHARING_SCHEMA_VERSION,
sharingSchemaVersion: SHARING_SCHEMA_VERSION,
producedByVersion: '9.9.9',
createdAt: new Date().toISOString(),
kind: 'universe',
senderInstanceId: 'hostile-peer',
source: 'Hostile Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [u.id],
assetRefs: [{ kind: 'image', ref: 'pwned.png', hash: rel }],
note: null,
};
const filename = `2099-01-01T00-00-00-000Z-hostile-peer-${hostileManifest.id}.json`;
fs.mkdirSync(join(tempBucket, 'manifests'), { recursive: true });
fs.writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(hostileManifest));
const result = await importer.processManifest(bucket.id, filename);
// The universe record imports fine; the asset ref is dropped at the
// manifest-parse boundary so no file copy is attempted.
expect(result.processed).toBe(true);
// The hostile file MUST NOT have been copied into the local data dirs.
expect(fs.existsSync(join(tempData, 'images', 'pwned.png'))).toBe(false);
expect(fs.existsSync(join(tempData, 'images', 'secret.txt'))).toBe(false);
// The secret on disk should be untouched.
expect(fs.readFileSync(secretPath, 'utf-8')).toBe('SECRET-CONTENT-DO-NOT-LEAK');
rmSync(secretsDir, { recursive: true, force: true });
});
it('bucketBlobPath / bucketBlobSidecarPath throw on malformed hash (defense-in-depth)', async () => {
const bogus = [
'../../../../etc/hosts',
'ABCDEF', // uppercase — must be lowercase
'g'.repeat(64), // not hex
'0'.repeat(63), // wrong length
'0'.repeat(65),
'',
null,
undefined,
42,
];
for (const h of bogus) {
expect(() => buckets.bucketBlobPath(tempBucket, h)).toThrow();
expect(() => buckets.bucketBlobSidecarPath(tempBucket, h)).toThrow();
}
// Valid hash passes.
const ok = sha256Hex('whatever');
expect(buckets.bucketBlobPath(tempBucket, ok)).toBe(join(tempBucket, 'assets', 'blobs', ok));
expect(buckets.bucketBlobSidecarPath(tempBucket, ok)).toBe(join(tempBucket, 'assets', 'blobs', `${ok}.metadata.json`));
});
it('importer falls back to legacy assets/<kind>/<filename> when manifest asset ref omits hash (v1 compat)', async () => {
const bucket = await buckets.createBucket({ name: 'LegacyImportBucket', path: tempBucket, mode: 'auto-merge' });
const fs = await import('fs');
const { SHARING_SCHEMA_VERSION } = await import('./version.js');
// Hand-craft a v1-style bucket: blob lives at assets/images/<filename>,
// manifest's assetRefs has no `hash` field, schemaVersion: 1.
fs.mkdirSync(join(tempBucket, 'assets', 'images'), { recursive: true });
fs.writeFileSync(join(tempBucket, 'assets', 'images', 'legacy-v1.png'), pngBytes('V1BYTES'));
const universeBuilder = await import('../universeBuilder.js');
const u = await universeBuilder.createUniverse({ name: 'Legacy v1 Universe' });
fs.writeFileSync(join(tempBucket, 'records', 'universes', `${u.id}.json`), JSON.stringify({
...u,
origin: {
bucketId: bucket.id, bucketName: bucket.name,
source: 'old-peer', sourceBio: null,
manifestId: 'mfst-v1', importedAt: new Date().toISOString(),
},
}));
await universeBuilder.deleteUniverse(u.id);
const v1Manifest = {
id: 'mfst-v1',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'universe',
senderInstanceId: 'old-peer',
source: 'Old Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [u.id],
assetRefs: [{ kind: 'image', ref: 'legacy-v1.png' }], // no hash
note: null,
};
const filename = `2000-01-01T00-00-00-000Z-old-peer-${v1Manifest.id}.json`;
fs.writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(v1Manifest));
expect(SHARING_SCHEMA_VERSION).toBeGreaterThanOrEqual(2); // sanity
const result = await importer.processManifest(bucket.id, filename);
expect(result.processed).toBe(true);
expect(result.pending).toBeFalsy();
// Asset blob made it to the local data dir via the legacy path.
expect(fs.existsSync(join(tempData, 'images', 'legacy-v1.png'))).toBe(true);
expect(fs.readFileSync(join(tempData, 'images', 'legacy-v1.png'))).toEqual(pngBytes('V1BYTES'));
});
it('migrates legacy series canon arrays into the linked universe on import (pre-B.4 peer)', async () => {
const bucket = await buckets.createBucket({ name: 'LegacyCanonBucket', path: tempBucket, mode: 'auto-merge' });
const _fs = await import('fs');
// Local target universe — the migration writes incoming canon here.
const uni = await universeSvc.createUniverse({ name: 'Pre-B.4 Universe' });
expect((uni.characters || []).length).toBe(0);
expect((uni.places || []).length).toBe(0);
expect((uni.objects || []).length).toBe(0);
// Hand-write a pre-B.4 series record carrying the legacy canon arrays.
// `sanitizeSeries` would normally strip these on insert; the importer's
// pre-pass must fold them into the universe first.
const seriesId = 'ser-pre-b4-test';
const legacySeries = {
id: seriesId,
name: 'Pre-B.4 Series',
logline: 'Test',
premise: 'Test premise',
universeId: uni.id,
characters: [{ name: 'Echo', physicalDescription: 'tall' }],
// Pre-022 wire name — the helper coalesces this onto `places`.
settings: [{ name: 'The Foundry', slugline: 'INT. FOUNDRY - NIGHT' }],
objects: [{ name: 'Brass Key', description: 'opens the gate' }],
createdAt: '2026-05-01T00:00:00.000Z',
updatedAt: '2026-05-01T00:00:00.000Z',
};
mkdirSync(join(tempBucket, 'records', 'series'), { recursive: true });
writeFileSync(
join(tempBucket, 'records', 'series', `${seriesId}.json`),
JSON.stringify(legacySeries),
);
const manifest = {
id: 'mfst-pre-b4',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'series',
senderInstanceId: 'pre-b4-peer',
source: 'Pre B.4 Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [seriesId],
assetRefs: [],
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-pre-b4-peer-${manifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(manifest));
const result = await importer.processManifest(bucket.id, filename);
expect(result.processed).toBe(true);
expect(result.outcome.applied).toBeGreaterThan(0);
// Series imported under the preserved id, with legacy canon stripped.
const restored = await series.getSeries(seriesId);
expect(restored.id).toBe(seriesId);
expect(restored.universeId).toBe(uni.id);
expect(restored.characters).toBeUndefined();
expect(restored.settings).toBeUndefined();
expect(restored.places).toBeUndefined();
expect(restored.objects).toBeUndefined();
// Universe gained the canon entries with SERIES_EXTRACT provenance.
const merged = await universeSvc.getUniverse(uni.id);
expect(merged.characters.map((c) => c.name)).toContain('Echo');
expect(merged.places.map((p) => p.name)).toContain('The Foundry');
expect(merged.objects.map((o) => o.name)).toContain('Brass Key');
// Provenance: live extract path tags series-driven canon as locked + sourceSeriesId.
const echo = merged.characters.find((c) => c.name === 'Echo');
expect(echo.locked).toBe(true);
expect(echo.sourceSeriesId).toBe(seriesId);
expect(echo.source).toBe('series-extract');
});
it('creates an orphan universe and links the series when a pre-B.4 record has no universeId', async () => {
const bucket = await buckets.createBucket({ name: 'OrphanCanonBucket', path: tempBucket, mode: 'auto-merge' });
const seriesId = 'ser-orphan-test';
const legacySeries = {
id: seriesId,
name: 'Orphan Series',
logline: 'unlinked',
premise: 'unlinked premise',
// No universeId — pre-B universes-don't-exist era.
characters: [{ name: 'Solo', physicalDescription: 'lone' }],
createdAt: '2026-05-01T00:00:00.000Z',
updatedAt: '2026-05-01T00:00:00.000Z',
};
mkdirSync(join(tempBucket, 'records', 'series'), { recursive: true });
writeFileSync(
join(tempBucket, 'records', 'series', `${seriesId}.json`),
JSON.stringify(legacySeries),
);
const manifest = {
id: 'mfst-orphan',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'series',
senderInstanceId: 'orphan-peer',
source: 'Orphan Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [seriesId],
assetRefs: [],
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-orphan-peer-${manifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(manifest));
const result = await importer.processManifest(bucket.id, filename);
expect(result.processed).toBe(true);
const restored = await series.getSeries(seriesId);
expect(restored.universeId).toBeTruthy(); // freshly minted
const orphanUni = await universeSvc.getUniverse(restored.universeId);
expect(orphanUni.name).toMatch(/Orphan Series/);
expect(orphanUni.characters.map((c) => c.name)).toContain('Solo');
});
it('reuses an existing local series.universeId on retry — no duplicate auto-migrated universes', async () => {
// When the same orphan-series manifest is processed twice (e.g. an
// unrelated pending condition held the cursor back the first time),
// the legacy-canon helper must reuse the persisted local universeId
// instead of minting a fresh "<name> (auto-migrated)" universe each pass.
const bucket = await buckets.createBucket({ name: 'OrphanIdempBucket', path: tempBucket, mode: 'auto-merge' });
const seriesId = 'ser-orphan-idemp';
const legacySeries = {
id: seriesId,
name: 'Orphan Idemp Series',
logline: 'will be reimported',
premise: 'idempotency test',
characters: [{ name: 'Echo', physicalDescription: 'on retry' }],
createdAt: '2026-05-01T00:00:00.000Z',
updatedAt: '2026-05-01T00:00:00.000Z',
};
mkdirSync(join(tempBucket, 'records', 'series'), { recursive: true });
writeFileSync(
join(tempBucket, 'records', 'series', `${seriesId}.json`),
JSON.stringify(legacySeries),
);
const manifest = {
id: 'mfst-orphan-idemp',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'series',
senderInstanceId: 'orphan-idemp-peer',
source: 'Orphan Idemp Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [seriesId],
assetRefs: [],
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-orphan-idemp-peer-${manifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(manifest));
// First pass — creates the orphan universe + inserts the series.
await importer.processManifest(bucket.id, filename);
const restoredFirst = await series.getSeries(seriesId);
const firstUniverseId = restoredFirst.universeId;
expect(firstUniverseId).toBeTruthy();
// Force a retry — simulate the cursor being un-advanced by forgetting the
// manifest, then re-process. Without idempotency the helper would mint a
// SECOND auto-migrated universe and `mergeOne` would no-op the series.
const { forgetProcessed } = await import('./manifest.js');
await forgetProcessed(bucket.id, filename);
await importer.processManifest(bucket.id, filename);
const restoredAfter = await series.getSeries(seriesId);
expect(restoredAfter.universeId).toBe(firstUniverseId);
const allUnis = await universeSvc.listUniverses();
const autoMigrated = allUnis.filter((u) => /Orphan Idemp Series/.test(u.name));
expect(autoMigrated).toHaveLength(1);
});
it('promoteInboxItem keeps the inbox row when legacy canon needs a missing universe', async () => {
// Without the gate in promoteInboxItem the user's "promote" click would
// splice the inbox row even though the series merge skipped — same
// silent-data-loss shape as the auto-merge path before this PR.
const bucket = await buckets.createBucket({ name: 'InboxLegacyBucket', path: tempBucket, mode: 'inbox' });
const missingUniverseId = 'uni-inbox-not-bundled';
const seriesId = 'ser-inbox-legacy';
const legacySeries = {
id: seriesId,
name: 'Inbox Legacy Series',
logline: 'inbox-pending test',
premise: 'links to a universe not in the bundle',
universeId: missingUniverseId,
characters: [{ name: 'Phantom', physicalDescription: 'inbox-pending' }],
createdAt: '2026-05-01T00:00:00.000Z',
updatedAt: '2026-05-01T00:00:00.000Z',
};
mkdirSync(join(tempBucket, 'records', 'series'), { recursive: true });
writeFileSync(
join(tempBucket, 'records', 'series', `${seriesId}.json`),
JSON.stringify(legacySeries),
);
const manifest = {
id: 'mfst-inbox-legacy',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'series',
senderInstanceId: 'inbox-legacy-peer',
source: 'Inbox Legacy Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [seriesId],
assetRefs: [],
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-inbox-legacy-peer-${manifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(manifest));
// First: queue as an inbox item (the bucket is inbox mode).
const r1 = await importer.processManifest(bucket.id, filename);
expect(r1.outcome.mode).toBe('inbox');
expect((await importer.listInbox(bucket.id))).toHaveLength(1);
// Promote — should throw because the linked universe is missing, AND the
// inbox row must NOT be removed.
let promoteErr = null;
await importer.promoteInboxItem(bucket.id, manifest.id).catch((err) => { promoteErr = err; });
expect(promoteErr).toBeTruthy();
expect(promoteErr.code).toBe('SHARING_LEGACY_CANON_UNIVERSE_PENDING');
expect(promoteErr.pendingLegacyCanonUniverses).toEqual([missingUniverseId]);
expect((await importer.listInbox(bucket.id))).toHaveLength(1);
const stillMissing = await series.getSeries(seriesId).catch(() => null);
expect(stillMissing).toBeNull();
});
it('leaves the manifest pending and retries when the missing universe later arrives', async () => {
// Without this guard, the importer would fall through to insertSeriesWithId
// and `sanitizeSeries` would silently drop the legacy canon arrays — the
// exact bug this PR fixes. The bucket record stays untouched and the
// cursor stays un-advanced so the watcher retries when the missing
// universe later shows up.
const { hasBeenProcessed, readCursor } = await import('./manifest.js');
const bucket = await buckets.createBucket({ name: 'MissingUniBucket', path: tempBucket, mode: 'auto-merge' });
const missingUniverseId = 'uni-not-yet-bundled-123';
const seriesId = 'ser-missing-uni';
const legacySeries = {
id: seriesId,
name: 'Missing-Uni Series',
logline: 'orphaned link',
premise: 'links to a universe not in the bundle',
universeId: missingUniverseId,
characters: [{ name: 'Ghost', physicalDescription: 'unseen' }],
createdAt: '2026-05-01T00:00:00.000Z',
updatedAt: '2026-05-01T00:00:00.000Z',
};
mkdirSync(join(tempBucket, 'records', 'series'), { recursive: true });
writeFileSync(
join(tempBucket, 'records', 'series', `${seriesId}.json`),
JSON.stringify(legacySeries),
);
const manifest = {
id: 'mfst-missing-uni',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'series',
senderInstanceId: 'missing-uni-peer',
source: 'Missing Uni Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [seriesId],
assetRefs: [],
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-missing-uni-peer-${manifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(manifest));
// First pass: universe is missing → manifest must stay pending, cursor not advanced, series not written.
const first = await importer.processManifest(bucket.id, filename);
expect(first.processed).toBe(true);
expect(first.pending).toBe(true);
expect(first.outcome.pendingLegacyCanonUniverses).toEqual([missingUniverseId]);
let cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, filename, manifest.id)).toBe(false);
const stillMissing = await series.getSeries(seriesId).catch(() => null);
expect(stillMissing).toBeNull();
// Local universe lands (peer re-shares it via a different channel, or
// the user creates one with the matching id).
await universeSvc.insertUniverseWithId({
id: missingUniverseId,
name: 'Late-Arriving Universe',
starterPrompt: '',
createdAt: '2026-05-01T00:00:00.000Z',
updatedAt: '2026-05-01T00:00:00.000Z',
});
// Retry: now the migration lands canon on the universe, the series imports.
const second = await importer.processManifest(bucket.id, filename);
expect(second.processed).toBe(true);
expect(second.pending).toBeFalsy();
cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, filename, manifest.id)).toBe(true);
const restored = await series.getSeries(seriesId);
expect(restored.id).toBe(seriesId);
expect(restored.universeId).toBe(missingUniverseId);
const restoredUni = await universeSvc.getUniverse(missingUniverseId);
expect(restoredUni.characters.map((c) => c.name)).toContain('Ghost');
});
it('tombstoned collection universe: manifest advances cursor with collectionTombstonedUniverse (not pending forever)', async () => {
// Regression: before the fix, getUniverse(id) on a tombstoned record threw
// ERR_NOT_FOUND (same as absent), which resolved to null via .catch(()=>null),
// returning { missingUniverse: true }. The manifest stayed pending indefinitely
// because the universe IS on disk — just soft-deleted. The fix uses
// includeDeleted:true to distinguish tombstoned from truly absent, and
// advances the cursor immediately with a clear collectionTombstonedUniverse signal.
const { hasBeenProcessed, readCursor } = await import('./manifest.js');
const bucket = await buckets.createBucket({ name: 'TombstonedUniBucket', path: tempBucket, mode: 'auto-merge' });
// Create a universe, then delete it — leaves a tombstone on disk.
const uni = await universeSvc.createUniverse({ name: 'Deleted Universe' });
await universeSvc.deleteUniverse(uni.id);
// Confirm it's tombstoned (not truly absent).
const tombstoned = await universeSvc.getUniverse(uni.id, { includeDeleted: true });
expect(tombstoned.deleted).toBe(true);
// Hand-write a collection-only manifest that references the tombstoned universe.
mkdirSync(join(tempBucket, 'manifests'), { recursive: true });
const collectionManifest = {
id: 'mfst-tombstoned-uni-collection',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'universe',
senderInstanceId: 'tombstone-peer',
source: 'Tombstone Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [],
assetRefs: [],
collection: {
universeId: uni.id,
name: `Universe: Deleted Universe`,
description: '',
items: [
{ kind: 'image', ref: 'fakeasset.png' },
{ kind: 'image', ref: 'other.png' },
],
},
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-tombstone-peer-${collectionManifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(collectionManifest));
const result = await importer.processManifest(bucket.id, filename);
// Must be processed (cursor advanced), NOT stuck pending.
expect(result.processed).toBe(true);
expect(result.pending).toBeFalsy();
// Outcome carries the distinct tombstoned sentinel, not missingUniverse.
expect(result.outcome.collectionTombstonedUniverse).toBe(uni.id);
// Cursor was advanced — a replay is a no-op (not re-attempted endlessly).
const cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, filename, collectionManifest.id)).toBe(true);
});
it('tombstoned collection universe via series link: manifest advances cursor (not pending)', async () => {
// Same fix applied to the series→universe re-route path: when a local series
// links to a tombstoned universe, the importer must NOT return missingSeries
// (which would loop pending forever). It returns tombstonedUniverse and the
// manifest cursor advances.
const { hasBeenProcessed, readCursor } = await import('./manifest.js');
const bucket = await buckets.createBucket({ name: 'TombstonedUniViaSeriesBucket', path: tempBucket, mode: 'auto-merge' });
// Create universe + linked series, then tombstone the universe. Local
// deleteUniverse is blocked while a live series references it (the
// hierarchy invariant), but this orphan-link-to-tombstone state still
// arises in production: a PEER deletes the universe (it had no series
// there) and the delete-tombstone arrives via sync while we hold an
// independently-created linked series. Reproduce that via the merge path.
const uni = await universeSvc.createUniverse({ name: 'Gone Universe' });
const s = await series.createSeries({ name: 'Linked Series', logline: 'x', universeId: uni.id });
await universeSvc.mergeUniversesFromSync([
{ ...uni, deleted: true, deletedAt: new Date().toISOString(), updatedAt: new Date(Date.now() + 60_000).toISOString() },
]);
// Hand-write a collection manifest referencing the series id (the exporter
// normally resolves series→universe, but a legacy peer may emit seriesId).
mkdirSync(join(tempBucket, 'manifests'), { recursive: true });
const collectionManifest = {
id: 'mfst-tombstoned-uni-via-series',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'series',
senderInstanceId: 'tombstone-via-series-peer',
source: 'Tombstone Via Series Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [],
assetRefs: [],
collection: {
seriesId: s.id,
name: `Series: Linked Series`,
description: '',
items: [{ kind: 'image', ref: 'fakeasset.png' }],
},
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-tombstone-via-series-peer-${collectionManifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(collectionManifest));
const result = await importer.processManifest(bucket.id, filename);
// Cursor must advance — no infinite pending loop.
expect(result.processed).toBe(true);
expect(result.pending).toBeFalsy();
expect(result.outcome.collectionTombstonedUniverse).toBe(uni.id);
const cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, filename, collectionManifest.id)).toBe(true);
});
it('promoteInboxItem throws SHARING_UNIVERSE_TOMBSTONED when collection universe is deleted locally', async () => {
const bucket = await buckets.createBucket({ name: 'TombstonedUniInboxBucket', path: tempBucket, mode: 'inbox' });
// Create universe, export a collection manifest, then delete the universe.
const uni = await universeSvc.createUniverse({ name: 'Soon Deleted Universe' });
mkdirSync(join(tempBucket, 'manifests'), { recursive: true });
mkdirSync(join(tempBucket, 'records'), { recursive: true });
const collectionManifest = {
id: 'mfst-tombstone-promote',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'universe',
senderInstanceId: 'tombstone-inbox-peer',
source: 'Tombstone Inbox Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [],
assetRefs: [],
collection: {
universeId: uni.id,
name: `Universe: Soon Deleted Universe`,
description: '',
items: [],
},
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-tombstone-inbox-peer-${collectionManifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(collectionManifest));
// First import into inbox while universe is live.
const result = await importer.processManifest(bucket.id, filename);
expect(result.processed).toBe(true);
expect(result.outcome.queued).toBe(true);
// Now delete the universe locally (soft-delete / tombstone).
await universeSvc.deleteUniverse(uni.id);
// Attempt to promote — must throw with the distinct tombstoned code.
const promoteErr = await importer.promoteInboxItem(bucket.id, collectionManifest.id).catch((e) => e);
expect(promoteErr).toBeInstanceOf(Error);
expect(promoteErr.code).toBe('SHARING_UNIVERSE_TOMBSTONED');
expect(promoteErr.collectionTombstonedUniverse).toBe(uni.id);
// Inbox item must NOT be consumed — user can retry after restoring the universe.
const inbox = await importer.listInbox(bucket.id);
expect(inbox.some((it) => it.manifestId === collectionManifest.id)).toBe(true);
});
it('refuses a manifest with a sharingSchemaVersion newer than local + emits incompatible event', async () => {
const { SHARING_SCHEMA_VERSION } = await import('./version.js');
const { sharingEvents } = await import('./importer.js');
const bucket = await buckets.createBucket({ name: 'Compat', path: tempBucket, mode: 'auto-merge' });
// Hand-craft a future-version manifest directly into the bucket.
const manifestsDir = join(tempBucket, 'manifests');
const futureManifest = {
id: 'mfst-future',
schemaVersion: SHARING_SCHEMA_VERSION + 1,
sharingSchemaVersion: SHARING_SCHEMA_VERSION + 1,
producedByVersion: '9.99.0',
createdAt: new Date().toISOString(),
kind: 'series',
senderInstanceId: 'peer-on-newer',
source: 'Future Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [],
assetRefs: [],
note: null,
};
const filename = `2099-01-01T00-00-00-000Z-future-peer-${futureManifest.id}.json`;
writeFileSync(join(manifestsDir, filename), JSON.stringify(futureManifest));
const events = [];
const onIncompat = (p) => events.push(p);
sharingEvents.on('incompatible-manifest', onIncompat);
const result = await importer.processManifest(bucket.id, filename);
sharingEvents.off('incompatible-manifest', onIncompat);
expect(result.skipped).toBe(true);
expect(result.reason).toBe('incompatible-version');
expect(result.remoteVersion).toBe(SHARING_SCHEMA_VERSION + 1);
expect(events).toHaveLength(1);
expect(events[0]).toMatchObject({
bucketId: bucket.id,
remoteVersion: SHARING_SCHEMA_VERSION + 1,
localVersion: SHARING_SCHEMA_VERSION,
source: 'Future Peer',
producedByVersion: '9.99.0',
});
// A second process is dedup'd via the cursor's refusal record (prevents the
// watcher replay loop) without re-announcing — and without marking it
// processed, so an upgraded install can still import it.
const replay = await importer.processManifest(bucket.id, filename);
expect(replay.skipped).toBe(true);
expect(replay.reason).toBe('already-refused');
expect(events).toHaveLength(1);
const { readCursor, hasBeenProcessed } = await import('./manifest.js');
expect(hasBeenProcessed(await readCursor(bucket.id), filename, futureManifest.id)).toBe(false);
});
it('annotation manifest round-trip: peer record merges into local annotations without touching pipeline records', async () => {
const { sharingEvents } = await import('./importer.js');
const { SHARING_SCHEMA_VERSION } = await import('./version.js');
const mediaAnnotations = await import('../mediaAnnotations.js');
const bucket = await buckets.createBucket({ name: 'AnnotationsBucket', path: tempBucket, mode: 'auto-merge' });
// Stage a bucket asset so peer annotations have a corresponding key.
mkdirSync(join(tempBucket, 'assets', 'images'), { recursive: true });
writeFileSync(join(tempBucket, 'assets', 'images', 'fakeasset.png'), pngBytes('PNGSTUB'));
// Hand-write a peer's annotation record + manifest. Bypasses the exporter
// (which would stamp the LOCAL instance id and short-circuit as
// self-authored on import). simulateRemoteSender is conceptually the same
// trick the other tests use.
const recordDir = join(tempBucket, 'records', 'media-annotations');
mkdirSync(recordDir, { recursive: true });
const peerRecord = {
id: 'peer-on-other-machine',
instanceId: 'peer-on-other-machine',
authorName: 'Sam',
updatedAt: '2099-01-01T00:00:00.000Z',
annotations: {
'image:fakeasset.png': { starred: true, note: 'great shot', updatedAt: '2099-01-01T00:00:00.000Z' },
},
};
writeFileSync(join(recordDir, 'peer-on-other-machine.json'), JSON.stringify(peerRecord));
const peerManifest = {
id: 'mfst-annotations-peer',
schemaVersion: SHARING_SCHEMA_VERSION,
sharingSchemaVersion: SHARING_SCHEMA_VERSION,
producedByVersion: '1.0.0',
createdAt: '2099-01-01T00:00:00.000Z',
kind: 'media-annotations',
senderInstanceId: 'peer-on-other-machine',
source: 'Sam',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: ['peer-on-other-machine'],
assetRefs: [],
note: null,
};
const filename = `annotations-peer-on-other-machine.json`;
mkdirSync(join(tempBucket, 'manifests'), { recursive: true });
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(peerManifest));
const events = [];
const onUpdate = (p) => events.push(p);
sharingEvents.on('annotation-updated', onUpdate);
const result = await importer.processManifest(bucket.id, filename);
sharingEvents.off('annotation-updated', onUpdate);
expect(result.processed).toBe(true);
expect(result.outcome.applied).toBe(1);
expect(events).toHaveLength(1);
expect(events[0].key).toBe('image:fakeasset.png');
expect(events[0].entry.others[0]).toMatchObject({ authorName: 'Sam', starred: true, note: 'great shot' });
// The peer record lives under their instanceId in local annotations; our
// own author entry (would-be empty in a fresh fixture) is untouched.
const local = await mediaAnnotations.listAnnotations();
expect(local['image:fakeasset.png'].own).toBeNull();
expect(local['image:fakeasset.png'].others[0]).toMatchObject({ authorName: 'Sam', starred: true, note: 'great shot' });
// Cursor was advanced — replay is a no-op.
const replay = await importer.processManifest(bucket.id, filename);
expect(replay.skipped).toBe(true);
expect(replay.reason).toBe('already-processed');
});
it('writes <bucket>/assets/blobs/.index.json mapping sourcePath:mtime:size → hash and invalidates on mtime change', async () => {
const bucket = await buckets.createBucket({ name: 'CacheBucket', path: tempBucket, mode: 'auto-merge' });
const sourcePath = join(tempData, 'images', 'fakeasset.png'); // seeded as pngBytes('PNGSTUB') in beforeEach
// Single-asset export — exportMedia falls through to copyAssetIfPresent (getJob is mocked → null).
await exporter.exportMedia([{ kind: 'image', ref: 'fakeasset.png' }], bucket.id);
const indexPath = join(tempBucket, 'assets', 'blobs', '.index.json');
expect(existsSync(indexPath)).toBe(true);
const initialStat = statSync(sourcePath);
const initialKey = `${sourcePath}:${initialStat.mtimeMs}:${initialStat.size}`;
const initialHash = sha256Hex(pngBytes('PNGSTUB'));
const idx1 = JSON.parse(readFileSync(indexPath, 'utf-8'));
expect(idx1[initialKey]).toBe(initialHash);
// Re-export unchanged file → cache hit → no new keys → index file not rewritten.
// Assert the index file's mtime is unchanged (dirty-flag short-circuits the write).
const indexMtimeBefore = statSync(indexPath).mtimeMs;
await new Promise((r) => setTimeout(r, 5));
await exporter.exportMedia([{ kind: 'image', ref: 'fakeasset.png' }], bucket.id);
expect(statSync(indexPath).mtimeMs).toBe(indexMtimeBefore);
// Bumping mtime alone (same bytes, same size) creates a new cache key — old entry stays,
// new entry covers the post-touch stat. The hash is unchanged because the bytes are the same.
const future = new Date(initialStat.mtimeMs + 60_000);
utimesSync(sourcePath, future, future);
await exporter.exportMedia([{ kind: 'image', ref: 'fakeasset.png' }], bucket.id);
const touchedStat = statSync(sourcePath);
const touchedKey = `${sourcePath}:${touchedStat.mtimeMs}:${touchedStat.size}`;
expect(touchedKey).not.toBe(initialKey);
const idx2 = JSON.parse(readFileSync(indexPath, 'utf-8'));
expect(idx2[touchedKey]).toBe(initialHash);
// Mutating content invalidates and records a fresh hash.
writeFileSync(sourcePath, pngBytes('PNGSTUB-v2'));
await exporter.exportMedia([{ kind: 'image', ref: 'fakeasset.png' }], bucket.id);
const mutatedStat = statSync(sourcePath);
const mutatedKey = `${sourcePath}:${mutatedStat.mtimeMs}:${mutatedStat.size}`;
const idx3 = JSON.parse(readFileSync(indexPath, 'utf-8'));
expect(idx3[mutatedKey]).toBe(sha256Hex(pngBytes('PNGSTUB-v2')));
// Mutated bytes also land in the bucket under the new hash (content-addressed).
expect(existsSync(join(tempBucket, 'assets', 'blobs', sha256Hex(pngBytes('PNGSTUB-v2'))))).toBe(true);
});
it('parallel exports against the same bucket merge cache entries instead of clobbering (exportByKind fanout)', async () => {
const bucket = await buckets.createBucket({ name: 'MergeBucket', path: tempBucket, mode: 'auto-merge' });
// Two distinct assets, both seeded with distinct bytes so they hash differently.
writeFileSync(join(tempData, 'images', 'parallelA.png'), pngBytes('PARALLEL_A'));
writeFileSync(join(tempData, 'images', 'parallelB.png'), pngBytes('PARALLEL_B'));
// Two singleton media exports run in parallel — each loads its own cache view,
// each saves with merge-on-save. Both new keys must survive in the persisted index.
await Promise.all([
exporter.exportMedia([{ kind: 'image', ref: 'parallelA.png' }], bucket.id),
exporter.exportMedia([{ kind: 'image', ref: 'parallelB.png' }], bucket.id),
]);
const indexPath = join(tempBucket, 'assets', 'blobs', '.index.json');
const idx = JSON.parse(readFileSync(indexPath, 'utf-8'));
const statA = statSync(join(tempData, 'images', 'parallelA.png'));
const statB = statSync(join(tempData, 'images', 'parallelB.png'));
const keyA = `${join(tempData, 'images', 'parallelA.png')}:${statA.mtimeMs}:${statA.size}`;
const keyB = `${join(tempData, 'images', 'parallelB.png')}:${statB.mtimeMs}:${statB.size}`;
expect(idx[keyA]).toBe(sha256Hex(pngBytes('PARALLEL_A')));
expect(idx[keyB]).toBe(sha256Hex(pngBytes('PARALLEL_B')));
});
it('retries a blob-index write after a transient failure instead of poisoning later exports', async () => {
const bucket = await buckets.createBucket({ name: 'RetryBucket', path: tempBucket, mode: 'auto-merge' });
const sourceA = join(tempData, 'images', 'retryA.png');
const sourceB = join(tempData, 'images', 'retryB.png');
writeFileSync(sourceA, 'RETRY_A');
writeFileSync(sourceB, 'RETRY_B');
const indexPath = join(tempBucket, 'assets', 'blobs', '.index.json');
let rejectFirstIndexWrite = true;
fileUtilsMock.atomicWrite.mockImplementation(async (...args) => {
if (String(args[0]) === indexPath && rejectFirstIndexWrite) {
rejectFirstIndexWrite = false;
throw new Error('transient blob-index failure');
}
return fileUtilsMock.realAtomicWrite(...args);
});
await expect(exporter.exportMedia([{ kind: 'image', ref: 'retryA.png' }], bucket.id))
.rejects.toThrow('transient blob-index failure');
await expect(exporter.exportMedia([{ kind: 'image', ref: 'retryB.png' }], bucket.id))
.resolves.toMatchObject({ assetCount: 1 });
const index = JSON.parse(readFileSync(indexPath, 'utf-8'));
const statB = statSync(sourceB);
const keyB = `${sourceB}:${statB.mtimeMs}:${statB.size}`;
expect(index[keyB]).toBe(sha256Hex('RETRY_B'));
expect(fileUtilsMock.atomicWrite.mock.calls.filter(([path]) => String(path) === indexPath)).toHaveLength(2);
});
// ---------------------------------------------------------------------------
// SCHEMA-VERSION GATING — share-bucket transport
// ---------------------------------------------------------------------------
describe('portos-schema-ahead manifest gate', () => {
it('manifest is stamped with the sender\'s PORTOS_SCHEMA_VERSIONS', async () => {
const bucket = await buckets.createBucket({ name: 'GateBucket', path: tempBucket, mode: 'inbox' });
const s = await series.createSeries({ name: 'Stamp Test', logline: 'x' });
const exp = await exporter.exportSeries(s.id, bucket.id);
const manifest = JSON.parse(readFileSync(join(tempBucket, 'manifests', exp.filename), 'utf-8'));
expect(manifest.portosSchemaVersions).toBeDefined();
expect(manifest.portosSchemaVersions.universes).toBe(14);
});
it('preserves character production packages when an older peer wins universe LWW', async () => {
const bucket = await buckets.createBucket({ name: 'LegacyUniverseBucket', path: tempBucket, mode: 'auto-merge' });
const u = await universeSvc.createUniverse({
name: 'Legacy Compatible Universe',
characters: [{
id: 'char-voice',
name: 'Aster',
imageRefs: ['fakeasset.png'],
voiceCanon: { version: 1, description: 'measured alto', approved: true },
identityPack: { assets: [{ role: 'neutral', imageRef: 'fakeasset.png', approved: true }] },
}],
});
const exp = await exporter.exportUniverse(u.id, bucket.id);
const recordPath = join(tempBucket, 'records', 'universes', `${u.id}.json`);
const remote = JSON.parse(readFileSync(recordPath, 'utf-8'));
remote.name = 'Older Peer Rename';
remote.updatedAt = new Date(Date.now() + 60_000).toISOString();
remote.characters = remote.characters.map(({ voiceCanon, identityPack, ...character }) => character);
writeFileSync(recordPath, JSON.stringify(remote, null, 2));
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
manifest.portosSchemaVersions.universes = 9;
writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
simulateRemoteSender(tempBucket, exp.filename);
const result = await importer.processManifest(bucket.id, exp.filename);
expect(result.processed).toBe(true);
const merged = await universeSvc.getUniverse(u.id);
expect(merged.name).toBe('Older Peer Rename');
expect(merged.characters[0].voiceCanon).toMatchObject({ description: 'measured alto', approved: true });
expect(merged.characters[0].identityPack.assets).toEqual([
{ role: 'neutral', imageRef: 'fakeasset.png', approved: true },
]);
});
it('importer rejects a manifest when the sender is AHEAD on a category the manifest CARRIES', async () => {
const bucket = await buckets.createBucket({ name: 'AheadBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Future', logline: 'x' });
const exp = await exporter.exportSeries(s.id, bucket.id);
// Stamp a future schema for pipelineSeries — the category this series
// manifest actually carries — simulating a manifest exported by a NEWER
// PortOS instance landing in an OLDER instance's bucket.
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
manifest.portosSchemaVersions = { universes: 6, pipelineSeries: 99, pipelineIssues: 1, mediaCollections: 1 };
manifest.producedByVersion = '99.0.0';
writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
// Delete the local series so the auto-merge would normally re-create it.
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const result = await importer.processManifest(bucket.id, exp.filename);
expect(result.skipped).toBe(true);
expect(result.reason).toBe('portos-schema-ahead');
// Receiver version read from the live registry — this test is about the
// per-category GATE, not about which number pipelineSeries is on today
// (the registry's own test pins that). Imported lazily because the
// static-import graph is hoisted above this file's `vi.mock` setup.
const { PORTOS_SCHEMA_VERSIONS } = await import('../../lib/schemaVersions.js');
expect(result.ahead).toEqual([
{ category: 'pipelineSeries', senderV: 99, receiverV: PORTOS_SCHEMA_VERSIONS.pipelineSeries },
]);
expect(result.producedByVersion).toBe('99.0.0');
// Series stayed tombstoned (or absent) — apply was refused.
await expect(series.getSeries(s.id)).rejects.toThrow();
});
it('a refused manifest stays quiet on replay, then imports once this install is upgraded', async () => {
const { sharingEvents } = await import('./importer.js');
const { markRefused, readCursor, hasBeenProcessed } = await import('./manifest.js');
const bucket = await buckets.createBucket({ name: 'RetryAfterUpgradeBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Arrives Early', logline: 'x' });
const exp = await exporter.exportSeries(s.id, bucket.id);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
const compatibleVersions = manifest.portosSchemaVersions;
manifest.portosSchemaVersions = { ...compatibleVersions, pipelineSeries: 99 };
writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
const announced = [];
const onAhead = (p) => announced.push(p);
sharingEvents.on('portos-schema-ahead', onAhead);
try {
expect((await importer.processManifest(bucket.id, exp.filename)).reason).toBe('portos-schema-ahead');
// Every bundle file landing re-walks the backlog: the replay must not
// re-announce the same refusal.
expect((await importer.processManifest(bucket.id, exp.filename)).reason).toBe('already-refused');
expect(announced).toHaveLength(1);
} finally {
sharingEvents.off('portos-schema-ahead', onAhead);
}
// Upgrade: the refusal was recorded by the previous build's schema, and
// the new build reads the sender's layout. The boot backlog re-walk then
// imports the share with no manual cursor surgery.
await markRefused(bucket.id, exp.filename, manifest.id, 'previous-build-schema');
manifest.portosSchemaVersions = compatibleVersions;
writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
await importer.processBacklog(bucket.id);
expect((await series.getSeries(s.id)).id).toBe(s.id);
const cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, manifest.id)).toBe(true);
expect(cursor.refusedById[exp.filename]).toBeUndefined();
});
it('importer IMPORTS a manifest when the sender is ahead only on a category the manifest does NOT carry', async () => {
// Per-category gate: a universeless series manifest carries only
// pipelineSeries (+ pipelineIssues for bundled issues). A sender ahead on
// `universes` must NOT block it — the old whole-payload gate did, severing
// sync across a federation upgrading on independent schedules.
const bucket = await buckets.createBucket({ name: 'UnrelatedBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Unaffected', logline: 'x' });
const exp = await exporter.exportSeries(s.id, bucket.id);
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
manifest.portosSchemaVersions = { universes: 99, pipelineSeries: 2, pipelineIssues: 1, mediaCollections: 99 };
writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const result = await importer.processManifest(bucket.id, exp.filename);
expect(result.reason).not.toBe('portos-schema-ahead');
expect(result.processed).toBe(true);
const restored = await series.getSeries(s.id);
expect(restored.id).toBe(s.id);
});
it('importer falls through for manifests with no portosSchemaVersions (legacy peer)', async () => {
// A manifest produced by a pre-this-PR PortOS won't have the field;
// the comparator treats it as no-contract, so the merge proceeds.
const bucket = await buckets.createBucket({ name: 'LegacyBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Legacy Test', logline: 'x' });
const exp = await exporter.exportSeries(s.id, bucket.id);
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
delete manifest.portosSchemaVersions;
writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const result = await importer.processManifest(bucket.id, exp.filename);
expect(result.processed).toBe(true);
expect(result.outcome.mode).toBe('auto-merge');
const restored = await series.getSeries(s.id);
expect(restored.id).toBe(s.id);
});
});
// ---------------------------------------------------------------------------
// PENDING-SIGNAL LADDER (#6845) — processManifest derives its "still waiting
// on something" decision, the outcome.pending* keys, and the `⏳ sharing:`
// log suffix from one table (PENDING_SIGNALS) instead of three separately
// maintained lists. These tests pin the two signal formats not already
// covered above (a universe-linked collection defer, and a legacy-canon
// migration failure) plus the exact log-line shape and the all-clear path.
// ---------------------------------------------------------------------------
describe('processManifest pending-signal ladder (#6845)', () => {
it('defers when the collection payload targets a universe not yet imported locally (pendingCollectionUniverse)', async () => {
// `getUniverse(id, { includeDeleted: true })` distinguishes a
// tombstoned universe (deleteUniverse always soft-deletes) from one
// that never existed locally at all — only the latter produces
// `missingUniverse: true` → `pendingCollectionUniverse`. So the
// collection payload must target an id no local universe ever held;
// repoint the manifest's collection at a fabricated id after export.
const bucket = await buckets.createBucket({ name: 'UniverseCollectionDeferBucket', path: tempBucket, mode: 'auto-merge' });
const mediaCollections = await import('../mediaCollections.js');
const universeBuilder = await import('../universeBuilder.js');
const fs = await import('fs');
const { hasBeenProcessed, readCursor } = await import('./manifest.js');
const u = await universeBuilder.createUniverse({ name: 'Has A Collection Universe' });
fs.writeFileSync(join(tempData, 'images', 'late-universe-cover.png'), pngBytes('LATEUNI'));
const collection = await mediaCollections.findOrCreateCollectionByName({
name: `Universe: ${u.name}`, description: 'Linked', universeId: u.id,
});
await mediaCollections.addItem(collection.id, { kind: 'image', ref: 'late-universe-cover.png' });
const exp = await exporter.exportUniverse(u.id, bucket.id);
const missingUniverseId = 'uni-not-imported-anywhere';
const manifestPath = join(tempBucket, 'manifests', exp.filename);
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
manifest.collection.universeId = missingUniverseId;
fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
simulateRemoteSender(tempBucket, exp.filename);
const r = await importer.processManifest(bucket.id, exp.filename);
expect(r.pending).toBe(true);
expect(r.outcome.pendingCollectionUniverse).toBe(missingUniverseId);
expect(r.outcome.pendingRecords).toBeUndefined();
expect(r.outcome.pendingAssets).toBeUndefined();
const cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(false);
});
it('keeps a manifest retryable when the legacy-canon migration throws (pendingLegacyCanonFailures)', async () => {
const migrateSeriesCanon = await import('../pipeline/migrateSeriesCanon.js');
const { hasBeenProcessed, readCursor } = await import('./manifest.js');
const bucket = await buckets.createBucket({ name: 'LegacyCanonThrowBucket', path: tempBucket, mode: 'auto-merge' });
const seriesId = 'ser-legacy-canon-throws';
const legacySeries = {
id: seriesId,
name: 'Legacy Canon Throws Series',
logline: 'orphaned link',
premise: 'migration helper fails transiently',
characters: [{ name: 'Ghost', physicalDescription: 'unseen' }],
createdAt: '2026-05-01T00:00:00.000Z',
updatedAt: '2026-05-01T00:00:00.000Z',
};
mkdirSync(join(tempBucket, 'records', 'series'), { recursive: true });
writeFileSync(join(tempBucket, 'records', 'series', `${seriesId}.json`), JSON.stringify(legacySeries));
const manifest = {
id: 'mfst-legacy-canon-throws',
schemaVersion: 1,
sharingSchemaVersion: 1,
producedByVersion: '1.0.0',
createdAt: new Date().toISOString(),
kind: 'series',
senderInstanceId: 'legacy-canon-throws-peer',
source: 'Legacy Canon Throws Peer',
sourceBio: null,
bucketId: bucket.id,
bucketName: bucket.name,
recordIds: [seriesId],
assetRefs: [],
note: null,
};
const filename = `2026-05-01T00-00-00-000Z-legacy-canon-throws-peer-${manifest.id}.json`;
writeFileSync(join(tempBucket, 'manifests', filename), JSON.stringify(manifest));
const spy = vi.spyOn(migrateSeriesCanon, 'applyLegacySeriesCanonToUniverse')
.mockRejectedValueOnce(new Error('simulated migration failure'));
const first = await importer.processManifest(bucket.id, filename);
expect(first.pending).toBe(true);
expect(first.outcome.pendingLegacyCanonFailures).toEqual([seriesId]);
let cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, filename, manifest.id)).toBe(false);
const stillMissing = await series.getSeries(seriesId).catch(() => null);
expect(stillMissing).toBeNull();
spy.mockRestore();
const second = await importer.processManifest(bucket.id, filename);
expect(second.pending).toBeFalsy();
cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, filename, manifest.id)).toBe(true);
});
it('formats the ⏳ sharing: pending log line with always-on counts alongside a conditional count signal', async () => {
const bucket = await buckets.createBucket({ name: 'LogLineFormatBucket', path: tempBucket, mode: 'auto-merge' });
const s = await series.createSeries({ name: 'Log Line Series', logline: 'A' });
await issues.createIssue({ seriesId: s.id, title: 'Issue 1' });
await manuscriptReview.seedReviewFromFindings(s.id, [
{ problem: 'Act II sags', severity: 'medium', anchorQuote: 'the long road', issueNumber: 1 },
]);
const exp = await exporter.exportSeries(s.id, bucket.id);
const reviewFile = join(tempBucket, 'records', 'reviews', `${s.id}.json`);
const stashedReview = readFileSync(reviewFile, 'utf-8');
rmSync(reviewFile);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const r = await importer.processManifest(bucket.id, exp.filename);
const pendingLine = logSpy.mock.calls.map(([line]) => line).find((line) => line.startsWith('⏳ sharing:'));
logSpy.mockRestore();
expect(r.pending).toBe(true);
expect(r.outcome.pendingReviews).toContain(s.id);
expect(pendingLine).toBe(
`⏳ sharing: bucket=${bucket.name} manifest=${exp.manifestId} kind=series mode=auto-merge ` +
`waitingForAssets=0 waitingForRecords=0 waitingForReviews=1`,
);
writeFileSync(reviewFile, stashedReview);
const r2 = await importer.processManifest(bucket.id, exp.filename);
expect(r2.pending).toBeFalsy();
});
it('advances the cursor and logs no ⏳ sharing: line when every signal is clear (all-clear case)', async () => {
const bucket = await buckets.createBucket({ name: 'AllClearBucket', path: tempBucket, mode: 'auto-merge' });
const { hasBeenProcessed, readCursor } = await import('./manifest.js');
const s = await series.createSeries({ name: 'All Clear Series', logline: 'A' });
const exp = await exporter.exportSeries(s.id, bucket.id);
await series.deleteSeries(s.id);
simulateRemoteSender(tempBucket, exp.filename);
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const r = await importer.processManifest(bucket.id, exp.filename);
const sawPendingLog = logSpy.mock.calls.some(([line]) => line.startsWith('⏳ sharing:'));
logSpy.mockRestore();
expect(r.pending).toBeFalsy();
expect(Object.keys(r.outcome).some((key) => key.startsWith('pending'))).toBe(false);
expect(sawPendingLog).toBe(false);
const cursor = await readCursor(bucket.id);
expect(hasBeenProcessed(cursor, exp.filename, exp.manifestId)).toBe(true);
});
});
// ---------------------------------------------------------------------------
// Remote LWW applies keep the SOURCE clock and compare inside the owning
// write queue (#10761). A receipt-time stamp let a delayed second source
// revision lose to the first one's manufactured clock, and the out-of-queue
// compare let an older snapshot overwrite a local edit made after the read.
// Clocks sit in 2020 so any real "now" a local edit stamps is newer.
// ---------------------------------------------------------------------------
describe('remote LWW keeps source clocks (#10761)', () => {
const CLOCK = {
initial: '2020-01-01T00:00:00.000Z',
v2: '2020-01-02T00:00:00.000Z',
v3: '2020-01-03T00:00:00.000Z',
};
const KINDS = [
{
kind: 'universe', recordDir: 'universes', field: 'name',
async seed(bucketId) {
const u = await universeSvc.createUniverse({ name: 'Initial' });
await universeSvc.updateUniverse(u.id, { name: 'Initial' }, { updatedAt: CLOCK.initial });
return { id: u.id, exportOnce: () => exporter.exportUniverse(u.id, bucketId) };
},
get: (id) => universeSvc.getUniverse(id),
edit: (id, value) => universeSvc.updateUniverse(id, { name: value }),
store: () => universeSvc.store(),
},
{
kind: 'series', recordDir: 'series', field: 'name',
async seed(bucketId) {
const s = await series.createSeries({ name: 'Initial' });
await series.updateSeries(s.id, { name: 'Initial' }, { updatedAt: CLOCK.initial });
return { id: s.id, exportOnce: () => exporter.exportSeries(s.id, bucketId) };
},
get: (id) => series.getSeries(id),
edit: (id, value) => series.updateSeries(id, { name: value }),
store: () => series.seriesStore(),
},
{
kind: 'issue', recordDir: 'issues', field: 'title',
async seed(bucketId) {
const s = await series.createSeries({ name: 'Parent Series' });
const iss = await issues.createIssue({ seriesId: s.id, title: 'Initial' });
await issues.updateIssue(iss.id, { title: 'Initial' }, { updatedAt: CLOCK.initial });
return { id: iss.id, exportOnce: () => exporter.exportSeries(s.id, bucketId) };
},
get: (id) => issues.getIssue(id),
edit: (id, value) => issues.updateIssue(id, { title: value }),
store: () => issues.store(),
},
];
// Export N manifests up front (as if the sender shared N times before any
// of them was delivered), each attributed to a remote peer.
async function exportManifests(seeded, count) {
const exps = [];
for (let i = 0; i < count; i++) exps.push(await seeded.exportOnce());
for (const exp of exps) simulateRemoteSender(tempBucket, exp.filename);
expect(new Set(exps.map((e) => e.filename)).size).toBe(count);
return exps;
}
// Overwrite the bucket's record file with one source revision — the
// record-file content is what the next processed manifest delivers.
function deliverRevision(fixture, id, value, updatedAt) {
const p = join(tempBucket, 'records', fixture.recordDir, `${id}.json`);
const rec = JSON.parse(readFileSync(p, 'utf-8'));
writeFileSync(p, JSON.stringify({ ...rec, [fixture.field]: value, updatedAt }, null, 2));
}
const overriddenFor = (result, fixture, id) =>
result.outcome.overridden.filter((o) => o.kind === fixture.kind && o.id === id);
for (const fixture of KINDS) {
it(`applies two delayed source revisions in order and stores the winning source clock (${fixture.kind})`, async () => {
const bucket = await buckets.createBucket({ name: 'ClockBucket', path: tempBucket, mode: 'auto-merge' });
const seeded = await fixture.seed(bucket.id);
const [first, second] = await exportManifests(seeded, 2);
deliverRevision(fixture, seeded.id, 'Remote Version 2', CLOCK.v2);
const r1 = await importer.processManifest(bucket.id, first.filename);
expect(overriddenFor(r1, fixture, seeded.id)).toHaveLength(1);
expect(await fixture.get(seeded.id)).toMatchObject({ [fixture.field]: 'Remote Version 2', updatedAt: CLOCK.v2 });
deliverRevision(fixture, seeded.id, 'Remote Version 3', CLOCK.v3);
const r2 = await importer.processManifest(bucket.id, second.filename);
expect(overriddenFor(r2, fixture, seeded.id)).toHaveLength(1);
expect(await fixture.get(seeded.id)).toMatchObject({ [fixture.field]: 'Remote Version 3', updatedAt: CLOCK.v3 });
});
it(`converges on reverse-order and tied deliveries without bumping the clock (${fixture.kind})`, async () => {
const bucket = await buckets.createBucket({ name: 'ReverseBucket', path: tempBucket, mode: 'auto-merge' });
const seeded = await fixture.seed(bucket.id);
const [first, second, third] = await exportManifests(seeded, 3);
deliverRevision(fixture, seeded.id, 'Remote Version 3', CLOCK.v3);
await importer.processManifest(bucket.id, second.filename);
// The older revision arrives late, then a different body at the SAME
// clock — both are no-ops that must neither apply nor manufacture a clock.
deliverRevision(fixture, seeded.id, 'Remote Version 2', CLOCK.v2);
const late = await importer.processManifest(bucket.id, first.filename);
expect(overriddenFor(late, fixture, seeded.id)).toEqual([]);
deliverRevision(fixture, seeded.id, 'Tied Rival', CLOCK.v3);
const tied = await importer.processManifest(bucket.id, third.filename);
expect(overriddenFor(tied, fixture, seeded.id)).toEqual([]);
expect(await fixture.get(seeded.id)).toMatchObject({ [fixture.field]: 'Remote Version 3', updatedAt: CLOCK.v3 });
});
it(`keeps a local edit made after the importer read but before its queued write (${fixture.kind})`, async () => {
const bucket = await buckets.createBucket({ name: 'RaceBucket', path: tempBucket, mode: 'auto-merge' });
const seeded = await fixture.seed(bucket.id);
const [exp] = await exportManifests(seeded, 1);
deliverRevision(fixture, seeded.id, 'Remote Version 2', CLOCK.v2);
// The importer's first read of this record returns the stale snapshot,
// but only after a local edit has fully committed — exactly the window
// the old out-of-queue compare could not see.
const st = fixture.store();
const realLoadOne = st.loadOne;
let armed = true;
const spy = vi.spyOn(st, 'loadOne').mockImplementation(async (id, ...rest) => {
const snapshot = await realLoadOne(id, ...rest);
if (armed && id === seeded.id) {
armed = false;
await fixture.edit(seeded.id, 'Local Newer');
}
return snapshot;
});
try {
const r = await importer.processManifest(bucket.id, exp.filename);
expect(armed).toBe(false);
expect(overriddenFor(r, fixture, seeded.id)).toEqual([]);
} finally {
spy.mockRestore();
}
const stored = await fixture.get(seeded.id);
expect(stored[fixture.field]).toBe('Local Newer');
expect(stored.updatedAt > CLOCK.v2).toBe(true);
});
}
it('inbox promotion applies a remote revision with its source clock and origin', async () => {
const bucket = await buckets.createBucket({ name: 'PromoteClockBucket', path: tempBucket, mode: 'inbox' });
const fixture = KINDS.find((k) => k.kind === 'series');
const seeded = await fixture.seed(bucket.id);
const [exp] = await exportManifests(seeded, 1);
deliverRevision(fixture, seeded.id, 'Remote Version 2', CLOCK.v2);
const queued = await importer.processManifest(bucket.id, exp.filename);
expect(queued.outcome.queued).toBe(true);
await importer.promoteInboxItem(bucket.id, exp.manifestId);
expect(await series.getSeries(seeded.id)).toMatchObject({
name: 'Remote Version 2',
updatedAt: CLOCK.v2,
origin: { bucketId: bucket.id, manifestId: exp.manifestId },
});
});
});
});