@lingjingai/scriptctl 0.20.0 → 0.21.0

package/dist/usecases/script.js

@@ -1,2348 +0,0 @@
-import * as fs from "node:fs";
-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, blankScript, collectAssetRefs, collectStateRefs, parseAnyAddress, parseStateTarget, validateScript, PATCH_OP_SCHEMA, } from "../domain/script-core.js";
-import { RemoteScriptOutputStore } from "../infra/script-output-api.js";
-import { LocalScriptOutputStore } from "../infra/local-script-output-store.js";
-import { ScriptOutputApiError, resolveOutputMode, } from "../infra/script-output-store.js";
-import { readRunState, summarizeIssues, updateRunState, } from "./direct.js";
-import { sortDeep } from "../domain/direct-core.js";
-function strOf(v) {
-    if (v === null || v === undefined)
-        return "";
-    return String(v);
-}
-function isDict(v) {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-function isList(v) {
-    return Array.isArray(v);
-}
-function asList(v) {
-    return Array.isArray(v) ? v : [];
-}
-function parseBound(v) {
-    if (v === null || v === undefined || v === "")
-        return null;
-    const n = Number(v);
-    if (!Number.isFinite(n)) {
-        throw new CliError("SCRIPT INSPECT BLOCKED: Bound invalid", "--min-chars / --max-chars must be a non-negative integer.", {
-            exitCode: EXIT_USAGE,
-            required: ["non-negative integer"],
-            received: [strOf(v)],
-            nextSteps: ["Pass --min-chars 1000 (positive integer)."],
-            errorCode: "INSPECT_BOUND_INVALID",
-        });
-    }
-    return Math.max(0, Math.floor(n));
-}
-// Count characters in an episode's actions. Splits dialogue-class (`dialogue`,
-// `inner_thought`) from narrative/screen-text (`action`) so agents can answer
-// "which episodes exceed N spoken chars" vs. raw size. Overlap dialogue stores
-// content on `lines[].content`; non-overlap stores it on `content`.
-function episodeCharCounts(scenes) {
-    let dialogue = 0;
-    let action = 0;
-    for (const scene of scenes) {
-        for (const a of asList(scene["actions"])) {
-            const kind = strOf(a["type"]).trim();
-            let chars = strOf(a["content"]).length;
-            for (const line of asList(a["lines"])) {
-                chars += strOf(line["content"]).length;
-            }
-            if (kind === "dialogue" || kind === "inner_thought")
-                dialogue += chars;
-            else
-                action += chars;
-        }
-    }
-    return { total: dialogue + action, dialogue, action };
-}
-// ---------------------------------------------------------------------------
-// ScriptEditSession
-// ---------------------------------------------------------------------------
-export class ScriptEditSession {
-    workspace;
-    script;
-    scriptPath;
-    client;
-    projectGroupNo;
-    revision;
-    constructor(opts) {
-        this.workspace = opts.workspace;
-        this.script = opts.script;
-        this.scriptPath = opts.scriptPath ?? null;
-        this.client = opts.client ?? null;
-        this.projectGroupNo = opts.projectGroupNo ?? null;
-        this.revision = opts.revision ?? null;
-    }
-    get remote() {
-        return this.client !== null;
-    }
-    get artifactLabel() {
-        if (this.remote) {
-            // Public label — strips the internal `db:/script-output/project-groups/`
-            // storage prefix (which leaks implementation), but keeps the project id
-            // and revision so two different project groups at the same revision stay
-            // distinguishable in user-visible report.artifacts entries. The project
-            // id is not a secret: the user supplies it themselves via
-            // `--project-group-no` or env config.
-            return `script-output/${this.projectGroupNo}@revision/${this.revision ?? 0}`;
-        }
-        return this.scriptPath ?? "";
-    }
-}
-export function scriptOutputClient(opts) {
-    const mode = resolveOutputMode().mode;
-    try {
-        if (mode === "local") {
-            return LocalScriptOutputStore.fromEnv(strOf(opts["workspace_path"]).trim() || undefined);
-        }
-        return RemoteScriptOutputStore.fromEnv(strOf(opts["project_group_no"]).trim() || null);
-    }
-    catch (exc) {
-        // ScriptOutputApiError carries a `configMissing` discriminator so callers
-        // can show the user which slot is unconfigured without naming the env var.
-        if (exc instanceof ScriptOutputApiError) {
-            const { title, message } = describeConfigMissing(mode, exc.configMissing);
-            throw new CliError(title, message, {
-                exitCode: EXIT_INPUT,
-                required: [
-                    mode === "local"
-                        ? "SCRIPTCTL_OUTPUT_DIR"
-                        : "AWB_BASE_URL, LINGJING_AWB_ACCESS_KEY, and SANDBOX_PROJECT_GROUP_NO (or --project-group-no)",
-                ],
-                received: [exc.message, `configMissing: ${exc.configMissing ?? "unknown"}`],
-                nextSteps: ["Run `scriptctl doctor` to identify missing configuration."],
-                errorCode: "SCRIPT_API_CONFIG_MISSING",
-            });
-        }
-        // Belt-and-suspenders: anything else that escapes RemoteScriptOutputStore.fromEnv
-        // (a TypeError on a malformed gateway URL, future programmer errors) still
-        // surfaces as a clean CliError envelope rather than the generic
-        // "RUNTIME FAILED: Unexpected error" path in cli.ts.
-        const raw = exc instanceof Error ? exc.message : String(exc);
-        throw new CliError(mode === "local"
-            ? "SCRIPT API BLOCKED: local output dir not configured"
-            : "SCRIPT API BLOCKED: gateway not configured", mode === "local"
-            ? "Local output dir is not configured for this environment."
-            : "Gateway is not configured for this environment.", {
-            exitCode: EXIT_INPUT,
-            required: [mode === "local" ? "valid local output dir" : "valid gateway configuration"],
-            received: [raw],
-            nextSteps: ["Run `scriptctl doctor` to identify missing configuration."],
-            errorCode: "SCRIPT_API_CONFIG_MISSING",
-        });
-    }
-}
-function describeConfigMissing(mode, slot) {
-    // Mode wins over slot — if the caller is in local mode, the failure is
-    // unambiguously about the output dir even if the underlying error tagged
-    // the slot differently.
-    // NOTE: this early return short-circuits the exhaustive switch below. New
-    // ConfigMissingSlot values for remote-mode callers are guarded by the
-    // switch (TS will flag a missing case); values intended for local-mode-only
-    // callers must be handled explicitly above this guard.
-    if (mode === "local") {
-        return {
-            title: "SCRIPT API BLOCKED: local output dir missing",
-            message: "Local output dir is not configured. Set `SCRIPTCTL_OUTPUT_DIR` to a writable directory.",
-        };
-    }
-    // Unknown / unspecified failures in remote mode default to the gateway
-    // bucket — keeps the pre-0.7.0 UX stable.
-    if (slot === null) {
-        return {
-            title: "SCRIPT API BLOCKED: gateway not configured",
-            message: "Gateway is not configured for this environment.",
-        };
-    }
-    // After the two guards above, `slot` is narrowed to ConfigMissingSlot. TS
-    // exhaustiveness on the switch means adding a new slot without handling it
-    // here is a compile error — `assertNever` makes the intent explicit.
-    switch (slot) {
-        case "output":
-            return {
-                title: "SCRIPT API BLOCKED: local output dir missing",
-                message: "Local output dir is not configured. Set `SCRIPTCTL_OUTPUT_DIR` to a writable directory.",
-            };
-        case "project":
-            return {
-                title: "SCRIPT API BLOCKED: project identifier missing",
-                message: "Project identifier is not configured. Pass `--project-group-no <id>` or configure the project for this environment.",
-            };
-        case "access":
-            return {
-                title: "SCRIPT API BLOCKED: access credential missing",
-                message: "Access credential is not configured for this environment.",
-            };
-        case "gateway":
-            return {
-                title: "SCRIPT API BLOCKED: gateway not configured",
-                message: "Gateway is not configured for this environment.",
-            };
-        default:
-            return assertNever(slot);
-    }
-}
-function assertNever(x) {
-    throw new Error(`describeConfigMissing: unhandled ConfigMissingSlot ${JSON.stringify(x)}`);
-}
-export function apiErrorToCli(title, exc) {
-    const rawMessage = exc.message || "script-output API failed";
-    // Use the gateway's own canonical Chinese keywords as the only signal. Free
-    // text like "revision" or "not found" can leak in from upstream proxies,
-    // DNS errors ("name not found"), or HTTP 404 routing mismatches — matching on
-    // those substrings would misroute auth/network failures into the conflict /
-    // missing-script UX. The fake-gateway contract is `code:9001` + Chinese
-    // keyword for both conflict and missing, so the keyword is precise enough.
-    const isConflict = rawMessage.includes("版本冲突");
-    const isMissing = rawMessage.includes("剧本不存在");
-    const publicMessage = isConflict
-        ? "Script has been updated by another revision; reload and retry."
-        : isMissing
-            ? "Script not found on the gateway."
-            : "Gateway request failed.";
-    return new CliError(title, publicMessage, {
-        exitCode: exc.status !== null && exc.status >= 500 ? EXIT_RUNTIME : EXIT_INPUT,
-        required: ["successful script-output gateway request"],
-        received: [rawMessage, `status: ${exc.status ?? "<unknown>"}`],
-        nextSteps: [
-            isConflict
-                ? "Reload the latest script revision and retry."
-                : isMissing
-                    ? "Run `scriptctl direct export` to publish a script first."
-                    : "Run `scriptctl doctor` to verify gateway configuration; retry if it was transient.",
-        ],
-        errorCode: isConflict
-            ? "SCRIPT_REVISION_CONFLICT"
-            : isMissing
-                ? "SCRIPT_NOT_FOUND"
-                : "SCRIPT_API_FAILED",
-    });
-}
-export async function currentRevisionOrZero(client) {
-    try {
-        const revision = await client.getRevision();
-        if (!revision)
-            return 0;
-        return Number(revision["revision"] ?? 0);
-    }
-    catch (exc) {
-        if (exc instanceof ScriptOutputApiError) {
-            throw apiErrorToCli("SCRIPT API BLOCKED: Revision query failed", exc);
-        }
-        throw exc;
-    }
-}
-async function loadRemoteScript(opts, workspace) {
-    const client = scriptOutputClient(opts);
-    let script;
-    let revision;
-    try {
-        script = await client.getScript();
-        revision = await client.getRevision();
-    }
-    catch (exc) {
-        if (exc instanceof ScriptOutputApiError) {
-            throw apiErrorToCli("SCRIPT API BLOCKED: Script query failed", exc);
-        }
-        throw exc;
-    }
-    if (script === null) {
-        throw new CliError("SCRIPT BLOCKED: Final script not found", "No script has been published for this project.", {
-            exitCode: EXIT_INPUT,
-            required: ["existing script-output project document"],
-            received: [`projectGroupNo=${client.projectGroupNo}`],
-            nextSteps: ["Run `scriptctl direct export` first, or pass `--script-path` to edit a local intermediate script JSON."],
-            errorCode: "SCRIPT_NOT_FOUND",
-        });
-    }
-    if (!isDict(script)) {
-        throw new CliError("SCRIPT BLOCKED: script root invalid", "script root invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["script root object"],
-            received: [typeof script],
-            nextSteps: ["Replace the final script with a valid script document object."],
-            errorCode: "SCRIPT_ROOT_INVALID",
-        });
-    }
-    return new ScriptEditSession({
-        workspace,
-        script,
-        client,
-        projectGroupNo: client.projectGroupNo,
-        revision: Number((revision ?? {})["revision"] ?? 0),
-    });
-}
-async function loadScriptForEdit(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    // --draft is the blessed entrance for editing the direct intermediate draft:
-    // it resolves to script.initial.json without exposing the storage path to the
-    // agent. It is mutually exclusive with the raw --script-path and the DB-mode
-    // --project-group-no (both name a different target).
-    const draft = Boolean(opts["draft"]);
-    let draftPath = null;
-    if (draft) {
-        if (opts["script_path"]) {
-            throw new CliError("SCRIPT BLOCKED: --draft conflicts with --script-path", "--draft conflicts with --script-path.", {
-                exitCode: EXIT_USAGE,
-                required: ["either --draft (edit the direct draft) or --script-path (edit a named local script), not both"],
-                received: ["--draft and --script-path"],
-                nextSteps: ["Drop one of the two flags and retry."],
-                errorCode: "DRAFT_FLAG_CONFLICT",
-            });
-        }
-        if (opts["project_group_no"]) {
-            throw new CliError("SCRIPT BLOCKED: --draft conflicts with --project-group-no", "--draft conflicts with --project-group-no.", {
-                exitCode: EXIT_USAGE,
-                required: ["either --draft (edit the local direct draft) or --project-group-no (edit the DB script), not both"],
-                received: ["--draft and --project-group-no"],
-                nextSteps: ["Drop one of the two flags and retry."],
-                errorCode: "DRAFT_FLAG_CONFLICT",
-            });
-        }
-        draftPath = path.join(directDir(workspace), "script.initial.json");
-        if (!exists(draftPath)) {
-            throw new CliError("SCRIPT BLOCKED: Draft script not found", "Direct draft script not found.", {
-                exitCode: EXIT_INPUT,
-                required: ["a direct draft produced by `direct init`"],
-                received: [draftPath],
-                nextSteps: ["Run `scriptctl direct init` first, then edit with --draft."],
-                errorCode: "SCRIPT_NOT_FOUND",
-            });
-        }
-    }
-    // Resolve the local file from --draft or --script-path WITHOUT mutating opts:
-    // commandAlias loads twice with the same opts, and writing script_path back
-    // would make the second load see a phantom --script-path and reject --draft.
-    if (!draftPath && !opts["script_path"]) {
-        return loadRemoteScript(opts, workspace);
-    }
-    const p = draftPath ?? scriptJsonPath(opts);
-    if (!exists(p)) {
-        throw new CliError("SCRIPT BLOCKED: Local script file not found", "Local script file not found.", {
-            exitCode: EXIT_INPUT,
-            required: ["--script-path existing local script JSON"],
-            received: [p],
-            nextSteps: ["Pass --script-path to an existing local intermediate script JSON, or omit --script-path to use DB-backed script-output."],
-            errorCode: "SCRIPT_NOT_FOUND",
-        });
-    }
-    let data;
-    try {
-        data = readJson(p);
-    }
-    catch (exc) {
-        throw new CliError("SCRIPT BLOCKED: script JSON invalid", "script JSON invalid.", {
-            exitCode: EXIT_INPUT,
-            required: ["valid JSON"],
-            received: [`${p}: ${exc.message}`],
-            nextSteps: ["Fix the local script JSON syntax before editing."],
-            errorCode: "SCRIPT_JSON_INVALID",
-        });
-    }
-    if (!isDict(data)) {
-        throw new CliError("SCRIPT BLOCKED: script root invalid", "script root invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["script root object"],
-            received: [Array.isArray(data) ? "array" : typeof data],
-            nextSteps: ["Use a valid script document object."],
-            errorCode: "SCRIPT_ROOT_INVALID",
-        });
-    }
-    return new ScriptEditSession({ workspace, scriptPath: p, script: data });
-}
-function validateSession(session, opts = {}) {
-    const requireSource = opts.requireSource ?? false;
-    if (!session.remote) {
-        return validateScript(session.workspace, session.scriptPath, { requireSource });
-    }
-    const tmpPath = path.join(os.tmpdir(), `scriptctl-db-script-${randomUUID()}.json`);
-    try {
-        fs.writeFileSync(tmpPath, JSON.stringify(session.script, null, 2) + "\n", "utf-8");
-        const validation = validateScript(session.workspace, tmpPath, { requireSource });
-        validation["script_path"] = session.artifactLabel;
-        writeJson(path.join(directDir(session.workspace), "validation.json"), validation);
-        return validation;
-    }
-    finally {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            // ignore
-        }
-    }
-}
-function validationIssuePath(issue) {
-    if (issue["path"])
-        return strOf(issue["path"]);
-    const parts = [];
-    if (issue["episode"] !== null && issue["episode"] !== undefined)
-        parts.push(strOf(issue["episode"]));
-    if (issue["scene"] !== null && issue["scene"] !== undefined)
-        parts.push(strOf(issue["scene"]));
-    if (issue["action_index"] !== null && issue["action_index"] !== undefined)
-        parts.push(`action[${issue["action_index"]}]`);
-    return parts.length > 0 ? parts.join("/") : null;
-}
-function validationIssueSeverity(raw) {
-    const severity = strOf(raw || "info");
-    if (severity === "blocking" || severity === "error")
-        return "error";
-    if (severity === "warning")
-        return "warning";
-    return "info";
-}
-function validationToApiPayload(validation) {
-    const issues = asList(validation["issues"]);
-    const status = validation["passed"] ? "valid" : "invalid";
-    const summary = {
-        passed: Boolean(validation["passed"]),
-        hasBlocking: Boolean(validation["has_blocking"]),
-        stats: validation["stats"] ?? {},
-        issueCount: issues.length,
-    };
-    const apiIssues = [];
-    for (const issue of issues) {
-        if (!isDict(issue))
-            continue;
-        const payload = { ...issue };
-        for (const key of ["severity", "code", "path", "summary", "repair_hint"])
-            delete payload[key];
-        apiIssues.push({
-            severity: validationIssueSeverity(issue["severity"]),
-            code: strOf(issue["code"] || "SCRIPT_VALIDATION_ISSUE"),
-            path: validationIssuePath(issue),
-            summary: strOf(issue["summary"]),
-            repairHint: issue["repair_hint"],
-            payload,
-        });
-    }
-    return [status, summary, apiIssues];
-}
-async function syncValidationResult(session, validation, revision) {
-    if (!session.remote || session.client === null)
-        return;
-    const targetRevision = Number(revision ?? session.revision ?? 0);
-    if (targetRevision <= 0)
-        return;
-    const [status, summary, issues] = validationToApiPayload(validation);
-    try {
-        await session.client.saveValidationResult({
-            revision: targetRevision,
-            validationStatus: status,
-            validationSummary: summary,
-            issues,
-        });
-    }
-    catch (exc) {
-        if (exc instanceof ScriptOutputApiError) {
-            throw apiErrorToCli("SCRIPT API BLOCKED: Validation sync failed", exc);
-        }
-        throw exc;
-    }
-}
-// 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;
-    const canonical = JSON.stringify(sortDeep({
-        op,
-        script: payload.script,
-    }));
-    return `scriptctl:${op}:${sha256Text(canonical)}`;
-}
-async function saveScriptSession(session, opts, op) {
-    if (!session.remote) {
-        writeJson(session.scriptPath, session.script);
-        return [null, false];
-    }
-    if (session.client === null)
-        throw new Error("remote script session missing client");
-    const baseRevision = Number(session.revision ?? 0);
-    const requestId = requestIdForScriptWrite(opts, op, { script: session.script });
-    let res;
-    try {
-        res = await session.client.replaceScript({
-            requestId,
-            baseRevision,
-            script: session.script,
-            source: "ctl",
-        });
-    }
-    catch (exc) {
-        if (exc instanceof ScriptOutputApiError) {
-            throw apiErrorToCli("SCRIPT API BLOCKED: Script write failed", exc);
-        }
-        throw exc;
-    }
-    session.revision = Number(res["revision"] ?? session.revision ?? 0);
-    return [session.revision, Boolean(res["idempotent"])];
-}
-function scriptSourceText(workspace) {
-    const sourcePath = path.join(workspace, "source.txt");
-    return exists(sourcePath) ? readText(sourcePath) : "";
-}
-function patchOperationsFromPayload(payload) {
-    let operations;
-    if (isList(payload)) {
-        operations = payload;
-    }
-    else if (isDict(payload) && isList(payload["ops"])) {
-        operations = payload["ops"];
-    }
-    else if (isDict(payload) && isList(payload["operations"])) {
-        operations = payload["operations"];
-    }
-    else if (isDict(payload)) {
-        operations = [payload];
-    }
-    else {
-        throw new CliError("PATCH BLOCKED: Patch schema invalid", "Patch schema invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["object, array, object with ops[], or object with operations[]"],
-            received: [Array.isArray(payload) ? "array" : typeof payload],
-            nextSteps: ["Fix patch JSON and rerun patch."],
-        });
-    }
-    if (operations.some((op) => !isDict(op))) {
-        throw new CliError("PATCH BLOCKED: Patch operation invalid", "Patch operation invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["each operation must be an object"],
-            received: [JSON.stringify(operations).slice(0, 500)],
-            nextSteps: ["Fix patch JSON and rerun patch."],
-        });
-    }
-    return operations;
-}
-// ---------------------------------------------------------------------------
-// commandScriptValidate / commandScriptInspect
-// ---------------------------------------------------------------------------
-export async function commandScriptValidate(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const session = await loadScriptForEdit(opts);
-    const validation = validateSession(session);
-    await syncValidationResult(session, validation);
-    const stats = validation["stats"] ?? {};
-    const passed = Boolean(validation["passed"]);
-    const report = {
-        title: passed ? "SCRIPT VALIDATE PASSED" : "SCRIPT VALIDATE NEEDS REPAIR",
-        op: "script.validate",
-        changed: false,
-        summary: `episodes=${stats["episodes"] ?? 0}, scenes=${stats["scenes"] ?? 0}, actions=${stats["actions"] ?? 0}`,
-        result: [
-            `episodes: ${stats["episodes"] ?? 0}`,
-            `scenes: ${stats["scenes"] ?? 0}`,
-            `actions: ${stats["actions"] ?? 0}`,
-            `speakers: ${stats["speakers"] ?? 0}`,
-        ],
-        issues: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel, path.join(directDir(workspace), "validation.json")],
-        next: [passed ? "Continue editing the final script." : "Inspect issues and apply a script patch."],
-    };
-    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
-}
-function actionAddress(epId, sceneId, idx) {
-    return `${epId}/${sceneId}#${idx}`;
-}
-function formatInspectAction(epId, sceneId, idx, action) {
-    const addr = actionAddress(epId, sceneId, idx);
-    const type = strOf(action["type"]).trim() || "action";
-    const delivery = strOf(action["delivery"]).trim();
-    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(action["speaker_id"]).trim();
-    const actorId = strOf(action["actor_id"]).trim();
-    const who = speakerId || actorId;
-    let content = strOf(action["content"]);
-    if (!content) {
-        const lines = asList(action["lines"]);
-        if (lines.length > 0)
-            content = lines.map((l) => strOf(l["content"])).join(" / ");
-    }
-    const prefix = who ? `${addr} [${tag} ${who}]` : `${addr} [${tag}]`;
-    return content ? `${prefix} ${content}` : prefix;
-}
-// ---------------------------------------------------------------------------
-// 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 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: ["existing patch JSON file"],
-            received: [patchPath],
-            nextSteps: ["Write patch JSON and rerun."],
-            errorCode: "PATCH_NOT_FOUND",
-        });
-    }
-    let payload;
-    try {
-        payload = readJson(patchPath);
-    }
-    catch (exc) {
-        throw new CliError("SCRIPT PATCH BLOCKED: Patch JSON invalid", "Patch JSON invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["valid JSON patch"],
-            received: [`${patchPath}: ${exc.message}`],
-            nextSteps: ["Fix patch JSON and rerun."],
-            errorCode: "PATCH_JSON_INVALID",
-        });
-    }
-    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);
-    const passed = Boolean(validation["passed"]);
-    const resultLines = [
-        `operations: ${applied.length}`,
-        `validation: ${passed ? "passed" : "needs repair"}`,
-    ];
-    if (session.remote) {
-        resultLines.push(`revision: ${newRevision}`);
-        resultLines.push(`idempotent: ${String(idempotent).toLowerCase()}`);
-    }
-    const report = {
-        title: passed ? "SCRIPT PATCH APPLIED" : "SCRIPT PATCH APPLIED: Validation needs repair",
-        op: applied.length === 1 ? applied[0] : "script.patch",
-        changed: applied.length > 0,
-        summary: `applied ${applied.length} operation(s)`,
-        warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
-        result: resultLines,
-        issues: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel, path.join(directDir(workspace), "validation.json")],
-        next: [passed ? "Continue editing the final script." : "Inspect issues and apply another patch."],
-    };
-    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
-}
-// ---------------------------------------------------------------------------
-// Single-op helpers
-// ---------------------------------------------------------------------------
-async function applySingleScriptOp(opts, op) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const session = await loadScriptForEdit(opts);
-    const script = session.script;
-    const applied = applyPatchOperations(script, scriptSourceText(workspace), [op]);
-    const opName = applied[0] ?? strOf(op["op"]);
-    const [newRevision, idempotent] = await saveScriptSession(session, opts, opName);
-    const validation = validateSession(session);
-    await syncValidationResult(session, validation, newRevision);
-    const passed = Boolean(validation["passed"]);
-    const resultLines = [
-        `operation: ${opName}`,
-        `validation: ${passed ? "passed" : "needs repair"}`,
-    ];
-    if (session.remote) {
-        resultLines.push(`revision: ${newRevision}`);
-        resultLines.push(`idempotent: ${String(idempotent).toLowerCase()}`);
-    }
-    const report = {
-        title: passed ? "SCRIPT OP APPLIED" : "SCRIPT OP APPLIED: Validation needs repair",
-        op: opName,
-        changed: applied.length > 0,
-        summary: summarizeScriptOp(script, op),
-        warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
-        result: resultLines,
-        issues: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel, path.join(directDir(workspace), "validation.json")],
-        next: [passed ? "Continue editing the final script." : "Inspect issues and apply another patch."],
-    };
-    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
-}
-function summarizeScriptOp(_script, op) {
-    const kind = strOf(op["op"]);
-    if (kind === "actor.add")
-        return `已新增人物 ${op["name"] || op["actor_name"]}${op["role_type"] ? `（${op["role_type"]}）` : ""}`;
-    if (kind === "location.add")
-        return `已新增场景地点 ${op["name"] || op["location_name"]}`;
-    if (kind === "prop.add")
-        return `已新增道具 ${op["name"] || op["prop_name"]}`;
-    if (kind === "episode.add")
-        return `已新增分集${op["episode_id"] ? ` ${op["episode_id"]}` : "（自动编号）"}${op["title"] ? `：${op["title"]}` : ""}`;
-    if (kind === "state.add")
-        return `已为 ${op["target"]} 新增状态 ${op["state_id"]}: ${op["name"] || op["state_name"]}`;
-    if (kind === "action.state.change")
-        return `已在 ${op["at"]} 为 ${op["target"]} 设置状态切换到 ${op["to"] || op["to_state_id"]}`;
-    if (kind.startsWith("state."))
-        return `已执行 ${kind}: ${op["target"]}`;
-    if (kind.startsWith("dialogue."))
-        return `已执行 ${kind}: ${op["at"]}`;
-    return `已执行 ${kind}`;
-}
-async function commandStateRefs(opts, plan = false) {
-    const session = await loadScriptForEdit(opts);
-    const script = session.script;
-    const args = asList(opts["_args"]);
-    const [targetKind, targetId, stateId] = parseStateTarget(args[0] ?? "");
-    // Verify state exists (will throw if not)
-    const _asset = (() => {
-        for (const asset of asList(script[`${targetKind}s`])) {
-            if (strOf(asset[`${targetKind}_id`]) === targetId) {
-                for (const st of asList(asset["states"])) {
-                    if (strOf(st["state_id"]) === stateId)
-                        return st;
-                }
-            }
-        }
-        throw new CliError("SCRIPT OP BLOCKED: State not found", "State not found.", {
-            exitCode: EXIT_USAGE,
-            required: ["existing state_id on the target asset"],
-            received: [`${targetKind}:${targetId}/${stateId}`],
-            nextSteps: ["Inspect states and fix the target."],
-            errorCode: "STATE_NOT_FOUND",
-        });
-    })();
-    void _asset;
-    const refs = collectStateRefs(script, targetKind, targetId, stateId);
-    const report = {
-        title: plan ? "SCRIPT STATE DELETE PLAN" : "SCRIPT STATE REFS",
-        op: plan ? "state.delete-plan" : "state.refs",
-        changed: false,
-        summary: `${targetKind}:${targetId}/${stateId} refs=${refs.length}`,
-        result: refs.length > 0 ? refs.map((r) => JSON.stringify(r)) : ["No references."],
-        refs: refs,
-        artifacts: [session.artifactLabel],
-        next: plan && refs.length > 0
-            ? ["Choose replace/remove strategy. Do not delete silently when references affect story continuity."]
-            : [plan ? "State can be deleted directly." : "Use delete-plan before deleting a state."],
-    };
-    return [report, EXIT_OK];
-}
-// ---------------------------------------------------------------------------
-// command_export (direct export)
-// ---------------------------------------------------------------------------
-export async function commandExport(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const force = Boolean(opts["force"]);
-    const scriptPath = path.join(directDir(workspace), "script.initial.json");
-    if (!exists(scriptPath)) {
-        throw new CliError("EXPORT BLOCKED: script.initial.json not found", "script.initial.json not found.", {
-            exitCode: EXIT_INPUT,
-            required: ["workspace/draft/scriptctl/direct/script.initial.json"],
-            received: [scriptPath],
-            nextSteps: ["Run scriptctl direct init first."],
-        });
-    }
-    const state = readRunState(workspace);
-    const provider = strOf(state["provider"]);
-    if (provider === "mock" && process.env.SCRIPTCTL_ALLOW_MOCK_EXPORT !== "1") {
-        const report = {
-            title: "EXPORT BLOCKED: Mock provider result",
-            result: ["script.initial.json was produced by --provider mock and was not exported."],
-            artifacts: [path.join(directDir(workspace), "run_state.json")],
-            next: ["Rerun init with --provider anthropic for deliverable conversion."],
-        };
-        return [report, EXIT_NEEDS_AGENT];
-    }
-    const validation = validateScript(workspace, scriptPath);
-    const blockingOrError = Boolean(validation["has_blocking"]) ||
-        asList(validation["issues"]).some((it) => isDict(it) && (it["severity"] === "blocking" || it["severity"] === "error"));
-    if (!validation["passed"] && (!force || blockingOrError)) {
-        const title = force
-            ? "EXPORT BLOCKED: Validation errors require repair"
-            : "EXPORT BLOCKED: Validation needs agent repair";
-        const report = {
-            title,
-            result: ["script.initial.json was not exported."],
-            artifacts: [path.join(directDir(workspace), "validation.json")],
-            issues: summarizeIssues(asList(validation["issues"])),
-            next: ["Inspect issues and apply structured patches, then validate/export."],
-        };
-        return [report, EXIT_NEEDS_AGENT];
-    }
-    let script;
-    try {
-        script = readJson(scriptPath);
-    }
-    catch (exc) {
-        throw new CliError("EXPORT BLOCKED: script.initial.json invalid", "script.initial.json invalid.", {
-            exitCode: EXIT_INPUT,
-            required: ["valid script.initial.json"],
-            received: [`${scriptPath}: ${exc.message}`],
-            nextSteps: ["Fix script.initial.json or rerun direct init."],
-            errorCode: "SCRIPT_JSON_INVALID",
-        });
-    }
-    if (!isDict(script)) {
-        throw new CliError("EXPORT BLOCKED: script root invalid", "script root invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["script root object"],
-            received: [Array.isArray(script) ? "array" : typeof script],
-            nextSteps: ["Use a valid script document object."],
-            errorCode: "SCRIPT_ROOT_INVALID",
-        });
-    }
-    const client = scriptOutputClient(opts);
-    const baseRevision = await currentRevisionOrZero(client);
-    // Sorted-keys serialization mirrors Python json.dumps(sort_keys=True, separators=(",",":"))
-    const sortedScript = sortDeep(script);
-    const scriptHash = sha256Text(JSON.stringify(sortedScript));
-    const requestId = strOf(opts["request_id"]).trim() || `scriptctl-direct-export:${scriptHash}`;
-    let replaceRes;
-    try {
-        replaceRes = await client.replaceScript({
-            requestId,
-            baseRevision,
-            script,
-            source: "ctl",
-        });
-    }
-    catch (exc) {
-        if (exc instanceof ScriptOutputApiError) {
-            throw apiErrorToCli("SCRIPT API BLOCKED: Export write failed", exc);
-        }
-        throw exc;
-    }
-    const revision = Number(replaceRes["revision"] ?? 0);
-    const remoteSession = new ScriptEditSession({
-        workspace,
-        script,
-        client,
-        projectGroupNo: client.projectGroupNo,
-        revision,
-    });
-    await syncValidationResult(remoteSession, validation, revision);
-    const outputLabel = remoteSession.artifactLabel;
-    updateRunState(workspace, { status: "exported", output_path: outputLabel });
-    const report = {
-        title: "EXPORT COMPLETE: Final script stored in DB",
-        result: [
-            `validation: ${validation["passed"] ? "passed" : "forced"}`,
-            `base_revision: ${baseRevision}`,
-            `revision: ${revision}`,
-            `idempotent: ${String(Boolean(replaceRes["idempotent"])).toLowerCase()}`,
-        ],
-        artifacts: [outputLabel, path.join(directDir(workspace), "validation.json")],
-        next: ["Proceed to downstream asset or footage stages."],
-    };
-    return [report, EXIT_OK];
-}
-// sortDeep is the canonical helper in domain/direct-core; re-exported here for
-// back-compat with existing importers of `usecases/script`.
-export { sortDeep };
-// ===========================================================================
-// 0.6.0 plural-noun query commands (replace `commandScriptInspect --target X`)
-// ===========================================================================
-//
-// Each command is a thin read-only wrapper around the underlying script
-// document. They all return a Report shaped like inspect's existing output but
-// 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 --------------------------------------------------------------
-function synopsisPreview(text, limit) {
-    const oneLine = text.replace(/\s+/g, " ").trim();
-    return oneLine.length > limit ? `${oneLine.slice(0, limit)}…` : oneLine;
-}
-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}`,
-    ];
-    const logline = strOf(script["logline"]).trim();
-    if (logline)
-        lines.push(`logline: ${logline}`);
-    const theme = strOf(script["theme"]).trim();
-    if (theme)
-        lines.push(`theme: ${theme}`);
-    const synopsis = strOf(script["synopsis"]).trim();
-    if (synopsis)
-        lines.push(`synopsis: ${synopsisPreview(synopsis, 120)}`);
-    const mainCharacters = asList(script["main_characters"])
-        .map((c) => strOf(c["name"]).trim())
-        .filter((n) => n);
-    if (mainCharacters.length > 0)
-        lines.push(`main characters: ${mainCharacters.slice(0, 6).join(", ")}`);
-    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;
-        const epSynopsis = strOf(ep["synopsis"]).trim();
-        const synopsisField = epSynopsis ? `, synopsis=${synopsisPreview(epSynopsis, 60)}` : "";
-        lines.push(`${ep["episode_id"]}: scenes=${scenes.length}, actions=${actionCount}, chars=${chars.total} (dialogue=${chars.dialogue}, action=${chars.action}), title=${ep["title"] || "-"}${synopsisField}`);
-    }
-    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"],
-    });
-}
-// ----- create (blank scaffold) ----------------------------------------------
-// Create an empty schema-v2 script as the starting point for building a script
-// bottom-up with the atomic add/insert verbs (instead of direct/parse/write
-// assembly). Targets the same three destinations as the edit verbs:
-//   --script-path <file>  local JSON file
-//   --draft               the direct intermediate (script.initial.json)
-//   --project-group-no    DB-backed script-output (first write at revision 0)
-// Refuses to clobber an existing target (local: pass --force to overwrite; DB:
-// edit the existing script instead). Validates in incomplete-tolerant mode, so
-// the blank scaffold reports passed.
-export async function commandCreate(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const force = Boolean(opts["force"]);
-    const title = strOf(opts["title"]).trim();
-    const script = blankScript(title);
-    const draft = Boolean(opts["draft"]);
-    const scriptPathOpt = strOf(opts["script_path"]).trim();
-    if (draft && scriptPathOpt) {
-        throw new CliError("CREATE BLOCKED: --draft conflicts with --script-path", "--draft conflicts with --script-path.", {
-            exitCode: EXIT_USAGE,
-            required: ["either --draft or --script-path, not both"],
-            received: ["--draft and --script-path"],
-            nextSteps: ["Drop one of the two flags and retry."],
-            errorCode: "DRAFT_FLAG_CONFLICT",
-        });
-    }
-    if (draft && strOf(opts["project_group_no"]).trim()) {
-        throw new CliError("CREATE BLOCKED: --draft conflicts with --project-group-no", "--draft conflicts with --project-group-no.", {
-            exitCode: EXIT_USAGE,
-            required: ["either --draft (local draft) or --project-group-no (DB), not both"],
-            received: ["--draft and --project-group-no"],
-            nextSteps: ["Drop one of the two flags and retry."],
-            errorCode: "DRAFT_FLAG_CONFLICT",
-        });
-    }
-    const localPath = draft ? path.join(directDir(workspace), "script.initial.json") : (scriptPathOpt || null);
-    if (localPath) {
-        if (exists(localPath) && !force) {
-            throw new CliError("CREATE BLOCKED: target already exists", "A script already exists at the target.", {
-                exitCode: EXIT_INPUT,
-                required: ["a non-existent target, or --force to overwrite"],
-                received: [localPath],
-                nextSteps: ["Edit the existing script with the atomic verbs, or pass --force to overwrite with a blank scaffold."],
-                errorCode: "SCRIPT_EXISTS",
-            });
-        }
-        writeJson(localPath, script);
-        const session = new ScriptEditSession({ workspace, scriptPath: localPath, script });
-        const validation = validateSession(session);
-        const passed = Boolean(validation["passed"]);
-        return [blankCreateReport(session, validation, null), passed ? EXIT_OK : EXIT_NEEDS_AGENT];
-    }
-    // DB mode: first write must be at revision 0. We never silently overwrite a
-    // populated DB script with a blank one — that would destroy work.
-    const client = scriptOutputClient(opts);
-    const baseRevision = await currentRevisionOrZero(client);
-    if (baseRevision > 0) {
-        throw new CliError("CREATE BLOCKED: DB script already exists", "A script already exists for this project.", {
-            exitCode: EXIT_INPUT,
-            required: ["an empty project (no published script)"],
-            received: [`revision=${baseRevision}`],
-            nextSteps: ["Edit the existing script with the atomic verbs instead of creating a blank one."],
-            errorCode: "SCRIPT_EXISTS",
-        });
-    }
-    const requestId = requestIdForScriptWrite(opts, "script.create", { script });
-    let res;
-    try {
-        res = await client.replaceScript({ requestId, baseRevision, script, source: "ctl" });
-    }
-    catch (exc) {
-        if (exc instanceof ScriptOutputApiError) {
-            throw apiErrorToCli("SCRIPT API BLOCKED: Create write failed", exc);
-        }
-        throw exc;
-    }
-    const revision = Number(res["revision"] ?? 0);
-    const session = new ScriptEditSession({ workspace, script, client, projectGroupNo: client.projectGroupNo, revision });
-    const validation = validateSession(session);
-    await syncValidationResult(session, validation, revision);
-    const passed = Boolean(validation["passed"]);
-    return [blankCreateReport(session, validation, Boolean(res["idempotent"])), passed ? EXIT_OK : EXIT_NEEDS_AGENT];
-}
-function blankCreateReport(session, validation, idempotent) {
-    const passed = Boolean(validation["passed"]);
-    const resultLines = ["created: blank script (schema v2)", `validation: ${passed ? "passed" : "needs repair"}`];
-    if (session.remote) {
-        resultLines.push(`revision: ${session.revision}`);
-        if (idempotent !== null)
-            resultLines.push(`idempotent: ${String(idempotent).toLowerCase()}`);
-    }
-    return {
-        title: passed ? "SCRIPT CREATED: Blank scaffold" : "SCRIPT CREATED: Validation needs repair",
-        op: "script.create",
-        changed: true,
-        summary: "已创建空白剧本（schema v2，待填充人物/地点/道具/分集）",
-        result: resultLines,
-        warnings: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel],
-        next: [
-            "用 worldview 设定世界观，用 add-actor / add-location / add-prop 注册资产，用 add-episode + insert 搭出分集与场景。",
-        ],
-    };
-}
-// ----- 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.
-function requireNameArg(opts, verb, example) {
-    const args = asList(opts["_args"]);
-    if (args.length < 1) {
-        throw new CliError(`VERB BLOCKED: ${verb} name missing`, "Name missing.", {
-            exitCode: EXIT_USAGE,
-            required: ["<name>"],
-            received: ["<empty>"],
-            nextSteps: [example],
-            errorCode: "ARGS_MISSING",
-        });
-    }
-    return args[0];
-}
-export async function commandAddActor(opts) {
-    const name = requireNameArg(opts, "add-actor", "Example: scriptctl add-actor \"林夏\" --role 主角");
-    return applySingleScriptOp(opts, {
-        op: "actor.add",
-        name,
-        actor_id: opts["id"],
-        role_type: opts["role"],
-        description: opts["description"],
-        aliases: opts["alias"],
-    });
-}
-export async function commandAddLocation(opts) {
-    const name = requireNameArg(opts, "add-location", "Example: scriptctl add-location \"教室\"");
-    return applySingleScriptOp(opts, {
-        op: "location.add",
-        name,
-        location_id: opts["id"],
-        description: opts["description"],
-    });
-}
-export async function commandAddProp(opts) {
-    const name = requireNameArg(opts, "add-prop", "Example: scriptctl add-prop \"怀表\"");
-    return applySingleScriptOp(opts, {
-        op: "prop.add",
-        name,
-        prop_id: opts["id"],
-        description: opts["description"],
-    });
-}
-export async function commandAddEpisode(opts) {
-    return applySingleScriptOp(opts, {
-        op: "episode.add",
-        episode_id: opts["id"],
-        title: opts["title"],
-    });
-}
-//# sourceMappingURL=script.js.map