@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/verify/determinism.js

@@ -0,0 +1,59 @@
+/**
+ * Same-machine determinism bar from the scene3d spike: two renders reached
+ * SSIM All=1.0 and byte-identical md5. The gate passes on byte-identical
+ * sha256; anything else fails closed and names the SSIM bar for the
+ * frame-level re-check.
+ */
+export const SSIM_GATE = 0.9999;
+/**
+ * Scope of the claim: same machine, GPU and driver only. Cross-machine and
+ * cross-GPU output is NOT claimed (GPU float differs); deterministic scenes
+ * only — seeded grain, pure function of t, no rAF/Clock/random (scene3d and
+ * caption qualify).
+ */
+export const DETERMINISM_NOTE = "same-machine only: same GPU/driver; cross-machine output is not claimed " +
+    "(GPU float may differ). Deterministic scenes only: seeded grain, no rAF.";
+/** sha256 of both renders; a missing file hashes to undefined (fails closed downstream). */
+export async function hashPair(host, pair) {
+    const [first, second] = await Promise.all([
+        host.sha256File(pair.first),
+        host.sha256File(pair.second),
+    ]);
+    return { first, second };
+}
+/** Pure hash comparison: identical passes, anything else is a fatal finding. */
+export function determinismFindings(first, second) {
+    if (first === undefined || second === undefined) {
+        return [
+            {
+                code: "determinism-unreadable",
+                level: "fatal",
+                message: "could not hash both renders; the gate fails closed, re-render the pair",
+            },
+        ];
+    }
+    if (first === second) {
+        return [
+            {
+                code: "determinism-match",
+                level: "info",
+                message: "two renders are byte-identical; same-machine determinism holds",
+            },
+        ];
+    }
+    return [
+        {
+            code: "determinism-mismatch",
+            level: "fatal",
+            message: `renders differ byte-for-byte; re-check frames at SSIM >= ${SSIM_GATE}, same machine only`,
+        },
+    ];
+}
+/** Merges gate findings into a verify report; any fatal escalates the status to FAIL. */
+export function withDeterminism(report, findings) {
+    const merged = [...report.findings, ...findings];
+    const fatal = findings.some((f) => f.level === "fatal");
+    if (fatal && report.status !== "FAIL")
+        return { status: "FAIL", findings: merged };
+    return { ...report, findings: merged };
+}

package/dist/verify/expectation.d.ts

@@ -0,0 +1,15 @@
+import type { MediaExpectation } from "@anvpx/motion-build";
+export interface FrameSpec {
+    width: number;
+    height: number;
+    fps: number;
+}
+/** Draft renders are downscaled to this width at this rate (see `mk draft`). */
+export declare const DRAFT_WIDTH = 960;
+export declare const DRAFT_FPS = 15;
+/** ffmpeg `scale=960:-2` keeps the aspect ratio and rounds the height to an even number. */
+export declare const draftHeight: (meta: FrameSpec) => number;
+/** What a final render of a storyboard must look like. */
+export declare const finalExpectation: (meta: FrameSpec, total: number, fps: number) => MediaExpectation;
+/** What a draft of a storyboard must look like. */
+export declare const draftExpectation: (meta: FrameSpec, total: number) => MediaExpectation;

package/dist/verify/expectation.js

@@ -0,0 +1,19 @@
+/** Draft renders are downscaled to this width at this rate (see `mk draft`). */
+export const DRAFT_WIDTH = 960;
+export const DRAFT_FPS = 15;
+/** ffmpeg `scale=960:-2` keeps the aspect ratio and rounds the height to an even number. */
+export const draftHeight = (meta) => Math.round((meta.height * DRAFT_WIDTH) / meta.width / 2) * 2;
+/** What a final render of a storyboard must look like. */
+export const finalExpectation = (meta, total, fps) => ({
+    width: meta.width,
+    height: meta.height,
+    fps,
+    duration: total,
+});
+/** What a draft of a storyboard must look like. */
+export const draftExpectation = (meta, total) => ({
+    width: DRAFT_WIDTH,
+    height: draftHeight(meta),
+    fps: DRAFT_FPS,
+    duration: total,
+});

