@lingjingai/scriptctl 0.49.16 → 0.50.0

package/dist/usecases/script/lib.js

@@ -1,12 +1,19 @@
-import { CliError, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_USAGE, } from "../../common.js";
-import { applyPatchOperations } from "../../domain/script/patch/apply.js";
+import { CliError, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_USAGE, sha256Text, } from "../../common.js";
+import { applyPatchOperationsV4 } from "../../domain/script/v4/patch/apply.js";
+import { isV4Id } from "../../domain/script/v4/ids.js";
+import { requireScriptV4 } from "../../domain/script/v4/parse.js";
+import { validateScriptV4 } from "../../domain/script/v4/validation.js";
 import { sceneRefs } from "../../domain/script/scene-refs.js";
 import { isDangerousRegex, MAX_GREP_PATTERN_LEN, parseInSelector, selectorSingleActionPoint, WHOLE_SCRIPT, } from "../../domain/script/selector.js";
 import { parseAnyAddress, } from "../../domain/script/address.js";
+import { parseV4Address } from "../../domain/script/v4/address.js";
 import { summarizeIssues } from "../../domain/script/text-util.js";
 import { sortDeep } from "../../domain/script/text-util.js";
 import { asList, idNum, isDict, strOf, } from "../../domain/script/shared.js";
 import { loadScriptForEdit, validateSession, saveScriptSession, syncValidationResult, scriptSourceText, } from "./session.js";
