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

25.7 KB
Raw Blame
/**
 * Music Video — selective section revision (#8987, part of #8966): pure record
 * transforms.
 *
 * A director reviews a draft excerpt (#8986), flags the moments that don't
 * work, and asks for a revision. The revision is a persisted CHECKPOINT on the
 * project (`project.revisions[]`) that:
 *
 *   - maps the excerpt's flagged notes onto the sections the draft actually
 *     rendered (`excerpt.sections`, absolute song time) and REJECTS the selected
 *     take of each flagged section — the slot clears, so that section, and only
 *     that section, reads as "needs a take" again (takes.js semantics);
 *   - leaves every other section in the window APPROVED and untouched, with its
 *     selection snapshotted (`keptAssetId`) so the record shows what was kept;
 *   - is resumed by `resumeRevision` (revisionService.js), which re-derives each
 *     rejected section's state from the record plus the media-job queue EVERY
 *     time rather than trusting a stored "submitted" flag. A section whose slot
 *     holds a take is `ready` and is never asked to generate again, whatever
 *     happened to the render — so a rendering retry, a restart, or a second
 *     click can never re-submit paid generation for it.
 *
 * Title cards are code-rendered (no paid generation, #8985), so a flagged card
 * is reported as skipped rather than revised — its fix is an edit, not a take.
 *
 * Peer sync: `revisions` (like `excerpts`) is an additive field on the
 * whole-record LWW project body. An older peer stores it verbatim and has no
 * route that acts on it, so no `musicVideoProjects` schema bump is needed.
 */

import { captureTakeDependencies, musicVideoDependencyChanges, musicVideoTakeChanges } from '../../lib/musicVideoDependencies.js';
import { randomUUID } from 'crypto';
import { ServerError } from '../../lib/errorHandler.js';
import { isNonBlankStr } from '../../lib/textUtils.js';
import { canonicalSnapshotChecksum } from '../../lib/snapshotChecksum.js';
import { normalizeMusicVideoProductionPolicy, summarizeMusicVideoMediumPlan } from '../../lib/musicVideoMediumPlan.js';
import { ensureSceneTakes, reviewSceneTake, TAKE_SLOT } from './takes.js';
import { projectExcerpts } from './excerpt.js';

// A project row carries its recent revisions; the oldest SETTLED ones are
// dropped past this so a long review loop can't grow one record without bound.
const MAX_PROJECT_REVISIONS = 20;
// A resume that hands a section out for generation CLAIMS it for this long, so
// a second resume (another tab, a double submit) in the window between the
// hand-out and the job reaching the queue can't hand it out again. After the
// lease a section with no job and no take is handed out again — the earlier
// submission evidently never reached the queue.
const GENERATION_CLAIM_LEASE_MS = 90_000;
// A job that completed but whose take never attached (a failed attach write)
// counts as in flight only this long, so it can't wedge the revision forever.
const TAKE_ATTACH_GRACE_MS = 120_000;

const revisionError = (status, code, message, context) =>
  new ServerError(message, { status, code, ...(context ? { context } : {}) });

const codeFirst = (project) => normalizeMusicVideoProductionPolicy(project?.productionPolicy).strategy === 'code-first';
const mediumFor = (project, sceneId) => project?.treatment?.shotDirections?.find((direction) => direction.sceneId === sceneId)?.medium;
const mediumBasis = (project) => canonicalSnapshotChecksum({
  productionPolicy: project?.productionPolicy || null,
  directions: project?.treatment?.shotDirections || null,
  scenes: (project?.scenes || []).map(({ sceneId, startSec, endSec }) => ({ sceneId, startSec, endSec })),
  durationSec: project?.audioAnalysis?.durationSec ?? null,
});

function assertCodeFirstPlan(project) {
  const plan = summarizeMusicVideoMediumPlan(project);
  if (plan.blocked) throw revisionError(409, 'REVISION_MEDIUM_PLAN_CONFLICT',
    plan.unresolved.filter((item) => item.blocking).map((item) => item.message).join(' '));
}

/** The revision array on a project, tolerating a legacy record with none. */
export const projectRevisions = (project) => (Array.isArray(project?.revisions) ? project.revisions : []);

const isActive = (revision) => revision.status === 'open' || revision.status === 'rendering';

function findRevision(project, revisionId) {
  const revision = projectRevisions(project).find((r) => r.id === revisionId);
  if (!revision) throw revisionError(404, 'NOT_FOUND', 'Revision not found');
  return revision;
}

