@lingfan-engine/stories-build 0.0.0-stage → 0.1.2

package/src/config/state-type.ts

@@ -0,0 +1,85 @@
+/**
+ * InferStateSchema：把 config.state 数据声明推导为强类型（TS 原生推导，运行期零开销）。
+ * 形态 A 的 StoryState
+ * 类型面 = `InferStateSchema<typeof state>`，由消费工程按需引用，不再依赖 lib 约定。
+ *
+ * schema 值文法（与编排层 state-schema.ts 的降维一一对应；源形态统一纯嵌套对象，
+ * 点路径键已砍——扁平 defines 键由降维展平产生）：
+ * - shorthand 字面量（100 / "other" / true）→ 宽类型，嵌套字面量对象递归展开；
+ * - descriptor { type: X; default: D } → 类型只由 X 决定：保留字 "number"|"string"|"boolean"
+ *   映射原生类型；X 为枚举对象 → 成员值联合（X[keyof X]）；X 为单元素数组 [Leaf] →
+ *   InferLeaf<Leaf>[]；X 为多元素数组（as const 元组）→ 成员槽位并集
+ *   （InferUnionMember：保留字/null/嵌套并集/[leaf]/枚举对象）；其余兜底 unknown；
+ * - 嵌套对象递归展开。
+ */
+
+type Primitive = string | number | boolean;
+
+/** descriptor 的 type 槽位 → TS 类型；多元素数组（as const 元组）先行判为并集。 */
+type InferTypeRef<X> = X extends readonly [unknown, unknown, ...unknown[]]
+  ? InferUnionMember<X[number]>
+  : X extends "number"
+    ? number
+    : X extends "string"
+      ? string
+      : X extends "boolean"
+        ? boolean
+        : X extends readonly unknown[]
+          ? X extends readonly (infer Leaf)[]
+            ? InferLeaf<Leaf>[]
+            : never
+          : X[keyof X] extends Primitive
+            ? X[keyof X]
+            : unknown;
+
+/**
+ * 并集成员 → TS 类型（分布条件类型：对成员联合逐成员求值）。
+ * 顺序即优先级：保留字 → null → 多元素元组（嵌套并集递归）→ 单元素数组 → 枚举对象。
+ */
+type InferUnionMember<M> = M extends "number"
+  ? number
+  : M extends "string"
+    ? string
+    : M extends "boolean"
+      ? boolean
+      : M extends null
+        ? null
+        : M extends readonly [unknown, unknown, ...unknown[]]
+          ? InferUnionMember<M[number]>
+          : M extends readonly (infer Leaf)[]
+            ? InferLeaf<Leaf>[]
+            : M[keyof M] extends Primitive
+              ? M[keyof M]
+              : unknown;
+
+/** 数组 descriptor 的元素类型 → TS 类型。 */
+type InferLeaf<L> = L extends "number"
+  ? number
+  : L extends "string"
+    ? string
+    : L extends "boolean"
+      ? boolean
+      : L[keyof L] extends Primitive
+        ? L[keyof L]
+        : never;
+
+/** 单个 schema 值 → TS 类型：descriptor 优先，其次 shorthand 宽类型，嵌套对象递归。 */
+type InferValue<V> = V extends {
+  readonly type: unknown;
+  readonly default: unknown;
+}
+  ? InferTypeRef<V["type"]>
+  : V extends string
+    ? string
+    : V extends number
+      ? number
+      : V extends boolean
+        ? boolean
+        : V extends Record<PropertyKey, unknown>
+          ? { -readonly [K in keyof V]: InferValue<V[K]> }
+          : unknown;
+
+/** schema 以 as const 声明（字面量/descriptor 判别需要），但 state 运行期可写——推导全程剥 readonly。 */
+export type InferStateSchema<T> = {
+  -readonly [K in keyof T]: InferValue<T[K]>;
+};

package/src/config/story-config.ts

