@anvpx/motion-cli 0.0.0-stage → 0.1.1

package/dist/tooling/session.js

@@ -0,0 +1,106 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { readPins } from "../doctor/pins.js";
+import { formatVersion, parseVersion } from "../doctor/version.js";
+import { EXIT } from "../exit-codes.js";
+export const LOG_FILE = "render-log.txt";
+const TAIL_LINES = 15;
+/** Renders of long storyboards are slow; the probe default of 30 s would kill them. */
+const STEP_TIMEOUT_MS = 60 * 60_000;
+const pkgRequire = createRequire(import.meta.url);
+/**
+ * Absolute path of the hyperframes CLI entry point, resolved from the packages
+ * installed alongside this one (hyperframes is a runtime dependency of
+ * `@anvpx/motion`). Throws when the install cannot provide it.
+ */
+export function hyperframesCliPath() {
+    return join(dirname(pkgRequire.resolve("hyperframes/package.json")), "dist", "cli.js");
+}
+/** Absolute path of the installed hyperframes manifest (doctor reports its version). */
+export function hyperframesPackagePath() {
+    return pkgRequire.resolve("hyperframes/package.json");
+}
+/**
+ * Why hyperframes may not be used (missing install or mismatched pin), or undefined when
+ * it is runnable. A pin is optional: consumer projects get it from `@anvpx/motion`, so
+ * no pin plus a runnable installed CLI is acceptable.
+ */
+export async function pinProblem(io, project, resolveCli = hyperframesCliPath) {
+    const pin = readPins(await io.host.readRootPackageJson()).hyperframes;
+    let cli;
+    try {
+        cli = resolveCli();
+    }
+    catch {
+        const message = pin
+            ? `cannot resolve hyperframes@${pin} from the installed packages; fix: reinstall @anvpx/motion (it ships hyperframes@${pin} as a runtime dependency)`
+            : "cannot resolve hyperframes from the installed packages; fix: reinstall @anvpx/motion (it ships hyperframes as a runtime dependency)";
+        return { message, code: EXIT.MISSING_TOOL };
+    }
+    const result = await io.run(process.execPath, [cli, "--version"], { cwd: project });
+    const installed = result.code === 0 ? parseVersion(result.stdout) : undefined;
+    if (!installed) {
+        const message = pin
+            ? `cannot run hyperframes --version (node ${cli}) in ${project}; fix: reinstall @anvpx/motion so hyperframes@${pin} is installed alongside it`
+            : `cannot run hyperframes --version (node ${cli}) in ${project}; fix: reinstall @anvpx/motion so its hyperframes dependency is installed alongside it`;
+        return { message, code: EXIT.MISSING_TOOL };
+    }
+    if (pin === undefined)
+        return undefined;
+    const found = formatVersion(installed);
+    if (found === pin)
+        return undefined;
+    const message = `hyperframes ${found} installed but ${pin} pinned; fix: install hyperframes@${pin} alongside @anvpx/motion (or update motionKit.pins.hyperframes)`;
+    return { message, code: EXIT.ERROR };
+}
+const tail = (result) => `${result.stdout}\n${result.stderr}`
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .slice(-TAIL_LINES)
+    .join("\n");
+/**
+ * Checks the hyperframes pin, runs `steps` in the project directory, and always writes
+ * `render-log.txt` with every command's output. Resolves to the exit code: OK, ERROR on a failed step, MISSING_TOOL when a program cannot run.
+ */
+export async function runInProject(io, project, steps) {
+    const problem = await pinProblem(io, project);
+    if (problem) {
+        io.stderr(`mk: ${problem.message}\n`);
+        return problem.code;
+    }
+    const log = [];
+    const outcome = {};
+    const cli = hyperframesCliPath();
+    const probe = async (cmd, args, options) => {
+        if (outcome.failure) {
+            return { code: EXIT.ERROR, stdout: "", stderr: "skipped: an earlier step failed" };
+        }
+        const command = [cmd, ...args].join(" ");
+        const result = await io.run(cmd, args, {
+            cwd: project,
+            timeoutMs: STEP_TIMEOUT_MS,
+            ...options,
+        });
+        log.push(`$ ${command}\n${result.stdout}${result.stderr}\n[exit ${result.code}]\n\n`);
+        if (result.code !== 0)
+            outcome.failure = { command, result };
+        return result;
+    };
+    const exec = async (cmd, args, options) => (await probe(cmd, args, options)).code === 0;
+    const logPath = join(project, LOG_FILE);
+    try {
+        await steps({
+            hf: (args, options) => exec(process.execPath, [cli, ...args], options),
+            tool: exec,
+            probe,
+        });
+    }
+    finally {
+        await io.host.writeText(logPath, log.join(""));
+    }
+    if (!outcome.failure)
+        return EXIT.OK;
+    const { command, result } = outcome.failure;
+    io.stderr(`mk: \`${command}\` failed (exit ${result.code}); last ${TAIL_LINES} lines:\n${tail(result)}\nlog: ${logPath}\n`);
+    return result.code === EXIT.MISSING_TOOL ? EXIT.MISSING_TOOL : EXIT.ERROR;
+}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+export interface CommandResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface RunOptions {
+    cwd?: string;
+    /** Merged over the parent environment. */
+    env?: Readonly<Record<string, string>>;
+    /** Kill the program after this long; defaults to a short probe timeout. */
+    timeoutMs?: number;
+}
+/** Runs an external program. Never throws: a missing program yields code 127. */
+export type Runner = (cmd: string, args: readonly string[], options?: RunOptions) => Promise<CommandResult>;
+export interface Host {
+    platform: NodeJS.Platform;
+    /** Without leading "v", e.g. "24.12.0". */
+    nodeVersion: string;
+    homeDir: string;
+    /** Process environment; absent in old fakes means empty. Prefer host.env over process.env in checks. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** Entry names of a directory; rejects when it does not exist. */
+    listDir(path: string): Promise<string[]>;
+    /** Creates a directory recursively. Optional so minimal test hosts need not implement it. */
+    mkdir?(path: string): Promise<void>;
+    /** Parsed repo-root package.json, or undefined when absent/unreadable. */
+    readRootPackageJson(): Promise<unknown>;
+    /** UTF-8 file contents; rejects when unreadable. */
+    readText(path: string): Promise<string>;
+    /** Writes UTF-8 text, creating parent directories. */
+    writeText(path: string, text: string): Promise<void>;
+    /** Replaces a file atomically (temp file in the same directory, then rename): readers never see a partial write. */
+    writeTextAtomic(path: string, text: string): Promise<void>;
+    /** True when a file or directory exists at the path. */
+    exists(path: string): Promise<boolean>;
+    /** Hex sha256 of a file's bytes, or undefined when it does not exist. */
+    sha256File(path: string): Promise<string | undefined>;
+    /** Copies a file byte for byte, creating parent directories. */
+    copyFile(from: string, to: string): Promise<void>;
+    /**
+     * Moves `from` over `to`, replacing it in one step (same volume), creating the
+     * parent directory. Readers never see a half-written `to`.
+     */
+    renameFile(from: string, to: string): Promise<void>;
+    /** Deletes a file; a missing file is not an error. */
+    remove(path: string): Promise<void>;
+}
+export interface Io {
+    stdout(text: string): void;
+    stderr(text: string): void;
+    run: Runner;
+    host: Host;
+}
+export interface Command {
+    name: string;
+    summary: string;
+    /** Resolves to the process exit code. */
+    run(args: readonly string[], io: Io): Promise<number>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/verify/audio-loudness.d.ts

@@ -0,0 +1,46 @@
+import type { VerifyReport } from "@anvpx/motion-build";
+import type { PlatformTemplate } from "@anvpx/motion-schema";
+import type { Io } from "../types.ts";
+/** Accepted drift for integrated loudness vs a verified platform target. */
+export declare const LOUDNESS_TOLERANCE_LU = 1;
+/** Accepted excess for true peak above a verified platform ceiling. */
+export declare const TRUE_PEAK_TOLERANCE_DB = 0.5;
+/** Fixed measurement filter; never user-supplied (no gain, ducking, or arbitrary strings). */
+export declare const LOUDNORM_FILTER = "loudnorm=print_format=json";
+/** Fixed ffmpeg argv template; `IN` is replaced with the file under test. */
+export declare const LOUDNORM_ARGS: readonly string[];
+export interface LoudnessMeasure {
+    readonly integratedLufs: number;
+    readonly truePeakDb: number;
+}
+export type LoudnessUnavailableKind = "missing-tool" | "missing-filter" | "no-audio-stream" | "parse-failed" | "non-finite" | "unreadable";
+export interface LoudnessAvailability {
+    readonly kind: LoudnessUnavailableKind;
+    readonly reason?: string;
+}
+export type LoudnessOutcome = {
+    ok: true;
+    measure: LoudnessMeasure;
+} | {
+    ok: false;
+    kind: LoudnessUnavailableKind;
+    reason?: string;
+};
+/**
+ * Parses `loudnorm=print_format=json` output. Returns undefined when the JSON
+ * is missing, lacks fields, or is non-finite (silence reports -inf).
+ */
+export declare function parseLoudnormJson(text: string): LoudnessMeasure | undefined;
+/** Builds the fixed ffmpeg argv for one file; the filter string never varies. */
+export declare const loudnormArgsFor: (file: string) => string[];
+/**
+ * Measures integrated loudness + true peak with installed FFmpeg loudnorm.
+ * Measurement only: single pass, no gain or normalization applied.
+ */
+export declare function measureAudioLoudness(io: Io, file: string): Promise<LoudnessOutcome>;
+/**
+ * Judges a measurement only against an explicit verified platform policy.
+ * Unverified or absent policy, and any measurement unavailability, is UNKNOWN
+ * (exit 2); only a verified-policy breach is FAIL (exit 5).
+ */
+export declare function assessAudioLoudness(measure: LoudnessMeasure | undefined, platform: PlatformTemplate | undefined, availability?: LoudnessAvailability): VerifyReport;

package/dist/verify/audio-loudness.js

@@ -0,0 +1,186 @@
+import { EXIT } from "../exit-codes.js";
+/** Accepted drift for integrated loudness vs a verified platform target. */
+export const LOUDNESS_TOLERANCE_LU = 1;
+/** Accepted excess for true peak above a verified platform ceiling. */
+export const TRUE_PEAK_TOLERANCE_DB = 0.5;
+/** Fixed measurement filter; never user-supplied (no gain, ducking, or arbitrary strings). */
+export const LOUDNORM_FILTER = "loudnorm=print_format=json";
+/** Fixed ffmpeg argv template; `IN` is replaced with the file under test. */
+export const LOUDNORM_ARGS = [
+    "-v",
+    "info",
+    "-i",
+    "IN",
+    "-filter:a",
+    LOUDNORM_FILTER,
+    "-f",
+    "null",
+    "-",
+];
+const numberOrUndefined = (value) => {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string" && value.trim().length > 0)
+        return Number(value);
+    return undefined;
+};
+/** Extracts the JSON object ffmpeg prints (usually on stderr) from surrounding noise. */
+const jsonObjectOf = (text) => {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        return undefined;
+    try {
+        return JSON.parse(text.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+};
+const rawOf = (doc) => ({
+    i: numberOrUndefined(doc.measured_I ?? doc.input_i ?? doc.measured_i ?? doc.input_I ?? doc.integrated),
+    tp: numberOrUndefined(doc.measured_TP ?? doc.input_tp ?? doc.measured_tp ?? doc.input_TP ?? doc.true_peak),
+});
+/**
+ * Parses `loudnorm=print_format=json` output. Returns undefined when the JSON
+ * is missing, lacks fields, or is non-finite (silence reports -inf).
+ */
+export function parseLoudnormJson(text) {
+    const doc = jsonObjectOf(text);
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        return undefined;
+    const { i, tp } = rawOf(doc);
+    if (i === undefined || tp === undefined)
+        return undefined;
+    if (!Number.isFinite(i) || !Number.isFinite(tp))
+        return undefined;
+    return { integratedLufs: i, truePeakDb: tp };
+}
+/** Builds the fixed ffmpeg argv for one file; the filter string never varies. */
+export const loudnormArgsFor = (file) => LOUDNORM_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 integrated loudness + true peak with installed FFmpeg loudnorm.
+ * Measurement only: single pass, no gain or normalization applied.
+ */
+export async function measureAudioLoudness(io, file) {
+    const result = await io.run("ffmpeg", loudnormArgsFor(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) };
+        }
+        if (/does not contain any stream|matches no streams|no audio|no stream/i.test(stderr)) {
+            return { ok: false, kind: "no-audio-stream", reason: shortReason(stderr) };
+        }
+        return { ok: false, kind: "unreadable", reason: shortReason(stderr) };
+    }
+    const combined = `${result.stderr ?? ""}\n${result.stdout ?? ""}`;
+    const parsed = parseLoudnormJson(combined);
+    if (parsed)
+        return { ok: true, measure: parsed };
+    const doc = jsonObjectOf(combined);
+    if (typeof doc === "object" && doc !== null && !Array.isArray(doc)) {
+        const { i, tp } = rawOf(doc);
+        const hasBoth = i !== undefined && tp !== undefined;
+        const nonFinite = hasBoth &&
+            ((typeof i === "number" && !Number.isFinite(i)) ||
+                (typeof tp === "number" && !Number.isFinite(tp)));
+        if (nonFinite)
+            return { ok: false, kind: "non-finite" };
+    }
+    return { ok: false, kind: "parse-failed", reason: "ffmpeg loudnorm printed no parsable JSON" };
+}
+const finding = (code, level, message) => ({
+    code,
+    level,
+    message,
+});
+const round1 = (n) => (Math.round(n * 10) / 10).toFixed(1);
+/**
+ * Judges a measurement only against an explicit verified platform policy.
+ * Unverified or absent policy, and any measurement unavailability, is UNKNOWN
+ * (exit 2); only a verified-policy breach is FAIL (exit 5).
+ */
+export function assessAudioLoudness(measure, platform, availability) {
+    if (availability) {
+        if (availability.kind === "no-audio-stream") {
+            return {
+                status: "UNKNOWN",
+                findings: [
+                    finding("audio-loudness-no-stream", "warn", "No audio stream to measure loudness from."),
+                ],
+            };
+        }
+        if (availability.kind === "missing-tool" || availability.kind === "missing-filter") {
+            return {
+                status: "UNKNOWN",
+                findings: [
+                    finding("audio-loudness-unavailable", "warn", "Audio loudness could not be measured; ffmpeg loudnorm unavailable."),
+                ],
+            };
+        }
+        return {
+            status: "UNKNOWN",
+            findings: [
+                finding("audio-loudness-unmeasurable", "warn", "Audio loudness could not be measured; loudnorm output unparsable."),
+            ],
+        };
+    }
+    if (platform === undefined) {
+        return {
+            status: "UNKNOWN",
+            findings: [
+                finding("audio-loudness-no-policy", "info", "No platform audio policy supplied; loudness not judged."),
+            ],
+        };
+    }
+    if (!platform.verified) {
+        return {
+            status: "UNKNOWN",
+            findings: [
+                finding("audio-loudness-unverified", "info", `Template ${platform.id} has verified: false; loudness not judged.`),
+            ],
+        };
+    }
+    if (measure === undefined ||
+        !Number.isFinite(measure.integratedLufs) ||
+        !Number.isFinite(measure.truePeakDb)) {
+        return {
+            status: "UNKNOWN",
+            findings: [
+                finding("audio-loudness-unmeasurable", "warn", "Audio loudness could not be measured; loudnorm output unparsable."),
+            ],
+        };
+    }
+    const targetI = platform.audio.lufsTarget;
+    const targetTp = platform.audio.truePeakDb;
+    if (Math.abs(measure.integratedLufs - targetI) > LOUDNESS_TOLERANCE_LU) {
+        return {
+            status: "FAIL",
+            findings: [
+                finding("audio-loudness-mismatch", "fatal", `Integrated ${round1(measure.integratedLufs)} LUFS differs from ${platform.id} target ${round1(targetI)} LUFS by more than ${round1(LOUDNESS_TOLERANCE_LU)} LU.`),
+            ],
+        };
+    }
+    if (measure.truePeakDb - targetTp > TRUE_PEAK_TOLERANCE_DB) {
+        return {
+            status: "FAIL",
+            findings: [
+                finding("audio-true-peak-mismatch", "fatal", `True peak ${round1(measure.truePeakDb)} dBTP exceeds ${platform.id} ceiling ${round1(targetTp)} dBTP.`),
+            ],
+        };
+    }
+    return {
+        status: "PASS",
+        findings: [
+            finding("audio-loudness-ok", "info", `Integrated ${round1(measure.integratedLufs)} LUFS, true peak ${round1(measure.truePeakDb)} dBTP within ${platform.id} policy.`),
+        ],
+    };
+}

package/dist/verify/command.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "../types.ts";
+export declare const verifyCommand: Command;

package/dist/verify/command.js

@@ -0,0 +1,161 @@
+import { parseFlags, requirePositional, textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { checkStoryboard } from "../storyboard/check.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { formatFindings } from "../storyboard/report.js";
+import { measureAudioLoudness } from "./audio-loudness.js";
+import { draftExpectation, finalExpectation } from "./expectation.js";
+import { assessMediaEvents, measureMediaEvents } from "./media-events.js";
+import { loadPlatform, platformAudioReport } from "./platform.js";
+import { exitCodeForStatus, formatReport, formatReportJson, mergeReports } from "./report.js";
+import { verifyFile } from "./run.js";
+const USAGE = `mk verify <file.mp4> [--storyboard <sb.json>] [--platform <id>] [--draft] [--determinism <second.mp4>] [--events] [--loudness] [--json]
+
+Re-probe a rendered file with ffprobe and report findings; QC measures, it never decides for you.
+  --storyboard <f>  expect its size, fps and total duration; frames = duration x fps (+-1)
+  --platform <id>   also check aspect, fps and duration cap against a platform template
+  --draft           with --storyboard: expect a 960 px wide 15 fps draft
+  --determinism <f> compare a second render byte-for-byte; a mismatch is a QA FAIL
+                    (same machine/GPU/driver only; deterministic scenes only: seeded grain, no rAF)
+  --events          also detect frozen and black spans (one extra ffmpeg decode; never fatal)
+  --loudness        also measure integrated LUFS + true peak against a verified platform policy
+  --json            one compact JSON line {status, file, findings}
+Exit 0 PASS or WARN; 5 FAIL; 2 UNKNOWN (could not decide); 2 bad arguments; 127 ffprobe missing.
+`;
+const FLAGS = {
+    storyboard: { type: "string" },
+    platform: { type: "string" },
+    draft: { type: "boolean" },
+    determinism: { type: "string" },
+    events: { type: "boolean" },
+    loudness: { type: "boolean" },
+    json: { type: "boolean" },
+};
+const DRAFT_NEEDS_STORYBOARD = "--draft needs --storyboard";
+async function expectationFromStoryboard(path, draft, io) {
+    const loaded = await readJsonFile(path, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk verify: ${loaded.message}\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    const report = checkStoryboard(loaded.value);
+    if (report.errors.length > 0 || !report.meta || report.total === undefined) {
+        io.stderr(`mk verify: storyboard is invalid; run \`mk validate\`.\n${formatFindings(report.errors.slice(0, 3))}`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    return draft
+        ? draftExpectation(report.meta, report.total)
+        : finalExpectation(report.meta, report.total, report.meta.fps);
+}
+async function platformFrom(id, io) {
+    if (id === undefined)
+        return undefined;
+    const loaded = await loadPlatform(io.host, id);
+    if (loaded.ok)
+        return loaded.template;
+    io.stderr(`mk verify: ${loaded.message}\n`);
+    return { kind: "exit", code: EXIT.USAGE };
+}
+const isExit = (value) => typeof value === "object" && value !== null && value.kind === "exit";
+/** The `--determinism` second render, or the usage failure to exit with. */
+async function determinismFrom(second, file, io) {
+    if (second === undefined)
+        return undefined;
+    if (!(await io.host.exists(second))) {
+        io.stderr(`mk verify: cannot read ${second}; check the path.\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    return { first: file, second };
+}
+/** File reads and check setup, or the usage failure to exit with. */
+async function resolveChecks(io, file, inputs) {
+    if (!(await io.host.exists(file))) {
+        io.stderr(`mk verify: cannot read ${file}; check the path.\n`);
+        return { kind: "exit", code: EXIT.USAGE };
+    }
+    const { storyboard, draft, platform, second } = inputs;
+    const expectation = storyboard === undefined ? undefined : await expectationFromStoryboard(storyboard, draft, io);
+    if (isExit(expectation))
+        return expectation;
+    const template = await platformFrom(platform, io);
+    if (isExit(template))
+        return template;
+    const determinism = await determinismFrom(second, file, io);
+    if (isExit(determinism))
+        return determinism;
+    return {
+        ...(expectation ? { expect: expectation } : {}),
+        ...(template ? { platform: template } : {}),
+        ...(determinism ? { determinism } : {}),
+    };
+}
+/** Turns arguments into what to check, or the usage failure to exit with. */
+async function resolveTarget(args, io) {
+    const parsed = parseFlags("verify", USAGE, args, FLAGS, io);
+    if (parsed.kind === "exit")
+        return parsed;
+    const file = requirePositional("verify", USAGE, parsed.positionals, "<file.mp4>", io);
+    if (typeof file !== "string")
+        return file;
+    const storyboard = textFlag(parsed.flags, "storyboard");
+    const draft = parsed.flags.draft === true;
+    if (draft && storyboard === undefined) {
+        return usageError("verify", USAGE, DRAFT_NEEDS_STORYBOARD, io);
+    }
+    const checks = await resolveChecks(io, file, {
+        storyboard,
+        draft,
+        platform: textFlag(parsed.flags, "platform"),
+        second: textFlag(parsed.flags, "determinism"),
+    });
+    if (isExit(checks))
+        return checks;
+    return {
+        file,
+        json: parsed.flags.json === true,
+        events: parsed.flags.events === true,
+        loudness: parsed.flags.loudness === true,
+        ...checks,
+    };
+}
+/** Judges one measurement only against the loaded verified platform policy. */
+function loudnessReport(outcome, platform) {
+    return outcome.ok
+        ? platformAudioReport(outcome.measure, platform)
+        : platformAudioReport(undefined, platform, { kind: outcome.kind, reason: outcome.reason });
+}
+/** Layers the opt-in probes on the base report; the merged status is the exit authority. */
+async function withProbes(io, target, base, durationSec, probes) {
+    let report = base;
+    if (probes.events) {
+        const outcome = await measureMediaEvents(io, target.file, durationSec);
+        report = mergeReports(report, assessMediaEvents(outcome, durationSec));
+    }
+    if (probes.loudness) {
+        const outcome = await measureAudioLoudness(io, target.file);
+        report = mergeReports(report, loudnessReport(outcome, target.platform));
+    }
+    return report;
+}
+export const verifyCommand = {
+    name: "verify",
+    summary: "re-probe a rendered mp4: streams, size, fps, duration, frame count, platform, determinism",
+    async run(args, io) {
+        const target = await resolveTarget(args, io);
+        if (isExit(target))
+            return target.code;
+        const { file, json, events, loudness, ...rest } = target;
+        const run = await verifyFile(io, { file, ...rest });
+        if (!run.ok) {
+            io.stderr(`${run.message}\n`);
+            return run.code;
+        }
+        const report = await withProbes(io, { file, ...rest }, run.report, run.durationSec, {
+            events,
+            loudness,
+        });
+        const print = json ? formatReportJson : formatReport;
+        io.stdout(print(file, report));
+        return exitCodeForStatus(report.status);
+    },
+};

package/dist/verify/determinism.d.ts

@@ -0,0 +1,30 @@
+import type { VerifyFinding, VerifyReport } from "@anvpx/motion-build";
+import type { Host } from "../types.ts";
+/**
+ * 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 declare 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 declare const DETERMINISM_NOTE: string;
+export interface DeterminismPair {
+    first: string;
+    second: string;
+}
+export interface DeterminismHashes {
+    first: string | undefined;
+    second: string | undefined;
+}
+/** sha256 of both renders; a missing file hashes to undefined (fails closed downstream). */
+export declare function hashPair(host: Host, pair: DeterminismPair): Promise<DeterminismHashes>;
+/** Pure hash comparison: identical passes, anything else is a fatal finding. */
+export declare function determinismFindings(first: string | undefined, second: string | undefined): VerifyFinding[];
+/** Merges gate findings into a verify report; any fatal escalates the status to FAIL. */
+export declare function withDeterminism(report: VerifyReport, findings: readonly VerifyFinding[]): VerifyReport;

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;