package/dist/verify/media-events.d.ts

@@ -0,0 +1,61 @@
+import type { VerifyReport } from "@anvpx/motion-build";
+import type { Io } from "../types.ts";
+import { mergeReports } from "./report.ts";
+/** Freeze noise floor in dB; a lower floor treats quieter changes as motion. */
+export declare const FREEZE_NOISE_DB = -60;
+/** Shortest still span reported as frozen, seconds. */
+export declare const FREEZE_MIN_SECONDS = 2;
+/** Shortest black span reported, seconds. */
+export declare const BLACK_MIN_SECONDS = 0.1;
+/** Fraction of pixels dark enough to count as black. */
+export declare const BLACK_PIXEL_THRESHOLD = 0.1;
+/** Black this close to either end is treated as an intentional fade. */
+export declare const HEAD_TAIL_SECONDS = 0.5;
+/** Fixed filter chain; never user-supplied (mirrors LOUDNORM_FILTER, no second decode). */
+export declare const MEDIA_EVENTS_FILTER: string;
+/** Fixed ffmpeg argv template; `IN` is replaced with the file under test. */
+export declare const MEDIA_EVENTS_ARGS: readonly string[];
+export interface MediaEvent {
+    readonly start: number;
+    readonly duration: number;
+}
+export interface MediaEvents {
+    readonly frozen: readonly MediaEvent[];
+    readonly black: readonly MediaEvent[];
+}
+export type MediaEventsUnavailableKind = "missing-tool" | "missing-filter" | "unreadable";
+export type MediaEventsOutcome = {
+    ok: true;
+    events: MediaEvents;
+} | {
+    ok: false;
+    kind: MediaEventsUnavailableKind;
+    reason?: string;
+};
+/**
+ * Reads the freezedetect/blackdetect metadata lines out of combined stdout+stderr.
+ * Real ffmpeg prints freezedetect as `lavfi.freezedetect.freeze_start|_duration` and
+ * blackdetect as `black_start/black_end/black_duration` on one line, so both that
+ * spelling and the documented `lavfi.blackdetect.black_*` form are accepted.
+ * A span still open at EOF (ffmpeg prints no duration for it) is closed at the probed
+ * clip duration when one is known, and dropped otherwise.
+ * Malformed numbers and unpaired fields are ignored: a missing event is evidence,
+ * a thrown parse error is not.
+ */
+export declare function parseMediaEvents(text: string, durationSec?: number): MediaEvents;
+/** Builds the fixed ffmpeg argv for one file; the filter string never varies. */
+export declare const mediaEventsArgsFor: (file: string) => string[];
+/**
+ * Measures frozen and black spans with one decode pass and two fixed filters.
+ * `durationSec` (from the existing ffprobe result, never a second probe) closes a
+ * span that reaches EOF. Measurement only: audio is dropped (`-an`), nothing is written.
+ */
+export declare function measureMediaEvents(io: Io, file: string, durationSec?: number): Promise<MediaEventsOutcome>;
+/**
+ * Turns measured events into findings. A freeze or a mid-clip black run is a WARN,
+ * never fatal: both are judgment calls on the clip (CRAFT-RUBRIC §2 allows holds).
+ * Black at the head or tail is reported as info and leaves the status alone.
+ */
+export declare function assessMediaEvents(outcome: MediaEventsOutcome, durationSec?: number): VerifyReport;
+/** The spec's seam name: merges this probe's report into the base report. */
+export declare const withMediaEvents: typeof mergeReports;

package/dist/verify/media-events.js

