@faicad/faijs 0.19.0 → 0.29.3

package/dist/api/fillet.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib fillet — fillet 圆角库函数（BREP-only，directEdit 能力）
+ * api fillet — fillet 圆角库函数（BREP-only，directEdit 能力）
  *
  * 平台分层（narrowing plan Phase 5，D11）：**中立 op**——`filletWithHistory` 是
  * L1 核心面（brepkit 亦实现），实现全程走 L1（getBrepApi，D12），不声明 engines；
@@ -20,28 +20,48 @@
  * - 几何限定符字符串选边（§4）
  */
 import type { Shape } from '../mesh/types.js';
+/** 边选择器校验选项。 */
+export interface EdgeSelectorCheckOptions {
+    /**
+     * 允许 1 起序号作为边选择器（**仅网格链**；见 `resolveMeshEdges`）。
+     *
+     * 精度链不开这个口子：BREP 的边身份是 role 线路（两个相邻面的 `(origin, role)`），
+     * 序号只是内核枚举序，跨特征会漂移——让精度链接受序号等于把"可重放的引用"降级成
+     * "这次跑出来的下标"。近似链相反：没有 role 层，序号是唯一无歧义的指认方式。
+     */
+    readonly allowOrdinals?: boolean;
+}
 /**
- * Validate fillet parameters: `edges` must be a non-empty array of EdgeTopoRef,
- * each with kind key "edge" and a two-entry faces pair; `radius` must be a
+ * Validate fillet parameters: `edges` must be a non-empty array of EdgeTopoRef
+ * (each with kind key "edge" and a two-entry faces pair) — or of 1-based
+ * ordinals when `opts.allowOrdinals` (the mesh chain); `radius` must be a
  * positive number (M1: uniform radius only).
  * @param params the raw fillet operation parameters.
+ * @param opts the selector-form options (mesh chain allows ordinals).
  */
