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 episodic continuity review.
*
* Deterministic, multi-vector continuity checks across an episode graph:
* - Visual entity bindings (characters, wardrobes, places, objects)
* - Graph convergence & temporal continuity source unambiguousness
* - Voice profile consistency & revision drift detection
* - Pronunciation anchor coverage for Universe terminology
* - Audio occupancy safety (no dialogue on hold loops, blocking effects)
* - Live interaction window readiness & protagonist presence safety
*
* Produces structured findings without automatic mutations.
*/
import { computeTopologicalNodeOrder } from './fableLoomProduction.js';
import {
resolveFableLoomProtagonistPresence,
validateAudioOccupancy,
} from './fableLoomPlayback.js';
import { characterIdentityPackReadiness } from './storyBible.js';
import { isNonBlankStr } from './textUtils.js';
export const CONTINUITY_CATEGORIES = Object.freeze(['visual', 'voice', 'playback', 'graph']);
export const CONTINUITY_CODES = Object.freeze({
MISSING_UNIVERSE_CHARACTER: 'MISSING_UNIVERSE_CHARACTER',
MISSING_UNIVERSE_PLACE: 'MISSING_UNIVERSE_PLACE',
MISSING_UNIVERSE_OBJECT: 'MISSING_UNIVERSE_OBJECT',
MISSING_WARDROBE_REFERENCE: 'MISSING_WARDROBE_REFERENCE',
WARDROBE_DRIFT: 'WARDROBE_DRIFT',
CANONICAL_PROTAGONIST_UNRESOLVED: 'CANONICAL_PROTAGONIST_UNRESOLVED',
CANONICAL_WARDROBE_UNRESOLVED: 'CANONICAL_WARDROBE_UNRESOLVED',
CANONICAL_IDENTITY_PACK_NOT_READY: 'CANONICAL_IDENTITY_PACK_NOT_READY',
PROTAGONIST_BINDING_MISMATCH: 'PROTAGONIST_BINDING_MISMATCH',
PROTAGONIST_VISUAL_BINDING_WHILE_OFFSCREEN: 'PROTAGONIST_VISUAL_BINDING_WHILE_OFFSCREEN',
CANONICAL_WARDROBE_DRIFT: 'CANONICAL_WARDROBE_DRIFT',
AMBIGUOUS_CONVERGENCE: 'AMBIGUOUS_CONVERGENCE',
VOICE_PROFILE_REVISION_DRIFT: 'VOICE_PROFILE_REVISION_DRIFT',
VOICE_ENGINE_DRIFT: 'VOICE_ENGINE_DRIFT',
NO_APPROVED_VOICE_PROFILE: 'NO_APPROVED_VOICE_PROFILE',
MISSING_PRONUNCIATION_ANCHOR: 'MISSING_PRONUNCIATION_ANCHOR',
HOLD_LOOP_HAS_DIALOGUE: 'HOLD_LOOP_HAS_DIALOGUE',
HOLD_LOOP_HAS_BLOCKING_EFFECTS: 'HOLD_LOOP_HAS_BLOCKING_EFFECTS',
HOLD_LOOP_HAS_CLIPPING: 'HOLD_LOOP_HAS_CLIPPING',
PROTAGONIST_ONSCREEN_INTERACTION: 'PROTAGONIST_ONSCREEN_INTERACTION',
INTERACTION_ON_ENDING_OR_CUT: 'INTERACTION_ON_ENDING_OR_CUT',
DISCONNECTED_INTERACTION_CHANNEL: 'DISCONNECTED_INTERACTION_CHANNEL',
UNREACHABLE_SCENE_CONTINUITY: 'UNREACHABLE_SCENE_CONTINUITY',
VOICE_MODEL_REVISION_DRIFT: 'VOICE_MODEL_REVISION_DRIFT',
VOICE_PROFILE_BINDING_MISMATCH: 'VOICE_PROFILE_BINDING_MISMATCH',
PRONUNCIATION_REVISION_DRIFT: 'PRONUNCIATION_REVISION_DRIFT',
});
const asArray = (value) => (Array.isArray(value) ? value : []);
/**
* Universe terminology (character names/aliases, places, objects) that scene
* prose may mention, plus the terms that already carry a pronunciation anchor.
*/
function collectUniversePronunciationLexicon(universe) {
const universeTerms = new Set();
const definedPronunciations = new Set();
if (!universe) return { universeTerms, definedPronunciations };
for (const char of asArray(universe.characters)) {
if (char.name) universeTerms.add(char.name.toLowerCase());
for (const alias of asArray(char.aliases)) universeTerms.add(alias.toLowerCase());
for (const p of asArray(char.voiceCanon?.pronunciations)) {
if (p.term) definedPronunciations.add(p.term.toLowerCase());
}
}
for (const place of asArray(universe.places)) {
if (place.name) universeTerms.add(place.name.toLowerCase());
}
for (const obj of asArray(universe.objects)) {
if (obj.name) universeTerms.add(obj.name.toLowerCase());
}
return { universeTerms, definedPronunciations };
}
function evaluateCanonicalProtagonist({ universe, canonicalProtagonistId, canonicalWardrobeId, push }) {
const canonicalProtagonist = canonicalProtagonistId && Array.isArray(universe?.characters)
? universe.characters.find((character) => character.id === canonicalProtagonistId)
: null;
if (canonicalProtagonistId && !universe) {
push({
category: 'visual',
severity: 'error',
code: CONTINUITY_CODES.CANONICAL_PROTAGONIST_UNRESOLVED,
message: `Canonical protagonist "${canonicalProtagonistId}" cannot be resolved because the linked Universe is unavailable.`,
remediation: 'Restore the linked Universe before reviewing or rendering character continuity.',
characterId: canonicalProtagonistId,
});
} else if (canonicalProtagonistId && !canonicalProtagonist) {
push({
category: 'visual',
severity: 'error',
code: CONTINUITY_CODES.CANONICAL_PROTAGONIST_UNRESOLVED,
message: `Canonical protagonist "${canonicalProtagonistId}" is not present in the linked Universe.`,
remediation: 'Choose an existing Universe character or restore the missing character.',
characterId: canonicalProtagonistId,
});
} else if (canonicalProtagonist && canonicalWardrobeId) {
const wardrobeExists = Array.isArray(canonicalProtagonist.wardrobes)
&& canonicalProtagonist.wardrobes.some((wardrobe) => wardrobe.id === canonicalWardrobeId);
if (!wardrobeExists) {
push({
category: 'visual',
severity: 'error',
code: CONTINUITY_CODES.CANONICAL_WARDROBE_UNRESOLVED,
message: `Canonical wardrobe "${canonicalWardrobeId}" is not present on protagonist "${canonicalProtagonistId}".`,
remediation: 'Choose a wardrobe from the protagonist character sheet or clear the stale reference.',
characterId: canonicalProtagonistId,
});
}
}
if (canonicalProtagonist) {
const identityReadiness = characterIdentityPackReadiness(canonicalProtagonist);
if (identityReadiness.status !== 'ready') {
push({
category: 'visual',
severity: 'warning',
code: CONTINUITY_CODES.CANONICAL_IDENTITY_PACK_NOT_READY,
message: `Canonical protagonist "${canonicalProtagonist.name || canonicalProtagonistId}" identity pack is ${identityReadiness.status}; canon-locked storyboard renders need approved neutral, profile, and full-body references.`,
remediation: 'Open the Universe character sheet and approve one neutral, profile, and full-body reference image.',
characterId: canonicalProtagonistId,
});
}
}
}
function evaluateGraphReachabilityAndConvergence({ nodeById, unreachableNodeIds, convergenceNodeIds, predecessorsByNodeId, push }) {
for (const nodeId of unreachableNodeIds) {
const node = nodeById.get(nodeId);
push({
category: 'graph',
severity: 'warning',
code: CONTINUITY_CODES.UNREACHABLE_SCENE_CONTINUITY,
message: `Scene "${node?.title || nodeId}" is unreachable from opening scene and will not be reached in story continuity.`,
remediation: 'Connect an incoming transition from a reachable scene or mark as opening scene.',
nodeId,
});
}
for (const nodeId of convergenceNodeIds) {
const node = nodeById.get(nodeId);
const preds = predecessorsByNodeId.get(nodeId) || [];
const explicitSource = node.visualCanon?.continuitySourceNodeId;
const hasValidSource = explicitSource && preds.some((pred) => pred.nodeId === explicitSource);
if (!hasValidSource) {
push({
category: 'graph',
severity: explicitSource ? 'error' : 'info',
code: CONTINUITY_CODES.AMBIGUOUS_CONVERGENCE,
message: explicitSource
? `Convergence scene "${node?.title || nodeId}" names a predecessor that is not one of its ${preds.length} incoming paths.`
: `Convergence scene "${node?.title || nodeId}" has ${preds.length} incoming paths without an explicit visual continuity source.`,
remediation: 'Set visualCanon.continuitySourceNodeId to one incoming predecessor to lock deterministic continuity.',
nodeId,
});
}
}
}
function evaluateCanonicalAndGraphContinuity({
universe, canonicalProtagonistId, canonicalWardrobeId, nodeById,
unreachableNodeIds, convergenceNodeIds, predecessorsByNodeId, push,
}) {
evaluateCanonicalProtagonist({ universe, canonicalProtagonistId, canonicalWardrobeId, push });
evaluateGraphReachabilityAndConvergence({
nodeById, unreachableNodeIds, convergenceNodeIds, predecessorsByNodeId, push,
});
}
/** Protagonist-specific visual bindings: off-screen leaks, interaction mismatch, wardrobe drift. */
function evaluateProtagonistVisualBindings({
node, loom, visualCanon, canonicalProtagonistId, canonicalWardrobeId,
interactionProtagonistId, sceneProtagonistIds, protagonistPresence, push,
}) {
const appearances = asArray(visualCanon.characterAppearances);
const protagonistAppearances = appearances.filter((appearance) => (
sceneProtagonistIds.has(appearance?.characterId)
));
if (protagonistPresence === 'offscreen' && protagonistAppearances.length) {
push({
category: 'visual',
severity: 'warning',
code: CONTINUITY_CODES.PROTAGONIST_VISUAL_BINDING_WHILE_OFFSCREEN,
message: `Scene "${node.title || node.id}" is marked off-screen for the protagonist but still declares a protagonist visual binding; the render compiler will omit it.`,
remediation: 'Remove the protagonist from this scene cast, or mark the beat on-screen if the audience should see them.',
nodeId: node.id,
characterId: interactionProtagonistId || canonicalProtagonistId,
});
}
if (canonicalProtagonistId && interactionProtagonistId
&& interactionProtagonistId !== canonicalProtagonistId) {
push({
category: 'playback',
severity: 'error',
code: CONTINUITY_CODES.PROTAGONIST_BINDING_MISMATCH,
message: `Live interaction in scene "${node.title || node.id}" binds protagonist "${interactionProtagonistId}" instead of the loom's canonical protagonist "${canonicalProtagonistId}".`,
remediation: 'Use the canonical protagonist selected in Story settings so voice and visual identity stay aligned.',
nodeId: node.id,
characterId: interactionProtagonistId,
});
}
if (canonicalProtagonistId && canonicalWardrobeId && protagonistPresence !== 'offscreen') {
for (const appearance of protagonistAppearances.filter(
(item) => item.characterId === canonicalProtagonistId,
)) {
if (appearance.wardrobeId && appearance.wardrobeId !== canonicalWardrobeId) {
push({
category: 'visual',
severity: loom.protagonistWardrobeLocked === true ? 'warning' : 'info',
code: CONTINUITY_CODES.CANONICAL_WARDROBE_DRIFT,
message: `Scene "${node.title || node.id}" selects wardrobe "${appearance.wardrobeId}" for the canonical protagonist instead of "${canonicalWardrobeId}".`,
remediation: loom.protagonistWardrobeLocked === true
? 'Keep the scene wardrobe on the locked canonical reference or change the loom wardrobe deliberately in Story settings.'
: 'Confirm the wardrobe change is intentional, or select the loom canonical wardrobe for this scene.',
nodeId: node.id,
characterId: canonicalProtagonistId,
});
}
}
}
}
/** Every character, wardrobe, place and object a scene binds must exist in the Universe. */
function evaluateUniverseEntityBindings({ node, universe, visualCanon, push }) {
for (const app of asArray(visualCanon.characterAppearances)) {
const charId = app.characterId;
const char = universe.characters?.find((c) => c.id === charId);
if (!char) {
push({
category: 'visual',
severity: 'error',
code: CONTINUITY_CODES.MISSING_UNIVERSE_CHARACTER,
message: `Bound character "${charId}" in scene "${node.title || node.id}" does not exist in Universe.`,
remediation: 'Rebind to an existing Universe character or create the character in Universe.',
nodeId: node.id,
characterId: charId,
});
} else if (app.wardrobeId) {
const wardrobeExists = Array.isArray(char.wardrobes) && char.wardrobes.some((w) => w.id === app.wardrobeId);
if (!wardrobeExists) {
push({
category: 'visual',
severity: 'warning',
code: CONTINUITY_CODES.MISSING_WARDROBE_REFERENCE,
message: `Bound wardrobe "${app.wardrobeId}" for character "${char.name || charId}" is not in Universe character wardrobes.`,
remediation: 'Select an approved wardrobe from Universe character sheet.',
nodeId: node.id,
characterId: charId,
});
}
}
}
if (visualCanon.placeId && !universe.places?.find((p) => p.id === visualCanon.placeId)) {
push({
category: 'visual',
severity: 'error',
code: CONTINUITY_CODES.MISSING_UNIVERSE_PLACE,
message: `Bound place "${visualCanon.placeId}" in scene "${node.title || node.id}" does not exist in Universe.`,
remediation: 'Rebind to an existing Universe location.',
nodeId: node.id,
});
}
for (const objId of asArray(visualCanon.objectIds)) {
if (!universe.objects?.find((o) => o.id === objId)) {
push({
category: 'visual',
severity: 'error',
code: CONTINUITY_CODES.MISSING_UNIVERSE_OBJECT,
message: `Bound object "${objId}" in scene "${node.title || node.id}" does not exist in Universe.`,
remediation: 'Rebind to an existing Universe object.',
nodeId: node.id,
});
}
}
}
function evaluateSceneVisualCanonBindings(args) {
evaluateProtagonistVisualBindings(args);
evaluateUniverseEntityBindings(args);
}
/** Adjacent-scene wardrobe change against the single (or explicitly chosen) predecessor. */
function evaluatePredecessorWardrobeContinuity({ node, visualCanon, predecessorsByNodeId, nodeById, push }) {
const preds = predecessorsByNodeId.get(node.id) || [];
const explicitSource = visualCanon.continuitySourceNodeId;
const continuityPreds = preds.length === 1
? preds
: (explicitSource ? preds.filter((pred) => pred.nodeId === explicitSource) : []);
if (continuityPreds.length !== 1) return;
const predNode = nodeById.get(continuityPreds[0].nodeId);
const predAppearances = asArray(predNode?.visualCanon?.characterAppearances);
const currentAppearances = asArray(visualCanon.characterAppearances);
if (!predAppearances.length || !currentAppearances.length) return;
for (const app of currentAppearances) {
const predApp = predAppearances.find((a) => a.characterId === app.characterId);
if (predApp && predApp.wardrobeId && app.wardrobeId && predApp.wardrobeId !== app.wardrobeId) {
push({
category: 'visual',
severity: 'info',
code: CONTINUITY_CODES.WARDROBE_DRIFT,
message: `Character "${app.characterId}" changes wardrobe from "${predApp.wardrobeId}" to "${app.wardrobeId}" across adjacent scenes.`,
remediation: 'Confirm wardrobe change is intentional in narrative continuity.',
nodeId: node.id,
characterId: app.characterId,
});
}
}
}
/** Drift between one asset's recorded voice and the installed local voice profile. */
function evaluateInstalledProfileDrift({ node, charId, voiceInfo, matchingProfile, push }) {
if (matchingProfile.binding?.characterId && matchingProfile.binding.characterId !== charId) {
push({
category: 'voice',
severity: 'error',
code: CONTINUITY_CODES.VOICE_PROFILE_BINDING_MISMATCH,
message: `Voice profile "${voiceInfo.profileId}" is bound to a different character than scene provenance expects.`,
remediation: 'Select the voice profile bound to this scene character and re-render the dialogue asset.',
nodeId: node.id,
characterId: charId,
});
}
if (Number.isFinite(voiceInfo.profileVersion) && matchingProfile.version !== voiceInfo.profileVersion) {
push({
category: 'voice',
severity: 'warning',
code: CONTINUITY_CODES.VOICE_PROFILE_REVISION_DRIFT,
message: `Character "${charId}" audio uses voice profile revision ${voiceInfo.profileVersion}, while the installed profile is revision ${matchingProfile.version}.`,
remediation: 'Re-render dialogue assets with the installed approved voice profile revision.',
nodeId: node.id,
characterId: charId,
});
}
if (voiceInfo.engine && matchingProfile.engine && voiceInfo.engine !== matchingProfile.engine) {
push({
category: 'voice',
severity: 'warning',
code: CONTINUITY_CODES.VOICE_ENGINE_DRIFT,
message: `Character "${charId}" audio uses engine "${voiceInfo.engine}", while the installed profile uses "${matchingProfile.engine}".`,
remediation: 'Re-render dialogue with the approved profile engine.',
nodeId: node.id,
characterId: charId,
});
}
if (voiceInfo.modelRevision && matchingProfile.modelRevision
&& voiceInfo.modelRevision !== matchingProfile.modelRevision) {
push({
category: 'voice',
severity: 'warning',
code: CONTINUITY_CODES.VOICE_MODEL_REVISION_DRIFT,
message: `Character "${charId}" audio uses model revision "${voiceInfo.modelRevision}", while the installed profile uses "${matchingProfile.modelRevision}".`,
remediation: 'Re-render dialogue with the model revision recorded by the approved profile.',
nodeId: node.id,
characterId: charId,
});
}
}
/**
* Records one asset's voice revision for the episode-wide drift check. The
* label is display-only (it appears verbatim in drift messages); drift is
* decided from the structured fields.
*/
function recordVoiceRevision(characterVoiceRevisions, charId, voiceInfo) {
const profileRevision = `${voiceInfo.profileId || 'default'}@v${voiceInfo.profileVersion || 1}`;
const engine = voiceInfo.engine || 'preset';
const modelRevision = voiceInfo.modelRevision || 'unknown';
const label = `${profileRevision} (${engine}:${modelRevision})`;
if (!characterVoiceRevisions.has(charId)) characterVoiceRevisions.set(charId, new Map());
characterVoiceRevisions.get(charId).set(label, { label, profileRevision, engine, modelRevision });
}
function evaluateCharacterVoiceProvenance({
node, universe, localVoiceProfiles, visualCharacterIds, charProv, characterVoiceRevisions, push,
}) {
const charId = charProv.characterId;
const voiceInfo = charProv.voice;
if (charId && visualCharacterIds.size > 0 && !visualCharacterIds.has(charId)) {
push({
category: 'voice',
severity: 'error',
code: CONTINUITY_CODES.VOICE_PROFILE_BINDING_MISMATCH,
message: `Voice provenance for character "${charId}" is not bound to a character visible in scene "${node.title || node.id}".`,
remediation: 'Re-render the asset with the scene character binding or correct the voice binding.',
nodeId: node.id,
characterId: charId,
});
}
if (!charId || !voiceInfo) return;
recordVoiceRevision(characterVoiceRevisions, charId, voiceInfo);
const canonCharacter = universe?.characters?.find((character) => character.id === charId);
const pronunciationRevision = Number.isFinite(voiceInfo.pronunciationRevision)
? voiceInfo.pronunciationRevision
: null;
if (pronunciationRevision !== null
&& Number.isFinite(canonCharacter?.voiceCanon?.version)
&& pronunciationRevision !== canonCharacter.voiceCanon.version) {
push({
category: 'voice',
severity: 'warning',
code: CONTINUITY_CODES.PRONUNCIATION_REVISION_DRIFT,
message: `Character "${charId}" audio uses pronunciation revision ${pronunciationRevision}, but the current Universe voice canon is revision ${canonCharacter.voiceCanon.version}.`,
remediation: 'Re-render dialogue after confirming the current pronunciation anchors.',
nodeId: node.id,
characterId: charId,
});
}
const matchingProfile = localVoiceProfiles?.find((profile) => profile.id === voiceInfo.profileId);
if (matchingProfile) {
evaluateInstalledProfileDrift({ node, charId, voiceInfo, matchingProfile, push });
}
}
/** Voice provenance, Voice Lab approval for live interaction, and pronunciation anchors in prose. */
function evaluateNodeVoiceContinuity({
node, universe, localVoiceProfiles, visualCanon, interaction, assets,
universeTerms, definedPronunciations, characterVoiceRevisions, push,
}) {
if (Array.isArray(assets?.provenance?.characters)) {
const visualCharacterIds = new Set(
asArray(visualCanon.characterAppearances)
.map((appearance) => appearance.characterId)
.filter(Boolean),
);
for (const charProv of assets.provenance.characters) {
evaluateCharacterVoiceProvenance({
node, universe, localVoiceProfiles, visualCharacterIds, charProv, characterVoiceRevisions, push,
});
}
}
if (interaction.enabled && interaction.protagonistCharacterId) {
const charId = interaction.protagonistCharacterId;
const approvedProfile = localVoiceProfiles?.find(
(p) => p.binding?.characterId === charId && p.approval?.status === 'approved',
);
if (!approvedProfile) {
push({
category: 'voice',
severity: 'warning',
code: CONTINUITY_CODES.NO_APPROVED_VOICE_PROFILE,
message: `Live interaction protagonist "${charId}" has no approved local voice profile in Voice Lab.`,
remediation: 'Create and approve a local voice profile for this character in Voice Lab.',
nodeId: node.id,
characterId: charId,
});
}
}
const sceneText = `${node.prose || ''} ${node.title || ''}`.toLowerCase();
for (const term of universeTerms) {
if (term.length >= 4 && sceneText.includes(term) && !definedPronunciations.has(term)) {
push({
category: 'voice',
severity: 'info',
code: CONTINUITY_CODES.MISSING_PRONUNCIATION_ANCHOR,
message: `Universe term "${term}" appears in scene dialogue/prose without a defined pronunciation anchor.`,
remediation: 'Add a pronunciation guide for this term in Universe voiceCanon.pronunciations.',
nodeId: node.id,
});
}
}
}
function evaluateHoldLoopAudio({ node, assets, push }) {
if (!Array.isArray(assets.holdLoopVideoHistoryIds)) return;
for (const holdId of assets.holdLoopVideoHistoryIds) {
const occ = assets.audioOccupancy?.[holdId];
if (!occ) continue;
const validated = validateAudioOccupancy(occ);
if (validated.characterDialogue.length > 0) {
push({
category: 'playback',
severity: 'error',
code: CONTINUITY_CODES.HOLD_LOOP_HAS_DIALOGUE,
message: `Hold loop "${holdId}" in scene "${node.title || node.id}" contains rendered dialogue and cannot be used for live interaction.`,
remediation: 'Remove dialogue from hold loop or render as separate entry clip.',
nodeId: node.id,
assetId: holdId,
});
}
if (validated.effects.some((e) => e.blocking)) {
push({
category: 'playback',
severity: 'warning',
code: CONTINUITY_CODES.HOLD_LOOP_HAS_BLOCKING_EFFECTS,
message: `Hold loop "${holdId}" contains author-marked voice-blocking sound effects.`,
remediation: 'Unmark blocking flag or adjust effect timing.',
nodeId: node.id,
assetId: holdId,
});
}
if (validated.clipping) {
push({
category: 'playback',
severity: 'error',
code: CONTINUITY_CODES.HOLD_LOOP_HAS_CLIPPING,
message: `Hold loop "${holdId}" contains clipped audio${validated.peakDb !== undefined ? ` (peak ${validated.peakDb} dBFS)` : ''}.`,
remediation: 'Remaster the hold loop below digital full scale before enabling hosted interaction.',
nodeId: node.id,
assetId: holdId,
});
}
}
}
function evaluateLiveInteractionSafety({ node, loom, interaction, push }) {
if (!interaction.enabled) return;
if (interaction.protagonistPresence === 'onscreen') {
push({
category: 'playback',
severity: 'warning',
code: CONTINUITY_CODES.PROTAGONIST_ONSCREEN_INTERACTION,
message: `Scene "${node.title || node.id}" has live voice enabled with onscreen protagonist presence.`,
remediation: 'Change protagonist presence to off-screen for seamless live voice conversation.',
nodeId: node.id,
});
}
if (node.isEnding || node.playbackMode === 'cut') {
push({
category: 'playback',
severity: 'error',
code: CONTINUITY_CODES.INTERACTION_ON_ENDING_OR_CUT,
message: `Scene "${node.title || node.id}" has live interaction enabled on an ending or automatic cut scene.`,
remediation: 'Disable live interaction on this scene or change playbackMode to decision.',
nodeId: node.id,
});
}
if (loom?.participationMode === 'helper' && node.audienceConnection !== 'connected') {
push({
category: 'playback',
severity: 'error',
code: CONTINUITY_CODES.DISCONNECTED_INTERACTION_CHANNEL,
message: `Scene "${node.title || node.id}" has live voice enabled while audience communication channel is disconnected.`,
remediation: 'Set audience connection to connected or disable live interaction.',
nodeId: node.id,
});
}
}
function evaluateNodePlaybackContinuity({ node, loom, interaction, assets, push }) {
evaluateHoldLoopAudio({ node, assets, push });
evaluateLiveInteractionSafety({ node, loom, interaction, push });
}
/** Cross-scene drift: one character rendered with several profile revisions, engines or model revisions. */
function evaluateEpisodeVoiceDrift(characterVoiceRevisions, push) {
for (const [charId, revMap] of characterVoiceRevisions.entries()) {
const records = Array.from(revMap.values());
const profileRevisions = new Set(records.map((record) => record.profileRevision));
const engines = new Set(records.map((record) => record.engine));
const modelRevisions = new Set(records.map((record) => record.modelRevision));
if (profileRevisions.size > 1) {
push({
category: 'voice',
severity: 'warning',
code: CONTINUITY_CODES.VOICE_PROFILE_REVISION_DRIFT,
message: `Character "${charId}" has assets rendered with different voice profile revisions across scenes (${records.map((record) => record.label).join(', ')}).`,
remediation: 'Re-render dialogue assets with the latest approved voice profile for consistent character voice.',
characterId: charId,
});
}
if (engines.size > 1) {
push({
category: 'voice',
severity: 'warning',
code: CONTINUITY_CODES.VOICE_ENGINE_DRIFT,
message: `Character "${charId}" has assets rendered with different voice engines across scenes (${Array.from(engines).join(', ')}).`,
remediation: 'Re-render dialogue assets with one approved voice engine for the episode.',
characterId: charId,
});
}
if (modelRevisions.size > 1) {
push({
category: 'voice',
severity: 'warning',
code: CONTINUITY_CODES.VOICE_MODEL_REVISION_DRIFT,
message: `Character "${charId}" has assets rendered with different voice model revisions across scenes (${Array.from(modelRevisions).join(', ')}).`,
remediation: 'Re-render dialogue assets with one recorded model revision for the episode.',
characterId: charId,
});
}
}
}
/**
* Run comprehensive episodic continuity review.
* Pure deterministic rule evaluation — NO unsolicited AI calls.
*
* Finding ids are assigned in emission order, so the evaluator sequence below
* is part of the output contract.
*/
export function analyzeEpisodeContinuity({
loom = null,
episode = null,
universe = null,
localVoiceProfiles = [],
} = {}) {
const findings = [];
const push = ({ category, severity, code, message, remediation, nodeId = null, characterId = null, assetId = null }) => {
findings.push({
id: `finding-${findings.length + 1}`,
category,
severity, // 'error' | 'warning' | 'info'
code,
message,
remediation,
...(nodeId ? { nodeId } : {}),
...(characterId ? { characterId } : {}),
...(assetId ? { assetId } : {}),
});
};
const nodes = Array.isArray(episode?.nodes) ? episode.nodes : [];
const nodeById = new Map(nodes.map((n) => [n.id, n]));
const {
orderedNodes,
predecessorsByNodeId,
convergenceNodeIds,
unreachableNodeIds,
} = computeTopologicalNodeOrder(episode);
// characterId -> Map<label, structured voice revision> seen across the episode
const characterVoiceRevisions = new Map();
const { universeTerms, definedPronunciations } = collectUniversePronunciationLexicon(universe);
const canonicalProtagonistId = isNonBlankStr(loom?.protagonistCharacterId)
? loom.protagonistCharacterId
: null;
const canonicalWardrobeId = isNonBlankStr(loom?.protagonistWardrobeId)
? loom.protagonistWardrobeId
: null;
evaluateCanonicalAndGraphContinuity({
universe, canonicalProtagonistId, canonicalWardrobeId, nodeById,
unreachableNodeIds, convergenceNodeIds, predecessorsByNodeId, push,
});
for (const node of orderedNodes) {
const visualCanon = node.visualCanon || {};
const interaction = node.interactionWindow || {};
const assets = node.playbackAssets || {};
const interactionProtagonistId = isNonBlankStr(interaction.protagonistCharacterId)
? interaction.protagonistCharacterId
: null;
const sceneProtagonistIds = new Set(
[canonicalProtagonistId, interactionProtagonistId].filter(Boolean),
);
const protagonistPresence = resolveFableLoomProtagonistPresence(node, loom);
if (universe) {
evaluateSceneVisualCanonBindings({
node, loom, universe, visualCanon, canonicalProtagonistId, canonicalWardrobeId,
interactionProtagonistId, sceneProtagonistIds, protagonistPresence, push,
});
}
evaluatePredecessorWardrobeContinuity({ node, visualCanon, predecessorsByNodeId, nodeById, push });
evaluateNodeVoiceContinuity({
node, universe, localVoiceProfiles, visualCanon, interaction, assets,
universeTerms, definedPronunciations, characterVoiceRevisions, push,
});
evaluateNodePlaybackContinuity({ node, loom, interaction, assets, push });
}
evaluateEpisodeVoiceDrift(characterVoiceRevisions, push);
const errorCount = findings.filter((f) => f.severity === 'error').length;
const warningCount = findings.filter((f) => f.severity === 'warning').length;
const infoCount = findings.filter((f) => f.severity === 'info').length;
const categoryCounts = {
visual: findings.filter((f) => f.category === 'visual').length,
voice: findings.filter((f) => f.category === 'voice').length,
playback: findings.filter((f) => f.category === 'playback').length,
graph: findings.filter((f) => f.category === 'graph').length,
};
return {
passed: errorCount === 0,
summary: {
totalFindings: findings.length,
errors: errorCount,
warnings: warningCount,
info: infoCount,
categoryCounts,
},
nodesEvaluated: orderedNodes.length,
findings,
};
}