@faicad/faijs 0.13.0

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

@@ -0,0 +1,271 @@
+/**
+ * module-executor — JS VM 模块加载与增量调度（VM 执行方案 Phase 1）
+ *
+ *
+ * ModuleExecutor 是 VM 执行的核心：
+ * - `ctx` 持久变量容器（跨 execute/append/update 存活）
+ * - `load(code)` 用 data:/Blob URL 动态 import 编译产物（零 import，两平台同构）
+ * - `executeAll/executeIds/executeFrom` 按 deps 拓扑序调度
+ * - `reconcileCtx` 回收"定义语句已不在脚本中"的变量并释放其内核资源
+ * - `cache` 记录每语句 statementKey + outputContentKey（plan 增量判定）
+ */
+import type { CompiledStatementMeta } from '../lang/compile.js';
+import type { StatementIR, ScriptIR } from '../lang/types.js';
+import { type InternalKeepRecord } from '../lang/keep.js';
+import type { Shape } from '../mesh/types.js';
+import type { BrepHandle } from '../brep/engine/types.js';
+import type { PartName, StmtId } from '../identity.js';
+import { type StdlibNamespace } from '../runtime-state.js';
+/**
+ * 已装配的命名空间集合（标准库 `cad` + 宿主注册的库）。
+ * 编译产物 `fn(ctx, ns)` 经 ns.<binding>.<callee>() 调用——引擎不区分函数来自哪个库。
+ */
+export interface Namespaces {
+    readonly cad: StdlibNamespace;
+    readonly [binding: string]: StdlibNamespace;
+}
+/**
+ * 执行记账（P5：exec 上下文删除后，ModuleExecutor 只需 beforeStatement + outputCache）。
+ * beforeStatement：undo 逐语句快照钩子；outputCache：语句产物缓存（collectResult 消费）。
+ */
+export interface ExecBookkeeping {
+    beforeStatement?: (stmtId: string, index: number) => void;
+    outputCache: Map<PartName, Shape>;
+    /** 变更声明（P6：引擎比对推导 + 装配应用记录），collectResult 消费。 */
+    changed: Set<PartName>;
+}
+/** 编译产物中的单条语句（模块文本 `{ id, deps, fn }`）。 */
+export interface CompiledStatement {
+    id: StmtId;
+    deps: StmtId[];
+    fn: (ctx: Record<string, unknown>, ns: Namespaces) => Promise<void>;
+}
+/**
+ * Options for constructing a ModuleExecutor, providing the OCCT handle
+ * callbacks the executor needs to integrate with the runtime's persistent
+ * solid caches.
+ */
+export interface ModuleExecutorOptions {
+    /** Release the OCCT handle for a PartName (called when reconcileCtx deletes a variable; no-op without a handle). */
+    releaseSolid?: (partName: PartName) => void;
+    /** Read the OCCT handle currently held for a PartName (used for replacement-release pre-capture). */
+    getSolid?: (partName: PartName) => BrepHandle | undefined;
+    /** Release a previously captured OCCT handle (replacement release: free the old handle after a same-id recompute succeeds). */
+    releaseHandle?: (handle: BrepHandle) => void;
+    /** Sync an identity-slot solid into the PartName-keyed solidCache (relied on by existing runtime logic). */
+    setSolid?: (partName: PartName, solid: BrepHandle) => void;
+    /** Sync an identity-slot faceEvolution into the PartName-keyed faceEvolutionCache. */
+    setFaceEvolution?: (partName: PartName, evo: Map<number, number[]>) => void;
+    /** Sync an identity-slot roleTable into the PartName-keyed roleTableCache (§2.3 naming). */
+    setRoleTable?: (partName: PartName, roleTable: unknown) => void;
+}
+/**
+ * ModuleExecutor loads JS VM modules and schedules incremental execution.
+ *
+ * It is the heart of the VM execution approach: it keeps the persistent `ctx`
+ * variable container alive across execute/append/update calls, dynamically
+ * imports compiled modules from data:/Blob URLs (zero imports, isomorphic on
+ * both platforms), schedules all/selected/from statements in dependency
+ * topological order, reclaims variables whose defining statements have left the
+ * script, and caches each statement's key + output content key for incremental
+ * planning.
+ */
+export declare class ModuleExecutor {
+    /** Persistent variable container across incremental executions. */
+    readonly ctx: Record<string, unknown>;
+    private stmts;
+    /** statementKey 缓存（增量判定；key = op|JSON(args)|deps 的 outputContentKey） */
+    private cache;
+    /**
+     * 函数体 keep 登记（keep-syntax 设计 §2.2）：
+     * stmtId → { kept, hidden }。语句执行前清空本条记录，执行中累加；
+     * 本轮未执行（缓存命中）→ 保留上一轮记录（keep 零重算的前提）。
+     */
+    readonly internalKeep: Map<StmtId, InternalKeepRecord>;
+    private sourceById;
+    private metaById;
+    private script;
+    private lastCode;
+    /**
+     * 默认命名空间绑定名（U10/R2）：与 runtime 的 registerLib(…, {default: true}) 声明同步；
+     * statementKey/computeKey 中 namespace 缺省（undefined）的语句按该绑定名计 key。
+     */
+    private defaultNsName;
+    /**
+     * Sync the default namespace binding name (called by runtime.registerLib with {default:true}).
+     * @param name - the namespace binding name to use as default.
+     */
+    setDefaultNsName(name: string): void;
+    private namespaces;
+    /** 库内容身份表（binding → content hash；增量 key 版控，B2 §7.3） */
+    private libIds;
+    /** 本机函数调用嵌套深度（§5.5）：> 0 表示当前在函数体内执行——keep 登记被抑制。 */
+    private userFunctionDepth;
+    private readonly releaseSolid?;
+    private readonly getSolid?;
+    private readonly releaseHandle?;
+    private readonly setSolid?;
+    private readonly setFaceEvolution?;
+    private readonly setRoleTable?;
+    constructor(namespaces: Namespaces, options?: ModuleExecutorOptions);
+    /**
+     * Hot-update the assembled namespace set (after registerLib mounts a new
+     * library).
+     * @param namespaces - the new assembled namespaces.
+     * @param libIds - the library content-identity table (binding → libId), used
+     * to version library-branch statement keys (B2, §7.3).
+     */
+    setNamespaces(namespaces: Namespaces, libIds?: ReadonlyMap<string, string>): void;
+    /**
+     * Update the script and its compiled metadata (ctx stays alive).
+     * @param script - the parsed ScriptIR.
+     * @param compiled - the compiled statement metadata.
+     */
+    setCompiled(script: ScriptIR, compiled: CompiledStatementMeta[]): void;
+    /**
+     * Load the compiled module, skipping a reload when the code is unchanged
+     * (compiled-product cache).
+     * @param code - the compiled module source.
+     */
+    load(code: string): Promise<void>;
+    /**
+     * Execute every statement in dependency topological order (i.e. statement
+     * table order).
+     * @param exec - the execution bookkeeping.
+     */
+    executeAll(exec: ExecBookkeeping): Promise<void>;
+    /**
+     * Execute only the given statements (append: the prefix is already in the
+     * persistent ctx). As in the old interpreter, beforeStatement fires only for
+     * new_shape statements; void/same_shape statements (do_assemble/add_constraint)
+     * do not trigger it (do_assemble's fn delegates internally).
+     * @param ids - the compiled statement ids to execute.
+     * @param exec - the execution bookkeeping.
+     */
+    executeIds(ids: StmtId[], exec: ExecBookkeeping): Promise<void>;
+    /**
+     * Re-execute from the change points on (update: plan derives the stale set).
+     * The stale set is closed over deps (a statement depending on a stale one is
+     * itself stale) and runs in topological order.
+     * @param staleIds - the set of stale statement ids to recompute.
+     * @param exec - the execution bookkeeping.
+     */
+    executeFrom(staleIds: Set<StmtId>, exec: ExecBookkeeping): Promise<void>;
+    /**
+     * Reclaim ctx variables whose defining statement is no longer in the script
+     * and release their kernel resources (a required action after undoing a
+     * statement deletion). Variables in `referencedVars` are kept even when not
+     * written by an active statement (cross-file references to other files'
+     * parts).
+     * @param activeStmtIds - the ids of statements still considered active.
+     * @param writeSets - mapping of statement id to the variable names it writes.
+     * @param referencedVars - variable names still referenced by the active
+     * script; these survive reclaim.
+     */
+    reconcileCtx(activeStmtIds: Set<StmtId>, writeSets: Map<StmtId, PartName[]>, referencedVars?: Set<string>): void;
+    /** 清除所有缓存（key 缓存 + ctx 变量）。测试用：CadRuntime.clearStatementCache 调用。 */
+    clearCache(): void;
+    /**
+     * Read a statement's statementKey cache entry.
+     * @param id - the compiled statement id.
+     * @returns the cached key and output content key, or undefined.
+     */
+    getCachedKey(id: StmtId): {
+        key: string;
+        outputContentKey: string;
+    } | undefined;
+    /**
+     * Read a statement's function-body keep registration (used by the terminal-dag
+     * C1 check); undefined when none exists.
+     * @param id - the compiled statement id.
+     * @returns the internal keep record, or undefined.
+     */
+    getInternalKeep(id: StmtId): InternalKeepRecord | undefined;
+    /**
+     * Register a function-body keep entry into ModuleExecutor.internalKeep,
+     * accumulating during execution.
+     * @param id - the compiled statement id.
+     * @param names - the kept variable names.
+     * @param hidden - whether the kept variables are hidden.
+     */
+    registerKeep(id: StmtId, names: PartName[], hidden: boolean): void;
+    /**
+     * 函数 BREP 域释放（§5.6 / D13）：取走当前域的句柄登记表，收集本语句输出
+     * （返回值）可到达的全部句柄为 keep 集，释放登记域内除 keep 集外的全部句柄。
+     * 函数体内中间体的瞬态句柄在此一次性释放——单次调用内存有界，不逐轮释放。
+     */
+    private releaseFunctionBrepDomain;
+    /**
+     * Read a ctx variable.
+     * @param name - the variable name.
+     * @returns the variable value.
+     */
+    getCtxVar(name: string): unknown;
+    /**
+     * Write a ctx variable (used to sync assembly transforms from outputCache
+     * back into ctx).
+     * @param name - the variable name.
+     * @param value - the value to store.
+     */
+    setCtxVar(name: string, value: unknown): void;
+    /**
+     * All variable names currently held in the persistent ctx (covers parts
+     * executed by previous execute/append/update calls).
+     * @returns the ctx variable names.
+     */
+    listCtxKeys(): string[];
+    /**
+     * Returns the compiled metadata in params + statements order.
+     * @returns the compiled statement metadata array.
+     */
+    getMetas(): CompiledStatementMeta[];
+    /** 清空 ctx 与 statementKey 缓存（CadRuntime.dispose 用）。 */
+    clear(): void;
+    /** 语句执行后：ctx → outputCache 同步 + 身份槽 → solidCache/faceEvolutionCache 同步 + statementKey 缓存 + 装配传播。 */
+    private afterStatement;
+    /**
+     * P6：装配传播——取走全部待应用变换，引擎应用到成员（mesh 原地 + BREP 槽 + solidCache），
+     * 记录 changed，并让依赖成员的下游语句失效重算（DAG 重放，替代 exec.dependentsOf 图遍历）。
+     */
+    private applyPendingAssemblyTransforms;
+    /** 找出依赖给定变量名的语句（装配成员 → 消费它的下游）。 */
+    private computeDownstream;
+    /**
+     * 判定并发 part-brep-lost 事件。
+     *
+     * 判据：语句有几何输入且**全部**输入都在 BREP 链上，但输出**不在**链上
+     * → BREP 链在此断开（mesh-only 函数或 fallthrough）。
+     *
+     * true-JS-subset §4.4.2：几何输入 = positional 中的 VarRefIR + ExprIR.refs
+     * （表达式实参引用的 Shape 变量同样喂进本语句；CallRef 嵌套调用是只读查询不计）。
+     */
+    private emitBrepLost;
+    /**
+     * Compute a statementKey = op | JSON(positional + args without keep) | each
+     * dependency's output content key (parameter statements use the parameter
+     * value). The keep/keepHidden keys are excluded so toggling retain/hide state
+     * triggers no geometric recompute. plan() uses this with the current cache to
+     * compute the expected key for incremental decisions.
+     *
+     * true-JS-subset §4.4.1：位置实参槽入 key——ExprIR 可 JSON 化
+     * （text + refs + params），表达式文本变化即触发重算；表达式引用的上游变量
+     * 变化经 deps 的 outputContentKey 传递。
+     *
+     * 本机函数调用（local）：key 前缀 `local.<callee>#<bodyHash>`（§6.2 / P4 内容寻址）——
+     * 编辑函数体文本 → 所有调用该函数的语句 key 变化 → 下游失效重算；不改函数体零重算。
+     * @param meta - the compiled statement metadata.
+     * @param source - the source statement, or undefined for parameter statements.
+     * @returns the computed statement key string.
+     */
+    computeKey(meta: CompiledStatementMeta, source: StatementIR | undefined): string;
+    /**
+     * 按绑定名查 libId（setNamespaces 已存表；本机函数不含——只适用于库分支 key）。
+     * 库未登记或表缺失 → 'missing'，增量会自动失效重算。
+     * @param binding 命名空间绑定名。
+     * @returns 库的内容身份；`'missing'` 表示该绑定无登记身份。
+     */
+    libIdOf(binding: string): string;
+    /** outputContentKey：shape 语句 = mesh 内容哈希；参数语句 = 参数值。 */
+    private computeOutputContentKey;
+}
+//# sourceMappingURL=module-executor.d.ts.map

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

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