@lingjingai/scriptctl 0.5.0 → 0.6.1

package/dist/usecases/script.js

@@ -3,7 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 import { CliError, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, directDir, exists, readJson, readText, scriptJsonPath, sha256Text, writeJson, } from "../common.js";
-import { applyPatchOperations, collectStateRefs, parseStateTarget, validateScript, } from "../domain/script-core.js";
+import { applyPatchOperations, collectAssetRefs, collectStateRefs, parseAnyAddress, parseStateTarget, validateScript, PATCH_OP_SCHEMA, } from "../domain/script-core.js";
 import { ScriptOutputApiError, ScriptOutputClient } from "../infra/script-output-api.js";
 import { markMetadataConfidenceReviewed, readRunState, reviewBlockers, summarizeIssues, updateRunState, markPatched, } from "./direct.js";
 function strOf(v) {
@@ -361,11 +361,23 @@ async function syncValidationResult(session, validation, revision) {
         throw exc;
     }
 }
-function requestIdForScriptWrite(opts, op) {
+// Idempotency key for gateway writes. Returns the agent-provided --request-id
+// when present, otherwise derives a deterministic key from (op, post-mutation
+// script content). baseRevision is intentionally NOT in the hash: in a
+// partial-success retry the client reloads at a new baseRevision but the
+// post-mutation script is identical, so the hash matches and the gateway can
+// dedupe. The cost of including baseRevision (an old version of this code)
+// was that retries produced different ids and committed redundant no-op
+// revisions to the gateway history.
+function requestIdForScriptWrite(opts, op, payload) {
     const explicit = strOf(opts["request_id"]).trim();
     if (explicit)
         return explicit;
-    return `scriptctl:${op}:${randomUUID()}`;
+    const canonical = JSON.stringify(sortDeep({
+        op,
+        script: payload.script,
+    }));
+    return `scriptctl:${op}:${sha256Text(canonical)}`;
 }
 async function saveScriptSession(session, opts, op) {
     if (!session.remote) {
@@ -374,12 +386,13 @@ async function saveScriptSession(session, opts, op) {
     }
     if (session.client === null)
         throw new Error("remote script session missing client");
-    const requestId = requestIdForScriptWrite(opts, op);
+    const baseRevision = Number(session.revision ?? 0);
+    const requestId = requestIdForScriptWrite(opts, op, { script: session.script });
     let res;
     try {
         res = await session.client.replaceScript({
             requestId,
-            baseRevision: Number(session.revision ?? 0),
+            baseRevision,
             script: session.script,
             source: "ctl",
         });
@@ -512,55 +525,6 @@ export async function commandScriptValidate(opts) {
     };
     return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
 }
-// Parse the inspect --id value when target=action. Accepts:
-//   - "ep_001" / "1" / "01" → episode filter only
-//   - "ep_001/scn_001"      → scene-level filter
-//   - "ep_001/scn_001#3"    → single action
-// Returns null fields for the levels that weren't constrained.
-function parseActionInspectId(raw) {
-    if (!raw)
-        return { epId: null, sceneId: null, actionIndex: null };
-    let value = raw.trim();
-    let actionIndex = null;
-    if (value.includes("#")) {
-        const i = value.lastIndexOf("#");
-        const idx = parseInt(value.slice(i + 1), 10);
-        if (!Number.isFinite(idx)) {
-            throw new CliError("SCRIPT INSPECT BLOCKED: Action ref invalid", "Action ref invalid.", {
-                exitCode: EXIT_USAGE,
-                required: ["action ref: ep_001/scn_001#3"],
-                received: [raw],
-                nextSteps: ["Use ep_id/scn_id#action_index."],
-                errorCode: "INSPECT_ID_INVALID",
-            });
-        }
-        actionIndex = idx;
-        value = value.slice(0, i);
-    }
-    let epId = null;
-    let sceneId = null;
-    if (value.includes("/")) {
-        const [ep, scn] = value.split("/", 2);
-        epId = normalizeEpisodeRef(ep);
-        sceneId = scn.trim() || null;
-    }
-    else if (value) {
-        epId = normalizeEpisodeRef(value);
-    }
-    return { epId, sceneId, actionIndex };
-}
-// "1" / "01" / "ep_001" / "ep_15" → "ep_001" / "ep_015". Anything that already
-// starts with "ep_" is passed through verbatim so non-standard ids still work.
-function normalizeEpisodeRef(raw) {
-    const value = raw.trim();
-    if (!value)
-        return value;
-    if (value.startsWith("ep_"))
-        return value;
-    if (/^\d+$/.test(value))
-        return `ep_${value.padStart(3, "0")}`;
-    return value;
-}
 function actionAddress(epId, sceneId, idx) {
     return `${epId}/${sceneId}#${idx}`;
 }
@@ -584,149 +548,71 @@ function formatInspectAction(epId, sceneId, idx, action) {
     const prefix = who ? `${addr} [${tag} ${who}]` : `${addr} [${tag}]`;
     return content ? `${prefix} ${content}` : prefix;
 }
-export async function commandScriptInspect(opts) {
-    const session = await loadScriptForEdit(opts);
-    const script = session.script;
-    const target = strOf(opts["target"] || "summary").trim();
-    const itemId = strOf(opts["id"]).trim();
-    const lines = [];
-    if (target === "summary") {
-        const episodes = asList(script["episodes"]);
-        const scenes = [];
-        for (const ep of episodes)
-            scenes.push(...asList(ep["scenes"]));
-        const actions = [];
-        for (const scene of scenes)
-            actions.push(...asList(scene["actions"]));
-        lines.push(`title: ${script["title"] || "-"}`, `episodes: ${episodes.length}`, `scenes: ${scenes.length}`, `actions: ${actions.length}`, `actors: ${asList(script["actors"]).length}`, `locations: ${asList(script["locations"]).length}`, `props: ${asList(script["props"]).length}`, `speakers: ${asList(script["speakers"]).length}`);
-    }
-    else if (target === "episode") {
-        const minChars = parseBound(opts["min_chars"]);
-        const maxChars = parseBound(opts["max_chars"]);
-        for (const ep of asList(script["episodes"])) {
-            if (itemId && itemId !== strOf(ep["episode_id"]))
-                continue;
-            const scenes = asList(ep["scenes"]);
-            let actionCount = 0;
-            const chars = episodeCharCounts(scenes);
-            for (const scene of scenes)
-                actionCount += asList(scene["actions"]).length;
-            if (minChars !== null && chars.total < minChars)
-                continue;
-            if (maxChars !== null && chars.total > maxChars)
-                continue;
-            lines.push(`${ep["episode_id"]}: scenes=${scenes.length}, actions=${actionCount}, chars=${chars.total} (dialogue=${chars.dialogue}, action=${chars.action}), title=${ep["title"] || "-"}`);
-        }
-    }
-    else if (target === "action") {
-        // Lists action addresses + content. Designed for "find which action says X"
-        // workflows: the agent greps the content, gets back ep_NN/scn_NN#idx, then
-        // edits via `script action content-replace`. Requires at least one filter
-        // (--id / --grep) — dumping every action across 30+ episodes would blow
-        // past any sane context window.
-        const grep = strOf(opts["grep"]);
-        const filter = parseActionInspectId(itemId);
-        if (!grep && !itemId) {
-            throw new CliError("SCRIPT INSPECT BLOCKED: Action filter missing", "Action filter missing.", {
-                exitCode: EXIT_USAGE,
-                required: ["--id <ep_001|ep_001/scn_001|ep_001/scn_001#3> or --grep <text>"],
-                received: ["<empty>"],
-                nextSteps: ["Pass --grep to search content, or --id to scope to an episode/scene/action."],
-                errorCode: "INSPECT_FILTER_MISSING",
-            });
-        }
-        for (const ep of asList(script["episodes"])) {
-            const epId = strOf(ep["episode_id"]);
-            if (filter.epId && filter.epId !== epId)
-                continue;
-            for (const scene of asList(ep["scenes"])) {
-                const sceneId = strOf(scene["scene_id"]);
-                if (filter.sceneId && filter.sceneId !== sceneId)
-                    continue;
-                const actions = asList(scene["actions"]);
-                for (let i = 0; i < actions.length; i++) {
-                    if (filter.actionIndex !== null && filter.actionIndex !== i)
-                        continue;
-                    const a = actions[i];
-                    if (grep) {
-                        let hay = strOf(a["content"]);
-                        for (const line of asList(a["lines"]))
-                            hay += "\n" + strOf(line["content"]);
-                        if (!hay.includes(grep))
-                            continue;
-                    }
-                    lines.push(formatInspectAction(epId, sceneId, i, a));
-                }
-            }
-        }
-    }
-    else if (target === "asset") {
-        for (const [key, idKey, nameKey] of [
-            ["actors", "actor_id", "actor_name"],
-            ["locations", "location_id", "location_name"],
-            ["props", "prop_id", "prop_name"],
-        ]) {
-            for (const asset of asList(script[key])) {
-                if (itemId && itemId !== strOf(asset[idKey]) && itemId !== strOf(asset[nameKey]))
-                    continue;
-                const singular = key.slice(0, -1);
-                lines.push(`${singular} ${asset[idKey]}: ${asset[nameKey]} states=${asList(asset["states"]).length}`);
-            }
-        }
-    }
-    else if (target === "speaker") {
-        for (const speaker of asList(script["speakers"])) {
-            if (itemId && itemId !== strOf(speaker["speaker_id"]))
-                continue;
-            lines.push(`${speaker["speaker_id"]}: ${speaker["display_name"]} [${speaker["source_kind"]}] source=${speaker["source_id"]}`);
-        }
-    }
-    else if (target === "issue") {
-        const validation = validateSession(session);
-        for (const issue of asList(validation["issues"])) {
-            if (itemId && itemId !== strOf(issue["code"]) && itemId !== strOf(issue["severity"]))
-                continue;
-            const whereParts = [];
-            for (const k of ["episode", "scene", "action_index"]) {
-                if (issue[k] !== null && issue[k] !== undefined)
-                    whereParts.push(strOf(issue[k]));
-            }
-            const where = whereParts.join(" ");
-            lines.push(`${issue["severity"]} ${issue["code"]}: ${issue["summary"]}${where ? ` [${where}]` : ""}`);
-        }
-    }
-    else {
-        throw new CliError("SCRIPT INSPECT BLOCKED: Target invalid", "Target invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["target: summary, episode, action, asset, speaker, or issue"],
-            received: [target],
-            nextSteps: ["Use a supported target."],
-            errorCode: "INSPECT_TARGET_INVALID",
-        });
-    }
-    const report = {
-        title: `SCRIPT INSPECT: ${target}`,
-        op: "script.inspect",
-        changed: false,
-        summary: `${target}: ${lines.length} item(s)`,
-        result: lines.length > 0 ? lines : ["No matching items."],
-        artifacts: [session.artifactLabel],
-        next: ["Use script subcommands or script patch for edits."],
-    };
-    return [report, EXIT_OK];
-}
 // ---------------------------------------------------------------------------
 // command_script_patch
 // ---------------------------------------------------------------------------
 export async function commandScriptPatch(opts) {
+    // --schema: dump op schemas as JSON; no script load, no file required.
+    // `--schema <op>` narrows to a single op; bare `--schema` dumps all.
+    const schemaOpt = opts["schema"];
+    if (schemaOpt !== undefined && schemaOpt !== false) {
+        const specificOp = typeof schemaOpt === "string" && schemaOpt !== "" ? schemaOpt : null;
+        if (specificOp) {
+            const entry = PATCH_OP_SCHEMA[specificOp];
+            if (!entry) {
+                throw new CliError("SCRIPT PATCH BLOCKED: Unknown op", "Unknown op.", {
+                    exitCode: EXIT_USAGE,
+                    required: ["existing dot-style op name (e.g. asset.rename)"],
+                    received: [specificOp],
+                    nextSteps: ["Run `scriptctl patch --schema` (no value) to list all ops."],
+                    errorCode: "PATCH_OP_UNKNOWN",
+                });
+            }
+            const report = {
+                title: `PATCH OP SCHEMA: ${specificOp}`,
+                op: "patch.schema",
+                changed: false,
+                summary: entry.description,
+                result: [
+                    `op: ${specificOp}`,
+                    `required: ${entry.required.join(", ") || "(none)"}`,
+                    `optional: ${entry.optional.join(", ") || "(none)"}`,
+                ],
+                body: JSON.stringify({ op: specificOp, ...entry }, null, 2),
+                next: ["Construct a patch file with these fields and run `scriptctl patch <file>`."],
+            };
+            return [report, EXIT_OK];
+        }
+        const ops = Object.keys(PATCH_OP_SCHEMA).sort();
+        const report = {
+            title: "PATCH OP SCHEMA",
+            op: "patch.schema",
+            changed: false,
+            summary: `${ops.length} dot-style ops supported`,
+            result: ops.map((name) => {
+                const e = PATCH_OP_SCHEMA[name];
+                return `${name}: required=[${e.required.join(",")}] optional=[${e.optional.join(",")}]`;
+            }),
+            body: JSON.stringify(PATCH_OP_SCHEMA, null, 2),
+            next: ["Use `scriptctl patch --schema <op>` for a single op, or write a patch file and run `scriptctl patch <file>`."],
+        };
+        return [report, EXIT_OK];
+    }
     const workspace = strOf(opts["workspace_path"] || "workspace");
-    const session = await loadScriptForEdit(opts);
-    const script = session.script;
     const patchPath = strOf(opts["patch"]);
+    if (!patchPath) {
+        throw new CliError("SCRIPT PATCH BLOCKED: Patch file missing", "Patch file missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<file> positional argument"],
+            received: ["<empty>"],
+            nextSteps: ["Pass a patch JSON file, or use --schema to inspect op definitions."],
+            errorCode: "PATCH_FILE_MISSING",
+        });
+    }
     if (!exists(patchPath)) {
         throw new CliError("SCRIPT PATCH BLOCKED: Patch file not found", "Patch file not found.", {
             exitCode: EXIT_INPUT,
-            required: ["--patch existing JSON file"],
+            required: ["existing patch JSON file"],
             received: [patchPath],
             nextSteps: ["Write patch JSON and rerun."],
             errorCode: "PATCH_NOT_FOUND",
@@ -746,10 +632,41 @@ export async function commandScriptPatch(opts) {
         });
     }
     const operations = patchOperationsFromPayload(payload);
+    const dryRun = Boolean(opts["dry_run"]);
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
     const applied = applyPatchOperations(script, scriptSourceText(workspace), operations);
+    if (dryRun) {
+        // Validate the in-memory mutated script WITHOUT calling saveScriptSession.
+        // Run validate but skip syncValidationResult (which writes to remote) too.
+        const validation = validateSession(session);
+        const passed = Boolean(validation["passed"]);
+        const report = {
+            title: passed ? "SCRIPT PATCH DRY-RUN PASSED" : "SCRIPT PATCH DRY-RUN: Validation needs repair",
+            op: "script.patch.dry-run",
+            changed: false,
+            summary: `would apply ${applied.length} operation(s) — no write performed`,
+            warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
+            result: [
+                `operations: ${applied.length}`,
+                `validation: ${passed ? "would pass" : "would need repair"}`,
+                "dry-run: no remote/local write performed",
+            ],
+            issues: summarizeIssues(asList(validation["issues"])),
+            artifacts: [session.artifactLabel],
+            next: [passed ? "Re-run without --dry-run to commit." : "Resolve validation issues before committing."],
+        };
+        return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
+    }
     const [newRevision, idempotent] = await saveScriptSession(session, opts, applied.length === 1 ? applied[0] : "script.patch");
     const validation = validateSession(session);
     await syncValidationResult(session, validation, newRevision);
+    // Direct-stage local patches: keep run_state in sync so reviewBlockers can
+    // unblock direct export. Detect via script path under directDir.
+    if (!session.remote && session.scriptPath && session.scriptPath.startsWith(directDir(workspace))) {
+        markMetadataConfidenceReviewed(workspace, operations);
+        markPatched(workspace, applied.length);
+    }
     const passed = Boolean(validation["passed"]);
     const resultLines = [
         `operations: ${applied.length}`,
@@ -857,222 +774,6 @@ async function commandStateRefs(opts, plan = false) {
     };
     return [report, EXIT_OK];
 }
-export async function commandScriptState(opts, action) {
-    const args = asList(opts["_args"]);
-    if (action === "refs" || action === "delete-plan") {
-        return commandStateRefs(opts, action === "delete-plan");
-    }
-    if (args.length === 0) {
-        throw new CliError("SCRIPT STATE BLOCKED: Target missing", "Target missing.", {
-            exitCode: EXIT_USAGE,
-            required: ["state or asset target"],
-            received: ["<empty>"],
-            nextSteps: ["Run scriptctl script state --help."],
-            errorCode: "TARGET_MISSING",
-        });
-    }
-    let op;
-    if (action === "add") {
-        op = {
-            op: "state.add",
-            target: args[0],
-            name: opts["name"],
-            description: opts["description"],
-            state_id: opts["state_id"],
-        };
-    }
-    else if (action === "rename") {
-        op = { op: "state.rename", target: args[0], name: opts["name"] };
-    }
-    else if (action === "describe") {
-        op = { op: "state.describe", target: args[0], description: opts["description"] };
-    }
-    else if (action === "delete-apply") {
-        op = {
-            op: "state.delete",
-            target: args[0],
-            strategy: opts["strategy"],
-            replacement: opts["replacement"],
-        };
-    }
-    else {
-        throw new CliError("SCRIPT STATE BLOCKED: Command invalid", "Command invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["add, rename, describe, refs, delete-plan, delete-apply"],
-            received: [action],
-            nextSteps: ["Run scriptctl script state --help."],
-            errorCode: "STATE_COMMAND_INVALID",
-        });
-    }
-    return applySingleScriptOp(opts, op);
-}
-export async function commandScriptContext(opts, action) {
-    const args = asList(opts["_args"]);
-    if (args.length < 2) {
-        throw new CliError("SCRIPT CONTEXT BLOCKED: Arguments missing", "Arguments missing.", {
-            exitCode: EXIT_USAGE,
-            required: ["scene ref and target"],
-            received: args,
-            nextSteps: ["Run scriptctl script context --help."],
-            errorCode: "ARGS_MISSING",
-        });
-    }
-    if (action !== "set" && action !== "clear") {
-        throw new CliError("SCRIPT CONTEXT BLOCKED: Command invalid", "Command invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["set or clear"],
-            received: [action],
-            nextSteps: ["Run scriptctl script context --help."],
-            errorCode: "CONTEXT_COMMAND_INVALID",
-        });
-    }
-    const op = {
-        op: action === "set" ? "context.set" : "context.clear",
-        at: args[0],
-        target: args[1],
-        state: opts["state"],
-    };
-    return applySingleScriptOp(opts, op);
-}
-export async function commandScriptAction(opts, action) {
-    const args = asList(opts["_args"]);
-    if (args.length < 2) {
-        throw new CliError("SCRIPT ACTION BLOCKED: Arguments missing", "Arguments missing.", {
-            exitCode: EXIT_USAGE,
-            required: ["action ref and target"],
-            received: args,
-            nextSteps: ["Run scriptctl script action --help."],
-            errorCode: "ARGS_MISSING",
-        });
-    }
-    let op;
-    if (action === "state-change") {
-        op = {
-            op: "action.state.change",
-            at: args[0],
-            target: args[1],
-            to: opts["to"],
-            from: opts["from"],
-            effective: opts["effective"] || "after",
-        };
-    }
-    else if (action === "state-remove") {
-        op = { op: "action.state.remove", at: args[0], target: args[1] };
-    }
-    else if (action === "transition-set") {
-        op = {
-            op: "action.transition.set",
-            at: args[0],
-            target: args[1],
-            process: opts["process"],
-            contrast: opts["contrast"],
-        };
-    }
-    else if (action === "transition-clear") {
-        op = { op: "action.transition.clear", at: args[0], target: args[1] };
-    }
-    else {
-        throw new CliError("SCRIPT ACTION BLOCKED: Command invalid", "Command invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["state-change, state-remove, transition-set, transition-clear"],
-            received: [action],
-            nextSteps: ["Run scriptctl script action --help."],
-            errorCode: "ACTION_COMMAND_INVALID",
-        });
-    }
-    return applySingleScriptOp(opts, op);
-}
-export async function commandScriptActionContentReplace(opts) {
-    const args = asList(opts["_args"]);
-    if (args.length < 1) {
-        throw new CliError("SCRIPT ACTION BLOCKED: Action ref missing", "Action ref missing.", {
-            exitCode: EXIT_USAGE,
-            required: ["action ref: ep_001/scn_001#3"],
-            received: ["<empty>"],
-            nextSteps: ["Run scriptctl script action --help."],
-            errorCode: "ACTION_REF_MISSING",
-        });
-    }
-    // commander's requiredOption catches missing --from / --to, but it lets an
-    // explicit empty string through. We allow --to "" intentionally (it means
-    // "delete this substring") but require --from to be non-empty so the op
-    // cannot match the empty string at every cursor position.
-    if (opts["from"] === undefined) {
-        throw new CliError("SCRIPT ACTION BLOCKED: --from missing", "--from missing.", {
-            exitCode: EXIT_USAGE,
-            required: ["--from <text>"],
-            received: ["<missing>"],
-            nextSteps: ["Pass --from with the substring to replace."],
-            errorCode: "FROM_TEXT_EMPTY",
-        });
-    }
-    const op = {
-        op: "action.content.replace",
-        at: args[0],
-        from: opts["from"],
-        to: opts["to"] ?? "",
-        all: Boolean(opts["all"]),
-    };
-    return applySingleScriptOp(opts, op);
-}
-export async function commandScriptSpeaker(opts, action) {
-    if (action !== "add") {
-        throw new CliError("SCRIPT SPEAKER BLOCKED: Command invalid", "Command invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["add"],
-            received: [action],
-            nextSteps: ["Run scriptctl script speaker --help."],
-            errorCode: "SPEAKER_COMMAND_INVALID",
-        });
-    }
-    const op = {
-        op: "speaker.add",
-        kind: opts["kind"],
-        name: opts["name"],
-        source_id: opts["source_id"],
-        voice_desc: opts["voice_desc"],
-        speaker_id: opts["speaker_id"],
-    };
-    return applySingleScriptOp(opts, op);
-}
-export async function commandScriptDialogue(opts, action) {
-    const args = asList(opts["_args"]);
-    if (args.length === 0) {
-        throw new CliError("SCRIPT DIALOGUE BLOCKED: Action ref missing", "Action ref missing.", {
-            exitCode: EXIT_USAGE,
-            required: ["action ref"],
-            received: ["<empty>"],
-            nextSteps: ["Run scriptctl script dialogue --help."],
-            errorCode: "ACTION_REF_MISSING",
-        });
-    }
-    let op;
-    if (action === "speakers") {
-        op = {
-            op: "dialogue.speakers",
-            at: args[0],
-            speakers: opts["speaker"] || [],
-            delivery: opts["delivery"] || "simultaneous",
-        };
-    }
-    else if (action === "overlap") {
-        op = {
-            op: "dialogue.overlap",
-            at: args[0],
-            lines: opts["line"] || [],
-        };
-    }
-    else {
-        throw new CliError("SCRIPT DIALOGUE BLOCKED: Command invalid", "Command invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["speakers or overlap"],
-            received: [action],
-            nextSteps: ["Run scriptctl script dialogue --help."],
-            errorCode: "DIALOGUE_COMMAND_INVALID",
-        });
-    }
-    return applySingleScriptOp(opts, op);
-}
 // ---------------------------------------------------------------------------
 // command_export (direct export)
 // ---------------------------------------------------------------------------