@@ -0,0 +1,174 @@
+import { EXIT } from "../exit-codes.js";
+import { mergeReports } from "./report.js";
+/** Freeze noise floor in dB; a lower floor treats quieter changes as motion. */
+export const FREEZE_NOISE_DB = -60;
+/** Shortest still span reported as frozen, seconds. */
+export const FREEZE_MIN_SECONDS = 2;
+/** Shortest black span reported, seconds. */
+export const BLACK_MIN_SECONDS = 0.1;
+/** Fraction of pixels dark enough to count as black. */
+export const BLACK_PIXEL_THRESHOLD = 0.1;
+/** Black this close to either end is treated as an intentional fade. */
+export const HEAD_TAIL_SECONDS = 0.5;
+/** Fixed filter chain; never user-supplied (mirrors LOUDNORM_FILTER, no second decode). */
+export const MEDIA_EVENTS_FILTER = `freezedetect=n=${FREEZE_NOISE_DB}dB:d=${FREEZE_MIN_SECONDS},` +
+    `blackdetect=d=${BLACK_MIN_SECONDS}:pix_th=${BLACK_PIXEL_THRESHOLD.toFixed(2)}`;
+/** Fixed ffmpeg argv template; `IN` is replaced with the file under test. */
+export const MEDIA_EVENTS_ARGS = [
+    "-v",
+    "info",
+    "-i",
+    "IN",
+    "-vf",
+    MEDIA_EVENTS_FILTER,
+    "-an",
+    "-f",
+    "null",
+    "-",
+];
+/** `[blackdetect @ …] black_start:1.5`, `lavfi.freezedetect.freeze_duration: 2`. */
+const EVENT_META = /(freezedetect\.freeze|blackdetect\.black|black)_(start|duration|end)\s*:\s*(-?\d+(?:\.\d+)?)/g;
+const sorted = (events) => [...events].sort((a, b) => a.start - b.start);
+/** Applies one metadata field; unpaired, negative or malformed values are dropped. */
+function applyField(state, pair, field, value) {
+    if (field === "start") {
+        if (value >= 0)
+            state.open[pair] = value;
+        return;
+    }
+    const start = state.open[pair];
+    state.open[pair] = undefined;
+    if (start === undefined)
+        return;
+    const duration = field === "duration" ? value : value - start;
+    if (duration >= 0)
+        (pair === "frozen" ? state.frozen : state.black).push({ start, duration });
+}
+/**
+ * Reads the freezedetect/blackdetect metadata lines out of combined stdout+stderr.
+ * Real ffmpeg prints freezedetect as `lavfi.freezedetect.freeze_start|_duration` and
+ * blackdetect as `black_start/black_end/black_duration` on one line, so both that
+ * spelling and the documented `lavfi.blackdetect.black_*` form are accepted.
+ * A span still open at EOF (ffmpeg prints no duration for it) is closed at the probed
+ * clip duration when one is known, and dropped otherwise.
+ * Malformed numbers and unpaired fields are ignored: a missing event is evidence,
+ * a thrown parse error is not.
+ */
+export function parseMediaEvents(text, durationSec) {
+    const state = {
+        frozen: [],
+        black: [],
+        open: { frozen: undefined, black: undefined },
+    };
+    for (const match of text.matchAll(EVENT_META)) {
+        const value = Number(match[3]);
+        if (!Number.isFinite(value))
+            continue;
+        const pair = (match[1] ?? "").startsWith("freeze") ? "frozen" : "black";
+        applyField(state, pair, match[2] ?? "", value);
+    }
+    closeOpen(state, "frozen", durationSec);
+    closeOpen(state, "black", durationSec);
+    return { frozen: sorted(state.frozen), black: sorted(state.black) };
+}
+/** Closes a span that never printed its end: a freeze or black run reaching EOF. */
+function closeOpen(state, pair, durationSec) {
+    const start = state.open[pair];
+    state.open[pair] = undefined;
+    if (start === undefined)
+        return;
+    const duration = durationSec === undefined ? -1 : durationSec - start;
+    if (duration >= 0)
+        (pair === "frozen" ? state.frozen : state.black).push({ start, duration });
+}
+/** Builds the fixed ffmpeg argv for one file; the filter string never varies. */
+export const mediaEventsArgsFor = (file) => MEDIA_EVENTS_ARGS.map((arg) => (arg === "IN" ? file : arg));
+const shortReason = (stderr) => (stderr.split(/\r?\n/).find((line) => line.trim().length > 0) ?? "no details")
+    .trim()
+    .split(/\s+/)
+    .slice(-12)
+    .join(" ");
+/**
+ * Measures frozen and black spans with one decode pass and two fixed filters.
+ * `durationSec` (from the existing ffprobe result, never a second probe) closes a
+ * span that reaches EOF. Measurement only: audio is dropped (`-an`), nothing is written.
+ */
+export async function measureMediaEvents(io, file, durationSec) {
+    const result = await io.run("ffmpeg", mediaEventsArgsFor(file));
+    if (result.code === EXIT.MISSING_TOOL)
+        return { ok: false, kind: "missing-tool" };
+    if (result.code !== 0) {
+        const stderr = result.stderr ?? "";
+        if (/no such filter|unknown filter|not recognized/i.test(stderr)) {
+            return { ok: false, kind: "missing-filter", reason: shortReason(stderr) };
+        }
+        return { ok: false, kind: "unreadable", reason: shortReason(stderr) };
+    }
+    const text = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+    return { ok: true, events: parseMediaEvents(text, durationSec) };
+}
+const finding = (code, level, message) => ({
+    code,
+    level,
+    message,
+});
+const round1 = (n) => (Math.round(n * 10) / 10).toFixed(1);
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+/** Longest span, earliest on a tie. */
+const longest = (spans) => spans.reduce((best, span) => (best === undefined || span.duration > best.duration ? span : best), undefined);
+/** True when the span starts or ends within HEAD_TAIL_SECONDS of either end of the clip. */
+const nearEnd = (span, durationSec) => span.start <= HEAD_TAIL_SECONDS ||
+    (durationSec !== undefined && span.start + span.duration >= durationSec - HEAD_TAIL_SECONDS);
+function freezeFinding(frozen) {
+    const span = longest(frozen) ?? { start: 0, duration: 0 };
+    const message = `${plural(frozen.length, "frozen span")}, longest ${round1(span.duration)} s at ` +
+        `${round1(span.start)} s; review each against an intentional hold.`;
+    return finding("media-freeze-detected", "warn", message);
+}
+function strayBlackFinding(stray) {
+    const first = stray[0] ?? { start: 0, duration: 0 };
+    const message = `${plural(stray.length, "black span")} outside head/tail, first at ` +
+        `${round1(first.start)} s for ${round1(first.duration)} s.`;
+    return finding("media-black-detected", "warn", message);
+}
+function headTailFinding(excused, durationSec) {
+    const head = excused.find((span) => span.start <= HEAD_TAIL_SECONDS);
+    const tail = durationSec === undefined
+        ? undefined
+        : excused.find((span) => span.start + span.duration >= durationSec - HEAD_TAIL_SECONDS);
+    const parts = [
+        ...(head === undefined ? [] : [`head ${round1(head.start)} s`]),
+        ...(tail === undefined ? [] : [`tail ${round1(tail.start)} s`]),
+    ];
+    return finding("media-black-head-tail", "info", `Black at ${parts.join(" and ")} treated as intentional.`);
+}
+function unavailable(kind) {
+    const message = kind === "unreadable"
+        ? "ffmpeg could not decode the file for event detection."
+        : "Media event detection skipped; ffmpeg freezedetect/blackdetect unavailable.";
+    const code = kind === "unreadable" ? "media-events-unreadable" : "media-events-unavailable";
+    return { status: "UNKNOWN", findings: [finding(code, "warn", message)] };
+}
+/**
+ * Turns measured events into findings. A freeze or a mid-clip black run is a WARN,
+ * never fatal: both are judgment calls on the clip (CRAFT-RUBRIC §2 allows holds).
+ * Black at the head or tail is reported as info and leaves the status alone.
+ */
+export function assessMediaEvents(outcome, durationSec) {
+    if (!outcome.ok)
+        return unavailable(outcome.kind);
+    const { frozen, black } = outcome.events;
+    const excused = black.filter((span) => nearEnd(span, durationSec));
+    const stray = black.filter((span) => !nearEnd(span, durationSec));
+    const findings = [
+        ...(frozen.length > 0 ? [freezeFinding(frozen)] : []),
+        ...(stray.length > 0 ? [strayBlackFinding(stray)] : []),
+        ...(excused.length > 0 ? [headTailFinding(excused, durationSec)] : []),
+    ];
+    if (findings.length === 0) {
+        findings.push(finding("media-events-clear", "info", "No frozen or black spans detected."));
+    }
+    return { status: frozen.length > 0 || stray.length > 0 ? "WARN" : "PASS", findings };
+}
+/** The spec's seam name: merges this probe's report into the base report. */
+export const withMediaEvents = mergeReports;

