@lingjingai/scriptctl 0.35.0 → 0.36.0

package/skills/scriptctl/references/state-reference-repair.md

@@ -1,72 +1,59 @@
-# State 引用修复核验
+# State 引用修复核验（v3）
 
-适用：合并 state、删除 state，或修 `STATE_NOT_FOUND` / 状态引用错连。重点不是只改 `states[]`，而是确认引用该状态的场和动作都被修好。
+适用：合并 state、删除 state，或修 `STATE_NOT_MATERIALIZED` / 状态引用错连。重点不是只改 `states[]`，而是确认**引用该状态的场景 cast 引用**都被修好。
+
+> v3 里造型（state）只挂在**场景级 cast 引用**上（`scene.actors[]` / `props[]` / `location` 的 `state_id`），**没有** action 级 `state_changes`。所以引用只有一层，比 v2 简单。
 
 ## 操作语义
 
-scriptctl 没有单独的 `state-merge` 命令；合并 state 用“删除旧 state 并替换引用”表达：
+scriptctl 没有单独的 `state-merge` 命令；合并 state = "删旧 state 并替换引用"：
 
 ```bash
-scriptctl delete actor:act_001/st_old --strategy replace --replacement st_keep
-```
-
-删除且不保留引用：
+# 合并：把 st_old 的引用全指向 st_keep，再删 st_old（replacement 必须是同一资产已存在的 state_id）
+scriptctl state-delete actor:act_001/st_old --strategy replace --replacement st_keep
 
-```bash
-scriptctl delete actor:act_001/st_old --strategy remove
+# 真删除：删 st_old，引用它的场景 ref 的 state_id 被清掉
+scriptctl state-delete actor:act_001/st_old --strategy remove
 ```
 
-等价别名：`state-delete actor:act_001/st_old --strategy ...`。
+（`delete actor:act_001/st_old --strategy ...` 是等价写法。）
 
 ## 必查流程
 
-1. 操作前反查旧 state：
+1. **操作前反查旧 state**，看谁在引用它：
 
 ```bash
 scriptctl refs actor:act_001/st_old
 ```
 
-输出里 `scene_initial_state` 是场景 context 引用，形如 `ep_001/scn_003.context.actors[0]`；`state_change_from` / `state_change_to` 是 action 的 `state_changes` 引用。
+输出里是各场景 cast 引用（形如 `ep_001/scn_003.actors[0].state_id`）。
 
-2. 合并时用 `replace`，不要先裸删 state：
+2. **合并用 `replace`**，不要先裸删：
 
 ```bash
-scriptctl delete actor:act_001/st_old --strategy replace --replacement st_keep
+scriptctl state-delete actor:act_001/st_old --strategy replace --replacement st_keep
 ```
 
-期望结果：
-- `scriptctl refs actor:act_001/st_old` 为空。
-- `scriptctl refs actor:act_001/st_keep` 包含原来应该保留的场景初始状态和 action 状态变化引用。
-- `scriptctl validate` 通过。
+期望：`refs actor:act_001/st_old` 为空；`refs actor:act_001/st_keep` 含原来该保留的场景引用；`scriptctl validate` 通过。
 
-3. 真删除时用 `remove`：
+3. **真删除用 `remove`**：
 
 ```bash
-scriptctl delete actor:act_001/st_old --strategy remove
+scriptctl state-delete actor:act_001/st_old --strategy remove
 ```
 
-期望结果：
-- 场景 context 中引用该 state 的 ref 被保留，但 `state_id` 变成 `null`。
-- 涉及该 state 的 action `state_changes` 被移除，避免留下半截 from/to。
-- `scriptctl refs actor:act_001/st_old` 为空，`scriptctl validate` 通过。
-
-4. 如果只想清某场的初始状态，不要删 state：
+期望：引用该 state 的场景 ref 被保留、但 `state_id` 被清（角色仍在场，只是没造型）；`refs actor:act_001/st_old` 为空；`validate` 通过。
 