@@ -1203,4 +904,1256 @@ export function sortDeep(value) {
     }
     return value;
 }
+// ===========================================================================
+// 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
+// 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.
+function speakerSourceActorMap(script) {
+    const map = new Map();
+    for (const s of asList(script["speakers"])) {
+        const sourceKind = strOf(s["source_kind"]);
+        if (sourceKind === "actor") {
+            const sid = strOf(s["speaker_id"]);
+            const src = strOf(s["source_id"]);
+            if (sid && src)
+                map.set(sid, src);
+        }
+    }
+    return map;
+}
+function speakerIdsInAction(action) {
+    const ids = new Set();
+    const direct = strOf(action["speaker_id"]).trim();
+    if (direct)
+        ids.add(direct);
+    for (const sp of asList(action["speakers"])) {
+        const id = strOf(sp["speaker_id"]).trim();
+        if (id)
+            ids.add(id);
+    }
+    for (const line of asList(action["lines"])) {
+        const id = strOf(line["speaker_id"]).trim();
+        if (id)
+            ids.add(id);
+    }
+    return ids;
+}
+function actorIdsInAction(action, speakerToActor) {
+    const ids = new Set();
+    const direct = strOf(action["actor_id"]).trim();
+    if (direct)
+        ids.add(direct);
+    for (const spkId of speakerIdsInAction(action)) {
+        const actor = speakerToActor.get(spkId);
+        if (actor)
+            ids.add(actor);
+    }
+    return ids;
+}
+function parseInFilter(raw) {
+    if (!raw)
+        return { epId: null, sceneId: null, actionIndex: null };
+    try {
+        const addr = parseAnyAddress(raw);
+        if (addr.kind === "action")
+            return { epId: addr.episodeId, sceneId: addr.sceneId, actionIndex: addr.actionIndex };
+        if (addr.kind === "scene")
+            return { epId: addr.episodeId, sceneId: addr.sceneId, actionIndex: null };
+        if (addr.kind === "episode")
+            return { epId: addr.episodeId, sceneId: null, actionIndex: null };
+    }
+    catch {
+        // Fall through; raw address not recognized.
+    }
+    throw new CliError("QUERY BLOCKED: --in address invalid", "--in address invalid.", {
+        exitCode: EXIT_USAGE,
+        required: ["--in: ep_NNN | ep_NNN/scn_NNN | ep_NNN/scn_NNN#idx"],
+        received: [raw],
+        nextSteps: ["Pass a recognized address format."],
+        errorCode: "IN_ADDRESS_INVALID",
+    });
+}
+// 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.
+const MAX_GREP_PATTERN_LEN = 256;
+function isDangerousRegex(pattern) {
+    if (pattern.length > MAX_GREP_PATTERN_LEN)
+        return true;
+    // Quantifier ({+,*,?,{n,m}}) outside a group whose interior contains another
+    // quantifier — classic catastrophic-backtracking template. The check is a
+    // heuristic, not a parser; false positives are tolerated as long as the
+    // common ReDoS shapes are blocked.
+    return /\([^)]*[*+?{][^)]*\)[*+?{]/.test(pattern);
+}
+function buildGrepMatcher(raw) {
+    if (!raw)
+        return null;
+    const m = /^\/(.+)\/([gimsuy]*)$/.exec(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.", {
+                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",
+            });
+        }
+        try {
+            const re = new RegExp(pattern, m[2]);
+            return (hay) => re.test(hay);
+        }
+        catch {
+            // Malformed regex — treat as literal.
+        }
+    }
+    return (hay) => hay.includes(raw);
+}
+function buildReport(op, title, lines, artifactLabel, next) {
+    return {
+        title,
+        op,
+        changed: false,
+        summary: `${lines.length} item(s)`,
+        result: lines.length > 0 ? lines : ["No matching items."],
+        artifacts: [artifactLabel],
+        next,
+    };
+}
+// ----- summary --------------------------------------------------------------
+export async function commandSummary(opts) {
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const episodes = asList(script["episodes"]);
+    const scenes = [];
+    for (const ep of episodes)
+        scenes.push(...asList(ep["scenes"]));
+    const actions = [];
+    for (const scene of scenes)
+        actions.push(...asList(scene["actions"]));
+    const lines = [
+        `title: ${script["title"] || "-"}`,
+        `episodes: ${episodes.length}`,
+        `scenes: ${scenes.length}`,
+        `actions: ${actions.length}`,
+        `actors: ${asList(script["actors"]).length}`,
+        `locations: ${asList(script["locations"]).length}`,
+        `props: ${asList(script["props"]).length}`,
+        `speakers: ${asList(script["speakers"]).length}`,
+    ];
+    return [buildReport("query.summary", "SCRIPT SUMMARY", lines, session.artifactLabel, ["Use plural-noun queries (episodes / scenes / actions / actors / ...) or edit verbs to act on the script."]), EXIT_OK];
+}
+// ----- episodes -------------------------------------------------------------
+export async function commandEpisodes(opts) {
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const itemId = strOf(opts["id"]).trim();
+    const minChars = parseBound(opts["min_chars"]);
+    const maxChars = parseBound(opts["max_chars"]);
+    const lines = [];
+    for (const ep of asList(script["episodes"])) {
+        if (itemId && itemId !== strOf(ep["episode_id"]))
+            continue;
+        const scenes = asList(ep["scenes"]);
+        let actionCount = 0;
+        const chars = episodeCharCounts(scenes);
+        for (const scene of scenes)
+            actionCount += asList(scene["actions"]).length;
+        if (minChars !== null && chars.total < minChars)
+            continue;
+        if (maxChars !== null && chars.total > maxChars)
+            continue;
+        lines.push(`${ep["episode_id"]}: scenes=${scenes.length}, actions=${actionCount}, chars=${chars.total} (dialogue=${chars.dialogue}, action=${chars.action}), title=${ep["title"] || "-"}`);
+    }
+    return [buildReport("query.episodes", "EPISODES", lines, session.artifactLabel, ["Use `scriptctl scenes --in <ep>` to drill in, or edit verbs to mutate."]), EXIT_OK];
+}
+// ----- scenes ---------------------------------------------------------------
+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;
+}
+function formatScene(epId, scene, names) {
+    const ctx = isDict(scene["context"]) ? scene["context"] : {};
+    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;
+    return `${epId}/${scene["scene_id"]} [${space} ${time}] location=${locations.join(",") || "-"} actors=${actors.join(",") || "-"} props=${props.join(",") || "-"} actions=${actionCount}`;
+}
+export async function commandScenes(opts) {
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const inFilter = parseInFilter(strOf(opts["in"]));
+    const hasActor = strOf(opts["has_actor"]).trim();
+    const hasLocation = strOf(opts["has_location"]).trim();
+    const hasProp = strOf(opts["has_prop"]).trim();
+    const names = nameMaps(script);
+    const lines = [];
+    for (const ep of asList(script["episodes"])) {
+        const epId = strOf(ep["episode_id"]);
+        if (inFilter.epId && inFilter.epId !== epId)
+            continue;
+        for (const scene of asList(ep["scenes"])) {
+            const sceneId = strOf(scene["scene_id"]);
+            if (inFilter.sceneId && inFilter.sceneId !== sceneId)
+                continue;
+            if (hasActor) {
+                const refs = asList((scene["context"] || {})["actors"]);
+                if (!refs.some((r) => strOf(r["actor_id"]) === hasActor))
+                    continue;
+            }
+            if (hasLocation) {
+                const refs = asList((scene["context"] || {})["locations"]);
+                if (!refs.some((r) => strOf(r["location_id"]) === hasLocation))
+                    continue;
+            }
+            if (hasProp) {
+                const refs = asList((scene["context"] || {})["props"]);
+                if (!refs.some((r) => strOf(r["prop_id"]) === hasProp))
+                    continue;
+            }
+            lines.push(formatScene(epId, scene, names));
+        }
+    }
+    return [buildReport("query.scenes", "SCENES", lines, session.artifactLabel, ["Use `scriptctl actions --in <ep/scn>` to see actions, or edit verbs to mutate."]), EXIT_OK];
+}
+// ----- actions --------------------------------------------------------------
+export async function commandActions(opts) {
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const inFilter = parseInFilter(strOf(opts["in"]));
+    const grep = strOf(opts["grep"]);
+    const typeFilter = strOf(opts["type"]).trim();
+    const actorFilter = strOf(opts["actor"]).trim();
+    const speakerFilter = strOf(opts["speaker"]).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.
+    const HAS_FILTERS = new Set(["state-changes", "transition", "lines"]);
+    if (hasFilter && !HAS_FILTERS.has(hasFilter)) {
+        throw new CliError("QUERY BLOCKED: --has value invalid", "--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",
+        });
+    }
+    const contextN = (() => {
+        const n = opts["context"];
+        if (n === undefined || n === null || n === "")
+            return 0;
+        const parsed = Number(n);
+        return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 0;
+    })();
+    const grepMatcher = buildGrepMatcher(grep);
+    const speakerToActor = (actorFilter || speakerFilter) ? speakerSourceActorMap(script) : new Map();
+    if (!inFilter.epId && !grep && !actorFilter && !speakerFilter && !typeFilter && !hasFilter && inFilter.actionIndex === null) {
+        throw new CliError("QUERY BLOCKED: actions filter missing", "actions filter missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["at least one of --in / --grep / --type / --actor / --speaker / --has"],
+            received: ["<empty>"],
+            nextSteps: ["Add a filter — dumping every action across all episodes is too large."],
+            errorCode: "ACTIONS_FILTER_MISSING",
+        });
+    }
+    const allInScope = [];
+    const matchKeys = new Set();
+    for (const ep of asList(script["episodes"])) {
+        const epId = strOf(ep["episode_id"]);
+        if (inFilter.epId && inFilter.epId !== epId)
+            continue;
+        for (const scene of asList(ep["scenes"])) {
+            const sceneId = strOf(scene["scene_id"]);
+            if (inFilter.sceneId && inFilter.sceneId !== sceneId)
+                continue;
+            const actions = asList(scene["actions"]);
+            for (let i = 0; i < actions.length; i++) {
+                if (inFilter.actionIndex !== null && inFilter.actionIndex !== i)
+                    continue;
+                const a = actions[i];
+                if (typeFilter && strOf(a["type"]).trim() !== typeFilter)
+                    continue;
+                if (speakerFilter && !speakerIdsInAction(a).has(speakerFilter))
+                    continue;
+                if (actorFilter && !actorIdsInAction(a, speakerToActor).has(actorFilter))
+                    continue;
+                if (hasFilter === "state-changes" && asList(a["state_changes"]).length === 0)
+                    continue;
+                if (hasFilter === "transition" && !isDict(a["transition_prompt"]))
+                    continue;
+                if (hasFilter === "lines" && asList(a["lines"]).length === 0)
+                    continue;
+                if (grepMatcher) {
+                    let hay = strOf(a["content"]);
+                    for (const line of asList(a["lines"]))
+                        hay += "\n" + strOf(line["content"]);
+                    if (!grepMatcher(hay))
+                        continue;
+                }
+                const key = `${epId}/${sceneId}#${i}`;
+                matchKeys.add(key);
+                allInScope.push({ epId, sceneId, idx: i, action: a });
+            }
+        }
+    }
+    // --context N: expand matches to include neighbors within each scene.
+    const lines = [];
+    if (contextN > 0 && matchKeys.size > 0) {
+        // Walk again, emitting any hit within N of a match (same scene).
+        const matchBySceneIdx = new Map();
+        for (const k of matchKeys) {
+            const [scene, idxStr] = k.split("#");
+            const set = matchBySceneIdx.get(scene) ?? new Set();
+            set.add(parseInt(idxStr, 10));
+            matchBySceneIdx.set(scene, set);
+        }
+        for (const ep of asList(script["episodes"])) {
+            const epId = strOf(ep["episode_id"]);
+            for (const scene of asList(ep["scenes"])) {
+                const sceneKey = `${epId}/${scene["scene_id"]}`;
+                const matchIdxSet = matchBySceneIdx.get(sceneKey);
+                if (!matchIdxSet)
+                    continue;
+                const actions = asList(scene["actions"]);
+                for (let i = 0; i < actions.length; i++) {
+                    let withinRange = false;
+                    for (const m of matchIdxSet) {
+                        if (Math.abs(i - m) <= contextN) {
+                            withinRange = true;
+                            break;
+                        }
+                    }
+                    if (!withinRange)
+                        continue;
+                    lines.push(formatInspectAction(epId, strOf(scene["scene_id"]), i, actions[i]));
+                }
+            }
+        }
+    }
+    else {
+        for (const hit of allInScope) {
+            lines.push(formatInspectAction(hit.epId, hit.sceneId, hit.idx, hit.action));
+        }
+    }
+    return [buildReport("query.actions", "ACTIONS", lines, session.artifactLabel, ["Use `scriptctl replace <addr>` or `scriptctl type <addr> <type>` etc. to edit."]), EXIT_OK];
+}
+// ----- actors / locations / props / assets ----------------------------------
+function listAssetsByKind(script, kind, opts) {
+    const lines = [];
+    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 set of ids referenced inside the --in scope if filter is set.
+    let scopeIds = null;
+    if (opts.inFilter.epId) {
+        scopeIds = new Set();
+        for (const ep of asList(script["episodes"])) {
+            if (strOf(ep["episode_id"]) !== opts.inFilter.epId)
+                continue;
+            for (const scene of asList(ep["scenes"])) {
+                if (opts.inFilter.sceneId && strOf(scene["scene_id"]) !== opts.inFilter.sceneId)
+                    continue;
+                const ctx = isDict(scene["context"]) ? scene["context"] : {};
+                const pluralKey = kind === "actor" ? "actors" : kind === "location" ? "locations" : "props";
+                for (const ref of asList(ctx[pluralKey])) {
+                    scopeIds.add(strOf(ref[idKey]));
+                }
+                if (opts.inFilter.actionIndex !== null) {
+                    // Narrow further to a single action's refs.
+                    const actions = asList(scene["actions"]);
+                    const a = actions[opts.inFilter.actionIndex];
+                    if (!a)
+                        continue;
+                    scopeIds = new Set();
+                    if (kind === "actor") {
+                        const aid = strOf(a["actor_id"]).trim();
+                        if (aid)
+                            scopeIds.add(aid);
+                    }
+                }
+            }
+        }
+    }
+    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 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 (role)
+            extra.push(`role=${role}`);
+        extra.push(`states=${states}`, `description=${descPresent}`);
+        lines.push(`${kind} ${id}: ${name || "-"} ${extra.join(" ")}`);
+    }
+    return lines;
+}
+export async function commandActors(opts) {
+    const session = await loadScriptForEdit(opts);
+    const lines = listAssetsByKind(session.script, "actor", {
+        id: strOf(opts["id"]).trim(),
+        name: strOf(opts["name"]).trim(),
+        inFilter: parseInFilter(strOf(opts["in"])),
+    });
+    return [buildReport("query.actors", "ACTORS", lines, session.artifactLabel, ["Use `scriptctl rename actor:<id>` / `describe` / `merge` to edit."]), EXIT_OK];
+}
+export async function commandLocations(opts) {
+    const session = await loadScriptForEdit(opts);
+    const lines = listAssetsByKind(session.script, "location", {
+        id: strOf(opts["id"]).trim(),
+        name: strOf(opts["name"]).trim(),
+        inFilter: parseInFilter(strOf(opts["in"])),
+    });
+    return [buildReport("query.locations", "LOCATIONS", lines, session.artifactLabel, ["Use `scriptctl rename location:<id>` etc. to edit."]), EXIT_OK];
+}
+export async function commandProps(opts) {
+    const session = await loadScriptForEdit(opts);
+    const lines = listAssetsByKind(session.script, "prop", {
+        id: strOf(opts["id"]).trim(),
+        name: strOf(opts["name"]).trim(),
+        inFilter: parseInFilter(strOf(opts["in"])),
+    });
+    return [buildReport("query.props", "PROPS", lines, session.artifactLabel, ["Use `scriptctl rename prop:<id>` etc. to edit."]), EXIT_OK];
+}
+export async function commandAssets(opts) {
+    const session = await loadScriptForEdit(opts);
+    const kindFilter = strOf(opts["kind"]).trim();
+    const nameOpt = strOf(opts["name"]).trim();
+    const idOpt = strOf(opts["id"]).trim();
+    const inFilter = parseInFilter(strOf(opts["in"]));
+    const lines = [];
+    for (const kind of ["actor", "location", "prop"]) {
+        if (kindFilter && kindFilter !== kind)
+            continue;
+        lines.push(...listAssetsByKind(session.script, kind, { id: idOpt, name: nameOpt, inFilter }));
+    }
+    return [buildReport("query.assets", "ASSETS", lines, session.artifactLabel, ["Use `scriptctl actors` / `locations` / `props` for kind-scoped views."]), EXIT_OK];
+}
+// ----- speakers -------------------------------------------------------------
+export async function commandSpeakers(opts) {
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const idOpt = strOf(opts["id"]).trim();
+    const nameOpt = strOf(opts["name"]).trim();
+    const kindOpt = strOf(opts["kind"]).trim();
+    const lines = [];
+    for (const sp of asList(script["speakers"])) {
+        const id = strOf(sp["speaker_id"]);
+        const name = strOf(sp["display_name"]);
+        const sourceKind = strOf(sp["source_kind"]);
+        const sourceId = strOf(sp["source_id"]);
+        if (idOpt && idOpt !== id)
+            continue;
+        if (nameOpt && !name.includes(nameOpt))
+            continue;
+        if (kindOpt && kindOpt !== sourceKind)
+            continue;
+        lines.push(`${id}: ${name} [${sourceKind}] source=${sourceId || "-"}`);
+    }
+    return [buildReport("query.speakers", "SPEAKERS", lines, session.artifactLabel, ["Use `scriptctl add-speaker` to register more, or `scriptctl refs <spk_id>` to see usage."]), EXIT_OK];
+}
+// ----- issues ---------------------------------------------------------------
+export async function commandIssues(opts) {
+    const session = await loadScriptForEdit(opts);
+    const severityFilter = strOf(opts["severity"]).trim();
+    const codeFilter = strOf(opts["code"]).trim();
+    const validation = validateSession(session);
+    const lines = [];
+    for (const issue of asList(validation["issues"])) {
+        if (severityFilter && severityFilter !== strOf(issue["severity"]))
+            continue;
+        if (codeFilter && codeFilter !== strOf(issue["code"]))
+            continue;
+        const whereParts = [];
+        for (const k of ["episode", "scene", "action_index"]) {
+            if (issue[k] !== null && issue[k] !== undefined)
+                whereParts.push(strOf(issue[k]));
+        }
+        const where = whereParts.join(" ");
+        lines.push(`${issue["severity"]} ${issue["code"]}: ${issue["summary"]}${where ? ` [${where}]` : ""}`);
+    }
+    return [buildReport("query.issues", "ISSUES", lines, session.artifactLabel, ["Use the relevant edit verb to repair each issue."]), EXIT_OK];
+}
+// ----- refs (unified reverse lookup) ----------------------------------------
+export async function commandRefs(opts) {
+    const session = await loadScriptForEdit(opts);
+    const script = session.script;
+    const args = asList(opts["_args"]);
+    const target = strOf(args[0]).trim();
+    if (!target) {
+        throw new CliError("QUERY BLOCKED: refs target missing", "refs target missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["address: actor|location|prop:<id>[/<state_id>] or spk_<id>"],
+            received: ["<empty>"],
+            nextSteps: ["Pass a recognized address."],
+            errorCode: "REFS_TARGET_MISSING",
+        });
+    }
+    const level = strOf(opts["level"]).trim(); // scene|action|""
+    const addr = parseAnyAddress(target);
+    let refs = [];
+    if (addr.kind === "state") {
+        refs = collectStateRefs(script, addr.assetKind, addr.assetId, addr.stateId);
+    }
+    else if (addr.kind === "asset") {
+        refs = collectAssetRefs(script, addr.assetKind, addr.assetId);
+    }
+    else if (addr.kind === "speaker") {
+        refs = collectAssetRefs(script, "speaker", addr.speakerId);
+    }
+    else {
+        throw new CliError("QUERY BLOCKED: refs target invalid", "refs target invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["asset / state / speaker address"],
+            received: [target],
+            nextSteps: ["Use a kind:id, kind:id/state_id, or spk_id form."],
+            errorCode: "REFS_TARGET_INVALID",
+        });
+    }
+    const lines = [];
+    for (const ref of refs) {
+        const role = strOf(ref["role"]);
+        if (level === "scene" && !role.startsWith("scene_") && role !== "speaker_source")
+            continue;
+        if (level === "action" && (role.startsWith("scene_") || role === "speaker_source"))
+            continue;
+        lines.push(`${ref["location"]} [${ref["role"]}]`);
+    }
+    return [buildReport("query.refs", `REFS ${target}`, lines, session.artifactLabel, ["Use the relevant edit verb (merge / delete --strategy / rename) to mutate."]), EXIT_OK];
+}
+// ===========================================================================
+// 0.6.0 edit verbs (flat top-level — replace `script <group> <leaf>` chains)
+// ===========================================================================
+//
+// Each verb is a thin function over applySingleScriptOp / parseAnyAddress.
+// Multipolar verbs (delete / merge / move / describe / insert) dispatch on
+// the first positional address to pick the underlying dot-style patch op.
+// ----- content-level (action) -----------------------------------------------
+export async function commandReplace(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: Action ref missing", "Action ref missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["action ref: ep_001/scn_001#3"],
+            received: ["<empty>"],
+            nextSteps: ["Run `scriptctl --help` for the full command surface."],
+            errorCode: "ACTION_REF_MISSING",
+        });
+    }
+    if (opts["from"] === undefined) {
+        throw new CliError("VERB BLOCKED: --from missing", "--from missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["--from <text>"],
+            received: ["<missing>"],
+            nextSteps: ["Pass --from with the substring to replace."],
+            errorCode: "FROM_TEXT_EMPTY",
+        });
+    }
+    return applySingleScriptOp(opts, {
+        op: "action.content.replace",
+        at: args[0],
+        from: opts["from"],
+        to: opts["to"] ?? "",
+        all: Boolean(opts["all"]),
+    });
+}
+export async function commandType(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: Type args missing", "Type args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<action ref> <type>"],
+            received: args,
+            nextSteps: ["Example: scriptctl type ep_001/scn_001#3 dialogue"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return applySingleScriptOp(opts, { op: "action.type.set", at: args[0], type: args[1] });
+}
+export async function commandActor(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: Actor args missing", "Actor args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<action ref> <actor_id|none>"],
+            received: args,
+            nextSteps: ["Example: scriptctl actor ep_001/scn_001#3 act_002"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    // Empty string is almost always a shell-expansion accident ("$ACTOR" with
+    // $ACTOR unset). Old set_action_actor required explicit allow_null; we
+    // restore the safety by demanding the literal token `none` to clear.
+    if (args[1].trim() === "") {
+        throw new CliError("VERB BLOCKED: actor_id empty", "actor_id is empty.", {
+            exitCode: EXIT_USAGE,
+            required: ["<actor_id> or the literal 'none' to clear"],
+            received: [`"${args[1]}"`],
+            nextSteps: ["Pass an existing actor id, or pass 'none' to explicitly clear."],
+            errorCode: "ACTOR_ID_EMPTY",
+        });
+    }
+    return applySingleScriptOp(opts, { op: "action.actor.set", at: args[0], actor_id: args[1] });
+}
+// ----- structural (multipolar delete / move / insert) -----------------------
+export async function commandDelete(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: Address missing", "Address missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["address"],
+            received: ["<empty>"],
+            nextSteps: ["Pass an address (action / scene / asset / speaker)."],
+            errorCode: "ADDRESS_MISSING",
+        });
+    }
+    const addr = parseAnyAddress(args[0]);
+    // Per-kind flag whitelist — silently ignoring wrong-kind flags hid real
+    // misuse (e.g. `delete actor:X --force` did NOT bypass ref protection, but
+    // the user assumed it did). Surface the mismatch with an explicit error.
+    const flagsUsed = {
+        strategy: opts["strategy"] !== undefined,
+        replacement: opts["replacement"] !== undefined,
+        force: Boolean(opts["force"]),
+    };
+    function rejectFlags(kind, allowed) {
+        const allow = new Set(allowed);
+        const bad = [];
+        for (const f of ["strategy", "replacement", "force"]) {
+            if (flagsUsed[f] && !allow.has(f))
+                bad.push(`--${f}`);
+        }
+        if (bad.length > 0) {
+            throw new CliError("VERB BLOCKED: flag not applicable", `${bad.join(", ")} cannot be used with ${kind} delete.`, {
+                exitCode: EXIT_USAGE,
+                required: [`for ${kind} delete: ${allowed.length === 0 ? "no extra flags" : allowed.map((f) => `--${f}`).join(" / ")}`],
+                received: bad,
+                nextSteps: ["Drop the unsupported flag(s) and retry."],
+                errorCode: "DELETE_FLAG_INVALID",
+            });
+        }
+    }
+    const op = (() => {
+        if (addr.kind === "action") {
+            rejectFlags("action", []);
+            return { op: "action.delete", at: args[0] };
+        }
+        if (addr.kind === "scene") {
+            rejectFlags("scene", ["force"]);
+            return { op: "scene.delete", at: args[0], force: Boolean(opts["force"]) };
+        }
+        if (addr.kind === "asset") {
+            rejectFlags("asset", ["strategy", "replacement"]);
+            return {
+                op: "asset.delete",
+                target: args[0],
+                strategy: opts["strategy"],
+                replacement: opts["replacement"],
+            };
+        }
+        if (addr.kind === "speaker") {
+            rejectFlags("speaker", ["strategy", "replacement"]);
+            return {
+                op: "speaker.delete",
+                target: addr.speakerId,
+                strategy: opts["strategy"],
+                replacement: opts["replacement"],
+            };
+        }
+        throw new CliError("VERB BLOCKED: delete cannot operate on this address", "delete cannot operate on this address.", {
+            exitCode: EXIT_USAGE,
+            required: ["action / scene / asset / speaker address"],
+            received: [args[0]],
+            nextSteps: ["Use a supported address."],
+            errorCode: "ADDRESS_UNSUPPORTED",
+        });
+    })();
+    return applySingleScriptOp(opts, op);
+}
+export async function commandMove(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: Move args missing", "Move args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<from-addr> <to-addr>"],
+            received: args,
+            nextSteps: ["Example: scriptctl move ep_001/scn_001#5 ep_001/scn_002#0"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    const addr = parseAnyAddress(args[0]);
+    if (addr.kind === "action") {
+        return applySingleScriptOp(opts, { op: "action.move", at: args[0], to: args[1] });
+    }
+    if (addr.kind === "scene") {
+        return applySingleScriptOp(opts, {
+            op: "scene.move", at: args[0], to: args[1], at_index: opts["at_index"] ?? opts["at"],
+        });
+    }
+    throw new CliError("VERB BLOCKED: move cannot operate on this address", "move cannot operate on this address.", {
+        exitCode: EXIT_USAGE,
+        required: ["action / scene address"],
+        received: [args[0]],
+        nextSteps: ["Use an action or scene address."],
+        errorCode: "ADDRESS_UNSUPPORTED",
+    });
+}
+export async function commandInsert(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: Insert address missing", "Insert address missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<addr>: ep_NNN/scn_NNN (action insert) or ep_NNN (scene insert)"],
+            received: ["<empty>"],
+            nextSteps: ["Example: scriptctl insert ep_001/scn_001 --type action --content \"...\""],
+            errorCode: "ADDRESS_MISSING",
+        });
+    }
+    const addr = parseAnyAddress(args[0]);
+    // Per-kind flag whitelist. Silently dropping mismatched flags hid two
+    // real bugs:
+    //   - scene insert was ignoring --scene-id (the user lost custom IDs).
+    //   - mixing action + scene insert flags (`--type` with episode addr, or
+    //     `--location` with scene addr) ran the wrong dispatch silently.
+    const flagsUsed = {
+        type: opts["type"] !== undefined,
+        content: opts["content"] !== undefined,
+        actor: (opts["actor_id"] ?? opts["actor"]) !== undefined,
+        speaker: (opts["speaker_id"] ?? opts["speaker"]) !== undefined,
+        location: opts["location"] !== undefined,
+        time: opts["time"] !== undefined,
+        space: opts["space"] !== undefined,
+        "scene-id": opts["scene_id"] !== undefined,
+    };
+    function rejectFlags(kind, allowed) {
+        const allow = new Set(allowed);
+        const bad = [];
+        for (const f of Object.keys(flagsUsed)) {
+            if (flagsUsed[f] && !allow.has(f))
+                bad.push(`--${f}`);
+        }
+        if (bad.length > 0) {
+            throw new CliError("VERB BLOCKED: flag not applicable", `${bad.join(", ")} cannot be used with ${kind} insert.`, {
+                exitCode: EXIT_USAGE,
+                required: [`for ${kind} insert: ${allowed.map((f) => `--${f}`).join(" / ")}`],
+                received: bad,
+                nextSteps: ["Drop the unsupported flag(s) and retry."],
+                errorCode: "INSERT_FLAG_INVALID",
+            });
+        }
+    }
+    if (addr.kind === "scene") {
+        rejectFlags("action", ["type", "content", "actor", "speaker"]);
+        return applySingleScriptOp(opts, {
+            op: "action.insert",
+            at: args[0],
+            type: opts["type"],
+            content: opts["content"],
+            at_index: opts["at_index"] ?? opts["at"],
+            before: opts["before"],
+            after: opts["after"],
+            actor_id: opts["actor_id"] ?? opts["actor"],
+            speaker_id: opts["speaker_id"] ?? opts["speaker"],
+        });
+    }
+    if (addr.kind === "episode") {
+        rejectFlags("scene", ["location", "time", "space", "scene-id"]);
+        return applySingleScriptOp(opts, {
+            op: "scene.insert",
+            at: addr.episodeId,
+            location: opts["location"],
+            time: opts["time"],
+            space: opts["space"],
+            // Forward --scene-id (was previously silently dropped — scene.insert op
+            // reads `scene_id` to honor user-supplied ids for round-trip stability).
+            scene_id: opts["scene_id"],
+            at_index: opts["at_index"] ?? opts["at"],
+            before: opts["before"],
+            after: opts["after"],
+        });
+    }
+    throw new CliError("VERB BLOCKED: insert cannot operate on this address", "insert cannot operate on this address.", {
+        exitCode: EXIT_USAGE,
+        required: ["ep_NNN (scene insert) or ep_NNN/scn_NNN (action insert)"],
+        received: [args[0]],
+        nextSteps: ["Use an episode or scene address."],
+        errorCode: "ADDRESS_UNSUPPORTED",
+    });
+}
+export async function commandSplit(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: Scene ref missing", "Scene ref missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<ep/scn>"],
+            received: ["<empty>"],
+            nextSteps: ["Example: scriptctl split ep_001/scn_005 --at 7"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    // Commander hands back --at as a string; the scene.split handler does a
+    // strict typeof === "number" check (no implicit coercion), so we coerce here
+    // before dispatch. Without this, every CLI `scriptctl split` invocation
+    // would fail with SPLIT_INDEX_INVALID.
+    const rawAt = opts["at_index"] ?? opts["at"];
+    const atIndex = rawAt === undefined || rawAt === null || rawAt === "" ? undefined : Number(rawAt);
+    if (atIndex !== undefined && (!Number.isFinite(atIndex) || !Number.isInteger(atIndex))) {
+        throw new CliError("VERB BLOCKED: --at not an integer", "--at must be an integer.", {
+            exitCode: EXIT_USAGE,
+            required: ["--at <integer>"],
+            received: [String(rawAt)],
+            nextSteps: ["Pass an integer action index."],
+            errorCode: "AT_INDEX_INVALID",
+        });
+    }
+    return applySingleScriptOp(opts, {
+        op: "scene.split",
+        at: args[0],
+        at_index: atIndex,
+        new_scene_id: opts["new_scene_id"],
+    });
+}
+export async function commandMerge(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: Source address missing", "Source address missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<src-addr> --into <dst-addr>"],
+            received: args,
+            nextSteps: ["Example: scriptctl merge actor:act_001 --into actor:act_002"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    const into = strOf(opts["into"]);
+    if (!into) {
+        throw new CliError("VERB BLOCKED: --into missing", "--into missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["--into <dst-addr>"],
+            received: ["<missing>"],
+            nextSteps: ["Pass --into <addr>."],
+            errorCode: "INTO_MISSING",
+        });
+    }
+    const fromAddr = parseAnyAddress(args[0]);
+    const intoAddr = parseAnyAddress(into);
+    if (fromAddr.kind === "asset" && intoAddr.kind === "asset") {
+        return applySingleScriptOp(opts, { op: "asset.merge", from: args[0], into });
+    }
+    if (fromAddr.kind === "scene" && intoAddr.kind === "scene") {
+        return applySingleScriptOp(opts, { op: "scene.merge", from: args[0], into });
+    }
+    throw new CliError("VERB BLOCKED: merge address mismatch", "merge: both sides must be the same kind (asset or scene).", {
+        exitCode: EXIT_USAGE,
+        required: ["asset & asset, or scene & scene"],
+        received: [`${args[0]} → ${into}`],
+        nextSteps: ["Use two addresses of the same kind."],
+        errorCode: "MERGE_ADDR_MISMATCH",
+    });
+}
+// ----- asset metadata -------------------------------------------------------
+export async function commandRename(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: Rename args missing", "Rename args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<asset-addr> <new-name>"],
+            received: args,
+            nextSteps: ["Example: scriptctl rename actor:act_001 \"陈墨\""],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return applySingleScriptOp(opts, { op: "asset.rename", target: args[0], name: args[1] });
+}
+export async function commandDescribe(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: Describe args missing", "Describe args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<addr> <text>"],
+            received: args,
+            nextSteps: ["Example: scriptctl describe actor:act_001 \"男主\" or scriptctl describe actor:act_001/st_calm \"...\""],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    const addr = parseAnyAddress(args[0]);
+    if (addr.kind === "state") {
+        return applySingleScriptOp(opts, { op: "state.describe", target: args[0], description: args[1] });
+    }
+    if (addr.kind === "asset") {
+        return applySingleScriptOp(opts, { op: "asset.describe", target: args[0], description: args[1] });
+    }
+    throw new CliError("VERB BLOCKED: describe address invalid", "describe address invalid.", {
+        exitCode: EXIT_USAGE,
+        required: ["asset address (e.g. actor:act_001) or state address (e.g. actor:act_001/st_calm)"],
+        received: [args[0]],
+        nextSteps: ["Use a supported address."],
+        errorCode: "ADDRESS_UNSUPPORTED",
+    });
+}
+export async function commandAlias(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: Asset address missing", "Asset address missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<asset-addr>"],
+            received: ["<empty>"],
+            nextSteps: ["Example: scriptctl alias actor:act_001 --add \"陈总\""],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    // appendStr collectors default to []; empty arrays are truthy, so we MUST
+    // check `.length === 0` rather than `!add` (which is always false here).
+    // Without this, passing only --add still runs the remove op with alias=[]
+    // and crashes mid-write at op layer after the add already succeeded.
+    const add = asList(opts["add"]);
+    const remove = asList(opts["remove"]);
+    if (add.length === 0 && remove.length === 0) {
+        throw new CliError("VERB BLOCKED: --add or --remove required", "--add or --remove required.", {
+            exitCode: EXIT_USAGE,
+            required: ["--add <alias> and/or --remove <alias>"],
+            received: ["<empty>"],
+            nextSteps: ["Pass --add and/or --remove at least once."],
+            errorCode: "ALIAS_EMPTY",
+        });
+    }
+    // Run only the ops that have content; either one of them solo, or both.
+    let lastReport = null;
+    if (add.length > 0) {
+        lastReport = await applySingleScriptOp(opts, { op: "asset.alias.add", target: args[0], alias: add });
+    }
+    if (remove.length > 0) {
+        lastReport = await applySingleScriptOp(opts, { op: "asset.alias.remove", target: args[0], alias: remove });
+    }
+    return lastReport;
+}
+export async function commandRole(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: Role args missing", "Role args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<actor:id> <主角|配角>"],
+            received: args,
+            nextSteps: ["Example: scriptctl role actor:act_001 主角"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return applySingleScriptOp(opts, { op: "asset.role.set", target: args[0], role_type: args[1] });
+}
+export async function commandWorldview(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: Worldview value missing", "Worldview value missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<value>"],
+            received: ["<empty>"],
+            nextSteps: ["Example: scriptctl worldview 现代"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return applySingleScriptOp(opts, { op: "meta.worldview.set", worldview: args[0] });
+}
+// ----- state management -----------------------------------------------------
+export async function commandStateAdd(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: state-add args missing", "state-add args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<asset-addr> <state-name>"],
+            received: args,
+            nextSteps: ["Example: scriptctl state-add actor:act_001 \"震惊\""],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return applySingleScriptOp(opts, {
+        op: "state.add",
+        target: args[0],
+        name: args[1],
+        description: opts["description"],
+        state_id: opts["state_id"],
+    });
+}
+export async function commandStateRename(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: state-rename args missing", "state-rename args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<state-addr> <new-name>"],
+            received: args,
+            nextSteps: ["Example: scriptctl state-rename actor:act_001/st_calm \"平静（新）\""],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return applySingleScriptOp(opts, { op: "state.rename", target: args[0], name: args[1] });
+}
+export async function commandStateDelete(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: state-delete address missing", "state-delete address missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<state-addr>"],
+            received: ["<empty>"],
+            nextSteps: ["Example: scriptctl state-delete actor:act_001/st_calm --strategy remove"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return applySingleScriptOp(opts, {
+        op: "state.delete",
+        target: args[0],
+        strategy: opts["strategy"],
+        replacement: opts["replacement"],
+    });
+}
+// ----- scene context ref ----------------------------------------------------
+export async function commandContext(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: context args missing", "context args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<scene-addr> <asset-addr>"],
+            received: args,
+            nextSteps: ["Example: scriptctl context ep_001/scn_001 actor:act_001 --state st_calm"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    // Mutex XOR: help-text promises 'exactly one of --state / --clear /
+    // --remove'. Enforce it instead of silently picking by precedence.
+    const stateSet = opts["state"] !== undefined;
+    const clearSet = Boolean(opts["clear"]);
+    const removeSet = Boolean(opts["remove"]);
+    const flagCount = (stateSet ? 1 : 0) + (clearSet ? 1 : 0) + (removeSet ? 1 : 0);
+    if (flagCount === 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",
+        });
+    }
+    if (flagCount > 1) {
+        const passed = [];
+        if (stateSet)
+            passed.push("--state");
+        if (clearSet)
+            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",
+        });
+    }
+    if (removeSet) {
+        return applySingleScriptOp(opts, { op: "context.ref.remove", at: args[0], target: args[1] });
+    }
+    if (clearSet) {
+        return applySingleScriptOp(opts, { op: "context.clear", at: args[0], target: args[1] });
+    }
+    const state = opts["state"];
+    return applySingleScriptOp(opts, {
+        op: "context.set",
+        at: args[0],
+        target: args[1],
+        state: state === "none" ? "" : state,
+    });
+}
+// ----- state change / transition --------------------------------------------
+export async function commandStateChange(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: state-change args missing", "state-change args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<action-addr> <asset-addr>"],
+            received: args,
+            nextSteps: ["Example: scriptctl state-change ep_001/scn_001#3 actor:act_001 --to st_shock"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    // Mutex XOR: --to (set) and --clear (remove) cannot coexist.
+    const toSet = opts["to"] !== undefined;
+    const clearSet = Boolean(opts["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",
+        });
+    }
+    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",
+        });
+    }
+    if (clearSet) {
+        return applySingleScriptOp(opts, { op: "action.state.remove", at: args[0], target: args[1] });
+    }
+    return applySingleScriptOp(opts, {
+        op: "action.state.change",
+        at: args[0],
+        target: args[1],
+        to: opts["to"],
+        from: opts["from"],
+        effective: opts["effective"] || "after",
+    });
+}
+export async function commandTransition(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 2) {
+        throw new CliError("VERB BLOCKED: transition args missing", "transition args missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<action-addr> <asset-addr>"],
+            received: args,
+            nextSteps: ["Example: scriptctl transition ep_001/scn_001#3 actor:act_001 --process \"...\" --contrast \"...\""],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    // Mutex XOR: --clear vs --process/--contrast.
+    const setBoth = opts["process"] !== undefined || opts["contrast"] !== undefined;
+    const clearSet = Boolean(opts["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",
+        });
+    }
+    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",
+        });
+    }
+    if (clearSet) {
+        return applySingleScriptOp(opts, { op: "action.transition.clear", at: args[0], target: args[1] });
+    }
+    return applySingleScriptOp(opts, {
+        op: "action.transition.set",
+        at: args[0],
+        target: args[1],
+        process: opts["process"],
+        contrast: opts["contrast"],
+    });
+}
+// ----- dialogue / speaker ---------------------------------------------------
+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 async function commandDialogue(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: dialogue action ref missing", "dialogue action ref missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<action-addr>"],
+            received: ["<empty>"],
+            nextSteps: ["Example: scriptctl dialogue ep_001/scn_001#3 --speakers spk_001"],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    const speakers = splitSpeakerList(opts["speakers"]);
+    if (speakers.length === 0) {
+        throw new CliError("VERB BLOCKED: --speakers required", "--speakers required.", {
+            exitCode: EXIT_USAGE,
+            required: ["--speakers id1[,id2,...]"],
+            received: ["<empty>"],
+            nextSteps: ["Pass one or more speaker ids."],
+            errorCode: "SPEAKERS_EMPTY",
+        });
+    }
+    return applySingleScriptOp(opts, {
+        op: "dialogue.speakers",
+        at: args[0],
+        speakers,
+        delivery: opts["delivery"] || (speakers.length > 1 ? "simultaneous" : "single"),
+    });
+}
+export async function commandOverlap(opts) {
+    const args = asList(opts["_args"]);
+    if (args.length < 1) {
+        throw new CliError("VERB BLOCKED: overlap action ref missing", "overlap action ref missing.", {
+            exitCode: EXIT_USAGE,
+            required: ["<action-addr>"],
+            received: ["<empty>"],
+            nextSteps: ["Example: scriptctl overlap ep_001/scn_001#3 --line \"spk_a:hi\" --line \"spk_b:hi\""],
+            errorCode: "ARGS_MISSING",
+        });
+    }
+    return applySingleScriptOp(opts, {
+        op: "dialogue.overlap",
+        at: args[0],
+        lines: opts["line"] || [],
+    });
+}
+export async function commandAddSpeaker(opts) {
+    return applySingleScriptOp(opts, {
+        op: "speaker.add",
+        kind: opts["kind"],
+        name: opts["name"],
+        source_id: opts["source_id"],
+        voice_desc: opts["voice_desc"],
+        speaker_id: opts["speaker_id"],
+    });
+}
 //# sourceMappingURL=script.js.map