package/dist/verify/platform.d.ts

@@ -0,0 +1,33 @@
+import type { VerifyReport } from "@anvpx/motion-build";
+import { type PlatformTemplate } from "@anvpx/motion-schema";
+import type { Host } from "../types.ts";
+import { type LoudnessAvailability, type LoudnessMeasure } from "./audio-loudness.ts";
+export type PlatformLoad = {
+    ok: true;
+    template: PlatformTemplate;
+} | {
+    ok: false;
+    message: string;
+};
+/** `data/platforms` of the schema package, resolved from its entry point. */
+export declare const platformDir: () => string;
+/** Finds a platform template by id or alias in the schema package's data directory. */
+export declare function loadPlatform(host: Host, id: string, dir?: string): Promise<PlatformLoad>;
+/** Sync platform lookup for template styles, read once from the schema package's data directory. */
+export declare function platformLookup(host: Host, dir?: string): Promise<(id: string) => PlatformTemplate | undefined>;
+export interface PlatformAudioPolicy {
+    readonly id: string;
+    readonly lufsTarget: number;
+    readonly truePeakDb: number;
+}
+/**
+ * Audio policy usable for QC: only an explicit verified template counts.
+ * Unverified or absent policy yields undefined so callers report UNKNOWN,
+ * never a universal-LUFS FAIL.
+ */
+export declare const verifiedAudioPolicy: (template: PlatformTemplate | undefined) => PlatformAudioPolicy | undefined;
+/**
+ * Verify-seam entry: judges a loudness measurement only against a verified
+ * platform policy. Reuses verify report/exit semantics (PASS/FAIL/UNKNOWN).
+ */
+export declare const platformAudioReport: (measure: LoudnessMeasure | undefined, template: PlatformTemplate | undefined, availability?: LoudnessAvailability) => VerifyReport;