-```bash
-scriptctl context ep_001/scn_003 actor:act_001 --clear
-```
-
-如果要移除该角色在某场的引用：
+4. **只想清某场的造型**（不删 state）：
 
 ```bash
-scriptctl context ep_001/scn_003 actor:act_001 --remove
+scriptctl scene-ref ep_001/scn_003 actor:act_001 --clear     # 保留在场，清造型
+scriptctl scene-ref ep_001/scn_003 actor:act_001 --remove    # 整个移出该场
 ```
 
-## 状态引用散在两层
-
-改状态引用时两层都要覆盖，`replace`/`remove` 会自动处理，核验时也按这两层看：
-
-- 场景初始状态：`scene.context.{actors|locations|props}[].state_id`。
-- 动作状态变化：`action.state_changes[].from_state_id` / `to_state_id`。
+## 核验要点
 
-`replace` 把两层里指向旧 state 的引用全改成 replacement 再删旧定义；`remove` 把 context ref 的 `state_id` 清成 `null` 并删掉碰到旧 state 的 action state_changes。replacement 只能是**同一资产**上已存在的 state_id。改完用 `scriptctl refs actor:<id>/<st>` 复查为空、`scriptctl validate` 通过。
+- 引用只有一层：`scene.{actors|props}[].state_id` 和 `scene.location.state_id`。`replace`/`remove` 会自动处理这一层。
+- replacement 只能是**同一资产**上已存在的 state_id。
+- 改完固定两步复查：`scriptctl refs actor:<id>/<st>` 为空 + `scriptctl validate` 通过。
+- `STATE_NOT_MATERIALIZED`：某场引用了一个该资产上不存在的 state_id。用 `scriptctl states <asset>` 看合法 state_id，再 `scene-ref <ep/scn> <kind:id> --state <合法 id>` 修正。

package/dist/domain/direct/runner.d.ts

@@ -1,25 +0,0 @@
-import { type Stage, type StageContext } from "./stage.js";
-export interface RunStagesOptions {
-    force?: boolean;
-    bypassInternalCaches?: boolean;
-    only?: Set<string>;
-    persistScriptAfterStages?: boolean;
-}
-/**
- * Run the pipeline in order. A stage whose output artifact already exists and
- * validates is skipped (resume), unless `force` is set or it isn't in `only`.
- * Stages with `output: null` always run (they decide their own per-unit reuse).
- *
- * The StageIncomplete sentinel (raised by episode-synopsis when some episode
- * still has unextracted batches) is NOT swallowed — it propagates so the
- * orchestrator can emit the INIT INCOMPLETE report + EXIT_RUNTIME, exactly as
- * the former god-command did with its early return.
- */
-export declare function runStages(ctx: StageContext, stages?: readonly Stage[], opts?: RunStagesOptions): Promise<void>;
-/**
- * Run exactly one stage by name against an existing workspace. Each stage
- * rehydrates the prior artifacts it needs from disk (ensure* helpers), so a
- * single step can run standalone — `direct run metadata` re-extracts metadata
- * for a workspace whose script.initial.json already exists, etc.
- */
-export declare function runOne(ctx: StageContext, stageName: string): Promise<Stage>;

package/dist/domain/direct/runner.js

