@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/voice/manifest.d.ts

@@ -0,0 +1,33 @@
+import { type TimingManifest } from "@anvpx/motion-schema";
+export interface VoiceSceneTimings {
+    id: string;
+    /** Measured wav length, seconds. */
+    durationS: number;
+    /** Aligner words on the clip clock (local to this scene). */
+    words: Array<{
+        w: string;
+        start: number;
+        end: number;
+    }>;
+    /** Silence intervals on the clip clock (local to this scene). */
+    silences?: ReadonlyArray<readonly [number, number]>;
+}
+export type VoiceManifestResult = {
+    ok: true;
+    manifest: TimingManifest;
+} | {
+    ok: false;
+    problems: string[];
+};
+/** Float tolerance for aligner-vs-measured boundary comparison (rounding, not drift). */
+export declare const WORD_BOUND_EPSILON_S = 0.01;
+/**
+ * Voice TimingManifest with per-scene words on the absolute clock plus the
+ * full AudioAnalysis. Durations stay measured (never inferred from spans);
+ * starts are the exact cumulative sums from `buildVoiceManifest`.
+ *
+ * Fail-closed: every local word end must sit within its scene duration
+ * (+ epsilon). Overflow words pass the schema's overlap check but lie past
+ * the clip, so they are rejected here before offsetting to the absolute clock.
+ */
+export declare function buildVoiceManifestWithAnalysis(rows: readonly VoiceSceneTimings[]): VoiceManifestResult;

package/dist/voice/manifest.js

@@ -0,0 +1,69 @@
+import { ALIGN_MODEL_ID, buildVoiceManifest, VOICE_PROVENANCE } from "@anvpx/motion-audio";
+import { TimingManifestSchema, } from "@anvpx/motion-schema";
+/** Float tolerance for aligner-vs-measured boundary comparison (rounding, not drift). */
+export const WORD_BOUND_EPSILON_S = 0.01;
+const checkWordBounds = (rows) => {
+    for (const row of rows) {
+        for (const w of row.words) {
+            if (!(w.end <= row.durationS + WORD_BOUND_EPSILON_S)) {
+                return `scene "${row.id}": word "${w.w}" ends at ${w.end}s beyond duration ${row.durationS}s`;
+            }
+        }
+    }
+    return undefined;
+};
+const offsetScenes = (base, rows, starts) => base.scenes.map((scene) => {
+    const row = rows.find((r) => r.id === scene.id);
+    const start = starts.get(scene.id) ?? scene.start;
+    const words = (row?.words ?? []).map((w) => ({
+        w: w.w,
+        start: start + w.start,
+        end: start + w.end,
+    }));
+    return words.length === 0 ? scene : { ...scene, words };
+});
+/**
+ * Voice TimingManifest with per-scene words on the absolute clock plus the
+ * full AudioAnalysis. Durations stay measured (never inferred from spans);
+ * starts are the exact cumulative sums from `buildVoiceManifest`.
+ *
+ * Fail-closed: every local word end must sit within its scene duration
+ * (+ epsilon). Overflow words pass the schema's overlap check but lie past
+ * the clip, so they are rejected here before offsetting to the absolute clock.
+ */
+export function buildVoiceManifestWithAnalysis(rows) {
+    const overflow = checkWordBounds(rows);
+    if (overflow !== undefined)
+        return { ok: false, problems: [overflow] };
+    const base = buildVoiceManifest(rows.map((row) => ({ id: row.id, durationS: row.durationS })));
+    if (!base.ok)
+        return base;
+    const starts = new Map(base.manifest.scenes.map((scene) => [scene.id, scene.start]));
+    const scenes = offsetScenes(base.manifest, rows, starts);
+    const flatWords = [];
+    for (const scene of scenes) {
+        flatWords.push(...(scene.words ?? []));
+    }
+    const flatSilences = rows.flatMap((row) => {
+        const start = starts.get(row.id) ?? 0;
+        return (row.silences ?? []).map(([s0, s1]) => ({ start: start + s0, end: start + s1 }));
+    });
+    const total = scenes.reduce((sum, scene) => sum + scene.duration, 0);
+    const audio = flatWords.length === 0
+        ? undefined
+        : {
+            words: flatWords,
+            ...(flatSilences.length === 0 ? {} : { silences: [...flatSilences] }),
+            model: ALIGN_MODEL_ID,
+            modelRevision: VOICE_PROVENANCE.alignModelRev,
+            duration: total,
+        };
+    const parsed = TimingManifestSchema.safeParse(audio === undefined ? { source: "voice", scenes } : { source: "voice", scenes, audio });
+    if (!parsed.success) {
+        return {
+            ok: false,
+            problems: parsed.error.issues.map((issue) => `${issue.path.join("/")}: ${issue.message}`),
+        };
+    }
+    return { ok: true, manifest: parsed.data };
+}