package/dist/verify/platform.js

@@ -0,0 +1,59 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { parsePlatformTemplate } from "@anvpx/motion-schema";
+import { assessAudioLoudness, } from "./audio-loudness.js";
+const SCHEMA_ENTRY = "@anvpx/motion-schema";
+const DATA_FROM_ENTRY = ["..", "data", "platforms"];
+/** `data/platforms` of the schema package, resolved from its entry point. */
+export const platformDir = () => join(dirname(createRequire(import.meta.url).resolve(SCHEMA_ENTRY)), ...DATA_FROM_ENTRY);
+async function readTemplates(host, dir) {
+    const names = (await host.listDir(dir)).filter((name) => name.endsWith(".json")).sort();
+    const templates = [];
+    for (const name of names) {
+        const parsed = parsePlatformTemplate(JSON.parse(await host.readText(join(dir, name))));
+        if (parsed.ok)
+            templates.push(parsed.value);
+    }
+    return templates;
+}
+/** Finds a platform template by id or alias in the schema package's data directory. */
+export async function loadPlatform(host, id, dir = platformDir()) {
+    let templates;
+    try {
+        templates = await readTemplates(host, dir);
+    }
+    catch (error) {
+        return { ok: false, message: `cannot read platform templates: ${error.message}` };
+    }
+    const wanted = id.toLowerCase();
+    const match = templates.find((t) => t.id === wanted || t.aliases.includes(wanted));
+    if (match)
+        return { ok: true, template: match };
+    const known = templates.map((t) => t.id).join(", ");
+    return { ok: false, message: `unknown platform "${id}"; use one of: ${known}` };
+}
+/** Sync platform lookup for template styles, read once from the schema package's data directory. */
+export async function platformLookup(host, dir = platformDir()) {
+    const templates = await readTemplates(host, dir).catch(() => []);
+    return (id) => {
+        const wanted = id.toLowerCase();
+        return templates.find((t) => t.id === wanted || t.aliases.includes(wanted));
+    };
+}
+/**
+ * Audio policy usable for QC: only an explicit verified template counts.
+ * Unverified or absent policy yields undefined so callers report UNKNOWN,
+ * never a universal-LUFS FAIL.
+ */
+export const verifiedAudioPolicy = (template) => template?.verified === true
+    ? {
+        id: template.id,
+        lufsTarget: template.audio.lufsTarget,
+        truePeakDb: template.audio.truePeakDb,
+    }
+    : undefined;
+/**
+ * Verify-seam entry: judges a loudness measurement only against a verified
+ * platform policy. Reuses verify report/exit semantics (PASS/FAIL/UNKNOWN).
+ */
+export const platformAudioReport = (measure, template, availability) => assessAudioLoudness(measure, template, availability);