@@ -1,88 +0,0 @@
-import { CliError, EXIT_USAGE } from "../../common.js";
-import { stageRunStateName } from "./stage.js";
-import { STAGES, stageByName, stageNames } from "./stages/index.js";
-// Stages that mutate the in-memory script but rely on a LATER stage to persist
-// it: in a full init the script-synopsis stage is the single write point for
-// script.initial.json. When one of these runs standalone via `direct run`, no
-// later stage follows, so runOne must persist the result or the mutation is
-// silently lost (e.g. `direct run metadata` would update asset_metadata.json but
-// leave the stale script on disk). script-synopsis writes the script itself and
-// validate is read-only, so neither is listed.
-const SCRIPT_PERSISTING_STAGES = new Set(["script-merge", "asset-curation", "state-curation", "state-binding", "metadata"]);
-// Whether a stage can be skipped because its single output artifact is already
-// present and valid. Stages with `output: null` (per-unit / always-recompute)
-// are never skipped wholesale — they manage their own reuse internally.
-function isStageSatisfied(stage, ctx) {
-    if (stage.output === null)
-        return false;
-    return ctx.ws.readJsonSafe(stage.output) !== null;
-}
-/**
- * Run the pipeline in order. A stage whose output artifact already exists and
- * validates is skipped (resume), unless `force` is set or it isn't in `only`.
- * Stages with `output: null` always run (they decide their own per-unit reuse).
- *
- * The StageIncomplete sentinel (raised by episode-synopsis when some episode
- * still has unextracted batches) is NOT swallowed — it propagates so the
- * orchestrator can emit the INIT INCOMPLETE report + EXIT_RUNTIME, exactly as
- * the former god-command did with its early return.
- */
-export async function runStages(ctx, stages = STAGES, opts = {}) {
-    ctx.ws.ensure();
-    // script-synopsis is the natural write point for script.initial.json. If it will
-    // run later in THIS invocation it persists the cumulative script once at the end,
-    // so the per-stage hook below would only duplicate that write (and flush partial
-    // pre-synopsis artifacts). Only persist per-stage when synopsis is NOT in this run
-    // (a single-stage `direct run metadata` / runOne path), so the mutation isn't lost.
-    const synopsisPersistsLater = stages.some((s) => s.name === "script-synopsis" && (!opts.only || opts.only.has("script-synopsis")));
-    const persistScriptAfterStages = opts.persistScriptAfterStages ?? true;
-    for (const stage of stages) {
-        if (opts.only && !opts.only.has(stage.name))
-            continue;
-        if (!opts.force && isStageSatisfied(stage, ctx)) {
-            ctx.emitProgress(stage.name, "success");
-            ctx.timing.record({
-                name: stageRunStateName(stage.name),
-                category: "stage",
-                status: "skipped",
-                startedAtMs: Date.now(),
-                finishedAtMs: Date.now(),
-            });
-            continue;
-        }
-        const previousBypassInternalCaches = ctx.state.bypassInternalCaches;
-        ctx.state.bypassInternalCaches = Boolean(opts.bypassInternalCaches);
-        try {
-            await ctx.timing.span({ name: stageRunStateName(stage.name), category: "stage" }, () => stage.run(ctx));
-        }
-        finally {
-            ctx.state.bypassInternalCaches = previousBypassInternalCaches;
-        }
-        if (persistScriptAfterStages && !synopsisPersistsLater && SCRIPT_PERSISTING_STAGES.has(stage.name) && ctx.state.script) {
-            ctx.ws.writeJson("script.initial.json", ctx.state.script);
-        }
-    }
-}
-/**
- * Run exactly one stage by name against an existing workspace. Each stage
- * rehydrates the prior artifacts it needs from disk (ensure* helpers), so a
- * single step can run standalone — `direct run metadata` re-extracts metadata
- * for a workspace whose script.initial.json already exists, etc.
- */
-export async function runOne(ctx, stageName) {
-    const stage = stageByName(stageName);
-    if (!stage) {
-        throw new CliError("DIRECT RUN BLOCKED: unknown stage", `Unknown stage "${stageName}".`, {
-            exitCode: EXIT_USAGE,
-            required: [`one of: ${stageNames().join(", ")}`],
-            received: [stageName],
-            nextSteps: ["Pass a valid stage name to `direct run`."],
-        });
-    }
-    // Delegate to runStages so the single post-stage persist hook (and any future
-    // shared behaviour) applies identically to the standalone path — `direct run
-    // <stage> --force` and the non-force `runStages({only})` path must not diverge.
-    await runStages(ctx, [stage], { force: true, bypassInternalCaches: true });
-    return stage;
-}
-//# sourceMappingURL=runner.js.map