package/dist/voice/run.d.ts

@@ -0,0 +1,21 @@
+import type { Io } from "../types.ts";
+export interface VoiceRunOptions {
+    /** Voice id from the storyboard/adapters (never a hardcoded default). */
+    voice: string;
+    /** Manifest path; defaults to `<dir>/.mk/<stem>/voice-manifest.json`. */
+    outPath?: string;
+    /** Directory for per-scene wavs; defaults to `<dir>/.mk/<stem>/audio`. */
+    audioDir?: string;
+    /** Explicit python binary; skips the venv probe when set (tests, custom venvs). */
+    python?: string;
+}
+/** DL-01b voice bar notes (constants, shared with the CLI usage text). */
+export declare const VOICE_WAV_FALLBACK_NOTE = "pre-rendered WAV fallback in pack";
+export declare const VOICE_MEASURED_QC_NOTE = "human QC via `mk qc` (pronunciation/intelligibility/pacing/alignment/no-silence)";
+export declare const VOICE_ENV_NOTE = "BLOCKED_ENV stays NOT_RUN, never PASS";
+/**
+ * Synthesize every narrated base scene, align words, gate silence, and write
+ * `.mk/<stem>/voice-manifest.json` + licences-style provenance. Resolves to
+ * the process exit code; never falls back to silent durations.
+ */
+export declare function runVoice(storyboard: string, options: VoiceRunOptions, io: Io): Promise<number>;

package/dist/voice/run.js

