@faicad/faijs 0.14.1 → 0.16.0

package/dist/api/revolve.js

@@ -0,0 +1,165 @@
+/**
+ * revolve — 手写平台 op（E3 / Q13 路线①的 revolve 实例）
+ *
+ * 生成投影（`api/generated/operations.ts` 的 revolve）是 compat op：几何由
+ * vendored brepjs 承载，但**没有可挂面命名的代码位置**，产物不带 roleTable，
+ * 下游 `cad.edgeRef` 抛 "nameless shape"（ModelFromV021 缺陷）。
+ *
+ * 本文件按 `cut` 覆盖生成投影的同一先例（`api-namespace.ts`），用 defineOp 包住
+ * 投影调用，并在产物登记处建链根 roleTable（origin = 语句 StmtId，与
+ * `extrude.ts` / `import-brep.ts` 同源机制）。
+ *
+ * 词汇表沿用生成 spec 的 construct 声明：`bottom` / `top`（旋转轴两端的平面
+ * 端面）+ `wall:<i>`（其余侧面，按枚举序）。判定口径与 extrude 相同——现场
+ * 几何是唯一真值：平面法向与轴 |cos| ≈ 1 → 端面，按中心沿轴坐标分 bottom/top；
+ * 其余（含圆柱等曲面侧面）→ wall:i。无法分类的面不进表（缺身份是显式状态）。
+ */
+import { defineOp } from '../sdk.js';
+import { getBackends, getCurrentStmt } from '../runtime-state.js';
+import { brepOf } from '../shape.js';
+import { adoptEntity, callBrepjs } from './internal/l3-bridge.js';
+import { borrowDeep } from './internal/compat-op.js';
+import { unwrapResult } from './internal/result-unwrap.js';
+import { runtimeLineage } from '../topology/naming/lineage.js';
+import { revolve as vendoredRevolve } from '../vendored/brepjs/operations/api.js';
+import { formatRoleName, semantic, wall } from '../topology/naming/role-name.js';
+/**
+ * revolve 的 construct 词汇表：`bottom` / `top`（旋转轴两端的平面端面）+ `wall:<i>`。
+ * 判定口径见 {@link revolveConstructRoles}。
+ */
+/** options.axis 的宽松形态（数组或 {x,y,z}）。 */
+function axisVec(v) {
+    if (Array.isArray(v) && v.length >= 3 && v.every((n) => typeof n === 'number')) {
+        return [v[0], v[1], v[2]];
+    }
+    if (typeof v === 'object' && v !== null && 'x' in v) {
+        const o = v;
+        return [o.x, o.y, o.z];
+    }
+    return [0, 0, 1];
+}
+/**
+ * revolve 的 construct 词汇枚举器（与 `extrudeConstructRoles` 同口径，轴来源不同：
+ * extrude 从端面法向对差反推，revolve 直接用调用点声明的旋转轴）。
+ *
+ * @param kernel - the OCCT kernel.
+ * @param solid - the revolved solid.
+ * @param axis - the revolution axis (call-site declared; default [0,0,1]).
+ * @returns role（线格式串）→ hash 子表。
+ */
+function revolveConstructRoles(kernel, solid, axisOpt) {
+    const roles = new Map();
+    const faceHandles = kernel.getSubShapes(solid, 'face');
+    try {
+        const hashes = kernel.subShapeHashes(solid, 'face', 2147483647);
+        const [ax0, ax1, ax2] = axisVec(axisOpt);
+        const axLen = Math.hypot(ax0, ax1, ax2);
+        if (axLen < 1e-9)
+            return roles;
+        const ax = [ax0 / axLen, ax1 / axLen, ax2 / axLen];
+        const caps = [];
+        const isPlaneCap = faceHandles.map((f) => {
+            if (kernel.surfaceType(f) !== 'plane')
+                return false;
+            const uv = kernel.uvBounds(f);
+            const n = kernel.surfaceNormal(f, (uv.uMin + uv.uMax) / 2, (uv.vMin + uv.vMax) / 2);
+            const len = Math.hypot(n.x, n.y, n.z) || 1;
+            const cos = Math.abs(n.x * ax[0] + n.y * ax[1] + n.z * ax[2]) / len;
+            return cos > 0.999;
+        });
+        for (let i = 0; i < faceHandles.length; i++) {
+            if (hashes[i] === undefined)
+                continue;
+            if (isPlaneCap[i]) {
+                const c = kernel.getSurfaceCenterOfMass(faceHandles[i]);
+                caps.push({ idx: i, t: c.x * ax[0] + c.y * ax[1] + c.z * ax[2] });
+            }
+        }
+        if (caps.length >= 2) {
+            // 常规旋转体：轴两端平面端面 = bottom/top，其余面（含曲面侧面）wall:<i>
+            let wallIdx = 0;
+            for (let i = 0; i < faceHandles.length; i++) {
+                const hash = hashes[i];
+                if (hash === undefined || isPlaneCap[i])
+                    continue;
+                roles.set(formatRoleName(wall(wallIdx)), [hash]);
+                wallIdx++;
+            }
+            caps.sort((p, q) => p.t - q.t);
+            roles.set(formatRoleName(semantic('bottom')), [hashes[caps[0].idx]]);
+            roles.set(formatRoleName(semantic('top')), [hashes[caps[caps.length - 1].idx]]);
+        }
+        else {
+            // GOTCHA（退化形态，2026-09-23）：轮廓面在轴平面内（如 XY 草图绕 Z 转）
+            // 时产物的面法向全部 ∥ 轴 → caps 判不出两端。此时退化为按枚举序
+            // wall:<i> 命名全部面——身份是能力，退化形态不给名字就会重演 nameless
+            // shape 缺陷；枚举序稳定（同 extrude 的 wall 序依据）。
+            for (let i = 0; i < faceHandles.length; i++) {
+                const hash = hashes[i];
+                if (hash === undefined)
+                    continue;
+                roles.set(formatRoleName(wall(i)), [hash]);
+            }
+        }
+        return roles;
+    }
+    finally {
+        for (const h of faceHandles) {
+            try {
+                kernel.release(h);
+            }
+            catch { /* 已释放 */ }
+        }
+    }
+}
+/**
+ * 旋转成形：把平面轮廓绕轴旋转（兼容生成投影签名）。
+ * @group 特征
+ * @inputs 1
+ * @async true
+ * @qual ok
+ * @name revolve
+ * @param face - 平面轮廓。type:Shape required:true
+ * @param options - 旋转轴/点/角度（透传 vendored 语义）。type:RevolveOptions
+ * @returns Shape 旋转体（带链根 roleTable：bottom/top/wall:i）。
+ * @example
+ * const p1 = await cad.revolve(part0, { axis: [0, 0, 1], at: [0, 0, 0], angle: 6.283185307179586 })
+ */
+export const revolve = defineOp({
+    brep: async (face, options) => {
+        // vendored 语义经 l3-bridge 三步桥接（与 compatOp 的 adapter 相同步骤，
+        // 但在这里执行以便在**同一处**收编产物并建链根 roleTable——compatOp 的
+        // 自动 adoptOut 会先登记一次，二次 fromBrep 会让 edgeRef 读到残缺表）。
+        const value = unwrapResult(await callBrepjs(vendoredRevolve, [borrowDeep(face, 0), borrowDeep(options ?? {}, 0)]), 'revolve');
+        const s = adoptEntity(value, 'revolve');
+        const kernel = getBackends().kernel.brep;
+        const handle = kernel ? brepOf(s) : undefined;
+        if (!kernel || !handle)
+            return s;
+        // E3（Q13 路线①）：链根建 roleTable，origin = 语句 StmtId（Phase 1.6 口径）。
+        // GOTCHA（2026-09-23）：不能对 adoptEntity 的产物再走一次 fromBrep——同语句的
+        // registeredStmtId 去重会让第二次登记被吞（探针实测：outputTables 里没有本
+        // 语句键）。直接经 runtimeLineage.recordOutput 落语句键表；define-op 包装层
+        // 会在 impl 返回后把它传播到 part 键权威位（edgeRef 的读口）。
+        const origin = String(getCurrentStmt()?.id ?? '');
+        const table = new Map([[origin, revolveConstructRoles(kernel, handle, options?.axis)]]);
+        // GOTCHA：recordOutput 必须带第 4 参 part——part 键表（outputTablesByPart）
+        // 是 op 实现与 edgeRef 解析的权威读口，只落语句键表时 part 键会保持
+        // adoptEntity 时登记的空表（探针实测），下游仍报 no role lineage。
+        const part = getCurrentStmt()?.outputs?.[0];
+        runtimeLineage.recordOutput(origin, table, handle, part);
+        return s;
+    },
+    naming: {
+        kind: 'construct',
+        newFaces: {
+            via: 'explicit',
+            vocab: [
+                { kind: 'semantic', name: 'top' },
+                { kind: 'semantic', name: 'bottom' },
+                { kind: 'wall', index: 0 },
+            ],
+        },
+    },
+});
+//# sourceMappingURL=revolve.js.map