package/dist/domain/direct/runner.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../src/domain/direct/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAiC,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpE,+EAA+E;AAC/E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,iFAAiF;AACjF,gFAAgF;AAChF,+CAA+C;AAC/C,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,CAAC,CAAC,CAAC;AAkB5H,+EAA+E;AAC/E,8EAA8E;AAC9E,wEAAwE;AACxE,SAAS,gBAAgB,CAAC,KAAY,EAAE,GAAiB;IACvD,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,GAAG,CAAC,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;AACpD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAiB,EAAE,SAA2B,MAAM,EAAE,OAAyB,EAAE;IAC/G,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,kFAAkF;IAClF,iFAAiF;IACjF,mFAAmF;IACnF,oFAAoF;IACpF,MAAM,qBAAqB,GAAG,MAAM,CAAC,IAAI,CACvC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,iBAAiB,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CACxF,CAAC;IACF,MAAM,wBAAwB,GAAG,IAAI,CAAC,wBAAwB,IAAI,IAAI,CAAC;IACvE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,SAAS;QACtD,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;YAChD,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACxC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;gBAChB,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC;gBACnC,QAAQ,EAAE,OAAO;gBACjB,MAAM,EAAE,SAAS;gBACjB,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;gBACvB,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE;aACzB,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,MAAM,4BAA4B,GAAG,GAAG,CAAC,KAAK,CAAC,oBAAoB,CAAC;QACpE,GAAG,CAAC,KAAK,CAAC,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACpE,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1G,CAAC;gBAAS,CAAC;YACT,GAAG,CAAC,KAAK,CAAC,oBAAoB,GAAG,4BAA4B,CAAC;QAChE,CAAC;QACD,IAAI,wBAAwB,IAAI,CAAC,qBAAqB,IAAI,wBAAwB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACvH,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,qBAAqB,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,GAAiB,EAAE,SAAiB;IAC/D,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,QAAQ,CAAC,mCAAmC,EAAE,kBAAkB,SAAS,IAAI,EAAE;YACvF,QAAQ,EAAE,UAAU;YACpB,QAAQ,EAAE,CAAC,WAAW,UAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,QAAQ,EAAE,CAAC,SAAS,CAAC;YACrB,SAAS,EAAE,CAAC,0CAA0C,CAAC;SACxD,CAAC,CAAC;IACL,CAAC;IACD,8EAA8E;IAC9E,6EAA6E;IAC7E,gFAAgF;IAChF,MAAM,SAAS,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3E,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/domain/direct/stage.d.ts

@@ -1,108 +0,0 @@
-import type { ProviderLike } from "../direct-core.js";
-export type Dict = Record<string, unknown>;
-export type StageName = "source-prepare" | "episode-plan" | "episode-titles" | "batch-plan" | "batch-extract" | "episode-merge" | "episode-synopsis" | "script-merge" | "asset-curation" | "state-curation" | "state-binding" | "metadata" | "script-synopsis" | "validate";
-export declare function stageRunStateName(stage: StageName): string;
-export declare class Workspace {
-    readonly root: string;
-    readonly dir: string;
-    constructor(root: string);
-    ensure(): void;
-    pathOf(name: string): string;
-    rootPathOf(name: string): string;
-    has(name: string): boolean;
-    hasRoot(name: string): boolean;
-    readJson<T = Dict>(name: string): T;
-    readJsonOr<T = Dict>(name: string, fallback: T): T;
-    readJsonSafe<T = Dict>(name: string): T | null;
-    writeJson(name: string, data: unknown): void;
-    readText(name: string): string;
-    readRootText(name: string): string;
-    mkdir(name: string): string;
-    delete(name: string): void;
-}
-export interface DirectRunOptions {
-    source: string;
-    workspace: string;
-    providerName: string;
-    model: string;
-    concurrency: number;
-    batchMode: string;
-    batchTargetLines: number;
-    batchMaxChars: number;
-    batchMinLines: number;
-    selEpisodes: Set<number>;
-    selBatches: Set<string>;
-    retryErrors: boolean;
-    runAll: boolean;
-    skipSummary: boolean;
-    skipMetadata: boolean;
-    resummarize: boolean;
-    summaryThresholdChars: number;
-}
-export interface DirectRunState {
-    manifest: Dict | null;
-    episodePlan: Dict | null;
-    batchPlan: Dict | null;
-    sourceText: string;
-    projectName: string;
-    titleDegraded: number[];
-    pending: Dict[];
-    reusedBatchCount: number;
-    stickyErrorCount: number;
-    changedEpisodes: Set<number>;
-    doneBatches: number;
-    erroredBatches: number;
-    totalEpisodes: number;
-    totalBatches: number;
-    mergedResults: Dict[];
-    incompleteEpisodes: number[];
-    summaryDegradedEpisodes: number[];
-    summaryFullDegraded: boolean;
-    summaryDegradeReason: string;
-    script: Dict | null;
-    assetNormalization: Dict | null;
-    bypassInternalCaches: boolean;
-    validation: Dict | null;
-}
-export declare function emptyRunState(): DirectRunState;
-export declare class StageIncomplete extends Error {
-    constructor(message?: string);
-}
-export interface StageContext {
-    ws: Workspace;
-    options: DirectRunOptions;
-    state: DirectRunState;
-    provider(): ProviderLike;
-    timing: DirectTimingRecorder;
-    emitProgress: ProgressEmitter;
-    updateRunState(updates: Dict): void;
-}
-export type DirectTimingStatus = "success" | "error" | "skipped";
-export type DirectTimingCategory = "stage" | "substage" | "chunk" | "repair" | "branch";
-export interface DirectTimingSpanOptions {
-    name: string;
-    category: DirectTimingCategory;
-    parent?: string;
-    metadata?: Dict;
-}
-export interface DirectTimingRecordOptions extends DirectTimingSpanOptions {
-    status: DirectTimingStatus;
-    startedAtMs: number;
-    finishedAtMs: number;
-    error?: string;
-}
-export interface DirectTimingRecorder {
-    reset(command: string): void;
-    span<T>(options: DirectTimingSpanOptions, run: () => Promise<T> | T): Promise<T>;
-    record(options: DirectTimingRecordOptions): void;
-    flush(): void;
-}
-export interface Stage {
-    readonly name: StageName;
-    readonly output: string | null;
-    run(ctx: StageContext): Promise<void>;
-}
-export interface ProgressEmitter {
-    (stage: StageName, status?: "running" | "success" | "warning" | "skipped" | "error" | "pending"): void;
-}
-export type ProviderFactory = () => ProviderLike;

