@lingjingai/scriptctl 0.35.0 → 0.36.0

package/dist/domain/script/validate.js

@@ -1,997 +0,0 @@
-import * as path from "node:path";
-import { ACTION_TYPE_VALUES, CliError, DELIVERY_VALUES, EFFECTIVE_FROM_VALUES, EXIT_INPUT, ROLE_TYPE_VALUES, SCRIPT_SCHEMA_VERSION, SCRIPT_TARGET_KINDS, SPEAKER_SOURCE_KINDS, directDir, exists, readJson, readText, writeJson, } from "../../common.js";
-import { canonicalAssetNameKey, cleanName, contentHasSpeakerPrefix, inferNonActorSpeakerKind, isTechnicalEpisodeTitle, sceneContext, stateRejectionReason, } from "../direct-core.js";
-import { asList, isDict, isList, strOf } from "./shared.js";
-export function entityFieldMissingIssue(kindLabel, field, idValue) {
-    const isDescription = field === "description";
-    return {
-        code: "SCHEMA_ENTITY_FIELD_MISSING",
-        severity: isDescription ? "warning" : "error",
-        ...(isDescription ? { incomplete_ok: true } : {}),
-        summary: `${kindLabel} missing ${field}: ${idValue}`,
-        repair_hint: isDescription
-            ? "Describe with `describe` when ready (an undescribed asset is publishable)."
-            : `Patch ${kindLabel.toLowerCase()} metadata.`,
-    };
-}
-// ---------------------------------------------------------------------------
-// validate_script
-// ---------------------------------------------------------------------------
-/**
- * Validate a script's schema and asset wiring.
- *
- * Pass either:
- *   - `scriptPath: string` (or null → default to direct's script.initial.json), or
- *   - `opts.scriptData: Dict` to validate an in-memory object without writing to disk.
- *
- * Callers that already have the script as a parsed object (episode draft / publish
- * after assembly) should prefer `scriptData` to avoid the write-validate-rm dance.
- *
- * Completeness issues (no episodes, empty episode/scene, scene without location,
- * missing asset description) are emitted as warnings (`incomplete_ok`), not
- * errors — an unfinished but structurally-sound script passes. Only integrity
- * violations (dangling refs, dup ids, invalid enums, missing ids/names) fail it.
- */
-export function validateScript(workspace, scriptPath = null, opts = {}) {
-    const requireSource = opts.requireSource ?? true;
-    const dd = directDir(workspace);
-    const sourcePath = path.join(workspace, "source.txt");
-    if (requireSource && !exists(sourcePath)) {
-        throw new CliError("VALIDATE BLOCKED: source.txt not found", "source.txt not found.", {
-            exitCode: EXIT_INPUT,
-            required: ["workspace/source.txt"],
-            received: [sourcePath],
-            nextSteps: ["Run scriptctl direct init first."],
-        });
-    }
-    if (exists(sourcePath))
-        readText(sourcePath); // touch, mirror Python
-    let script;
-    if (opts.scriptData !== undefined) {
-        script = opts.scriptData;
-    }
-    else {
-        const finalScriptPath = scriptPath ?? path.join(dd, "script.initial.json");
-        if (!exists(finalScriptPath)) {
-            throw new CliError("VALIDATE BLOCKED: script not found", "Script JSON not found.", {
-                exitCode: EXIT_INPUT,
-                required: ["script.initial.json or --script-path"],
-                received: [finalScriptPath],
-                nextSteps: ["Run scriptctl direct init first."],
-            });
-        }
-        try {
-            script = readJson(finalScriptPath);
-        }
-        catch (exc) {
-            throw new CliError("VALIDATE BLOCKED: script JSON invalid", "Script JSON invalid.", {
-                exitCode: EXIT_INPUT,
-                required: ["valid script JSON"],
-                received: [`${finalScriptPath}: ${exc.message}`],
-                nextSteps: ["Fix script.initial.json or rerun init."],
-            });
-        }
-    }
-    const issues = [];
-    for (const field of ["version", "title", "worldview", "style", "actors", "locations", "props", "speakers", "episodes"]) {
-        if (!(field in script)) {
-            issues.push({
-                code: "SCHEMA_TOP_FIELD_MISSING",
-                severity: "error",
-                summary: `Top-level field missing: ${field}`,
-                repair_hint: "Patch script.json or rerun init.",
-            });
-        }
-    }
-    if (script["version"] !== SCRIPT_SCHEMA_VERSION && script["version"] !== String(SCRIPT_SCHEMA_VERSION)) {
-        issues.push({
-            code: "SCHEMA_VERSION_UNSUPPORTED",
-            severity: "warning",
-            summary: `script version should be ${SCRIPT_SCHEMA_VERSION}.`,
-            repair_hint: "Update the internal numeric version when migrating script.json.",
-        });
-    }
-    const actorIds = new Set();
-    for (const item of asList(script["actors"])) {
-        const id = strOf(item["actor_id"]);
-        if (id)
-            actorIds.add(id);
-    }
-    const locationIds = new Set();
-    for (const item of asList(script["locations"])) {
-        const id = strOf(item["location_id"]);
-        if (id)
-            locationIds.add(id);
-    }
-    const propIds = new Set();
-    for (const item of asList(script["props"])) {
-        const id = strOf(item["prop_id"]);
-        if (id)
-            propIds.add(id);
-    }
-    const speakerDisplayNames = new Set();
-    for (const item of asList(script["speakers"])) {
-        if (!isDict(item))
-            continue;
-        const name = strOf(item["display_name"]).trim();
-        if (name)
-            speakerDisplayNames.add(cleanName(name));
-    }
-    const canonicalAssetNames = new Map();
-    const checkCanonicalAssetName = (kind, kindLabel, id, name) => {
-        if (!id || !name)
-            return;
-        const key = canonicalAssetNameKey(kind, name);
-        const existing = canonicalAssetNames.get(key);
-        if (!existing) {
-            canonicalAssetNames.set(key, { kindLabel, id, name });
-            return;
-        }
-        if (existing.id === id)
-            return;
-        issues.push({
-            code: "DUPLICATE_ASSET_NAME",
-            severity: "error",
-            summary: `${kindLabel} canonical name duplicates ${existing.kindLabel}: ${name} (${id}) conflicts with ${existing.name} (${existing.id})`,
-            repair_hint: "Merge duplicate same-kind assets or rename one to a distinct canonical name.",
-        });
-    };
-    const actors = asList(script["actors"]);
-    for (let idx = 0; idx < actors.length; idx++) {
-        const actor = actors[idx];
-        if (!isDict(actor)) {
-            issues.push({
-                code: "SCHEMA_ENTITY_FIELD_MISSING",
-                severity: "error",
-                summary: `actors[${idx}] is not an object.`,
-                repair_hint: "Patch actor entry.",
-            });
-            continue;
-        }
-        const actorName = strOf(actor["actor_name"]).trim();
-        for (const field of ["actor_id", "actor_name", "description"]) {
-            if (!strOf(actor[field]).trim()) {
-                issues.push(entityFieldMissingIssue("Actor", field, strOf(actor["actor_id"]) || String(idx)));
-            }
-        }
-        if (actorName && cleanName(actorName) !== actorName) {
-            issues.push({
-                code: "ASSET_NAME_HAS_STATE_ANNOTATION",
-                severity: "error",
-                summary: `Actor name contains state annotation: ${actorName}`,
-                repair_hint: "Keep actor_name canonical and move state text to states[] or action content only if reusable.",
-            });
-        }
-        if (actorName && inferNonActorSpeakerKind(actorName) !== "actor") {
-            issues.push({
-                code: "NONHUMAN_AS_ACTOR",
-                severity: "error",
-                summary: `Non-human speaker is registered as actor: ${actorName}`,
-                repair_hint: "Use speakers[] with source_kind system/broadcast/prop/group/other; do not create an actor.",
-            });
-        }
-        checkCanonicalAssetName("actor", "Actor", strOf(actor["actor_id"]), actorName);
-        if (actor["role_type"] && !ROLE_TYPE_VALUES.includes(strOf(actor["role_type"]))) {
-            issues.push({
-                code: "ENUM_ROLE_TYPE",
-                severity: "error",
-                summary: `Actor role_type invalid: ${actor["role_type"]}`,
-                repair_hint: "Patch role_type to 主角 or 配角.",
-            });
-        }
-    }
-    const locations = asList(script["locations"]);
-    for (let idx = 0; idx < locations.length; idx++) {
-        const loc = locations[idx];
-        if (!isDict(loc)) {
-            issues.push({
-                code: "SCHEMA_ENTITY_FIELD_MISSING",
-                severity: "error",
-                summary: `locations[${idx}] is not an object.`,
-                repair_hint: "Patch location entry.",
-            });
-            continue;
-        }
-        const locationName = strOf(loc["location_name"]).trim();
-        for (const field of ["location_id", "location_name", "description"]) {
-            if (!strOf(loc[field]).trim()) {
-                issues.push(entityFieldMissingIssue("Location", field, strOf(loc["location_id"]) || String(idx)));
-            }
-        }
-        if (locationName && cleanName(locationName) !== locationName) {
-            issues.push({
-                code: "ASSET_NAME_HAS_STATE_ANNOTATION",
-                severity: "error",
-                summary: `Location name contains state annotation: ${locationName}`,
-                repair_hint: "Keep location_name canonical and move durable visual variants to states[] only when reusable.",
-            });
-        }
-        checkCanonicalAssetName("location", "Location", strOf(loc["location_id"]), locationName);
-    }
-    const propsArr = asList(script["props"]);
-    for (let idx = 0; idx < propsArr.length; idx++) {
-        const prop = propsArr[idx];
-        if (!isDict(prop)) {
-            issues.push({
-                code: "SCHEMA_ENTITY_FIELD_MISSING",
-                severity: "error",
-                summary: `props[${idx}] is not an object.`,
-                repair_hint: "Patch prop entry.",
-            });
-            continue;
-        }
-        const propName = strOf(prop["prop_name"]).trim();
-        for (const field of ["prop_id", "prop_name", "description"]) {
-            if (!strOf(prop[field]).trim()) {
-                issues.push(entityFieldMissingIssue("Prop", field, strOf(prop["prop_id"]) || String(idx)));
-            }
-        }
-        if (propName && cleanName(propName) !== propName) {
-            issues.push({
-                code: "ASSET_NAME_HAS_STATE_ANNOTATION",
-                severity: "error",
-                summary: `Prop name contains state annotation: ${propName}`,
-                repair_hint: "Keep prop_name canonical and move durable visual variants to states[] only when reusable.",
-            });
-        }
-        checkCanonicalAssetName("prop", "Prop", strOf(prop["prop_id"]), propName);
-    }
-    const stateIdsByAsset = new Map();
-    const assetLabelsById = new Map();
-    const assetIdsByLabel = new Map();
-    const stateIdsByAssetLabel = new Map();
-    const stateNameKeysByAssetLabel = new Set();
-    for (const [collection, idKey] of [["actors", "actor_id"], ["locations", "location_id"], ["props", "prop_id"]]) {
-        const targetKind = { actors: "actor", locations: "location", props: "prop" }[collection];
-        const nameKey = { actors: "actor_name", locations: "location_name", props: "prop_name" }[collection];
-        for (const asset of asList(script[collection])) {
-            const assetId = strOf(asset[idKey]);
-            const assetName = strOf(asset[nameKey]).trim();
-            const assetNameKey = cleanName(assetName);
-            const assetLabelKey = `${targetKind}::${assetNameKey}`;
-            if (assetId) {
-                assetLabelsById.set(assetId, { kind: targetKind, name: assetName });
-                if (assetNameKey)
-                    assetIdsByLabel.set(assetLabelKey, assetId);
-            }
-            const rawStates = asset["states"];
-            stateIdsByAsset.set(assetId, new Set());
-            if (assetNameKey)
-                stateIdsByAssetLabel.set(assetLabelKey, stateIdsByAsset.get(assetId));
-            const seenStateNames = new Set();
-            // Mirror Python `asset.get("states", []) or []`: absent/null → empty list (no issue)
-            if (rawStates !== undefined && rawStates !== null && !isList(rawStates)) {
-                issues.push({
-                    code: "SCHEMA_STATE_LIST_INVALID",
-                    severity: "error",
-                    summary: `${collection} ${assetId} states must be an array.`,
-                    repair_hint: "Patch states to an array.",
-                });
-                continue;
-            }
-            const states = isList(rawStates) ? rawStates : [];
-            let defaultStateCount = 0;
-            for (const state of states) {
-                if (!isDict(state)) {
-                    issues.push({
-                        code: "SCHEMA_STATE_INVALID",
-                        severity: "error",
-                        summary: `${collection} ${assetId} contains a non-object state.`,
-                        repair_hint: "Patch or remove the invalid state.",
-                    });
-                    continue;
-                }
-                const sid = strOf(state["state_id"]);
-                const sname = strOf(state["state_name"] || state["name"]);
-                if (!sid || !sname) {
-                    issues.push({
-                        code: "SCHEMA_STATE_FIELD_MISSING",
-                        severity: "error",
-                        summary: `${collection} ${assetId} state missing state_id or state_name.`,
-                        repair_hint: "Patch state_id/state_name.",
-                    });
-                }
-                if (sid && stateIdsByAsset.get(assetId).has(sid)) {
-                    issues.push({
-                        code: "DUPLICATE_STATE_ID",
-                        severity: "error",
-                        summary: `Duplicate state_id ${targetKind}:${assetId}/${sid}`,
-                        repair_hint: `Two states share id ${sid}. There is no verb to re-id a state, and delete ${targetKind}:${assetId}/${sid} would remove BOTH. Fix the raw script.json: give one state a fresh state_id (or drop the unwanted one), then re-validate.`,
-                    });
-                }
-                if (sid === "default")
-                    defaultStateCount += 1;
-                if (sname && seenStateNames.has(sname)) {
-                    issues.push({
-                        code: "DUPLICATE_STATE_NAME",
-                        severity: "warning",
-                        summary: `Duplicate state_name "${sname}" on ${targetKind}:${assetId}/${sid}`,
-                        repair_hint: `Inspect with: scriptctl states ${targetKind}:${assetId} — then rename if distinct: scriptctl rename ${targetKind}:${assetId}/${sid} "<新名>"`,
-                    });
-                }
-                const reason = stateRejectionReason(targetKind, sname);
-                if (sname && reason) {
-                    issues.push({
-                        code: "STATE_LABEL_INVALID",
-                        severity: "error",
-                        summary: `${collection} ${assetId} state label invalid: ${sname}`,
-                        repair_hint: "Use one clear state label; do not combine multiple states into one label.",
-                    });
-                }
-                if (sid)
-                    stateIdsByAsset.get(assetId).add(sid);
-                if (sname) {
-                    seenStateNames.add(sname);
-                    if (assetNameKey)
-                        stateNameKeysByAssetLabel.add(`${assetLabelKey}::${sname}`);
-                }
-            }
-            if (states.length > 0 && defaultStateCount === 0) {
-                issues.push({
-                    code: "DEFAULT_STATE_MISSING",
-                    severity: "error",
-                    summary: `${collection} ${assetId} has states but no asset-scoped default state.`,
-                    repair_hint: "Run direct state-curation or set the most common state_id to `default` while preserving its state_name.",
-                });
-            }
-        }
-    }
-    const speakerIds = new Set();
-    const speakersArr = asList(script["speakers"]);
-    for (let idx = 0; idx < speakersArr.length; idx++) {
-        const speaker = speakersArr[idx];
-        if (!isDict(speaker)) {
-            issues.push({
-                code: "SCHEMA_SPEAKER_INVALID",
-                severity: "error",
-                summary: `speakers[${idx}] is not an object.`,
-                repair_hint: "Patch speaker entry.",
-            });
-            continue;
-        }
-        const speakerId = strOf(speaker["speaker_id"]);
-        const sourceKind = strOf(speaker["source_kind"]);
-        const sourceId = speaker["source_id"];
-        if (!speakerId || !strOf(speaker["display_name"]).trim()) {
-            issues.push({
-                code: "SCHEMA_SPEAKER_FIELD_MISSING",
-                severity: "error",
-                summary: `Speaker missing speaker_id or display_name: ${idx}`,
-                repair_hint: "Patch speaker metadata.",
-            });
-        }
-        if (speakerIds.has(speakerId)) {
-            issues.push({
-                code: "DUPLICATE_SPEAKER_ID",
-                severity: "error",
-                summary: `Duplicate speaker_id: ${speakerId}`,
-                repair_hint: "Rename or merge duplicate speakers.",
-            });
-        }
-        if (speakerId)
-            speakerIds.add(speakerId);
-        if (!SPEAKER_SOURCE_KINDS.has(sourceKind)) {
-            issues.push({
-                code: "ENUM_SPEAKER_SOURCE_KIND",
-                severity: "error",
-                summary: `speaker.source_kind invalid: ${sourceKind || "<empty>"}`,
-                repair_hint: "Use actor/location/prop/system/broadcast/group/other.",
-            });
-        }
-        if (sourceKind === "actor" && !actorIds.has(strOf(sourceId))) {
-            issues.push({
-                code: "DANGLING_SPEAKER_SOURCE_REF",
-                severity: "error",
-                summary: `Speaker actor source not found: ${sourceId}`,
-                repair_hint: "Patch source_id or source_kind.",
-            });
-        }
-        if (sourceKind === "location" && !locationIds.has(strOf(sourceId))) {
-            issues.push({
-                code: "DANGLING_SPEAKER_SOURCE_REF",
-                severity: "error",
-                summary: `Speaker location source not found: ${sourceId}`,
-                repair_hint: "Patch source_id or source_kind.",
-            });
-        }
-        if (sourceKind === "prop" && !propIds.has(strOf(sourceId))) {
-            issues.push({
-                code: "DANGLING_SPEAKER_SOURCE_REF",
-                severity: "error",
-                summary: `Speaker prop source not found: ${sourceId}`,
-                repair_hint: "Patch source_id or source_kind.",
-            });
-        }
-    }
-    const planPath = path.join(dd, "episode_plan.json");
-    if (exists(planPath)) {
-        const plan = readJson(planPath);
-        if (plan["boundary_confidence"] === "low") {
-            issues.push({
-                code: "LOW_CONFIDENCE_EPISODE_PLAN",
-                severity: "warning",
-                summary: "Episode plan used a single-episode fallback.",
-                repair_hint: "Inspect the initial script and adjust structure with patch if needed.",
-            });
-        }
-    }
-    const episodes = asList(script["episodes"]);
-    if (episodes.length === 0) {
-        issues.push({ code: "NO_EPISODES", severity: "warning", incomplete_ok: true, summary: "No episodes in script.", repair_hint: "Add episodes with add-episode (an empty script is publishable but renders to nothing)." });
-    }
-    const episodeIds = new Set();
-    let totalScenes = 0;
-    let totalActions = 0;
-    let lastSceneNum = 0;
-    const usedPropStateIds = new Set();
-    const issueNullableStateRef = (kind, assetId, episode, scene) => {
-        if ((stateIdsByAsset.get(assetId) ?? new Set()).size === 0)
-            return;
-        const label = assetLabelsById.get(assetId);
-        issues.push({
-            code: "STATE_REF_MISSING",
-            severity: "warning",
-            incomplete_ok: true,
-            episode,
-            scene,
-            asset_kind: kind,
-            asset_id: assetId,
-            summary: `${kind} ${label?.name || assetId} has states but scene ref has no state_id.`,
-            repair_hint: "在 ep_*.md 的场景引用里写明状态，或确认资产只有默认/唯一状态让 parse 自动绑定。",
-        });
-    };
-    for (const ep of episodes) {
-        const epId = strOf(ep["episode_id"]).trim();
-        if (!epId) {
-            issues.push({
-                code: "EPISODE_ID_MISSING",
-                severity: "error",
-                summary: "Episode missing episode_id.",
-                repair_hint: "Patch episode_id to ep_### or rerun init.",
-            });
-        }
-        else if (episodeIds.has(epId)) {
-            issues.push({
-                code: "DUPLICATE_EPISODE_ID",
-                severity: "error",
-                episode: epId,
-                summary: `Duplicate episode_id: ${epId}`,
-                repair_hint: "Rerun init or patch episode ids to a unique ep_### sequence.",
-            });
-        }
-        if (epId)
-            episodeIds.add(epId);
-        const epTitle = strOf(ep["title"]).trim();
-        if (!epTitle || isTechnicalEpisodeTitle(epTitle)) {
-            issues.push({
-                code: "EPISODE_TITLE_INVALID",
-                severity: "warning",
-                episode: ep["episode_id"],
-                summary: `Episode title is missing or technical: ${epTitle || "<empty>"}`,
-                repair_hint: 'Rerun `direct init` to regenerate, or `script patch episode <episode_id> --field title --value "第N集：短标题"`.',
-            });
-        }
-        const scenes = asList(ep["scenes"]);
-        if (scenes.length === 0) {
-            issues.push({
-                code: "EPISODE_WITHOUT_SCENES",
-                severity: "warning",
-                incomplete_ok: true,
-                episode: ep["episode_id"],
-                summary: "Episode has no scenes.",
-                repair_hint: "Add scenes with insert (an empty episode is publishable but renders to nothing).",
-            });
-        }
-        for (const scene of scenes) {
-            totalScenes += 1;
-            const rawSceneId = strOf(scene["scene_id"]);
-            const match = /^scn_(\d+)$/.exec(rawSceneId);
-            if (match) {
-                const sceneNum = parseInt(match[1], 10);
-                if (sceneNum <= lastSceneNum) {
-                    issues.push({
-                        code: "REF_SCENE_ID_NONMONO",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: rawSceneId,
-                        summary: `scene_id must increase globally: ${rawSceneId}`,
-                        repair_hint: "Rerun init or patch scene ids to a global monotonic sequence.",
-                    });
-                }
-                lastSceneNum = Math.max(lastSceneNum, sceneNum);
-            }
-            else {
-                issues.push({
-                    code: "REF_SCENE_ID_INVALID",
-                    severity: "error",
-                    episode: ep["episode_id"],
-                    scene: rawSceneId || null,
-                    summary: "scene_id must use scn_### format.",
-                    repair_hint: "Patch scene_id to scn_###.",
-                });
-            }
-            const ctx = sceneContext(scene);
-            for (const unresolved of asList(ctx["unresolved_state_refs"])) {
-                const kind = strOf(unresolved["kind"]);
-                const assetName = strOf(unresolved["asset_name"]).trim();
-                const stateName = strOf(unresolved["state_name"]).trim();
-                if (!SCRIPT_TARGET_KINDS.has(kind) || !assetName || !stateName)
-                    continue;
-                const assetLabelKey = `${kind}::${cleanName(assetName)}`;
-                if (stateNameKeysByAssetLabel.has(`${assetLabelKey}::${stateName}`))
-                    continue;
-                const assetId = assetIdsByLabel.get(assetLabelKey);
-                const currentStateIds = stateIdsByAssetLabel.get(assetLabelKey) ?? new Set();
-                const refKeys = {
-                    actor: { list: "actors", id: "actor_id" },
-                    location: { list: "locations", id: "location_id" },
-                    prop: { list: "props", id: "prop_id" },
-                }[kind];
-                const currentRefResolved = asList(ctx[refKeys.list])
-                    .some((ref) => strOf(ref[refKeys.id]) === assetId && currentStateIds.has(strOf(ref["state_id"])));
-                if (currentRefResolved)
-                    continue;
-                issues.push({
-                    code: "UNRESOLVED_EXPLICIT_STATE_REF",
-                    severity: "warning",
-                    incomplete_ok: true,
-                    episode: ep["episode_id"],
-                    scene: scene["scene_id"],
-                    asset_kind: kind,
-                    summary: `${kind} ${assetName} explicit state not found: ${stateName}`,
-                    repair_hint: "修改 ep_*.md 中的状态名，或在对应 人物/场景/道具.md 中登记这个状态。",
-                });
-            }
-            const ctxLocations = asList(ctx["locations"]);
-            if (ctxLocations.length === 0) {
-                issues.push({
-                    code: "SCENE_WITHOUT_LOCATION",
-                    severity: "warning",
-                    incomplete_ok: true,
-                    episode: ep["episode_id"],
-                    scene: scene["scene_id"],
-                    summary: "Scene has no location.",
-                    repair_hint: "Set a location with context (an unlocated scene is publishable but cannot render).",
-                });
-            }
-            for (const ref of ctxLocations) {
-                const locationId = strOf(ref["location_id"]);
-                const stateId = strOf(ref["state_id"]);
-                if (!locationIds.has(locationId)) {
-                    issues.push({
-                        code: "DANGLING_LOCATION_REF",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        summary: `Location ref not found: ${locationId || "<empty>"}`,
-                        repair_hint: "Patch scene location to an existing location_id.",
-                    });
-                }
-                if (stateId && !(stateIdsByAsset.get(locationId) ?? new Set()).has(stateId)) {
-                    issues.push({
-                        code: "DANGLING_LOCATION_STATE_REF",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        summary: `Location state ref not found: ${stateId}`,
-                        repair_hint: "Patch location state_id or asset states.",
-                    });
-                }
-                if (locationIds.has(locationId) && !stateId)
-                    issueNullableStateRef("location", locationId, ep["episode_id"], scene["scene_id"]);
-            }
-            for (const ref of asList(ctx["actors"])) {
-                const actorId = strOf(ref["actor_id"]);
-                const stateId = strOf(ref["state_id"]);
-                if (!actorIds.has(actorId)) {
-                    issues.push({
-                        code: "DANGLING_ACTOR_REF",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        summary: `Actor ref not found: ${actorId || "<empty>"}`,
-                        repair_hint: "Patch scene actor refs to existing actor_id.",
-                    });
-                }
-                if (stateId && !(stateIdsByAsset.get(actorId) ?? new Set()).has(stateId)) {
-                    issues.push({
-                        code: "DANGLING_ACTOR_STATE_REF",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        summary: `Actor state ref not found: ${stateId}`,
-                        repair_hint: "Patch actor state_id or asset states.",
-                    });
-                }
-                if (actorIds.has(actorId) && !stateId)
-                    issueNullableStateRef("actor", actorId, ep["episode_id"], scene["scene_id"]);
-            }
-            for (const ref of asList(ctx["props"])) {
-                const propId = strOf(ref["prop_id"]);
-                const stateId = strOf(ref["state_id"]);
-                if (!propIds.has(propId)) {
-                    issues.push({
-                        code: "DANGLING_PROP_REF",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        summary: `Prop ref not found: ${propId || "<empty>"}`,
-                        repair_hint: "Patch scene prop refs to existing prop_id.",
-                    });
-                }
-                if (stateId && !(stateIdsByAsset.get(propId) ?? new Set()).has(stateId)) {
-                    issues.push({
-                        code: "DANGLING_PROP_STATE_REF",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        summary: `Prop state ref not found: ${stateId}`,
-                        repair_hint: "Patch prop state_id or asset states.",
-                    });
-                }
-                if (stateId)
-                    usedPropStateIds.add(stateId);
-                if (propIds.has(propId) && !stateId)
-                    issueNullableStateRef("prop", propId, ep["episode_id"], scene["scene_id"]);
-            }
-            const actionsArr = asList(scene["actions"]);
-            if (actionsArr.length === 0) {
-                issues.push({
-                    code: "SCENE_WITHOUT_ACTIONS",
-                    severity: "warning",
-                    incomplete_ok: true,
-                    episode: ep["episode_id"],
-                    scene: scene["scene_id"],
-                    summary: "Scene has no actions.",
-                    repair_hint: "Add actions with insert (an empty scene is publishable but renders to nothing).",
-                });
-            }
-            for (let actionIndex = 0; actionIndex < actionsArr.length; actionIndex++) {
-                const action = actionsArr[actionIndex];
-                totalActions += 1;
-                const kind = strOf(action["type"]).trim();
-                if (!ACTION_TYPE_VALUES.has(kind)) {
-                    issues.push({
-                        code: "ENUM_ACTION_TYPE",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        action_index: actionIndex,
-                        summary: `action.type invalid: ${kind || "<empty>"}`,
-                        repair_hint: "Patch action.type to dialogue, inner_thought, or action.",
-                    });
-                }
-                const content = strOf(action["content"]).trim();
-                const hasOverlapLines = action["delivery"] === "overlap" && isList(action["lines"]) && action["lines"].length > 0;
-                if (!content && !hasOverlapLines) {
-                    issues.push({
-                        code: "EMPTY_ACTION_CONTENT",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        action_index: actionIndex,
-                        summary: "Action content is empty.",
-                        repair_hint: "Patch content from a source span.",
-                    });
-                }
-                if (content && contentHasSpeakerPrefix(content, speakerDisplayNames)) {
-                    issues.push({
-                        code: "DIALOGUE_CONTENT_SPEAKER_PREFIX",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        action_index: actionIndex,
-                        summary: "Dialogue content appears to contain speaker prefixes.",
-                        repair_hint: "Move speaker labels into speaker_id/speakers/lines and keep content as spoken text only.",
-                    });
-                }
-                if (action["type"] === "dialogue") {
-                    const delivery = strOf(action["delivery"] || "single");
-                    if (!DELIVERY_VALUES.has(delivery)) {
-                        issues.push({
-                            code: "ENUM_DIALOGUE_DELIVERY",
-                            severity: "error",
-                            episode: ep["episode_id"],
-                            scene: scene["scene_id"],
-                            action_index: actionIndex,
-                            summary: `dialogue.delivery invalid: ${delivery}`,
-                            repair_hint: "Use single, simultaneous, overlap, or group.",
-                        });
-                    }
-                    if (delivery === "overlap") {
-                        const lines = asList(action["lines"]);
-                        if (lines.length === 0) {
-                            issues.push({
-                                code: "DIALOGUE_OVERLAP_LINES_EMPTY",
-                                severity: "error",
-                                episode: ep["episode_id"],
-                                scene: scene["scene_id"],
-                                action_index: actionIndex,
-                                summary: "Overlapping dialogue has no lines.",
-                                repair_hint: "Add lines with speaker_id and content.",
-                            });
-                        }
-                        for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
-                            const line = lines[lineIdx] ?? {};
-                            const sid = strOf(line["speaker_id"]);
-                            const lineContent = strOf(line["content"]).trim();
-                            if (!speakerIds.has(sid)) {
-                                issues.push({
-                                    code: "DANGLING_DIALOGUE_SPEAKER_REF",
-                                    severity: "error",
-                                    episode: ep["episode_id"],
-                                    scene: scene["scene_id"],
-                                    action_index: actionIndex,
-                                    summary: `Overlap line speaker not found: ${sid || "<empty>"}`,
-                                    repair_hint: "Patch speaker_id or add a speaker.",
-                                });
-                            }
-                            if (!lineContent) {
-                                issues.push({
-                                    code: "EMPTY_DIALOGUE_LINE",
-                                    severity: "error",
-                                    episode: ep["episode_id"],
-                                    scene: scene["scene_id"],
-                                    action_index: actionIndex,
-                                    summary: `Overlap line ${lineIdx} content is empty.`,
-                                    repair_hint: "Patch line content.",
-                                });
-                            }
-                            else if (contentHasSpeakerPrefix(lineContent, speakerDisplayNames)) {
-                                issues.push({
-                                    code: "DIALOGUE_CONTENT_SPEAKER_PREFIX",
-                                    severity: "error",
-                                    episode: ep["episode_id"],
-                                    scene: scene["scene_id"],
-                                    action_index: actionIndex,
-                                    summary: `Overlap line ${lineIdx} content contains a speaker prefix.`,
-                                    repair_hint: "Keep each overlap line content as spoken text only.",
-                                });
-                            }
-                        }
-                    }
-                    else if (action["speakers"]) {
-                        const speakersInAction = asList(action["speakers"]);
-                        if (speakersInAction.length === 0) {
-                            issues.push({
-                                code: "DIALOGUE_SPEAKERS_INVALID",
-                                severity: "error",
-                                episode: ep["episode_id"],
-                                scene: scene["scene_id"],
-                                action_index: actionIndex,
-                                summary: "dialogue.speakers must be an array.",
-                                repair_hint: "Patch speakers list.",
-                            });
-                        }
-                        for (const speaker of speakersInAction) {
-                            const sid = strOf(speaker["speaker_id"]);
-                            if (!speakerIds.has(sid)) {
-                                issues.push({
-                                    code: "DANGLING_DIALOGUE_SPEAKER_REF",
-                                    severity: "error",
-                                    episode: ep["episode_id"],
-                                    scene: scene["scene_id"],
-                                    action_index: actionIndex,
-                                    summary: `Dialogue speaker not found: ${sid || "<empty>"}`,
-                                    repair_hint: "Patch speaker_id or add a speaker.",
-                                });
-                            }
-                        }
-                    }
-                    else if (action["speaker_id"]) {
-                        const sid = strOf(action["speaker_id"]);
-                        if (!speakerIds.has(sid)) {
-                            issues.push({
-                                code: "DANGLING_DIALOGUE_SPEAKER_REF",
-                                severity: "error",
-                                episode: ep["episode_id"],
-                                scene: scene["scene_id"],
-                                action_index: actionIndex,
-                                summary: `Dialogue speaker not found: ${sid}`,
-                                repair_hint: "Patch speaker_id or add a speaker.",
-                            });
-                        }
-                    }
-                    else if (!action["actor_id"]) {
-                        issues.push({
-                            code: "DIALOGUE_WITHOUT_SPEAKER",
-                            severity: "error",
-                            episode: ep["episode_id"],
-                            scene: scene["scene_id"],
-                            action_index: actionIndex,
-                            summary: "Dialogue has no speaker.",
-                            repair_hint: "Patch speaker_id, speakers, lines, or legacy actor_id.",
-                        });
-                    }
-                }
-                if (action["type"] === "inner_thought") {
-                    const sid = strOf(action["speaker_id"]);
-                    if (sid && !speakerIds.has(sid)) {
-                        issues.push({
-                            code: "DANGLING_DIALOGUE_SPEAKER_REF",
-                            severity: "error",
-                            episode: ep["episode_id"],
-                            scene: scene["scene_id"],
-                            action_index: actionIndex,
-                            summary: `Inner thought speaker not found: ${sid}`,
-                            repair_hint: "Patch speaker_id or add a speaker.",
-                        });
-                    }
-                    if (!action["actor_id"] && !sid) {
-                        issues.push({
-                            code: "DIALOGUE_WITHOUT_ACTOR",
-                            severity: "error",
-                            episode: ep["episode_id"],
-                            scene: scene["scene_id"],
-                            action_index: actionIndex,
-                            summary: "Inner thought has no actor_id or speaker_id.",
-                            repair_hint: "Patch actor_id, speaker_id, or speaker registry.",
-                        });
-                    }
-                }
-                if (action["actor_id"] && !actorIds.has(strOf(action["actor_id"]))) {
-                    issues.push({
-                        code: "DANGLING_ACTION_ACTOR_REF",
-                        severity: "error",
-                        episode: ep["episode_id"],
-                        scene: scene["scene_id"],
-                        action_index: actionIndex,
-                        summary: `Action actor_id not found: ${action["actor_id"]}`,
-                        repair_hint: "Patch action actor_id to an existing actor.",
-                    });
-                }
-                for (const change of asList(action["state_changes"])) {
-                    const targetKind = strOf(change["target_kind"]);
-                    const targetId = strOf(change["target_id"]);
-                    const fromStateId = strOf(change["from_state_id"]);
-                    const toStateId = strOf(change["to_state_id"]);
-                    const effectiveFrom = strOf(change["effective_from"] || "after_action");
-                    if (!SCRIPT_TARGET_KINDS.has(targetKind)) {
-                        issues.push({
-                            code: "STATE_CHANGE_TARGET_KIND_INVALID",
-                            severity: "error",
-                            episode: ep["episode_id"],
-                            scene: scene["scene_id"],
-                            action_index: actionIndex,
-                            summary: `state_changes target_kind invalid: ${targetKind || "<empty>"}`,
-                            repair_hint: "Use actor, location, or prop.",
-                        });
-                        continue;
-                    }
-                    const validIds = { actor: actorIds, location: locationIds, prop: propIds }[targetKind];
-                    if (!validIds.has(targetId)) {
-                        issues.push({
-                            code: "DANGLING_STATE_CHANGE_TARGET_REF",
-                            severity: "error",
-                            episode: ep["episode_id"],
-                            scene: scene["scene_id"],
-                            action_index: actionIndex,
-                            summary: `State change target not found: ${targetKind}:${targetId}`,
-                            repair_hint: "Patch target_id.",
-                        });
-                    }
-                    for (const [label, sid] of [["from_state_id", fromStateId], ["to_state_id", toStateId]]) {
-                        if (sid && !(stateIdsByAsset.get(targetId) ?? new Set()).has(sid)) {
-                            issues.push({
-                                code: "DANGLING_STATE_CHANGE_STATE_REF",
-                                severity: "error",
-                                episode: ep["episode_id"],
-                                scene: scene["scene_id"],
-                                action_index: actionIndex,
-                                summary: `State change ${label} not found: ${sid}`,
-                                repair_hint: "Patch state change or asset states.",
-                            });
-                        }
-                    }
-                    if (!EFFECTIVE_FROM_VALUES.has(effectiveFrom)) {
-                        issues.push({
-                            code: "ENUM_STATE_CHANGE_EFFECTIVE_FROM",
-                            severity: "error",
-                            episode: ep["episode_id"],
-                            scene: scene["scene_id"],
-                            action_index: actionIndex,
-                            summary: `effective_from invalid: ${effectiveFrom}`,
-                            repair_hint: "Use before_action or after_action.",
-                        });
-                    }
-                }
-                const transition = action["transition_prompt"];
-                if (transition !== null && transition !== undefined) {
-                    if (!isDict(transition)) {
-                        issues.push({
-                            code: "TRANSITION_PROMPT_INVALID",
-                            severity: "error",
-                            episode: ep["episode_id"],
-                            scene: scene["scene_id"],
-                            action_index: actionIndex,
-                            summary: "transition_prompt must be an object.",
-                            repair_hint: "Patch or clear transition_prompt.",
-                        });
-                    }
-                    else {
-                        const targetKind = strOf(transition["target_kind"]);
-                        const targetId = strOf(transition["target_id"]);
-                        if (!SCRIPT_TARGET_KINDS.has(targetKind)) {
-                            issues.push({
-                                code: "TRANSITION_PROMPT_TARGET_KIND_INVALID",
-                                severity: "error",
-                                episode: ep["episode_id"],
-                                scene: scene["scene_id"],
-                                action_index: actionIndex,
-                                summary: `transition target_kind invalid: ${targetKind || "<empty>"}`,
-                                repair_hint: "Use actor, location, or prop.",
-                            });
-                        }
-                        else {
-                            const validIds = { actor: actorIds, location: locationIds, prop: propIds }[targetKind];
-                            if (!validIds.has(targetId)) {
-                                issues.push({
-                                    code: "DANGLING_TRANSITION_TARGET_REF",
-                                    severity: "error",
-                                    episode: ep["episode_id"],
-                                    scene: scene["scene_id"],
-                                    action_index: actionIndex,
-                                    summary: `Transition target not found: ${targetKind}:${targetId}`,
-                                    repair_hint: "Patch transition target.",
-                                });
-                            }
-                        }
-                    }
-                }
-            }
-        }
-    }
-    for (const prop of asList(script["props"])) {
-        const propId = strOf(prop["prop_id"]);
-        const propName = strOf(prop["prop_name"]).trim();
-        const propStateIds = stateIdsByAsset.get(propId) ?? new Set();
-        if (propStateIds.size === 0)
-            continue;
-        let hasUsedState = false;
-        for (const stateId of propStateIds) {
-            if (usedPropStateIds.has(stateId)) {
-                hasUsedState = true;
-                break;
-            }
-        }
-        if (!hasUsedState) {
-            issues.push({
-                code: "PROP_STATES_UNUSED",
-                severity: "warning",
-                incomplete_ok: true,
-                asset_kind: "prop",
-                asset_id: propId,
-                summary: `Prop ${propName || propId} defines states but no scene binds any of them.`,
-                repair_hint: "在 ep_*.md 的 `- 道具:` 中写明状态，或删除不需要的道具状态。",
-            });
-        }
-    }
-    const hasBlocking = issues.some((it) => it["severity"] === "blocking");
-    const hasErrors = issues.some((it) => it["severity"] === "error");
-    const validation = {
-        passed: !hasBlocking && !hasErrors,
-        has_blocking: hasBlocking,
-        issues,
-        stats: {
-            episodes: episodes.length,
-            scenes: totalScenes,
-            actions: totalActions,
-            actors: asList(script["actors"]).length,
-            locations: asList(script["locations"]).length,
-            props: asList(script["props"]).length,
-            speakers: asList(script["speakers"]).length,
-        },
-        script_path: opts.scriptData !== undefined ? "<in-memory>" : (scriptPath ?? path.join(dd, "script.initial.json")),
-        validated_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
-    };
-    // persist defaults to true (direct/write flows write validation.json into
-    // directDir); callers that want a side-effect-free check (e.g. `parse`) pass
-    // persist:false so no direct artifacts are created.
-    if (opts.persist !== false)
-        writeJson(path.join(dd, "validation.json"), validation);
-    return validation;
-}
-// ---------------------------------------------------------------------------
-// Resolve/lookup helpers
-// ---------------------------------------------------------------------------
-//# sourceMappingURL=validate.js.map