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

package/src/discovery/source-discovery.ts

@@ -0,0 +1,193 @@
+import { join } from "node:path";
+import ts from "typescript";
+import {
+  defaultStoriesBuildTexts,
+  walkFiles,
+  type StoriesBuildTexts,
+} from "../shared/index.ts";
+import { CONFIG_FILE, type StorySourceConfig } from "../config/index.ts";
+import { StoryBuildError } from "../shared/index.ts";
+
+/**
+ * 源发现 v2（多目录形态）：
+ * - 编译域 = folders 显式目录递归（含 "*" 时扩展为全部含故事目录），始终排除生成物目录；
+ * - 探测域 = Stories.src 递归全集（同样排除生成物）——覆盖外发现 default 导出按覆盖规则拒绝
+ *   fail-closed（Stories.src 是全量管理：未登记的新章节文件不进编译域，其旧产物会被
+ *   当作陈旧产物删除，必须在发现期拦住）；
+ * - 故事 = default 具名 function 声明（列 id = 函数名，编译器侧解析）；default 存在但
+ *   匿名 / 表达式形态 fail-closed；仅具名导出 = 纯模块（无列，import 可达即可，
+ *   不要求在 folders 内）；
+ * - config.start = 入口故事文件名（含 .ts），跨探测域精确匹配，全局恰一。
+ */
+export interface DiscoveredSources {
+  /** 故事文件（相对 `Stories.src/`，posix 排序）——default 具名 function 声明的 .ts */
+  readonly stories: readonly string[];
+  /** 模块文件（相对 `Stories.src/`，posix 排序）——被 import 的支撑 .ts（含覆盖外纯模块） */
+  readonly modules: readonly string[];
+  /** `config.start` 匹配到的入口故事（相对 `Stories.src/`） */
+  readonly startSource: string;
+  /** 布局声明（编排层复核 / 报告用） */
+  readonly config: StorySourceConfig;
+}
+
+export async function discoverSources(
+  root: string,
+  sourcesDirName: string,
+  config: StorySourceConfig,
+  texts: StoriesBuildTexts = defaultStoriesBuildTexts,
+): Promise<DiscoveredSources> {
+  const tree = walkFiles(join(root, sourcesDirName));
+  const dirs = collectCoveredDirs(config, tree);
+
+  // —— 探测域：全部 .ts（排除生成物目录；config.ts 只能是根级唯一根文件）——
+  const probe: string[] = [];
+  for (const rel of tree.keys()) {
+    if (!rel.endsWith(".ts") || rel.startsWith("gen/")) continue;
+    if (rel.endsWith(`/${CONFIG_FILE}`)) {
+      throw new StoryBuildError(
+        `${sourcesDirName}/${rel}——${CONFIG_FILE} 只能是根级唯一根文件，故事与模块源请放进 folders 声明的目录`,
+      );
+    }
+    probe.push(rel);
+  }
+
+  const isCovered = (rel: string): boolean => {
+    if (rel === CONFIG_FILE) return false;
+    for (const dir of dirs) {
+      if (rel.startsWith(`${dir}/`)) return true;
+    }
+    return false;
+  };
+
+  // —— 覆盖外 default 导出（含转发形态；纯模块无 default 不受影响；
+  // 根级 config.ts 自身的 default 是布局声明，豁免）——
+  const uncoveredDefaults = probe.filter(
+    (rel) =>
+      rel !== CONFIG_FILE &&
+      !isCovered(rel) &&
+      classifyDefault(tree.get(rel)!) !== "none",
+  );
+  if (uncoveredDefaults.length > 0) {
+    throw new StoryBuildError(
+      texts.uncoveredDefaults(uncoveredDefaults, sourcesDirName),
+    );
+  }
+
+  // —— 覆盖域分类：故事（default 具名 function 声明）/ 模块（无 default）——
+  const stories: string[] = [];
+  const modules: string[] = [];
+  for (const rel of probe) {
+    if (rel === CONFIG_FILE) continue;
+    if (!isCovered(rel)) {
+      modules.push(rel);
+      continue;
+    }
+    const verdict = classifyDefault(tree.get(rel)!);
+    if (verdict === "story") {
+      stories.push(rel);
+    } else if (verdict === "none") {
+      modules.push(rel);
+    } else {
+      throw new StoryBuildError(
+        `${sourcesDirName}/${rel}: default 导出须是具名 function 声明（如 export default function main() {}）——匿名函数、类与表达式形态无法确定列 id`,
+      );
+    }
+  }
+
+  // —— start：跨探测域按精确文件名匹配，全局恰一 ——
+  const hits = probe.filter((rel) => fileNameOf(rel) === config.start);
+  if (hits.length === 0) {
+    throw new StoryBuildError(
+      stories.length === 0
+        ? `${sourcesDirName}/${CONFIG_FILE}: start "${config.start}" 未匹配任何故事文件——folders 声明的目录里没有 default 导出故事函数的 .ts`
+        : `${sourcesDirName}/${CONFIG_FILE}: start "${config.start}" 未匹配任何故事文件（候选：${stories.map(fileNameOf).join("、")}）`,
+    );
+  }
+  if (hits.length > 1) {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${CONFIG_FILE}: start "${config.start}" 命中 ${hits.length} 个文件（${hits.join("、")}）——入口故事必须全局恰一，请重命名文件消歧`,
+    );
+  }
+  const startSource = hits[0]!;
+  if (classifyDefault(tree.get(startSource)!) !== "story") {
+    throw new StoryBuildError(
+      `${sourcesDirName}/${startSource}: start "${config.start}" 命中的文件没有 default 导出的具名故事函数`,
+    );
+  }
+  return { stories, modules, startSource, config };
+}
+
+function fileNameOf(rel: string): string {
+  return rel.slice(rel.lastIndexOf("/") + 1);
+}
+
+/** 编译域目录集：显式 folders（含 "*" 时扩展为全树含 .ts 的目录），始终排除生成物目录前缀。 */
+function collectCoveredDirs(
+  config: StorySourceConfig,
+  tree: ReadonlyMap<string, string>,
+): Set<string> {
+  const dirs = new Set<string>();
+  for (const folder of config.folders) {
+    if (folder !== "*") dirs.add(folder);
+  }
+  if (config.folders.includes("*")) {
+    for (const rel of tree.keys()) {
+      if (!rel.endsWith(".ts") || rel.startsWith("gen/") || rel === CONFIG_FILE)
+        continue;
+      const dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
+      if (dir !== "" && !dir.startsWith("gen/")) dirs.add(dir);
+    }
+  }
+  return dirs;
+}
+
+type DefaultVerdict = "story" | "none" | "bad";
+
+/**
+ * default 导出形态判定（AST，非文本猜测）。TS 语法两条路径：
+ * - `export default function main() {}` = 直接 FunctionDeclaration 节点（default 修饰符）；
+ * - `export default …`（表达式 / 匿名函数）= ExportAssignment 包装；
+ * - `export { main as default }` = 具名转发（编译器侧解析函数名）。
+ * 具名 function 声明 / 具名转发 → "story"；匿名、类、表达式 → "bad"（不可作故事入口）；无 default → "none"。
+ */
+function classifyDefault(text: string): DefaultVerdict {
+  const source = ts.createSourceFile(
+    "source.ts",
+    text,
+    ts.ScriptTarget.Latest,
+    true,
+  );
+  let verdict: DefaultVerdict = "none";
+  for (const statement of source.statements) {
+    if (ts.isFunctionDeclaration(statement) && hasDefaultModifier(statement)) {
+      return statement.name !== undefined ? "story" : "bad";
+    }
+    if (ts.isExportAssignment(statement)) {
+      if (statement.isExportEquals) return "bad";
+      verdict = isNamedFunctionDeclaration(statement.expression)
+        ? "story"
+        : "bad";
+      continue;
+    }
+    if (!ts.isExportDeclaration(statement)) continue;
+    const clause = statement.exportClause;
+    if (clause === undefined || !ts.isNamedExports(clause)) continue;
+    const forwardsDefault = clause.elements.some(
+      (element) =>
+        element.name.text === "default" ||
+        element.propertyName?.text === "default",
+    );
+    if (forwardsDefault) return "story";
+  }
+  return verdict;
+}
+
+function hasDefaultModifier(node: ts.FunctionDeclaration): boolean {
+  return (node.modifiers ?? []).some(
+    (modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword,
+  );
+}
+
+function isNamedFunctionDeclaration(node: ts.Expression): boolean {
+  return ts.isFunctionDeclaration(node) && node.name !== undefined;
+}

package/src/emit/compile-roundtrip.ts

@@ -0,0 +1,45 @@
+import {
+  assembleProject,
+  MANIFEST_FILE,
+  serializeProject,
+  type SerializedProject,
+  type Story,
+} from "@lingfan-engine/core";
+import { StoryBuildError } from "../shared/index.ts";
+
+/**
+ * 编译：`serializeProject` = 编辑器写回同一条布局规则
+ * （单列拆分 + 清单托管键更新 + 非托管键保真）。
+ */
+export function compileStory(
+  story: Story,
+  manifest: unknown,
+): SerializedProject {
+  return serializeProject(story, manifest);
+}
+
+/**
+ * 往返自检（编译期互锁）：产物重组回 story，再序列化必须逐字节幂等。
+ * 不幂等说明「序列化 ↔ 组装」两条规则出现了分叉——这会让编辑器每次保存都漂移，
+ * 故构建期直接拦下（报第一个不一致的键名）。
+ */
+export function assertRoundTrip(serialized: SerializedProject): void {
+  const productManifestText = serialized.files.get(MANIFEST_FILE);
+  if (productManifestText === undefined) {
+    throw new StoryBuildError(
+      `编译产物缺 ${MANIFEST_FILE}（serializeProject 契约破坏）`,
+    );
+  }
+  // assembleProject 的 files = 故事文件集（不含清单）；清单单独走 manifest 参数
+  const columnFiles = new Map(serialized.files);
+  columnFiles.delete(MANIFEST_FILE);
+  const rebuilt = assembleProject(JSON.parse(productManifestText), columnFiles);
+  const recheck = serializeProject(rebuilt, JSON.parse(productManifestText));
+  for (const key of serialized.files.keys()) {
+    if (recheck.files.get(key) !== serialized.files.get(key)) {
+      throw new StoryBuildError(
+        `编译往返自检失败（serialize → assemble → serialize 不幂等）：${key}`,
+      );
+    }
+  }
+}

package/src/emit/emit.ts

@@ -0,0 +1,147 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { STORIES_DIR, type SerializedProject } from "@lingfan-engine/core";
+import { renderFunRegister, type CellScan } from "../cell/index.ts";
+import { walkFiles } from "../shared/index.ts";
+
+/** 写盘所需的位置与内容（全部由编排层算好，本模块只做差量判定与落盘） */
+export interface EmitOptions {
+  readonly root: string;
+  readonly resourcesDir: string;
+  readonly storiesDir: string;
+  readonly generatedRel: string;
+  readonly serialized: SerializedProject;
+  readonly cellScan: CellScan;
+  /** 类型面生成物：逻辑相对路径 + 已渲染好的全文（内容由编排层算，本模块只差量落盘） */
+  readonly typegen: { readonly rel: string; readonly content: string };
+  /** state 类型面生成物（state.gen.d.ts）：与 typegen 同一差量规则的恒产出生成物 */
+  readonly stateGen: { readonly rel: string; readonly content: string };
+  /** script 命名空间 ambient 声明生成物（script.gen.d.ts）：同规则的恒产出生成物 */
+  readonly scriptGen: { readonly rel: string; readonly content: string };
+  /** font 字面量类型面生成物（font.gen.d.ts）：同规则的恒产出生成物（空注册表也恒产出） */
+  readonly fontGen: { readonly rel: string; readonly content: string };
+}
+
+/**
+ * 差量写盘 + 生成物更新：
+ * - `Stories/**` 由源全量管理——内容不同的产物才写（新增/更新分开计），不在产物集内的
+ *   既有列文件 = 陈旧，删除；
+ * - 生成物（`<sourcesDir>/<generatedDir>/fun_register.g.ts`、`stories.gen.d.ts`、
+ *   `state.gen.d.ts`、`script.gen.d.ts`、`font.gen.d.ts`）同规则：零守卫时若存在则删除，否则内容不同才写。它们的逻辑路径与
+ *   `Stories/**` 不同命名空间，报告里以 `Stories.src/` 开头即生成物。
+ * 返回值里的路径都是逻辑路径（相对工程根），供 CLI 直接打印。
+ */
+export function emitArtifacts(options: EmitOptions): {
+  added: string[];
+  updated: string[];
+  removed: string[];
+} {
+  const {
+    root,
+    resourcesDir,
+    storiesDir,
+    generatedRel,
+    serialized,
+    cellScan,
+    typegen,
+    stateGen,
+    scriptGen,
+    fontGen,
+  } = options;
+  const existing = walkFiles(storiesDir);
+  const added: string[] = [];
+  const updated: string[] = [];
+  const removed: string[] = [];
+  for (const [rel, text] of serialized.files) {
+    const target = join(resourcesDir, rel);
+    const exists = existsSync(target);
+    if (exists && readFileSync(target, "utf8") === text) continue;
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, text);
+    (exists ? updated : added).push(rel);
+  }
+  for (const rel of existing.keys()) {
+    const logical = `${STORIES_DIR}/${rel}`;
+    if (serialized.files.has(logical)) continue;
+    rmSync(join(storiesDir, rel), { force: true });
+    removed.push(logical);
+  }
+
+  const genTarget = join(root, generatedRel);
+  if (cellScan.guards.length === 0) {
+    if (existsSync(genTarget)) {
+      rmSync(genTarget, { force: true });
+      removed.push(generatedRel);
+    }
+  } else {
+    const content = renderFunRegister(cellScan);
+    if (existsSync(genTarget)) {
+      if (readFileSync(genTarget, "utf8") !== content) {
+        writeFileSync(genTarget, content);
+        updated.push(generatedRel);
+      }
+    } else {
+      mkdirSync(dirname(genTarget), { recursive: true });
+      writeFileSync(genTarget, content);
+      added.push(generatedRel);
+    }
+  }
+  // 类型面生成物（stories.gen.d.ts / state.gen.d.ts / script.gen.d.ts / font.gen.d.ts）：恒产出的差量落盘。语义与守卫注册表
+  // 相反——空集合也写文件、结构在（注册表退化为 string / 状态面退化为 Record<string, never> / script 声明恒定 /
+  // font 面退化为 Record<never, never>），不拿空集合把作者的正常写法判红（见 typegen/render.ts 与 typegen/state-render.ts）。
+  writeConstantArtifact(
+    join(root, typegen.rel),
+    typegen.rel,
+    typegen.content,
+    added,
+    updated,
+  );
+  writeConstantArtifact(
+    join(root, stateGen.rel),
+    stateGen.rel,
+    stateGen.content,
+    added,
+    updated,
+  );
+  writeConstantArtifact(
+    join(root, scriptGen.rel),
+    scriptGen.rel,
+    scriptGen.content,
+    added,
+    updated,
+  );
+  writeConstantArtifact(
+    join(root, fontGen.rel),
+    fontGen.rel,
+    fontGen.content,
+    added,
+    updated,
+  );
+  return { added, updated, removed };
+}
+
+/** 恒产出生成物的差量落盘：存在即内容比较，不同才写（新增/更新分开计）。 */
+function writeConstantArtifact(
+  target: string,
+  rel: string,
+  content: string,
+  added: string[],
+  updated: string[],
+): void {
+  if (existsSync(target)) {
+    if (readFileSync(target, "utf8") !== content) {
+      writeFileSync(target, content);
+      updated.push(rel);
+    }
+    return;
+  }
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+  added.push(rel);
+}

package/src/emit/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 写盘域：编译产物落盘、结果报告、以及编译前后的往返比对。
+ *
+ * 三者共用同一个关注点——「源编译成引擎能读的东西」——往返比对是落盘前
+ * 的最后一道闸，报告是落盘的结果描述，故同域。
+ */
+export { emitArtifacts, type EmitOptions } from "./emit.ts";
+export { drainBuildWarnings, type BuildReport } from "./report.ts";
+export { assertRoundTrip, compileStory } from "./compile-roundtrip.ts";

package/src/emit/report.ts

@@ -0,0 +1,29 @@
+import { script, type ExpressionWarning } from "@lingfan-engine/editor";
+
+/** 一次构建的结果（CLI 据此打印，测试据此断言） */
+export interface BuildReport {
+  /** 入口故事源（相对 `Stories.src/`，= config.start 命中的文件） */
+  source: string;
+  storyId: string;
+  columns: number;
+  /** 本次新写入的产物（逻辑路径，相对资源根；首次出现的文件） */
+  added: string[];
+  /** 本次更新内容的产物（逻辑路径；已存在但内容变化，含生成物） */
+  updated: string[];
+  /** 本次清理的陈旧项（逻辑路径；`Stories.src/...` 是生成物命名空间） */
+  removed: string[];
+  /** 本轮按清单声明装载的扩展说明符（声明缺席/为空 = 空数组，装载器一次不触） */
+  extensions: string[];
+  /** cell(...) 声明并生成进注册物的守卫名（书写序；缺席 = 空数组） */
+  functions: string[];
+  /** 词汇层轻类型校验警告（expr/cond 组装时按引擎类型规则产出；不拦构建——引擎/编辑期仍是权威） */
+  warnings: ExpressionWarning[];
+}
+
+/**
+ * 取走并清空词汇层类型警告。
+ * 源模块导入即完成全部表达式组装，故整次构建只在收尾调一次——不拦构建，只进报告由 CLI 呈现。
+ */
+export function drainBuildWarnings(): ExpressionWarning[] {
+  return [...script.drainExpressionWarnings()];
+}

package/src/fonts/font-registry.ts

@@ -0,0 +1,53 @@
+/**
+ * 字体名注册表：扫描 Resources/Fonts 下的字体文件，以「文件名去扩展名」为合法字体名。
+ *
+ * 字体名只在 stories-build 构建链内流转（构建期检查 + 宿主 @font-face 注入），不含运行时状态，
+ * 因此引擎侧不设端口。目录缺失 = 空注册表（未引用字体名的工程零打扰；引用了即 fail-closed）。
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { compareOrdinal } from "@lingfan-engine/core";
+
+/** 字体根目录名（位于 Resources/ 之下） */
+export const FONTS_DIR_NAME = "Fonts";
+
+/** 参与注册表的字体扩展名（小写比较）；注册表只发文件名，宿主按扩展名选 format() */
+export const FONT_EXTENSIONS = [".ttf", ".otf", ".woff", ".woff2"] as const;
+
+export interface FontEntry {
+  /** 文件名（含扩展名），供宿主拼 URL */
+  readonly file: string;
+  /** 字体名 = 文件名去扩展名，故事层只引用这个名字 */
+  readonly name: string;
+}
+
+/**
+ * 扫描字体根目录产注册表；目录不存在或为空 = 空数组（合法，等价「未声明任何字体」）。
+ * 文件名按码元序稳定排序，保证注册表（与后续产物）不受文件系统枚举顺序影响。
+ */
+export function scanFontRegistry(fontsDir: string): readonly FontEntry[] {
+  if (!existsSync(fontsDir)) {
+    return [];
+  }
+  const entries: FontEntry[] = [];
+  for (const file of readdirSync(fontsDir)) {
+    const dot = file.lastIndexOf(".");
+    // 点文件（.DS_Store、.hidden.ttf）整族跳过：后者虽有扩展名，但「.hidden」不是作者意图内的字体名
+    if (dot <= 0 || file.startsWith(".")) {
+      continue;
+    }
+    const ext = file.slice(dot).toLowerCase();
+    if (!(FONT_EXTENSIONS as readonly string[]).includes(ext)) {
+      continue;
+    }
+    entries.push({ file, name: file.slice(0, dot) });
+  }
+  entries.sort((a, b) => compareOrdinal(a.file, b.file));
+  return entries;
+}
+
+/** 字体名集合视图（供编译器 fail-closed 检查使用） */
+export function fontNameSet(
+  entries: readonly FontEntry[],
+): ReadonlySet<string> {
+  return new Set(entries.map((entry) => entry.name));
+}

package/src/fonts/index.ts

@@ -0,0 +1,7 @@
+export {
+  FONTS_DIR_NAME,
+  FONT_EXTENSIONS,
+  fontNameSet,
+  scanFontRegistry,
+} from "./font-registry.ts";
+export type { FontEntry } from "./font-registry.ts";

package/src/index.ts

@@ -0,0 +1,76 @@
+/**
+ * TS 故事源编译流水线出口（唯一出口）：把 `Stories.src/` 多目录原生 TS 语句源编译成
+ * `Resources/Stories/**` + `project.json`，并维护 cell 生成物。
+ *
+ * 布局声明 `Stories.src/config.ts`（根级唯一根文件，named exports 单次求值）：
+ * `folders` 声明源目录（可含 `"*"` 通配全部目录）、`start` 声明入口故事文件名（跨目录全局
+ * 恰一）；`vars`（键集对象）登记插值变量键、`state`（形态 A）/`define(...)`（形态 B）
+ * 声明 state 初始值，两者可缺省但互斥。
+ * 源发现按「default 导出存在」区分故事/模块文件；产物路径 = 源文件路径
+ * （`Stories/<相对源路径>.json`，文件名与列 id 解耦）。`config.start` 经托管键
+ * 更新落到 `project.json` 的 `entry`（`serializeProject` 既有语义）。
+ *
+ * 零第二套规则：TS 源合法 ⇔ 其编译产物作为 JSON 合法（与 JSON 同一 `parseStory`）。
+ * 工程清单（entry/defines/shell）不归 TS 源管——必须先有 `Resources/project.json`，
+ * 编译只更新其托管键。`Stories/**` 列集由源全量管理：启用 TS 源的工程，手写列文件
+ * 会被当作陈旧产物清理（报告逐条列出）。构建在清单写入非托管标记键 `tsSource`，
+ * 编辑器据此对 TS 源工程的 JSON 产物只读（`packages/editor` 的 `tsSourceGuard`）。
+ *
+ * 编译器对接：`compileStories` 契约（`./compiler`）——默认装载其中的
+ * `story-compiler.ts`，`StoryBuildOptions.compiler` 可注入（过渡期/测试）。
+ *
+ * 扩展 op 放行（对齐运行期声明制）：清单 `extensions` 声明扩展模块说明符——编译期
+ * 用与运行期同一个装载契约（`loadDeclaredExtensions`）装载，收集其提供的 op 名；
+ * 故事里既非内建、也未被声明扩展提供的 op 名 = 运行期必 unknown-op ⇒ 构建期即拦截
+ * （fail-early，带列与命令指针定位，一次报全部）。声明缺席/为空 = 零装载零副作用。
+ *
+ * 测试直接调 `buildStories`（纯编排，fs 全在参数 root 之下）；CLI 主守卫在
+ * `cli` 域——那里依赖被直接执行这一事实，不属于本流水线的出口面，故不在下面导出
+ * （它以包说明符 `@lingfan-engine/stories-build/cli` 暴露给宿主）。
+ */
+
+/** 构建失败（fail-closed）。消息即 CLI 打印的失败原因，逐字稳定——不要在别处重写措辞 */
+export { StoryBuildError } from "./shared/index.ts";
+/** 集中文案表（StoryBuildOptions.texts / compileStories input.texts 的注入类型与缺省值） */
+export {
+  defaultStoriesBuildTexts,
+  type StoriesBuildTexts,
+} from "./shared/index.ts";
+/** 一次构建的结果与词汇层警告的取口 */
+export { drainBuildWarnings, type BuildReport } from "./emit/index.ts";
+/** 目录布局的默认值与可配置项 */
+export {
+  DEFAULT_GENERATED_DIR,
+  DEFAULT_RESOURCES_DIR,
+  DEFAULT_SOURCES_DIR,
+  type StoryBuildOptions,
+} from "./pipeline/index.ts";
+/** 十二段串行编排（流水线主入口） */
+export { buildStories } from "./pipeline/index.ts";
+/** 编译期求值域（config.ts 单次求值 + define 内建 + 形态 A/B 状态降维） */
+export {
+  evalConfigModule,
+  type ConfigEvalOutcome,
+} from "./const-eval/index.ts";
+/** 布局声明与 config.ts 契约类型 */
+export { CONFIG_FILE, type StorySourceConfig } from "./config/index.ts";
+/** 创作垫片类型（@lingfan-engine/stories-build/authoring 随包 .d.ts 的主出口同源） */
+export type { InferStateSchema } from "./config/state-type.ts";
+/** 源发现 v2（folders 多目录 + start 全局恰一） */
+export { discoverSources, type DiscoveredSources } from "./discovery/index.ts";
+/** 编译器契约（story-compiler 对接面） */
+export {
+  loadDefaultCompiler,
+  type CompiledStories,
+  type CompiledStoryEntry,
+  type CompilerDiagnostic,
+  type StoriesCompiler,
+} from "./compiler/index.ts";
+/** 字体名注册表（Resources/Fonts 扫描；宿主 Vite 插件与构建期检查同源消费） */
+export {
+  FONTS_DIR_NAME,
+  FONT_EXTENSIONS,
+  fontNameSet,
+  scanFontRegistry,
+  type FontEntry,
+} from "./fonts/index.ts";

package/src/pipeline/gates.ts

@@ -0,0 +1,107 @@
+import {
+  BUILTIN_OP_NAMES,
+  MANIFEST_FILE,
+  type Story,
+} from "@lingfan-engine/core";
+import { walkStoryCommands } from "@lingfan-engine/editor";
+import {
+  defaultStoriesBuildTexts,
+  StoryBuildError,
+  type StoriesBuildTexts,
+} from "../shared/index.ts";
+
+/** 闸门判定的可配置项：文案里出现的目录名（缺省 = 现状；只影响文案，不影响判定） */
+export interface GateOptions {
+  readonly resourcesDir: string;
+  readonly sourcesDir: string;
+  /** 文案注入（Partial）；缺省 = 内建缺省文案（即构建层的既有文案） */
+  readonly texts?: Partial<StoriesBuildTexts>;
+}
+
+/** 指针 → 「列 "id" /columns/N/...」：指针里的列下标映射回列 id，越界则原样返回 */
+function columnLabeler(story: Story): (pointer: string) => string {
+  const columnIds = story.columns.map((column) => column.id);
+  return (pointer: string): string => {
+    const index = Number(/^\/columns\/(\d+)/.exec(pointer)?.[1] ?? NaN);
+    const id = columnIds[index];
+    return id === undefined ? pointer : `列 "${id}" ${pointer}`;
+  };
+}
+
+/**
+ * 扩展 op 闸门（fail-early）：运行期 `unknown-op` 的构建期等价判定。
+ * 内建与已声明扩展之外出现的 op 名 = 运行期必 unknown-op ⇒ 构建期即拦截
+ * （遍历含嵌套块体——`if.then`/`while.body`/`func.body` 内的命令同样在列；一次报全部，
+ * 同一 op 超过 3 处折叠为「（共 N 处）」）。
+ */
+export function assertKnownOps(
+  story: Story,
+  extensionOpNames: ReadonlySet<string>,
+  options: GateOptions,
+): void {
+  const unknownOps = new Map<string, string[]>();
+  walkStoryCommands(story, (cmd, pointer) => {
+    const op = cmd.op;
+    if (
+      typeof op !== "string" ||
+      BUILTIN_OP_NAMES.has(op) ||
+      extensionOpNames.has(op)
+    ) {
+      return;
+    }
+    const hits = unknownOps.get(op) ?? [];
+    hits.push(pointer);
+    unknownOps.set(op, hits);
+  });
+  if (unknownOps.size === 0) return;
+  const texts: StoriesBuildTexts = {
+    ...defaultStoriesBuildTexts,
+    ...options.texts,
+  };
+  const at = columnLabeler(story);
+  const detail = [...unknownOps.entries()]
+    .map(([op, pointers]) => {
+      const shown = pointers.slice(0, 3).map(at).join("、");
+      const more = pointers.length > 3 ? `（共 ${pointers.length} 处）` : "";
+      return `  - op "${op}" —— ${shown}${more}`;
+    })
+    .join("\n");
+  throw new StoryBuildError(
+    texts.unknownOpsGate(detail, options.resourcesDir, MANIFEST_FILE),
+  );
+}
+
+/**
+ * 守卫名闸门（cell 范式的闭合校验）：故事 `guard.fn` 必须都在 cell 注册表键集内。
+ * fail-closed 带命令指针定位（编辑器不校验守卫名——构建期兜住）。
+ */
+export function assertKnownGuards(
+  story: Story,
+  guardNames: ReadonlySet<string>,
+  options: GateOptions,
+): void {
+  const unknownGuards = new Map<string, string[]>();
+  walkStoryCommands(story, (cmd, pointer) => {
+    if (cmd.op !== "guard") return;
+    const fn = cmd.fn;
+    if (typeof fn !== "string" || guardNames.has(fn)) return;
+    const hits = unknownGuards.get(fn) ?? [];
+    hits.push(pointer);
+    unknownGuards.set(fn, hits);
+  });
+  if (unknownGuards.size === 0) return;
+  const texts: StoriesBuildTexts = {
+    ...defaultStoriesBuildTexts,
+    ...options.texts,
+  };
+  const detail = [...unknownGuards.entries()]
+    .map(([fn, pointers]) => `  - guard "${fn}" —— ${pointers.join("、")}`)
+    .join("\n");
+  throw new StoryBuildError(
+    texts.unknownGuardsGate(
+      detail,
+      options.sourcesDir,
+      [...unknownGuards.keys()][0],
+    ),
+  );
+}