@faicad/faijs 0.13.2 → 0.16.0

package/dist/cad-runtime/runtime.js

@@ -34,13 +34,30 @@ import { computeContentKey, stableFingerprint } from './content-key.js';
 export { computeContentKey } from './content-key.js';
 export { stableFingerprint } from './content-key.js';
 import { isCompoundLike, getSlot, ensureSlot } from '../shape.js';
-import { buildPartNaming, assignPrimitiveFaceRoles } from '../topology/naming/build-naming.js';
+import { buildPartNaming } from '../topology/naming/build-naming.js';
 import { faceRowToHint } from '../topology/naming/geom-hint.js';
 import { HASH_UPPER_BOUND } from '../brep/face-evolution.js';
+import { scanDeterminism } from '../lang/determinism-scanner.js';
 // 执行护栏超时错误（§6.3 / D8）定义在独立叶子文件 execution-limit-error.ts，
 // DirectExecutor（direct 路径单元循环内检查）与本文件共用；此处 import + re-export
 // 保持宿主 import 面不变（module 路径 runWithFailureHandling 的 Promise.race 使用）。
 export { ExecutionLimitError } from './execution-limit-error.js';
+import { RuntimeConcurrentError } from './runtime-concurrent-error.js';
+export { RuntimeConcurrentError } from './runtime-concurrent-error.js';
+/**
+ * 全局执行态锁（C1）：进程内同一时刻只允许一个 runtime 处于执行态。
+ *
+ * 进程级单例（`setCurrentStmt` / backends / 内核）决定了并发执行多 runtime 不可支持；
+ * 旧行为是"互踩"（见 {@link CadRuntime.claimBackends} 文档），现在改为显式拒绝。
+ *
+ * **同实例的重入放行**：`update` 内部会经 `executeDirectText`/`appendDirectText` 落入
+ * 同一调用栈——那已被"同一栈上串行"保证，不构成并发。跨实例一律拒绝。
+ */
+let executingRuntimeId = null;
+/** 执行态持有者（诊断用：错误信息里给出被谁挡住）。 */
+let executingEntry = null;
+/** runtime id 分配器（仅用于错误信息定位，不参与任何语义判定）。 */
+let nextRuntimeId = 1;
 /**
  * Thrown by CadRuntime.append when a newly appended statement references a
  * variable that is not in the persistent context — its producer was never
@@ -125,8 +142,14 @@ export class CadRuntime {
     topologyCache = new Map();
     /** 无 IR 执行器（DirectExecutor，T5 后唯一执行路径） */
     directExecutor;
+    /** 实例 id（仅用于 C1 并发错误信息里的定位，不参与任何语义判定）。 */
+    runtimeId = nextRuntimeId++;
     /** 安全策略档位（透传给 extractMetadata 与 DirectExecutor；缺省 'strict'） */
     securityPolicy;
+    /** 确定性扫描档位（缺省 'error'；execute/append 前对源码做 B 档 taint 扫描）。 */
+    determinismPolicy;
+    /** warn 档位下收集的确定性警告，合并进最终 ExecutionResult.infos。 */
+    determinismWarnings = [];
     /** 宿主注册库（含 cad：由根门面 createRuntime 包装注入；注入编译产物 fn 的第二参 ns） */
     libs;
     /** 库内容身份表 (binding → content hash)，增量 key 用（B2，§7.3） */
