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

42.7 KB
Raw Blame
import { musicVideoAllowsMedia, assertMusicVideoMediaSelections } from '../../lib/musicVideoMediaPolicy.js';
import { castAndSetsApprovalInputs, castAndSetsApprovalValues, productionFeedbackContext, seedArtDraft } from './productionReview.js';
import { withMusicVideoStyle } from './styleReferences.js';
/**
 * Music Video — Cast & Sets check-in orchestrator.
 *
 * Runs the stage whose record transforms live in castAndSets.js:
 *
 *   1. direction  — one provider call (castAndSetsDirection.js) through the
 *                   shared runner, outside the write lock, against a snapshot;
 *   2. images     — the reference images of castAndSetsPlan.js, enqueued on
 *                   the normal image queue with a `musicVideo.castAndSets` tag
 *                   so the completion hook (musicVideoCastSetsImageHook.js)
 *                   files each result back here; a key is dispatched only once
 *                   every image it is conditioned on has landed;
 *   3. sheet      — castAndSetsSheet.js, saved as a `cast-sets` development
 *                   artifact (a new version on every regeneration);
 *   4. check-in   — `review` (default) waits for the director; `auto` approves.
 *
 * Approval writes the result into the project: the character sheet and set
 * plates become visual-spec references (conditioning frame generation), the
 * protagonist and sets become concept subjects. A production run waiting on the
 * stage re-bases its creative-setup checksum in the same write and continues.
 *
 * Everything is started by the director (Start / Regenerate / Resume, or a
 * production run they started). Nothing here runs at boot: the image hook only
 * files completions of jobs that were already queued, and a stage pinned to a
 * previous process dispatches nothing until it is resumed.
 */

import { randomUUID } from 'crypto';
import { readFile } from 'fs/promises';
import { basename, extname } from 'path';
import { ServerError } from '../../lib/errorHandler.js';
import { QUEUEABLE_IMAGE_MODES } from '../../lib/generationModes.js';
import { resolveGalleryImage, resolveImageRef } from '../../lib/pathSafety.js';
import { RENDER_TARGET } from '../../lib/renderTargets.js';
import { trimTo } from '../../lib/textUtils.js';
import { getProject, mutateProjectRecord } from './projects.js';
import { requireProject } from './requireProject.js';
import { musicVideoEvents } from './events.js';
import { effortArg, recordLlmRoute, resolveMusicVideoLlm } from './llmRoute.js';
import {
  allCastAndSetsImagesDone,
  assertCastAndSetsApprovable,
  castAndSetsCheckinMode,
  dispatchableImageKeys,
  linkCastAndSetsJob,
  presentCastAndSets,
  addCastAndSetsFeedback,
  reconfirmCastAndSetsOnProject,
  removeCastAndSetsFeedback,
  reserveCastAndSetsImage,
  resumeCastAndSetsOnProject,
  reviseCastAndSetsOnProject,
  setCastAndSetsDirection,
  setCastAndSetsStatus,
  settleCastAndSetsImage,
  startCastAndSetsOnProject,
} from './castAndSets.js';
import {
  applyCastAndSetsDirectionEdits,
  buildCastAndSetsPrompt,
  castAndSetsAllowsImages,
  castAndSetsMedium,
  describeDirectionChanges,
  mergeCastAndSetsDirection,
  moodBoardImageList,
  parseCastAndSetsResponse,
  songSections,
} from './castAndSetsDirection.js';
import {
  CAST_SETS_IMAGE_SIZE,
  affectedImageKeys,
  buildCastAndSetsImagePlan,
  castAndSetsReferences,
  castAndSetsSubjects,
  noteImageKeys,
} from './castAndSetsPlan.js';
import { renderCastAndSetsSheet } from './castAndSetsSheet.js';
import { findDevArtifact, reviewDevArtifact, resolveDevArtifactNotes } from './devArtifacts.js';
import { findProductionRun, haltProduction, rebaseProductionAfterCheckin, reserveProductionStep, settleProductionStep } from './production.js';

const PROCESS_ID = `proc-${randomUUID()}`;
const short = (id) => String(id || '').slice(3, 11);
const MAX_KEY_NOTES = 8;
const MAX_SUBMITTED_PROMPT = 20_000;
const MAX_SUBMITTED_REFERENCES = 16;

// Test seam: provider, queue, settings and mood-board access are swappable.
const defaults = {
  resolveProvider: async (opts) => resolveMusicVideoLlm(opts),
  runPrompt: async (opts) => (await import('../promptRunner.js')).runPromptThroughProvider(opts),
  getSettings: async () => (await import('../settings.js')).getSettings(),
  enqueue: async (job) => (await import('../mediaJobQueue/index.js')).enqueueJob(job),
  loadBoard: async (id) => (await import('../moodBoard/index.js')).getBoard(id),
  boardItemImage: async () => (await import('../moodBoard/logic.js')).boardItemLocalImage,
  loadTrack: async (id) => (await import('../tracks/index.js')).getTrack(id),
  readImage: (path) => readFile(path),
  imageParams: (settings, route, common) => imageJobParams(settings, route, common),
  resolveRoute: null,
};
let deps = { ...defaults };
export function __setCastAndSetsDepsForTests(overrides) { deps = { ...defaults, ...overrides }; }
export const __castAndSetsProcessId = () => PROCESS_ID;

