videoclaw 3.0.0-alpha.1

package/src/video/providers/xskill.ts

@@ -0,0 +1,304 @@
+/**
+ * xskill.ts — a thin REST client for the apiz.ai / suitui-ai aggregator (also
+ * branded "xskill" / "速推" / "NEX AI"), which fronts the fal.ai post-production
+ * models we need: Topaz video upscale and OmniHuman audio-driven lip-sync.
+ *
+ * It is NOT a per-scene generation route (those go through the storyboard →
+ * execute pipeline). It is the async-task client the new `finish` / `lipsync`
+ * commands call directly:
+ *   xskillSubmit(modelId, params) → taskId
+ *     → xskillAwait(taskId) polls until completed → the output URL
+ *       → xskillDownload(url, dest).
+ *
+ * The HTTP contract (verified against the live API + the MCP tool schemas):
+ *   POST  {base}/api/v3/tasks/create     Bearer <key>   { model_id, params }       → { task_id, status }
+ *   GET   {base}/api/v3/tasks/{task_id}  Bearer <key>                              → { status, result }
+ *   status ∈ pending | processing | completed | failed
+ *   output URL lives in `result` — `result.video.url` (video) / `result.images[].url` (image).
+ * The key is read from APIZ_API_KEY (the official CLI's var) or XSKILL_API_KEY
+ * (kept for continuity); its form is `sk-...`. Transports are injectable so the
+ * whole client is unit-testable offline.
+ */
+
+export const XSKILL_BASE = 'https://api.apiz.ai';
+export const XSKILL_SUBMIT_PATH = '/api/v3/tasks/create';
+export const xskillTaskPath = (taskId: string): string => `/api/v3/tasks/${encodeURIComponent(taskId)}`;
+
+export type XskillTaskStatus = 'pending' | 'processing' | 'completed' | 'failed';
+
+/** Minimal fetch surface for JSON submit/poll — injectable for offline tests. */
+export type XskillFetchLike = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body?: string },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+/** Fetch surface for binary download — injectable for offline tests. */
+export type XskillDownloadFetchLike = (
+  url: string,
+) => Promise<{ ok: boolean; status: number; arrayBuffer(): Promise<ArrayBuffer> }>;
+
+export interface XskillClientOptions {
+  /** Explicit key; falls back to APIZ_API_KEY / XSKILL_API_KEY. */
+  apiKey?: string;
+  /** Base URL override (default {@link XSKILL_BASE}). */
+  baseUrl?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: XskillFetchLike;
+  /** Transient-retry budget for 429/5xx/network errors (default 3). */
+  maxRetries?: number;
+  /** Base backoff between retries, ms (default 800; grows linearly). */
+  retryBackoffMs?: number;
+}
+
+/** Resolve the API key from options/env, or throw a clear, actionable error. */
+export function resolveXskillApiKey(options: XskillClientOptions = {}): string {
+  const env = options.env ?? process.env;
+  const key = options.apiKey ?? env.APIZ_API_KEY ?? env.XSKILL_API_KEY;
+  if (!key) {
+    throw new Error(
+      'xskill: no API key. Create one in the apiz.ai console (sk-...) and `export APIZ_API_KEY=sk-...` ' +
+        '(XSKILL_API_KEY is also accepted).',
+    );
+  }
+  return key;
+}
+
+const TRANSIENT_BODY = /downstream_service_unavailable|temporarily|rate.?limit|try again/i;
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+function authHeaders(key: string): Record<string, string> {
+  return { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' };
+}
+
+/**
+ * A failed xskill HTTP exchange, carrying the status (0 = network error — the
+ * request may or may not have reached the server) and the response/error body
+ * so callers can discriminate failure modes instead of regexing messages.
+ */
+export class XskillHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: string,
+  ) {
+    super(`xskill request failed (${status || '?'}): ${body.slice(0, 300)}`);
+    this.name = 'XskillHttpError';
+  }
+}
+
+/**
+ * Is this status/body worth a transient retry? 429/5xx/transient-message
+ * always; a network error (status 0) ONLY when the request is idempotent —
+ * a dropped POST to the paid task-create endpoint is ambiguous (the task may
+ * already have been created), so re-POSTing risks double spend.
+ */
+function isTransient(status: number, body: string, idempotent: boolean): boolean {
+  if (status === 0) return idempotent;
+  return status === 429 || status >= 500 || TRANSIENT_BODY.test(body);
+}
+
+async function requestWithRetry(
+  fetchImpl: XskillFetchLike,
+  url: string,
+  init: { method: string; headers: Record<string, string>; body?: string },
+  maxRetries: number,
+  backoffMs: number,
+  idempotent: boolean,
+): Promise<{ status: number; text: string }> {
+  let lastErr: { status: number; text: string } | null = null;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    let status = 0;
+    let text = '';
+    try {
+      const res = await fetchImpl(url, init);
+      status = res.status;
+      text = await res.text();
+      if (res.ok) return { status, text };
+    } catch (err) {
+      status = 0;
+      text = (err as Error).message ?? 'network error';
+    }
+    lastErr = { status, text };
+    if (attempt < maxRetries && isTransient(status, text, idempotent)) {
+      await sleep(backoffMs * (attempt + 1));
+      continue;
+    }
+    break;
+  }
+  throw new XskillHttpError(lastErr?.status ?? 0, lastErr?.text ?? '');
+}
+
+function parseJson(text: string): Record<string, unknown> {
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    throw new Error(`xskill: unparseable response body: ${text.slice(0, 200)}`);
+  }
+}
+
+/** Pull the task id from a submit response (`task_id` / `data.task_id` / `id`). */
+function extractTaskId(parsed: Record<string, unknown>): string {
+  const data = (parsed.data as Record<string, unknown> | undefined) ?? parsed;
+  const id = (data.task_id ?? data.id ?? parsed.task_id) as unknown;
+  if (typeof id !== 'string' || !id) {
+    throw new Error(`xskill submit: no task_id in response: ${JSON.stringify(parsed).slice(0, 200)}`);
+  }
+  return id;
+}
+
+/**
+ * Submit an async task. Body is `{ model_id, params }`. If the API rejects
+ * `model_id` with a 4xx validation error, it retries once with the alternate
+ * `model` field name (both appear in the CLI docs). Returns the task id.
+ */
+export async function xskillSubmit(
+  modelId: string,
+  parameters: Record<string, unknown>,
+  options: XskillClientOptions = {},
+): Promise<string> {
+  const key = resolveXskillApiKey(options);
+  const base = options.baseUrl ?? XSKILL_BASE;
+  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as unknown as XskillFetchLike);
+  const maxRetries = options.maxRetries ?? 3;
+  const backoffMs = options.retryBackoffMs ?? 800;
+  const url = `${base}${XSKILL_SUBMIT_PATH}`;
+
+  const submitWith = async (field: 'model_id' | 'model'): Promise<string> => {
+    // The live v3 API keys the input object as `params` (the MCP tool exposes it
+    // as `parameters`, but that name 422s the REST endpoint — verified live).
+    // NOT idempotent: a dropped POST may still have created (and charged) the
+    // task, so network errors are never auto-retried here.
+    const body = JSON.stringify({ [field]: modelId, params: parameters });
+    const { text } = await requestWithRetry(fetchImpl, url, { method: 'POST', headers: authHeaders(key), body }, maxRetries, backoffMs, false);
+    return extractTaskId(parseJson(text));
+  };
+
+  try {
+    return await submitWith('model_id');
+  } catch (err) {
+    // One alternate-field retry, ONLY for a 4xx that actually rejects the
+    // `model_id` field name. The old message-regex (/4\d\d|model|.../) re-POSTed
+    // the paid create endpoint on EVERY 4xx (auth, quota, bad params) and even
+    // on task-id parse failures after a SUCCESSFUL submit (the echoed model id
+    // matched /model/) — masking the original error and risking double spend.
+    // Two live-observed rejection shapes: the body calls `model_id` itself
+    // unknown/invalid, OR (2026-06-11) a FastAPI-style 422 demands the missing
+    // required `model` field ({"type":"missing","loc":["body","model"],
+    // "msg":"Field required"}) while echoing our `model_id` in `input`. Either
+    // way the task was NOT created, so the alternate-field retry is spend-safe.
+    const fieldNameRejection =
+      err instanceof XskillHttpError &&
+      err.status >= 400 && err.status < 500 &&
+      /model_id/i.test(err.body) &&
+      /unknown|unexpected|unrecognized|not (allowed|recognized|supported)|invalid|validation|missing|required/i.test(err.body);
+    if (fieldNameRejection) {
+      return await submitWith('model');
+    }
+    throw err;
+  }
+}
+
+export interface XskillTaskResult {
+  status: XskillTaskStatus;
+  /** Model-specific output container (`result.video.url`, `result.images[].url`, …). */
+  result: Record<string, unknown> | undefined;
+  /** The full parsed response, for diagnostics. */
+  raw: Record<string, unknown>;
+}
+
+/** Poll a task once. Returns the normalized status + result container. */
+export async function xskillPoll(taskId: string, options: XskillClientOptions = {}): Promise<XskillTaskResult> {
+  const key = resolveXskillApiKey(options);
+  const base = options.baseUrl ?? XSKILL_BASE;
+  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as unknown as XskillFetchLike);
+  const maxRetries = options.maxRetries ?? 3;
+  const backoffMs = options.retryBackoffMs ?? 800;
+  const url = `${base}${xskillTaskPath(taskId)}`;
+
+  // Idempotent GET — network drops here ARE retried (a socket blip must not
+  // abort a 10-minute await of a paid, still-running task).
+  const { text } = await requestWithRetry(fetchImpl, url, { method: 'GET', headers: authHeaders(key) }, maxRetries, backoffMs, true);
+  const parsed = parseJson(text);
+  const data = (parsed.data as Record<string, unknown> | undefined) ?? parsed;
+  const status = (data.status ?? parsed.status) as XskillTaskStatus;
+  const result = (data.result ?? parsed.result) as Record<string, unknown> | undefined;
+  return { status, result, raw: parsed };
+}
+
+/** Extract the first output media URL from a task `result` container. */
+export function extractOutputUrl(result: Record<string, unknown> | undefined): string | null {
+  if (!result || typeof result !== 'object') return null;
+  const video = result.video as { url?: unknown } | undefined;
+  if (video && typeof video.url === 'string') return video.url;
+  const images = result.images as Array<{ url?: unknown }> | undefined;
+  if (Array.isArray(images) && images[0] && typeof images[0].url === 'string') return images[0].url;
+  if (typeof (result as { url?: unknown }).url === 'string') return (result as { url: string }).url;
+  // Last resort: a URL-looking string field — but never one whose key suggests
+  // it is an INPUT echo (source/input/origin) or a preview/thumbnail, which
+  // would silently save the uploaded input back as the "finished" output.
+  for (const [k, v] of Object.entries(result)) {
+    if (/source|input|origin|thumb|preview/i.test(k)) continue;
+    if (typeof v === 'string' && /^https?:\/\//.test(v)) return v;
+  }
+  return null;
+}
+
+export interface XskillAwaitOptions extends XskillClientOptions {
+  /** Poll interval, ms (default 5000). */
+  pollIntervalMs?: number;
+  /** Give up after this long, ms (default 600000 = 10 min). */
+  timeoutMs?: number;
+  /** Called after each poll with the latest status (for progress logging). */
+  onTick?: (status: XskillTaskStatus, elapsedMs: number) => void;
+  /** Injected clock (ms) for deterministic tests; defaults to Date.now. */
+  now?: () => number;
+}
+
+export interface XskillCompleted {
+  taskId: string;
+  videoUrl: string;
+  result: Record<string, unknown>;
+}
+
+/**
+ * Poll `taskId` until it completes. Resolves with the output URL on `completed`,
+ * throws on `failed` or when `timeoutMs` elapses. Pure of wall-clock except the
+ * injected `now`/`sleep` (overridable for tests).
+ */
+export async function xskillAwait(taskId: string, options: XskillAwaitOptions = {}): Promise<XskillCompleted> {
+  const interval = options.pollIntervalMs ?? 5000;
+  const timeout = options.timeoutMs ?? 600000;
+  const now = options.now ?? Date.now;
+  const start = now();
+  for (;;) {
+    const { status, result, raw } = await xskillPoll(taskId, options);
+    const elapsed = now() - start;
+    options.onTick?.(status, elapsed);
+    if (status === 'completed') {
+      const videoUrl = extractOutputUrl(result);
+      if (!videoUrl) throw new Error(`xskill: task ${taskId} completed but no output URL in result: ${JSON.stringify(raw).slice(0, 200)}`);
+      return { taskId, videoUrl, result: result ?? {} };
+    }
+    if (status === 'failed') {
+      throw new Error(`xskill: task ${taskId} failed: ${JSON.stringify(raw).slice(0, 300)}`);
+    }
+    if (elapsed >= timeout) {
+      throw new Error(`xskill: task ${taskId} timed out after ${Math.round(elapsed / 1000)}s (last status: ${status}).`);
+    }
+    await sleep(interval);
+  }
+}
+
+/** Download a completed output URL to `dest`. Uses global fetch unless injected. */
+export async function xskillDownload(
+  url: string,
+  dest: string,
+  options: { fetchImpl?: XskillDownloadFetchLike } = {},
+): Promise<string> {
+  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as unknown as XskillDownloadFetchLike);
+  const res = await fetchImpl(url);
+  if (!res.ok) throw new Error(`xskill download failed (${res.status}) for ${url}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(dest, buf);
+  return dest;
+}

package/src/video/readiness.ts

@@ -0,0 +1,284 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { artifactPathFor } from './artifact-store.js';
+import { buildCharacterConsistencyReport } from './character-consistency.js';
+import { readImageDimensions } from './image-dimensions.js';
+import { readReferenceSheetsArtifact } from './reference-sheet-store.js';
+import { sheetsCoveringScene } from './reference-sheets.js';
+import { readSceneCandidatesArtifact, sceneCandidatesPathFor } from './scene-candidate-store.js';
+import { readSceneSelectionArtifact } from './scene-selection-store.js';
+import { readMultiShotPromptArtifactSummary, type MultiShotPromptArtifactSummary } from './multi-shot-artifact.js';
+import { readProjectManifest, resolveProjectWorkspace } from './workspace.js';
+import type { CharacterConsistencyReport, VideoProductionMode } from './types.js';
+import type { ReferenceSheet } from './types.js';
+
+export interface VideoProjectReadiness {
+  slug: string;
+  root: string;
+  productionMode: VideoProductionMode;
+  ready: boolean;
+  requiredArtifacts: string[];
+  presentArtifacts: string[];
+  missingArtifacts: string[];
+  characterConsistency: CharacterConsistencyReport;
+  multiShotPrompt?: MultiShotPromptArtifactSummary;
+  blockers: string[];
+  warnings: string[];
+  nextAction: string;
+}
+
+type ExecutionAspectRatio = '16:9' | '9:16' | '1:1';
+type ExecutionResolution = '720p' | '1080p';
+
+function normalizeAspectRatio(value: unknown): ExecutionAspectRatio | null {
+  return value === '16:9' || value === '9:16' || value === '1:1' ? value : null;
+}
+
+function normalizeResolution(value: unknown): ExecutionResolution | null {
+  return value === '720p' || value === '1080p' ? value : null;
+}
+
+function expectedRatio(value: ExecutionAspectRatio): number {
+  switch (value) {
+    case '16:9':
+      return 16 / 9;
+    case '9:16':
+      return 9 / 16;
+    case '1:1':
+      return 1;
+  }
+}
+
+function minShortEdge(value: ExecutionResolution): number {
+  return value === '1080p' ? 1080 : 720;
+}
+
+async function readImageExecutionProfile(workspace: ReturnType<typeof resolveProjectWorkspace>): Promise<{
+  aspectRatio: ExecutionAspectRatio;
+  resolution: ExecutionResolution;
+}> {
+  const briefPath = artifactPathFor(workspace, 'brief');
+  if (!existsSync(briefPath)) {
+    return { aspectRatio: '16:9', resolution: '720p' };
+  }
+  try {
+    const brief = JSON.parse(await readFile(briefPath, 'utf-8')) as {
+      metadata?: {
+        platform?: string;
+        executionProfile?: Record<string, unknown>;
+      };
+    };
+    const explicitAspectRatio = normalizeAspectRatio(brief.metadata?.executionProfile?.aspectRatio);
+    const platform = String(brief.metadata?.platform ?? '').toLowerCase();
+    const inferredAspectRatio = ['tiktok', 'reels', 'shorts'].includes(platform) ? '9:16' : '16:9';
+    return {
+      aspectRatio: explicitAspectRatio ?? inferredAspectRatio,
+      resolution: normalizeResolution(brief.metadata?.executionProfile?.resolution) ?? '720p',
+    };
+  } catch {
+    return { aspectRatio: '16:9', resolution: '720p' };
+  }
+}
+
+function localAssetPath(workspace: ReturnType<typeof resolveProjectWorkspace>, value: string): string {
+  return isAbsolute(value) ? value : resolve(workspace.projectDir, value);
+}
+
+function identitySheetWarnings(sceneIndex: number, characters: string[], sheets: ReferenceSheet[]): string[] {
+  const warnings: string[] = [];
+  const characterSet = new Set(characters.map((name) => name.toLowerCase()));
+  for (const sheet of sheets.filter((candidate) => candidate.type === 'identity')) {
+    const identityRefs = sheet.references.filter((reference) => reference.role === 'identity').length;
+    if (sheet.characterName && !characterSet.has(sheet.characterName.toLowerCase())) {
+      warnings.push(
+        `reference-sheet-character-mismatch: scene ${sceneIndex} binds Identity Sheet ${sheet.id} for ${sheet.characterName}, but that character is not listed on the scene`,
+      );
+    }
+    if (identityRefs === 0) {
+      warnings.push(
+        `reference-sheet-weak-identity: scene ${sceneIndex} Identity Sheet ${sheet.id} has no identity-role reference`,
+      );
+      continue;
+    }
+    if (identityRefs < 2) {
+      warnings.push(
+        `reference-sheet-thin-identity-coverage: scene ${sceneIndex} Identity Sheet ${sheet.id} has ${identityRefs} identity reference; add front/profile/detail references when continuity matters`,
+      );
+    }
+  }
+  return warnings;
+}
+
+export async function buildProjectReadiness(
+  slug: string,
+  root = process.cwd(),
+  fallbackMode: VideoProductionMode = 'storyboard',
+): Promise<VideoProjectReadiness> {
+  const workspace = resolveProjectWorkspace(slug, root);
+  const manifest = await readProjectManifest(workspace);
+  const productionMode = manifest?.productionMode ?? fallbackMode;
+
+  const requiredArtifacts = ['brief', 'storyboard', 'asset-manifest'];
+  const presentArtifacts = requiredArtifacts.filter((artifact) =>
+    existsSync(artifactPathFor(workspace, artifact as 'brief' | 'storyboard' | 'asset-manifest')),
+  );
+  const missingArtifacts = requiredArtifacts.filter((artifact) => !presentArtifacts.includes(artifact));
+
+  const blockers: string[] = [];
+  const warnings: string[] = [];
+  if (!manifest) {
+    blockers.push('Project manifest is missing.');
+  }
+  if (manifest?.blockedBy && manifest.blockedBy.length > 0) {
+    blockers.push(
+      manifest.blockedReason
+        ? `${manifest.blockedReason} (blocked by: ${manifest.blockedBy.join(', ')})`
+        : `Blocked by: ${manifest.blockedBy.join(', ')}`,
+    );
+  }
+  if (missingArtifacts.length > 0) {
+    blockers.push(`Missing required artifacts: ${missingArtifacts.join(', ')}`);
+  }
+  const characterConsistency = await buildCharacterConsistencyReport(slug, root);
+  blockers.push(...characterConsistency.issues);
+  const multiShotPrompt = await readMultiShotPromptArtifactSummary(workspace);
+  if (multiShotPrompt && multiShotPrompt.valid === false) {
+    warnings.push(
+      `multi-shot-prompt-invalid: ${multiShotPrompt.issueCount} issue(s) recorded; rerun \`vclaw video multi-shot --validate --explain-issues\` before rendering this prompt`,
+    );
+  }
+
+  // Reference-sheet readiness (director-mode only): any scene that binds at least one
+  // character must be covered by at least one Identity Sheet.
+  const missingIdentityScenes: number[] = [];
+  if (productionMode === 'director') {
+    const storyboardPath = artifactPathFor(workspace, 'storyboard');
+    if (existsSync(storyboardPath)) {
+      try {
+        const storyboard = JSON.parse(await readFile(storyboardPath, 'utf-8')) as {
+          scenes?: Array<{ sceneIndex?: number; characters?: string[] }>;
+        };
+        const sheetsArtifact = await readReferenceSheetsArtifact(workspace.root, slug);
+        for (const [i, scene] of (storyboard.scenes ?? []).entries()) {
+          if (!scene.characters || scene.characters.length === 0) continue;
+          const sceneIndex = typeof scene.sceneIndex === 'number' ? scene.sceneIndex : i;
+          const covering = sheetsCoveringScene(sheetsArtifact, sceneIndex);
+          const hasIdentity = covering.some((sheet) => sheet.type === 'identity');
+          if (!hasIdentity) {
+            missingIdentityScenes.push(sceneIndex);
+            blockers.push(
+              `reference-sheet-missing-identity: scene ${sceneIndex} has character bindings but no Identity Sheet is bound to it`,
+            );
+          } else {
+            warnings.push(...identitySheetWarnings(sceneIndex, scene.characters, covering));
+          }
+        }
+      } catch {
+        // Storyboard or sheets unreadable — other blockers will surface it.
+      }
+    }
+  }
+
+  // Scene-candidate selection readiness (feature-gated on the candidates file).
+  // When the project has no `scene-candidates.json` on disk we skip entirely so
+  // legacy projects without candidates continue to advance. When the file does
+  // exist, any scene with ≥1 candidate but no selection blocks review/publish.
+  const scenesMissingSelection: number[] = [];
+  if (existsSync(sceneCandidatesPathFor(workspace.root, slug))) {
+    const candidates = await readSceneCandidatesArtifact(workspace.root, slug);
+    const selection = await readSceneSelectionArtifact(workspace.root, slug);
+    const selectedByScene = new Map<number, string | null>();
+    const rerollByScene = new Map<number, boolean>();
+    for (const entry of selection.scenes) {
+      selectedByScene.set(entry.sceneIndex, entry.selectedCandidateId);
+      rerollByScene.set(entry.sceneIndex, entry.rerollRequested);
+    }
+    for (const entry of candidates.scenes) {
+      // Only scenes with at least one *completed* candidate require a
+      // selection — scenes whose candidates are still pending/failed are
+      // in-flight and shouldn't block further execute runs on sibling scenes.
+      const hasCompleted = entry.candidates.some((c) => c.status === 'completed');
+      if (!hasCompleted) continue;
+      const selected = selectedByScene.get(entry.sceneIndex) ?? null;
+      const rerollRequested = rerollByScene.get(entry.sceneIndex) ?? false;
+      if (!selected && !rerollRequested) {
+        scenesMissingSelection.push(entry.sceneIndex);
+      }
+    }
+    if (scenesMissingSelection.length > 0) {
+      blockers.push(
+        `scene-selection-missing: scene(s) ${scenesMissingSelection.join(', ')} have candidates but no selection`,
+      );
+    }
+  }
+
+  const assetManifestPath = artifactPathFor(workspace, 'asset-manifest');
+  if (existsSync(assetManifestPath)) {
+    try {
+      const assetManifest = JSON.parse(await readFile(assetManifestPath, 'utf-8')) as {
+        assets?: Array<{ id?: string; kind?: string; path?: string; sceneIndex?: number }>;
+      };
+      const profile = await readImageExecutionProfile(workspace);
+      const expected = expectedRatio(profile.aspectRatio);
+      const ratioTolerance = 0.03;
+      for (const asset of assetManifest.assets ?? []) {
+        if (asset.kind !== 'image' || !asset.path) continue;
+        const path = localAssetPath(workspace, asset.path);
+        const label = asset.id ?? asset.path;
+        if (!existsSync(path)) {
+          warnings.push(`image-input-missing: asset ${label} points to missing local image ${asset.path}`);
+          continue;
+        }
+        const dimensions = await readImageDimensions(path);
+        if (!dimensions) {
+          warnings.push(`image-input-unreadable: asset ${label} is not a supported PNG/JPEG image`);
+          continue;
+        }
+        const actualRatio = dimensions.width / dimensions.height;
+        if (Math.abs(actualRatio - expected) > ratioTolerance) {
+          warnings.push(
+            `image-input-aspect-ratio-mismatch: asset ${label} is ${dimensions.width}x${dimensions.height}, expected ${profile.aspectRatio}`,
+          );
+        }
+        const shortEdge = Math.min(dimensions.width, dimensions.height);
+        const minimum = minShortEdge(profile.resolution);
+        if (shortEdge < minimum) {
+          warnings.push(
+            `image-input-low-resolution: asset ${label} is ${dimensions.width}x${dimensions.height}, below ${profile.resolution} short-edge target ${minimum}px`,
+          );
+        }
+      }
+    } catch {
+      warnings.push('image-input-check-skipped: asset-manifest could not be parsed for image readiness checks');
+    }
+  }
+
+  const ready = blockers.length === 0;
+  const nextAction = ready
+    ? 'Project is ready for execution/runtime wiring.'
+    : missingArtifacts.length > 0
+      ? `Create missing artifacts: ${missingArtifacts.join(', ')}`
+      : characterConsistency.issues.length > 0
+        ? 'Resolve character consistency issues before execution.'
+      : missingIdentityScenes.length > 0
+        ? `Bind an Identity Sheet to scene(s) ${missingIdentityScenes.join(', ')} before execution.`
+      : scenesMissingSelection.length > 0
+        ? `Select a candidate for scene(s) ${scenesMissingSelection.join(', ')} before review.`
+      : blockers[0] ?? 'Resolve project blockers.';
+
+  return {
+    slug,
+    root: workspace.root,
+    productionMode,
+    ready,
+    requiredArtifacts,
+    presentArtifacts,
+    missingArtifacts,
+    characterConsistency,
+    ...(multiShotPrompt ? { multiShotPrompt } : {}),
+    blockers,
+    warnings,
+    nextAction,
+  };
+}

