@lingjingai/scriptctl 0.63.14 → 0.63.16

package/dist/usecases/script/lib.js

@@ -1,1654 +0,0 @@
-import { CliError, EXIT_INPUT, 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 { requireStructurallyReadableScriptV4 } 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, mutationValidationWarnings, } from "./session.js";
-import { resolveActionTargetsV4 } from "./v4/queries.js";
-import { actionTimestampFilter, actionTimestampMatches } from "./timestamp-filter.js";
-import { applyVersionedMutations } from "./dispatch.js";
-import { assertInsertCommandFlags, assertMoveCommandFlags, assertSceneRefCommandFlags, buildTimestampOperation, } from "./command-constraints.js";
-export function tokenizeLine(line) {
-    const out = [];
-    let cur = "";
-    let started = false;
-    let quoted = false;
-    let inSingle = false;
-    let inDouble = false;
-    const flush = () => { if (started) {
-        out.push({ text: cur, quoted });
-        cur = "";
-        started = false;
-        quoted = false;
-    } };
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-        if (inSingle) {
-            if (ch === "'")
-                inSingle = false;
-            else {
-                cur += ch;
-                quoted = true;
-            }
-        }
-        else if (inDouble) {
-            if (ch === '"')
-                inDouble = false;
-            else if (ch === "\\" && i + 1 < line.length) {
-                cur += line[++i];
-                quoted = true;
-            }
-            else {
-                cur += ch;
-                quoted = true;
-            }
-        }
-        else if (ch === "'") {
-            inSingle = true;
-            started = true;
-        }
-        else if (ch === '"') {
-            inDouble = true;
-            started = true;
-        }
-        else if (ch === "\\" && i + 1 < line.length) {
-            cur += line[++i];
-            started = true;
-            quoted = true;
-        }
-        else if (ch === " " || ch === "\t" || ch === "\r") {
-            flush();
-        }
-        else {
-            cur += ch;
-            started = true;
-        }
-    }
-    flush();
-    return out;
-}
-// A token is a flag only if it was unquoted AND starts with `--`.
-function isDoFlag(t) {
-    return !t.quoted && t.text.startsWith("--");
-}
-// Per-verb flag arity. Everything else takes the next token as its value.
-export const DO_BOOL_FLAGS = {
-    replace: new Set(["all", "regex"]),
-    transition: new Set(["clear"]),
-    emotion: new Set(["clear"]),
-    parenthetical: new Set(["remove"]),
-    timestamp: new Set(["remove"]),
-    "scene-ref": new Set(["clear", "remove", "append"]),
-    delete: new Set(["force"]),
-    extend: new Set(["clear", "json-value"]),
-};
-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)) {
-        const arr = flags[name] ?? [];
-        arr.push(val);
-        flags[name] = arr;
-    }
-    else {
-        flags[name] = val;
-    }
-}
-export function parseDoLine(tokens) {
-    if (tokens.length === 0 || isDoFlag(tokens[0])) {
-        throw doErr("a line must start with a verb (not a flag)");
-    }
-    const verb = tokens[0].text;
-    const bools = DO_BOOL_FLAGS[verb] ?? new Set();
-    const repeats = DO_REPEAT_FLAGS[verb] ?? new Set();
-    const args = [];
-    const flags = {};
-    for (let i = 1; i < tokens.length; i++) {
-        const t = tokens[i];
-        if (isDoFlag(t)) {
-            let name = t.text.slice(2);
-            // Support `--flag=value` (a common CLI habit) alongside `--flag value`.
-            const eq = name.indexOf("=");
-            if (eq >= 0) {
-                const inlineVal = name.slice(eq + 1);
-                name = name.slice(0, eq);
-                if (!name)
-                    throw doErr(`empty flag name in "${t.text}"`);
-                // A boolean flag written as `--all=false` must become false, not the
-                // truthy string "false" — `--force=false` especially must NOT force.
-                if (bools.has(name)) {
-                    flags[name] = !["false", "0", "no", "off"].includes(inlineVal.toLowerCase());
-                }
-                else {
-                    pushFlag(flags, repeats, name, inlineVal);
-                }
-                continue;
-            }
-            if (!name)
-                throw doErr(`empty flag name "${t.text}"`);
-            if (bools.has(name)) {
-                flags[name] = true;
-                continue;
-            }
-            // A value-taking flag must be followed by an actual value, not another
-            // unquoted `--flag` (or end-of-line) — otherwise `--to --from x` silently
-            // binds '--from' as --to's value. A quoted `"--x"` IS a valid value.
-            const next = tokens[i + 1];
-            if (next === undefined || isDoFlag(next)) {
-                throw doErr(`--${name} needs a value`);
-            }
-            pushFlag(flags, repeats, name, tokens[++i].text);
-        }
-        else {
-            args.push(t.text);
-        }
-    }
-    return { verb, args, flags };
-}
-export function doErr(detail) {
-    return new CliError(detail, {
-        exitCode: EXIT_USAGE,
-        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 ------------------------------------------
-// One source of truth for the verbs whose op has validation/defaults, so the
-// typed CLI handler and `do`'s lineToOp can never drift. Each returns the op
-// WITHOUT `at` (the caller adds the single address or sweeps it over a selector)
-// and throws the SAME CliError the handler used to throw inline.
-export function stateChangeTemplate(target, f) {
-    const toSet = f.to !== undefined;
-    const clearSet = Boolean(f.clear);
-    if (toSet && clearSet) {
-        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("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("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("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("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
-        ? { op: "action.transition.clear", target }
-        : { op: "action.transition.set", target, process: f.process, contrast: f.contrast };
-}
-export function emotionTemplate(f) {
-    const emotionSet = f.emotion !== undefined;
-    const clearSet = Boolean(f.clear);
-    if (emotionSet && clearSet) {
-        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("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
-        ? { op: "action.emotion.clear" }
-        : { op: "action.emotion.set", emotion: f.emotion };
-}
-export function contextTemplate(target, f) {
-    const stateSet = f.state !== undefined;
-    const clearSet = Boolean(f.clear);
-    const removeSet = Boolean(f.remove);
-    const n = (stateSet ? 1 : 0) + (clearSet ? 1 : 0) + (removeSet ? 1 : 0);
-    if (n === 0) {
-        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) {
-        const passed = [];
-        if (stateSet)
-            passed.push("--state");
-        if (clearSet)
-            passed.push("--clear");
-        if (removeSet)
-            passed.push("--remove");
-        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("scene-ref: --occurrence must be a positive integer.", {
-            exitCode: EXIT_USAGE,
-            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("scene-ref: --append requires --state and cannot be combined with --occurrence.", {
-            exitCode: EXIT_USAGE,
-            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)
-        return { op: "scene.ref.remove", target, occurrence };
-    if (clearSet)
-        return { op: "scene.ref.clear", target, occurrence };
-    return { op: "scene.ref.set", target, state: f.state === "none" ? "" : f.state, append, occurrence };
-}
-// v3 dialogue speaker: a single inline speaker — an actor, OR a non-actor kind
-// (system|broadcast|offscreen|group) with an optional label.
-export function dialogueTemplate(f) {
-    const actorId = strOf(f.actor).trim();
-    const speakerKind = strOf(f.kind).trim();
-    const label = strOf(f.label).trim();
-    if (actorId && speakerKind) {
-        throw new CliError("dialogue: --actor and --kind are mutually exclusive.", {
-            exitCode: EXIT_USAGE,
-            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("dialogue: --label is only valid with --kind.", {
-            exitCode: EXIT_USAGE,
-            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("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.
-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"]
-                ? { op: "action.content.regex-replace", at: a0, pattern: regexPattern(strOf(flags["from"])), to: flags["to"] ?? "", all: Boolean(flags["all"]) }
-                : { op: "action.content.replace", at: a0, from: strOf(flags["from"]), to: flags["to"] ?? "", all: Boolean(flags["all"]) };
-        case "type":
-            return { op: "action.type.set", at: a0, type: a1 };
-        case "actor":
-            return { op: "action.actor.set", at: a0, actor_id: a1 };
-        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 "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 "timestamp":
-            return buildTimestampOperation(a0, flags["set"], Boolean(flags["remove"]));
-        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: sceneRefFlags.states[0],
-                    clear: sceneRefFlags.clear,
-                    remove: sceneRefFlags.remove,
-                    append: sceneRefFlags.append,
-                    occurrence: sceneRefFlags.occurrence,
-                }),
-                at: a0,
-            };
-        }
-        case "dialogue":
-            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":
-            return { op: "asset.role.set", target: a0, role_type: a1 };
-        case "worldview":
-            return { op: "meta.worldview.set", worldview: a0 };
-        case "synopsis": {
-            if (args.length === 0)
-                throw doErr("synopsis needs <text> or <episode_id> <text>");
-            if (args.length > 2)
-                throw doErr("synopsis text with spaces must be quoted");
-            if (args.length === 1) {
-                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 = 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: "id" in addr ? addr.id : addr.episodeId, synopsis: a1 };
-        }
-        case "alias": {
-            const add = flags["add"] ?? [];
-            const remove = flags["remove"] ?? [];
-            if (add.length)
-                return { op: "asset.alias.add", target: a0, alias: add };
-            if (remove.length)
-                return { op: "asset.alias.remove", target: a0, alias: remove };
-            throw doErr("alias needs --add <alias> or --remove <alias>");
-        }
-        case "describe": {
-            const addr = parseAddress(a0);
-            if (addr.kind === "state")
-                return { op: "state.describe", target: a0, description: a1 };
-            if (addr.kind === "asset")
-                return { op: "asset.describe", target: a0, description: a1 };
-            throw doErr(`describe cannot operate on a ${addr.kind} address (${a0}); use an asset or asset/state target`);
-        }
-        case "extend": {
-            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)");
-                return { op: "extend.clear", at: a0, key: a1 || undefined };
-            }
-            if (args.length < 3)
-                throw doErr("extend needs <addr> <key> <value> (or --clear)");
-            let value = args[2];
-            if (flags["json-value"]) {
-                try {
-                    value = JSON.parse(strOf(args[2]));
-                }
-                catch {
-                    throw doErr("extend --json-value: value is not valid JSON");
-                }
-            }
-            return { op: "extend.set", at: a0, key: a1, value };
-        }
-        case "state-add":
-            return { op: "state.add", target: a0, name: a1, description: flags["description"], state_id: flags["state-id"] };
-        case "state-rename":
-            return { op: "state.rename", target: a0, name: a1 };
-        case "state-delete":
-            return { op: "state.delete", target: a0, strategy: flags["strategy"], replacement: flags["replacement"] };
-        case "add-actor":
-            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", location_id: flags["id"], name: a0, description: flags["description"] };
-        case "add-prop":
-            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 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 = 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})`);
-        }
-        case "move": {
-            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 = parseAddress(a0);
-            if (addr.kind === "scene")
-                return { op: "scene.merge", from: a0, into: strOf(flags["into"]) };
-            if (addr.kind === "asset")
-                return { op: "asset.merge", from: a0, into: strOf(flags["into"]) };
-            throw doErr(`merge cannot operate on a ${addr.kind} address (${a0}); merge two assets or two scenes`);
-        }
-        case "insert": {
-            const addr = parseAddress(a0);
-            const insertFlags = doInsertFlags(flags);
-            if (addr.kind === "episode") {
-                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") {
-                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})`);
-        }
-        default:
-            throw doErr(`unknown verb '${verb}' (structural/edit/create verbs are supported; queries are not)`);
-    }
-}
-export function actionAddress(epId, sceneId, idx) {
-    return `${epId}/${sceneId}#${idx}`;
-}
-// The action's authored timeline position, carried in extend.timestamp as a
-// "M:SS" / "MM:SS" string (episode-local by convention). Empty string when the
-// action carries no timestamp. This is the anchor event-level alignment reads:
-// an event's span is the delta between its first and last action timestamp.
-export function actionTimestamp(action) {
-    const extend = isDict(action["extend"]) ? action["extend"] : {};
-    return strOf(extend["timestamp"]).trim();
-}
-// First and last non-empty action timestamps within a scene, in document order.
-// Timestamps are monotonic within an episode, so first = t_start, last = t_end.
-export function sceneTimeSpan(scene) {
-    let t_start = "";
-    let t_end = "";
-    for (const action of asList(scene["actions"])) {
-        const ts = actionTimestamp(action);
-        if (!ts)
-            continue;
-        if (!t_start)
-            t_start = ts;
-        t_end = ts;
-    }
-    return { t_start, t_end };
-}
-export function actionDisplayFields(epId, sceneId, idx, action) {
-    const actorId = actionActorId(action);
-    const s = isDict(action["speaker"]) ? action["speaker"] : null;
-    // For a non-actor speaker ({kind,label}) surface it under `speaker`; an actor
-    // line surfaces under `actor` (its id). Narrative lines have neither.
-    const speaker = s && !actorId ? (strOf(s["label"]).trim() || strOf(s["kind"]).trim()) : "";
-    return {
-        addr: actionAddress(epId, sceneId, idx),
-        timestamp: actionTimestamp(action),
-        type: strOf(action["type"]).trim() || "action",
-        speaker,
-        actor: actorId,
-        emotion: strOf(action["emotion"]).trim(),
-        content: strOf(action["content"]),
-    };
-}
-export function formatInspectAction(epId, sceneId, idx, action) {
-    const fields = actionDisplayFields(epId, sceneId, idx, action);
-    const addr = strOf(fields["addr"]);
-    const type = strOf(fields["type"]);
-    const delivery = strOf(fields["delivery"]);
-    const tag = delivery ? `${type} ${delivery}` : type;
-    // Prefer the speaker_id (concrete) over actor_id (asset), and skip both when
-    // the action is narrative (no speaker). Format kept on a single line so agents
-    // can grep the output.
-    const speakerId = strOf(fields["speaker"]);
-    const actorId = strOf(fields["actor"]);
-    const who = speakerId || actorId;
-    const emotion = strOf(fields["emotion"]);
-    const timestamp = strOf(fields["timestamp"]);
-    const content = strOf(fields["content"]);
-    const meta = [tag, timestamp ? `t=${timestamp}` : "", emotion ? `emotion=${emotion}` : "", who].filter((v) => v).join(" ");
-    const prefix = `${addr} [${meta}]`;
-    return content ? `${prefix} ${content}` : prefix;
-}
-// ---------------------------------------------------------------------------
-// command_script_patch
-// ---------------------------------------------------------------------------
-export const SKIPPABLE_EDIT_CODES = new Set([
-    "REGEX_NO_MATCH",
-    "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.timestamp.set":
-        case "action.timestamp.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 = requireStructurallyReadableScriptV4(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 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 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"]);
-    const warnings = mutationValidationWarnings(session, validation);
-    // One outcome line: what changed + revision (remote) + validation verdict.
-    const rev = session.remote ? `; rev ${newRevision}` : "";
-    const resultLine = `${applied.join(", ")} applied${rev}; validation ${passed ? "passed" : "needs repair"}`;
-    const issues = summarizeIssues(asList(validation["issues"]));
-    const warningLines = summarizeIssues(warnings);
-    const report = {
-        text: [resultLine, ...warningLines].join("\n"),
-        data: {
-            op: opName,
-            changed: applied.length > 0,
-            revision: session.remote ? newRevision : undefined,
-            idempotent: session.remote ? idempotent : undefined,
-            validation,
-            issues,
-            warnings,
-            script_path: session.artifactLabel,
-        },
-    };
-    return [report, EXIT_OK];
-}
-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 `Added actor ${op["name"] || op["actor_name"]}${op["role_type"] ? ` (${op["role_type"]})` : ""}`;
-    if (kind === "location.add")
-        return `Added location ${op["name"] || op["location_name"]}`;
-    if (kind === "prop.add")
-        return `Added prop ${op["name"] || op["prop_name"]}`;
-    if (kind === "episode.add")
-        return `Added episode${op["episode_id"] ? ` ${op["episode_id"]}` : " (generated ID)"}${op["title"] ? `: ${op["title"]}` : ""}`;
-    if (kind === "meta.synopsis.set")
-        return "Updated script synopsis";
-    if (kind === "episode.synopsis.set")
-        return `Updated episode synopsis ${op["episode_id"] ?? op["target"] ?? op["at"]}`;
-    if (kind === "state.add")
-        return `Added state ${op["state_id"]}: ${op["name"] || op["state_name"]} to ${op["target"]}`;
-    if (kind === "importance.set")
-        return `Set ${op["target"]} importance to ${op["importance"]}`;
-    if (kind === "scene.ref.set")
-        return `Set reference ${op["target"]} on ${op["at"]}${op["state"] ? ` (state ${op["state"]})` : ""}`;
-    if (kind === "extend.set")
-        return `Set extend.${op["key"]} on ${op["at"]}`;
-    if (kind === "extend.clear")
-        return op["key"] ? `Removed extend.${op["key"]} from ${op["at"]}` : `Cleared extend on ${op["at"]}`;
-    if (kind === "action.timestamp.set")
-        return `Set timestamp on ${op["at"]}`;
-    if (kind === "action.timestamp.remove")
-        return `Removed timestamp from ${op["at"]}`;
-    if (kind.startsWith("state."))
-        return `Applied ${kind}: ${op["target"]}`;
-    if (kind.startsWith("dialogue."))
-        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.
-export function regexPattern(raw) {
-    const s = raw.trim();
-    if (s.length >= 2 && s.startsWith("/") && s.lastIndexOf("/") > 0)
-        return s;
-    return `/${s}/`;
-}
-// The selector-driven write runner. Resolves `opts` to its matched actions
-// (range/region + predicates) and applies one op template to each, as a single
-// in-memory pass committed once. Guardrail: with no --apply it's a DRY-RUN that
-// 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 applySelectorEditsToSession(session, opts, template, verbLabel) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const apply = Boolean(opts["apply"]);
-    const opName = strOf(template["op"]);
-    const script = session.script;
-    const refs = session.version === 3
-        ? resolveActionTargets(script, opts).map((target) => `${target.epId}/${target.sceneId}#${target.idx}`)
-        : resolveActionTargetsV4(requireStructurallyReadableScriptV4(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 = 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;
-            }
-        }
-    }
-    else if (apply) {
-        for (const step of planned.plan.steps) {
-            if (step.status === "applied") {
-                applyPatchOperationsForSession(session, source, [step.operation]);
-            }
-        }
-    }
-    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}`,
-        ...(displayedRefs.length ? [`targets: ${displayedRefs.join(", ")}${refs.length > displayedRefs.length ? ` … (+${refs.length - displayedRefs.length} more)` : ""}`] : []),
-        ...(planDigest ? [`plan_digest: ${planDigest}`] : []),
-    ];
-    if (!apply) {
-        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${passed ? "." : "; validation issues will remain available as follow-up diagnostics."}`
-                : `Run again with --apply to commit${passed ? "." : "; validation issues will remain available as follow-up diagnostics."}`;
-        const lines = [...blast, `validation: ${passed ? "would pass" : "would need repair"}; no write`, ...issues, hint];
-        const report = {
-            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, EXIT_OK];
-    }
-    if (refs.length === 0) {
-        return [{
-                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);
-    const validation = validateSession(session);
-    await syncValidationResult(session, validation, newRevision);
-    const passed = Boolean(validation["passed"]);
-    const warnings = mutationValidationWarnings(session, validation);
-    const rev = session.remote ? `; rev ${newRevision}` : "";
-    const issues = summarizeIssues(asList(validation["issues"]));
-    const warningLines = summarizeIssues(warnings);
-    const report = {
-        text: [...blast, `validation: ${passed ? "passed" : "needs repair"}${rev}`, ...warningLines].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,
-            warnings,
-            script_path: session.artifactLabel,
-            ...(planDigest ? {
-                baseline: session.baselineHash,
-                plan_digest: planDigest,
-                operations,
-                targets: refs,
-                plan: planned?.plan,
-            } : {}),
-        },
-    };
-    return [report, EXIT_OK];
-}
-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 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
-// / --speaker / --severity / --code / --has-{actor,location,prop}).
-// Resolve the speaker_id → source actor mapping once per call. Used by
-// commandActions's --actor filter when the action speaks via a speaker.
-// v3: a dialogue line carries a single inline speaker — an actor ({actor_id})
-// or a non-actor source ({kind, label?}). These read that shape.
-// The actor id behind an action's speaker, or "" for a non-actor / narrative line.
-export function actionActorId(action) {
-    const s = action["speaker"];
-    if (isDict(s) && strOf(s["actor_id"]).trim())
-        return strOf(s["actor_id"]).trim();
-    return "";
-}
-// A human label for the speaker: the actor's name (resolved via `names`), or a
-// non-actor kind's label / kind, or "" when the line has no speaker.
-export function actionSpeakerLabel(action, actorNames) {
-    const s = action["speaker"];
-    if (!isDict(s))
-        return "";
-    const actorId = strOf(s["actor_id"]).trim();
-    if (actorId)
-        return actorNames?.get(actorId) || actorId;
-    const kind = strOf(s["kind"]).trim();
-    if (kind)
-        return strOf(s["label"]).trim() || kind;
-    return "";
-}
-export function actorIdsInAction(action) {
-    const ids = new Set();
-    const id = actionActorId(action);
-    if (id)
-        ids.add(id);
-    return ids;
-}
-// Build a grep matcher. /pattern/flags → RegExp, otherwise literal substring.
-// Pre-flight checks block the common ReDoS shapes before they hit V8's regex
-// engine: nested quantifiers like (a+)+, (a*)+, (a*|b*)+ etc. compile fine
-// but hang the process on adversarial input. Since --grep accepts caller-
-// controlled patterns and runs over every action in scope, the safe move is
-// to reject patterns with quantifier-on-group-with-internal-quantifier and
-// cap the pattern length.
-export function buildGrepMatcher(raw) {
-    if (!raw)
-        return null;
-    const m = /^\/(.+)\/([gimsuy]*)$/.exec(raw);
-    if (m) {
-        const pattern = m[1];
-        if (isDangerousRegex(pattern)) {
-            throw new CliError("regex pattern has nested quantifiers (ReDoS risk) or exceeds the length limit.", {
-                exitCode: EXIT_USAGE,
-                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.lastIndex = 0;
-                return re.test(hay);
-            };
-        }
-        catch {
-            // Malformed regex — treat as literal.
-        }
-    }
-    return (hay) => hay.includes(raw);
-}
-export function buildReport(op, lines) {
-    const outputLines = lines.length > 0 ? lines : ["No matches."];
-    return {
-        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();
-    return oneLine.length > limit ? `${oneLine.slice(0, limit)}…` : oneLine;
-}
-export function episodeInSelector(selector, epId, scenes) {
-    if (selector.isEmpty)
-        return true;
-    if (selector.matchesScene(epId, "scn_000000"))
-        return true;
-    for (const scene of scenes) {
-        if (selector.matchesScene(epId, strOf(scene["scene_id"])))
-            return true;
-    }
-    return false;
-}
-export function nameMaps(script) {
-    const out = { actor: new Map(), location: new Map(), prop: new Map() };
-    for (const a of asList(script["actors"]))
-        out.actor.set(strOf(a["actor_id"]), strOf(a["actor_name"]));
-    for (const l of asList(script["locations"]))
-        out.location.set(strOf(l["location_id"]), strOf(l["location_name"]));
-    for (const p of asList(script["props"]))
-        out.prop.set(strOf(p["prop_id"]), strOf(p["prop_name"]));
-    return out;
-}
-export function formatScene(epId, scene, names) {
-    const ctx = sceneRefs(scene);
-    const env = isDict(scene["environment"]) ? scene["environment"] : {};
-    const space = strOf(env["space"]) || "-";
-    const time = strOf(env["time"]) || "-";
-    const locations = asList(ctx["locations"]).map((r) => {
-        const id = strOf(r["location_id"]);
-        return `${id}(${names.location.get(id) || "?"})`;
-    });
-    const actors = asList(ctx["actors"]).map((r) => {
-        const id = strOf(r["actor_id"]);
-        return `${id}(${names.actor.get(id) || "?"})`;
-    });
-    const props = asList(ctx["props"]).map((r) => {
-        const id = strOf(r["prop_id"]);
-        return `${id}(${names.prop.get(id) || "?"})`;
-    });
-    const actionCount = asList(scene["actions"]).length;
-    const { t_start, t_end } = sceneTimeSpan(scene);
-    const timePart = t_start || t_end ? ` t=${t_start || "?"}..${t_end || "?"}` : "";
-    return `${epId}/${scene["scene_id"]} [${space} ${time}] location=${locations.join(",") || "-"} actors=${actors.join(",") || "-"} props=${props.join(",") || "-"} actions=${actionCount}${timePart}`;
-}
-export const HAS_FILTERS = new Set(["transition", "speaker"]);
-// Resolve a selection (--in range/region selector + --type/--actor/--speaker/
-// --grep/--has predicates, AND-combined) to the matching actions, in document
-// order. The single matcher behind both `actions` queries and selector-driven
-// writes. Does NOT enforce "at least one filter" — that policy is caller-owned
-// (queries refuse a bare dump; writes gate on --all). Validates the --has value.
-export function resolveActionTargets(script, opts) {
-    const selector = parseInSelector(strOf(opts["in"]));
-    const timestampRange = actionTimestampFilter(opts);
-    const typeFilter = strOf(opts["type"]).trim();
-    const actorFilter = strOf(opts["actor"]).trim();
-    const hasFilter = strOf(opts["has"]).trim();
-    // Whitelist --has: silently accepting unknown values means a typo like
-    // "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("--has value invalid.", {
-            exitCode: EXIT_USAGE,
-            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"]));
-    const out = [];
-    for (const ep of asList(script["episodes"])) {
-        const epId = strOf(ep["episode_id"]);
-        for (const scene of asList(ep["scenes"])) {
-            const sceneId = strOf(scene["scene_id"]);
-            if (!selector.matchesScene(epId, sceneId))
-                continue;
-            const actions = asList(scene["actions"]);
-            for (let i = 0; i < actions.length; i++) {
-                if (!selector.matchesAction(epId, sceneId, i))
-                    continue;
-                const a = actions[i];
-                if (timestampRange
-                    && !actionTimestampMatches(isDict(a["extend"]) ? a["extend"]["timestamp"] : undefined, timestampRange, actionAddress(epId, sceneId, i)))
-                    continue;
-                if (typeFilter && strOf(a["type"]).trim() !== typeFilter)
-                    continue;
-                if (actorFilter && !actorIdsInAction(a).has(actorFilter))
-                    continue;
-                if (hasFilter === "transition" && !isDict(a["transition_prompt"]))
-                    continue;
-                if (hasFilter === "speaker" && !isDict(a["speaker"]))
-                    continue;
-                if (grepMatcher && !grepMatcher(strOf(a["content"])))
-                    continue;
-                out.push({ epId, sceneId, idx: i, action: a });
-            }
-        }
-    }
-    return out;
-}
-// Whether a selection in `opts` has any filter at all (scope or predicate).
-export function selectionHasAnyFilter(opts) {
-    return Boolean(strOf(opts["in"]).trim() ||
-        strOf(opts["grep"]) || strOf(opts["type"]).trim() || strOf(opts["actor"]).trim() ||
-        strOf(opts["has"]).trim());
-}
-// Collapse a set of episode ids into sorted, comma-joined ranges:
-// {ep_001, ep_002, ep_003, ep_007} → "ep_001..ep_003,ep_007". Keeps the state
-// arc / appearance lines readable even when an item spans dozens of episodes.
-export function compactEpisodeRanges(ids) {
-    const nums = [...new Set([...ids])]
-        .map((id) => ({ id, n: idNum(id, "ep") }))
-        .filter((x) => Number.isFinite(x.n))
-        .sort((a, b) => a.n - b.n);
-    if (nums.length === 0)
-        return "";
-    const parts = [];
-    let start = nums[0];
-    let prev = nums[0];
-    const flush = () => parts.push(start.id === prev.id ? start.id : `${start.id}..${prev.id}`);
-    for (let i = 1; i < nums.length; i++) {
-        const cur = nums[i];
-        if (cur.n === prev.n + 1) {
-            prev = cur;
-            continue;
-        }
-        flush();
-        start = cur;
-        prev = cur;
-    }
-    flush();
-    return parts.join(",");
-}
-// One pass over scene context: for each asset id of `kind`, the set of episodes
-// and count of scenes it is referenced in. "Appearance" = presence in a scene's
-// context (the canonical who/what-is-in-this-scene list direct-init populates).
-export function assetAppearanceCounts(script, kind) {
-    const idKey = kind === "actor" ? "actor_id" : kind === "location" ? "location_id" : "prop_id";
-    const pluralKey = kind === "actor" ? "actors" : kind === "location" ? "locations" : "props";
-    const out = new Map();
-    for (const ep of asList(script["episodes"])) {
-        const epId = strOf(ep["episode_id"]);
-        for (const scene of asList(ep["scenes"])) {
-            const ctx = sceneRefs(scene);
-            const seen = new Set();
-            for (const ref of asList(ctx[pluralKey])) {
-                const id = strOf(ref[idKey]);
-                if (!id || seen.has(id))
-                    continue;
-                seen.add(id);
-                const entry = out.get(id) ?? { episodes: new Set(), scenes: 0 };
-                entry.episodes.add(epId);
-                entry.scenes += 1;
-                out.set(id, entry);
-            }
-        }
-    }
-    return out;
-}
-export function listAssetsByKind(script, kind, opts) {
-    const lines = [];
-    const rows = [];
-    const [key, idKey, nameKey] = (() => {
-        switch (kind) {
-            case "actor": return ["actors", "actor_id", "actor_name"];
-            case "location": return ["locations", "location_id", "location_name"];
-            case "prop": return ["props", "prop_id", "prop_name"];
-        }
-    })();
-    // Build the set of asset ids referenced inside the --in scope. A range or
-    // multi-region selector takes the union of context refs over every matched
-    // scene; a bare single action point (e.g. ep_001/scn_003#2) keeps the legacy
-    // "narrow to that one action's actor" behavior.
-    // WHOLE_SCRIPT ('--in *') means "all assets" — it must NOT narrow to the set
-    // of assets referenced in scene context (that would drop registered-but-not-
-    // yet-placed assets). Only a real address-region selector narrows.
-    let scopeIds = null;
-    if (!opts.selector.isEmpty && opts.selector !== WHOLE_SCRIPT) {
-        scopeIds = new Set();
-        const single = selectorSingleActionPoint(opts.selector);
-        const pluralKey = kind === "actor" ? "actors" : kind === "location" ? "locations" : "props";
-        for (const ep of asList(script["episodes"])) {
-            const epId = strOf(ep["episode_id"]);
-            for (const scene of asList(ep["scenes"])) {
-                const sceneId = strOf(scene["scene_id"]);
-                if (!opts.selector.matchesScene(epId, sceneId))
-                    continue;
-                if (single) {
-                    // Single action point: matchesScene already isolates the target
-                    // scene. Legacy narrowing is implemented for actor only.
-                    if (kind === "actor") {
-                        const a = asList(scene["actions"])[single.idx];
-                        const aid = a ? actionActorId(a) : "";
-                        if (aid)
-                            scopeIds.add(aid);
-                    }
-                    continue;
-                }
-                const ctx = sceneRefs(scene);
-                for (const ref of asList(ctx[pluralKey])) {
-                    scopeIds.add(strOf(ref[idKey]));
-                }
-            }
-        }
-    }
-    // Appearance counts (scenes / episodes) computed in one pass, only when asked
-    // — keeps the default listing lean.
-    const appearances = opts.counts ? assetAppearanceCounts(script, kind) : null;
-    for (const asset of asList(script[key])) {
-        const id = strOf(asset[idKey]);
-        const name = strOf(asset[nameKey]);
-        if (opts.id && opts.id !== id)
-            continue;
-        if (opts.name && !name.includes(opts.name))
-            continue;
-        if (scopeIds && !scopeIds.has(id))
-            continue;
-        const aliases = asList(asset["aliases"]).map((s) => strOf(s));
-        const role = strOf(asset["role_type"]);
-        const importance = strOf(asset["importance"]);
-        const descPresent = strOf(asset["description"]).trim() ? "yes" : "missing";
-        const states = asList(asset["states"]).length;
-        const extra = [];
-        if (aliases.length > 0)
-            extra.push(`aliases=(${aliases.join(",")})`);
-        if (importance)
-            extra.push(`importance=${importance}`);
-        if (role)
-            extra.push(`role=${role}`);
-        extra.push(`states=${states}`, `description=${descPresent}`);
-        if (appearances) {
-            const seen = appearances.get(id);
-            const eps = seen ? seen.episodes.size : 0;
-            const scns = seen ? seen.scenes : 0;
-            const arc = seen && eps > 0 ? ` episodes=${compactEpisodeRanges(seen.episodes)}` : "";
-            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,
-        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))
-        return raw.map((v) => strOf(v)).filter((v) => v);
-    return strOf(raw).split(",").map((s) => s.trim()).filter((s) => s);
-}
-export function blankCreateReport(session, validation, idempotent) {
-    const passed = Boolean(validation["passed"]);
-    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 {
-        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) ----------------------------------------
-// Read the single positional <name> arg shared by add-actor/location/prop, or
-// throw the common ARGS_MISSING usage error with a verb-specific example.
-export function requireNameArg(opts, verb, example) {
-    const args = asList(opts["_args"]);
-    if (args.length < 1) {
-        throw new CliError("Name missing.", {
-            exitCode: EXIT_USAGE,
-            errorCode: "ARGS_MISSING",
-            hint: example,
-            data: { expected: ["<name>"], actual: ["<empty>"] },
-        });
-    }
-    return args[0];
-}
-//# sourceMappingURL=lib.js.map