/**
 * The project as a CLIENT reads it. Only this process knows its own id, so only
 * the server can tell a working stage a restart unpinned (`interrupted`) from
 * one still running here; a raw record read would show every such stage as
 * live forever (#9940). Not for write paths — never persist the result.
 */
export const presentProjectCastAndSets = (project) => (project?.castAndSets
  ? { ...project, castAndSets: presentCastAndSets(project.castAndSets, PROCESS_ID) }
  : project);

function publish(projectId, project) {
  musicVideoEvents.emit('cast-and-sets', {
    projectId,
    stage: presentCastAndSets(project?.castAndSets, PROCESS_ID),
    project,
  });
}

async function fail(projectId, reason, error = null) {
  const out = await mutateProjectRecord(projectId, (current) => setCastAndSetsStatus(refundUnusedCheckinSteps(current), 'failed', { reason, error }));
  console.error(`❌ Music Video Cast & Sets ${short(projectId)} failed: ${reason}`);
  publish(projectId, out.project);
  return out;
}

// ---- route choice -------------------------------------------------------------

/**
 * The image route: a production run's pool route when one is given; otherwise
 * Codex when the brief allows it (or names no image tool) and it is enabled,
 * then the brief's other queueable image tools in catalog order, then the
 * install's Music Video render default. Returns `{ mode, model }` or null.
 */
async function chooseCastAndSetsRoute(project, { preferred = null, settings } = {}) {
  if (deps.resolveRoute) return deps.resolveRoute(project, { preferred, settings });
  const { resolveRenderTargetConfig } = await import('../imageGen/cloudProviderConfig.js');
  // A mode is usable when it rides the queue and, for a cloud backend, its
  // opt-in toggle is on (the same resolver the dispatch itself goes through).
  const usable = (mode) => {
    if (!QUEUEABLE_IMAGE_MODES.includes(mode)) return false;
    const resolved = resolveRenderTargetConfig(settings, RENDER_TARGET.MUSIC_VIDEO, { mode });
    return resolved.mode === mode && (!resolved.cloud || resolved.cloud.enabled);
  };
  if (preferred?.mode) return usable(preferred.mode) ? { mode: preferred.mode, model: preferred.model || null } : null;
  const tools = (project?.automation?.tools || []).filter((t) => t.startsWith('image:')).map((t) => t.slice('image:'.length));
  const candidates = tools.length ? tools : ['codex'];
  if (candidates.includes('codex') && usable('codex')) return { mode: 'codex', model: null };
  const listed = candidates.find((mode) => mode !== 'codex' && usable(mode));
  if (listed) return { mode: listed, model: null };
  if (tools.length) return null;
  const resolved = resolveRenderTargetConfig(settings, RENDER_TARGET.MUSIC_VIDEO, {});
  return usable(resolved.mode) ? { mode: resolved.mode, model: null } : null;
}

// ---- direction ------------------------------------------------------------------

async function loadContext(project) {
  assertMusicVideoMediaSelections(project);
  const boardId = project?.visualSpec?.moodBoardId;
  const board = boardId ? await deps.loadBoard(boardId).catch(() => null) : null;
  const resolveItem = board ? await deps.boardItemImage() : null;
  const moodImages = board ? moodBoardImageList(board, resolveItem) : [];
  const track = project?.trackId ? await deps.loadTrack(project.trackId).catch(() => null) : null;
  return { board, moodImages, track };
}

/**
 * Run the direction call for the stage's current revision and write the image
 * plan. `notes` (a revision) are sent with the current direction; `forceKeys`
 * are image keys the director flagged directly.
 */
async function runDirection(projectId, { providerId, model, effort, notes = [], forceKeys = [] } = {}) {
  const project = await requireProject(projectId);
  const stage = project.castAndSets;
  const { board, moodImages, track } = await loadContext(project);
  // Request pin > the brief's Cast & Sets pin > its direction LLM > an eligible TUI provider > the active one (llmRoute.js).
  const { provider, selectedModel, route } = await deps.resolveProvider({ providerId, model, effort, automation: project.automation, stage: 'castAndSets' }).catch(() => ({ provider: null }));
  if (!provider) return fail(projectId, 'No AI provider is available for the creative direction');
  if (provider.enabled === false) return fail(projectId, `The ${provider.name || provider.id} provider is disabled`);
  const previous = stage?.direction || null;
  // A revision keeps the medium it was directed in; a fresh pass resolves it
  // from the project's policy and tools, so a saved direction is never
  // silently re-cast into the other medium.
  // A saved direction without a medium predates the procedural one: photographic.
  const medium = notes.length && previous ? (previous.medium || 'photographic') : castAndSetsMedium(project);
  // Standing sheet feedback rides on every direction call, a fresh rebuild included.
  const feedback = stage?.feedback || [];
  const standing = feedback.length > 0;
  const prompt = buildCastAndSetsPrompt(project, { moodImages, board, track, previous: notes.length ? previous : null, notes, medium, feedback }) + productionFeedbackContext(project);
  let text;
  try {
    ({ text } = await deps.runPrompt({ provider, model: selectedModel, ...effortArg(route), prompt, source: 'music-video-cast-sets' }));
  } catch (err) {
    return fail(projectId, 'The creative direction call failed', err.message);
  }
  await recordLlmRoute(projectId, 'castAndSets', route);
  const parsed = parseCastAndSetsResponse(text);
  if (!parsed) return fail(projectId, 'The creative direction answer had no usable JSON');
  const sections = songSections(project);
  const { direction, missing } = mergeCastAndSetsDirection(notes.length ? previous : null, parsed, { sections, medium });
  if (missing.length) return fail(projectId, `The creative direction answer is missing: ${missing.join(', ')}`);
  // The look every image prompt carries. While the director's sheet feedback
  // stands, the look line rewritten to agree with it wins; otherwise the
  // director's palette/light/texture line, else the project's visual style.
  // Never the board's composed style verbatim: it can describe a whole person
  // and scene, which then lands in every empty set plate.
  direction.look = (standing && (parsed.look || previous?.look)) || direction.look || trimTo(project.concept?.style, 500) || '';
  // Mood board images inform the direction as text only, never as image references.
  return writePlan(projectId, { direction, forceKeys, changes: previous ? describeDirectionChanges(previous, direction) : null });
}

