@lingjingai/scriptctl 0.49.16 → 0.51.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)) {
@@ -145,12 +155,11 @@ export function parseDoLine(tokens) {
     return { verb, args, flags };
 }
 export function doErr(detail) {
-    return new CliError("DO BLOCKED: line invalid", detail, {
+    return new CliError(detail, {
         exitCode: EXIT_USAGE,
-        required: ["a valid <verb> ...args... line"],
-        received: [detail],
-        nextSteps: ["Each line is a scriptctl verb minus the leading `scriptctl`; see `scriptctl do --help`."],
         errorCode: "DO_LINE_INVALID",
+        hint: "Each line is a scriptctl verb minus the leading `scriptctl`; see `scriptctl do --help`.",
+        data: { expected: ["a valid <verb> ...args... line"], actual: [detail] },
     });
 }
 // ---- shared op-template builders ------------------------------------------
@@ -162,36 +171,46 @@ export function stateChangeTemplate(target, f) {
     const toSet = f.to !== undefined;
     const clearSet = Boolean(f.clear);
     if (toSet && clearSet) {
-        throw new CliError("VERB BLOCKED: state-change flags mutually exclusive", "state-change: --to and --clear are mutually exclusive.", {
-            exitCode: EXIT_USAGE, required: ["exactly one of --to <state> / --clear"], received: ["--to", "--clear"],
-            nextSteps: ["Pick one and retry."], errorCode: "STATE_CHANGE_FLAG_CONFLICT",
+        throw new CliError("state-change: --to and --clear are mutually exclusive.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "STATE_CHANGE_FLAG_CONFLICT",
+            hint: "Pick one and retry.",
+            data: { expected: ["exactly one of --to <state> / --clear"], actual: ["--to", "--clear"] },
         });
     }
     if (!toSet && !clearSet) {
-        throw new CliError("VERB BLOCKED: state-change flag missing", "state-change: must specify --to <state> or --clear.", {
-            exitCode: EXIT_USAGE, required: ["one of --to <state> / --clear"], received: ["<missing>"],
-            nextSteps: ["Pick exactly one flag."], errorCode: "STATE_CHANGE_FLAG_MISSING",
+        throw new CliError("state-change: must specify --to <state> or --clear.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "STATE_CHANGE_FLAG_MISSING",
+            hint: "Pick exactly one flag.",
+            data: { expected: ["one of --to <state> / --clear"], actual: ["<missing>"] },
         });
     }
     // v3 has no per-action state_changes; state lives on scene.ref.* only.
-    throw new CliError("VERB BLOCKED: state-change removed", "state-change was removed in v3; set a scene ref's state instead.", {
-        exitCode: EXIT_USAGE, required: ["scene-ref state edit"], received: ["state-change"],
-        nextSteps: ["Use `scene-ref <ep/scn> <kind:id> --state <state_id>` (op scene.ref.set)."], errorCode: "STATE_CHANGE_REMOVED",
+    throw new CliError("state-change was removed in v3; set a scene ref's state instead.", {
+        exitCode: EXIT_USAGE,
+        errorCode: "STATE_CHANGE_REMOVED",
+        hint: "Use `scene-ref <ep/scn> <kind:id> --state <state_id>` (op scene.ref.set).",
+        data: { expected: ["scene-ref state edit"], actual: ["state-change"] },
     });
 }
 export function transitionTemplate(target, f) {
     const setBoth = f.process !== undefined || f.contrast !== undefined;
     const clearSet = Boolean(f.clear);
     if (setBoth && clearSet) {
-        throw new CliError("VERB BLOCKED: transition flags mutually exclusive", "transition: --clear is mutually exclusive with --process/--contrast.", {
-            exitCode: EXIT_USAGE, required: ["either --clear, or --process + --contrast"], received: ["--clear", "--process/--contrast"],
-            nextSteps: ["Pick one mode and retry."], errorCode: "TRANSITION_FLAG_CONFLICT",
+        throw new CliError("transition: --clear is mutually exclusive with --process/--contrast.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "TRANSITION_FLAG_CONFLICT",
+            hint: "Pick one mode and retry.",
+            data: { expected: ["either --clear, or --process + --contrast"], actual: ["--clear", "--process/--contrast"] },
         });
     }
     if (!setBoth && !clearSet) {
-        throw new CliError("VERB BLOCKED: transition flag missing", "transition: must specify --process/--contrast or --clear.", {
-            exitCode: EXIT_USAGE, required: ["--process + --contrast, or --clear"], received: ["<missing>"],
-            nextSteps: ["Pick exactly one mode."], errorCode: "TRANSITION_FLAG_MISSING",
+        throw new CliError("transition: must specify --process/--contrast or --clear.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "TRANSITION_FLAG_MISSING",
+            hint: "Pick exactly one mode.",
+            data: { expected: ["--process + --contrast, or --clear"], actual: ["<missing>"] },
         });
     }
     return clearSet
@@ -202,15 +221,19 @@ export function emotionTemplate(f) {
     const emotionSet = f.emotion !== undefined;
     const clearSet = Boolean(f.clear);
     if (emotionSet && clearSet) {
-        throw new CliError("VERB BLOCKED: emotion flags mutually exclusive", "emotion: value and --clear are mutually exclusive.", {
-            exitCode: EXIT_USAGE, required: ["either <emotion>, or --clear"], received: ["<emotion>", "--clear"],
-            nextSteps: ["Pick one mode and retry."], errorCode: "EMOTION_FLAG_CONFLICT",
+        throw new CliError("emotion: value and --clear are mutually exclusive.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "EMOTION_FLAG_CONFLICT",
+            hint: "Pick one mode and retry.",
+            data: { expected: ["either <emotion>, or --clear"], actual: ["<emotion>", "--clear"] },
         });
     }
     if (!emotionSet && !clearSet) {
-        throw new CliError("VERB BLOCKED: emotion value missing", "emotion: must specify <emotion> or --clear.", {
-            exitCode: EXIT_USAGE, required: ["<emotion>, or --clear"], received: ["<missing>"],
-            nextSteps: ["Pass an emotion label, or use --clear."], errorCode: "EMOTION_VALUE_MISSING",
+        throw new CliError("emotion: must specify <emotion> or --clear.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "EMOTION_VALUE_MISSING",
+            hint: "Pass an emotion label, or use --clear.",
+            data: { expected: ["<emotion>, or --clear"], actual: ["<missing>"] },
         });
     }
     return clearSet
@@ -223,9 +246,11 @@ export function contextTemplate(target, f) {
     const removeSet = Boolean(f.remove);
     const n = (stateSet ? 1 : 0) + (clearSet ? 1 : 0) + (removeSet ? 1 : 0);
     if (n === 0) {
-        throw new CliError("VERB BLOCKED: context flag missing", "context: must specify --state X, --clear, or --remove.", {
-            exitCode: EXIT_USAGE, required: ["one of --state <state_id> / --clear / --remove"], received: ["<missing>"],
-            nextSteps: ["Pick exactly one flag."], errorCode: "CONTEXT_FLAG_MISSING",
+        throw new CliError("context: must specify --state X, --clear, or --remove.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "CONTEXT_FLAG_MISSING",
+            hint: "Pick exactly one flag.",
+            data: { expected: ["one of --state <state_id> / --clear / --remove"], actual: ["<missing>"] },
         });
     }
     if (n > 1) {
@@ -236,30 +261,30 @@ export function contextTemplate(target, f) {
             passed.push("--clear");
         if (removeSet)
             passed.push("--remove");
-        throw new CliError("VERB BLOCKED: context flags mutually exclusive", "context: --state / --clear / --remove are mutually exclusive.", {
-            exitCode: EXIT_USAGE, required: ["exactly one of --state / --clear / --remove"], received: passed,
-            nextSteps: ["Pick one and retry."], errorCode: "CONTEXT_FLAG_CONFLICT",
+        throw new CliError("context: --state / --clear / --remove are mutually exclusive.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "CONTEXT_FLAG_CONFLICT",
+            hint: "Pick one and retry.",
+            data: { expected: ["exactly one of --state / --clear / --remove"], actual: passed },
         });
     }
     const append = Boolean(f.append);
     const occurrenceRaw = strOf(f.occurrence).trim();
     const occurrence = occurrenceRaw ? Number(occurrenceRaw) : undefined;
     if (occurrence !== undefined && (!Number.isInteger(occurrence) || occurrence < 1)) {
-        throw new CliError("VERB BLOCKED: scene-ref occurrence invalid", "scene-ref: --occurrence must be a positive integer.", {
+        throw new CliError("scene-ref: --occurrence must be a positive integer.", {
             exitCode: EXIT_USAGE,
-            required: ["--occurrence <positive integer> (1-based)"],
-            received: [occurrenceRaw],
-            nextSteps: ["Use 1 for the first matching scene ref, 2 for the second, and so on."],
             errorCode: "SCENE_REF_OCCURRENCE_INVALID",
+            hint: "Use 1 for the first matching scene ref, 2 for the second, and so on.",
+            data: { expected: ["--occurrence <positive integer> (1-based)"], actual: [occurrenceRaw] },
         });
     }
     if (append && (!stateSet || occurrence !== undefined)) {
-        throw new CliError("VERB BLOCKED: scene-ref append flags invalid", "scene-ref: --append requires --state and cannot be combined with --occurrence.", {
+        throw new CliError("scene-ref: --append requires --state and cannot be combined with --occurrence.", {
             exitCode: EXIT_USAGE,
-            required: ["--state <state_id> --append"],
-            received: [append ? "--append" : "", occurrence !== undefined ? "--occurrence" : "", clearSet ? "--clear" : "", removeSet ? "--remove" : ""].filter(Boolean),
-            nextSteps: ["Append a new actor ref with --state <state_id> --append, or target an existing ref with --occurrence <n>."],
             errorCode: "SCENE_REF_APPEND_FLAG_CONFLICT",
+            hint: "Append a new actor ref with --state <state_id> --append, or target an existing ref with --occurrence <n>.",
+            data: { expected: ["--state <state_id> --append"], actual: [append ? "--append" : "", occurrence !== undefined ? "--occurrence" : "", clearSet ? "--clear" : "", removeSet ? "--remove" : ""].filter(Boolean) },
         });
     }
     if (removeSet)
@@ -275,39 +300,67 @@ export function dialogueTemplate(f) {
     const speakerKind = strOf(f.kind).trim();
     const label = strOf(f.label).trim();
     if (actorId && speakerKind) {
-        throw new CliError("VERB BLOCKED: dialogue speaker ambiguous", "dialogue: --actor and --kind are mutually exclusive.", {
+        throw new CliError("dialogue: --actor and --kind are mutually exclusive.", {
             exitCode: EXIT_USAGE,
-            required: ["exactly one of --actor <actor_id> or --kind <non-actor kind>"],
-            received: ["--actor", "--kind"],
-            nextSteps: ["Keep --actor for a character, or --kind for a non-actor source."],
             errorCode: "SPEAKER_AMBIGUOUS",
+            hint: "Keep --actor for a character, or --kind for a non-actor source.",
+            data: { expected: ["exactly one of --actor <actor_id> or --kind <non-actor kind>"], actual: ["--actor", "--kind"] },
         });
     }
     if (actorId && label) {
-        throw new CliError("VERB BLOCKED: dialogue speaker label misplaced", "dialogue: --label is only valid with --kind.", {
+        throw new CliError("dialogue: --label is only valid with --kind.", {
             exitCode: EXIT_USAGE,
-            required: ["omit --label with --actor, or pair --label with --kind"],
-            received: ["--actor", "--label"],
-            nextSteps: ["Remove --label for an actor line, or use --kind for a labeled non-actor source."],
             errorCode: "SPEAKER_LABEL_WITHOUT_KIND",
+            hint: "Remove --label for an actor line, or use --kind for a labeled non-actor source.",
+            data: { expected: ["omit --label with --actor, or pair --label with --kind"], actual: ["--actor", "--label"] },
         });
     }
     if (actorId)
         return { op: "dialogue.speaker.set", actor_id: actorId };
     if (speakerKind)
         return { op: "dialogue.speaker.set", kind: speakerKind, label: label || undefined };
-    throw new CliError("VERB BLOCKED: dialogue speaker missing", "dialogue: pass --actor <id> or --kind <system|broadcast|offscreen|group>.", {
-        exitCode: EXIT_USAGE, required: ["--actor <actor_id> or --kind <non-actor kind>"], received: ["<missing>"],
-        nextSteps: ["Set --actor for an actor line, or --kind for a non-actor line."], errorCode: "DIALOGUE_SPEAKER_MISSING",
+    throw new CliError("dialogue: pass --actor <id> or --kind <system|broadcast|offscreen|group>.", {
+        exitCode: EXIT_USAGE,
+        errorCode: "DIALOGUE_SPEAKER_MISSING",
+        hint: "Set --actor for an actor line, or --kind for a non-actor line.",
+        data: { expected: ["--actor <actor_id> or --kind <non-actor kind>"], actual: ["<missing>"] },
     });
 }
 // Translate one parsed verb line into a patch op dict (the SAME ops `patch`
 // 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 +373,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 +431,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 +451,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 +459,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 +486,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 +539,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,65 +655,402 @@ 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("A v4 mutation plan requires Script v4.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "V4_PLAN_VERSION_INVALID",
+            data: { actual: [`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("Planned creation operations require an explicit candidate ID.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "V4_PLAN_ID_REQUIRED",
+            hint: `Generate a candidate with \`scriptctl ids --kind ${idKind} --count 1\`, then include it in the operation.`,
+            data: { expected: [`${kind}.${field}`], actual: [`${kind}.${field}=<missing>`] },
+        });
+    }
+}
 // ---------------------------------------------------------------------------
 // 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("Single-point writes do not use plan digests.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MULTI_PLAN_USAGE_INVALID",
+            hint: "Remove --plan from this single-point edit.",
+            data: { actual: [plan] },
+        });
+    }
+    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 issues = summarizeIssues(asList(validation["issues"]));
     const report = {
-        title: passed ? "SCRIPT OP APPLIED" : "SCRIPT OP APPLIED: Validation needs repair",
-        op: opName,
-        changed: applied.length > 0,
-        ...(session.remote ? { idempotent } : {}),
-        warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
-        result: [resultLine],
-        issues: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel],
-        // Success carries no guidance; only a failed validation needs a next step.
-        next: passed ? undefined : ["Inspect issues and apply another patch."],
+        text: [resultLine, ...issues].join("\n"),
+        data: {
+            op: opName,
+            changed: applied.length > 0,
+            revision: session.remote ? newRevision : undefined,
+            idempotent: session.remote ? idempotent : undefined,
+            validation,
+            issues,
+            script_path: session.artifactLabel,
+        },
     };
     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")
-        return `已新增人物 ${op["name"] || op["actor_name"]}${op["role_type"] ? `（${op["role_type"]}）` : ""}`;
+        return `Added actor ${op["name"] || op["actor_name"]}${op["role_type"] ? ` (${op["role_type"]})` : ""}`;
     if (kind === "location.add")
-        return `已新增场景地点 ${op["name"] || op["location_name"]}`;
+        return `Added location ${op["name"] || op["location_name"]}`;
     if (kind === "prop.add")
-        return `已新增道具 ${op["name"] || op["prop_name"]}`;
+        return `Added prop ${op["name"] || op["prop_name"]}`;
     if (kind === "episode.add")
-        return `已新增分集${op["episode_id"] ? ` ${op["episode_id"]}` : "（自动编号）"}${op["title"] ? `：${op["title"]}` : ""}`;
+        return `Added episode${op["episode_id"] ? ` ${op["episode_id"]}` : " (generated ID)"}${op["title"] ? `: ${op["title"]}` : ""}`;
     if (kind === "meta.synopsis.set")
-        return `已更新全剧梗概`;
+        return "Updated script synopsis";
     if (kind === "episode.synopsis.set")
-        return `已更新分集梗概 ${op["episode_id"] ?? op["target"] ?? op["at"]}`;
+        return `Updated episode synopsis ${op["episode_id"] ?? op["target"] ?? op["at"]}`;
     if (kind === "state.add")
-        return `已为 ${op["target"]} 新增状态 ${op["state_id"]}: ${op["name"] || op["state_name"]}`;
+        return `Added state ${op["state_id"]}: ${op["name"] || op["state_name"]} to ${op["target"]}`;
     if (kind === "importance.set")
-        return `已将 ${op["target"]} 重要度设为 ${op["importance"]}`;
+        return `Set ${op["target"]} importance to ${op["importance"]}`;
     if (kind === "scene.ref.set")
-        return `已在 ${op["at"]} 设置引用 ${op["target"]}${op["state"] ? `（状态 ${op["state"]}）` : ""}`;
+        return `Set reference ${op["target"]} on ${op["at"]}${op["state"] ? ` (state ${op["state"]})` : ""}`;
     if (kind === "extend.set")
-        return `已在 ${op["at"]} 设置 extend.${op["key"]}`;
+        return `Set extend.${op["key"]} on ${op["at"]}`;
     if (kind === "extend.clear")
-        return op["key"] ? `已在 ${op["at"]} 删除 extend.${op["key"]}` : `已清空 ${op["at"]} 的 extend`;
+        return op["key"] ? `Removed extend.${op["key"]} from ${op["at"]}` : `Cleared extend on ${op["at"]}`;
     if (kind.startsWith("state."))
-        return `已执行 ${kind}: ${op["target"]}`;
+        return `Applied ${kind}: ${op["target"]}`;
     if (kind.startsWith("dialogue."))
-        return `已执行 ${kind}: ${op["at"]}`;
-    return `已执行 ${kind}`;
+        return `Applied ${kind}: ${op["at"]}`;
+    return `Applied ${kind}`;
 }
 // Accept `/re/flags` as-is; wrap a bare pattern as `/pattern/` so
 // `replace --regex --from '^\s*\[[^\]]*\]'` works without the user typing slashes.
@@ -593,61 +1066,129 @@ 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("A plan digest is only accepted for a v4 multi-target apply.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MULTI_PLAN_USAGE_INVALID",
+            hint: "Remove --plan, or apply the same v4 multi-target selection that produced the digest.",
+            data: { actual: [suppliedPlan] },
+        });
+    }
+    if (multiV4 && apply && !suppliedPlan) {
+        throw new CliError("A v4 multi-target write requires its dry-run plan digest.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "MULTI_PLAN_REQUIRED",
+            hint: "Run the same command without --apply, review the full plan, then retry with `--apply --plan <digest>`.",
+            data: { expected: [planDigest ?? ""], actual: ["<missing>"] },
+        });
+    }
+    if (multiV4 && apply && suppliedPlan !== planDigest) {
+        throw new CliError("The supplied digest does not match the current targets and operations.", {
+            exitCode: EXIT_INPUT,
+            errorCode: "MULTI_PLAN_MISMATCH",
+            hint: "Review the newly computed dry-run plan, then apply its exact digest.",
+            data: { expected: [planDigest ?? ""], actual: [suppliedPlan] },
+        });
+    }
     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 issues = plannedIssueLines ?? legacyIssueLines;
+        const hint = refs.length === 0
+            ? "Widen the selection with --in, --grep, or predicates."
+            : planDigest
+                ? `Run again with --apply --plan ${planDigest} to commit this exact plan.`
+                : "Run again with --apply to commit.";
+        const lines = [...blast, `validation: ${passed ? "would pass" : "would need repair"}; no write`, ...issues, hint];
         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"])),
-            artifacts: [session.artifactLabel],
-            next: [refs.length === 0 ? "Widen the selection (--in / --grep / predicates)." : "Re-run with --apply to commit."],
+            text: lines.join("\n"),
+            data: {
+                op: `${opName}.dry-run`,
+                changed: false,
+                matched: refs.length,
+                applied,
+                skipped,
+                issues,
+                script_path: session.artifactLabel,
+                ...(planDigest ? {
+                    baseline: session.baselineHash,
+                    plan_digest: planDigest,
+                    operations,
+                    targets: refs,
+                    plan: planned?.plan,
+                } : {}),
+            },
         };
         return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
     }
     if (refs.length === 0) {
         return [{
-                title: "SELECTOR EDIT: no match",
-                op: opName,
-                changed: false,
-                result: blast,
-                artifacts: [session.artifactLabel],
-                next: ["Widen the selection (--in / --grep / predicates)."],
+                text: [...blast, "Widen the selection with --in, --grep, or predicates."].join("\n"),
+                data: {
+                    op: opName,
+                    changed: false,
+                    matched: 0,
+                    script_path: session.artifactLabel,
+                },
             }, EXIT_OK];
     }
     const [newRevision, idempotent] = await saveScriptSession(session, opts, opName);
@@ -655,26 +1196,42 @@ export async function applySelectorEdits(opts, template, verbLabel) {
     await syncValidationResult(session, validation, newRevision);
     const passed = Boolean(validation["passed"]);
     const rev = session.remote ? `; rev ${newRevision}` : "";
+    const issues = summarizeIssues(asList(validation["issues"]));
     const report = {
-        title: passed ? "SELECTOR EDIT APPLIED" : "SELECTOR EDIT APPLIED: Validation needs repair",
-        op: opName,
-        changed: applied > 0,
-        ...(session.remote ? { idempotent } : {}),
-        result: [...blast, `validation: ${passed ? "passed" : "needs repair"}${rev}`],
-        warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
-        issues: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel],
-        next: passed ? undefined : ["Inspect issues and apply another edit."],
+        text: [...blast, `validation: ${passed ? "passed" : "needs repair"}${rev}`, ...issues].join("\n"),
+        data: {
+            op: opName,
+            changed: applied > 0,
+            matched: refs.length,
+            applied,
+            skipped,
+            revision: session.remote ? newRevision : undefined,
+            idempotent: session.remote ? idempotent : undefined,
+            validation,
+            issues,
+            script_path: session.artifactLabel,
+            ...(planDigest ? {
+                baseline: session.baselineHash,
+                plan_digest: planDigest,
+                operations,
+                targets: refs,
+                plan: planned?.plan,
+            } : {}),
+        },
     };
     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`)
 // ===========================================================================
 //
 // Each command is a thin read-only wrapper around the underlying script
-// document. They all return a Report shaped like inspect's existing output but
+// document. They all return a CommandOutput shaped like inspect's existing output but
 // without the `--target` flag — the verb itself encodes the target. Filters
 // use `--in <addr>` (compose with the address parsers) plus per-target
 // predicates (--name / --kind / --has / --grep / --context / --type / --actor
@@ -725,17 +1282,19 @@ export function buildGrepMatcher(raw) {
     if (m) {
         const pattern = m[1];
         if (isDangerousRegex(pattern)) {
-            throw new CliError("QUERY BLOCKED: regex unsafe", "regex pattern has nested quantifiers (ReDoS risk) or exceeds the length limit.", {
+            throw new CliError("regex pattern has nested quantifiers (ReDoS risk) or exceeds the length limit.", {
                 exitCode: EXIT_USAGE,
-                required: [`pattern length <= ${MAX_GREP_PATTERN_LEN}; no quantifier-on-group-with-internal-quantifier (e.g. (a+)+)`],
-                received: [`length=${pattern.length}, sample=${pattern.slice(0, 80)}`],
-                nextSteps: ["Rewrite the regex to avoid nested quantifiers, or use a literal substring (drop the /…/ wrapper)."],
                 errorCode: "REGEX_UNSAFE",
+                hint: "Rewrite the regex to avoid nested quantifiers, or use a literal substring (drop the /…/ wrapper).",
+                data: { expected: [`pattern length <= ${MAX_GREP_PATTERN_LEN}; no quantifier-on-group-with-internal-quantifier (e.g. (a+)+)`], actual: [`length=${pattern.length}, sample=${pattern.slice(0, 80)}`] },
             });
         }
         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.
@@ -743,15 +1302,22 @@ export function buildGrepMatcher(raw) {
     }
     return (hay) => hay.includes(raw);
 }
-export function buildReport(op, title, lines, artifactLabel) {
+export function buildReport(op, lines) {
+    const outputLines = lines.length > 0 ? lines : ["No matches."];
     return {
-        title,
-        op,
-        changed: false,
-        result: lines.length > 0 ? lines : ["No matching items."],
-        artifacts: [artifactLabel],
+        text: outputLines.join("\n"),
+        data: {
+            op,
+            changed: false,
+        },
     };
 }
+export function buildTableReport(op, lines, rowColumns, rows) {
+    const report = buildReport(op, lines);
+    report.data["row_columns"] = rowColumns;
+    report.data["rows"] = rows;
+    return report;
+}
 // ----- summary --------------------------------------------------------------
 export function synopsisPreview(text, limit) {
     const oneLine = text.replace(/\s+/g, " ").trim();
@@ -815,12 +1381,11 @@ export function resolveActionTargets(script, opts) {
     // "state_changes" (underscore) passed the filter-missing guard but bypassed
     // every concrete predicate, returning the whole script.
     if (hasFilter && !HAS_FILTERS.has(hasFilter)) {
-        throw new CliError("QUERY BLOCKED: --has value invalid", "--has value invalid.", {
+        throw new CliError("--has value invalid.", {
             exitCode: EXIT_USAGE,
-            required: [`--has: one of ${[...HAS_FILTERS].join(", ")}`],
-            received: [hasFilter],
-            nextSteps: ["Use a supported --has value."],
             errorCode: "HAS_FILTER_INVALID",
+            hint: "Use a supported --has value.",
+            data: { expected: [`--has: one of ${[...HAS_FILTERS].join(", ")}`], actual: [hasFilter] },
         });
     }
     const grepMatcher = buildGrepMatcher(strOf(opts["grep"]));
@@ -854,7 +1419,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());
 }
@@ -913,6 +1478,7 @@ export function assetAppearanceCounts(script, kind) {
 }
 export function listAssetsByKind(script, kind, opts) {
     const lines = [];
+    const rows = [];
     const [key, idKey, nameKey] = (() => {
         switch (kind) {
             case "actor": return ["actors", "actor_id", "actor_name"];
@@ -989,8 +1555,42 @@ export function listAssetsByKind(script, kind, opts) {
             extra.push(`scenes=${scns}`, `episodes_count=${eps}${arc}`);
         }
         lines.push(`${kind} ${id}: ${name || "-"} ${extra.join(" ")}`);
+        const seen = appearances?.get(id);
+        rows.push({
+            addr: `${kind}:${id}`,
+            kind,
+            id,
+            name,
+            aliases,
+            importance,
+            role,
+            states,
+            description_present: descPresent === "yes",
+            ...(appearances
+                ? {
+                    scenes: seen?.scenes ?? 0,
+                    episodes_count: seen?.episodes.size ?? 0,
+                    episodes: seen ? compactEpisodeRanges(seen.episodes) : "",
+                }
+                : {}),
+        });
     }
-    return lines;
+    return {
+        lines,
+        rows,
+        rowColumns: [
+            "addr",
+            "kind",
+            "id",
+            "name",
+            "aliases",
+            "importance",
+            "role",
+            "states",
+            "description_present",
+            ...(appearances ? ["scenes", "episodes_count", "episodes"] : []),
+        ],
+    };
 }
 export function splitSpeakerList(raw) {
     if (Array.isArray(raw))
@@ -999,22 +1599,21 @@ 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)
             resultLines.push(`idempotent: ${String(idempotent).toLowerCase()}`);
     }
     return {
-        title: passed ? "SCRIPT CREATED: Blank scaffold" : "SCRIPT CREATED: Validation needs repair",
-        op: "script.create",
-        changed: true,
-        result: resultLines,
-        warnings: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel],
-        next: [
-            "用 worldview 设定世界观，用 add-actor / add-location / add-prop 注册资产，用 add-episode + insert 搭出分集与场景。",
-        ],
+        text: resultLines.join("\n"),
+        data: {
+            op: "script.create",
+            changed: true,
+            validation,
+            script_path: session.artifactLabel,
+            ...(session.remote ? { revision: session.revision, idempotent } : {}),
+        },
     };
 }
 // ----- add-* (register new entities) ----------------------------------------
@@ -1023,12 +1622,11 @@ export function blankCreateReport(session, validation, idempotent) {
 export function requireNameArg(opts, verb, example) {
     const args = asList(opts["_args"]);
     if (args.length < 1) {
-        throw new CliError(`VERB BLOCKED: ${verb} name missing`, "Name missing.", {
+        throw new CliError("Name missing.", {
             exitCode: EXIT_USAGE,
-            required: ["<name>"],
-            received: ["<empty>"],
-            nextSteps: [example],
             errorCode: "ARGS_MISSING",
+            hint: example,
+            data: { expected: ["<name>"], actual: ["<empty>"] },
         });
     }
     return args[0];