@faicad/faijs 0.13.0

package/dist/cad-runtime/runtime.d.ts

@@ -0,0 +1,575 @@
+/**
+ * CadRuntime — 执行核心（L2 编排层）
+ *
+ * Direct-only execution: the runtime runs only the direct path
+ * (extractMetadata → DirectExecutor → computeLiveShapes).
+ *
+ * 职责：
+ * - 执行 .fai.js 源码文本，产出 ExecutionResult（纯计算，不碰 store/DOM）
+ * - 管理 statementCache 作为实例成员
+ * - 执行模式感知（auto / brep / mesh）
+ *
+ * 不做的事（留给 browser host）：
+ * - undo 快照
+ * - SceneMutator.createPart / commitGeometry
+ * - scriptStore 写入
+ * - group/assembly 重建
+ * - window.dispatchEvent / toast
+ */
+import type { TerminalShape } from '../lang/types.js';
+import type { Shape } from '../mesh/types.js';
+import type { BrepChainState } from '../brep/brep-chain.js';
+import type { BrepHandle } from '../brep/engine/types.js';
+import type { BrepEngineApi } from '../brep/engine/primitives.js';
+import type { SecurityPolicy } from '../lang/security-scanner.js';
+import type { HostPorts, ExecutionMode } from './ports.js';
+import type { SelectorRuntimeData } from '../topology/build-selector-runtime.js';
+import type { SelectorRuntime } from '../topology/types.js';
+import { type PartName } from '../identity.js';
+import type { ExecBackendChoice } from './exec-backend.js';
+import { type StdlibNamespace, type AssemblyKinematicsPose } from '../runtime-state.js';
+export { computeContentKey } from './content-key.js';
+export { stableFingerprint } from './content-key.js';
+import { type CompoundShape } from '../shape.js';
+import type { PartNaming } from '../topology/naming/types.js';
+/**
+ * A single validation error produced by CadRuntime.check.
+ */
+export interface CheckError {
+    /** The stage that produced the error ('keep' = keep directive validation). */
+    stage: 'parse' | 'symbol' | 'reference' | 'keep' | 'security';
+    message: string;
+    line?: number;
+    stmtId?: string;
+    /** Parse diagnostic code (e.g. E_CONTROL_FLOW, passed through from parser ParseError.code). */
+    code?: string;
+    /** SecurityScanner rule ID (only when stage='security'; e.g. SEC_IDENT / SEC_SYNTAX / ...). */
+    ruleId?: string;
+}
+/**
+ * The aggregated result of a CadRuntime.check dry run.
+ */
+export interface CheckResult {
+    ok: boolean;
+    errors: CheckError[];
+    warnings: string[];
+    /** Structured context for AI self-correction. */
+    script?: {
+        statements: number;
+        callees: string[];
+    };
+}
+/**
+ * 拓扑来源类型 — 静态判定，不混用。
+ * - `brep`：BREP 真拓扑（stepRuntimes），由 OCCT solid 构建
+ * - `primitive`：primitive 假拓扑（primitiveRuntimes），创建时刻快照
+ * - `mesh`：mesh 假拓扑（meshRuntimes），加载时刻快照
+ */
+export type TopologySource = 'brep' | 'primitive' | 'mesh';
+/**
+ * 单个 part 的拓扑数据 — 由 ExecutionResult 携带，宿主从结果消费。
+ *
+ * 宿主不应再直接 import faijs 的拓扑构建函数（buildSelectorRuntime 等），
+ * 而是从 ExecutionResult.topology 中读取。
+ */
+export interface PartTopology {
+    /** partName 即 faijs 变量名（PartName，品牌型） */
+    partName: PartName;
+    /** 拓扑来源（静态判定） */
+    source: TopologySource;
+    /** 序列化的拓扑数据（可跨 Worker 传输） */
+    data: SelectorRuntimeData;
+}
+/**
+ * The result of a CadRuntime execution, carrying geometry, chain state, and
+ * host-consumable topology data.
+ */
+export interface ExecutionResult {
+    /**
+     * Statement output cache (PartName → Shape or compound; includes the dual
+     * front/back outputs of a split). UI query entry point listing every shape
+     * variable — unregistered compounds returned by third parties (structural
+     * test isCompoundLike) enter as well.
+     */
+    outputs: Map<PartName, Shape | CompoundShape>;
+    /** BREP 链状态（含逐 part solid 句柄） */
+    brepChain: BrepChainState;
+    /** 终端几何列表 */
+    terminals: TerminalShape[];
+    /** 信息/警告列表 */
+    infos: string[];
+    /** 失败信息（如果执行中途出错）；lineNo 为 DirectExecutor 路径新增（§4.2 E-add，宿主按现状读前三个字段不破裂）；code 为原始错误码（如有，如 E_TOPO_NOT_FOUND / E_ARGS_FORM） */
+    failedAt?: {
+        index: number;
+        callee: string;
+        message: string;
+        lineNo?: number;
+        code?: string;
+    };
+    /** 逐终端的 BREP 实体（仅持有 solid 的终端出现在此表）。key 为终端 PartName。 */
+    brepSolids?: Map<PartName, {
+        solid: BrepHandle;
+        kernel: BrepEngineApi;
+    }>;
+    /**
+     * 拓扑数据 — 每个 part 的拓扑运行时。
+     * key 为 PartName。
+     * E13：由 ExecutionResult 携带，宿主从结果消费。
+     * 拓扑来源静态判定：BREP 成功时 source='brep'，否则根据 part 类型判定。
+     */
+    topology?: Map<PartName, PartTopology>;
+    /**
+     * 拓扑命名数据 — 每个 part 的命名行（§3.7 of
+     *
+     * 宿主拾取到 Reference（序号）后 O(1) 反查命名行 → captureTopoRef 造 TopoRef。
+     * BREP/primitive 完整（faceNaming 有 origin+role），mesh 只给 hint（role=''）。
+     * 与 topology 并列、选择器 manifest 不改动；命名数据不进 topology-store。
+     */
+    naming?: Map<PartName, PartNaming>;
+    /**
+     * 装配/分组结构 — 每个 compound 变量（group/assembly 产物）的成员变量名列表。
+     * key 为 compound 变量名（PartName），value 为成员变量名列表。
+     */
+    compounds?: Map<PartName, PartName[]>;
+    /** 被 touch 声明的原地修改 Shape 的持有变量名（装配变换后 collectResult 填充，去重） */
+    changed?: PartName[];
+    /**
+     * 活跃但非几何的值（keep-syntax 设计 §5.2，UI 可选消费）。
+     * DAG 叶子且非 shape/compound：第三方测量/查询函数返回的 number/普通对象等。
+     * 不进 terminals（terminals 只含几何，零回归）。
+     */
+    activeValues?: Map<PartName, unknown>;
+    /**
+     * P3：装配运动副 per-member 位姿（键 = 成员名；含恒等链根），仅在含 joints 的
+     * assembly solve 语句执行后出现。宿主从本字段读取（动画/导出），不新增返回值
+     * 消费语义（asm.solve() 保持 R0 语句形态，与 do_assemble 现状一致）。
+     */
+    kinematics?: Map<PartName, AssemblyKinematicsPose>;
+}
+/**
+ * Options controlling a single CadRuntime execution. All inputs are code text
+ * or plain values — the engine's internal IR is never part of this surface.
+ */
+export interface ExecuteOptions {
+    /** The parameter table. */
+    params?: Record<string, unknown>;
+    /** partTransform（世界→局部坐标偏移 + 单位缩放） */
+    partTransform?: {
+        position: [number, number, number];
+        scale?: [number, number, number];
+    };
+    /** 语句前钩子（用于 undo 逐语句快照）；参数为语句 id（sN）与语句下标 */
+    beforeStatement?: (stmtId: string, index: number) => void;
+    /**
+     * 增量执行起点（兼容旧签名）：从指定位置开始顺序执行，
+     * 之前的语句不进执行循环（缺省 0 = 全量执行）。
+     */
+    startIndex?: number;
+    /**
+     * 拓扑构建开关（Phase 2.6）：
+     * - 'auto'（默认）：为"在 BREP 链上"的终端自动构建 BREP 真拓扑
+     * - 'brep'：为所有在 BREP 链上的输出构建拓扑（含非终端）
+     * - 'off'：不自动构建（只返回宿主 setTopology 注入的拓扑）
+     */
+    topology?: 'auto' | 'brep' | 'off';
+    /**
+     * 主模块 key（相对项目根的路径，如 `src/assembly.fai.js`；多文件 §4.5）。
+     * 宿主执行某个文件时传入——主模块的相对 import 以此为解析基准；不传则视为
+     * 位于项目根（存量单文件行为不变：无 key 时 `./x.fai.js` 相对根解析）。
+     */
+    entryKey?: string;
+    /**
+     * 执行护栏（§6.3 / D8，v1 可选、默认关闭）：**整轮超时**（覆盖 execute/append/update
+     * 全程，含全部函数体重放），超时抛 {@link ExecutionLimitError}（E_EXEC_LIMIT）。
+     * 防 `while(true)` 死循环挂死 worker/UI；不传则无超时（现状行为不变）。
+     */
+    executionTimeoutMs?: number;
+}
+export { ExecutionLimitError } from './execution-limit-error.js';
+/**
+ * Thrown by CadRuntime.append when a newly appended statement references a
+ * variable that is not in the persistent context — its producer was never
+ * executed (cross-file reference to an unloaded part, or ctx cleared by
+ * dispose). The host should upgrade to a full `execute(code)`.
+ */
+export declare class AppendPrefixError extends Error {
+    /** The source statement id (sN) whose reference is missing. */
+    readonly statementId: string;
+    /** The referenced variable missing from the persistent ctx. */
+    readonly missingVar: string;
+    constructor(
+    /** The source statement id (sN) whose reference is missing. */
+    statementId: string, 
+    /** The referenced variable missing from the persistent ctx. */
+    missingVar: string);
+}
+/**
+ * CadRuntime 构造选项（第 4 参；缺省全部可选）。
+ *
+ * direct 是唯一执行路径。security 透传给 DirectExecutor 与 extractMetadata
+ * （A1/A2/A3 缺省 'strict'）。
+ */
+export interface CadRuntimeOptions {
+    /** 安全策略档位（缺省 'strict'；透传给 DirectExecutor 与 extractMetadata） */
+    security?: SecurityPolicy;
+    /**
+     * 执行后端（缺省 'vm'；静态选定，无运行时回退）。'interpreter' 为无
+     * `new Function`/eval 的 AST 解释器后端，供禁 eval 环境（weapp / 严格 CSP）
+     * 使用——见 docs/plans/2026-09-14-no-eval-interpreter-backend-design.md。
+     */
+    execBackend?: ExecBackendChoice;
+}
+/**
+ * CadRuntime is the execution core of the L2 orchestration layer.
+ *
+ * It executes a .fai.js source text and produces an ExecutionResult
+ * (pure computation that touches neither the scene store nor the DOM), manages
+ * the statementCache as an instance member, resolves shape references
+ * internally, and is execution-mode aware (auto/brep/mesh). Hosts own undoing,
+ * scene mutation, script-store writes, group/assembly rebuilding, and event
+ * dispatch.
+ */
+export declare class CadRuntime {
+    /** The host-injected environment capabilities. */
+    readonly ports: HostPorts;
+    /** The execution mode (auto/brep/mesh). */
+    readonly mode: ExecutionMode;
+    /** direct 是唯一执行路径。保留属性以兼容外部读取。 */
+    readonly executorMode: "direct";
+    /** 语句缓存（实例级，不再是模块单例）。key = 可命中的 PartName（stmt.id 即其首输出名） */
+    private statementCache;
+    /** 场景代码累积（三接口收敛：append 只传新行，faijs 累积全文使 id 按位置稳定 + DAG/keep 分析可见全场景）。 */
+    private accumulatedCode;
+    /** 已累积场景的语句 id 集（append 据此判定「新增语句」）。 */
+    private accumulatedIds;
+    private lastParamsFingerprint;
+    private lastLibIdsFingerprint;
+    private lastPartTransformFingerprint;
+    private lastHadKinematics;
+    /**
+     * PartName → OCCT 实体句柄，跨 execute 存活，持有所有权（顶替释放/删除/dispose 的唯一操作对象）。
+     * op 层通过 brepChain.solidCache 读写——该引用指向此持久 Map（见 ensureBrepChain）。
+     */
+    private solidCache;
+    /** 面演化映射缓存（PartName → FaceEvolution），随 solidCache 一并持久。 */
+    private faceEvolutionCache;
+    /** 拓扑命名 RoleTable 缓存（PartName → RoleTable，§2.3），与 faceEvolutionCache 同生命周期。 */
+    private roleTableCache;
+    /** OCCT 内核引用（环境级单例，initOcctWasm() 幂等；mesh 模式为 null）。供顶替释放用。 */
+    private kernel;
+    /**
+     * 惰性初始化的 BREP 链：solidCache / faceEvolutionCache 引用实例持久 Map，
+     * kernel 取环境单例。首次需要时创建一次，跨 execute 复用（不再每次新建）。
+     */
+    private brepChain;
+    /**
+     * 拓扑数据缓存：partName → PartTopology（实例级）
+     * E13：宿主不再直接 import faijs 拓扑构建函数，而是从 ExecutionResult.topology 消费。
+     * 拓扑构建由宿主在 execute 后调用 setTopology 注入（BREP 路径）或由加载时注入（mesh/primitive 路径）。
+     */
+    private topologyCache;
+    /** 无 IR 执行器（DirectExecutor，T5 后唯一执行路径） */
+    private readonly directExecutor;
+    /** 安全策略档位（透传给 extractMetadata 与 DirectExecutor；缺省 'strict'） */
+    private readonly securityPolicy;
+    /** 宿主注册库（含 cad：由根门面 createRuntime 包装注入；注入编译产物 fn 的第二参 ns） */
+    private readonly libs;
+    /** 库内容身份表 (binding → content hash)，增量 key 用（B2，§7.3） */
+    private readonly libIds;
+    /** import specifier → binding 映射（registerLib 的 packageName 声明；check ①.5 校验 specifier） */
+    private readonly specifierToBinding;
+    private readonly namespaces;
+    /** 默认命名空间绑定名（U10/R2）：根门面经 registerLib(binding, ns, {default: true}) 显式声明；
+     *  缺省 'cad'（与 parser 缺省 defaultNs 一致）。namespace 字段缺省的语句归属该绑定。 */
+    private defaultNsName;
+    /**
+     * Register a library namespace. A version mismatch throws (no silent
+     * degradation); afterwards compiled products may use the library via
+     * `ns.<binding>.<callee>`. `cad` is registered the same way: the root facade
+     * injects it through registerLib('cad', createInternalStdlib(), { default: true }).
+     * @param binding - the namespace binding name.
+     * @param ns - the namespace object to register.
+     * @param options - `{ default: true }` declares this binding as the default
+     *   namespace (host-declared default binding name, U10/R2).
+     */
+    /**
+     * Register a library namespace under a statement-level binding.
+     *
+     * Third-party libraries (no defineOp / no contractVersion) are admitted
+     * through compatOp so bare functions cannot silently bypass the statement
+     * boundary contract (B4, §4.3.3). The `autoLift` option controls this:
+     *   - `true`  → bare functions are lifted via compatOp (brep-only, B4).
+     *   - `false` → no lifting (the library's functions are used as-is; the
+     *     built-in cad surface uses this since its ops already carry
+     *     `DUAL_OP_META`).
+     *   - omitted → inferred: `!hasDualOp(ns)`. Libraries that already declare
+     *     dual-ops (cad, gear-lib-demo's defineOp mocks) auto-lift `false`;
+     *     all-bare-function libraries (sheetmetal) auto-lift `true`.
+     *
+     * The engine's built-in L3 surface is registered without `autoLift` by the
+     * facade: inferred `false` (all ops carry `DUAL_OP_META`).
+     * @param binding - the name scripts use to reach the namespace (e.g. 'cad').
+     * @param ns - the library's export object.
+     * @param options - registration hints. `packageName` declares the npm package
+     *   backing this binding so `check()` can validate script import specifiers
+     *   against registered libraries (specifier mismatch = hard check error).
+     */
+    registerLib(binding: string, ns: StdlibNamespace, options?: {
+        default?: boolean;
+        autoLift?: boolean;
+        packageName?: string;
+    }): void;
+    /** The runtime's default namespace binding name (host-declared; 'cad' by default). */
+    get defaultNs(): string;
+    constructor(ports: HostPorts, mode?: ExecutionMode, libs?: Record<string, StdlibNamespace>, options?: CadRuntimeOptions);
+    /**
+     * 认领全局 backends 配置（P2 修复）：全局 backends 是单例，任何 runtime 创建都会
+     * 覆盖它——后创建的实例（如预览用 mesh runtime）会把 mode/kernel getter 指向自己，
+     * 先前 runtime 的后续 execute 会被静默劫持（dispatch 走错槽、缓存键漂移、
+     * 顶替释放旧 BREP 句柄后拓扑重建撞上悬空句柄）。因此除构造外，每个执行入口
+     * （execute，所有执行路径的汇聚点）都必须先重新认领本实例的配置。
+     * 限制：并发交错执行多个 runtime 仍会互踩（与 setCurrentStmt 同级的串行假设）。
+     * ⚠️ getter 的 this 指向所在对象字面量，用箭头闭包捕获实例（避免 no-this-alias）。
+     */
+    private claimBackends;
+    /**
+     * 确保持久 BREP 链存在（惰性初始化）。
+     * 引擎从注册表取当前 BREP 引擎（宿主装配时注册）；无引擎或 mesh 模式 → kernel 为 null。
+     * OCCT 是内置默认引擎：宿主未注册任何引擎时，非 mesh 模式自动装配 OCCT——
+     * 现有宿主无需改动即恢复默认 BREP 行为；换引擎仍是静态的（装配期注册其它引擎即可）。
+     */
+    private ensureBrepChain;
+    /**
+     * Full execution from code text: parse → execute every statement.
+     * @param code - the .fai.js source text.
+     * @param opts - optional execution options.
+     * @returns promise resolving to the ExecutionResult.
+     */
+    execute(code: string, opts?: ExecuteOptions): Promise<ExecutionResult>;
+    /**
+     * Append new statements (incremental execution): only execute the new code
+     * text on the persistent ctx; prefix validation enforces that references
+     * must already exist (AppendPrefixError otherwise).
+     * @param code - the new .fai.js source text to append.
+     * @param opts - optional execution options.
+     * @returns promise resolving to the ExecutionResult.
+     */
+    append(code: string, opts?: ExecuteOptions): Promise<ExecutionResult>;
+    /**
+     * Direct-mode full execution: the code text runs on the DirectExecutor
+     * and outputs/terminals are assembled from the persistent ctx +
+     * extractMetadata + computeLiveShapes.
+     */
+    private executeDirectText;
+    /** E6：DirectExecutor 失败行 → 场景语句序数（meta.lines 下标）；不在 lines → undefined。 */
+    private directStmtOrdinal;
+    /**
+     * Direct-mode failedAt handling (T5 direct-only path): all execution errors
+     * from DirectExecutor's catch block are statement-level failures → keep in
+     * failedAt (no re-throw). This includes OpError / BrepUnsupportedError /
+     * MeshUnsupportedError (engine capability failures), TypeError (no_such_op),
+     * and business parameter errors (e.g. E_ARGS_FORM, E_CHAMFER_NO_EDGES,
+     * E_TOPO_NOT_FOUND). ParseError is re-thrown by DirectExecutor (not here).
+     * The original error's `code` (e.g. E_TOPO_NOT_FOUND) is surfaced on
+     * failedAt.code so hosts can programmatically distinguish error kinds.
+     */
+    private directFailedAtOrThrow;
+    /**
+     * Direct-mode update: R3 语义——清 ctx 全量重跑新文本
+     * （DirectExecutor.update 即 execute；无需 oldCode 差量）。
+     */
+    private updateDirectText;
+    /**
+     * Direct-mode append: DirectExecutor 共享 ctx 只执行新单元
+     * （行号即边界）；prefix 校验保留 AppendPrefixError 语义（引用不在持久 ctx → 抛错，
+     * 宿主升级为全量 execute）。
+     */
+    private appendDirectText;
+    /** Direct-mode 失败结果的 outputs 部分：持久 ctx 中已产出的 shape/compound。 */
+    private directShapes;
+    /**
+     * 多文件装载（direct 模式，§4.5）：项目内相对 import 依赖经 ModuleRegistry 装载
+     * （每依赖独立 ctx 执行 + 绑定校验），返回 seed（绑定名 → 值，供 DirectExecutor
+     * opts.imports 预置）。装载错误 → failedAt 短路结果（不抛穿）。
+     */
+    private loadDirectModuleImports;
+    /** 依赖模块执行（direct）：独立 DirectExecutor + 独立 ctx；失败抛 ModuleRegistryError。 */
+    private runDirectModule;
+    /**
+     * Direct-mode result assembly：ctx → outputs / statementCache / terminals /
+     * brepSolids / compounds（与 collectResult 的 mesh 面同构；输入换源为
+     * DirectExecutor ctx + UiMetadata + computeLiveShapes，§4.2/§4.4）。
+     */
+    private collectDirectResult;
+    /** 块起始行 → lines 中第一个 >= 该行的下标（与 live-shapes.blockIdxOf 同逻辑）。 */
+    private static blockIdxOfLine;
+    /**
+     * T2：Direct-mode activeValues 收集——镜像 collectActiveValues（module 路径），
+     * 输入换 meta.lines + lineConsumes/blockConsumes。
+     *
+     * 判定与 computeLiveShapes 同构：变量 v 的最后写者行（lines 下标 + blockOutputs）
+     * 之后没有语句/块消费 v → DAG 叶子。叶子且非 shape/compound → activeValues。
+     * 几何叶子走 terminals（跳过，零回归）。
+     */
+    private collectDirectActiveValues;
+    /** Direct-mode 逐终端 BREP solid 提取（终端 + 装配成员；无 kernel → 空）。 */
+    private directBrepSolids;
+    /**
+     * P 四（4.2）：execute 阶段自动装载未注册的库。
+     *
+     * import 表（UiMetadata.imports）驱动的自动装载。
+     */
+    private autoLoadLibsFromImports;
+    /**
+     * 构建一个 part 的命名输入（§3.7）。
+     *
+     * - BREP：roleTableCache 反查 {origin, role} + subShapeHashes 序号对照 + 面/边行 hint；
+     * - primitive：assignPrimitiveFaceRoles 按固定面序给语义 role（§5.2，与 BREP 同一套命名器）；
+     * - mesh：只填 hint（role=''，§5.3）。
+     */
+    private buildNamingInput;
+    /**
+     * 从 SelectorRuntimeData 的 edgeFaceRows 提取每条边的两邻面序号（1 起；§3.7）。
+     * mesh 无邻接 → undefined（edgeNaming.faces=null，只能 hint 兜底，§5.3）。
+     */
+    private edgeFaceOrdinalsOf;
+    /**
+     * Update from the two code texts (before/after an edit): the diff is derived
+     * from the passed codes themselves — the engine's persistent ctx is only an
+     * execution cache, never the diff authority. Changed statements (paired by
+     * positional id, S-2) plus their downstream closure are recomputed in
+     * topological order; when nothing changed, the result is assembled from the
+     * persistent ctx with zero execution.
+     * @param oldCode - the .fai.js source text before the edit.
+     * @param newCode - the .fai.js source text after the edit.
+     * @param opts - optional execution options.
+     * @returns promise resolving to the ExecutionResult.
+     */
+    update(oldCode: string, newCode: string, opts?: ExecuteOptions): Promise<ExecutionResult>;
+    /**
+     * Get the output geometry from the statement cache (keyed by PartName).
+     * @param partName - the part name to look up.
+     * @returns the cached shape, or undefined.
+     */
+    getCachedOutput(partName: PartName): Shape | undefined;
+    /**
+     * Get a statement cache's full entry (statementKey / outputContentKey / output;
+     * used by tests and host diagnostics).
+     * @param partName - the part name to look up.
+     * @returns the cached entry, or undefined.
+     */
+    getStatementCacheEntry(partName: PartName): {
+        statementKey: string;
+        outputContentKey: string;
+        output: Shape;
+    } | undefined;
+    /**
+     * Write an entry into the statement cache (keyed by PartName).
+     * @param partName - the part name to store under.
+     * @param _stmt - unused (T5: direct path has no StatementIR).
+     * @param output - the shape output.
+     * @param outputContentKey - the output's content key.
+     */
+    writeToStatementCache(partName: PartName, _stmt: unknown, output: Shape, outputContentKey: string): void;
+    /** 清除语句缓存（含 statementCache + DirectExecutor ctx 变量） */
+    clearStatementCache(): void;
+    /**
+     * Write an entry into the topology data cache. Hosts call this after a
+     * successful BREP execution (building source='brep' topology via
+     * buildSolidTopologyRuntime), on file load (source='mesh' via
+     * buildSelectorRuntime), and on primitive creation (source='primitive' via the
+     * primitive topology builder). The topology returned by execute()'s
+     * ExecutionResult includes these cached entries.
+     * @param partName - the part name to store under.
+     * @param source - the topology source (brep/primitive/mesh).
+     * @param data - the serialized topology data.
+     */
+    setTopology(partName: PartName, source: TopologySource, data: SelectorRuntimeData): void;
+    /**
+     * Get the topology data for a part.
+     * @param partName - the part name to look up.
+     * @returns the part topology, or undefined.
+     */
+    getTopology(partName: PartName): PartTopology | undefined;
+    /**
+     * Delete the topology data for a part.
+     * @param partName - the part name to delete.
+     */
+    deleteTopology(partName: PartName): void;
+    /**
+     * 从 BREP solid 构建拓扑数据（接口分离 P0）。
+     *
+     * 宿主不再直接 import faijs 内部构建函数（buildSolidTopologyRuntime），
+     * 而是通过此方法从 runtime 获取 BREP 拓扑。
+     *
+     * 按 PartName 直接查持久 solidCache + brepChain.meshShapeCache（均为 PartName key），
+     * 不再需要 scopedId 投影。单一真源：solidCache（PartName → BrepHandle）。
+     *
+     * @param partName 终端变量名（PartName，在 brepChain.solidCache 中查找）
+     * @returns SelectorRuntime，或 null（无可用 BREP solid）
+     */
+    buildBrepTopology(partName: PartName): SelectorRuntime | null;
+    /**
+     * dryRun：acorn 语法门禁 + 元数据提取（T5 后唯一路径）。
+     *
+     * extractMetadata 全量解析（语法 + 引用），不查符号表。未知 callee 放行，
+     * 试执行见 execute 的 failedAt。
+     *
+     * @param code .fai.js 文本
+     * @returns CheckResult
+     */
+    check(code: string): CheckResult;
+    /**
+     * 派生缓存失效（P0-4）：重放前对 `replayKeys`（经 `asPartName()` 转换）逐一清理
+     * 所有派生缓存，确保重放后几何/拓扑/mesh 不命中旧值。
+     *
+     * 清理清单（§4.4）：
+     * - `solidCache`：先 `kernel.release(handle)`，再删键（参照 dispose 的 try/catch）；
+     * - `brepChain.meshShapeCache`：删键（跨轮保留，不清会返回旧 solid 的三角化）；
+     * - `faceEvolutionCache` / `roleTableCache`：删键（与 runtime 同 Map 引用，删键即生效）；
+     * - `topologyCache` / `statementCache`：删键（collectDirectResult 按新几何重新填充）。
+     */
+    private releasePartCaches;
+    /**
+     * 前缀重放式 update 增量执行（P0-5）。
+     *
+     * 流程：
+     * 1. 保守闸门 G0–G8 判定——任一命中则退化为全量 `executeDirectText`；
+     * 2. 公共前缀扫描定位首个变更行 → 物理行；
+     * 3. `unitRanges(newCode)` 映射物理行 → 单元起始行 `startLine`；
+     * 4. `releasePartCaches(replayKeys)` 失效派生缓存；
+     * 5. `directExecutor.replayFrom(newCode, startLine, opts)` 重放后缀区间；
+     * 6. `outcome.failedAt` → 降级全量（§4.7）；
+     * 7. `collectDirectResult` 组装结果。
+     *
+     * @param oldCode - 变更前文本（不信任，G3 校验与内部 accumulatedCode 一致）。
+     * @param newCode - 变更后文本。
+     * @param opts - 执行选项。
+     * @returns ExecutionResult。
+     */
+    private updateIncremental;
+    /**
+     * 零变更路径（§4.6）：不执行任何语句，但需重新 collectDirectResult。
+     */
+    private zeroChangePath;
+    /**
+     * 记录指纹快照（每次成功执行结束时调用）。
+     */
+    private recordFingerprints;
+    /**
+     * Dispose the runtime, releasing all acquired OCCT handles and clearing every
+     * cache. The instance is unusable afterwards.
+     */
+    dispose(): void;
+}
+/**
+ * Create a CadRuntime instance.
+ * @param ports - the host-injected environment capabilities.
+ * @param mode - the execution mode (default 'auto').
+ * @param libs - the host-injected library namespaces (including `cad`, which the
+ * root facade injects automatically; core does not assemble it by default).
+ * @param options - optional runtime options (e.g. `executor: 'direct' | 'module'`).
+ * @returns a new CadRuntime.
+ */
+export declare function createRuntime(ports: HostPorts, mode?: ExecutionMode, libs?: Record<string, StdlibNamespace>, options?: CadRuntimeOptions): CadRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/cad-runtime/runtime.d.ts.map

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