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
/**
* FableLoom whole-series editorial automation.
*
* One editor call can diagnose and repair the series plan, missing/invalid beat
* outlines, existing scene metadata, path labels/targets, and convergence
* continuity without changing episode, scene, or transition membership. A
* separate playthrough judge reviews the deterministic variation harness after
* edits land; the autopilot composes the two bounded operations.
*/
import { asArray } from '../../lib/arrayUtils.js';
import { ServerError } from '../../lib/errorHandler.js';
import { analyzeEpisodeContinuity, CONTINUITY_CODES } from '../../lib/fableLoomContinuity.js';
import { analyzeEpisodeGraph, describeGraphForPrompt } from '../../lib/fableLoomGraph.js';
import {
analyzeSeriesStoryOutlines,
analyzeStoryOutline,
analyzeStoryOutlineTeleplaySync,
describeStoryOutlineForPrompt,
fableLoomEpisodeChallenges,
sanitizeStoryOutline,
} from '../../lib/fableLoomOutline.js';
import {
analyzeLoomPlaythroughs,
buildLoomPlaythroughPromptDigest,
} from '../../lib/fableLoomPlaytest.js';
import { computeTopologicalNodeOrder } from '../../lib/fableLoomProduction.js';
import { CHARS_PER_TOKEN, usableInputTokens } from '../../lib/contextBudget.js';
import { buildCastIntegrityReport } from '../../lib/characterIntegrity.js';
import { analyzeCharacterEvolutionCoverage } from '../../lib/characterEvolutionCoverage.js';
import { renderCastIntegrity } from '../../lib/castIntegrityPrompt.js';
import {
isFableLoomPlaybackMode,
FABLELOOM_PROTAGONIST_PRESENCE,
} from '../../lib/fableLoomPlayback.js';
import { renderStoryCanonDigest } from '../../lib/universePromptRenderers.js';
import { renderSeriesDesign } from '../../lib/storyArc.js';
import { normalizeFableLoomCameraMovement } from '../../lib/fableLoomCameraMovements.js';
import { startAIOp } from '../aiStatusEvents.js';
import { buildPrompt } from '../promptService.js';
import { resolveStageContext, runStageScopedInlineLLM } from '../stageRunner.js';
import { getUniverse } from '../universeBuilder.js';
import { listVoiceProfiles } from '../voice/profiles.js';
import {
getLoom,
mutateLoom,
sanitizeLoom,
} from './records.js';
import { trimTo, isNonBlankStr } from '../../lib/textUtils.js';
import { isPlainObject } from '../../lib/objects.js';
const REVIEW_SEVERITIES = new Set(['high', 'medium', 'low']);
const REVIEW_CATEGORIES = new Set([
'coherence', 'character', 'choice', 'pacing', 'ending', 'continuity', 'canon', 'structure',
]);
const AUTOPILOT_QUALITY_THRESHOLD = 8;
const EDITORIAL_PROMPT_HARD_MAX_CHARS = 1_000_000;
const EDITORIAL_OUTPUT_RESERVE_TOKENS = 8_000;
// The cast-integrity block is CARVED OUT of the editorial prompt budget, never
// added beside it (#6415): whatever it uses is subtracted from what the
// playthrough digest is offered, so the total rendered prompt is bounded
// exactly as it was before. One short line per cast member is all it needs.
const EDITORIAL_CAST_INTEGRITY_BUDGET_SHARE = 0.02;
const EDITORIAL_CAST_INTEGRITY_MIN_CHARS = 400;
const INSTRUCTION_PLACEHOLDER_VALUES = new Set([
'concise whole-series editorial assessment',
'episode_id_from_input',
'only when changed',
'complete replacement only when changed',
'existing scene id, only when changed',
'existing scene id or null',
'existing episode id or null',
'existing transition id',
'scene_id_from_input',
"sharpened one scene's sensory detail without changing its beat.",
'specific strength worth preserving',
'the signal shivers through the flooded tunnel walls.',
]);
const hasOwn = (value, key) => Object.hasOwn(value, key);
const clampScore = (value) => (Number.isFinite(value)
? Math.max(0, Math.min(10, Math.round(value * 10) / 10))
: null);
const aiShapeError = (message) => new ServerError(message, {
status: 502,
code: 'AI_RESPONSE_INVALID',
});
const requireLoom = async (loomId) => {
const loom = await getLoom(loomId);
if (!loom) throw new ServerError('Loom not found', { status: 404, code: 'NOT_FOUND' });
return loom;
};
const llmOptions = ({ providerId, model, effort } = {}, source) => ({
source,
returnsJson: true,
// The complete path trace is budgeted against this exact resolved route.
// A smaller proactive/runtime fallback could silently exceed its context.
allowFallback: false,
...(providerId ? { providerOverride: providerId } : {}),
...(model ? { modelOverride: model } : {}),
...(effort ? { effortOverride: effort } : {}),
});
const runEditorialAi = (stage, prompt, route, { action, label, source }) => {
const status = route.operationId ? startAIOp({
op: `fableloom-${action}`,
label,
operationId: route.operationId,
localOnly: true,
silent: true,
}) : null;
const options = llmOptions(route, source);
if (status) {
options.onRunCreated = (runId, meta = {}) => status.update(
'running',
`${label} is running…`,
{ ...meta, runId, shellReady: false },
);
options.onRunReady = (meta = {}) => status.update(
'ready',
'TUI run is ready — open Shell to watch and interact',
meta,
);
options.onRunSettled = (runId) => status.update(
'applying',
'AI response received — validating the story changes…',
{ runId },
);
}
return runStageScopedInlineLLM(stage, prompt, options).then((result) => {
return { ...result, status };
}, (error) => {
status?.error(error?.message || 'FableLoom editorial operation failed', {
...(error?.runId ? { runId: error.runId } : {}),
});
throw error;
});
};
const finalizeEditorialOperation = (status, runId, work) => Promise.resolve()
.then(work)
.then((result) => {
status?.complete('Editorial operation complete', { runId, shellReady: false });
return result;
}, (error) => {
status?.error(error?.message || 'FableLoom editorial operation failed', {
...(runId ? { runId } : {}),
});
throw error;
});
const storyContext = (loom) => [
`Story: ${loom.name}`,
loom.logline ? `Logline: ${loom.logline}` : '',
loom.premise ? `Premise: ${loom.premise}` : '',
loom.styleNotes ? `Style: ${loom.styleNotes}` : '',
`Audience participation mode: ${loom.participationMode || 'protagonist'}`,
loom.audienceCommunicationMedium
? `Audience communication medium: ${loom.audienceCommunicationMedium}`
: '',
loom.protagonistCharacterId
? `Canonical protagonist id: ${loom.protagonistCharacterId}`
: '',
loom.protagonistWardrobeId
? `Canonical protagonist wardrobe id: ${loom.protagonistWardrobeId}`
: '',
renderSeriesDesign(loom.seriesPlan?.seriesDesign),
].filter(Boolean).join('\n');
const withoutTemporalMetadata = (value) => {
if (Array.isArray(value)) return value.map(withoutTemporalMetadata);
if (!value || typeof value !== 'object') return value;
return Object.fromEntries(Object.entries(value)
.filter(([key]) => !['createdAt', 'updatedAt'].includes(key))
.map(([key, item]) => [key, withoutTemporalMetadata(item)]));
};
const editorialDependencyFingerprint = ({ universe, voiceProfiles, canonDigest }) => JSON.stringify({
canonDigest,
continuityUniverse: universe ? withoutTemporalMetadata({
characters: universe.characters,
places: universe.places,
objects: universe.objects,
}) : null,
voiceProfiles: asArray(voiceProfiles).map((profile) => ({
id: profile.id,
version: profile.version,
binding: profile.binding,
approval: profile.approval,
engine: profile.engine,
modelRevision: profile.modelRevision,
})).sort((a, b) => String(a.id).localeCompare(String(b.id))),
});
const loadEditorialDependencies = async (loom, {
getUniverseFn = getUniverse,
listVoiceProfilesFn = listVoiceProfiles,
} = {}) => {
const [universe, voiceProfiles] = await Promise.all([
loom.universeId ? getUniverseFn(loom.universeId) : null,
listVoiceProfilesFn(),
]);
return {
universe,
voiceProfiles,
// Same composer the generation stages use, so the editor reviews a story
// against the SAME authored psychology the writer was given — a reviewer
// that can't see the Lie can't tell a broken arc from an intended one.
//
// The reveal gate is OFF here on purpose (#6426). The editorial pass is a
// read-only author-side critique whose whole job includes catching a
// premature reveal; a reviewer handed the masked view cannot tell concealed
// history from history the story never had. storyBible.js makes the same
// call for its editorial checks ("NOT by the editorial checks — they get
// full canon"). Generation stages keep the gate on via the default.
canonDigest: universe
? renderStoryCanonDigest(universe, {
protagonistCharacterId: loom.protagonistCharacterId,
respectRevealGates: false,
})
: '',
};
};
const assertEditorialDependenciesUnchanged = (current, fingerprint, { code, message }) => {
if (editorialDependencyFingerprint(current) !== fingerprint) {
throw new ServerError(message, { status: 409, code });
}
};
const seriesPlanDigest = (loom) => JSON.stringify({
...(Object.prototype.hasOwnProperty.call(loom.seriesPlan || {}, 'seriesDesign')
? { seriesDesign: loom.seriesPlan.seriesDesign }
: {}),
storyArc: loom.seriesPlan?.storyArc || '',
plotPoints: asArray(loom.seriesPlan?.plotPoints),
sideQuests: asArray(loom.seriesPlan?.sideQuests),
deliveryOptions: loom.seriesPlan?.deliveryOptions || null,
interEpisodeVoicemails: asArray(loom.seriesPlan?.interEpisodeVoicemails),
nextSeasonTeaser: loom.seriesPlan?.nextSeasonTeaser || null,
episodes: asArray(loom.episodes).map((episode) => ({
id: episode.id,
number: episode.number,
title: episode.title,
synopsis: episode.synopsis || '',
storyOutline: episode.storyOutline
? describeStoryOutlineForPrompt(episode.storyOutline)
: '(missing)',
})),
}, null, 2);
const exactGraphIdContract = (episode) => asArray(episode.nodes).flatMap((node) => (
asArray(node.transitions).map((transition) => (
`transition=${transition.id} sourceNode=${node.id} targetNode=${transition.targetNodeId}`
))
)).join('\n');
const teleplayDigest = (loom) => asArray(loom.episodes).map((episode) => [
`## Episode ${episode.number}: ${episode.title || 'Untitled'}`,
`Episode id: ${episode.id}`,
episode.synopsis ? `Synopsis: ${episode.synopsis}` : '',
episode.storyOutline
? `Beat outline:\n${describeStoryOutlineForPrompt(episode.storyOutline)}`
: 'Beat outline: (missing)',
episode.nodes.length
// Whole-series editing and approval need each scene's payoff, not just its
// opening. The rendered-prompt budget below rejects oversized inputs.
? describeGraphForPrompt(episode, { proseLimit: Infinity, participationMode: loom.participationMode })
: '(no expanded teleplay scenes)',
episode.nodes.length
? `Exact graph ids for patches (copy verbatim):\n${exactGraphIdContract(episode) || '(no transitions)'}`
: '',
].filter(Boolean).join('\n')).join('\n\n');
// Whole-record writes must conflict on every semantic persisted field. Only
// timestamps are excluded: they can change without changing the story input.
const editorialFingerprint = (loom) => {
const { createdAt: _createdAt, updatedAt: _updatedAt, ...semantic } = loom || {};
return JSON.stringify(semantic);
};
const assertEditorialSnapshotUnchanged = (current, fingerprint, { code, message }) => {
if (editorialFingerprint(current) !== fingerprint) {
throw new ServerError(message, { status: 409, code });
}
};
const editorialPromptBudgetChars = (contextWindow) => Math.min(
EDITORIAL_PROMPT_HARD_MAX_CHARS,
usableInputTokens({
contextWindow,
outputReserveTokens: EDITORIAL_OUTPUT_RESERVE_TOKENS,
}) * CHARS_PER_TOKEN,
);
const editorialPromptCharacterCount = (variables) => Object.values(variables).reduce((total, value) => (
total + (typeof value === 'string' ? value.length : 0)
), 0);
const assertEditorialPromptBudget = (variables, maxChars = EDITORIAL_PROMPT_HARD_MAX_CHARS) => {
const characterCount = editorialPromptCharacterCount(variables);
if (characterCount > maxChars) {
throw new ServerError(
`This story needs ${characterCount.toLocaleString()} prompt characters, above the selected model's ${maxChars.toLocaleString()}-character single-editor limit. Shorten the series, choose a larger-context model, or review it in smaller sections.`,
{ status: 413, code: 'FABLELOOM_EDITORIAL_CONTEXT_TOO_LARGE' },
);
}
return variables;
};
const withCompletePlaythroughDigest = ({ loom, report, variables, maxPromptChars }) => {
const digest = buildLoomPlaythroughPromptDigest(loom, report, { maxChars: maxPromptChars });
if (!digest.complete) {
throw new ServerError(
`The selected model can hold ${digest.includedVariationCount}/${digest.totalVariationCount} complete playthrough variations after the story context. No paths were silently omitted. Choose a larger-context model or review a smaller series.`,
{ status: 413, code: 'FABLELOOM_PLAYTHROUGH_CONTEXT_TOO_LARGE' },
);
}
return { ...variables, playthroughDigest: digest.text };
};
const renderEditorialPrompt = async (
stage,
variables,
maxPromptChars,
{ buildPromptFn = buildPrompt } = {},
) => {
const prompt = await buildPromptFn(stage, variables);
assertEditorialPromptBudget({ renderedPrompt: prompt }, maxPromptChars);
return prompt;
};
const resolveEditorialPromptBudgetChars = async (stage, route, source) => {
const { contextWindow } = await resolveStageContext(stage, llmOptions(route, source));
return editorialPromptBudgetChars(contextWindow);
};
// ---------- cast integrity (#6415) ----------
/**
* The characters this story actually stages: the canonical protagonist, every
* scene visual binding, and every interaction-window speaker.
*
* Scoping matters because the integrity block is BINDING on the editor. A
* universe holds every character its author ever wrote; measuring all of them
* would hand the editor rulings about people this loom never puts on screen,
* and spend the block's budget saying so.
*/
const loomCastCharacterIds = (loom) => {
const ids = new Set();
if (isNonBlankStr(loom?.protagonistCharacterId)) ids.add(loom.protagonistCharacterId);
for (const episode of asArray(loom?.episodes)) {
for (const node of asArray(episode.nodes)) {
for (const appearance of asArray(node.visualCanon?.characterAppearances)) {
if (isNonBlankStr(appearance?.characterId)) ids.add(appearance.characterId);
}
if (isNonBlankStr(node.interactionWindow?.protagonistCharacterId)) {
ids.add(node.interactionWindow.protagonistCharacterId);
}
}
}
return ids;
};
/**
* The deterministic cast-integrity report for this loom. ZERO provider calls —
* it runs wherever the other deterministic diagnostics do.
*
* A loom with no visual bindings yet stages nobody, and reporting "(no cast)"
* there would silently exempt exactly the early stories that most need the
* ruling. So an unbound loom falls back to the linked universe's cast: it is
* the only cast the story can be about, and the editor already receives that
* same canon in full.
*/
const loomCastIntegrityReport = (loom, universe) => {
const cast = asArray(universe?.characters);
const staged = loomCastCharacterIds(loom);
const scoped = cast.filter((character) => staged.has(character?.id));
return buildCastIntegrityReport(scoped.length ? scoped : cast);
};
const castIntegrityBudgetChars = (maxPromptChars) => Math.min(
maxPromptChars,
Math.max(
EDITORIAL_CAST_INTEGRITY_MIN_CHARS,
Math.floor(maxPromptChars * EDITORIAL_CAST_INTEGRITY_BUDGET_SHARE),
),
);
/** The prompt block, in the editor's own budget terms. */
const renderLoomCastIntegrity = (report, maxPromptChars) => renderCastIntegrity(report, {
maxChars: castIntegrityBudgetChars(maxPromptChars),
castLabel: 'story-linked',
budgetLabel: 'editorial prompt budget',
});
/** Assemble every deterministic series-level authoring/playthrough signal. */
export async function collectFableLoomEditorialDiagnostics(
loom,
dependencySnapshot = null,
{ playthroughReport = null } = {},
) {
const { universe, voiceProfiles } = dependencySnapshot || await loadEditorialDependencies(loom);
const outline = analyzeSeriesStoryOutlines(loom);
const playthrough = playthroughReport || analyzeLoomPlaythroughs(loom);
const episodes = loom.episodes.map((episode, index) => {
const graph = analyzeEpisodeGraph(episode, {
participationMode: loom.participationMode,
requireAudienceIntroduction: index === 0,
});
const continuity = analyzeEpisodeContinuity({
loom,
episode,
universe,
localVoiceProfiles: voiceProfiles,
});
const playtest = playthrough.episodes.find((item) => item.episodeId === episode.id);
return {
episodeId: episode.id,
number: episode.number || index + 1,
title: episode.title || `Episode ${episode.number || index + 1}`,
graph,
continuity,
playtest,
};
});
const graphErrors = episodes.reduce((total, episode) => total + episode.graph.stats.errorCount, 0);
const graphWarnings = episodes.reduce((total, episode) => total + episode.graph.stats.warningCount, 0);
const continuityErrors = episodes.reduce((total, episode) => total + episode.continuity.summary.errors, 0);
const continuityWarnings = episodes.reduce((total, episode) => total + episode.continuity.summary.warnings, 0);
const convergenceIssues = episodes.reduce((total, episode) => total + episode.continuity.findings.filter((finding) => (
finding.code === CONTINUITY_CODES.AMBIGUOUS_CONVERGENCE
)).length, 0);
const playthroughErrors = episodes.reduce((total, episode) => (
total + (episode.playtest?.stats.errorCount || 0)
), 0);
// Deterministic, zero-provider, and measured off the SAME universe snapshot
// the continuity pass reads — so a depth ruling the editor is told is binding
// always names a character the canon digest actually describes.
const castIntegrity = loomCastIntegrityReport(loom, universe);
// Branch coverage for the OPTIONAL evolution lens (#6444). `null` when the
// plan never opted in, and every key it contributes is then omitted — so a
// loom without a lens produces byte-identical diagnostics to a pre-#6444
// install, and the lens never becomes a gate on a legacy story. Reuses the
// playthrough report already computed above; it adds no enumeration.
const evolutionCoverage = analyzeCharacterEvolutionCoverage(loom, {
playthroughReport: playthrough,
});
const stats = {
outlineErrors: outline.stats.errorCount,
outlineWarnings: outline.stats.warningCount,
graphErrors,
graphWarnings,
continuityErrors,
continuityWarnings,
convergenceIssues,
playthroughErrors,
variationCount: playthrough.stats.variationCount,
endingVariationCount: playthrough.stats.endingVariationCount,
visitedTransitionCount: playthrough.stats.visitedTransitionCount,
transitionCount: playthrough.stats.transitionCount,
castCharacterCount: castIntegrity.castCount,
castIntegrityFindings: castIntegrity.findings.length,
...(evolutionCoverage ? {
evolutionCoverageStatus: evolutionCoverage.status,
evolutionCoverageFindings: evolutionCoverage.stats.findingCount,
unreviewedEvolutionLenses: evolutionCoverage.stats.unreviewedLensCount,
} : {}),
};
return {
passed: outline.stats.ready
&& graphErrors === 0
&& continuityErrors === 0
&& convergenceIssues === 0
&& playthrough.passed,
outline,
playthrough,
episodes,
// Reported, never gating: a thin spear-carrier must not block a FableLoom
// autopilot run the way a broken graph does. The editor is told about it;
// the pass/fail contract is unchanged.
castIntegrity,
// Reported, never gating — for the same reason cast integrity is not: an
// unproven branch is a craft note, not a broken graph, and `passed` stays
// exactly the contract it was before the lens existed.
...(evolutionCoverage ? { evolutionCoverage } : {}),
stats,
};
}
const diagnosticLines = (diagnostics) => {
const lines = [
`Series outlines: ${diagnostics.stats.outlineErrors} error(s), ${diagnostics.stats.outlineWarnings} warning(s).`,
`Episode graphs: ${diagnostics.stats.graphErrors} error(s), ${diagnostics.stats.graphWarnings} warning(s).`,
`Continuity: ${diagnostics.stats.continuityErrors} error(s), ${diagnostics.stats.continuityWarnings} warning(s), ${diagnostics.stats.convergenceIssues} ambiguous convergence scene(s).`,
`Playthroughs: ${diagnostics.stats.variationCount} variation(s), ${diagnostics.stats.endingVariationCount} ending path(s), ${diagnostics.stats.visitedTransitionCount}/${diagnostics.stats.transitionCount} transitions exercised.`,
];
diagnostics.outline.issues.forEach((issue) => {
lines.push(`- [outline/${issue.severity}] episode=${issue.episodeId || 'series'} scene=${issue.sceneKey || '-'} code=${issue.code}: ${issue.message}`);
});
diagnostics.episodes.forEach((episode) => {
episode.graph.issues.forEach((issue) => {
lines.push(`- [graph/${issue.severity}] episode=${episode.episodeId} node=${issue.nodeId || '-'} code=${issue.code}: ${issue.message}`);
});
episode.continuity.findings.forEach((finding) => {
lines.push(`- [continuity/${finding.severity}] episode=${episode.episodeId} node=${finding.nodeId || '-'} code=${finding.code}: ${finding.message} Fix: ${finding.remediation}`);
});
asArray(episode.playtest?.issues).forEach((issue) => {
lines.push(`- [playthrough/${issue.severity}] episode=${episode.episodeId} path=${issue.pathId || '-'} node=${issue.nodeId || '-'} code=${issue.code}: ${issue.message}`);
});
});
if (diagnostics.evolutionCoverage) {
const coverage = diagnostics.evolutionCoverage;
lines.push(`Character evolution coverage: ${coverage.status}; ${coverage.stats.declaredLensCount}/${coverage.stats.lensCount} lens(es) declared, ${coverage.stats.unreviewedLensCount} unreviewed.`);
coverage.findings.forEach((finding) => {
lines.push(`- [evolution/${finding.severity}] episode=${finding.episodeId || '-'} node=${finding.nodeId || '-'} stage=${finding.stageId || '-'} code=${finding.code}: ${finding.message} Fix: ${finding.remediation}`);
});
}
return lines.join('\n');
};
const compactEditorialDiagnostics = (diagnostics) => {
const findings = [
...diagnostics.outline.issues
.filter((issue) => issue.severity === 'error')
.map((issue) => ({
severity: 'high',
category: 'structure',
episodeId: issue.episodeId || null,
nodeId: issue.sceneKey || null,
pathId: null,
problem: issue.message,
suggestion: 'Repair and revalidate the complete episode beat outline.',
})),
...diagnostics.episodes.flatMap((episode) => episode.graph.issues
.filter((issue) => issue.severity === 'error')
.map((issue) => ({
severity: 'high',
category: 'structure',
episodeId: episode.episodeId,
nodeId: issue.nodeId || null,
pathId: null,
problem: issue.message,
suggestion: 'Repair the episode graph contract before another playthrough review.',
}))),
...diagnostics.episodes.flatMap((episode) => episode.continuity.findings
.filter((finding) => finding.severity === 'error'
|| finding.code === CONTINUITY_CODES.AMBIGUOUS_CONVERGENCE)
.map((finding) => ({
severity: finding.severity === 'error' ? 'high' : 'medium',
category: 'continuity',
episodeId: episode.episodeId,
nodeId: finding.nodeId || null,
pathId: null,
problem: finding.message,
suggestion: finding.remediation || 'Repair the continuity break.',
}))),
// Branch coverage for the evolution lens lands in the shared shape as
// `character`, so the editor reads it beside every other finding. Absent
// entirely when no lens is authored.
...asArray(diagnostics.evolutionCoverage?.findings).map((finding) => ({
severity: finding.severity === 'error' ? 'high' : 'medium',
category: 'character',
episodeId: finding.episodeId || null,
nodeId: finding.nodeId || null,
pathId: finding.pathId || null,
problem: finding.message,
suggestion: finding.remediation,
})),
];
return {
passed: diagnostics.passed,
stats: diagnostics.stats,
findings: findings.slice(0, 80),
};
};
const analysisStrings = (value) => asArray(value)
.filter((item) => typeof item === 'string')
.map((item) => trimTo(item, 1000))
.filter(Boolean)
.slice(0, 20);
const sanitizeEvaluation = (content, loom) => {
const episodeIds = new Set(loom.episodes.map((episode) => episode.id));
const nodesByEpisode = new Map(loom.episodes.map((episode) => [
episode.id,
new Set(episode.nodes.map((node) => node.id)),
]));
const findings = asArray(content?.findings)
.filter((finding) => finding && typeof finding === 'object' && isNonBlankStr(finding.problem))
.slice(0, 40)
.map((finding) => {
const episodeId = episodeIds.has(finding.episodeId) ? finding.episodeId : null;
const nodeId = episodeId && nodesByEpisode.get(episodeId).has(finding.nodeId)
? finding.nodeId
: null;
return {
severity: REVIEW_SEVERITIES.has(finding.severity) ? finding.severity : 'medium',
category: REVIEW_CATEGORIES.has(finding.category) ? finding.category : 'coherence',
episodeId,
nodeId,
problem: trimTo(finding.problem, 1200),
suggestion: trimTo(finding.suggestion, 1200),
};
});
return {
summary: trimTo(content?.summary, 2500),
strengths: analysisStrings(content?.strengths),
findings,
};
};
const allowedEpisodeFields = ['title', 'synopsis', 'startNodeId'];
const allowedSceneFields = [
'title', 'prose', 'imagePrompt', 'videoPrompt', 'cameraMovement', 'playbackMode',
'audienceConnection', 'protagonistPresence', 'isEnding', 'endingLabel',
];
const allowedTransitionFields = ['targetNodeId', 'intent', 'triggers', 'description'];
const clearableSeriesPlanFields = new Set([
'plotPoints', 'sideQuests', 'deliveryOptions', 'interEpisodeVoicemails', 'nextSeasonTeaser',
]);
const containsInstructionPlaceholder = (value) => {
if (typeof value === 'string') return INSTRUCTION_PLACEHOLDER_VALUES.has(value.trim().toLowerCase());
if (Array.isArray(value)) return value.some(containsInstructionPlaceholder);
if (value && typeof value === 'object') return Object.values(value).some(containsInstructionPlaceholder);
return false;
};
const collectionHasContent = (value) => (
(Array.isArray(value) && value.length > 0)
|| (value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0)
);
const isOptionalId = (value) => value === undefined
|| (typeof value === 'string' && value.trim().length > 0);
const isPlanItem = (value) => isPlainObject(value)
&& isOptionalId(value.id)
&& typeof value.title === 'string'
&& typeof value.description === 'string';
const isEpisodeRef = (value, episodeIds) => value === undefined
|| value === null
|| (typeof value === 'string' && episodeIds.has(value));
const seriesPlanFieldValueIsValid = (key, value, episodeIds) => {
if (key === 'storyArc') return typeof value === 'string';
if (key === 'plotPoints') {
return Array.isArray(value) && value.every((item) => (
isPlanItem(item) && isEpisodeRef(item.episodeId, episodeIds)
));
}
if (key === 'sideQuests') {
return Array.isArray(value) && value.every((item) => (
isPlanItem(item)
&& ['idea', 'planned', 'active', 'resolved'].includes(item.status)
&& isEpisodeRef(item.startEpisodeId, episodeIds)
&& isEpisodeRef(item.endEpisodeId, episodeIds)
));
}
if (key === 'deliveryOptions') {
return isPlainObject(value)
&& Object.keys(value).every((field) => ['overnightVoicemails', 'nextSeasonTeaser'].includes(field))
&& Object.values(value).every((field) => typeof field === 'boolean');
}
if (key === 'interEpisodeVoicemails') {
return Array.isArray(value) && value.every((item) => (
isPlainObject(item)
&& isOptionalId(item.id)
&& isEpisodeRef(item.fromEpisodeId, episodeIds)
&& isEpisodeRef(item.toEpisodeId, episodeIds)
&& typeof item.title === 'string'
&& typeof item.transcript === 'string'
));
}
if (key === 'nextSeasonTeaser') {
return value === null || (isPlainObject(value)
&& typeof value.title === 'string'
&& typeof value.transcript === 'string');
}
return false;
};
const seriesPlanFieldValueIsClear = (key, value) => (
(['plotPoints', 'sideQuests', 'interEpisodeVoicemails'].includes(key)
&& Array.isArray(value) && value.length === 0)
|| (key === 'deliveryOptions'
&& value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0)
|| (key === 'nextSeasonTeaser' && (
value === null
|| (isPlainObject(value)
&& !value.title.trim()
&& !value.transcript.trim())
))
);
const applySeriesPlanPatch = (currentPlan, raw, explicitClears, episodeIds) => {
if (!raw || typeof raw !== 'object') return currentPlan;
const next = { ...currentPlan };
for (const key of [
'storyArc', 'plotPoints', 'sideQuests', 'deliveryOptions',
'interEpisodeVoicemails', 'nextSeasonTeaser',
]) {
if (!hasOwn(raw, key)) continue;
if (!seriesPlanFieldValueIsValid(key, raw[key], episodeIds)) {
throw aiShapeError(`The model returned an invalid value for seriesPlan.${key}`);
}
if (clearableSeriesPlanFields.has(key)
&& seriesPlanFieldValueIsClear(key, raw[key])
&& collectionHasContent(currentPlan?.[key])
&& !explicitClears.has(`seriesPlan.${key}`)) {
throw aiShapeError(`The model tried to clear seriesPlan.${key} without listing it in clears`);
}
next[key] = key === 'deliveryOptions' && !seriesPlanFieldValueIsClear(key, raw[key])
? { ...(currentPlan?.deliveryOptions || {}), ...raw[key] }
: raw[key];
}
return next;
};
const outlineRelevantEpisodeFingerprint = (episode) => JSON.stringify({
title: episode.title,
synopsis: episode.synopsis,
startNodeId: episode.startNodeId,
nodes: episode.nodes.map((node) => ({
id: node.id,
title: node.title,
playbackMode: node.playbackMode,
audienceConnection: node.audienceConnection,
protagonistPresence: node.protagonistPresence,
isEnding: node.isEnding,
endingLabel: node.endingLabel,
transitions: asArray(node.transitions).map((transition) => ({
targetNodeId: transition.targetNodeId,
intent: transition.intent,
})),
})),
});
const assertOutlineMatchesExpandedEpisode = (episode, outline, participationMode) => {
const sync = analyzeStoryOutlineTeleplaySync(episode, outline, { participationMode });
if (sync.stats.matches) return;
throw aiShapeError(`The model returned a stale outline for episode ${episode.id}: ${sync.issues[0].message}`);
};
const applyScenePatch = (episode, scene, rawScene) => {
for (const key of allowedSceneFields) {
if (!hasOwn(rawScene, key)) continue;
const value = rawScene[key];
if (['title', 'prose', 'imagePrompt', 'videoPrompt', 'endingLabel'].includes(key)
&& typeof value === 'string') scene[key] = value;
if (key === 'cameraMovement' && typeof value === 'string') {
scene.cameraMovement = normalizeFableLoomCameraMovement(value);
}
if (key === 'playbackMode' && isFableLoomPlaybackMode(value)) scene.playbackMode = value;
if (key === 'audienceConnection' && ['connected', 'disconnected'].includes(value)) {
scene.audienceConnection = value;
}
if (key === 'protagonistPresence' && FABLELOOM_PROTAGONIST_PRESENCE.includes(value)) {
scene.protagonistPresence = value;
}
if (key === 'isEnding' && typeof value === 'boolean') scene.isEnding = value;
}
const transitionsById = new Map(asArray(scene.transitions).map((transition) => [transition.id, transition]));
const nodeIds = new Set(episode.nodes.map((node) => node.id));
if (hasOwn(rawScene, 'transitions') && !Array.isArray(rawScene.transitions)) {
throw aiShapeError(`The model returned invalid transitions for scene ${scene.id}`);
}
const returnedTransitionIds = new Set();
for (const rawTransition of asArray(rawScene.transitions)) {
if (!isPlainObject(rawTransition) || !isNonBlankStr(rawTransition.id)) {
throw aiShapeError(`The model returned a transition without an existing id for scene ${scene.id}`);
}
const transition = transitionsById.get(rawTransition?.id);
if (!transition) {
throw aiShapeError(`The model returned unknown transition id ${rawTransition.id} for scene ${scene.id}`);
}
if (returnedTransitionIds.has(transition.id)) {
throw aiShapeError(`The model returned duplicate transition id ${transition.id} for scene ${scene.id}`);
}
returnedTransitionIds.add(transition.id);
for (const key of allowedTransitionFields) {
if (!hasOwn(rawTransition, key)) continue;
const value = rawTransition[key];
if (key === 'targetNodeId') {
if (typeof value !== 'string' || !nodeIds.has(value)) {
throw aiShapeError(`The model returned an invalid transition target for ${transition.id}`);
}
transition.targetNodeId = value;
}
if (['intent', 'description'].includes(key) && typeof value === 'string') transition[key] = value;
if (key === 'triggers') {
if (!Array.isArray(value) || value.some((trigger) => typeof trigger !== 'string')) {
throw aiShapeError(`The model returned invalid triggers for transition ${transition.id}`);
}
transition.triggers = value;
}
}
}
};
const applyContinuitySourcePatch = (scene, sourceId, predecessorsByNodeId) => {
const validPredecessors = new Set(
asArray(predecessorsByNodeId.get(scene.id)).map((item) => item.nodeId),
);
if (sourceId !== null && (!isNonBlankStr(sourceId) || !validPredecessors.has(sourceId))) {
throw aiShapeError(`The model selected an invalid continuity predecessor for scene ${scene.id}`);
}
scene.visualCanon = {
...(scene.visualCanon || {}),
continuitySourceNodeId: sourceId,
};
};
const countGraphErrors = (loom) => loom.episodes.reduce((total, episode, index) => (
total + analyzeEpisodeGraph(episode, {
participationMode: loom.participationMode,
requireAudienceIntroduction: index === 0,
}).stats.errorCount
), 0);
const graphErrorIdentities = (loom) => new Set(loom.episodes.flatMap((episode, index) => (
analyzeEpisodeGraph(episode, {
participationMode: loom.participationMode,
requireAudienceIntroduction: index === 0,
}).issues
.filter((issue) => issue.severity === 'error')
.map((issue) => JSON.stringify([
episode.id,
issue.code,
issue.nodeId || null,
issue.transitionId || null,
]))
)));
const outlineErrorIdentities = (loom) => new Set(analyzeSeriesStoryOutlines(loom).issues
.filter((issue) => issue.severity === 'error')
.map((issue) => JSON.stringify([
issue.episodeId || null,
issue.code,
issue.sceneKey || null,
Number.isInteger(issue.transitionIndex) ? issue.transitionIndex : null,
])));
const playthroughErrorIdentities = (report) => new Set(report.episodes.flatMap((episode) => (
episode.issues
.filter((issue) => issue.severity === 'error')
.map((issue) => JSON.stringify([
episode.episodeId,
issue.code,
issue.nodeId || null,
issue.transitionId || null,
]))
)));
const continuityBlockers = (loom, { universe = null, voiceProfiles = [] } = {}) => (
loom.episodes.flatMap((episode) => analyzeEpisodeContinuity({
loom,
episode,
universe,
localVoiceProfiles: voiceProfiles,
}).findings
.filter((finding) => finding.severity === 'error'
|| finding.code === CONTINUITY_CODES.AMBIGUOUS_CONVERGENCE)
.map((finding) => ({ episodeId: episode.id, ...finding })))
);
const continuityBlockerIdentities = (findings) => new Set(findings.map((finding) => JSON.stringify([
finding.episodeId,
finding.code,
finding.severity,
finding.nodeId || null,
finding.characterId || null,
finding.assetId || null,
])));
const hasIntroducedIdentity = (before, after) => [...after].some((identity) => !before.has(identity));
/**
* Apply a model response to an in-memory loom while preserving graph
* membership. Exported for focused contract tests and the persistence wrapper.
*/
export function applyFableLoomEditorialPatch(
loom,
content,
{ universe = null, voiceProfiles = [] } = {},
) {
if (!content || typeof content !== 'object') throw aiShapeError('The model returned no editorial response');
if (containsInstructionPlaceholder(content)) {
throw aiShapeError('The model copied an instructional placeholder instead of returning authored story data');
}
const candidate = structuredClone(loom);
const beforeGraphErrors = countGraphErrors(candidate);
const beforeOutlineErrors = analyzeSeriesStoryOutlines(candidate).stats.errorCount;
const beforePlaythrough = analyzeLoomPlaythroughs(candidate);
const beforeContinuityBlockers = continuityBlockers(candidate, { universe, voiceProfiles });
const beforeGraphErrorIdentities = graphErrorIdentities(candidate);
const beforeOutlineErrorIdentities = outlineErrorIdentities(candidate);
const beforePlaythroughErrorIdentities = playthroughErrorIdentities(beforePlaythrough);
const beforeContinuityBlockerIdentities = continuityBlockerIdentities(beforeContinuityBlockers);
const explicitClears = new Set(asArray(content.clears).filter((value) => typeof value === 'string'));
if (hasOwn(content, 'episodes') && !Array.isArray(content.episodes)) {
throw aiShapeError('The model returned an invalid episode patch list');
}
if (content.seriesPlan && typeof content.seriesPlan === 'object') {
const episodeIds = new Set(candidate.episodes.map((episode) => episode.id));
candidate.seriesPlan = applySeriesPlanPatch(
candidate.seriesPlan,
content.seriesPlan,
explicitClears,
episodeIds,
);
}
const episodesById = new Map(candidate.episodes.map((episode) => [episode.id, episode]));
const returnedEpisodeIds = new Set();
for (const rawEpisode of asArray(content.episodes)) {
if (!isPlainObject(rawEpisode) || !isNonBlankStr(rawEpisode.id)) {
throw aiShapeError('The model returned an episode patch without an existing id');
}
const episode = episodesById.get(rawEpisode?.id);
if (!episode) throw aiShapeError(`The model returned unknown episode id ${rawEpisode.id}`);
if (returnedEpisodeIds.has(episode.id)) {
throw aiShapeError(`The model returned duplicate episode id ${episode.id}`);
}
returnedEpisodeIds.add(episode.id);
const beforeOutlineContract = outlineRelevantEpisodeFingerprint(episode);
const replacementOutline = hasOwn(rawEpisode, 'storyOutline')
? rawEpisode.storyOutline
: undefined;
for (const key of allowedEpisodeFields) {
if (!hasOwn(rawEpisode, key)) continue;
const value = rawEpisode[key];
if (['title', 'synopsis'].includes(key) && typeof value === 'string') episode[key] = value;
if (key === 'startNodeId') {
if (typeof value !== 'string' || !episode.nodes.some((node) => node.id === value)) {
throw aiShapeError(`The model returned an invalid opening scene for episode ${episode.id}`);
}
episode.startNodeId = value;
}
}
const scenesById = new Map(episode.nodes.map((scene) => [scene.id, scene]));
const continuitySourcePatches = [];
if (hasOwn(rawEpisode, 'scenes') && !Array.isArray(rawEpisode.scenes)) {
throw aiShapeError(`The model returned an invalid scene patch list for episode ${episode.id}`);
}
const returnedSceneIds = new Set();
for (const rawScene of asArray(rawEpisode.scenes)) {
if (!isPlainObject(rawScene) || !isNonBlankStr(rawScene.id)) {
throw aiShapeError(`The model returned a scene patch without an existing id for episode ${episode.id}`);
}
const scene = scenesById.get(rawScene?.id);
if (!scene) throw aiShapeError(`The model returned unknown scene id ${rawScene.id}`);
if (returnedSceneIds.has(scene.id)) {
throw aiShapeError(`The model returned duplicate scene id ${scene.id}`);
}
returnedSceneIds.add(scene.id);
applyScenePatch(episode, scene, rawScene);
if (rawScene.visualCanon && typeof rawScene.visualCanon === 'object'
&& hasOwn(rawScene.visualCanon, 'continuitySourceNodeId')) {
continuitySourcePatches.push({
scene,
sourceId: rawScene.visualCanon.continuitySourceNodeId,
});
}
}
// Transition targets are patchable, so predecessor validation must run
// against the resulting graph rather than the graph the model inspected.
const { predecessorsByNodeId } = computeTopologicalNodeOrder(episode);
for (const { scene, sourceId } of continuitySourcePatches) {
applyContinuitySourcePatch(scene, sourceId, predecessorsByNodeId);
}
const outlineContractChanged = beforeOutlineContract !== outlineRelevantEpisodeFingerprint(episode);
if (replacementOutline !== undefined) {
const storyOutline = sanitizeStoryOutline(replacementOutline, {
participationMode: candidate.participationMode,
});
if (!storyOutline) throw aiShapeError(`The model returned an unusable outline for episode ${episode.id}`);
const analysis = analyzeStoryOutline(storyOutline, {
participationMode: candidate.participationMode,
requireAudienceIntroduction: candidate.episodes[0]?.id === episode.id,
challenges: fableLoomEpisodeChallenges(candidate, episode.id),
});
if (analysis.stats.errorCount) {
throw aiShapeError(`The model returned an invalid outline for episode ${episode.id}: ${analysis.issues.find((issue) => issue.severity === 'error')?.message}`);
}
assertOutlineMatchesExpandedEpisode(episode, storyOutline, candidate.participationMode);
episode.storyOutline = {
...storyOutline,
validation: {
status: 'valid',
issues: analysis.issues,
validatedAt: new Date().toISOString(),
},
};
} else if (outlineContractChanged && episode.storyOutline?.validation?.status === 'valid') {
throw aiShapeError(`The model changed episode ${episode.id}'s outline contract without returning a synchronized storyOutline`);
} else if (outlineContractChanged && episode.storyOutline) {
episode.storyOutline.validation = { status: 'draft', issues: [] };
}
}
for (const episode of candidate.episodes) {
if (!episode.nodes.length || episode.storyOutline?.validation?.status !== 'valid') continue;
const sync = analyzeStoryOutlineTeleplaySync(episode, episode.storyOutline, {
participationMode: candidate.participationMode,
});
if (!sync.stats.matches) {
throw aiShapeError(`Episode ${episode.id} has a stale validated outline; return a synchronized storyOutline before applying other edits`);
}
}
const sanitized = sanitizeLoom(candidate);
if (!sanitized) throw aiShapeError('The editorial response produced an invalid loom');
const afterGraphErrors = countGraphErrors(sanitized);
const afterOutlineErrors = analyzeSeriesStoryOutlines(sanitized).stats.errorCount;
const afterPlaythrough = analyzeLoomPlaythroughs(sanitized);
const afterContinuityBlockers = continuityBlockers(sanitized, { universe, voiceProfiles });
const afterGraphErrorIdentities = graphErrorIdentities(sanitized);
const afterOutlineErrorIdentities = outlineErrorIdentities(sanitized);
const afterPlaythroughErrorIdentities = playthroughErrorIdentities(afterPlaythrough);
const afterContinuityBlockerIdentities = continuityBlockerIdentities(afterContinuityBlockers);
if (afterGraphErrors > beforeGraphErrors
|| hasIntroducedIdentity(beforeGraphErrorIdentities, afterGraphErrorIdentities)) {
throw aiShapeError('The editorial response introduced new episode graph errors');
}
if (afterOutlineErrors > beforeOutlineErrors
|| hasIntroducedIdentity(beforeOutlineErrorIdentities, afterOutlineErrorIdentities)) {
throw aiShapeError('The editorial response introduced new series-outline errors');
}
if ((beforePlaythrough.passed && !afterPlaythrough.passed)
|| afterPlaythrough.stats.errorCount > beforePlaythrough.stats.errorCount
|| afterPlaythrough.stats.nonEndingVariationCount > beforePlaythrough.stats.nonEndingVariationCount
|| hasIntroducedIdentity(beforePlaythroughErrorIdentities, afterPlaythroughErrorIdentities)) {
throw aiShapeError('The editorial response introduced new playthrough failures');
}
if (afterContinuityBlockers.length > beforeContinuityBlockers.length
|| hasIntroducedIdentity(
beforeContinuityBlockerIdentities,
afterContinuityBlockerIdentities,
)) {
throw aiShapeError('The editorial response introduced new continuity blockers');
}
const before = editorialFingerprint(loom);
const after = editorialFingerprint(sanitized);
if (before === after && analysisStrings(content?.changes).length) {
throw aiShapeError('The model claimed editorial changes but returned no applicable patch');
}
return {
loom: sanitized,
changed: before !== after,
before: { graphErrors: beforeGraphErrors, outlineErrors: beforeOutlineErrors },
after: { graphErrors: afterGraphErrors, outlineErrors: afterOutlineErrors },
};
}
/** One AI call that evaluates and repairs the complete existing loom. */
export async function evaluateAndRemediateFableLoom(loomId, {
guidance = '', providerId, model, effort, operationId,
} = {}) {
const loom = await requireLoom(loomId);
const fingerprint = editorialFingerprint(loom);
const dependencies = await loadEditorialDependencies(loom);
const dependencyFingerprint = editorialDependencyFingerprint(dependencies);
const diagnostics = await collectFableLoomEditorialDiagnostics(loom, dependencies);
const stage = 'fableloom-editorial-remediate';
const maxPromptChars = await resolveEditorialPromptBudgetChars(
stage,
{ providerId, model, effort },
'fableloom-editorial-remediate',
);
const castIntegrity = renderLoomCastIntegrity(diagnostics.castIntegrity, maxPromptChars);
const variables = withCompletePlaythroughDigest({
loom,
report: diagnostics.playthrough,
// Carved out, not added beside: the playthrough digest is offered what the
// integrity block did not spend, so the editorial prompt total is bounded
// exactly as it was before this block existed.
maxPromptChars: Math.max(0, maxPromptChars - castIntegrity.length),
variables: {
storyContext: storyContext(loom),
canonDigest: dependencies.canonDigest || '(none)',
castIntegrity,
seriesPlanJson: seriesPlanDigest(loom),
teleplayDigest: teleplayDigest(loom),
deterministicDigest: diagnosticLines(diagnostics),
guidance: trimTo(guidance, 4000) || '(none)',
},
});
const prompt = await renderEditorialPrompt(stage, variables, maxPromptChars);
const { content, runId, status } = await runEditorialAi(stage, prompt, {
providerId, model, effort, operationId,
}, {
action: 'editorial-remediate',
label: 'Evaluating and remediating the FableLoom series',
source: 'fableloom-editorial-remediate',
});
return finalizeEditorialOperation(status, runId, async () => {
const evaluation = sanitizeEvaluation(content, loom);
if (!evaluation.summary && !evaluation.strengths.length && !evaluation.findings.length) {
throw aiShapeError('The model returned no usable editorial evaluation');
}
const applied = applyFableLoomEditorialPatch(loom, content, dependencies);
let verifiedDependencies;
const updated = applied.changed ? await mutateLoom(loomId, async (current) => {
assertEditorialSnapshotUnchanged(current, fingerprint, {
code: 'LOOM_CHANGED_DURING_GENERATION',
message: 'The story changed while the editorial pass was running',
});
verifiedDependencies = await loadEditorialDependencies(current);
assertEditorialDependenciesUnchanged(verifiedDependencies, dependencyFingerprint, {
code: 'LOOM_DEPENDENCIES_CHANGED_DURING_GENERATION',
message: 'Linked canon or voice profiles changed while the editorial pass was running',
});
return applied.loom;
}) : await requireLoom(loomId);
if (!applied.changed) {
assertEditorialSnapshotUnchanged(updated, fingerprint, {
code: 'LOOM_CHANGED_DURING_GENERATION',
message: 'The story changed while the editorial pass was running',
});
verifiedDependencies = await loadEditorialDependencies(updated);
assertEditorialDependenciesUnchanged(verifiedDependencies, dependencyFingerprint, {
code: 'LOOM_DEPENDENCIES_CHANGED_DURING_GENERATION',
message: 'Linked canon or voice profiles changed while the editorial pass was running',
});
}
const afterDiagnostics = await collectFableLoomEditorialDiagnostics(
updated,
verifiedDependencies || dependencies,
);
return {
loom: updated,
changed: applied.changed,
changes: analysisStrings(content?.changes),
evaluation,
before: diagnostics.stats,
after: afterDiagnostics.stats,
diagnostics: afterDiagnostics,
runId,
};
});
}
const sanitizePlaythroughReview = (content, loom, deterministic) => {
const episodeById = new Map(loom.episodes.map((episode) => [episode.id, episode]));
const pathsByEpisode = new Map(deterministic.episodes.map((episode) => [
episode.episodeId,
new Set(episode.paths.map((path) => path.id)),
]));
const findings = asArray(content?.findings)
.filter((finding) => finding && typeof finding === 'object' && isNonBlankStr(finding.problem))
.slice(0, 60)
.map((finding) => {
const episode = episodeById.get(finding.episodeId);
const episodeId = episode?.id || null;
const nodeId = episode?.nodes.some((node) => node.id === finding.nodeId)
? finding.nodeId
: null;
const pathId = episodeId && pathsByEpisode.get(episodeId)?.has(finding.pathId)
? finding.pathId
: null;
return {
severity: REVIEW_SEVERITIES.has(finding.severity) ? finding.severity : 'medium',
category: REVIEW_CATEGORIES.has(finding.category) ? finding.category : 'coherence',
episodeId,
nodeId,
pathId,
problem: trimTo(finding.problem, 1200),
suggestion: trimTo(finding.suggestion, 1200),
};
});
const qualityScore = clampScore(content?.qualityScore);
if (qualityScore === null || !isNonBlankStr(content?.summary)) {
throw aiShapeError('The model returned no usable playthrough quality verdict');
}
return {
passed: content?.passed === true,
qualityScore,
summary: trimTo(content.summary, 2500),
strengths: analysisStrings(content?.strengths),
findings,
};
};
/** Run the deterministic variations and optionally one AI quality review. */
export async function reviewFableLoomPlaythroughs(loomId, {
aiReview = true, maxPaths, providerId, model, effort, operationId,
} = {}) {
const loom = await requireLoom(loomId);
const fingerprint = editorialFingerprint(loom);
const deterministic = analyzeLoomPlaythroughs(loom, { maxPaths });
if (!aiReview) return { passed: deterministic.passed, deterministic, review: null, runId: null };
const dependencies = await loadEditorialDependencies(loom);
const dependencyFingerprint = editorialDependencyFingerprint(dependencies);
const diagnostics = await collectFableLoomEditorialDiagnostics(
loom,
dependencies,
{ playthroughReport: deterministic },
);
const stage = 'fableloom-review-playthroughs';
const maxPromptChars = await resolveEditorialPromptBudgetChars(
stage,
{ providerId, model, effort },
'fableloom-review-playthroughs',
);
const variables = withCompletePlaythroughDigest({
loom,
report: deterministic,
maxPromptChars,
variables: {
storyContext: storyContext(loom),
canonDigest: dependencies.canonDigest || '(none)',
seriesPlanJson: seriesPlanDigest(loom),
teleplayDigest: teleplayDigest(loom),
deterministicDigest: diagnosticLines(diagnostics),
},
});
const prompt = await renderEditorialPrompt(stage, variables, maxPromptChars);
const { content, runId, status } = await runEditorialAi(stage, prompt, {
providerId, model, effort, operationId,
}, {
action: 'review-playthroughs',
label: 'Reviewing FableLoom playthrough variations',
source: 'fableloom-review-playthroughs',
});
return finalizeEditorialOperation(status, runId, async () => {
const current = await requireLoom(loomId);
assertEditorialSnapshotUnchanged(current, fingerprint, {
code: 'LOOM_CHANGED_DURING_REVIEW',
message: 'The story changed while the playthrough review was running',
});
const currentDependencies = await loadEditorialDependencies(current);
assertEditorialDependenciesUnchanged(currentDependencies, dependencyFingerprint, {
code: 'LOOM_DEPENDENCIES_CHANGED_DURING_REVIEW',
message: 'Linked canon or voice profiles changed while the playthrough review was running',
});
const review = sanitizePlaythroughReview(content, loom, deterministic);
const hasHighFinding = review.findings.some((finding) => finding.severity === 'high');
return {
passed: diagnostics.passed
&& deterministic.passed
&& review.passed
&& !hasHighFinding
&& review.qualityScore >= AUTOPILOT_QUALITY_THRESHOLD,
deterministic,
diagnostics: compactEditorialDiagnostics(diagnostics),
review,
runId,
qualityThreshold: AUTOPILOT_QUALITY_THRESHOLD,
};
});
}
export const __testing = {
assertEditorialDependenciesUnchanged,
assertEditorialPromptBudget,
assertEditorialSnapshotUnchanged,
castIntegrityBudgetChars,
compactEditorialDiagnostics,
diagnosticLines,
editorialDependencyFingerprint,
editorialPromptBudgetChars,
editorialPromptCharacterCount,
editorialFingerprint,
exactGraphIdContract,
finalizeEditorialOperation,
loadEditorialDependencies,
loomCastCharacterIds,
loomCastIntegrityReport,
renderEditorialPrompt,
renderLoomCastIntegrity,
sanitizeEvaluation,
sanitizePlaythroughReview,
seriesPlanDigest,
storyContext,
teleplayDigest,
withCompletePlaythroughDigest,
};