@anvpx/motion-cli 0.0.0-stage → 0.1.0

package/dist/workflow/render.js

@@ -0,0 +1,705 @@
+import { dirname, join, resolve } from "node:path";
+import { validateMusicBed } from "@anvpx/motion-audio";
+import { AUDIO_DIR_NAME, clipsFromManifest, compiledAssetMismatches, frozenClips, frozenCopyProblems, frozenMusic, isContiguous, missingMusic, mixAtDeliveryLevel, parseAudioManifest, } from "@anvpx/motion-build";
+import { approvalState, readApproval } from "../approval/approval.js";
+import { buildApprovalInputManifest, hashApprovalInput, } from "../approval/hash.js";
+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 { finalExpectation } from "../verify/expectation.js";
+import { finishRender } from "./finish.js";
+import { parseBuildArgs, prepareProject } from "./project.js";
+const USAGE = `mk render <storyboard.json> [--out <dir>] [--fps 30] [--format mp4|webm|mov|gif|png-sequence] [--resolution 1080p|4k] [--resume] [--assets <dir>] [--ledger <assets.json>] [--verify] [--gated] [--audio <manifest>] [--music <wav>]
+
+Build, then render the final H.264 mp4 to <out>/final.mp4 with \`hyperframes render --quality delivery\`
+(x264 preset slow, CRF 15; size and colour come from the storyboard meta).
+  --fps <n>    integer frame rate 1-240 (default 30)
+  --format f   delivery container: mp4 (default), webm, mov (ProRes 4444), gif or png-sequence.
+               Non-mp4 formats are converted from the rendered master with ffmpeg; \`--verify\` stays mp4-only.
+  --resolution r  1080p (default) or 4k (landscape/portrait/square chosen from the storyboard frame)
+  --resume     continue an interrupted render: uses hyperframes' segmented capture
+                (HF_SEGMENTED_CAPTURE=true + --resume) and reuses finished segments
+  --verify     re-probe final.mp4 (see \`mk verify\`); exit 5 on FAIL
+  --audio <manifest>
+               voice TimingManifest: mix each scene's wav (the manifest's sibling
+               audio/ dir, <id>.wav) under the render at its absolute start.
+               Absent means silent video; a missing/silent wav fails instead of silence.
+               With gated, the identical approved audio manifest is required:
+               any wav, manifest, mix, bed, volume or license drift exits 4;
+               a visual-only receipt never authorizes audio, narration-only
+               never authorizes music.
+  --music <wav>
+                user CC0 music bed: loops to the narration length, ducks under
+                narration via sidechaincompress (same buildMusicMixArgs as
+                preview), then joins it. Requires --audio; a missing/silent bed
+                wav fails instead of silence. With --gated the identical approved
+                bed, volume and license receipt are required: any drift exits 4.
+                Music is covered by the same gate, not a parallel one.
+  --music-volume <n>  bed level within (0, 1] (default 0.5)
+  --music-license <file>  license-evidence file hashed into the receipt (hash only)
+  --gated      require a current approval (storyboard + themes + exact
+               referenced assets + ledger + (for audiovisual) audio manifest, no timestamp/machine path in hash);
+               any mismatch exits 4 with one fix line; inputs are rechecked
+               before publication so a mid-render edit cannot slip through.
+Output of hyperframes: <out>/render-log.txt; provenance: <out>/render-manifest.json.
+`;
+const FINAL = "final.mp4";
+/** Silent intermediate when --audio mixes narration underneath. */
+const SILENT = "final-silent.mp4";
+/** This attempt's mixed output; published over FINAL only when delivery succeeded. */
+const MIX_TEMP = "final-mix.mp4";
+/** This attempt's direct video (visual-only gated run); published only after the last gate. */
+const VIDEO_TEMP = "final-video.mp4";
+/** Frozen approved audio: the only bytes ffmpeg is allowed to consume. */
+const FROZEN_DIR = ".frozen-audio";
+const DEFAULT_FPS = "30";
+const MAX_FPS = 240;
+/** hyperframes only honours --resume when segmented capture is switched on. */
+const SEGMENTED_CAPTURE = { HF_SEGMENTED_CAPTURE: "true" };
+/** Delivery containers the command can write (the master is always final.mp4). */
+export const DELIVERY_FORMATS = ["mp4", "webm", "mov", "gif", "png-sequence"];
+export const RESOLUTIONS = ["1080p", "4k"];
+const isDeliveryFormat = (value) => DELIVERY_FORMATS.includes(value);
+/** `4k` maps to the hyperframes preset that matches the storyboard's aspect. */
+export const resolutionPreset = (width, height) => {
+    const ratio = width / height;
+    if (ratio > 1.2)
+        return "landscape-4k";
+    if (ratio < 0.8)
+        return "portrait-4k";
+    return "square-4k";
+};
+/** Output of a non-mp4 format: `final.<ext>`, or the `final.frames` directory for a PNG sequence. */
+export const exportFile = (outDir, format) => join(outDir, format === "png-sequence" ? "final.frames" : `final.${format}`);
+/** ffmpeg argv for the delivery conversion; the master mp4 is the source of truth. */
+export const exportArgs = (master, format, outDir) => {
+    const file = exportFile(outDir, format);
+    const target = format === "png-sequence" ? join(file, "%04d.png") : file;
+    const head = ["-y", "-hide_banner", "-loglevel", "error", "-i", master];
+    switch (format) {
+        case "webm":
+            return {
+                file,
+                args: [
+                    ...head,
+                    "-c:v",
+                    "libvpx-vp9",
+                    "-b:v",
+                    "0",
+                    "-crf",
+                    "32",
+                    "-c:a",
+                    "libopus",
+                    "-b:a",
+                    "128k",
+                    target,
+                ],
+            };
+        case "mov":
+            return {
+                file,
+                args: [...head, "-c:v", "prores_ks", "-profile:v", "4444", "-c:a", "pcm_s16le", target],
+            };
+        case "gif":
+            return {
+                file,
+                args: [
+                    ...head,
+                    "-vf",
+                    "fps=15,scale=960:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse",
+                    "-loop",
+                    "0",
+                    target,
+                ],
+            };
+        case "png-sequence":
+            return { file, args: [...head, "-vsync", "0", target] };
+    }
+};
+/** Converts the published master into the requested delivery format. */
+export async function exportArtifact(io, outDir, format) {
+    const master = join(outDir, FINAL);
+    const { args, file } = exportArgs(master, format, outDir);
+    if (format === "png-sequence")
+        await io.host.mkdir?.(file);
+    const result = await io.run("ffmpeg", args);
+    if (result.code !== 0) {
+        io.stderr(`mk render: converting to ${format} failed: ${result.stderr.slice(-500) || `exit ${result.code}`}\n`);
+        return { ok: false, code: EXIT.ERROR };
+    }
+    return { ok: true, file };
+}
+/** sha256 of zero bytes: a silent/empty wav can never qualify as audible proof. */
+const EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+const isFps = (text) => /^\d+$/.test(text) && Number(text) >= 1 && Number(text) <= MAX_FPS;
+/** Loads a voice TimingManifest plus its sibling wavs; fails closed, never silent. */
+async function loadNarration(name, audioPath, io) {
+    const loaded = await readJsonFile(audioPath, io.host);
+    if (!loaded.ok) {
+        io.stderr(`mk ${name}: cannot read --audio manifest: ${loaded.message}\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    const parsed = parseAudioManifest(loaded.value);
+    if (!parsed.ok) {
+        io.stderr(`mk ${name}: 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 ${name}: --audio manifest has no scenes; nothing to mix\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    for (const clip of clips) {
+        if (!(await io.host.exists(clip.wav))) {
+            io.stderr(`mk ${name}: missing narration wav for scene "${clip.id}": ${clip.wav}\n`);
+            return { ok: false, code: EXIT.ERROR };
+        }
+        // AU-01 MEDIUM: ungated --audio must reject silent wavs like the manifest
+        // path does (hash.ts EMPTY_SHA256); never mix silence as narration.
+        const digest = await io.host.sha256File(clip.wav);
+        if (digest === EMPTY_SHA256) {
+            io.stderr(`mk ${name}: narration wav is silent/empty for scene "${clip.id}": ${clip.wav}\n`);
+            return { ok: false, code: EXIT.USAGE };
+        }
+    }
+    return { ok: true, clips, manifest: parsed.manifest };
+}
+/** Validates the explicit user bed through the audio guard; fails closed, never silent. */
+async function loadMusic(name, musicPath, io, musicVolume) {
+    const validated = validateMusicBed(musicVolume === undefined ? { wav: musicPath } : { wav: musicPath, volume: musicVolume });
+    if (!validated.ok) {
+        io.stderr(`mk ${name}: 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 ${name}: missing music bed wav: ${validated.bed.wav}\n`);
+        return { ok: false, code: EXIT.ERROR };
+    }
+    const digest = await io.host.sha256File(validated.bed.wav);
+    if (digest === undefined) {
+        io.stderr(`mk ${name}: missing music bed wav: ${validated.bed.wav}\n`);
+        return { ok: false, code: EXIT.ERROR };
+    }
+    if (digest === EMPTY_SHA256) {
+        io.stderr(`mk ${name}: music bed wav is silent/empty: ${validated.bed.wav}\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    return { ok: true, music: validated.bed };
+}
+/** Request with the voice timing override, or the base request without audio. */
+const withVoiceTiming = (request, manifest) => (manifest === undefined ? request : { ...request, timing: manifest });
+/** Parses flags and fails fast on bad input or a missing voice wav. */
+async function resolvePlan(args, io) {
+    const flags = {
+        fps: { type: "string" },
+        format: { type: "string" },
+        resolution: { type: "string" },
+        resume: { type: "boolean" },
+        verify: { type: "boolean" },
+        gated: { type: "boolean" },
+        audio: { type: "string" },
+        music: { type: "string" },
+        "music-volume": { type: "string" },
+        "music-license": { type: "string" },
+    };
+    const parsed = parseBuildArgs("render", USAGE, args, flags, io);
+    if (parsed.kind === "exit")
+        return { code: parsed.code };
+    const fps = textFlag(parsed.flags, "fps") ?? DEFAULT_FPS;
+    if (!isFps(fps))
+        return { code: usageError("render", USAGE, `--fps must be an integer 1-${MAX_FPS}`, io).code };
+    const formatRaw = textFlag(parsed.flags, "format") ?? "mp4";
+    if (!isDeliveryFormat(formatRaw)) {
+        return {
+            code: usageError("render", USAGE, `--format must be ${DELIVERY_FORMATS.join("|")}`, io).code,
+        };
+    }
+    const resolutionRaw = textFlag(parsed.flags, "resolution") ?? "1080p";
+    if (resolutionRaw !== "1080p" && resolutionRaw !== "4k") {
+        return {
+            code: usageError("render", USAGE, `--resolution must be ${RESOLUTIONS.join("|")}`, io).code,
+        };
+    }
+    if (formatRaw !== "mp4" && parsed.flags.verify === true) {
+        return {
+            code: usageError("render", USAGE, "--verify supports the mp4 master only", io).code,
+        };
+    }
+    const audioPath = textFlag(parsed.flags, "audio");
+    const musicPath = textFlag(parsed.flags, "music");
+    const musicVolumeRaw = textFlag(parsed.flags, "music-volume");
+    const musicLicensePath = textFlag(parsed.flags, "music-license");
+    let musicVolume;
+    if (musicVolumeRaw !== undefined) {
+        musicVolume = Number(musicVolumeRaw);
+        if (!Number.isFinite(musicVolume) || musicVolume <= 0 || musicVolume > 1) {
+            return { code: usageError("render", USAGE, "--music-volume must be within (0, 1]", io).code };
+        }
+    }
+    if ((musicVolumeRaw !== undefined || musicLicensePath !== undefined) && musicPath === undefined) {
+        return {
+            code: usageError("render", USAGE, "--music-volume/--music-license need --music", io).code,
+        };
+    }
+    if (musicPath !== undefined && audioPath === undefined) {
+        return {
+            code: usageError("render", USAGE, "--music needs --audio: the bed loops to the narration length", io).code,
+        };
+    }
+    const narration = audioPath === undefined ? undefined : await loadNarration("render", audioPath, io);
+    if (narration !== undefined && !narration.ok)
+        return { code: narration.code };
+    const bedded = musicPath === undefined ? undefined : await loadMusic("render", musicPath, io, musicVolume);
+    if (bedded !== undefined && !bedded.ok)
+        return { code: bedded.code };
+    if (musicLicensePath !== undefined) {
+        const licDigest = await io.host.sha256File(musicLicensePath);
+        if (licDigest === undefined) {
+            io.stderr(`mk render: cannot read --music-license ${musicLicensePath}: not found\n`);
+            return { code: EXIT.USAGE };
+        }
+    }
+    let resolutionArg;
+    if (resolutionRaw === "4k") {
+        const loaded = await readJsonFile(parsed.request.storyboard, io.host);
+        if (!loaded.ok) {
+            io.stderr(`mk render: cannot read the storyboard for --resolution 4k: ${loaded.message}\n`);
+            return { code: EXIT.USAGE };
+        }
+        const meta = loaded.value.meta;
+        const width = typeof meta?.width === "number" ? meta.width : 1920;
+        const height = typeof meta?.height === "number" ? meta.height : 1080;
+        resolutionArg = resolutionPreset(width, height);
+    }
+    return {
+        request: withVoiceTiming(parsed.request, narration?.manifest),
+        fps,
+        format: formatRaw,
+        resolution: resolutionRaw,
+        resolutionArg,
+        resume: parsed.flags.resume === true,
+        verify: parsed.flags.verify === true,
+        gated: parsed.flags.gated === true,
+        narration: narration?.clips,
+        audioManifest: audioPath,
+        music: bedded?.music,
+        musicPath,
+        musicVolume,
+        musicLicensePath,
+    };
+}
+/**
+ * `--gated`: undefined when the CURRENT inputs (visual or audiovisual) are
+ * approved, else EXIT.AWAITING_APPROVAL with one fix line. A visual-only
+ * receipt never authorizes audio: resolving with --audio recomputes the
+ * audiovisual hash, which cannot match. Fails closed on unreadable
+ * inputs (missing asset, ledger, wav…): exit 2. An unreadable storyboard is
+ * left to the normal build path to report.
+ */
+async function gatedGate(io, request, audioManifest, musicOpts = {}) {
+    let state;
+    try {
+        state = await approvalState(io.host, request.storyboard, {
+            ...(request.assetsDir === undefined ? {} : { assetsDir: request.assetsDir }),
+            ...(request.ledger === undefined ? {} : { ledgerPath: request.ledger }),
+            ...(audioManifest === undefined ? {} : { audioManifest }),
+            ...(musicOpts.musicPath === undefined ? {} : { music: musicOpts.musicPath }),
+            ...(musicOpts.musicVolume === undefined ? {} : { musicVolume: musicOpts.musicVolume }),
+            ...(musicOpts.musicLicensePath === undefined
+                ? {}
+                : { musicLicense: musicOpts.musicLicensePath }),
+        });
+    }
+    catch (error) {
+        io.stderr(`mk render: cannot resolve approval inputs for gated render: ${error.message}\n`);
+        return EXIT.USAGE;
+    }
+    if (state.state === "approved")
+        return undefined;
+    const scope = audioManifest === undefined ? "visual" : "audiovisual";
+    const why = state.state === "stale"
+        ? `the ${scope} inputs (storyboard, themes, referenced assets, ledger${audioManifest === undefined ? "" : ", audio manifest, wavs, mix, bed, volume or license"}) changed since approval`
+        : "no approval recorded";
+    return awaitingApproval(io, request, audioManifest, state.hash, why, musicOpts);
+}
+/** One AWAITING_APPROVAL line with the fix: preview, show the user, explicit yes, approve. */
+function awaitingApproval(io, request, audioManifest, hash, why, musicOpts = {}) {
+    const audioFlag = audioManifest === undefined ? "" : ` --audio ${audioManifest}`;
+    const musicFlag = musicOpts.musicPath === undefined ? "" : ` --music ${musicOpts.musicPath}`;
+    const musicVolumeFlag = musicOpts.musicVolume === undefined ? "" : ` --music-volume ${musicOpts.musicVolume}`;
+    const musicLicenseFlag = musicOpts.musicLicensePath === undefined
+        ? ""
+        : ` --music-license ${musicOpts.musicLicensePath}`;
+    const audioMusicFlags = `${audioFlag}${musicFlag}${musicVolumeFlag}${musicLicenseFlag}`;
+    io.stderr(`mk: AWAITING_APPROVAL (${hash.slice(0, 12)}): ${why}. Run \`mk preview ${request.storyboard}${audioMusicFlags}\`, show the user the pack, and only after an explicit yes run \`mk approve ${request.storyboard}${audioMusicFlags}\`.\n`);
+    return EXIT.AWAITING_APPROVAL;
+}
+async function checkPrePublish(io, request, audioManifest, outDir, musicOpts = {}) {
+    let manifest;
+    try {
+        manifest = await buildApprovalInputManifest(io.host, request.storyboard, {
+            ...(request.assetsDir === undefined ? {} : { assetsDir: request.assetsDir }),
+            ...(request.ledger === undefined ? {} : { ledgerPath: request.ledger }),
+            ...(audioManifest === undefined ? {} : { audioManifest }),
+            ...(musicOpts.musicPath === undefined ? {} : { music: musicOpts.musicPath }),
+            ...(musicOpts.musicVolume === undefined ? {} : { musicVolume: musicOpts.musicVolume }),
+            ...(musicOpts.musicLicensePath === undefined
+                ? {}
+                : { musicLicense: musicOpts.musicLicensePath }),
+        });
+    }
+    catch (error) {
+        io.stderr(`mk render: cannot resolve approval inputs for gated render: ${error.message}\n`);
+        return { ok: false, code: EXIT.USAGE };
+    }
+    const sha = hashApprovalInput(manifest);
+    const stored = await readApproval(io.host, request.storyboard);
+    if (stored === undefined || stored.inputManifestSha256 !== sha) {
+        const scope = audioManifest === undefined ? "visual" : "audiovisual";
+        const why = stored === undefined
+            ? "no approval recorded"
+            : `the ${scope} inputs (storyboard, themes, referenced assets, ledger${audioManifest === undefined ? "" : ", audio manifest, wavs, mix, bed, volume or license"}) changed since approval`;
+        return {
+            ok: false,
+            code: awaitingApproval(io, request, audioManifest, sha, why, musicOpts),
+        };
+    }
+    let files;
+    try {
+        const parsed = JSON.parse(await io.host.readText(join(outDir, "manifest.json")));
+        if (typeof parsed !== "object" || parsed === null || !("files" in parsed)) {
+            throw new Error("compiled manifest has no files map");
+        }
+        const candidate = parsed.files;
+        if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) {
+            throw new Error("compiled manifest has no files map");
+        }
+        files = candidate;
+    }
+    catch (error) {
+        io.stderr(`mk render: cannot verify the compiled snapshot before publishing: ${error.message}\n`);
+        return { ok: false, code: EXIT.ERROR };
+    }
+    const mismatches = compiledAssetMismatches(files, manifest.assets);
+    if (mismatches.length > 0) {
+        return {
+            ok: false,
+            code: awaitingApproval(io, request, audioManifest, sha, `the built media changed since approval (${mismatches.join("; ")})`, musicOpts),
+        };
+    }
+    return { ok: true, manifest, sha };
+}
+/**
+ * ADR-0008 D1/D2: copies the approved narration and bed into the frozen layout
+ * before any external tool runs, and checks the copies against the approved
+ * digests twice - right after the copy (catches a file that changes only while
+ * its bytes are read and is restored before the post-run recheck) and again
+ * immediately before ffmpeg opens them (the render can take minutes; the post
+ * run gate re-resolves the mutable sources, not the frozen copies). Both checks
+ * refuse through the existing approval path (exit 4); missing or empty copies
+ * fail even without an approval.
+ */
+async function copyFrozenInputs(io, outDir, narration, music) {
+    const frozenDir = join(outDir, FROZEN_DIR);
+    const frozenNarration = frozenClips(narration, frozenDir);
+    const frozenBed = music === undefined ? undefined : frozenMusic(music, frozenDir);
+    for (const [index, clip] of frozenNarration.entries()) {
+        const source = narration[index];
+        if (source === undefined)
+            continue;
+        try {
+            await io.host.copyFile(source.wav, clip.wav);
+        }
+        catch (error) {
+            io.stderr(`mk render: cannot freeze narration wavs: ${error.message}\n`);
+            return { ok: false, code: EXIT.ERROR };
+        }
+    }
+    if (frozenBed !== undefined && music !== undefined) {
+        try {
+            await io.host.copyFile(music.wav, frozenBed.wav);
+        }
+        catch (error) {
+            io.stderr(`mk render: cannot freeze music bed: ${error.message}\n`);
+            return { ok: false, code: EXIT.ERROR };
+        }
+    }
+    return {
+        ok: true,
+        narration: frozenNarration,
+        ...(frozenBed === undefined ? {} : { music: frozenBed }),
+    };
+}
+/**
+ * Every reason the frozen state is not the approved state: missing/empty/
+ * mismatched bytes, and a clip list that no longer lines up with the approved
+ * `mix.clips` (count, id, start, mix mode). Alignment matters because the
+ * narration used for the build is loaded before the approval is re-resolved; an
+ * extra or reordered clip must not ride along on a matching file digest.
+ */
+async function frozenApprovalProblems(io, frozen, narration, plan, approved) {
+    const checks = [];
+    for (const [index, clip] of frozen.narration.entries()) {
+        checks.push({
+            label: `narration "${clip.id}" (${clip.wav})`,
+            actualSha256: await io.host.sha256File(clip.wav),
+            expectedSha256: approved?.manifest.mix?.clips[index]?.wavSha,
+        });
+    }
+    if (frozen.music !== undefined) {
+        checks.push({
+            label: `music bed (${frozen.music.wav})`,
+            actualSha256: await io.host.sha256File(frozen.music.wav),
+            expectedSha256: approved?.manifest.music?.sha256,
+        });
+        if (plan.musicLicensePath !== undefined && approved?.manifest.music !== undefined) {
+            checks.push({
+                label: `music license evidence (${plan.musicLicensePath})`,
+                actualSha256: await io.host.sha256File(plan.musicLicensePath),
+                expectedSha256: approved.manifest.music.licenseEvidenceSha256 ?? undefined,
+            });
+        }
+    }
+    const problems = frozenCopyProblems(checks);
+    if (approved === undefined)
+        return problems;
+    const expected = approved.manifest.mix?.clips ?? [];
+    if (expected.length !== narration.length) {
+        problems.push(`the approved mix has ${expected.length} clips but ${narration.length} were prepared`);
+    }
+    for (const [index, clip] of narration.entries()) {
+        const want = expected[index];
+        if (want === undefined)
+            continue;
+        if (want.id !== clip.id || want.start !== clip.start) {
+            problems.push(`narration ${index + 1} does not match the approved clip "${want.id}" at ${want.start}s`);
+        }
+    }
+    if (approved.manifest.mix !== undefined) {
+        const mode = narration.length === 1 ? "single" : isContiguous(narration) ? "concat" : "adelay";
+        if (approved.manifest.mix.mode !== mode) {
+            problems.push(`the approved mix mode "${approved.manifest.mix.mode}" does not match "${mode}"`);
+        }
+    }
+    return problems;
+}
+/** Prints the refusal and returns the code: re-approve when approved, else a plain failure. */
+function refuseFrozen(io, problems, plan, approved, request) {
+    io.stderr(`mk render: the frozen audio is not the approved audio: ${problems.join("; ")}. ` +
+        "If you did not change it, another process wrote it while this render ran; re-preview, " +
+        "show the user, then re-approve.\n");
+    if (approved === undefined)
+        return EXIT.ERROR;
+    return awaitingApproval(io, request, plan.audioManifest, approved.sha, `the frozen audio differs from the approved bytes (${problems.join("; ")})`, {
+        ...(plan.musicPath === undefined ? {} : { musicPath: plan.musicPath }),
+        ...(plan.musicVolume === undefined ? {} : { musicVolume: plan.musicVolume }),
+        ...(plan.musicLicensePath === undefined ? {} : { musicLicensePath: plan.musicLicensePath }),
+    });
+}
+/**
+ * ADR-0008 D3: the problems to report for a typed failed delivery. A failure
+ * with an empty list is still a failure, never a silent success.
+ */
+export const deliveryFailureProblems = (delivery) => delivery.problems.length > 0 ? [...delivery.problems] : ["mix delivery failed"];
+/** Renders silent video, then mixes narration (plus the ducked bed) underneath. */
+async function runRender(io, outDir, plan, approved, request) {
+    const silent = join(outDir, SILENT);
+    const mixedTemp = join(outDir, MIX_TEMP);
+    // ADR-0008 D1/D2: freeze the approved bytes before any external tool runs and
+    // refuse when the copies are not the approved bytes. Preview and final share
+    // this layout and the same buildMusicMixArgs graph (no second pipeline).
+    let frozenNarration = [];
+    let music;
+    if (plan.narration !== undefined) {
+        const copied = await copyFrozenInputs(io, outDir, plan.narration, plan.music);
+        if (!copied.ok)
+            return { code: copied.code, pending: undefined };
+        frozenNarration = copied.narration;
+        music = copied.music;
+        const early = await frozenApprovalProblems(io, copied, plan.narration, plan, approved);
+        if (early.length > 0) {
+            return { code: refuseFrozen(io, early, plan, approved, request), pending: undefined };
+        }
+    }
+    // Visual-only gated runs render to a temp too: the post-run gate must pass before
+    // this attempt's bytes can replace a previous final.mp4 (ADR-0008 D3).
+    const videoOut = plan.narration === undefined ? (plan.gated ? VIDEO_TEMP : FINAL) : SILENT;
+    const renderArgs = [
+        "render",
+        ".",
+        "-o",
+        videoOut,
+        "--fps",
+        plan.fps,
+        ...(plan.resolutionArg === undefined ? [] : ["--resolution", plan.resolutionArg]),
+        "--quality",
+        "delivery",
+        "--quiet",
+    ];
+    let deliveryFailed = false;
+    let refusal;
+    let pending;
+    const code = await runInProject(io, outDir, async (session) => {
+        const rendered = await session.hf(plan.resume ? [...renderArgs, "--resume"] : renderArgs, plan.resume ? { env: SEGMENTED_CAPTURE } : undefined);
+        if (!rendered || plan.narration === undefined)
+            return;
+        // ADR-0008 D2: check again at consumption time. A render takes minutes, and
+        // the frozen files are what ffmpeg opens; the post-run gate re-resolves the
+        // mutable sources, not these copies.
+        const late = await frozenApprovalProblems(io, { narration: frozenNarration, ...(music === undefined ? {} : { music }) }, plan.narration, plan, approved);
+        if (late.length > 0) {
+            refusal = refuseFrozen(io, late, plan, approved, request);
+            await discardAttempt(io, outDir);
+            return;
+        }
+        // ADR-0008 D3: mix into this attempt's temp file, never into final.mp4. A
+        // typed ok:false (including an empty problem list) is a failed command: the
+        // temps are cleaned and publication never happens.
+        const delivery = await mixAtDeliveryLevel((argv) => session.probe("ffmpeg", argv), {
+            videoIn: silent,
+            clips: frozenNarration,
+            ...(music === undefined ? {} : { music }),
+            out: mixedTemp,
+            swap: async (from, to) => {
+                await io.host.copyFile(from, to);
+                await io.host.remove(from);
+            },
+        });
+        if (!delivery.ok) {
+            const problems = deliveryFailureProblems(delivery);
+            io.stderr(`mk render: ${problems.join("; ")}\n`);
+            await discardAttempt(io, outDir);
+            deliveryFailed = true;
+            return;
+        }
+        if (delivery.problems.length > 0) {
+            io.stderr(`mk render: ${delivery.problems.join("; ")}\n`);
+        }
+        pending = "mix";
+    });
+    if (refusal !== undefined)
+        return { code: refusal, pending: undefined };
+    if (deliveryFailed)
+        return { code: EXIT.ERROR, pending: undefined };
+    // A visual-only gated attempt leaves its video temp for publication after the gate.
+    if (code === 0 && plan.narration === undefined && plan.gated)
+        pending = "video";
+    return { code, pending };
+}
+/** Removes this attempt's intermediates; a previous final.mp4 and the frozen bytes stay. */
+async function discardAttempt(io, outDir) {
+    for (const name of [MIX_TEMP, `${MIX_TEMP}.loudnorm.mp4`, SILENT, VIDEO_TEMP]) {
+        await io.host.remove(join(outDir, name)).catch(() => undefined);
+    }
+}
+/**
+ * ADR-0008 D3: publishes this attempt's temp over final.mp4 only after the last
+ * gate passed. It covers both shapes: a mixed temp, and the direct video of a
+ * visual-only gated run (which must not touch final.mp4 before the gate either).
+ * `renameFile` replaces the file in one step, so a previous final is either fully
+ * replaced or untouched; the published bytes are hashed before success is reported.
+ */
+async function publishAttempt(io, outDir, pending) {
+    const temp = join(outDir, pending === "mix" ? MIX_TEMP : VIDEO_TEMP);
+    const final = join(outDir, FINAL);
+    const expected = await io.host.sha256File(temp);
+    if (expected === undefined) {
+        io.stderr("mk render: the rendered file disappeared before it could be published\n");
+        await discardAttempt(io, outDir);
+        return EXIT.ERROR;
+    }
+    try {
+        await io.host.renameFile(temp, final);
+    }
+    catch (error) {
+        io.stderr(`mk render: cannot publish the final: ${error.message}\n`);
+        await discardAttempt(io, outDir);
+        return EXIT.ERROR;
+    }
+    const published = await io.host.sha256File(final);
+    if (published !== expected) {
+        io.stderr("mk render: the published final does not match the rendered bytes; do not deliver it\n");
+        await io.host.remove(final).catch(() => undefined);
+        await io.host.remove(join(outDir, "render-manifest.json")).catch(() => undefined);
+        await discardAttempt(io, outDir);
+        return EXIT.ERROR;
+    }
+    if (pending === "mix")
+        await io.host.remove(join(outDir, SILENT));
+    return undefined;
+}
+const checkGatedEntry = async (io, request, audioManifest, musicOpts = {}) => gatedGate(io, request, audioManifest, musicOpts);
+export const renderCommand = {
+    name: "render",
+    summary: "build, then render the final video (mp4 by default; webm/mov/gif/png-sequence)",
+    async run(args, io) {
+        const plan = await resolvePlan(args, io);
+        if ("code" in plan)
+            return plan.code;
+        const musicOpts = {
+            ...(plan.musicPath === undefined ? {} : { musicPath: plan.musicPath }),
+            ...(plan.musicVolume === undefined ? {} : { musicVolume: plan.musicVolume }),
+            ...(plan.musicLicensePath === undefined ? {} : { musicLicensePath: plan.musicLicensePath }),
+        };
+        if (plan.gated) {
+            const blocked = await checkGatedEntry(io, plan.request, plan.audioManifest, musicOpts);
+            if (blocked !== undefined)
+                return blocked;
+        }
+        const prepared = await prepareProject(plan.request, io);
+        if (!prepared.ok)
+            return prepared.code;
+        let approved;
+        if (plan.gated) {
+            const snapshot = await checkPrePublish(io, plan.request, plan.audioManifest, prepared.outDir, musicOpts);
+            if (!snapshot.ok)
+                return snapshot.code;
+            approved = { manifest: snapshot.manifest, sha: snapshot.sha };
+        }
+        const run = await runRender(io, prepared.outDir, plan, approved, plan.request);
+        if (run.code !== 0)
+            return run.code;
+        // The last gate runs before publication, so a refusal never replaces a
+        // previous final.mp4 with this attempt's bytes (ADR-0008 D3).
+        if (plan.gated) {
+            const recheck = await gatedGate(io, plan.request, plan.audioManifest, musicOpts);
+            if (recheck !== undefined) {
+                await discardAttempt(io, prepared.outDir);
+                return recheck;
+            }
+        }
+        if (run.pending !== undefined) {
+            const published = await publishAttempt(io, prepared.outDir, run.pending);
+            if (published !== undefined)
+                return published;
+        }
+        const { total, meta } = prepared;
+        // Delivery formats are conversions of the published master; the mp4 stays the source of truth.
+        let outputFile = join(prepared.outDir, FINAL);
+        if (plan.format !== "mp4") {
+            const exported = await exportArtifact(io, prepared.outDir, plan.format);
+            if (!exported.ok)
+                return exported.code;
+            outputFile = exported.file;
+        }
+        const renderedMeta = plan.resolution === "4k" ? { ...meta, width: meta.width * 2, height: meta.height * 2 } : meta;
+        return finishRender(io, {
+            record: {
+                kind: "final",
+                outDir: prepared.outDir,
+                file: outputFile,
+                params: {
+                    fps: Number(plan.fps),
+                    quality: "delivery",
+                    width: renderedMeta.width,
+                    height: renderedMeta.height,
+                    resume: plan.resume,
+                },
+            },
+            ...(plan.verify ? { verify: finalExpectation(renderedMeta, total, Number(plan.fps)) } : {}),
+        });
+    },
+};