function replaceRevision(project, revision) {
  return { ...project, revisions: projectRevisions(project).map((r) => (r.id === revision.id ? revision : r)) };
}

function pruneRevisions(revisions) {
  const next = revisions.slice();
  for (let i = 0; i < next.length && next.length > MAX_PROJECT_REVISIONS;) {
    if (isActive(next[i])) i += 1;
    else next.splice(i, 1);
  }
  return next;
}

// The section a song-time instant falls in. Sections are half-open, except the
// window's last one also owns its end instant (a note dropped on the final frame).
function sectionAt(sections, t) {
  const last = sections[sections.length - 1];
  return sections.find((s) => t >= s.startSec - 1e-6 && t < s.endSec - 1e-6)
    || (last && Math.abs(t - last.endSec) <= 1e-6 ? last : null);
}

/**
 * Open a revision from one reviewed excerpt. `sceneIds` (optional) names the
 * sections to reject explicitly; otherwise every section holding a `flagged`
 * note is rejected. Returns `{ project, revision, skippedSceneIds }`.
 */
export function startRevisionOnProject(project, excerptId, { sceneIds } = {}, now = new Date().toISOString()) {
  const active = projectRevisions(project).find(isActive);
  if (active) {
    throw revisionError(409, 'REVISION_IN_PROGRESS', 'Finish or cancel the open revision before starting another', { revisionId: active.id });
  }
  const excerpt = projectExcerpts(project).find((e) => e.id === excerptId);
  if (!excerpt) throw revisionError(404, 'NOT_FOUND', 'Excerpt not found');
  if (excerpt.status !== 'complete') throw revisionError(409, 'EXCERPT_NOT_READY', 'Only a finished draft excerpt can be revised');
  const sections = Array.isArray(excerpt.sections) ? excerpt.sections.filter((s) => isNonBlankStr(s?.sceneId)) : null;
  if (!sections?.length) {
    throw revisionError(422, 'EXCERPT_SECTIONS_UNKNOWN', 'This draft predates section tracking — render the excerpt again to revise it');
  }
  const inWindow = new Set(sections.map((s) => s.sceneId));

  // Notes are timecoded on the excerpt's OWN timeline; sections are in song time.
  const noteIdsByScene = new Map();
  for (const note of excerpt.notes || []) {
    if (note.verdict !== 'flagged') continue;
    const section = sectionAt(sections, excerpt.startSec + note.atSec);
    if (!section) continue;
    noteIdsByScene.set(section.sceneId, [...(noteIdsByScene.get(section.sceneId) || []), note.id]);
  }
  let rejectIds;
  if (Array.isArray(sceneIds)) {
    const outside = sceneIds.filter((id) => !inWindow.has(id));
    if (outside.length) throw revisionError(422, 'SCENE_NOT_IN_EXCERPT', 'Every revised section must be part of this draft excerpt', { sceneIds: outside });
    rejectIds = new Set(sceneIds);
  } else {
    rejectIds = new Set(noteIdsByScene.keys());
  }

  if (codeFirst(project)) {
    assertCodeFirstPlan(project);
    const conflicts = [...rejectIds].filter((sceneId) => !['still', 'generated-footage'].includes(mediumFor(project, sceneId)));
    if (conflicts.length) throw revisionError(409, 'REVISION_MEDIUM_PLAN_CONFLICT',
      'The review flagged a procedural or existing-footage section. Revise its code or selected asset, or explicitly change the medium plan before retrying.',
      { sceneIds: conflicts });
  }

  const scenesById = new Map((project.scenes || []).map((s) => [s.sceneId, s]));
  const skippedSceneIds = [];
  let next = project;
  const revisionSections = [];
  const seen = new Set();
  for (const section of sections) {
    if (seen.has(section.sceneId)) continue; // a scene appears once however it was cut
    seen.add(section.sceneId);
    const scene = scenesById.get(section.sceneId);
    if (!scene) continue; // deleted since the draft — nothing left to keep or revise
    const rejected = rejectIds.has(section.sceneId);
    if (!codeFirst(project) && (section.layer === 'card' || section.layer === 'code')) {
      if (rejected) skippedSceneIds.push(section.sceneId);
      continue;
    }
    const kind = codeFirst(project) ? (mediumFor(project, section.sceneId) === 'still' ? 'image' : 'video')
      : section.layer === 'still' ? 'image' : 'video';
    const assetId = isNonBlankStr(scene[TAKE_SLOT[kind]]) ? scene[TAKE_SLOT[kind]] : null;
    if (rejected && assetId) {
      // Materialize a legacy selection as a take first, so the take id the
      // review below resolves is the one persisted (ensureSceneTakes mints
      // fresh ids on every call for a selection that has no take yet).
      const idx = next.scenes.findIndex((s) => s.sceneId === section.sceneId);
      const withTakes = { ...next.scenes[idx], takes: ensureSceneTakes(next.scenes[idx], now) };
      const scenes = next.scenes.slice();
      scenes[idx] = withTakes;
      next = { ...next, scenes };
      const take = withTakes.takes.find((t) => t.kind === kind && t.assetId === assetId);
      next = reviewSceneTake(next, section.sceneId, take.takeId, { status: 'rejected' }).project;
    }
    revisionSections.push({
      sceneId: section.sceneId,
      layer: section.layer,
      kind,
      verdict: rejected ? 'rejected' : 'approved',
      rejectedAssetId: rejected ? assetId : null,
      keptAssetId: rejected ? null : assetId,
      noteIds: noteIdsByScene.get(section.sceneId) || [],
    });
  }
  if (!revisionSections.some((s) => s.verdict === 'rejected')) {
    throw revisionError(422, 'NOTHING_TO_REVISE', skippedSceneIds.length
      ? 'The flagged sections are title cards — edit their text instead; there is no footage to regenerate'
      : 'Flag a moment in this draft (or pick a section) before revising it', skippedSceneIds.length ? { skippedSceneIds } : undefined);
  }

  const revision = {
    id: `mvr-${randomUUID()}`,
    excerptId,
    startSec: excerpt.startSec,
    endSec: excerpt.endSec,
    status: 'open',
    ...(codeFirst(project) ? { mediumBasis: mediumBasis(project) } : {}),
    sections: revisionSections,
    renderExcerptId: null,
    renderAttempts: 0,
    error: null,
    createdAt: now,
    updatedAt: now,
  };
  return {
    project: { ...next, revisions: pruneRevisions([...projectRevisions(next), revision]), updatedAt: now },
    revision,
    skippedSceneIds,
  };
}