package/dist/domain/direct/stage.js

@@ -1,134 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { deletePath, directDir, exists, readJson, readText, writeJson, } from "../../common.js";
-// run_state.json carries the snake_case stage names that `direct status` and
-// emitInitProgress already key on; keep them as the persisted identity so the
-// status table is byte-compatible with the pre-refactor pipeline.
-export function stageRunStateName(stage) {
-    switch (stage) {
-        case "source-prepare": return "source_prepare";
-        case "episode-plan": return "episode_plan";
-        case "episode-titles": return "episode_titles";
-        case "batch-plan": return "batch_plan";
-        case "batch-extract": return "batch_extract";
-        case "episode-merge": return "episode_merge";
-        case "episode-synopsis": return "episode_synopsis";
-        case "script-merge": return "script_merge";
-        case "asset-curation": return "asset_curation";
-        case "state-curation": return "state_curation";
-        case "state-binding": return "state_binding";
-        case "metadata": return "metadata_extract";
-        case "script-synopsis": return "script_synopsis";
-        case "validate": return "validate";
-    }
-}
-// ---------------------------------------------------------------------------
-// Workspace — typed, atomic artifact IO over the direct workspace directory.
-// Wraps common.ts's DEFAULT_STORE writes (tmp file + rename), so a crash mid-
-// write can never leave a torn artifact. Sole owner of the `*_results/`,
-// `script.initial.json`, `run_state.json` on-disk layout used by the pipeline.
-// ---------------------------------------------------------------------------
-export class Workspace {
-    root;
-    dir;
-    constructor(root) {
-        this.root = root;
-        this.dir = directDir(root);
-    }
-    ensure() {
-        fs.mkdirSync(this.dir, { recursive: true });
-    }
-    // Absolute path of an artifact under the direct dir (e.g. "episode_plan.json"
-    // or "batch_results"). Relative segments are joined onto the direct dir.
-    pathOf(name) {
-        return path.join(this.dir, name);
-    }
-    // Absolute path of a file relative to the workspace ROOT (e.g. "source.txt",
-    // which lives beside the direct dir, not inside it).
-    rootPathOf(name) {
-        return path.join(this.root, name);
-    }
-    has(name) {
-        return exists(this.pathOf(name));
-    }
-    hasRoot(name) {
-        return exists(this.rootPathOf(name));
-    }
-    readJson(name) {
-        return readJson(this.pathOf(name));
-    }
-    readJsonOr(name, fallback) {
-        return this.has(name) ? this.readJson(name) : fallback;
-    }
-    // Read but never throw on a malformed/absent artifact — returns null so a
-    // stage can treat "present but corrupt" the same as "missing" (self-heal).
-    readJsonSafe(name) {
-        if (!this.has(name))
-            return null;
-        try {
-            return this.readJson(name);
-        }
-        catch {
-            return null;
-        }
-    }
-    // Atomic write (tmp + rename, via DEFAULT_STORE.writeJson). Creates the parent
-    // dir if needed so a stage never has to mkdir its own results dir.
-    writeJson(name, data) {
-        fs.mkdirSync(path.dirname(this.pathOf(name)), { recursive: true });
-        writeJson(this.pathOf(name), data);
-    }
-    readText(name) {
-        return readText(this.pathOf(name));
-    }
-    readRootText(name) {
-        return readText(this.rootPathOf(name));
-    }
-    mkdir(name) {
-        const p = this.pathOf(name);
-        fs.mkdirSync(p, { recursive: true });
-        return p;
-    }
-    delete(name) {
-        const p = this.pathOf(name);
-        if (exists(p))
-            deletePath(p);
-    }
-}
-export function emptyRunState() {
-    return {
-        manifest: null,
-        episodePlan: null,
-        batchPlan: null,
-        sourceText: "",
-        projectName: "",
-        titleDegraded: [],
-        pending: [],
-        reusedBatchCount: 0,
-        stickyErrorCount: 0,
-        changedEpisodes: new Set(),
-        doneBatches: 0,
-        erroredBatches: 0,
-        totalEpisodes: 0,
-        totalBatches: 0,
-        mergedResults: [],
-        incompleteEpisodes: [],
-        summaryDegradedEpisodes: [],
-        summaryFullDegraded: false,
-        summaryDegradeReason: "",
-        script: null,
-        assetNormalization: null,
-        bypassInternalCaches: false,
-        validation: null,
-    };
-}
-// Sentinel a stage throws to abort the run with an "incomplete" (not "failed")
-// outcome — the batch-extract → episode-merge path uses it when some episode
-// still has unextracted batches, which is a resumable non-error stop.
-export class StageIncomplete extends Error {
-    constructor(message = "stage incomplete") {
-        super(message);
-        this.name = "StageIncomplete";
-    }
-}
-//# sourceMappingURL=stage.js.map

