Skip to content

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

28.8 KB
Raw Blame
/**
 * FableLoom node playback semantics shared by persistence, prompts, and UI.
 *
 * Supports entry clips, deterministic hold loops, transition exit clips,
 * live interaction windows, audio-occupancy manifests, and production
 * readiness inspection. Legacy nodes default to decision mode and single
 * videoHistoryId playback.
 */

import { LOOM_LIMITS } from './fableLoomLimits.js';
import { isNonBlankStr, trimTo } from './textUtils.js';

// Version of docs/features/fableloom-runtime-v1.md, independent of package schema versions.
export const FABLELOOM_RUNTIME_VERSION = '1.0.0';

export const FABLELOOM_PLAYBACK_MODES = Object.freeze(['cut', 'decision']);
export const FABLELOOM_PLAYBACK_MODE_DEFAULT = 'decision';

export const FABLELOOM_PLAYBACK_PHASES = Object.freeze(['entry', 'hold', 'exit', 'ended']);

export const FABLELOOM_PROTAGONIST_PRESENCE = Object.freeze(['offscreen', 'onscreen']);
export const FABLELOOM_PROTAGONIST_PRESENCE_DEFAULT = 'offscreen';

/**
 * Resolve the visual presence contract for one scene. Explicit live-window
 * presence wins because hosted playback must obey that safety setting. Helper
 * decision scenes default to an off-screen audience conversation; a loom with
 * a canonical protagonist defaults other scenes to on-screen until the author
 * marks them otherwise.
 */
export const resolveFableLoomProtagonistPresence = (node, loom = null) => {
  if (node?.interactionWindow?.enabled
    && FABLELOOM_PROTAGONIST_PRESENCE.includes(node.interactionWindow.protagonistPresence)) {
    return node.interactionWindow.protagonistPresence;
  }
  if (FABLELOOM_PROTAGONIST_PRESENCE.includes(node?.protagonistPresence)) {
    return node.protagonistPresence;
  }
  if (loom?.participationMode === 'helper'
    && node?.playbackMode === 'decision'
    && node?.audienceConnection === 'connected') {
    return 'offscreen';
  }
  return loom?.protagonistCharacterId ? 'onscreen' : null;
};

export const FABLELOOM_AUDIO_TARGETS = Object.freeze(['host', 'audience']);
export const FABLELOOM_AUDIO_TARGET_DEFAULT = 'host';

export const FABLELOOM_HOLD_ROTATION_MODES = Object.freeze(['deterministic', 'shuffle', 'sequential']);
export const FABLELOOM_HOLD_ROTATION_MODE_DEFAULT = 'deterministic';

export const isFableLoomPlaybackMode = (value) => FABLELOOM_PLAYBACK_MODES.includes(value);
export const asFableLoomPlaybackMode = (value) => (
  isFableLoomPlaybackMode(value) ? value : FABLELOOM_PLAYBACK_MODE_DEFAULT
);

export const isSafeVideoHistoryId = (value) =>
  typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(value);

const clamp = (v, min, max) => Math.max(min, Math.min(max, v));
const SAFE_PRODUCTION_PARAMETER_KEYS = new Set([
  'width', 'height', 'numFrames', 'fps', 'steps', 'guidance', 'guidanceScale',
  'seed', 'imageStrength', 'quantize', 'effort', 'mode', 'videoMode',
  'aspectRatio', 'disableAudio', 'tiling',
]);

/**
 * Sanitize an audio interval (dialogue, music, or effect).
 */
export function sanitizeAudioInterval(raw) {
  if (!raw || typeof raw !== 'object') return null;
  const startMs = Number.isFinite(raw.startMs) && raw.startMs >= 0 ? Math.round(raw.startMs) : 0;
  const endMs = Number.isFinite(raw.endMs) && raw.endMs >= startMs ? Math.round(raw.endMs) : startMs;
  return {
    startMs,
    endMs,
    ...(isNonBlankStr(raw.characterId) ? { characterId: trimTo(raw.characterId, 80) } : {}),
    ...(isNonBlankStr(raw.speaker) ? { speaker: trimTo(raw.speaker, 100) } : {}),
    ...(raw.blocking === true ? { blocking: true } : {}),
    ...(isNonBlankStr(raw.name) ? { name: trimTo(raw.name, 100) } : {}),
  };
}