@@ -0,0 +1,113 @@
+import { existsSync, readdirSync } from "node:fs";
+import { isSafeFileNameSegment } from "@lingfan-engine/core";
+import { StoryBuildError } from "../shared/index.ts";
+
+/**
+ * 源工程布局声明（`Stories.src/config.ts`，根级唯一根文件）：
+ * `export const folders = [...]; export const start = "...";`（named exports 契约，
+ * 求值产物由 const-eval/config-eval 喂入）。
+ * - `folders`：故事/模块源目录（相对 `Stories.src/`，递归扫描；`"*"` = 未显式列出的
+ *   目录全部自动纳入，排除生成物目录）；
+ * - `start`：入口**故事文件名**——跨全部目录按文件名匹配，全局恰一（0 或 ≥2 fail-closed）；
+ * - `version`：可选故事版本（正整数，缺省 1）——进存档 `storyVersion`，
+ *   升级时经宿主 `migrateState` 钩子迁移旧档。
+ */
+export interface StorySourceConfig {
+  readonly folders: readonly string[];
+  readonly start: string;
+  readonly version?: number;
+}
+
+/** 布局声明文件名（根级唯一根 .ts；其余 .ts 一律住 folders 声明的目录里） */
+export const CONFIG_FILE = "config.ts";
+
+/** 根级唯一根文件守卫：根层（不递归）出现第二个 .ts 即 fail-closed。 */
+export function assertSingleRootScript(
+  sourcesDir: string,
+  sourcesDirName: string,
+): void {
+  const rootScripts = existsSync(sourcesDir)
+    ? readdirSync(sourcesDir)
+        .filter((name) => name.endsWith(".ts"))
+        .sort()
+    : [];
+  if (rootScripts.length > 1) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/ 根级发现 ${rootScripts.length} 个 .ts（${rootScripts.join("、")}）——根级唯一根文件是 ${CONFIG_FILE}；故事与模块源请放进 folders 声明的目录`,
+    );
+  }
+}
+
+/** folders 校验：非空数组，元素 = "*" 或相对 `Stories.src/` 的段级安全目录路径；禁指生成物目录。 */
+export function parseFolders(
+  value: unknown,
+  sourcesDirName: string,
+): readonly string[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: folders 须为非空目录名数组（可含 "*" 兜底）`,
+    );
+  }
+  const folders = value.map((entry, index) => {
+    if (entry === "*") return "*";
+    if (typeof entry !== "string") {
+      throw new StoryBuildError(
+        `${sourcesDirName}/${CONFIG_FILE}: folders[${index}] 须为目录名字符串或 "*"，得到 ${describe(entry)}`,
+      );
+    }
+    if (entry === "gen" || entry.startsWith("gen/")) {
+      throw new StoryBuildError(
+        `${sourcesDirName}/${CONFIG_FILE}: folders[${index}] "${entry}" 指向生成物目录——gen/ 由构建管理，不参与源扫描`,
+      );
+    }
+    if (
+      entry.length === 0 ||
+      entry.includes("\\") ||
+      !entry.split("/").every((segment) => isSafeFileNameSegment(segment))
+    ) {
+      throw new StoryBuildError(
+        `${sourcesDirName}/${CONFIG_FILE}: folders[${index}] "${entry}" 不是合法目录名（须为相对 ${sourcesDirName}/ 的段级安全路径）`,
+      );
+    }
+    return entry;
+  });
+  return folders;
+}
+
+/** start 校验：含 .ts 的故事文件名（如 "main.ts"），不含目录——目录归属由 folders 管。 */
+export function parseStart(value: unknown, sourcesDirName: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: start 须为入口故事文件名（如 "main.ts"）`,
+    );
+  }
+  if (value.includes("/") || value.includes("\\")) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: start "${value}" 须为文件名不含目录——目录布局归 folders 管`,
+    );
+  }
+  if (!value.endsWith(".ts")) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: start "${value}" 须含 .ts 扩展名（如 "main.ts"）`,
+    );
+  }
+  return value;
+}
+
+/** version 校验：正整数（存档 storyVersion 语义，读档迁移对账）；缺省 = 1（不写导出即缺省）。 */
+export function parseVersion(
+  value: unknown,
+  sourcesDirName: string,
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: version 须为正整数（进存档 storyVersion；缺省 = 1），得到 ${describe(value)}`,
+    );
+  }
+  return value;
+}
+
+function describe(value: unknown): string {
+  return value === null ? "null" : Array.isArray(value) ? "数组" : typeof value;
+}

