@lingjingai/scriptctl 0.4.0 → 0.6.0

package/dist/domain/script-core.js

@@ -1236,8 +1236,18 @@ function setContextState(script, epId, sceneId, kind, targetId, stateId) {
     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);
+    // location is single-valued per scene by direct-init invariant; the legacy
+    // set_scene_location_ref op replaced the whole locations[] array to preserve
+    // that. Mirror it here: for location kind, context.set REPLACES (one entry
+    // total). actor/prop stay upsert because multi-actor / multi-prop per scene
+    // is intentional.
+    if (kind === "location") {
+        ctx[pluralForKind(kind)] = [{ [idKey]: targetId, state_id: normalizedState }];
+        setSceneContext(scene, ctx);
+        return;
+    }
+    const refs = [...contextRefsForKind(ctx, kind)];
     const existing = refs.find((ref) => strOf(ref[idKey]) === targetId);
     if (existing) {
         existing["state_id"] = normalizedState;
@@ -1304,6 +1314,167 @@ export function collectStateRefs(script, kind, targetId, stateId) {
     }
     return refs;
 }
+// Try each format in order. The order matters: action (has `#`) is checked
+// before scene (just `/`), and asset+state (has `:`) is checked before scene.
+// Episode and speaker are bare ids (no separators) distinguished by prefix.
+export function parseAnyAddress(raw) {
+    const value = strOf(raw).trim();
+    if (!value) {
+        throw new CliError("ADDRESS BLOCKED: Address empty", "Address empty.", {
+            exitCode: EXIT_USAGE,
+            required: ["one of the supported address formats"],
+            received: ["<empty>"],
+            nextSteps: ["Pass an address like ep_001/scn_001#3, ep_001/scn_001, actor:act_001, actor:act_001/st_001, ep_001, or spk_001."],
+            errorCode: "ADDRESS_EMPTY",
+        });
+    }
+    if (value.includes("#")) {
+        const [episodeId, sceneId, actionIndex] = parseActionRef(value);
+        return { kind: "action", episodeId, sceneId, actionIndex };
+    }
+    if (value.includes(":")) {
+        if (value.slice(value.indexOf(":") + 1).includes("/")) {
+            const [assetKind, assetId, stateId] = parseStateTarget(value);
+            return { kind: "state", assetKind, assetId, stateId };
+        }
+        const [assetKind, assetId] = parseAssetTarget(value);
+        return { kind: "asset", assetKind, assetId };
+    }
+    if (value.includes("/")) {
+        const [episodeId, sceneId] = parseSceneRef(value);
+        return { kind: "scene", episodeId, sceneId };
+    }
+    if (/^ep_/.test(value)) {
+        return { kind: "episode", episodeId: value };
+    }
+    if (/^spk_/.test(value)) {
+        return { kind: "speaker", speakerId: value };
+    }
+    throw new CliError("ADDRESS BLOCKED: Address invalid", "Address invalid.", {
+        exitCode: EXIT_USAGE,
+        required: [
+            "address: ep_NNN/scn_NNN#idx (action) | ep_NNN/scn_NNN (scene) | actor|location|prop:id (asset) | actor|location|prop:id/state_id (state) | ep_NNN (episode) | spk_XXX (speaker)",
+        ],
+        received: [value],
+        nextSteps: ["Use a recognized address format."],
+        errorCode: "ADDRESS_INVALID",
+    });
+}
+// Reverse lookup for asset / speaker references. Parallel to collectStateRefs
+// but tracks where an actor/location/prop/speaker is mentioned rather than
+// where a specific state is mentioned. Returns one `{target, location, role}`
+// entry per reference site. Walks the same edges the validator does
+// (script-core.ts validateScript) so coverage is complete:
+//   - scene.context.{actors|locations|props}[]
+//   - action.actor_id (actor only)
+//   - action.speaker_id + action.speakers[] + action.lines[].speaker_id (speaker only)
+//   - action.state_changes[].target_{kind,id}
+//   - action.transition_prompt.target_{kind,id}
+//   - script.speakers[].source_{kind,id} (for actor/location/prop reverse)
+export function collectAssetRefs(script, kind, targetId) {
+    const refs = [];
+    const isSpeaker = kind === "speaker";
+    const target = isSpeaker ? `speaker:${targetId}` : `${kind}:${targetId}`;
+    const idKey = isSpeaker ? null : 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"]);
+            if (!isSpeaker) {
+                const ctx = sceneContext(scene);
+                const refsList = contextRefsForKind(ctx, kind);
+                for (let i = 0; i < refsList.length; i++) {
+                    if (strOf(refsList[i][idKey]) === targetId) {
+                        refs.push({
+                            target,
+                            location: `${epId}/${sceneId}.context.${pluralForKind(kind)}[${i}]`,
+                            role: `scene_${pluralForKind(kind)}`,
+                        });
+                    }
+                }
+            }
+            const actions = asList(scene["actions"]);
+            for (let actionIdx = 0; actionIdx < actions.length; actionIdx++) {
+                const action = actions[actionIdx];
+                if (kind === "actor" && strOf(action["actor_id"]) === targetId) {
+                    refs.push({
+                        target,
+                        location: `${epId}/${sceneId}#${actionIdx}.actor_id`,
+                        role: "action_actor",
+                    });
+                }
+                if (isSpeaker) {
+                    if (strOf(action["speaker_id"]) === targetId) {
+                        refs.push({
+                            target,
+                            location: `${epId}/${sceneId}#${actionIdx}.speaker_id`,
+                            role: "action_speaker",
+                        });
+                    }
+                    const speakers = asList(action["speakers"]);
+                    for (let i = 0; i < speakers.length; i++) {
+                        if (strOf(speakers[i]["speaker_id"]) === targetId) {
+                            refs.push({
+                                target,
+                                location: `${epId}/${sceneId}#${actionIdx}.speakers[${i}]`,
+                                role: "dialogue_speaker",
+                            });
+                        }
+                    }
+                    const lines = asList(action["lines"]);
+                    for (let i = 0; i < lines.length; i++) {
+                        if (strOf(lines[i]["speaker_id"]) === targetId) {
+                            refs.push({
+                                target,
+                                location: `${epId}/${sceneId}#${actionIdx}.lines[${i}].speaker_id`,
+                                role: "overlap_line_speaker",
+                            });
+                        }
+                    }
+                }
+                if (!isSpeaker) {
+                    const changes = asList(action["state_changes"]);
+                    for (let i = 0; i < changes.length; i++) {
+                        const change = changes[i];
+                        if (strOf(change["target_kind"]) === kind && strOf(change["target_id"]) === targetId) {
+                            refs.push({
+                                target,
+                                location: `${epId}/${sceneId}#${actionIdx}.state_changes[${i}]`,
+                                role: "state_change_target",
+                            });
+                        }
+                    }
+                    const transition = action["transition_prompt"];
+                    if (isDict(transition) && strOf(transition["target_kind"]) === kind && strOf(transition["target_id"]) === targetId) {
+                        refs.push({
+                            target,
+                            location: `${epId}/${sceneId}#${actionIdx}.transition_prompt`,
+                            role: "transition_target",
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Speaker registrations pointing at this asset (actor/location/prop only).
+    // A speaker.source_id ties an actor/location/prop to a speaker entity; the
+    // speaker entry itself counts as a reference, so deleting / merging the
+    // asset must surface it.
+    if (!isSpeaker) {
+        const speakers = asList(script["speakers"]);
+        for (let i = 0; i < speakers.length; i++) {
+            const s = speakers[i];
+            if (strOf(s["source_kind"]) === kind && strOf(s["source_id"]) === targetId) {
+                refs.push({
+                    target,
+                    location: `speakers[${i}]`,
+                    role: "speaker_source",
+                });
+            }
+        }
+    }
+    return refs;
+}
 function nextSceneId(script) {
     let maxSeen = 0;
     for (const ep of asList(script["episodes"])) {
@@ -1344,9 +1515,53 @@ function opErr(title, message, opts = {}) {
         nextSteps: opts.nextSteps,
         op: opts.op,
         errorCode: opts.errorCode,
-        hint: opts.hint,
     });
 }
+export const PATCH_OP_SCHEMA = {
+    // meta
+    "meta.worldview.set": { required: ["worldview"], optional: ["worldview_raw"], description: "Set the script.worldview enum." },
+    // state
+    "state.add": { required: ["target", "name"], optional: ["description", "state_id"], description: "Add a state to an asset's states[]." },
+    "state.rename": { required: ["target", "name"], optional: [], description: "Rename an asset state." },
+    "state.describe": { required: ["target", "description"], optional: [], description: "Set a state's description." },
+    "state.delete": { required: ["target", "strategy"], optional: ["replacement"], description: "Delete a state. strategy: replace|remove." },
+    // asset
+    "asset.rename": { required: ["target", "name"], optional: [], description: "Rename an asset (actor / location / prop)." },
+    "asset.describe": { required: ["target", "description"], optional: [], description: "Set asset description." },
+    "asset.alias.set": { required: ["target", "aliases"], optional: [], description: "Bulk replace aliases[]." },
+    "asset.alias.add": { required: ["target", "alias"], optional: [], description: "Append alias(es)." },
+    "asset.alias.remove": { required: ["target", "alias"], optional: [], description: "Remove alias(es)." },
+    "asset.states.set": { required: ["target", "states"], optional: ["asset_type"], description: "Bulk replace states[]." },
+    "asset.role.set": { required: ["target", "role_type"], optional: [], description: "Set actor role_type (主角|配角)." },
+    "asset.merge": { required: ["from", "into"], optional: [], description: "Merge from asset into another; from disappears." },
+    "asset.delete": { required: ["target"], optional: ["strategy", "replacement"], description: "Delete an asset. strategy: replace|remove (required if refs exist)." },
+    // action
+    "action.type.set": { required: ["at", "type"], optional: [], description: "Set action.type (dialogue|action|inner_thought)." },
+    "action.actor.set": { required: ["at"], optional: ["actor_id"], description: "Set/clear action.actor_id." },
+    "action.content.replace": { required: ["at", "from"], optional: ["to", "all"], description: "Literal substring replace in action.content." },
+    "action.state.change": { required: ["at", "target", "to"], optional: ["from", "effective"], description: "Add/update a state_change on an action." },
+    "action.state.remove": { required: ["at", "target"], optional: [], description: "Remove a state_change from an action." },
+    "action.transition.set": { required: ["at", "target", "process", "contrast"], optional: [], description: "Set transition_prompt." },
+    "action.transition.clear": { required: ["at", "target"], optional: [], description: "Clear transition_prompt." },
+    "action.delete": { required: ["at"], optional: [], description: "Remove an action; later indices shift." },
+    "action.insert": { required: ["at", "type"], optional: ["content", "at_index", "before", "after", "actor_id", "speaker_id"], description: "Insert an action into a scene." },
+    "action.move": { required: ["at", "to"], optional: [], description: "Move an action (within or across scenes)." },
+    // scene
+    "scene.split": { required: ["at", "at_index"], optional: ["new_scene_id"], description: "Split a scene at an action boundary." },
+    "scene.merge": { required: ["from", "into"], optional: [], description: "Merge two scenes within the same episode." },
+    "scene.delete": { required: ["at"], optional: ["force"], description: "Delete a scene; empty by default, force=true for non-empty." },
+    "scene.move": { required: ["at", "to"], optional: ["at_index"], description: "Move a scene to another episode." },
+    "scene.insert": { required: ["at", "location"], optional: ["time", "space", "at_index", "before", "after", "scene_id"], description: "Insert a new empty scene." },
+    // context
+    "context.set": { required: ["at", "target"], optional: ["state", "state_id"], description: "Upsert (actor/prop) or replace (location) scene context ref + state." },
+    "context.clear": { required: ["at", "target"], optional: [], description: "Keep ref, clear state_id." },
+    "context.ref.remove": { required: ["at", "target"], optional: [], description: "Remove the ref entirely from scene context." },
+    // dialogue / speaker
+    "dialogue.speakers": { required: ["at", "speakers"], optional: ["delivery"], description: "Set dialogue speakers; delivery: single|simultaneous|group." },
+    "dialogue.overlap": { required: ["at", "lines"], optional: [], description: "Set overlap dialogue lines[]." },
+    "speaker.add": { required: ["kind", "name"], optional: ["source_id", "voice_desc", "speaker_id"], description: "Register a new speaker." },
+    "speaker.delete": { required: ["target"], optional: ["strategy", "replacement"], description: "Delete a speaker. strategy: replace|remove (required if refs exist)." },
+};
 export function applyPatchOperations(script, sourceText, operations) {
     const applied = [];
     for (const op of operations) {
@@ -1485,7 +1700,7 @@ export function applyPatchOperations(script, sourceText, operations) {
             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: "先设置场景初始状态，或修复前序状态变化。" });
+                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" });
             }
             validateStateForTarget(script, targetKind, targetId, fromState);
             const effective = strOf(op["effective"] || op["effective_from"] || "after").trim();
@@ -1539,6 +1754,72 @@ export function applyPatchOperations(script, sourceText, operations) {
             }
             applied.push(kind);
         }
+        else if (kind === "action.content.replace") {
+            // Literal substring replace on action.content. Designed for "find this
+            // phrase and edit it" — the script-stage equivalent of
+            // set_action_content_from_span, but without needing source.txt (the DB-
+            // backed script doesn't ship source). Refuses ambiguous matches by
+            // default so an off-by-one edit can't silently rewrite the wrong copy.
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const from = strOf(op["from"]);
+            const to = strOf(op["to"]);
+            const all = Boolean(op["all"]);
+            if (!from) {
+                throw opErr("SCRIPT OP BLOCKED: From text empty", "From text empty.", {
+                    required: ["from: non-empty string"],
+                    received: [JSON.stringify(op)],
+                    nextSteps: ["Pass --from with the literal substring to replace."],
+                    op: kind,
+                    errorCode: "FROM_TEXT_EMPTY",
+                });
+            }
+            const action = findAction(script, epId, sceneId, actionIndex);
+            if (strOf(action["type"]) === "dialogue" && strOf(action["delivery"]) === "overlap") {
+                throw opErr("SCRIPT OP BLOCKED: Overlap dialogue not supported", "action.content.replace cannot edit overlap dialogue lines.", {
+                    required: ["non-overlap action"],
+                    received: [`${op["at"]} delivery=overlap`],
+                    nextSteps: ["Use `script dialogue overlap` to rewrite the lines."],
+                    op: kind,
+                    errorCode: "OVERLAP_DIALOGUE_UNSUPPORTED",
+                });
+            }
+            const current = strOf(action["content"]);
+            let count = 0;
+            let cursor = 0;
+            while (true) {
+                const i = current.indexOf(from, cursor);
+                if (i < 0)
+                    break;
+                count += 1;
+                cursor = i + from.length;
+            }
+            if (count === 0) {
+                throw opErr("SCRIPT OP BLOCKED: From text not found", "From text not found in action content.", {
+                    required: ["from substring present in action.content"],
+                    received: [`${op["at"]} from=${JSON.stringify(from)}`],
+                    nextSteps: ["Inspect the action with `script inspect --target action --grep` and adjust --from."],
+                    op: kind,
+                    errorCode: "FROM_TEXT_NOT_FOUND",
+                });
+            }
+            if (count > 1 && !all) {
+                throw opErr("SCRIPT OP BLOCKED: From text ambiguous", `From text matches ${count} times in this action.`, {
+                    required: ["unique substring, or pass all=true to replace every occurrence"],
+                    received: [`${op["at"]} matches=${count}`],
+                    nextSteps: ["Use a longer/more specific --from, or pass --all."],
+                    op: kind,
+                    errorCode: "FROM_TEXT_AMBIGUOUS",
+                });
+            }
+            if (all) {
+                action["content"] = current.split(from).join(to);
+            }
+            else {
+                const i = current.indexOf(from);
+                action["content"] = current.slice(0, i) + to + current.slice(i + from.length);
+            }
+            applied.push(kind);
+        }
         else if (kind === "speaker.add") {
             const sourceKind = strOf(op["kind"] || op["source_kind"]).trim();
             if (!SPEAKER_SOURCE_KINDS.has(sourceKind)) {
@@ -1642,234 +1923,626 @@ export function applyPatchOperations(script, sourceText, operations) {
             delete action["speaker_id"];
             applied.push(kind);
         }
-        else if (kind === "set_worldview") {
-            const worldview = strOf(op["worldview"]).trim();
+        else if (kind === "meta.worldview.set") {
+            // 0.6.0 dot-style equivalent of the legacy `set_worldview` op.
+            const worldview = strOf(op["worldview"] ?? op["value"]).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."] });
+                throw opErr("SCRIPT OP BLOCKED: Worldview invalid", "Worldview invalid.", {
+                    required: [`worldview: one of ${WORLDVIEW_VALUES.join(", ")}`],
+                    received: [worldview || "<empty>"],
+                    nextSteps: ["Use a supported worldview enum."],
+                    op: kind,
+                    errorCode: "WORLDVIEW_INVALID",
+                });
             }
             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();
+        else if (kind === "asset.role.set") {
+            const [assetKind, assetId] = parseAssetTarget(op["target"]);
+            if (assetKind !== "actor") {
+                throw opErr("SCRIPT OP BLOCKED: Role only on actors", "Role applies to actor only.", {
+                    required: ["actor:<id>"],
+                    received: [strOf(op["target"])],
+                    nextSteps: ["Use an actor target."],
+                    op: kind,
+                    errorCode: "ROLE_TARGET_INVALID",
+                });
+            }
+            const asset = resolveAssetByTarget(script, "actor", assetId);
+            const roleType = strOf(op["role_type"] ?? op["role"]).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."] });
+                throw opErr("SCRIPT OP BLOCKED: Role type invalid", "Role type invalid.", {
+                    required: ["role_type: 主角 or 配角"],
+                    received: [roleType || "<empty>"],
+                    nextSteps: ["Use a supported actor role_type."],
+                    op: kind,
+                    errorCode: "ROLE_TYPE_INVALID",
+                });
             }
             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."] });
+        else if (kind === "asset.rename") {
+            const [assetKind, assetId] = parseAssetTarget(op["target"]);
+            const asset = resolveAssetByTarget(script, assetKind, assetId);
+            const newName = strOf(op["name"] ?? op["new_name"]).trim();
+            if (!newName) {
+                throw opErr("SCRIPT OP BLOCKED: Name empty", "Name empty.", {
+                    required: ["name"],
+                    received: [JSON.stringify(op)],
+                    nextSteps: ["Provide a non-empty name."],
+                    op: kind,
+                    errorCode: "NAME_EMPTY",
+                });
             }
-            asset["description"] = description;
+            const [, , nameKey] = assetKeys(assetKind);
+            asset[nameKey] = newName;
             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."] });
+        else if (kind === "asset.describe") {
+            const [assetKind, assetId] = parseAssetTarget(op["target"]);
+            const asset = resolveAssetByTarget(script, assetKind, assetId);
+            const description = strOf(op["description"]).trim();
+            if (!description) {
+                throw opErr("SCRIPT OP BLOCKED: Description empty", "Description empty.", {
+                    required: ["description"],
+                    received: [JSON.stringify(op)],
+                    nextSteps: ["Provide a concise grounded description."],
+                    op: kind,
+                    errorCode: "DESCRIPTION_EMPTY",
+                });
             }
-            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);
+            asset["description"] = description;
             applied.push(kind);
         }
-        else if (kind === "set_asset_aliases") {
-            const [asset] = resolvePatchAsset(script, op);
+        else if (kind === "asset.alias.set") {
+            // Bulk replace. Rare; primarily for migration tools.
+            const [assetKind, assetId] = parseAssetTarget(op["target"]);
+            const asset = resolveAssetByTarget(script, assetKind, assetId);
             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."] });
+                throw opErr("SCRIPT OP BLOCKED: Aliases invalid", "Aliases invalid.", {
+                    required: ["aliases: array of strings"],
+                    received: [JSON.stringify(op)],
+                    nextSteps: ["Pass a string array."],
+                    op: kind,
+                    errorCode: "ALIASES_INVALID",
+                });
             }
             const seen = new Set();
-            const cleanedAliases = [];
+            const cleaned = [];
             for (const item of aliases) {
-                const alias = item.trim();
-                if (alias && !seen.has(alias)) {
+                const trimmed = item.trim();
+                if (trimmed && !seen.has(trimmed)) {
+                    seen.add(trimmed);
+                    cleaned.push(trimmed);
+                }
+            }
+            asset["aliases"] = cleaned;
+            applied.push(kind);
+        }
+        else if (kind === "asset.alias.add") {
+            const [assetKind, assetId] = parseAssetTarget(op["target"]);
+            const asset = resolveAssetByTarget(script, assetKind, assetId);
+            const rawAdd = op["alias"] ?? op["aliases"];
+            const toAdd = isList(rawAdd)
+                ? rawAdd.map((v) => strOf(v).trim()).filter((v) => v)
+                : strOf(rawAdd).trim() ? [strOf(rawAdd).trim()] : [];
+            if (toAdd.length === 0) {
+                throw opErr("SCRIPT OP BLOCKED: Alias empty", "Alias empty.", {
+                    required: ["alias: non-empty string or array"],
+                    received: [JSON.stringify(op)],
+                    nextSteps: ["Pass --add <alias> at least once."],
+                    op: kind,
+                    errorCode: "ALIAS_EMPTY",
+                });
+            }
+            const existing = asList(asset["aliases"]).map((s) => strOf(s));
+            const seen = new Set(existing);
+            for (const alias of toAdd) {
+                if (!seen.has(alias)) {
+                    existing.push(alias);
                     seen.add(alias);
-                    cleanedAliases.push(alias);
                 }
             }
-            asset["aliases"] = cleanedAliases;
+            asset["aliases"] = existing;
+            applied.push(kind);
+        }
+        else if (kind === "asset.alias.remove") {
+            const [assetKind, assetId] = parseAssetTarget(op["target"]);
+            const asset = resolveAssetByTarget(script, assetKind, assetId);
+            const rawRemove = op["alias"] ?? op["aliases"];
+            const toRemove = new Set(isList(rawRemove)
+                ? rawRemove.map((v) => strOf(v).trim()).filter((v) => v)
+                : strOf(rawRemove).trim() ? [strOf(rawRemove).trim()] : []);
+            if (toRemove.size === 0) {
+                throw opErr("SCRIPT OP BLOCKED: Alias empty", "Alias empty.", {
+                    required: ["alias: non-empty string or array"],
+                    received: [JSON.stringify(op)],
+                    nextSteps: ["Pass --remove <alias> at least once."],
+                    op: kind,
+                    errorCode: "ALIAS_EMPTY",
+                });
+            }
+            asset["aliases"] = asList(asset["aliases"]).map((s) => strOf(s)).filter((a) => !toRemove.has(a));
             applied.push(kind);
         }
-        else if (kind === "set_asset_states") {
-            const [asset] = resolvePatchAsset(script, op);
-            const assetKind = strOf(op["asset_type"]).trim();
+        else if (kind === "asset.states.set") {
+            const [assetKind, assetId] = parseAssetTarget(op["target"]);
+            const asset = resolveAssetByTarget(script, assetKind, assetId);
             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."] });
+        else if (kind === "asset.merge") {
+            // Direction is explicit: `from` disappears, `into` keeps everything.
+            const fromRaw = op["from"] ?? op["source"];
+            const intoRaw = op["into"] ?? op["target"];
+            const [fromKind, fromId] = parseAssetTarget(fromRaw);
+            const [intoKind, intoId] = parseAssetTarget(intoRaw);
+            if (fromKind !== intoKind) {
+                throw opErr("SCRIPT OP BLOCKED: Merge kind mismatch", "Merge source and target must be the same kind.", {
+                    required: ["same kind on both sides (actor/actor, location/location, prop/prop)"],
+                    received: [`${fromKind}:${fromId} → ${intoKind}:${intoId}`],
+                    nextSteps: ["Use a same-kind target."],
+                    op: kind,
+                    errorCode: "MERGE_KIND_MISMATCH",
+                });
             }
-            script[key] = asList(script[key]).filter((it) => it[idKey] !== sourceId);
+            const [key, idKey] = assetKeys(fromKind);
+            // Verify both exist.
+            resolveAssetByTarget(script, fromKind, fromId);
+            resolveAssetByTarget(script, intoKind, intoId);
+            // Pre-flight: refuse merge if any scene context already references BOTH
+            // from and into with conflicting state_ids. Silently picking one (the
+            // array-order-first) was a quiet data-loss bug — we'd rather make the
+            // user resolve the state divergence explicitly.
             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;
+                    const ctx = sceneContext(scene);
+                    const refList = contextRefsForKind(ctx, fromKind);
+                    const fromRef = refList.find((ref) => strOf(ref[idKey]) === fromId);
+                    const intoRef = refList.find((ref) => strOf(ref[idKey]) === intoId);
+                    if (fromRef && intoRef) {
+                        const fromState = strOf(fromRef["state_id"]);
+                        const intoState = strOf(intoRef["state_id"]);
+                        if (fromState !== intoState) {
+                            throw opErr("SCRIPT OP BLOCKED: Merge state conflict", "Merge has conflicting state_ids in a shared scene.", {
+                                required: ["from and into agree on state_id in every scene where both appear"],
+                                received: [`${ep["episode_id"]}/${scene["scene_id"]}: ${fromId}=${fromState || "null"}, ${intoId}=${intoState || "null"}`],
+                                nextSteps: ["Resolve the state divergence (run `scriptctl context <scene> <kind>:<into-id> --state <state>`) then retry merge."],
+                                op: kind,
+                                errorCode: "MERGE_STATE_CONFLICT",
+                            });
+                        }
                     }
+                }
+            }
+            // Drop source from the asset list.
+            script[key] = asList(script[key]).filter((it) => strOf(it[idKey]) !== fromId);
+            // Rewrite refs: scene.context, action.actor_id (actor only), state_changes targets, transition targets, speaker.source_id.
+            for (const ep of asList(script["episodes"])) {
+                for (const scene of asList(ep["scenes"])) {
+                    const ctx = sceneContext(scene);
+                    const refList = contextRefsForKind(ctx, fromKind);
+                    for (const ref of refList) {
+                        if (strOf(ref[idKey]) === fromId)
+                            ref[idKey] = intoId;
+                    }
+                    // After rewrite, dedupe (intoId may now appear twice). State_id was
+                    // pre-validated to agree above, so first-seen wins is safe.
+                    const seen = new Set();
+                    ctx[pluralForKind(fromKind)] = refList.filter((ref) => {
+                        const key2 = strOf(ref[idKey]);
+                        if (seen.has(key2))
+                            return false;
+                        seen.add(key2);
+                        return true;
+                    });
+                    setSceneContext(scene, ctx);
                     for (const action of asList(scene["actions"])) {
-                        if (idKey === "actor_id" && action["actor_id"] === sourceId)
-                            action["actor_id"] = targetId;
+                        if (fromKind === "actor" && strOf(action["actor_id"]) === fromId)
+                            action["actor_id"] = intoId;
+                        for (const change of asList(action["state_changes"])) {
+                            if (strOf(change["target_kind"]) === fromKind && strOf(change["target_id"]) === fromId) {
+                                change["target_id"] = intoId;
+                            }
+                        }
+                        const transition = action["transition_prompt"];
+                        if (isDict(transition) && strOf(transition["target_kind"]) === fromKind && strOf(transition["target_id"]) === fromId) {
+                            transition["target_id"] = intoId;
+                        }
                     }
                 }
             }
+            // Speakers anchored to the source actor get reattached to the target.
+            for (const sp of asList(script["speakers"])) {
+                if (strOf(sp["source_kind"]) === fromKind && strOf(sp["source_id"]) === fromId) {
+                    sp["source_id"] = intoId;
+                }
+            }
             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 if (kind === "asset.delete") {
+            // Refs are walked via collectAssetRefs. Default: refuse if any refs exist.
+            // strategy=replace → rewrite refs to a replacement asset, then delete.
+            // strategy=remove → rewrite refs to null/clean and delete (leaves dangling
+            // pointers cleaned by per-edge logic; validation will still surface anything
+            // still wrong).
+            const [assetKind, assetId] = parseAssetTarget(op["target"]);
+            resolveAssetByTarget(script, assetKind, assetId);
+            const refs = collectAssetRefs(script, assetKind, assetId);
+            const strategy = strOf(op["strategy"]).trim();
+            if (refs.length > 0 && !strategy) {
+                throw opErr("SCRIPT OP BLOCKED: Asset has refs", `Asset is referenced ${refs.length} time(s).`, {
+                    required: ["--strategy replace|remove"],
+                    received: [`refs=${refs.length}`],
+                    nextSteps: ["Use --strategy replace --replacement <addr> to remap, or --strategy remove to scrub refs."],
+                    op: kind,
+                    errorCode: "ASSET_HAS_REFS",
+                });
+            }
+            if (strategy === "replace") {
+                const replacementRaw = op["replacement"] ?? op["into"];
+                const [replacementKind, replacementId] = parseAssetTarget(replacementRaw);
+                if (replacementKind !== assetKind) {
+                    throw opErr("SCRIPT OP BLOCKED: Replacement kind mismatch", "Replacement must be same kind.", {
+                        required: ["replacement same kind as target"],
+                        received: [`${assetKind} vs ${replacementKind}`],
+                        nextSteps: ["Pass a same-kind replacement."],
+                        op: kind,
+                        errorCode: "REPLACEMENT_KIND_MISMATCH",
+                    });
+                }
+                resolveAssetByTarget(script, replacementKind, replacementId);
+                // Delegate ref rewrite to asset.merge logic by reusing the same traversal.
+                applyPatchOperations(script, sourceText, [
+                    { op: "asset.merge", from: op["target"], into: replacementRaw },
+                ]);
+                applied.push(kind);
+            }
+            else if (strategy === "remove" || refs.length === 0) {
+                // Scrub refs (actor_id → undefined, state_changes/transition refs removed, scene.context entries removed, speakers' source_id cleared).
+                const [key, idKey] = assetKeys(assetKind);
+                script[key] = asList(script[key]).filter((it) => strOf(it[idKey]) !== assetId);
+                for (const ep of asList(script["episodes"])) {
+                    for (const scene of asList(ep["scenes"])) {
+                        const ctx = sceneContext(scene);
+                        ctx[pluralForKind(assetKind)] = contextRefsForKind(ctx, assetKind).filter((ref) => strOf(ref[idKey]) !== assetId);
+                        setSceneContext(scene, ctx);
+                        for (const action of asList(scene["actions"])) {
+                            if (assetKind === "actor" && strOf(action["actor_id"]) === assetId)
+                                delete action["actor_id"];
+                            const changes = asList(action["state_changes"]).filter((c) => !(strOf(c["target_kind"]) === assetKind && strOf(c["target_id"]) === assetId));
+                            if (changes.length > 0)
+                                action["state_changes"] = changes;
+                            else
+                                delete action["state_changes"];
+                            const transition = action["transition_prompt"];
+                            if (isDict(transition) && strOf(transition["target_kind"]) === assetKind && strOf(transition["target_id"]) === assetId) {
+                                delete action["transition_prompt"];
+                            }
+                        }
+                    }
+                }
+                for (const sp of asList(script["speakers"])) {
+                    if (strOf(sp["source_kind"]) === assetKind && strOf(sp["source_id"]) === assetId) {
+                        sp["source_id"] = null;
+                    }
+                }
+                applied.push(kind);
             }
             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 });
+                throw opErr("SCRIPT OP BLOCKED: Strategy invalid", "Strategy invalid.", {
+                    required: ["strategy: replace or remove"],
+                    received: [strategy],
+                    nextSteps: ["Use replace (with --replacement) or remove."],
+                    op: kind,
+                    errorCode: "DELETE_STRATEGY_INVALID",
+                });
             }
-            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."] });
+        else if (kind === "action.type.set") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const actionType = strOf(op["type"] ?? op["action_type"]).trim();
+            if (!ACTION_TYPE_VALUES.has(actionType)) {
+                throw opErr("SCRIPT OP BLOCKED: Action type invalid", "Action type invalid.", {
+                    required: ["type: dialogue, inner_thought, or action"],
+                    received: [actionType || "<empty>"],
+                    nextSteps: ["Use a supported action type."],
+                    op: kind,
+                    errorCode: "ACTION_TYPE_INVALID",
+                });
             }
-            const action = findAction(script, strOf(op["episode_id"]), strOf(op["scene_id"]), actionIndex);
+            const action = findAction(script, epId, sceneId, actionIndex);
+            action["type"] = actionType;
+            applied.push(kind);
+        }
+        else if (kind === "action.actor.set") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const rawActor = op["actor_id"] ?? op["actor"];
+            const isNone = rawActor === null || strOf(rawActor).trim() === "" || strOf(rawActor).trim() === "none";
+            const actorId = isNone ? null : ensureRefId(script, "actor", rawActor);
+            const action = findAction(script, epId, sceneId, 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);
+        else if (kind === "action.delete") {
+            const [epId, sceneId, actionIndex] = parseActionRef(op["at"]);
+            const scene = findScene(script, epId, sceneId);
+            const actions = asList(scene["actions"]);
+            if (actionIndex < 0 || actionIndex >= actions.length) {
+                throw opErr("SCRIPT OP BLOCKED: Action index out of range", "Action index out of range.", {
+                    required: [`0 <= action_index < ${actions.length}`],
+                    received: [String(actionIndex)],
+                    nextSteps: ["Inspect actions in the scene and use a valid index."],
+                    op: kind,
+                    errorCode: "ACTION_INDEX_OUT_OF_RANGE",
+                });
+            }
+            actions.splice(actionIndex, 1);
+            scene["actions"] = actions;
+            applied.push(kind);
+        }
+        else if (kind === "action.insert") {
+            // <at> is a scene ref (ep_xxx/scn_xxx). Position resolved from
+            // --at <idx> | --before <action-ref> | --after <action-ref> | default-append.
+            const [epId, sceneId] = parseSceneRef(op["at"]);
+            const scene = findScene(script, epId, sceneId);
+            const actions = asList(scene["actions"]);
+            const actionType = strOf(op["type"]).trim();
+            if (!ACTION_TYPE_VALUES.has(actionType)) {
+                throw opErr("SCRIPT OP BLOCKED: Action type invalid", "Action type invalid.", {
+                    required: ["type: dialogue, inner_thought, or action"],
+                    received: [actionType || "<empty>"],
+                    nextSteps: ["Use a supported action type."],
+                    op: kind,
+                    errorCode: "ACTION_TYPE_INVALID",
+                });
+            }
+            const content = strOf(op["content"]);
+            let insertIndex;
+            if (op["before"]) {
+                const [bEp, bScn, bIdx] = parseActionRef(op["before"]);
+                if (bEp !== epId || bScn !== sceneId) {
+                    throw opErr("SCRIPT OP BLOCKED: before address mismatch", "--before must point at the same scene.", {
+                        required: [`${epId}/${sceneId}#<idx>`],
+                        received: [strOf(op["before"])],
+                        nextSteps: ["Use a sibling action address."],
+                        op: kind,
+                        errorCode: "INSERT_REF_MISMATCH",
+                    });
+                }
+                insertIndex = bIdx;
+            }
+            else if (op["after"]) {
+                const [aEp, aScn, aIdx] = parseActionRef(op["after"]);
+                if (aEp !== epId || aScn !== sceneId) {
+                    throw opErr("SCRIPT OP BLOCKED: after address mismatch", "--after must point at the same scene.", {
+                        required: [`${epId}/${sceneId}#<idx>`],
+                        received: [strOf(op["after"])],
+                        nextSteps: ["Use a sibling action address."],
+                        op: kind,
+                        errorCode: "INSERT_REF_MISMATCH",
+                    });
+                }
+                insertIndex = aIdx + 1;
+            }
+            else if (op["at_index"] !== undefined && op["at_index"] !== null) {
+                const n = Number(op["at_index"]);
+                if (!Number.isInteger(n) || n < 0 || n > actions.length) {
+                    throw opErr("SCRIPT OP BLOCKED: at_index out of range", "at_index out of range.", {
+                        required: [`0..${actions.length}`],
+                        received: [String(op["at_index"])],
+                        nextSteps: ["Use a valid integer index."],
+                        op: kind,
+                        errorCode: "AT_INDEX_OUT_OF_RANGE",
+                    });
+                }
+                insertIndex = n;
+            }
+            else {
+                // Default: append at end.
+                insertIndex = actions.length;
+            }
+            const newAction = { type: actionType, content };
+            if (op["actor_id"])
+                newAction["actor_id"] = ensureRefId(script, "actor", op["actor_id"]);
+            if (op["speaker_id"])
+                newAction["speaker_id"] = ensureSpeakerId(script, strOf(op["speaker_id"]));
+            actions.splice(insertIndex, 0, newAction);
+            scene["actions"] = actions;
             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."] });
+        else if (kind === "action.move") {
+            const [fromEp, fromScn, fromIdx] = parseActionRef(op["at"] ?? op["from"]);
+            const [toEp, toScn, toIdx] = parseActionRef(op["to"]);
+            const fromScene = findScene(script, fromEp, fromScn);
+            const fromActions = asList(fromScene["actions"]);
+            if (fromIdx < 0 || fromIdx >= fromActions.length) {
+                throw opErr("SCRIPT OP BLOCKED: Action index out of range", "Source action index out of range.", {
+                    required: [`0 <= idx < ${fromActions.length}`],
+                    received: [String(fromIdx)],
+                    nextSteps: ["Inspect actions and use a valid index."],
+                    op: kind,
+                    errorCode: "ACTION_INDEX_OUT_OF_RANGE",
+                });
             }
+            const [moved] = fromActions.splice(fromIdx, 1);
+            fromScene["actions"] = fromActions;
+            const toScene = (fromEp === toEp && fromScn === toScn) ? fromScene : findScene(script, toEp, toScn);
+            const toActions = asList(toScene["actions"]);
+            // After removing the source, when target is the same scene and idx is past
+            // the removed slot, the agent's intended index is already correct (no
+            // shift needed in the destination); otherwise clamp.
+            let dest = toIdx;
+            if (dest < 0)
+                dest = 0;
+            if (dest > toActions.length)
+                dest = toActions.length;
+            toActions.splice(dest, 0, moved);
+            toScene["actions"] = toActions;
+            applied.push(kind);
+        }
+        else if (kind === "scene.insert") {
+            // Insert a new empty scene into an episode. Position resolved from
+            // --at <idx> | --before <ep/scn> | --after <ep/scn> | default-append.
+            // Requires --location to anchor the scene's locations[] context (matches
+            // direct-init's assumption that every scene names at least one location).
+            const epId = strOf(op["at"] ?? op["episode_id"]);
+            const ep = findEpisode(script, epId);
             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);
-                    }
+            const locationId = strOf(op["location"] ?? op["location_id"]).trim();
+            if (!locationId) {
+                throw opErr("SCRIPT OP BLOCKED: location required", "Scene insert requires --location.", {
+                    required: ["location: existing location_id"],
+                    received: ["<empty>"],
+                    nextSteps: ["Pass --location <loc_id>."],
+                    op: kind,
+                    errorCode: "SCENE_LOCATION_MISSING",
+                });
+            }
+            ensureRefId(script, "location", locationId);
+            let insertIndex;
+            if (op["before"]) {
+                const [bEp, bScn] = parseSceneRef(op["before"]);
+                if (bEp !== epId) {
+                    throw opErr("SCRIPT OP BLOCKED: before address mismatch", "--before must point at the same episode.", {
+                        required: [`${epId}/<scn>`],
+                        received: [strOf(op["before"])],
+                        nextSteps: ["Use a sibling scene address."],
+                        op: kind,
+                        errorCode: "INSERT_REF_MISMATCH",
+                    });
                 }
+                insertIndex = scenes.findIndex((s) => strOf(s["scene_id"]) === bScn);
+                if (insertIndex < 0) {
+                    throw opErr("SCRIPT OP BLOCKED: before scene not found", "before scene not found.", {
+                        required: ["existing scene_id"],
+                        received: [bScn],
+                        nextSteps: ["Inspect scenes."],
+                        op: kind,
+                        errorCode: "SCENE_NOT_FOUND",
+                    });
+                }
+            }
+            else if (op["after"]) {
+                const [aEp, aScn] = parseSceneRef(op["after"]);
+                if (aEp !== epId) {
+                    throw opErr("SCRIPT OP BLOCKED: after address mismatch", "--after must point at the same episode.", {
+                        required: [`${epId}/<scn>`],
+                        received: [strOf(op["after"])],
+                        nextSteps: ["Use a sibling scene address."],
+                        op: kind,
+                        errorCode: "INSERT_REF_MISMATCH",
+                    });
+                }
+                const found = scenes.findIndex((s) => strOf(s["scene_id"]) === aScn);
+                if (found < 0) {
+                    throw opErr("SCRIPT OP BLOCKED: after scene not found", "after scene not found.", {
+                        required: ["existing scene_id"],
+                        received: [aScn],
+                        nextSteps: ["Inspect scenes."],
+                        op: kind,
+                        errorCode: "SCENE_NOT_FOUND",
+                    });
+                }
+                insertIndex = found + 1;
+            }
+            else if (op["at_index"] !== undefined && op["at_index"] !== null) {
+                const n = Number(op["at_index"]);
+                if (!Number.isInteger(n) || n < 0 || n > scenes.length) {
+                    throw opErr("SCRIPT OP BLOCKED: at_index out of range", "at_index out of range.", {
+                        required: [`0..${scenes.length}`],
+                        received: [String(op["at_index"])],
+                        nextSteps: ["Use a valid integer index."],
+                        op: kind,
+                        errorCode: "AT_INDEX_OUT_OF_RANGE",
+                    });
+                }
+                insertIndex = n;
             }
-            setSceneContext(keep, keepCtx);
-            ep["scenes"] = scenes.filter((s) => s !== remove);
+            else {
+                insertIndex = scenes.length;
+            }
+            const newSceneId = strOf(op["scene_id"]).trim() || nextSceneId(script);
+            if (sceneIdExists(script, newSceneId)) {
+                throw opErr("SCRIPT OP BLOCKED: New scene id exists", "New scene id exists.", {
+                    required: ["unused scene_id"],
+                    received: [newSceneId],
+                    nextSteps: ["Pass --scene-id <unused> or omit."],
+                    op: kind,
+                    errorCode: "NEW_SCENE_ID_EXISTS",
+                });
+            }
+            const time = strOf(op["time"]).trim() || "day";
+            const space = strOf(op["space"]).trim() || "interior";
+            const newScene = {
+                scene_id: newSceneId,
+                environment: { time, space },
+                context: {
+                    locations: [{ location_id: locationId, state_id: null }],
+                    actors: [],
+                    props: [],
+                },
+                locations: [{ location_id: locationId, state_id: null }],
+                actors: [],
+                props: [],
+                actions: [],
+            };
+            scenes.splice(insertIndex, 0, newScene);
+            ep["scenes"] = scenes;
             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"];
+        else if (kind === "scene.split") {
+            const [epId, sceneId] = parseSceneRef(op["at"]);
+            const splitAt = op["at_index"] ?? 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."] });
+                throw opErr("SCRIPT OP BLOCKED: Split index invalid", "Split index invalid.", {
+                    required: ["at_index: integer between existing actions"],
+                    received: [JSON.stringify(op)],
+                    nextSteps: ["Inspect actions and use a valid index."],
+                    op: kind,
+                    errorCode: "SPLIT_INDEX_INVALID",
+                });
             }
             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."] });
+                throw opErr("SCRIPT OP BLOCKED: Scene not found", "Scene not found.", {
+                    required: ["existing scene_id"],
+                    received: [sceneId],
+                    nextSteps: ["Inspect scenes and fix the address."],
+                    op: kind,
+                    errorCode: "SCENE_NOT_FOUND",
+                });
             }
             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."] });
+                throw opErr("SCRIPT OP BLOCKED: Split index invalid", "Split index out of bounds.", {
+                    required: [`0 < at_index < ${actions.length}`],
+                    received: [String(splitAt)],
+                    nextSteps: ["Choose an action boundary inside the scene."],
+                    op: kind,
+                    errorCode: "SPLIT_INDEX_INVALID",
+                });
             }
             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."] });
+                throw opErr("SCRIPT OP 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."],
+                    op: kind,
+                    errorCode: "NEW_SCENE_ID_EXISTS",
+                });
             }
             const ctx = sceneContext(scene);
             const newScene = {
@@ -1885,13 +2558,312 @@ export function applyPatchOperations(script, sourceText, operations) {
             scenes.splice(index + 1, 0, newScene);
             applied.push(kind);
         }
+        else if (kind === "scene.merge") {
+            // 0.6.0 uses {from, into} (source disappears, into keeps). The legacy op
+            // used {keep_scene_id, remove_scene_id}; payload still accepted for back-
+            // compat during transition.
+            const fromRaw = op["from"] ?? op["remove_scene_id"];
+            const intoRaw = op["into"] ?? op["keep_scene_id"];
+            // from can be either ep/scn or just scn (legacy). Normalize.
+            let fromEp, fromScn, intoEp, intoScn;
+            if (typeof fromRaw === "string" && fromRaw.includes("/")) {
+                [fromEp, fromScn] = parseSceneRef(fromRaw);
+            }
+            else {
+                // Legacy: needs episode_id from op.
+                fromEp = strOf(op["episode_id"]);
+                fromScn = strOf(fromRaw);
+            }
+            if (typeof intoRaw === "string" && intoRaw.includes("/")) {
+                [intoEp, intoScn] = parseSceneRef(intoRaw);
+            }
+            else {
+                intoEp = strOf(op["episode_id"]);
+                intoScn = strOf(intoRaw);
+            }
+            if (fromEp !== intoEp) {
+                throw opErr("SCRIPT OP BLOCKED: Merge cross-episode", "Scene merge must be within one episode.", {
+                    required: ["same episode_id on both sides"],
+                    received: [`${fromEp}/${fromScn} → ${intoEp}/${intoScn}`],
+                    nextSteps: ["Move one scene first, or merge same-episode scenes."],
+                    op: kind,
+                    errorCode: "MERGE_CROSS_EPISODE",
+                });
+            }
+            const ep = findEpisode(script, fromEp);
+            const scenes = asList(ep["scenes"]);
+            const intoScene = scenes.find((s) => s["scene_id"] === intoScn);
+            const fromScene = scenes.find((s) => s["scene_id"] === fromScn);
+            if (!intoScene || !fromScene) {
+                throw opErr("SCRIPT OP BLOCKED: Scene not found", "Scene not found.", {
+                    required: ["existing scene_id on both sides"],
+                    received: [`from=${fromScn}, into=${intoScn}`],
+                    nextSteps: ["Inspect scenes and fix the address."],
+                    op: kind,
+                    errorCode: "SCENE_NOT_FOUND",
+                });
+            }
+            intoScene["actions"].push(...asList(fromScene["actions"]));
+            const intoCtx = sceneContext(intoScene);
+            const fromCtx = sceneContext(fromScene);
+            for (const [field, idKey] of [["actors", "actor_id"], ["locations", "location_id"], ["props", "prop_id"]]) {
+                const existingIds = new Set();
+                for (const ref of asList(intoCtx[field]))
+                    existingIds.add(ref[idKey]);
+                for (const ref of asList(fromCtx[field])) {
+                    if (!existingIds.has(ref[idKey])) {
+                        if (!isList(intoCtx[field]))
+                            intoCtx[field] = [];
+                        intoCtx[field].push(ref);
+                    }
+                }
+            }
+            setSceneContext(intoScene, intoCtx);
+            ep["scenes"] = scenes.filter((s) => s !== fromScene);
+            applied.push(kind);
+        }
+        else if (kind === "scene.delete") {
+            const [epId, sceneId] = parseSceneRef(op["at"]);
+            const ep = findEpisode(script, epId);
+            const scenes = asList(ep["scenes"]);
+            const scene = scenes.find((s) => s["scene_id"] === sceneId);
+            if (!scene) {
+                throw opErr("SCRIPT OP BLOCKED: Scene not found", "Scene not found.", {
+                    required: ["existing scene_id"],
+                    received: [`${epId}/${sceneId}`],
+                    nextSteps: ["Inspect scenes."],
+                    op: kind,
+                    errorCode: "SCENE_NOT_FOUND",
+                });
+            }
+            const actions = asList(scene["actions"]);
+            const force = Boolean(op["force"]);
+            if (actions.length > 0 && !force) {
+                throw opErr("SCRIPT OP BLOCKED: Scene non-empty", `Scene has ${actions.length} action(s).`, {
+                    required: ["empty scene, or force=true"],
+                    received: [`actions=${actions.length}`],
+                    nextSteps: ["Pass --force to delete with actions, or move/delete actions first."],
+                    op: kind,
+                    errorCode: "SCENE_NON_EMPTY",
+                });
+            }
+            ep["scenes"] = scenes.filter((s) => s !== scene);
+            applied.push(kind);
+        }
+        else if (kind === "scene.move") {
+            const [fromEp, fromScn] = parseSceneRef(op["at"] ?? op["from"]);
+            const toEpRaw = strOf(op["to"]);
+            // `to` accepts either bare `ep_NNN` (append) or `ep_NNN/scn_NNN` (insert before that scene).
+            // `--at <idx>` overrides positioning.
+            let toEp;
+            let toAnchorScn = null;
+            if (toEpRaw.includes("/")) {
+                const [a, b] = parseSceneRef(toEpRaw);
+                toEp = a;
+                toAnchorScn = b;
+            }
+            else {
+                toEp = toEpRaw;
+            }
+            if (!toEp) {
+                throw opErr("SCRIPT OP BLOCKED: to address invalid", "to address invalid.", {
+                    required: ["to: ep_NNN or ep_NNN/scn_NNN"],
+                    received: [toEpRaw],
+                    nextSteps: ["Pass a target episode id."],
+                    op: kind,
+                    errorCode: "SCENE_MOVE_TO_INVALID",
+                });
+            }
+            const fromEpisode = findEpisode(script, fromEp);
+            const fromScenes = asList(fromEpisode["scenes"]);
+            const sourceIdx = fromScenes.findIndex((s) => s["scene_id"] === fromScn);
+            if (sourceIdx < 0) {
+                throw opErr("SCRIPT OP BLOCKED: Scene not found", "Source scene not found.", {
+                    required: ["existing scene_id"],
+                    received: [`${fromEp}/${fromScn}`],
+                    nextSteps: ["Inspect scenes."],
+                    op: kind,
+                    errorCode: "SCENE_NOT_FOUND",
+                });
+            }
+            const [moved] = fromScenes.splice(sourceIdx, 1);
+            fromEpisode["scenes"] = fromScenes;
+            const toEpisode = findEpisode(script, toEp);
+            const toScenes = asList(toEpisode["scenes"]);
+            let destIdx;
+            if (op["at_index"] !== undefined && op["at_index"] !== null) {
+                const n = Number(op["at_index"]);
+                if (!Number.isInteger(n) || n < 0 || n > toScenes.length) {
+                    throw opErr("SCRIPT OP BLOCKED: at_index out of range", "at_index out of range.", {
+                        required: [`0..${toScenes.length}`],
+                        received: [String(op["at_index"])],
+                        nextSteps: ["Use a valid integer index."],
+                        op: kind,
+                        errorCode: "AT_INDEX_OUT_OF_RANGE",
+                    });
+                }
+                destIdx = n;
+            }
+            else if (toAnchorScn) {
+                const found = toScenes.findIndex((s) => s["scene_id"] === toAnchorScn);
+                if (found < 0) {
+                    throw opErr("SCRIPT OP BLOCKED: Target scene not found", "Target scene not found.", {
+                        required: ["existing scene_id in target episode"],
+                        received: [`${toEp}/${toAnchorScn}`],
+                        nextSteps: ["Inspect the target episode."],
+                        op: kind,
+                        errorCode: "SCENE_NOT_FOUND",
+                    });
+                }
+                destIdx = found;
+            }
+            else {
+                destIdx = toScenes.length;
+            }
+            toScenes.splice(destIdx, 0, moved);
+            toEpisode["scenes"] = toScenes;
+            applied.push(kind);
+        }
+        else if (kind === "speaker.delete") {
+            // Mirror of asset.delete for speakers: refs scrub or replace via
+            // --strategy. Speaker refs live in action.speaker_id /
+            // action.speakers[] / action.lines[].speaker_id only — no scene
+            // context entries to handle.
+            const speakerId = strOf(op["target"] ?? op["speaker_id"]).trim();
+            if (!speakerId) {
+                throw opErr("SCRIPT OP BLOCKED: Speaker id missing", "Speaker id missing.", {
+                    required: ["target speaker id"],
+                    received: [JSON.stringify(op)],
+                    nextSteps: ["Pass a spk_id."],
+                    op: kind,
+                    errorCode: "SPEAKER_ID_MISSING",
+                });
+            }
+            const refs = collectAssetRefs(script, "speaker", speakerId);
+            const strategy = strOf(op["strategy"]).trim();
+            if (refs.length > 0 && !strategy) {
+                throw opErr("SCRIPT OP BLOCKED: Speaker has refs", `Speaker is referenced ${refs.length} time(s).`, {
+                    required: ["--strategy replace|remove"],
+                    received: [`refs=${refs.length}`],
+                    nextSteps: ["Use --strategy replace --replacement <spk_id> to remap, or --strategy remove to scrub refs."],
+                    op: kind,
+                    errorCode: "SPEAKER_HAS_REFS",
+                });
+            }
+            const replacement = strOf(op["replacement"]).trim();
+            if (strategy === "replace") {
+                if (!replacement) {
+                    throw opErr("SCRIPT OP BLOCKED: Replacement missing", "Replacement missing.", {
+                        required: ["replacement speaker id"],
+                        received: ["<empty>"],
+                        nextSteps: ["Pass --replacement <spk_id>."],
+                        op: kind,
+                        errorCode: "REPLACEMENT_MISSING",
+                    });
+                }
+                // Verify replacement exists.
+                if (!asList(script["speakers"]).some((s) => strOf(s["speaker_id"]) === replacement)) {
+                    throw opErr("SCRIPT OP BLOCKED: Replacement speaker not found", "Replacement speaker not found.", {
+                        required: ["existing speaker id"],
+                        received: [replacement],
+                        nextSteps: ["Add the speaker first or use a different replacement."],
+                        op: kind,
+                        errorCode: "SPEAKER_NOT_FOUND",
+                    });
+                }
+                for (const ep of asList(script["episodes"])) {
+                    for (const scene of asList(ep["scenes"])) {
+                        for (const action of asList(scene["actions"])) {
+                            if (strOf(action["speaker_id"]) === speakerId)
+                                action["speaker_id"] = replacement;
+                            const speakers = asList(action["speakers"]);
+                            for (const sp of speakers) {
+                                if (strOf(sp["speaker_id"]) === speakerId)
+                                    sp["speaker_id"] = replacement;
+                            }
+                            // Dedupe action.speakers[] in case the action already referenced
+                            // the replacement: an unconditional rewrite + no dedupe would
+                            // leave [spk_replacement, spk_replacement], breaking overlap/
+                            // simultaneous delivery counts downstream.
+                            if (action["speakers"] !== undefined) {
+                                const seen = new Set();
+                                action["speakers"] = speakers.filter((s) => {
+                                    const id = strOf(s["speaker_id"]);
+                                    if (seen.has(id))
+                                        return false;
+                                    seen.add(id);
+                                    return true;
+                                });
+                            }
+                            const lines = asList(action["lines"]);
+                            for (const line of lines) {
+                                if (strOf(line["speaker_id"]) === speakerId)
+                                    line["speaker_id"] = replacement;
+                            }
+                            // lines[] semantically represents distinct overlapping lines
+                            // (a speaker can legitimately overlap with themselves), so we do
+                            // NOT dedupe lines — preserve overlap-with-self if it existed.
+                        }
+                    }
+                }
+            }
+            else if (strategy === "remove" || refs.length === 0) {
+                for (const ep of asList(script["episodes"])) {
+                    for (const scene of asList(ep["scenes"])) {
+                        for (const action of asList(scene["actions"])) {
+                            if (strOf(action["speaker_id"]) === speakerId)
+                                delete action["speaker_id"];
+                            const speakers = asList(action["speakers"]).filter((s) => strOf(s["speaker_id"]) !== speakerId);
+                            if (action["speakers"] !== undefined) {
+                                if (speakers.length > 0)
+                                    action["speakers"] = speakers;
+                                else
+                                    delete action["speakers"];
+                            }
+                            const lines = asList(action["lines"]).filter((l) => strOf(l["speaker_id"]) !== speakerId);
+                            if (action["lines"] !== undefined) {
+                                if (lines.length > 0)
+                                    action["lines"] = lines;
+                                else
+                                    delete action["lines"];
+                            }
+                        }
+                    }
+                }
+            }
+            else {
+                throw opErr("SCRIPT OP BLOCKED: Strategy invalid", "Strategy invalid.", {
+                    required: ["strategy: replace or remove"],
+                    received: [strategy],
+                    nextSteps: ["Use replace (with --replacement) or remove."],
+                    op: kind,
+                    errorCode: "DELETE_STRATEGY_INVALID",
+                });
+            }
+            script["speakers"] = asList(script["speakers"]).filter((s) => strOf(s["speaker_id"]) !== speakerId);
+            applied.push(kind);
+        }
+        else if (kind === "context.ref.remove") {
+            const [epId, sceneId] = parseSceneRef(op["at"]);
+            const [targetKind, targetId] = parseAssetTarget(op["target"]);
+            const scene = findScene(script, epId, sceneId);
+            const ctx = sceneContext(scene);
+            const idKey = idKeyForKind(targetKind);
+            ctx[pluralForKind(targetKind)] = contextRefsForKind(ctx, targetKind).filter((ref) => strOf(ref[idKey]) !== targetId);
+            setSceneContext(scene, ctx);
+            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",
+                    "dot-style op: meta.worldview.set / asset.{rename,describe,alias.set,alias.add,alias.remove,states.set,role.set,merge,delete} / state.{add,rename,describe,delete} / context.{set,clear,ref.remove} / action.{type.set,actor.set,delete,insert,move,state.change,state.remove,transition.set,transition.clear,content.replace} / scene.{split,merge,delete,move} / dialogue.{speakers,overlap} / speaker.add",
                 ],
                 received: [kind],
-                nextSteps: ["Use a supported patch operation."],
+                nextSteps: [
+                    "Use a supported dot-style patch operation.",
+                    "Legacy snake-style ops (set_worldview / rename_actor / set_action_type / merge_scenes / split_scene / set_scene_*_ref / set_action_actor / set_asset_aliases / set_asset_states / set_action_content_from_span etc.) were removed in 0.6.0; use the new dot-style equivalents.",
+                ],
+                errorCode: "OP_UNSUPPORTED",
             });
         }
     }