/**
 * Sanitize and validate an audio occupancy manifest.
 * `safeForLiveVoice` is strictly computed/enforced:
 * - A hold asset containing character dialogue CANNOT open a live voice window.
 * - An asset with author-marked blocking effects CANNOT open a live voice window.
 */
export function validateAudioOccupancy(raw) {
  if (!raw || typeof raw !== 'object') {
    return {
      durationMs: 0,
      characterDialogue: [],
      music: [],
      effects: [],
      safeForLiveVoice: true,
    };
  }

  const durationMs = Number.isFinite(raw.durationMs) && raw.durationMs >= 0
    ? Math.round(raw.durationMs)
    : 0;

  const characterDialogue = (Array.isArray(raw.characterDialogue) ? raw.characterDialogue : [])
    .map(sanitizeAudioInterval)
    .filter(Boolean)
    .slice(0, LOOM_LIMITS.AUDIO_INTERVALS_MAX || 50);

  const music = (Array.isArray(raw.music) ? raw.music : [])
    .map(sanitizeAudioInterval)
    .filter(Boolean)
    .slice(0, LOOM_LIMITS.AUDIO_INTERVALS_MAX || 50);

  const effects = (Array.isArray(raw.effects) ? raw.effects : [])
    .map(sanitizeAudioInterval)
    .filter(Boolean)
    .slice(0, LOOM_LIMITS.AUDIO_INTERVALS_MAX || 50);

  const hasCharacterDialogue = characterDialogue.length > 0;
  const hasBlockingEffects = effects.some((e) => e.blocking === true);
  const peakDb = Number.isFinite(raw.truePeakDb)
    ? raw.truePeakDb
    : (Number.isFinite(raw.peakDb) ? raw.peakDb : null);
  const clipping = raw.clipping === true
    || raw.clipped === true
    || raw.clippingDetected === true
    || (peakDb !== null && peakDb > 0);

  // safeForLiveVoice is false if any dialogue, blocking effects, or clipping
  // exists. A caller cannot override these derived safety fields with a stale
  // `safeForLiveVoice: true` value from an older manifest.
  const safeForLiveVoice = !hasCharacterDialogue && !hasBlockingEffects && !clipping;

  return {
    durationMs,
    characterDialogue,
    music,
    effects,
    clipping,
    ...(peakDb !== null ? { peakDb } : {}),
    safeForLiveVoice,
  };
}

export const sanitizeAudioOccupancy = validateAudioOccupancy;

/**
 * Sanitize the path-free visual conditioning manifest attached to a scene or
 * typed playback asset. The playback module owns this shape so the node
 * sanitizer can safely handle one manifest per rendered clip without a
 * records-module import cycle.
 */
