@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/pipeline/review.ts

@@ -0,0 +1,642 @@
+/**
+ * The quality gate. `reviewPackage()` runs a list of checks on a video before it is rendered, and `reviewRendered()`
+ * runs more on the finished file. Each check has a stable id, a severity, a plain message, and a Fix.
+ *
+ * Severity decides the job's outcome: any failed `compliance` check blocks the job (no retry); a failed `quality`
+ * check rejects it (after one automatic re-render when the check ran on a rendered file). See `gateOutcome()`.
+ */
+import { execFile } from "node:child_process";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import {
+  COMPLIANCE_CHECKLIST,
+  buildFacebookFinish,
+  buildInstagramContainer,
+  buildTikTokInit,
+  buildYouTubeMetadata,
+  claimsAdvicePersona,
+  longestSharedWordRun,
+} from "@vfrey/contracts";
+import type { Account, ContentPackage, Platform } from "@vfrey/contracts";
+import { SCRIPT_LIMITS } from "../generate/script.js";
+import { labelPosition, labelSize } from "../scene/label.js";
+import { sanitizeSvg } from "../scene/sanitize.js";
+import { checkScene, SceneError } from "../scene/scene.js";
+import type { RenderedVideo } from "../render/probe.js";
+
+export type CheckSeverity = "quality" | "compliance";
+export type CheckPhase = "before" | "after";
+
+export interface CheckResult {
+  /** Stable. The run page, the tick summary, and `--json` all key on it. */
+  id: string;
+  phase: CheckPhase;
+  severity: CheckSeverity;
+  /** `skipped` means the check could not run (a tool is missing, or nothing was rendered). It never fails a job. */
+  status: "pass" | "fail" | "skipped";
+  message: string;
+  /** How to make a failed check pass. Null when the check passed. */
+  fix: string | null;
+  /** 1 for the first review of this phase; 2 after the automatic re-render. */
+  attempt: number;
+}
+
+/** Every threshold in one place, so the tests and the skill text quote the same numbers. */
+export const THRESHOLDS = {
+  /** Words a voice reads per second. The same figure `linesToBeats` uses to time a beat. */
+  wordsPerSecond: 2.6,
+  /** How long the words take to say, before any voice exists. A short outside this is a stub or a lecture. */
+  spokenMinSec: 6,
+  spokenMaxSec: 75,
+  /** Measured pace on the finished video: words over the voice's real length. Outside this it races or drags. */
+  paceMinWps: 1.4,
+  paceMaxWps: 3.8,
+  /** Word count against the series' target length (`plan.durationTargetSec` at 2.6 words per second). */
+  lengthMinRatio: 0.25,
+  lengthMaxRatio: 1.8,
+  /** A scene file that can run script or touch the network is not shipped; the scene folder limit is in scene.ts. */
+  /** Rendered length against the voice length. */
+  durationToleranceSec: 2,
+  durationToleranceRatio: 0.15,
+  /** The picture is a 9:16 short. */
+  width: 1080,
+  height: 1920,
+  /** Black for more than this share of the video. */
+  blackShare: 0.5,
+  /** Frozen (no change between sampled frames) for more than this share of the video. */
+  frozenShare: 0.9,
+  /** Share of the label's border pixels that must be found where the label is burned. */
+  labelMatchShare: 0.4,
+} as const;
+
+const result = (partial: Omit<CheckResult, "attempt" | "fix"> & { fix?: string | null }, attempt: number): CheckResult => ({
+  fix: null,
+  ...partial,
+  attempt,
+});
+
+function pass(id: string, phase: CheckPhase, severity: CheckSeverity, message: string, attempt: number): CheckResult {
+  return result({ id, phase, severity, status: "pass", message }, attempt);
+}
+
+function fail(id: string, phase: CheckPhase, severity: CheckSeverity, message: string, fix: string, attempt: number): CheckResult {
+  return result({ id, phase, severity, status: "fail", message, fix }, attempt);
+}
+
+function skipped(id: string, phase: CheckPhase, severity: CheckSeverity, message: string, attempt: number): CheckResult {
+  return result({ id, phase, severity, status: "skipped", message }, attempt);
+}
+
+const wordCount = (text: string): number => text.split(/\s+/).filter(Boolean).length;
+
+/** Words in a script, the same count the checks use. */
+export const wordTotal = (script: string | null | undefined): number => wordCount(script ?? "");
+
+// ------------------------------------------------------------------ script and copy
+
+const PLACEHOLDER = /lorem ipsum|\bdolor sit amet\b|\bTODO\b|\bTBD\b|\bFIXME\b|\[(?:insert|your|add)[^\]]*\]|\{\{[^}]*\}\}|<(?:insert|your)[^>]*>|your (?:text|script|copy|title) here|\bxxx+\b/i;
+
+/** Claims a short may not make: a promise of money, a cure, or no risk. Compliance, because the platforms act on them. */
+export const BANNED_CLAIMS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /\bguaranteed? (?:returns?|profits?|income|results?|to (?:make|earn|win))\b/i, label: "a guaranteed return" },
+  { pattern: /\b(?:get|getting) rich quick\b|\bmake \$?\d[\d,]*\s*(?:a|per|every) (?:day|week|month)\b/i, label: "an income promise" },
+  { pattern: /\b(?:risk[- ]free|no risk at all|cannot lose|can't lose)\b/i, label: "a no-risk promise" },
+  { pattern: /\b(?:cures?|cured|reverses?) (?:cancer|diabetes|alzheimer'?s|covid|depression|arthritis)\b/i, label: "a medical cure claim" },
+];
+
+export interface ScriptInput {
+  content: ContentPackage;
+}
+
+/** Pure. The copy and pace checks, run on the package before anything is rendered. */
+export function checkScript(input: ScriptInput, attempt = 1): CheckResult[] {
+  const { content } = input;
+  const out: CheckResult[] = [];
+  const spoken = (content.voiceoverScript ?? "").split("\n");
+  const lines = spoken.map((line) => line.trim());
+  const words = wordCount(lines.join(" "));
+
+  const empties = lines.map((line, index) => (line ? -1 : index)).filter((index) => index >= 0);
+  if (words === 0 || empties.length > 0) {
+    out.push(
+      fail(
+        "copy.empty",
+        "before",
+        "quality",
+        words === 0 ? "The script has no spoken words." : `The script has ${empties.length} empty line${empties.length === 1 ? "" : "s"} (line ${empties.map((i) => i + 1).join(", ")}).`,
+        "write every line, or remove the empty ones, in the --script file.",
+        attempt,
+      ),
+    );
+  } else {
+    out.push(pass("copy.empty", "before", "quality", "Every line has words.", attempt));
+  }
+
+  const long = lines.map((line, index) => ({ index, length: line.length })).filter((item) => item.length > SCRIPT_LIMITS.lineMax);
+  out.push(
+    long.length > 0
+      ? fail(
+          "copy.line-length",
+          "before",
+          "quality",
+          `Line ${long[0]!.index + 1} is ${long[0]!.length} characters; the limit is ${SCRIPT_LIMITS.lineMax}.`,
+          `split it into shorter spoken lines of ${SCRIPT_LIMITS.lineMax} characters or fewer.`,
+          attempt,
+        )
+      : pass("copy.line-length", "before", "quality", `No line is longer than ${SCRIPT_LIMITS.lineMax} characters.`, attempt),
+  );
+
+  const target = content.plan?.durationTargetSec;
+  if (target && words > 0) {
+    const targetWords = target * THRESHOLDS.wordsPerSecond;
+    const min = Math.round(targetWords * THRESHOLDS.lengthMinRatio);
+    const max = Math.round(targetWords * THRESHOLDS.lengthMaxRatio);
+    out.push(
+      words < min || words > max
+        ? fail(
+            "copy.length",
+            "before",
+            "quality",
+            `The script is ${words} words; this series' length target of ${target} s fits ${min} to ${max}.`,
+            words < min ? `add lines: about ${Math.round(targetWords)} words reads in ${target} s.` : `cut lines: about ${Math.round(targetWords)} words reads in ${target} s.`,
+            attempt,
+          )
+        : pass("copy.length", "before", "quality", `${words} words, inside ${min} to ${max} for a ${target} s target.`, attempt),
+    );
+  }
+
+  const text = [content.title, content.hook, lines.join(" ")].join(" ");
+  const holder = PLACEHOLDER.exec(text);
+  out.push(
+    holder
+      ? fail("copy.placeholder", "before", "quality", `The copy holds placeholder text ("${holder[0]}").`, "replace it with the real words in the --script file.", attempt)
+      : pass("copy.placeholder", "before", "quality", "No placeholder or lorem text.", attempt),
+  );
+
+  const claim = BANNED_CLAIMS.find((item) => item.pattern.test(text));
+  const persona = claimsAdvicePersona(text);
+  const source = content.candidate ? `${content.candidate.title} ${content.candidate.excerpt}` : "";
+  const run = source ? longestSharedWordRun(lines.join(" "), source) : 0;
+  if (claim) {
+    out.push(fail("copy.claims", "before", "compliance", `The copy makes ${claim.label}, which platforms treat as a deceptive claim.`, "remove the claim or say what the evidence actually shows.", attempt));
+  } else if (persona) {
+    out.push(fail("copy.claims", "before", "compliance", "The script speaks as a doctor, lawyer, or financial adviser giving advice.", "rewrite it as information, not as a professional's advice.", attempt));
+  } else if (run >= 12) {
+    out.push(fail("copy.claims", "before", "compliance", `The script shares a ${run}-word run with its source; that is reused content.`, "put the idea in your own words.", attempt));
+  } else {
+    out.push(pass("copy.claims", "before", "compliance", "No banned claim, adviser persona, or copied source run.", attempt));
+  }
+
+  if (words > 0) {
+    // The planned seconds are the template's band, not the voice's, so pace is judged on how long the words take to say.
+    const spokenSec = Math.round((words / THRESHOLDS.wordsPerSecond) * 10) / 10;
+    out.push(
+      spokenSec < THRESHOLDS.spokenMinSec || spokenSec > THRESHOLDS.spokenMaxSec
+        ? fail(
+            "pace",
+            "before",
+            "quality",
+            `${words} words take about ${spokenSec} s to say at ${THRESHOLDS.wordsPerSecond} words per second; a short runs ${THRESHOLDS.spokenMinSec} to ${THRESHOLDS.spokenMaxSec} s.`,
+            spokenSec < THRESHOLDS.spokenMinSec ? `add lines: at least ${Math.ceil(THRESHOLDS.spokenMinSec * THRESHOLDS.wordsPerSecond)} words.` : `cut lines: at most ${Math.floor(THRESHOLDS.spokenMaxSec * THRESHOLDS.wordsPerSecond)} words.`,
+            attempt,
+          )
+        : pass("pace", "before", "quality", `About ${spokenSec} s of speech, inside ${THRESHOLDS.spokenMinSec} to ${THRESHOLDS.spokenMaxSec} s.`, attempt),
+    );
+  }
+  return out;
+}
+
+// ------------------------------------------------------------------ disclosure
+
+export interface DisclosureInput {
+  content: ContentPackage;
+  account: Pick<Account, "platforms" | "language">;
+  /** `vfrey` when vfrey overlays the label on the finished file (agent-written scenes); `template` when the built-in template draws it. */
+  label: "vfrey" | "template";
+}
+
+function platformProof(platform: Platform, content: ContentPackage, account: DisclosureInput["account"]): { value: unknown; field: string } | null {
+  try {
+    if (platform === "youtube") {
+      const settings = account.platforms.youtube;
+      const built = buildYouTubeMetadata({
+        title: content.title,
+        description: content.description,
+        tags: content.hashtags,
+        categoryId: settings?.categoryId ?? "27",
+        privacyStatus: settings?.privacyStatus ?? "private",
+        madeForKids: settings?.madeForKids ?? false,
+        language: account.language ?? "en",
+      });
+      return built.proof;
+    }
+    if (platform === "tiktok") {
+      const settings = account.platforms.tiktok;
+      return buildTikTokInit({
+        caption: content.caption,
+        privacyLevel: "SELF_ONLY",
+        disableComment: settings?.disableComment ?? false,
+        coverTimestampMs: 0,
+        brandContent: settings?.brandContent ?? false,
+        brandOrganic: settings?.brandOrganic ?? false,
+        videoSize: 1,
+        chunkSize: 1,
+        totalChunkCount: 1,
+        audited: false,
+        privacyOptions: ["SELF_ONLY"],
+      }).proof;
+    }
+    if (platform === "instagram") return buildInstagramContainer({ caption: content.caption, shareToFeed: account.platforms.instagram?.shareToFeed ?? true }).proof;
+    return buildFacebookFinish({ videoId: "check", title: content.title, description: content.description }).proof;
+  } catch {
+    return null;
+  }
+}
+
+/** Pure. The label will be burned, and every platform the series publishes to carries its AI-content field. */
+export function checkDisclosure(input: DisclosureInput, attempt = 1): CheckResult[] {
+  const out: CheckResult[] = [];
+  out.push(
+    pass(
+      "disclosure.label",
+      "before",
+      "compliance",
+      input.label === "vfrey" ? "vfrey burns the AI-GENERATED label on the finished video." : "The AI-GENERATED label is part of the built-in template, on every frame.",
+      attempt,
+    ),
+  );
+  const enabled = (["youtube", "tiktok", "instagram", "facebook"] as Platform[]).filter((platform) => input.account.platforms[platform]?.enabled);
+  if (enabled.length === 0) {
+    out.push(skipped("disclosure.platform", "before", "compliance", "No platform is enabled, so there is no platform field to set.", attempt));
+    return out;
+  }
+  const missing: string[] = [];
+  for (const platform of enabled) {
+    const wanted = COMPLIANCE_CHECKLIST.find((item) => item.platform === platform);
+    const proof = platformProof(platform, input.content, input.account);
+    if (!proof || proof.value !== true || (wanted && proof.field !== wanted.field)) missing.push(wanted?.field ? `${platform} (${wanted.field})` : platform);
+  }
+  out.push(
+    missing.length > 0
+      ? fail(
+          "disclosure.platform",
+          "before",
+          "compliance",
+          `The platform AI-content field would not be set for ${missing.join(", ")}.`,
+          "do not publish there until vfrey sets the field; run `npx vfrey doctor` and update vfrey.",
+          attempt,
+        )
+      : pass("disclosure.platform", "before", "compliance", `The AI-content field is set for ${enabled.join(", ")}.`, attempt),
+  );
+  return out;
+}
+
+// ------------------------------------------------------------------ scene
+
+const TEXT_EXT = new Set([".html", ".htm", ".css", ".js", ".mjs", ".ts", ".tsx", ".jsx", ".svg"]);
+/** The pinned GSAP script tags vfrey rewrites to its local copy. They are the one allowed address. */
+const GSAP_TAG = /<script\b[^>]*\bsrc\s*=\s*["']https?:\/\/(?:cdn\.jsdelivr\.net\/npm\/gsap@[^"']*|cdnjs\.cloudflare\.com\/ajax\/libs\/gsap\/[^"']*|unpkg\.com\/gsap[^"']*|code\.jquery\.com\/[^"']*gsap[^"']*)["'][^>]*>\s*<\/script>/gi;
+const EXTERNAL = /(?:\b(?:src|href|poster|data|action)\s*=\s*["']\s*(?:https?:)?\/\/[^"']+|url\(\s*["']?\s*(?:https?:)?\/\/[^)"']+|@import\s+(?:url\()?["']?\s*(?:https?:)?\/\/[^"')]+|\bfrom\s+["']https?:\/\/[^"']+|\bimport\(\s*["']https?:\/\/[^"']+|\bfetch\(\s*["']https?:\/\/[^"']+|\bnew\s+(?:WebSocket|EventSource)\(\s*["']\s*(?:https?|wss?):\/\/[^"']+)/i;
+
+async function sceneFiles(dir: string, base = dir): Promise<string[]> {
+  const out: string[] = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === ".git" || (dir === base && entry.name === "vfrey")) continue;
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await sceneFiles(abs, base)));
+    else if (entry.isFile()) out.push(abs);
+  }
+  return out;
+}
+
+export interface SceneInput {
+  dir: string;
+  engineId: string;
+}
+
+/** The scene checks. They read the folder, so they are async; each failure names the file. */
+export async function checkSceneFolder(input: SceneInput, attempt = 1): Promise<CheckResult[]> {
+  const out: CheckResult[] = [];
+  try {
+    const info = await checkScene(input.dir, input.engineId);
+    out.push(pass("scene.entry", "before", "quality", `The scene has its ${info.kind === "html" ? "index.html" : "index.tsx"} for this engine.`, attempt));
+    out.push(pass("scene.size", "before", "quality", `${info.files} files, ${(info.bytes / 1024 / 1024).toFixed(1)} MB, inside the limit.`, attempt));
+  } catch (error) {
+    if (!(error instanceof SceneError)) throw error;
+    const id = error.code === "scene_too_large" ? "scene.size" : "scene.entry";
+    out.push(fail(id, "before", "quality", error.message, error.fix, attempt));
+    if (id === "scene.entry") return out;
+    out.push(pass("scene.entry", "before", "quality", "The scene has its entry file.", attempt));
+  }
+  const files = await sceneFiles(input.dir).catch(() => [] as string[]);
+  const badSvg: string[] = [];
+  const stripped: string[] = [];
+  const external: string[] = [];
+  for (const file of files) {
+    const ext = path.extname(file).toLowerCase();
+    const rel = path.relative(input.dir, file).split(path.sep).join("/");
+    if (!TEXT_EXT.has(ext)) continue;
+    if ((await stat(file)).size > 8 * 1024 * 1024) continue;
+    const text = await readFile(file, "utf8");
+    if (ext === ".svg") {
+      const checked = sanitizeSvg(text);
+      if (!checked.ok) badSvg.push(`${rel}: ${checked.message}`);
+      else if (checked.removed.length > 0) stripped.push(rel);
+    }
+    const found = EXTERNAL.exec(text.replace(GSAP_TAG, "").replace(/xmlns(?::\w+)?\s*=\s*["'][^"']*["']/gi, ""));
+    if (found) external.push(`${rel} (${found[0].slice(0, 60).replace(/\s+/g, " ")})`);
+  }
+  out.push(
+    badSvg.length > 0
+      ? fail("scene.svg", "before", "quality", `An SVG cannot be used: ${badSvg[0]}.`, "redraw that SVG without entities or scripts, or remove it from the scene folder.", attempt)
+      : pass("scene.svg", "before", "quality", stripped.length > 0 ? `SVGs are clean; unsafe parts were stripped from ${stripped.join(", ")}.` : "Every SVG passed the sanitizer.", attempt),
+  );
+  // A scene that reaches for the network is not refused: a render has no network, so the request fails fast and the
+  // run records a warning (see net-guard.ts). The check passes and says so, so the run page shows it.
+  out.push(
+    pass(
+      "scene.external-url",
+      "before",
+      "quality",
+      external.length > 0
+        ? `The scene points at the network (${external[0]}). A render has no network, so it will not load; the run records a warning. Put the file in the scene folder to use it.`
+        : "The scene loads nothing from the network.",
+      attempt,
+    ),
+  );
+  return out;
+}
+
+// ------------------------------------------------------------------ reviewPackage
+
+export interface ReviewPackageInput {
+  content: ContentPackage;
+  account: Pick<Account, "platforms" | "language">;
+  /** The agent-written scene the render will use, or null for the default template. */
+  scene: SceneInput | null;
+  attempt?: number;
+}
+
+/** Everything that can be checked before a render. Scene checks run only when there is a scene folder to read. */
+export async function reviewPackage(input: ReviewPackageInput): Promise<CheckResult[]> {
+  const attempt = input.attempt ?? 1;
+  const out = [...checkScript({ content: input.content }, attempt)];
+  if (input.scene) out.push(...(await checkSceneFolder(input.scene, attempt)));
+  out.push(...checkDisclosure({ content: input.content, account: input.account, label: input.scene ? "vfrey" : "template" }, attempt));
+  return out;
+}
+
+// ------------------------------------------------------------------ after the render
+
+/** What the after-render checks read from the file. Tests pass fakes; the pipeline passes `realTools`. */
+export interface ReviewTools {
+  /** False when ffprobe or ffmpeg is not installed: the after-render checks are skipped, not failed. */
+  available(): Promise<boolean>;
+  probe(file: string): Promise<RenderedVideo | null>;
+  voiceSeconds(file: string): Promise<number | null>;
+  /** Seconds black, seconds frozen, from a sampled pass. Null when the pass failed. */
+  sampleMotion(file: string, durationSec: number): Promise<{ blackSec: number; frozenSec: number } | null>;
+  /** The share of the label's border colour found where the label is burned (0 to 1). Null when it could not be read. */
+  labelMatch(file: string, atSec: number): Promise<number | null>;
+}
+
+export interface ReviewRenderedInput {
+  file: string;
+  /** The voice file, when there is one. The video should be as long as the voice. */
+  voicePath: string | null;
+  /** Words in the script, for the measured pace. */
+  words?: number;
+  /** True when vfrey burned the label (an agent-written scene). Template renders draw it inside the picture. */
+  labelBurned: boolean;
+  tools: ReviewTools;
+  attempt?: number;
+}
+
+/** True when the rendered video could pass every after-render check; `fail` results say why not. */
+export async function reviewRendered(input: ReviewRenderedInput): Promise<CheckResult[]> {
+  const attempt = input.attempt ?? 1;
+  const { tools } = input;
+  if (!(await tools.available())) {
+    return ["frames.readable", "frames.duration", "pace.measured", "frames.resolution", "frames.black", "frames.frozen", "label.present"].map((id) =>
+      skipped(id, "after", id === "label.present" ? "compliance" : "quality", "ffprobe and ffmpeg are not installed, so the rendered file was not inspected.", attempt),
+    );
+  }
+  const out: CheckResult[] = [];
+  const probe = await tools.probe(input.file);
+  if (!probe) {
+    out.push(fail("frames.readable", "after", "quality", "The rendered file is not a readable video.", "render again; if it repeats, run `npx vfrey doctor` and check the engine.", attempt));
+    out.push(skipped("label.present", "after", "compliance", "There is no readable video to look for the label in.", attempt));
+    return out;
+  }
+  out.push(pass("frames.readable", "after", "quality", `A ${probe.width}×${probe.height} video of ${probe.durationSec} s.`, attempt));
+
+  const voice = input.voicePath ? await tools.voiceSeconds(input.voicePath) : null;
+  if (voice) {
+    const allowed = Math.max(THRESHOLDS.durationToleranceSec, voice * THRESHOLDS.durationToleranceRatio);
+    const gap = Math.abs(probe.durationSec - voice);
+    out.push(
+      gap > allowed
+        ? fail(
+            "frames.duration",
+            "after",
+            "quality",
+            `The video is ${probe.durationSec} s and the voice is ${Math.round(voice * 10) / 10} s; they may differ by ${Math.round(allowed * 10) / 10} s.`,
+            "make the picture last as long as the voice: end the scene at the last line's end time.",
+            attempt,
+          )
+        : pass("frames.duration", "after", "quality", `${probe.durationSec} s against a ${Math.round(voice * 10) / 10} s voice.`, attempt),
+    );
+  } else {
+    out.push(
+      probe.durationSec < 1
+        ? fail("frames.duration", "after", "quality", `The video is ${probe.durationSec} s long.`, "render again; a short has at least a few seconds.", attempt)
+        : pass("frames.duration", "after", "quality", `${probe.durationSec} s (no voice to compare with).`, attempt),
+    );
+  }
+
+  // Without a voice the picture's length is the template's, not a reading speed, so there is no pace to measure.
+  if (input.words && input.words > 0 && voice) {
+    const basis = voice;
+    const wps = input.words / basis;
+    const rounded = Math.round(wps * 10) / 10;
+    out.push(
+      wps < THRESHOLDS.paceMinWps || wps > THRESHOLDS.paceMaxWps
+        ? fail(
+            "pace.measured",
+            "after",
+            "quality",
+            `${input.words} words over ${Math.round(basis * 10) / 10} s is ${rounded} words per second; a viewer can follow ${THRESHOLDS.paceMinWps} to ${THRESHOLDS.paceMaxWps}.`,
+            wps > THRESHOLDS.paceMaxWps ? "cut words or lengthen the picture; the voice races." : "add words or shorten the picture; the voice drags.",
+            attempt,
+          )
+        : pass("pace.measured", "after", "quality", `${rounded} words per second, inside ${THRESHOLDS.paceMinWps} to ${THRESHOLDS.paceMaxWps}.`, attempt),
+    );
+  }
+
+  out.push(
+    probe.width !== THRESHOLDS.width || probe.height !== THRESHOLDS.height
+      ? fail(
+          "frames.resolution",
+          "after",
+          "quality",
+          `The video is ${probe.width}×${probe.height}; a short is ${THRESHOLDS.width}×${THRESHOLDS.height}.`,
+          `make the scene root ${THRESHOLDS.width}×${THRESHOLDS.height}.`,
+          attempt,
+        )
+      : pass("frames.resolution", "after", "quality", `${THRESHOLDS.width}×${THRESHOLDS.height}.`, attempt),
+  );
+
+  const motion = await tools.sampleMotion(input.file, probe.durationSec);
+  if (!motion) {
+    out.push(skipped("frames.black", "after", "quality", "The frames could not be sampled.", attempt));
+    out.push(skipped("frames.frozen", "after", "quality", "The frames could not be sampled.", attempt));
+  } else {
+    const black = motion.blackSec / probe.durationSec;
+    const frozen = motion.frozenSec / probe.durationSec;
+    const pct = (value: number) => `${Math.round(value * 100)}%`;
+    out.push(
+      black > THRESHOLDS.blackShare
+        ? fail("frames.black", "after", "quality", `${pct(black)} of the video is black.`, "the scene drew nothing: check that its background and text are painted at the first frame.", attempt)
+        : pass("frames.black", "after", "quality", `${pct(black)} black, under ${pct(THRESHOLDS.blackShare)}.`, attempt),
+    );
+    out.push(
+      frozen > THRESHOLDS.frozenShare
+        ? fail("frames.frozen", "after", "quality", `${pct(frozen)} of the video does not change.`, "the scene's animation did not run: drive it from the timeline, not from timers or requestAnimationFrame.", attempt)
+        : pass("frames.frozen", "after", "quality", `${pct(frozen)} frozen, under ${pct(THRESHOLDS.frozenShare)}.`, attempt),
+    );
+  }
+
+  if (!input.labelBurned) {
+    out.push(pass("label.present", "after", "compliance", "The AI-GENERATED label is drawn by the built-in template.", attempt));
+  } else {
+    const match = await tools.labelMatch(input.file, probe.durationSec / 2);
+    out.push(
+      match === null
+        ? skipped("label.present", "after", "compliance", "The label position could not be read.", attempt)
+        : match < THRESHOLDS.labelMatchShare
+          ? fail(
+              "label.present",
+              "after",
+              "compliance",
+              `The AI-GENERATED label was not found in the finished video (${Math.round(match * 100)}% of its border, needs ${Math.round(THRESHOLDS.labelMatchShare * 100)}%).`,
+              "do not publish this file; render again so vfrey burns the label, and do not draw over the bottom right corner.",
+              attempt,
+            )
+          : pass("label.present", "after", "compliance", "The AI-GENERATED label is on the finished video.", attempt),
+    );
+  }
+  return out;
+}
+
+// ------------------------------------------------------------------ real tools
+
+const SKY: [number, number, number] = [0x90, 0xca, 0xf9];
+
+/** Share of the label's border pixels that are sky-blue in a raw rgb24 crop of the label rectangle. Pure. */
+export function labelBorderMatch(rgb: Buffer, width: number, height: number, border = 3): number {
+  let border_ = 0;
+  let found = 0;
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      if (!(x < border || y < border || x >= width - border || y >= height - border)) continue;
+      border_ += 1;
+      const at = (y * width + x) * 3;
+      if (Math.abs(rgb[at]! - SKY[0]) < 40 && Math.abs(rgb[at + 1]! - SKY[1]) < 40 && Math.abs(rgb[at + 2]! - SKY[2]) < 40) found += 1;
+    }
+  }
+  return border_ === 0 ? 0 : found / border_;
+}
+
+/** Adds up the lengths ffmpeg prints for black and frozen stretches. Pure. */
+export function parseMotionLog(log: string): { blackSec: number; frozenSec: number } {
+  let blackSec = 0;
+  let frozenSec = 0;
+  for (const match of log.matchAll(/black_duration:([\d.]+)/g)) blackSec += Number(match[1]);
+  for (const match of log.matchAll(/freeze_duration:\s*([\d.]+)/g)) frozenSec += Number(match[1]);
+  return { blackSec, frozenSec };
+}
+
+type Env = Record<string, string | undefined>;
+
+export function realTools(env: Env = process.env): ReviewTools {
+  const exec = promisify(execFile);
+  const opts = { env: env as NodeJS.ProcessEnv, timeout: 5 * 60_000, maxBuffer: 32 * 1024 * 1024 };
+  return {
+    async available() {
+      try {
+        await exec("ffprobe", ["-version"], { env: env as NodeJS.ProcessEnv, timeout: 15_000 });
+        await exec("ffmpeg", ["-version"], { env: env as NodeJS.ProcessEnv, timeout: 15_000 });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    async probe(file) {
+      const { probeVideo } = await import("../render/probe.js");
+      return probeVideo(file, env);
+    },
+    async voiceSeconds(file) {
+      const { voiceSeconds } = await import("../render/html-engine.js");
+      return voiceSeconds(file, env);
+    },
+    async sampleMotion(file) {
+      try {
+        // Two frames a second are enough to see black or a frozen picture, and cost a fraction of a full decode.
+        const { stderr } = await exec(
+          "ffmpeg",
+          ["-hide_banner", "-nostats", "-i", file, "-an", "-vf", "fps=2,blackdetect=d=1:pic_th=0.98:pix_th=0.10,freezedetect=n=0.001:d=3", "-f", "null", "-"],
+          opts,
+        );
+        return parseMotionLog(String(stderr));
+      } catch {
+        return null;
+      }
+    },
+    async labelMatch(file, atSec) {
+      try {
+        const { width, height } = labelSize();
+        const { x, y } = labelPosition();
+        const { stdout } = await exec(
+          "ffmpeg",
+          ["-v", "error", "-ss", String(Math.max(0, atSec)), "-i", file, "-frames:v", "1", "-vf", `crop=${width}:${height}:${x}:${y}`, "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+          { ...opts, encoding: "buffer" },
+        );
+        const buf = stdout as unknown as Buffer;
+        return buf.length >= width * height * 3 ? labelBorderMatch(buf, width, height) : null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+// ------------------------------------------------------------------ outcome
+
+export type GateOutcome =
+  | { kind: "pass" }
+  /** Compliance. The job is `blocked`; nothing retries. */
+  | { kind: "blocked"; failed: CheckResult[] }
+  /** Quality. The job is `rejected`. `retry` is true when the failed checks ran on a rendered file that a re-render can change. */
+  | { kind: "rejected"; failed: CheckResult[]; retry: boolean };
+
+export function gateOutcome(results: CheckResult[]): GateOutcome {
+  const failed = results.filter((item) => item.status === "fail");
+  if (failed.length === 0) return { kind: "pass" };
+  const compliance = failed.filter((item) => item.severity === "compliance");
+  if (compliance.length > 0) return { kind: "blocked", failed: compliance };
+  return { kind: "rejected", failed, retry: failed.every((item) => item.phase === "after") };
+}
+
+/** One line for an error or the tick summary: what failed, with the first Fix after the marker the CLI splits on. */
+export function failureMessage(failed: CheckResult[]): { code: string; message: string } {
+  const first = failed[0]!;
+  const more = failed.length > 1 ? ` (and ${failed.length - 1} more: ${failed.slice(1).map((item) => item.id).join(", ")})` : "";
+  return { code: first.id, message: `${first.message}${more}${first.fix ? ` Fix: ${first.fix}` : ""}` };
+}
+
+/** Replaces the results of the phases just reviewed and keeps the others, so a payload always holds the latest of each check. */
+export function mergeChecks(previous: CheckResult[] | undefined, fresh: CheckResult[]): CheckResult[] {
+  const ids = new Set(fresh.map((item) => item.id));
+  return [...(previous ?? []).filter((item) => !ids.has(item.id)), ...fresh];
+}