/**
 * A direction saved before the look was written by the director copied the
 * mood board's composed style prompt verbatim (people and places included);
 * such a look falls back to the project's visual style.
 */
async function withoutBoardLook(project, direction) {
  const boardId = project?.visualSpec?.moodBoardId;
  if (!direction?.look || !boardId) return direction;
  const board = await deps.loadBoard(boardId).catch(() => null);
  const boardLook = trimTo(board?.style?.prompt, 500);
  return boardLook && direction.look === boardLook ? { ...direction, look: trimTo(project.concept?.style, 500) || '' } : direction;
}

/** (Re)build the plan from the stage's direction + accumulated per-image notes, then dispatch. */
async function writePlan(projectId, { direction = null, forceKeys = [], changes = null } = {}) {
  const project = await requireProject(projectId);
  const stage = project.castAndSets;
  const nextDirection = await withoutBoardLook(project, direction || stage.direction);
  // A procedural project whose brief names no image tool is code-only: nothing
  // is rendered, so no image backend is needed (or consulted).
  const codeOnly = !musicVideoAllowsMedia(project, 'image') || nextDirection.medium === 'procedural' && !castAndSetsAllowsImages(project);
  const plan = codeOnly ? {} : buildCastAndSetsImagePlan(project, nextDirection, { revisionNotes: keyNotesText(stage.keyNotes) });
  const renderKeys = affectedImageKeys(stage.plan || {}, plan, forceKeys);
  const settings = await deps.getSettings();
  const run = stage.productionRunId ? (project.productionRuns || []).find((r) => r.id === stage.productionRunId) : null;
  const preferred = run?.pool?.find((r) => r.kind === 'image') || stage.route || null;
  const route = codeOnly ? (stage.route || null) : await chooseCastAndSetsRoute(project, { preferred, settings });
  if (!route && !codeOnly) return fail(projectId, 'No enabled image backend is allowed for the Cast & Sets images — enable Codex (or another image tool in the brief) and resume');
  const out = await mutateProjectRecord(projectId, (current) => {
    const next = setCastAndSetsDirection(current, { direction: nextDirection, plan, route, renderKeys });
    if (!changes) return next;
    // What this revision changed, for the director to read beside the new sheet.
    const changeSummary = { revision: next.stage.revision, changes, rerendered: renderKeys.length, at: next.stage.updatedAt };
    const stage = { ...next.stage, changeSummary };
    return { project: { ...next.project, castAndSets: stage }, stage };
  });
  console.log(`🎭 Music Video Cast & Sets ${short(projectId)} r${out.stage.revision}: ${renderKeys.length} image(s) to render${route ? ` on ${route.mode}` : ' (code-only, no image backend)'}`);
  publish(projectId, out.project);
  return advance(projectId);
}

const keyNotesText = (keyNotes = {}) => Object.fromEntries(Object.entries(keyNotes).map(([k, list]) => [k, list.join('; ')]));

// ---- images -----------------------------------------------------------------------

function referencePaths(stage, item) {
  const paths = [];
  for (const key of item.refKeys || []) {
    const id = stage.images?.[key]?.imageId;
    const path = id ? resolveGalleryImage(id, { mustExist: false }) : null;
    if (path) paths.push(path);
  }
  for (const id of item.refImages || []) {
    const path = resolveGalleryImage(id, { mustExist: false });
    if (path && !paths.includes(path)) paths.push(path);
  }
  return paths.slice(0, 4);
}

/** Job params for one image on the stage's route (cloud provider bag or the local model). */
export async function imageJobParams(settings, route, common) {
  const [{ resolveRenderTargetConfig }, { resolveImageCleaners }, { resolveLocalImageModel }] = await Promise.all([
    import('../imageGen/cloudProviderConfig.js'),
    import('../../lib/imageCleanDefaults.js'),
    import('../imageGen/prepareParams.js'),
  ]);
  const resolved = resolveRenderTargetConfig(settings, RENDER_TARGET.MUSIC_VIDEO, { mode: route.mode, model: route.model });
  // Never substitute another backend for the one the stage chose.
  if (resolved.mode !== route.mode) throw new ServerError(`The ${route.mode} image backend is not available`, { status: 409, code: 'CAST_SETS_ROUTE_UNAVAILABLE' });
  if (resolved.cloud && !resolved.cloud.enabled) throw resolved.cloud.disabledError;
  const { cleanC2PA, denoise } = resolveImageCleaners(undefined, settings, route.mode);
  if (resolved.cloud) return { ...resolved.cloud.jobParams, ...common, cleanC2PA, denoise };
  const { pythonPath, selectedModel } = resolveLocalImageModel(settings, { modelId: route.model || undefined });
  return { ...common, cleanC2PA, denoise, pythonPath, ...(selectedModel?.id ? { modelId: selectedModel.id } : {}) };
}