export function sanitizeVisualConditioning(raw) {
  if (!raw || typeof raw !== 'object' || raw.version !== 1) return null;
  const list = (value, max) => (Array.isArray(value) ? value.slice(0, max) : []);
  const nullableRef = (value) => (isNonBlankStr(value) ? trimTo(value, LOOM_LIMITS.REF_ID_MAX) : null);
  const capability = raw.capability && typeof raw.capability === 'object' ? raw.capability : {};
  const bindings = raw.bindings && typeof raw.bindings === 'object' ? raw.bindings : {};
  const protagonistBinding = bindings.protagonist && typeof bindings.protagonist === 'object'
    && nullableRef(bindings.protagonist.characterId)
    ? {
      characterId: nullableRef(bindings.protagonist.characterId),
      wardrobeId: nullableRef(bindings.protagonist.wardrobeId),
      presence: FABLELOOM_PROTAGONIST_PRESENCE.includes(bindings.protagonist.presence)
        ? bindings.protagonist.presence
        : null,
    }
    : null;
  const productionParameters = raw.render?.parameters && typeof raw.render.parameters === 'object'
    ? Object.fromEntries(Object.entries(raw.render.parameters).flatMap(([key, value]) => {
      if (!SAFE_PRODUCTION_PARAMETER_KEYS.has(key)) return [];
      if (typeof value === 'number' && Number.isFinite(value)) return [[key.slice(0, 40), value]];
      if (typeof value === 'boolean') return [[key.slice(0, 40), value]];
      if (isNonBlankStr(value)) return [[key.slice(0, 40), trimTo(value, 200)]];
      return [];
    }))
    : {};
  return {
    version: 1,
    compilerVersion: trimTo(raw.compilerVersion, 40),
    status: ['locked', 'draft', 'degraded'].includes(raw.status) ? raw.status : 'degraded',
    universeId: nullableRef(raw.universeId),
    capability: {
      version: Number.isInteger(capability.version) ? capability.version : 1,
      kind: capability.kind === 'video' ? 'video' : 'image',
      backend: trimTo(capability.backend, 40),
      modelId: nullableRef(capability.modelId),
      modelRevision: nullableRef(capability.modelRevision),
      referenceRoles: list(capability.referenceRoles, 24)
        .map((item) => trimTo(item, 64)).filter(Boolean),
      referenceBudget: Number.isInteger(capability.referenceBudget)
        ? Math.max(0, Math.min(24, capability.referenceBudget)) : 0,
      supportsLora: capability.supportsLora === true,
      loraCompatKey: nullableRef(capability.loraCompatKey),
      loraBudget: Number.isInteger(capability.loraBudget)
        ? Math.max(0, Math.min(8, capability.loraBudget)) : 0,
      multiCharacterPreservation: capability.multiCharacterPreservation === true,
      ...(capability.kind === 'video' ? {
        firstFrame: capability.firstFrame === true,
        lastFrame: capability.lastFrame === true,
        extension: capability.extension === true,
      } : {}),
    },
    bindings: {
      inferred: bindings.inferred === true,
      characterAppearances: list(bindings.characterAppearances, LOOM_LIMITS.VISUAL_BINDINGS_MAX)
        .filter((item) => item && typeof item === 'object' && nullableRef(item.characterId))
        .map((item) => ({
          characterId: nullableRef(item.characterId),
          wardrobeId: nullableRef(item.wardrobeId),
          expression: trimTo(item.expression, LOOM_LIMITS.VISUAL_NOTE_MAX),
          continuityNotes: trimTo(item.continuityNotes, LOOM_LIMITS.VISUAL_NOTE_MAX),
        })),
      placeId: nullableRef(bindings.placeId),
      objectIds: list(bindings.objectIds, LOOM_LIMITS.VISUAL_BINDINGS_MAX)
        .map(nullableRef).filter(Boolean),
      ...(protagonistBinding ? { protagonist: protagonistBinding } : {}),
    },
    assets: list(raw.assets, LOOM_LIMITS.VISUAL_PROVENANCE_ASSETS_MAX)
      .filter((item) => item && typeof item === 'object')
      .map((item) => ({
        role: trimTo(item.role, 64), bindingId: nullableRef(item.bindingId),
        required: item.required === true, filename: trimTo(item.filename, 256),
      })),
    adapters: list(raw.adapters, 8)
      .filter((item) => item && typeof item === 'object')
      .map((item) => ({
        characterId: nullableRef(item.characterId), filename: trimTo(item.filename, 256),
        scale: Number.isFinite(item.scale) ? Math.max(0, Math.min(2, item.scale)) : 1,
        sha256: typeof item.sha256 === 'string' && /^[a-f0-9]{64}$/i.test(item.sha256) ? item.sha256 : null,
      })),
    omitted: list(raw.omitted, LOOM_LIMITS.VISUAL_PROVENANCE_MESSAGES_MAX)
      .filter((item) => item && typeof item === 'object')
      .map((item) => ({
        role: trimTo(item.role, 64), bindingId: nullableRef(item.bindingId),
        reason: trimTo(item.reason, 80),
        ...(item.filename ? { filename: trimTo(item.filename, 256) } : {}),
      })),
    warnings: (Array.isArray(raw.warnings) ? raw.warnings : [])
      .map((item) => trimTo(item, LOOM_LIMITS.VISUAL_NOTE_MAX)).filter(Boolean)
      .slice(0, LOOM_LIMITS.VISUAL_PROVENANCE_MESSAGES_MAX),
    temporalSourceNodeId: nullableRef(raw.temporalSourceNodeId),
    ...(typeof raw.compiledPrompt === 'string' ? { compiledPrompt: trimTo(raw.compiledPrompt, 8000) } : {}),
    ...(typeof raw.compiledNegativePrompt === 'string' ? { compiledNegativePrompt: trimTo(raw.compiledNegativePrompt, 8000) } : {}),
    referenceImageStrengths: (Array.isArray(raw.referenceImageStrengths) ? raw.referenceImageStrengths : [])
      .filter((value) => Number.isFinite(value))
      .map((value) => Math.max(0, Math.min(1, value)))
      .slice(0, LOOM_LIMITS.VISUAL_PROVENANCE_ASSETS_MAX),
    ...(isNonBlankStr(raw.assetId) ? { assetId: nullableRef(raw.assetId) } : {}),
    ...(raw.render && typeof raw.render === 'object' ? {
      render: {
        provider: trimTo(raw.render.provider, 40),
        modelId: nullableRef(raw.render.modelId),
        modelRevision: nullableRef(raw.render.modelRevision),
        parameters: productionParameters,
      },
    } : {}),
    compiledAt: isNonBlankStr(raw.compiledAt) ? raw.compiledAt : null,
  };
}