package/dist/domain/direct/stage.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"stage.js","sourceRoot":"","sources":["../../../src/domain/direct/stage.ts"],"names":[],"mappings":"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"}

package/dist/domain/direct/stages/asset-curation.d.ts

@@ -1,2 +0,0 @@
-import type { Stage } from "../stage.js";
-export declare const assetCurationStage: Stage;

package/dist/domain/direct/stages/asset-curation.js

@@ -1,10 +0,0 @@
-import { stageAssetCuration } from "../../../usecases/direct.js";
-// Provider first emits name-only grouping expressions, then compact curation
-// expressions; deterministic code parses and applies both to ctx.state.script
-// (or script.initial.json). Writes: asset_grouping.json, asset_curation.json.
-export const assetCurationStage = {
-    name: "asset-curation",
-    output: "asset_curation.json",
-    run: (ctx) => stageAssetCuration(ctx),
-};
-//# sourceMappingURL=asset-curation.js.map

package/dist/domain/direct/stages/asset-curation.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"asset-curation.js","sourceRoot":"","sources":["../../../../src/domain/direct/stages/asset-curation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,6EAA6E;AAC7E,8EAA8E;AAC9E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAU;IACvC,IAAI,EAAE,gBAAgB;IACtB,MAAM,EAAE,qBAAqB;IAC7B,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC;CACtC,CAAC"}

package/dist/domain/direct/stages/batch-extract.d.ts

@@ -1,2 +0,0 @@
-import type { Stage } from "../stage.js";
-export declare const batchExtractStage: Stage;

package/dist/domain/direct/stages/batch-extract.js