// A job's music-video tag matches this revision's section EXACTLY when it
// carries `revisionId` (#9011) — added by the revision hook at kickoff time,
// so a job another surface tagged with a different (or no) revisionId can
// never be mistaken for this revision's own generation. A job with no
// `revisionId` at all (submitted before this field existed, or a board
// generation never told which revision, if any, is open) falls back to the
// pre-#9011 scene+time heuristic so an in-flight legacy job is still tracked
// through a rolling deploy.
const tagMatches = (job, projectId, sceneId, revision) => {
  const tag = job?.params?.musicVideo;
  if (tag?.projectId !== projectId || tag?.sceneId !== sceneId) return false;
  if (isNonBlankStr(tag.revisionId)) return tag.revisionId === revision.id;
  return typeof job.queuedAt === 'string' && job.queuedAt >= revision.createdAt;
};

const within = (iso, windowMs, nowMs) => {
  const t = typeof iso === 'string' ? Date.parse(iso) : NaN;
  return Number.isFinite(t) && nowMs - t < windowMs;
};

/**
 * Pure: each section of a revision with its current `state`:
 *   - `kept`             — approved; its selection is untouched;
 *   - `removed`          — the scene was deleted since;
 *   - `ready`            — the slot holds a take (a new one landed, or the
 *                          director selected one) — never generated again;
 *   - `generating`       — a generation job for the scene is queued/running,
 *                          finished moments ago but its take hasn't attached
 *                          yet, or a resume claimed it within the lease;
 *   - `needs-generation` — nothing selected and nothing in flight.
 * `jobs` is the media-job queue's list (queued, running and recent archive).
 */