/**
 * Check if a manifest or asset is safe for live voice.
 */
export function isAssetSafeForLiveVoice(manifest) {
  if (!manifest) return true;
  return validateAudioOccupancy(manifest).safeForLiveVoice === true;
}

/**
 * Transport-neutral live-input admission for runtime v1. A missing playback
 * mode retains the persisted legacy decision default; an explicit cut never
 * opens a conversation even if a stale player reports the hold phase.
 */
export function evaluateFableLoomLiveInput({ node, phase, asset } = {}) {
  if (!node) return { allowed: false, reason: 'NODE_NOT_FOUND' };
  if (node.isEnding) return { allowed: false, reason: 'STORY_ENDED' };
  if (node.audienceConnection !== 'connected') {
    return { allowed: false, reason: 'AUDIENCE_DISCONNECTED' };
  }
  if (asFableLoomPlaybackMode(node.playbackMode) !== 'decision') {
    return { allowed: false, reason: 'PLAYBACK_NOT_DECISION' };
  }
  if (phase !== 'hold') {
    return { allowed: false, reason: 'PLAYBACK_NOT_IN_HOLD_PHASE' };
  }
  if (resolveFableLoomProtagonistPresence(node) === 'onscreen') {
    return { allowed: false, reason: 'PROTAGONIST_ONSCREEN' };
  }
  if (asset) {
    const occupancy = asset.manifest || asset.audioOccupancy || asset;
    if (asset.safeForLiveVoice === false
      || occupancy.safeForLiveVoice === false || !isAssetSafeForLiveVoice(occupancy)) {
      return { allowed: false, reason: 'HOLD_ASSET_OCCUPIED_BY_DIALOGUE' };
    }
  }
  return { allowed: true };
}

/**
 * Helper to build an audio occupancy manifest.
 */
export function createAudioOccupancyManifest({
  durationMs = 0,
  characterDialogue = [],
  music = [],
  effects = [],
} = {}) {
  return validateAudioOccupancy({ durationMs, characterDialogue, music, effects });
}

/**
 * Mux audio tracks into a single unified occupancy manifest.
 */
export function muxAudioTracks({
  durationMs = 0,
  characterDialogue = [],
  music = [],
  effects = [],
} = {}) {
  const manifest = createAudioOccupancyManifest({ durationMs, characterDialogue, music, effects });
  return {
    manifest,
    totalDialogueMs: manifest.characterDialogue.reduce((sum, d) => sum + Math.max(0, d.endMs - d.startMs), 0),
    totalMusicMs: manifest.music.reduce((sum, m) => sum + Math.max(0, m.endMs - m.startMs), 0),
    totalEffectsMs: manifest.effects.reduce((sum, e) => sum + Math.max(0, e.endMs - e.startMs), 0),
    safeForLiveVoice: manifest.safeForLiveVoice,
  };
}

/**
 * Compute ducking and audio level adjustments when live voice or dialogue is active.
 */