async function enqueueImage(project, stage, key) {
  const item = stage.plan[key];
  const referenceImagePaths = referencePaths(stage, item);
  const common = {
    prompt: item.prompt,
    width: CAST_SETS_IMAGE_SIZE.width,
    height: CAST_SETS_IMAGE_SIZE.height,
    ...(referenceImagePaths.length ? { referenceImagePaths, referenceImageStrengths: referenceImagePaths.map(() => 1) } : {}),
    // The completion hook files the result by this tag. No `sceneId`, so the
    // scene-frame hook ignores the job.
    musicVideo: {
      projectId: project.id, castAndSets: { key, revision: stage.revision },
      ...(stage.productionRunId ? {
        productionRunId: stage.productionRunId,
        productionStepKey: checkinStep(project, stage, key)?.key,
      } : {}),
    },
  };
  const settings = await deps.getSettings();
  const baseParams = await deps.imageParams(settings, stage.route, common);
  const params = await withMusicVideoStyle(project, baseParams, stage.route.mode, stage.route.model, settings);
  // Persist the actual styled queue input, with only served local references.
  // Never expose the absolute host paths used by the provider transport.
  const submittedReferences = (params.referenceImagePaths || []).flatMap((path) => {
    if (typeof path !== 'string') return [];
    const filename = basename(path);
    if (resolveGalleryImage(filename, { mustExist: false }) === path) return [{ kind: 'image', filename }];
    if (resolveImageRef(filename, { mustExist: false }) === path) return [{ kind: 'image-ref', filename }];
    return [];
  });
  const prompt = String(params.prompt || '');
  const submission = {
    submittedPrompt: prompt.slice(0, MAX_SUBMITTED_PROMPT),
    submittedPromptTruncated: prompt.length > MAX_SUBMITTED_PROMPT,
    submittedReferences: submittedReferences.slice(0, MAX_SUBMITTED_REFERENCES),
    submittedReferencesTruncated: submittedReferences.length > MAX_SUBMITTED_REFERENCES,
    submittedRevision: stage.revision,
  };
  const sent = await deps.enqueue({ kind: 'image', params, owner: `music-video-cast-sets:${project.id}` });
  return { ...sent, submission };
}

// Check-in slots use the existing production ledger; the revision separates
// regenerated images and a terminal attempt permits a charged retry.
function checkinStep(project, stage, key) {
  const run = findProductionRun(project, stage.productionRunId);
  return run.steps.findLast((step) => step.kind === 'checkin'
    && step.sceneId === key && step.revisionId === String(stage.revision));
}

// Images never submitted must not remain charged after the check-in ends.
function refundUnusedCheckinSteps(project) {
  const runId = project.castAndSets?.productionRunId;
  if (!runId) return project;
  let next = project;
  for (const step of findProductionRun(project, runId).steps) {
    if (step.kind === 'checkin' && step.status === 'reserved'
      && project.castAndSets.images?.[step.sceneId]?.status !== 'queued') {
      next = settleProductionStep(next, runId, step.key, {
        status: 'refused', error: 'The check-in stopped before this image was submitted',
      }).project;
    }
  }
  return next;
}

/** Reserve the WHOLE pending plan in one write before any job can be queued. */
async function reserveCheckinPlan(projectId) {
  return mutateProjectRecord(projectId, (current) => {
    const stage = current.castAndSets;
    if (!stage?.productionRunId) return { project: current };
    const run = findProductionRun(current, stage.productionRunId);
    let next = current;
    for (const [key, image] of Object.entries(stage.images)) {
      if (image.status !== 'pending') continue;
      const step = checkinStep(next, stage, key);
      if (step?.status === 'reserved') continue;
      next = reserveProductionStep(next, run.id, {
        kind: 'checkin', sceneId: key, revisionId: String(stage.revision),
        route: { kind: 'image', ...stage.route }, processId: run.processId,
      }).project;
    }
    return { project: next };
  });
}

