@lingjingai/scriptctl 0.1.0

package/dist/domain/script-core.js

@@ -0,0 +1,1886 @@
+import { ACTION_TYPE_VALUES, CliError, DELIVERY_VALUES, EFFECTIVE_FROM_VALUES, EXIT_INPUT, EXIT_USAGE, ROLE_TYPE_VALUES, SCRIPT_SCHEMA_VERSION, SCRIPT_TARGET_KINDS, SPEAKER_SOURCE_KINDS, WORLDVIEW_VALUES, directDir, exists, fmtId, readJson, readText, writeJson, } from "../common.js";
+import { cleanName, contentHasSpeakerPrefix, inferNonActorSpeakerKind, isTechnicalEpisodeTitle, sceneContext, setSceneContext, stateLabelError, stateRejectionReason, } from "./direct-core.js";
+import * as path from "node:path";
+function strOf(v) {
+    if (v === null || v === undefined)
+        return "";
+    return String(v);
+}
+function isDict(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isList(v) {
+    return Array.isArray(v);
+}
+function asList(v) {
+    return Array.isArray(v) ? v : [];
+}
+// ---------------------------------------------------------------------------
+// Find helpers
+// ---------------------------------------------------------------------------
+export function findAction(script, epId, sceneId, actionIndex) {
+    for (const ep of asList(script["episodes"])) {
+        if (ep["episode_id"] !== epId)
+            continue;
+        for (const scene of asList(ep["scenes"])) {
+            if (scene["scene_id"] === sceneId) {
+                const actions = asList(scene["actions"]);
+                if (actionIndex >= 0 && actionIndex < actions.length)
+                    return actions[actionIndex];
+            }
+        }
+    }
+    throw new CliError("PATCH BLOCKED: Action not found", "Action not found.", {
+        exitCode: EXIT_USAGE,
+        required: ["existing episode_id, scene_id, action_index"],
+        received: [`${epId} ${sceneId} ${actionIndex}`],
+        nextSteps: ["Inspect episodes and fix the patch."],
+    });
+}
+export function findEpisode(script, epId) {
+    for (const ep of asList(script["episodes"])) {
+        if (ep["episode_id"] === epId)
+            return ep;
+    }
+    throw new CliError("PATCH BLOCKED: Episode not found", "Episode not found.", {
+        exitCode: EXIT_USAGE,
+        required: ["existing episode_id"],
+        received: [epId],
+        nextSteps: ["Inspect episodes and fix the patch."],
+    });
+}
+export function findScene(script, epId, sceneId) {
+    const ep = findEpisode(script, epId);
+    for (const scene of asList(ep["scenes"])) {
+        if (scene["scene_id"] === sceneId)
+            return scene;
+    }
+    throw new CliError("PATCH BLOCKED: Scene not found", "Scene not found.", {
+        exitCode: EXIT_USAGE,
+        required: ["existing episode_id and scene_id"],
+        received: [`${epId} ${sceneId}`],
+        nextSteps: ["Inspect episodes and fix the patch."],
+    });
+}
+// ---------------------------------------------------------------------------
+// validate_script
+// ---------------------------------------------------------------------------
+export function validateScript(workspace, scriptPath = null, opts = {}) {
+    const requireSource = opts.requireSource ?? true;
+    const dd = directDir(workspace);
+    const sourcePath = path.join(workspace, "source.txt");
+    const finalScriptPath = scriptPath ?? path.join(dd, "script.initial.json");
+    if (requireSource && !exists(sourcePath)) {
+        throw new CliError("VALIDATE BLOCKED: source.txt not found", "source.txt not found.", {
+            exitCode: EXIT_INPUT,
+            required: ["workspace/source.txt"],
+            received: [sourcePath],
+            nextSteps: ["Run scriptctl direct init first."],
+        });
+    }
+    if (!exists(finalScriptPath)) {
+        throw new CliError("VALIDATE BLOCKED: script not found", "Script JSON not found.", {
+            exitCode: EXIT_INPUT,
+            required: ["script.initial.json or --script-path"],
+            received: [finalScriptPath],
+            nextSteps: ["Run scriptctl direct init first."],
+        });
+    }
+    if (exists(sourcePath))
+        readText(sourcePath); // touch, mirror Python
+    let script;
+    try {
+        script = readJson(finalScriptPath);
+    }
+    catch (exc) {
+        throw new CliError("VALIDATE BLOCKED: script JSON invalid", "Script JSON invalid.", {
+            exitCode: EXIT_INPUT,
+            required: ["valid script JSON"],
+            received: [`${finalScriptPath}: ${exc.message}`],
+            nextSteps: ["Fix script.initial.json or rerun init."],
+        });
+    }
+    const issues = [];
+    const metadataPath = path.join(dd, "asset_metadata.json");
+    if (exists(metadataPath)) {
+        let metadata = {};
+        try {
+            metadata = readJson(metadataPath);
+        }
+        catch {
+            metadata = {};
+        }
+        if (isDict(metadata) && metadata["confidence"] === "low") {
+            issues.push({
+                code: "LOW_CONFIDENCE_METADATA",
+                severity: "error",
+                summary: "AI metadata confidence is low.",
+                repair_hint: "Inspect assets and patch worldview, role_type, or descriptions explicitly.",
+            });
+        }
+    }
+    for (const field of ["version", "title", "worldview", "style", "actors", "locations", "props", "speakers", "episodes"]) {
+        if (!(field in script)) {
+            issues.push({
+                code: "SCHEMA_TOP_FIELD_MISSING",
+                severity: "error",
+                summary: `Top-level field missing: ${field}`,
+                repair_hint: "Patch script.json or rerun init.",
+            });
+        }
+    }
+    if (script["version"] !== SCRIPT_SCHEMA_VERSION && script["version"] !== String(SCRIPT_SCHEMA_VERSION)) {
+        issues.push({
+            code: "SCHEMA_VERSION_UNSUPPORTED",
+            severity: "warning",
+            summary: `script version should be ${SCRIPT_SCHEMA_VERSION}.`,
+            repair_hint: "Update the internal numeric version when migrating script.json.",
+        });
+    }
+    const actorIds = new Set();
+    for (const item of asList(script["actors"])) {
+        const id = strOf(item["actor_id"]);
+        if (id)
+            actorIds.add(id);
+    }
+    const locationIds = new Set();
+    for (const item of asList(script["locations"])) {
+        const id = strOf(item["location_id"]);
+        if (id)
+            locationIds.add(id);
+    }
+    const propIds = new Set();
+    for (const item of asList(script["props"])) {
+        const id = strOf(item["prop_id"]);
+        if (id)
+            propIds.add(id);
+    }
+    const speakerDisplayNames = new Set();
+    for (const item of asList(script["speakers"])) {
+        if (!isDict(item))
+            continue;
+        const name = strOf(item["display_name"]).trim();
+        if (name)
+            speakerDisplayNames.add(cleanName(name));
+    }
+    const actors = asList(script["actors"]);
+    for (let idx = 0; idx < actors.length; idx++) {
+        const actor = actors[idx];
+        if (!isDict(actor)) {
+            issues.push({
+                code: "SCHEMA_ENTITY_FIELD_MISSING",
+                severity: "error",
+                summary: `actors[${idx}] is not an object.`,
+                repair_hint: "Patch actor entry.",
+            });
+            continue;
+        }
+        const actorName = strOf(actor["actor_name"]).trim();
+        for (const field of ["actor_id", "actor_name", "description"]) {
+            if (!strOf(actor[field]).trim()) {
+                issues.push({
+                    code: "SCHEMA_ENTITY_FIELD_MISSING",
+                    severity: "error",
+                    summary: `Actor missing ${field}: ${actor["actor_id"] || idx}`,
+                    repair_hint: "Patch actor metadata.",
+                });
+            }
+        }
+        if (actorName && cleanName(actorName) !== actorName) {
+            issues.push({
+                code: "ASSET_NAME_HAS_STATE_ANNOTATION",
+                severity: "error",
+                summary: `Actor name contains state annotation: ${actorName}`,
+                repair_hint: "Keep actor_name canonical and move state text to states[] or action content only if reusable.",
+            });
+        }
+        if (actorName && inferNonActorSpeakerKind(actorName) !== "actor") {
+            issues.push({
+                code: "NONHUMAN_AS_ACTOR",
+                severity: "error",
+                summary: `Non-human speaker is registered as actor: ${actorName}`,
+                repair_hint: "Use speakers[] with source_kind system/broadcast/prop/group/other; do not create an actor.",
+            });
+        }
+        if (actor["role_type"] && !ROLE_TYPE_VALUES.includes(strOf(actor["role_type"]))) {
+            issues.push({
+                code: "ENUM_ROLE_TYPE",
+                severity: "error",
+                summary: `Actor role_type invalid: ${actor["role_type"]}`,
+                repair_hint: "Patch role_type to 主角 or 配角.",
+            });
+        }
+    }
+    const locations = asList(script["locations"]);
+    for (let idx = 0; idx < locations.length; idx++) {
+        const loc = locations[idx];
+        if (!isDict(loc)) {
+            issues.push({
+                code: "SCHEMA_ENTITY_FIELD_MISSING",
+                severity: "error",
+                summary: `locations[${idx}] is not an object.`,
+                repair_hint: "Patch location entry.",
+            });
+            continue;
+        }
+        const locationName = strOf(loc["location_name"]).trim();
+        for (const field of ["location_id", "location_name", "description"]) {
+            if (!strOf(loc[field]).trim()) {
+                issues.push({
+                    code: "SCHEMA_ENTITY_FIELD_MISSING",
+                    severity: "error",
+                    summary: `Location missing ${field}: ${loc["location_id"] || idx}`,
+                    repair_hint: "Patch location metadata.",
+                });
+            }
+        }
+        if (locationName && cleanName(locationName) !== locationName) {
+            issues.push({
+                code: "ASSET_NAME_HAS_STATE_ANNOTATION",
+                severity: "error",
+                summary: `Location name contains state annotation: ${locationName}`,
+                repair_hint: "Keep location_name canonical and move durable visual variants to states[] only when reusable.",
+            });
+        }
+    }
+    const propsArr = asList(script["props"]);
+    for (let idx = 0; idx < propsArr.length; idx++) {
+        const prop = propsArr[idx];
+        if (!isDict(prop)) {
+            issues.push({
+                code: "SCHEMA_ENTITY_FIELD_MISSING",
+                severity: "error",
+                summary: `props[${idx}] is not an object.`,
+                repair_hint: "Patch prop entry.",
+            });
+            continue;
+        }
+        const propName = strOf(prop["prop_name"]).trim();
+        for (const field of ["prop_id", "prop_name", "description"]) {
+            if (!strOf(prop[field]).trim()) {
+                issues.push({
+                    code: "SCHEMA_ENTITY_FIELD_MISSING",
+                    severity: "error",
+                    summary: `Prop missing ${field}: ${prop["prop_id"] || idx}`,
+                    repair_hint: "Patch prop metadata.",
+                });
+            }
+        }
+        if (propName && cleanName(propName) !== propName) {
+            issues.push({
+                code: "ASSET_NAME_HAS_STATE_ANNOTATION",
+                severity: "error",
+                summary: `Prop name contains state annotation: ${propName}`,
+                repair_hint: "Keep prop_name canonical and move durable visual variants to states[] only when reusable.",
+            });
+        }
+    }
+    const stateIdsByAsset = new Map();
+    for (const [collection, idKey] of [["actors", "actor_id"], ["locations", "location_id"], ["props", "prop_id"]]) {
+        const targetKind = { actors: "actor", locations: "location", props: "prop" }[collection];
+        for (const asset of asList(script[collection])) {
+            const assetId = strOf(asset[idKey]);
+            const rawStates = asset["states"];
+            stateIdsByAsset.set(assetId, new Set());
+            const seenStateNames = new Set();
+            // Mirror Python `asset.get("states", []) or []`: absent/null → empty list (no issue)
+            if (rawStates !== undefined && rawStates !== null && !isList(rawStates)) {
+                issues.push({
+                    code: "SCHEMA_STATE_LIST_INVALID",
+                    severity: "error",
+                    summary: `${collection} ${assetId} states must be an array.`,
+                    repair_hint: "Patch states to an array.",
+                });
+                continue;
+            }
+            const states = isList(rawStates) ? rawStates : [];
+            for (const state of states) {
+                if (!isDict(state)) {
+                    issues.push({
+                        code: "SCHEMA_STATE_INVALID",
+                        severity: "error",
+                        summary: `${collection} ${assetId} contains a non-object state.`,
+                        repair_hint: "Patch or remove the invalid state.",
+                    });
+                    continue;
+                }
+                const sid = strOf(state["state_id"]);
+                const sname = strOf(state["state_name"] || state["name"]);
+                if (!sid || !sname) {
+                    issues.push({
+                        code: "SCHEMA_STATE_FIELD_MISSING",
+                        severity: "error",
+                        summary: `${collection} ${assetId} state missing state_id or state_name.`,
+                        repair_hint: "Patch state_id/state_name.",
+                    });
+                }
+                if (sid && stateIdsByAsset.get(assetId).has(sid)) {
+                    issues.push({
+                        code: "DUPLICATE_STATE_ID",
+                        severity: "error",
+                        summary: `Duplicate state_id in ${assetId}: ${sid}`,
+                        repair_hint: "Rename or merge duplicate states.",
+                    });
+                }
+                if (sname && seenStateNames.has(sname)) {
+                    issues.push({
+                        code: "DUPLICATE_STATE_NAME",
+                        severity: "warning",
+                        summary: `Duplicate state_name in ${assetId}: ${sname}`,
+                        repair_hint: "Rename duplicate states if they are different shapes.",
+                    });
+                }
+                const reason = stateRejectionReason(targetKind, sname);
+                if (sname && reason) {
+                    issues.push({
+                        code: "STATE_LABEL_INVALID",
+                        severity: "error",
+                        summary: `${collection} ${assetId} state label invalid: ${sname}`,
+                        repair_hint: "Use one clear state label; do not combine multiple states into one label.",
+                    });
+                }
+                if (sid)
+                    stateIdsByAsset.get(assetId).add(sid);
+                if (sname)
+                    seenStateNames.add(sname);
+            }
+        }
+    }
+    const speakerIds = new Set();
+    const speakersArr = asList(script["speakers"]);
+    for (let idx = 0; idx < speakersArr.length; idx++) {
+        const speaker = speakersArr[idx];
+        if (!isDict(speaker)) {
+            issues.push({
+                code: "SCHEMA_SPEAKER_INVALID",
+                severity: "error",
+                summary: `speakers[${idx}] is not an object.`,
+                repair_hint: "Patch speaker entry.",
+            });
+            continue;
+        }
+        const speakerId = strOf(speaker["speaker_id"]);
+        const sourceKind = strOf(speaker["source_kind"]);
+        const sourceId = speaker["source_id"];
+        if (!speakerId || !strOf(speaker["display_name"]).trim()) {
+            issues.push({
+                code: "SCHEMA_SPEAKER_FIELD_MISSING",
+                severity: "error",
+                summary: `Speaker missing speaker_id or display_name: ${idx}`,
+                repair_hint: "Patch speaker metadata.",
+            });
+        }
+        if (speakerIds.has(speakerId)) {
+            issues.push({
+                code: "DUPLICATE_SPEAKER_ID",
+                severity: "error",
+                summary: `Duplicate speaker_id: ${speakerId}`,
+                repair_hint: "Rename or merge duplicate speakers.",
+            });
+        }
+        if (speakerId)
+            speakerIds.add(speakerId);
+        if (!SPEAKER_SOURCE_KINDS.has(sourceKind)) {
+            issues.push({
+                code: "ENUM_SPEAKER_SOURCE_KIND",
+                severity: "error",
+                summary: `speaker.source_kind invalid: ${sourceKind || "<empty>"}`,
+                repair_hint: "Use actor/location/prop/system/broadcast/group/other.",
+            });
+        }
+        if (sourceKind === "actor" && !actorIds.has(strOf(sourceId))) {
+            issues.push({
+                code: "DANGLING_SPEAKER_SOURCE_REF",
+                severity: "error",
+                summary: `Speaker actor source not found: ${sourceId}`,
+                repair_hint: "Patch source_id or source_kind.",
+            });
+        }
+        if (sourceKind === "location" && !locationIds.has(strOf(sourceId))) {
+            issues.push({
+                code: "DANGLING_SPEAKER_SOURCE_REF",
+                severity: "error",
+                summary: `Speaker location source not found: ${sourceId}`,
+                repair_hint: "Patch source_id or source_kind.",
+            });
+        }
+        if (sourceKind === "prop" && !propIds.has(strOf(sourceId))) {
+            issues.push({
+                code: "DANGLING_SPEAKER_SOURCE_REF",
+                severity: "error",
+                summary: `Speaker prop source not found: ${sourceId}`,
+                repair_hint: "Patch source_id or source_kind.",
+            });
+        }
+    }
+    const planPath = path.join(dd, "episode_plan.json");
+    if (exists(planPath)) {
+        const plan = readJson(planPath);
+        if (plan["boundary_confidence"] === "low") {
+            issues.push({
+                code: "LOW_CONFIDENCE_EPISODE_PLAN",
+                severity: "warning",
+                summary: "Episode plan used a single-episode fallback.",
+                repair_hint: "Inspect the initial script and adjust structure with patch if needed.",
+            });
+        }
+    }
+    const episodes = asList(script["episodes"]);
+    if (episodes.length === 0) {
+        issues.push({ code: "NO_EPISODES", severity: "blocking", summary: "No episodes in script.", repair_hint: "Rerun init or patch episodes." });
+    }
+    let totalScenes = 0;
+    let totalActions = 0;
+    let lastSceneNum = 0;
+    for (const ep of episodes) {
+        const epTitle = strOf(ep["title"]).trim();
+        if (!epTitle || isTechnicalEpisodeTitle(epTitle)) {
+            issues.push({
+                code: "EPISODE_TITLE_INVALID",
+                severity: "warning",
+                episode: ep["episode_id"],
+                summary: `Episode title is missing or technical: ${epTitle || "<empty>"}`,
+                repair_hint: 'Rerun `direct init` to regenerate, or `script patch episode <episode_id> --field title --value "第N集：短标题"`.',
+            });
+        }
+        const scenes = asList(ep["scenes"]);
+        if (scenes.length === 0) {
+            issues.push({
+                code: "EPISODE_WITHOUT_SCENES",
+                severity: "error",
+                episode: ep["episode_id"],
+                summary: "Episode has no scenes.",
+                repair_hint: "Patch at least one scene into the episode.",
+            });
+        }
+        for (const scene of scenes) {
+            totalScenes += 1;
+            const rawSceneId = strOf(scene["scene_id"]);
+            const match = /^scn_(\d+)$/.exec(rawSceneId);
+            if (match) {
+                const sceneNum = parseInt(match[1], 10);
+                if (sceneNum <= lastSceneNum) {
+                    issues.push({
+                        code: "REF_SCENE_ID_NONMONO",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: rawSceneId,
+                        summary: `scene_id must increase globally: ${rawSceneId}`,
+                        repair_hint: "Rerun init or patch scene ids to a global monotonic sequence.",
+                    });
+                }
+                lastSceneNum = Math.max(lastSceneNum, sceneNum);
+            }
+            else {
+                issues.push({
+                    code: "REF_SCENE_ID_INVALID",
+                    severity: "error",
+                    episode: ep["episode_id"],
+                    scene: rawSceneId || null,
+                    summary: "scene_id must use scn_### format.",
+                    repair_hint: "Patch scene_id to scn_###.",
+                });
+            }
+            const ctx = sceneContext(scene);
+            const ctxLocations = asList(ctx["locations"]);
+            if (ctxLocations.length === 0) {
+                issues.push({
+                    code: "SCENE_WITHOUT_LOCATION",
+                    severity: "error",
+                    episode: ep["episode_id"],
+                    scene: scene["scene_id"],
+                    summary: "Scene has no location.",
+                    repair_hint: "Patch scene.locations with a registered location_id.",
+                });
+            }
+            for (const ref of ctxLocations) {
+                const locationId = strOf(ref["location_id"]);
+                const stateId = strOf(ref["state_id"]);
+                if (!locationIds.has(locationId)) {
+                    issues.push({
+                        code: "DANGLING_LOCATION_REF",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        summary: `Location ref not found: ${locationId || "<empty>"}`,
+                        repair_hint: "Patch scene location to an existing location_id.",
+                    });
+                }
+                if (stateId && !(stateIdsByAsset.get(locationId) ?? new Set()).has(stateId)) {
+                    issues.push({
+                        code: "DANGLING_LOCATION_STATE_REF",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        summary: `Location state ref not found: ${stateId}`,
+                        repair_hint: "Patch location state_id or asset states.",
+                    });
+                }
+            }
+            for (const ref of asList(ctx["actors"])) {
+                const actorId = strOf(ref["actor_id"]);
+                const stateId = strOf(ref["state_id"]);
+                if (!actorIds.has(actorId)) {
+                    issues.push({
+                        code: "DANGLING_ACTOR_REF",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        summary: `Actor ref not found: ${actorId || "<empty>"}`,
+                        repair_hint: "Patch scene actor refs to existing actor_id.",
+                    });
+                }
+                if (stateId && !(stateIdsByAsset.get(actorId) ?? new Set()).has(stateId)) {
+                    issues.push({
+                        code: "DANGLING_ACTOR_STATE_REF",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        summary: `Actor state ref not found: ${stateId}`,
+                        repair_hint: "Patch actor state_id or asset states.",
+                    });
+                }
+            }
+            for (const ref of asList(ctx["props"])) {
+                const propId = strOf(ref["prop_id"]);
+                const stateId = strOf(ref["state_id"]);
+                if (!propIds.has(propId)) {
+                    issues.push({
+                        code: "DANGLING_PROP_REF",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        summary: `Prop ref not found: ${propId || "<empty>"}`,
+                        repair_hint: "Patch scene prop refs to existing prop_id.",
+                    });
+                }
+                if (stateId && !(stateIdsByAsset.get(propId) ?? new Set()).has(stateId)) {
+                    issues.push({
+                        code: "DANGLING_PROP_STATE_REF",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        summary: `Prop state ref not found: ${stateId}`,
+                        repair_hint: "Patch prop state_id or asset states.",
+                    });
+                }
+            }
+            const actionsArr = asList(scene["actions"]);
+            if (actionsArr.length === 0) {
+                issues.push({
+                    code: "SCENE_WITHOUT_ACTIONS",
+                    severity: "error",
+                    episode: ep["episode_id"],
+                    scene: scene["scene_id"],
+                    summary: "Scene has no actions.",
+                    repair_hint: "Patch actions from source spans.",
+                });
+            }
+            for (let actionIndex = 0; actionIndex < actionsArr.length; actionIndex++) {
+                const action = actionsArr[actionIndex];
+                totalActions += 1;
+                const kind = strOf(action["type"]).trim();
+                if (!ACTION_TYPE_VALUES.has(kind)) {
+                    issues.push({
+                        code: "ENUM_ACTION_TYPE",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        action_index: actionIndex,
+                        summary: `action.type invalid: ${kind || "<empty>"}`,
+                        repair_hint: "Patch action.type to dialogue, inner_thought, or action.",
+                    });
+                }
+                const content = strOf(action["content"]).trim();
+                const hasOverlapLines = action["delivery"] === "overlap" && isList(action["lines"]) && action["lines"].length > 0;
+                if (!content && !hasOverlapLines) {
+                    issues.push({
+                        code: "EMPTY_ACTION_CONTENT",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        action_index: actionIndex,
+                        summary: "Action content is empty.",
+                        repair_hint: "Patch content from a source span.",
+                    });
+                }
+                if (content && contentHasSpeakerPrefix(content, speakerDisplayNames)) {
+                    issues.push({
+                        code: "DIALOGUE_CONTENT_SPEAKER_PREFIX",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        action_index: actionIndex,
+                        summary: "Dialogue content appears to contain speaker prefixes.",
+                        repair_hint: "Move speaker labels into speaker_id/speakers/lines and keep content as spoken text only.",
+                    });
+                }
+                if (action["type"] === "dialogue") {
+                    const delivery = strOf(action["delivery"] || "single");
+                    if (!DELIVERY_VALUES.has(delivery)) {
+                        issues.push({
+                            code: "ENUM_DIALOGUE_DELIVERY",
+                            severity: "error",
+                            episode: ep["episode_id"],
+                            scene: scene["scene_id"],
+                            action_index: actionIndex,
+                            summary: `dialogue.delivery invalid: ${delivery}`,
+                            repair_hint: "Use single, simultaneous, overlap, or group.",
+                        });
+                    }
+                    if (delivery === "overlap") {
+                        const lines = asList(action["lines"]);
+                        if (lines.length === 0) {
+                            issues.push({
+                                code: "DIALOGUE_OVERLAP_LINES_EMPTY",
+                                severity: "error",
+                                episode: ep["episode_id"],
+                                scene: scene["scene_id"],
+                                action_index: actionIndex,
+                                summary: "Overlapping dialogue has no lines.",
+                                repair_hint: "Add lines with speaker_id and content.",
+                            });
+                        }
+                        for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+                            const line = lines[lineIdx] ?? {};
+                            const sid = strOf(line["speaker_id"]);
+                            const lineContent = strOf(line["content"]).trim();
+                            if (!speakerIds.has(sid)) {
+                                issues.push({
+                                    code: "DANGLING_DIALOGUE_SPEAKER_REF",
+                                    severity: "error",
+                                    episode: ep["episode_id"],
+                                    scene: scene["scene_id"],
+                                    action_index: actionIndex,
+                                    summary: `Overlap line speaker not found: ${sid || "<empty>"}`,
+                                    repair_hint: "Patch speaker_id or add a speaker.",
+                                });
+                            }
+                            if (!lineContent) {
+                                issues.push({
+                                    code: "EMPTY_DIALOGUE_LINE",
+                                    severity: "error",
+                                    episode: ep["episode_id"],
+                                    scene: scene["scene_id"],
+                                    action_index: actionIndex,
+                                    summary: `Overlap line ${lineIdx} content is empty.`,
+                                    repair_hint: "Patch line content.",
+                                });
+                            }
+                            else if (contentHasSpeakerPrefix(lineContent, speakerDisplayNames)) {
+                                issues.push({
+                                    code: "DIALOGUE_CONTENT_SPEAKER_PREFIX",
+                                    severity: "error",
+                                    episode: ep["episode_id"],
+                                    scene: scene["scene_id"],
+                                    action_index: actionIndex,
+                                    summary: `Overlap line ${lineIdx} content contains a speaker prefix.`,
+                                    repair_hint: "Keep each overlap line content as spoken text only.",
+                                });
+                            }
+                        }
+                    }
+                    else if (action["speakers"]) {
+                        const speakersInAction = asList(action["speakers"]);
+                        if (speakersInAction.length === 0) {
+                            issues.push({
+                                code: "DIALOGUE_SPEAKERS_INVALID",
+                                severity: "error",
+                                episode: ep["episode_id"],
+                                scene: scene["scene_id"],
+                                action_index: actionIndex,
+                                summary: "dialogue.speakers must be an array.",
+                                repair_hint: "Patch speakers list.",
+                            });
+                        }
+                        for (const speaker of speakersInAction) {
+                            const sid = strOf(speaker["speaker_id"]);
+                            if (!speakerIds.has(sid)) {
+                                issues.push({
+                                    code: "DANGLING_DIALOGUE_SPEAKER_REF",
+                                    severity: "error",
+                                    episode: ep["episode_id"],
+                                    scene: scene["scene_id"],
+                                    action_index: actionIndex,
+                                    summary: `Dialogue speaker not found: ${sid || "<empty>"}`,
+                                    repair_hint: "Patch speaker_id or add a speaker.",
+                                });
+                            }
+                        }
+                    }
+                    else if (action["speaker_id"]) {
+                        const sid = strOf(action["speaker_id"]);
+                        if (!speakerIds.has(sid)) {
+                            issues.push({
+                                code: "DANGLING_DIALOGUE_SPEAKER_REF",
+                                severity: "error",
+                                episode: ep["episode_id"],
+                                scene: scene["scene_id"],
+                                action_index: actionIndex,
+                                summary: `Dialogue speaker not found: ${sid}`,
+                                repair_hint: "Patch speaker_id or add a speaker.",
+                            });
+                        }
+                    }
+                    else if (!action["actor_id"]) {
+                        issues.push({
+                            code: "DIALOGUE_WITHOUT_SPEAKER",
+                            severity: "error",
+                            episode: ep["episode_id"],
+                            scene: scene["scene_id"],
+                            action_index: actionIndex,
+                            summary: "Dialogue has no speaker.",
+                            repair_hint: "Patch speaker_id, speakers, lines, or legacy actor_id.",
+                        });
+                    }
+                }
+                if (action["type"] === "inner_thought") {
+                    const sid = strOf(action["speaker_id"]);
+                    if (sid && !speakerIds.has(sid)) {
+                        issues.push({
+                            code: "DANGLING_DIALOGUE_SPEAKER_REF",
+                            severity: "error",
+                            episode: ep["episode_id"],
+                            scene: scene["scene_id"],
+                            action_index: actionIndex,
+                            summary: `Inner thought speaker not found: ${sid}`,
+                            repair_hint: "Patch speaker_id or add a speaker.",
+                        });
+                    }
+                    if (!action["actor_id"] && !sid) {
+                        issues.push({
+                            code: "DIALOGUE_WITHOUT_ACTOR",
+                            severity: "error",
+                            episode: ep["episode_id"],
+                            scene: scene["scene_id"],
+                            action_index: actionIndex,
+                            summary: "Inner thought has no actor_id or speaker_id.",
+                            repair_hint: "Patch actor_id, speaker_id, or speaker registry.",
+                        });
+                    }
+                }
+                if (action["actor_id"] && !actorIds.has(strOf(action["actor_id"]))) {
+                    issues.push({
+                        code: "DANGLING_ACTION_ACTOR_REF",
+                        severity: "error",
+                        episode: ep["episode_id"],
+                        scene: scene["scene_id"],
+                        action_index: actionIndex,
+                        summary: `Action actor_id not found: ${action["actor_id"]}`,
+                        repair_hint: "Patch action actor_id to an existing actor.",
+                    });
+                }
+                for (const change of asList(action["state_changes"])) {
+                    const targetKind = strOf(change["target_kind"]);
+                    const targetId = strOf(change["target_id"]);
+                    const fromStateId = strOf(change["from_state_id"]);
+                    const toStateId = strOf(change["to_state_id"]);
+                    const effectiveFrom = strOf(change["effective_from"] || "after_action");
+                    if (!SCRIPT_TARGET_KINDS.has(targetKind)) {
+                        issues.push({
+                            code: "STATE_CHANGE_TARGET_KIND_INVALID",
+                            severity: "error",
+                            episode: ep["episode_id"],
+                            scene: scene["scene_id"],
+                            action_index: actionIndex,
+                            summary: `state_changes target_kind invalid: ${targetKind || "<empty>"}`,
+                            repair_hint: "Use actor, location, or prop.",
+                        });
+                        continue;
+                    }
+                    const validIds = { actor: actorIds, location: locationIds, prop: propIds }[targetKind];
+                    if (!validIds.has(targetId)) {
+                        issues.push({
+                            code: "DANGLING_STATE_CHANGE_TARGET_REF",
+                            severity: "error",
+                            episode: ep["episode_id"],
+                            scene: scene["scene_id"],
+                            action_index: actionIndex,
+                            summary: `State change target not found: ${targetKind}:${targetId}`,
+                            repair_hint: "Patch target_id.",
+                        });
+                    }
+                    for (const [label, sid] of [["from_state_id", fromStateId], ["to_state_id", toStateId]]) {
+                        if (sid && !(stateIdsByAsset.get(targetId) ?? new Set()).has(sid)) {
+                            issues.push({
+                                code: "DANGLING_STATE_CHANGE_STATE_REF",
+                                severity: "error",
+                                episode: ep["episode_id"],
+                                scene: scene["scene_id"],
+                                action_index: actionIndex,
+                                summary: `State change ${label} not found: ${sid}`,
+                                repair_hint: "Patch state change or asset states.",
+                            });
+                        }
+                    }
+                    if (!EFFECTIVE_FROM_VALUES.has(effectiveFrom)) {
+                        issues.push({
+                            code: "ENUM_STATE_CHANGE_EFFECTIVE_FROM",
+                            severity: "error",
+                            episode: ep["episode_id"],
+                            scene: scene["scene_id"],
+                            action_index: actionIndex,
+                            summary: `effective_from invalid: ${effectiveFrom}`,
+                            repair_hint: "Use before_action or after_action.",
+                        });
+                    }
+                }
+                const transition = action["transition_prompt"];
+                if (transition !== null && transition !== undefined) {
+                    if (!isDict(transition)) {
+                        issues.push({
+                            code: "TRANSITION_PROMPT_INVALID",
+                            severity: "error",
+                            episode: ep["episode_id"],
+                            scene: scene["scene_id"],
+                            action_index: actionIndex,
+                            summary: "transition_prompt must be an object.",
+                            repair_hint: "Patch or clear transition_prompt.",
+                        });
+                    }
+                    else {
+                        const targetKind = strOf(transition["target_kind"]);
+                        const targetId = strOf(transition["target_id"]);
+                        if (!SCRIPT_TARGET_KINDS.has(targetKind)) {
+                            issues.push({
+                                code: "TRANSITION_PROMPT_TARGET_KIND_INVALID",
+                                severity: "error",
+                                episode: ep["episode_id"],
+                                scene: scene["scene_id"],
+                                action_index: actionIndex,
+                                summary: `transition target_kind invalid: ${targetKind || "<empty>"}`,
+                                repair_hint: "Use actor, location, or prop.",
+                            });
+                        }
+                        else {
+                            const validIds = { actor: actorIds, location: locationIds, prop: propIds }[targetKind];
+                            if (!validIds.has(targetId)) {
+                                issues.push({
+                                    code: "DANGLING_TRANSITION_TARGET_REF",
+                                    severity: "error",
+                                    episode: ep["episode_id"],
+                                    scene: scene["scene_id"],
+                                    action_index: actionIndex,
+                                    summary: `Transition target not found: ${targetKind}:${targetId}`,
+                                    repair_hint: "Patch transition target.",
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const hasBlocking = issues.some((it) => it["severity"] === "blocking");
+    const hasErrors = issues.some((it) => it["severity"] === "error");
+    const validation = {
+        passed: !hasBlocking && !hasErrors,
+        has_blocking: hasBlocking,
+        issues,
+        stats: {
+            episodes: episodes.length,
+            scenes: totalScenes,
+            actions: totalActions,
+            actors: asList(script["actors"]).length,
+            locations: asList(script["locations"]).length,
+            props: asList(script["props"]).length,
+            speakers: asList(script["speakers"]).length,
+        },
+        script_path: finalScriptPath,
+        validated_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
+    };
+    writeJson(path.join(dd, "validation.json"), validation);
+    return validation;
+}
+// ---------------------------------------------------------------------------
+// Resolve/lookup helpers
+// ---------------------------------------------------------------------------
+function resolveAsset(items, idKey, nameKey, raw) {
+    for (const item of items) {
+        if (raw === item[idKey] || raw === item[nameKey])
+            return item;
+    }
+    return null;
+}
+const ASSET_KEY_MAP = {
+    actor: ["actors", "actor_id", "actor_name"],
+    location: ["locations", "location_id", "location_name"],
+    prop: ["props", "prop_id", "prop_name"],
+};
+export function assetKeys(assetType) {
+    const entry = ASSET_KEY_MAP[assetType];
+    if (!entry) {
+        throw new CliError("PATCH BLOCKED: Asset type invalid", "Asset type invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["asset_type: actor, location, or prop"],
+            received: [`asset_type: ${assetType}`],
+            nextSteps: ["Fix the patch operation and rerun patch."],
+        });
+    }
+    return entry;
+}
+function resolvePatchAsset(script, op, assetType = null) {
+    const kind = strOf(assetType || op["asset_type"]);
+    const [key, idKey, nameKey] = assetKeys(kind);
+    const raw = op[idKey] ?? op["id"] ?? op["name"] ?? op[nameKey];
+    const asset = resolveAsset(asList(script[key]), idKey, nameKey, strOf(raw));
+    if (!asset) {
+        throw new CliError("PATCH BLOCKED: Asset not found", "Asset not found.", {
+            exitCode: EXIT_USAGE,
+            required: [`existing ${idKey} or ${nameKey}`],
+            received: [JSON.stringify(op)],
+            nextSteps: ["Inspect assets and fix the patch."],
+        });
+    }
+    return [asset, idKey, nameKey];
+}
+function nextStateId(script) {
+    let maxSeen = 0;
+    for (const key of ["actors", "locations", "props"]) {
+        for (const asset of asList(script[key])) {
+            for (const state of asList(asset["states"])) {
+                const m = /^st_(\d+)$/.exec(strOf(state["state_id"]));
+                if (m)
+                    maxSeen = Math.max(maxSeen, parseInt(m[1], 10));
+            }
+        }
+    }
+    return fmtId("st", maxSeen + 1);
+}
+function normalizeStates(script, rawStates, assetKind = "") {
+    if (!isList(rawStates)) {
+        throw new CliError("PATCH BLOCKED: States invalid", "States invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["states: array of state names or {state_id,state_name} objects"],
+            received: [typeof rawStates],
+            nextSteps: ["Fix the patch operation and rerun patch."],
+        });
+    }
+    let maxSeen = 0;
+    for (const key of ["actors", "locations", "props"]) {
+        for (const asset of asList(script[key])) {
+            for (const state of asList(asset["states"])) {
+                const m = /^st_(\d+)$/.exec(strOf(state["state_id"]));
+                if (m)
+                    maxSeen = Math.max(maxSeen, parseInt(m[1], 10));
+            }
+        }
+    }
+    const states = [];
+    const seenNames = new Set();
+    for (const raw of rawStates) {
+        let name = "";
+        let sid = "";
+        if (typeof raw === "string") {
+            name = raw.trim();
+            maxSeen += 1;
+            sid = fmtId("st", maxSeen);
+        }
+        else if (isDict(raw)) {
+            name = strOf(raw["state_name"] || raw["name"]).trim();
+            sid = strOf(raw["state_id"] || raw["id"]).trim();
+            if (!sid) {
+                maxSeen += 1;
+                sid = fmtId("st", maxSeen);
+            }
+        }
+        else
+            continue;
+        if (!name || seenNames.has(name))
+            continue;
+        if (assetKind === "actor") {
+            const reason = stateLabelError(name);
+            if (reason) {
+                throw new CliError("PATCH BLOCKED: State label invalid", "State label invalid.", {
+                    exitCode: EXIT_USAGE,
+                    required: ["one clear state label"],
+                    received: [name],
+                    nextSteps: ["Do not combine multiple states into one label."],
+                    errorCode: "STATE_LABEL_INVALID",
+                });
+            }
+        }
+        seenNames.add(name);
+        states.push({ state_id: sid, state_name: name });
+    }
+    return states;
+}
+export function ensureRefId(script, assetType, rawId, opts = {}) {
+    const allowNone = opts.allowNone ?? false;
+    if (rawId === null && allowNone)
+        return null;
+    const value = strOf(rawId).trim();
+    if (!value && allowNone)
+        return null;
+    const [key, idKey] = assetKeys(assetType);
+    const valid = new Set();
+    for (const item of asList(script[key]))
+        valid.add(strOf(item[idKey]));
+    if (!valid.has(value)) {
+        throw new CliError("PATCH BLOCKED: Reference target not found", "Reference target not found.", {
+            exitCode: EXIT_USAGE,
+            required: [`existing ${idKey}`],
+            received: [`${idKey}: ${value || "<empty>"}`],
+            nextSteps: ["Inspect assets and fix the patch."],
+        });
+    }
+    return value;
+}
+function idKeyForKind(kind) {
+    const map = { actor: "actor_id", location: "location_id", prop: "prop_id" };
+    return map[kind];
+}
+function pluralForKind(kind) {
+    const map = { actor: "actors", location: "locations", prop: "props" };
+    return map[kind];
+}
+export function parseAssetTarget(raw) {
+    const value = strOf(raw).trim();
+    if (!value.includes(":")) {
+        throw new CliError("SCRIPT OP BLOCKED: Target invalid", "Target invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["target: actor:<id>, location:<id>, or prop:<id>"],
+            received: [value || "<empty>"],
+            nextSteps: ["Use a concrete asset target."],
+            errorCode: "TARGET_INVALID",
+        });
+    }
+    const idx = value.indexOf(":");
+    const kind = value.slice(0, idx).trim();
+    const targetId = value.slice(idx + 1).trim();
+    if (!SCRIPT_TARGET_KINDS.has(kind) || !targetId) {
+        throw new CliError("SCRIPT OP BLOCKED: Target invalid", "Target invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["target: actor:<id>, location:<id>, or prop:<id>"],
+            received: [value],
+            nextSteps: ["Use actor, location, or prop with a non-empty id."],
+            errorCode: "TARGET_INVALID",
+        });
+    }
+    return [kind, targetId];
+}
+export function parseStateTarget(raw) {
+    const value = strOf(raw).trim();
+    if (!value.includes("/")) {
+        throw new CliError("SCRIPT OP BLOCKED: State target invalid", "State target invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["state target: actor:<id>/<state_id>"],
+            received: [value || "<empty>"],
+            nextSteps: ["Use a concrete state target."],
+            errorCode: "STATE_TARGET_INVALID",
+        });
+    }
+    const lastSlash = value.lastIndexOf("/");
+    const assetRaw = value.slice(0, lastSlash);
+    const stateId = value.slice(lastSlash + 1).trim();
+    const [kind, targetId] = parseAssetTarget(assetRaw);
+    if (!stateId) {
+        throw new CliError("SCRIPT OP BLOCKED: State target invalid", "State target invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["state_id after '/'"],
+            received: [value],
+            nextSteps: ["Use a non-empty state_id."],
+            errorCode: "STATE_TARGET_INVALID",
+        });
+    }
+    return [kind, targetId, stateId];
+}
+export function parseSceneRef(raw) {
+    const value = strOf(raw).trim();
+    if (!value.includes("/")) {
+        throw new CliError("SCRIPT OP BLOCKED: Scene ref invalid", "Scene ref invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["scene ref: ep_001/scn_001"],
+            received: [value || "<empty>"],
+            nextSteps: ["Use ep_id/scn_id."],
+            errorCode: "SCENE_REF_INVALID",
+        });
+    }
+    const idx = value.indexOf("/");
+    return [value.slice(0, idx).trim(), value.slice(idx + 1).trim()];
+}
+export function parseActionRef(raw) {
+    const value = strOf(raw).trim();
+    if (!value.includes("#")) {
+        throw new CliError("SCRIPT OP BLOCKED: Action ref invalid", "Action ref invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["action ref: ep_001/scn_001#4"],
+            received: [value || "<empty>"],
+            nextSteps: ["Use ep_id/scn_id#action_index."],
+            errorCode: "ACTION_REF_INVALID",
+        });
+    }
+    const lastHash = value.lastIndexOf("#");
+    const sceneRaw = value.slice(0, lastHash);
+    const indexRaw = value.slice(lastHash + 1);
+    const [epId, sceneId] = parseSceneRef(sceneRaw);
+    const actionIndex = parseInt(indexRaw, 10);
+    if (Number.isNaN(actionIndex)) {
+        throw new CliError("SCRIPT OP BLOCKED: Action index invalid", "Action index invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["integer action index after '#'"],
+            received: [value],
+            nextSteps: ["Use a zero-based action index."],
+            errorCode: "ACTION_INDEX_INVALID",
+        });
+    }
+    return [epId, sceneId, actionIndex];
+}
+function resolveAssetByTarget(script, kind, targetId) {
+    const [key, idKey] = assetKeys(kind);
+    for (const item of asList(script[key])) {
+        if (strOf(item[idKey]) === targetId)
+            return item;
+    }
+    throw new CliError("SCRIPT OP BLOCKED: Asset not found", "Asset not found.", {
+        exitCode: EXIT_USAGE,
+        required: [`existing ${kind} id`],
+        received: [`${kind}:${targetId}`],
+        nextSteps: ["Inspect assets and fix the target."],
+        errorCode: "ASSET_NOT_FOUND",
+    });
+}
+function resolveState(script, kind, targetId, stateId) {
+    const asset = resolveAssetByTarget(script, kind, targetId);
+    for (const state of asList(asset["states"])) {
+        if (strOf(state["state_id"]) === stateId)
+            return state;
+    }
+    throw new CliError("SCRIPT OP BLOCKED: State not found", "State not found.", {
+        exitCode: EXIT_USAGE,
+        required: ["existing state_id on the target asset"],
+        received: [`${kind}:${targetId}/${stateId}`],
+        nextSteps: ["Inspect states and fix the target."],
+        errorCode: "STATE_NOT_FOUND",
+    });
+}
+function validateStateForTarget(script, kind, targetId, stateId) {
+    const value = strOf(stateId).trim();
+    if (!value)
+        return null;
+    resolveState(script, kind, targetId, value);
+    return value;
+}
+function nextSpeakerId(script, sourceKind, sourceId = null) {
+    const existing = new Set();
+    for (const item of asList(script["speakers"]))
+        existing.add(strOf(item["speaker_id"]));
+    if (sourceKind === "actor" && sourceId) {
+        const candidate = `spk_${sourceId}`;
+        if (!existing.has(candidate))
+            return candidate;
+    }
+    let maxSeen = 0;
+    const prefix = `spk_${sourceKind}_`;
+    for (const id of existing) {
+        if (id.startsWith(prefix)) {
+            const m = new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\d+)$`).exec(id);
+            if (m)
+                maxSeen = Math.max(maxSeen, parseInt(m[1], 10));
+        }
+    }
+    return `${prefix}${String(maxSeen + 1).padStart(3, "0")}`;
+}
+function speakerSourceActorId(script, speakerId) {
+    for (const speaker of asList(script["speakers"])) {
+        if (strOf(speaker["speaker_id"]) === speakerId && speaker["source_kind"] === "actor") {
+            return strOf(speaker["source_id"]).trim() || null;
+        }
+    }
+    return null;
+}
+function ensureSpeakerId(script, speakerId) {
+    const value = strOf(speakerId).trim();
+    const valid = new Set();
+    for (const item of asList(script["speakers"]))
+        valid.add(strOf(item["speaker_id"]));
+    if (!valid.has(value)) {
+        throw new CliError("SCRIPT OP BLOCKED: Speaker not found", "Speaker not found.", {
+            exitCode: EXIT_USAGE,
+            required: ["existing speaker_id"],
+            received: [value || "<empty>"],
+            nextSteps: ["Add a speaker first, or fix the dialogue patch."],
+            errorCode: "SPEAKER_NOT_FOUND",
+        });
+    }
+    return value;
+}
+function contextRefsForKind(context, kind) {
+    return asList(context[pluralForKind(kind)]);
+}
+function findContextRef(context, kind, targetId) {
+    const idKey = idKeyForKind(kind);
+    for (const ref of contextRefsForKind(context, kind)) {
+        if (strOf(ref[idKey]) === targetId)
+            return ref;
+    }
+    return null;
+}
+function setContextState(script, epId, sceneId, kind, targetId, stateId) {
+    ensureRefId(script, kind, targetId);
+    const normalizedState = validateStateForTarget(script, kind, targetId, stateId);
+    const scene = findScene(script, epId, sceneId);
+    const ctx = sceneContext(scene);
+    const refs = [...contextRefsForKind(ctx, kind)];
+    const idKey = idKeyForKind(kind);
+    const existing = refs.find((ref) => strOf(ref[idKey]) === targetId);
+    if (existing) {
+        existing["state_id"] = normalizedState;
+    }
+    else {
+        refs.push({ [idKey]: targetId, state_id: normalizedState });
+    }
+    ctx[pluralForKind(kind)] = refs;
+    setSceneContext(scene, ctx);
+}
+function inferStateBeforeAction(script, epId, sceneId, actionIndex, kind, targetId) {
+    const scene = findScene(script, epId, sceneId);
+    const ctx = sceneContext(scene);
+    let current = null;
+    const ref = findContextRef(ctx, kind, targetId);
+    if (ref)
+        current = strOf(ref["state_id"]).trim() || null;
+    const actions = asList(scene["actions"]);
+    for (let i = 0; i < actionIndex && i < actions.length; i++) {
+        for (const change of asList(actions[i]["state_changes"])) {
+            if (strOf(change["target_kind"]) === kind && strOf(change["target_id"]) === targetId) {
+                const toState = strOf(change["to_state_id"]).trim();
+                if (toState)
+                    current = toState;
+            }
+        }
+    }
+    return current;
+}
+function stateRefSummary(kind, targetId, stateId, location, role) {
+    return { target: `${kind}:${targetId}/${stateId}`, location, role };
+}
+export function collectStateRefs(script, kind, targetId, stateId) {
+    const refs = [];
+    const idKey = idKeyForKind(kind);
+    for (const ep of asList(script["episodes"])) {
+        const epId = strOf(ep["episode_id"]);
+        for (const scene of asList(ep["scenes"])) {
+            const sceneId = strOf(scene["scene_id"]);
+            const ctx = sceneContext(scene);
+            const refsList = contextRefsForKind(ctx, kind);
+            for (let idx = 0; idx < refsList.length; idx++) {
+                const ref = refsList[idx];
+                if (strOf(ref[idKey]) === targetId && strOf(ref["state_id"]) === stateId) {
+                    refs.push(stateRefSummary(kind, targetId, stateId, `${epId}/${sceneId}.context.${pluralForKind(kind)}[${idx}]`, "scene_initial_state"));
+                }
+            }
+            const actions = asList(scene["actions"]);
+            for (let actionIdx = 0; actionIdx < actions.length; actionIdx++) {
+                const changes = asList(actions[actionIdx]["state_changes"]);
+                for (let changeIdx = 0; changeIdx < changes.length; changeIdx++) {
+                    const change = changes[changeIdx];
+                    if (strOf(change["target_kind"]) !== kind || strOf(change["target_id"]) !== targetId)
+                        continue;
+                    if (strOf(change["from_state_id"]) === stateId) {
+                        refs.push(stateRefSummary(kind, targetId, stateId, `${epId}/${sceneId}#${actionIdx}.state_changes[${changeIdx}].from_state_id`, "state_change_from"));
+                    }
+                    if (strOf(change["to_state_id"]) === stateId) {
+                        refs.push(stateRefSummary(kind, targetId, stateId, `${epId}/${sceneId}#${actionIdx}.state_changes[${changeIdx}].to_state_id`, "state_change_to"));
+                    }
+                }
+            }
+        }
+    }
+    return refs;
+}
+function nextSceneId(script) {
+    let maxSeen = 0;
+    for (const ep of asList(script["episodes"])) {
+        for (const scene of asList(ep["scenes"])) {
+            const m = /^scn_(\d+)$/.exec(strOf(scene["scene_id"]));
+            if (m)
+                maxSeen = Math.max(maxSeen, parseInt(m[1], 10));
+        }
+    }
+    return fmtId("scn", maxSeen + 1);
+}
+function sceneIdExists(script, sceneId) {
+    for (const ep of asList(script["episodes"])) {
+        for (const scene of asList(ep["scenes"])) {
+            if (scene["scene_id"] === sceneId)
+                return true;
+        }
+    }
+    return false;
+}
+function renumberSceneIds(script) {
+    let counter = 0;
+    for (const ep of asList(script["episodes"])) {
+        for (const scene of asList(ep["scenes"])) {
+            counter += 1;
+            scene["scene_id"] = fmtId("scn", counter);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// apply_patch_operations
+// ---------------------------------------------------------------------------
+function opErr(title, message, opts = {}) {
+    return new CliError(title, message, {
+        exitCode: opts.exitCode ?? EXIT_USAGE,
+        required: opts.required,
+        received: opts.received,
+        nextSteps: opts.nextSteps,
+        op: opts.op,
+        errorCode: opts.errorCode,
+        hint: opts.hint,
+    });
+}
+export function applyPatchOperations(script, sourceText, operations) {
+    const applied = [];
+    for (const op of operations) {
+        const kind = strOf(op["op"]);
+        if (kind === "state.add") {
+            const [targetKind, targetId] = parseAssetTarget(op["target"]);
+            const asset = resolveAssetByTarget(script, targetKind, targetId);
+            const name = strOf(op["name"] || op["state_name"]).trim();
+            const description = strOf(op["description"]).trim();
+            const stateId = strOf(op["state_id"]).trim() || nextStateId(script);
+            if (!name) {
+                throw opErr("SCRIPT OP BLOCKED: State name empty", "State name empty.", {
+                    required: ["name"], received: [JSON.stringify(op)],
+                    nextSteps: ["Provide a state name."], op: kind, errorCode: "STATE_NAME_EMPTY",
+                });
+            }
+            const reason = stateRejectionReason(targetKind, name);
+            if (reason) {
+                throw opErr("SCRIPT OP BLOCKED: State label invalid", "State label invalid.", {
+                    required: ["one clear state label"], received: [name],
+                    nextSteps: ["Do not combine multiple states into one label."], op: kind, errorCode: "STATE_LABEL_INVALID",
+                });
+            }
+            if (!isList(asset["states"]))
+                asset["states"] = [];
+            const existingStates = asset["states"];
+            if (existingStates.some((s) => strOf(s["state_id"]) === stateId)) {
+                throw opErr("SCRIPT OP BLOCKED: State id exists", "State id exists.", { required: ["unused state_id"], received: [stateId], nextSteps: ["Use another state_id or edit the existing state."], op: kind, errorCode: "STATE_ID_EXISTS" });
+            }
+            if (existingStates.some((s) => strOf(s["state_name"] || s["name"]) === name)) {
+                throw opErr("SCRIPT OP BLOCKED: State name exists", "State name exists.", { required: ["unused state name"], received: [name], nextSteps: ["Rename the existing state or choose another name."], op: kind, errorCode: "STATE_NAME_EXISTS" });
+            }
+            const state = { state_id: stateId, state_name: name };
+            if (description)
+                state["description"] = description;
+            existingStates.push(state);
+            op["state_id"] = stateId;
+            applied.push(kind);
+        }
+        else if (kind === "state.rename") {
+            const [targetKind, targetId, stateId] = parseStateTarget(op["target"]);
+            const state = resolveState(script, targetKind, targetId, stateId);
+            const name = strOf(op["name"] || op["state_name"]).trim();
+            if (!name) {
+                throw opErr("SCRIPT OP BLOCKED: State name empty", "State name empty.", { required: ["name"], received: [JSON.stringify(op)], nextSteps: ["Provide a state name."], op: kind, errorCode: "STATE_NAME_EMPTY" });
+            }
+            const reason = stateRejectionReason(targetKind, name);
+            if (reason) {
+                throw opErr("SCRIPT OP BLOCKED: State label invalid", "State label invalid.", { required: ["one clear state label"], received: [name], nextSteps: ["Do not combine multiple states into one label."], op: kind, errorCode: "STATE_LABEL_INVALID" });
+            }
+            state["state_name"] = name;
+            applied.push(kind);
+        }
+        else if (kind === "state.describe") {
+            const [targetKind, targetId, stateId] = parseStateTarget(op["target"]);
+            const state = resolveState(script, targetKind, targetId, stateId);
+            state["description"] = strOf(op["description"]).trim();
+            applied.push(kind);
+        }
+        else if (kind === "state.delete") {
+            const [targetKind, targetId, stateId] = parseStateTarget(op["target"]);
+            const asset = resolveAssetByTarget(script, targetKind, targetId);
+            resolveState(script, targetKind, targetId, stateId);
+            const strategy = strOf(op["strategy"]).trim();
+            const replacement = strOf(op["replacement"]).trim();
+            if (strategy !== "replace" && strategy !== "remove") {
+                throw opErr("SCRIPT OP BLOCKED: Delete strategy invalid", "Delete strategy invalid.", { required: ["strategy: replace or remove"], received: [strategy || "<empty>"], nextSteps: ["Choose replace with --replacement, or remove."], op: kind, errorCode: "DELETE_STRATEGY_INVALID" });
+            }
+            if (strategy === "replace") {
+                if (!replacement) {
+                    throw opErr("SCRIPT OP BLOCKED: Replacement missing", "Replacement missing.", { required: ["replacement state_id"], received: ["<empty>"], nextSteps: ["Pass --replacement with an existing state_id."], op: kind, errorCode: "REPLACEMENT_MISSING" });
+                }
+                validateStateForTarget(script, targetKind, targetId, replacement);
+            }
+            const contextField = pluralForKind(targetKind);
+            const idKey = idKeyForKind(targetKind);
+            for (const ep of asList(script["episodes"])) {
+                for (const scene of asList(ep["scenes"])) {
+                    const ctx = sceneContext(scene);
+                    for (const ref of contextRefsForKind(ctx, targetKind)) {
+                        if (strOf(ref[idKey]) === targetId && strOf(ref["state_id"]) === stateId) {
+                            ref["state_id"] = strategy === "replace" ? replacement : null;
+                        }
+                    }
+                    ctx[contextField] = contextRefsForKind(ctx, targetKind);
+                    setSceneContext(scene, ctx);
+                    for (const action of asList(scene["actions"])) {
+                        const nextChanges = [];
+                        for (const change of asList(action["state_changes"])) {
+                            if (strOf(change["target_kind"]) === targetKind && strOf(change["target_id"]) === targetId) {
+                                let touched = false;
+                                for (const stateField of ["from_state_id", "to_state_id"]) {
+                                    if (strOf(change[stateField]) === stateId) {
+                                        touched = true;
+                                        if (strategy === "replace")
+                                            change[stateField] = replacement;
+                                    }
+                                }
+                                if (strategy === "remove" && touched)
+                                    continue;
+                            }
+                            nextChanges.push(change);
+                        }
+                        if (action["state_changes"] !== undefined && action["state_changes"] !== null) {
+                            if (nextChanges.length > 0)
+                                action["state_changes"] = nextChanges;
+                            else
+                                delete action["state_changes"];
+                        }
+                    }
+                }
+            }
+            asset["states"] = asList(asset["states"]).filter((s) => strOf(s["state_id"]) !== stateId);
+            applied.push(kind);
+        }
+        else if (kind === "context.set") {
+            const [epId, sceneId] = parseSceneRef(op["at"]);
+            const [targetKind, targetId] = parseAssetTarget(op["target"]);
+            setContextState(script, epId, sceneId, targetKind, targetId, strOf(op["state"] || op["state_id"]).trim());
+            applied.push(kind);
+        }
+        else if (kind === "context.clear") {
+            const [epId, sceneId] = parseSceneRef(op["at"]);
+            const [targetKind, targetId] = parseAssetTarget(op["target"]);
+            setContextState(script, epId, sceneId, targetKind, targetId, null);
+            applied.push(kind);
+        }
+        else if (kind === "action.state.change") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const [targetKind, targetId] = parseAssetTarget(op["target"]);
+            ensureRefId(script, targetKind, targetId);
+            const toState = validateStateForTarget(script, targetKind, targetId, strOf(op["to"] || op["to_state_id"]).trim());
+            if (!toState) {
+                throw opErr("SCRIPT OP BLOCKED: Target state missing", "Target state missing.", { required: ["to state_id"], received: [JSON.stringify(op)], nextSteps: ["Pass --to with an existing state_id."], op: kind, errorCode: "TO_STATE_MISSING" });
+            }
+            const fromStateExplicit = strOf(op["from"] || op["from_state_id"]).trim();
+            const fromState = fromStateExplicit || inferStateBeforeAction(script, epId, sceneId, actionIndex, targetKind, targetId);
+            if (!fromState) {
+                throw opErr("SCRIPT OP BLOCKED: From state ambiguous", "Unable to infer current state before this action.", { required: ["scene initial state or --from"], received: [`${op["at"]} ${op["target"]}`], nextSteps: ["Set scene context first, or pass --from explicitly."], op: kind, errorCode: "FROM_STATE_AMBIGUOUS", hint: "先设置场景初始状态，或修复前序状态变化。" });
+            }
+            validateStateForTarget(script, targetKind, targetId, fromState);
+            const effective = strOf(op["effective"] || op["effective_from"] || "after").trim();
+            const effectiveFrom = effective === "after" ? "after_action" : effective === "before" ? "before_action" : effective;
+            if (!EFFECTIVE_FROM_VALUES.has(effectiveFrom)) {
+                throw opErr("SCRIPT OP BLOCKED: Effective invalid", "Effective invalid.", { required: ["effective: after or before"], received: [effective], nextSteps: ["Use after or before."], op: kind, errorCode: "EFFECTIVE_INVALID" });
+            }
+            const action = findAction(script, epId, sceneId, actionIndex);
+            const changes = asList(action["state_changes"]).filter((c) => !(strOf(c["target_kind"]) === targetKind && strOf(c["target_id"]) === targetId));
+            changes.push({
+                target_kind: targetKind,
+                target_id: targetId,
+                from_state_id: fromState,
+                to_state_id: toState,
+                effective_from: effectiveFrom,
+            });
+            action["state_changes"] = changes;
+            applied.push(kind);
+        }
+        else if (kind === "action.state.remove") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const [targetKind, targetId] = parseAssetTarget(op["target"]);
+            const action = findAction(script, epId, sceneId, actionIndex);
+            const changes = asList(action["state_changes"]).filter((c) => !(strOf(c["target_kind"]) === targetKind && strOf(c["target_id"]) === targetId));
+            if (changes.length > 0)
+                action["state_changes"] = changes;
+            else
+                delete action["state_changes"];
+            applied.push(kind);
+        }
+        else if (kind === "action.transition.set") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const [targetKind, targetId] = parseAssetTarget(op["target"]);
+            ensureRefId(script, targetKind, targetId);
+            const process = strOf(op["process"]).trim();
+            const contrast = strOf(op["contrast"]).trim();
+            if (!process || !contrast) {
+                throw opErr("SCRIPT OP BLOCKED: Transition prompt incomplete", "Transition prompt incomplete.", { required: ["process and contrast"], received: [JSON.stringify(op)], nextSteps: ["Provide both process and contrast."], op: kind, errorCode: "TRANSITION_PROMPT_INCOMPLETE" });
+            }
+            const action = findAction(script, epId, sceneId, actionIndex);
+            action["transition_prompt"] = { target_kind: targetKind, target_id: targetId, process, contrast };
+            applied.push(kind);
+        }
+        else if (kind === "action.transition.clear") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const [targetKind, targetId] = parseAssetTarget(op["target"]);
+            const action = findAction(script, epId, sceneId, actionIndex);
+            const transition = action["transition_prompt"];
+            if (isDict(transition) && strOf(transition["target_kind"]) === targetKind && strOf(transition["target_id"]) === targetId) {
+                delete action["transition_prompt"];
+            }
+            applied.push(kind);
+        }
+        else if (kind === "speaker.add") {
+            const sourceKind = strOf(op["kind"] || op["source_kind"]).trim();
+            if (!SPEAKER_SOURCE_KINDS.has(sourceKind)) {
+                throw opErr("SCRIPT OP BLOCKED: Speaker kind invalid", "Speaker kind invalid.", { required: ["kind: actor/location/prop/system/broadcast/group/other"], received: [sourceKind || "<empty>"], nextSteps: ["Use a supported speaker kind."], op: kind, errorCode: "SPEAKER_KIND_INVALID" });
+            }
+            const name = strOf(op["name"] || op["display_name"]).trim();
+            if (!name) {
+                throw opErr("SCRIPT OP BLOCKED: Speaker name empty", "Speaker name empty.", { required: ["name"], received: [JSON.stringify(op)], nextSteps: ["Provide display name."], op: kind, errorCode: "SPEAKER_NAME_EMPTY" });
+            }
+            const sourceId = strOf(op["source_id"]).trim() || null;
+            if (SCRIPT_TARGET_KINDS.has(sourceKind)) {
+                if (!sourceId) {
+                    throw opErr("SCRIPT OP BLOCKED: Speaker source missing", "Speaker source missing.", { required: ["source_id for actor/location/prop speakers"], received: ["<empty>"], nextSteps: ["Pass --source-id."], op: kind, errorCode: "SPEAKER_SOURCE_MISSING" });
+                }
+                ensureRefId(script, sourceKind, sourceId);
+            }
+            const speakerId = strOf(op["speaker_id"]).trim() || nextSpeakerId(script, sourceKind, sourceId);
+            if (asList(script["speakers"]).some((s) => strOf(s["speaker_id"]) === speakerId)) {
+                throw opErr("SCRIPT OP BLOCKED: Speaker id exists", "Speaker id exists.", { required: ["unused speaker_id"], received: [speakerId], nextSteps: ["Use another speaker_id."], op: kind, errorCode: "SPEAKER_ID_EXISTS" });
+            }
+            if (!isList(script["speakers"]))
+                script["speakers"] = [];
+            script["speakers"].push({
+                speaker_id: speakerId,
+                display_name: name,
+                source_kind: sourceKind,
+                source_id: sourceId,
+                voice_desc: strOf(op["voice_desc"]).trim(),
+            });
+            applied.push(kind);
+        }
+        else if (kind === "dialogue.speakers") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const delivery = strOf(op["delivery"] || "simultaneous").trim();
+            if (delivery !== "single" && delivery !== "simultaneous" && delivery !== "group") {
+                throw opErr("SCRIPT OP BLOCKED: Delivery invalid", "Delivery invalid.", { required: ["delivery: single, simultaneous, or group"], received: [delivery], nextSteps: ["Use a supported delivery."], op: kind, errorCode: "DELIVERY_INVALID" });
+            }
+            let rawSpeakers = op["speakers"] ?? op["speaker"] ?? [];
+            if (typeof rawSpeakers === "string")
+                rawSpeakers = [rawSpeakers];
+            if (!isList(rawSpeakers) || rawSpeakers.length === 0) {
+                throw opErr("SCRIPT OP BLOCKED: Speakers empty", "Speakers empty.", { required: ["speaker list"], received: [JSON.stringify(op)], nextSteps: ["Pass at least one --speaker."], op: kind, errorCode: "SPEAKERS_EMPTY" });
+            }
+            const speakerIds = rawSpeakers.map((sid) => ensureSpeakerId(script, strOf(sid)));
+            const action = findAction(script, epId, sceneId, actionIndex);
+            action["type"] = "dialogue";
+            action["delivery"] = delivery;
+            action["speakers"] = speakerIds.map((sid) => ({ speaker_id: sid }));
+            delete action["lines"];
+            const actorId = speakerIds.length === 1 ? speakerSourceActorId(script, speakerIds[0]) : null;
+            if (actorId) {
+                action["actor_id"] = actorId;
+                action["speaker_id"] = speakerIds[0];
+            }
+            else {
+                delete action["actor_id"];
+                delete action["speaker_id"];
+            }
+            applied.push(kind);
+        }
+        else if (kind === "dialogue.overlap") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            let rawLines = op["lines"] ?? op["line"] ?? [];
+            if (typeof rawLines === "string")
+                rawLines = [rawLines];
+            if (!isList(rawLines) || rawLines.length === 0) {
+                throw opErr("SCRIPT OP BLOCKED: Lines empty", "Lines empty.", { required: ["line list"], received: [JSON.stringify(op)], nextSteps: ["Pass at least one --line speaker_id:content."], op: kind, errorCode: "LINES_EMPTY" });
+            }
+            const lines = [];
+            for (const line of rawLines) {
+                let speakerId;
+                let content;
+                if (isDict(line)) {
+                    speakerId = ensureSpeakerId(script, strOf(line["speaker_id"]));
+                    content = strOf(line["content"]).trim();
+                }
+                else {
+                    const rawLine = strOf(line);
+                    if (!rawLine.includes(":") && !rawLine.includes("：")) {
+                        throw opErr("SCRIPT OP BLOCKED: Line invalid", "Line invalid.", { required: ["speaker_id:content"], received: [rawLine], nextSteps: ["Use --line spk_xxx:对白."], op: kind, errorCode: "LINE_INVALID" });
+                    }
+                    const m = /^([^:：]+)[:：](.*)$/.exec(rawLine);
+                    if (!m) {
+                        throw opErr("SCRIPT OP BLOCKED: Line invalid", "Line invalid.", { required: ["speaker_id:content"], received: [rawLine], nextSteps: ["Use --line spk_xxx:对白."], op: kind, errorCode: "LINE_INVALID" });
+                    }
+                    speakerId = ensureSpeakerId(script, m[1]);
+                    content = m[2].trim();
+                }
+                if (!content) {
+                    throw opErr("SCRIPT OP BLOCKED: Line content empty", "Line content empty.", { required: ["non-empty line content"], received: [JSON.stringify(line)], nextSteps: ["Provide line content."], op: kind, errorCode: "LINE_CONTENT_EMPTY" });
+                }
+                lines.push({ speaker_id: speakerId, content });
+            }
+            const action = findAction(script, epId, sceneId, actionIndex);
+            action["type"] = "dialogue";
+            action["delivery"] = "overlap";
+            action["lines"] = lines;
+            action["content"] = lines.map((l) => l["content"]).join(" / ");
+            delete action["speakers"];
+            delete action["actor_id"];
+            delete action["speaker_id"];
+            applied.push(kind);
+        }
+        else if (kind === "set_worldview") {
+            const worldview = strOf(op["worldview"]).trim();
+            if (!WORLDVIEW_VALUES.includes(worldview)) {
+                throw opErr("PATCH BLOCKED: Worldview invalid", "Worldview invalid.", { required: [`worldview: one of ${WORLDVIEW_VALUES.join(", ")}`], received: [worldview || "<empty>"], nextSteps: ["Use a supported worldview enum."] });
+            }
+            script["worldview"] = worldview;
+            if ("worldview_raw" in op)
+                script["worldview_raw"] = strOf(op["worldview_raw"]).trim();
+            applied.push(kind);
+        }
+        else if (kind === "set_actor_role_type") {
+            const [asset] = resolvePatchAsset(script, op, "actor");
+            const roleType = strOf(op["role_type"]).trim();
+            if (!ROLE_TYPE_VALUES.includes(roleType)) {
+                throw opErr("PATCH BLOCKED: Role type invalid", "Role type invalid.", { required: ["role_type: 主角 or 配角"], received: [roleType || "<empty>"], nextSteps: ["Use a supported actor role_type."] });
+            }
+            asset["role_type"] = roleType;
+            applied.push(kind);
+        }
+        else if (kind === "set_asset_description") {
+            const [asset] = resolvePatchAsset(script, op);
+            const description = strOf(op["description"]).trim();
+            if (!description) {
+                throw opErr("PATCH BLOCKED: Description empty", "Description empty.", { required: ["description: non-empty string"], received: [JSON.stringify(op)], nextSteps: ["Provide a concise grounded description."] });
+            }
+            asset["description"] = description;
+            applied.push(kind);
+        }
+        else if (kind === "set_action_type") {
+            const actionIndex = op["action_index"];
+            if (typeof actionIndex !== "number" || !Number.isInteger(actionIndex)) {
+                throw opErr("PATCH BLOCKED: Action index invalid", "Action index invalid.", { required: ["action_index: integer"], received: [JSON.stringify(op)], nextSteps: ["Inspect episodes and fix the patch."] });
+            }
+            const actionType = strOf(op["action_type"] || op["type"]).trim();
+            if (!ACTION_TYPE_VALUES.has(actionType)) {
+                throw opErr("PATCH BLOCKED: Action type invalid", "Action type invalid.", { required: ["action_type: dialogue, inner_thought, or action"], received: [actionType || "<empty>"], nextSteps: ["Use a supported action type."] });
+            }
+            const action = findAction(script, strOf(op["episode_id"]), strOf(op["scene_id"]), actionIndex);
+            action["type"] = actionType;
+            applied.push(kind);
+        }
+        else if (kind === "rename_actor" || kind === "rename_location" || kind === "rename_prop") {
+            const map = {
+                rename_actor: ["actors", "actor_id", "actor_name"],
+                rename_location: ["locations", "location_id", "location_name"],
+                rename_prop: ["props", "prop_id", "prop_name"],
+            };
+            const [key, idKey, nameKey] = map[kind];
+            const raw = op[idKey] ?? op["id"] ?? op["name"];
+            const newName = op["new_name"] ?? op[nameKey];
+            const asset = resolveAsset(asList(script[key]), idKey, nameKey, strOf(raw));
+            if (!asset || !newName) {
+                throw opErr("PATCH BLOCKED: Rename target invalid", "Rename target invalid.", { required: [`${idKey} or name, and new_name`], received: [JSON.stringify(op)], nextSteps: ["Fix the patch operation and rerun patch."] });
+            }
+            asset[nameKey] = String(newName);
+            applied.push(kind);
+        }
+        else if (kind === "set_asset_aliases") {
+            const [asset] = resolvePatchAsset(script, op);
+            const aliases = op["aliases"];
+            if (!isList(aliases) || aliases.some((it) => typeof it !== "string")) {
+                throw opErr("PATCH BLOCKED: Aliases invalid", "Aliases invalid.", { required: ["aliases: array of strings"], received: [JSON.stringify(op)], nextSteps: ["Fix the patch operation and rerun patch."] });
+            }
+            const seen = new Set();
+            const cleanedAliases = [];
+            for (const item of aliases) {
+                const alias = item.trim();
+                if (alias && !seen.has(alias)) {
+                    seen.add(alias);
+                    cleanedAliases.push(alias);
+                }
+            }
+            asset["aliases"] = cleanedAliases;
+            applied.push(kind);
+        }
+        else if (kind === "set_asset_states") {
+            const [asset] = resolvePatchAsset(script, op);
+            const assetKind = strOf(op["asset_type"]).trim();
+            asset["states"] = normalizeStates(script, op["states"], assetKind);
+            applied.push(kind);
+        }
+        else if (kind === "merge_actor" || kind === "merge_location" || kind === "merge_prop") {
+            const map = {
+                merge_actor: ["actors", "actor_id", "actors"],
+                merge_location: ["locations", "location_id", "locations"],
+                merge_prop: ["props", "prop_id", "props"],
+            };
+            const [key, idKey, refKey] = map[kind];
+            const sourceId = op["source_id"];
+            const targetId = op["target_id"];
+            if (!sourceId || !targetId) {
+                throw opErr("PATCH BLOCKED: Merge target invalid", "Merge target invalid.", { required: ["source_id and target_id"], received: [JSON.stringify(op)], nextSteps: ["Fix the patch operation and rerun patch."] });
+            }
+            script[key] = asList(script[key]).filter((it) => it[idKey] !== sourceId);
+            for (const ep of asList(script["episodes"])) {
+                for (const scene of asList(ep["scenes"])) {
+                    for (const ref of asList(scene[refKey])) {
+                        if (ref[idKey] === sourceId)
+                            ref[idKey] = targetId;
+                    }
+                    for (const action of asList(scene["actions"])) {
+                        if (idKey === "actor_id" && action["actor_id"] === sourceId)
+                            action["actor_id"] = targetId;
+                    }
+                }
+            }
+            applied.push(kind);
+        }
+        else if (kind === "set_scene_actor_ref" || kind === "set_scene_location_ref" || kind === "set_scene_prop_ref") {
+            const epId = strOf(op["episode_id"]);
+            const sceneId = strOf(op["scene_id"]);
+            const scene = findScene(script, epId, sceneId);
+            const ctx = sceneContext(scene);
+            if (kind === "set_scene_actor_ref") {
+                const actorId = ensureRefId(script, "actor", op["actor_id"]);
+                const stateId = strOf(op["state_id"]).trim() || null;
+                if (!isList(ctx["actors"]))
+                    ctx["actors"] = [];
+                const refs = ctx["actors"];
+                const existing = refs.find((r) => r["actor_id"] === actorId);
+                if (existing)
+                    existing["state_id"] = stateId;
+                else
+                    refs.push({ actor_id: actorId, state_id: stateId });
+            }
+            else if (kind === "set_scene_location_ref") {
+                const locationId = ensureRefId(script, "location", op["location_id"]);
+                const stateId = strOf(op["state_id"]).trim() || null;
+                ctx["locations"] = [{ location_id: locationId, state_id: stateId }];
+            }
+            else {
+                const propId = ensureRefId(script, "prop", op["prop_id"]);
+                const stateId = strOf(op["state_id"]).trim() || null;
+                if (!isList(ctx["props"]))
+                    ctx["props"] = [];
+                const refs = ctx["props"];
+                const existing = refs.find((r) => r["prop_id"] === propId);
+                if (existing)
+                    existing["state_id"] = stateId;
+                else
+                    refs.push({ prop_id: propId, state_id: stateId });
+            }
+            setSceneContext(scene, ctx);
+            applied.push(kind);
+        }
+        else if (kind === "set_action_actor") {
+            const actorId = ensureRefId(script, "actor", op["actor_id"], { allowNone: Boolean(op["allow_null"]) });
+            const actionIndex = op["action_index"];
+            if (typeof actionIndex !== "number" || !Number.isInteger(actionIndex)) {
+                throw opErr("PATCH BLOCKED: Action index invalid", "Action index invalid.", { required: ["action_index: integer"], received: [JSON.stringify(op)], nextSteps: ["Inspect episodes and fix the patch."] });
+            }
+            const action = findAction(script, strOf(op["episode_id"]), strOf(op["scene_id"]), actionIndex);
+            if (actorId === null)
+                delete action["actor_id"];
+            else
+                action["actor_id"] = actorId;
+            applied.push(kind);
+        }
+        else if (kind === "set_action_content_from_span") {
+            const epId = op["episode_id"];
+            const sceneId = op["scene_id"];
+            const actionIndex = op["action_index"];
+            const start = op["start"];
+            const end = op["end"];
+            if (typeof actionIndex !== "number" || !Number.isInteger(actionIndex) ||
+                typeof start !== "number" || !Number.isInteger(start) ||
+                typeof end !== "number" || !Number.isInteger(end) ||
+                start < 0 || end <= start || end > sourceText.length) {
+                throw opErr("PATCH BLOCKED: Source span invalid", "Source span invalid.", { required: ["episode_id, scene_id, action_index, start, end"], received: [JSON.stringify(op)], nextSteps: ["Use a valid source.txt character span."] });
+            }
+            const action = findAction(script, strOf(epId), strOf(sceneId), actionIndex);
+            action["content"] = sourceText.slice(start, end);
+            applied.push(kind);
+        }
+        else if (kind === "merge_scenes") {
+            const epId = strOf(op["episode_id"]);
+            const keepId = strOf(op["keep_scene_id"]);
+            const removeId = strOf(op["remove_scene_id"]);
+            const ep = asList(script["episodes"]).find((e) => e["episode_id"] === epId);
+            if (!ep) {
+                throw opErr("PATCH BLOCKED: Episode not found", "Episode not found.", { required: ["existing episode_id"], received: [epId], nextSteps: ["Inspect episodes and fix the patch."] });
+            }
+            const scenes = asList(ep["scenes"]);
+            const keep = scenes.find((s) => s["scene_id"] === keepId);
+            const remove = scenes.find((s) => s["scene_id"] === removeId);
+            if (!keep || !remove) {
+                throw opErr("PATCH BLOCKED: Scene not found", "Scene not found.", { required: ["existing keep_scene_id and remove_scene_id"], received: [JSON.stringify(op)], nextSteps: ["Inspect episodes and fix the patch."] });
+            }
+            keep["actions"].push(...asList(remove["actions"]));
+            const keepCtx = sceneContext(keep);
+            const removeCtx = sceneContext(remove);
+            for (const [field, idKey] of [["actors", "actor_id"], ["locations", "location_id"], ["props", "prop_id"]]) {
+                const existingIds = new Set();
+                for (const ref of asList(keepCtx[field]))
+                    existingIds.add(ref[idKey]);
+                for (const ref of asList(removeCtx[field])) {
+                    if (!existingIds.has(ref[idKey])) {
+                        if (!isList(keepCtx[field]))
+                            keepCtx[field] = [];
+                        keepCtx[field].push(ref);
+                    }
+                }
+            }
+            setSceneContext(keep, keepCtx);
+            ep["scenes"] = scenes.filter((s) => s !== remove);
+            applied.push(kind);
+        }
+        else if (kind === "split_scene") {
+            const epId = strOf(op["episode_id"]);
+            const sceneId = strOf(op["scene_id"]);
+            const splitAt = op["action_index"];
+            if (typeof splitAt !== "number" || !Number.isInteger(splitAt)) {
+                throw opErr("PATCH BLOCKED: Split index invalid", "Split index invalid.", { required: ["action_index: integer between existing actions"], received: [JSON.stringify(op)], nextSteps: ["Inspect episode actions and fix the patch."] });
+            }
+            const ep = findEpisode(script, epId);
+            const scenes = asList(ep["scenes"]);
+            const index = scenes.findIndex((s) => s["scene_id"] === sceneId);
+            if (index < 0) {
+                throw opErr("PATCH BLOCKED: Scene not found", "Scene not found.", { required: ["existing scene_id"], received: [sceneId], nextSteps: ["Inspect episodes and fix the patch."] });
+            }
+            const scene = scenes[index];
+            const actions = asList(scene["actions"]);
+            if (splitAt <= 0 || splitAt >= actions.length) {
+                throw opErr("PATCH BLOCKED: Split index invalid", "Split index invalid.", { required: ["0 < action_index < action count"], received: [`action_index: ${splitAt}, actions: ${actions.length}`], nextSteps: ["Choose an action boundary inside the scene."] });
+            }
+            const newSceneId = strOf(op["new_scene_id"]) || nextSceneId(script);
+            if (sceneIdExists(script, newSceneId)) {
+                throw opErr("PATCH BLOCKED: New scene id exists", "New scene id exists.", { required: ["unused new_scene_id"], received: [newSceneId], nextSteps: ["Choose an unused scene id or omit new_scene_id."] });
+            }
+            const ctx = sceneContext(scene);
+            const newScene = {
+                scene_id: newSceneId,
+                environment: { ...(isDict(scene["environment"]) ? scene["environment"] : {}) },
+                context: ctx,
+                locations: [...asList(ctx["locations"])],
+                actors: [...asList(ctx["actors"])],
+                props: [...asList(ctx["props"])],
+                actions: actions.slice(splitAt),
+            };
+            scene["actions"] = actions.slice(0, splitAt);
+            scenes.splice(index + 1, 0, newScene);
+            applied.push(kind);
+        }
+        else {
+            throw opErr("PATCH BLOCKED: Unsupported operation", "Unsupported patch operation.", {
+                required: [
+                    "supported op: set_worldview, set_actor_role_type, set_asset_description, set_action_type, rename_*, merge_*, set_asset_aliases, set_asset_states, set_scene_*_ref, set_action_actor, merge_scenes, split_scene, set_action_content_from_span",
+                ],
+                received: [kind],
+                nextSteps: ["Use a supported patch operation."],
+            });
+        }
+    }
+    renumberSceneIds(script);
+    return applied;
+}
+//# sourceMappingURL=script-core.js.map