export function computeAudioMix({
  assetManifest = null,
  liveVoiceActive = false,
  baseDuckDb = LOOM_LIMITS.AMBIENT_DUCK_DB_DEFAULT || -8,
  currentTimeMs = 0,
} = {}) {
  const manifest = validateAudioOccupancy(assetManifest);
  const duckDb = clamp(
    Number.isFinite(baseDuckDb) ? baseDuckDb : (LOOM_LIMITS.AMBIENT_DUCK_DB_DEFAULT || -8),
    LOOM_LIMITS.AMBIENT_DUCK_DB_MIN || -60,
    LOOM_LIMITS.AMBIENT_DUCK_DB_MAX || 0,
  );

  const duckFactor = liveVoiceActive ? 10 ** (duckDb / 20) : 1.0;

  const dialogueActive = manifest.characterDialogue.some(
    (d) => currentTimeMs >= d.startMs && currentTimeMs <= d.endMs,
  );

  const blockingEffectActive = manifest.effects.some(
    (e) => e.blocking && currentTimeMs >= e.startMs && currentTimeMs <= e.endMs,
  );

  return {
    duckDb: liveVoiceActive ? duckDb : 0,
    duckFactor: Math.round(duckFactor * 1000) / 1000,
    musicLevel: duckFactor,
    effectsLevel: blockingEffectActive ? 1.0 : duckFactor,
    dialogueActive,
    blockingEffectActive,
    safeForLiveVoice: manifest.safeForLiveVoice,
    canOpenLiveVoice: manifest.safeForLiveVoice && !dialogueActive && !blockingEffectActive,
  };
}

/**
 * Sanitize asset provenance envelope.
 */
export function sanitizeProvenance(raw) {
  if (!raw || typeof raw !== 'object') return null;
  return {
    version: Number.isFinite(raw.version) ? Math.max(1, Math.round(raw.version)) : 1,
    loomId: isNonBlankStr(raw.loomId) ? trimTo(raw.loomId, 80) : null,
    episodeId: isNonBlankStr(raw.episodeId) ? trimTo(raw.episodeId, 80) : null,
    nodeId: isNonBlankStr(raw.nodeId) ? trimTo(raw.nodeId, 80) : null,
    universeId: isNonBlankStr(raw.universeId) ? trimTo(raw.universeId, 80) : null,
    characters: (Array.isArray(raw.characters) ? raw.characters : [])
      .filter((c) => c && typeof c === 'object' && isNonBlankStr(c.characterId))
      .slice(0, LOOM_LIMITS.PROVENANCE_CHARACTERS_MAX || 12)
      .map((c) => ({
        characterId: trimTo(c.characterId, 80),
        wardrobeId: isNonBlankStr(c.wardrobeId) ? trimTo(c.wardrobeId, 80) : null,
        identityAssets: Array.isArray(c.identityAssets) ? c.identityAssets.filter(isNonBlankStr).slice(0, 5) : [],
        lora: c.lora && typeof c.lora === 'object' ? {
          filename: trimTo(c.lora.filename, 200),
          sha256: trimTo(c.lora.sha256, 128),
          scale: Number.isFinite(c.lora.scale) ? c.lora.scale : 1.0,
        } : null,
        voice: c.voice && typeof c.voice === 'object' ? {
          profileId: trimTo(c.voice.profileId, 80),
          profileVersion: Number.isFinite(c.voice.profileVersion) ? Math.round(c.voice.profileVersion) : 1,
          engine: trimTo(c.voice.engine, 80),
          modelRevision: trimTo(c.voice.modelRevision, 120),
          pronunciationRevision: Number.isFinite(c.voice.pronunciationRevision)
            ? Math.max(1, Math.round(c.voice.pronunciationRevision))
            : null,
        } : null,
      })),
    visualConditioningVersion: Number.isFinite(raw.visualConditioningVersion) ? raw.visualConditioningVersion : 1,
    promptCompilerVersion: Number.isFinite(raw.promptCompilerVersion) ? raw.promptCompilerVersion : 1,
    audioMixVersion: Number.isFinite(raw.audioMixVersion) ? raw.audioMixVersion : 1,
    omitted: Array.isArray(raw.omitted) ? raw.omitted.filter(isNonBlankStr).slice(0, 20) : [],
    warnings: Array.isArray(raw.warnings) ? raw.warnings.filter(isNonBlankStr).slice(0, 20) : [],
  };
}

/**
 * Sanitize playbackAssets node field.
 */