package/dist/verify/probe.d.ts

@@ -0,0 +1,14 @@
+import type { Io } from "../types.ts";
+export type ProbeOutcome = {
+    ok: true;
+    probe: unknown;
+} | {
+    ok: false;
+    kind: "missing-tool";
+} | {
+    ok: false;
+    kind: "unreadable";
+    reason: string;
+};
+/** Runs `ffprobe` (found on PATH, as doctor finds ffmpeg) and parses its JSON. */
+export declare function probeMedia(io: Io, file: string): Promise<ProbeOutcome>;

package/dist/verify/probe.js

@@ -0,0 +1,23 @@
+import { EXIT } from "../exit-codes.js";
+const PROBE_ARGS = ["-v", "error", "-show_streams", "-show_format", "-of", "json"];
+const REASON_WORDS = 12;
+/** First stderr line, cut to a few words so a finding message stays short. */
+const shortReason = (stderr) => (stderr.split(/\r?\n/).find((line) => line.trim().length > 0) ?? "no details")
+    .trim()
+    .split(/\s+/)
+    .slice(-REASON_WORDS)
+    .join(" ");
+/** Runs `ffprobe` (found on PATH, as doctor finds ffmpeg) and parses its JSON. */
+export async function probeMedia(io, file) {
+    const result = await io.run("ffprobe", [...PROBE_ARGS, file]);
+    if (result.code === EXIT.MISSING_TOOL)
+        return { ok: false, kind: "missing-tool" };
+    if (result.code !== 0)
+        return { ok: false, kind: "unreadable", reason: shortReason(result.stderr) };
+    try {
+        return { ok: true, probe: JSON.parse(result.stdout) };
+    }
+    catch {
+        return { ok: false, kind: "unreadable", reason: "ffprobe printed invalid JSON" };
+    }
+}

package/dist/verify/report.d.ts

@@ -0,0 +1,15 @@
+import type { VerifyReport } from "@anvpx/motion-build";
+/** Findings shown before the rest are summarised as "+N more" (constitution 8.6). */
+export declare const MAX_FINDINGS = 10;
+/** PASS and WARN succeed, FAIL is a QA failure, UNKNOWN could not be decided (exit 2, doctor parity). */
+export declare const exitCodeForStatus: (status: VerifyReport["status"]) => number;
+/**
+ * Combines a base report with an opt-in probe's report: FAIL > UNKNOWN > WARN > PASS,
+ * findings base first. The merged status stays the one exit authority; the probes
+ * never set a status the base could not have reached on its own.
+ */
+export declare function mergeReports(base: VerifyReport, extra: VerifyReport): VerifyReport;
+/** `STATUS file` then one line per finding, most severe first, capped. */
+export declare function formatReport(file: string, report: VerifyReport): string;
+/** One compact JSON line: {status, file, findings, more?}. */
+export declare function formatReportJson(file: string, report: VerifyReport): string;

package/dist/verify/report.js