package/src/const-eval/config-eval.ts

@@ -0,0 +1,181 @@
+/**
+ * config.ts 求值（编排层唯一的 config 读取通道）：
+ * `Stories.src/config.ts` 两种声明形态等价，单次求值一并取出，**双形态混用 fail-closed**：
+ * - default 对象（推荐）：`export default { folders, start, version?, vars?, state? }`
+ *   —— 强类型单出口（配合 `StoriesConfig` 全局类型做 IDE 补全）；
+ * - named exports：`export const folders/start/version/vars/state`（兼容既有工程）。
+ * 再叠加形态 B 的 define() 累积（与两种 config 形态正交）。
+ * - 布局字段复用 parseFolders/parseStart/parseVersion 校验（fail-closed 带定位）；
+ * - define 调用经 mergeDefineCalls 合并为纯嵌套树（同键二次定义/形状冲突一次报全部）；
+ * - state 与 define 调用互斥（形态 A/B 二选一，皆缺省合法）。
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  CONFIG_FILE,
+  assertSingleRootScript,
+  parseFolders,
+  parseStart,
+  parseVersion,
+  type StorySourceConfig,
+} from "../config/story-config.ts";
+import {
+  defaultStoriesBuildTexts,
+  StoryBuildError,
+  type StoriesBuildTexts,
+} from "../shared/index.ts";
+import { evalConstModule } from "./const-eval.ts";
+import { formatConstDiagFile } from "./const-eval-pass.ts";
+import { mergeDefineCalls } from "./define-merge.ts";
+
+/** config.ts 单次求值的产物（编排层的 config 消费形态）。 */
+export interface ConfigEvalOutcome {
+  /** 布局声明（folders/start，已过校验） */
+  readonly config: StorySourceConfig;
+  /** `config.vars` 导出的键（typegen defineKeys 域贡献）；缺省 = 空数组 */
+  readonly vars: readonly string[];
+  /** `config.state` 导出原始树（形态 A）；缺省 = undefined（与 define 累积互斥） */
+  readonly state: unknown;
+  /** 形态 B define() 调用合并出的纯嵌套树；无调用 = 空对象 */
+  readonly defineTree: Record<string, unknown>;
+}
+
+export async function evalConfigModule(
+  root: string,
+  sourcesDirName: string,
+  texts: StoriesBuildTexts = defaultStoriesBuildTexts,
+  timeoutMs?: number,
+): Promise<ConfigEvalOutcome> {
+  const sourcesDir = join(root, sourcesDirName);
+  const configPath = join(sourcesDir, CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    throw new StoryBuildError(texts.configMissing(sourcesDirName, CONFIG_FILE));
+  }
+  assertSingleRootScript(sourcesDir, sourcesDirName);
+
+  const result = await evalConstModule(configPath, timeoutMs);
+  if ("diags" in result) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE} 求值失败（${result.diags.length} 条）：\n${result.diags
+        .map(
+          (diag) =>
+            `- ${formatConstDiagFile(diag.file, sourcesDir, sourcesDirName)}:${diag.line}:${diag.col} ${diag.message}`,
+        )
+        .join("\n")}`,
+    );
+  }
+  const values = result.values;
+
+  // 读取通道：default 对象优先，named exports 兜底；混用即报（契约不能有两个来源）。
+  const hasDefault = "default" in values;
+  const hasNamedConfig = ["folders", "start", "version", "vars", "state"].some(
+    (key) => key in values,
+  );
+  if (hasDefault && hasNamedConfig) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: default 对象与 named exports（folders/start/version/vars/state）混用——两种声明形态二选一`,
+    );
+  }
+  let foldersRaw: unknown;
+  let startRaw: unknown;
+  let versionRaw: unknown;
+  let varsRaw: unknown;
+  let stateRaw: unknown;
+  if (hasDefault) {
+    const spec = values.default;
+    if (spec === null || typeof spec !== "object" || Array.isArray(spec)) {
+      throw new StoryBuildError(
+        `${sourcesDirName}/${CONFIG_FILE}: default 导出须为配置对象 { folders, start, version?, vars?, state? }，得到 ${describe(spec)}`,
+      );
+    }
+    const obj = spec as Record<string, unknown>;
+    if (!("folders" in obj) || !("start" in obj)) {
+      const missing = ["folders", "start"].filter((key) => !(key in obj));
+      throw new StoryBuildError(
+        `${sourcesDirName}/${CONFIG_FILE}: default 配置缺少 ${missing.join("、")} 字段（folders/start 必需，version/vars/state 可缺省）`,
+      );
+    }
+    foldersRaw = obj.folders;
+    startRaw = obj.start;
+    versionRaw = obj.version;
+    varsRaw = "vars" in obj ? obj.vars : undefined;
+    stateRaw = "state" in obj ? obj.state : undefined;
+  } else {
+    foldersRaw = requireExport(values, "folders", sourcesDirName);
+    startRaw = requireExport(values, "start", sourcesDirName);
+    versionRaw = values.version;
+    varsRaw = values.vars;
+    stateRaw = "state" in values ? values.state : undefined;
+  }
+
+  const folders = parseFolders(foldersRaw, sourcesDirName);
+  const start = parseStart(startRaw, sourcesDirName);
+  const version = parseVersion(versionRaw, sourcesDirName);
+
+  const vars = readVarsKeySet(varsRaw, sourcesDirName);
+  const hasState = stateRaw !== undefined;
+  if (
+    hasState &&
+    (stateRaw === null ||
+      typeof stateRaw !== "object" ||
+      Array.isArray(stateRaw))
+  ) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: state 须为键集对象（形态 A：state = { ... } as const），得到 ${describe(stateRaw)}`,
+    );
+  }
+
+  const merged = mergeDefineCalls(result.defineCalls);
+  if (merged.conflicts.length > 0) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: define 声明冲突（${merged.conflicts.length} 条）：\n${merged.conflicts
+        .map((conflict) => `- ${conflict}`)
+        .join("\n")}`,
+    );
+  }
+  if (hasState && result.defineCalls.length > 0) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: 同时出现 state 声明与 define() 调用——形态 A/B 二选一（同文件混用即报错；两者皆缺省合法）`,
+    );
+  }
+
+  return {
+    config: { folders, start, version },
+    vars,
+    state: hasState ? stateRaw : undefined,
+    defineTree: merged.tree,
+  };
+}
+
+/** named exports 形态的布局必需导出（folders/start）；缺省 = fail-closed 并说明契约。 */
+function requireExport(
+  values: Record<string, unknown>,
+  name: string,
+  sourcesDirName: string,
+): unknown {
+  if (!(name in values)) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: 缺少 ${name} 导出（config.ts 契约：default 对象或 folders/start named exports 二选一，vars/state/version 可缺省）`,
+    );
+  }
+  return values[name];
+}
+
+/** vars 键集提取（键 = typegen defineKeys 域贡献；值文法不在此校验，与旧图谱扫描同宽）。 */
+function readVarsKeySet(
+  varsRaw: unknown,
+  sourcesDirName: string,
+): readonly string[] {
+  if (varsRaw === undefined) return [];
+  const spec = varsRaw;
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec)) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: vars 须为键集对象（defineVars({ ... }) 的返回值），得到 ${describe(spec)}`,
+    );
+  }
+  return Object.keys(spec as Record<string, unknown>);
+}
+
+function describe(value: unknown): string {
+  return value === null ? "null" : Array.isArray(value) ? "数组" : typeof value;
+}

package/src/const-eval/const-eval-pass.ts

@@ -0,0 +1,133 @@
+/**
+ * 编译期求值接入段（编排层）：扫描源清单，把含 node_modules 值导入的文件
+ * 整体交给 const-eval 求值，产出「文件 → 导出名 → JSON 值」喂给 story-compiler 内联。
+ *
+ * 触发判据（npm 值导入边界）：静态 import 的模块说明符非相对路径、非 @lingfan-engine/editor、
+ * 非 @lingfan-engine/core，且存在值绑定（default / 命名空间 / 任一非 type 具名绑定）。
+ * `import type` 整句编译期擦除，不触发求值；副作用导入同样不触发（图谱层自有
+ * fail-closed 诊断）。
+ *
+ * fail-closed（一次报全部）：
+ * - 故事文件含 node_modules 值导入 → 定向诊断（求值器只作用于纯模块；故事文件的
+ *   default 函数导出必然不可序列化，npm 值请收敛为纯模块的导出 const 再相对导入）；
+ * - 求值诊断（不可序列化导出 / 顶层抛错 / 超时 / esbuild 失败）→ 原样透传；
+ * - 双求值不一致（E13 确定性闸门，逐键 deepEqual）内建于 evalConstModule，诊断同此透传。
+ *
+ * 注意：被求值文件整体求值，因此不得再导出函数/类等非序列化值——请把函数与
+ * node_modules 值分模块放置（函数导出留在普通支撑模块）。
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as ts from "typescript";
+import { evalConstModule } from "./const-eval.ts";
+import type { CompilerConstValues } from "../compiler/index.ts";
+import {
+  defaultStoriesBuildTexts,
+  StoryBuildError,
+  type StoriesBuildTexts,
+} from "../shared/index.ts";
+
+/** 词汇层两包不触发求值：editor 是词汇出口（图谱层按词/命名空间绑定），engine 不参与创作导入。 */
+const RESERVED_SPECS: ReadonlySet<string> = new Set([
+  "@lingfan-engine/editor",
+  "@lingfan-engine/core",
+]);
+
+interface NpmValueImport {
+  spec: string;
+  line: number;
+  col: number;
+}
+
+function findNpmValueImports(rel: string, text: string): NpmValueImport[] {
+  const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true);
+  const hits: NpmValueImport[] = [];
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt)) continue;
+    if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const spec = stmt.moduleSpecifier.text;
+    if (spec.startsWith(".") || RESERVED_SPECS.has(spec)) continue;
+    const clause = stmt.importClause;
+    if (clause === undefined) continue; // 副作用导入：不触发求值（图谱层自有诊断）
+    if (clause.isTypeOnly) continue; // import type：编译期擦除，不在 npm 值导入约束内
+    const hasValueBinding =
+      clause.name !== undefined ||
+      (clause.namedBindings !== undefined &&
+        (ts.isNamespaceImport(clause.namedBindings) ||
+          (ts.isNamedImports(clause.namedBindings) &&
+            clause.namedBindings.elements.some((el) => !el.isTypeOnly))));
+    if (!hasValueBinding) continue;
+    const pos = sf.getLineAndCharacterOfPosition(stmt.getStart(sf));
+    hits.push({ spec, line: pos.line + 1, col: pos.character + 1 });
+  }
+  return hits;
+}
+
+/** 求值段：返回喂给编译器的 constValues（无触发文件 = 空对象，行为与未接入一致）。 */
+export async function runConstEvalPass(
+  sourcesDir: string,
+  storyFiles: readonly string[],
+  moduleFiles: readonly string[],
+  sourcesDirName: string,
+  texts: StoriesBuildTexts = defaultStoriesBuildTexts,
+  timeoutMs?: number,
+): Promise<CompilerConstValues> {
+  const storySet = new Set(storyFiles);
+  const failures: string[] = [];
+  const constValues: Record<string, Record<string, unknown>> = {};
+  // 排序保证诊断顺序确定（同一份输入 ⇒ 同一份报告）。
+  for (const rel of [...new Set([...storyFiles, ...moduleFiles])].sort()) {
+    let text: string;
+    try {
+      text = readFileSync(join(sourcesDir, rel), "utf8");
+    } catch {
+      continue; // 文件消失等读取异常交由源发现/编译段按既有路径报错
+    }
+    const hits = findNpmValueImports(rel, text);
+    if (hits.length === 0) continue;
+    if (storySet.has(rel)) {
+      for (const hit of hits) {
+        failures.push(
+          texts.storyNpmValueImport(
+            rel,
+            hit.line,
+            hit.col,
+            hit.spec,
+            sourcesDirName,
+          ),
+        );
+      }
+      continue;
+    }
+    const result = await evalConstModule(join(sourcesDir, rel), timeoutMs);
+    if ("diags" in result) {
+      failures.push(
+        ...result.diags.map(
+          (diag) =>
+            `- ${formatConstDiagFile(diag.file, sourcesDir, sourcesDirName)}:${diag.line}:${diag.col} ${diag.message}`,
+        ),
+      );
+      continue;
+    }
+    constValues[rel] = result.values;
+  }
+  if (failures.length > 0) {
+    throw new StoryBuildError(
+      `编译期求值失败（${failures.length} 条）：\n${failures.join("\n")}`,
+    );
+  }
+  return constValues;
+}
+
+/** const-eval 诊断的 file 是绝对入口路径；归一为 `Stories.src/<rel>` 与其余诊断同构。 */
+export function formatConstDiagFile(
+  file: string,
+  sourcesDir: string,
+  sourcesDirName: string,
+): string {
+  const norm = file.replace(/\\/g, "/");
+  const prefix = `${sourcesDir.replace(/\\/g, "/").replace(/\/$/, "")}/`;
+  return norm.startsWith(prefix)
+    ? `${sourcesDirName}/${norm.slice(prefix.length)}`
+    : norm;
+}

package/src/const-eval/const-eval.ts

@@ -0,0 +1,114 @@
+/**
+ * 编译期求值器（const-eval）：把 Stories.src 模块的模块层 const 初始化链求值成
+ * JSON 可序列化值，供 story-compiler 后续接入（const 内联 / staticFor 展开等）。
+ *
+ * 管线（每轮一遍，共两轮）：
+ * 1. esbuild 把入口模块的依赖链（含 node_modules 包）打包为内存 bundle（不落盘）；
+ * 2. 在隔离 worker（node worker_threads）中执行 bundle，取导出常量值；
+ * 3. 导出分类：仅接受 JSON 可序列化值；函数 / undefined / symbol / bigint / NaN /
+ *    非普通对象（Date/Map/Set/class 实例）等一律报诊断。
+ * 4. 构建期内建注入：`define` / `defineVars` 以求值环境实参进 factory（无运行时实体）——
+ *    define 调用按书写序累积成 DefineCall 序列（形态 B），defineVars 返回实参本身
+ *    （`export const vars = defineVars({...})` 的导出值 = 键集对象，即 config.vars 键来源）。
+ *
+ * 确定性闸门（fail-closed）：同一 entry 求值两次，逐键 deepEqual；不一致即报错，
+ * 文案指明禁 Date / Math.random / IO 等不确定源。
+ *
+ * 硬性约束：
+ * - 求值只执行模块顶层代码；导出的函数体（含故事默认导出函数体）从不被调用；
+ * - esbuild 打包与求值都在 worker 内完成，主进程不被模块顶层代码污染；
+ * - 本模块不修改 build/ 下其他既有文件，也不修改 packages/ 任何代码。
+ *
+ * 分文件：共享契约 `./contracts.ts`；worker 轮次 `./round/`；诊断辅助 `./diag/`。
+ */
+import { createRequire } from "node:module";
+import path from "node:path";
+import type { ConstEvalResult } from "./contracts.ts";
+import { deepEqual, firstDeterminismDiff } from "./diag/index.ts";
+import { evaluateOnce } from "./round/index.ts";
+
+/** 契约类型仍从本文件转出（同域兄弟模块按 `./const-eval.ts` 取件，取件面不变）。 */
+export type {
+  ConstEvalResult,
+  DefineCall,
+  DefineBad,
+  JsonValue,
+} from "./contracts.ts";
+
+/** 单轮求值超时缺省值（毫秒；模块顶层死循环不应拖死构建）。 */
+export const DEFAULT_EVAL_TIMEOUT_MS = 30_000;
+
+/**
+ * 求值入口：`entry` = Stories.src 内源文件绝对路径。
+ * `timeoutMs` = 单轮求值时限（缺省 30_000；编排入口 evalTimeoutMs 逐层透传至此）。
+ * 返回该模块全部导出常量的 JSON 可序列化值；任何不可序列化导出、打包失败、
+ * 顶层执行抛错、求值超时或两次求值不一致，都返回诊断集（fail-closed）。
+ */
+export async function evalConstModule(
+  entry: string,
+  timeoutMs: number = DEFAULT_EVAL_TIMEOUT_MS,
+): Promise<ConstEvalResult> {
+  const absEntry = path.resolve(entry);
+  const esbuildPath = resolveEsbuildPath();
+  if (esbuildPath === null) {
+    return {
+      diags: [
+        {
+          file: absEntry,
+          line: 1,
+          col: 1,
+          message:
+            "esbuild 未解析到——@lingfan-engine/stories-build 依赖 esbuild 完成依赖链打包，" +
+            "请确认该依赖已装好（本包从自身位置解析 esbuild，不借用调用方工程的 node_modules）",
+        },
+      ],
+    };
+  }
+
+  const evaluateRound = (): Promise<ConstEvalResult> =>
+    evaluateOnce(absEntry, esbuildPath, timeoutMs);
+
+  const first = await evaluateRound();
+  if ("diags" in first) return first;
+  const second = await evaluateRound();
+  if ("diags" in second) return second;
+
+  const differingKey = firstDeterminismDiff(first.values, second.values);
+  if (differingKey !== null) {
+    return {
+      diags: [
+        {
+          file: absEntry,
+          line: 1,
+          col: 1,
+          message:
+            `编译期求值不确定：导出 "${differingKey}" 在两次求值间不一致 —— ` +
+            "模块层 const 必须确定性求值：禁用 Date（new Date()/Date.now()）、Math.random、文件/网络 IO 等不确定源",
+        },
+      ],
+    };
+  }
+  if (!deepEqual(first.defineCalls, second.defineCalls)) {
+    return {
+      diags: [
+        {
+          file: absEntry,
+          line: 1,
+          col: 1,
+          message:
+            "编译期求值不确定：define() 声明在两次求值间不一致 —— " +
+            "模块顶层代码必须确定性求值：禁用 Date（new Date()/Date.now()）、Math.random、文件/网络 IO 等不确定源",
+        },
+      ],
+    };
+  }
+  return { values: first.values, defineCalls: first.defineCalls };
+}
+
+function resolveEsbuildPath(): string | null {
+  try {
+    return createRequire(import.meta.url).resolve("esbuild");
+  } catch {
+    return null;
+  }
+}