@lingjingai/scriptctl 0.31.0 → 0.33.0

package/dist/usecases/direct.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { CliError, DEFAULT_BATCH_MAX_CHARS, DEFAULT_BATCH_MIN_LINES, DEFAULT_BATCH_MODE, DEFAULT_BATCH_TARGET_LINES, DEFAULT_DIRECT_CONCURRENCY, DEFAULT_MODEL, DEFAULT_PROVIDER, DEFAULT_SUMMARY_GROUP_SIZE, DEFAULT_SUMMARY_REDUCE_THRESHOLD_CHARS, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, SUPPORTED_EXTS, deletePath, directDir, exists, fmtId, readJson, readText, sha256Text, writeJson, } from "../common.js";
-import { compactBatchResult, compactEpisodeResult, expandCompactEpisodeResult, buildBatchPlan, buildEpisodePlan, DEFAULT_TITLE_CHUNK_SIZE, chunkEpisodesNeedingTitles, applyEpisodeTitlesToPlan, cleanSynopsisList, episodeTitleResponseMap, extractBatchWithRecovery, mergeEpisodeResultsWithReport, normalizeEpisodeResult, planSynopsisReduction, readCarriedSynopsis, sortDeep, uniqueAdd, validateEpisodeExtractionQuality, _md_push_asset, curateScriptAssets, applyMetadataToScript, } from "../domain/direct-core.js";
+import { compactBatchResult, compactEpisodeResult, expandCompactEpisodeResult, buildBatchPlan, buildEpisodePlan, DEFAULT_TITLE_CHUNK_SIZE, chunkEpisodesNeedingTitles, applyEpisodeTitlesToPlan, cleanSynopsisList, episodeTitleResponseMap, extractBatchWithRecovery, mergeEpisodeResultsWithReport, normalizeEpisodeResult, planSynopsisReduction, readCarriedSynopsis, sortDeep, uniqueAdd, validateEpisodeExtractionQuality, _md_push_asset, applyAssetGroupingDuplicateMerges, applyStateCurationPlan, applyStateBindingPlan, bindDefaultStateRefsInScript, buildAssetCurationAuditContextText, buildAssetCurationContextText, buildAssetCurationRepairContextText, buildAssetGroupingContextText, buildLocationCanonicalizationAuditContextText, buildPrimaryAssetCurationChunks, buildStateCurationChunks, buildStateCurationContextText, groupedAssetCurationChunks, combineLocationCanonicalizationPlan, buildStateBindingContexts, assetCurationAuditSourceKeys, combineAssetCurationExpressionPlans, combinePrimaryAssetCurationPlans, combineAssetCurationPlans, curateScriptAssets, ensureDefaultStates, assetCurationAuditCandidateSourceKeys, locationCanonicalizationCandidateSourceKeys, missingAssetCurationRequiredSourceKeys, normalizeStateBindingPlanShape, parseStateCurationExpressions, parseAssetCurationExpressions, parseAssetCurationExpressionsTolerant, parseAssetGroupingExpressions, assertLocationCanonicalizationPlan, applyMetadataToScript, validateAssetGroupingPlan, stateCurationSourceKeysForRefs, assertStateCurationPlan, } from "../domain/direct-core.js";
 import { validateScript } from "../domain/script/validate.js";
 import { makeProvider, providerCapabilities } from "../infra/providers.js";
 import { remoteScriptOutputStoreFromEnv } from "../infra/script-output-api.js";
@@ -118,6 +118,152 @@ export function readRunState(workspace) {
         return {};
     }
 }
+function isoFromMs(ms) {
+    return new Date(ms).toISOString();
+}
+function durationMs(startedAtMs, finishedAtMs) {
+    return Math.max(0, Math.round(finishedAtMs - startedAtMs));
+}
+function timingErrorSummary(error) {
+    const e = error;
+    return `${e?.name ?? "Error"}: ${e?.message ?? ""}`.slice(0, 240);
+}
+function timingSummary(events) {
+    const stages = {};
+    const branches = {};
+    const slowChunks = events
+        .filter((event) => event.category === "chunk")
+        .sort((left, right) => right.duration_ms - left.duration_ms)
+        .slice(0, 20)
+        .map((event) => ({
+        name: event.name,
+        parent: event.parent ?? "",
+        duration_ms: event.duration_ms,
+        status: event.status,
+    }));
+    for (const event of events) {
+        if (event.category === "stage")
+            stages[event.name] = event.duration_ms;
+        if (event.category === "branch")
+            branches[event.name] = event.duration_ms;
+    }
+    return { stages, branches, slow_chunks: slowChunks };
+}
+class JsonTimingRecorder {
+    ws;
+    workspace;
+    command = "";
+    events = [];
+    activeSpans = [];
+    counter = 0;
+    constructor(ws, workspace) {
+        this.ws = ws;
+        this.workspace = workspace;
+    }
+    reset(command) {
+        this.command = command;
+        this.events = [];
+        this.activeSpans = [];
+        this.counter = 0;
+        this.flush();
+        updateRunState(this.workspace, {
+            timing_current: null,
+            timing_current_stage: null,
+            timing_current_branch: null,
+            timing_summary: { stages: {}, branches: {}, slow_chunks: [] },
+        });
+    }
+    async span(options, run) {
+        const startedAtMs = Date.now();
+        const active = {
+            name: options.name,
+            category: options.category,
+            ...(options.parent ? { parent: options.parent } : {}),
+            started_at: isoFromMs(startedAtMs),
+        };
+        this.activeSpans.push(active);
+        this.updateTimingCurrent();
+        try {
+            const value = await run();
+            this.removeActiveSpan(active);
+            this.record({
+                ...options,
+                status: "success",
+                startedAtMs,
+                finishedAtMs: Date.now(),
+            });
+            return value;
+        }
+        catch (error) {
+            this.removeActiveSpan(active);
+            this.record({
+                ...options,
+                status: "error",
+                startedAtMs,
+                finishedAtMs: Date.now(),
+                error: timingErrorSummary(error),
+            });
+            throw error;
+        }
+    }
+    removeActiveSpan(active) {
+        const index = this.activeSpans.lastIndexOf(active);
+        if (index >= 0)
+            this.activeSpans.splice(index, 1);
+    }
+    activeSpanByCategory(category) {
+        for (let index = this.activeSpans.length - 1; index >= 0; index -= 1) {
+            const span = this.activeSpans[index];
+            if (span.category === category)
+                return span;
+        }
+        return null;
+    }
+    currentSpanPayload(span) {
+        if (!span)
+            return null;
+        return {
+            name: span.name,
+            category: span.category,
+            parent: span.parent ?? null,
+            started_at: span.started_at,
+        };
+    }
+    updateTimingCurrent() {
+        updateRunState(this.workspace, {
+            timing_current: this.currentSpanPayload(this.activeSpans[this.activeSpans.length - 1] ?? null),
+            timing_current_stage: this.currentSpanPayload(this.activeSpanByCategory("stage")),
+            timing_current_branch: this.currentSpanPayload(this.activeSpanByCategory("branch")),
+            timing_summary: timingSummary(this.events),
+        });
+    }
+    record(options) {
+        const event = {
+            id: `tim_${String(++this.counter).padStart(5, "0")}`,
+            name: options.name,
+            category: options.category,
+            ...(options.parent ? { parent: options.parent } : {}),
+            status: options.status,
+            started_at: isoFromMs(options.startedAtMs),
+            finished_at: isoFromMs(options.finishedAtMs),
+            duration_ms: durationMs(options.startedAtMs, options.finishedAtMs),
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+            ...(options.error ? { error: options.error } : {}),
+        };
+        this.events.push(event);
+        this.flush();
+        this.updateTimingCurrent();
+    }
+    flush() {
+        this.ws.writeJson("timings.json", {
+            version: 1,
+            command: this.command,
+            updated_at: checkpointTimestamp(),
+            events: this.events,
+            summary: timingSummary(this.events),
+        });
+    }
+}
 // ---------------------------------------------------------------------------
 // Paths for episode/batch results
 // ---------------------------------------------------------------------------
@@ -214,6 +360,8 @@ function isDirectStageName(value) {
         case "episode_synopsis":
         case "script_merge":
         case "asset_curation":
+        case "state_curation":
+        case "state_binding":
         case "metadata_extract":
         case "script_synopsis":
         case "validate":
@@ -254,6 +402,56 @@ function stageSnapshot(name, status, completed, total, message) {
         message: message ?? "",
     };
 }