async function dispatchKey(projectId, key) {
  const reserved = await mutateProjectRecord(projectId, (current) => {
    if (current.castAndSets?.productionRunId) {
      const run = findProductionRun(current, current.castAndSets.productionRunId);
      if (run.status !== 'running' || checkinStep(current, current.castAndSets, key)?.status !== 'reserved') {
        throw new ServerError('The production run is not dispatching this image', { status: 409, code: 'CAST_SETS_NOT_RUNNING' });
      }
    }
    return reserveCastAndSetsImage(current, key, { processId: PROCESS_ID });
  })
    .catch((err) => ({ error: err }));
  if (reserved.error) {
    if (['CAST_SETS_IMAGE_BUSY', 'CAST_SETS_NOT_RUNNING'].includes(reserved.error.code)) return;
    throw reserved.error;
  }
  const productionStep = reserved.stage.productionRunId ? checkinStep(reserved.project, reserved.stage, key) : null;
  const runId = reserved.stage.productionRunId;
  const sent = await enqueueImage(reserved.project, reserved.stage, key).catch((err) => ({ error: err }));
  if (sent?.error || !sent?.jobId) {
    const reason = sent?.error?.message || 'The image job was not queued';
    const out = await mutateProjectRecord(projectId, (current) => {
      const next = productionStep ? settleProductionStep(current, runId, productionStep.key, { status: 'refused', error: reason }).project : current;
      const settled = settleCastAndSetsImage(next, key, { error: reason, revision: reserved.stage.revision });
      if (settled.stage?.status === 'failed') settled.project = refundUnusedCheckinSteps(settled.project);
      return settled;
    });
    console.warn(`⚠️ Music Video Cast & Sets ${short(projectId)} ${key} refused: ${reason}`);
    publish(projectId, out.project);
    return;
  }
  const linked = await mutateProjectRecord(projectId, (current) => {
    const next = productionStep ? settleProductionStep(current, runId, productionStep.key, { status: 'queued', jobId: sent.jobId }).project : current;
    return linkCastAndSetsJob(next, key, sent.jobId, sent.submission);
  });
  publish(projectId, linked.project);
  console.log(`🎭 Music Video Cast & Sets ${short(projectId)} ${key} → ${reserved.stage.route.mode} job ${String(sent.jobId).slice(0, 8)}`);
}

const advancing = new Map();
const backgroundWork = new Set();

/** Drain owned work before a test replaces its queue/provider/store fixtures. */
export async function __settleCastAndSetsForTests() {
  while (backgroundWork.size || advancing.size) {
    await Promise.allSettled([...backgroundWork, ...[...advancing.values()].map(entry => entry.promise)]);
  }
}

/**
 * Dispatch every image whose inputs are ready; assemble the sheet once every
 * image is done. Concurrent calls for one project coalesce.
 */
function advance(projectId) {
  const live = advancing.get(projectId);
  if (live) { live.again = true; return live.promise; }
  const entry = { again: false, promise: null };
  entry.promise = (async () => {
    try {
      do {
        entry.again = false;
        await advanceOnce(projectId);
      } while (entry.again);
    } finally {
      advancing.delete(projectId);
    }
  })();
  advancing.set(projectId, entry);
  return entry.promise;
}

async function advanceOnce(projectId) {
  const project = await requireProject(projectId);
  const stage = project.castAndSets;
  if (!stage || stage.processId !== PROCESS_ID || stage.status !== 'imaging') return;
  if (allCastAndSetsImagesDone(stage)) {
    await assemble(projectId);
    return;
  }
  if (stage.productionRunId) {
    const run = findProductionRun(project, stage.productionRunId);
    if (run.status !== 'running') return;
    const reserved = await reserveCheckinPlan(projectId).catch((error) => ({ error }));
    if (reserved.error) {
      const limit = ['PRODUCTION_SPEND_LIMIT', 'PRODUCTION_BUDGET_EXHAUSTED'].includes(reserved.error.code);
      const out = await mutateProjectRecord(projectId, (current) => {
        const failed = setCastAndSetsStatus(refundUnusedCheckinSteps(current), 'failed', { reason: reserved.error.message });
        return haltProduction(failed.project, stage.productionRunId, {
          status: limit ? 'limit-reached' : 'blocked', reason: reserved.error.message,
        });
      });
      musicVideoEvents.emit('production', { projectId, runId: out.run.id, run: out.run, action: { type: 'idle' }, project: out.project });
      publish(projectId, out.project);
      return;
    }
  }
  const keys = dispatchableImageKeys(stage);
  for (const key of keys) await dispatchKey(projectId, key);
  if (keys.length) publish(projectId, await requireProject(projectId));
}

function inBackground(label, projectId, fn) {
  const work = Promise.resolve().then(fn).catch(async (err) => {
    console.error(`❌ Music Video Cast & Sets ${short(projectId)} ${label} failed: ${err.message}`);
    await fail(projectId, `${label} failed: ${err.message}`).catch((recordErr) => console.error(`❌ Music Video Cast & Sets ${projectId} ${label} failed and its failure could not be recorded: ${recordErr.message}`));
  }).finally(() => backgroundWork.delete(work));
  backgroundWork.add(work);
}

// ---- sheet ----------------------------------------------------------------------------

const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };

async function embeddedImages(stage) {
  const out = {};
  for (const [key, img] of Object.entries(stage.images || {})) {
    const path = img.imageId ? resolveGalleryImage(img.imageId, { mustExist: false }) : null;
    const mime = path ? MIME[extname(path).toLowerCase()] : null;
    if (!path || !mime) continue;
    const bytes = await deps.readImage(path).catch(() => null);
    if (bytes) out[key] = `data:${mime};base64,${Buffer.from(bytes).toString('base64')}`;
  }
  return out;
}

