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
/**
* Foundation rollback fidelity — verified against the REAL universe write path.
*
* The main `foundationJudge.test.js` suite stubs `updateUniverse` with a shallow
* merge, so it cannot see what actually stalled the gate in production: undoing a
* character repair is ITSELF a content change, and the real `updateUniverse`
* re-stamps `updatedAt` on every canon entry whose content changed (the
* canon→catalog LWW clock). A byte-comparison of the checkpoint therefore failed
* on a perfectly faithful revert, and the autopilot paused with
* "checkpoint verification failed after rollback" every single time a character
* repair was rolled back.
*
* These tests run the checkpoint/restore round-trip through the actual
* universeBuilder store (file-backed, in a per-suite tmpdir) so the write path's
* stamping and pointer-preservation behavior is exercised, not re-implemented.
*/
import { describe, it, expect, vi, beforeEach, afterAll } from 'vitest';
import { mkdtempSync, rmSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { mockNoPeerSync, mockNoPeers } from '../../lib/mockPathsDataRoot.js';
const TEST_DATA_ROOT = mkdtempSync(join(tmpdir(), 'foundation-rollback-test-'));
vi.mock('../../lib/fileUtils.js', async (importActual) => {
const actual = await importActual();
return {
...actual,
PATHS: { ...actual.PATHS, data: TEST_DATA_ROOT },
// Every sheet filename "exists" so mergePreservedSheetPointers takes its
// preserve branch — the behavior this suite asserts the comparison tolerates.
resolveImageRef: vi.fn((ref) => (typeof ref === 'string' && ref ? `/mock/refs/${ref}` : null)),
};
});
vi.mock('../instances.js', () => mockNoPeers());
vi.mock('../sharing/peerSync.js', () => mockNoPeerSync());
// Everything the foundation judge needs but this round-trip doesn't exercise.
vi.mock('../stageRunner.js', () => ({
runStagedLLM: vi.fn(),
resolveStageContext: vi.fn(async () => ({ contextWindow: 200_000 })),
resolveJudgeForStage: vi.fn(async () => ({ provider: { id: 'judge-x' }, model: 'jm-heavy' })),
}));
vi.mock('../promptService.js', () => ({ getStage: vi.fn(() => ({ name: 'writer' })) }));
vi.mock('./issues.js', async (importActual) => ({
...(await importActual()),
listIssues: vi.fn(async () => []),
}));
vi.mock('./seriesCanon.js', async (importActual) => ({
...(await importActual()),
getSeriesCanon: vi.fn(async () => ({ characters: [] })),
}));
vi.mock('./arcPlanner.js', async (importActual) => ({
...(await importActual()),
restoreArcState: vi.fn(async () => ({ restored: true, episodesRestored: 0 })),
snapshotArcState: vi.fn(async () => ({ seriesId: 'ser-1', arc: null, seasons: [], episodes: [] })),
}));
// In-memory series record — the series store isn't what's under test here; the
// universe canon write path is.
let seriesState = null;
vi.mock('./series.js', async (importActual) => ({
...(await importActual()),
getSeries: vi.fn(async () => structuredClone(seriesState)),
updateSeries: vi.fn(async (_id, patch) => {
seriesState = { ...seriesState, ...structuredClone(patch) };
return structuredClone(seriesState);
}),
}));
// Imported after the mocks (which are hoisted above the TEST_DATA_ROOT literal)
// so the mocked `PATHS.data` is in place before the store modules read it.
const { BIBLE_KEYS } = await import('../../lib/storyBible.js');
const { createUniverse, getUniverse, updateUniverse, PREMISE_MAX } = await import('../universeBuilder.js');
const {
snapshotFoundationState,
restoreFoundationState,
getFoundationJudge,
__testing,
} = await import('./foundationJudge.js');
afterAll(() => rmSync(TEST_DATA_ROOT, { recursive: true, force: true }));
const CAST = [
{
name: 'Example Lead',
role: 'protagonist',
want: 'to reopen the gateway network',
need: 'to stop bargaining with the dead',
referenceSheetImageRef: 'lead-sheet.png',
imageRefs: ['lead-1.png'],
},
{ name: 'Example Rival', role: 'antagonist', want: 'to keep the gates shut', need: 'to be believed' },
];
async function seedFoundation() {
const universe = await createUniverse({
name: `Example Universe ${Math.random().toString(36).slice(2, 8)}`,
logline: 'world before',
premise: 'rules before',
styleNotes: 'style before',
influences: { embrace: ['Example'], avoid: [] },
characters: CAST,
places: [{ name: 'Example Gatehouse', description: 'a shuttered relay station', imageRefs: ['gate-1.png'] }],
});
seriesState = {
id: 'ser-1',
universeId: universe.id,
styleNotes: 'voice before',
styleGuide: null,
characterArcs: [{ characterName: 'Example Lead', want: 'to reopen the network', status: 'draft' }],
};
return universe;
}
beforeEach(() => {
vi.clearAllMocks();
});
describe('restoreFoundationState — against the real universe write path', () => {
it('reports a character rollback as restored even though the write path re-stamps updatedAt', async () => {
const universe = await seedFoundation();
const checkpoint = await snapshotFoundationState('ser-1');
// What a character repair does: rewrite the framework fields of the existing
// cast through the mutator form, and add a character the judge asked for.
await updateUniverse(universe.id, (latest) => ({
characters: [
...latest.characters.map((c) => ({ ...c, need: `${c.need} (rewritten by the repair)` })),
{ name: 'Example Confidant', role: 'supporting', want: 'to be trusted', need: 'to trust' },
],
}));
seriesState = {
...seriesState,
characterArcs: [
...seriesState.characterArcs,
{ characterName: 'Example Confidant', want: 'a seat at the table', status: 'draft' },
],
};
const rollback = await restoreFoundationState('ser-1', checkpoint);
expect(rollback).toMatchObject({ restored: true, mismatchedFields: [] });
expect(rollback.reason).toBeNull();
const after = await getUniverse(universe.id);
expect(after.characters.map((c) => c.name)).toEqual(['Example Lead', 'Example Rival']);
expect(after.characters.map((c) => c.need)).toEqual([
'to stop bargaining with the dead',
'to be believed',
]);
expect(seriesState.characterArcs).toHaveLength(1);
// The reason the naive byte-comparison failed: the revert legitimately moved
// the LWW clock forward on every entry it changed back.
const beforeStamp = checkpoint.universe.characters.find((c) => c.name === 'Example Lead').updatedAt;
const afterStamp = after.characters.find((c) => c.name === 'Example Lead').updatedAt;
expect(Date.parse(afterStamp)).toBeGreaterThan(Date.parse(beforeStamp));
});
it('re-pins the checkpoint verdict on a verified rewind, and leaves it alone on a failed one', async () => {
// The cached verdict is keyed by a content hash, so after a rewind the
// stored one describes content that no longer exists — and the gate's next
// read (a resume, the UI) buys a whole judge call to learn a score the
// rewind already had. Only a VERIFIED restore may put it back.
await seedFoundation();
const checkpoint = await snapshotFoundationState('ser-1');
const judge = {
seriesId: 'ser-1', status: 'complete', sourceInputsHash: 'hash-before-repair',
weightedScore: 6.5, cached: true,
dimensions: { character: { score: 5, gap: 'thin lead', fix: 'build the chain' } },
};
const rollback = await restoreFoundationState('ser-1', checkpoint, { judge });
expect(rollback.restored).toBe(true);
const repinned = await getFoundationJudge('ser-1');
expect(repinned).toMatchObject({ sourceInputsHash: 'hash-before-repair', weightedScore: 6.5 });
// `cached` is a per-read flag, not part of the stored verdict.
expect(repinned).not.toHaveProperty('cached');
const corrupted = structuredClone(checkpoint);
corrupted.universe.premise = 'x'.repeat(PREMISE_MAX + 100);
const failed = await restoreFoundationState('ser-1', corrupted, {
judge: { ...judge, sourceInputsHash: 'hash-that-must-not-be-pinned' },
});
expect(failed.restored).toBe(false);
expect((await getFoundationJudge('ser-1')).sourceInputsHash).toBe('hash-before-repair');
});
it('still reports a mismatch — naming the field — when authored content does not come back', async () => {
const universe = await seedFoundation();
const checkpoint = await snapshotFoundationState('ser-1');
// A checkpoint the write path provably cannot reproduce: an over-cap premise
// comes back truncated by the sanitizer, so the restored record legitimately
// differs from what was asked for — exactly the case the check exists for.
const corrupted = structuredClone(checkpoint);
corrupted.universe.premise = 'x'.repeat(PREMISE_MAX + 100);
const rollback = await restoreFoundationState('ser-1', corrupted);
expect(rollback.restored).toBe(false);
expect(rollback.mismatchedFields).toContain('universe.premise');
expect(rollback.reason).toContain('universe.premise');
// Untouched fields stay out of the diagnosis so the pause names one thing.
expect(rollback.mismatchedFields).not.toContain('universe.characters');
await getUniverse(universe.id);
});
it('ignores only the write-path-owned canon fields, not authored ones', () => {
const { mismatchedFoundationFields, CANON_WRITE_PATH_OWNED_FIELDS } = __testing;
const entry = {
id: 'chr-1', name: 'Example Lead', need: 'trust',
updatedAt: '2026-01-01T00:00:00.000Z',
referenceSheetImageRef: 'a.png', referenceSheets: { front: 'f.png' }, imageRefs: ['a.png'],
};
const snap = (character) => ({
universeId: 'uni-1',
universe: { logline: 'L', premise: 'P', styleNotes: 'S', influences: {}, characters: [character] },
series: { styleNotes: 'V', styleGuide: null, characterArcs: [] },
arcState: { arc: null, seasons: [], episodes: [] },
});
// Every owned field differing → still a faithful restore.
const volatile = {
...entry,
updatedAt: '2026-08-11T12:00:00.000Z',
referenceSheetImageRef: 'b.png', referenceSheets: { front: 'g.png' }, imageRefs: ['a.png', 'b.png'],
};
expect(CANON_WRITE_PATH_OWNED_FIELDS).toContain('updatedAt');
expect(mismatchedFoundationFields(snap(entry), snap(volatile))).toEqual([]);
// An authored field differing → still caught.
expect(mismatchedFoundationFields(snap(entry), snap({ ...volatile, need: 'something else' })))
.toEqual(['universe.characters']);
});
it('strips the write-path-owned fields from EVERY canon array, not just characters', () => {
const { comparableUniverseFields } = __testing;
const owned = {
updatedAt: '2026-01-01T00:00:00.000Z',
referenceSheetImageRef: 'a.png',
referenceSheets: { front: 'f.png' },
imageRefs: ['a.png'],
};
// No `characters` key at all — the old `characters`-only guard bailed out
// here and returned every other canon array with its owned fields intact.
const universe = {
logline: 'L',
...Object.fromEntries(BIBLE_KEYS
.filter((key) => key !== 'characters')
.map((key) => [key, [{ id: `${key}-1`, name: `Example ${key}`, ...owned }]])),
};
const comparable = comparableUniverseFields(universe);
expect(comparable.logline).toBe('L');
for (const key of BIBLE_KEYS.filter((k) => k !== 'characters')) {
expect(Object.keys(comparable[key][0]).sort()).toEqual(['id', 'name']);
}
});
it('tolerates the write path re-stamping a NON-character canon entry', async () => {
const universe = await seedFoundation();
const before = await getUniverse(universe.id);
// A worldbuilding repair rewriting an existing place — the same shape of
// edit a character repair makes, on the canon array the character-only
// stripping used to miss.
await updateUniverse(universe.id, (latest) => ({
places: latest.places.map((p) => ({ ...p, description: `${p.description} (rewritten by the repair)` })),
}));
// ...and the faithful undo, which is itself a content change.
await updateUniverse(universe.id, () => ({ places: structuredClone(before.places) }));
const after = await getUniverse(universe.id);
const { comparableUniverseFields } = __testing;
// Authored content came back byte-for-byte once the owned fields are gone.
expect(comparableUniverseFields(after).places).toEqual(comparableUniverseFields(before).places);
// ...and the reason a raw comparison would have failed: the LWW clock moved.
expect(Date.parse(after.places[0].updatedAt))
.toBeGreaterThan(Date.parse(before.places[0].updatedAt));
});
it('distinguishes an absent checkpoint field from a null one', () => {
const { mismatchedFoundationFields } = __testing;
const base = {
universeId: 'uni-1',
universe: { logline: 'L', premise: 'P', styleNotes: 'S', influences: {}, characters: [] },
arcState: { arc: null, seasons: [], episodes: [] },
};
// Checkpoint never carried a styleGuide (the restore skips absent fields), but
// the repair added one — an unrevertable leftover the verification must catch.
const checkpoint = { ...base, series: { styleNotes: 'V', characterArcs: [] } };
const after = { ...base, series: { styleNotes: 'V', styleGuide: null, characterArcs: [] } };
expect(mismatchedFoundationFields(checkpoint, after)).toEqual(['series.styleGuide']);
});
});