export function revisionSectionStates(project, revision, jobs = [], nowMs = Date.now()) {
  const scenesById = new Map((project.scenes || []).map((s) => [s.sceneId, s]));
  return (revision.sections || []).map((section) => {
    if (section.verdict !== 'rejected') return { ...section, state: 'kept' };
    const scene = scenesById.get(section.sceneId);
    if (!scene) return { ...section, state: 'removed' };
    const selected = (scene.takes || []).find((take) => take.kind === section.kind && take.assetId === scene[TAKE_SLOT[section.kind]]);
    if (isNonBlankStr(scene[TAKE_SLOT[section.kind]]) && !musicVideoTakeChanges(project, scene, selected).length) return { ...section, state: 'ready' };
    const takes = Array.isArray(scene.takes) ? scene.takes : [];
    const pending = jobs.some((job) => job?.kind === section.kind && tagMatches(job, project.id, section.sceneId, revision) && (
      job.status === 'queued' || job.status === 'running'
      // Completed after the revision opened, but its take isn't on the scene
      // yet: the attach hook is still writing it. Asking again would pay twice.
      || (job.status === 'completed' && typeof job.queuedAt === 'string' && job.queuedAt >= revision.createdAt
        && within(job.completedAt, TAKE_ATTACH_GRACE_MS, nowMs) && !takes.some((t) => t.jobId === job.id))
    ));
    const claimed = within(section.claimedAt, GENERATION_CLAIM_LEASE_MS, nowMs);
    return { ...section, state: pending || claimed ? 'generating' : revision.repair?.submitted ? 'review-needed' : 'needs-generation' };
  });
}

/** Find a revision that can still be resumed (open, or rendering). Throws 404/409. */
function resumableRevision(project, revisionId) {
  const revision = findRevision(project, revisionId);
  if (!isActive(revision)) {
    throw revisionError(409, 'REVISION_CLOSED', `This revision is already ${revision.status}`);
  }
  return revision;
}

/**
 * Pure: the live (queued/running) generation jobs a revision started — tagged
 * for one of its rejected sections and queued since it opened. Cancelling the
 * revision cancels these, so no paid work keeps running for a closed revision.
 */
export function revisionGenerationJobs(project, revision, jobs = []) {
  const rejected = (revision.sections || []).filter((s) => s.verdict === 'rejected');
  return jobs.filter((job) => (job?.status === 'queued' || job?.status === 'running')
    && rejected.some((s) => job.kind === s.kind && tagMatches(job, project.id, s.sceneId, revision)));
}

/**
 * Resume's atomic step (run under the record's write serialization): derive
 * every section's state and CLAIM the ones about to be handed out for
 * generation, so two overlapping resumes can never both hand out the same
 * section. Returns `{ project, revision, needsGeneration, generating }` —
 * `revision.sections` carry their derived `state`.
 */
export function claimRevisionGeneration(project, revisionId, jobs = [], nowMs = Date.now()) {
  const revision = resumableRevision(project, revisionId);
  if (revision.type === 'dependencies' && revision.sections.some((section) => musicVideoDependencyChanges(project, section.dependencies).length)) {
    throw revisionError(409, 'DEPENDENCY_REPAIR_CHANGED', 'The repair inputs changed — cancel and preview the affected dependencies again');
  }
  const states = revisionSectionStates(project, revision, jobs, nowMs);
  if (revision.type === 'dependencies' && states.some((section) => section.state === 'needs-generation'
    && project.scenes.find((scene) => scene.sceneId === section.sceneId)?.videoHistoryId)) {
    throw revisionError(409, 'DEPENDENCY_REPAIR_STALE_SELECTION', 'Clear the selected stale clip or select a current replacement before resuming');
  }
  const ref = ({ sceneId, kind }) => ({ sceneId, kind });
  const needsGeneration = states.filter((s) => s.state === 'needs-generation').map(ref);
  const generating = states.filter((s) => s.state === 'generating').map(ref);
  if (!needsGeneration.length) return { project, revision: { ...revision, sections: states }, needsGeneration, generating };
  const claimedAt = new Date(nowMs).toISOString();
  const claimIds = new Set(needsGeneration.map((s) => s.sceneId));
  const next = { ...revision, sections: revision.sections.map((s) => (claimIds.has(s.sceneId) ? { ...s, claimedAt } : s)), updatedAt: claimedAt };
  return {
    project: replaceRevision(project, next),
    revision: { ...next, sections: states.map((s) => (claimIds.has(s.sceneId) ? { ...s, claimedAt } : s)) },
    needsGeneration,
    generating,
  };
}

/**
 * Link a draft re-render to an open revision (same write as the excerpt's
 * creation, so a fast finish can always find the revision it settles).
 */