@@ -0,0 +1,181 @@
+import { join } from "node:path";
+import { alignWords, detectSilence, isJapaneseVoice, resolveVenvPython, synthesize, VOICE_PROVENANCE, wordsInSilence, } from "@anvpx/motion-audio";
+import { resolveTimeline, validateStoryboardFull, WORDS_PER_SECOND } from "@anvpx/motion-build";
+import { mkDir } from "../approval/hash.js";
+import { EXIT } from "../exit-codes.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { buildVoiceManifestWithAnalysis } from "./manifest.js";
+const splitTokens = (narration) => narration.split(/\s+/).filter((w) => w.length > 0);
+/** DL-01b voice bar notes (constants, shared with the CLI usage text). */
+export const VOICE_WAV_FALLBACK_NOTE = "pre-rendered WAV fallback in pack";
+export const VOICE_MEASURED_QC_NOTE = "human QC via `mk qc` (pronunciation/intelligibility/pacing/alignment/no-silence)";
+export const VOICE_ENV_NOTE = "BLOCKED_ENV stays NOT_RUN, never PASS";
+const doctorHint = `Run \`mk doctor\` for the voice setup steps. ${VOICE_WAV_FALLBACK_NOTE} when env blocked; ` +
+    `${VOICE_MEASURED_QC_NOTE}; ${VOICE_ENV_NOTE}.`;
+/** Validated storyboard plus its narrated base scenes, or an exit code. */
+async function loadNarrated(storyboard, io) {
+    const loaded = await readJsonFile(storyboard, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk voice: ${loaded.message}\n`);
+        return EXIT.USAGE;
+    }
+    const valid = validateStoryboardFull(loaded.value);
+    if (!valid.ok) {
+        io.stderr("mk voice: storyboard is invalid; run `mk validate`.\n");
+        return EXIT.USAGE;
+    }
+    const narrated = valid.value.scenes.filter((scene) => scene.layer !== "overlay" && (scene.narration?.trim() ?? "") !== "");
+    if (narrated.length === 0) {
+        io.stderr("mk voice: no narrated scenes; nothing to synthesize\n");
+        return EXIT.USAGE;
+    }
+    return { board: valid.value, narrated };
+}
+/** Probe the voice venv (or honor an explicit `--python`); fails closed on absence. */
+async function pickPython(io, explicit) {
+    if (explicit !== undefined)
+        return { python: explicit };
+    const probe = await resolveVenvPython(io.run);
+    if (probe.ok)
+        return { python: probe.python };
+    io.stderr(`mk voice: ${probe.hint}\n${doctorHint}\n`);
+    return { code: EXIT.MISSING_TOOL };
+}
+const synthDuration = async (io, sceneId, narration, voice, audioPath, python) => {
+    const synth = await synthesize(io.run, { text: narration, voice, outPath: audioPath, python });
+    if (synth.ok)
+        return { durationS: synth.durationS };
+    io.stderr(`mk voice: synth for "${sceneId}" failed: ${synth.hint}\n${doctorHint}\n`);
+    return { code: synth.status === "missing" ? EXIT.MISSING_TOOL : EXIT.ERROR };
+};
+const alignSceneWords = async (io, sceneId, audioPath, tokens, python) => {
+    const aligned = await alignWords(io.run, { audioPath, tokens, python });
+    if (aligned.ok)
+        return { words: aligned.words };
+    io.stderr(`mk voice: align for "${sceneId}" failed: ${aligned.hint}\n${doctorHint}\n`);
+    return { code: aligned.status === "missing" ? EXIT.MISSING_TOOL : EXIT.ERROR };
+};
+const gateSilence = async (io, sceneId, audioPath, words) => {
+    const silence = await detectSilence(io.run, { audioPath });
+    if (!silence.ok) {
+        io.stderr(`mk voice: silence gate for "${sceneId}" failed: ${silence.hint}\n`);
+        return { code: silence.status === "missing" ? EXIT.MISSING_TOOL : EXIT.ERROR };
+    }
+    const swallowed = wordsInSilence(words, silence.intervals);
+    if (swallowed.length > 0) {
+        const shown = swallowed
+            .slice(0, 3)
+            .map((word) => `"${word.w}" at ${word.start.toFixed(2)}s`)
+            .join(", ");
+        const more = swallowed.length > 3 ? ", ..." : "";
+        io.stderr(`mk voice: "${sceneId}" has ${swallowed.length} word(s) inside silence (${shown}${more}); refusing fake timing\n`);
+        return { code: EXIT.ERROR };
+    }
+    return { silences: silence.intervals };
+};
+/**
+ * A6: narration must fit the scene at 180 wpm before anything is synthesized.
+ * The render-time reading/narration checks then cannot fail for a length the
+ * voice command could have refused; the fix names the scene and the exact edit.
+ */
+function narrationFitProblems(board) {
+    const timeline = resolveTimeline(board.board);
+    if (!timeline.ok)
+        return timeline.errors.map((error) => `${error.path}: ${error.message}`);
+    const available = new Map(timeline.value.scenes.map((scene) => [scene.id, scene.duration]));
+    return board.narrated.flatMap((scene) => {
+        const count = splitTokens(scene.narration ?? "").length;
+        const needed = Math.ceil(count / WORDS_PER_SECOND);
+        const seconds = available.get(scene.id) ?? scene.duration ?? 0;
+        if (needed <= seconds)
+            return [];
+        const excess = count - Math.floor(seconds * WORDS_PER_SECOND);
+        return [
+            `"${scene.id}": narration ${count} words needs >= ${needed}s at ${WORDS_PER_SECOND} words/s, ` +
+                `scene is ${seconds}s; set duration >= ${needed} or cut ${excess} word(s)`,
+        ];
+    });
+}
+/** Synth + align + silence gate for one narrated scene; fails closed, never fakes.
+ * `j*` (Japanese-pipeline) voices are unaligned-only: the EN wav2vec2 aligner
+ * cannot honestly caption non-ASCII narration, so alignment is skipped and
+ * the scene keeps measured duration with no words (QC stays UNKNOWN, never FAIL).
+ */
+async function voiceScene(io, scene, voice, audioDir, python) {
+    const narration = scene.narration;
+    const audioPath = join(audioDir, `${scene.id}.wav`);
+    const synth = await synthDuration(io, scene.id, narration, voice, audioPath, python);
+    if ("code" in synth)
+        return synth;
+    if (isJapaneseVoice(voice)) {
+        const gated = await gateSilence(io, scene.id, audioPath, []);
+        if ("code" in gated)
+            return gated;
+        return { id: scene.id, durationS: synth.durationS, words: [], silences: gated.silences };
+    }
+    const aligned = await alignSceneWords(io, scene.id, audioPath, splitTokens(narration), python);
+    if ("code" in aligned)
+        return aligned;
+    const gated = await gateSilence(io, scene.id, audioPath, aligned.words);
+    if ("code" in gated)
+        return gated;
+    return {
+        id: scene.id,
+        durationS: synth.durationS,
+        words: aligned.words,
+        silences: gated.silences,
+    };
+}
+/** Build the voice manifest, verify the timing override, and write artifacts. */
+async function finishVoice(args) {
+    const built = buildVoiceManifestWithAnalysis(args.rows);
+    if (!built.ok) {
+        args.io.stderr(`mk voice: refusing to write invalid manifest: ${built.problems.join("; ")}\n`);
+        return EXIT.ERROR;
+    }
+    const timeline = resolveTimeline(args.board, built.manifest);
+    if (!timeline.ok) {
+        args.io.stderr(`mk voice: voice timing does not apply: ${timeline.errors.map((e) => e.message).join("; ")}\n`);
+        return EXIT.ERROR;
+    }
+    const provenance = {
+        voice: args.voice,
+        ...VOICE_PROVENANCE,
+        scenes: args.rows.map((row) => row.id),
+        total: timeline.value.total,
+    };
+    await args.io.host.writeTextAtomic(args.outPath, `${JSON.stringify(built.manifest, null, 2)}\n`);
+    await args.io.host.writeTextAtomic(join(mkDir(args.storyboard), "voice-provenance.json"), `${JSON.stringify(provenance, null, 2)}\n`);
+    args.io.stdout(`voice ok | ${args.rows.length} scenes ${timeline.value.total}s source voice -> ${args.outPath}\n`);
+    return EXIT.OK;
+}
+/**
+ * Synthesize every narrated base scene, align words, gate silence, and write
+ * `.mk/<stem>/voice-manifest.json` + licences-style provenance. Resolves to
+ * the process exit code; never falls back to silent durations.
+ */
+export async function runVoice(storyboard, options, io) {
+    const board = await loadNarrated(storyboard, io);
+    if (typeof board === "number")
+        return board;
+    const misfit = narrationFitProblems(board);
+    if (misfit.length > 0) {
+        io.stderr(`mk voice: narration does not fit before synthesis:\n${misfit.map((line) => `  - ${line}`).join("\n")}\n`);
+        return EXIT.USAGE;
+    }
+    const picked = await pickPython(io, options.python);
+    if (!("python" in picked))
+        return picked.code;
+    const audioDir = options.audioDir ?? join(mkDir(storyboard), "audio");
+    const outPath = options.outPath ?? join(mkDir(storyboard), "voice-manifest.json");
+    // A6: first runs used to fail here because the synthesizer cannot create its own directory.
+    await io.host.mkdir?.(audioDir);
+    const rows = [];
+    for (const scene of board.narrated) {
+        const timed = await voiceScene(io, scene, options.voice, audioDir, picked.python);
+        if ("code" in timed)
+            return timed.code;
+        rows.push(timed);
+    }
+    return finishVoice({ board: board.board, storyboard, rows, voice: options.voice, outPath, io });
+}

package/dist/workflow/build.d.ts

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

package/dist/workflow/build.js

@@ -0,0 +1,25 @@
+import { EXIT } from "../exit-codes.js";
+import { parseBuildArgs, prepareProject } from "./project.js";
+const USAGE = `mk build <storyboard.json> [--out <dir>] [--assets <dir>] [--ledger <assets.json>] [--incremental] [--clean-cache] [--shared-cache-dir <dir>]
+
+Validate the storyboard and compile it into a HyperFrames project.
+  --out <dir>          project directory (default: <storyboard dir>/out/project)
+  --assets <dir>       directory that asset refs are relative to
+  --ledger <file>      asset licence ledger (assets.json); every copied asset needs a row
+  --incremental        reuse unchanged scenes from <storyboard dir>/.mk-cache (output is byte-identical);
+                       prints "cache: N hit / M miss"; draft, render and still accept it too
+  --no-incremental     build without the cache (the default)
+  --clean-cache        delete the cache first (cache files only)
+  --shared-cache-dir <dir>  opt-in shared cache across storyboards (requires --incremental); absent means per-storyboard only
+`;
+export const buildCommand = {
+    name: "build",
+    summary: "validate a storyboard and compile it into a HyperFrames project",
+    async run(args, io) {
+        const parsed = parseBuildArgs("build", USAGE, args, {}, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const prepared = await prepareProject(parsed.request, io);
+        return prepared.ok ? EXIT.OK : prepared.code;
+    },
+};

package/dist/workflow/draft.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "../types.ts";
+/**
+ * `mk draft`. `lint: false` is for `mk preview`'s clip only: its scenes are cut to a couple of
+ * seconds on purpose, which the authored-work rules (reading time, minimum hold) would reject.
+ */
+export declare const makeDraftCommand: (options?: {
+    lint?: boolean;
+}) => Command;
+export declare const draftCommand: Command;

package/dist/workflow/draft.js

@@ -0,0 +1,201 @@
+import { dirname, join, resolve } from "node:path";
+import { validateMusicBed } from "@anvpx/motion-audio";
+import { AUDIO_DIR_NAME, clipsFromManifest, missingMusic, mixAtDeliveryLevel, parseAudioManifest, } from "@anvpx/motion-build";
+import { textFlag, usageError } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { runInProject } from "../tooling/session.js";
+import { DRAFT_FPS, DRAFT_WIDTH, draftExpectation, draftHeight } from "../verify/expectation.js";
+import { finishRender } from "./finish.js";
+import { parseBuildArgs, prepareProject } from "./project.js";
+const USAGE = `mk draft <storyboard.json> [--out <dir>] [--assets <dir>] [--ledger <assets.json>] [--verify] [--audio <manifest>] [--music <wav>]
+
+Build, then render a fast 960 px wide draft at 15 fps to <out>/draft.mp4.
+hyperframes only renders at the composition size or larger (--resolution presets start at
+1080p), so it renders 1080p with --quality draft and ffmpeg downscales with lanczos.
+Output of the tools: <out>/render-log.txt; provenance: <out>/render-manifest.json.
+  --audio <manifest> voice TimingManifest: mix per-scene wavs (the manifest's
+               sibling audio/ dir, <id>.wav) under the render at absolute
+               starts. Absent means silent video; missing wavs fail instead.
+  --music <wav> user CC0 music bed: loops to the narration length, ducks under
+                narration via sidechaincompress, then joins it. Requires
+                --audio; a missing bed wav fails instead of silence.
+  --verify   re-probe draft.mp4 (see \`mk verify\`); exit 5 on FAIL
+`;
+const FULL_SIZE = "draft-full.mp4";
+/** Narrated intermediate when --audio mixes before the downscale. */
+const MIXED_SIZE = "draft-mixed.mp4";
+const DRAFT = "draft.mp4";
+const downscale = (input, output) => [
+    "-y",
+    "-i",
+    input,
+    "-vf",
+    `scale=${DRAFT_WIDTH}:-2:flags=lanczos`,
+    "-c:v",
+    "libx264",
+    "-preset",
+    "veryfast",
+    "-crf",
+    "23",
+    "-pix_fmt",
+    "yuv420p",
+    "-movflags",
+    "+faststart",
+    "-c:a",
+    "copy",
+    output,
+];
+/** Loads a voice TimingManifest plus its sibling wavs; fails closed, never silent. */
+async function loadNarration(audioPath, io) {
+    const loaded = await readJsonFile(audioPath, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk draft: cannot read --audio manifest: ${loaded.message}\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    const parsed = parseAudioManifest(loaded.value);
+    if (!parsed.ok) {
+        io.stderr(`mk draft: invalid --audio manifest: ${parsed.problems.join("; ")}\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    const audioDir = join(dirname(resolve(audioPath)), AUDIO_DIR_NAME);
+    const clips = clipsFromManifest(parsed.manifest, audioDir);
+    if (clips.length === 0) {
+        io.stderr("mk draft: --audio manifest has no scenes; nothing to mix\n");
+        return { ok: false, code: EXIT.USAGE };
+    }
+    // NOTE (AU-01 scope): missing-only fails closed here; draft is explicitly
+    // non-approved, so audible/silent enforcement lives in the preview gate
+    // (mixPreviewClip silent reject → approve refuses unheard audio).
+    for (const clip of clips) {
+        if (!(await io.host.exists(clip.wav))) {
+            io.stderr(`mk draft: missing narration wav for scene "${clip.id}": ${clip.wav}\n`);
+            return { ok: false, code: EXIT.ERROR };
+        }
+    }
+    return { ok: true, clips, manifest: parsed.manifest };
+}
+/** Validates the explicit user bed through the audio guard; fails closed, never silent. */
+async function loadMusic(musicPath, io) {
+    const validated = validateMusicBed({ wav: musicPath });
+    if (!validated.ok) {
+        io.stderr(`mk draft: invalid --music bed: ${validated.hint}\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    const present = await io.host.exists(validated.bed.wav);
+    if (missingMusic(validated.bed, () => present).length > 0) {
+        io.stderr(`mk draft: missing music bed wav: ${validated.bed.wav}\n`);
+        return { ok: false, code: EXIT.ERROR };
+    }
+    return { ok: true, music: validated.bed };
+}
+/** Parses flags and fails fast on bad input or a missing voice wav. */
+async function resolveDraftPlan(args, io) {
+    const parsed = parseBuildArgs("draft", USAGE, args, { verify: { type: "boolean" }, audio: { type: "string" }, music: { type: "string" } }, io);
+    if (parsed.kind === "exit")
+        return { code: parsed.code };
+    const audioPath = textFlag(parsed.flags, "audio");
+    const musicPath = textFlag(parsed.flags, "music");
+    if (musicPath !== undefined && audioPath === undefined) {
+        return {
+            code: usageError("draft", USAGE, "--music needs --audio: the bed loops to the narration length", io).code,
+        };
+    }
+    const narration = audioPath === undefined ? undefined : await loadNarration(audioPath, io);
+    if (narration !== undefined && !narration.ok)
+        return { code: narration.code };
+    const bedded = musicPath === undefined ? undefined : await loadMusic(musicPath, io);
+    if (bedded !== undefined && !bedded.ok)
+        return { code: bedded.code };
+    return {
+        request: narration?.manifest === undefined
+            ? parsed.request
+            : { ...parsed.request, timing: narration.manifest },
+        verify: parsed.flags.verify === true,
+        narration: narration?.clips,
+        music: bedded?.music,
+    };
+}
+/** Renders silent full-size video, mixes narration when requested, then downscales. */
+async function runDraft(io, outDir, plan) {
+    const full = join(outDir, FULL_SIZE);
+    const mixed = join(outDir, MIXED_SIZE);
+    const draft = join(outDir, DRAFT);
+    let deliveryFailed = false;
+    const code = await runInProject(io, outDir, async (session) => {
+        const rendered = await session.hf([
+            "render",
+            ".",
+            "-o",
+            FULL_SIZE,
+            "--fps",
+            String(DRAFT_FPS),
+            "--quality",
+            "draft",
+            "--quiet",
+        ]);
+        if (plan.narration !== undefined) {
+            const delivery = await mixAtDeliveryLevel((argv) => session.probe("ffmpeg", argv), {
+                videoIn: full,
+                clips: plan.narration,
+                ...(plan.music === undefined ? {} : { music: plan.music }),
+                out: mixed,
+                swap: async (from, to) => {
+                    await io.host.copyFile(from, to);
+                    await io.host.remove(from);
+                },
+            });
+            // ADR-0008 D3 applies to the draft consumer too: a typed failed delivery
+            // is a failed command, not a logged problem, and never becomes draft.mp4.
+            if (!delivery.ok) {
+                const problems = delivery.problems.length > 0 ? delivery.problems : ["mix delivery failed"];
+                io.stderr(`mk draft: ${problems.join("; ")}\n`);
+                await io.host.remove(mixed).catch(() => undefined);
+                await io.host.remove(`${mixed}.loudnorm.mp4`).catch(() => undefined);
+                deliveryFailed = true;
+                return;
+            }
+            if (delivery.problems.length > 0) {
+                io.stderr(`mk draft: ${delivery.problems.join("; ")}\n`);
+            }
+        }
+        if (rendered)
+            await session.tool("ffmpeg", downscale(plan.narration === undefined ? full : mixed, draft));
+    });
+    await io.host.remove(full);
+    if (plan.narration !== undefined)
+        await io.host.remove(mixed);
+    return deliveryFailed ? EXIT.ERROR : code;
+}
+/**
+ * `mk draft`. `lint: false` is for `mk preview`'s clip only: its scenes are cut to a couple of
+ * seconds on purpose, which the authored-work rules (reading time, minimum hold) would reject.
+ */
+export const makeDraftCommand = (options = {}) => ({
+    name: "draft",
+    summary: "build, then render a fast 960x540 15 fps draft.mp4",
+    async run(args, io) {
+        const plan = await resolveDraftPlan(args, io);
+        if ("code" in plan)
+            return plan.code;
+        const request = options.lint === false ? { ...plan.request, lint: false } : plan.request;
+        const prepared = await prepareProject(request, io);
+        if (!prepared.ok)
+            return prepared.code;
+        const code = await runDraft(io, prepared.outDir, plan);
+        if (code !== 0)
+            return code;
+        const { total, meta } = prepared;
+        const draft = join(prepared.outDir, DRAFT);
+        return finishRender(io, {
+            record: {
+                kind: "draft",
+                outDir: prepared.outDir,
+                file: draft,
+                params: { fps: DRAFT_FPS, quality: "draft", width: DRAFT_WIDTH, height: draftHeight(meta) },
+            },
+            ...(plan.verify ? { verify: draftExpectation(meta, total) } : {}),
+        });
+    },
+});
+export const draftCommand = makeDraftCommand();

package/dist/workflow/finish.d.ts

@@ -0,0 +1,23 @@
+import type { MediaExpectation, VerifyReport } from "@anvpx/motion-build";
+import type { Io } from "../types.ts";
+import { type RenderRecord } from "./provenance.ts";
+export interface Finish {
+    record: Omit<RenderRecord, "verify">;
+    /** Present when `--verify` was given: what the output must look like. */
+    verify?: MediaExpectation;
+}
+export type FinishStatus = VerifyReport["status"] | "not-run";
+export interface FinishLines {
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * What to report after the render manifest is written. A failed render is not a deliverable,
+ * so its path never reaches stdout: the one line a caller may relay is the refusal.
+ */
+export declare function finishLines(file: string, status: FinishStatus): FinishLines;
+/**
+ * After a successful render: verify it (QA failure is EXIT.QA_FAIL), write
+ * `render-manifest.json` recording that status, then report only what was proven.
+ */
+export declare function finishRender(io: Io, finish: Finish): Promise<number>;

package/dist/workflow/finish.js

@@ -0,0 +1,28 @@
+import { verifyStep } from "../verify/run.js";
+import { writeRenderManifest } from "./provenance.js";
+/**
+ * What to report after the render manifest is written. A failed render is not a deliverable,
+ * so its path never reaches stdout: the one line a caller may relay is the refusal.
+ */
+export function finishLines(file, status) {
+    if (status === "FAIL") {
+        return { stdout: "", stderr: `mk: QA FAILED, do not deliver: ${file}\n` };
+    }
+    return { stdout: `${file}\n`, stderr: "" };
+}
+/**
+ * After a successful render: verify it (QA failure is EXIT.QA_FAIL), write
+ * `render-manifest.json` recording that status, then report only what was proven.
+ */
+export async function finishRender(io, finish) {
+    const verified = finish.verify
+        ? await verifyStep(io, { file: finish.record.file, expect: finish.verify })
+        : { code: 0, status: "not-run" };
+    await writeRenderManifest(io, { ...finish.record, verify: verified.status });
+    const lines = finishLines(finish.record.file, verified.status);
+    if (lines.stdout !== "")
+        io.stdout(lines.stdout);
+    if (lines.stderr !== "")
+        io.stderr(lines.stderr);
+    return verified.code;
+}