+function formatDuration(ms) {
+    const value = Math.max(0, Math.round(ms));
+    if (value < 1000)
+        return `${value}ms`;
+    const seconds = value / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rest = Math.round(seconds % 60);
+    return `${minutes}m${String(rest).padStart(2, "0")}s`;
+}
+function stageTimingDurations(state) {
+    const timingSummaryRaw = state["timing_summary"];
+    const timingSummary = isDict(timingSummaryRaw) ? timingSummaryRaw : {};
+    const stagesRaw = timingSummary["stages"];
+    const stages = isDict(stagesRaw) ? stagesRaw : {};
+    const out = {};
+    for (const [key, value] of Object.entries(stages)) {
+        const n = Number(value);
+        if (!Number.isNaN(n))
+            out[key] = n;
+    }
+    return out;
+}
+function runningTimingElapsed(state, stageName) {
+    const stageRaw = state["timing_current_stage"];
+    const currentRaw = isDict(stageRaw) ? stageRaw : state["timing_current"];
+    const current = isDict(currentRaw) ? currentRaw : null;
+    if (!current || strOf(current["category"]) !== "stage" || strOf(current["name"]) !== stageName)
+        return null;
+    const startedAt = Date.parse(strOf(current["started_at"]));
+    if (Number.isNaN(startedAt))
+        return null;
+    return Date.now() - startedAt;
+}
+function applyStageTiming(stage, state, durations) {
+    const duration = durations[stage.name];
+    const elapsed = stage.status === "running" ? runningTimingElapsed(state, stage.name) : null;
+    const messageParts = [stage.message].filter((item) => item);
+    if (typeof duration === "number")
+        messageParts.push(`耗时 ${formatDuration(duration)}`);
+    else if (elapsed !== null)
+        messageParts.push(`已运行 ${formatDuration(elapsed)}`);
+    return {
+        ...stage,
+        ...(typeof duration === "number" ? { duration_ms: duration } : {}),
+        ...(elapsed !== null ? { elapsed_ms: elapsed } : {}),
+        message: messageParts.join("; "),
+    };
+}
 function fileStage(name, filePath, runningStage) {
     if (exists(filePath))
         return stageSnapshot(name, "success", 1, 1);
@@ -304,6 +502,8 @@ function stageLabel(name) {
         case "episode_synopsis": return "补充信息";
         case "script_merge": return "生成剧本";
         case "asset_curation": return "补充信息";
+        case "state_curation": return "补充信息";
+        case "state_binding": return "补充信息";
         case "metadata_extract": return "补充信息";
         case "script_synopsis": return "补充信息";
         case "validate": return "检查结果";
@@ -364,9 +564,11 @@ function stageOrder(name) {
         case "episode_synopsis": return 6;
         case "script_merge": return 7;
         case "asset_curation": return 8;
-        case "metadata_extract": return 9;
-        case "script_synopsis": return 10;
-        case "validate": return 11;
+        case "state_curation": return 9;
+        case "state_binding": return 10;
+        case "metadata_extract": return 11;
+        case "script_synopsis": return 12;
+        case "validate": return 13;
     }
 }
 function stageRatio(stage) {
@@ -602,6 +804,8 @@ function buildDirectStatusSnapshot(workspace) {
     const episodeResultsDir = path.join(dd, "episode_results");
     const trustEpisodeMergeArtifacts = canTrustStageArtifacts("episode_merge", runningStage, runStatus);
     const trustEpisodeSynopsisArtifacts = canTrustStageArtifacts("episode_synopsis", runningStage, runStatus);
+    const trustStateCurationArtifacts = canTrustStageArtifacts("state_curation", runningStage, runStatus);
+    const trustStateBindingArtifacts = canTrustStageArtifacts("state_binding", runningStage, runStatus);
     const trustMetadataArtifacts = canTrustStageArtifacts("metadata_extract", runningStage, runStatus);
     const trustScriptSynopsisArtifacts = canTrustStageArtifacts("script_synopsis", runningStage, runStatus);
     const batchesByEpisode = new Map();
@@ -741,6 +945,12 @@ function buildDirectStatusSnapshot(workspace) {
     };
     const scriptStage = orderedFileStage("script_merge", path.join(dd, "script.initial.json"), runningStage, runStatus);
     const curationStage = orderedFileStage("asset_curation", path.join(dd, "asset_curation.json"), runningStage, runStatus);
+    const stateCurationStage = trustStateCurationArtifacts
+        ? orderedFileStage("state_curation", path.join(dd, "state_curation.json"), runningStage, runStatus)
+        : stageSnapshot("state_curation", runningStage === "state_curation" ? "running" : "pending", 0, 1);
+    const stateBindingStage = trustStateBindingArtifacts
+        ? orderedFileStage("state_binding", path.join(dd, "state_binding.json"), runningStage, runStatus)
+        : stageSnapshot("state_binding", runningStage === "state_binding" ? "running" : "pending", 0, 1);
     const metadataStage = Boolean(state["metadata_skipped"]) && trustMetadataArtifacts
         ? stageSnapshot("metadata_extract", "skipped", 0, 1, "metadata: skipped (--skip-metadata)")
         : orderedFileStage("metadata_extract", path.join(dd, "asset_metadata.json"), runningStage, runStatus);
@@ -761,6 +971,7 @@ function buildDirectStatusSnapshot(workspace) {
         const validation = readJson(validationPath);
         validationStage = stageSnapshot("validate", Boolean(validation["passed"]) ? "success" : "warning", 1, 1);
     }
+    const timingDurations = stageTimingDurations(state);
     const stages = [
         sourceStage,
         episodePlanStage,
@@ -771,10 +982,14 @@ function buildDirectStatusSnapshot(workspace) {
         episodeSynopsisStage,
         scriptStage,
         curationStage,
+        stateCurationStage,
+        stateBindingStage,
         metadataStage,
         scriptSynopsisStage,
         validationStage,
-    ].map((stage) => failedStage === stage.name ? { ...stage, status: "error", error: Math.max(1, stage.error) } : stage);
+    ]
+        .map((stage) => failedStage === stage.name ? { ...stage, status: "error", error: Math.max(1, stage.error) } : stage)
+        .map((stage) => applyStageTiming(stage, state, timingDurations));
     let overallStatus = "pending";
     const maxStage = stages.reduce((max, stage) => statusPriority(stage.status) > statusPriority(max) ? stage.status : max, "success");
     if (runStatus === "init_failed" || runStatus === "init_incomplete" || maxStage === "error")
@@ -1010,11 +1225,16 @@ function initFailedReport(workspace, opts) {
 // into every stage's catch block.
 function stageFailure(workspace, exc, opts) {
     const e = exc;
+    const received = exc instanceof CliError && exc.received.length > 0
+        ? exc.received
+        : [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`];
     throw initFailedReport(workspace, {
         title: opts.title,
         stage: opts.stage,
+        exitCode: exc instanceof CliError ? exc.exitCode : undefined,
+        errorCode: exc instanceof CliError ? exc.errorCode : undefined,
         required: opts.required,
-        received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+        received,
         nextSteps: opts.nextSteps,
         ...(opts.updates ? { updates: opts.updates } : {}),
     });
@@ -1042,6 +1262,12 @@ async function pMapWithConcurrency(items, concurrency, worker) {
     }));
     return out;
 }
+function unwrapConcurrentOutcomes(outcomes) {
+    const failed = outcomes.find((outcome) => !outcome.ok);
+    if (failed)
+        throw failed.error;
+    return outcomes.map((outcome) => outcome.value);
+}
 function providerErrorSummary(error) {
     if (error instanceof CliError && error.errorCode)
         return error.errorCode;
@@ -1051,6 +1277,9 @@ function providerErrorSummary(error) {
         return "PROVIDER_CONTENT_FILTERED";
     return `${e?.name ?? "Error"}: ${msg}`.slice(0, 160);
 }
+function cloneDict(value) {
+    return structuredClone(value);
+}
 // Generate the plan's missing episode titles in bounded, concurrent chunks.
 // Title generation is non-essential (every episode has a deterministic
 // fallback), so a chunk that the provider filters or fails does NOT abort
@@ -1188,6 +1417,56 @@ function assignOverviewFields(script, o) {
 function applyScriptSynopsisFields(script, fields) {
     assignOverviewFields(script, normalizeOverviewFields(fields));
 }
+function synopsisGroupSignature(opts) {
+    return sha256Text(JSON.stringify(sortDeep({
+        title: strOf(opts.title),
+        thresholdChars: opts.thresholdChars,
+        groupSize: opts.groupSize,
+        level: opts.level,
+        groupIndex: opts.groupIndex,
+        synopses: opts.synopses,
+    })));
+}
+function synopsisGroupPartPath(dd, signature) {
+    return path.join(dd, "synopsis_parts", `${signature}.json`);
+}
+async function loadOrRunSynopsisGroup(provider, groupSynopses, opts) {
+    if (groupSynopses.length <= 1)
+        return { value: groupSynopses[0] ?? "", reused: false };
+    const signature = synopsisGroupSignature({
+        title: opts.title,
+        thresholdChars: opts.thresholdChars,
+        groupSize: opts.groupSize,
+        level: opts.level,
+        groupIndex: opts.groupIndex,
+        synopses: groupSynopses,
+    });
+    const partPath = synopsisGroupPartPath(opts.dd, signature);
+    if (!opts.resummarize && exists(partPath)) {
+        const prior = readJson(partPath);
+        if (isDict(prior) && strOf(prior["source_group_signature"]) === signature) {
+            const synopsis = strOf(prior["synopsis"]).trim();
+            if (synopsis)
+                return { value: synopsis, reused: true };
+        }
+    }
+    try {
+        const synopsis = await reduceSynopses(provider, [...groupSynopses], { title: opts.title });
+        writeJson(partPath, {
+            version: 1,
+            source_group_signature: signature,
+            level: opts.level,
+            group_index: opts.groupIndex,
+            source_count: groupSynopses.length,
+            synopsis,
+            updated_at: checkpointTimestamp(),
+        });
+        return { value: synopsis, reused: false };
+    }
+    catch (error) {
+        return { value: groupSynopses.join(" "), error, reused: false };
+    }
+}
 // Whole-script reduce-2: collapse the episode synopses down to a set that fits
 // one final reduce, then produce the top-level overview. Reuses a prior
 // synopsis.json when the episode synopses are unchanged (signature match). Soft
@@ -1244,6 +1523,7 @@ async function buildScriptSynopsis(provider, script, opts) {
         // whenever it can't form fewer groups than items), so `current` strictly
         // shrinks each non-terminal pass and this terminates without a counter.
         let current = episodeSynopses;
+        let level = 1;
         while (true) {
             const plan = planSynopsisReduction(current, opts.thresholdChars, opts.groupSize);
             if (plan.fitsInOnePass)
@@ -1252,16 +1532,10 @@ async function buildScriptSynopsis(provider, script, opts) {
             // singleton group passes through verbatim (no LLM rewrite), mirroring the
             // reduce-1 passthrough. A group whose stitch FAILS degrades to its joined
             // beats (soft, per-group) — one bad group never wipes the whole overview.
-            const outcomes = await pMapWithConcurrency(plan.groups, opts.concurrency, async (group) => {
+            const currentLevel = level;
+            const outcomes = await pMapWithConcurrency(plan.groups, opts.concurrency, async (group, groupIndex) => {
                 const groupSynopses = group.map((i) => current[i]).filter((s) => s.trim());
-                if (groupSynopses.length <= 1)
-                    return { value: groupSynopses[0] ?? "" };
-                try {
-                    return { value: await reduceSynopses(provider, groupSynopses, { title: script["title"] }) };
-                }
-                catch (err) {
-                    return { value: groupSynopses.join(" "), error: err };
-                }
+                return loadOrRunSynopsisGroup(provider, groupSynopses, { ...opts, title: script["title"], level: currentLevel, groupIndex });
             });
             const next = [];
             for (const o of outcomes) {
@@ -1275,6 +1549,7 @@ async function buildScriptSynopsis(provider, script, opts) {
                     next.push(o.value.value);
             }
             current = next;
+            level += 1;
             if (current.length === 0)
                 break;
         }
@@ -1416,10 +1691,12 @@ function parseDirectRunOptions(opts) {
 function buildStageContext(options) {
     const ws = new Workspace(options.workspace);
     let provider = null;
+    const timing = new JsonTimingRecorder(ws, options.workspace);
     const ctx = {
         ws,
         options,
         state: emptyRunState(),
+        timing,
         provider() {
             if (provider)
                 return provider;
@@ -1545,11 +1822,98 @@ function buildIncompleteReport(ctx) {
     };
     return [report, EXIT_RUNTIME];
 }
+function initPreFanoutStages() {
+    const end = STAGES.findIndex((stage) => stage.name === "state-curation");
+    return STAGES.slice(0, end + 1);
+}
+function validateOnlyStages() {
+    return STAGES.filter((stage) => stage.name === "validate");
+}
+function updatePostCurationBranch(ctx, name, status) {
+    const current = readRunState(ctx.options.workspace);
+    const rawBranches = current["post_curation_branches"];
+    const branches = isDict(rawBranches) ? { ...rawBranches } : {};
+    branches[name] = { status, updated_at: checkpointTimestamp() };
+    ctx.updateRunState({ post_curation_branches: branches });
+}
+async function runPostCurationBranch(ctx, name, run) {
+    updatePostCurationBranch(ctx, name, "running");
+    try {
+        const value = await ctx.timing.span({ name, category: "branch", parent: "post_curation" }, run);
+        updatePostCurationBranch(ctx, name, "success");
+        return value;
+    }
+    catch (error) {
+        updatePostCurationBranch(ctx, name, "error");
+        throw error;
+    }
+}
+async function runPostCurationFanout(ctx) {
+    const { ws, state, options } = ctx;
+    const baseScript = ensureScript(ctx);
+    ctx.updateRunState({
+        status: "init_running",
+        init_stage: "state_binding",
+        post_curation_parallel: true,
+        post_curation_branches: {
+            state_binding: { status: "running", updated_at: checkpointTimestamp() },
+            metadata_extract: { status: options.skipMetadata ? "skipped" : "running", updated_at: checkpointTimestamp() },
+            script_synopsis: { status: options.skipSummary ? "skipped" : "running", updated_at: checkpointTimestamp() },
+        },
+    });
+    ctx.emitProgress("state-binding");
+    ctx.emitProgress("metadata", options.skipMetadata ? "skipped" : "running");
+    ctx.emitProgress("script-synopsis", options.skipSummary ? "skipped" : "running");
+    const stateBindingPromise = runPostCurationBranch(ctx, "state_binding", async () => {
+        const script = cloneDict(baseScript);
+        const result = await runStateBindingForScript(ctx, script, false);
+        return { ...result, script };
+    });
+    const metadataPromise = runPostCurationBranch(ctx, "metadata_extract", async () => {
+        const script = cloneDict(baseScript);
+        return runMetadataForScript(ctx, script, false, false);
+    });
+    const synopsisPromise = runPostCurationBranch(ctx, "script_synopsis", async () => {
+        const script = cloneDict(baseScript);
+        return runScriptSynopsisForScript(ctx, script, false);
+    });
+    const settled = await Promise.allSettled([stateBindingPromise, metadataPromise, synopsisPromise]);
+    const failed = settled.find((item) => item.status === "rejected");
+    if (failed && failed.status === "rejected")
+        throw failed.reason;
+    const stateBinding = await stateBindingPromise;
+    const metadata = await metadataPromise;
+    const synopsis = await synopsisPromise;
+    await ctx.timing.span({ name: "post_curation.merge", category: "substage", parent: "post_curation" }, () => {
+        const finalScript = stateBinding.script;
+        if (!metadata.skipped)
+            applyMetadataToScript(finalScript, metadata.metadata);
+        applyScriptSynopsisFields(finalScript, synopsis.fields);
+        ws.writeJson("script.initial.json", finalScript);
+        state.script = finalScript;
+        state.summaryFullDegraded = synopsis.degraded;
+        state.summaryDegradeReason = synopsis.reason;
+    });
+    state.summaryDegradedEpisodes.sort((a, b) => a - b);
+    const summaryDegraded = state.summaryFullDegraded || state.summaryDegradedEpisodes.length > 0;
+    ctx.updateRunState({
+        post_curation_parallel: false,
+        summary_skipped: options.skipSummary,
+        summary_degraded: summaryDegraded,
+        summary_degraded_episodes: state.summaryDegradedEpisodes,
+        summary_degraded_reason: state.summaryDegradeReason || null,
+        metadata_skipped: options.skipMetadata,
+    });
+    ctx.emitProgress("state-binding", "success");
+    ctx.emitProgress("metadata", metadata.skipped ? "skipped" : "success");
+    ctx.emitProgress("script-synopsis", summaryDegraded ? "warning" : options.skipSummary ? "skipped" : "success");
+}
 async function commandInitImpl(opts) {
     const options = parseDirectRunOptions(opts);
     assertInitSource(options.source);
     const ctx = buildStageContext(options);
     ctx.ws.ensure();
+    ctx.timing.reset("direct init");
     // Seed run_state with the init header before the first stage runs (provider /
     // model / source_path / metadata flag) — the god-command set these up front.
     updateRunState(options.workspace, {
@@ -1563,13 +1927,9 @@ async function commandInitImpl(opts) {
         metadata_skipped: options.skipMetadata,
     });
     try {
-        // `direct init` runs EVERY stage (force) — exactly like the former god
-        // command, which had no whole-stage skip. The reuse model lives INSIDE the
-        // stages (per-batch file presence in batch-extract; per-episode `syn` reuse
-        // in the synopsis stages), so a deterministic stage must still re-derive its
-        // output from the (possibly reused/edited) upstream artifacts. Whole-stage
-        // skip-on-present is a `direct run <stage>` convenience only.
-        await runStages(ctx, STAGES, { force: true });
+        await runStages(ctx, initPreFanoutStages(), { force: true, persistScriptAfterStages: false });
+        await ctx.timing.span({ name: "post_curation", category: "stage" }, () => runPostCurationFanout(ctx));
+        await runStages(ctx, validateOnlyStages(), { force: true, persistScriptAfterStages: false });
     }
     catch (exc) {
         // The resumable "incomplete" stop is not a failure — surface the INCOMPLETE
@@ -1645,6 +2005,8 @@ export async function commandRun(opts) {
     }
     const options = parseDirectRunOptions(opts);
     const ctx = buildStageContext(options);
+    ctx.ws.ensure();
+    ctx.timing.reset(`direct run ${stageName}`);
     const force = Boolean(opts["force"]);
     try {
         if (force) {
@@ -2131,16 +2493,661 @@ export async function stageScriptMerge(ctx) {
     }
 }
 // --- asset-curation -------------------------------------------------------
+const ASSET_GROUPING_CACHE_VERSION = 3;
+const ASSET_CURATION_CACHE_VERSION = 4;
+function assetCacheIdentity(options) {
+    return {
+        provider: options.providerName,
+        model: options.model,
+    };
+}
+function assetCacheArtifactFields(ctx, cacheVersion) {
+    return {
+        cache_version: cacheVersion,
+        ...assetCacheIdentity(ctx.options),
+    };
+}
+function assetCurationScriptFingerprint(script, options) {
+    return sha256Text(JSON.stringify(sortDeep({
+        cache_version: ASSET_CURATION_CACHE_VERSION,
+        ...assetCacheIdentity(options),
+        script: {
+            actors: script["actors"],
+            locations: script["locations"],
+            props: script["props"],
+            speakers: script["speakers"],
+            episodes: script["episodes"],
+        },
+    })));
+}
+function assetCurationPlanFingerprint(scriptFingerprint, plan) {
+    return sha256Text(JSON.stringify(sortDeep({
+        script_fingerprint: scriptFingerprint,
+        decisions: plan["decisions"],
+    })));
+}
+function chunkStrings(values, chunkSize) {
+    const chunks = [];
+    for (let index = 0; index < values.length; index += chunkSize) {
+        chunks.push(values.slice(index, index + chunkSize));
+    }
+    return chunks;
+}
+function curationSourceKey(kind, id) {
+    return `${kind}:${id}`;
+}
+function curationDecisionSourceKey(decision) {
+    return curationSourceKey(strOf(decision["kind"]), strOf(decision["source_id"]));
+}
+function curationSourceKeysForIds(kind, ids) {
+    return ids.map((id) => curationSourceKey(kind, id));
+}
+function curationPartSelection(kind, ids) {
+    if (kind === "actor")
+        return { actor: ids };
+    if (kind === "location")
+        return { location: ids };
+    return { prop: ids };
+}
+function curationIdsFromSourceKeys(kind, ids, sourceKeys) {
+    const allowed = new Set(sourceKeys);
+    return ids.filter((id) => allowed.has(curationSourceKey(kind, id)));
+}
+function invalidCurationPart(title, received) {
+    return new CliError(title, title, {
+        exitCode: EXIT_RUNTIME,
+        required: ["repairable asset curation expressions"],
+        received,
+        nextSteps: ["Rerun init; completed extraction checkpoints will be reused and only invalid curation parts will retry."],
+    });
+}
+const MAX_CURATION_PART_REPAIR_ATTEMPTS = 2;
+function assetGroupingKindListKey(kind) {
+    if (kind === "actor")
+        return "actors";
+    if (kind === "location")
+        return "locations";
+    return "props";
+}
+function assetGroupingKindIdKey(kind) {
+    if (kind === "actor")
+        return "actor_id";
+    if (kind === "location")
+        return "location_id";
+    return "prop_id";
+}
+function assetGroupingKindNameKey(kind) {
+    if (kind === "actor")
+        return "actor_name";
+    if (kind === "location")
+        return "location_name";
+    return "prop_name";
+}
+function assetGroupingScriptFingerprint(script, options) {
+    const compact = {};
+    for (const kind of ["actor", "location", "prop"]) {
+        const idKey = assetGroupingKindIdKey(kind);
+        const nameKey = assetGroupingKindNameKey(kind);
+        compact[assetGroupingKindListKey(kind)] = asList(script[assetGroupingKindListKey(kind)])
+            .filter(isDict)
+            .map((asset) => ({ id: strOf(asset[idKey]), name: strOf(asset[nameKey]) }));
+    }
+    return sha256Text(JSON.stringify(sortDeep({
+        cache_version: ASSET_GROUPING_CACHE_VERSION,
+        ...assetCacheIdentity(options),
+        assets: compact,
+    })));
+}
+function combineAssetGroupingPlans(parts) {
+    const groups = parts.flatMap((part) => asList(part["groups"]).filter(isDict));
+    const duplicateMergeDecisions = parts.flatMap((part) => asList(part["duplicate_merge_decisions"]).filter(isDict));
+    const normalizations = parts.flatMap((part) => asList(part["normalizations"]).filter(isDict));
+    const summaries = parts.map((part) => part["summary"]).filter(isDict);
+    return {
+        version: 1,
+        format: "asset-grouping-v1",
+        groups,
+        duplicate_merge_decisions: duplicateMergeDecisions,
+        normalizations,
+        parts: parts.map((part) => ({
+            kind: part["kind"],
+            expression_text: part["expression_text"],
+            summary: part["summary"],
+            normalizations: part["normalizations"],
+        })),
+        summary: {
+            group_count: groups.length,
+            duplicate_merge_count: duplicateMergeDecisions.length,
+            normalization_count: normalizations.length,
+            parts: summaries,
+        },
+    };
+}
+async function loadOrRunAssetGroupingPart(ctx, script, groupAssets, kind, fingerprint) {
+    const artifactName = `asset_grouping_parts/${kind}.json`;
+    const cached = ctx.ws.readJsonSafe(artifactName);
+    const cachedPlan = !ctx.state.bypassInternalCaches && isDict(cached) && cached["script_fingerprint"] === fingerprint && cached["parse_status"] === "ok" && isDict(cached["plan"]) ? cached["plan"] : null;
+    if (cachedPlan && isList(cachedPlan["groups"]))
+        return cachedPlan;
+    const startedAtMs = Date.now();
+    const idKey = assetGroupingKindIdKey(kind);
+    const assetCount = asList(script[assetGroupingKindListKey(kind)])
+        .filter(isDict)
+        .map((asset) => strOf(asset[idKey]).trim())
+        .filter((id) => id).length;
+    if (assetCount === 0) {
+        const plan = {
+            version: 1,
+            format: "asset-grouping-v1",
+            kind,
+            expression_text: "",
+            expressions: [],
+            groups: [],
+            duplicate_merge_decisions: [],
+            summary: { input_count: 0, group_count: 0, mentioned_count: 0, omitted_duplicate_count: 0 },
+        };
+        ctx.ws.writeJson(artifactName, {
+            version: 1,
+            ...assetCacheArtifactFields(ctx, ASSET_GROUPING_CACHE_VERSION),
+            script_fingerprint: fingerprint,
+            parse_status: "ok",
+            kind,
+            context_chars: 0,
+            expression_text: "",
+            duration_ms: durationMs(startedAtMs, Date.now()),
+            plan,
+            updated_at: checkpointTimestamp(),
+        });
+        return plan;
+    }
+    const contextText = buildAssetGroupingContextText(script, kind);
+    let rawText = "";
+    try {
+        rawText = await ctx.timing.span({ name: `asset_grouping.${kind}`, category: "chunk", parent: "asset_curation.grouping", metadata: { artifact: artifactName } }, () => groupAssets(script, contextText));
+        const parsed = parseAssetGroupingExpressions(rawText);
+        const plan = validateAssetGroupingPlan(script, kind, parsed);
+        ctx.ws.writeJson(artifactName, {
+            version: 1,
+            ...assetCacheArtifactFields(ctx, ASSET_GROUPING_CACHE_VERSION),
+            script_fingerprint: fingerprint,
+            parse_status: "ok",
+            kind,
+            context_chars: contextText.length,
+            expression_text: rawText,
+            duration_ms: durationMs(startedAtMs, Date.now()),
+            plan,
+            updated_at: checkpointTimestamp(),
+        });
+        return plan;
+    }
+    catch (exc) {
+        const e = exc;
+        ctx.ws.writeJson(artifactName, {
+            version: 1,
+            ...assetCacheArtifactFields(ctx, ASSET_GROUPING_CACHE_VERSION),
+            script_fingerprint: fingerprint,
+            parse_status: "failed",
+            kind,
+            context_chars: contextText.length,
+            expression_text: rawText,
+            duration_ms: durationMs(startedAtMs, Date.now()),
+            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
+            updated_at: checkpointTimestamp(),
+        });
+        throw exc;
+    }
+}
+async function loadOrRunAssetGrouping(ctx, script, groupAssets, fingerprint) {
+    ctx.ws.mkdir("asset_grouping_parts");
+    const outcomes = await pMapWithConcurrency(["actor", "location", "prop"], ctx.options.concurrency, async (kind) => loadOrRunAssetGroupingPart(ctx, script, groupAssets, kind, fingerprint));
+    return combineAssetGroupingPlans(unwrapConcurrentOutcomes(outcomes));
+}
+function curationDecisionSourceKeys(plan) {
+    return new Set(asList(plan["decisions"]).filter(isDict).map((decision) => curationDecisionSourceKey(decision)));
+}
+function sourceKeysFromRejectedExpressions(rejected, candidateSourceKeys) {
+    const candidateSet = new Set(candidateSourceKeys);
+    const keys = [];
+    for (const item of rejected) {
+        const key = strOf(item["source_key"]);
+        if (key && (candidateSet.size === 0 || candidateSet.has(key)))
+            uniqueAdd(keys, key);
+    }
+    return keys;
+}
+function scopedCurationPlan(plan, allowedSourceKeys) {
+    const allowed = new Set(allowedSourceKeys);
+    const decisions = asList(plan["decisions"]).filter(isDict);
+    const acceptedExpressions = asList(plan["accepted_expressions"]);
+    const scopedDecisions = [];
+    const scopedExpressions = [];
+    const ignored = [];
+    for (let index = 0; index < decisions.length; index += 1) {
+        const decision = decisions[index];
+        const sourceKey = curationDecisionSourceKey(decision);
+        const expression = acceptedExpressions[index] ?? "";
+        if (allowed.has(sourceKey)) {
+            scopedDecisions.push(decision);
+            if (expression)
+                scopedExpressions.push(expression);
+        }
+        else {
+            ignored.push({ source_key: sourceKey, expression, reason: "outside_repair_scope" });
+        }
+    }
+    return {
+        plan: {
+            ...plan,
+            expression_text: formatCurationExpressionText(scopedExpressions),
+            expressions: scopedExpressions.length > 0 ? scopedExpressions : ["NOOP # no asset curation changes"],
+            accepted_expressions: scopedExpressions,
+            decisions: scopedDecisions,
+        },
+        ignored,
+    };
+}
+function missingRequiredSourceKeysForPart(script, candidateSourceKeys, partialPlan) {
+    const candidateSet = new Set(candidateSourceKeys);
+    return missingAssetCurationRequiredSourceKeys(script, partialPlan).filter((key) => candidateSet.has(key));
+}
+function repairSourceKeysForPart(script, candidateSourceKeys, partialPlan, requireCoverage) {
+    const candidateSet = new Set(candidateSourceKeys);
+    const accepted = new Set(asList(partialPlan["decisions"]).filter(isDict).map((decision) => curationDecisionSourceKey(decision)));
+    const rejected = asList(partialPlan["rejected_expressions"]).filter(isDict);
+    const repairKeys = [];
+    let hasUnlocatedRejection = false;
+    for (const item of rejected) {
+        const key = strOf(item["source_key"]);
+        if (key && (candidateSet.size === 0 || candidateSet.has(key)))
+            uniqueAdd(repairKeys, key);
+        else
+            hasUnlocatedRejection = true;
+    }
+    if (hasUnlocatedRejection) {
+        for (const key of candidateSourceKeys) {
+            if (!accepted.has(key))
+                uniqueAdd(repairKeys, key);
+        }
+    }
+    if (requireCoverage) {
+        for (const key of missingRequiredSourceKeysForPart(script, candidateSourceKeys, partialPlan)) {
+            uniqueAdd(repairKeys, key);
+        }
+    }
+    return repairKeys;
+}
+function mergeRepairedCurationPlan(rawText, partialPlan, repairPlan, repairAttempts) {
+    const acceptedExpressions = asList(partialPlan["accepted_expressions"]);
+    const repairExpressions = asList(repairPlan["accepted_expressions"]);
+    const decisions = [
+        ...asList(partialPlan["decisions"]).filter(isDict),
+        ...asList(repairPlan["decisions"]).filter(isDict),
+    ];
+    const expressions = [...acceptedExpressions, ...repairExpressions].filter((expression) => !/^NOOP(?:\s|#|$)/i.test(expression.trim()));
+    return {
+        version: 3,
+        format: "asset-curation-exp-v1",
+        expression_text: formatCurationExpressionText(expressions),
+        raw_expression_text: rawText,
+        accepted_expressions: [...acceptedExpressions, ...repairExpressions],
+        rejected_expressions: asList(partialPlan["rejected_expressions"]).filter(isDict),
+        repair_attempts: repairAttempts,
+        expressions: expressions.length > 0 ? expressions : ["NOOP # no asset curation changes"],
+        decisions,
+        partial: false,
+    };
+}
+function formatCurationExpressionText(expressions) {
+    if (expressions.length > 0)
+        return expressions.map((expression) => `<exp>${expression}</exp>`).join("\n");
+    return "<exp>NOOP # no asset curation changes</exp>";
+}
+function writeFailedCurationPartArtifact(opts) {
+    const e = opts.error;
+    opts.ctx.ws.writeJson(opts.artifactName, {
+        version: 1,
+        ...assetCacheArtifactFields(opts.ctx, ASSET_CURATION_CACHE_VERSION),
+        script_fingerprint: opts.fingerprint,
+        ...opts.metadata,
+        parse_status: "failed",
+        candidate_source_keys: opts.candidateSourceKeys,
+        expression_text: opts.partPlan?.["expression_text"] ?? null,
+        raw_expression_text: opts.partPlan?.["raw_expression_text"] ?? opts.expressionText,
+        accepted_expressions: opts.partPlan?.["accepted_expressions"] ?? [],
+        rejected_expressions: opts.partPlan?.["rejected_expressions"] ?? [],
+        repair_attempts: opts.repairAttempts,
+        duration_ms: durationMs(opts.startedAtMs, Date.now()),
+        error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
+        plan: opts.partPlan,
+        updated_at: checkpointTimestamp(),
+    });
+}
+async function loadOrRunCurationPart(ctx, script, artifactName, fingerprint, metadata, candidateSourceKeys, parentTiming, requireCoverage, contextText, run) {
+    const cached = ctx.ws.readJsonSafe(artifactName);
+    const cachedPlan = !ctx.state.bypassInternalCaches && isDict(cached) && cached["script_fingerprint"] === fingerprint && cached["parse_status"] === "ok" && isDict(cached["plan"]) ? cached["plan"] : null;
+    if (cachedPlan && isList(cachedPlan["decisions"]))
+        return cachedPlan;
+    const startedAtMs = Date.now();
+    const baseContextText = contextText(candidateSourceKeys);
+    const expressionText = await ctx.timing.span({ name: strOf(metadata["part_id"]) || artifactName, category: "chunk", parent: parentTiming, metadata: { artifact: artifactName } }, () => run(baseContextText));
+    let partPlan = parseAssetCurationExpressionsTolerant(expressionText);
+    if (!isDict(partPlan) || !isList(partPlan["decisions"])) {
+        throw new CliError("INIT FAILED: Provider returned invalid asset curation", "Provider returned invalid asset curation.", {
+            exitCode: EXIT_RUNTIME,
+            required: ["object with decisions[]"],
+            received: [typeof partPlan],
+            nextSteps: ["Rerun init; completed extraction checkpoints will be reused and curation will retry."],
+        });
+    }
+    const repairAttempts = [];
+    let repairSourceKeys = repairSourceKeysForPart(script, candidateSourceKeys, partPlan, requireCoverage);
+    let repairRejectedContext = asList(partPlan["rejected_expressions"]).filter(isDict);
+    try {
+        for (let attempt = 1; repairSourceKeys.length > 0 && attempt <= MAX_CURATION_PART_REPAIR_ATTEMPTS; attempt += 1) {
+            const repairContext = buildAssetCurationRepairContextText({
+                baseContextText: contextText(repairSourceKeys),
+                repairSourceKeys,
+                rejectedExpressions: repairRejectedContext,
+                acceptedDecisions: asList(partPlan["decisions"]).filter(isDict),
+            });
+            const repairText = await ctx.timing.span({ name: `${strOf(metadata["part_id"]) || artifactName}.repair.${pad3(attempt)}`, category: "repair", parent: parentTiming, metadata: { artifact: artifactName, repair_source_keys: repairSourceKeys } }, () => run(repairContext));
+            const repairPlan = parseAssetCurationExpressionsTolerant(repairText);
+            const repairRejected = asList(repairPlan["rejected_expressions"]).filter(isDict);
+            const scopedRepair = scopedCurationPlan(repairPlan, repairSourceKeys);
+            repairAttempts.push({
+                index: attempt,
+                repair_source_keys: repairSourceKeys,
+                expression_text: repairText,
+                accepted_expressions: scopedRepair.plan["accepted_expressions"],
+                ignored_expressions: scopedRepair.ignored,
+                rejected_expressions: repairRejected,
+                decisions: scopedRepair.plan["decisions"],
+            });
+            if (repairRejected.length > 0) {
+                if (asList(scopedRepair.plan["decisions"]).filter(isDict).length > 0) {
+                    partPlan = mergeRepairedCurationPlan(expressionText, partPlan, scopedRepair.plan, repairAttempts);
+                }
+                const missingKeys = requireCoverage ? missingRequiredSourceKeysForPart(script, candidateSourceKeys, partPlan) : [];
+                const rejectedKeys = sourceKeysFromRejectedExpressions(repairRejected, repairSourceKeys);
+                const nextRepairSourceKeys = [...(rejectedKeys.length > 0 ? rejectedKeys : []), ...missingKeys]
+                    .filter((key, index, all) => all.indexOf(key) === index);
+                if (nextRepairSourceKeys.length === 0) {
+                    repairSourceKeys = [];
+                    repairRejectedContext = [];
+                    continue;
+                }
+                if (attempt >= MAX_CURATION_PART_REPAIR_ATTEMPTS) {
+                    throw invalidCurationPart("INIT FAILED: Asset curation repair returned invalid expressions", repairRejected.map((item) => `${strOf(item["source_key"]) || "-"}: ${strOf(item["error"])}`).slice(0, 40));
+                }
+                repairSourceKeys = nextRepairSourceKeys;
+                repairRejectedContext = repairRejected;
+                continue;
+            }
+            const finalKeys = new Set([...curationDecisionSourceKeys(partPlan), ...curationDecisionSourceKeys(scopedRepair.plan)]);
+            const unrepaired = repairSourceKeys.filter((key) => !finalKeys.has(key));
+            if (unrepaired.length > 0 && attempt >= MAX_CURATION_PART_REPAIR_ATTEMPTS) {
+                throw invalidCurationPart("INIT FAILED: Asset curation repair omitted required source decisions", unrepaired.slice(0, 40));
+            }
+            partPlan = mergeRepairedCurationPlan(expressionText, partPlan, scopedRepair.plan, repairAttempts);
+            repairRejectedContext = [];
+            const missingKeys = requireCoverage ? missingRequiredSourceKeysForPart(script, candidateSourceKeys, partPlan) : [];
+            repairSourceKeys = [...unrepaired, ...missingKeys]
+                .filter((key, index, all) => all.indexOf(key) === index);
+        }
+        if (repairSourceKeys.length > 0) {
+            throw invalidCurationPart("INIT FAILED: Asset curation repair omitted required source decisions", repairSourceKeys.slice(0, 40));
+        }
+    }
+    catch (exc) {
+        writeFailedCurationPartArtifact({
+            ctx,
+            artifactName,
+            fingerprint,
+            metadata,
+            candidateSourceKeys,
+            expressionText,
+            partPlan,
+            repairAttempts,
+            startedAtMs,
+            error: exc,
+        });
+        throw exc;
+    }
+    for (const [key, value] of Object.entries(metadata))
+        partPlan[key] = value;
+    ctx.ws.writeJson(artifactName, {
+        version: 1,
+        ...assetCacheArtifactFields(ctx, ASSET_CURATION_CACHE_VERSION),
+        script_fingerprint: fingerprint,
+        ...metadata,
+        parse_status: "ok",
+        candidate_source_keys: candidateSourceKeys,
+        expression_text: partPlan["expression_text"],
+        raw_expression_text: partPlan["raw_expression_text"] ?? expressionText,
+        accepted_expressions: partPlan["accepted_expressions"],
+        rejected_expressions: partPlan["rejected_expressions"],
+        repair_attempts: repairAttempts,
+        duration_ms: durationMs(startedAtMs, Date.now()),
+        plan: partPlan,
+        updated_at: checkpointTimestamp(),
+    });
+    return partPlan;
+}
+async function loadOrRunPrimaryCurationPart(ctx, script, curateAssets, kind, partId, fingerprint, ids) {
+    const selection = curationPartSelection(kind, ids);
+    return loadOrRunCurationPart(ctx, script, `asset_curation_parts/primary.${partId}.json`, fingerprint, { asset_kind: kind, part_id: partId, selection }, curationSourceKeysForIds(kind, ids), "asset_curation.primary", true, (selectedSourceKeys = curationSourceKeysForIds(kind, ids)) => {
+        const selectedIds = curationIdsFromSourceKeys(kind, ids, selectedSourceKeys);
+        return buildAssetCurationContextText(script, [kind], curationPartSelection(kind, selectedIds.length > 0 ? selectedIds : ids));
+    }, (contextText) => curateAssets(script, contextText));
+}
+function primaryCurationChunks(script, groupingPlan) {
+    const chunks = [];
+    for (const kind of ["actor", "location", "prop"]) {
+        const groupingGroups = groupingPlan
+            ? asList(groupingPlan["groups"]).filter((group) => isDict(group) && group["kind"] === kind)
+            : [];
+        const kindChunks = groupingGroups.length > 0
+            ? groupedAssetCurationChunks(script, kind, groupingGroups)
+            : buildPrimaryAssetCurationChunks(script, kind);
+        for (let index = 0; index < kindChunks.length; index += 1) {
+            chunks.push({
+                kind,
+                partId: `${kind}.${String(index + 1).padStart(3, "0")}`,
+                ids: kindChunks[index],
+            });
+        }
+    }
+    return chunks;
+}
+async function loadOrRunAuditCurationParts(ctx, script, curateAssets, primaryPlan, fingerprint) {
+    const sourceChunks = chunkStrings(assetCurationAuditSourceKeys(script, primaryPlan), 24);
+    if (sourceChunks.length === 0) {
+        return parseAssetCurationExpressions("<exp>NOOP # no asset curation changes</exp>");
+    }
+    const outcomes = await pMapWithConcurrency(sourceChunks, ctx.options.concurrency, async (selectedSourceKeys, index) => {
+        const partId = `audit.${String(index + 1).padStart(3, "0")}`;
+        return loadOrRunCurationPart(ctx, script, `asset_curation_parts/${partId}.json`, fingerprint, { part_id: partId, selected_source_keys: selectedSourceKeys }, selectedSourceKeys, "asset_curation.audit", false, (repairSourceKeys = selectedSourceKeys) => buildAssetCurationAuditContextText(script, primaryPlan, repairSourceKeys), (contextText) => curateAssets(script, contextText));
+    });
+    const parts = unwrapConcurrentOutcomes(outcomes);
+    return combineAssetCurationExpressionPlans(parts);
+}
+async function loadOrRunLocationCanonicalizationParts(ctx, script, curateAssets, plan, fingerprint) {
+    const sourceChunks = chunkStrings(locationCanonicalizationCandidateSourceKeys(script, plan), 24);
+    if (sourceChunks.length === 0) {
+        return parseAssetCurationExpressions("<exp>NOOP # no location canonicalization changes</exp>");
+    }
+    const outcomes = await pMapWithConcurrency(sourceChunks, ctx.options.concurrency, async (selectedSourceKeys, index) => {
+        const partId = `location_canonical.${String(index + 1).padStart(3, "0")}`;
+        return loadOrRunCurationPart(ctx, script, `asset_curation_parts/${partId}.json`, fingerprint, { part_id: partId, selected_source_keys: selectedSourceKeys }, selectedSourceKeys, "asset_curation.location_canonical", false, (repairSourceKeys = selectedSourceKeys) => buildLocationCanonicalizationAuditContextText(script, plan, repairSourceKeys), (contextText) => curateAssets(script, contextText));
+    });
+    const parts = unwrapConcurrentOutcomes(outcomes);
+    return combineAssetCurationExpressionPlans(parts);
+}
 export async function stageAssetCuration(ctx) {
     const { ws, state, options } = ctx;
     const script = ensureScript(ctx);
+    let groupingPlan = null;
+    let groupingApplySummary = null;
+    let plan = null;
+    let primaryPlan = null;
+    let auditPlan = null;
+    let locationCanonicalPlan = null;
+    let primaryExpressionText = null;
+    let primaryPartExpressionTexts = [];
+    let auditExpressionText = null;
+    let locationCanonicalExpressionText = null;
     try {
         ctx.updateRunState({ status: "init_running", init_stage: "asset_curation" });
         ctx.emitProgress("asset-curation");
-        const curation = curateScriptAssets(script);
+        const provider = ctx.provider();
+        if (!provider.curateAssets) {
+            throw new CliError("INIT FAILED: Provider does not support asset curation", "Provider does not support asset curation.", {
+                exitCode: EXIT_RUNTIME,
+                required: ["provider.curateAssets(script, contextText)"],
+                received: [`provider: ${provider.name || options.providerName}`],
+                nextSteps: ["Use a direct provider that supports asset curation."],
+            });
+        }
+        if (!provider.groupAssets) {
+            throw new CliError("INIT FAILED: Provider does not support asset grouping", "Provider does not support asset grouping.", {
+                exitCode: EXIT_RUNTIME,
+                required: ["provider.groupAssets(script, contextText)"],
+                received: [`provider: ${provider.name || options.providerName}`],
+                nextSteps: ["Use a direct provider that supports asset grouping."],
+            });
+        }
+        const groupAssets = provider.groupAssets.bind(provider);
+        const curateAssets = provider.curateAssets.bind(provider);
+        const groupingFingerprint = assetGroupingScriptFingerprint(script, options);
+        groupingPlan = await ctx.timing.span({ name: "asset_curation.grouping", category: "substage", parent: "asset_curation" }, () => loadOrRunAssetGrouping(ctx, script, groupAssets, groupingFingerprint));
+        groupingApplySummary = await ctx.timing.span({ name: "asset_curation.grouping.apply", category: "substage", parent: "asset_curation.grouping" }, () => applyAssetGroupingDuplicateMerges(script, { decisions: groupingPlan["duplicate_merge_decisions"] }));
+        Object.assign(groupingPlan, assetCacheArtifactFields(ctx, ASSET_GROUPING_CACHE_VERSION));
+        groupingPlan["apply_summary"] = groupingApplySummary;
+        groupingPlan["script_fingerprint"] = groupingFingerprint;
+        ws.writeJson("asset_grouping.json", groupingPlan);
+        const fingerprint = assetCurationScriptFingerprint(script, options);
+        const cachedCuration = ws.readJsonSafe("asset_curation.json");
+        if (!state.bypassInternalCaches && isDict(cachedCuration) && cachedCuration["script_fingerprint"] === fingerprint && isList(cachedCuration["decisions"])) {
+            const curation = curateScriptAssets(script, { decisions: cachedCuration["decisions"] });
+            Object.assign(curation, assetCacheArtifactFields(ctx, ASSET_CURATION_CACHE_VERSION));
+            curation["script_fingerprint"] = fingerprint;
+            curation["grouping"] = groupingPlan;
+            curation["grouping_apply_summary"] = groupingApplySummary;
+            if (typeof cachedCuration["expression_text"] === "string")
+                curation["expression_text"] = cachedCuration["expression_text"];
+            if (typeof cachedCuration["primary_expression_text"] === "string")
+                curation["primary_expression_text"] = cachedCuration["primary_expression_text"];
+            if (typeof cachedCuration["primary_part_expression_text"] === "string")
+                curation["primary_part_expression_text"] = cachedCuration["primary_part_expression_text"];
+            if (typeof cachedCuration["audit_expression_text"] === "string")
+                curation["audit_expression_text"] = cachedCuration["audit_expression_text"];
+            if (typeof cachedCuration["location_canonical_expression_text"] === "string")
+                curation["location_canonical_expression_text"] = cachedCuration["location_canonical_expression_text"];
+            if (isList(cachedCuration["expressions"]))
+                curation["expressions"] = cachedCuration["expressions"];
+            if (isList(cachedCuration["primary_expressions"]))
+                curation["primary_expressions"] = cachedCuration["primary_expressions"];
+            if (isList(cachedCuration["primary_parts"]))
+                curation["primary_parts"] = cachedCuration["primary_parts"];
+            if (isList(cachedCuration["audit_expressions"]))
+                curation["audit_expressions"] = cachedCuration["audit_expressions"];
+            if (isList(cachedCuration["location_canonical_expressions"]))
+                curation["location_canonical_expressions"] = cachedCuration["location_canonical_expressions"];
+            if (typeof cachedCuration["format"] === "string")
+                curation["format"] = cachedCuration["format"];
+            if (isDict(cachedCuration["audit_summary"]))
+                curation["audit_summary"] = cachedCuration["audit_summary"];
+            ws.writeJson("asset_curation.json", curation);
+            ws.delete("asset_curation.failed.json");
+            ctx.emitProgress("asset-curation", "success");
+            return;
+        }
+        const primaryChunkSpecs = primaryCurationChunks(script, groupingPlan);
+        const primaryOutcomes = await pMapWithConcurrency(primaryChunkSpecs, options.concurrency, async (chunk) => loadOrRunPrimaryCurationPart(ctx, script, curateAssets, chunk.kind, chunk.partId, fingerprint, chunk.ids));
+        const primaryParts = unwrapConcurrentOutcomes(primaryOutcomes);
+        primaryPartExpressionTexts = primaryParts.map((part) => ({
+            asset_kind: part["asset_kind"],
+            part_id: part["part_id"],
+            expression_text: part["expression_text"],
+        }));
+        primaryPlan = await ctx.timing.span({ name: "asset_curation.primary.combine", category: "substage", parent: "asset_curation.primary", metadata: { chunks: primaryParts.length } }, () => combinePrimaryAssetCurationPlans(primaryParts));
+        primaryExpressionText = typeof primaryPlan["expression_text"] === "string" ? primaryPlan["expression_text"] : "";
+        if (!isDict(primaryPlan) || !isList(primaryPlan["decisions"])) {
+            throw new CliError("INIT FAILED: Provider returned invalid asset curation", "Provider returned invalid asset curation.", {
+                exitCode: EXIT_RUNTIME,
+                required: ["object with decisions[]"],
+                received: [typeof primaryPlan],
+                nextSteps: ["Rerun init; completed extraction checkpoints will be reused and curation will retry."],
+            });
+        }
+        const allowedNewAuditSources = [
+            ...missingAssetCurationRequiredSourceKeys(script, primaryPlan),
+            ...assetCurationAuditCandidateSourceKeys(script, primaryPlan),
+        ];
+        auditPlan = await ctx.timing.span({ name: "asset_curation.audit", category: "substage", parent: "asset_curation" }, () => loadOrRunAuditCurationParts(ctx, script, curateAssets, primaryPlan, assetCurationPlanFingerprint(`${fingerprint}:audit-chunk-v1`, primaryPlan)));
+        auditExpressionText = typeof auditPlan["expression_text"] === "string" ? auditPlan["expression_text"] : "";
+        if (!isDict(auditPlan) || !isList(auditPlan["decisions"])) {
+            throw new CliError("INIT FAILED: Provider returned invalid asset curation audit", "Provider returned invalid asset curation audit.", {
+                exitCode: EXIT_RUNTIME,
+                required: ["object with decisions[]"],
+                received: [typeof auditPlan],
+                nextSteps: ["Rerun init; completed extraction checkpoints will be reused and curation audit will retry."],
+            });
+        }
+        plan = combineAssetCurationPlans(primaryPlan, auditPlan, allowedNewAuditSources);
+        const allowedNewLocationCanonicalSources = locationCanonicalizationCandidateSourceKeys(script, plan);
+        locationCanonicalPlan = await ctx.timing.span({ name: "asset_curation.location_canonical", category: "substage", parent: "asset_curation" }, () => loadOrRunLocationCanonicalizationParts(ctx, script, curateAssets, plan, assetCurationPlanFingerprint(`${fingerprint}:location-canonical-chunk-v2`, plan)));
+        locationCanonicalExpressionText = typeof locationCanonicalPlan["expression_text"] === "string" ? locationCanonicalPlan["expression_text"] : "";
+        if (!isDict(locationCanonicalPlan) || !isList(locationCanonicalPlan["decisions"])) {
+            throw new CliError("INIT FAILED: Provider returned invalid location canonicalization audit", "Provider returned invalid location canonicalization audit.", {
+                exitCode: EXIT_RUNTIME,
+                required: ["object with decisions[]"],
+                received: [typeof locationCanonicalPlan],
+                nextSteps: ["Rerun init; completed extraction checkpoints will be reused and location canonicalization will retry."],
+            });
+        }
+        assertLocationCanonicalizationPlan(locationCanonicalPlan);
+        plan = combineLocationCanonicalizationPlan(script, plan, locationCanonicalPlan, allowedNewLocationCanonicalSources);
+        const curation = await ctx.timing.span({ name: "asset_curation.apply", category: "substage", parent: "asset_curation" }, () => curateScriptAssets(script, plan));
+        Object.assign(curation, assetCacheArtifactFields(ctx, ASSET_CURATION_CACHE_VERSION));
+        curation["script_fingerprint"] = fingerprint;
+        curation["format"] = plan["format"];
+        curation["expression_text"] = plan["expression_text"];
+        curation["primary_expression_text"] = plan["primary_expression_text"];
+        curation["audit_expression_text"] = plan["audit_expression_text"];
+        curation["location_canonical_expression_text"] = plan["location_canonical_expression_text"];
+        curation["primary_part_expression_text"] = plan["primary_part_expression_text"];
+        curation["primary_parts"] = plan["primary_parts"];
+        curation["expressions"] = plan["expressions"];
+        curation["primary_expressions"] = plan["primary_expressions"];
+        curation["audit_expressions"] = plan["audit_expressions"];
+        curation["location_canonical_expressions"] = plan["location_canonical_expressions"];
+        curation["audit_summary"] = plan["audit_summary"];
+        curation["grouping"] = groupingPlan;
+        curation["grouping_apply_summary"] = groupingApplySummary;
         ws.writeJson("asset_curation.json", curation);
+        ws.delete("asset_curation.failed.json");
     }
     catch (exc) {
+        if (plan || primaryPlan || auditPlan || locationCanonicalPlan || primaryExpressionText !== null || auditExpressionText !== null || locationCanonicalExpressionText !== null) {
+            const e = exc;
+            ws.writeJson("asset_curation.failed.json", {
+                version: 3,
+                failed_at: checkpointTimestamp(),
+                error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
+                expression_text: plan?.["expression_text"] ?? null,
+                primary_expression_text: primaryExpressionText,
+                primary_part_expression_texts: primaryPartExpressionTexts,
+                audit_expression_text: auditExpressionText,
+                location_canonical_expression_text: locationCanonicalExpressionText,
+                primary_plan: primaryPlan,
+                audit_plan: auditPlan,
+                location_canonical_plan: locationCanonicalPlan,
+                grouping_plan: groupingPlan,
+                grouping_apply_summary: groupingApplySummary,
+                plan,
+            });
+        }
         stageFailure(options.workspace, exc, {
             title: "INIT FAILED: Asset curation failed",
             stage: "asset_curation",
@@ -2151,28 +3158,403 @@ export async function stageAssetCuration(ctx) {
     }
     ctx.emitProgress("asset-curation", "success");
 }
-// --- metadata -------------------------------------------------------------
-export async function stageMetadata(ctx) {
+// --- state-curation -------------------------------------------------------
+const STATE_CURATION_CACHE_VERSION = 1;
+function stateCurationScriptFingerprint(script, options) {
+    return sha256Text(JSON.stringify(sortDeep({
+        cache_version: STATE_CURATION_CACHE_VERSION,
+        ...assetCacheIdentity(options),
+        script: {
+            actors: script["actors"],
+            locations: script["locations"],
+            props: script["props"],
+            episodes: script["episodes"],
+        },
+    })));
+}
+function stateCurationContextFingerprint(scriptFingerprint, partId, refs) {
+    return sha256Text(JSON.stringify(sortDeep({
+        script_fingerprint: scriptFingerprint,
+        part_id: partId,
+        refs,
+    })));
+}
+function combineStateCurationPlans(parts) {
+    const decisions = parts.flatMap((part) => asList(part.plan["decisions"]).filter(isDict));
+    const expressions = parts.flatMap((part) => asList(part.plan["expressions"]));
+    return {
+        version: 1,
+        format: "state-curation-exp-v1",
+        expression_text: expressions.length > 0 ? expressions.map((expression) => `<exp>${expression}</exp>`).join("\n") : "<exp>NOOP # no state curation changes</exp>",
+        expressions,
+        decisions,
+        parts: parts.map((part) => ({
+            part_id: part.partId,
+            refs: part.refs,
+            context_fingerprint: part.contextFingerprint,
+            context_chars: part.contextChars,
+            reused: part.reused,
+            decisions: asList(part.plan["decisions"]).length,
+        })),
+    };
+}
+async function loadOrRunStateCurationPart(ctx, script, curateStates, scriptFingerprint, partId, refs) {
+    const artifactName = `state_curation_parts/${partId}.json`;
+    const contextFingerprint = stateCurationContextFingerprint(scriptFingerprint, partId, refs);
+    const cached = ctx.ws.readJsonSafe(artifactName);
+    const cachedPlan = !ctx.state.bypassInternalCaches
+        && isDict(cached)
+        && cached["context_fingerprint"] === contextFingerprint
+        && cached["parse_status"] === "ok"
+        && isDict(cached["plan"])
+        ? cached["plan"]
+        : null;
+    if (cachedPlan && isList(cachedPlan["decisions"])) {
+        const cachedContextChars = isDict(cached) ? Number(cached["context_chars"] ?? 0) : 0;
+        return {
+            partId,
+            refs: [...refs],
+            contextFingerprint,
+            contextChars: cachedContextChars,
+            plan: cachedPlan,
+            reused: true,
+        };
+    }
+    const startedAtMs = Date.now();
+    const contextText = buildStateCurationContextText(script, refs);
+    const requiredKeys = stateCurationSourceKeysForRefs(script, refs);
+    let expressionText = "";
+    try {
+        expressionText = await ctx.timing.span({ name: `state_curation.${partId}`, category: "chunk", parent: "state_curation.chunks", metadata: { artifact: artifactName } }, () => curateStates(script, contextText));
+        const parsed = parseStateCurationExpressions(expressionText);
+        const plan = assertStateCurationPlan(script, parsed, requiredKeys);
+        ctx.ws.writeJson(artifactName, {
+            version: 1,
+            ...assetCacheArtifactFields(ctx, STATE_CURATION_CACHE_VERSION),
+            context_fingerprint: contextFingerprint,
+            script_fingerprint: scriptFingerprint,
+            parse_status: "ok",
+            part_id: partId,
+            refs,
+            required_state_ids: requiredKeys,
+            context_chars: contextText.length,
+            expression_text: expressionText,
+            duration_ms: durationMs(startedAtMs, Date.now()),
+            plan,
+            updated_at: checkpointTimestamp(),
+        });
+        return {
+            partId,
+            refs: [...refs],
+            contextFingerprint,
+            contextChars: contextText.length,
+            plan,
+            reused: false,
+        };
+    }
+    catch (exc) {
+        const e = exc;
+        ctx.ws.writeJson(artifactName, {
+            version: 1,
+            ...assetCacheArtifactFields(ctx, STATE_CURATION_CACHE_VERSION),
+            context_fingerprint: contextFingerprint,
+            script_fingerprint: scriptFingerprint,
+            parse_status: "failed",
+            part_id: partId,
+            refs,
+            required_state_ids: requiredKeys,
+            context_chars: contextText.length,
+            expression_text: expressionText,
+            duration_ms: durationMs(startedAtMs, Date.now()),
+            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
+            updated_at: checkpointTimestamp(),
+        });
+        throw exc;
+    }
+}
+export async function stageStateCuration(ctx) {
     const { ws, state, options } = ctx;
     const script = ensureScript(ctx);
+    let plan = null;
+    try {
+        ctx.updateRunState({ status: "init_running", init_stage: "state_curation" });
+        ctx.emitProgress("state-curation");
+        const scriptFingerprint = stateCurationScriptFingerprint(script, options);
+        const cached = ws.readJsonSafe("state_curation.json");
+        if (!state.bypassInternalCaches && isDict(cached) && cached["script_fingerprint"] === scriptFingerprint && isList(cached["decisions"])) {
+            const curation = await ctx.timing.span({ name: "state_curation.apply", category: "substage", parent: "state_curation" }, () => applyStateCurationPlan(script, { decisions: cached["decisions"] }));
+            curation["script_fingerprint"] = scriptFingerprint;
+            curation["cache_version"] = STATE_CURATION_CACHE_VERSION;
+            curation["provider"] = options.providerName;
+            curation["model"] = options.model;
+            if (isList(cached["parts"]))
+                curation["parts"] = cached["parts"];
+            if (typeof cached["expression_text"] === "string")
+                curation["expression_text"] = cached["expression_text"];
+            if (isList(cached["expressions"]))
+                curation["expressions"] = cached["expressions"];
+            ws.writeJson("state_curation.json", curation);
+            ws.delete("state_curation.failed.json");
+            ctx.emitProgress("state-curation", "success");
+            return;
+        }
+        const chunks = buildStateCurationChunks(script);
+        if (chunks.length === 0) {
+            const curation = applyStateCurationPlan(script, { decisions: [] });
+            curation["script_fingerprint"] = scriptFingerprint;
+            curation["cache_version"] = STATE_CURATION_CACHE_VERSION;
+            curation["provider"] = options.providerName;
+            curation["model"] = options.model;
+            curation["parts"] = [];
+            curation["expression_text"] = "<exp>NOOP # no state curation changes</exp>";
+            curation["expressions"] = ["NOOP # no state curation changes"];
+            ws.writeJson("state_curation.json", curation);
+            ws.delete("state_curation.failed.json");
+            ctx.emitProgress("state-curation", "success");
+            return;
+        }
+        const provider = ctx.provider();
+        if (!provider.curateStates) {
+            throw new CliError("INIT FAILED: Provider does not support state curation", "Provider does not support state curation.", {
+                exitCode: EXIT_RUNTIME,
+                required: ["provider.curateStates(script, contextText)"],
+                received: [`provider: ${provider.name || options.providerName}`],
+                nextSteps: ["Use a direct provider that supports state curation."],
+            });
+        }
+        ws.mkdir("state_curation_parts");
+        ctx.updateRunState({ state_curation_completed_chunks: 0, state_curation_total_chunks: chunks.length });
+        const curateStates = provider.curateStates.bind(provider);
+        let completedChunks = 0;
+        const outcomes = await pMapWithConcurrency(chunks, options.concurrency, async (chunk) => {
+            const part = await loadOrRunStateCurationPart(ctx, script, curateStates, scriptFingerprint, chunk.part_id, chunk.refs);
+            completedChunks += 1;
+            ctx.updateRunState({ state_curation_completed_chunks: completedChunks, state_curation_total_chunks: chunks.length });
+            return part;
+        });
+        const parts = unwrapConcurrentOutcomes(outcomes).sort((left, right) => left.partId.localeCompare(right.partId));
+        plan = combineStateCurationPlans(parts);
+        const curation = await ctx.timing.span({ name: "state_curation.apply", category: "substage", parent: "state_curation" }, () => applyStateCurationPlan(script, plan));
+        curation["script_fingerprint"] = scriptFingerprint;
+        curation["cache_version"] = STATE_CURATION_CACHE_VERSION;
+        curation["provider"] = options.providerName;
+        curation["model"] = options.model;
+        curation["expression_text"] = plan["expression_text"];
+        curation["expressions"] = plan["expressions"];
+        curation["parts"] = plan["parts"];
+        ws.writeJson("state_curation.json", curation);
+        ws.delete("state_curation.failed.json");
+    }
+    catch (exc) {
+        const e = exc;
+        ws.writeJson("state_curation.failed.json", {
+            version: 1,
+            failed_at: checkpointTimestamp(),
+            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
+            plan,
+        });
+        stageFailure(options.workspace, exc, {
+            title: "INIT FAILED: State curation failed",
+            stage: "state_curation",
+            required: ["provider state curation decisions for the assembled script state catalog"],
+            nextSteps: ["Rerun init; completed extraction and asset curation checkpoints will be reused."],
+            updates: { episode_completed: state.mergedResults.length },
+        });
+    }
+    ctx.emitProgress("state-curation", "success");
+}
+const STATE_BINDING_CHUNK_CACHE_VERSION = 1;
+function stateBindingChunkFingerprint(options, context) {
+    return sha256Text(JSON.stringify(sortDeep({
+        cache_version: STATE_BINDING_CHUNK_CACHE_VERSION,
+        provider: options.providerName,
+        model: options.model,
+        context,
+    })));
+}
+async function runStateBindingForScript(ctx, script, progress) {
+    const { ws, options } = ctx;
+    const provider = ctx.provider();
+    if (!provider.bindStates) {
+        throw new CliError("INIT FAILED: Provider does not support state binding", "Provider does not support state binding.", {
+            exitCode: EXIT_RUNTIME,
+            required: ["provider.bindStates(script, context)"],
+            received: [`provider: ${provider.name || options.providerName}`],
+            nextSteps: ["Use a direct provider that supports state binding."],
+        });
+    }
+    const defaultSummary = await ctx.timing.span({ name: "state_binding.default_states", category: "substage", parent: "state_binding" }, () => ensureDefaultStates(script));
+    const defaultBindingSummary = await ctx.timing.span({ name: "state_binding.default_refs", category: "substage", parent: "state_binding" }, () => bindDefaultStateRefsInScript(script));
+    const chunks = buildStateBindingContexts(script, 8);
+    ws.mkdir("state_binding_chunks");
+    if (progress) {
+        ctx.updateRunState({ state_binding_completed_chunks: 0, state_binding_total_chunks: chunks.length });
+    }
+    let chunkPlans = [];
+    const bypassChunkCache = ctx.state.bypassInternalCaches;
+    try {
+        const outcomes = await pMapWithConcurrency(chunks, options.concurrency, async (context, index) => {
+            const chunkArtifact = `state_binding_chunks/chunk_${pad3(index + 1)}.json`;
+            const contextFingerprint = stateBindingChunkFingerprint(options, context);
+            const cachedChunk = ws.readJsonSafe(chunkArtifact);
+            const cachedPlanRaw = isDict(cachedChunk) ? cachedChunk["plan"] : null;
+            const cachedPlan = !bypassChunkCache
+                && isDict(cachedChunk)
+                && cachedChunk["context_fingerprint"] === contextFingerprint
+                && isDict(cachedPlanRaw)
+                ? cachedPlanRaw
+                : null;
+            const startedAtMs = Date.now();
+            const rawPlan = normalizeStateBindingPlanShape(cachedPlan ?? await ctx.timing.span({ name: `state_binding.chunk.${pad3(index + 1)}`, category: "chunk", parent: "state_binding.chunks", metadata: { index } }, () => provider.bindStates(script, context)));
+            if (!isDict(rawPlan) || !isList(rawPlan["scenes"])) {
+                throw new CliError("INIT FAILED: Provider returned invalid state binding", "Provider returned invalid state binding.", {
+                    exitCode: EXIT_RUNTIME,
+                    required: ["object with scenes[]"],
+                    received: [typeof rawPlan],
+                    nextSteps: ["Rerun init; completed extraction checkpoints will be reused and state binding will retry."],
+                });
+            }
+            if (!cachedPlan) {
+                ws.writeJson(chunkArtifact, {
+                    version: 1,
+                    cache_version: STATE_BINDING_CHUNK_CACHE_VERSION,
+                    index,
+                    provider: options.providerName,
+                    model: options.model,
+                    context_fingerprint: contextFingerprint,
+                    scene_ids: asList(context["scenes"]).map((scene) => strOf(scene["scene_id"])),
+                    duration_ms: durationMs(startedAtMs, Date.now()),
+                    plan: rawPlan,
+                    updated_at: checkpointTimestamp(),
+                });
+            }
+            if (progress) {
+                ctx.updateRunState({ state_binding_completed_chunks: index + 1, state_binding_total_chunks: chunks.length });
+            }
+            return { index, context, plan: rawPlan, contextFingerprint, reused: Boolean(cachedPlan) };
+        });
+        chunkPlans = unwrapConcurrentOutcomes(outcomes).sort((left, right) => left.index - right.index);
+    }
+    catch (exc) {
+        const e = exc;
+        ws.writeJson("state_binding.failed.json", {
+            version: 1,
+            failed_at: checkpointTimestamp(),
+            chunks_total: chunks.length,
+            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
+            completed_chunks: [],
+        });
+        throw exc;
+    }
+    const chunkReports = [];
+    let sceneRefsBound = 0;
+    let stateChangesApplied = 0;
+    let invalidSceneRefsSkipped = 0;
+    let invalidStateChangesSkipped = 0;
+    try {
+        await ctx.timing.span({ name: "state_binding.apply", category: "substage", parent: "state_binding" }, () => {
+            for (const item of chunkPlans) {
+                const applied = applyStateBindingPlan(script, item.plan, { invalidStateMode: "skip" });
+                sceneRefsBound += Number(applied["scene_refs_bound"] ?? 0);
+                stateChangesApplied += Number(applied["state_changes_applied"] ?? 0);
+                invalidSceneRefsSkipped += Number(applied["invalid_scene_refs_skipped"] ?? 0);
+                invalidStateChangesSkipped += Number(applied["invalid_state_changes_skipped"] ?? 0);
+                chunkReports.push({
+                    index: item.index,
+                    reused: item.reused,
+                    context_fingerprint: item.contextFingerprint,
+                    scene_count: asList(item.context["scenes"]).length,
+                    scene_refs_bound: applied["scene_refs_bound"],
+                    state_changes_applied: applied["state_changes_applied"],
+                    invalid_scene_refs_skipped: applied["invalid_scene_refs_skipped"],
+                    invalid_state_changes_skipped: applied["invalid_state_changes_skipped"],
+                });
+            }
+        });
+    }
+    catch (exc) {
+        const e = exc;
+        ws.writeJson("state_binding.failed.json", {
+            version: 1,
+            failed_at: checkpointTimestamp(),
+            chunks_total: chunks.length,
+            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
+            completed_chunks: chunkReports,
+        });
+        throw exc;
+    }
+    const summary = {
+        ...defaultSummary,
+        ...defaultBindingSummary,
+        llm_scene_refs_bound: sceneRefsBound,
+        llm_state_changes_applied: stateChangesApplied,
+        invalid_scene_refs_skipped: invalidSceneRefsSkipped,
+        invalid_state_changes_skipped: invalidStateChangesSkipped,
+        chunks: chunks.length,
+        cached_chunks: chunkPlans.filter((chunk) => chunk.reused).length,
+        llm_scene_count: chunks.reduce((n, chunk) => n + asList(chunk["scenes"]).length, 0),
+    };
+    ws.writeJson("state_binding.json", {
+        version: 1,
+        summary,
+        chunks: chunkReports,
+    });
+    ws.delete("state_binding.failed.json");
+    return { summary, chunks: chunkReports };
+}
+export async function stageStateBinding(ctx) {
+    const { state, options } = ctx;
+    const script = ensureScript(ctx);
+    try {
+        ctx.updateRunState({ status: "init_running", init_stage: "state_binding" });
+        ctx.emitProgress("state-binding");
+        await runStateBindingForScript(ctx, script, true);
+    }
+    catch (exc) {
+        stageFailure(options.workspace, exc, {
+            title: "INIT FAILED: State binding failed",
+            stage: "state_binding",
+            required: ["provider state binding decisions for a well-formed assembled script"],
+            nextSteps: ["Rerun init; completed extraction and curation checkpoints will be reused."],
+            updates: { episode_completed: state.mergedResults.length },
+        });
+    }
+    ctx.emitProgress("state-binding", "success");
+}
+async function runMetadataForScript(ctx, script, applyToScript, progress) {
+    const { ws, options } = ctx;
     const sourceText = ensureSourceText(ctx);
     const assetMetadataPath = ws.pathOf("asset_metadata.json");
     if (options.skipMetadata) {
-        ctx.updateRunState({ status: "init_running", init_stage: "metadata_extract", metadata_skipped: true });
+        if (progress)
+            ctx.updateRunState({ status: "init_running", init_stage: "metadata_extract", metadata_skipped: true });
         if (exists(assetMetadataPath))
             deletePath(assetMetadataPath);
-        ctx.emitProgress("metadata", "skipped");
-        return;
+        return { metadata: {}, skipped: true };
     }
     const provider = ctx.provider();
+    let metadata = provider.extractMetadata
+        ? await ctx.timing.span({ name: "metadata.extract", category: "substage", parent: "metadata_extract" }, () => provider.extractMetadata(sourceText, script))
+        : {};
+    if (!isDict(metadata))
+        metadata = {};
+    ws.writeJson("asset_metadata.json", metadata);
+    if (applyToScript) {
+        await ctx.timing.span({ name: "metadata.apply", category: "substage", parent: "metadata_extract" }, () => applyMetadataToScript(script, metadata));
+    }
+    return { metadata, skipped: false };
+}
+export async function stageMetadata(ctx) {
+    const { state, options } = ctx;
+    const script = ensureScript(ctx);
     try {
         ctx.updateRunState({ status: "init_running", init_stage: "metadata_extract", metadata_skipped: false });
         ctx.emitProgress("metadata");
-        let metadata = provider.extractMetadata ? await provider.extractMetadata(sourceText, script) : {};
-        if (!isDict(metadata))
-            metadata = {};
-        ws.writeJson("asset_metadata.json", metadata);
-        applyMetadataToScript(script, metadata);
+        const result = await runMetadataForScript(ctx, script, true, true);
+        if (result.skipped) {
+            ctx.emitProgress("metadata", "skipped");
+            return;
+        }
     }
     catch (exc) {
         if (exc instanceof CliError) {
@@ -2197,16 +3579,21 @@ export async function stageMetadata(ctx) {
     }
     ctx.emitProgress("metadata", "success");
 }
-// --- script-synopsis ------------------------------------------------------
-export async function stageScriptSynopsis(ctx) {
-    const { ws, state, options } = ctx;
-    const script = ensureScript(ctx);
+function overviewFieldsFromScript(script) {
+    return {
+        synopsis: script["synopsis"],
+        theme: script["theme"],
+        logline: script["logline"],
+        style: script["style"],
+        main_characters: script["main_characters"],
+    };
+}
+async function runScriptSynopsisForScript(ctx, script, persistScript) {
+    const { ws, options } = ctx;
     const provider = ctx.provider();
-    let summaryFullDegraded = false;
-    let summaryDegradeReason = "";
+    let degraded = false;
+    let reason = "";
     try {
-        ctx.updateRunState({ status: "init_running", init_stage: "script_synopsis" });
-        ctx.emitProgress("script-synopsis");
         const summary = await buildScriptSynopsis(provider, script, {
             dd: ws.dir,
             thresholdChars: options.summaryThresholdChars,
@@ -2215,25 +3602,32 @@ export async function stageScriptSynopsis(ctx) {
             skipSummary: options.skipSummary,
             concurrency: options.concurrency,
         });
-        summaryFullDegraded = summary.degraded;
-        summaryDegradeReason = summary.reason ?? "";
+        degraded = summary.degraded;
+        reason = summary.reason ?? "";
     }
     catch (exc) {
-        summaryFullDegraded = true;
-        summaryDegradeReason = providerErrorSummary(exc);
+        degraded = true;
+        reason = providerErrorSummary(exc);
     }
-    state.summaryFullDegraded = summaryFullDegraded;
-    state.summaryDegradeReason = summaryDegradeReason;
+    if (persistScript)
+        ws.writeJson("script.initial.json", script);
+    return { degraded, reason, fields: overviewFieldsFromScript(script) };
+}
+export async function stageScriptSynopsis(ctx) {
+    const { ws, state, options } = ctx;
+    const script = ensureScript(ctx);
+    ctx.updateRunState({ status: "init_running", init_stage: "script_synopsis" });
+    ctx.emitProgress("script-synopsis");
+    const summary = await runScriptSynopsisForScript(ctx, script, true);
+    state.summaryFullDegraded = summary.degraded;
+    state.summaryDegradeReason = summary.reason;
     state.summaryDegradedEpisodes.sort((a, b) => a - b);
-    const summaryDegraded = summaryFullDegraded || state.summaryDegradedEpisodes.length > 0;
-    // Persist script.initial.json now that the overview fields are assigned — the
-    // same write point as the god-command (right after the synopsis stage).
-    ws.writeJson("script.initial.json", script);
+    const summaryDegraded = summary.degraded || state.summaryDegradedEpisodes.length > 0;
     ctx.updateRunState({
         summary_skipped: options.skipSummary,
         summary_degraded: summaryDegraded,
         summary_degraded_episodes: state.summaryDegradedEpisodes,
-        summary_degraded_reason: summaryDegradeReason || null,
+        summary_degraded_reason: summary.reason || null,
     });
     ctx.emitProgress("script-synopsis", summaryDegraded ? "warning" : options.skipSummary ? "skipped" : "success");
 }
@@ -2502,6 +3896,40 @@ function renderAssetCurationSummary(curation) {
             `locations ${summary["locations_before"] ?? 0}->${summary["locations_after"] ?? 0} ` +
             `(merged ${summary["locations_merged"] ?? 0})`,
     ];
+    const coverage = isDict(summary["coverage"]) ? summary["coverage"] : {};
+    const required = isDict(coverage["required"]) ? coverage["required"] : {};
+    const auditSummary = isDict(curation["audit_summary"]) ? curation["audit_summary"] : {};
+    if (summary["explicit_keep_count"] !== undefined || auditSummary["audit_decisions"] !== undefined || required["prop"] !== undefined) {
+        lines.push(`curation coverage: ` +
+            `keep ${summary["explicit_keep_count"] ?? 0}, ` +
+            `implicit ${summary["implicit_keep_count"] ?? 0}, ` +
+            `audit ${auditSummary["audit_decisions"] ?? 0}, ` +
+            `required actor/location/prop ${required["actor"] ?? 0}/${required["location"] ?? 0}/${required["prop"] ?? 0}`);
+    }
+    for (const decision of asList(curation["decisions"])) {
+        if (!isDict(decision))
+            continue;
+        const action = strOf(decision["decision"]);
+        if (!action || action === "keep")
+            continue;
+        const kind = strOf(decision["kind"]);
+        const sourceId = strOf(decision["source_id"]);
+        const targetKind = strOf(decision["target_kind"]);
+        const targetId = strOf(decision["target_id"]);
+        const newName = strOf(decision["new_name"]);
+        const stateName = strOf(decision["state_name"]);
+        const speakerKind = strOf(decision["speaker_kind"]);
+        const target = targetId
+            ? ` -> ${targetKind || kind}:${targetId}`
+            : newName
+                ? ` -> ${newName}`
+                : stateName
+                    ? ` -> state:${stateName}`
+                    : speakerKind
+                        ? ` -> speaker:${speakerKind}`
+                        : "";
+        lines.push(`curation ${kind}:${sourceId} ${action}${target} — ${decision["reason"] || "-"}`);
+    }
     for (const actor of asList(curation["actors"])) {
         if (!isDict(actor) || actor["decision"] !== "remove")
             continue;
@@ -2519,6 +3947,46 @@ function renderAssetCurationSummary(curation) {
     }
     return lines;
 }
+function renderStateBindingSummary(binding) {
+    const summary = isDict(binding["summary"]) ? binding["summary"] : {};
+    return [
+        `state-binding: ` +
+            `default-states +${summary["default_states_added"] ?? 0}, ` +
+            `llm refs ${summary["llm_scene_refs_bound"] ?? 0}, ` +
+            `default refs ${summary["default_or_unique_refs_bound"] ?? 0}, ` +
+            `unresolved ${summary["unresolved_stateful_refs"] ?? 0}, ` +
+            `state_changes ${summary["llm_state_changes_applied"] ?? 0}, ` +
+            `chunks ${summary["chunks"] ?? 0}`,
+    ];
+}
+function renderStateCurationSummary(curation) {
+    const summary = isDict(curation["summary"]) ? curation["summary"] : {};
+    const decisionSummary = isDict(summary["decisions"]) ? summary["decisions"] : {};
+    const lines = [
+        `state-curation: ` +
+            `states ${summary["states_before"] ?? 0}->${summary["states_after"] ?? 0} ` +
+            `(removed ${summary["states_removed"] ?? 0}), ` +
+            `actor/location/prop ${summary["actor_states_after"] ?? 0}/${summary["location_states_after"] ?? 0}/${summary["prop_states_after"] ?? 0}, ` +
+            `merge ${decisionSummary["merge"] ?? 0}, drop ${decisionSummary["drop"] ?? 0}, action ${decisionSummary["action_desc"] ?? 0}, rename ${decisionSummary["rename"] ?? 0}`,
+    ];
+    for (const decision of asList(curation["decisions"])) {
+        if (!isDict(decision))
+            continue;
+        const action = strOf(decision["decision"]);
+        if (!action || action === "keep")
+            continue;
+        const kind = strOf(decision["kind"]);
+        const assetId = strOf(decision["asset_id"]);
+        const stateId = strOf(decision["state_id"]);
+        const target = action === "merge"
+            ? ` -> ${decision["target_state_id"] || "-"}`
+            : action === "rename"
+                ? ` -> ${decision["new_name"] || "-"}`
+                : "";
+        lines.push(`state-curation ${kind}:${assetId}/${stateId} ${action}${target} — ${decision["reason"] || "-"}`);
+    }
+    return lines;
+}
 function renderAssetNormalizationSummary(normalization) {
     const summary = isDict(normalization["summary"]) ? normalization["summary"] : {};
     const lines = [
@@ -2631,6 +4099,8 @@ export function commandReview(opts) {
     // (validation issues recomputed live, plus batch extraction failures).
     const lines = [];
     const curationPath = path.join(dd, "asset_curation.json");
+    const stateCurationPath = path.join(dd, "state_curation.json");
+    const stateBindingPath = path.join(dd, "state_binding.json");
     const normalizationPath = path.join(dd, "asset_normalization.json");
     if (exists(normalizationPath)) {
         const normalization = readJson(normalizationPath);
@@ -2642,6 +4112,16 @@ export function commandReview(opts) {
         if (isDict(curation))
             lines.push(...renderAssetCurationSummary(curation));
     }
+    if (exists(stateCurationPath)) {
+        const curation = readJson(stateCurationPath);
+        if (isDict(curation))
+            lines.push(...renderStateCurationSummary(curation));
+    }
+    if (exists(stateBindingPath)) {
+        const binding = readJson(stateBindingPath);
+        if (isDict(binding))
+            lines.push(...renderStateBindingSummary(binding));
+    }
     const batchFailures = collectBatchFailures(batchResultsDir);
     for (const errors of batchFailures.values()) {
         for (const error of errors) {
@@ -2665,7 +4145,7 @@ export function commandReview(opts) {
     const report = {
         title: "DIRECT REVIEW",
         result: lines.length > 0 ? lines : ["No issues, curation decisions, or batch failures to review."],
-        artifacts: [scriptPath, normalizationPath, path.join(dd, "asset_curation.json"), batchResultsDir],
+        artifacts: [scriptPath, normalizationPath, path.join(dd, "asset_grouping.json"), path.join(dd, "asset_curation.json"), stateCurationPath, stateBindingPath, batchResultsDir],
         next: [
             "Run `direct review --episode <n>` for source↔extract alignment.",
             "Edit with `--draft` (e.g. `scriptctl rename … --draft`), then validate/export.",