@@ -0,0 +1,45 @@
+import { basename } from "node:path";
+import { EXIT } from "../exit-codes.js";
+/** Findings shown before the rest are summarised as "+N more" (constitution 8.6). */
+export const MAX_FINDINGS = 10;
+const ORDER = { fatal: 0, warn: 1, info: 2 };
+/** PASS and WARN succeed, FAIL is a QA failure, UNKNOWN could not be decided (exit 2, doctor parity). */
+export const exitCodeForStatus = (status) => {
+    if (status === "FAIL")
+        return EXIT.QA_FAIL;
+    return status === "UNKNOWN" ? EXIT.USAGE : EXIT.OK;
+};
+/** Heaviest status wins when an opt-in probe is merged into the base report. */
+const STATUS_ORDER = {
+    PASS: 0,
+    WARN: 1,
+    UNKNOWN: 2,
+    FAIL: 3,
+};
+/**
+ * Combines a base report with an opt-in probe's report: FAIL > UNKNOWN > WARN > PASS,
+ * findings base first. The merged status stays the one exit authority; the probes
+ * never set a status the base could not have reached on its own.
+ */
+export function mergeReports(base, extra) {
+    const heavier = STATUS_ORDER[extra.status] > STATUS_ORDER[base.status] ? extra.status : base.status;
+    return { status: heavier, findings: [...base.findings, ...extra.findings] };
+}
+const ranked = (findings) => [...findings].sort((a, b) => ORDER[a.level] - ORDER[b.level]);
+const line = (f) => `${f.level} ${f.code}: ${f.message}${f.path === undefined ? "" : ` (${f.path})`}`;
+/** `STATUS file` then one line per finding, most severe first, capped. */
+export function formatReport(file, report) {
+    const shown = ranked(report.findings).slice(0, MAX_FINDINGS);
+    const more = report.findings.length - shown.length;
+    const rows = [`${report.status} ${basename(file)}`, ...shown.map(line)];
+    if (more > 0)
+        rows.push(`(+${more} more)`);
+    return `${rows.join("\n")}\n`;
+}
+/** One compact JSON line: {status, file, findings, more?}. */
+export function formatReportJson(file, report) {
+    const shown = ranked(report.findings).slice(0, MAX_FINDINGS);
+    const more = report.findings.length - shown.length;
+    const doc = { status: report.status, file: basename(file), findings: shown };
+    return `${JSON.stringify(more > 0 ? { ...doc, more } : doc)}\n`;
+}

package/dist/verify/run.d.ts

@@ -0,0 +1,27 @@
+import { type MediaExpectation, type VerifyReport } from "@anvpx/motion-build";
+import type { PlatformTemplate } from "@anvpx/motion-schema";
+import type { Io } from "../types.ts";
+import { type DeterminismPair } from "./determinism.ts";
+export type VerifyRun = {
+    ok: true;
+    report: VerifyReport;
+    durationSec?: number;
+} | {
+    ok: false;
+    code: number;
+    message: string;
+};
+export interface VerifyTarget {
+    file: string;
+    expect?: MediaExpectation;
+    platform?: PlatformTemplate;
+    /** When set, both renders are hashed and byte-identity is gated (exit 5 on mismatch). */
+    determinism?: DeterminismPair;
+}
+/** Probes a file with ffprobe and assesses it; never throws. */
+export declare function verifyFile(io: Io, target: VerifyTarget): Promise<VerifyRun>;
+/** The `--verify` step of draft and render: prints the report, resolves the exit code. */
+export declare function verifyStep(io: Io, target: VerifyTarget): Promise<{
+    code: number;
+    status: VerifyReport["status"] | "not-run";
+}>;

package/dist/verify/run.js

