@lingfan-engine/stories-build 0.2.0 → 0.3.1

package/src/compiler/story-compiler/graph/state-root.ts

@@ -5,11 +5,11 @@
  * 根名与词函数冲突、或多个异名声明并存 → fail-closed 诊断（定位声明处）。
  */
 import * as ts from "typescript";
+import { MAX_ALIAS_HOPS } from "../../../shared/index.ts";
 import { DEFAULT_STATE_ROOT, WORD_NAMES } from "./core.ts";
 import type { DiagBag, ModuleRecord } from "./core.ts";
 
 const STATE_ROOT_ANNOTATION = "StoryState";
-const MAX_ALIAS_HOPS = 10;
 
 interface StateRootCandidate {
   rel: string;

package/src/compiler/story-compiler/graph.ts

@@ -8,6 +8,7 @@ export type {
   Graph,
   ModuleRecord,
   StoryConfig,
+  UiRegistryEntry,
 } from "./graph/index.ts";
 export {
   buildGraph,

package/src/compiler/story-compiler/index.ts

@@ -10,6 +10,7 @@ export type {
   Graph,
   ModuleRecord,
   StoryConfig,
+  UiRegistryEntry,
 } from "./graph.ts";
 export {
   buildGraph,

package/src/compiler/story-compiler/translate/expr/words/arg.ts

@@ -22,6 +22,11 @@ export function evaluateWordArg(
     if (binding?.kind === "cell") {
       return { name: binding.guard };
     }
+    // UI 句柄作词实参时就是它的名字（`mount(hub, true)` 的 `hub`），
+    // 与句柄在其他位置被折叠成字符串是同一件事。
+    if (binding?.kind === "ui") {
+      return { name: binding.name };
+    }
   }
   if (ts.isArrayLiteralExpression(expr)) {
     const out: unknown[] = [];

package/src/compiler/story-compiler.ts

@@ -17,8 +17,10 @@ import {
   type CompileDiag,
   type CompiledStory,
   type Graph,
+  type UiRegistryEntry,
 } from "./story-compiler/index.ts";
 import type { CompilerConstValues } from "./compiler-contract.ts";
+import type { AliasResolver } from "./story-compiler/graph/scan/alias.ts";
 
 export interface CompileStoriesResult {
   stories: Array<{ columnId: string; sourceRelPath: string; story: Story }>;
@@ -41,6 +43,13 @@ export function compileStories(input: {
   readonly characters?: ReadonlyMap<string, CharacterDef>;
   /** 文案注入（Partial）；缺省 = 内建缺省文案（即构建层的既有文案） */
   readonly texts?: Partial<StoriesBuildTexts>;
+  /** 工程 `tsconfig.json` 的 paths 解析器；缺省 = 只认相对路径 */
+  readonly alias?: AliasResolver;
+  /**
+   * UI 名注册表（扫描 `ui/` 目录的产物）；缺省 = 空表。
+   * 由编排层扫描后注入，编译器自己不读 UI 目录。
+   */
+  readonly uiRegistry?: readonly UiRegistryEntry[];
 }): CompileStoriesResult {
   const texts: StoriesBuildTexts = {
     ...defaultStoriesBuildTexts,
@@ -53,6 +62,8 @@ export function compileStories(input: {
     input.config,
     input.constValues,
     texts,
+    input.alias,
+    input.uiRegistry,
   );
   if (graph === null) return { stories: [], diags: diags.list() };
   const entry = resolveStart(graph, diags);

package/src/config/story-config.ts

@@ -1,6 +1,10 @@
 import { existsSync, readdirSync } from "node:fs";
 import { isSafeFileNameSegment } from "@lingfan-engine/core";
-import { StoryBuildError } from "../shared/index.ts";
+import {
+  StoryBuildError,
+  DEFAULT_GENERATED_DIR,
+  GEN_PREFIX,
+} from "../shared/index.ts";
 
 /**
  * 源工程布局声明（`Stories.src/config.ts`，根级唯一根文件）：
@@ -55,7 +59,7 @@ export function parseFolders(
         `${sourcesDirName}/${CONFIG_FILE}: folders[${index}] 须为目录名字符串或 "*"，得到 ${describe(entry)}`,
       );
     }
-    if (entry === "gen" || entry.startsWith("gen/")) {
+    if (entry === DEFAULT_GENERATED_DIR || entry.startsWith(GEN_PREFIX)) {
       throw new StoryBuildError(
         `${sourcesDirName}/${CONFIG_FILE}: folders[${index}] "${entry}" 指向生成物目录——gen/ 由构建管理，不参与源扫描`,
       );

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

@@ -7,6 +7,10 @@
  * `import type` 整句编译期擦除，不触发求值；副作用导入同样不触发（图谱层自有
  * fail-closed 诊断）。
  *
+ * 能展开成工程 `paths` 别名的说明符也不算 npm 值导入：别名指向的是工程内的文件，
+ * 由图谱层按普通模块连边。这里只问一次解析器（「有模式命中吗」），不判存在性与越界——
+ * 那两类错误由图谱层给出各自的诊断，本段提前拦会把别名笔误误报成 npm 导入。
+ *
  * fail-closed（一次报全部）：
  * - 故事文件含 node_modules 值导入 → 定向诊断（求值器只作用于纯模块；故事文件的
  *   default 函数导出必然不可序列化，npm 值请收敛为纯模块的导出 const 再相对导入）；
@@ -26,6 +30,7 @@ import {
   StoryBuildError,
   type StoriesBuildTexts,
 } from "../shared/index.ts";
+import { expandAlias, type PathsConfig } from "../pipeline/tsconfig-paths.ts";
 
 /** 词汇层两包不触发求值：editor 是词汇出口（图谱层按词/命名空间绑定），engine 不参与创作导入。 */
 const RESERVED_SPECS: ReadonlySet<string> = new Set([
@@ -39,7 +44,11 @@ interface NpmValueImport {
   col: number;
 }
 
-function findNpmValueImports(rel: string, text: string): NpmValueImport[] {
+function findNpmValueImports(
+  rel: string,
+  text: string,
+  paths: PathsConfig | null,
+): NpmValueImport[] {
   const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true);
   const hits: NpmValueImport[] = [];
   for (const stmt of sf.statements) {
@@ -47,6 +56,8 @@ function findNpmValueImports(rel: string, text: string): NpmValueImport[] {
     if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue;
     const spec = stmt.moduleSpecifier.text;
     if (spec.startsWith(".") || RESERVED_SPECS.has(spec)) continue;
+    // 工程别名指向工程内文件，不是 npm 值：留给图谱层按普通模块连边。
+    if (paths !== null && expandAlias(paths, spec).length > 0) continue;
     const clause = stmt.importClause;
     if (clause === undefined) continue; // 副作用导入：不触发求值（图谱层自有诊断）
     if (clause.isTypeOnly) continue; // import type：编译期擦除，不在 npm 值导入约束内
@@ -63,7 +74,10 @@ function findNpmValueImports(rel: string, text: string): NpmValueImport[] {
   return hits;
 }
 
-/** 求值段：返回喂给编译器的 constValues（无触发文件 = 空对象，行为与未接入一致）。 */
+/**
+ * 求值段：返回喂给编译器的 constValues（无触发文件 = 空对象，行为与未接入一致）。
+ * `paths` 为工程 `tsconfig.json` 的别名配置——别名说明符指向工程内文件，不算 npm 值导入。
+ */
 export async function runConstEvalPass(
   sourcesDir: string,
   storyFiles: readonly string[],
@@ -71,6 +85,7 @@ export async function runConstEvalPass(
   sourcesDirName: string,
   texts: StoriesBuildTexts = defaultStoriesBuildTexts,
   timeoutMs?: number,
+  paths: PathsConfig | null = null,
 ): Promise<CompilerConstValues> {
   const storySet = new Set(storyFiles);
   const failures: string[] = [];
@@ -83,7 +98,7 @@ export async function runConstEvalPass(
     } catch {
       continue; // 文件消失等读取异常交由源发现/编译段按既有路径报错
     }
-    const hits = findNpmValueImports(rel, text);
+    const hits = findNpmValueImports(rel, text, paths);
     if (hits.length === 0) continue;
     if (storySet.has(rel)) {
       for (const hit of hits) {

package/src/discovery/source-discovery.ts

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import ts from "typescript";
 import {
   defaultStoriesBuildTexts,
+  GEN_PREFIX,
   walkFiles,
   type StoriesBuildTexts,
 } from "../shared/index.ts";
@@ -42,7 +43,7 @@ export async function discoverSources(
   // —— 探测域：全部 .ts（排除生成物目录；config.ts 只能是根级唯一根文件）——
   const probe: string[] = [];
   for (const rel of tree.keys()) {
-    if (!rel.endsWith(".ts") || rel.startsWith("gen/")) continue;
+    if (!rel.endsWith(".ts") || rel.startsWith(GEN_PREFIX)) continue;
     if (rel.endsWith(`/${CONFIG_FILE}`)) {
       throw new StoryBuildError(
         `${sourcesDirName}/${rel}——${CONFIG_FILE} 只能是根级唯一根文件，故事与模块源请放进 folders 声明的目录`,
@@ -132,10 +133,14 @@ function collectCoveredDirs(
   }
   if (config.folders.includes("*")) {
     for (const rel of tree.keys()) {
-      if (!rel.endsWith(".ts") || rel.startsWith("gen/") || rel === CONFIG_FILE)
+      if (
+        !rel.endsWith(".ts") ||
+        rel.startsWith(GEN_PREFIX) ||
+        rel === CONFIG_FILE
+      )
         continue;
       const dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
-      if (dir !== "" && !dir.startsWith("gen/")) dirs.add(dir);
+      if (dir !== "" && !dir.startsWith(GEN_PREFIX)) dirs.add(dir);
     }
   }
   return dirs;

package/src/emit/emit.ts

@@ -26,6 +26,8 @@ export interface EmitOptions {
   readonly scriptGen: { readonly rel: string; readonly content: string };
   /** font 字面量类型面生成物（font.gen.d.ts）：同规则的恒产出生成物（空注册表也恒产出） */
   readonly fontGen: { readonly rel: string; readonly content: string };
+  /** UI 注册表生成物（ui_register.g.ts）：同规则的恒产出生成物（没有 UI 也恒产出） */
+  readonly uiGen: { readonly rel: string; readonly content: string };
 }
 
 /**
@@ -33,7 +35,7 @@ export interface EmitOptions {
  * - `Stories/**` 由源全量管理——内容不同的产物才写（新增/更新分开计），不在产物集内的
  *   既有列文件 = 陈旧，删除；
  * - 生成物（`<sourcesDir>/<generatedDir>/fun_register.g.ts`、`stories.gen.d.ts`、
- *   `state.gen.d.ts`、`script.gen.d.ts`、`font.gen.d.ts`）同规则：零守卫时若存在则删除，否则内容不同才写。它们的逻辑路径与
+ *   `state.gen.d.ts`、`script.gen.d.ts`、`font.gen.d.ts`、`ui_register.g.ts`）同规则：零守卫时若存在则删除，否则内容不同才写。它们的逻辑路径与
  *   `Stories/**` 不同命名空间，报告里以 `Stories.src/` 开头即生成物。
  * 返回值里的路径都是逻辑路径（相对工程根），供 CLI 直接打印。
  */
@@ -53,6 +55,7 @@ export function emitArtifacts(options: EmitOptions): {
     stateGen,
     scriptGen,
     fontGen,
+    uiGen,
   } = options;
   const existing = walkFiles(storiesDir);
   const added: string[] = [];
@@ -123,6 +126,13 @@ export function emitArtifacts(options: EmitOptions): {
     added,
     updated,
   );
+  writeConstantArtifact(
+    join(root, uiGen.rel),
+    uiGen.rel,
+    uiGen.content,
+    added,
+    updated,
+  );
   return { added, updated, removed };
 }
 

package/src/host-plugins/index.ts

@@ -0,0 +1,11 @@
+export {
+  STORY_FONTS_MODULE_ID,
+  STORY_LIST_MODULE_ID,
+  storyFontsVirtual,
+  storyListVirtual,
+} from "./virtual-modules.ts";
+export type {
+  DevServerLike,
+  HostPlugin,
+  ResourceRootOptions,
+} from "./virtual-modules.ts";

package/src/host-plugins/virtual-modules.ts

@@ -0,0 +1,138 @@
+/**
+ * 宿主构建期的清单虚拟模块：字体清单与故事清单。
+ *
+ * 两个清单都是**磁盘事实的投影**，不是需要作者维护的声明文件。让作者手抄名单的代价
+ * 不是「多写一行」，而是漏抄时构建期毫无察觉——漏登记的那一列要到运行期才以
+ * `unknown-column` 现形。
+ *
+ * 资源根与故事目录名都取 `@lingfan-engine/core` 的一处声明（`RESOURCES_DIR` /
+ * `STORIES_DIR`），且都可由调用方覆盖：工程把资源根搬到别处时改配置，不改扫描逻辑。
+ *
+ * 本模块只依赖 `node:*` 与引擎常量，**不 import vite**——插件对象按结构类型返回，
+ * 宿主自带的 vite 版本决定实际类型，这里不引入版本约束。
+ */
+import { fileURLToPath } from "node:url";
+import { join, resolve } from "node:path";
+import { RESOURCES_DIR, STORIES_DIR } from "@lingfan-engine/core";
+import { scanFontRegistry } from "../fonts/font-registry.ts";
+import { scanStoryRegistry } from "../story-list/story-registry.ts";
+
+/** 虚拟模块 id：字体清单 */
+export const STORY_FONTS_MODULE_ID = "virtual:story-fonts";
+/** 虚拟模块 id：故事清单 */
+export const STORY_LIST_MODULE_ID = "virtual:story-list";
+
+/** 宿主构建插件的最小结构面（vite 的 `Plugin` 与其它打包器同名成员兼容） */
+export interface HostPlugin {
+  readonly name: string;
+  readonly resolveId: (id: string) => string | null;
+  readonly load: (id: string) => string | null;
+  readonly configureServer?: (server: DevServerLike) => void;
+}
+
+/** dev server 的最小结构面：只用到「加监听目录、作废模块、整页刷新」三件事 */
+export interface DevServerLike {
+  readonly watcher: {
+    add: (paths: readonly string[]) => void;
+    on: (event: "add" | "unlink", listener: (file: string) => void) => void;
+  };
+  readonly moduleGraph: {
+    getModuleById: (id: string) => unknown;
+    invalidateModule: (mod: unknown) => void;
+  };
+  readonly ws: { send: (payload: { type: "full-reload" }) => void };
+}
+
+/** 资源根定位选项 */
+export interface ResourceRootOptions {
+  /**
+   * 资源根目录的绝对路径；缺省 = 调用方所在模块同级的 `<RESOURCES_DIR>`。
+   *
+   * 给绝对路径就完全由调用方决定资源根落在哪里——扫描不假设工程布局。
+   */
+  readonly resourcesDir?: string;
+}
+
+/** 缺省资源根：与调用方模块同级的 `<RESOURCES_DIR>`（模板/宿主的常规布局） */
+function defaultResourcesDir(moduleUrl: string): string {
+  return fileURLToPath(new URL(`./${RESOURCES_DIR}`, moduleUrl));
+}
+
+/**
+ * 造一个只提供固定值的虚拟模块插件。
+ *
+ * `watch` 里的目录在 dev 下被监听：新增或删除文件时把本模块作废并整页刷新，
+ * 这样「放一个故事文件进去」在 dev 里立即生效，不必重启 dev server。
+ */
+function virtualModule(
+  name: string,
+  moduleId: string,
+  build: () => string,
+  watch: readonly string[],
+): HostPlugin {
+  const resolved = `\0${moduleId}`;
+  return {
+    name,
+    resolveId: (id) => (id === moduleId ? resolved : null),
+    load: (id) => (id === resolved ? build() : null),
+    configureServer(server) {
+      const roots = watch.map((dir) => resolve(dir).replace(/\\/g, "/"));
+      server.watcher.add([...watch]);
+      const onChange = (file: string): void => {
+        const path = resolve(file).replace(/\\/g, "/");
+        if (!roots.some((root) => path.startsWith(`${root}/`))) return;
+        const mod = server.moduleGraph.getModuleById(resolved);
+        if (mod) server.moduleGraph.invalidateModule(mod);
+        server.ws.send({ type: "full-reload" });
+      };
+      server.watcher.on("add", onChange);
+      server.watcher.on("unlink", onChange);
+    },
+  };
+}
+
+/**
+ * 字体清单虚拟模块：扫描资源根下的字体目录产出字体名清单，
+ * 宿主据此注入 @font-face 与项目默认字体——与 `stories:build` 的字体名注册表同源。
+ *
+ * @param options 资源根覆盖；缺省取调用方模块同级的 `<RESOURCES_DIR>`
+ * @param moduleUrl 调用方模块的 `import.meta.url`（决定缺省资源根位置）
+ */
+export function storyFontsVirtual(
+  options: ResourceRootOptions = {},
+  moduleUrl: string,
+): HostPlugin {
+  const resourcesDir = options.resourcesDir ?? defaultResourcesDir(moduleUrl);
+  const fontsDir = join(resourcesDir, "Fonts");
+  return virtualModule(
+    "story-fonts",
+    STORY_FONTS_MODULE_ID,
+    () =>
+      `export const storyFonts = ${JSON.stringify(scanFontRegistry(fontsDir))};`,
+    [fontsDir],
+  );
+}
+
+/**
+ * 故事清单虚拟模块：扫描资源根下的故事目录得出要装载的故事文件表。
+ *
+ * TS 创作链的产物（`Stories.src/` 编译出的 `.json`）与手写 `.story` 落在同一棵树，
+ * 共用这一条扫描——创作形态不改变清单的来源。
+ *
+ * @param options 资源根覆盖；缺省取调用方模块同级的 `<RESOURCES_DIR>`
+ * @param moduleUrl 调用方模块的 `import.meta.url`（决定缺省资源根位置）
+ */
+export function storyListVirtual(
+  options: ResourceRootOptions = {},
+  moduleUrl: string,
+): HostPlugin {
+  const resourcesDir = options.resourcesDir ?? defaultResourcesDir(moduleUrl);
+  const storiesDir = join(resourcesDir, STORIES_DIR);
+  return virtualModule(
+    "story-list",
+    STORY_LIST_MODULE_ID,
+    () =>
+      `export const STORIES = ${JSON.stringify(scanStoryRegistry(storiesDir))};`,
+    [storiesDir],
+  );
+}

package/src/index.ts

@@ -74,3 +74,23 @@ export {
   scanFontRegistry,
   type FontEntry,
 } from "./fonts/index.ts";
+/** 故事文件清单注册表（资源根下故事目录扫描；宿主 Vite 插件与构建期检查同源消费） */
+export {
+  scanStoryRegistry,
+  STORY_EXTENSIONS,
+  type StoryPath,
+} from "./story-list/index.ts";
+/** UI 名注册表（源根兄弟目录 `ui/<名>/` 扫描；构建期 uis 闸门的判据来源） */
+export {
+  UI_DIR_NAME,
+  scanUiRegistry,
+  uiNameSet,
+  type UiFileEntry,
+} from "./ui/index.ts";
+/** UI import 面静态校验（UI 不归构建管，越界依赖只能在这里拦） */
+export {
+  checkUiImports,
+  scanUiImports,
+  type UiImportRef,
+  type UiImportViolation,
+} from "./ui/index.ts";

package/src/pipeline/gates.ts

@@ -9,11 +9,14 @@ import {
   StoryBuildError,
   type StoriesBuildTexts,
 } from "../shared/index.ts";
+import type { UiImportViolation } from "../ui/scan-imports.ts";
 
 /** 闸门判定的可配置项：文案里出现的目录名（缺省 = 现状；只影响文案，不影响判定） */
 export interface GateOptions {
   readonly resourcesDir: string;
   readonly sourcesDir: string;
+  /** UI 根目录名（源根的兄弟目录；只用于 `uis` 闸门的文案定位） */
+  readonly uiDirName: string;
   /** 文案注入（Partial）；缺省 = 内建缺省文案（即构建层的既有文案） */
   readonly texts?: Partial<StoriesBuildTexts>;
 }
@@ -71,11 +74,79 @@ export function assertKnownOps(
   );
 }
 
+/**
+ * 列级 `uis` 闸门：产物里出现的每个 UI 名，源里必须有对应实现文件。
+ *
+ * 判据取 `src/ui/<名>/<名>.<扩展名>`（与导入期同一条落位规则）——名字写错一个字母
+ * 在编译期毫无反应，只在宿主预加载落空时表现为「界面闪一下才出现」，很难归因；
+ * 构建期对着目录核一遍就把这类笔误变成一次构建失败。
+ */
+export function assertKnownUis(
+  story: Story,
+  uiNames: ReadonlySet<string>,
+  options: GateOptions,
+): void {
+  const unknownUis = new Map<string, string[]>();
+  story.columns.forEach((column, index) => {
+    const uis = column.uis;
+    if (!Array.isArray(uis)) return;
+    for (const name of uis) {
+      if (typeof name !== "string" || uiNames.has(name)) continue;
+      const hits = unknownUis.get(name) ?? [];
+      hits.push(`/columns/${index}`);
+      unknownUis.set(name, hits);
+    }
+  });
+  if (unknownUis.size === 0) return;
+  const texts: StoriesBuildTexts = {
+    ...defaultStoriesBuildTexts,
+    ...options.texts,
+  };
+  const at = columnLabeler(story);
+  const detail = [...unknownUis.entries()]
+    .map(
+      ([name, pointers]) =>
+        `  - ui "${name}" —— ${pointers.map(at).join("、")}`,
+    )
+    .join("\n");
+  throw new StoryBuildError(
+    texts.unknownUisGate(detail, options.sourcesDir, options.uiDirName),
+  );
+}
+
+/**
+ * UI import 面闸门（fail-closed）：`src/ui/**` 下任何越界 import 都让构建整体失败。
+ *
+ * 为什么在构建期拦：UI 不归 stories-build 编译，宿主打包器又拦不住 `@/host/boot`
+ * 这类合法路径。越界依赖只在这里可见，放过一次就再也看不见了。
+ * 明细每行带 `文件:行` 与说明符，超过 3 处折叠为「（共 N 处）」。
+ */
+export function assertUiImports(
+  violations: readonly UiImportViolation[],
+  options: GateOptions,
+): void {
+  if (violations.length === 0) return;
+  const texts: StoriesBuildTexts = {
+    ...defaultStoriesBuildTexts,
+    ...options.texts,
+  };
+  const shown = violations
+    .slice(0, 3)
+    .map(
+      (violation) =>
+        `  - ${violation.file}:${violation.line} \`${violation.specifier}\` —— ${violation.reason}`,
+    );
+  const more =
+    violations.length > 3 ? `\n  （共 ${violations.length} 处）` : "";
+  throw new StoryBuildError(
+    texts.uiImportGate(shown.join("\n") + more, options.uiDirName),
+  );
+}
+
 /**
  * 守卫名闸门（cell 范式的闭合校验）：故事 `guard.fn` 必须都在 cell 注册表键集内。
  * fail-closed 带命令指针定位（编辑器不校验守卫名——构建期兜住）。
- */
-export function assertKnownGuards(
+ */ export function assertKnownGuards(
   story: Story,
   guardNames: ReadonlySet<string>,
   options: GateOptions,

package/src/pipeline/index.ts

@@ -14,5 +14,7 @@ export {
 export {
   assertKnownGuards,
   assertKnownOps,
+  assertKnownUis,
+  assertUiImports,
   type GateOptions,
 } from "./gates.ts";

package/src/pipeline/merge.ts

@@ -0,0 +1,132 @@
+/**
+ * 工程级合并：把编译器交回的条目拼成一份 `Story`，并把跨来源的 defines 收敛成一张表。
+ *
+ * 与 `orchestrate.ts` 的分工：那边负责「按什么顺序做哪些段」，这边负责「段与段之间的
+ * 拼接与冲突判定」——都是纯函数，入参出参都是普通值，不碰 fs、不读配置。
+ */
+import {
+  STORIES_DIR,
+  type Story,
+  type StoryColumn,
+} from "@lingfan-engine/core";
+import { StoryBuildError } from "../shared/index.ts";
+import type { CompiledStoryEntry } from "../compiler/index.ts";
+import type { LocatedDefineCall } from "../const-eval/index.ts";
+
+/**
+ * 把一个编译条目读成 `{ story, column }`：取条目列（columnId 必须在产物列集中）、
+ * 回填产物 sourcePath、复核 story 骨架（columns 列集 + id/entry 字符串）。
+ * 更深的合法性（列 id 安全段、重复、entry 存在性等）交给 serializeProject /
+ * assembleProject 的既有校验兜底。
+ */
+export function readCompiledEntry(
+  entry: CompiledStoryEntry,
+  sourcesDirName: string,
+): { story: Story; column: StoryColumn } {
+  const sourceLabel = `${sourcesDirName}/${entry.sourceRelPath}`;
+  if (!isRecord(entry.story) || !Array.isArray(entry.story.columns)) {
+    throw new StoryBuildError(
+      `${sourceLabel}: 编译器条目 story 缺少列集（compileStories 契约破坏）`,
+    );
+  }
+  const column = entry.story.columns.find(
+    (item) => isRecord(item) && item.id === entry.columnId,
+  );
+  if (column === undefined) {
+    throw new StoryBuildError(
+      `${sourceLabel}: 编译器条目 columnId "${entry.columnId}" 不在产物列集中（compileStories 契约破坏）`,
+    );
+  }
+  if (
+    typeof entry.story.id !== "string" ||
+    entry.story.id === "" ||
+    typeof entry.story.entry !== "string" ||
+    entry.story.entry === ""
+  ) {
+    throw new StoryBuildError(
+      `${sourceLabel}: 编译器条目 story 缺少 id/entry（compileStories 契约破坏）`,
+    );
+  }
+  const story = entry.story as unknown as Story;
+  const typedColumn = column as unknown as StoryColumn;
+  typedColumn.sourcePath = `${STORIES_DIR}/${entry.sourceRelPath.replace(/\.ts$/, ".json")}`;
+  return { story, column: typedColumn };
+}
+
+/** 形态 A（state 导出）与模块层 define 互斥时的失败文案：每条调用一行，带落点。 */
+export function raiseFormAConflict(
+  sourcesDirName: string,
+  configFile: string,
+  calls: readonly LocatedDefineCall[],
+): never {
+  throw new StoryBuildError(
+    [
+      `${sourcesDirName}/${configFile}: 形态 A（state 导出）与模块层构建期 define 互斥——形态 A/B 二选一：`,
+      ...calls.map((call) => `- ${call.origin}${defineLabel(call)}`),
+    ].join("\n"),
+  );
+}
+
+/**
+ * 跨来源的 defines 合并：同键同值收敛，同键异值 = 冲突 fail-closed（一次报全部）。
+ * 来源 = config 状态（config 先行：形态 A state 或形态 B define 合并树）+ 各故事文件；
+ * config 与故事同键异值同样冲突。
+ */
+export function mergeDefines(
+  bySource: ReadonlyMap<string, { story: Story; columns: StoryColumn[] }>,
+  sourcesDirName: string,
+  schemaDefines: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = {};
+  const conflicts: string[] = [];
+  const put = (key: string, value: unknown, source: string): void => {
+    if (key in merged && merged[key] !== value) {
+      conflicts.push(
+        `- defines["${key}"] 在 ${sourcesDirName}/${source} 与先前的声明不一致（${JSON.stringify(merged[key])} ≠ ${JSON.stringify(value)}）`,
+      );
+      return;
+    }
+    merged[key] = value;
+  };
+  for (const [key, value] of Object.entries(schemaDefines)) {
+    put(key, value, "config.ts（state/define）");
+  }
+  for (const [source, { story }] of bySource) {
+    for (const [key, value] of Object.entries(story.defines ?? {})) {
+      put(key, value, source);
+    }
+  }
+  if (conflicts.length > 0) {
+    throw new StoryBuildError(
+      `跨故事文件的 defines 冲突（工程级 defines 只有一份，请统一到工程清单或消除同名异值）：\n${conflicts.join("\n")}`,
+    );
+  }
+  return merged;
+}
+
+/**
+ * 枚举槽位回收的模块源文：按调用落点去重排序，树里缺文本的文件跳过。
+ * 排序是为让回收顺序稳定（同样的源必得同样的类型面）。
+ */
+export function moduleSlotFiles(
+  sourceTree: ReadonlyMap<string, string>,
+  calls: readonly { rel: string }[],
+): Map<string, string> {
+  const files = new Map<string, string>();
+  for (const rel of [...new Set(calls.map((call) => call.rel))].sort()) {
+    const text = sourceTree.get(rel);
+    if (text !== undefined) files.set(rel, text);
+  }
+  return files;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 互斥文案里的一条调用签名（path 形带键名；spec 形统一签名） */
+function defineLabel(call: LocatedDefineCall): string {
+  return call.call.kind === "path"
+    ? `define("${call.call.path}")`
+    : "define({…})";
+}