export function sanitizePlaybackAssets(raw) {
  if (!raw || typeof raw !== 'object') return null;

  const entryVideoHistoryId = isSafeVideoHistoryId(raw.entryVideoHistoryId)
    ? raw.entryVideoHistoryId
    : null;

  const holdLoopVideoHistoryIds = (Array.isArray(raw.holdLoopVideoHistoryIds) ? raw.holdLoopVideoHistoryIds : [])
    .filter(isSafeVideoHistoryId)
    .slice(0, LOOM_LIMITS.HOLD_LOOPS_MAX || 8);

  const exitByTransition = {};
  if (raw.exitByTransition && typeof raw.exitByTransition === 'object') {
    for (const [trId, vid] of Object.entries(raw.exitByTransition)) {
      if (isNonBlankStr(trId) && isSafeVideoHistoryId(vid)) {
        exitByTransition[trId.slice(0, 80)] = vid;
      }
    }
  }

  const audioOccupancy = {};
  if (raw.audioOccupancy && typeof raw.audioOccupancy === 'object') {
    for (const [assetId, occ] of Object.entries(raw.audioOccupancy)) {
      if (isNonBlankStr(assetId) && occ && typeof occ === 'object') {
        audioOccupancy[assetId.slice(0, 200)] = validateAudioOccupancy(occ);
      }
    }
  }

  const provenance = sanitizeProvenance(raw.provenance);
  const visualConditioningByAsset = {};
  if (raw.visualConditioningByAsset && typeof raw.visualConditioningByAsset === 'object') {
    for (const [assetId, manifest] of Object.entries(raw.visualConditioningByAsset)) {
      if (!isSafeVideoHistoryId(assetId)) continue;
      const sanitized = sanitizeVisualConditioning(manifest);
      if (sanitized) visualConditioningByAsset[assetId] = sanitized;
    }
  }

  // If completely empty, return null
  if (!entryVideoHistoryId
    && !holdLoopVideoHistoryIds.length
    && !Object.keys(exitByTransition).length
    && !Object.keys(audioOccupancy).length
    && !provenance
    && !Object.keys(visualConditioningByAsset).length) {
    return null;
  }

  return {
    entryVideoHistoryId,
    holdLoopVideoHistoryIds,
    exitByTransition,
    audioOccupancy,
    ...(provenance ? { provenance } : {}),
    ...(Object.keys(visualConditioningByAsset).length ? { visualConditioningByAsset } : {}),
  };
}

/**
 * Sanitize interactionWindow node field.
 */
export function sanitizeInteractionWindow(raw) {
  if (!raw || typeof raw !== 'object') return null;

  const enabled = raw.enabled === true;
  const protagonistCharacterId = isNonBlankStr(raw.protagonistCharacterId)
    ? trimTo(raw.protagonistCharacterId, LOOM_LIMITS.REF_ID_MAX || 64)
    : null;

  const protagonistPresence = FABLELOOM_PROTAGONIST_PRESENCE.includes(raw.protagonistPresence)
    ? raw.protagonistPresence
    : FABLELOOM_PROTAGONIST_PRESENCE_DEFAULT;

  const audioTarget = FABLELOOM_AUDIO_TARGETS.includes(raw.audioTarget)
    ? raw.audioTarget
    : FABLELOOM_AUDIO_TARGET_DEFAULT;

  const ambientDuckDb = Number.isFinite(raw.ambientDuckDb)
    ? clamp(
      Math.round(raw.ambientDuckDb),
      LOOM_LIMITS.AMBIENT_DUCK_DB_MIN || -60,
      LOOM_LIMITS.AMBIENT_DUCK_DB_MAX || 0,
    )
    : (LOOM_LIMITS.AMBIENT_DUCK_DB_DEFAULT || -8);

  const holdLoopRotation = FABLELOOM_HOLD_ROTATION_MODES.includes(raw.holdLoopRotation)
    ? raw.holdLoopRotation
    : FABLELOOM_HOLD_ROTATION_MODE_DEFAULT;

  return {
    enabled,
    protagonistCharacterId,
    protagonistPresence,
    audioTarget,
    ambientDuckDb,
    holdLoopRotation,
  };
}