+import { resolveActionTargetsV4 } from "./v4/queries.js";
+import { applyVersionedMutations } from "./dispatch.js";
+import { assertInsertCommandFlags, assertMoveCommandFlags, assertSceneRefCommandFlags, } from "./command-constraints.js";
 export function tokenizeLine(line) {
     const out = [];
     let cur = "";
@@ -75,6 +82,7 @@ export const DO_BOOL_FLAGS = {
     replace: new Set(["all", "regex"]),
     transition: new Set(["clear"]),
     emotion: new Set(["clear"]),
+    parenthetical: new Set(["remove"]),
     "scene-ref": new Set(["clear", "remove", "append"]),
     delete: new Set(["force"]),
     extend: new Set(["clear", "json-value"]),
@@ -82,6 +90,8 @@ export const DO_BOOL_FLAGS = {
 export const DO_REPEAT_FLAGS = {
     alias: new Set(["add", "remove"]),
     "add-actor": new Set(["alias"]),
+    "scene-ref": new Set(["state"]),
+    insert: new Set(["state"]),
 };
 function pushFlag(flags, repeats, name, val) {
     if (repeats.has(name)) {
@@ -305,9 +315,37 @@ export function dialogueTemplate(f) {
 // consumes). `do` = the human/agent-friendly notation for those ops: no JSON,
 // no field-name guessing — the verbs you already type. Multipolar verbs
 // (delete/move/insert/merge/describe) pick their op by the address kind.
-export function lineToOp(verb, args, flags) {
+function repeatedDoFlag(raw) {
+    if (raw === undefined)
+        return [];
+    return Array.isArray(raw) ? raw.map(strOf) : [strOf(raw)];
+}
+function doInsertFlags(flags) {
+    return {
+        type: flags["type"],
+        content: flags["content"],
+        emotion: flags["emotion"],
+        parenthetical: flags["parenthetical"],
+        actionId: flags["action-id"],
+        at: flags["at"],
+        before: flags["before"],
+        after: flags["after"],
+        actor: flags["actor"],
+        speaker: flags["speaker"],
+        speakerState: flags["speaker-state"],
+        kind: flags["kind"],
+        label: flags["label"],
+        location: flags["location"],
+        time: flags["time"],
+        space: flags["space"],
+        sceneId: flags["scene-id"],
+        states: repeatedDoFlag(flags["state"]),
+    };
+}
+export function lineToOp(verb, args, flags, scriptVersion = 3) {
     const a0 = strOf(args[0]);
     const a1 = strOf(args[1]);
+    const parseAddress = (raw) => scriptVersion === 4 ? parseV4Address(raw) : parseAnyAddress(raw);
     switch (verb) {
         case "replace":
             return flags["regex"]
@@ -320,20 +358,52 @@ export function lineToOp(verb, args, flags) {
         case "transition":
             return { ...transitionTemplate(a1, { process: flags["process"], contrast: flags["contrast"], clear: Boolean(flags["clear"]) }), at: a0 };
         case "emotion":
+            if (scriptVersion === 4)
+                throw doErr("emotion belongs to Script v3; use parenthetical for Script v4");
             return { ...emotionTemplate({ emotion: args[1], clear: Boolean(flags["clear"]) }), at: a0 };
-        case "scene-ref":
+        case "parenthetical":
+            if (scriptVersion === 3)
+                throw doErr("parenthetical belongs to Script v4; use emotion for Script v3");
+            if (Boolean(flags["remove"]) === (flags["set"] !== undefined)) {
+                throw doErr("parenthetical needs exactly one of --set <text> or --remove");
+            }
+            return Boolean(flags["remove"])
+                ? { op: "action.parenthetical.remove", at: a0 }
+                : { op: "action.parenthetical.set", at: a0, parenthetical: strOf(flags["set"]) };
+        case "scene-ref": {
+            const sceneRefFlags = {
+                states: repeatedDoFlag(flags["state"]),
+                clear: Boolean(flags["clear"]),
+                remove: Boolean(flags["remove"]),
+                append: Boolean(flags["append"]),
+                occurrence: flags["occurrence"],
+            };
+            assertSceneRefCommandFlags(scriptVersion, sceneRefFlags);
+            if (scriptVersion === 4) {
+                return sceneRefFlags.remove
+                    ? { op: "scene.ref.remove", at: a0, target: a1 }
+                    : { op: "scene.ref.set", at: a0, target: a1, state_ids: sceneRefFlags.states };
+            }
             return {
                 ...contextTemplate(a1, {
-                    state: flags["state"],
-                    clear: Boolean(flags["clear"]),
-                    remove: Boolean(flags["remove"]),
-                    append: Boolean(flags["append"]),
-                    occurrence: flags["occurrence"],
+                    state: sceneRefFlags.states[0],
+                    clear: sceneRefFlags.clear,
+                    remove: sceneRefFlags.remove,
+                    append: sceneRefFlags.append,
+                    occurrence: sceneRefFlags.occurrence,
                 }),
                 at: a0,
             };
+        }
         case "dialogue":
-            return { ...dialogueTemplate({ actor: flags["actor"], kind: flags["kind"], label: flags["label"] }), at: a0 };
+            if (scriptVersion === 3 && flags["state"] !== undefined) {
+                throw doErr("dialogue --state belongs to Script v4");
+            }
+            return {
+                ...dialogueTemplate({ actor: flags["actor"], kind: flags["kind"], label: flags["label"] }),
+                ...(scriptVersion === 4 && flags["state"] !== undefined ? { state_id: flags["state"] } : {}),
+                at: a0,
+            };
         case "rename":
             return { op: "asset.rename", target: a0, name: a1 };
         case "role":
@@ -346,14 +416,15 @@ export function lineToOp(verb, args, flags) {
             if (args.length > 2)
                 throw doErr("synopsis text with spaces must be quoted");
             if (args.length === 1) {
-                if (/^ep_/.test(a0))
+                if (/^ep_/.test(a0) || /^ep[1-9A-HJ-NP-Za-km-z]{6}$/.test(a0)) {
                     throw doErr(`synopsis for ${a0} needs text`);
+                }
                 return { op: "meta.synopsis.set", synopsis: a0 };
             }
-            const addr = parseAnyAddress(a0);
+            const addr = parseAddress(a0);
             if (addr.kind !== "episode")
                 throw doErr(`synopsis target must be an episode id or omitted for global (${a0})`);
-            return { op: "episode.synopsis.set", episode_id: addr.episodeId, synopsis: a1 };
+            return { op: "episode.synopsis.set", episode_id: "id" in addr ? addr.id : addr.episodeId, synopsis: a1 };
         }
         case "alias": {
             const add = flags["add"] ?? [];
@@ -365,7 +436,7 @@ export function lineToOp(verb, args, flags) {
             throw doErr("alias needs --add <alias> or --remove <alias>");
         }
         case "describe": {
-            const addr = parseAnyAddress(a0);
+            const addr = parseAddress(a0);
             if (addr.kind === "state")
                 return { op: "state.describe", target: a0, description: a1 };
             if (addr.kind === "asset")
@@ -373,7 +444,8 @@ export function lineToOp(verb, args, flags) {
             throw doErr(`describe cannot operate on a ${addr.kind} address (${a0}); use an asset or asset/state target`);
         }
         case "extend": {
-            parseAnyAddress(a0); // early-validate (any kind is valid)
+            if (a0 !== "global")
+                parseAddress(a0);
             if (flags["clear"]) {
                 if (args.length >= 3)
                     throw doErr("extend --clear takes no value (drop --clear to set, or drop the value to delete)");
@@ -399,37 +471,52 @@ export function lineToOp(verb, args, flags) {
         case "state-delete":
             return { op: "state.delete", target: a0, strategy: flags["strategy"], replacement: flags["replacement"] };
         case "add-actor":
-            return { op: "actor.add", name: a0, role_type: flags["role"], description: flags["description"], aliases: flags["alias"] ?? undefined };
+            return { op: "actor.add", actor_id: flags["id"], name: a0, role_type: flags["role"], description: flags["description"], aliases: flags["alias"] ?? undefined };
         case "add-location":
-            return { op: "location.add", name: a0, description: flags["description"] };
+            return { op: "location.add", location_id: flags["id"], name: a0, description: flags["description"] };
         case "add-prop":
-            return { op: "prop.add", name: a0, description: flags["description"] };
+            return { op: "prop.add", prop_id: flags["id"], name: a0, description: flags["description"] };
         case "add-episode":
             return { op: "episode.add", title: flags["title"], episode_id: flags["id"] };
         case "importance":
             return { op: "importance.set", target: a0, importance: a1 };
         case "split":
-            return { op: "scene.split", at: a0, at_index: flags["at"], new_scene_id: flags["new-scene-id"] };
+            return scriptVersion === 4
+                ? { op: "scene.split", at: a0, at_action: flags["at"], new_scene_id: flags["new-scene-id"] }
+                : { op: "scene.split", at: a0, at_index: Number(flags["at"]), new_scene_id: flags["new-scene-id"] };
         case "delete": {
-            const addr = parseAnyAddress(a0);
+            const addr = parseAddress(a0);
             if (addr.kind === "action")
                 return { op: "action.delete", at: a0 };
             if (addr.kind === "scene")
                 return { op: "scene.delete", at: a0, force: Boolean(flags["force"]) };
+            if (addr.kind === "state")
+                return { op: "state.delete", target: a0, strategy: flags["strategy"], replacement: flags["replacement"] };
             if (addr.kind === "asset")
                 return { op: "asset.delete", target: a0, strategy: flags["strategy"], replacement: flags["replacement"] };
-            throw doErr(`delete cannot operate on a ${addr.kind} address (${a0}); episodes/states have no delete op`);
+            throw doErr(`delete cannot operate on a ${addr.kind} address (${a0})`);
         }
         case "move": {
-            const addr = parseAnyAddress(a0);
-            if (addr.kind === "scene")
-                return { op: "scene.move", at: a0, to: a1, at_index: flags["at"] };
-            if (addr.kind === "action")
-                return { op: "action.move", at: a0, to: a1 };
+            assertMoveCommandFlags(scriptVersion, {
+                at: flags["at"],
+                before: flags["before"],
+                after: flags["after"],
+            });
+            const addr = parseAddress(a0);
+            if (addr.kind === "scene") {
+                return scriptVersion === 4
+                    ? { op: "scene.move", at: a0, to: a1, before: flags["before"], after: flags["after"] }
+                    : { op: "scene.move", at: a0, to: a1, at_index: flags["at"] };
+            }
+            if (addr.kind === "action") {
+                return scriptVersion === 4
+                    ? { op: "action.move", at: a0, to: a1, before: flags["before"], after: flags["after"] }
+                    : { op: "action.move", at: a0, to: a1 };
+            }
             throw doErr(`move cannot operate on a ${addr.kind} address (${a0}); move an action or a scene`);
         }
         case "merge": {
-            const addr = parseAnyAddress(a0);
+            const addr = parseAddress(a0);
             if (addr.kind === "scene")
                 return { op: "scene.merge", from: a0, into: strOf(flags["into"]) };
             if (addr.kind === "asset")
@@ -437,12 +524,46 @@ export function lineToOp(verb, args, flags) {
             throw doErr(`merge cannot operate on a ${addr.kind} address (${a0}); merge two assets or two scenes`);
         }
         case "insert": {
-            const addr = parseAnyAddress(a0);
+            const addr = parseAddress(a0);
+            const insertFlags = doInsertFlags(flags);
             if (addr.kind === "episode") {
-                return { op: "scene.insert", at: a0, location: flags["location"], time: flags["time"], space: flags["space"], at_index: flags["at"], before: flags["before"], after: flags["after"], scene_id: flags["scene-id"] };
+                assertInsertCommandFlags(scriptVersion, "scene", insertFlags);
+                return {
+                    op: "scene.insert",
+                    at: a0,
+                    location: flags["location"],
+                    time: flags["time"],
+                    space: flags["space"],
+                    ...(scriptVersion === 4
+                        ? { location_state_ids: insertFlags.states, before: flags["before"], after: flags["after"] }
+                        : { at_index: flags["at"], before: flags["before"], after: flags["after"] }),
+                    scene_id: flags["scene-id"],
+                };
             }
             if (addr.kind === "scene") {
-                return { op: "action.insert", at: a0, type: flags["type"], content: flags["content"], at_index: flags["at"], before: flags["before"], after: flags["after"], actor_id: flags["actor"], speaker_id: flags["speaker"], kind: flags["kind"], label: flags["label"], emotion: flags["emotion"] };
+                assertInsertCommandFlags(scriptVersion, "action", insertFlags);
+                return {
+                    op: "action.insert",
+                    at: a0,
+                    type: flags["type"],
+                    content: flags["content"],
+                    before: flags["before"],
+                    after: flags["after"],
+                    actor_id: flags["actor"],
+                    kind: flags["kind"],
+                    label: flags["label"],
+                    ...(scriptVersion === 4
+                        ? {
+                            action_id: flags["action-id"],
+                            state_id: flags["speaker-state"],
+                            parenthetical: flags["parenthetical"],
+                        }
+                        : {
+                            at_index: flags["at"],
+                            speaker_id: flags["speaker"],
+                            emotion: flags["emotion"],
+                        }),
+                };
             }
             throw doErr(`insert needs ep_NNN (scene insert) or ep_NNN/scn_NNN (action insert), got a ${addr.kind} address (${a0})`);
         }
@@ -519,22 +640,355 @@ export const SKIPPABLE_EDIT_CODES = new Set([
     "FROM_TEXT_NOT_FOUND",
     "OVERLAP_DIALOGUE_UNSUPPORTED",
 ]);
+export function applyPatchOperationsForSession(session, source, operations) {
+    return applyVersionedMutations(session.version, session.script, source, operations);
+}
+function v4Counts(script) {
+    return {
+        episodes: script.episodes.length,
+        scenes: script.episodes.reduce((sum, episode) => sum + episode.scenes.length, 0),
+        actions: script.episodes.reduce((sum, episode) => sum + episode.scenes.reduce((sceneSum, scene) => sceneSum + scene.actions.length, 0), 0),
+        actors: script.actors.length,
+        locations: script.locations.length,
+        props: script.props.length,
+        states: [...script.actors, ...script.locations, ...script.props]
+            .reduce((sum, asset) => sum + asset.states.length, 0),
+    };
+}
+function v4CanonicalIds(script) {
+    return [
+        ...script.actors.flatMap((asset) => [
+            asset.actor_id,
+            ...asset.states.map((state) => `${asset.actor_id}/${state.state_id}`),
+        ]),
+        ...script.locations.flatMap((asset) => [
+            asset.location_id,
+            ...asset.states.map((state) => `${asset.location_id}/${state.state_id}`),
+        ]),
+        ...script.props.flatMap((asset) => [
+            asset.prop_id,
+            ...asset.states.map((state) => `${asset.prop_id}/${state.state_id}`),
+        ]),
+        ...script.episodes.flatMap((episode) => [
+            episode.episode_id,
+            ...episode.scenes.flatMap((scene) => [
+                scene.scene_id,
+                ...scene.actions.map((action) => action.action_id),
+            ]),
+        ]),
+    ];
+}
+function orderedIntersection(left, right) {
+    return left.filter((value) => right.has(value));
+}
+function v4OperationTargets(operation) {
+    const values = [];
+    const isIdentity = (value) => {
+        if (value === "global")
+            return true;
+        if (isV4Id("episode", value)
+            || isV4Id("scene", value)
+            || isV4Id("action", value)
+            || isV4Id("actor", value)
+            || isV4Id("location", value)
+            || isV4Id("prop", value))
+            return true;
+        const slash = value.indexOf("/");
+        if (slash < 0 || slash !== value.lastIndexOf("/"))
+            return false;
+        const owner = value.slice(0, slash);
+        const state = value.slice(slash + 1);
+        return (isV4Id("actor", owner)
+            || isV4Id("location", owner)
+            || isV4Id("prop", owner)) && (state === "default" || isV4Id("state", state));
+    };
+    const add = (value) => {
+        if (typeof value !== "string" || value.trim() === "")
+            return;
+        const normalized = value.trim();
+        if (isIdentity(normalized))
+            values.push(normalized);
+    };
+    const first = (...fields) => {
+        for (const field of fields) {
+            const value = operation[field];
+            if (typeof value === "string" && value.trim() !== "")
+                return value;
+        }
+        return undefined;
+    };
+    const addState = (ownerValue, stateValue) => {
+        const owner = strOf(ownerValue).trim();
+        const state = strOf(stateValue).trim();
+        if (owner && state)
+            add(`${owner}/${state}`);
+    };
+    const addStates = (ownerValue, stateValues) => {
+        if (!Array.isArray(stateValues))
+            return;
+        stateValues.forEach((state) => addState(ownerValue, state));
+    };
+    const addPlacement = () => {
+        add(operation["before"]);
+        add(operation["after"]);
+    };
+    const kind = strOf(operation["op"]);
+    switch (kind) {
+        case "action.parenthetical.set":
+        case "action.parenthetical.remove":
+        case "action.content.replace":
+        case "action.content.regex-replace":
+        case "action.type.set":
+        case "action.delete":
+        case "action.transition.clear":
+            add(operation["at"]);
+            break;
+        case "action.actor.set":
+        case "dialogue.speaker.set":
+            add(operation["at"]);
+            add(operation["actor_id"]);
+            addState(operation["actor_id"], operation["state_id"]);
+            break;
+        case "action.insert":
+            add(operation["at"]);
+            add(first("action_id", "id"));
+            add(operation["actor_id"]);
+            addState(operation["actor_id"], operation["state_id"]);
+            addPlacement();
+            break;
+        case "action.move":
+            add(operation["at"]);
+            add(operation["to"]);
+            addPlacement();
+            break;
+        case "action.transition.set":
+            add(operation["at"]);
+            add(operation["target"]);
+            break;
+        case "scene.ref.set":
+        case "scene.ref.remove":
+            add(operation["at"]);
+            add(operation["target"]);
+            addStates(operation["target"], operation["state_ids"]);
+            break;
+        case "actor.add":
+            add(first("actor_id", "id"));
+            break;
+        case "location.add":
+            add(first("location_id", "id"));
+            break;
+        case "prop.add":
+            add(first("prop_id", "id"));
+            break;
+        case "state.add": {
+            const owner = operation["target"];
+            add(owner);
+            addState(owner, first("state_id", "id"));
+            break;
+        }
+        case "state.rename":
+        case "state.describe":
+            add(operation["target"]);
+            break;
+        case "state.delete": {
+            const target = strOf(operation["target"]).trim();
+            add(target);
+            const slash = target.indexOf("/");
+            if (slash > 0)
+                addState(target.slice(0, slash), operation["replacement"]);
+            break;
+        }
+        case "asset.rename":
+        case "asset.describe":
+        case "asset.role.set":
+        case "asset.alias.set":
+        case "asset.alias.add":
+        case "asset.alias.remove":
+        case "importance.set":
+            add(operation["target"]);
+            break;
+        case "asset.merge":
+            add(first("from", "source"));
+            add(first("into", "target"));
+            break;
+        case "asset.delete":
+            add(operation["target"]);
+            if (operation["strategy"] === "replace")
+                add(operation["replacement"]);
+            break;
+        case "episode.add":
+            add(first("episode_id", "id"));
+            break;
+        case "episode.synopsis.set":
+            add(first("episode_id", "target", "at"));
+            break;
+        case "meta.worldview.set":
+        case "meta.synopsis.set":
+            add("global");
+            break;
+        case "scene.insert": {
+            const location = first("location", "location_id");
+            add(first("at", "episode_id"));
+            add(first("scene_id", "id"));
+            add(location);
+            addStates(location, operation["location_state_ids"]);
+            addPlacement();
+            break;
+        }
+        case "scene.move":
+            add(operation["at"]);
+            add(operation["to"]);
+            addPlacement();
+            break;
+        case "scene.delete":
+            add(operation["at"]);
+            break;
+        case "scene.split":
+            add(operation["at"]);
+            add(first("at_action", "action_id"));
+            add(first("new_scene_id", "scene_id"));
+            break;
+        case "scene.merge":
+            add(operation["from"]);
+            add(operation["into"]);
+            break;
+        case "extend.set":
+        case "extend.clear":
+            add(operation["at"]);
+            break;
+        default:
+            throw new Error(`V4 plan target mapping is missing for operation ${kind}`);
+    }
+    return [...new Set(values)];
+}
+export function buildV4MutationPlan(session, operations, options = {}) {
+    if (session.version !== 4) {
+        throw new CliError("SCRIPT PLAN BLOCKED: wrong version", "A v4 mutation plan requires Script v4.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "V4_PLAN_VERSION_INVALID",
+            received: [`Script v${session.version}`],
+        });
+    }
+    const original = requireScriptV4(session.script);
+    const proposed = structuredClone(original);
+    const originalIds = v4CanonicalIds(original);
+    const applied = [];
+    const steps = [];
+    for (const [index, operation] of operations.entries()) {
+        const beforeIds = v4CanonicalIds(proposed);
+        const beforeSet = new Set(beforeIds);
+        const before = v4Counts(proposed);
+        let status = "applied";
+        try {
+            applied.push(...applyPatchOperationsV4(proposed, [operation]));
+        }
+        catch (error) {
+            if (error instanceof CliError
+                && error.errorCode
+                && options.skipCodes?.has(error.errorCode)) {
+                status = "skipped";
+            }
+            else {
+                throw error;
+            }
+        }
+        const afterIds = v4CanonicalIds(proposed);
+        const afterSet = new Set(afterIds);
+        steps.push({
+            index,
+            operation,
+            targets: v4OperationTargets(operation),
+            status,
+            before,
+            after: v4Counts(proposed),
+            created_ids: afterIds.filter((id) => !beforeSet.has(id)),
+            removed_ids: beforeIds.filter((id) => !afterSet.has(id)),
+            retained_ids: orderedIntersection(beforeIds, afterSet),
+        });
+    }
+    const proposedIds = v4CanonicalIds(proposed);
+    const originalSet = new Set(originalIds);
+    const proposedSet = new Set(proposedIds);
+    const targets = [...new Set(steps.flatMap((step) => step.targets))];
+    const touched = new Set([
+        ...targets,
+        ...steps.flatMap((step) => step.created_ids),
+        ...steps.flatMap((step) => step.removed_ids),
+    ]);
+    const plan = {
+        version: 1,
+        script_version: 4,
+        baseline: session.baselineHash,
+        operations,
+        targets,
+        steps,
+        before: v4Counts(original),
+        after: v4Counts(proposed),
+        created_ids: proposedIds.filter((id) => !originalSet.has(id)),
+        removed_ids: originalIds.filter((id) => !proposedSet.has(id)),
+        retained_ids: orderedIntersection(originalIds, proposedSet),
+        untouched_ids: orderedIntersection(originalIds, proposedSet)
+            .filter((id) => !touched.has(id)),
+        validation: validateScriptV4(proposed),
+    };
+    return {
+        plan,
+        digest: `sha256:${sha256Text(JSON.stringify(sortDeep(plan)))}`,
+        applied,
+    };
+}
+const V4_PLANNED_ID_FIELDS = {
+    "actor.add": "actor_id",
+    "location.add": "location_id",
+    "prop.add": "prop_id",
+    "state.add": "state_id",
+    "episode.add": "episode_id",
+    "scene.insert": "scene_id",
+    "scene.split": "new_scene_id",
+    "action.insert": "action_id",
+};
+export function assertV4PlanHasExplicitNewIds(operations) {
+    for (const operation of operations) {
+        const kind = strOf(operation["op"]);
+        const field = V4_PLANNED_ID_FIELDS[kind];
+        if (!field || strOf(operation[field]).trim())
+            continue;
+        const idKind = field === "new_scene_id" ? "scene" : field.replace(/_id$/, "");
+        throw new CliError("SCRIPT V4 PLAN BLOCKED: new ID missing", "Planned creation operations require an explicit candidate ID.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "V4_PLAN_ID_REQUIRED",
+            required: [`${kind}.${field}`],
+            received: [`${kind}.${field}=<missing>`],
+            nextSteps: [`Generate a candidate with \`scriptctl ids --kind ${idKind} --count 1\`, then include it in the operation.`],
+        });
+    }
+}
 // ---------------------------------------------------------------------------
 // Single-op helpers
 // ---------------------------------------------------------------------------
-export async function applySingleScriptOp(opts, op) {
+export async function applySingleScriptOpToSession(session, opts, op) {
+    const plan = strOf(opts["plan"]).trim();
+    if (plan) {
+        throw new CliError("SCRIPT OP BLOCKED: --plan is not applicable", "Single-point writes do not use plan digests.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MULTI_PLAN_USAGE_INVALID",
+            received: [plan],
+            nextSteps: ["Remove --plan from this single-point edit."],
+        });
+    }
+    return applyScriptOpsToSession(session, opts, [op]);
+}
+export async function applyScriptOpsToSession(session, opts, operations) {
     const workspace = strOf(opts["workspace_path"] || "workspace");
-    const session = await loadScriptForEdit(opts);
-    const script = session.script;
-    const applied = applyPatchOperations(script, scriptSourceText(workspace), [op]);
-    const opName = applied[0] ?? strOf(op["op"]);
+    const applied = applyPatchOperationsForSession(session, scriptSourceText(workspace), operations);
+    const opName = applied.length === 1 ? applied[0] : "script.ops";
     const [newRevision, idempotent] = await saveScriptSession(session, opts, opName);
     const validation = validateSession(session);
     await syncValidationResult(session, validation, newRevision);
     const passed = Boolean(validation["passed"]);
     // One outcome line: what changed + revision (remote) + validation verdict.
     const rev = session.remote ? `; rev ${newRevision}` : "";
-    const resultLine = `${opName} applied${rev}; validation ${passed ? "passed" : "needs repair"}`;
+    const resultLine = `${applied.join(", ")} applied${rev}; validation ${passed ? "passed" : "needs repair"}`;
     const report = {
         title: passed ? "SCRIPT OP APPLIED" : "SCRIPT OP APPLIED: Validation needs repair",
         op: opName,
@@ -549,6 +1003,10 @@ export async function applySingleScriptOp(opts, op) {
     };
     return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
 }
+export async function applySingleScriptOp(opts, op) {
+    const session = await loadScriptForEdit(opts);
+    return applySingleScriptOpToSession(session, opts, op);
+}
 export function summarizeScriptOp(_script, op) {
     const kind = strOf(op["op"]);
     if (kind === "actor.add")
@@ -593,50 +1051,116 @@ export function regexPattern(raw) {
 // reports the blast radius and writes nothing; --apply commits. Per-action
 // "no match here / overlap dialogue" errors are skipped (a sweep); anything else
 // aborts the whole edit before any write. Shared by every selector-capable verb.
-export async function applySelectorEdits(opts, template, verbLabel) {
+export async function applySelectorEditsToSession(session, opts, template, verbLabel) {
     const workspace = strOf(opts["workspace_path"] || "workspace");
     const apply = Boolean(opts["apply"]);
     const opName = strOf(template["op"]);
-    const session = await loadScriptForEdit(opts);
     const script = session.script;
-    const targets = resolveActionTargets(script, opts);
-    const refs = targets.map((t) => `${t.epId}/${t.sceneId}#${t.idx}`);
+    const refs = session.version === 3
+        ? resolveActionTargets(script, opts).map((target) => `${target.epId}/${target.sceneId}#${target.idx}`)
+        : resolveActionTargetsV4(requireScriptV4(script), opts, { allowOrdinals: false })
+            .map((target) => target.action.action_id);
+    const operations = refs.map((ref) => ({ ...template, at: ref }));
+    const multiV4 = session.version === 4 && refs.length > 1;
+    const planned = multiV4
+        ? buildV4MutationPlan(session, operations, { skipCodes: SKIPPABLE_EDIT_CODES })
+        : null;
+    const planDigest = planned?.digest ?? null;
+    const suppliedPlan = strOf(opts["plan"]).trim();
+    if (suppliedPlan && (!multiV4 || !apply)) {
+        throw new CliError("SELECTOR EDIT BLOCKED: --plan is not applicable", "A plan digest is only accepted for a v4 multi-target apply.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MULTI_PLAN_USAGE_INVALID",
+            received: [suppliedPlan],
+            nextSteps: ["Remove --plan, or apply the same v4 multi-target selection that produced the digest."],
+        });
+    }
+    if (multiV4 && apply && !suppliedPlan) {
+        throw new CliError("SELECTOR EDIT BLOCKED: plan required", "A v4 multi-target write requires its dry-run plan digest.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MULTI_PLAN_REQUIRED",
+            required: [planDigest ?? ""],
+            received: ["<missing>"],
+            nextSteps: ["Run the same command without --apply, review the full plan, then retry with `--apply --plan <digest>`."],
+        });
+    }
+    if (multiV4 && apply && suppliedPlan !== planDigest) {
+        throw new CliError("SELECTOR EDIT BLOCKED: plan mismatch", "The supplied digest does not match the current targets and operations.", {
+            exitCode: EXIT_INPUT,
+            errorCode: "MULTI_PLAN_MISMATCH",
+            required: [planDigest ?? ""],
+            received: [suppliedPlan],
+            nextSteps: ["Review the newly computed dry-run plan, then apply its exact digest."],
+        });
+    }
     const source = scriptSourceText(workspace);
-    let applied = 0;
-    let skipped = 0;
-    for (const ref of refs) {
-        try {
-            applyPatchOperations(script, source, [{ ...template, at: ref }]);
-            applied += 1;
+    let applied = planned?.plan.steps.filter((step) => step.status === "applied").length ?? 0;
+    let skipped = planned?.plan.steps.filter((step) => step.status === "skipped").length ?? 0;
+    if (!planned) {
+        for (const ref of refs) {
+            try {
+                applyPatchOperationsForSession(session, source, [{ ...template, at: ref }]);
+                applied += 1;
+            }
+            catch (err) {
+                if (err instanceof CliError && err.errorCode && SKIPPABLE_EDIT_CODES.has(err.errorCode)) {
+                    skipped += 1;
+                    continue;
+                }
+                throw err;
+            }
         }
-        catch (err) {
-            if (err instanceof CliError && err.errorCode && SKIPPABLE_EDIT_CODES.has(err.errorCode)) {
-                skipped += 1;
-                continue;
+    }
+    else if (apply) {
+        for (const step of planned.plan.steps) {
+            if (step.status === "applied") {
+                applyPatchOperationsForSession(session, source, [step.operation]);
             }
-            throw err;
         }
     }
-    const sample = refs.slice(0, 12);
+    const displayedRefs = multiV4 ? refs : refs.slice(0, 12);
     const blast = [
         `verb: ${verbLabel} (${opName})`,
         `matched: ${refs.length} action(s)`,
         `${apply ? "applied" : "would-apply"}: ${applied}`,
         `${apply ? "skipped" : "would-skip"}: ${skipped}`,
-        ...(sample.length ? [`targets: ${sample.join(", ")}${refs.length > sample.length ? ` … (+${refs.length - sample.length} more)` : ""}`] : []),
+        ...(displayedRefs.length ? [`targets: ${displayedRefs.join(", ")}${refs.length > displayedRefs.length ? ` … (+${refs.length - displayedRefs.length} more)` : ""}`] : []),
+        ...(planDigest ? [`plan_digest: ${planDigest}`] : []),
     ];
     if (!apply) {
-        const validation = validateSession(session);
-        const passed = Boolean(validation["passed"]);
+        const legacyValidation = planned ? null : validateSession(session);
+        const passed = planned
+            ? planned.plan.validation.ok
+            : Boolean(legacyValidation?.["passed"]);
+        const plannedIssueLines = planned
+            ? [...planned.plan.validation.errors, ...planned.plan.validation.warnings]
+                .map((issue) => `${issue.path}: ${issue.code} - ${issue.message}`)
+            : null;
+        const legacyIssueLines = legacyValidation === null
+            ? []
+            : summarizeIssues(asList(legacyValidation["issues"]));
         const report = {
             title: refs.length === 0 ? "SELECTOR EDIT DRY-RUN: no match" : "SELECTOR EDIT DRY-RUN (no write)",
             op: `${opName}.dry-run`,
             changed: false,
             result: [...blast, `validation: ${passed ? "would pass" : "would need repair"}; dry-run, no write`],
-            warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
-            issues: summarizeIssues(asList(validation["issues"])),
+            warnings: passed
+                ? []
+                : plannedIssueLines ?? legacyIssueLines,
+            issues: plannedIssueLines ?? legacyIssueLines,
             artifacts: [session.artifactLabel],
-            next: [refs.length === 0 ? "Widen the selection (--in / --grep / predicates)." : "Re-run with --apply to commit."],
+            ...(planDigest ? {
+                baseline: session.baselineHash,
+                plan_digest: planDigest,
+                operations,
+                targets: refs,
+                plan: planned?.plan,
+            } : {}),
+            next: [refs.length === 0
+                    ? "Widen the selection (--in / --grep / predicates)."
+                    : planDigest
+                        ? `Re-run with --apply --plan ${planDigest} to commit this exact plan.`
+                        : "Re-run with --apply to commit."],
         };
         return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
     }
@@ -664,10 +1188,21 @@ export async function applySelectorEdits(opts, template, verbLabel) {
         warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
         issues: summarizeIssues(asList(validation["issues"])),
         artifacts: [session.artifactLabel],
+        ...(planDigest ? {
+            baseline: session.baselineHash,
+            plan_digest: planDigest,
+            operations,
+            targets: refs,
+            plan: planned?.plan,
+        } : {}),
         next: passed ? undefined : ["Inspect issues and apply another edit."],
     };
     return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
 }
+export async function applySelectorEdits(opts, template, verbLabel) {
+    const session = await loadScriptForEdit(opts);
+    return applySelectorEditsToSession(session, opts, template, verbLabel);
+}
 export { sortDeep };
 // ===========================================================================
 // 0.6.0 plural-noun query commands (replace `commandScriptInspect --target X`)
@@ -735,7 +1270,10 @@ export function buildGrepMatcher(raw) {
         }
         try {
             const re = new RegExp(pattern, m[2]);
-            return (hay) => re.test(hay);
+            return (hay) => {
+                re.lastIndex = 0;
+                return re.test(hay);
+            };
         }
         catch {
             // Malformed regex — treat as literal.
@@ -854,7 +1392,7 @@ export function resolveActionTargets(script, opts) {
 }
 // Whether a selection in `opts` has any filter at all (scope or predicate).
 export function selectionHasAnyFilter(opts) {
-    return Boolean(!parseInSelector(strOf(opts["in"])).isEmpty ||
+    return Boolean(strOf(opts["in"]).trim() ||
         strOf(opts["grep"]) || strOf(opts["type"]).trim() || strOf(opts["actor"]).trim() ||
         strOf(opts["has"]).trim());
 }
@@ -999,7 +1537,7 @@ export function splitSpeakerList(raw) {
 }
 export function blankCreateReport(session, validation, idempotent) {
     const passed = Boolean(validation["passed"]);
-    const resultLines = ["created: blank script (schema v2)", `validation: ${passed ? "passed" : "needs repair"}`];
+    const resultLines = [`created: blank script (Script v${session.version})`, `validation: ${passed ? "passed" : "needs repair"}`];
     if (session.remote) {
         resultLines.push(`revision: ${session.revision}`);
         if (idempotent !== null)