@@ -1,12 +0,0 @@
-import { stageBatchExtract } from "../../../usecases/direct.js";
-// LLM-extract each batch concurrently, persisting per-batch result/error files
-// (the resume unit). Reads: source.txt + episode_plan.json + batch_plan.json.
-// Writes: batch_results/<key>.json|.error.json. `output: null` — completion is
-// per-batch, not a single artifact, so the runner never skips it wholesale;
-// reuse is decided per batch inside the stage (classifyBatch).
-export const batchExtractStage = {
-    name: "batch-extract",
-    output: null,
-    run: (ctx) => stageBatchExtract(ctx),
-};
-//# sourceMappingURL=batch-extract.js.map

package/dist/domain/direct/stages/batch-extract.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch-extract.js","sourceRoot":"","sources":["../../../../src/domain/direct/stages/batch-extract.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,iBAAiB,GAAU;IACtC,IAAI,EAAE,eAAe;IACrB,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC;CACrC,CAAC"}

package/dist/domain/direct/stages/batch-plan.d.ts

@@ -1,2 +0,0 @@
-import type { Stage } from "../stage.js";
-export declare const batchPlanStage: Stage;

package/dist/domain/direct/stages/batch-plan.js

@@ -1,9 +0,0 @@
-import { stageBatchPlan } from "../../../usecases/direct.js";
-// Split each episode into natural extraction batches (deterministic). Reads:
-// source.txt + episode_plan.json. Writes: batch_plan.json.
-export const batchPlanStage = {
-    name: "batch-plan",
-    output: "batch_plan.json",
-    run: (ctx) => stageBatchPlan(ctx),
-};
-//# sourceMappingURL=batch-plan.js.map

package/dist/domain/direct/stages/batch-plan.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"batch-plan.js","sourceRoot":"","sources":["../../../../src/domain/direct/stages/batch-plan.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,6EAA6E;AAC7E,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAU;IACnC,IAAI,EAAE,YAAY;IAClB,MAAM,EAAE,iBAAiB;IACzB,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC;CAClC,CAAC"}

package/dist/domain/direct/stages/episode-merge.d.ts

@@ -1,2 +0,0 @@
-import type { Stage } from "../stage.js";
-export declare const episodeMergeStage: Stage;

package/dist/domain/direct/stages/episode-merge.js

@@ -1,11 +0,0 @@
-import { stageEpisodeMerge } from "../../../usecases/direct.js";
-// Merge each episode's batch results into one episode result (deterministic).
-// Reads: batch_results/ + plans. Writes: in-memory merged results carried on
-// ctx.state (persisted by the episode-synopsis stage, matching the god-command
-// order). `output: null` — the persisted artifact is written by the next stage.
-export const episodeMergeStage = {
-    name: "episode-merge",
-    output: null,
-    run: (ctx) => stageEpisodeMerge(ctx),
-};
-//# sourceMappingURL=episode-merge.js.map

package/dist/domain/direct/stages/episode-merge.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"episode-merge.js","sourceRoot":"","sources":["../../../../src/domain/direct/stages/episode-merge.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,8EAA8E;AAC9E,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAU;IACtC,IAAI,EAAE,eAAe;IACrB,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC;CACrC,CAAC"}

package/dist/domain/direct/stages/episode-plan.d.ts

@@ -1,2 +0,0 @@
-import type { Stage } from "../stage.js";
-export declare const episodePlanStage: Stage;

package/dist/domain/direct/stages/episode-plan.js

@@ -1,9 +0,0 @@
-import { stageEpisodePlan } from "../../../usecases/direct.js";
-// Split source.txt into episodes (deterministic). Reads: source.txt. Writes:
-// episode_plan.json.
-export const episodePlanStage = {
-    name: "episode-plan",
-    output: "episode_plan.json",
-    run: (ctx) => stageEpisodePlan(ctx),
-};
-//# sourceMappingURL=episode-plan.js.map

package/dist/domain/direct/stages/episode-plan.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"episode-plan.js","sourceRoot":"","sources":["../../../../src/domain/direct/stages/episode-plan.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,6EAA6E;AAC7E,qBAAqB;AACrB,MAAM,CAAC,MAAM,gBAAgB,GAAU;IACrC,IAAI,EAAE,cAAc;IACpB,MAAM,EAAE,mBAAmB;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC;CACpC,CAAC"}

package/dist/domain/direct/stages/episode-synopsis.d.ts