package/src/video/reference-sheet-store.ts

@@ -0,0 +1,40 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { resolveProjectWorkspace } from './workspace.js';
+import { writeTextFileAtomic } from './atomic-write.js';
+import type { ReferenceSheetsArtifact } from './types.js';
+import { validateArtifact } from './reference-sheets.js';
+
+export function referenceSheetsPathFor(root: string, slug: string): string {
+  return join(resolveProjectWorkspace(slug, root).projectDir, 'references', 'reference-sheets.json');
+}
+
+export async function readReferenceSheetsArtifact(
+  root: string,
+  slug: string,
+): Promise<ReferenceSheetsArtifact> {
+  const path = referenceSheetsPathFor(root, slug);
+  if (!existsSync(path)) {
+    return { schemaVersion: 1, sheets: [] };
+  }
+  const raw = await readFile(path, 'utf8');
+  const parsed = JSON.parse(raw) as ReferenceSheetsArtifact;
+  const result = validateArtifact(parsed);
+  if (!result.ok) {
+    throw new Error(
+      `invalid reference-sheets artifact at ${path}: ${result.errors.join(', ')}`,
+    );
+  }
+  return parsed;
+}
+
+export async function writeReferenceSheetsArtifact(
+  root: string,
+  slug: string,
+  artifact: ReferenceSheetsArtifact,
+): Promise<void> {
+  const path = referenceSheetsPathFor(root, slug);
+  await mkdir(dirname(path), { recursive: true });
+  await writeTextFileAtomic(path, JSON.stringify(artifact, null, 2) + '\n');
+}