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
import http from 'node:http';
import { once } from 'node:events';
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { PORTOS_SCHEMA_VERSIONS } from '../lib/schemaVersions.js';
// Mock all dependencies
vi.mock('./instances.js', async () => ({
// Keep the REAL resolveEffectiveCategories (and the default map it resolves
// against): a hand-written stand-in would let the shipped defaults drift from
// what these tests assert the sync loop does with them.
...(await vi.importActual('./instances.js')),
getPeers: vi.fn(),
setPeerSchemaGap: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('./instanceIdentity.js', () => ({
UNKNOWN_INSTANCE_ID: 'unknown',
// forPeer scoping resolves our own instanceId; the orchestrator catches a
// throw/UNKNOWN and just omits the query param, so the default mock returns
// a stable id to exercise the scoped path.
getInstanceId: vi.fn().mockResolvedValue('our-inst-id'),
}));
vi.mock('./brainSyncLog.js', () => ({
getChangesSince: vi.fn(),
getCurrentSeq: vi.fn(() => 0),
compactLog: vi.fn().mockResolvedValue(0),
retryPendingAppends: vi.fn().mockResolvedValue(0)
}));
vi.mock('./brainSync.js', () => ({
applyRemoteChanges: vi.fn()
}));
// Real brainStorage builds data paths at module load, which the fileUtils mock
// breaks — the orchestrator only needs the type list for the checksum-cache
// signature. Keep it a stable literal here; the real list is pinned elsewhere.
vi.mock('./brainStorage.js', () => ({
BRAIN_ENTITY_TYPES: Object.freeze([
'people', 'projects', 'ideas', 'admin', 'memories',
'links', 'buckets', 'journals', 'inbox', 'songs',
]),
}));
vi.mock('./brainReconcile.js', () => ({
getBrainChecksum: vi.fn().mockResolvedValue('local-cksum'),
getBrainSnapshot: vi.fn(),
applyBrainSnapshot: vi.fn().mockResolvedValue({ inserted: 0, updated: 0, deleted: 0, skipped: 0 }),
}));
vi.mock('./memorySync.js', () => ({
applyRemoteChanges: vi.fn(),
getMaxSequence: vi.fn().mockResolvedValue('0')
}));
vi.mock('./catalogSync.js', async (importOriginal) => {
// Keep the real countAppliedFromStats (pure tally over the stats shape) so
// the orchestrator's totalApplied assertions exercise the production sum.
const actual = await importOriginal();
return {
countAppliedFromStats: actual.countAppliedFromStats,
applyRemoteChanges: vi.fn().mockResolvedValue({
scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 0, updated: 0 },
sources: { applied: 0 }, refs: { applied: 0 }, relations: { applied: 0 },
tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: []
}),
getMaxSequences: vi.fn().mockResolvedValue({
scraps: '0', ingredients: '0', sources: '0', refs: '0', relations: '0', tags: '0', media: '0'
})
};
});
vi.mock('./memoryBackend.js', () => ({
getBackendName: vi.fn(() => 'postgres')
}));
vi.mock('./dataSync.js', () => ({
getSnapshot: vi.fn().mockResolvedValue({ data: {}, checksum: 'abc' }),
getChecksum: vi.fn().mockResolvedValue({ checksum: 'abc' }),
// null = "this category serves no manifest" (every category but `usage`),
// which is the signal to fetch the whole snapshot.
getManifest: vi.fn().mockResolvedValue(null),
applyRemote: vi.fn().mockResolvedValue({ applied: false, count: 0 }),
getSupportedCategories: vi.fn(() => ['goals', 'character', 'digitalTwin', 'meatspace'])
}));
vi.mock('./sharing/peerSync.js', () => ({
listPeerSubscriptions: vi.fn().mockResolvedValue([]),
getOutboundCoverageForPeer: vi.fn().mockResolvedValue({
universe: new Set(), pipeline: new Set(), mediaCollections: new Set(),
}),
}));
vi.mock('./instanceEvents.js', () => ({
instanceEvents: { on: vi.fn(), removeListener: vi.fn(), emit: vi.fn() }
}));
vi.mock('../lib/fileUtils.js', () => ({
tryReadFile: vi.fn().mockResolvedValue(null),
// Fresh object per call: `mockResolvedValue({})` would hand every
// loadCursors() the SAME object, so one test's saveCursors mutation leaks
// into the next (a prior test's high catalog cursor then trips the
// rebuild/reset detection). A fresh {} isolates each test's cursor state.
readJSONFile: vi.fn(async () => ({})),
ensureDir: vi.fn().mockResolvedValue(),
atomicWrite: vi.fn().mockResolvedValue(),
writeFileGuarded: vi.fn().mockResolvedValue(),
PATHS: { data: '/mock/data', images: '/mock/data/images' },
dataPath: (name) => `/mock/data/${name}`
}));
vi.mock('../lib/asyncMutex.js', () => ({
createMutex: () => async (fn) => fn()
}));
// Spy on the REAL peerFetch (not a stand-in) so the orchestrator's hops still
// go through the production client — the assertion is only that they do.
vi.mock('../lib/peerHttpClient.js', async (importOriginal) => {
const actual = await importOriginal();
return { ...actual, peerFetch: vi.fn(actual.peerFetch) };
});
vi.mock('fs/promises', () => ({
access: vi.fn().mockRejectedValue(new Error('missing')),
writeFile: vi.fn().mockResolvedValue(),
rename: vi.fn().mockResolvedValue()
}));
// runTombstoneSweep/runBrainTombstoneSweep each `await import(...)` this
// module lazily (keeps the GC dependency graphs off the orchestrator's own
// module-load path) — vitest's mock registry covers a dynamic import the same
// as a static one, so this intercepts it. Zero-valued results so the
// no-op-cycle logging branches in both functions stay quiet.
vi.mock('./sharing/tombstoneGc.js', () => ({
sweepTombstones: vi.fn().mockResolvedValue({
universes: 0, series: 0, issues: 0, collections: 0,
orphanBaseHashes: 0, orphanSubscriptions: 0, refused: [],
}),
}));
vi.mock('./brainTombstoneGc.js', () => ({
sweepBrainTombstones: vi.fn().mockResolvedValue({ pruned: 0 }),
}));
import { readJSONFile, atomicWrite, writeFileGuarded } from '../lib/fileUtils.js';
import { sweepTombstones } from './sharing/tombstoneGc.js';
import { sweepBrainTombstones } from './brainTombstoneGc.js';
import { getPeers } from './instances.js';
import { applyRemoteChanges as applyBrainChanges } from './brainSync.js';
import { BRAIN_ENTITY_TYPES } from './brainStorage.js';
import { applyRemoteChanges as applyMemoryChanges } from './memorySync.js';
import { applyRemoteChanges as applyCatalogChanges } from './catalogSync.js';
import { instanceEvents } from './instanceEvents.js';
import { getCurrentSeq, compactLog } from './brainSyncLog.js';
import { getBrainChecksum, applyBrainSnapshot } from './brainReconcile.js';
import { getMaxSequence } from './memorySync.js';
import { peerFetch } from '../lib/peerHttpClient.js';
import {
syncWithPeer,
syncAllPeers,
getSyncStatus,
initSyncOrchestrator,
stopSyncOrchestrator,
BRAIN_TOMBSTONE_SWEEP_INTERVAL_MS,
} from './syncOrchestrator.js';
const nativeFetch = globalThis.fetch;
const mockFetch = vi.fn();
describe('syncOrchestrator', () => {
const mockPeer = {
name: 'test-peer',
address: '10.0.0.2',
port: 5555,
instanceId: 'peer-inst-1',
enabled: true,
status: 'online'
};
beforeEach(() => {
vi.clearAllMocks();
// Reset the cursor-store read to a FRESH empty object each test. The
// brain/memory reset tests below override it with `mockResolvedValue(
// cursorData)`, and that implementation survives `clearAllMocks` — without
// this reset a later test inherits a prior test's (mutated) cursor and the
// catalog rebuild/reset detection fires on it.
readJSONFile.mockImplementation(async () => ({}));
getPeers.mockResolvedValue([]);
vi.useFakeTimers();
mockFetch.mockReset();
vi.stubGlobal('fetch', mockFetch);
});
afterEach(async () => {
stopSyncOrchestrator();
// A fake-timer advance can fire the orchestrator's fire-and-forget interval
// cycle (syncAllPeers + the tombstone sweeps), whose console.log/console.error
// land on promise resolution — AFTER a synchronous advanceTimersByTime returns.
// Drain that in-flight async here (stopSyncOrchestrator already cleared the
// recurring timer, so this terminates) before restoring real timers and ending
// the file, so a late log can't race vitest's worker teardown
// ("Closing rpc while onUserConsoleLog was pending").
await vi.runOnlyPendingTimersAsync();
vi.useRealTimers();
vi.unstubAllGlobals();
});
describe('syncWithPeer', () => {
it('records a stalled HTTP body failure, settles progress, and allows the next sync', async () => {
const server = http.createServer((_req, res) => {
res.writeHead(200, { 'content-type': 'application/json' });
res.flushHeaders();
});
server.listen(0, '127.0.0.1');
await once(server, 'listening');
const peer = { ...mockPeer, address: '127.0.0.1', port: server.address().port,
syncCategories: { brain: true, memory: false } };
let headersReceived;
const received = new Promise(resolve => { headersReceived = resolve; });
mockFetch.mockImplementationOnce(async (...args) => {
const response = await nativeFetch(...args);
headersReceived();
return response;
});
try {
const sync = syncWithPeer(peer);
const rejected = expect(sync).rejects.toMatchObject({ code: 'PEER_BODY_IDLE_TIMEOUT' });
await received;
await vi.advanceTimersByTimeAsync(60000);
await rejected;
expect(atomicWrite).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
[peer.instanceId]: expect.objectContaining({ lastSyncError: 'Peer response body stalled' })
}));
expect(instanceEvents.emit).toHaveBeenCalledWith('sync:progress', expect.objectContaining({
phase: 'complete', peerId: peer.instanceId, error: 'Peer response body stalled'
}));
mockFetch.mockResolvedValue({ ok: true, json: async () => ({ changes: [], hasMore: false }) });
await syncWithPeer(peer);
expect(instanceEvents.emit.mock.calls.filter(([, event]) => event.phase === 'start')).toHaveLength(2);
expect(instanceEvents.emit).toHaveBeenLastCalledWith('sync:progress', expect.objectContaining({
phase: 'complete', error: null
}));
} finally {
server.closeAllConnections();
await new Promise(resolve => server.close(resolve));
}
});
it('reports an avatar body stall without persisting partial image bytes', async () => {
const { applyRemote } = await import('./dataSync.js');
applyRemote.mockResolvedValue({ applied: true, count: 1 });
mockFetch.mockImplementation(async (url) => {
if (url.includes('/data/images/')) return new Response(new ReadableStream({}));
return { ok: true, json: async () => ({ data: { avatarPath: '/data/images/example.png' }, checksum: 'avatar' }) };
});
const peer = { ...mockPeer, syncCategories: { brain: false, memory: false, character: true } };
const sync = syncWithPeer(peer);
await vi.advanceTimersByTimeAsync(60000);
await sync;
expect(writeFileGuarded).not.toHaveBeenCalled();
expect(instanceEvents.emit).toHaveBeenLastCalledWith('sync:progress', expect.objectContaining({
phase: 'complete', error: 'character: Peer response body stalled'
}));
applyRemote.mockResolvedValue({ applied: false, count: 0 });
});
// An endless chunked body (no Content-Length) must fail the pull at the cap
// rather than grow the heap. One shared chunk keeps the test cheap.
const endlessBody = () => {
const chunk = new Uint8Array(16 * 1024 * 1024);
const state = { pulled: 0, cancel: vi.fn() };
state.response = new Response(new ReadableStream({
pull(controller) { state.pulled++; controller.enqueue(chunk); },
cancel: state.cancel,
}));
return state;
};
it('drops a snapshot that streams past the body cap without buffering it all', async () => {
const body = endlessBody();
mockFetch.mockImplementation(async () => body.response);
const result = await syncWithPeer({ ...mockPeer, syncCategories: { brain: true, memory: false } });
expect(result.brain.totalApplied).toBe(0);
expect(applyBrainChanges).not.toHaveBeenCalled();
expect(body.cancel).toHaveBeenCalledOnce();
// 256 MiB default cap / 16 MiB chunks, plus the stream's read-ahead.
expect(body.pulled).toBeLessThanOrEqual(18);
});
it('skips an avatar that streams past the asset cap', async () => {
const { applyRemote } = await import('./dataSync.js');
applyRemote.mockResolvedValue({ applied: true, count: 1 });
const body = endlessBody();
mockFetch.mockImplementation(async (url) => (url.includes('/data/images/')
? body.response
: { ok: true, json: async () => ({ data: { avatarPath: '/data/images/example.png' }, checksum: 'avatar' }) }));
await syncWithPeer({ ...mockPeer, syncCategories: { brain: false, memory: false, character: true } });
expect(writeFileGuarded).not.toHaveBeenCalled();
expect(body.cancel).toHaveBeenCalledOnce();
expect(body.pulled).toBeLessThanOrEqual(8);
applyRemote.mockResolvedValue({ applied: false, count: 0 });
});
it('does not fetch or store a peer-supplied SVG avatar', async () => {
const { applyRemote } = await import('./dataSync.js');
applyRemote.mockResolvedValue({ applied: true, count: 1 });
mockFetch.mockResolvedValue({ ok: true, json: async () => ({
data: { avatarPath: '/data/images/peer.svg' }, checksum: 'avatar',
}) });
await syncWithPeer({ ...mockPeer, syncCategories: { brain: false, memory: false, character: true } });
expect(mockFetch.mock.calls.some(([url]) => String(url).includes('/data/images/peer.svg'))).toBe(false);
expect(writeFileGuarded).not.toHaveBeenCalled();
applyRemote.mockResolvedValue({ applied: false, count: 0 });
});
it.each([
['non-success response', () => new Response('unavailable', { status: 503 })],
['malformed JSON', () => new Response('{')],
])('retains the no-op behavior for a %s', async (_name, response) => {
mockFetch.mockImplementation(async () => response());
const result = await syncWithPeer({ ...mockPeer, syncCategories: { brain: true, memory: false } });
expect(result.brain.totalApplied).toBe(0);
expect(applyBrainChanges).not.toHaveBeenCalled();
expect(instanceEvents.emit).toHaveBeenLastCalledWith('sync:progress', expect.objectContaining({
phase: 'complete', error: null
}));
});
it('skips peers without instanceId', async () => {
await syncWithPeer({ ...mockPeer, instanceId: undefined });
expect(mockFetch).not.toHaveBeenCalled();
});
it('fetches brain and memory changes from peer', async () => {
// URL-routed (resilient to the #1077 reconcile checksum fetch between
// brain and memory). Brain + memory each return a single batch.
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [{ seq: 1, op: 'create', type: 'people', id: 'p1', record: {} }], maxSeq: 1, hasMore: false }) };
if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [{ id: 'm1', content: 'test' }], maxSequence: '5', hasMore: false }) };
return { ok: true, json: async () => ({}) };
});
applyBrainChanges.mockResolvedValue({ inserted: 1, updated: 0, deleted: 0, skipped: 0 });
applyMemoryChanges.mockResolvedValue({ inserted: 1, updated: 0 });
const result = await syncWithPeer(mockPeer);
expect(result.brain.totalApplied).toBe(1);
expect(result.memory.totalApplied).toBe(1);
// brain delta + reconcile checksum + memory = 3 fetches
expect(mockFetch).toHaveBeenCalledTimes(3);
});
it('stops draining a peer that reports more without advancing its cursor', async () => {
// Every page repeats the same window: unguarded, both loops never end.
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [{ seq: 1 }], maxSeq: 0, hasMore: true }) };
if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [{ id: 'm1' }], maxSequence: '0', hasMore: true }) };
return { ok: true, json: async () => ({}) };
});
applyBrainChanges.mockResolvedValue({ inserted: 0, updated: 1, deleted: 0, skipped: 0 });
applyMemoryChanges.mockResolvedValue({ inserted: 0, updated: 1 });
const result = await syncWithPeer(mockPeer);
expect(applyBrainChanges).toHaveBeenCalledTimes(1);
expect(applyMemoryChanges).toHaveBeenCalledTimes(1);
expect(result.brain.brainSeq).toBe(0);
expect(result.memory.memorySeq).toBe('0');
});
it('advances on the numeric memory cursor older peers send', async () => {
let memoryPages = 0;
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/memory/sync')) {
memoryPages += 1;
return { ok: true, json: async () => ({ memories: [{ id: `m${memoryPages}` }], maxSequence: memoryPages * 100, hasMore: memoryPages < 2 }) };
}
return { ok: true, json: async () => ({}) };
});
applyMemoryChanges.mockResolvedValue({ inserted: 1, updated: 0 });
const result = await syncWithPeer(mockPeer);
expect(applyMemoryChanges).toHaveBeenCalledTimes(2);
expect(result.memory.memorySeq).toBe('200');
});
it('handles pagination loop with hasMore=true', async () => {
// First brain batch: hasMore=true
mockFetch
.mockResolvedValueOnce({
ok: true,
json: async () => ({
changes: [{ seq: 1 }],
maxSeq: 1,
hasMore: true
})
})
// Second brain batch: hasMore=false
.mockResolvedValueOnce({
ok: true,
json: async () => ({
changes: [{ seq: 2 }],
maxSeq: 2,
hasMore: false
})
})
// Memory: no changes
.mockResolvedValueOnce({
ok: true,
json: async () => ({
memories: [],
maxSequence: '0',
hasMore: false
})
});
applyBrainChanges
.mockResolvedValueOnce({ inserted: 1, updated: 0, deleted: 0, skipped: 0 })
.mockResolvedValueOnce({ inserted: 0, updated: 1, deleted: 0, skipped: 0 });
const result = await syncWithPeer(mockPeer);
expect(applyBrainChanges).toHaveBeenCalledTimes(2);
expect(result.brain.totalApplied).toBe(2);
});
it('resets memory cursor when peer DB was rebuilt (cursor > peerMax)', async () => {
const peerWithReset = {
...mockPeer,
remoteSyncSeqs: { brainSeq: 0, memorySeq: '2' }
};
// Simulate stale cursor (we previously synced to 1127 but peer reset to 2)
const { readJSONFile } = await import('../lib/fileUtils.js');
const cursorData = {
[peerWithReset.instanceId]: { brainSeq: 0, memorySeq: '1127', lastSyncAt: '2026-01-01T00:00:00.000Z' }
};
readJSONFile.mockResolvedValue(cursorData);
// URL-routed so the test is resilient to the order/number of fetches
// (the anti-entropy reconcile adds a /reconcile/checksum fetch — #1077).
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [{ id: 'm1', content: 'new' }], maxSequence: '2', hasMore: false }) };
return { ok: true, json: async () => ({}) };
});
applyMemoryChanges.mockResolvedValue({ inserted: 1, updated: 0 });
const result = await syncWithPeer(peerWithReset);
// Memory sync should have fetched since=0 (reset), not since=1127
const memoryCall = mockFetch.mock.calls.find(c => c[0].includes('/api/memory/sync'));
expect(memoryCall[0]).toContain('since=0');
expect(result.memory.totalApplied).toBe(1);
});
it('resets brain cursor when peer sync log was rebuilt', async () => {
const peerWithReset = {
...mockPeer,
remoteSyncSeqs: { brainSeq: 0, memorySeq: '10' }
};
const { readJSONFile } = await import('../lib/fileUtils.js');
const cursorData = {
[peerWithReset.instanceId]: { brainSeq: 5, memorySeq: '10', lastSyncAt: '2026-01-01T00:00:00.000Z' }
};
readJSONFile.mockResolvedValue(cursorData);
// URL-routed (resilient to the reconcile fetch added in #1077). Brain
// returns data from seq 0 (after cursor reset); memory + reconcile quiet.
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [{ seq: 1, op: 'create', type: 'people', id: 'p1', record: {} }], maxSeq: 1, hasMore: false }) };
if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [], maxSequence: '10', hasMore: false }) };
return { ok: true, json: async () => ({}) };
});
applyBrainChanges.mockResolvedValue({ inserted: 1, updated: 0, deleted: 0, skipped: 0 });
const result = await syncWithPeer(peerWithReset);
const brainCall = mockFetch.mock.calls.find(c => c[0].includes('/api/brain/sync') && !c[0].includes('reconcile'));
expect(brainCall[0]).toContain('since=0');
expect(result.brain.totalApplied).toBe(1);
});
it('handles fetch failure gracefully', async () => {
mockFetch.mockRejectedValue(new Error('Network error'));
const result = await syncWithPeer(mockPeer);
// fetchPeer catches errors and returns null, so no changes applied
expect(result.brain.totalApplied).toBe(0);
expect(result.memory.totalApplied).toBe(0);
});
it('ALWAYS pulls every enabled snapshot category, scoped with forPeer (no whole-category skip)', async () => {
// Item A fix: a per-record subscription must NO LONGER suppress the
// inbound snapshot pull for the whole category. The pull always fires,
// but with `?forPeer=<ourId>` so the SOURCE excludes the records it
// already pushes us. This is what lets UN-subscribed records (and
// torn-down-sub tombstones) keep converging via the snapshot.
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['universe', 'pipeline', 'character']);
const peerWithCats = {
...mockPeer,
syncCategories: { universe: true, pipeline: true, character: true },
};
mockFetch.mockResolvedValue({
ok: true,
json: async () => ({ checksum: 'x', data: null }),
});
await syncWithPeer(peerWithCats);
const urls = mockFetch.mock.calls.map((c) => c[0]);
// Every category is pulled — none skipped.
expect(urls.some((u) => u.includes('/api/sync/universe/'))).toBe(true);
expect(urls.some((u) => u.includes('/api/sync/pipeline/'))).toBe(true);
expect(urls.some((u) => u.includes('/api/sync/character/'))).toBe(true);
// Snapshot/checksum URLs carry our instanceId so the source can scope.
const universeUrls = urls.filter((u) => u.includes('/api/sync/universe/'));
expect(universeUrls.length).toBeGreaterThan(0);
expect(universeUrls.every((u) => u.includes('forPeer=our-inst-id'))).toBe(true);
});
it('omits forPeer when our instanceId is UNKNOWN (older/uninitialized install)', async () => {
const dataSync = await import('./dataSync.js');
const instanceIdentity = await import('./instanceIdentity.js');
dataSync.getSupportedCategories.mockReturnValue(['universe', 'character']);
instanceIdentity.getInstanceId.mockResolvedValueOnce('unknown'); // === UNKNOWN_INSTANCE_ID
const peerWithCats = { ...mockPeer, syncCategories: { universe: true, character: true } };
mockFetch.mockResolvedValue({ ok: true, json: async () => ({ checksum: 'x', data: null }) });
await syncWithPeer(peerWithCats);
const urls = mockFetch.mock.calls.map((c) => c[0]);
// Categories still pulled, but WITHOUT the forPeer param (full snapshot).
expect(urls.some((u) => u.includes('/api/sync/universe/'))).toBe(true);
expect(urls.some((u) => u.includes('forPeer='))).toBe(false);
});
it('pulls snapshots through peerFetch, with the peer record, so the hop is identified (#5663)', async () => {
// The receiver's peer-pull gate keys on `X-PortOS-Instance-Id`; without
// it the PII categories now refuse us outright. Passing the peer record
// as peerFetch's third arg is what attaches that header AND the stored
// Basic credential (header contents themselves: peerHttpClient.test.js).
// `forPeer` is a payload-scoping hint, NOT identity — don't confuse them.
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['digitalTwin']);
const peerWithCats = {
...mockPeer,
syncCategories: { digitalTwin: true },
auth: { username: 'alice', password: 'pw' },
};
mockFetch.mockResolvedValue({ ok: true, json: async () => ({ checksum: 'x', data: null }) });
await syncWithPeer(peerWithCats);
const call = peerFetch.mock.calls.find((c) => c[0].includes('/api/sync/digitalTwin/'));
expect(call).toBeDefined();
expect(call[2]).toBe(peerWithCats);
// The 15s budget survived the move off fetchWithTimeout.
expect(call[1].signal).toBeInstanceOf(AbortSignal);
});
});
describe('catalog sync (delta-based, Postgres-only)', () => {
const catalogPeer = { ...mockPeer, syncCategories: { catalog: true } };
it('pulls /api/catalog/sync with per-kind cursors and applies locally', async () => {
mockFetch.mockResolvedValueOnce({
ok: true,
json: async () => ({
ingredients: [{ id: 'cat-chr-1' }],
refs: [{ ingredientId: 'cat-chr-1', refKind: 'universe', refId: 'u1', role: 'canon-character' }],
maxSequences: { scraps: '0', ingredients: '7', sources: '0', refs: '3', relations: '0', tags: '0', media: '0' },
hasMore: false,
portosMeta: { schemaVersions: { catalog: 1 } },
}),
});
applyCatalogChanges.mockResolvedValueOnce({
scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
sources: { applied: 0 }, refs: { applied: 1 }, relations: { applied: 0 },
tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [],
});
const result = await syncWithPeer(catalogPeer);
const url = mockFetch.mock.calls[0][0];
expect(url).toContain('/api/catalog/sync?');
expect(url).toContain('since[ingredients]=0');
expect(url).toContain('since[refs]=0');
expect(applyCatalogChanges).toHaveBeenCalledTimes(1);
// inserted ingredient (1) + applied ref (1)
expect(result.catalog.totalApplied).toBe(2);
});
it('drains multiple batches via hasMore, advancing the per-kind cursor', async () => {
mockFetch
.mockResolvedValueOnce({
ok: true,
json: async () => ({
ingredients: [{ id: 'a' }],
maxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
hasMore: true,
portosMeta: { schemaVersions: { catalog: 1 } },
}),
})
.mockResolvedValueOnce({
ok: true,
json: async () => ({
ingredients: [{ id: 'b' }],
maxSequences: { scraps: '0', ingredients: '9', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
hasMore: false,
portosMeta: { schemaVersions: { catalog: 1 } },
}),
});
applyCatalogChanges.mockResolvedValue({
scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
sources: { applied: 0 }, refs: { applied: 0 }, relations: { applied: 0 },
tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [],
});
const result = await syncWithPeer(catalogPeer);
expect(applyCatalogChanges).toHaveBeenCalledTimes(2);
expect(result.catalog.totalApplied).toBe(2);
// Second pull must carry the cursor from the first batch.
const secondUrl = mockFetch.mock.calls[1][0];
expect(secondUrl).toContain('since[ingredients]=5');
// Final cursor advanced to the last batch's max.
expect(result.catalog.catalogSeqs.ingredients).toBe('9');
});
it('rewinds a stale catalog cursor that exceeds the peer max (peer DB rebuild) and re-pulls from 0', async () => {
// Saved cursor is far ahead of the peer's rebuilt table maxima.
readJSONFile.mockResolvedValue({
[catalogPeer.instanceId]: {
catalogSeqs: { scraps: '0', ingredients: '999', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
},
});
mockFetch
.mockResolvedValueOnce({
ok: true,
json: async () => ({
ingredients: [],
// No rows for the stale cursor → maxSequences ECHOES the inbound
// cursor (999), but tableMaxSequences reports the TRUE max (5).
maxSequences: { scraps: '0', ingredients: '999', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
tableMaxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
hasMore: true,
portosMeta: { schemaVersions: { catalog: 1 } },
}),
})
.mockResolvedValueOnce({
ok: true,
json: async () => ({
ingredients: [{ id: 'a' }],
maxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
tableMaxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
hasMore: false,
portosMeta: { schemaVersions: { catalog: 1 } },
}),
});
applyCatalogChanges.mockResolvedValue({
scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
sources: { applied: 0 }, refs: { applied: 0 }, relations: { applied: 0 },
tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [],
});
await syncWithPeer(catalogPeer);
// First fetch carries the stale cursor; detecting cursor(999) > peerMax(5)
// rewinds ingredients to 0 and re-fetches BEFORE applying, so the stale
// page isn't applied and the rewound page is.
expect(mockFetch.mock.calls[0][0]).toContain('since[ingredients]=999');
expect(mockFetch.mock.calls[1][0]).toContain('since[ingredients]=0');
expect(applyCatalogChanges).toHaveBeenCalledTimes(1);
});
it('advances durably deferred child cursors to reach later tag and scrap parent pages', async () => {
for (const position of ['1', '2']) {
mockFetch.mockResolvedValueOnce({
ok: true,
json: async () => ({
maxSequences: { tags: position, scraps: position }, hasMore: position === '1',
}),
});
}
applyCatalogChanges
.mockResolvedValueOnce({
tags: { deferred: 1, failed: 0 }, scraps: { deferred: 1, failed: 0 },
})
.mockResolvedValueOnce({
tags: { inserted: 1, failed: 0 }, scraps: { inserted: 1, failed: 0 },
});
const result = await syncWithPeer(catalogPeer);
expect(mockFetch).toHaveBeenCalledTimes(2);
expect(mockFetch.mock.calls[1][0]).toContain('since[tags]=1');
expect(mockFetch.mock.calls[1][0]).toContain('since[scraps]=1');
expect(result.catalog.catalogSeqs).toMatchObject({ tags: '2', scraps: '2' });
});
it('holds a kind cursor when that kind had apply failures (parent on a later page)', async () => {
// A ref fails because its parent ingredient is on a later page; the
// ingredient itself applies cleanly in the same batch.
mockFetch.mockResolvedValueOnce({
ok: true,
json: async () => ({
ingredients: [{ id: 'a' }], refs: [{ id: 'r' }],
maxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '5', relations: '0', tags: '0', media: '0' },
hasMore: false,
portosMeta: { schemaVersions: { catalog: 1 } },
}),
});
applyCatalogChanges.mockResolvedValue({
scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
sources: { applied: 0 }, refs: { applied: 0, failed: 1 }, relations: { applied: 0 },
tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [{ kind: 'refs', id: 'r' }],
});
const result = await syncWithPeer(catalogPeer);
// ingredients applied cleanly → its cursor advances; refs failed → its
// cursor is HELD (unset/0) so the next sync re-requests it once the parent
// ingredient has landed.
expect(result.catalog.catalogSeqs.ingredients).toBe('5');
expect(result.catalog.catalogSeqs.refs ?? '0').toBe('0');
});
it('retains ingredient and association cursors during identity reservation, then retries the same page after unfreeze', async () => {
const page = {
ingredients: [{ id: 'reserved-survivor' }], media: [{ ingredientId: 'reserved-survivor', mediaKey: 'later.png' }],
maxSequences: { scraps: '0', ingredients: '7', sources: '0', refs: '0', relations: '0', tags: '0', media: '9' },
hasMore: false, portosMeta: { schemaVersions: { catalog: 1 } },
};
mockFetch.mockResolvedValue({ ok: true, json: async () => page });
applyCatalogChanges.mockResolvedValueOnce({
ingredients: { skipped: 1, failed: 0, identityPending: 1 },
media: { skipped: 1, failed: 0, identityPending: 1 },
});
const pending = await syncWithPeer(catalogPeer);
expect(pending.catalog.catalogSeqs.ingredients ?? '0').toBe('0');
expect(pending.catalog.catalogSeqs.media ?? '0').toBe('0');
applyCatalogChanges.mockResolvedValueOnce({ ingredients: { updated: 1, failed: 0 }, media: { applied: 1, failed: 0 } });
const completed = await syncWithPeer(catalogPeer);
expect(applyCatalogChanges.mock.calls.at(-1)[0].ingredients).toEqual(page.ingredients);
expect(completed.catalog.catalogSeqs.ingredients).toBe('7');
expect(completed.catalog.catalogSeqs.media).toBe('9');
});
it('clears a previously recorded schema gap after a successful catalog drain', async () => {
mockFetch.mockResolvedValueOnce({
ok: true,
json: async () => ({
ingredients: [{ id: 'cat-chr-2' }],
maxSequences: { scraps: '0', ingredients: '3', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
hasMore: false,
portosMeta: { schemaVersions: { catalog: 1 } },
}),
});
applyCatalogChanges.mockResolvedValueOnce({
scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
sources: { applied: 0 }, refs: { applied: 0 }, relations: { applied: 0 },
tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [],
});
const { setPeerSchemaGap } = await import('./instances.js');
await syncWithPeer(catalogPeer);
// A successful, non-blocked drain clears the gap it previously recorded.
expect(setPeerSchemaGap).toHaveBeenCalledWith(catalogPeer.instanceId, 'catalog', null);
});
it.each(['ahead', 'behind'])('records a %s catalog gap without advancing cursors, then retries', async (direction) => {
mockFetch.mockResolvedValue({
ok: true,
json: async () => ({
ingredients: [{ id: 'x' }],
maxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
hasMore: true,
portosMeta: { schemaVersions: { catalog: 99 }, portosVersion: '99.0.0' },
}),
});
const mismatch = new Error('catalog ahead');
mismatch.code = 'CATALOG_SCHEMA_VERSION_AHEAD';
const gap = { category: 'catalog', senderV: direction === 'ahead' ? 99 : 0, receiverV: 10 };
mismatch.diff = { ahead: [], behind: [], [direction]: [gap] };
applyCatalogChanges.mockRejectedValueOnce(mismatch);
const { setPeerSchemaGap } = await import('./instances.js');
const result = await syncWithPeer(catalogPeer);
// Only one apply attempt — we stop draining on the block (no hasMore loop).
expect(applyCatalogChanges).toHaveBeenCalledTimes(1);
expect(result.catalog.blockedBySchema).toBeTruthy();
expect(result.catalog.catalogSeqs.ingredients).toBeUndefined();
// Gap persisted on the local peer row under schemaGaps.catalog.
expect(setPeerSchemaGap).toHaveBeenCalledWith(
catalogPeer.instanceId,
'catalog',
expect.objectContaining({ [direction]: [gap] }),
);
// The next cycle retries the same rows after peers upgrade.
mockFetch.mockResolvedValue({ ok: true, json: async () => ({
ingredients: [{ id: 'x' }], maxSequences: { ingredients: '5' }, hasMore: false,
}) });
applyCatalogChanges.mockResolvedValueOnce({ ingredients: { inserted: 1 } });
const retry = await syncWithPeer(catalogPeer);
expect(mockFetch.mock.calls.at(-1)[0]).toContain('since[ingredients]=0');
expect(retry.catalog.catalogSeqs.ingredients).toBe('5');
});
});
describe('categoriesCoveredByPeerSync (per-direction coverage)', () => {
it('returns outbound from our local subs, grouped by snapshot category', async () => {
const peerSync = await import('./sharing/peerSync.js');
peerSync.getOutboundCoverageForPeer.mockResolvedValueOnce({
universe: new Set(['u1', 'u2']),
pipeline: new Set(['s1']),
mediaCollections: new Set(),
});
const { categoriesCoveredByPeerSync } = await import('./syncOrchestrator.js');
// No peer/ourId → inbound stays empty (no peer query).
const { outbound, inbound } = await categoriesCoveredByPeerSync('peer-inst-1');
expect([...outbound.universe].sort()).toEqual(['u1', 'u2']);
expect([...outbound.pipeline]).toEqual(['s1']);
expect(inbound.universe.size).toBe(0);
expect(inbound.pipeline.size).toBe(0);
});
it('populates inbound from the peer\'s subscriptions targeting our instanceId (NOT our outbound)', async () => {
const peerSync = await import('./sharing/peerSync.js');
// Our OUTBOUND coverage is EMPTY — proving inbound is sourced separately
// (the inbound-vs-outbound distinction). The peer pushes us s9 (series →
// pipeline) and col-7 (mediaCollection).
peerSync.getOutboundCoverageForPeer.mockResolvedValueOnce({
universe: new Set(), pipeline: new Set(), mediaCollections: new Set(),
});
mockFetch.mockResolvedValueOnce({
ok: true,
json: async () => ({
subscriptions: [
{ peerId: 'our-inst-id', recordKind: 'series', recordId: 's9' },
{ peerId: 'our-inst-id', recordKind: 'mediaCollection', recordId: 'col-7' },
],
}),
});
const { categoriesCoveredByPeerSync } = await import('./syncOrchestrator.js');
const { outbound, inbound } = await categoriesCoveredByPeerSync(
'peer-inst-1',
{ ...mockPeer, instanceId: 'peer-inst-1' },
'our-inst-id',
);
// Outbound empty; inbound carries the peer-pushed records.
expect(outbound.pipeline.size).toBe(0);
expect([...inbound.pipeline]).toEqual(['s9']);
expect([...inbound.mediaCollections]).toEqual(['col-7']);
// The peer's /subscriptions endpoint was queried filtered by our id.
const calledUrl = mockFetch.mock.calls.map((c) => c[0]).find((u) => u.includes('/api/peer-sync/subscriptions'));
expect(calledUrl).toContain('peerId=our-inst-id');
});
it('inbound stays empty when the peer query fails (older/offline peer → full snapshot)', async () => {
const peerSync = await import('./sharing/peerSync.js');
peerSync.getOutboundCoverageForPeer.mockResolvedValueOnce({
universe: new Set(), pipeline: new Set(), mediaCollections: new Set(),
});
mockFetch.mockRejectedValueOnce(new Error('peer offline'));
const { categoriesCoveredByPeerSync } = await import('./syncOrchestrator.js');
const { inbound } = await categoriesCoveredByPeerSync(
'peer-inst-1',
{ ...mockPeer, instanceId: 'peer-inst-1' },
'our-inst-id',
);
expect(inbound.universe.size).toBe(0);
expect(inbound.pipeline.size).toBe(0);
expect(inbound.mediaCollections.size).toBe(0);
});
});
describe('getSyncStatus forPeer / cursorForYou', () => {
it('returns our cursor into the requesting peer as cursorForYou', async () => {
getCurrentSeq.mockReturnValue(120);
getMaxSequence.mockResolvedValue('45');
// Our stored cursors: how far we've pulled from each peer. The requesting
// peer ('peer-A') wants its own entry back as its push-frontier toward us.
readJSONFile.mockImplementation(async () => ({
'peer-A': { brainSeq: 88, memorySeq: '30', lastSyncAt: '2026-01-01T00:00:00.000Z' },
'peer-B': { brainSeq: 5 },
}));
const status = await getSyncStatus({ forPeer: 'peer-A' });
expect(status.cursorForYou).toEqual({ brainSeq: 88, memorySeq: '30', lastSyncAt: '2026-01-01T00:00:00.000Z' });
// Our own local maxes are reported under `local`.
expect(status.local.brainSeq).toBe(120);
});
it('returns null cursorForYou when we have never synced the requesting peer', async () => {
readJSONFile.mockImplementation(async () => ({ 'peer-B': { brainSeq: 5 } }));
const status = await getSyncStatus({ forPeer: 'peer-A' });
expect(status.cursorForYou).toBeNull();
});
it('omits cursorForYou entirely when no forPeer is supplied (legacy shape)', async () => {
readJSONFile.mockImplementation(async () => ({ 'peer-A': { brainSeq: 88 } }));
const status = await getSyncStatus({});
expect(status).not.toHaveProperty('cursorForYou');
});
// Regression (#1077, Bug 3): the served local.checksums must be SCOPED to the
// requesting peer (forPeerId === forPeer) so they match the scoped checksum
// the peer's cursor cached during sync. Computing them unscoped (global) made
// every per-record-subscribable category (universe/pipeline/mediaCollections)
// read "behind" forever — including the both-empty case.
it('computes local.checksums scoped to the requesting peer (forPeerId === forPeer)', async () => {
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['mediaCollections']);
dataSync.getChecksum.mockResolvedValue({ checksum: 'scoped-xyz' });
readJSONFile.mockImplementation(async () => ({ 'peer-A': { brainSeq: 88 } }));
const status = await getSyncStatus({ includeChecksums: true, forPeer: 'peer-A' });
expect(dataSync.getChecksum).toHaveBeenCalledWith('mediaCollections', { forPeerId: 'peer-A' });
expect(status.local.checksums.mediaCollections).toBe('scoped-xyz');
});
it('computes UNscoped local.checksums when no forPeer is supplied (self-view)', async () => {
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['mediaCollections']);
dataSync.getChecksum.mockResolvedValue({ checksum: 'global-abc' });
readJSONFile.mockImplementation(async () => ({}));
await getSyncStatus({ includeChecksums: true });
expect(dataSync.getChecksum).toHaveBeenCalledWith('mediaCollections', { forPeerId: undefined });
});
});
// #7943: a persistently broken peer used to be indistinguishable from a
// healthy one — every failure path logged to stdout with only the message,
// and the consolidated cursor write stamped `lastSyncAt` whether or not
// anything actually synced.
describe('failure visibility (#7943)', () => {
const cursorWrites = () => atomicWrite.mock.calls
.filter(([path]) => String(path).includes('instances_sync_cursors'))
.map(([, payload]) => payload);
const lastCursor = () => cursorWrites().at(-1)?.['peer-inst-1'];
const completeEvent = () => instanceEvents.emit.mock.calls
.filter(([event]) => event === 'sync:progress')
.map(([, payload]) => payload)
.find((p) => p.phase === 'complete');
// Serve a category snapshot the sync will try to APPLY. A transport failure
// is NOT a failure for these purposes — fetchPeer degrades it to null and an
// unreachable peer is a legitimately quiet no-op. What must be visible is an
// apply that throws.
const serveSnapshots = () => mockFetch.mockImplementation(async (url) => {
if (url.includes('/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
if (url.includes('/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'remote' }) };
return { ok: true, json: async () => ({}) };
});
let dataSync;
let errorSpy;
beforeEach(async () => {
dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['usage']);
dataSync.getChecksum.mockResolvedValue({ checksum: 'local' });
dataSync.applyRemote.mockResolvedValue({ applied: true, count: 1 });
errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
serveSnapshots();
});
afterEach(() => errorSpy.mockRestore());
it('logs a failed category to stderr WITH a stack frame', async () => {
dataSync.applyRemote.mockRejectedValue(new Error('peer refused the usage snapshot'));
await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
const logged = errorSpy.mock.calls.find(([msg]) => String(msg).includes('usage sync with peer failed'));
expect(logged).toBeTruthy();
// The stack rides as a second argument (logFailureWithStack), so the
// failure names a frame instead of collapsing to one message-only line.
expect(String(logged[1])).toContain('Error: peer refused the usage snapshot');
expect(String(logged[1])).toMatch(/\n\s+at /);
});
it('records lastSyncError and does NOT advance lastSyncAt when every attempted category fails', async () => {
readJSONFile.mockImplementation(async () => ({
'peer-inst-1': { lastSyncAt: '2026-01-01T00:00:00.000Z' },
}));
dataSync.applyRemote.mockRejectedValue(new Error('peer DB was rebuilt'));
await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
const cursor = lastCursor();
expect(cursor.lastSyncSucceeded).toBe(false);
expect(cursor.lastSyncError).toContain('peer DB was rebuilt');
// The stale timestamp stays exactly as it was — it IS when we last
// successfully synced. Advancing it is what made the peer read healthy.
expect(cursor.lastSyncAt).toBe('2026-01-01T00:00:00.000Z');
});
it('carries the failure on the terminal sync:progress complete so the card does not animate to done', async () => {
dataSync.applyRemote.mockRejectedValue(new Error('inbox disk full'));
await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
expect(completeEvent().error).toContain('inbox disk full');
});
it('clears lastSyncError and advances lastSyncAt on a clean cycle', async () => {
readJSONFile.mockImplementation(async () => ({
'peer-inst-1': {
lastSyncAt: '2026-01-01T00:00:00.000Z',
lastSyncError: 'peer DB was rebuilt',
lastSyncSucceeded: false,
},
}));
await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
const cursor = lastCursor();
expect(cursor.lastSyncSucceeded).toBe(true);
expect(cursor).not.toHaveProperty('lastSyncError');
expect(cursor.lastSyncAt).not.toBe('2026-01-01T00:00:00.000Z');
expect(completeEvent().error).toBeNull();
});
it('treats a partial failure as a successful cycle — one live category still advances the clock', async () => {
dataSync.getSupportedCategories.mockReturnValue(['goals', 'usage']);
dataSync.applyRemote.mockImplementation(async (category) => {
if (category === 'goals') throw new Error('goals is broken');
return { applied: true, count: 1 };
});
readJSONFile.mockImplementation(async () => ({
'peer-inst-1': { lastSyncAt: '2026-01-01T00:00:00.000Z' },
}));
await syncWithPeer({ ...mockPeer, syncCategories: { goals: true, usage: true } });
const cursor = lastCursor();
expect(cursor.lastSyncSucceeded).toBe(true);
expect(cursor).not.toHaveProperty('lastSyncError');
expect(cursor.lastSyncAt).not.toBe('2026-01-01T00:00:00.000Z');
});
it('persists lastSyncError when a delta category throws straight out of the sync body', async () => {
// brain/memory/catalog reject out of syncWithPeer rather than being caught
// per-category, so the consolidated cursor write never runs — nothing used
// to record WHY the peer stopped syncing.
readJSONFile.mockImplementation(async () => ({
'peer-inst-1': { brainSeq: 7, lastSyncAt: '2026-01-01T00:00:00.000Z' },
}));
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/sync')) {
return { ok: true, json: async () => ({ changes: [{ id: 'b1' }], maxSeq: 8, hasMore: false }) };
}
return { ok: true, json: async () => ({}) };
});
applyBrainChanges.mockRejectedValue(new Error('brain log unreadable'));
await expect(syncWithPeer({ ...mockPeer, syncCategories: { brain: true } }))
.rejects.toThrow('brain log unreadable');
const cursor = lastCursor();
expect(cursor.lastSyncSucceeded).toBe(false);
expect(cursor.lastSyncError).toContain('brain log unreadable');
expect(cursor.lastSyncAt).toBe('2026-01-01T00:00:00.000Z');
// The pre-existing cursor is preserved, not clobbered by the failure write.
expect(cursor.brainSeq).toBe(7);
});
it('withholds our local failure string from the peer-facing cursorForYou projection', async () => {
// /api/instances/sync-status is reachable by any tailnet machine, and the
// stored message is whatever an exception on THIS host happened to say.
readJSONFile.mockImplementation(async () => ({
'peer-A': {
brainSeq: 88,
lastSyncAt: '2026-01-01T00:00:00.000Z',
lastSyncError: 'ENOENT: /Users/someone/private/path',
lastSyncSucceeded: false,
},
}));
const status = await getSyncStatus({ forPeer: 'peer-A' });
expect(status.cursorForYou).toEqual({ brainSeq: 88, lastSyncAt: '2026-01-01T00:00:00.000Z' });
// The self-view (our own browser, which renders the peer card) keeps it.
expect(status.cursors['peer-A'].lastSyncError).toBe('ENOENT: /Users/someone/private/path');
});
});
describe('sync:progress events', () => {
it('emits start → applied → complete around a sync that moves records', async () => {
mockFetch
.mockResolvedValueOnce({ ok: true, json: async () => ({ changes: [{ id: 'b1' }], maxSeq: 1, hasMore: false }) })
.mockResolvedValueOnce({ ok: true, json: async () => ({ changes: [], maxSeq: 1, hasMore: false }) })
.mockResolvedValueOnce({ ok: true, json: async () => ({ memories: [], maxSequence: '0', hasMore: false }) });
applyBrainChanges.mockResolvedValue({ inserted: 1, updated: 0, deleted: 0, skipped: 0 });
await syncWithPeer({ ...mockPeer, syncCategories: { brain: true, memory: true } });
const progressCalls = instanceEvents.emit.mock.calls
.filter(([event]) => event === 'sync:progress')
.map(([, payload]) => payload);
expect(progressCalls[0]).toEqual({ phase: 'start', peerId: 'peer-inst-1' });
expect(progressCalls).toContainEqual({ phase: 'applied', peerId: 'peer-inst-1', category: 'brain', applied: 1 });
const complete = progressCalls.find(p => p.phase === 'complete');
expect(complete).toMatchObject({ phase: 'complete', peerId: 'peer-inst-1' });
expect(complete.totalApplied).toBeGreaterThanOrEqual(1);
});
it('releases the per-peer lock and still emits complete when the cursor read throws', async () => {
// readCursors → loadCursors → readJSONFile. A throw here (corrupt cursor
// file, disk error) happens AFTER the lock is acquired and the `start`
// emit fires — the finally must release the lock and emit a terminal
// `complete`, or the peer is wedged "syncing" until restart.
readJSONFile.mockRejectedValueOnce(new Error('cursor file corrupt'));
await expect(syncWithPeer({ ...mockPeer, syncCategories: { brain: true } })).rejects.toThrow('cursor file corrupt');
const progress = instanceEvents.emit.mock.calls
.filter(([event]) => event === 'sync:progress')
.map(([, payload]) => payload);
expect(progress).toContainEqual({ phase: 'start', peerId: 'peer-inst-1' });
expect(progress).toContainEqual({ phase: 'complete', peerId: 'peer-inst-1', totalApplied: 0, error: expect.any(String) });
// Lock released: a subsequent sync is NOT short-circuited by syncingPeers.
mockFetch.mockResolvedValue({ ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) });
instanceEvents.emit.mockClear();
await syncWithPeer({ ...mockPeer, syncCategories: { brain: true } });
const reran = instanceEvents.emit.mock.calls.some(([event, p]) => event === 'sync:progress' && p.phase === 'start');
expect(reran).toBe(true);
});
it('emits exactly one complete (totalApplied 0) for a no-op sync — card never sticks on "syncing"', async () => {
// A category enabled but no changes available: lifecycle still settles.
mockFetch.mockResolvedValue({ ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) });
await syncWithPeer({ ...mockPeer, syncCategories: { brain: true } });
const progress = instanceEvents.emit.mock.calls
.filter(([event]) => event === 'sync:progress')
.map(([, payload]) => payload);
const completes = progress.filter(p => p.phase === 'complete');
// Exactly one complete, and no spurious second one from the finally guard.
expect(completes).toEqual([{ phase: 'complete', peerId: 'peer-inst-1', totalApplied: 0, error: null }]);
// No `applied` events when nothing moved.
expect(progress.some(p => p.phase === 'applied')).toBe(false);
});
});
// #1077 Part 1: anti-entropy reconcile. After draining the delta log, brain
// sync compares a whole-brain checksum with the peer and pulls+merges the
// snapshot on a mismatch — the only path that re-converges a peer that missed
// compacted entries.
describe('brain anti-entropy reconcile (#1077)', () => {
// Brain delta drain is always empty here; we exercise the reconcile leg.
const routeFetch = (handlers) => mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => handlers.checksum };
if (url.includes('/api/brain/reconcile/snapshot')) return { ok: true, json: async () => handlers.snapshot };
if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [], maxSequence: '0', hasMore: false }) };
return { ok: true, json: async () => ({}) };
});
it('pulls + merges the snapshot when peer checksum differs from local', async () => {
getBrainChecksum.mockResolvedValue('local-AAA');
applyBrainSnapshot.mockResolvedValue({ inserted: 0, updated: 3, deleted: 1, skipped: 0 });
routeFetch({
checksum: { checksum: 'peer-BBB' },
snapshot: { records: { links: { x: { id: 'x', updatedAt: '2026-02-02T00:00:00.000Z' } } }, checksum: 'peer-BBB' },
});
const result = await syncWithPeer(mockPeer);
expect(applyBrainSnapshot).toHaveBeenCalledTimes(1);
// delta(0) + reconcile merge(3 upd + 1 del) = 4
expect(result.brain.totalApplied).toBe(4);
});
it('does NOT cache the peer checksum when the snapshot relay append fails (#8351)', async () => {
// A cached checksum short-circuits every later cycle, so caching it over
// a merge whose relay never reached our log would strand those records
// outside the log for good. The failure must leave the cursor untouched.
getBrainChecksum.mockResolvedValue('local-AAA');
applyBrainSnapshot.mockRejectedValueOnce(new Error('disk full'));
routeFetch({
checksum: { checksum: 'peer-BBB' },
snapshot: { records: { links: {} }, checksum: 'peer-BBB' },
});
await expect(syncWithPeer(mockPeer)).rejects.toThrow('disk full');
const cachedPeerChecksum = atomicWrite.mock.calls
.filter(([path]) => String(path).includes('instances_sync_cursors'))
.some(([, cursors]) => cursors?.[mockPeer.instanceId]?.brainChecksum === 'peer-BBB');
expect(cachedPeerChecksum).toBe(false);
});
it('SKIPS the snapshot fetch when peer checksum equals our local checksum', async () => {
getBrainChecksum.mockResolvedValue('same-CCC');
routeFetch({ checksum: { checksum: 'same-CCC' }, snapshot: { records: {} } });
await syncWithPeer(mockPeer);
expect(applyBrainSnapshot).not.toHaveBeenCalled();
const snapshotFetches = mockFetch.mock.calls.filter(c => c[0].includes('/api/brain/reconcile/snapshot'));
expect(snapshotFetches).toHaveLength(0);
});
it('SKIPS reconcile entirely when peer checksum matches the cached cursor checksum', async () => {
const typesSig = [...BRAIN_ENTITY_TYPES].sort().join(',');
readJSONFile.mockImplementation(async () => ({
[mockPeer.instanceId]: { brainSeq: 0, brainChecksum: 'cached-DDD', brainChecksumTypes: typesSig },
}));
routeFetch({ checksum: { checksum: 'cached-DDD' }, snapshot: { records: {} } });
await syncWithPeer(mockPeer);
// Cached match → never even computes local checksum or fetches snapshot.
expect(getBrainChecksum).not.toHaveBeenCalled();
expect(applyBrainSnapshot).not.toHaveBeenCalled();
});
it('IGNORES a cached checksum from a different entity-type enrollment (version-skew healing)', async () => {
// An older install skipped unknown types (e.g. `songs`) while applying a
// snapshot yet cached the peer's checksum. Post-upgrade, that cache must
// NOT short-circuit reconcile — a stale/absent type signature is cold.
getBrainChecksum.mockResolvedValue('local-post-upgrade');
readJSONFile.mockImplementation(async () => ({
[mockPeer.instanceId]: {
brainSeq: 0,
brainChecksum: 'cached-DDD', // matches the remote, but from old code
brainChecksumTypes: 'people,projects', // pre-songs enrollment (also covers absent)
},
}));
routeFetch({ checksum: { checksum: 'cached-DDD' }, snapshot: { records: {}, checksum: 'cached-DDD' } });
await syncWithPeer(mockPeer);
// Stale signature → cache treated as cold → local checksum computed,
// mismatch → snapshot pulled and merged.
expect(getBrainChecksum).toHaveBeenCalled();
expect(applyBrainSnapshot).toHaveBeenCalled();
});
it('falls back to delta-only when peer is too old to expose /reconcile/checksum', async () => {
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
if (url.includes('/api/brain/reconcile/checksum')) return { ok: false, status: 404, json: async () => ({}) };
if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [], maxSequence: '0', hasMore: false }) };
return { ok: true, json: async () => ({}) };
});
const result = await syncWithPeer(mockPeer);
expect(applyBrainSnapshot).not.toHaveBeenCalled();
expect(result.brain.totalApplied).toBe(0);
});
});
// AI usage metrics are the one DEFAULT-ON sync category: a fresh peer syncs
// them without the user enabling anything, and the peer-level `syncEnabled`
// master switch (which predates default-on categories and means "don't
// replicate my content here") must not silently retract them.
describe('default-ON categories', () => {
const categoryUrls = () => mockFetch.mock.calls
.map((c) => c[0])
.filter((url) => url.includes('/api/sync/'));
beforeEach(async () => {
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['usage', 'goals']);
dataSync.getChecksum.mockResolvedValue({ checksum: 'local' });
mockFetch.mockImplementation(async (url) => {
if (url.includes('/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
if (url.includes('/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'remote' }) };
return { ok: true, json: async () => ({}) };
});
dataSync.applyRemote.mockResolvedValue({ applied: true, count: 1 });
});
it('pulls usage from a peer whose stored map predates the category', async () => {
// A peer record written before `usage` existed has no key for it — it must
// pick up the shipped default rather than reading as off forever.
await syncWithPeer({ ...mockPeer, syncEnabled: true, syncCategories: { goals: false } });
expect(categoryUrls().some((url) => url.includes('/api/sync/usage/'))).toBe(true);
});
it('keeps pulling usage — and only usage — when the master switch is off', async () => {
await syncWithPeer({ ...mockPeer, syncEnabled: false, syncCategories: { goals: true } });
const urls = categoryUrls();
expect(urls.some((url) => url.includes('/api/sync/usage/'))).toBe(true);
expect(urls.some((url) => url.includes('/api/sync/goals/'))).toBe(false);
});
it('honors an explicit opt-out of the category itself', async () => {
await syncWithPeer({ ...mockPeer, syncEnabled: true, syncCategories: { usage: false } });
expect(categoryUrls().some((url) => url.includes('/api/sync/usage/'))).toBe(false);
});
it('still syncs nothing for a disabled peer', async () => {
getPeers.mockResolvedValue([{ ...mockPeer, enabled: false, syncCategories: { usage: true } }]);
await syncAllPeers();
expect(categoryUrls()).toHaveLength(0);
});
// The peer:online handler gates only on hasAnySyncEnabled, and a default-ON
// category makes that truthy for nearly every peer — so `enabled: false`
// has to be checked there too, or a manual Connect on a disabled peer would
// start syncing it.
it('a disabled peer is not eligible even when its status flips online', async () => {
const disabled = { ...mockPeer, enabled: false, syncCategories: { usage: true } };
getPeers.mockResolvedValue([disabled]);
initSyncOrchestrator();
// instanceEvents is mocked, so invoke the handler the orchestrator just
// registered rather than relying on a real emit.
const [, onPeerOnline] = instanceEvents.on.mock.calls.find(([event]) => event === 'peer:online');
await onPeerOnline(disabled);
await vi.runOnlyPendingTimersAsync();
expect(categoryUrls()).toHaveLength(0);
});
});
// A category refused for a schema gap must not re-download the refused body
// every cycle; only a changed checksum, peer version or local schema retries.
describe('schema-gapped snapshot category', () => {
let dataSync;
const snapshotCalls = () => mockFetch.mock.calls.filter((c) => c[0].includes('/goals/snapshot'));
const gapPeer = (gapOverrides = {}, peerOverrides = {}) => ({
...mockPeer,
version: '2.5.0',
syncCategories: { goals: true },
schemaGaps: {
goals: {
detectedAt: '2026-01-01T00:00:00.000Z', ahead: ['goals'], behind: [],
senderPortosVersion: '2.5.0', checksum: 'remote',
localSchemaVersions: { ...PORTOS_SCHEMA_VERSIONS }, ...gapOverrides,
},
},
...peerOverrides,
});
beforeEach(async () => {
dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['goals']);
mockFetch.mockImplementation(async (url) => {
if (url.includes('/goals/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
if (url.includes('/goals/snapshot')) return { ok: true, json: async () => ({ data: { goals: [] }, checksum: 'remote' }) };
return { ok: true, json: async () => ({}) };
});
});
it('makes no snapshot request while checksum, peer version and local schema are unchanged', async () => {
await syncWithPeer(gapPeer());
expect(snapshotCalls()).toHaveLength(0);
expect(dataSync.applyRemote).not.toHaveBeenCalled();
});
it.each([
['the checksum', {}, { checksum: 'older' }],
['the peer version', { version: '2.6.0' }, {}],
['our local schema versions', {}, { localSchemaVersions: { ...PORTOS_SCHEMA_VERSIONS, goals: -1 } }],
['a gap recorded without retry evidence', {}, { checksum: undefined, localSchemaVersions: undefined }],
])('fetches exactly once when %s changed, and a compatible payload clears the gap', async (_label, peerOverrides, gapOverrides) => {
const { setPeerSchemaGap } = await import('./instances.js');
dataSync.applyRemote.mockResolvedValue({ applied: true, count: 1 });
await syncWithPeer(gapPeer(gapOverrides, peerOverrides));
expect(snapshotCalls()).toHaveLength(1);
expect(setPeerSchemaGap).toHaveBeenCalledWith(mockPeer.instanceId, 'goals', null);
});
it('records the refused checksum and schema versions when a snapshot is blocked', async () => {
const { setPeerSchemaGap } = await import('./instances.js');
dataSync.applyRemote.mockResolvedValue({
applied: false, count: 0,
blockedBySchema: { ahead: ['goals'], behind: [], senderPortosVersion: '2.7.0' },
});
await syncWithPeer({ ...mockPeer, syncCategories: { goals: true } });
expect(setPeerSchemaGap).toHaveBeenCalledWith(mockPeer.instanceId, 'goals', expect.objectContaining({
checksum: 'remote', senderPortosVersion: '2.7.0', localSchemaVersions: PORTOS_SCHEMA_VERSIONS,
}));
});
});
// #5759: `usage` is always dirty AND a map of per-instance slots, so the
// checksum short-circuit alone dragged every instance's digest across the
// wire whenever any one of them advanced.
describe('manifest-scoped snapshot pull (#5759)', () => {
const syncUrls = () => mockFetch.mock.calls.map((c) => c[0]).filter((url) => url.includes('/api/sync/'));
const urlFor = (leg) => syncUrls().find((url) => url.includes(`/usage/${leg}`));
// We already hold two instances; the source peer's own digest advanced.
const localManifest = {
data: { instances: { 'inst-a': '2026-09-01T10:00:00.000Z', 'inst-b': '2026-09-01T10:00:00.000Z' }, tombstones: [] },
checksum: 'local-manifest',
};
const remoteManifest = {
data: { instances: { 'inst-a': '2026-09-01T10:00:00.000Z', 'inst-b': '2026-09-01T12:00:00.000Z' }, tombstones: [] },
checksum: 'remote-manifest',
portosMeta: { portosVersion: '2.56.0', schemaVersions: {} },
};
let dataSync;
beforeEach(async () => {
dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['usage']);
dataSync.getManifest.mockResolvedValue(localManifest);
dataSync.applyRemote.mockResolvedValue({ applied: true, count: 1 });
mockFetch.mockImplementation(async (url) => {
if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'remote-manifest' }) };
if (url.includes('/usage/manifest')) return { ok: true, json: async () => remoteManifest };
if (url.includes('/usage/snapshot')) return { ok: true, json: async () => ({ data: { instances: { 'inst-b': {} } }, checksum: 'remote-manifest' }) };
return { ok: true, json: async () => ({}) };
});
});
it('fetches only the slot whose capturedAt advanced', async () => {
await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
expect(urlFor('manifest')).toBeTruthy();
// `inst-a` is level on both sides, so it must not ride the wire.
expect(urlFor('snapshot')).toContain('slots=inst-b');
expect(urlFor('snapshot')).not.toContain('inst-a');
// `?forPeer=` already opened the query string.
expect(urlFor('snapshot')).toContain('forPeer=our-inst-id&slots=');
});
it('caches the manifest checksum, not the snapshot response checksum', async () => {
// A digest landing between the two fetches would make the snapshot
// describe state we did not pull; caching that would skip it forever.
mockFetch.mockImplementation(async (url) => {
if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'remote-manifest' }) };
if (url.includes('/usage/manifest')) return { ok: true, json: async () => remoteManifest };
if (url.includes('/usage/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'even-newer' }) };
return { ok: true, json: async () => ({}) };
});
const result = await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
expect(result.usage.checksum).toBe('remote-manifest');
});
it('applies the tombstones without a snapshot fetch when no slot moved', async () => {
// A retirement advances no capturedAt, so the checksum moves and the
// manifest diff comes back empty — the tombstones still have to land.
const tombstones = [{ instanceId: 'inst-a', deletedAt: '2026-09-02T00:00:00.000Z' }];
mockFetch.mockImplementation(async (url) => {
if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'retired' }) };
if (url.includes('/usage/manifest')) return { ok: true, json: async () => ({ data: { instances: localManifest.data.instances, tombstones }, checksum: 'retired' }) };
return { ok: true, json: async () => ({}) };
});
await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
expect(urlFor('snapshot')).toBeUndefined();
expect(dataSync.applyRemote).toHaveBeenCalledWith('usage', { instances: {}, tombstones }, expect.anything());
});
// Backward compatibility: the source peer runs the pre-manifest code and
// 404s the endpoint. The whole-snapshot leg is then exactly the old path.
it('falls back to the whole snapshot against a pre-manifest peer', async () => {
mockFetch.mockImplementation(async (url) => {
if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'remote-full' }) };
if (url.includes('/usage/manifest')) return { ok: false, status: 404, json: async () => ({}) };
if (url.includes('/usage/snapshot')) return { ok: true, json: async () => ({ data: { instances: { 'inst-a': {}, 'inst-b': {} } }, checksum: 'remote-full' }) };
return { ok: true, json: async () => ({}) };
});
const result = await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
expect(urlFor('snapshot')).not.toContain('slots=');
expect(result.usage.checksum).toBe('remote-full');
expect(dataSync.applyRemote).toHaveBeenCalledWith('usage', { instances: { 'inst-a': {}, 'inst-b': {} } }, expect.anything());
});
// The slot cap bounds the request URL; without leaving the checksum
// unadvanced, the slots it dropped would sit behind a checksum that now
// matches and would never be fetched again.
it('leaves the checksum unadvanced when the diff exceeds the slot cap', async () => {
const { MAX_MANIFEST_SLOTS } = await import('../lib/syncManifest.js');
const instances = Object.fromEntries(
Array.from({ length: MAX_MANIFEST_SLOTS + 5 }, (_, i) => [`inst-${i}`, '2026-09-01T12:00:00.000Z']),
);
dataSync.getManifest.mockResolvedValue({ data: { instances: {}, tombstones: [] }, checksum: 'local' });
mockFetch.mockImplementation(async (url) => {
if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'wide' }) };
if (url.includes('/usage/manifest')) return { ok: true, json: async () => ({ data: { instances, tombstones: [] }, checksum: 'wide' }) };
if (url.includes('/usage/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'wide' }) };
return { ok: true, json: async () => ({}) };
});
const result = await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
expect(urlFor('snapshot').match(/inst-\d+/g)).toHaveLength(MAX_MANIFEST_SLOTS);
expect(result.usage.checksum).toBeNull();
});
// The other direction of the same compatibility rule: a category with no
// manifest must not pay for a manifest probe at all.
it('never probes for a manifest on a category that serves none', async () => {
dataSync.getSupportedCategories.mockReturnValue(['goals']);
dataSync.getManifest.mockResolvedValue(null);
mockFetch.mockImplementation(async (url) => {
if (url.includes('/goals/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
if (url.includes('/goals/snapshot')) return { ok: true, json: async () => ({ data: { goals: [] }, checksum: 'remote' }) };
return { ok: true, json: async () => ({}) };
});
await syncWithPeer({ ...mockPeer, syncCategories: { goals: true } });
expect(syncUrls().some((url) => url.includes('/manifest'))).toBe(false);
});
});
describe('syncAllPeers', () => {
afterEach(async () => {
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['goals', 'character', 'digitalTwin', 'meatspace']);
});
const brainOnlyPeer = { ...mockPeer, syncCategories: { brain: true, usage: false } };
const serveBrainNoOp = () => mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
return { ok: true, json: async () => ({}) };
});
it('emits no per-tick logs for unchanged no-op cycles', async () => {
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue([]);
getPeers.mockResolvedValue([brainOnlyPeer]);
serveBrainNoOp();
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
try {
await syncAllPeers();
await syncAllPeers();
expect(logSpy).not.toHaveBeenCalled();
expect(errorSpy).not.toHaveBeenCalled();
} finally {
logSpy.mockRestore();
errorSpy.mockRestore();
}
});
it('logs a cycle when online peer membership changes', async () => {
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue([]);
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
getPeers.mockResolvedValue([]);
try {
await syncAllPeers();
getPeers.mockResolvedValue([brainOnlyPeer]);
serveBrainNoOp();
await syncAllPeers();
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync cycle: 1 peer online'));
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync starting with peer 1'));
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync cycle complete: 0 changes applied across 1 peer'));
} finally {
logSpy.mockRestore();
}
});
it('keeps the cycle summary when a sync applies changes', async () => {
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue([]);
getPeers.mockResolvedValue([brainOnlyPeer]);
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
if (url.includes('/api/brain/sync')) return {
ok: true,
json: async () => ({ changes: [{ seq: 1, op: 'create', type: 'people', id: 'p1', record: {} }], maxSeq: 1, hasMore: false }),
};
return { ok: true, json: async () => ({}) };
});
applyBrainChanges.mockResolvedValueOnce({ inserted: 1, updated: 0, deleted: 0, skipped: 0 });
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
try {
await syncAllPeers();
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Synced with peer 1: 1 brain changes'));
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync cycle complete: 1 change applied across 1 peer'));
} finally {
logSpy.mockRestore();
}
});
it('keeps category failure lines and the cycle summary visible', async () => {
const dataSync = await import('./dataSync.js');
dataSync.getSupportedCategories.mockReturnValue(['usage']);
dataSync.getChecksum.mockResolvedValue({ checksum: 'local' });
dataSync.applyRemote.mockRejectedValue(new Error('peer refused the usage snapshot'));
getPeers.mockResolvedValue([{ ...mockPeer, syncCategories: { usage: true } }]);
mockFetch.mockImplementation(async (url) => {
if (url.includes('/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
if (url.includes('/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'remote' }) };
return { ok: true, json: async () => ({}) };
});
const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
try {
await syncAllPeers();
expect(errorSpy.mock.calls.some(([message]) => String(message).includes('usage sync with peer 1 failed'))).toBe(true);
expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync cycle complete: 0 changes applied across 1 peer'));
} finally {
logSpy.mockRestore();
errorSpy.mockRestore();
}
});
it('iterates online peers with instanceId', async () => {
const onlinePeer = { ...mockPeer };
const offlinePeer = { ...mockPeer, name: 'offline', status: 'offline', instanceId: 'p2' };
const disabledPeer = { ...mockPeer, name: 'disabled', enabled: false, instanceId: 'p3' };
const noIdPeer = { ...mockPeer, name: 'no-id', instanceId: undefined };
getPeers.mockResolvedValue([onlinePeer, offlinePeer, disabledPeer, noIdPeer]);
// For the single qualifying peer: brain delta + reconcile checksum (#1077)
// + memory fetch. URL-routed so it doesn't depend on call order.
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [], maxSequence: '0', hasMore: false }) };
return { ok: true, json: async () => ({}) };
});
await syncAllPeers();
// Only 1 peer qualifies (online + enabled + has instanceId): brain delta +
// reconcile checksum + memory. Match by URL so unrelated fetches don't skew.
const brainSyncCalls = mockFetch.mock.calls.filter(c => c[0].includes('/api/brain/sync'));
const reconcileCalls = mockFetch.mock.calls.filter(c => c[0].includes('/api/brain/reconcile/checksum'));
const memoryCalls = mockFetch.mock.calls.filter(c => c[0].includes('/api/memory/sync'));
expect(brainSyncCalls).toHaveLength(1);
expect(reconcileCalls).toHaveLength(1);
expect(memoryCalls).toHaveLength(1);
});
});
// #1077 Bug 1: compaction must floor on how much each brain-enabled peer has
// pulled FROM us (peer.remoteSyncSeqs.cursorForYou.brainSeq), NOT our outbound
// pull cursor into them (cursors[peerId].brainSeq). Flooring on the wrong
// cursor drops log entries a peer hasn't consumed → that peer can never learn
// those records (the divergence this issue fixes).
describe('brain log compaction floor (#1077)', () => {
beforeEach(() => {
getCurrentSeq.mockReturnValue(200);
// No changes to pull, so each peer's sync is a no-op drain.
mockFetch.mockResolvedValue({ ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) });
});
it('floors on the MIN of peers consumption of our log (cursorForYou.brainSeq)', async () => {
const peerA = { ...mockPeer, instanceId: 'A', remoteSyncSeqs: { cursorForYou: { brainSeq: 150 } } };
const peerB = { ...mockPeer, name: 'B', instanceId: 'B', remoteSyncSeqs: { cursorForYou: { brainSeq: 90 } } };
getPeers.mockResolvedValue([peerA, peerB]);
// Our OUTBOUND pull cursors are high — the old (buggy) floor would use these.
readJSONFile.mockImplementation(async () => ({ A: { brainSeq: 199 }, B: { brainSeq: 199 } }));
await syncAllPeers();
// Floor = min(150, 90) = 90 — NOT min(199,199), and NOT our pull cursors.
expect(compactLog).toHaveBeenCalledWith(90);
});
it('floors at 0 when a brain-enabled peer has not reported its cursor into us', async () => {
const reported = { ...mockPeer, instanceId: 'A', remoteSyncSeqs: { cursorForYou: { brainSeq: 150 } } };
// peer B is brain-enabled but never told us how far it pulled — must NOT
// assume it caught up. Floor drops to 0 so we keep everything for it.
const unreported = { ...mockPeer, name: 'B', instanceId: 'B', remoteSyncSeqs: null };
getPeers.mockResolvedValue([reported, unreported]);
readJSONFile.mockImplementation(async () => ({}));
await syncAllPeers();
expect(compactLog).toHaveBeenCalledWith(0);
});
it('calls compactLog(0) for compatibility-preserving compaction when peers are configured but none is brain-enabled (#5439)', async () => {
const memoryOnlyPeer = {
...mockPeer,
instanceId: 'A',
syncCategories: { brain: false, memory: true }
};
getPeers.mockResolvedValue([memoryOnlyPeer]);
readJSONFile.mockImplementation(async () => ({}));
await syncAllPeers();
expect(compactLog).toHaveBeenCalledWith(0);
});
it('calls compactLog(0) for compatibility-preserving compaction when no peers are configured (#5439)', async () => {
getPeers.mockResolvedValue([]);
readJSONFile.mockImplementation(async () => ({}));
await syncAllPeers();
expect(compactLog).toHaveBeenCalledWith(0);
});
});
describe('initSyncOrchestrator', () => {
it('registers peer:online event handler', () => {
initSyncOrchestrator();
expect(instanceEvents.on).toHaveBeenCalledWith('peer:online', expect.any(Function));
});
it('sets up periodic sync interval', async () => {
initSyncOrchestrator();
getPeers.mockResolvedValue([]);
// Advance past the interval (60s) and AWAIT the triggered cycle so its
// fire-and-forget logs settle inside the test rather than after it returns
// (the async variant flushes the promise chain the timer kicked off).
await vi.advanceTimersByTimeAsync(60000);
// syncAllPeers should have been triggered
expect(getPeers).toHaveBeenCalled();
});
// #6851 — the tombstone sweep no longer rides every 60s tick; it's gated
// to once per TOMBSTONE_SWEEP_INTERVAL_MS (1h), except the very first tick
// after boot always runs it so a fresh process doesn't wait an hour.
it('runs the tombstone sweep on the first tick after boot', async () => {
initSyncOrchestrator();
getPeers.mockResolvedValue([]);
await vi.advanceTimersByTimeAsync(60000);
expect(sweepTombstones).toHaveBeenCalledTimes(1);
});
it('does not run the tombstone sweep again on the very next tick (60s later)', async () => {
initSyncOrchestrator();
getPeers.mockResolvedValue([]);
await vi.advanceTimersByTimeAsync(60000); // first tick — sweeps
await vi.advanceTimersByTimeAsync(60000); // second tick, 60s later — gated
expect(sweepTombstones).toHaveBeenCalledTimes(1);
});
it('runs the tombstone sweep again once a full hour has elapsed', async () => {
initSyncOrchestrator();
getPeers.mockResolvedValue([]);
await vi.advanceTimersByTimeAsync(60000); // first tick (t=60s) — sweeps
await vi.advanceTimersByTimeAsync(60 * 60 * 1000); // t=1h60s — due again
expect(sweepTombstones).toHaveBeenCalledTimes(2);
});
it('resets the tombstone-sweep gate on failure so the very next tick retries', async () => {
initSyncOrchestrator();
getPeers.mockResolvedValue([]);
sweepTombstones.mockRejectedValueOnce(new Error('db blip'));
await vi.advanceTimersByTimeAsync(60000); // first tick — sweeps, rejects
await vi.advanceTimersByTimeAsync(60000); // second tick, only 60s later — retries because the failure cleared the gate
expect(sweepTombstones).toHaveBeenCalledTimes(2);
});
it('runs syncAllPeers every tick but gates brain tombstone sweeps to six hours', async () => {
const tickMs = 60 * 1000;
const sixHoursMs = 6 * 60 * 60 * 1000;
expect(BRAIN_TOMBSTONE_SWEEP_INTERVAL_MS).toBe(sixHoursMs);
initSyncOrchestrator();
getPeers.mockResolvedValue([]);
await vi.advanceTimersByTimeAsync(tickMs);
expect(sweepBrainTombstones).toHaveBeenCalledTimes(1); // first tick after boot
for (let tick = 1; tick < 60; tick += 1) {
await vi.advanceTimersByTimeAsync(tickMs);
}
expect(getPeers).toHaveBeenCalledTimes(60); // syncAllPeers fires every tick
expect(compactLog).toHaveBeenCalledTimes(60); // brain-sync-log compaction stays on every tick
expect(sweepBrainTombstones).toHaveBeenCalledTimes(1); // no repeat across 60 one-minute ticks
expect(sweepTombstones).toHaveBeenCalledTimes(1); // gated on the second tick
await vi.advanceTimersByTimeAsync(sixHoursMs - (60 * tickMs));
expect(sweepBrainTombstones).toHaveBeenCalledTimes(1); // still before six hours since the first sweep
await vi.advanceTimersByTimeAsync(tickMs);
expect(sweepBrainTombstones).toHaveBeenCalledTimes(2);
});
it('does not retry a failed brain sweep before six hours', async () => {
initSyncOrchestrator();
getPeers.mockResolvedValue([]);
sweepBrainTombstones.mockRejectedValueOnce(new Error('db blip'));
await vi.advanceTimersByTimeAsync(60 * 1000);
await vi.advanceTimersByTimeAsync(60 * 1000);
expect(sweepBrainTombstones).toHaveBeenCalledTimes(1);
});
});
describe('stopSyncOrchestrator', () => {
it('clears the interval', () => {
initSyncOrchestrator();
stopSyncOrchestrator();
getPeers.mockResolvedValue([]);
vi.advanceTimersByTime(120000);
// getPeers should not be called after stopping
expect(getPeers).not.toHaveBeenCalled();
});
it('removes the peer:online event listener', () => {
initSyncOrchestrator();
stopSyncOrchestrator();
expect(instanceEvents.removeListener).toHaveBeenCalledWith('peer:online', expect.any(Function));
});
});
// #8710: a DB restore discards rows the memory/Catalog cursors already passed.
describe('rewindPostgresSyncCursors', () => {
const ZERO_CATALOG = { scraps: '0', ingredients: '0', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' };
let store;
beforeEach(() => {
store = {
'peer-inst-1': {
brainSeq: 42, memorySeq: '1000000000000050',
catalogSeqs: { ...ZERO_CATALOG, ingredients: '1000000000000009' },
checksums: { goals: 'g1' }, brainChecksum: 'b1', lastSyncAt: '2026-01-01T00:00:00.000Z',
},
'peer-inst-2': { memorySeq: '1000000000000007' },
};
readJSONFile.mockImplementation(async () => structuredClone(store));
atomicWrite.mockImplementation(async (path, payload) => {
if (String(path).includes('instances_sync_cursors')) store = structuredClone(payload);
});
});
it('zeroes memory and every Catalog kind for every peer, leaving brain and checksum state', async () => {
const { rewindPostgresSyncCursors } = await import('./syncOrchestrator.js');
expect(await rewindPostgresSyncCursors()).toBe(2);
expect(store['peer-inst-1']).toEqual({
brainSeq: 42, memorySeq: '0', catalogSeqs: ZERO_CATALOG,
checksums: { goals: 'g1' }, brainChecksum: 'b1', lastSyncAt: '2026-01-01T00:00:00.000Z',
});
expect(store['peer-inst-2']).toEqual({ memorySeq: '0', catalogSeqs: ZERO_CATALOG });
});
it('keeps the rewind when a sync that read cursors before it finishes afterwards', async () => {
const { rewindPostgresSyncCursors } = await import('./syncOrchestrator.js');
const peer = { ...mockPeer, syncCategories: { memory: true } };
mockFetch.mockImplementation(async (url) => {
if (url.includes('/api/memory/sync')) {
// The restore completes while this pull is on the wire.
await rewindPostgresSyncCursors();
return { ok: true, json: async () => ({ memories: [{ id: 'm1' }], maxSequence: '1000000000000060', hasMore: false }) };
}
return { ok: true, json: async () => ({}) };
});
applyMemoryChanges.mockResolvedValue({ inserted: 1, updated: 0 });
await syncWithPeer(peer);
expect(mockFetch.mock.calls.some(([url]) => url.includes('since=1000000000000050'))).toBe(true);
expect(store['peer-inst-1'].memorySeq).toBe('0');
expect(store['peer-inst-1'].catalogSeqs).toEqual(ZERO_CATALOG);
});
});
});