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 { describe, it, expect, beforeEach, afterAll, vi } from 'vitest';
import { mkdtempSync, rmSync, readdirSync, unlinkSync, existsSync, statSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { mockNoPeerSync, mockNoPeers } from '../lib/mockPathsDataRoot.js';
// Create the tempRoot at top-level so PATHS.data resolves before any
// service module runs its `const STATE_PATH = join(PATHS.data, ...)` at
// import time. universeBuilder.js reads PATHS.data eagerly at module init,
// so a per-test `let tempRoot = mkdtempSync()` would land too late.
//
// Vitest module-scoping caveat: this mock is sticky for the entire worker
// — every service this file imports (universeBuilder, series, issues)
// captures the redirected PATHS at THEIR module init. Any other test file
// loaded by the same Vitest worker that imports those same services will
// inherit our redirected PATHS through the shared module cache. Vitest's
// default `pool: 'forks'` isolates by-file so this is safe today; if the
// project ever switches to `pool: 'threads'` with shared module caches,
// this file should be wrapped in `vi.isolate()` or moved into its own
// project to avoid cross-test PATHS leakage.
const tempRoot = mkdtempSync(join(tmpdir(), 'importer-test-'));
// Mock fileUtils.js so every PATHS member points under tempRoot — not
// just `data`. The importer's transitive imports (universeBuilder,
// series, issues, runner) only touch PATHS.data today, but if a future
// change starts writing under PATHS.logs / PATHS.runs / PATHS.cache,
// those writes would leak into the developer's working tree under the
// previous "override data only" pattern. Redirecting every key keeps
// tests hermetic regardless of which PATHS member the SUT picks up.
//
// Spread the actual exports into a plain object — matches the pattern
// used by bibleExtractor.test.js + sceneExtractor.test.js. A Proxy over
// the ESM namespace exotic object that `vi.importActual` returns is
// brittle: it intercepts only `get`, can bypass `[[Module]]` invariants
// Vitest's transform expects, and behaves unpredictably for
// `Symbol.toStringTag` / re-exports.
vi.mock('../lib/fileUtils.js', async () => {
const actual = await vi.importActual('../lib/fileUtils.js');
const redirectedPaths = Object.fromEntries(
Object.keys(actual.PATHS).map((k) => [k, join(tempRoot, k)]),
);
return {
...actual,
PATHS: redirectedPaths,
};
});
// Stub instances.js so non-ephemeral createSeries/createUniverse paths
// don't fan out to real peers via peerSync's autoSubscribeRecordToAllPeers
// (instances.js uses `dataPath` whose closure points at the REAL PATHS,
// bypassing our PATHS mock above). Defense-in-depth: even with explicit
// ephemeral:true on the direct fixtures, downstream production code may
// still create non-ephemeral records.
vi.mock('./instances.js', () => mockNoPeers());
vi.mock('./sharing/peerSync.js', () => mockNoPeerSync());
// Mock runStagedLLM so tests never hit a real provider — every importer
// LLM call resolves to a canned JSON shape we control per-test.
const mockRunStagedLLM = vi.fn();
vi.mock('./stageRunner.js', () => ({
runStagedLLM: (...args) => mockRunStagedLLM(...args),
}));
// Mock `./pipeline/issues.js` so a single test can force `ensureIssueWithId`
// (the importer's create boundary) to throw mid-loop and exercise the
// ERR_PARTIAL_COMMIT_ISSUES rollback path.
// `vi.hoisted` keeps the mock fn ref reachable from both the mock factory
// (hoisted before imports) and the beforeEach reset (runs later). Default
// behavior passes through to the real module so the dozen other tests that
// expect real create behavior keep working unchanged.
// `mockDeleteIssue` follows the same pattern so the replaceMode-abort test
// can force a delete failure mid-wipe.
const { mockEnsureIssue, mockDeleteIssue, realIssuesRef, sessionFaults } = vi.hoisted(() => ({
mockEnsureIssue: vi.fn(),
mockDeleteIssue: vi.fn(),
realIssuesRef: { current: null },
// Status values whose `recordImportProgress` write rejects — lets a test lose
// one specific session write (e.g. the final `committed` receipt, #10762).
sessionFaults: { failStatuses: new Set() },
}));
vi.mock('./pipeline/issues.js', async () => {
const actual = await vi.importActual('./pipeline/issues.js');
realIssuesRef.current = actual;
return {
...actual,
ensureIssueWithId: (...args) => mockEnsureIssue(...args),
deleteIssue: (...args) => mockDeleteIssue(...args),
};
});
vi.mock('./importerSessions.js', async () => {
const actual = await vi.importActual('./importerSessions.js');
return {
...actual,
recordImportProgress: (importId, patch) => (sessionFaults.failStatuses.has(patch?.status)
? Promise.reject(new Error(`simulated ${patch.status} session write failure`))
: actual.recordImportProgress(importId, patch)),
};
});
const importerSvc = await import('./importer.js');
const universeSvc = await import('./universeBuilder.js');
const seriesSvc = await import('./pipeline/series.js');
const issuesSvc = await import('./pipeline/issues.js');
const sessionsSvc = await import('./importerSessions.js');
// Per-test: wipe every file under tempRoot so each test starts with a clean
// data dir. We can't rmSync the dir itself because the universeBuilder
// state path is captured at module init.
function wipeTempRoot() {
for (const entry of readdirSync(tempRoot)) {
const full = join(tempRoot, entry);
const stat = statSync(full);
if (stat.isFile()) unlinkSync(full);
else rmSync(full, { recursive: true, force: true });
}
}
beforeEach(() => {
wipeTempRoot();
mockRunStagedLLM.mockReset();
// Default ensureIssueWithId + deleteIssue to pass-through to the real module —
// only the rollback and replace-abort tests override these to inject
// failures.
mockEnsureIssue.mockReset();
mockEnsureIssue.mockImplementation((...args) => realIssuesRef.current.ensureIssueWithId(...args));
sessionFaults.failStatuses.clear();
mockDeleteIssue.mockReset();
mockDeleteIssue.mockImplementation((...args) => realIssuesRef.current.deleteIssue(...args));
});
afterAll(() => {
if (existsSync(tempRoot)) rmSync(tempRoot, { recursive: true, force: true });
});
// ---------------------------------------------------------------------------
// findOrCreate helpers
// ---------------------------------------------------------------------------
describe('findUniverseByName', () => {
it('returns null when no universe matches', async () => {
expect(await importerSvc.findUniverseByName('Unknown')).toBeNull();
});
it('matches case-insensitively', async () => {
const made = await universeSvc.createUniverse({ name: 'Cyberpunk 2099' });
const found = await importerSvc.findUniverseByName('CYBERPUNK 2099');
expect(found).not.toBeNull();
expect(found.id).toBe(made.id);
});
});
describe('findSeriesByName', () => {
it('scopes the match to a universe', async () => {
const uniA = await universeSvc.createUniverse({ name: 'Universe A' });
const uniB = await universeSvc.createUniverse({ name: 'Universe B' });
await seriesSvc.createSeries({ name: 'Same Title', universeId: uniA.id });
// Match in universe A works.
const foundInA = await importerSvc.findSeriesByName('SAME TITLE', uniA.id);
expect(foundInA).not.toBeNull();
expect(foundInA.universeId).toBe(uniA.id);
// Same name in a different universe is NOT a match.
const foundInB = await importerSvc.findSeriesByName('Same Title', uniB.id);
expect(foundInB).toBeNull();
});
});
// ---------------------------------------------------------------------------
// analyzeImport
// ---------------------------------------------------------------------------
const canonRunResponse = {
characters: [
{ name: 'Aria', role: 'protagonist', physicalDescription: 'tall, freckles' },
],
places: [
{ name: 'The Foundry', slugline: 'INT. FOUNDRY — NIGHT', description: 'molten light' },
],
objects: [
{ name: 'The Locket', description: 'silver, dented', significance: "mother's keepsake" },
],
};
const arcRunResponse = {
logline: 'A blacksmith chases a hidden inheritance.',
summary: 'Aria leaves the foundry to find her mother\'s past.',
protagonistArc: 'Reluctant heir grows into reluctant leader.',
themes: ['legacy', 'craft'],
shape: 'man-in-hole',
seasons: [
{ number: 1, title: 'Foundry', logline: 'Aria leaves home.', synopsis: 'opening', endingHook: '' },
],
};
const issuesRunResponse = {
issues: [
{
title: 'Cold Iron',
arcPosition: 1,
arcRole: 'pilot',
logline: 'The forge dies.',
synopsis: 'Aria finds the letter.',
proseExcerpt: 'The vault loomed in the dark.',
},
],
};
function wireDefaultLLMResponses() {
// Mock per-stage so the call order doesn't matter — important because
// analyze fires canon + arc in parallel.
mockRunStagedLLM.mockImplementation(async (stageName) => {
if (stageName === 'importer-canon-extract') {
return { content: canonRunResponse, model: 'mock', providerId: 'mock', runId: 'run-canon' };
}
if (stageName === 'importer-arc-extract') {
return { content: arcRunResponse, model: 'mock', providerId: 'mock', runId: 'run-arc' };
}
if (stageName === 'importer-issue-proposal') {
return { content: issuesRunResponse, model: 'mock', providerId: 'mock', runId: 'run-issues' };
}
throw new Error(`Unexpected stage: ${stageName}`);
});
}
describe('splitComicScriptIssues (mechanical comic split)', () => {
it('splits on ISSUE headers — one verbatim issue each, sequential positions', () => {
const src = [
'ISSUE #1: THE FOUNDRY',
'PAGE 1',
'Panel 1. Aria forges a blade.',
'ISSUE #2: THE LOCKET',
'PAGE 1',
'Panel 1. The vault loomed.',
].join('\n');
const out = importerSvc.splitComicScriptIssues(src);
expect(out).toHaveLength(2);
expect(out[0].arcPosition).toBe(1);
expect(out[1].arcPosition).toBe(2);
// Title preserved verbatim from the header; prose is verbatim + bounded.
expect(out[0].title).toBe('THE FOUNDRY');
expect(out[0].proseExcerpt).toContain('Aria forges a blade');
expect(out[0].proseExcerpt).toContain('ISSUE #1');
expect(out[0].proseExcerpt).not.toContain('The vault'); // boundary holds
expect(out[1].title).toBe('THE LOCKET');
expect(out[1].proseExcerpt).toContain('The vault loomed');
// No interpretation — mechanical split sets no logline/synopsis.
expect(out[0].logline).toBeUndefined();
expect(out[0].synopsis).toBeUndefined();
});
it('labels sequentially when an ISSUE header carries no title', () => {
const out = importerSvc.splitComicScriptIssues('ISSUE ONE\nstuff\nISSUE TWO\nmore');
expect(out.map((i) => i.title)).toEqual(['Issue 1', 'Issue 2']);
});
it('bundles PAGE markers into ~22-page issues when there are no ISSUE headers', () => {
const lines = [];
for (let p = 1; p <= 25; p++) { lines.push(`PAGE ${p}`); lines.push(`content ${p}`); }
const out = importerSvc.splitComicScriptIssues(lines.join('\n'));
expect(out).toHaveLength(2); // ceil(25 / 22)
expect(out[0].proseExcerpt).toContain('content 1');
expect(out[1].proseExcerpt).toContain('content 25');
// every page lands somewhere (no drops)
const joined = out.map((i) => i.proseExcerpt).join('\n');
for (let p = 1; p <= 25; p++) expect(joined).toContain(`content ${p}`);
});
it('honors an explicit targetIssueCount in the PAGE-bundle path', () => {
const lines = [];
for (let p = 1; p <= 6; p++) { lines.push(`PAGE ${p}`); lines.push(`c${p}`); }
const out = importerSvc.splitComicScriptIssues(lines.join('\n'), { targetIssueCount: 3 });
expect(out).toHaveLength(3);
});
it('returns null for a header-less script so the caller falls back to the LLM', () => {
expect(importerSvc.splitComicScriptIssues('Just prose, no markers anywhere here.')).toBeNull();
});
it('does not mistake a long prose sentence opening with "Page" for a header', () => {
const src = 'Page after page of the manuscript blurred together as she read on into the small hours.';
expect(importerSvc.splitComicScriptIssues(src)).toBeNull();
});
it('does not match a plural-keyword prose line ("ISSUES …") as an ISSUE header', () => {
// Word boundary after the keyword: "ISSUES" must not read as "ISSUE".
expect(importerSvc.splitComicScriptIssues('ISSUES with the forge piled up fast.')).toBeNull();
});
it('does not treat a prose line "Issue <word>" / "Pages <word>" as a header (number-token gate)', () => {
// The header number token is digits or spelled numbers — NOT any word —
// so ordinary prose that opens with the keyword no longer mis-splits.
expect(importerSvc.splitComicScriptIssues('Issue resolved by the council that night.')).toBeNull();
expect(importerSvc.splitComicScriptIssues('Pages turned slowly as the night wore on.')).toBeNull();
// A genuine spelled-number header still splits.
const out = importerSvc.splitComicScriptIssues('ISSUE ONE\nstuff\nISSUE TWO\nmore');
expect(out).toHaveLength(2);
});
it('does not mis-split a content line that starts with "Page N …" / "Issue N …" (standalone-header anchor)', () => {
// The number-token gate alone passed these (they DO contain a number); the
// standalone-header anchor (number then EOL/punct only) rejects the trailing
// prose so the mechanical path falls back to the LLM split.
expect(importerSvc.splitComicScriptIssues('Page 1 of the ancient book lies open and the dust settles.')).toBeNull();
expect(importerSvc.splitComicScriptIssues('Issue 1 of the saga had long been forgotten by the elders.')).toBeNull();
// Real standalone headers (incl. a parenthetical suffix) still split.
expect(importerSvc.splitComicScriptIssues('PAGE 1 (FIVE PANELS)\nart\nPAGE 2\nmore')).toHaveLength(1);
});
});
describe('importer cap invariants', () => {
it('IMPORTER_PROSE_EXCERPT_MAX stays ≤ STAGE_OUTPUT_MAX (no silent truncation on commit)', () => {
// createIssue trims stage output to STAGE_OUTPUT_MAX; if the importer's
// per-issue ceiling were larger, a verbatim excerpt between the two would
// pass analyze then be silently truncated on commit. lib/validation can't
// import the services-side constant, so pin the invariant here.
expect(importerSvc.IMPORTER_PROSE_EXCERPT_MAX).toBeLessThanOrEqual(issuesSvc.STAGE_OUTPUT_MAX);
});
});
describe('analyzeImport', () => {
it('creates universe + series on first run and returns preview shape', async () => {
wireDefaultLLMResponses();
const result = await importerSvc.analyzeImport({
universeName: 'Test Universe',
seriesName: 'Test Series',
contentType: 'short-story',
source: 'The vault loomed in the dark.',
});
expect(result.isExistingUniverse).toBe(false);
expect(result.isExistingSeries).toBe(false);
expect(result.universe.id).toBeDefined();
expect(result.series.id).toMatch(/^ser-/);
expect(result.series.universeId).toBe(result.universe.id);
// New shells are created as import drafts (issue #727): `ephemeral` keeps
// them out of sync, `importDraft` is the marker the orphan-shell GC keys on
// so an abandoned analyze self-cleans (without touching a user's private
// `ephemeral`-only records).
expect(result.universe.ephemeral).toBe(true);
expect(result.series.ephemeral).toBe(true);
expect(result.universe.importDraft).toBe(true);
expect(result.series.importDraft).toBe(true);
expect(result.canonPreview.characters).toHaveLength(1);
expect(result.canonPreview.characters[0].name).toBe('Aria');
expect(result.canonPreview.places).toHaveLength(1);
expect(result.canonPreview.objects).toHaveLength(1);
expect(result.arcPreview.shape).toBe('man-in-hole');
expect(result.seasonsPreview).toHaveLength(1);
expect(result.issueProposals).toHaveLength(1);
expect(result.runIds).toEqual({ canon: 'run-canon', arc: 'run-arc', issues: 'run-issues' });
});
it('reuses existing universe + series on a second analyze with same names', async () => {
wireDefaultLLMResponses();
const first = await importerSvc.analyzeImport({
universeName: 'Test U',
seriesName: 'Test S',
contentType: 'short-story',
source: 'first',
});
const second = await importerSvc.analyzeImport({
universeName: 'TEST U', // case-insensitive
seriesName: 'test s',
contentType: 'short-story',
source: 'second',
});
expect(second.isExistingUniverse).toBe(true);
expect(second.isExistingSeries).toBe(true);
expect(second.universe.id).toBe(first.universe.id);
expect(second.series.id).toBe(first.series.id);
});
it('rejects oversized source with ERR_VALIDATION before calling the LLM', async () => {
wireDefaultLLMResponses();
let caught;
try {
await importerSvc.analyzeImport({
universeName: 'U',
seriesName: 'S',
contentType: 'novel',
source: 'x'.repeat(importerSvc.IMPORTER_SOURCE_CHAR_LIMIT + 1),
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
expect(mockRunStagedLLM).not.toHaveBeenCalled();
});
it('passes returnsJson:true so the stage runner parses the LLM reply', async () => {
// Regression-pin: without `returnsJson: true`, runStagedLLM returns the
// raw text and the orchestrator's `Array.isArray(content?.field)` checks
// all silently fail (preview becomes empty). Lock the opt in by asserting
// every analyze stage call passes it.
wireDefaultLLMResponses();
await importerSvc.analyzeImport({
universeName: 'U', seriesName: 'S', contentType: 'short-story', source: 'x',
});
expect(mockRunStagedLLM).toHaveBeenCalled();
for (const call of mockRunStagedLLM.mock.calls) {
const opts = call[2];
expect(opts).toMatchObject({ returnsJson: true });
}
});
it('forwards providerOverride + modelOverride to every analyze stage call', async () => {
// Regression-pin: the importer UI lets the user pin a specific provider +
// model for extraction (mirrors universe/series). Both must reach every
// staged LLM call (canon, arc, issues) — a one-sided drop would silently
// ignore the user's model choice on one of the three extractions.
wireDefaultLLMResponses();
await importerSvc.analyzeImport({
universeName: 'U', seriesName: 'S', contentType: 'short-story', source: 'x',
providerOverride: 'anthropic', modelOverride: 'claude-opus-4-7',
});
expect(mockRunStagedLLM).toHaveBeenCalled();
for (const call of mockRunStagedLLM.mock.calls) {
expect(call[2]).toMatchObject({ providerOverride: 'anthropic', modelOverride: 'claude-opus-4-7' });
}
});
it('forwards Mustache section-guard flags so per-content-type prompt blocks render', async () => {
// Regression-pin: PortOS's template engine is Mustache-only — the prompts
// use `{{#isShortStory}}…{{/isShortStory}}` blocks, so the orchestrator
// must pass per-type booleans alongside the contentType string.
wireDefaultLLMResponses();
await importerSvc.analyzeImport({
universeName: 'U', seriesName: 'S', contentType: 'novel', source: 'x',
});
const firstVars = mockRunStagedLLM.mock.calls[0][1];
expect(firstVars).toMatchObject({
isNovel: true,
isShortStory: false,
isScreenplay: false,
isComicScript: false,
});
});
it('wires existingCanonBlock into the canon-extract prompt for dedup on a second-pass import', async () => {
// Regression-pin: a refactor that drops the `existingCanonBlock` arg
// (or wires it to `null` / `''`) leaves the canon-extract LLM blind to
// already-seeded canon and silently re-extracts duplicates on every
// subsequent import.
const uni = await universeSvc.createUniverse({ name: 'Seeded U' });
await universeSvc.updateUniverse(uni.id, {
characters: [{ name: 'Aria Existing' }],
});
wireDefaultLLMResponses();
await importerSvc.analyzeImport({
universeName: 'Seeded U',
seriesName: 'New Series',
contentType: 'short-story',
source: 'A new story arrives.',
});
// Lookup by stage name rather than calls[0] — analyzeImport fires
// canon + arc via Promise.all and any future scheduling change could
// swap the order without breaking the contract.
const canonCall = mockRunStagedLLM.mock.calls.find((c) => c[0] === 'importer-canon-extract');
expect(canonCall).toBeDefined();
expect(canonCall[1].existingCanonBlock).toContain('Aria Existing');
});
it('emits ordered stage-progress frames with a stable runId', async () => {
// Regression-pin: the Importer page renders a live checklist from these
// `progress` frames. A `start` opens the run (carrying the stage list);
// each pass then flips `running`→`done`, and every frame shares one runId
// so the client can ignore stragglers from a prior run.
wireDefaultLLMResponses();
const frames = [];
const onProgress = (f) => frames.push(f);
importerSvc.importerEvents.on('progress', onProgress);
try {
await importerSvc.analyzeImport({
universeName: 'Progress U', seriesName: 'Progress S', contentType: 'short-story', source: 'x',
});
} finally {
importerSvc.importerEvents.off('progress', onProgress);
}
const start = frames.find((f) => f.type === 'start');
expect(start).toBeDefined();
expect(start.stages.map((s) => s.id)).toEqual(['canon', 'arc', 'issues']);
// Every frame shares the start frame's runId.
const runId = start.runId;
expect(runId).toBeTruthy();
expect(frames.every((f) => f.runId === runId)).toBe(true);
// Each stage reaches both running and done.
for (const id of ['canon', 'arc', 'issues']) {
const statuses = frames.filter((f) => f.type === 'stage' && f.id === id).map((f) => f.status);
expect(statuses).toContain('running');
expect(statuses).toContain('done');
}
// issues can't start until arc resolves — its `running` follows arc `done`.
const arcDoneIdx = frames.findIndex((f) => f.type === 'stage' && f.id === 'arc' && f.status === 'done');
const issuesRunningIdx = frames.findIndex((f) => f.type === 'stage' && f.id === 'issues' && f.status === 'running');
expect(issuesRunningIdx).toBeGreaterThan(arcDoneIdx);
});
it('passes the extended analyze timeout to every staged LLM call', async () => {
// Regression-pin: each analyze pass feeds the whole corpus to a heavy
// model, so the importer overrides the toolkit's 5-min default. A dropped
// override would reintroduce false timeouts + expensive fallback re-runs.
wireDefaultLLMResponses();
await importerSvc.analyzeImport({
universeName: 'Timeout U', seriesName: 'Timeout S', contentType: 'short-story', source: 'x',
});
expect(mockRunStagedLLM).toHaveBeenCalled();
for (const call of mockRunStagedLLM.mock.calls) {
expect(call[2]).toMatchObject({ timeoutOverride: importerSvc.ANALYZE_STAGE_TIMEOUT_MS });
}
});
it('mechanically splits a comic script and skips the LLM issue-proposal call', async () => {
wireDefaultLLMResponses();
const src = 'ISSUE #1: ONE\nPage stuff here.\nISSUE #2: TWO\nMore page stuff.';
const result = await importerSvc.analyzeImport({
universeName: 'Comic U', seriesName: 'Comic S', contentType: 'comic-script', source: src,
});
expect(result.issueSplitFailed).toBe(false);
expect(result.issueProposals).toHaveLength(2);
expect(result.issueProposals[0].proseExcerpt).toContain('Page stuff here');
// The LLM split was NOT invoked — canon + arc still were.
const issueCall = mockRunStagedLLM.mock.calls.find((c) => c[0] === 'importer-issue-proposal');
expect(issueCall).toBeUndefined();
expect(mockRunStagedLLM.mock.calls.some((c) => c[0] === 'importer-canon-extract')).toBe(true);
// Mechanical path carries no run id.
expect(result.runIds.issues).toBeNull();
});
it('preserves canon+arc and flags issueSplitFailed when the issue split throws', async () => {
// canon + arc succeed; the issue-proposal pass throws (e.g. a timeout).
// The expensive passes must NOT be discarded — analyze returns the
// preview with issueSplitFailed=true and persisted universe/series shells.
mockRunStagedLLM.mockImplementation(async (stageName) => {
if (stageName === 'importer-canon-extract') return { content: canonRunResponse, model: 'mock', providerId: 'mock', runId: 'run-canon' };
if (stageName === 'importer-arc-extract') return { content: arcRunResponse, model: 'mock', providerId: 'mock', runId: 'run-arc' };
if (stageName === 'importer-issue-proposal') throw new Error('codex timed out after 1200000ms');
throw new Error(`Unexpected stage: ${stageName}`);
});
// Capture progress frames to assert the issues stage reaches 'error'.
const frames = [];
const onProgress = (f) => frames.push(f);
importerSvc.importerEvents.on('progress', onProgress);
let result;
try {
result = await importerSvc.analyzeImport({
universeName: 'Resilient U', seriesName: 'Resilient S', contentType: 'novel', source: 'x',
});
} finally {
importerSvc.importerEvents.off('progress', onProgress);
}
expect(result.issueSplitFailed).toBe(true);
expect(result.issueSplitError).toContain('codex timed out');
expect(result.issueProposals).toEqual([]);
// The checklist's issues stage must reach a terminal 'error' frame (drives
// the client's error icon + retry banner).
const issuesStatuses = frames.filter((f) => f.type === 'stage' && f.id === 'issues').map((f) => f.status);
expect(issuesStatuses).toContain('running');
expect(issuesStatuses).toContain('error');
// Canon + arc preserved.
expect(result.canonPreview.characters).toHaveLength(1);
expect(result.arcPreview.shape).toBe('man-in-hole');
// Universe + series are actually PERSISTED (not just in-memory shells) so
// the client has stable ids to retry/commit against — re-read from disk.
expect(result.universe.id).toBeDefined();
expect(result.series.id).toMatch(/^ser-/);
expect(await universeSvc.getUniverse(result.universe.id)).toBeTruthy();
expect(await seriesSvc.getSeries(result.series.id)).toBeTruthy();
expect(result.runIds.issues).toBeNull();
});
it('fails analyze with ERR_VALIDATION when a comic split would exceed the per-issue prose cap', async () => {
// One ISSUE header with a body over IMPORTER_PROSE_EXCERPT_MAX → the
// verbatim excerpt would be rejected at commit; surface it at analyze
// instead of letting it dead-end on a commit-time 400. The failure rides
// the non-fatal issue-split path, so canon+arc are still preserved.
mockRunStagedLLM.mockImplementation(async (stageName) => {
if (stageName === 'importer-canon-extract') return { content: canonRunResponse, model: 'mock', providerId: 'mock', runId: 'run-canon' };
if (stageName === 'importer-arc-extract') return { content: arcRunResponse, model: 'mock', providerId: 'mock', runId: 'run-arc' };
throw new Error(`Unexpected stage: ${stageName}`);
});
const huge = `ISSUE 1\n${'x'.repeat(importerSvc.IMPORTER_PROSE_EXCERPT_MAX + 10)}`;
const result = await importerSvc.analyzeImport({
universeName: 'Big Comic U', seriesName: 'Big Comic S', contentType: 'comic-script', source: huge,
});
expect(result.issueSplitFailed).toBe(true);
expect(result.issueSplitError).toMatch(/per-issue limit/);
// No LLM issue-proposal call happened (the cap check fired on the mechanical path).
expect(mockRunStagedLLM.mock.calls.some((c) => c[0] === 'importer-issue-proposal')).toBe(false);
});
it('rejects a locked-arc series with ERR_LOCKED before calling the LLM', async () => {
// Pre-seed a series with locked.arc, then re-analyze with its name.
const uni = await universeSvc.createUniverse({ name: 'Locked U' });
const seeded = await seriesSvc.createSeries({ name: 'Locked S', universeId: uni.id });
await seriesSvc.updateSeries(seeded.id, { locked: { arc: true } });
wireDefaultLLMResponses();
let caught;
try {
await importerSvc.analyzeImport({
universeName: 'Locked U',
seriesName: 'Locked S',
contentType: 'short-story',
source: 'anything',
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_LOCKED);
expect(mockRunStagedLLM).not.toHaveBeenCalled();
});
});
// ---------------------------------------------------------------------------
// classifyImportContent — hallucination-guard coverage
//
// Copilot review: route tests mock classifyImportContent entirely, so the
// service-level sanitization logic (dropping out-of-enum contentType /
// confidence, truncating reasoning, handling non-object run.content) had
// no test coverage. A regression that accidentally accepted `raw.contentType`
// without enum-membership would not have been caught. These tests pin every
// guard branch directly against the service.
// ---------------------------------------------------------------------------
describe('retryIssueSplit', () => {
it('mechanically splits a comic script with no LLM call', async () => {
wireDefaultLLMResponses();
const out = await importerSvc.retryIssueSplit({
contentType: 'comic-script',
source: 'ISSUE #1: A\nstuff\nISSUE #2: B\nmore',
});
expect(out.method).toBe('mechanical');
expect(out.issueProposals).toHaveLength(2);
expect(out.runId).toBeNull();
expect(mockRunStagedLLM).not.toHaveBeenCalled();
});
it('falls through to the LLM split for prose content types, with the extended timeout', async () => {
wireDefaultLLMResponses();
const out = await importerSvc.retryIssueSplit({
contentType: 'novel', source: 'a novel body', arcSummary: 'the arc summary',
});
expect(out.method).toBe('llm');
expect(out.issueProposals).toHaveLength(1);
const call = mockRunStagedLLM.mock.calls.find((c) => c[0] === 'importer-issue-proposal');
expect(call).toBeDefined();
expect(call[2]).toMatchObject({ timeoutOverride: importerSvc.ANALYZE_STAGE_TIMEOUT_MS });
});
it('rejects an oversized source before calling the LLM', async () => {
wireDefaultLLMResponses();
await expect(importerSvc.retryIssueSplit({
contentType: 'novel',
source: 'x'.repeat(importerSvc.IMPORTER_SOURCE_CHAR_LIMIT + 1),
})).rejects.toMatchObject({ code: importerSvc.ERR_VALIDATION });
expect(mockRunStagedLLM).not.toHaveBeenCalled();
});
});
describe('classifyImportContent', () => {
it('passes valid contentType + confidence + reasoning through verbatim', async () => {
mockRunStagedLLM.mockResolvedValueOnce({
content: { contentType: 'screenplay', confidence: 'high', reasoning: 'has FADE IN markers' },
model: 'mock',
providerId: 'mock',
runId: 'run-classify-1',
});
const result = await importerSvc.classifyImportContent({ source: 'INT. ROOM - DAY' });
expect(result.contentType).toBe('screenplay');
expect(result.confidence).toBe('high');
expect(result.reasoning).toBe('has FADE IN markers');
expect(result.runId).toBe('run-classify-1');
});
it('forwards providerOverride + modelOverride to the classify stage call', async () => {
mockRunStagedLLM.mockResolvedValueOnce({
content: { contentType: 'novel', confidence: 'high', reasoning: 'chapters' },
model: 'mock',
providerId: 'mock',
runId: 'run-classify-override',
});
await importerSvc.classifyImportContent({
source: 'some prose', providerOverride: 'anthropic', modelOverride: 'claude-opus-4-7',
});
expect(mockRunStagedLLM).toHaveBeenCalledWith(
'importer-classify',
expect.any(Object),
expect.objectContaining({ providerOverride: 'anthropic', modelOverride: 'claude-opus-4-7' }),
);
});
it('drops a hallucinated contentType not in IMPORTER_CONTENT_TYPES to null', async () => {
mockRunStagedLLM.mockResolvedValueOnce({
content: { contentType: 'manga', confidence: 'high', reasoning: 'panels' },
model: 'mock',
providerId: 'mock',
runId: 'run-x',
});
const result = await importerSvc.classifyImportContent({ source: 'some prose' });
expect(result.contentType).toBeNull();
// Confidence + reasoning are independent guards — they stay valid.
expect(result.confidence).toBe('high');
expect(result.reasoning).toBe('panels');
});
it('drops a hallucinated confidence not in {high|medium|low} to null', async () => {
mockRunStagedLLM.mockResolvedValueOnce({
content: { contentType: 'novel', confidence: 'extremely-high', reasoning: 'chapters' },
model: 'mock',
providerId: 'mock',
runId: 'run-x',
});
const result = await importerSvc.classifyImportContent({ source: 'some prose' });
expect(result.contentType).toBe('novel');
expect(result.confidence).toBeNull();
expect(result.reasoning).toBe('chapters');
});
it('truncates reasoning to 500 chars', async () => {
const longReasoning = 'a'.repeat(2_000);
mockRunStagedLLM.mockResolvedValueOnce({
content: { contentType: 'short-story', confidence: 'medium', reasoning: longReasoning },
model: 'mock',
providerId: 'mock',
runId: 'run-x',
});
const result = await importerSvc.classifyImportContent({ source: 'some prose' });
expect(result.reasoning).toHaveLength(500);
expect(result.reasoning).toBe('a'.repeat(500));
});
it('coerces non-string reasoning to null', async () => {
mockRunStagedLLM.mockResolvedValueOnce({
content: { contentType: 'comic-script', confidence: 'low', reasoning: 42 },
model: 'mock',
providerId: 'mock',
runId: 'run-x',
});
const result = await importerSvc.classifyImportContent({ source: 'some prose' });
expect(result.reasoning).toBeNull();
expect(result.contentType).toBe('comic-script');
expect(result.confidence).toBe('low');
});
it('treats a non-object run.content as empty — all fields land at null', async () => {
mockRunStagedLLM.mockResolvedValueOnce({
content: 'I am a plain string, not JSON',
model: 'mock',
providerId: 'mock',
runId: 'run-x',
});
const result = await importerSvc.classifyImportContent({ source: 'some prose' });
expect(result.contentType).toBeNull();
expect(result.confidence).toBeNull();
expect(result.reasoning).toBeNull();
expect(result.runId).toBe('run-x');
});
it('treats a null run.content as empty', async () => {
mockRunStagedLLM.mockResolvedValueOnce({
content: null,
model: 'mock',
providerId: 'mock',
runId: 'run-x',
});
const result = await importerSvc.classifyImportContent({ source: 'some prose' });
expect(result.contentType).toBeNull();
expect(result.confidence).toBeNull();
expect(result.reasoning).toBeNull();
});
it('rejects missing source with ERR_VALIDATION before calling the LLM', async () => {
let caught;
try {
await importerSvc.classifyImportContent({ source: '' });
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
expect(mockRunStagedLLM).not.toHaveBeenCalled();
});
it('rejects oversized source with ERR_VALIDATION before calling the LLM', async () => {
const oversized = 'x'.repeat(importerSvc.IMPORTER_SOURCE_CHAR_LIMIT + 1);
let caught;
try {
await importerSvc.classifyImportContent({ source: oversized });
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
expect(mockRunStagedLLM).not.toHaveBeenCalled();
});
it('only passes the first CLASSIFY_SOURCE_HEAD_CHARS to the LLM', async () => {
mockRunStagedLLM.mockResolvedValueOnce({
content: { contentType: 'novel', confidence: 'low', reasoning: 'r' },
model: 'mock',
providerId: 'mock',
runId: 'run-x',
});
const big = 'a'.repeat(importerSvc.CLASSIFY_SOURCE_HEAD_CHARS + 5_000);
await importerSvc.classifyImportContent({ source: big });
expect(mockRunStagedLLM).toHaveBeenCalled();
const vars = mockRunStagedLLM.mock.calls[0][1];
expect(vars.sourceHead).toHaveLength(importerSvc.CLASSIFY_SOURCE_HEAD_CHARS);
});
});
// ---------------------------------------------------------------------------
// reformatSeededExcerpts (importer AI cleanup — issue #1335)
// ---------------------------------------------------------------------------
describe('reformatSeededExcerpts', () => {
// Collect importer progress frames the helper emits so we can assert the
// per-issue checklist is broadcast.
function captureFrames() {
const frames = [];
const onFrame = (f) => frames.push(f);
importerSvc.importerEvents.on('progress', onFrame);
return { frames, stop: () => importerSvc.importerEvents.off('progress', onFrame) };
}
it('returns the input unchanged (no LLM call) when no issue has a proseExcerpt', async () => {
const issues = [{ title: 'A', arcPosition: 1 }, { title: 'B', arcPosition: 2 }];
const out = await importerSvc.reformatSeededExcerpts(issues, { contentType: 'short-story' });
expect(out).toBe(issues); // same reference — nothing to do
expect(mockRunStagedLLM).not.toHaveBeenCalled();
});
it('replaces each excerpt with the cleaned text and emits per-issue progress frames', async () => {
// Cleaned output must preserve the word skeleton or the integrity guard
// rejects it — collapse the doubled space, nothing else.
mockRunStagedLLM.mockResolvedValue({ content: 'The vault loomed in the dark.', runId: 'r1' });
const { frames, stop } = captureFrames();
const issues = [{ title: 'Cold Iron', arcPosition: 1, proseExcerpt: 'The vault loomed in the\ndark.' }];
const out = await importerSvc.reformatSeededExcerpts(issues, { contentType: 'short-story' });
stop();
expect(out[0].proseExcerpt).toBe('The vault loomed in the dark.');
expect(out).not.toBe(issues); // fresh array, input untouched
expect(issues[0].proseExcerpt).toBe('The vault loomed in the\ndark.');
// start + (running, done) + done
expect(frames.find((f) => f.type === 'start')?.stages).toHaveLength(1);
expect(frames.some((f) => f.type === 'stage' && f.status === 'running')).toBe(true);
expect(frames.some((f) => f.type === 'stage' && f.status === 'done')).toBe(true);
expect(frames.some((f) => f.type === 'done')).toBe(true);
});
it('routes a comic-script import through the comicScript reformat format', async () => {
mockRunStagedLLM.mockResolvedValue({ content: 'PAGE 1 PANEL 1 Giant descends.', runId: 'r1' });
await importerSvc.reformatSeededExcerpts(
[{ title: 'P', arcPosition: 1, proseExcerpt: 'PAGE 1\nPANEL 1\nGiant descends.' }],
{ contentType: 'comic-script' },
);
const call = mockRunStagedLLM.mock.calls.find((c) => c[0] === 'manuscript-reformat');
expect(call).toBeDefined();
expect(call[1].format).toBe('Comic script');
});
it('falls back to the verbatim excerpt when the reformat fails (best-effort, never throws)', async () => {
// Default reset mock resolves undefined → reformatManuscriptText throws
// "model returned no text" → helper swallows and keeps the original.
const { frames, stop } = captureFrames();
const issues = [{ title: 'Cold Iron', arcPosition: 1, proseExcerpt: 'The vault loomed.' }];
const out = await importerSvc.reformatSeededExcerpts(issues, { contentType: 'short-story' });
stop();
expect(out[0].proseExcerpt).toBe('The vault loomed.');
// A failed pass surfaces as 'error' in the checklist (warning icon).
expect(frames.some((f) => f.type === 'stage' && f.status === 'error')).toBe(true);
});
it('falls back when the integrity guard rejects a word-altering reformat', async () => {
mockRunStagedLLM.mockResolvedValue({ content: 'The castle loomed.', runId: 'r1' });
const out = await importerSvc.reformatSeededExcerpts(
[{ title: 'Cold Iron', arcPosition: 1, proseExcerpt: 'The vault loomed.' }],
{ contentType: 'short-story' },
);
expect(out[0].proseExcerpt).toBe('The vault loomed.'); // guard tripped → verbatim kept
});
});
// commitImport
// ---------------------------------------------------------------------------
async function setupForCommit() {
// Create the universe + series the analyze phase would have created, then
// exercise commitImport directly with a hand-shaped payload.
//
// ephemeral:true keeps the fixtures out of peer-sync. Without it, the
// create*-time `autoSubscribeRecordToAllPeers` reads the LIVE peer
// registry (instances.json is NOT mocked by PATHS — only fileUtils.js
// PATHS is, and instances.js resolves its own file paths) and fans the
// fixture out to every actual peer, leaving "Commit U" / "Commit S"
// records on the user's null sync machine after every test run.
//
// importDraft:true models what analyzeImport stamps on a brand-new shell, so
// commitImport's promotion (which gates strictly on importDraft) clears both
// flags — matching the real analyze→commit lifecycle.
const uni = await universeSvc.createUniverse({ name: 'Commit U', ephemeral: true, importDraft: true });
const ser = await seriesSvc.createSeries({ name: 'Commit S', universeId: uni.id, ephemeral: true, importDraft: true });
return { uni, ser };
}
describe('commitImport', () => {
it('happy path: merges canon, writes arc + seasons, creates issues with prose seeded', async () => {
const { uni, ser } = await setupForCommit();
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: {
characters: [{ name: 'Aria', role: 'protagonist', physicalDescription: 'tall' }],
places: [{ name: 'The Foundry', slugline: 'INT. FOUNDRY — NIGHT', description: 'molten' }],
objects: [{ name: 'The Locket', significance: 'heirloom' }],
},
arc: {
logline: 'A reluctant heir.',
summary: 'Big story.',
protagonistArc: 'Growth.',
themes: ['legacy'],
shape: 'man-in-hole',
},
seasons: [
{ number: 1, title: 'Foundry', logline: 'Open', synopsis: 'a', endingHook: '' },
],
issues: [
{
title: 'Cold Iron',
arcPosition: 1,
arcRole: 'pilot',
logline: 'Forge dies.',
synopsis: 'Aria finds the letter.',
proseExcerpt: 'The vault loomed in the dark.',
},
],
});
// Universe canon was merged.
expect(result.universe.characters.find((c) => c.name === 'Aria')).toBeDefined();
expect(result.universe.places.find((s) => s.name === 'The Foundry')).toBeDefined();
expect(result.universe.objects.find((o) => o.name === 'The Locket')).toBeDefined();
// Series got arc + seasons.
expect(result.series.arc.shape).toBe('man-in-hole');
expect(result.series.seasons).toHaveLength(1);
expect(result.series.seasons[0].title).toBe('Foundry');
// Bible top-level fields populated from the extracted arc + issue count
// (the sidebar used to stay blank after import).
expect(result.series.logline).toBe('A reluctant heir.');
expect(result.series.premise).toBe('Big story.');
expect(result.series.issueCountTarget).toBe(1);
// A successful commit promotes both shells out of draft state (issue #727):
// ephemeral cleared so they sync to peers, importDraft cleared so the
// orphan-shell GC never touches them.
expect(result.universe.ephemeral).not.toBe(true);
expect(result.series.ephemeral).not.toBe(true);
expect(result.universe.importDraft).not.toBe(true);
expect(result.series.importDraft).not.toBe(true);
// One issue created with prose + idea seeded.
expect(result.createdIssueIds).toHaveLength(1);
const issue = await issuesSvc.getIssue(result.createdIssueIds[0]);
expect(issue.title).toBe('Cold Iron');
expect(issue.seriesId).toBe(ser.id);
expect(issue.stages.prose.output).toBe('The vault loomed in the dark.');
expect(issue.stages.prose.status).toBe('ready');
expect(issue.stages.idea.input).toContain('Logline: Forge dies.');
expect(issue.stages.idea.input).toContain('Synopsis: Aria finds the letter.');
// Issue was wired to the first season.
expect(issue.seasonId).toBe(result.series.seasons[0].id);
});
it('cleanupFormatting:true seeds the AI-reformatted excerpt (issue #1335)', async () => {
mockRunStagedLLM.mockResolvedValue({ content: 'The vault loomed in the dark.', runId: 'r1' });
const { uni, ser } = await setupForCommit();
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
contentType: 'short-story',
cleanupFormatting: true,
issues: [{ title: 'Cold Iron', arcPosition: 1, proseExcerpt: 'The vault loomed in the\ndark.' }],
});
const issue = await issuesSvc.getIssue(result.createdIssueIds[0]);
expect(issue.stages.prose.output).toBe('The vault loomed in the dark.');
expect(issue.stages.prose.status).toBe('ready');
expect(mockRunStagedLLM.mock.calls.some((c) => c[0] === 'manuscript-reformat')).toBe(true);
});
it('cleanupFormatting:true is best-effort — a failed reformat seeds the verbatim excerpt', async () => {
// Reset mock resolves undefined → reformat throws → fall back to verbatim;
// the commit still succeeds and creates the issue.
const { uni, ser } = await setupForCommit();
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
contentType: 'short-story',
cleanupFormatting: true,
issues: [{ title: 'Cold Iron', arcPosition: 1, proseExcerpt: 'The vault loomed in the dark.' }],
});
expect(result.createdIssueIds).toHaveLength(1);
const issue = await issuesSvc.getIssue(result.createdIssueIds[0]);
expect(issue.stages.prose.output).toBe('The vault loomed in the dark.');
});
// Race-safety regression coverage for issue #8453: commitImport reads the
// universe/series once, then (with cleanupFormatting on) can spend minutes
// in per-issue LLM calls before writing the merged canon/seasons. These
// tests simulate a concurrent edit landing DURING that window via the mock
// `runStagedLLM` — the one async gap the real reformat pass creates — and
// assert the concurrent edit survives the eventual merge instead of being
// silently overwritten by a merge against the stale up-front snapshot.
it('a universe canon edit made during cleanupFormatting survives the import merge (issue #8453)', async () => {
const { uni, ser } = await setupForCommit();
mockRunStagedLLM.mockImplementation(async () => {
// Simulates a user adding a character in another tab (or an Autopilot/
// Series job editing canon) while the AI cleanup pass is in flight.
await universeSvc.updateUniverse(uni.id, {
characters: [{ name: 'Concurrent Editor', role: 'supporting' }],
});
return { content: 'The vault loomed in the dark.', runId: 'r1' };
});
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
contentType: 'short-story',
cleanupFormatting: true,
canonSelections: { characters: [{ name: 'Aria', role: 'protagonist' }] },
issues: [{ title: 'Cold Iron', arcPosition: 1, proseExcerpt: 'The vault loomed in the\ndark.' }],
});
const names = result.universe.characters.map((c) => c.name);
expect(names).toContain('Aria');
expect(names).toContain('Concurrent Editor');
});
it('a season edit made during cleanupFormatting survives the import merge (issue #8453)', async () => {
const { uni, ser } = await setupForCommit();
mockRunStagedLLM.mockImplementation(async () => {
// Simulates a season edited on the series in another tab while the AI
// cleanup pass is in flight.
await seriesSvc.updateSeries(ser.id, {
seasons: [{ number: 5, title: 'Concurrent Season' }],
});
return { content: 'The vault loomed in the dark.', runId: 'r1' };
});
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
contentType: 'short-story',
cleanupFormatting: true,
seasons: [{ number: 1, title: 'Foundry' }],
issues: [{ title: 'Cold Iron', arcPosition: 1, proseExcerpt: 'The vault loomed in the\ndark.' }],
});
const numbers = result.series.seasons.map((s) => s.number);
expect(numbers).toContain(1);
expect(numbers).toContain(5);
});
it('an arc-only import (no canon selections) makes no universe write', async () => {
// importDraft:false so commitImport's own post-commit promotion (gated
// strictly on importDraft === true) doesn't also call updateUniverse —
// isolating the assertion to the canon-merge write this test targets.
const uni = await universeSvc.createUniverse({ name: 'Commit U', ephemeral: true, importDraft: false });
const ser = await seriesSvc.createSeries({
name: 'Commit S', universeId: uni.id, ephemeral: true, importDraft: false,
});
const updateUniverseSpy = vi.spyOn(universeSvc, 'updateUniverse');
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
arc: { logline: 'A reluctant heir.', summary: 'Big story.' },
issues: [{ title: 'Cold Iron', arcPosition: 1, proseExcerpt: 'The vault loomed in the dark.' }],
});
expect(updateUniverseSpy).not.toHaveBeenCalled();
expect(result.universe.characters ?? []).toHaveLength(0);
updateUniverseSpy.mockRestore();
});
it('seeds stages.comicScript (not prose) for a comic-script import', async () => {
// A comic-script source is already script-form, so its verbatim excerpt
// must land in comicScript (ready) — seeding prose would make the
// pipeline regenerate (re-interpret) the script.
const { uni, ser } = await setupForCommit();
const script = 'PAGE 1\nPANEL 1\nGiant descends.\nCAPTION\nNot real.';
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
contentType: 'comic-script',
canonSelections: { characters: [], places: [], objects: [] },
issues: [{ title: 'Issue 1', arcPosition: 1, proseExcerpt: script }],
});
const issue = await issuesSvc.getIssue(result.createdIssueIds[0]);
expect(issue.stages.comicScript.output).toBe(script);
expect(issue.stages.comicScript.status).toBe('ready');
// prose is NOT seeded — the script never round-trips through it.
expect(issue.stages.prose?.output).toBeFalsy();
});
it('seeds stages.teleplay (not prose) for a screenplay import', async () => {
// A screenplay source is already script-form, so its verbatim excerpt
// must land in teleplay (ready) — seeding prose would make the pipeline
// regenerate it. Downstream scene extraction already consumes teleplay.
const { uni, ser } = await setupForCommit();
const script = 'INT. VAULT - NIGHT\n\nARIA\nWho left this here?\n\nFADE OUT.';
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
contentType: 'screenplay',
canonSelections: { characters: [], places: [], objects: [] },
issues: [{ title: 'Issue 1', arcPosition: 1, proseExcerpt: script }],
});
const issue = await issuesSvc.getIssue(result.createdIssueIds[0]);
expect(issue.stages.teleplay.output).toBe(script);
expect(issue.stages.teleplay.status).toBe('ready');
// prose is NOT seeded — the script never round-trips through it.
expect(issue.stages.prose?.output).toBeFalsy();
});
it('still seeds stages.prose when contentType is absent (older clients)', async () => {
const { uni, ser } = await setupForCommit();
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
issues: [{ title: 'Issue 1', arcPosition: 1, proseExcerpt: 'Plain prose.' }],
});
const issue = await issuesSvc.getIssue(result.createdIssueIds[0]);
expect(issue.stages.prose.output).toBe('Plain prose.');
expect(issue.stages.comicScript?.output).toBeFalsy();
expect(issue.stages.teleplay?.output).toBeFalsy();
});
it('replace mode overwrites the bible, clearing stale fields when the new arc lacks them', async () => {
const { uni, ser } = await setupForCommit();
// First (additive) import seeds a bible logline + premise.
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: { logline: 'Old logline', summary: 'Old premise' },
seasons: [],
issues: [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' }],
});
expect((await seriesSvc.getSeries(ser.id)).logline).toBe('Old logline');
// Replace with an arc that has NO logline/summary — the bible must be
// cleared, not left showing the prior work's text beside a replaced arc.
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
replaceMode: true,
canonSelections: { characters: [], places: [], objects: [] },
arc: { logline: '', summary: '', protagonistArc: '' },
seasons: [],
issues: [{ title: 'I2', arcPosition: 1, proseExcerpt: 'p2' }],
});
expect(result.series.logline).toBe('');
expect(result.series.premise).toBe('');
expect(result.series.issueCountTarget).toBe(1);
});
it('refuses to commit when the series arc is locked', async () => {
const { uni, ser } = await setupForCommit();
await seriesSvc.updateSeries(ser.id, { locked: { arc: true } });
let caught;
try {
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: { logline: 'x', summary: 'y' },
seasons: [],
issues: [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p' }],
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_LOCKED);
// No issues were created.
const issuesAfter = await issuesSvc.listIssues({ seriesId: ser.id });
expect(issuesAfter).toHaveLength(0);
});
it('LWW-merges canon by name — second commit does not duplicate a known character', async () => {
const { uni, ser } = await setupForCommit();
// Seed Aria once.
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: {
characters: [{ name: 'Aria', role: 'protagonist', physicalDescription: 'tall' }],
places: [],
objects: [],
},
arc: null,
seasons: [],
issues: [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' }],
});
// Commit a second pass with Aria again (different case + no description
// to exercise the userEditable-blank rule).
const second = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: {
characters: [{ name: 'ARIA', role: 'protagonist' }],
places: [],
objects: [],
},
arc: null,
seasons: [],
issues: [{ title: 'I2', arcPosition: 2, proseExcerpt: 'p2' }],
});
const ariaEntries = second.universe.characters.filter((c) => c.name.toLowerCase() === 'aria');
expect(ariaEntries).toHaveLength(1);
// Original physicalDescription preserved (mergeExtractedBible doesn't
// overwrite non-blank userEditable fields).
expect(ariaEntries[0].physicalDescription).toBe('tall');
});
it('refuses commit when the issues array is empty', async () => {
const { uni, ser } = await setupForCommit();
let caught;
try {
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [],
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
});
it('refuses commit when at least one issue in the array is missing a title', async () => {
// Exercises the per-entry title validation loop (importer.js lines 315-323).
// A non-empty issues array where one entry has no title must be rejected
// fail-fast, before any state is written to disk.
const { uni, ser } = await setupForCommit();
let caught;
try {
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [
{ title: 'Valid Issue', arcPosition: 1, proseExcerpt: 'p1' },
{ title: '', arcPosition: 2, proseExcerpt: 'p2' },
],
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
expect(caught.message).toMatch(/position 2/i);
// Confirm no issues were created — the fail-fast guard prevented any write.
const issuesAfter = await issuesSvc.listIssues({ seriesId: ser.id });
expect(issuesAfter).toHaveLength(0);
});
it('second-pass seasons are MERGED into existing seasons, not replaced', async () => {
// Regression guard for importer.js:360 destructive-replace behavior.
// Both passes supply non-empty seasons arrays; after the second commit the
// series must contain seasons from BOTH calls (merge), not just the second.
//
// NOTE: this test asserts the intended post-fix MERGE behavior. If the
// parallel agent's merge fix in importer.js has not landed yet, this test
// will fail loudly — that is the correct signal.
const { uni, ser } = await setupForCommit();
// First pass: season 1.
const first = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [{ number: 1, title: 'Season One', logline: 'Beginning', synopsis: 'a', endingHook: '' }],
issues: [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' }],
});
expect(first.series.seasons).toHaveLength(1);
expect(first.series.seasons[0].title).toBe('Season One');
// Second pass: season 2 — the importer must MERGE this with season 1.
const second = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [{ number: 2, title: 'Season Two', logline: 'Escalation', synopsis: 'b', endingHook: '' }],
issues: [{ title: 'I2', arcPosition: 2, proseExcerpt: 'p2' }],
});
// After merge: series must contain both seasons.
expect(second.series.seasons).toHaveLength(2);
const titles = second.series.seasons.map((s) => s.title);
expect(titles).toContain('Season One');
expect(titles).toContain('Season Two');
// Season numbers must also be preserved correctly.
const s1 = second.series.seasons.find((s) => s.number === 1);
const s2 = second.series.seasons.find((s) => s.number === 2);
expect(s1).toBeDefined();
expect(s2).toBeDefined();
});
// Round-12 review: cross-universe guard must refuse commit when the
// series has NO universeId (legacy / hand-edited data), not just when
// it differs. Previously a falsy universeId silently bypassed the
// guard and let the importer re-home the series.
it('refuses commit when the series has no universeId', async () => {
const uni = await universeSvc.createUniverse({ name: 'Linkless U' });
const ser = await seriesSvc.createSeries({ name: 'Linkless S' });
// sanitizeSeries normalizes a missing universeId to null. Confirm
// the precondition before exercising the guard.
expect(ser.universeId).toBeFalsy();
let caught;
try {
await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p' }],
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
expect(caught.message).toMatch(/no universeId/i);
});
// Round-10 review: round-9's auto-assign fix only covered the omitted
// case. An incoming issue that EXPLICITLY sets `arcPosition: 1` while
// the series already holds an issue at position 1 must be rejected
// fail-fast, not silently land a duplicate.
it('refuses commit when an explicit arcPosition collides with an existing issue', async () => {
const { uni, ser } = await setupForCommit();
await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' }],
});
let caught;
try {
await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
// Explicit arcPosition 1 — already used by I1 above.
issues: [{ title: 'Collision', arcPosition: 1, proseExcerpt: 'p2' }],
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
expect(caught.message).toMatch(/collides with an existing issue/i);
// No issue created — the gate fires before createIssue.
const all = await issuesSvc.listIssues({ seriesId: ser.id });
expect(all).toHaveLength(1);
});
// Round-9 review: arcPosition auto-assign must seed `nextFreeArcPos`
// from the union of explicit incoming positions AND pre-existing
// series.issues[].arcPosition — re-import on a series that already
// has issues at [1..3] would otherwise auto-assign starting at 1 again
// and create duplicate positions silently.
it('arcPosition auto-assign on re-import skips arcPositions already used by existing issues', async () => {
const { uni, ser } = await setupForCommit();
// First pass: seed three issues at arcPositions 1, 2, 3.
await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [
{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' },
{ title: 'I2', arcPosition: 2, proseExcerpt: 'p2' },
{ title: 'I3', arcPosition: 3, proseExcerpt: 'p3' },
],
});
// Second pass: two new issues with NO arcPosition. Must auto-assign
// to 4 and 5, not collide with 1 and 2.
const second = await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [
{ title: 'I4 — auto', proseExcerpt: 'p4' },
{ title: 'I5 — auto', proseExcerpt: 'p5' },
],
});
expect(second.createdIssueIds).toHaveLength(2);
const i4 = await issuesSvc.getIssue(second.createdIssueIds[0]);
const i5 = await issuesSvc.getIssue(second.createdIssueIds[1]);
expect(i4.arcPosition).toBe(4);
expect(i5.arcPosition).toBe(5);
// And the full series now has 5 issues, no collisions on arcPosition.
const allIssues = await issuesSvc.listIssues({ seriesId: ser.id });
const positions = allIssues.map((i) => i.arcPosition).sort((a, b) => a - b);
expect(positions).toEqual([1, 2, 3, 4, 5]);
});
// Round-8 review: fallbackSeasonId must pick the LOWEST-NUMBERED season,
// not array-position [0]. After mergeSeasons the array order is
// `[...retained, ...incomingBuilt]` — retained existing seasons come
// first regardless of number, so a series with [season 2, season 3] that
// receives a new season 1 would otherwise pick season 2 as "fallback".
it('fallbackSeasonId picks the lowest-numbered season, not array[0]', async () => {
const { uni, ser } = await setupForCommit();
// First pass: seed seasons 2 and 3 (skip 1).
await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [
{ number: 2, title: 'Two', logline: 'a', synopsis: '', endingHook: '' },
{ number: 3, title: 'Three', logline: 'b', synopsis: '', endingHook: '' },
],
issues: [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' }],
});
// Second pass: add season 1 + an issue with no seasonNumber. The
// fallback must land it in season 1 (the new lowest), even though
// mergeSeasons returns [retained_2, retained_3, new_1] in that order.
const second = await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [{ number: 1, title: 'One', logline: 'c', synopsis: '', endingHook: '' }],
issues: [{ title: 'I-no-season', arcPosition: 4, proseExcerpt: 'p4' }],
});
const created = await issuesSvc.getIssue(second.createdIssueIds[0]);
const seasonOne = second.series.seasons.find((s) => s.number === 1);
expect(seasonOne).toBeDefined();
expect(created.seasonId).toBe(seasonOne.id);
});
// Round-8 review: remappedIssues entries now carry actualSeasonNumber
// and actualSeasonTitle so the client toast can name the season
// precisely instead of saying a generic "first season".
it('remappedIssues entries carry actualSeasonNumber + actualSeasonTitle', async () => {
const { uni, ser } = await setupForCommit();
// Seed season 1 only; the next commit references a non-existent season 99
// — the issue must land in season 1 and the remap entry must surface it.
const result = await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [{ number: 1, title: 'Foundry', logline: 'open', synopsis: '', endingHook: '' }],
issues: [
{ title: 'A', arcPosition: 1, seasonNumber: 99, proseExcerpt: 'pa' },
],
});
expect(result.remappedIssues).toHaveLength(1);
const remap = result.remappedIssues[0];
expect(remap.requestedSeasonNumber).toBe(99);
expect(remap.actualSeasonNumber).toBe(1);
expect(remap.actualSeasonTitle).toBe('Foundry');
expect(remap.actualSeasonId).toBeDefined();
});
// Round-8 review: missing test for the ERR_PARTIAL_COMMIT_ISSUES rollback
// path. Inject a createIssue failure on the 2nd of 3 issues; assert that
// the rollback deletes the 1st (already created), surfaces the partial
// code, and leaves the universe + series writes intact (those are
// idempotent + user-confirmed, so we don't roll them back).
it('rolls back created issues + throws ERR_PARTIAL_COMMIT_ISSUES when createIssue fails mid-loop', async () => {
const { uni, ser } = await setupForCommit();
let call = 0;
mockEnsureIssue.mockImplementation(async (...args) => {
call++;
if (call === 2) throw new Error('simulated mid-loop FS error');
return realIssuesRef.current.ensureIssueWithId(...args);
});
let caught;
try {
await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id,
canonSelections: { characters: [{ name: 'Aria' }], places: [], objects: [] },
arc: { logline: 'A', summary: 'S', shape: 'man-in-hole' },
seasons: [{ number: 1, title: 'S1', logline: '', synopsis: '', endingHook: '' }],
issues: [
{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' },
{ title: 'I2', arcPosition: 2, proseExcerpt: 'p2' },
{ title: 'I3', arcPosition: 3, proseExcerpt: 'p3' },
],
});
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe('IMPORTER_PARTIAL_COMMIT_ISSUES');
expect(caught.message).toMatch(/universe and series were updated/i);
expect(caught.message).toMatch(/simulated mid-loop FS error/);
// The error carries the structured context the client needs to shape
// its retry — universe + series ids (so a re-fetch isn't required) and
// `arcAlreadyPersisted` (so the retry drops arc + seasons + canon from
// the payload and lets the server-side state stand).
expect(caught.context).toBeDefined();
expect(caught.context.universeId).toBe(uni.id);
expect(caught.context.seriesId).toBe(ser.id);
expect(caught.context.arcAlreadyPersisted).toBe(true);
expect(caught.context.skipArcOnRetry).toBe(true);
// Universe + series writes survive (user-confirmed, idempotent).
const universeAfter = await universeSvc.getUniverse(uni.id);
expect(universeAfter.characters.some((c) => c.name === 'Aria')).toBe(true);
const seriesAfter = await seriesSvc.getSeries(ser.id);
expect(seriesAfter.arc?.shape).toBe('man-in-hole');
expect(seriesAfter.seasons).toHaveLength(1);
// No leftover issues from the partial loop.
const issuesAfter = await issuesSvc.listIssues({ seriesId: ser.id });
expect(issuesAfter).toHaveLength(0);
});
// Round-N: replaceMode behavior. Seed a series with one issue + one arc
// shape; re-commit with replaceMode=true and assert the existing issue
// is wiped, the new issue is created, and the arc was overwritten.
it('replaceMode=true wipes existing issues + overwrites arc + seasons', async () => {
const { uni, ser } = await setupForCommit();
// Seed pass — one issue, one season, "rags-to-riches" arc.
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: { logline: 'Old', summary: 'Old', shape: 'rags-to-riches' },
seasons: [{ number: 1, title: 'Old S1', logline: '', synopsis: '', endingHook: '' }],
issues: [{ title: 'Old Issue', arcPosition: 1, proseExcerpt: 'old prose' }],
});
const beforeIssues = await issuesSvc.listIssues({ seriesId: ser.id });
expect(beforeIssues).toHaveLength(1);
// Replace pass — different arc shape, different issue.
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: { logline: 'New', summary: 'New', shape: 'tragedy' },
seasons: [{ number: 1, title: 'New S1', logline: '', synopsis: '', endingHook: '' }],
issues: [{ title: 'New Issue', arcPosition: 1, proseExcerpt: 'new prose' }],
replaceMode: true,
});
// Old issue gone, only new issue remains.
const afterIssues = await issuesSvc.listIssues({ seriesId: ser.id });
expect(afterIssues).toHaveLength(1);
expect(afterIssues[0].title).toBe('New Issue');
expect(result.createdIssueIds).toEqual([afterIssues[0].id]);
// Arc was overwritten — shape is now `tragedy`.
expect(result.series.arc.shape).toBe('tragedy');
expect(result.series.arc.logline).toBe('New');
// Season title was overwritten.
expect(result.series.seasons[0].title).toBe('New S1');
});
// Copilot review: in replaceMode, a swallowed per-issue delete failure
// would leave the old issue on disk AND create a new one with a reused
// arcPosition (additive-mode's collision check is skipped in replace),
// producing duplicates the additive path explicitly rejects. The fix is
// to abort the commit before any new state is written if any delete
// fails. This test pins that contract — single-issue case: nothing got
// deleted before the failure, so the abort is fully transactional.
it('replaceMode=true aborts the commit when a delete fails — no new issues, arc unchanged', async () => {
const { uni, ser } = await setupForCommit();
// Seed pass — one issue, arc shape `rags-to-riches`.
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: { logline: 'Old', summary: 'Old', shape: 'rags-to-riches' },
seasons: [],
issues: [{ title: 'Old Issue', arcPosition: 1, proseExcerpt: 'old prose' }],
});
const beforeIssues = await issuesSvc.listIssues({ seriesId: ser.id });
expect(beforeIssues).toHaveLength(1);
const seededIssueId = beforeIssues[0].id;
// Inject a delete failure for the seeded issue id.
mockDeleteIssue.mockImplementationOnce(async () => {
throw new Error('disk full');
});
// Replace pass — should abort before universe/series/issue writes.
await expect(importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: { logline: 'New', summary: 'New', shape: 'tragedy' },
seasons: [],
issues: [{ title: 'New Issue', arcPosition: 1, proseExcerpt: 'new prose' }],
replaceMode: true,
})).rejects.toThrowError(/Replace mode aborted on first delete failure/);
// Old issue still on disk, no new issue created.
const afterIssues = await issuesSvc.listIssues({ seriesId: ser.id });
expect(afterIssues).toHaveLength(1);
expect(afterIssues[0].id).toBe(seededIssueId);
expect(afterIssues[0].title).toBe('Old Issue');
// Arc shape was NOT overwritten — series write never happened.
const seriesAfter = await seriesSvc.getSeries(ser.id);
expect(seriesAfter.arc.shape).toBe('rags-to-riches');
expect(seriesAfter.arc.logline).toBe('Old');
});
// Second Copilot review iteration: aborting on the FIRST delete failure
// (not after looping through all of them) minimizes the destructive
// surface. With 3 seeded issues + a failure injected on the 2nd call,
// only 1 should be deleted before the abort fires — the 3rd issue's
// delete must NEVER be attempted.
it('replaceMode=true aborts on the FIRST delete failure, leaving subsequent issues untouched', async () => {
const { uni, ser } = await setupForCommit();
// Seed pass — three issues at arcPositions 1, 2, 3.
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [
{ title: 'Old A', arcPosition: 1, proseExcerpt: 'a' },
{ title: 'Old B', arcPosition: 2, proseExcerpt: 'b' },
{ title: 'Old C', arcPosition: 3, proseExcerpt: 'c' },
],
});
const seeded = await issuesSvc.listIssues({ seriesId: ser.id });
expect(seeded).toHaveLength(3);
// First call succeeds (real passthrough); second call throws; we must
// never reach a third call. Track call count + which id failed.
let deleteCallCount = 0;
let failedId = null;
mockDeleteIssue.mockImplementation(async (id) => {
deleteCallCount += 1;
if (deleteCallCount === 2) {
failedId = id;
throw new Error('disk full');
}
return realIssuesRef.current.deleteIssue(id);
});
await expect(importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [{ title: 'New', arcPosition: 1, proseExcerpt: 'new' }],
replaceMode: true,
})).rejects.toThrowError(/Replace mode aborted on first delete failure/);
// Exactly two delete calls happened (one success + one failure);
// the third issue was NEVER touched.
expect(deleteCallCount).toBe(2);
// Two issues remain on disk: the one that failed to delete, and the
// one that was never attempted. Exactly one issue was actually
// deleted before the abort.
const remaining = await issuesSvc.listIssues({ seriesId: ser.id });
expect(remaining).toHaveLength(2);
expect(remaining.map((i) => i.id)).toContain(failedId);
// No new issue was created — replace aborted before issue-loop.
expect(remaining.map((i) => i.title)).not.toContain('New');
});
// Same arcPosition between old + new issues — additive mode would reject
// with "explicit arcPosition collides", but replaceMode wipes the old
// first so the collision is gone by the time we write the new set.
it('replaceMode=true tolerates arcPosition reuse from the wiped set', async () => {
const { uni, ser } = await setupForCommit();
await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [{ title: 'Old', arcPosition: 1, proseExcerpt: 'old' }],
});
// Same arcPosition=1 — additive would throw, replace accepts.
const result = await importerSvc.commitImport({
universeId: uni.id,
seriesId: ser.id,
canonSelections: { characters: [], places: [], objects: [] },
arc: null,
seasons: [],
issues: [{ title: 'New', arcPosition: 1, proseExcerpt: 'new' }],
replaceMode: true,
});
expect(result.createdIssueIds).toHaveLength(1);
const after = await issuesSvc.listIssues({ seriesId: ser.id });
expect(after).toHaveLength(1);
expect(after[0].title).toBe('New');
expect(after[0].arcPosition).toBe(1);
});
});
// Import sessions (#9943): the server, not the client's React state, remembers
// how far an import got, so a repeat commit cannot duplicate the issue set.
describe('commitImport import sessions (#9943)', () => {
const analyze = (source = 'The vault loomed in the dark.') => importerSvc.analyzeImport({
universeName: 'Session U', seriesName: 'Session S', contentType: 'short-story', source,
});
const payloadFor = (preview, extra = {}) => ({
universeId: preview.universe.id,
seriesId: preview.series.id,
importId: preview.importId,
arc: { logline: 'Original logline', summary: 'Original summary', shape: 'man-in-hole' },
seasons: [{ number: 1, title: 'S1', logline: '', synopsis: '', endingHook: '' }],
issues: [
{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' },
{ title: 'I2', arcPosition: 2, proseExcerpt: 'p2' },
],
...extra,
});
const issueCount = async (preview) => (await issuesSvc.listIssues({ seriesId: preview.series.id })).length;
it('replays a repeated commit: nothing new is created and the recorded ids come back', async () => {
wireDefaultLLMResponses();
const preview = await analyze();
const first = await importerSvc.commitImport(payloadFor(preview));
expect(first.createdIssueIds).toHaveLength(2);
expect(first.replayed).toBeUndefined();
// An edit made after the commit must survive a repeat: the replay writes nothing.
await seriesSvc.updateSeries(preview.series.id, { logline: 'Edited since' });
const again = await importerSvc.commitImport(payloadFor(preview));
expect(again.replayed).toBe(true);
expect(again.createdIssueIds).toEqual(first.createdIssueIds);
expect(await issueCount(preview)).toBe(2);
expect((await seriesSvc.getSeries(preview.series.id)).logline).toBe('Edited since');
});
it('survives a reload: re-analyzing the same text reads the committed session back', async () => {
wireDefaultLLMResponses();
const preview = await analyze();
expect(preview.importSession).toBeNull();
const first = await importerSvc.commitImport(payloadFor(preview));
// The reload dropped every client marker; analyze is all the client has.
const reanalyzed = await analyze(' The vault loomed in the dark.\r\n');
expect(reanalyzed.isExistingSeries).toBe(true);
expect(reanalyzed.importId).toBe(preview.importId);
expect(reanalyzed.importSession).toEqual({ status: 'committed', createdIssueIds: first.createdIssueIds });
const resumed = await importerSvc.commitImport(payloadFor(reanalyzed));
expect(resumed.replayed).toBe(true);
expect(await issueCount(preview)).toBe(2);
});
it('resumes after a rolled-back issue loop without resending canon or the arc', async () => {
wireDefaultLLMResponses();
const preview = await analyze();
let call = 0;
mockEnsureIssue.mockImplementation(async (...args) => {
call++;
if (call === 2) throw new Error('simulated mid-loop FS error');
return realIssuesRef.current.ensureIssueWithId(...args);
});
await expect(importerSvc.commitImport(payloadFor(preview))).rejects.toMatchObject({
code: importerSvc.ERR_PARTIAL_COMMIT_ISSUES,
});
expect(await issueCount(preview)).toBe(0);
const reanalyzed = await analyze();
expect(reanalyzed.importSession).toMatchObject({ status: 'arc-persisted' });
await seriesSvc.updateSeries(preview.series.id, { arc: { logline: 'Edited arc', summary: 'Edited', shape: 'rags-to-riches' } });
// A client with no memory of the failure resends the full payload, arc included.
const retried = await importerSvc.commitImport(payloadFor(reanalyzed));
expect(retried.createdIssueIds).toHaveLength(2);
expect((await seriesSvc.getSeries(preview.series.id)).arc.shape).toBe('rags-to-riches');
expect((await analyze()).importSession.status).toBe('committed');
});
it('does not block a different manuscript imported into the same series', async () => {
wireDefaultLLMResponses();
const first = await analyze('Chapter one text.');
await importerSvc.commitImport(payloadFor(first, { issues: [{ title: 'A', arcPosition: 1, proseExcerpt: 'a' }] }));
const second = await analyze('A different manuscript entirely.');
expect(second.importId).not.toBe(first.importId);
expect(second.importSession).toBeNull();
const result = await importerSvc.commitImport(payloadFor(second, { issues: [{ title: 'B', proseExcerpt: 'b' }] }));
expect(result.replayed).toBeUndefined();
expect(await issueCount(first)).toBe(2);
});
it('treats a committed session whose issues were all deleted as a fresh start', async () => {
wireDefaultLLMResponses();
const preview = await analyze();
const first = await importerSvc.commitImport(payloadFor(preview));
for (const id of first.createdIssueIds) await issuesSvc.deleteIssue(id);
const reanalyzed = await analyze();
expect(reanalyzed.importSession).toBeNull();
const again = await importerSvc.commitImport(payloadFor(reanalyzed));
expect(again.replayed).toBeUndefined();
expect(again.createdIssueIds).toHaveLength(2);
});
it('serializes concurrent commits of one import into a single issue set', async () => {
wireDefaultLLMResponses();
const preview = await analyze();
const [a, b] = await Promise.all([
importerSvc.commitImport(payloadFor(preview)),
importerSvc.commitImport(payloadFor(preview)),
]);
expect([a.replayed, b.replayed].filter(Boolean)).toHaveLength(1);
expect(a.createdIssueIds).toEqual(b.createdIssueIds);
expect(await issueCount(preview)).toBe(2);
});
it('keeps replace mode independent of the session — it rewrites rather than replays', async () => {
wireDefaultLLMResponses();
const preview = await analyze();
await importerSvc.commitImport(payloadFor(preview));
const replaced = await importerSvc.commitImport(payloadFor(preview, {
replaceMode: true,
issues: [{ title: 'Replacement', arcPosition: 1, proseExcerpt: 'r' }],
}));
expect(replaced.replayed).toBeUndefined();
const after = await issuesSvc.listIssues({ seriesId: preview.series.id });
expect(after.map((i) => i.title)).toEqual(['Replacement']);
});
// #10762: issue identities are planned durably before the first create, so a
// lost receipt or an interrupted loop resumes instead of minting a second batch.
it('finishes a commit whose final receipt was lost without creating a second copy', async () => {
wireDefaultLLMResponses();
const preview = await analyze();
// No arcPosition — a retry used to auto-assign the next free slot and land
// a duplicate at position 2.
const issues = [{ title: 'Example Chapter', proseExcerpt: 'p1' }];
sessionFaults.failStatuses.add('committed');
const first = await importerSvc.commitImport(payloadFor(preview, { issues }));
sessionFaults.failStatuses.clear();
expect(first.createdIssueIds).toHaveLength(1);
const reanalyzed = await analyze();
expect(reanalyzed.importSession).toEqual({ status: 'committed', createdIssueIds: first.createdIssueIds });
const retried = await importerSvc.commitImport(payloadFor(reanalyzed, { issues }));
expect(retried.replayed).toBe(true);
expect(retried.createdIssueIds).toEqual(first.createdIssueIds);
const after = await issuesSvc.listIssues({ seriesId: preview.series.id });
expect(after.map((i) => [i.id, i.arcPosition])).toEqual([[first.createdIssueIds[0], 1]]);
// The replay wrote the receipt the first attempt lost.
expect(await sessionsSvc.getImportSession(preview.importId)).toMatchObject({
status: 'committed', createdIssueIds: first.createdIssueIds, plan: null,
});
});
it('keeps a finished import resumable until its draft shells are promoted', async () => {
wireDefaultLLMResponses();
const preview = await analyze();
const issues = [{ title: 'I1', proseExcerpt: 'p1' }];
// The last issue lands, then the process dies before promotion and receipt.
mockEnsureIssue.mockImplementation(async (...args) => {
await realIssuesRef.current.ensureIssueWithId(...args);
throw new Error('simulated crash after the write');
});
mockDeleteIssue.mockRejectedValue(new Error('simulated delete failure'));
await expect(importerSvc.commitImport(payloadFor(preview, { issues }))).rejects.toThrow();
mockEnsureIssue.mockImplementation((...args) => realIssuesRef.current.ensureIssueWithId(...args));
mockDeleteIssue.mockImplementation((...args) => realIssuesRef.current.deleteIssue(...args));
expect((await seriesSvc.getSeries(preview.series.id)).importDraft).toBe(true);
// Not `committed` yet: a client that believed it would never send the
// commit that promotes the drafts.
const reanalyzed = await analyze();
expect(reanalyzed.importSession.status).toBe('arc-persisted');
const retried = await importerSvc.commitImport(payloadFor(reanalyzed, { issues }));
expect(retried.replayed).toBe(true);
expect((await seriesSvc.getSeries(preview.series.id)).importDraft).not.toBe(true);
expect(await issueCount(preview)).toBe(1);
expect((await analyze()).importSession).toEqual({ status: 'committed', createdIssueIds: retried.createdIssueIds });
});
// The disk state a crash after the first issue leaves: the plan is recorded,
// one issue exists, and nothing rolled it back.
const interruptAfterFirstIssue = async (preview, issues) => {
let call = 0;
mockEnsureIssue.mockImplementation(async (...args) => {
call++;
if (call === 2) throw new Error('simulated crash');
return realIssuesRef.current.ensureIssueWithId(...args);
});
mockDeleteIssue.mockRejectedValue(new Error('simulated delete failure'));
const err = await importerSvc.commitImport(payloadFor(preview, { issues })).catch((e) => e);
mockEnsureIssue.mockImplementation((...args) => realIssuesRef.current.ensureIssueWithId(...args));
mockDeleteIssue.mockImplementation((...args) => realIssuesRef.current.deleteIssue(...args));
return err;
};
it.each([
['explicit', [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' }, { title: 'I2', arcPosition: 2, proseExcerpt: 'p2' }]],
['omitted', [{ title: 'I1', proseExcerpt: 'p1' }, { title: 'I2', proseExcerpt: 'p2' }]],
])('resumes an interrupted issue set with %s positions, keeping the survivor and its edits', async (_label, issues) => {
wireDefaultLLMResponses();
const preview = await analyze();
const err = await interruptAfterFirstIssue(preview, issues);
// The rollback could not remove the survivor, and says so rather than
// reporting every created issue as rolled back.
expect(err.code).toBe(importerSvc.ERR_PARTIAL_COMMIT_ISSUES);
expect(err.context.survivingIssueIds).toHaveLength(1);
expect(err.message).toMatch(/0 issues created by this attempt were rolled back/);
expect(err.message).toMatch(/1 issue could not be removed .* remains part of this import/);
const [survivorId] = err.context.survivingIssueIds;
await issuesSvc.updateIssue(survivorId, { title: 'I1 (edited)' });
const reanalyzed = await analyze();
expect(reanalyzed.importSession.status).toBe('arc-persisted');
const retried = await importerSvc.commitImport(payloadFor(reanalyzed, { issues }));
expect(retried.createdIssueIds[0]).toBe(survivorId);
const after = await issuesSvc.listIssues({ seriesId: preview.series.id });
expect(after.map((i) => [i.id, i.title, i.arcPosition])).toEqual([
[survivorId, 'I1 (edited)', 1],
[retried.createdIssueIds[1], 'I2', 2],
]);
expect((await analyze()).importSession).toEqual({ status: 'committed', createdIssueIds: retried.createdIssueIds });
});
it.each([
['a new issue', (preview) => issuesSvc.createIssue({ seriesId: preview.series.id, title: 'Added since', arcPosition: 2 })],
['the moved survivor', (_preview, survivorId) => issuesSvc.updateIssue(survivorId, { arcPosition: 2 })],
])('refuses to resume onto a planned position %s took since', async (_label, takeSlot) => {
wireDefaultLLMResponses();
const preview = await analyze();
const issues = [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' }, { title: 'I2', arcPosition: 2, proseExcerpt: 'p2' }];
const { context: { survivingIssueIds } } = await interruptAfterFirstIssue(preview, issues);
await takeSlot(preview, survivingIssueIds[0]);
const before = await issueCount(preview);
await expect(importerSvc.commitImport(payloadFor(preview, { issues })))
.rejects.toMatchObject({ code: importerSvc.ERR_VALIDATION });
expect(await issueCount(preview)).toBe(before);
});
it("refuses a changed issue list while an earlier attempt's issues still exist", async () => {
wireDefaultLLMResponses();
const preview = await analyze();
const issues = [{ title: 'I1', arcPosition: 1, proseExcerpt: 'p1' }, { title: 'I2', arcPosition: 2, proseExcerpt: 'p2' }];
const { context: { survivingIssueIds } } = await interruptAfterFirstIssue(preview, issues);
await expect(importerSvc.commitImport(payloadFor(preview, {
issues: [{ title: 'A different split', proseExcerpt: 'x' }],
}))).rejects.toMatchObject({ code: importerSvc.ERR_IMPORT_IN_PROGRESS });
expect((await issuesSvc.listIssues({ seriesId: preview.series.id })).map((i) => i.id)).toEqual(survivingIssueIds);
// Deleting the survivor releases the plan: the new list then imports normally.
await issuesSvc.deleteIssue(survivingIssueIds[0]);
const fresh = await importerSvc.commitImport(payloadFor(preview, {
issues: [{ title: 'A different split', proseExcerpt: 'x' }],
}));
expect(fresh.createdIssueIds).toHaveLength(1);
});
it('commits without an importId exactly as before (older clients)', async () => {
const { uni, ser } = await setupForCommit();
const body = { universeId: uni.id, seriesId: ser.id, issues: [{ title: 'Solo', proseExcerpt: 'p' }] };
await importerSvc.commitImport(body);
await importerSvc.commitImport(body);
expect(await issuesSvc.listIssues({ seriesId: ser.id })).toHaveLength(2);
});
});
// #10763: commits into one series are admitted one at a time, whatever their
// importId, and the issue publication rechecks positions against fresh state.
// Each interleaving test holds the FIRST commit's first issue write at a
// barrier — the point where the issue's reproduction found both commits had
// already passed the collision check — and lets the second commit run into it.
describe('commitImport series admission (#10763)', () => {
function holdFirstPublication() {
let reached;
let release;
const reachedP = new Promise((resolve) => { reached = resolve; });
const releaseP = new Promise((resolve) => { release = resolve; });
mockEnsureIssue.mockImplementationOnce(async (...args) => {
reached();
await releaseP;
return realIssuesRef.current.ensureIssueWithId(...args);
});
return { reached: reachedP, release };
}
const importIdFor = (ser, source) => sessionsSvc.deriveImportId({ seriesId: ser.id, source });
const livePositions = async (ser) => (await issuesSvc.listIssues({ seriesId: ser.id }))
.map((i) => i.arcPosition).sort((a, b) => a - b);
it('two manuscripts claiming one explicit position: one commits, the other is refused before any write', async () => {
const { uni, ser } = await setupForCommit();
const held = holdFirstPublication();
const first = importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, importId: importIdFor(ser, 'manuscript A'),
canonSelections: { characters: [{ name: 'Aria' }] },
issues: [{ title: 'A1', arcPosition: 1, proseExcerpt: 'a' }],
});
await held.reached;
const second = importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, importId: importIdFor(ser, 'manuscript B'),
canonSelections: { characters: [{ name: 'Intruder' }] },
arc: { logline: 'B logline', summary: 'B summary', shape: 'rags-to-riches' },
issues: [{ title: 'B1', arcPosition: 1, proseExcerpt: 'b' }],
});
const secondOutcome = second.then(() => null, (err) => err);
held.release();
await expect(first).resolves.toMatchObject({ createdIssueIds: [expect.any(String)] });
const err = await secondOutcome;
expect(err?.code).toBe(importerSvc.ERR_VALIDATION);
expect(err.message).toMatch(/collides with an existing issue/);
expect((await issuesSvc.listIssues({ seriesId: ser.id })).map((i) => i.title)).toEqual(['A1']);
// The refused batch wrote nothing: no canon, no arc.
const universeAfter = await universeSvc.getUniverse(uni.id);
expect(universeAfter.characters.map((c) => c.name)).toEqual(['Aria']);
expect((await seriesSvc.getSeries(ser.id)).arc?.shape).not.toBe('rags-to-riches');
});
it('concurrent manuscripts with omitted positions get distinct sequential positions', async () => {
const { uni, ser } = await setupForCommit();
const held = holdFirstPublication();
const first = importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, importId: importIdFor(ser, 'manuscript A'),
issues: [{ title: 'A1', proseExcerpt: 'a' }, { title: 'A2', proseExcerpt: 'a2' }],
});
await held.reached;
const second = importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, importId: importIdFor(ser, 'manuscript B'),
issues: [{ title: 'B1', proseExcerpt: 'b' }],
});
held.release();
await Promise.all([first, second]);
expect(await livePositions(ser)).toEqual([1, 2, 3]);
});
it('applies the same admission to legacy commits with no importId', async () => {
const { uni, ser } = await setupForCommit();
const held = holdFirstPublication();
const body = (title) => ({ universeId: uni.id, seriesId: ser.id, issues: [{ title, arcPosition: 1, proseExcerpt: 'p' }] });
const first = importerSvc.commitImport(body('Legacy A'));
await held.reached;
const second = importerSvc.commitImport(body('Legacy B')).then(() => null, (err) => err);
held.release();
await first;
expect((await second)?.code).toBe(importerSvc.ERR_VALIDATION);
expect(await livePositions(ser)).toEqual([1]);
});
it('lets a commit into an unrelated series proceed while one series is held', async () => {
const { uni, ser } = await setupForCommit();
const other = await seriesSvc.createSeries({ name: 'Other S', universeId: uni.id, ephemeral: true });
const held = holdFirstPublication();
const first = importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, issues: [{ title: 'Held', arcPosition: 1, proseExcerpt: 'h' }],
});
await held.reached;
// Resolves while the first series is still held — no shared admission.
const result = await importerSvc.commitImport({
universeId: uni.id, seriesId: other.id, issues: [{ title: 'Free', arcPosition: 1, proseExcerpt: 'f' }],
});
expect(result.createdIssueIds).toHaveLength(1);
held.release();
await first;
expect(await livePositions(ser)).toEqual([1]);
});
it.each([
['explicit', { arcPosition: 1 }],
['omitted', {}],
])('a plain issue create racing the import cannot silently duplicate an %s position', async (_label, position) => {
const { uni, ser } = await setupForCommit();
// An ordinary create lands on the series after admission planned the
// position, before the import publishes it.
mockEnsureIssue.mockImplementationOnce(async (...args) => {
await realIssuesRef.current.createIssue({ seriesId: ser.id, title: 'Manual', arcPosition: 1 });
return realIssuesRef.current.ensureIssueWithId(...args);
});
await expect(importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, issues: [{ title: 'Imported', ...position, proseExcerpt: 'i' }],
})).rejects.toMatchObject({
code: importerSvc.ERR_PARTIAL_COMMIT_ISSUES,
message: expect.stringMatching(/already held by another issue/),
});
expect((await issuesSvc.listIssues({ seriesId: ser.id })).map((i) => i.title)).toEqual(['Manual']);
});
it('releases admission after a failed commit so the next one into the series proceeds', async () => {
const { uni, ser } = await setupForCommit();
mockEnsureIssue.mockRejectedValueOnce(new Error('simulated write failure'));
await expect(importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, issues: [{ title: 'Fails', arcPosition: 1, proseExcerpt: 'f' }],
})).rejects.toMatchObject({ code: importerSvc.ERR_PARTIAL_COMMIT_ISSUES });
const result = await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, issues: [{ title: 'Works', arcPosition: 1, proseExcerpt: 'w' }],
});
expect(result.createdIssueIds).toHaveLength(1);
});
it('runs cleanupFormatting outside the admission: another commit lands while the reformat is in flight', async () => {
const { uni, ser } = await setupForCommit();
let releaseReformat;
const reformatGate = new Promise((resolve) => { releaseReformat = resolve; });
let reformatStarted;
const started = new Promise((resolve) => { reformatStarted = resolve; });
mockRunStagedLLM.mockImplementation(async () => {
reformatStarted();
await reformatGate;
return { content: 'The vault loomed in the dark.', runId: 'r1' };
});
const slow = importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, contentType: 'short-story', cleanupFormatting: true,
issues: [{ title: 'Slow', proseExcerpt: 'The vault loomed in the\ndark.' }],
});
await started;
// Completes while the slow commit's LLM pass is still pending.
await importerSvc.commitImport({
universeId: uni.id, seriesId: ser.id, issues: [{ title: 'Fast', proseExcerpt: 'f' }],
});
releaseReformat();
await slow;
// The slow commit allocated from the state it found AFTER formatting, and
// seeded the cleaned excerpt.
const after = await issuesSvc.listIssues({ seriesId: ser.id });
expect(Object.fromEntries(after.map((i) => [i.title, i.arcPosition]))).toEqual({ Fast: 1, Slow: 2 });
expect(after.find((i) => i.title === 'Slow').stages.prose.output).toBe('The vault loomed in the dark.');
});
});
describe('mergeSeasons (pure helper)', () => {
const stubBuildSeason = (input) => ({
id: `built-${input.number}`,
number: input.number,
title: input.title,
logline: input.logline,
synopsis: input.synopsis,
endingHook: input.endingHook,
episodeCountTarget: input.episodeCountTarget,
status: input.status,
createdAt: '2025-01-01T00:00:00.000Z',
updatedAt: '2025-01-01T00:00:00.000Z',
});
it('auto-assigns sequential numbers when incoming seasons omit number', () => {
const incoming = [
{ title: 'A' },
{ title: 'B' },
{ title: 'C' },
];
const result = importerSvc.mergeSeasons([], incoming, stubBuildSeason);
const numbers = result.map((s) => s.number).sort((a, b) => a - b);
expect(numbers).toEqual([1, 2, 3]);
});
it('preserves existing ids when incoming season number matches', () => {
const existing = [
{ id: 'existing-1', number: 1, title: 'Old', logline: '', synopsis: '', updatedAt: '2020-01-01T00:00:00.000Z' },
];
const incoming = [{ number: 1, title: 'Old', logline: '', synopsis: '' }];
const result = importerSvc.mergeSeasons(existing, incoming, stubBuildSeason);
expect(result).toHaveLength(1);
expect(result[0].id).toBe('existing-1');
});
it('bumps updatedAt only when an importable field changes', () => {
const existing = [
{ id: 'e1', number: 1, title: 'Original', logline: 'L1', synopsis: 'S1', updatedAt: '2020-01-01T00:00:00.000Z' },
];
// No change → updatedAt preserved
const noChange = importerSvc.mergeSeasons(existing, [{ number: 1, title: 'Original' }], stubBuildSeason);
expect(noChange[0].updatedAt).toBe('2020-01-01T00:00:00.000Z');
// Title change → updatedAt bumped (to a value newer than the original)
const titleChange = importerSvc.mergeSeasons(existing, [{ number: 1, title: 'New title' }], stubBuildSeason);
expect(titleChange[0].updatedAt > '2020-01-01T00:00:00.000Z').toBe(true);
});
it('retains existing seasons that the incoming list does not touch', () => {
const existing = [
{ id: 'e1', number: 1, title: 'One', logline: '', synopsis: '' },
{ id: 'e2', number: 2, title: 'Two', logline: '', synopsis: '' },
];
const incoming = [{ number: 1, title: 'One updated' }];
const result = importerSvc.mergeSeasons(existing, incoming, stubBuildSeason);
expect(result).toHaveLength(2);
expect(result.find((s) => s.number === 2)?.id).toBe('e2');
});
it('skips over existing numbers when auto-assigning', () => {
const existing = [
{ id: 'e1', number: 1, title: 'One', logline: '', synopsis: '' },
{ id: 'e2', number: 3, title: 'Three', logline: '', synopsis: '' },
];
const incoming = [{ title: 'New A' }, { title: 'New B' }];
const result = importerSvc.mergeSeasons(existing, incoming, stubBuildSeason);
const newNumbers = result.filter((s) => s.id.startsWith('built-')).map((s) => s.number).sort((a, b) => a - b);
// nextFree = max(1,3) + 1 = 4 → [4, 5]
expect(newNumbers).toEqual([4, 5]);
});
// Round-7 review: distinguish absent-vs-empty per AGENTS.md's "LLM
// response merging" convention. An empty string is the user's intent
// to clear the field; null/undefined is the LLM omitting it and the
// existing value should win.
it('absent string fields (null/undefined) preserve the existing value', () => {
const existing = [
{ id: 'e1', number: 1, title: 'Kept', logline: 'L', synopsis: 'S', endingHook: 'H', updatedAt: '2020-01-01T00:00:00.000Z' },
];
const incoming = [{ number: 1, title: undefined, logline: null }];
const result = importerSvc.mergeSeasons(existing, incoming, stubBuildSeason);
expect(result[0].title).toBe('Kept');
expect(result[0].logline).toBe('L');
// No change in any tracked field → updatedAt preserved
expect(result[0].updatedAt).toBe('2020-01-01T00:00:00.000Z');
});
it('empty-string fields are treated as an intentional clear and bump updatedAt', () => {
const existing = [
{ id: 'e1', number: 1, title: 'Original', logline: 'L', synopsis: 'S', endingHook: 'H', updatedAt: '2020-01-01T00:00:00.000Z' },
];
const incoming = [{ number: 1, logline: '', synopsis: '' }];
const result = importerSvc.mergeSeasons(existing, incoming, stubBuildSeason);
expect(result[0].logline).toBe('');
expect(result[0].synopsis).toBe('');
// Title not present → preserved.
expect(result[0].title).toBe('Original');
// A clear is a change → updatedAt bumps.
expect(result[0].updatedAt > '2020-01-01T00:00:00.000Z').toBe(true);
});
it('throws ERR_VALIDATION when auto-assign would exceed the season number cap (99)', () => {
const existing = Array.from({ length: 99 }, (_, i) => ({
id: `e${i + 1}`, number: i + 1, title: `S${i + 1}`, logline: '', synopsis: '',
}));
let caught;
try {
importerSvc.mergeSeasons(existing, [{ title: 'overflow' }], stubBuildSeason);
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
expect(caught.message).toContain('99');
});
// Round-11 review: legacy seasons with `title: undefined` would
// previously churn updatedAt on every no-op re-import — the change
// check compared `'Season N'` (the default applied to the new value)
// against `undefined` (the existing value), always producing a
// truthy diff. Fix applies the same default to both sides of the
// comparison so a re-import with no edits is correctly a no-op.
it('does NOT bump updatedAt for a legacy season with undefined title and no incoming edit', () => {
const existing = [
{ id: 'e1', number: 1, /* title: undefined */ logline: '', synopsis: '', updatedAt: '2020-01-01T00:00:00.000Z' },
];
// Incoming season omits every editable field — pure no-op.
const result = importerSvc.mergeSeasons(existing, [{ number: 1 }], stubBuildSeason);
expect(result[0].updatedAt).toBe('2020-01-01T00:00:00.000Z');
});
// Round-8 review: the pure helper now rejects duplicate explicit incoming
// numbers directly — commitImport's route gate caught this for HTTP
// callers, but a future direct consumer would otherwise silently collapse
// two entries sharing a number into one merge target.
it('throws ERR_VALIDATION on duplicate explicit incoming season numbers', () => {
let caught;
try {
importerSvc.mergeSeasons([], [
{ number: 1, title: 'A' },
{ number: 1, title: 'B' },
], stubBuildSeason);
} catch (err) {
caught = err;
}
expect(caught).toBeDefined();
expect(caught.code).toBe(importerSvc.ERR_VALIDATION);
expect(caught.message).toMatch(/duplicate/i);
});
});
// ---------------------------------------------------------------------------
// Reconcile draft parent universe (issue #851)
//
// An import-draft universe (ephemeral + importDraft, created by analyzeImport)
// must be promoted to a normal syncing record when a COMMITTED (non-draft)
// series is linked to it WITHOUT going through commitImport — otherwise the
// universe holds real work but silently never syncs. The promotion mirrors
// commitImport: clear BOTH importDraft and ephemeral. It must NOT fire when a
// draft series is linked (that's commitImport's job) or when the parent isn't
// a draft.
// ---------------------------------------------------------------------------
describe('reconcile draft parent universe (issue #851)', () => {
it('promotes a draft universe when a committed series is linked via updateSeries', async () => {
// Draft universe shell, exactly as analyzeImport would stamp it.
const draftUni = await universeSvc.createUniverse({
name: 'Draft Parent', ephemeral: true, importDraft: true,
});
// A separate, committed (non-draft) universe the series starts under.
const realUni = await universeSvc.createUniverse({ name: 'Committed Home' });
const committedSeries = await seriesSvc.createSeries({ name: 'Real Work', universeId: realUni.id });
expect(committedSeries.importDraft).not.toBe(true);
// Manually re-home the committed series onto the draft universe.
await seriesSvc.updateSeries(committedSeries.id, { universeId: draftUni.id });
const promoted = await universeSvc.getUniverse(draftUni.id);
expect(promoted.importDraft).not.toBe(true);
expect(promoted.ephemeral).not.toBe(true);
});
it('promotes a draft universe when a committed series is CREATED already linked to it', async () => {
const draftUni = await universeSvc.createUniverse({
name: 'Draft Parent 2', ephemeral: true, importDraft: true,
});
await seriesSvc.createSeries({ name: 'Born Committed', universeId: draftUni.id });
const promoted = await universeSvc.getUniverse(draftUni.id);
expect(promoted.importDraft).not.toBe(true);
expect(promoted.ephemeral).not.toBe(true);
});
it('does NOT promote a draft universe when a DRAFT series is linked (commitImport owns that)', async () => {
const draftUni = await universeSvc.createUniverse({
name: 'Still Draft', ephemeral: true, importDraft: true,
});
// A draft-shell series, as analyzeImport stamps it — linking it must leave
// the universe a draft so the orphan GC + commitImport keep their contract.
const draftSeries = await seriesSvc.createSeries({
name: 'Draft Child', universeId: draftUni.id, ephemeral: true, importDraft: true,
});
expect(draftSeries.importDraft).toBe(true);
const after = await universeSvc.getUniverse(draftUni.id);
expect(after.importDraft).toBe(true);
expect(after.ephemeral).toBe(true);
});
it('leaves a private (ephemeral-only, non-draft) universe untouched when a committed series is linked', async () => {
// `ephemeral` alone is a user's "keep local" choice — linking a series must
// not un-privatize it. Only `importDraft` parents get promoted.
const privateUni = await universeSvc.createUniverse({ name: 'Private', ephemeral: true });
expect(privateUni.importDraft).not.toBe(true);
const realUni = await universeSvc.createUniverse({ name: 'Elsewhere' });
const series = await seriesSvc.createSeries({ name: 'A Series', universeId: realUni.id });
await seriesSvc.updateSeries(series.id, { universeId: privateUni.id });
const after = await universeSvc.getUniverse(privateUni.id);
expect(after.ephemeral).toBe(true);
expect(after.importDraft).not.toBe(true);
});
it('leaves a non-draft universe untouched when a committed series links to it', async () => {
const normalUni = await universeSvc.createUniverse({ name: 'Normal' });
const realUni = await universeSvc.createUniverse({ name: 'Origin' });
const series = await seriesSvc.createSeries({ name: 'Moving Series', universeId: realUni.id });
await seriesSvc.updateSeries(series.id, { universeId: normalUni.id });
const after = await universeSvc.getUniverse(normalUni.id);
expect(after.importDraft).not.toBe(true);
expect(after.ephemeral).not.toBe(true);
});
it('does NOT promote a draft universe when an EPHEMERAL (private, non-draft) series is linked', async () => {
// An ephemeral series is the user signaling "keep this local" — it carries
// no syncing work, so promoting (un-privatizing) its parent would push
// peers a universe whose only child never syncs. Only a series that itself
// reaches peers should pull its draft parent into sync.
const draftUni = await universeSvc.createUniverse({
name: 'Draft Parent 3', ephemeral: true, importDraft: true,
});
const privateSeries = await seriesSvc.createSeries({
name: 'Private Committed', universeId: draftUni.id, ephemeral: true,
});
expect(privateSeries.importDraft).not.toBe(true);
expect(privateSeries.ephemeral).toBe(true);
const after = await universeSvc.getUniverse(draftUni.id);
expect(after.importDraft).toBe(true);
expect(after.ephemeral).toBe(true);
});
});