@@ -0,0 +1,53 @@
+import { verifyMedia } from "@anvpx/motion-build";
+import { EXIT } from "../exit-codes.js";
+import { determinismFindings, hashPair, withDeterminism, } from "./determinism.js";
+import { probeMedia } from "./probe.js";
+import { exitCodeForStatus, formatReport } from "./report.js";
+/** Seconds from the existing probe (`format.duration`); undefined when absent or malformed. */
+const probedDuration = (probe) => {
+    const format = probe?.format;
+    const raw = format?.duration;
+    const seconds = typeof raw === "string" ? Number(raw) : raw;
+    return typeof seconds === "number" && Number.isFinite(seconds) && seconds >= 0
+        ? seconds
+        : undefined;
+};
+/** Probes a file with ffprobe and assesses it; never throws. */
+export async function verifyFile(io, target) {
+    const probed = await probeMedia(io, target.file);
+    if (!probed.ok && probed.kind === "missing-tool") {
+        const message = "mk: ffprobe not found; install ffmpeg and put it on PATH";
+        return { ok: false, code: EXIT.MISSING_TOOL, message };
+    }
+    if (!probed.ok) {
+        const message = `ffprobe could not read the file: ${probed.reason}`;
+        const finding = { code: "media-unreadable", level: "fatal", message };
+        return { ok: true, report: { status: "FAIL", findings: [finding] } };
+    }
+    const { expect, platform, determinism } = target;
+    const assessed = verifyMedia({
+        probe: probed.probe,
+        ...(expect ? { expect } : {}),
+        ...(platform ? { platform } : {}),
+    });
+    const durationSec = probedDuration(probed.probe);
+    const timing = durationSec === undefined ? {} : { durationSec };
+    if (determinism === undefined)
+        return { ok: true, report: assessed, ...timing };
+    const hashes = await hashPair(io.host, determinism);
+    return {
+        ok: true,
+        report: withDeterminism(assessed, determinismFindings(hashes.first, hashes.second)),
+        ...timing,
+    };
+}
+/** The `--verify` step of draft and render: prints the report, resolves the exit code. */
+export async function verifyStep(io, target) {
+    const run = await verifyFile(io, target);
+    if (!run.ok) {
+        io.stderr(`${run.message}\n`);
+        return { code: run.code, status: "not-run" };
+    }
+    io.stdout(formatReport(target.file, run.report));
+    return { code: exitCodeForStatus(run.report.status), status: run.report.status };
+}

package/dist/voice/command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "../types.ts";
+export declare const voiceCommand: Command;
+export declare const makeVoiceCommand: () => Command;

package/dist/voice/command.js

@@ -0,0 +1,49 @@
+import { parseFlags, requireStoryboard, textFlag, usageError } from "../args.js";
+import { runVoice, VOICE_ENV_NOTE, VOICE_MEASURED_QC_NOTE, VOICE_WAV_FALLBACK_NOTE, } from "./run.js";
+const USAGE = `mk voice <storyboard.json> --voice <id> [--out <manifest>] [--audio-dir <dir>] [--python <bin>]
+
+Kokoro local primary. Synthesize narration via the voice venv and write a voice TimingManifest.
+Reads narration per base scene, probes the venv, synthesizes each scene, aligns
+words, gates silence with ffprobe, then writes .mk/<stem>/voice-manifest.json
+plus licences-style voice-provenance.json. Feed it to the build timing path
+(resolveTimeline voice override). No venv: fails closed with a doctor hint,
+never silent fallback (fallback.ts is durations-only behind an explicit flag).
+${VOICE_WAV_FALLBACK_NOTE} when env blocked. ${VOICE_MEASURED_QC_NOTE}.
+${VOICE_ENV_NOTE}.
+  --voice <id>     voice name from the storyboard/adapters (required; never hardcoded)
+  --out <file>     manifest path (default .mk/<stem>/voice-manifest.json)
+  --audio-dir <d>  per-scene wav directory (default .mk/<stem>/audio)
+  --python <bin>   explicit venv python (skips the probe)
+`;
+const FLAGS = {
+    voice: { type: "string" },
+    out: { type: "string" },
+    "audio-dir": { type: "string" },
+    python: { type: "string" },
+};
+export const voiceCommand = {
+    name: "voice",
+    summary: "synthesize narration into a voice TimingManifest for the build timing path",
+    async run(args, io) {
+        const parsed = parseFlags("voice", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const storyboard = requireStoryboard("voice", USAGE, parsed.positionals, io);
+        if (typeof storyboard !== "string")
+            return storyboard.code;
+        const voice = textFlag(parsed.flags, "voice");
+        if (voice === undefined || voice.trim() === "") {
+            return usageError("voice", USAGE, "--voice <id> is required", io).code;
+        }
+        const out = textFlag(parsed.flags, "out");
+        const audioDir = textFlag(parsed.flags, "audio-dir");
+        const python = textFlag(parsed.flags, "python");
+        return runVoice(storyboard, {
+            voice,
+            ...(out === undefined ? {} : { outPath: out }),
+            ...(audioDir === undefined ? {} : { audioDir }),
+            ...(python === undefined ? {} : { python }),
+        }, io);
+    },
+};
+export const makeVoiceCommand = () => voiceCommand;