/** Build the sheet, save it as the stage's development artifact, then check in. */
async function assemble(projectId) {
  const marked = await mutateProjectRecord(projectId, (current) => setCastAndSetsStatus(current, 'assembling'));
  publish(projectId, marked.project);
  const project = marked.project;
  const stage = marked.stage;
  const mode = castAndSetsCheckinMode(project);
  const html = renderCastAndSetsSheet({
    title: project.name,
    project,
    direction: stage.direction,
    images: await embeddedImages(stage),
    sections: songSections(project),
    durationSec: project.audioAnalysis?.durationSec ?? null,
    bpm: project.audioAnalysis?.bpm ?? null,
    revision: stage.revision,
    notesApplied: stage.notesApplied || [],
    checkinMode: mode,
    status: mode === 'auto' ? 'approved' : 'review',
  });
  const { saveGeneratedDevArtifact } = await import('./devArtifactService.js');
  const existing = stage.artifactId && (project.devArtifacts || []).some((a) => a.id === stage.artifactId && !a.deleted) ? stage.artifactId : null;
  const { artifact } = await saveGeneratedDevArtifact(projectId, {
    artifactId: existing,
    kind: 'cast-sets',
    title: `Cast & Sets — ${stage.direction?.protagonist?.name || project.name}`,
    html,
    source: 'cast-and-sets',
  });
  const out = await mutateProjectRecord(projectId, (current) => setCastAndSetsStatus(current, 'review', {
    extra: { artifactId: artifact.id, artifactVersion: artifact.version },
  }));
  console.log(`🎭 Music Video Cast & Sets ${short(projectId)} sheet v${artifact.version} ready (${mode === 'auto' ? 'auto-approve' : 'waiting for check-in'})`);
  if (mode === 'auto') return approveCastAndSets(projectId);
  publish(projectId, out.project);
  return out;
}

// ---- approval ------------------------------------------------------------------------

// Save the approved check-in's new cast and sets to the catalog (Casting /
// Environments), then show the stamped subjects. The approval already landed.
function queueCheckinCastToCatalog(projectId) {
  import('./catalogCast.js')
    .then(({ saveCheckinCastToCatalog }) => saveCheckinCastToCatalog(projectId))
    .then((result) => { if (result?.project) publish(projectId, result.project); })
    .catch((err) => console.error(`❌ Music Video Cast & Sets ${short(projectId)}: saving cast to the catalog failed: ${err.message}`));
}

/**
 * Apply an approved check-in to the project (references, subjects), approve
 * its artifact, and re-base a production run that was waiting on it.
 */
function applyApproval(project, now) {
  const stage = project.castAndSets;
  let next = {
    ...project,
    visualSpec: {
      references: [], palette: [], typography: '', cameraRules: '', moodBoardId: null,
      ...(project.visualSpec || {}),
      references: castAndSetsReferences(project, stage),
    },
    concept: { ...(project.concept || {}), subjects: castAndSetsSubjects(project, stage) },
  };
  assertMusicVideoMediaSelections(next);
  // Approving the sheet seeds the art-direction draft and guide so the next
  // approval is one click, not a re-typing of what the sheet already says.
  next = seedArtDraft(next, stage);
  if (stage.artifactId && (next.devArtifacts || []).some((a) => a.id === stage.artifactId && !a.deleted)) {
    next = reviewDevArtifact(next, stage.artifactId, { status: 'approved' }, now).project;
  }
  // Record what the approval rests on, so a later concept/style/subject/song
  // edit can be named as "changed since" (#10141).
  return setCastAndSetsStatus(next, 'approved', { extra: { approvedInputs: castAndSetsApprovalInputs(next), approvedValues: castAndSetsApprovalValues(next) } }, now);
}

// Settle the stage and re-base a production run waiting on it, in ONE write,
// so the run never observes the new references without its new basis.
const settleAndRebase = (next, now) => {
  const { project } = rebaseProductionAfterCheckin(next.project, now);
  return { project, stage: project.castAndSets };
};