/**
 * Resolve which video asset should be active for a given playback phase and node.
 * Backward compatible with legacy nodes having only videoHistoryId.
 */
export function resolvePlaybackPhaseAsset({
  node,
  phase = 'entry',
  activeHoldIndex = 0,
  transitionId = null,
  seed = 0,
  iteration = 0,
} = {}) {
  if (!node) {
    return {
      phase: 'ended',
      videoHistoryId: null,
      audioOccupancy: null,
      safeForLiveVoice: true,
      isEntry: false,
      isHold: false,
      isExit: false,
    };
  }

  const assets = node.playbackAssets || null;
  const legacyVideoId = node.videoHistoryId || null;

  let selectedVideoId = null;
  let effectivePhase = phase;

  if (effectivePhase === 'entry') {
    selectedVideoId = assets?.entryVideoHistoryId || legacyVideoId || null;
    // If no entry video, try to fall back to hold loop or legacy video
    if (!selectedVideoId && assets?.holdLoopVideoHistoryIds?.length) {
      selectedVideoId = assets.holdLoopVideoHistoryIds[0];
      effectivePhase = 'hold';
    }
  } else if (effectivePhase === 'hold') {
    const holdIds = (assets?.holdLoopVideoHistoryIds?.length)
      ? assets.holdLoopVideoHistoryIds
      : (assets?.entryVideoHistoryId ? [assets.entryVideoHistoryId] : (legacyVideoId ? [legacyVideoId] : []));

    if (holdIds.length > 0) {
      const rotationMode = node.interactionWindow?.holdLoopRotation || 'deterministic';
      let index = 0;
      if (rotationMode === 'sequential') {
        index = Math.abs(activeHoldIndex) % holdIds.length;
      } else if (rotationMode === 'shuffle') {
        // deterministic pseudo-random from seed and iteration
        const hash = Math.abs((Number(seed) || 0) * 31 + (Number(iteration) || 0) * 17 + Number(activeHoldIndex));
        index = hash % holdIds.length;
      } else {
        // deterministic
        index = (Math.abs(Number(seed) || 0) + Number(iteration) + Number(activeHoldIndex)) % holdIds.length;
      }
      selectedVideoId = holdIds[index] || holdIds[0];
    }
  } else if (effectivePhase === 'exit') {
    if (transitionId && assets?.exitByTransition?.[transitionId]) {
      selectedVideoId = assets.exitByTransition[transitionId];
    } else {
      selectedVideoId = null;
    }
  } else if (effectivePhase === 'ended') {
    selectedVideoId = null;
  }

  const audioOccupancy = (selectedVideoId && assets?.audioOccupancy?.[selectedVideoId])
    ? validateAudioOccupancy(assets.audioOccupancy[selectedVideoId])
    : null;

  const safeForLiveVoice = audioOccupancy ? audioOccupancy.safeForLiveVoice : true;

  return {
    phase: effectivePhase,
    videoHistoryId: selectedVideoId,
    audioOccupancy,
    safeForLiveVoice,
    isEntry: effectivePhase === 'entry',
    isHold: effectivePhase === 'hold',
    isExit: effectivePhase === 'exit',
  };
}

/**
 * Inspect a scene node for production readiness and live voice safety.
 * Pure deterministic preflight check — NO AI / provider calls!
 */