export function markRevisionRendering(project, revisionId, renderExcerptId, now = new Date().toISOString()) {
  const revision = resumableRevision(project, revisionId);
  if (revision.status === 'rendering') {
    const current = projectExcerpts(project).find((e) => e.id === revision.renderExcerptId);
    if (current?.status === 'rendering') {
      throw revisionError(409, 'REVISION_RENDERING', 'This revision is already rendering its draft', { excerptId: current.id });
    }
  }
  return replaceRevision(project, {
    ...revision,
    status: 'rendering',
    renderExcerptId,
    renderAttempts: (revision.renderAttempts || 0) + 1,
    error: null,
    updatedAt: now,
  });
}

/**
 * Settle every revision whose draft re-render just ended. `complete` closes the
 * revision; an error or a cancel returns it to `open` (resumable — the next
 * resume re-renders without generating anything). A canceled revision stays so.
 */
export function settleRevisionRender(project, excerptId, { status, error = null }, now = new Date().toISOString()) {
  let changed = false;
  const revisions = projectRevisions(project).map((revision) => {
    if (revision.renderExcerptId !== excerptId || revision.status !== 'rendering') return revision;
    changed = true;
    return status === 'complete'
      ? { ...revision, status: 'complete', error: null, updatedAt: now }
      : { ...revision, status: 'open', error: error || 'The draft render was cancelled', updatedAt: now };
  });
  return changed ? { ...project, revisions } : project;
}

/** Cancel a revision. Its rejected takes stay rejected — the director can re-select one. */
export function cancelRevisionOnProject(project, revisionId, now = new Date().toISOString()) {
  const revision = resumableRevision(project, revisionId);
  const next = { ...revision, status: 'canceled', updatedAt: now };
  return { project: replaceRevision(project, next), revision: next, renderExcerptId: revision.status === 'rendering' ? revision.renderExcerptId : null };
}

/**
 * Guard for a generation route's enqueue step (#9011): a video/image request
 * tagged with a `revisionId` that no longer names an open (or rendering)
 * revision is refused BEFORE it reaches the queue, rather than being cancelled
 * moments later by whatever closed the revision. Throws 404/409; a project or
 * revision that no longer exists is treated the same as one that closed —
 * there is nothing left to hand this generation's output to. No-op when the
 * project itself is gone (the route's own lookup reports that separately).
 */
export function assertRevisionOpenForGeneration(project, revisionId, { sceneId = null, kind = null } = {}) {
  if (!project) return null;
  const revision = resumableRevision(project, revisionId);
  if (revision.type === 'dependencies') {
    const section = revision.sections.find((entry) => entry.sceneId === sceneId && entry.kind === kind);
    const scene = project.scenes.find((entry) => entry.sceneId === sceneId);
    if (scene?.[TAKE_SLOT[kind]]) throw revisionError(409, 'REVISION_SECTION_SELECTED', 'This repair section already has a selected clip — clear or review it before submitting again');
    if (!section || musicVideoDependencyChanges(project, section.dependencies).length) {
      throw revisionError(409, 'DEPENDENCY_REPAIR_CHANGED', 'This generation does not match the previewed repair inputs');
    }
  }
  if (revision.repair) {
    const scene = project.scenes?.find((s) => s.sceneId === sceneId);
    const prefix = project.scenes?.find((s) => s.sceneId === revision.repair.sourceSceneId);
    if (kind !== 'video' || sceneId !== revision.repair.suffixSceneId || scene?.performanceRepair?.revisionId !== revisionId
      || prefix?.videoHistoryId !== revision.repair.sourceAssetId || prefix?.endSec !== revision.repair.boundarySec
      || scene?.startSec !== revision.repair.boundarySec || scene?.endSec !== revision.repair.sourceInterval.endSec) {
      throw revisionError(409, 'PERFORMANCE_REPAIR_STALE', 'This generation no longer matches the accepted prefix and repair interval');
    }
  }
  if (revision.mediumBasis || codeFirst(project)) {
    if (!revision.mediumBasis || revision.mediumBasis !== mediumBasis(project)) {
      throw revisionError(409, 'REVISION_MEDIUM_PLAN_CHANGED', 'The medium plan or allowance changed since this revision opened');
    }
    assertCodeFirstPlan(project);
    const section = revision.sections.find((entry) => entry.sceneId === sceneId && entry.verdict === 'rejected');
    const medium = mediumFor(project, sceneId);
    if (!section || section.kind !== kind || (kind === 'video' && medium !== 'generated-footage')
      || (kind === 'image' && medium !== 'still')) {
      throw revisionError(409, 'REVISION_MEDIUM_PLAN_CONFLICT', 'This generation request does not match the approved medium for the rejected section');
    }
  }
  return revision;
}