@@ -177,6 +200,9 @@ export class CadRuntime {
         // wrapping — DUAL_OP_META hangs on the function object with
         // enumerable:false, and wrapping first would let bare functions silently
         // skip the strict validation pass (R8).
+        // Naming (2026-09-23): library authors no longer declare face naming; every
+        // bare function is admitted with the default unmodeled provenance (see
+        // admit-compat-lib.ts / docs/plans/2026-09-23-relax-lib-naming-design.md).
         const lift = options?.autoLift ?? !hasDualOp(ns);
         const admitted = lift
             ? admitCompatLib(ns)
@@ -201,6 +227,7 @@ export class CadRuntime {
         this.libs = libs;
         this.namespaces = { ...libs };
         this.securityPolicy = options.security ?? 'strict';
+        this.determinismPolicy = options.determinism ?? 'error';
         this.directExecutor = new DirectExecutor({
             namespaces: this.namespaces,
             setSolid: (partName, solid) => { this.solidCache.set(partName, solid); },
@@ -218,7 +245,11 @@ export class CadRuntime {
      * 先前 runtime 的后续 execute 会被静默劫持（dispatch 走错槽、缓存键漂移、
      * 顶替释放旧 BREP 句柄后拓扑重建撞上悬空句柄）。因此除构造外，每个执行入口
      * （execute，所有执行路径的汇聚点）都必须先重新认领本实例的配置。
-     * 限制：并发交错执行多个 runtime 仍会互踩（与 setCurrentStmt 同级的串行假设）。
+     *
+     * ⚠️ 并发交错执行多个 runtime **仍会互踩**——这条限制现在由全局执行态锁强制
+     * （{@link withExecutionLock}）：第二个 runtime 在他人执行态时抛
+     * {@link RuntimeConcurrentError}（E_RUNTIME_CONCURRENT），不再"尽力而为"。
+     * 用户已裁决不允许并发（开发计划 §4.7 C1）。
      * ⚠️ getter 的 this 指向所在对象字面量，用箭头闭包捕获实例（避免 no-this-alias）。
      */
     claimBackends() {
@@ -284,14 +315,48 @@ export class CadRuntime {
         return this.brepChain;
     }
     // ── 公开入口：execute / append / update（输入一律是代码文本，IR 在引擎内部） ──
+    /**
+     * 取全局执行态锁并运行 `fn`（C1）。跨实例并发 → 抛 {@link RuntimeConcurrentError}；
+     * 本实例重入（update 内部落到 executeDirectText/appendDirectText）放行。
+     *
+     * 刻意**同步**取锁（不在取锁前 await）：这样 `runtimeA.execute(...)` 尚未 await 时
+     * 紧接着调 `runtimeB.execute(...)` 必然被拒绝，行为可确定、可测试。
+     * @param entry - 入口名（execute / append / update），仅用于错误信息。
+     * @param fn - 实际执行体。
+     * @returns fn 的结果；无论成功失败都释放锁（finally）。
+     */
+    async withExecutionLock(entry, fn) {
+        if (executingRuntimeId !== null && executingRuntimeId !== this.runtimeId) {
+            throw new RuntimeConcurrentError(executingRuntimeId, this.runtimeId, entry);
+        }
+        const reentrant = executingRuntimeId === this.runtimeId;
+        if (!reentrant) {
+            executingRuntimeId = this.runtimeId;
+            executingEntry = entry;
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            if (!reentrant) {
+                executingRuntimeId = null;
+                executingEntry = null;
+            }
+        }
+    }
+    /** 当前执行态持有者的入口名（诊断；无持有者时 null）。 */
+    static get executingEntry() {
+        return executingEntry;
+    }
     /**
      * 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.
+     * @throws {RuntimeConcurrentError} when another CadRuntime is already executing (C1).
      */
     async execute(code, opts) {
-        return this.executeDirectText(code, opts);
+        return this.withExecutionLock('execute', () => this.executeDirectText(code, opts));
     }
     /**
      * Append new statements (incremental execution): only execute the new code
@@ -300,9 +365,97 @@ export class CadRuntime {
      * @param code - the new .fai.js source text to append.
      * @param opts - optional execution options.
      * @returns promise resolving to the ExecutionResult.
+     * @throws {RuntimeConcurrentError} when another CadRuntime is already executing (C1).
      */
     async append(code, opts) {
-        return this.appendDirectText(code, opts);
+        return this.withExecutionLock('append', () => this.appendDirectText(code, opts));
+    }
+    /**
+     * 确定性扫描门（B 档 taint）：执行前对源码做静态扫描，违规按 determinismPolicy 处理。
+     *
+     * 扫描范围：主文件 + @faicad/* 库源码（经 libLoader.loadSource，若宿主提供）。
+     * 项目内相对 import 模块的扫描由 ModuleRegistry.load 内部完成（构造时传入 policy）。
+     *
+     * @returns ExecutionResult（违规 + policy='error' 时），null（通过或 warn/off）。
+     *          warn 档位下警告收集到 this.determinismWarnings，由调用方合并进 infos。
+     */
+    async runDeterminismGate(code, meta) {
+        if (this.determinismPolicy === 'off')
+            return null;
+        this.determinismWarnings = [];
+        const hints = this.extractDeterminismHints(meta);
+        const violations = scanDeterminism(code, {
+            defaultNs: this.defaultNsName,
+            extraNamespaces: hints.namespaces,
+            extraCallees: hints.callees,
+        }).violations;
+        // 库源码扫描（@faicad/* 非引擎；经 libLoader.loadSource，宿主未提供则跳过）
+        const loadSource = this.ports.libLoader?.loadSource;
+        if (loadSource) {
+            for (const imp of meta.imports ?? []) {
+                const spec = imp.packageName ?? imp.specifier ?? '';
+                if (!spec.startsWith('@faicad/'))
+                    continue;
+                if (spec === '@faicad/faijs' || spec.startsWith('@faicad/faijs/'))
+                    continue;
+                let src;
+                try {
+                    src = await loadSource(spec);
+                }
+                catch {
+                    // 库源码不可读 → 跳过（不阻断执行；库违规由库作者负责）
+                }
+                if (src) {
+                    // scanLibrarySource strict：库源码含 TS 语法 → 显式抛错（不静默跳过）
+                    violations.push(...this.scanLibrarySource(src, hints).violations);
+                }
+            }
+        }
+        if (violations.length === 0)
+            return null;
+        const formatted = violations.map((v) => `[determinism] line ${v.lineNo} [${v.source}]: ${v.message}`);
+        if (this.determinismPolicy === 'warn') {
+            this.determinismWarnings = formatted;
+            return null;
+        }
+        // 'error'
+        const first = violations[0];
+        return {
+            outputs: new Map(),
+            brepChain: this.brepChain,
+            terminals: [],
+            infos: [],
+            failedAt: {
+                index: -1,
+                callee: 'determinism',
+                message: formatted[0],
+                lineNo: first.lineNo,
+                code: 'E_DETERMINISM',
+            },
+        };
+    }
+    /** 从 meta.imports 提取扫描提示：namespace import → extraNamespaces，named import → extraCallees。 */
+    extractDeterminismHints(meta) {
+        const namespaces = [];
+        const callees = [];
+        for (const imp of meta.imports ?? []) {
+            if (imp.kind === 'namespace' && imp.localName)
+                namespaces.push(imp.localName);
+            if (imp.kind === 'named')
+                callees.push(...imp.bindings);
+        }
+        return { namespaces, callees };
+    }
+    /** 扫描库源码（契约：输入必须是编译后的纯 JS；含 TS 语法/解析失败 → 显式报错，无剥离、无回退）。 */
+    scanLibrarySource(src, hints) {
+        return {
+            violations: scanDeterminism(src, {
+                defaultNs: this.defaultNsName,
+                extraNamespaces: hints.namespaces,
+                extraCallees: hints.callees,
+                strict: true, // 库源码非法（含 TS 语法）→ 抛错，不静默跳过
+            }).violations,
+        };
     }
     /**
      * Direct-mode full execution: the code text runs on the DirectExecutor
@@ -315,6 +468,9 @@ export class CadRuntime {
         this.claimBackends();
         this.accumulatedCode = code;
         const meta = extractMetadata(code, { defaultNs: this.defaultNsName, security: this.securityPolicy, namespaces: Object.keys(this.libs) });
+        const determinismFailure = await this.runDeterminismGate(code, meta);
+        if (determinismFailure)
+            return determinismFailure;
         const libLoadFailure = await this.autoLoadLibsFromImports(meta.imports);
         if (libLoadFailure)
             return libLoadFailure;
@@ -340,6 +496,8 @@ export class CadRuntime {
             return this.directFailedAtOrThrow(outcome.failedAt, meta);
         }
         const result = this.collectDirectResult(meta, opts);
+        if (this.determinismWarnings.length > 0)
+            result.infos.push(...this.determinismWarnings);
         this.recordFingerprints(opts);
         return result;
     }
@@ -403,6 +561,9 @@ export class CadRuntime {
         // A1 安全扫描需把 ctx 已有键 + 已注册命名空间都作为 knownNames（避免 SEC_FREE_IDENT 误杀 append 场景）。
         const appendKnownNames = [...Object.keys(this.libs), ...de.listCtxKeys()];
         const meta = extractMetadata(fullCode, { defaultNs: this.defaultNsName, looseVars: true, security: this.securityPolicy, namespaces: appendKnownNames, nsNames: Object.keys(this.libs) });
+        const determinismFailure = await this.runDeterminismGate(fullCode, meta);
+        if (determinismFailure)
+            return determinismFailure;
         const libLoadFailure = await this.autoLoadLibsFromImports(meta.imports);
         if (libLoadFailure)
             return libLoadFailure;
@@ -427,6 +588,8 @@ export class CadRuntime {
             return this.directFailedAtOrThrow(outcome.failedAt, meta);
         }
         const result = this.collectDirectResult(meta, opts);
+        if (this.determinismWarnings.length > 0)
+            result.infos.push(...this.determinismWarnings);
         this.recordFingerprints(opts);
         return result;
     }
@@ -452,7 +615,7 @@ export class CadRuntime {
             return { seed: {} };
         if (!(meta.imports ?? []).some((imp) => isRelativeSpecifier(imp.specifier)))
             return { seed: {} };
-        const registry = new ModuleRegistry(loader, (code, imports) => this.runDirectModule(code, imports), this.securityPolicy);
+        const registry = new ModuleRegistry(loader, (code, imports) => this.runDirectModule(code, imports), this.securityPolicy, this.determinismPolicy);
         try {
             const seed = await registry.resolveImports(meta.imports ?? [], baseKey);
             return { seed };
@@ -523,9 +686,15 @@ export class CadRuntime {
             const v = de.getCtxVar(String(name));
             if (isShapeLike(v)) {
                 const shape = v;
+                // 非实体导入（C6 线框/面/壳）不携带显示网格——positions/indices 为
+                // undefined 是已知限制（load-nonsolid.test.ts），content key 退化为
+                // 占位值而不是崩溃。
+                const hasMesh = shape.positions instanceof Float32Array && shape.indices instanceof Uint32Array;
                 this.statementCache.set(name, {
                     statementKey: `direct:${String(name)}`,
-                    outputContentKey: computeContentKey(shape.positions, shape.indices),
+                    outputContentKey: hasMesh
+                        ? computeContentKey(shape.positions, shape.indices)
+                        : `direct:nomesh:${String(name)}`,
                     output: shape,
                 });
             }
@@ -777,8 +946,9 @@ export class CadRuntime {
             };
         }
         if (partTopo.source === 'primitive') {
-            const primitiveRoles = assignPrimitiveFaceRoles(faces, partName);
-            return { source: 'primitive', partName, faces, edges, primitiveRoles, edgeFaceOrdinals };
+            // Phase 1.8（D6）：primitive 不再派生伪拓扑 role——拓扑身份是 BREP 专有能力，
+            // primitive/mesh 一致只填 hint（naming 行 origin/role 显式 null）。
+            return { source: partTopo.source, partName, faces, edges, edgeFaceOrdinals };
         }
         return { source: partTopo.source, partName, faces, edges, edgeFaceOrdinals };
     }
@@ -822,9 +992,10 @@ export class CadRuntime {
      * @param newCode - the .fai.js source text after the edit.
      * @param opts - optional execution options.
      * @returns promise resolving to the ExecutionResult.
+     * @throws {RuntimeConcurrentError} when another CadRuntime is already executing (C1).
      */
     async update(oldCode, newCode, opts) {
-        return this.updateIncremental(oldCode, newCode, opts);
+        return this.withExecutionLock('update', () => this.updateIncremental(oldCode, newCode, opts));
     }
     // ── 公开：缓存访问 ──
     /**