export function inspectNodeProductionReadiness(node, { universe = null, loom = null } = {}) {
  const findings = [];
  const push = (code, severity, message, remediation, extra = {}) => {
    findings.push({ code, severity, message, remediation, ...extra });
  };

  if (!node) {
    return { ready: false, findings: [{ code: 'NO_NODE', severity: 'error', message: 'No scene provided.', remediation: 'Select a scene.' }] };
  }

  const assets = node.playbackAssets;
  const interaction = node.interactionWindow;

  // Check audio occupancy safety on hold loops
  if (assets?.holdLoopVideoHistoryIds?.length) {
    for (const holdId of assets.holdLoopVideoHistoryIds) {
      const occ = assets.audioOccupancy?.[holdId];
      if (occ) {
        const validated = validateAudioOccupancy(occ);
        if (validated.characterDialogue.length > 0) {
          push(
            'HOLD_ASSET_HAS_DIALOGUE',
            'error',
            `Hold loop "${holdId}" contains rendered character dialogue and cannot open a live voice window.`,
            'Render dialogue separately or remove speech lane from hold loop.',
            { assetId: holdId },
          );
        }
        if (validated.effects.some((e) => e.blocking)) {
          push(
            'HOLD_ASSET_HAS_BLOCKING_EFFECTS',
            'warning',
            `Hold loop "${holdId}" contains author-marked voice-blocking sound effects.`,
            'Adjust effect intervals or unmark blocking flag.',
            { assetId: holdId },
          );
        }
      }
    }
  }

  // Check interaction window prerequisites
  if (interaction?.enabled) {
    if (node.isEnding) {
      push(
        'INTERACTION_ON_ENDING',
        'error',
        'Live interaction cannot be enabled on an ending scene.',
        'Disable live interaction on ending scene.',
      );
    }

    if (node.playbackMode === 'cut') {
      push(
        'INTERACTION_ON_CUT',
        'warning',
        'Scene is an automatic cut; live voice interaction will be bypassed.',
        'Change playback behavior to decision point or disable interaction.',
      );
    }

    if (interaction.protagonistPresence === 'onscreen') {
      push(
        'PROTAGONIST_ONSCREEN',
        'warning',
        'Live voice currently requires off-screen protagonist presence to avoid lip-sync mismatch.',
        'Set protagonist presence to off-screen.',
      );
    }

    if (!interaction.protagonistCharacterId) {
      push(
        'MISSING_PROTAGONIST_CHARACTER',
        'error',
        'Live interaction is enabled but no protagonist character is bound.',
        'Select a protagonist character in scene settings.',
      );
    } else if (universe && Array.isArray(universe.characters)) {
      const found = universe.characters.some((c) => c.id === interaction.protagonistCharacterId);
      if (!found) {
        push(
          'PROTAGONIST_NOT_IN_UNIVERSE',
          'error',
          `Bound protagonist character "${interaction.protagonistCharacterId}" does not exist in the linked Universe.`,
          'Re-bind a valid character from the Universe.',
        );
      }
    }

    if (loom?.participationMode === 'helper' && node.audienceConnection !== 'connected') {
      push(
        'DISCONNECTED_INTERACTION',
        'error',
        'Live interaction is enabled while the audience communication channel is disconnected.',
        'Set audience connection to connected or disable interaction.',
      );
    }

    const hasHoldAsset = (assets?.holdLoopVideoHistoryIds?.length > 0)
      || !!assets?.entryVideoHistoryId
      || !!node.videoHistoryId;

    if (!hasHoldAsset) {
      push(
        'NO_HOLD_ASSET',
        'warning',
        'No hold loop or video asset is rendered for this live conversation scene.',
        'Generate or attach a hold loop video asset.',
      );
    }
  }

  // Optional transition exit check
  const transitions = node.transitions || [];
  if (assets && transitions.length > 0) {
    const missingExits = transitions.filter((t) => !assets.exitByTransition?.[t.id]);
    if (missingExits.length > 0 && Object.keys(assets.exitByTransition || {}).length > 0) {
      push(
        'PARTIAL_EXIT_CLIPS',
        'info',
        `${missingExits.length} of ${transitions.length} transition(s) do not have exit clips and will cut directly to target scene.`,
        'Render and attach matching exit clips if continuous transition is desired.',
      );
    }
  }

  const errorCount = findings.filter((f) => f.severity === 'error').length;
  const warningCount = findings.filter((f) => f.severity === 'warning').length;

  return {
    ready: errorCount === 0,
    errorCount,
    warningCount,
    findings,
  };
}

/**
 * Inspect all scenes in an episode for production readiness.
 */
export function inspectEpisodeProductionReadiness(episode, { universe = null, loom = null } = {}) {
  const nodes = Array.isArray(episode?.nodes) ? episode.nodes : [];
  const nodeResults = {};
  let totalErrors = 0;
  let totalWarnings = 0;

  for (const node of nodes) {
    const res = inspectNodeProductionReadiness(node, { universe, loom });
    nodeResults[node.id] = res;
    totalErrors += res.errorCount;
    totalWarnings += res.warningCount;
  }

  return {
    ready: totalErrors === 0,
    totalErrors,
    totalWarnings,
    nodeResults,
  };
}