/** Approve & continue. Returns `{ project, stage }`. */
export async function approveCastAndSets(projectId) {
  const now = new Date().toISOString();
  const out = await mutateProjectRecord(projectId, (current) => {
    assertCastAndSetsApprovable(current);
    return settleAndRebase(applyApproval(current, now), now);
  });
  console.log(`✅ Music Video Cast & Sets ${short(projectId)} approved (r${out.stage.revision})`);
  publish(projectId, out.project);
  queueCheckinCastToCatalog(projectId);
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

/**
 * Keep an approved check-in approved on the project's current concept, style,
 * subjects and song (#10141): clears the "changed since" note without
 * rebuilding the sheet or re-applying its references. Returns `{ project, stage }`.
 */
export async function reconfirmCastAndSets(projectId) {
  await requireProject(projectId);
  const now = new Date().toISOString();
  const out = await mutateProjectRecord(projectId, (current) => reconfirmCastAndSetsOnProject(current, castAndSetsApprovalInputs(current), castAndSetsApprovalValues(current), now));
  console.log(`✅ Music Video Cast & Sets ${short(projectId)} kept approved on current inputs`);
  publish(projectId, out.project);
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

/** Skip the check-in (e.g. no image backend): the autopilot continues without it. */
export async function skipCastAndSets(projectId) {
  await requireProject(projectId);
  const now = new Date().toISOString();
  const out = await mutateProjectRecord(projectId, (current) => {
    const base = current.castAndSets ? current : { ...current, castAndSets: { revision: 0, images: {}, plan: {}, createdAt: now } };
    if (base.castAndSets.status === 'approved') throw new ServerError('The Cast & Sets check-in is already approved', { status: 409, code: 'CAST_SETS_EXISTS' });
    // A skip also releases work in flight for it: this process stops dispatching.
    return settleAndRebase(setCastAndSetsStatus(refundUnusedCheckinSteps(base), 'skipped', { reason: 'Skipped by the director' }, now), now);
  });
  console.log(`⏭️ Music Video Cast & Sets ${short(projectId)} skipped`);
  publish(projectId, out.project);
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

// ---- director actions ------------------------------------------------------------------

/** Start the check-in (explicit request). The work continues in the background. */
export async function startCastAndSets(projectId, { providerId, model, effort, productionRunId = null } = {}) {
  const project = await requireProject(projectId);
  if (!Array.isArray(project.audioAnalysis?.sections) || !project.audioAnalysis.sections.length) {
    throw new ServerError('Analyze the song before the Cast & Sets check-in', { status: 409, code: 'NOT_ANALYZED' });
  }
  const out = await mutateProjectRecord(projectId, (current) => startCastAndSetsOnProject(current, { processId: PROCESS_ID, productionRunId }));
  console.log(`🎭 Music Video Cast & Sets ${short(projectId)} started (r${out.stage.revision})`);
  publish(projectId, out.project);
  inBackground('The creative direction', projectId, () => runDirection(projectId, { providerId, model, effort }));
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

/**
 * Regenerate, with notes or without. `notes` default to the open notes on the stage's
 * sheet. A note aimed at an image (`character`, `looks`, `set:<id>`,
 * `test:<n>`, …) re-renders that image and what depends on it; any other
 * note revises the direction, and only images whose prompt changed re-render.
 * The consumed notes are resolved on the sheet. Returns `{ project, stage }`.
 */
export async function regenerateCastAndSets(projectId, { notes = null, providerId, model, effort } = {}) {
  const project = await requireProject(projectId);
  const stage = project.castAndSets;
  if (!stage?.direction) throw new ServerError('There is no Cast & Sets sheet to regenerate yet', { status: 409, code: 'CAST_SETS_NO_DIRECTION' });
  const artifact = stage.artifactId ? (() => { try { return findDevArtifact(project, stage.artifactId); } catch { return null; } })() : null;
  const reviewNotes = (project.productionReview?.feedback || []).filter(n => n.stage === 'art' && !n.resolvedAt)
    .map(n => ({ target: `production-review:${n.target}`, text: n.text }));
  const source = [...(Array.isArray(notes) ? notes : (artifact?.notes || []).filter((n) => !n.resolvedAt)), ...reviewNotes];
  const imageNotes = {};
  const directionNotes = [];
  for (const note of source) {
    const keys = noteImageKeys(note.target, stage.plan || {});
    if (keys) keys.forEach((k) => { imageNotes[k] = [...(imageNotes[k] || []), note.text]; });
    else directionNotes.push(note);
  }
  const redirect = directionNotes.length > 0;
  const consumed = new Set(source.map((n) => n.id).filter(Boolean));
  const out = await mutateProjectRecord(projectId, (current) => {
    const revised = reviseCastAndSetsOnProject(current, { processId: PROCESS_ID, notesApplied: source, redirect });
    const keyNotes = { ...(revised.stage.keyNotes || {}) };
    for (const [k, list] of Object.entries(imageNotes)) keyNotes[k] = [...(keyNotes[k] || []), ...list].slice(-MAX_KEY_NOTES);
    let next = { ...revised.project, castAndSets: { ...revised.stage, keyNotes } };
    if (artifact && consumed.size) next = resolveDevArtifactNotes(next, artifact.id, (n) => consumed.has(n.id)).project;
    return { project: next, stage: next.castAndSets };
  });
  console.log(`🎭 Music Video Cast & Sets ${short(projectId)} regenerating r${out.stage.revision} (${source.length} note(s)${redirect ? ', new direction' : ''})`);
  publish(projectId, out.project);
  // With no notes the director asks for another take: every image re-renders
  // from the current direction.
  const forceKeys = source.length ? Object.keys(imageNotes) : Object.keys(stage.plan || {});
  inBackground('The regeneration', projectId, () => (redirect
    ? runDirection(projectId, { providerId, model, effort, notes: directionNotes, forceKeys })
    : writePlan(projectId, { forceKeys })));
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

/**
 * Apply the director's plain-text feedback on the sheet. Aimed at one image
 * (`target`: `character`, `looks`, `set:<id>`, a set's name, …) it is that
 * image's revision note (see regenerateCastAndSets). Aimed at the whole sheet
 * (no target) it becomes STANDING feedback: the direction is rewritten to
 * honor it, including the look line every image prompt carries, and every
 * later direction call (a rebuild included) keeps honoring it until the
 * director removes it. Only images whose prompt changed re-render.
 * Returns `{ project, stage }`.
 */
export async function applyCastAndSetsFeedback(projectId, { text, target = null, providerId, model, effort } = {}) {
  const project = await requireProject(projectId);
  const stage = project.castAndSets;
  if (!stage?.direction) throw new ServerError('There is no Cast & Sets sheet to give feedback on yet', { status: 409, code: 'CAST_SETS_NO_DIRECTION' });
  if (target) {
    if (!noteImageKeys(target, stage.plan || {})) throw new ServerError(`No image on this sheet is called ${target}`, { status: 422, code: 'CAST_SETS_UNKNOWN_IMAGE' });
    return regenerateCastAndSets(projectId, { notes: [{ target, text }], providerId, model, effort });
  }
  const note = { id: null, target: 'sheet', text };
  const out = await mutateProjectRecord(projectId, (current) => {
    const added = addCastAndSetsFeedback(current, { id: `fb-${randomUUID().slice(0, 8)}`, text });
    return reviseCastAndSetsOnProject(added.project, { processId: PROCESS_ID, notesApplied: [note], redirect: true });
  });
  console.log(`🎭 Music Video Cast & Sets ${short(projectId)} applying sheet feedback r${out.stage.revision} (${out.stage.feedback.length} standing)`);
  publish(projectId, out.project);
  inBackground('The feedback', projectId, () => runDirection(projectId, { providerId, model, effort, notes: [note] }));
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

/** Stop honoring one piece of standing sheet feedback. Nothing re-renders until the next revision. Returns `{ project, stage }`. */
export async function removeCastAndSetsFeedbackEntry(projectId, feedbackId) {
  await requireProject(projectId);
  const out = await mutateProjectRecord(projectId, (current) => removeCastAndSetsFeedback(current, feedbackId));
  console.log(`🎭 Music Video Cast & Sets ${short(projectId)} feedback removed (${out.stage.feedback.length} standing)`);
  publish(projectId, out.project);
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

/**
 * Save the director's direct edits to a procedural direction (construction,
 * palette, expressions, movement, world rules, per-set image role) through the
 * revision path: the stage re-opens as a new revision, the edited direction is
 * persisted in the same write, and only images whose prompt changed re-render
 * before the sheet is re-assembled. No direction (text) provider call is made;
 * a changed image prompt is the director's save acting on the image queue.
 * Returns `{ project, stage }`.
 */
export async function editCastAndSetsDirection(projectId, edits) {
  const project = await requireProject(projectId);
  const sections = songSections(project);
  let changed = [];
  const out = await mutateProjectRecord(projectId, (current) => {
    const stage = current.castAndSets;
    if (!stage?.direction) throw new ServerError('There is no Cast & Sets direction to edit yet', { status: 409, code: 'CAST_SETS_NO_DIRECTION' });
    assertCastAndSetsApprovable(current);
    const edited = applyCastAndSetsDirectionEdits(stage.direction, edits, { sections });
    if (!edited.changed.length) throw new ServerError('Nothing changed — edit a field first', { status: 422, code: 'CAST_SETS_NO_EDITS' });
    changed = edited.changed;
    const notesApplied = [{ id: null, target: 'direction', text: `Edited by the director: ${changed.join(', ')}` }];
    const revised = reviseCastAndSetsOnProject(current, { processId: PROCESS_ID, notesApplied, redirect: false });
    const next = { ...revised.project, castAndSets: { ...revised.stage, direction: edited.direction } };
    return { project: next, stage: next.castAndSets };
  });
  console.log(`🎭 Music Video Cast & Sets ${short(projectId)} direction edited r${out.stage.revision} (${changed.length} field(s))`);
  publish(projectId, out.project);
  inBackground('The direction edit', projectId, () => writePlan(projectId));
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

/** Resume an interrupted (restart) or failed stage in this process. */
export async function resumeCastAndSets(projectId, { providerId, model, effort } = {}) {
  const out = await mutateProjectRecord(projectId, (current) => resumeCastAndSetsOnProject(current, { processId: PROCESS_ID }));
  console.log(`▶️ Music Video Cast & Sets ${short(projectId)} resumed (${out.stage.status})`);
  publish(projectId, out.project);
  inBackground('The resume', projectId, () => {
    if (out.stage.status === 'directing') return runDirection(projectId, { providerId, model, effort, notes: out.stage.notesApplied || [] });
    if (out.stage.status === 'assembling') return assemble(projectId);
    return advance(projectId);
  });
  return { project: out.project, stage: presentCastAndSets(out.stage, PROCESS_ID) };
}

/** The stage as the director sees it. */
export async function getCastAndSets(projectId) {
  const project = await requireProject(projectId);
  return { stage: presentCastAndSets(project.castAndSets, PROCESS_ID) };
}

// ---- completion hook entry points ----------------------------------------------------------

/**
 * A tagged image job ended. `filename` = it rendered; otherwise `error`.
 * Settles its key (idempotent) and, when the stage is dispatching in this
 * process, continues. Returns true when the record changed.
 */
export async function onCastAndSetsImageSettled({ projectId, key, jobId = null, filename = null, error = null, revision = null, productionRunId = null, productionStepKey = null, status = null }) {
  const project = await getProject(projectId);
  if (!project?.castAndSets?.images?.[key]) return false;
  const out = await mutateProjectRecord(projectId, (current) => {
    if (revision != null && revision !== current.castAndSets?.revision) return { project: current, changed: false };
    const next = productionRunId && productionStepKey
      ? settleProductionStep(current, productionRunId, productionStepKey, {
        status: filename ? 'completed' : status === 'canceled' ? 'canceled' : 'failed', jobId, error,
      }).project : current;
    const settled = settleCastAndSetsImage(next, key, { jobId, filename, error, revision });
    if (settled.stage?.status === 'failed') settled.project = refundUnusedCheckinSteps(settled.project);
    return settled;
  });
  if (!out.changed) return false;
  publish(projectId, out.project);
  if (out.stage?.processId === PROCESS_ID && out.stage.status === 'imaging') {
    advance(projectId).catch((err) => console.error(`❌ Music Video Cast & Sets ${short(projectId)} could not continue: ${err.message}`));
  }
  return true;
}