package/dist/api/revolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revolve.js","sourceRoot":"","sources":["../../src/api/revolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AACjC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,sCAAsC,CAAA;AACjF,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAA;AAI7E;;;GAGG;AAEH,uCAAuC;AACvC,SAAS,OAAO,CAAC,CAAU;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC/E,OAAO,CAAC,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAA;IAC9B,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,GAAG,IAAK,CAAY,EAAE,CAAC;QAChE,MAAM,CAAC,GAAG,CAAwC,CAAA;QAClD,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;IACxB,CAAC;IACD,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAC5B,MAAqB,EACrB,KAAiB,EACjB,OAAgB;IAEhB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAA;IACzC,MAAM,WAAW,GAAG,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,CAAA;QAC/D,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;QACvC,IAAI,KAAK,GAAG,IAAI;YAAE,OAAO,KAAK,CAAA;QAC9B,MAAM,EAAE,GAAsC,CAAC,GAAG,GAAG,KAAK,EAAE,GAAG,GAAG,KAAK,EAAE,GAAG,GAAG,KAAK,CAAC,CAAA;QAErF,MAAM,IAAI,GAAiC,EAAE,CAAA;QAC7C,MAAM,UAAU,GAAc,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAClD,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,OAAO;gBAAE,OAAO,KAAK,CAAA;YACnD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAC7B,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;YACnF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;YAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC,GAAG,GAAG,CAAA;YACtE,OAAO,GAAG,GAAG,KAAK,CAAA;QACpB,CAAC,CAAC,CAAA;QACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS;gBAAE,SAAQ;YACrC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClB,MAAM,CAAC,GAAG,MAAM,CAAC,sBAAsB,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC,CAAA;gBACxD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,EAAE,CAAC,CAAA;YACtE,CAAC;QACH,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACrB,gDAAgD;YAChD,IAAI,OAAO,GAAG,CAAC,CAAA;YACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;gBACtB,IAAI,IAAI,KAAK,SAAS,IAAI,UAAU,CAAC,CAAC,CAAC;oBAAE,SAAQ;gBACjD,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;gBAChD,OAAO,EAAE,CAAA;YACX,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;YAC9B,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,GAAG,CAAE,CAAC,CAAC,CAAA;YACtE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,GAAG,CAAE,CAAC,CAAC,CAAA;QACnF,CAAC;aAAM,CAAC;YACN,iDAAiD;YACjD,uCAAuC;YACvC,8CAA8C;YAC9C,wCAAwC;YACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;gBACtB,IAAI,IAAI,KAAK,SAAS;oBAAE,SAAQ;gBAChC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;YAC5C,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;YAAS,CAAC;QACT,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC;gBAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;IAC9B,IAAI,EAAE,KAAK,EAAE,IAAW,EAAE,OAA4B,EAAE,EAAE;QACxD,yDAAyD;QACzD,iDAAiD;QACjD,oDAAoD;QACpD,MAAM,KAAK,GAAG,YAAY,CACxB,MAAM,UAAU,CAAC,eAAwB,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAC/F,SAAS,CACV,CAAA;QACD,MAAM,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,SAAS,CAAU,CAAA;QAChD,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAA4B,CAAA;QAChE,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAE,MAAM,CAAC,CAAC,CAA4B,CAAC,CAAC,CAAC,SAAS,CAAA;QACzE,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM;YAAE,OAAO,CAAC,CAAA;QAChC,8DAA8D;QAC9D,4DAA4D;QAC5D,sDAAsD;QACtD,2DAA2D;QAC3D,2CAA2C;QAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;QACjD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;QACvF,iEAAiE;QACjE,6CAA6C;QAC7C,iDAAiD;QACjD,MAAM,IAAI,GAAG,cAAc,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAA;QAC3C,cAAc,CAAC,YAAY,CAAC,MAAe,EAAE,KAAK,EAAE,MAAM,EAAE,IAAa,CAAC,CAAA;QAC1E,OAAO,CAAC,CAAA;IACV,CAAC;IACD,MAAM,EAAE;QACN,IAAI,EAAE,WAAW;QACjB,QAAQ,EAAE;YACR,GAAG,EAAE,UAAU;YACf,KAAK,EAAE;gBACL,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE;gBACjC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACpC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE;aAC3B;SACF;KACO;CACX,CAAC,CAAA","sourcesContent":["/**\n * revolve — 手写平台 op（E3 / Q13 路线①的 revolve 实例）\n *\n * 生成投影（`api/generated/operations.ts` 的 revolve）是 compat op：几何由\n * vendored brepjs 承载，但**没有可挂面命名的代码位置**，产物不带 roleTable，\n * 下游 `cad.edgeRef` 抛 \"nameless shape\"（ModelFromV021 缺陷）。\n *\n * 本文件按 `cut` 覆盖生成投影的同一先例（`api-namespace.ts`），用 defineOp 包住\n * 投影调用，并在产物登记处建链根 roleTable（origin = 语句 StmtId，与\n * `extrude.ts` / `import-brep.ts` 同源机制）。\n *\n * 词汇表沿用生成 spec 的 construct 声明：`bottom` / `top`（旋转轴两端的平面\n * 端面）+ `wall:<i>`（其余侧面，按枚举序）。判定口径与 extrude 相同——现场\n * 几何是唯一真值：平面法向与轴 |cos| ≈ 1 → 端面，按中心沿轴坐标分 bottom/top；\n * 其余（含圆柱等曲面侧面）→ wall:i。无法分类的面不进表（缺身份是显式状态）。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { defineOp } from '../sdk'\nimport { getBackends, getCurrentStmt } from '../runtime-state'\nimport { brepOf } from '../shape'\nimport { adoptEntity, callBrepjs } from './internal/l3-bridge'\nimport { borrowDeep } from './internal/compat-op'\nimport { unwrapResult } from './internal/result-unwrap'\nimport { runtimeLineage } from '../topology/naming/lineage'\nimport { revolve as vendoredRevolve } from '../vendored/brepjs/operations/api.js'\nimport { formatRoleName, semantic, wall } from '../topology/naming/role-name'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport type { BrepHandle } from '../brep/engine/types'\n\n/**\n * revolve 的 construct 词汇表：`bottom` / `top`（旋转轴两端的平面端面）+ `wall:<i>`。\n * 判定口径见 {@link revolveConstructRoles}。\n */\n\n/** options.axis 的宽松形态（数组或 {x,y,z}）。 */\nfunction axisVec(v: unknown): readonly [number, number, number] {\n  if (Array.isArray(v) && v.length >= 3 && v.every((n) => typeof n === 'number')) {\n    return [v[0]!, v[1]!, v[2]!]\n  }\n  if (typeof v === 'object' && v !== null && 'x' in (v as object)) {\n    const o = v as { x: number; y: number; z: number }\n    return [o.x, o.y, o.z]\n  }\n  return [0, 0, 1]\n}\n\n/**\n * revolve 的 construct 词汇枚举器（与 `extrudeConstructRoles` 同口径，轴来源不同：\n * extrude 从端面法向对差反推，revolve 直接用调用点声明的旋转轴）。\n *\n * @param kernel - the OCCT kernel.\n * @param solid - the revolved solid.\n * @param axis - the revolution axis (call-site declared; default [0,0,1]).\n * @returns role（线格式串）→ hash 子表。\n */\nfunction revolveConstructRoles(\n  kernel: BrepEngineApi,\n  solid: BrepHandle,\n  axisOpt: unknown,\n): Map<string, number[]> {\n  const roles = new Map<string, number[]>()\n  const faceHandles = kernel.getSubShapes(solid, 'face')\n  try {\n    const hashes = kernel.subShapeHashes(solid, 'face', 2147483647)\n    const [ax0, ax1, ax2] = axisVec(axisOpt)\n    const axLen = Math.hypot(ax0, ax1, ax2)\n    if (axLen < 1e-9) return roles\n    const ax: readonly [number, number, number] = [ax0 / axLen, ax1 / axLen, ax2 / axLen]\n\n    const caps: { idx: number; t: number }[] = []\n    const isPlaneCap: boolean[] = faceHandles.map((f) => {\n      if (kernel.surfaceType(f) !== 'plane') return false\n      const uv = kernel.uvBounds(f)\n      const n = kernel.surfaceNormal(f, (uv.uMin + uv.uMax) / 2, (uv.vMin + uv.vMax) / 2)\n      const len = Math.hypot(n.x, n.y, n.z) || 1\n      const cos = Math.abs(n.x * ax[0]! + n.y * ax[1]! + n.z * ax[2]!) / len\n      return cos > 0.999\n    })\n    for (let i = 0; i < faceHandles.length; i++) {\n      if (hashes[i] === undefined) continue\n      if (isPlaneCap[i]) {\n        const c = kernel.getSurfaceCenterOfMass(faceHandles[i]!)\n        caps.push({ idx: i, t: c.x * ax[0]! + c.y * ax[1]! + c.z * ax[2]! })\n      }\n    }\n    if (caps.length >= 2) {\n      // 常规旋转体：轴两端平面端面 = bottom/top，其余面（含曲面侧面）wall:<i>\n      let wallIdx = 0\n      for (let i = 0; i < faceHandles.length; i++) {\n        const hash = hashes[i]\n        if (hash === undefined || isPlaneCap[i]) continue\n        roles.set(formatRoleName(wall(wallIdx)), [hash])\n        wallIdx++\n      }\n      caps.sort((p, q) => p.t - q.t)\n      roles.set(formatRoleName(semantic('bottom')), [hashes[caps[0]!.idx]!])\n      roles.set(formatRoleName(semantic('top')), [hashes[caps[caps.length - 1]!.idx]!])\n    } else {\n      // GOTCHA（退化形态，2026-09-23）：轮廓面在轴平面内（如 XY 草图绕 Z 转）\n      // 时产物的面法向全部 ∥ 轴 → caps 判不出两端。此时退化为按枚举序\n      // wall:<i> 命名全部面——身份是能力，退化形态不给名字就会重演 nameless\n      // shape 缺陷；枚举序稳定（同 extrude 的 wall 序依据）。\n      for (let i = 0; i < faceHandles.length; i++) {\n        const hash = hashes[i]\n        if (hash === undefined) continue\n        roles.set(formatRoleName(wall(i)), [hash])\n      }\n    }\n    return roles\n  } finally {\n    for (const h of faceHandles) {\n      try { kernel.release(h) } catch { /* 已释放 */ }\n    }\n  }\n}\n\n/**\n * 旋转成形：把平面轮廓绕轴旋转（兼容生成投影签名）。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name revolve\n * @param face - 平面轮廓。type:Shape required:true\n * @param options - 旋转轴/点/角度（透传 vendored 语义）。type:RevolveOptions\n * @returns Shape 旋转体（带链根 roleTable：bottom/top/wall:i）。\n * @example\n * const p1 = await cad.revolve(part0, { axis: [0, 0, 1], at: [0, 0, 0], angle: 6.283185307179586 })\n */\nexport const revolve = defineOp({\n  brep: async (face: Shape, options?: { axis?: unknown }) => {\n    // vendored 语义经 l3-bridge 三步桥接（与 compatOp 的 adapter 相同步骤，\n    // 但在这里执行以便在**同一处**收编产物并建链根 roleTable——compatOp 的\n    // 自动 adoptOut 会先登记一次，二次 fromBrep 会让 edgeRef 读到残缺表）。\n    const value = unwrapResult(\n      await callBrepjs(vendoredRevolve as never, [borrowDeep(face, 0), borrowDeep(options ?? {}, 0)]),\n      'revolve',\n    )\n    const s = adoptEntity(value, 'revolve') as Shape\n    const kernel = getBackends().kernel.brep as BrepEngineApi | null\n    const handle = kernel ? (brepOf(s) as BrepHandle | undefined) : undefined\n    if (!kernel || !handle) return s\n    // E3（Q13 路线①）：链根建 roleTable，origin = 语句 StmtId（Phase 1.6 口径）。\n    // GOTCHA（2026-09-23）：不能对 adoptEntity 的产物再走一次 fromBrep——同语句的\n    // registeredStmtId 去重会让第二次登记被吞（探针实测：outputTables 里没有本\n    // 语句键）。直接经 runtimeLineage.recordOutput 落语句键表；define-op 包装层\n    // 会在 impl 返回后把它传播到 part 键权威位（edgeRef 的读口）。\n    const origin = String(getCurrentStmt()?.id ?? '')\n    const table = new Map([[origin, revolveConstructRoles(kernel, handle, options?.axis)]])\n    // GOTCHA：recordOutput 必须带第 4 参 part——part 键表（outputTablesByPart）\n    // 是 op 实现与 edgeRef 解析的权威读口，只落语句键表时 part 键会保持\n    // adoptEntity 时登记的空表（探针实测），下游仍报 no role lineage。\n    const part = getCurrentStmt()?.outputs?.[0]\n    runtimeLineage.recordOutput(origin as never, table, handle, part as never)\n    return s\n  },\n  naming: {\n    kind: 'construct',\n    newFaces: {\n      via: 'explicit',\n      vocab: [\n        { kind: 'semantic', name: 'top' },\n        { kind: 'semantic', name: 'bottom' },\n        { kind: 'wall', index: 0 },\n      ],\n    },\n  } as never,\n})\n"]}

package/dist/api/surface/arg-spec.d.ts

@@ -29,6 +29,7 @@
 /** 生成器可用的投影方式。 */
 export type ProjectionKind = 'brep-op' | 'query' | 'pure' | 'type' | 'skip' | 'faijs';
 import type { Provenance } from '../../topology/naming/lineage.js';
+import type { BrepCapabilityName } from '../../cad-runtime/backend-dispatch.js';
 export type { Provenance } from '../../topology/naming/lineage.js';
 /** brep-op / query 的时间线消费声明（透传 defineOp 元数据，G3/G4）。 */
 /**
@@ -94,6 +95,13 @@ export interface ArgSpecEntry {
     returnType?: string;
     /** P20: 机器参数名表（按位置顺序），供 dual-form-args resolveArgs 映射对象形态→位置数组。 */
     params?: string[];
+    /**
+     * Phase 1（Brep 引擎可切换重构）：该 brep-op 所需的内核能力名（`BrepCapabilityName`：
+     * 族级布尔 / `BrepEvolutionKind` 真名 / `BrepMethodKind` 真名）。透传给 defineOp，
+     * 由 backend-dispatch 能力路由做执行前静态判定。依据 Phase 0 能力映射表
+     * （api/surface/capability-map.json）逐条填写。
+     */
+    capabilities?: BrepCapabilityName[];
     /** P20: D11 形态分类（A 单名双形态 / B1 单名单形态 / B2 双名）。 */
     formClass?: FormClass;
     /**

package/dist/api/surface/arg-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arg-spec.d.ts","sourceRoot":"","sources":["../../../src/api/surface/arg-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,kBAAkB;AAClB,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAErF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAE/D,YAAY,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAE/D,uDAAuD;AAEvD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,cAAc,CAAA;IACpB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;OAEG;IACH,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAA;IACjC,8GAA8G;IAC9G,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,yFAAyF;IACzF,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAC1B,uNAAuN;IACvN,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,iDAAiD;IACjD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,YAAY,EAy/GlC,CAAA"}
+{"version":3,"file":"arg-spec.d.ts","sourceRoot":"","sources":["../../../src/api/surface/arg-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,kBAAkB;AAClB,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAErF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAA;AAE5E,YAAY,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAE/D,uDAAuD;AAEvD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,cAAc,CAAA;IACpB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB;;OAEG;IACH,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAA;IACjC,8GAA8G;IAC9G,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,yFAAyF;IACzF,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAC1B,uNAAuN;IACvN,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,kBAAkB,EAAE,CAAA;IACnC,iDAAiD;IACjD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,YAAY,EA0/GlC,CAAA"}

package/dist/api/surface/arg-spec.js

@@ -41,6 +41,7 @@ export const ARG_SPEC = [
         name: 'torus',
         source: 'topology/primitiveFns.js#torus',
         kind: 'brep-op',
+        capabilities: ["dispose", "makeTorus"],
         args: '(majorRadius: number, minorRadius: number, options?: TorusOptions)',
         // 构造类：无几何输入（纯数值参数），brepjs 返回裸 ValidSolid（非 Result）。
         geometryArgs: [],
@@ -54,6 +55,7 @@ export const ARG_SPEC = [
         name: 'fuse',
         source: 'topology/booleanFns.js#fuse',
         kind: 'brep-op',
+        capabilities: ["dispose", "fuse", "fuseWithHistory", "isNull"],
         args: '(a: Shape3D, b: Shape3D, options?: BooleanOptions) -> Result<Shape3D>',
         // 两个输入都是 faijs Shape → 借入 brepjs handle；第三参 options 透传。
         geometryArgs: [0, 1],
@@ -1422,7 +1424,7 @@ export const ARG_SPEC = [
     },
     {
         // ---- brep-op：单/多单形状入参 → 单产物收养 ----
-        name: 'extrude', source: 'operations/api.js#extrude', kind: 'brep-op', module: 'operations',
+        name: 'extrude', source: 'operations/api.js#extrude', kind: 'brep-op', capabilities: ["dispose", "downcast", "extrude", "isNull"], module: 'operations',
         geometryArgs: [0],
         reason: 'faijs 侧 cad.extrude 由手写平台 op 覆盖（api/extrude.ts：对象形态 + upTo 拉伸到面/到支持体端面）。本投影只作为「长度形态」的引擎被手写 op 委托调用（vendored 是唯一拉伸引擎，既有 cad.extrude(face,[x,y,z]) 语义零漂移），生成模块符号不直接进 cad 命名空间 by design（同 fillet 口径）。',
         args: 'extrude(face: Shape, height: number|Vec3) → Shape｜extrude(face: Shape, params: { length? | upTo, normal?, mode?, baseFeature?, offset? }) → Shape',
@@ -1430,35 +1432,35 @@ export const ARG_SPEC = [
         naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [{ kind: 'semantic', name: 'top' }, { kind: 'semantic', name: 'bottom' }] } },
     },
     {
-        name: 'revolve', source: 'operations/api.js#revolve', kind: 'brep-op', module: 'operations',
+        name: 'revolve', source: 'operations/api.js#revolve', kind: 'brep-op', capabilities: ["dispose", "isNull", "revolveVec", "shapeType"], module: 'operations',
         geometryArgs: [0], reason: 'shapeable 面 → Result(Shape3D)，brep-op',
         args: 'revolve(face: Shape, options?: RevolveOptions): Shape',
         params: ['face', 'options'], formClass: 'A',
         naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [{ kind: 'semantic', name: 'top' }, { kind: 'semantic', name: 'bottom' }, { kind: 'wall', index: 0 }] } },
     },
     {
-        name: 'sweep', source: 'operations/extrudeFns.js#sweep', kind: 'brep-op', module: 'operations',
+        name: 'sweep', source: 'operations/extrudeFns.js#sweep', kind: 'brep-op', capabilities: ["dispose", "shapeType", "simplePipe", "sweepPipeShell"], module: 'operations',
         geometryArgs: [0, 1], reason: 'wire + spine → Result(Shape3D|tuple)，默认单产物，brep-op',
         args: 'sweep(wire: Shape, spine: Shape, config?: SweepOptions, shellMode?: boolean): Shape',
         params: ['wire', 'spine', 'config', 'shellMode'], formClass: 'A',
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'complexExtrude', source: 'operations/extrudeFns.js#complexExtrude', kind: 'brep-op', module: 'operations',
+        name: 'complexExtrude', source: 'operations/extrudeFns.js#complexExtrude', kind: 'brep-op', capabilities: ["buildExtrusionLaw", "dispose", "shapeType", "simplePipe", "sweepPipeShell"], module: 'operations',
         geometryArgs: [0], reason: 'wire → Result(Shape3D)，brep-op',
         args: 'complexExtrude(wire: Shape, center: Vec3, normal: Vec3, profile?: ExtrusionProfile): Shape',
         params: ['wire', 'center', 'normal', 'profile'], formClass: 'A',
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'twistExtrude', source: 'operations/extrudeFns.js#twistExtrude', kind: 'brep-op', module: 'operations',
+        name: 'twistExtrude', source: 'operations/extrudeFns.js#twistExtrude', kind: 'brep-op', capabilities: ["buildExtrusionLaw", "dispose", "shapeType", "simplePipe", "sweepPipeShell"], module: 'operations',
         geometryArgs: [0], reason: 'wire → Result(Shape3D)，brep-op',
         args: 'twistExtrude(wire: Shape, angleDegrees: number, center: Vec3, normal: Vec3): Shape',
         params: ['wire', 'angleDegrees', 'center', 'normal'], formClass: 'A',
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'linearPattern', source: 'operations/patternFns.js#linearPattern', kind: 'brep-op', module: 'operations',
+        name: 'linearPattern', source: 'operations/patternFns.js#linearPattern', kind: 'brep-op', capabilities: ["dispose", "fuseAll", "hashCode", "isNull", "iterShapes", "linearPattern", "section", "surfaceCenterOfMass", "surfaceNormal", "surfaceType", "uvBounds"], module: 'operations',
         geometryArgs: [0], reason: 'shape → Result(Shape3D)，brep-op',
         args: 'linearPattern(shape: Shape, direction: Vec3, count: number, spacing: number): Shape',
         params: ['shape', 'direction', 'count', 'spacing'], formClass: 'A',
@@ -1466,7 +1468,7 @@ export const ARG_SPEC = [
         naming: { kind: 'replicate', k: 0 },
     },
     {
-        name: 'circularPattern', source: 'operations/patternFns.js#circularPattern', kind: 'brep-op', module: 'operations',
+        name: 'circularPattern', source: 'operations/patternFns.js#circularPattern', kind: 'brep-op', capabilities: ["circularPattern", "dispose", "fuseAll", "hashCode", "isNull", "iterShapes", "section", "surfaceCenterOfMass", "surfaceNormal", "surfaceType", "uvBounds"], module: 'operations',
         geometryArgs: [0], reason: 'shape → Result(Shape3D)，brep-op',
         args: 'circularPattern(shape: Shape, axis: Vec3, count: number, fullAngle?: number, center?: Vec3): Shape',
         params: ['shape', 'axis', 'count', 'fullAngle', 'center'], formClass: 'A',
@@ -1474,7 +1476,7 @@ export const ARG_SPEC = [
         naming: { kind: 'replicate', k: 0 },
     },
     {
-        name: 'gridPattern', source: 'operations/patternFns.js#gridPattern', kind: 'brep-op', module: 'operations',
+        name: 'gridPattern', source: 'operations/patternFns.js#gridPattern', kind: 'brep-op', capabilities: ["dispose", "fuseAll", "gridPattern", "hashCode", "isNull", "iterShapes", "linearPattern", "section", "surfaceCenterOfMass", "surfaceNormal", "surfaceType", "uvBounds"], module: 'operations',
         geometryArgs: [0], reason: 'shape → Result(Shape3D)，brep-op',
         args: 'gridPattern(shape: Shape, directionX: Vec3, directionY: Vec3, countX: number, countY: number, spacingX: number, spacingY: number): Shape',
         params: ['shape', 'directionX', 'directionY', 'countX', 'countY', 'spacingX', 'spacingY'], formClass: 'A',
@@ -1482,14 +1484,14 @@ export const ARG_SPEC = [
         naming: { kind: 'replicate', k: 0 },
     },
     {
-        name: 'roof', source: 'operations/roofFns.js#roof', kind: 'brep-op', module: 'operations',
+        name: 'roof', source: 'operations/roofFns.js#roof', kind: 'brep-op', capabilities: ["buildTriFace", "dispose", "fixShape", "isValid", "sew", "sewAndSolidify"], module: 'operations',
         geometryArgs: [0], reason: 'wire → Result(ValidSolid)→solid，brep-op',
         args: 'roof(wire: Shape, options?: RoofOptions): Shape',
         params: ['wire', 'options'], formClass: 'A',
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'drill', source: 'operations/compoundOpsFns.js#drill', kind: 'brep-op', module: 'operations',
+        name: 'drill', source: 'operations/compoundOpsFns.js#drill', kind: 'brep-op', capabilities: ["boundingBox", "cut", "cutWithHistory", "dispose", "isNull", "makeCylinder"], module: 'operations',
         geometryArgs: [0], reason: 'Shapeable<Shape3D> → Result<T>，brep-op',
         args: 'drill(shape: Shape, options: DrillOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
@@ -1497,7 +1499,7 @@ export const ARG_SPEC = [
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'pocket', source: 'operations/compoundOpsFns.js#pocket', kind: 'brep-op', module: 'operations',
+        name: 'pocket', source: 'operations/compoundOpsFns.js#pocket', kind: 'brep-op', capabilities: ["addHolesInFace", "cut", "cutWithHistory", "dispose", "downcast", "extrude", "isNull", "makeFace", "surfaceCenterOfMass", "surfaceNormal", "surfaceType", "translateWithHistory", "uvBounds"], module: 'operations',
         geometryArgs: [0], reason: 'Shapeable<Shape3D> → Result<T>，brep-op',
         args: 'pocket(shape: Shape, options: PocketOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
@@ -1505,7 +1507,7 @@ export const ARG_SPEC = [
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'boss', source: 'operations/compoundOpsFns.js#boss', kind: 'brep-op', module: 'operations',
+        name: 'boss', source: 'operations/compoundOpsFns.js#boss', kind: 'brep-op', capabilities: ["addHolesInFace", "dispose", "downcast", "extrude", "fuse", "fuseWithHistory", "isNull", "makeFace", "surfaceCenterOfMass", "surfaceNormal", "surfaceType", "translateWithHistory", "uvBounds"], module: 'operations',
         geometryArgs: [0], reason: 'Shapeable<Shape3D> → Result<T>，brep-op',
         args: 'boss(shape: Shape, options: BossOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
@@ -1513,7 +1515,7 @@ export const ARG_SPEC = [
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'mirrorJoin', source: 'operations/compoundOpsFns.js#mirrorJoin', kind: 'brep-op', module: 'operations',
+        name: 'mirrorJoin', source: 'operations/compoundOpsFns.js#mirrorJoin', kind: 'brep-op', capabilities: ["dispose", "fuse", "fuseWithHistory", "isNull", "mirrorWithHistory"], module: 'operations',
         geometryArgs: [0], reason: 'Shapeable<Shape3D> → Result<T>，brep-op',
         args: 'mirrorJoin(shape: Shape, options?: MirrorJoinOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
@@ -1521,7 +1523,7 @@ export const ARG_SPEC = [
         naming: { kind: 'replicate', k: 2 },
     },
     {
-        name: 'rectangularPattern', source: 'operations/compoundOpsFns.js#rectangularPattern', kind: 'brep-op', module: 'operations',
+        name: 'rectangularPattern', source: 'operations/compoundOpsFns.js#rectangularPattern', kind: 'brep-op', capabilities: ["dispose", "fuse", "fuseAll", "fuseWithHistory", "hashCode", "isNull", "iterShapes", "section", "surfaceCenterOfMass", "surfaceNormal", "surfaceType", "translateWithHistory", "uvBounds"], module: 'operations',
         geometryArgs: [0], reason: 'Shapeable<Shape3D> → Result<T>，brep-op',
         args: 'rectangularPattern(shape: Shape, options: RectangularPatternOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
@@ -1529,14 +1531,14 @@ export const ARG_SPEC = [
         naming: { kind: 'replicate', k: 0 },
     },
     {
-        name: 'thread', source: 'operations/threadFns.js#thread', kind: 'brep-op', module: 'operations',
+        name: 'thread', source: 'operations/threadFns.js#thread', kind: 'brep-op', capabilities: ["dispose", "loftAdvanced", "makeLineEdge", "makeVertex", "makeWireFromMixed", "shapeType"], module: 'operations',
         geometryArgs: [], reason: '仅参数构造 → Result(Shape3D)，单产物，brep-op',
         args: 'thread(options: ThreadOptions): Shape',
         params: ['options'], formClass: 'B1',
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'convexHull', source: 'operations/convexHullFns.js#convexHull', kind: 'brep-op', module: 'operations',
+        name: 'convexHull', source: 'operations/convexHullFns.js#convexHull', kind: 'brep-op', capabilities: ["dispose", "hullFromPoints", "shapeType"], module: 'operations',
         geometryArgs: [], reason: '点集构造 → Result(Solid)，单产物，brep-op',
         args: 'convexHull(points: Vec3[]): Shape',
         params: ['points'], formClass: 'A',
@@ -2227,7 +2229,7 @@ export const ARG_SPEC = [
     },
     // 1 × brep-op（构造类：纯数值参数 → Shape3D，无几何输入）
     {
-        name: 'makeBaseBox', source: 'sketching/shortcuts.js#makeBaseBox', kind: 'brep-op', module: 'sketching',
+        name: 'makeBaseBox', source: 'sketching/shortcuts.js#makeBaseBox', kind: 'brep-op', capabilities: ["addHolesInFace", "buildEdgeOnSurface", "buildExtrusionLaw", "copyShape", "curveParameters", "curvePointAtParam", "curveTangent", "dispose", "downcast", "extrude", "isNull", "loftAdvanced", "makeFace", "makeFaceOnSurface", "makeVertex", "makeWireFromMixed", "mirror", "revolveVec", "shapeType", "simplePipe", "surfaceType", "sweepPipeShell"], module: 'sketching',
         args: '(xLength: number, yLength: number, zLength: number) -> Shape3D',
         geometryArgs: [],
         returnsResult: false,
@@ -2510,7 +2512,7 @@ export const ARG_SPEC = [
         reason: 'overridden by handwritten api/primitives.ts (cone dual-op, mesh+brep)',
     },
     {
-        name: 'ellipsoid', source: 'topology/primitiveFns.js#ellipsoid', kind: 'brep-op',
+        name: 'ellipsoid', source: 'topology/primitiveFns.js#ellipsoid', kind: 'brep-op', capabilities: ["dispose", "makeEllipsoid", "translateWithHistory"],
         geometryArgs: [], returnsResult: false,
         args: 'ellipsoid(rx: number, ry: number, rz: number, options?: EllipsoidOptions): Shape',
         reason: '纯数值整件构造（rx/ry/rz → ValidSolid），brep-op',
@@ -2609,7 +2611,7 @@ export const ARG_SPEC = [
         reason: 'faijs 同名 translate（§5.1 双形态：对象形态手写面覆盖 + v:Vec3 位置形态并入），生成层不重复投影',
     },
     {
-        name: 'rotate', source: 'topology/api.js#rotate', kind: 'brep-op',
+        name: 'rotate', source: 'topology/api.js#rotate', kind: 'brep-op', capabilities: ["dispose", "rotateWithHistory"],
         geometryArgs: [0], returnsResult: false,
         args: 'rotate(shape: Shape, angle: number, options?: { at?, axis? }): Shape',
         reason: 'faijs rotate 已更名 rotate_euler（faijs 面只导出 rotate_euler），上游轴角 rotate 空出 → brep-op 进脚本面'
@@ -2625,7 +2627,7 @@ export const ARG_SPEC = [
         reason: 'overridden by handwritten api/transform.ts (scale dual-op, mesh+brep)',
     },
     {
-        name: 'mirror', source: 'topology/api.js#mirror', kind: 'brep-op',
+        name: 'mirror', source: 'topology/api.js#mirror', kind: 'brep-op', capabilities: ["dispose", "mirrorWithHistory"],
         geometryArgs: [0], returnsResult: false,
         args: 'mirror(shape: Shape, options?: MirrorOptions): Shape',
         reason: 'faijs 无同名 mirror，整件反射 → brep-op',
@@ -2634,7 +2636,7 @@ export const ARG_SPEC = [
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'clone', source: 'topology/api.js#clone', kind: 'brep-op',
+        name: 'clone', source: 'topology/api.js#clone', kind: 'brep-op', capabilities: ["copyShape", "dispose"],
         geometryArgs: [0], returnsResult: true,
         args: 'clone(shape: Shape): Shape',
         reason: 'faijs 用 copy（不同名），整件克隆（Result<T>）→ brep-op',
@@ -2643,7 +2645,7 @@ export const ARG_SPEC = [
         naming: { kind: 'identity' },
     },
     {
-        name: 'applyMatrix', source: 'topology/api.js#applyMatrix', kind: 'brep-op',
+        name: 'applyMatrix', source: 'topology/api.js#applyMatrix', kind: 'brep-op', capabilities: ["dispose", "generalTransformNonOrthogonal", "generalTransformWithHistory", "hashCode", "iterShapes", "surfaceCenterOfMass", "surfaceNormal", "surfaceType", "uvBounds"],
         geometryArgs: [0], returnsResult: true,
         args: 'applyMatrix(shape: Shape, matrix: unknown): Shape',
         reason: 'faijs 用 applyTransform（不同名），整件矩阵变换 → brep-op',
@@ -2652,16 +2654,15 @@ export const ARG_SPEC = [
         naming: { kind: 'identity' },
     },
     {
-        name: 'transformCopy', source: 'topology/api.js#transformCopy', kind: 'brep-op',
+        name: 'transformCopy', source: 'topology/api.js#transformCopy', kind: 'skip',
         geometryArgs: [0], returnsResult: false,
         args: 'transformCopy(shape: Shape, composed: ComposedTransform): Shape',
-        reason: 'faijs 无同名，克隆+复合变换 → brep-op',
+        reason: 'scriptFace: ComposedTransform holds a kernel WASM handle — not constructible in .fai.js (no literal/params path), so the script-face op is dead. Covered by clone+translate/rotate chains and locate. TS library surface keeps the plain re-export (non-op).',
         params: ['shape', 'composed'], formClass: 'A',
-        scriptFace: true,
         naming: { kind: 'identity' },
     },
     {
-        name: 'locate', source: 'topology/api.js#locate', kind: 'brep-op',
+        name: 'locate', source: 'topology/api.js#locate', kind: 'brep-op', capabilities: ["composeTransform", "dispose", "hashCode", "locate"],
         geometryArgs: [0], returnsResult: false,
         args: 'locate(shape: Shape, placement: unknown): Shape',
         reason: 'faijs 无同名，整件定位变换 → brep-op',
@@ -2698,7 +2699,7 @@ export const ARG_SPEC = [
             + '（含 UI ops 与存量迁移）——生成期守卫见 gen-l3-surface.ts（§4.8 触发条件）。',
     },
     {
-        name: 'section', source: 'topology/api.js#section', kind: 'brep-op',
+        name: 'section', source: 'topology/api.js#section', kind: 'brep-op', capabilities: ["dispose", "isNull", "section"],
         geometryArgs: [0], returnsResult: true,
         args: 'section(shape: Shape, plane: PlaneInput): Shape',
         params: ['shape', 'plane'], formClass: 'A',
@@ -2709,7 +2710,7 @@ export const ARG_SPEC = [
         reason: '返回 Face 子形状产物，faijs 整件面不承载，skip',
     },
     {
-        name: 'split', source: 'topology/api.js#split', kind: 'brep-op',
+        name: 'split', source: 'topology/api.js#split', kind: 'brep-op', capabilities: ["dispose", "isNull", "split"],
         geometryArgs: [0], returnsResult: true,
         args: 'split(shape: Shape, tools: Shape[]): Shape',
         reason: 'faijs split 已更名 fai_split，上游工具切件 split 空出 → brep-op（§5.1 D-SPLIT；tools 暂登记几何首参，数组切件经 faijs 侧适配）',
@@ -2731,14 +2732,14 @@ export const ARG_SPEC = [
         reason: 'faijs 同名 chamfer（§5.1 O-CHAMFER-1：role 取边已保留，上游 Edge 句柄取边形态待处置），生成层不重复投影',
     },
     {
-        name: 'shell', source: 'topology/api.js#shell', kind: 'brep-op',
+        name: 'shell', source: 'topology/api.js#shell', kind: 'brep-op', capabilities: ["dispose", "shapeType", "shell", "shellWithHistory"],
         geometryArgs: [0], returnsResult: true,
         args: 'shell(shape: Shape, faces?: Shape[], thickness: number): Shape',
         params: ['shape', 'faces', 'thickness'], formClass: 'A',
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'offset', source: 'topology/api.js#offset', kind: 'brep-op',
+        name: 'offset', source: 'topology/api.js#offset', kind: 'brep-op', capabilities: ["dispose", "offsetWithHistory", "shapeType"],
         geometryArgs: [0], returnsResult: true,
         args: 'offset(shape: Shape, distance: number): Shape',
         reason: 'faijs 无同名偏置 → brep-op',
@@ -2755,7 +2756,7 @@ export const ARG_SPEC = [
         reason: 'DraftOptions 含 NeutralPlane 等 face 引用，faijs 面引用体系不同，skip',
     },
     {
-        name: 'heal', source: 'topology/api.js#heal', kind: 'brep-op',
+        name: 'heal', source: 'topology/api.js#heal', kind: 'brep-op', capabilities: ["dispose", "healFace", "healSolid", "healWire", "isValid", "shapeType"],
         geometryArgs: [0], returnsResult: true,
         args: 'heal(shape: Shape): Shape',
         reason: 'faijs 无同名整件修复 → brep-op',
@@ -2764,7 +2765,7 @@ export const ARG_SPEC = [
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'simplify', source: 'topology/api.js#simplify', kind: 'brep-op',
+        name: 'simplify', source: 'topology/api.js#simplify', kind: 'brep-op', capabilities: ["dispose", "simplify"],
         geometryArgs: [0], returnsResult: true,
         args: 'simplify(shape: Shape): Shape',
         reason: 'faijs 无同名整件简化 → brep-op',
@@ -3060,7 +3061,7 @@ export const ARG_SPEC = [
     },
     // healingFns：整件修复 brep-op；face/wire 级修复与 shell 组装 skip
     {
-        name: 'autoHeal', source: 'topology/healingFns.js#autoHeal', kind: 'brep-op',
+        name: 'autoHeal', source: 'topology/healingFns.js#autoHeal', kind: 'brep-op', capabilities: ["dispose", "fixSelfIntersection", "healFace", "healSolid", "healWire", "isValid", "iterShapes", "sew", "shapeType"],
         geometryArgs: [0], returnsResult: true,
         args: 'autoHeal(shape: Shape, options?: AutoHealOptions): Shape',
         reason: '整件自动修复（Result<Shape>），brep-op',
@@ -3069,7 +3070,7 @@ export const ARG_SPEC = [
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'fixShape', source: 'topology/healingFns.js#fixShape', kind: 'brep-op',
+        name: 'fixShape', source: 'topology/healingFns.js#fixShape', kind: 'brep-op', capabilities: ["fixShape"],
         geometryArgs: [0], returnsResult: true,
         args: 'fixShape(shape: Shape): Shape',
         reason: '整件修复（Result<Shape>），brep-op',
@@ -3078,7 +3079,7 @@ export const ARG_SPEC = [
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'healSolid', source: 'topology/healingFns.js#healSolid', kind: 'brep-op',
+        name: 'healSolid', source: 'topology/healingFns.js#healSolid', kind: 'brep-op', capabilities: ["dispose", "healSolid", "isValid", "shapeType"],
         geometryArgs: [0], returnsResult: true,
         args: 'healSolid(solid: Shape): Shape',
         reason: 'Solid 修复（Result<ValidSolid>），brep-op',
@@ -3087,7 +3088,7 @@ export const ARG_SPEC = [
         naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'fixSelfIntersection', source: 'topology/healingFns.js#fixSelfIntersection', kind: 'brep-op',
+        name: 'fixSelfIntersection', source: 'topology/healingFns.js#fixSelfIntersection', kind: 'brep-op', capabilities: ["dispose", "fixSelfIntersection", "shapeType"],
         geometryArgs: [0], returnsResult: true,
         args: 'fixSelfIntersection(shape: Shape): Shape',
         params: ['shape'], formClass: 'A',