@@ -1,2 +0,0 @@
-import type { Stage } from "../stage.js";
-export declare const episodeSynopsisStage: Stage;

package/dist/domain/direct/stages/episode-synopsis.js

@@ -1,12 +0,0 @@
-import { stageEpisodeSynopsis } from "../../../usecases/direct.js";
-// Resolve each episode's synopsis (reduce-1: passthrough / reuse / skip / LLM
-// stitch) then persist episode_results/ep_NNN.json. Reads: merged results +
-// prior persisted syn. Writes: episode_results/*.json. Also raises the resumable
-// "incomplete" stop when an episode still has unextracted batches. `output: null`
-// — completion is per-episode, decided inside the stage.
-export const episodeSynopsisStage = {
-    name: "episode-synopsis",
-    output: null,
-    run: (ctx) => stageEpisodeSynopsis(ctx),
-};
-//# sourceMappingURL=episode-synopsis.js.map

package/dist/domain/direct/stages/episode-synopsis.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"episode-synopsis.js","sourceRoot":"","sources":["../../../../src/domain/direct/stages/episode-synopsis.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAEnE,8EAA8E;AAC9E,4EAA4E;AAC5E,iFAAiF;AACjF,kFAAkF;AAClF,yDAAyD;AACzD,MAAM,CAAC,MAAM,oBAAoB,GAAU;IACzC,IAAI,EAAE,kBAAkB;IACxB,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,oBAAoB,CAAC,GAAG,CAAC;CACxC,CAAC"}

package/dist/domain/direct/stages/episode-titles.d.ts

@@ -1,2 +0,0 @@
-import type { Stage } from "../stage.js";
-export declare const episodeTitlesStage: Stage;

package/dist/domain/direct/stages/episode-titles.js

@@ -1,12 +0,0 @@
-import { stageEpisodeTitles } from "../../../usecases/direct.js";
-// LLM-enrich the plan's missing episode titles (soft-degrade to deterministic
-// titles). Reads: source.txt + episode_plan.json. Writes: episode_plan.json
-// (titles filled in place). `output: null` — the plan artifact already exists
-// from episode-plan, so completion isn't captured by file presence; the runner
-// never skips titles wholesale.
-export const episodeTitlesStage = {
-    name: "episode-titles",
-    output: null,
-    run: (ctx) => stageEpisodeTitles(ctx),
-};
-//# sourceMappingURL=episode-titles.js.map

package/dist/domain/direct/stages/episode-titles.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"episode-titles.js","sourceRoot":"","sources":["../../../../src/domain/direct/stages/episode-titles.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,+EAA+E;AAC/E,gCAAgC;AAChC,MAAM,CAAC,MAAM,kBAAkB,GAAU;IACvC,IAAI,EAAE,gBAAgB;IACtB,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC;CACtC,CAAC"}

package/dist/domain/direct/stages/index.d.ts

@@ -1,19 +0,0 @@
-import type { Stage, StageName } from "../stage.js";
-import { sourcePrepareStage } from "./source-prepare.js";
-import { episodePlanStage } from "./episode-plan.js";
-import { episodeTitlesStage } from "./episode-titles.js";
-import { batchPlanStage } from "./batch-plan.js";
-import { batchExtractStage } from "./batch-extract.js";
-import { episodeMergeStage } from "./episode-merge.js";
-import { episodeSynopsisStage } from "./episode-synopsis.js";
-import { scriptMergeStage } from "./script-merge.js";
-import { assetCurationStage } from "./asset-curation.js";
-import { stateCurationStage } from "./state-curation.js";
-import { stateBindingStage } from "./state-binding.js";
-import { metadataStage } from "./metadata.js";
-import { scriptSynopsisStage } from "./script-synopsis.js";
-import { validateStage } from "./validate.js";
-export declare const STAGES: readonly Stage[];
-export declare function stageByName(name: string): Stage | undefined;
-export declare function stageNames(): StageName[];
-export { sourcePrepareStage, episodePlanStage, episodeTitlesStage, batchPlanStage, batchExtractStage, episodeMergeStage, episodeSynopsisStage, scriptMergeStage, assetCurationStage, stateCurationStage, stateBindingStage, metadataStage, scriptSynopsisStage, validateStage, };