/**
 * A resume that claimed a section for generation (`claimRevisionGeneration`)
 * but whose kickoff never reached the queue (submission failed client-side or
 * the route refused it) leaves that section claimed for the full lease
 * (`GENERATION_CLAIM_LEASE_MS`) with nothing actually running. Clearing the
 * claim here lets the very next resume hand the section out again immediately
 * instead of waiting out the lease. A no-op if the section isn't found or
 * isn't rejected — best-effort cleanup, never a reason to fail the caller.
 */
export function releaseRevisionClaim(project, revisionId, sceneId, now = new Date().toISOString()) {
  const revision = resumableRevision(project, revisionId);
  const next = {
    ...revision,
    sections: revision.sections.map((s) => (s.sceneId === sceneId && s.verdict === 'rejected' ? { ...s, claimedAt: null, submissionClaimedAt: null } : s)),
    updatedAt: now,
  };
  return { project: replaceRevision(project, next), revision: next };
}

/** Start a previewed dependency repair under the existing serialized checkpoint. */
export function startDependencyRepairOnProject(project, impact, { basis }, now = new Date().toISOString()) {
  const active = projectRevisions(project).find(isActive);
  if (active?.dependencyBasis === basis) return { project, revision: active, skippedSceneIds: [] };
  if (active) throw revisionError(409, 'REVISION_IN_PROGRESS', 'Finish or cancel the open revision before repairing dependencies', { revisionId: active.id });
  if (basis !== impact.basis) throw revisionError(409, 'DEPENDENCY_PREVIEW_CHANGED', 'Assets changed after the repair preview — review the impact again');
  if (!impact.shots.length && !impact.evidence.length) throw revisionError(422, 'NOTHING_TO_REVISE', 'All recorded dependencies are current');
  if (codeFirst(project)) {
    assertCodeFirstPlan(project);
    if (impact.shots.some((shot) => mediumFor(project, shot.sceneId) !== 'generated-footage')) {
      throw revisionError(409, 'REVISION_MEDIUM_PLAN_CONFLICT', 'Select replacement footage for the affected existing-media shot; its approved medium does not permit generation');
    }
  }
  let next = project;
  const sections = [];
  for (const shot of impact.shots) {
    const scene = next.scenes.find((entry) => entry.sceneId === shot.sceneId);
    const withTakes = { ...scene, takes: ensureSceneTakes(scene, now) };
    next = { ...next, scenes: next.scenes.map((entry) => entry.sceneId === scene.sceneId ? withTakes : entry) };
    const take = withTakes.takes.find((entry) => entry.kind === 'video' && entry.assetId === scene.videoHistoryId);
    if (take) next = reviewSceneTake(next, scene.sceneId, take.takeId, { status: 'rejected' }).project;
    sections.push({ sceneId: scene.sceneId, layer: 'footage', kind: 'video', verdict: 'rejected',
      rejectedAssetId: shot.assetId, reasons: shot.reasons,
      // A repair cannot silently continue against another newly selected plate.
      dependencies: captureTakeDependencies(scene), noteIds: [] });
  }
  const ranges = [
    ...impact.shots.map((shot) => project.scenes.find((scene) => scene.sceneId === shot.sceneId)),
    ...impact.evidence.filter((entry) => entry.kind === 'excerpt'),
  ].filter((entry) => typeof entry.startSec === 'number' && typeof entry.endSec === 'number' && entry.endSec > entry.startSec);
  const startSec = ranges.length ? Math.min(...ranges.map((range) => range.startSec)) : 0;
  const endSec = ranges.length ? Math.max(...ranges.map((range) => range.endSec)) : project.audioAnalysis?.durationSec;
  if (!(endSec > startSec)) throw revisionError(422, 'DEPENDENCY_REPAIR_UNTIMED', 'Time the affected shots or analyze the song before repairing');
  const revision = { id: `mvr-${randomUUID()}`, type: 'dependencies', dependencyBasis: basis,
    excerptId: null, startSec, endSec, sections, status: 'open', renderExcerptId: null,
    renderAttempts: 0, error: null, createdAt: now, updatedAt: now,
    ...(codeFirst(project) ? { mediumBasis: mediumBasis(project) } : {}),
  };
  return { project: { ...next, revisions: pruneRevisions([...projectRevisions(next), revision]), updatedAt: now }, revision, skippedSceneIds: [] };
}