-export declare function assertFilletParams(params: Record<string, unknown>): void;
+export declare function assertFilletParams(params: Record<string, unknown>, opts?: EdgeSelectorCheckOptions): void;
 /**
- * 在几何体上做圆角（等半径）。仅 BREP 可用。
+ * 在几何体上做圆角（等半径）。
+ *
+ * 两条路径都以 `meshEngines: ['brepkit']` 之外的事实为界：BREP 输入走
+ * `filletWithHistory`（带面演化与 roleTable 传播）；**网格实体**输入走网格后端
+ * （近似拓扑无 role，边按几何或序号解析，无面演化）。非 BREP 的**裸网格**输入仍抛
+ * `E_MESH_SOLID_UNSUPPORTED`——裸网格没有近似拓扑，没有边可选。
  * @group 特征
  * @inputs 1
  * @async true
  * @qual ok
  * @name fillet
- * @note 圆角是 BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。`radius` 为正数（mm）。
- *       圆角后 roleTable 经 filletWithHistory 传播，保证后续特征仍可按 role 选面/选边。
+ * @note `radius` 为正数（mm）。BREP 路径圆角后 roleTable 经 filletWithHistory 传播，
+ *       后续特征仍可按 role 选面/选边；网格实体路径没有 role 层，边只能按几何或
+ *       序号（近似拓扑 `edges` 数组下标 + 1）指认。
  * @returns Shape 圆角后的几何。
  * @param input - 目标几何。type:Shape required:true
- * @param params.edges - 参与圆角的边（EdgeTopoRef[]，条目为相邻两面的 role 线路）。type:EdgeTopoRef[] required:true
+ * @param params.edges - 参与圆角的边：相邻两面的 role 线路（EdgeTopoRef[]）；网格链上也可用 1 起序号。type:EdgeTopoRef[] required:true
  * @param params.radius - 圆角半径（mm，>0）。type:number required:true
  * @example
  * const p = await cad.fillet(part0, { edges: [{ kind:'edge', faces:[{ origin:'box', role:'box:top' }, { origin:'box', role:'box:front' }], hint:{ kind:'edge' } }], radius:2 })
+ * const q = await cad.fillet(meshPart, { edges: [3], radius: 1 })
  */
 export declare const fillet: ((input: Shape, params: Record<string, unknown>) => Promise<Shape>) & {
     __faijs__dualOp?: import("../define-op.js").DualOpMeta;

package/dist/api/fillet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fillet.d.ts","sourceRoot":"","sources":["../../src/api/fillet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAe1C;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAkBxE;AAoED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM;;CAOjB,CAAA"}
+{"version":3,"file":"fillet.d.ts","sourceRoot":"","sources":["../../src/api/fillet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAgB1C,gBAAgB;AAChB,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,CAAC,EAAE,wBAAwB,GAC9B,IAAI,CAwBN;AA6GD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,MAAM;;CAYjB,CAAA"}

package/dist/api/fillet.js

@@ -1,5 +1,5 @@
 /**
- * stdlib fillet — fillet 圆角库函数（BREP-only，directEdit 能力）
+ * api fillet — fillet 圆角库函数（BREP-only，directEdit 能力）
  *
  * 平台分层（narrowing plan Phase 5，D11）：**中立 op**——`filletWithHistory` 是
  * L1 核心面（brepkit 亦实现），实现全程走 L1（getBrepApi，D12），不声明 engines；
@@ -27,19 +27,27 @@ import { fromBrep, brepOf, inputRoleTable } from '../shape.js';
 import { defineOp } from '../sdk.js';
 import { resolveTopoRef, TopoRefError } from '../topology/naming/index.js';
 import { buildEdgeResolutionContext } from './topo-resolve.js';
-// ── 参数自校验（stdlib 被直接 import 时的防御层）──
+import { meshKernelFailure, meshSolidEntry, meshSolidProduct, resolveMeshEdges } from './internal/mesh-solid-op.js';
 /**
- * Validate fillet parameters: `edges` must be a non-empty array of EdgeTopoRef,
- * each with kind key "edge" and a two-entry faces pair; `radius` must be a
+ * Validate fillet parameters: `edges` must be a non-empty array of EdgeTopoRef
+ * (each with kind key "edge" and a two-entry faces pair) — or of 1-based
+ * ordinals when `opts.allowOrdinals` (the mesh chain); `radius` must be a
  * positive number (M1: uniform radius only).
  * @param params the raw fillet operation parameters.
+ * @param opts the selector-form options (mesh chain allows ordinals).
  */
-export function assertFilletParams(params) {
+export function assertFilletParams(params, opts) {
     const edges = params.edges;
     if (!Array.isArray(edges) || edges.length === 0) {
         throw new Error('E_FILLET_NO_EDGES: fillet requires at least one edge');
     }
     for (const e of edges) {
+        if (opts?.allowOrdinals && typeof e === 'number') {
+            if (!Number.isInteger(e) || e < 1) {
+                throw new Error('E_FILLET_BAD_EDGE_REF: an edge ordinal must be a positive integer (1-based)');
+            }
+            continue;
+        }
         if (!e || typeof e !== 'object' || e.kind !== 'edge') {
             throw new Error('E_FILLET_BAD_EDGE_REF: every edge entry must be an EdgeTopoRef with kind:"edge"');
         }
@@ -105,23 +113,70 @@ function filletBrep(input, params) {
     return fromBrep(solidToShape(kernel, resultSolid), { solid: resultSolid, faceEvolution, roleTable });
 }
 /**
- * 在几何体上做圆角（等半径）。仅 BREP 可用。
+ * 网格实体路径：对近似拓扑里识别出的边倒圆角（方案 2026-10-01 §3.5 三明治）。
+ *
+ * 与 BREP 路径的三处实质差异，都是"网格零件没有精度链、没有 role 层"的直接后果：
+ * - 边**按几何或序号**解析：`EdgeTopoRef` 走长度/中点匹配；**1 起序号**直接取自近似
+ *   拓扑的 `edges` 数组下标 + 1（等长边靠几何分不开，序号是唯一无歧义的指认方式）；
+ * - 内核调用走 L1 裸 `kernel.fillet`（`filletWithHistory` 是精度链的面演化能力，
+ *   近似拓扑没有 hash 演化可言，故**不产生** faceEvolution / roleTable，如实缺席
+ *   而不是造一张恒等映射）；
+ * - 产物句柄写回后由 `meshSolidProduct` 重新三角化并重建近似拓扑。
+ *
+ * GOTCHA（2026-10-01 实测，见 `brepkit-kernel/mesh-solid-topology.test.ts`）：
+ * 一次请求里的**全部**边交给内核，会在共面边链（如圆柱端盖的 64 条边）上被整体
+ * 拒绝——不是单条边不可倒，而是"一次性磨圆会自交"。故本实现**如实失败**，不自动
+ * 拆成逐边重试（运行时换策略会掩盖几何事实）。要给共面边链倒角，请分多次调用，
+ * 每次一组几何上互不相邻的边。
+ *
+ * @param input - the mesh-solid input.
+ * @param params - the validated fillet parameters.
+ * @returns the filleted mesh solid as a new mesh part.
+ */
+function filletMeshSolid(input, params) {
+    const edges = params.edges;
+    const radius = params.radius;
+    const entry = meshSolidEntry(input, 'fillet');
+    const edgeHandles = resolveMeshEdges(entry, edges, 'fillet');
+    let result;
+    try {
+        result = entry.kernel.fillet(entry.solid, edgeHandles, radius);
+    }
+    catch (cause) {
+        throw meshKernelFailure('fillet', 'E_FILLET_RADIUS_TOO_LARGE', `fillet(r=${radius}) on ${edgeHandles.length} edge(s)`, cause);
+    }
+    return meshSolidProduct(entry, result);
+}
+/**
+ * 在几何体上做圆角（等半径）。
+ *
+ * 两条路径都以 `meshEngines: ['brepkit']` 之外的事实为界：BREP 输入走
+ * `filletWithHistory`（带面演化与 roleTable 传播）；**网格实体**输入走网格后端
+ * （近似拓扑无 role，边按几何或序号解析，无面演化）。非 BREP 的**裸网格**输入仍抛
+ * `E_MESH_SOLID_UNSUPPORTED`——裸网格没有近似拓扑，没有边可选。
  * @group 特征
  * @inputs 1
  * @async true
  * @qual ok
  * @name fillet
- * @note 圆角是 BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。`radius` 为正数（mm）。
- *       圆角后 roleTable 经 filletWithHistory 传播，保证后续特征仍可按 role 选面/选边。
+ * @note `radius` 为正数（mm）。BREP 路径圆角后 roleTable 经 filletWithHistory 传播，
+ *       后续特征仍可按 role 选面/选边；网格实体路径没有 role 层，边只能按几何或
+ *       序号（近似拓扑 `edges` 数组下标 + 1）指认。
  * @returns Shape 圆角后的几何。
  * @param input - 目标几何。type:Shape required:true
- * @param params.edges - 参与圆角的边（EdgeTopoRef[]，条目为相邻两面的 role 线路）。type:EdgeTopoRef[] required:true
+ * @param params.edges - 参与圆角的边：相邻两面的 role 线路（EdgeTopoRef[]）；网格链上也可用 1 起序号。type:EdgeTopoRef[] required:true
  * @param params.radius - 圆角半径（mm，>0）。type:number required:true
  * @example
  * const p = await cad.fillet(part0, { edges: [{ kind:'edge', faces:[{ origin:'box', role:'box:top' }, { origin:'box', role:'box:front' }], hint:{ kind:'edge' } }], radius:2 })
+ * const q = await cad.fillet(meshPart, { edges: [3], radius: 1 })
  */
 export const fillet = defineOp({
     capabilities: ['directEdit'],
+    meshEngines: ['brepkit'],
+    mesh(input, params) {
+        assertFilletParams(params, { allowOrdinals: true });
+        return filletMeshSolid(input, params);
+    },
     brep(input, params) {
         assertFilletParams(params);
         return filletBrep(input, params);

package/dist/api/fillet.js.map

@@ -1 +1 @@
-{"version":3,"file":"fillet.js","sourceRoot":"","sources":["../../src/api/fillet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAGjC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAE3D,sCAAsC;AAEtC;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA+B;IAChE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;IAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAAwB,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC7E,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAA;QACpG,CAAC;QACD,MAAM,KAAK,GAAI,CAAyB,CAAC,KAAK,CAAA;QAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAA;QACpG,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;IAC5B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAA;IACjF,CAAC;AACH,CAAC;AAED,qDAAqD;AACrD,SAAS,WAAW,CAAC,GAAsB,EAAE,GAAgB;IAC3D,MAAM,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAClC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,yCAAyC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAA;IACxI,CAAC;IACD,OAAO,CAAC,CAAC,MAAoB,CAAA;AAC/B,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,GAAY;IACtC,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC5D,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,GAAY,CAAA;IAC3E,OAAO,IAAI,KAAK,CAAC,mDAAmD,GAAG,EAAE,CAAC,CAAA;AAC5E,CAAC;AAED,kCAAkC;AAClC,SAAS,UAAU,CAAC,KAAY,EAAE,MAA+B;IAC/D,0CAA0C;IAC1C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAA2B,CAAA;IACrD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;IAEzE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAsB,CAAA;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAgB,CAAA;IACtC,MAAM,GAAG,GAAG,0BAA0B,CAAC,MAAM,EAAE,KAAe,CAAC,CAAA;IAC/D,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,0CAA0C,CAAC,CAAA;IAExG,6BAA6B;IAC7B,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAA;IAEzD,wEAAwE;IACxE,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAA8C,CAAA;IACrF,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IAElD,IAAI,WAAuB,CAAA;IAC3B,IAAI,aAAgD,CAAA;IACpD,IAAI,SAAoD,CAAA;IAExD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,mBAAmB,CAC3B,MAAM,EACN,KAAK,EACL,WAAW,EACX,MAAM,EACN,UAAU,IAAI,IAAI,GAAG,EAAE,EACvB,OAAO,CACR,CAAA;QACD,WAAW,GAAG,CAAC,CAAC,MAAM,CAAA;QACtB,aAAa,GAAG,CAAC,CAAC,aAAa,CAAA;QAC/B,SAAS,GAAG,CAAC,CAAC,SAAS,CAAA;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAC/B,CAAC;IAED,OAAO,QAAQ,CACb,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,EACjC,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,CACjD,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC;IAC7B,YAAY,EAAE,CAAC,YAAY,CAAC;IAC5B,IAAI,CAAC,KAAY,EAAE,MAA+B;QAChD,kBAAkB,CAAC,MAAM,CAAC,CAAA;QAC1B,OAAO,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAClC,CAAC;IACD,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,EAAgB;CAC3E,CAAC,CAAA","sourcesContent":["/**\n * stdlib fillet — fillet 圆角库函数（BREP-only，directEdit 能力）\n *\n * 平台分层（narrowing plan Phase 5，D11）：**中立 op**——`filletWithHistory` 是\n * L1 核心面（brepkit 亦实现），实现全程走 L1（getBrepApi，D12），不声明 engines；\n * capabilities 保留族级 `directEdit`（brepkit 声明 directEdit: true）。\n *\n * 与 chamfer 的差异：fillet 用 filletWithHistory 走面演化 + roleTable 传播\n * （chamfer 在 P5 同步改造）。M1 只支持等半径；M2 计划支持变半径与几何限定符。\n *\n * 设计见 docs/plans/2026-09-10-fillet-op-and-editor-ui.md §2–§3。\n *\n * M1：\n * - 等半径（number）：kernel.filletWithHistory(solid, edges, radius, hashes, bound)\n * - 走 filletWithRoleTable 传播 roleTable（§3.2）\n * - BREP-only：mesh 输入 → E_MESH_UNSUPPORTED（backend-dispatch 静态判定）\n *\n * M2（未实施）：\n * - 变半径 [r1, r2]：filletVariable + 单边 + 不产 roleTable（§3.3 降级）\n * - 几何限定符字符串选边（§4）\n */\n\nimport type { Shape } from '../mesh/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { filletWithRoleTable } from '../brep/face-evolution'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { getCurrentStmt } from '../runtime-state'\nimport { fromBrep, brepOf, inputRoleTable } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { BrepHandle } from '../brep/engine/types'\nimport type { EdgeTopoRef, ResolutionContext } from '../topology/naming'\nimport { resolveTopoRef, TopoRefError } from '../topology/naming'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { buildEdgeResolutionContext } from './topo-resolve'\n\n// ── 参数自校验（stdlib 被直接 import 时的防御层）──\n\n/**\n * Validate fillet parameters: `edges` must be a non-empty array of EdgeTopoRef,\n * each with kind key \"edge\" and a two-entry faces pair; `radius` must be a\n * positive number (M1: uniform radius only).\n * @param params the raw fillet operation parameters.\n */\nexport function assertFilletParams(params: Record<string, unknown>): void {\n  const edges = params.edges\n  if (!Array.isArray(edges) || edges.length === 0) {\n    throw new Error('E_FILLET_NO_EDGES: fillet requires at least one edge')\n  }\n  for (const e of edges) {\n    if (!e || typeof e !== 'object' || (e as { kind?: unknown }).kind !== 'edge') {\n      throw new Error('E_FILLET_BAD_EDGE_REF: every edge entry must be an EdgeTopoRef with kind:\"edge\"')\n    }\n    const faces = (e as { faces?: unknown }).faces\n    if (!Array.isArray(faces) || faces.length !== 2) {\n      throw new Error('E_FILLET_BAD_EDGE_REF: EdgeTopoRef.faces must be a two-entry RoleQualifier pair')\n    }\n  }\n  const radius = params.radius\n  if (typeof radius !== 'number' || !Number.isFinite(radius) || radius <= 0) {\n    throw new Error('E_FILLET_BAD_RADIUS: fillet.radius must be a positive number')\n  }\n}\n\n/** 解析一条 EdgeTopoRef → handle；失败抛命名层 TopoRefError。 */\nfunction resolveEdge(ctx: ResolutionContext, ref: EdgeTopoRef): BrepHandle {\n  const r = resolveTopoRef(ref, ctx)\n  if (r.handle === undefined) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', `fillet: edge resolved without handle (${ref.faces[0].role}/${ref.faces[1].role})`)\n  }\n  return r.handle as BrepHandle\n}\n\n/**\n * 把内核 OcctError 回译成 E_FILLET_RADIUS_TOO_LARGE。\n *\n * OCCT 在半径超过邻面尺寸、三面交汇处、凹边处都可能失败。\n * 绝不可静默返回未圆角的原形状（§9 风险）。\n */\nfunction translateOcctError(err: unknown): Error {\n  const msg = err instanceof Error ? err.message : String(err)\n  if (msg.includes('E_FILLET') || msg.includes('E_TOPO')) return err as Error\n  return new Error(`E_FILLET_RADIUS_TOO_LARGE: OCCT fillet failed — ${msg}`)\n}\n\n/** BREP-only 主入口（M1 等半径 flow）。 */\nfunction filletBrep(input: Shape, params: Record<string, unknown>): Shape {\n  // L1 面（D12）：filletWithHistory 是 L1，全链路中立。\n  const kernel = getBrepApi()\n  const solid = brepOf(input) as BrepHandle | undefined\n  if (!solid) throw new Error('E_FILLET_NO_BREP: fillet input is not BREP')\n\n  const edges = params.edges as EdgeTopoRef[]\n  const radius = params.radius as number\n  const ctx = buildEdgeResolutionContext(kernel, input as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', 'fillet: input has no edge naming context')\n\n  // 解析所有 EdgeTopoRef → Edge 句柄\n  const edgeHandles = edges.map((e) => resolveEdge(ctx, e))\n\n  // 输入 roleTable + outStmt（与 boolean.ts 同构）。Phase 1.6：origin=本次语句 StmtId。\n  const inputTable = inputRoleTable(input) as ReadonlyMap<unknown, unknown> | undefined\n  const outStmt = String(getCurrentStmt()?.id ?? '')\n\n  let resultSolid: BrepHandle\n  let faceEvolution: Map<number, number[]> | undefined\n  let roleTable: ReadonlyMap<unknown, unknown> | undefined\n\n  try {\n    const r = filletWithRoleTable(\n      kernel,\n      solid,\n      edgeHandles,\n      radius,\n      inputTable ?? new Map(),\n      outStmt,\n    )\n    resultSolid = r.result\n    faceEvolution = r.faceEvolution\n    roleTable = r.roleTable\n  } catch (err) {\n    throw translateOcctError(err)\n  }\n\n  return fromBrep(\n    solidToShape(kernel, resultSolid),\n    { solid: resultSolid, faceEvolution, roleTable },\n  )\n}\n\n/**\n * 在几何体上做圆角（等半径）。仅 BREP 可用。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name fillet\n * @note 圆角是 BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。`radius` 为正数（mm）。\n *       圆角后 roleTable 经 filletWithHistory 传播，保证后续特征仍可按 role 选面/选边。\n * @returns Shape 圆角后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param params.edges - 参与圆角的边（EdgeTopoRef[]，条目为相邻两面的 role 线路）。type:EdgeTopoRef[] required:true\n * @param params.radius - 圆角半径（mm，>0）。type:number required:true\n * @example\n * const p = await cad.fillet(part0, { edges: [{ kind:'edge', faces:[{ origin:'box', role:'box:top' }, { origin:'box', role:'box:front' }], hint:{ kind:'edge' } }], radius:2 })\n */\nexport const fillet = defineOp({\n  capabilities: ['directEdit'],\n  brep(input: Shape, params: Record<string, unknown>) {\n    assertFilletParams(params)\n    return filletBrep(input, params)\n  },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}
+{"version":3,"file":"fillet.js","sourceRoot":"","sources":["../../src/api/fillet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAGjC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAgBhH;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA+B,EAC/B,IAA+B;IAE/B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;IAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,IAAI,EAAE,aAAa,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YACjD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAA;YAChG,CAAC;YACD,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAAwB,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC7E,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAA;QACpG,CAAC;QACD,MAAM,KAAK,GAAI,CAAyB,CAAC,KAAK,CAAA;QAC9C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAA;QACpG,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;IAC5B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAA;IACjF,CAAC;AACH,CAAC;AAED,qDAAqD;AACrD,SAAS,WAAW,CAAC,GAAsB,EAAE,GAAgB;IAC3D,MAAM,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAClC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,yCAAyC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAA;IACxI,CAAC;IACD,OAAO,CAAC,CAAC,MAAoB,CAAA;AAC/B,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,GAAY;IACtC,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC5D,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,GAAY,CAAA;IAC3E,OAAO,IAAI,KAAK,CAAC,mDAAmD,GAAG,EAAE,CAAC,CAAA;AAC5E,CAAC;AAED,kCAAkC;AAClC,SAAS,UAAU,CAAC,KAAY,EAAE,MAA+B;IAC/D,0CAA0C;IAC1C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAA2B,CAAA;IACrD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAA;IAEzE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAsB,CAAA;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAgB,CAAA;IACtC,MAAM,GAAG,GAAG,0BAA0B,CAAC,MAAM,EAAE,KAAe,CAAC,CAAA;IAC/D,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,0CAA0C,CAAC,CAAA;IAExG,6BAA6B;IAC7B,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAA;IAEzD,wEAAwE;IACxE,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAA8C,CAAA;IACrF,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IAElD,IAAI,WAAuB,CAAA;IAC3B,IAAI,aAAgD,CAAA;IACpD,IAAI,SAAoD,CAAA;IAExD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,mBAAmB,CAC3B,MAAM,EACN,KAAK,EACL,WAAW,EACX,MAAM,EACN,UAAU,IAAI,IAAI,GAAG,EAAE,EACvB,OAAO,CACR,CAAA;QACD,WAAW,GAAG,CAAC,CAAC,MAAM,CAAA;QACtB,aAAa,GAAG,CAAC,CAAC,aAAa,CAAA;QAC/B,SAAS,GAAG,CAAC,CAAC,SAAS,CAAA;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAC/B,CAAC;IAED,OAAO,QAAQ,CACb,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,EACjC,EAAE,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,CACjD,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,eAAe,CAAC,KAAY,EAAE,MAA+B;IACpE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAiC,CAAA;IACtD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAgB,CAAA;IACtC,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;IAC7C,MAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAA;IAE5D,IAAI,MAAkB,CAAA;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,CAAA;IAChE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,iBAAiB,CACrB,QAAQ,EACR,2BAA2B,EAC3B,YAAY,MAAM,QAAQ,WAAW,CAAC,MAAM,UAAU,EACtD,KAAK,CACN,CAAA;IACH,CAAC;IACD,OAAO,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,QAAQ,CAAC;IAC7B,YAAY,EAAE,CAAC,YAAY,CAAC;IAC5B,WAAW,EAAE,CAAC,SAAS,CAAC;IACxB,IAAI,CAAC,KAAY,EAAE,MAA+B;QAChD,kBAAkB,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;QACnD,OAAO,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACvC,CAAC;IACD,IAAI,CAAC,KAAY,EAAE,MAA+B;QAChD,kBAAkB,CAAC,MAAM,CAAC,CAAA;QAC1B,OAAO,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAClC,CAAC;IACD,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,EAAgB;CAC3E,CAAC,CAAA","sourcesContent":["/**\n * api fillet — fillet 圆角库函数（BREP-only，directEdit 能力）\n *\n * 平台分层（narrowing plan Phase 5，D11）：**中立 op**——`filletWithHistory` 是\n * L1 核心面（brepkit 亦实现），实现全程走 L1（getBrepApi，D12），不声明 engines；\n * capabilities 保留族级 `directEdit`（brepkit 声明 directEdit: true）。\n *\n * 与 chamfer 的差异：fillet 用 filletWithHistory 走面演化 + roleTable 传播\n * （chamfer 在 P5 同步改造）。M1 只支持等半径；M2 计划支持变半径与几何限定符。\n *\n * 设计见 docs/plans/2026-09-10-fillet-op-and-editor-ui.md §2–§3。\n *\n * M1：\n * - 等半径（number）：kernel.filletWithHistory(solid, edges, radius, hashes, bound)\n * - 走 filletWithRoleTable 传播 roleTable（§3.2）\n * - BREP-only：mesh 输入 → E_MESH_UNSUPPORTED（backend-dispatch 静态判定）\n *\n * M2（未实施）：\n * - 变半径 [r1, r2]：filletVariable + 单边 + 不产 roleTable（§3.3 降级）\n * - 几何限定符字符串选边（§4）\n */\n\nimport type { Shape } from '../mesh/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { filletWithRoleTable } from '../brep/face-evolution'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { getCurrentStmt } from '../runtime-state'\nimport { fromBrep, brepOf, inputRoleTable } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { BrepHandle } from '../brep/engine/types'\nimport type { EdgeTopoRef, ResolutionContext } from '../topology/naming'\nimport { resolveTopoRef, TopoRefError } from '../topology/naming'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { buildEdgeResolutionContext } from './topo-resolve'\nimport { meshKernelFailure, meshSolidEntry, meshSolidProduct, resolveMeshEdges } from './internal/mesh-solid-op'\n\n// ── 参数自校验（api 层被直接 import 时的防御层）──\n\n/** 边选择器校验选项。 */\nexport interface EdgeSelectorCheckOptions {\n  /**\n   * 允许 1 起序号作为边选择器（**仅网格链**；见 `resolveMeshEdges`）。\n   *\n   * 精度链不开这个口子：BREP 的边身份是 role 线路（两个相邻面的 `(origin, role)`），\n   * 序号只是内核枚举序，跨特征会漂移——让精度链接受序号等于把\"可重放的引用\"降级成\n   * \"这次跑出来的下标\"。近似链相反：没有 role 层，序号是唯一无歧义的指认方式。\n   */\n  readonly allowOrdinals?: boolean\n}\n\n/**\n * Validate fillet parameters: `edges` must be a non-empty array of EdgeTopoRef\n * (each with kind key \"edge\" and a two-entry faces pair) — or of 1-based\n * ordinals when `opts.allowOrdinals` (the mesh chain); `radius` must be a\n * positive number (M1: uniform radius only).\n * @param params the raw fillet operation parameters.\n * @param opts the selector-form options (mesh chain allows ordinals).\n */\nexport function assertFilletParams(\n  params: Record<string, unknown>,\n  opts?: EdgeSelectorCheckOptions,\n): void {\n  const edges = params.edges\n  if (!Array.isArray(edges) || edges.length === 0) {\n    throw new Error('E_FILLET_NO_EDGES: fillet requires at least one edge')\n  }\n  for (const e of edges) {\n    if (opts?.allowOrdinals && typeof e === 'number') {\n      if (!Number.isInteger(e) || e < 1) {\n        throw new Error('E_FILLET_BAD_EDGE_REF: an edge ordinal must be a positive integer (1-based)')\n      }\n      continue\n    }\n    if (!e || typeof e !== 'object' || (e as { kind?: unknown }).kind !== 'edge') {\n      throw new Error('E_FILLET_BAD_EDGE_REF: every edge entry must be an EdgeTopoRef with kind:\"edge\"')\n    }\n    const faces = (e as { faces?: unknown }).faces\n    if (!Array.isArray(faces) || faces.length !== 2) {\n      throw new Error('E_FILLET_BAD_EDGE_REF: EdgeTopoRef.faces must be a two-entry RoleQualifier pair')\n    }\n  }\n  const radius = params.radius\n  if (typeof radius !== 'number' || !Number.isFinite(radius) || radius <= 0) {\n    throw new Error('E_FILLET_BAD_RADIUS: fillet.radius must be a positive number')\n  }\n}\n\n/** 解析一条 EdgeTopoRef → handle；失败抛命名层 TopoRefError。 */\nfunction resolveEdge(ctx: ResolutionContext, ref: EdgeTopoRef): BrepHandle {\n  const r = resolveTopoRef(ref, ctx)\n  if (r.handle === undefined) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', `fillet: edge resolved without handle (${ref.faces[0].role}/${ref.faces[1].role})`)\n  }\n  return r.handle as BrepHandle\n}\n\n/**\n * 把内核 OcctError 回译成 E_FILLET_RADIUS_TOO_LARGE。\n *\n * OCCT 在半径超过邻面尺寸、三面交汇处、凹边处都可能失败。\n * 绝不可静默返回未圆角的原形状（§9 风险）。\n */\nfunction translateOcctError(err: unknown): Error {\n  const msg = err instanceof Error ? err.message : String(err)\n  if (msg.includes('E_FILLET') || msg.includes('E_TOPO')) return err as Error\n  return new Error(`E_FILLET_RADIUS_TOO_LARGE: OCCT fillet failed — ${msg}`)\n}\n\n/** BREP-only 主入口（M1 等半径 flow）。 */\nfunction filletBrep(input: Shape, params: Record<string, unknown>): Shape {\n  // L1 面（D12）：filletWithHistory 是 L1，全链路中立。\n  const kernel = getBrepApi()\n  const solid = brepOf(input) as BrepHandle | undefined\n  if (!solid) throw new Error('E_FILLET_NO_BREP: fillet input is not BREP')\n\n  const edges = params.edges as EdgeTopoRef[]\n  const radius = params.radius as number\n  const ctx = buildEdgeResolutionContext(kernel, input as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', 'fillet: input has no edge naming context')\n\n  // 解析所有 EdgeTopoRef → Edge 句柄\n  const edgeHandles = edges.map((e) => resolveEdge(ctx, e))\n\n  // 输入 roleTable + outStmt（与 boolean.ts 同构）。Phase 1.6：origin=本次语句 StmtId。\n  const inputTable = inputRoleTable(input) as ReadonlyMap<unknown, unknown> | undefined\n  const outStmt = String(getCurrentStmt()?.id ?? '')\n\n  let resultSolid: BrepHandle\n  let faceEvolution: Map<number, number[]> | undefined\n  let roleTable: ReadonlyMap<unknown, unknown> | undefined\n\n  try {\n    const r = filletWithRoleTable(\n      kernel,\n      solid,\n      edgeHandles,\n      radius,\n      inputTable ?? new Map(),\n      outStmt,\n    )\n    resultSolid = r.result\n    faceEvolution = r.faceEvolution\n    roleTable = r.roleTable\n  } catch (err) {\n    throw translateOcctError(err)\n  }\n\n  return fromBrep(\n    solidToShape(kernel, resultSolid),\n    { solid: resultSolid, faceEvolution, roleTable },\n  )\n}\n\n/**\n * 网格实体路径：对近似拓扑里识别出的边倒圆角（方案 2026-10-01 §3.5 三明治）。\n *\n * 与 BREP 路径的三处实质差异，都是\"网格零件没有精度链、没有 role 层\"的直接后果：\n * - 边**按几何或序号**解析：`EdgeTopoRef` 走长度/中点匹配；**1 起序号**直接取自近似\n *   拓扑的 `edges` 数组下标 + 1（等长边靠几何分不开，序号是唯一无歧义的指认方式）；\n * - 内核调用走 L1 裸 `kernel.fillet`（`filletWithHistory` 是精度链的面演化能力，\n *   近似拓扑没有 hash 演化可言，故**不产生** faceEvolution / roleTable，如实缺席\n *   而不是造一张恒等映射）；\n * - 产物句柄写回后由 `meshSolidProduct` 重新三角化并重建近似拓扑。\n *\n * GOTCHA（2026-10-01 实测，见 `brepkit-kernel/mesh-solid-topology.test.ts`）：\n * 一次请求里的**全部**边交给内核，会在共面边链（如圆柱端盖的 64 条边）上被整体\n * 拒绝——不是单条边不可倒，而是\"一次性磨圆会自交\"。故本实现**如实失败**，不自动\n * 拆成逐边重试（运行时换策略会掩盖几何事实）。要给共面边链倒角，请分多次调用，\n * 每次一组几何上互不相邻的边。\n *\n * @param input - the mesh-solid input.\n * @param params - the validated fillet parameters.\n * @returns the filleted mesh solid as a new mesh part.\n */\nfunction filletMeshSolid(input: Shape, params: Record<string, unknown>): Shape {\n  const edges = params.edges as (number | EdgeTopoRef)[]\n  const radius = params.radius as number\n  const entry = meshSolidEntry(input, 'fillet')\n  const edgeHandles = resolveMeshEdges(entry, edges, 'fillet')\n\n  let result: BrepHandle\n  try {\n    result = entry.kernel.fillet(entry.solid, edgeHandles, radius)\n  } catch (cause) {\n    throw meshKernelFailure(\n      'fillet',\n      'E_FILLET_RADIUS_TOO_LARGE',\n      `fillet(r=${radius}) on ${edgeHandles.length} edge(s)`,\n      cause,\n    )\n  }\n  return meshSolidProduct(entry, result)\n}\n\n/**\n * 在几何体上做圆角（等半径）。\n *\n * 两条路径都以 `meshEngines: ['brepkit']` 之外的事实为界：BREP 输入走\n * `filletWithHistory`（带面演化与 roleTable 传播）；**网格实体**输入走网格后端\n * （近似拓扑无 role，边按几何或序号解析，无面演化）。非 BREP 的**裸网格**输入仍抛\n * `E_MESH_SOLID_UNSUPPORTED`——裸网格没有近似拓扑，没有边可选。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name fillet\n * @note `radius` 为正数（mm）。BREP 路径圆角后 roleTable 经 filletWithHistory 传播，\n *       后续特征仍可按 role 选面/选边；网格实体路径没有 role 层，边只能按几何或\n *       序号（近似拓扑 `edges` 数组下标 + 1）指认。\n * @returns Shape 圆角后的几何。\n * @param input - 目标几何。type:Shape required:true\n * @param params.edges - 参与圆角的边：相邻两面的 role 线路（EdgeTopoRef[]）；网格链上也可用 1 起序号。type:EdgeTopoRef[] required:true\n * @param params.radius - 圆角半径（mm，>0）。type:number required:true\n * @example\n * const p = await cad.fillet(part0, { edges: [{ kind:'edge', faces:[{ origin:'box', role:'box:top' }, { origin:'box', role:'box:front' }], hint:{ kind:'edge' } }], radius:2 })\n * const q = await cad.fillet(meshPart, { edges: [3], radius: 1 })\n */\nexport const fillet = defineOp({\n  capabilities: ['directEdit'],\n  meshEngines: ['brepkit'],\n  mesh(input: Shape, params: Record<string, unknown>) {\n    assertFilletParams(params, { allowOrdinals: true })\n    return filletMeshSolid(input, params)\n  },\n  brep(input: Shape, params: Record<string, unknown>) {\n    assertFilletParams(params)\n    return filletBrep(input, params)\n  },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}

package/dist/api/generated/script-face-manifest.d.ts

@@ -11,6 +11,10 @@ export interface ScriptFaceOp {
     module: string;
     /** Phase 5（D11）：平台 op 的平台身份（中立 op 缺省）。 */
     engines?: readonly string[];
+    /** P26 (unit-system D8)：参数量纲声明（参数名 → DimName）。 */
+    paramDims?: Record<string, string>;
+    /** P26 (unit-system D8)：返回值量纲。 */
+    retDim?: string;
 }
 /** Cad script-face op manifest (B1: single source for cad namespace, check() symbol table). */
 export declare const SCRIPT_FACE_OPS: readonly ScriptFaceOp[];

package/dist/api/generated/script-face-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script-face-manifest.d.ts","sourceRoot":"","sources":["../../../src/api/generated/script-face-manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uBAAuB;AACvB,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5B;AAED,+FAA+F;AAC/F,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAyClD,CAAA"}
+{"version":3,"file":"script-face-manifest.d.ts","sourceRoot":"","sources":["../../../src/api/generated/script-face-manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uBAAuB;AACvB,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,+FAA+F;AAC/F,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAyClD,CAAA"}

package/dist/api/generated/script-face-manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"script-face-manifest.js","sourceRoot":"","sources":["../../../src/api/generated/script-face-manifest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * generated/script-face-manifest.ts — 生成文件，禁手改。\n * 由 packages/core/scripts/gen-l3-surface.ts 依据 api/surface/arg-spec.ts 生成。\n * cad 脚本面新增 op 清单（P23 B1 三源一致：导出面 ≡ cad 面 ≡ check() 符号表）。\n */\n\n/** 一条 cad 脚本面新增 op。 */\nexport interface ScriptFaceOp {\n  /** faijs 面导出名（= brepjs 符号名）。 */\n  name: string\n  /** 所属分片模块（生成文件名）。 */\n  module: string\n  /** Phase 5（D11）：平台 op 的平台身份（中立 op 缺省）。 */\n  engines?: readonly string[]\n}\n\n/** Cad script-face op manifest (B1: single source for cad namespace, check() symbol table). */\nexport const SCRIPT_FACE_OPS: readonly ScriptFaceOp[] = [\n  { name: 'torus', module: 'topology' },\n  { name: 'fuse', module: 'topology', engines: [\"occt\"] },\n  { name: 'inspectMassProps', module: 'measurement', engines: [\"occt\"] },\n  { name: 'area', module: 'measurement' },\n  { name: 'length', module: 'measurement' },\n  { name: 'volume', module: 'measurement' },\n  { name: 'centerOfMass', module: 'measurement' },\n  { name: 'viewCamera', module: 'view' },\n  { name: 'projectView', module: 'view' },\n  { name: 'projectSheet', module: 'view' },\n  { name: 'complexExtrude', module: 'operations', engines: [\"occt\"] },\n  { name: 'twistExtrude', module: 'operations', engines: [\"occt\"] },\n  { name: 'linearPattern', module: 'operations', engines: [\"occt\"] },\n  { name: 'circularPattern', module: 'operations', engines: [\"occt\"] },\n  { name: 'gridPattern', module: 'operations', engines: [\"occt\"] },\n  { name: 'roof', module: 'operations' },\n  { name: 'drill', module: 'operations' },\n  { name: 'pocket', module: 'operations' },\n  { name: 'boss', module: 'operations' },\n  { name: 'mirrorJoin', module: 'operations' },\n  { name: 'rectangularPattern', module: 'operations', engines: [\"occt\"] },\n  { name: 'thread', module: 'operations', engines: [\"occt\"] },\n  { name: 'convexHull', module: 'operations' },\n  { name: 'makeBaseBox', module: 'sketching' },\n  { name: 'ellipsoid', module: 'topology' },\n  { name: 'rotate', module: 'topology' },\n  { name: 'mirror', module: 'topology' },\n  { name: 'clone', module: 'topology' },\n  { name: 'applyMatrix', module: 'topology' },\n  { name: 'locate', module: 'topology' },\n  { name: 'split', module: 'topology', engines: [\"occt\"] },\n  { name: 'offset', module: 'topology', engines: [\"occt\"] },\n  { name: 'heal', module: 'topology', engines: [\"occt\"] },\n  { name: 'simplify', module: 'topology', engines: [\"occt\"] },\n  { name: 'isValid', module: 'topology' },\n  { name: 'isSameShape', module: 'topology' },\n  { name: 'autoHeal', module: 'topology', engines: [\"occt\"] },\n  { name: 'fixShape', module: 'topology' },\n  { name: 'healSolid', module: 'topology' },\n  { name: 'fixSelfIntersection', module: 'topology', engines: [\"occt\"] },\n]\n"]}
+{"version":3,"file":"script-face-manifest.js","sourceRoot":"","sources":["../../../src/api/generated/script-face-manifest.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * generated/script-face-manifest.ts — 生成文件，禁手改。\n * 由 packages/core/scripts/gen-l3-surface.ts 依据 api/surface/arg-spec.ts 生成。\n * cad 脚本面新增 op 清单（P23 B1 三源一致：导出面 ≡ cad 面 ≡ check() 符号表）。\n */\n\n/** 一条 cad 脚本面新增 op。 */\nexport interface ScriptFaceOp {\n  /** faijs 面导出名（= brepjs 符号名）。 */\n  name: string\n  /** 所属分片模块（生成文件名）。 */\n  module: string\n  /** Phase 5（D11）：平台 op 的平台身份（中立 op 缺省）。 */\n  engines?: readonly string[]\n  /** P26 (unit-system D8)：参数量纲声明（参数名 → DimName）。 */\n  paramDims?: Record<string, string>\n  /** P26 (unit-system D8)：返回值量纲。 */\n  retDim?: string\n}\n\n/** Cad script-face op manifest (B1: single source for cad namespace, check() symbol table). */\nexport const SCRIPT_FACE_OPS: readonly ScriptFaceOp[] = [\n  { name: 'torus', module: 'topology' },\n  { name: 'fuse', module: 'topology', engines: [\"occt\"] },\n  { name: 'inspectMassProps', module: 'measurement', engines: [\"occt\"] },\n  { name: 'area', module: 'measurement' },\n  { name: 'length', module: 'measurement' },\n  { name: 'volume', module: 'measurement' },\n  { name: 'centerOfMass', module: 'measurement' },\n  { name: 'viewCamera', module: 'view' },\n  { name: 'projectView', module: 'view' },\n  { name: 'projectSheet', module: 'view' },\n  { name: 'complexExtrude', module: 'operations', engines: [\"occt\"] },\n  { name: 'twistExtrude', module: 'operations', engines: [\"occt\"] },\n  { name: 'linearPattern', module: 'operations', engines: [\"occt\"] },\n  { name: 'circularPattern', module: 'operations', engines: [\"occt\"] },\n  { name: 'gridPattern', module: 'operations', engines: [\"occt\"] },\n  { name: 'roof', module: 'operations' },\n  { name: 'drill', module: 'operations' },\n  { name: 'pocket', module: 'operations' },\n  { name: 'boss', module: 'operations' },\n  { name: 'mirrorJoin', module: 'operations' },\n  { name: 'rectangularPattern', module: 'operations', engines: [\"occt\"] },\n  { name: 'thread', module: 'operations', engines: [\"occt\"] },\n  { name: 'convexHull', module: 'operations' },\n  { name: 'makeBaseBox', module: 'sketching' },\n  { name: 'ellipsoid', module: 'topology' },\n  { name: 'rotate', module: 'topology' },\n  { name: 'mirror', module: 'topology' },\n  { name: 'clone', module: 'topology' },\n  { name: 'applyMatrix', module: 'topology' },\n  { name: 'locate', module: 'topology' },\n  { name: 'split', module: 'topology', engines: [\"occt\"] },\n  { name: 'offset', module: 'topology', engines: [\"occt\"] },\n  { name: 'heal', module: 'topology', engines: [\"occt\"] },\n  { name: 'simplify', module: 'topology', engines: [\"occt\"] },\n  { name: 'isValid', module: 'topology' },\n  { name: 'isSameShape', module: 'topology' },\n  { name: 'autoHeal', module: 'topology', engines: [\"occt\"] },\n  { name: 'fixShape', module: 'topology' },\n  { name: 'healSolid', module: 'topology' },\n  { name: 'fixSelfIntersection', module: 'topology', engines: [\"occt\"] },\n]\n"]}

package/dist/api/geom.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib geom — $geom 查询函数族（有形签名）
+ * api geom — $geom 查询函数族（有形签名）
  *
  *
  * `cad.<feature>(of, anchor?, ordinal?)`：

package/dist/api/geom.js

@@ -1,5 +1,5 @@
 /**
- * stdlib geom — $geom 查询函数族（有形签名）
+ * api geom — $geom 查询函数族（有形签名）
  *
  *
  * `cad.<feature>(of, anchor?, ordinal?)`：

package/dist/api/geom.js.map

@@ -1 +1 @@
-{"version":3,"file":"geom.js","sourceRoot":"","sources":["../../src/api/geom.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib geom — $geom 查询函数族（有形签名）\n *\n *\n * `cad.<feature>(of, anchor?, ordinal?)`：\n * - of 是 Shape（编译产物 `ctx.<var>` 引用），非变量名\n * - faceNormal：faceOrdinal + brepOf(of) + kernel（拓扑引用）\n *   优先 → anchor 几何反查（兜底）→ 报错\n * - bboxCenter/bboxMin/bboxMax：mesh 包围盒查询\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { brepOf } from '../shape'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/** 内部实现：faceNormal 专用——faceOrdinal+BREP 优先 → anchor 反查 → 报错（逻辑迁移自 resolveGeomRef）。 */\nfunction geomQuery(\n  of: Shape,\n  anchor: Vec3 | undefined,\n  faceOrdinal: number | undefined,\n): Vec3 {\n  // 优先路径：faceOrdinal 拓扑引用（BREP 路径）\n  if (faceOrdinal !== undefined) {\n    const solid = brepOf(of) as BrepHandle | undefined\n    const kernel = getBrepApi()\n    if (solid && kernel) {\n      try {\n        const faces = kernel.getSubShapes(solid, 'face')\n        if (faceOrdinal < faces.length) {\n          const face = faces[faceOrdinal]\n          // 面法向：用 surfaceNormal 在 (0.5, 0.5) 处取\n          let normal: Vec3 = [0, 0, 1]\n          try {\n            const n = kernel.surfaceNormal(face, 0.5, 0.5)\n            normal = [n.x, n.y, n.z]\n          } catch {\n            // surfaceNormal 可能对某些面失败，用默认法向\n          }\n          kernel.release(face)\n          for (let i = 0; i < faces.length; i++) {\n            if (i !== faceOrdinal) kernel.release(faces[i])\n          }\n          return normal\n        }\n        // ordinal 越界 → 释放并降级到 anchor\n        for (const f of faces) kernel.release(f)\n      } catch {\n        // BREP 取面失败 → 降级到 anchor\n      }\n    }\n  }\n\n  // 兜底路径：anchor 几何反查\n  if (!anchor) {\n    throw new Error('[GeomRef] faceNormal requires anchor or faceOrdinal')\n  }\n  const face = cad.faceAt(of, { point: anchor })\n  if (!face) {\n    throw new Error(`[GeomRef] faceAt failed for anchor at ${anchor}`)\n  }\n  return face.normal\n}\n\n/**\n * 查询面上某点（锚点）的法向。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name faceNormal\n * @returns Vec3 面上锚点处的法向 [x,y,z]。\n * @param of - 目标几何（编译产物 ctx.<var> 引用）。type:Shape required:true\n * @param anchor - 锚点（几何反查兜底）。type:[x,y,z]\n * @param ordinal - 面序号（BREP 拓扑引用优先）。type:number\n * @example\n * const n = cad.faceNormal(part0, [0, 0, 5])\n  */\nexport function faceNormal(of: Shape, anchor?: Vec3, ordinal?: number): Vec3 {\n  return geomQuery(of, anchor, ordinal)\n}\n\n/**\n * 查询几何包围盒中心。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxCenter\n * @returns Vec3 包围盒中心 [x,y,z]。交互式可编辑（参数量引用）。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const c = cad.bboxCenter(part0)\n  */\nexport function bboxCenter(of: Shape): Vec3 {\n  return cad.bboxCenter(of)\n}\n\n/**\n * 查询几何包围盒最小角点。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxMin\n * @returns Vec3 包围盒最小角点 [x,y,z]。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const mn = cad.bboxMin(part0)\n  */\nexport function bboxMin(of: Shape): Vec3 {\n  return cad.boundingBox(of).min\n}\n\n/**\n * 查询几何包围盒最大角点。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxMax\n * @returns Vec3 包围盒最大角点 [x,y,z]。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const mx = cad.bboxMax(part0)\n  */\nexport function bboxMax(of: Shape): Vec3 {\n  return cad.boundingBox(of).max\n}\n"]}
+{"version":3,"file":"geom.js","sourceRoot":"","sources":["../../src/api/geom.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api geom — $geom 查询函数族（有形签名）\n *\n *\n * `cad.<feature>(of, anchor?, ordinal?)`：\n * - of 是 Shape（编译产物 `ctx.<var>` 引用），非变量名\n * - faceNormal：faceOrdinal + brepOf(of) + kernel（拓扑引用）\n *   优先 → anchor 几何反查（兜底）→ 报错\n * - bboxCenter/bboxMin/bboxMax：mesh 包围盒查询\n */\n\nimport type { Shape, Vec3 } from '../mesh/types'\nimport { cad } from '../mesh'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { brepOf } from '../shape'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/** 内部实现：faceNormal 专用——faceOrdinal+BREP 优先 → anchor 反查 → 报错（逻辑迁移自 resolveGeomRef）。 */\nfunction geomQuery(\n  of: Shape,\n  anchor: Vec3 | undefined,\n  faceOrdinal: number | undefined,\n): Vec3 {\n  // 优先路径：faceOrdinal 拓扑引用（BREP 路径）\n  if (faceOrdinal !== undefined) {\n    const solid = brepOf(of) as BrepHandle | undefined\n    const kernel = getBrepApi()\n    if (solid && kernel) {\n      try {\n        const faces = kernel.getSubShapes(solid, 'face')\n        if (faceOrdinal < faces.length) {\n          const face = faces[faceOrdinal]\n          // 面法向：用 surfaceNormal 在 (0.5, 0.5) 处取\n          let normal: Vec3 = [0, 0, 1]\n          try {\n            const n = kernel.surfaceNormal(face, 0.5, 0.5)\n            normal = [n.x, n.y, n.z]\n          } catch {\n            // surfaceNormal 可能对某些面失败，用默认法向\n          }\n          kernel.release(face)\n          for (let i = 0; i < faces.length; i++) {\n            if (i !== faceOrdinal) kernel.release(faces[i])\n          }\n          return normal\n        }\n        // ordinal 越界 → 释放并降级到 anchor\n        for (const f of faces) kernel.release(f)\n      } catch {\n        // BREP 取面失败 → 降级到 anchor\n      }\n    }\n  }\n\n  // 兜底路径：anchor 几何反查\n  if (!anchor) {\n    throw new Error('[GeomRef] faceNormal requires anchor or faceOrdinal')\n  }\n  const face = cad.faceAt(of, { point: anchor })\n  if (!face) {\n    throw new Error(`[GeomRef] faceAt failed for anchor at ${anchor}`)\n  }\n  return face.normal\n}\n\n/**\n * 查询面上某点（锚点）的法向。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name faceNormal\n * @returns Vec3 面上锚点处的法向 [x,y,z]。\n * @param of - 目标几何（编译产物 ctx.<var> 引用）。type:Shape required:true\n * @param anchor - 锚点（几何反查兜底）。type:[x,y,z]\n * @param ordinal - 面序号（BREP 拓扑引用优先）。type:number\n * @example\n * const n = cad.faceNormal(part0, [0, 0, 5])\n  */\nexport function faceNormal(of: Shape, anchor?: Vec3, ordinal?: number): Vec3 {\n  return geomQuery(of, anchor, ordinal)\n}\n\n/**\n * 查询几何包围盒中心。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxCenter\n * @returns Vec3 包围盒中心 [x,y,z]。交互式可编辑（参数量引用）。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const c = cad.bboxCenter(part0)\n  */\nexport function bboxCenter(of: Shape): Vec3 {\n  return cad.bboxCenter(of)\n}\n\n/**\n * 查询几何包围盒最小角点。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxMin\n * @returns Vec3 包围盒最小角点 [x,y,z]。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const mn = cad.bboxMin(part0)\n  */\nexport function bboxMin(of: Shape): Vec3 {\n  return cad.boundingBox(of).min\n}\n\n/**\n * 查询几何包围盒最大角点。\n * @group 查询\n * @inputs 1\n * @async false\n * @qual ok\n * @name bboxMax\n * @returns Vec3 包围盒最大角点 [x,y,z]。\n * @param of - 目标几何。type:Shape required:true\n * @example\n * const mx = cad.bboxMax(part0)\n  */\nexport function bboxMax(of: Shape): Vec3 {\n  return cad.boundingBox(of).max\n}\n"]}

package/dist/api/helix.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib helix — 螺旋线（1D 曲线，平台 op engines:['occt']）
+ * api helix — 螺旋线（1D 曲线，平台 op engines:['occt']）
  *
  * @platform occt — 本文件 import occt-kernel：螺旋线用 `makeHelixWire` 构造
  * （occt-wasm 原生有，L1 无）。守卫 ① 要求平台 import 自证身份；调用方 op 声明

package/dist/api/helix.js

@@ -1,5 +1,5 @@
 /**
- * stdlib helix — 螺旋线（1D 曲线，平台 op engines:['occt']）
+ * api helix — 螺旋线（1D 曲线，平台 op engines:['occt']）
  *
  * @platform occt — 本文件 import occt-kernel：螺旋线用 `makeHelixWire` 构造
  * （occt-wasm 原生有，L1 无）。守卫 ① 要求平台 import 自证身份；调用方 op 声明

package/dist/api/helix.js.map

@@ -1 +1 @@
-{"version":3,"file":"helix.js","sourceRoot":"","sources":["../../src/api/helix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAgBzD,sDAAsD;AACtD,SAAS,SAAS,CAAC,IAAkB;IACnC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IACrC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC5E,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAChF,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;IACzE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAC/B,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAC5C,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EACtC,KAAK,EACL,MAAM,EACN,MAAM,CACkB,CAAA;IAC1B,OAAO,aAAa,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,IAAI,CAAC,IAAkB;QACrB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,sCAAsC,EAAgB;CAC5F,CAAC,CAAA","sourcesContent":["/**\n * stdlib helix — 螺旋线（1D 曲线，平台 op engines:['occt']）\n *\n * @platform occt — 本文件 import occt-kernel：螺旋线用 `makeHelixWire` 构造\n * （occt-wasm 原生有，L1 无）。守卫 ① 要求平台 import 自证身份；调用方 op 声明\n * `engines: ['occt']` 由守卫 ② 校验。\n *\n * 用途：G-D 门控层的 1D 造线能力（Phase 3）。下游 sweep / loft 等可用螺旋线作 spine。\n *\n * 设计：\n * - 平台 op：occt 原生 makeHelixWire（occt-wasm 有，L1 无）→ 声明 engines:['occt']（D11）。\n *   不声明 capabilities：实现直连平台原生方法，能力由引擎身份本身界定。\n * - 1D 产物：经 fromBrepCurve 登记，kind='curve'。\n * - 非 occt 引擎（brepkit）→ 执行前 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3\n *   豁免不拦截（且 getOcctKernel 为全局 occt 实例，brep_mock 下仍可真实出线）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrepCurve } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\n/** `cad.helix` 参数。 */\nexport interface HelixOptions {\n  /** 螺旋半径（mm，>0）。 */\n  radius: number\n  /** 螺距（mm，每圈沿轴的推进量，≠0）。 */\n  pitch: number\n  /** 圈数（>0）。 */\n  turns: number\n  /** 螺旋轴方向（单位向量，默认 +Z）。 */\n  axis?: [number, number, number]\n  /** 起点（默认原点）。 */\n  origin?: [number, number, number]\n}\n\n/** BREP 路径：用 occt 原生 makeHelixWire 构造螺旋线，登记 1D 句柄。 */\nfunction helixBrep(opts: HelixOptions): Shape {\n  const { radius, pitch, turns } = opts\n  if (!(radius > 0)) throw new Error('E_HELIX_BAD_RADIUS: radius must be > 0')\n  if (!(pitch !== 0)) throw new Error('E_HELIX_BAD_PITCH: pitch must be non-zero')\n  if (!(turns > 0)) throw new Error('E_HELIX_BAD_TURNS: turns must be > 0')\n  const axis = opts.axis ?? [0, 0, 1]\n  const origin = opts.origin ?? [0, 0, 0]\n  const height = pitch * turns\n  const kernel = getBrepApi()\n  const occt = getOcctKernel()\n  const handle = occt.makeHelixWire(\n    { x: origin[0], y: origin[1], z: origin[2] },\n    { x: axis[0], y: axis[1], z: axis[2] },\n    pitch,\n    height,\n    radius,\n  ) as unknown as BrepHandle\n  return fromBrepCurve(solidToShape(kernel, handle), { solid: handle })\n}\n\n/**\n * 构造螺旋线（1D 曲线）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name helix\n * @note 平台 op：仅 occt 引擎（原生 makeHelixWire）。非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 1D 螺旋线（kind:'curve'）。\n * @param options.radius - 螺旋半径（mm，>0）。type:number required:true\n * @param options.pitch - 螺距（mm，≠0）。type:number required:true\n * @param options.turns - 圈数（>0）。type:number required:true\n * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false\n * @param options.origin - 起点（默认原点）。type:Vec3 required:false\n * @example\n * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })\n */\nexport const helix = defineOp({\n  brep(opts: HelixOptions) {\n    return helixBrep(opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' } as Provenance,\n})\n"]}
+{"version":3,"file":"helix.js","sourceRoot":"","sources":["../../src/api/helix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAgBzD,sDAAsD;AACtD,SAAS,SAAS,CAAC,IAAkB;IACnC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IACrC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC5E,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAChF,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAA;IACzE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAC/B,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,EAC5C,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EACtC,KAAK,EACL,MAAM,EACN,MAAM,CACkB,CAAA;IAC1B,OAAO,aAAa,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,IAAI,CAAC,IAAkB;QACrB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,sCAAsC,EAAgB;CAC5F,CAAC,CAAA","sourcesContent":["/**\n * api helix — 螺旋线（1D 曲线，平台 op engines:['occt']）\n *\n * @platform occt — 本文件 import occt-kernel：螺旋线用 `makeHelixWire` 构造\n * （occt-wasm 原生有，L1 无）。守卫 ① 要求平台 import 自证身份；调用方 op 声明\n * `engines: ['occt']` 由守卫 ② 校验。\n *\n * 用途：G-D 门控层的 1D 造线能力（Phase 3）。下游 sweep / loft 等可用螺旋线作 spine。\n *\n * 设计：\n * - 平台 op：occt 原生 makeHelixWire（occt-wasm 有，L1 无）→ 声明 engines:['occt']（D11）。\n *   不声明 capabilities：实现直连平台原生方法，能力由引擎身份本身界定。\n * - 1D 产物：经 fromBrepCurve 登记，kind='curve'。\n * - 非 occt 引擎（brepkit）→ 执行前 BrepUnsupportedError（D11-4）；brep_mock 受 D11-3\n *   豁免不拦截（且 getOcctKernel 为全局 occt 实例，brep_mock 下仍可真实出线）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getBrepApi } from '../brep/handle-bridge'\nimport { fromBrepCurve } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\n/** `cad.helix` 参数。 */\nexport interface HelixOptions {\n  /** 螺旋半径（mm，>0）。 */\n  radius: number\n  /** 螺距（mm，每圈沿轴的推进量，≠0）。 */\n  pitch: number\n  /** 圈数（>0）。 */\n  turns: number\n  /** 螺旋轴方向（单位向量，默认 +Z）。 */\n  axis?: [number, number, number]\n  /** 起点（默认原点）。 */\n  origin?: [number, number, number]\n}\n\n/** BREP 路径：用 occt 原生 makeHelixWire 构造螺旋线，登记 1D 句柄。 */\nfunction helixBrep(opts: HelixOptions): Shape {\n  const { radius, pitch, turns } = opts\n  if (!(radius > 0)) throw new Error('E_HELIX_BAD_RADIUS: radius must be > 0')\n  if (!(pitch !== 0)) throw new Error('E_HELIX_BAD_PITCH: pitch must be non-zero')\n  if (!(turns > 0)) throw new Error('E_HELIX_BAD_TURNS: turns must be > 0')\n  const axis = opts.axis ?? [0, 0, 1]\n  const origin = opts.origin ?? [0, 0, 0]\n  const height = pitch * turns\n  const kernel = getBrepApi()\n  const occt = getOcctKernel()\n  const handle = occt.makeHelixWire(\n    { x: origin[0], y: origin[1], z: origin[2] },\n    { x: axis[0], y: axis[1], z: axis[2] },\n    pitch,\n    height,\n    radius,\n  ) as unknown as BrepHandle\n  return fromBrepCurve(solidToShape(kernel, handle), { solid: handle })\n}\n\n/**\n * 构造螺旋线（1D 曲线）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name helix\n * @note 平台 op：仅 occt 引擎（原生 makeHelixWire）。非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 1D 螺旋线（kind:'curve'）。\n * @param options.radius - 螺旋半径（mm，>0）。type:number required:true\n * @param options.pitch - 螺距（mm，≠0）。type:number required:true\n * @param options.turns - 圈数（>0）。type:number required:true\n * @param options.axis - 螺旋轴方向（默认 +Z）。type:Vec3 required:false\n * @param options.origin - 起点（默认原点）。type:Vec3 required:false\n * @example\n * const h = cad.helix({ radius: 5, pitch: 2, turns: 3 })\n */\nexport const helix = defineOp({\n  brep(opts: HelixOptions) {\n    return helixBrep(opts)\n  },\n  engines: ['occt'],\n  naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' } as Provenance,\n})\n"]}

package/dist/api/import-brep.d.ts

@@ -1,5 +1,5 @@
 /**
- * stdlib import_brep — 平台 BREP 资产导入 op（H11 / 方案 §4.1）
+ * api import_brep — 平台 BREP 资产导入 op（H11 / 方案 §4.1）
  *
  *
  * 与编辑器 `cad.load`（`api/load.ts`）的区别见方案 §4.5：
@@ -32,5 +32,23 @@ import type { Shape } from '../mesh/types.js';
  * @example
  * const a = await cad.import_brep({ asset: 'Array001.Shape' })
  */
-export declare function import_brep(params: Record<string, unknown>): Promise<Shape>;
+/**
+ * 裸实现：契约层测试直调（不经 defineOp 的 dispatch 拦截）。
+ *
+ * @param params - op 参数对象；`asset` 为容器资产名（去扩展名）。
+ * @returns 持 OCCT 句柄的几何（非实体亦可）。
+ */
+export declare function importBrepImpl(params: Record<string, unknown>): Promise<Shape>;
+/**
+ * GOTCHA（2026-09-30）：import_brep / import_step 必须经 defineOp 包装进入 cad
+ * 命名空间，不能是裸 async 函数。part 键 roleTable（outputTablesByPart）只在
+ * define-op.ts 包装层的 brep 分支登记（shape.ts attachBrep 只落语句键表，因为
+ * fromBrep 时刻 shape 还没被 executor 命名）。裸函数产物没有 part 键表 → 下游
+ * place 的 inputRoleTable（tableOfPart）拿到 undefined → place 产物 roleTable
+ * 断流 → edgeRef 报 "input shape has no role table (nameless shape)"
+ * （fcstd 语料 43 例，如 ISO4032_Hex_Nut_M10 的 chamfer(Pocket001__place)）。
+ */
+export declare const import_brep: ((params: Record<string, unknown>) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
 //# sourceMappingURL=import-brep.d.ts.map

package/dist/api/import-brep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-brep.d.ts","sourceRoot":"","sources":["../../src/api/import-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAQ1C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CA2CjF"}
+{"version":3,"file":"import-brep.d.ts","sourceRoot":"","sources":["../../src/api/import-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAU1C;;;;;;;;;;;;;;;;;GAiBG;AACH;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CA2CpF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW;;CAQtB,CAAA"}

package/dist/api/import-brep.js

@@ -1,5 +1,5 @@
 /**
- * stdlib import_brep — 平台 BREP 资产导入 op（H11 / 方案 §4.1）
+ * api import_brep — 平台 BREP 资产导入 op（H11 / 方案 §4.1）
  *
  *
  * 与编辑器 `cad.load`（`api/load.ts`）的区别见方案 §4.5：
@@ -17,6 +17,7 @@ import { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-st
 import { OpError } from './internal/result-unwrap.js';
 import { loadBrep } from '../brep/brep-ops.js';
 import { fromBrep } from '../shape.js';
+import { defineOp } from '../sdk.js';
 /**
  * 平台 BREP 资产导入：把容器 `assets/` 里的冻结 BREP 载体装成持 OCCT 句柄的 Shape。
  *
@@ -35,7 +36,13 @@ import { fromBrep } from '../shape.js';
  * @example
  * const a = await cad.import_brep({ asset: 'Array001.Shape' })
  */
-export async function import_brep(params) {
+/**
+ * 裸实现：契约层测试直调（不经 defineOp 的 dispatch 拦截）。
+ *
+ * @param params - op 参数对象；`asset` 为容器资产名（去扩展名）。
+ * @returns 持 OCCT 句柄的几何（非实体亦可）。
+ */
+export async function importBrepImpl(params) {
     const assets = getBackends().assets;
     if (!assets || !assets.resolveByKey) {
         throw new OpError('import_brep', 'E_OP_FAILED', '[api/import_brep] assets backend is required');
@@ -51,7 +58,7 @@ export async function import_brep(params) {
         throw new BrepUnsupportedError('E_BREP_UNSUPPORTED: import_brep requires an OCCT kernel (.brp assets have no mesh parser)');
     }
     // C6：非实体一等公民——始终允许导入 wire/face/shell（allowNonSolid=true）。
-    const { solid: solidHandle, shape } = loadBrep(kernel, buffer, undefined, undefined, undefined, { allowNonSolid: true });
+    const { solid: solidHandle, shape } = loadBrep(kernel, buffer, undefined, undefined, { allowNonSolid: true });
     // E3（H12）：链根建 roleTable（与 primitives.ts 同源机制）——冻结资产是
     // 无名形状，没有这张表下游 edgeRef/faceRef 无法解析（nameless-shape 缺陷）。
     // Phase 1.6：origin 用导入语句的 StmtId——同一资产导入两次是两条语句，
@@ -69,4 +76,22 @@ export async function import_brep(params) {
         roleTable: new Map([[stmtId, roles]]),
     });
 }
+/**
+ * GOTCHA（2026-09-30）：import_brep / import_step 必须经 defineOp 包装进入 cad
+ * 命名空间，不能是裸 async 函数。part 键 roleTable（outputTablesByPart）只在
+ * define-op.ts 包装层的 brep 分支登记（shape.ts attachBrep 只落语句键表，因为
+ * fromBrep 时刻 shape 还没被 executor 命名）。裸函数产物没有 part 键表 → 下游
+ * place 的 inputRoleTable（tableOfPart）拿到 undefined → place 产物 roleTable
+ * 断流 → edgeRef 报 "input shape has no role table (nameless shape)"
+ * （fcstd 语料 43 例，如 ISO4032_Hex_Nut_M10 的 chamfer(Pocket001__place)）。
+ */
+export const import_brep = defineOp({
+    name: 'import_brep',
+    brep: importBrepImpl,
+    engines: ['occt'],
+    // `imported:0` 是 <i> 采样值（同 extrude 的 `wall:0`）：实际产出 imported:0..n-1，
+    // 与上面 roleTable 的 `imported:${i}` 逐字对齐。不能写成 semantic 'imported'——
+    // 它是结构 kind，出现在串首会被 parseRoleName 读成结构而非语义名（见 role-name.ts RESERVED_KEYWORDS）。
+    naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [{ kind: 'imported', index: 0 }] } },
+});
 //# sourceMappingURL=import-brep.js.map

package/dist/api/import-brep.js.map

@@ -1 +1 @@
-{"version":3,"file":"import-brep.js","sourceRoot":"","sources":["../../src/api/import-brep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACpF,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAInC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAA+B;IAC/D,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAEhB,CAAA;IACb,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACpC,MAAM,IAAI,OAAO,CAAC,aAAa,EAAE,aAAa,EAAE,8CAA8C,CAAC,CAAA;IACjG,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;IAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,OAAO,CAAC,aAAa,EAAE,QAAQ,EAAE,mDAAmD,CAAC,CAAA;IACjG,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAA;IAEvD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAA;IACzC,MAAM,MAAM,GAAG,OAAO,CAAC,IAA4B,CAAA;IACnD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,oBAAoB,CAC5B,2FAA2F,CAC5F,CAAA;IACH,CAAC;IAED,0DAA0D;IAC1D,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,QAAQ,CAC5C,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CACzE,CAAA;IACD,qDAAqD;IACrD,wDAAwD;IACxD,iDAAiD;IACjD,6CAA6C;IAC7C,kFAAkF;IAClF,0FAA0F;IAC1F,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,CAAA;IACrE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAA;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAA;IAC1C,CAAC;IACD,OAAO,QAAQ,CAAC,KAAK,EAAE;QACrB,KAAK,EAAE,WAAW;QAClB,SAAS,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;KACtC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["/**\n * stdlib import_brep — 平台 BREP 资产导入 op（H11 / 方案 §4.1）\n *\n *\n * 与编辑器 `cad.load`（`api/load.ts`）的区别见方案 §4.5：\n * - `cad.load` 是 ../3d_editor 的「文件导入 Feature」（key/path/url 三键分流、\n *   语句位置约定、partIndex 画布语义），且历史契约要求实体。\n * - `cad.import_brep` 是 faijs **平台**几何 op：单一 asset 引用（容器资产名，\n *   去扩展名），语义是「把冻结的 BREP 载体装成持 OCCT 句柄的 Shape」。\n *\n * 非实体（wire/face/shell）一等公民（C6）：不要求实体，始终 allowNonSolid。\n * 需要实体的操作（布尔、up-to 目标面）在使用点报错（V-C8）。\n *\n * BREP 专属：`.brp` 无 mesh 解析器；mesh / 无内核模式抛 E_BREP_UNSUPPORTED。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state'\nimport { OpError } from './internal/result-unwrap'\nimport { loadBrep } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\n\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/**\n * 平台 BREP 资产导入：把容器 `assets/` 里的冻结 BREP 载体装成持 OCCT 句柄的 Shape。\n *\n * `asset` = 资产名（去扩展名，沿用 `FsAssetResolver` 的 `key = basename(file)` 规则），\n * 由宿主资产解析器按 key 解析（与 `cad.load` 同套解析器）。\n *\n * @group 创建\n * @inputs 0\n * @async true\n * @qual ok\n * @name import_brep\n * @param params.asset - 容器资产名（去扩展名）。type:string required:true\n * @note 非实体一等（C6）：wire/face/shell 一律可导入，本 op 不设 `allowNonSolid` 一类开关。需要实体的 op（布尔、up-to 目标面）在**使用点**报错，而不是在导入点拒绝。\n * @note 这是**平台**资产导入 op。编辑器 `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流 + 画布语句位置语义），平台侧不要复用它（C7）。\n * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。\n * @example\n * const a = await cad.import_brep({ asset: 'Array001.Shape' })\n */\nexport async function import_brep(params: Record<string, unknown>): Promise<Shape> {\n  const assets = getBackends().assets as {\n    resolveByKey?(key: string): Promise<{ bytes: ArrayBuffer }>\n  } | undefined\n  if (!assets || !assets.resolveByKey) {\n    throw new OpError('import_brep', 'E_OP_FAILED', '[api/import_brep] assets backend is required')\n  }\n\n  const asset = params.asset\n  if (typeof asset !== 'string' || asset.length === 0) {\n    throw new OpError('import_brep', 'E_ARGS', '[api/import_brep] asset name (string) is required')\n  }\n\n  const buffer = (await assets.resolveByKey(asset)).bytes\n\n  const { kernel: kernels } = getBackends()\n  const kernel = kernels.brep as BrepEngineApi | null\n  if (!kernel) {\n    throw new BrepUnsupportedError(\n      'E_BREP_UNSUPPORTED: import_brep requires an OCCT kernel (.brp assets have no mesh parser)',\n    )\n  }\n\n  // C6：非实体一等公民——始终允许导入 wire/face/shell（allowNonSolid=true）。\n  const { solid: solidHandle, shape } = loadBrep(\n    kernel, buffer, undefined, undefined, undefined, { allowNonSolid: true },\n  )\n  // E3（H12）：链根建 roleTable（与 primitives.ts 同源机制）——冻结资产是\n  // 无名形状，没有这张表下游 edgeRef/faceRef 无法解析（nameless-shape 缺陷）。\n  // Phase 1.6：origin 用导入语句的 StmtId——同一资产导入两次是两条语句，\n  // 各自产出的面天然分属不同 origin（旧实现用资产名，两次导入撞 origin）。\n  // 3.8: imported:<i> — imported faces have no semantic names (arbitrary geometry),\n  // named by enumeration order in the imported file (stable across re-import of same file).\n  const stmtId = String(getCurrentStmt()?.id ?? '')\n  const hashes = kernel.subShapeHashes(solidHandle, 'face', 2147483647)\n  const roles = new Map<string, number[]>()\n  for (let i = 0; i < hashes.length; i++) {\n    roles.set(`imported:${i}`, [hashes[i]!])\n  }\n  return fromBrep(shape, {\n    solid: solidHandle,\n    roleTable: new Map([[stmtId, roles]]),\n  })\n}\n"]}
+{"version":3,"file":"import-brep.js","sourceRoot":"","sources":["../../src/api/import-brep.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api import_brep — 平台 BREP 资产导入 op（H11 / 方案 §4.1）\n *\n *\n * 与编辑器 `cad.load`（`api/load.ts`）的区别见方案 §4.5：\n * - `cad.load` 是 ../3d_editor 的「文件导入 Feature」（key/path/url 三键分流、\n *   语句位置约定、partIndex 画布语义），且历史契约要求实体。\n * - `cad.import_brep` 是 faijs **平台**几何 op：单一 asset 引用（容器资产名，\n *   去扩展名），语义是「把冻结的 BREP 载体装成持 OCCT 句柄的 Shape」。\n *\n * 非实体（wire/face/shell）一等公民（C6）：不要求实体，始终 allowNonSolid。\n * 需要实体的操作（布尔、up-to 目标面）在使用点报错（V-C8）。\n *\n * BREP 专属：`.brp` 无 mesh 解析器；mesh / 无内核模式抛 E_BREP_UNSUPPORTED。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { getBackends, BrepUnsupportedError, getCurrentStmt } from '../runtime-state'\nimport { OpError } from './internal/result-unwrap'\nimport { loadBrep } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\n\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/**\n * 平台 BREP 资产导入：把容器 `assets/` 里的冻结 BREP 载体装成持 OCCT 句柄的 Shape。\n *\n * `asset` = 资产名（去扩展名，沿用 `FsAssetResolver` 的 `key = basename(file)` 规则），\n * 由宿主资产解析器按 key 解析（与 `cad.load` 同套解析器）。\n *\n * @group 创建\n * @inputs 0\n * @async true\n * @qual ok\n * @name import_brep\n * @param params.asset - 容器资产名（去扩展名）。type:string required:true\n * @note 非实体一等（C6）：wire/face/shell 一律可导入，本 op 不设 `allowNonSolid` 一类开关。需要实体的 op（布尔、up-to 目标面）在**使用点**报错，而不是在导入点拒绝。\n * @note 这是**平台**资产导入 op。编辑器 `cad.load` 是 `../3d_editor` 的「文件导入 Feature」（key/path/url 三键分流 + 画布语句位置语义），平台侧不要复用它（C7）。\n * @returns Promise<Shape> 持 OCCT 句柄的几何（非实体亦可）。\n * @example\n * const a = await cad.import_brep({ asset: 'Array001.Shape' })\n */\n/**\n * 裸实现：契约层测试直调（不经 defineOp 的 dispatch 拦截）。\n *\n * @param params - op 参数对象；`asset` 为容器资产名（去扩展名）。\n * @returns 持 OCCT 句柄的几何（非实体亦可）。\n */\nexport async function importBrepImpl(params: Record<string, unknown>): Promise<Shape> {\n  const assets = getBackends().assets as {\n    resolveByKey?(key: string): Promise<{ bytes: ArrayBuffer }>\n  } | undefined\n  if (!assets || !assets.resolveByKey) {\n    throw new OpError('import_brep', 'E_OP_FAILED', '[api/import_brep] assets backend is required')\n  }\n\n  const asset = params.asset\n  if (typeof asset !== 'string' || asset.length === 0) {\n    throw new OpError('import_brep', 'E_ARGS', '[api/import_brep] asset name (string) is required')\n  }\n\n  const buffer = (await assets.resolveByKey(asset)).bytes\n\n  const { kernel: kernels } = getBackends()\n  const kernel = kernels.brep as BrepEngineApi | null\n  if (!kernel) {\n    throw new BrepUnsupportedError(\n      'E_BREP_UNSUPPORTED: import_brep requires an OCCT kernel (.brp assets have no mesh parser)',\n    )\n  }\n\n  // C6：非实体一等公民——始终允许导入 wire/face/shell（allowNonSolid=true）。\n  const { solid: solidHandle, shape } = loadBrep(\n    kernel, buffer, undefined, undefined, { allowNonSolid: true },\n  )\n  // E3（H12）：链根建 roleTable（与 primitives.ts 同源机制）——冻结资产是\n  // 无名形状，没有这张表下游 edgeRef/faceRef 无法解析（nameless-shape 缺陷）。\n  // Phase 1.6：origin 用导入语句的 StmtId——同一资产导入两次是两条语句，\n  // 各自产出的面天然分属不同 origin（旧实现用资产名，两次导入撞 origin）。\n  // 3.8: imported:<i> — imported faces have no semantic names (arbitrary geometry),\n  // named by enumeration order in the imported file (stable across re-import of same file).\n  const stmtId = String(getCurrentStmt()?.id ?? '')\n  const hashes = kernel.subShapeHashes(solidHandle, 'face', 2147483647)\n  const roles = new Map<string, number[]>()\n  for (let i = 0; i < hashes.length; i++) {\n    roles.set(`imported:${i}`, [hashes[i]!])\n  }\n  return fromBrep(shape, {\n    solid: solidHandle,\n    roleTable: new Map([[stmtId, roles]]),\n  })\n}\n\n/**\n * GOTCHA（2026-09-30）：import_brep / import_step 必须经 defineOp 包装进入 cad\n * 命名空间，不能是裸 async 函数。part 键 roleTable（outputTablesByPart）只在\n * define-op.ts 包装层的 brep 分支登记（shape.ts attachBrep 只落语句键表，因为\n * fromBrep 时刻 shape 还没被 executor 命名）。裸函数产物没有 part 键表 → 下游\n * place 的 inputRoleTable（tableOfPart）拿到 undefined → place 产物 roleTable\n * 断流 → edgeRef 报 \"input shape has no role table (nameless shape)\"\n * （fcstd 语料 43 例，如 ISO4032_Hex_Nut_M10 的 chamfer(Pocket001__place)）。\n */\nexport const import_brep = defineOp({\n  name: 'import_brep',\n  brep: importBrepImpl,\n  engines: ['occt'],\n  // `imported:0` 是 <i> 采样值（同 extrude 的 `wall:0`）：实际产出 imported:0..n-1，\n  // 与上面 roleTable 的 `imported:${i}` 逐字对齐。不能写成 semantic 'imported'——\n  // 它是结构 kind，出现在串首会被 parseRoleName 读成结构而非语义名（见 role-name.ts RESERVED_KEYWORDS）。\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [{ kind: 'imported', index: 0 }] } } as Provenance,\n})\n"]}

package/dist/api/import-step.d.ts

@@ -1,6 +1,6 @@
 import type { Shape } from '../mesh/types.js';
 /**
- * stdlib import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）
+ * api import_step — 任意路径 STEP 文件导入 op（方案 Phase 5 / Q2 真缺口）
  *
  * 与 `import_brep`（容器资产）和 `cad.load`（编辑器 FileRef）的职责切分：
  * - `cad.import_step` 是 faijs **平台**几何 op：单一本地路径（宿主 `resolveFile`），
@@ -24,5 +24,20 @@ import type { Shape } from '../mesh/types.js';
  * @example
  * const a = await cad.import_step({ path: 'D:/models/box.step' })
  */
-export declare function import_step(params: Record<string, unknown>): Promise<Shape>;
+/**
+ * 裸实现：契约层测试直调（不经 defineOp 的 dispatch 拦截）。
+ *
+ * @param params - op 参数对象；`path` 为 STEP 文件路径。
+ * @returns 持 OCCT 句柄的几何（非实体亦可）。
+ */
+export declare function importStepImpl(params: Record<string, unknown>): Promise<Shape>;
+/**
+ * GOTCHA（2026-09-30）：与 import_brep 同——必须经 defineOp 包装进入 cad 命名空间，
+ * 不能是裸 async 函数。part 键 roleTable（outputTablesByPart）只在 define-op.ts
+ * 包装层的 brep 分支登记；裸 async 函数产物没有 part 键表，下游 place/edgeRef
+ * 报 "input shape has no role table (nameless shape)"。
+ */
+export declare const import_step: ((params: Record<string, unknown>) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
 //# sourceMappingURL=import-step.d.ts.map

package/dist/api/import-step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-step.d.ts","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAQ1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAuCjF"}
+{"version":3,"file":"import-step.d.ts","sourceRoot":"","sources":["../../src/api/import-step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAU1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAuCpF;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;CAMtB,CAAA"}