@faicad/faijs 0.13.2 → 0.14.1

package/dist/api/sketch.js

@@ -145,5 +145,6 @@ export const sketch = defineOp({
         assertSketchParams(params);
         return sketchBrep(params);
     },
+    naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [] } },
 });
 //# sourceMappingURL=sketch.js.map

package/dist/api/sketch.js.map

@@ -1 +1 @@
-{"version":3,"file":"sketch.js","sourceRoot":"","sources":["../../src/api/sketch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib sketch — 从 2D 轮廓构面（creator 函数，无输入，brep-only）。\n *\n * 用途：faijs 此前没有「从 2D 轮廓构造 planar face」的能力，导致草图轮廓无法喂给\n * extrude/revolve。本 op 接收 2D 轮廓（线段 + 圆弧），在 z=0 平面用 OCCT 构面：\n *   makeLineEdge/makeArcEdge → makeWire → makeFace（+ addHolesInFace）。\n *\n * 设计：\n * - 输入：{ contours: SketchLoop[] }，每个 loop = 有序 segments（line / arc，z=0）。\n * - 外环 = 面积（shoelace）绝对值最大的 loop；其余 loop 作为孔。\n * - 圆弧：用起点/中点/终点三点的 makeArcEdge；整圆（sweep≈2π）拆成两段弧。\n * - 输出：Shape（mesh 三角化 + 句柄登记）。brep-only（下游 extrude/revolve 亦 brep-only）。\n *\n * 坐标系：输入 2D 点即 (x, y, 0)，法向 +Z；草图在 Body 局部系内的定位由调用方（fcstd 端口）\n * 在轮廓坐标里预先变换，或由下游特征的 Placement 承担。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport { getBackends } from '../runtime-state'\nimport { solidToShape } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\n\n// ── 参数形状（与 fcstd Contour 结构相同，避免引擎依赖端口层）──\n\n/** 直线段（2D，z=0；端点为绝对坐标）。 */\nexport interface SketchLineSeg {\n  kind: 'line'\n  x1: number\n  y1: number\n  x2: number\n  y2: number\n}\n\n/** 圆弧段（圆心 + 半径 + 起止角，弧度；z=0）。 */\nexport interface SketchArcSeg {\n  kind: 'arc'\n  cx: number\n  cy: number\n  radius: number\n  /** 起始角（弧度） */\n  startAngle: number\n  /** 终止角（弧度） */\n  endAngle: number\n  ccw: boolean\n  x1: number\n  y1: number\n  x2: number\n  y2: number\n}\n\n/** 一条有序 2D 轮廓段（直线或圆弧）。 */\nexport type SketchSeg = SketchLineSeg | SketchArcSeg\n\n/** 单个轮廓环：有序段序列（首尾相接）。 */\nexport interface SketchLoop {\n  segments: SketchSeg[]\n}\n\n/** `cad.sketch` 参数：轮廓环集合（第一个为外环，其余为孔）。 */\nexport interface SketchContoursParams {\n  contours: SketchLoop[]\n}\n\n// ── 参数自校验 ──\n\n/**\n * Validate sketch parameters: `contours` must be a non-empty array of loops,\n * each with at least one segment.\n * @param params the raw sketch operation parameters.\n */\nexport function assertSketchParams(params: Record<string, unknown>): void {\n  const contours = params.contours\n  if (!Array.isArray(contours) || contours.length === 0) {\n    throw new Error('E_SKETCH_NO_CONTOURS: sketch requires at least one contour')\n  }\n  for (const loop of contours) {\n    if (!loop || typeof loop !== 'object' || !Array.isArray((loop as SketchLoop).segments)) {\n      throw new Error('E_SKETCH_BAD_LOOP: each contour must have a segments array')\n    }\n    if ((loop as SketchLoop).segments.length === 0) {\n      throw new Error('E_SKETCH_EMPTY_LOOP: a contour must have at least one segment')\n    }\n  }\n}\n\n/** 单环 shoelace 面积（带符号）。 */\nfunction loopSignedArea(loop: SketchLoop): number {\n  const pts: Array<[number, number]> = []\n  for (const seg of loop.segments) {\n    pts.push([seg.x1, seg.y1])\n  }\n  let a = 0\n  for (let i = 0; i < pts.length; i++) {\n    const [x1, y1] = pts[i]!\n    const [x2, y2] = pts[(i + 1) % pts.length]!\n    a += x1 * y2 - x2 * y1\n  }\n  return a / 2\n}\n\n/** 圆弧 → 一条或两条 makeArcEdge（整圆拆分）。 */\nfunction arcToHandles(\n  kernel: BrepEngineApi,\n  seg: SketchArcSeg,\n): ReturnType<BrepEngineApi['makeArcEdge']>[] {\n  const { cx, cy, radius, startAngle, endAngle } = seg\n  let sweep = endAngle - startAngle\n  // 归一化到 (0, 2π]，处理角度回绕\n  while (sweep <= 0) sweep += 2 * Math.PI\n  while (sweep > 2 * Math.PI) sweep -= 2 * Math.PI\n\n  const makeOne = (a0: number, a1: number): ReturnType<BrepEngineApi['makeArcEdge']> => {\n    const mid = (a0 + a1) / 2\n    const start = { x: cx + radius * Math.cos(a0), y: cy + radius * Math.sin(a0), z: 0 }\n    const m = { x: cx + radius * Math.cos(mid), y: cy + radius * Math.sin(mid), z: 0 }\n    const end = { x: cx + radius * Math.cos(a1), y: cy + radius * Math.sin(a1), z: 0 }\n    return kernel.makeArcEdge(start, m, end)\n  }\n\n  // 整圆（sweep≈2π）：拆成两段半圆，避免 makeArcEdge 起点≈终点退化\n  if (sweep >= 2 * Math.PI - 1e-9) {\n    const half = 2 * Math.PI / 2\n    return [makeOne(startAngle, startAngle + half), makeOne(startAngle + half, startAngle + 2 * Math.PI)]\n  }\n  return [makeOne(startAngle, endAngle)]\n}\n\n/** 单环 → wire handle（仅构面，不释放中间句柄，遵循现有惯例）。 */\nfunction loopToWire(kernel: BrepEngineApi, loop: SketchLoop): ReturnType<BrepEngineApi['makeWire']> {\n  const edges: ReturnType<BrepEngineApi['makeLineEdge']>[] = []\n  for (const seg of loop.segments) {\n    if (seg.kind === 'line') {\n      edges.push(kernel.makeLineEdge({ x: seg.x1, y: seg.y1, z: 0 }, { x: seg.x2, y: seg.y2, z: 0 }))\n    } else {\n      // 极小扫角（退化弧）→ 退化为线段，避免构边失败\n      let sweep = seg.endAngle - seg.startAngle\n      while (sweep <= 0) sweep += 2 * Math.PI\n      while (sweep > 2 * Math.PI) sweep -= 2 * Math.PI\n      if (sweep < 1e-9) {\n        edges.push(kernel.makeLineEdge({ x: seg.x1, y: seg.y1, z: 0 }, { x: seg.x2, y: seg.y2, z: 0 }))\n      } else {\n        edges.push(...arcToHandles(kernel, seg))\n      }\n    }\n  }\n  return kernel.makeWire(edges as ReturnType<BrepEngineApi['makeLineEdge']>[])\n}\n\n/** BREP 路径：2D 轮廓 → planar face（外环 + 孔）。 */\nfunction sketchBrep(params: Record<string, unknown>): Shape {\n  const kernel = getBackends().kernel.brep as BrepEngineApi | null\n  if (!kernel) throw new Error('[stdlib/sketch] no BREP kernel')\n\n  const loops = (params.contours as SketchLoop[]).map((loop) => ({ loop, area: Math.abs(loopSignedArea(loop)) }))\n  // 面积最大者为外环，其余为孔\n  let outerIdx = 0\n  for (let i = 1; i < loops.length; i++) {\n    if (loops[i]!.area > loops[outerIdx]!.area) outerIdx = i\n  }\n\n  const outerWire = loopToWire(kernel, loops[outerIdx]!.loop)\n  const face = kernel.makeFace(outerWire)\n\n  const holeWires: ReturnType<BrepEngineApi['makeWire']>[] = []\n  for (let i = 0; i < loops.length; i++) {\n    if (i === outerIdx) continue\n    holeWires.push(loopToWire(kernel, loops[i]!.loop))\n  }\n  if (holeWires.length > 0) {\n    const faced = kernel.addHolesInFace(face, holeWires)\n    kernel.release(face)\n    return fromBrep(solidToShape(kernel, faced), { solid: faced })\n  }\n\n  kernel.release(outerWire)\n  return fromBrep(solidToShape(kernel, face), { solid: face })\n}\n\n/**\n * 从 2D 轮廓构造平面（creator，无输入）。仅 BREP 可用。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sketch\n * @returns Shape 平面几何（mesh 三角化 + BREP 句柄）。\n * @param params.contours - 有序 2D 轮廓（线段/圆弧；外环 + 孔）。type:SketchLoop[] required:true\n * @example\n * const f = cad.sketch({ contours: [{ segments: [{ kind:'line', x1:0,y1:0,x2:10,y2:0 }, ...] }] })\n */\nexport const sketch = defineOp({\n  capabilities: ['directEdit'],\n  brep(params: Record<string, unknown>) {\n    assertSketchParams(params)\n    return sketchBrep(params)\n  },\n})\n"]}
+{"version":3,"file":"sketch.js","sourceRoot":"","sources":["../../src/api/sketch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib sketch — 从 2D 轮廓构面（creator 函数，无输入，brep-only）。\n *\n * 用途：faijs 此前没有「从 2D 轮廓构造 planar face」的能力，导致草图轮廓无法喂给\n * extrude/revolve。本 op 接收 2D 轮廓（线段 + 圆弧），在 z=0 平面用 OCCT 构面：\n *   makeLineEdge/makeArcEdge → makeWire → makeFace（+ addHolesInFace）。\n *\n * 设计：\n * - 输入：{ contours: SketchLoop[] }，每个 loop = 有序 segments（line / arc，z=0）。\n * - 外环 = 面积（shoelace）绝对值最大的 loop；其余 loop 作为孔。\n * - 圆弧：用起点/中点/终点三点的 makeArcEdge；整圆（sweep≈2π）拆成两段弧。\n * - 输出：Shape（mesh 三角化 + 句柄登记）。brep-only（下游 extrude/revolve 亦 brep-only）。\n *\n * 坐标系：输入 2D 点即 (x, y, 0)，法向 +Z；草图在 Body 局部系内的定位由调用方（fcstd 端口）\n * 在轮廓坐标里预先变换，或由下游特征的 Placement 承担。\n */\n\nimport type { Shape } from '../mesh/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\nimport { getBackends } from '../runtime-state'\nimport { solidToShape } from '../brep/brep-ops'\nimport { fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\n\n// ── 参数形状（与 fcstd Contour 结构相同，避免引擎依赖端口层）──\n\n/** 直线段（2D，z=0；端点为绝对坐标）。 */\nexport interface SketchLineSeg {\n  kind: 'line'\n  x1: number\n  y1: number\n  x2: number\n  y2: number\n}\n\n/** 圆弧段（圆心 + 半径 + 起止角，弧度；z=0）。 */\nexport interface SketchArcSeg {\n  kind: 'arc'\n  cx: number\n  cy: number\n  radius: number\n  /** 起始角（弧度） */\n  startAngle: number\n  /** 终止角（弧度） */\n  endAngle: number\n  ccw: boolean\n  x1: number\n  y1: number\n  x2: number\n  y2: number\n}\n\n/** 一条有序 2D 轮廓段（直线或圆弧）。 */\nexport type SketchSeg = SketchLineSeg | SketchArcSeg\n\n/** 单个轮廓环：有序段序列（首尾相接）。 */\nexport interface SketchLoop {\n  segments: SketchSeg[]\n}\n\n/** `cad.sketch` 参数：轮廓环集合（第一个为外环，其余为孔）。 */\nexport interface SketchContoursParams {\n  contours: SketchLoop[]\n}\n\n// ── 参数自校验 ──\n\n/**\n * Validate sketch parameters: `contours` must be a non-empty array of loops,\n * each with at least one segment.\n * @param params the raw sketch operation parameters.\n */\nexport function assertSketchParams(params: Record<string, unknown>): void {\n  const contours = params.contours\n  if (!Array.isArray(contours) || contours.length === 0) {\n    throw new Error('E_SKETCH_NO_CONTOURS: sketch requires at least one contour')\n  }\n  for (const loop of contours) {\n    if (!loop || typeof loop !== 'object' || !Array.isArray((loop as SketchLoop).segments)) {\n      throw new Error('E_SKETCH_BAD_LOOP: each contour must have a segments array')\n    }\n    if ((loop as SketchLoop).segments.length === 0) {\n      throw new Error('E_SKETCH_EMPTY_LOOP: a contour must have at least one segment')\n    }\n  }\n}\n\n/** 单环 shoelace 面积（带符号）。 */\nfunction loopSignedArea(loop: SketchLoop): number {\n  const pts: Array<[number, number]> = []\n  for (const seg of loop.segments) {\n    pts.push([seg.x1, seg.y1])\n  }\n  let a = 0\n  for (let i = 0; i < pts.length; i++) {\n    const [x1, y1] = pts[i]!\n    const [x2, y2] = pts[(i + 1) % pts.length]!\n    a += x1 * y2 - x2 * y1\n  }\n  return a / 2\n}\n\n/** 圆弧 → 一条或两条 makeArcEdge（整圆拆分）。 */\nfunction arcToHandles(\n  kernel: BrepEngineApi,\n  seg: SketchArcSeg,\n): ReturnType<BrepEngineApi['makeArcEdge']>[] {\n  const { cx, cy, radius, startAngle, endAngle } = seg\n  let sweep = endAngle - startAngle\n  // 归一化到 (0, 2π]，处理角度回绕\n  while (sweep <= 0) sweep += 2 * Math.PI\n  while (sweep > 2 * Math.PI) sweep -= 2 * Math.PI\n\n  const makeOne = (a0: number, a1: number): ReturnType<BrepEngineApi['makeArcEdge']> => {\n    const mid = (a0 + a1) / 2\n    const start = { x: cx + radius * Math.cos(a0), y: cy + radius * Math.sin(a0), z: 0 }\n    const m = { x: cx + radius * Math.cos(mid), y: cy + radius * Math.sin(mid), z: 0 }\n    const end = { x: cx + radius * Math.cos(a1), y: cy + radius * Math.sin(a1), z: 0 }\n    return kernel.makeArcEdge(start, m, end)\n  }\n\n  // 整圆（sweep≈2π）：拆成两段半圆，避免 makeArcEdge 起点≈终点退化\n  if (sweep >= 2 * Math.PI - 1e-9) {\n    const half = 2 * Math.PI / 2\n    return [makeOne(startAngle, startAngle + half), makeOne(startAngle + half, startAngle + 2 * Math.PI)]\n  }\n  return [makeOne(startAngle, endAngle)]\n}\n\n/** 单环 → wire handle（仅构面，不释放中间句柄，遵循现有惯例）。 */\nfunction loopToWire(kernel: BrepEngineApi, loop: SketchLoop): ReturnType<BrepEngineApi['makeWire']> {\n  const edges: ReturnType<BrepEngineApi['makeLineEdge']>[] = []\n  for (const seg of loop.segments) {\n    if (seg.kind === 'line') {\n      edges.push(kernel.makeLineEdge({ x: seg.x1, y: seg.y1, z: 0 }, { x: seg.x2, y: seg.y2, z: 0 }))\n    } else {\n      // 极小扫角（退化弧）→ 退化为线段，避免构边失败\n      let sweep = seg.endAngle - seg.startAngle\n      while (sweep <= 0) sweep += 2 * Math.PI\n      while (sweep > 2 * Math.PI) sweep -= 2 * Math.PI\n      if (sweep < 1e-9) {\n        edges.push(kernel.makeLineEdge({ x: seg.x1, y: seg.y1, z: 0 }, { x: seg.x2, y: seg.y2, z: 0 }))\n      } else {\n        edges.push(...arcToHandles(kernel, seg))\n      }\n    }\n  }\n  return kernel.makeWire(edges as ReturnType<BrepEngineApi['makeLineEdge']>[])\n}\n\n/** BREP 路径：2D 轮廓 → planar face（外环 + 孔）。 */\nfunction sketchBrep(params: Record<string, unknown>): Shape {\n  const kernel = getBackends().kernel.brep as BrepEngineApi | null\n  if (!kernel) throw new Error('[stdlib/sketch] no BREP kernel')\n\n  const loops = (params.contours as SketchLoop[]).map((loop) => ({ loop, area: Math.abs(loopSignedArea(loop)) }))\n  // 面积最大者为外环，其余为孔\n  let outerIdx = 0\n  for (let i = 1; i < loops.length; i++) {\n    if (loops[i]!.area > loops[outerIdx]!.area) outerIdx = i\n  }\n\n  const outerWire = loopToWire(kernel, loops[outerIdx]!.loop)\n  const face = kernel.makeFace(outerWire)\n\n  const holeWires: ReturnType<BrepEngineApi['makeWire']>[] = []\n  for (let i = 0; i < loops.length; i++) {\n    if (i === outerIdx) continue\n    holeWires.push(loopToWire(kernel, loops[i]!.loop))\n  }\n  if (holeWires.length > 0) {\n    const faced = kernel.addHolesInFace(face, holeWires)\n    kernel.release(face)\n    return fromBrep(solidToShape(kernel, faced), { solid: faced })\n  }\n\n  kernel.release(outerWire)\n  return fromBrep(solidToShape(kernel, face), { solid: face })\n}\n\n/**\n * 从 2D 轮廓构造平面（creator，无输入）。仅 BREP 可用。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name sketch\n * @returns Shape 平面几何（mesh 三角化 + BREP 句柄）。\n * @param params.contours - 有序 2D 轮廓（线段/圆弧；外环 + 孔）。type:SketchLoop[] required:true\n * @example\n * const f = cad.sketch({ contours: [{ segments: [{ kind:'line', x1:0,y1:0,x2:10,y2:0 }, ...] }] })\n */\nexport const sketch = defineOp({\n  capabilities: ['directEdit'],\n  brep(params: Record<string, unknown>) {\n    assertSketchParams(params)\n    return sketchBrep(params)\n  },\n  naming: { kind: 'construct', newFaces: { via: 'explicit', vocab: [] } } as Provenance,\n})\n"]}

package/dist/api/split.d.ts

@@ -0,0 +1,31 @@
+/**
+ * stdlib split — split（手写覆盖生成投影，Phase 3: L4 `splinter(#j)` 角色表）
+ *
+ * 生成投影是 brep-only compatOp，不带角色表；本文件手写 defineOp，BREP 路径
+ * 用内核原生 split（BRepAlgoAPI_Splitter）切分，存活面（hash 逐字不变）回投原
+ * role，新造面（截面 + 被切细的侧面片）记 `splinter(#j)`，片序按质心排序保证跨
+ * 重放稳定。
+ *
+ * 机制（无 splitWithHistory，纯 hash 比对 + 几何排序）：`subdivide` 类零声明，
+ * 新造面不对应任何输入面的因果坐标，故挂消费它的那条语句、用稳定的片序 `#j` 区分。
+ */
+import type { Shape } from '../mesh/types.js';
+/**
+ * 用工具几何切分目标几何（BRepAlgoAPI_Splitter），返回所有碎片组成的几何。
+ * @group 特征
+ * @inputs 2
+ * @async true
+ * @qual ok
+ * @name split
+ * @note BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。切分产生的截面 / 被切细的侧面
+ *       片记 `splinter(#j)`（Phase 3 L4 抗重放词汇）。
+ * @returns Shape 切分后的几何（compound of pieces）。
+ * @param input - 目标几何。type:Shape required:true
+ * @param tools - 切刀几何（数组）。type:Shape[] required:true
+ * @example
+ * const pieces = await cad.split(part0, [part1])
+ */
+export declare const split: ((input: Shape, tools: Shape[]) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=split.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"split.d.ts","sourceRoot":"","sources":["../../src/api/split.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAwE1C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK;;CAKhB,CAAA"}

package/dist/api/split.js

@@ -0,0 +1,96 @@
+/**
+ * stdlib split — split（手写覆盖生成投影，Phase 3: L4 `splinter(#j)` 角色表）
+ *
+ * 生成投影是 brep-only compatOp，不带角色表；本文件手写 defineOp，BREP 路径
+ * 用内核原生 split（BRepAlgoAPI_Splitter）切分，存活面（hash 逐字不变）回投原
+ * role，新造面（截面 + 被切细的侧面片）记 `splinter(#j)`，片序按质心排序保证跨
+ * 重放稳定。
+ *
+ * 机制（无 splitWithHistory，纯 hash 比对 + 几何排序）：`subdivide` 类零声明，
+ * 新造面不对应任何输入面的因果坐标，故挂消费它的那条语句、用稳定的片序 `#j` 区分。
+ */
+import { solidToShape } from '../brep/brep-ops.js';
+import { getFaceHashes } from '../brep/face-evolution.js';
+import { getBackends, getCurrentStmt } from '../runtime-state.js';
+import { fromBrep, brepOf, inputRoleTable } from '../shape.js';
+import { defineOp } from '../sdk.js';
+/** BREP 路径：用 tools 切分 input，存活面回投、新造面记 `splinter(#j)`。 */
+function splitBrep(input, tools) {
+    const kernel = getBackends().kernel.brep;
+    if (!kernel)
+        throw new Error('[stdlib/split] no OCCT kernel');
+    const inputSolid = brepOf(input);
+    if (!inputSolid)
+        throw new Error('[stdlib/split] input is not BREP');
+    const toolSolids = tools
+        .map((t) => brepOf(t))
+        .filter((s) => !!s);
+    if (toolSolids.length === 0)
+        return input;
+    // Phase 1.6：origin = 本次语句 StmtId。
+    const outStmt = String(getCurrentStmt()?.id ?? '');
+    const inputTable = inputRoleTable(input);
+    const inputHashes = getFaceHashes(kernel, inputSolid);
+    const inputHashSet = new Set(inputHashes);
+    const inputHashToRole = new Map();
+    if (inputTable) {
+        for (const roles of inputTable.values()) {
+            for (const [role, hashes] of roles)
+                for (const h of hashes)
+                    inputHashToRole.set(h, role);
+        }
+    }
+    // 内核原生 split（BRepAlgoAPI_Splitter）返回包含所有碎片的 compound
+    const resultSolid = kernel.split(inputSolid, toolSolids);
+    const resultHashes = getFaceHashes(kernel, resultSolid);
+    const resultFaces = kernel.getSubShapes(resultSolid, 'face');
+    const resultCentroids = resultFaces.map((f) => kernel.getSurfaceCenterOfMass(f));
+    const roleTable = new Map();
+    const inner = new Map();
+    // 存活面（hash 逐字不变）→ 回投原 role；其余 = 新造面 → splinter(#j)
+    const newFaces = [];
+    for (let i = 0; i < resultHashes.length; i++) {
+        const h = resultHashes[i];
+        if (inputHashSet.has(h)) {
+            const role = inputHashToRole.get(h);
+            if (role) {
+                if (!inner.has(role))
+                    inner.set(role, []);
+                inner.get(role).push(h);
+            }
+        }
+        else {
+            newFaces.push({ hash: h, c: resultCentroids[i] });
+        }
+    }
+    // 按质心 (x,y,z) 排序保证片序跨重放稳定
+    newFaces.sort((a, b) => a.c.x - b.c.x || a.c.y - b.c.y || a.c.z - b.c.z);
+    for (let j = 0; j < newFaces.length; j++) {
+        const role = `splinter(#${j})`;
+        inner.set(role, [newFaces[j].hash]);
+    }
+    roleTable.set(outStmt, inner);
+    return fromBrep(solidToShape(kernel, resultSolid), { solid: resultSolid, roleTable });
+}
+/**
+ * 用工具几何切分目标几何（BRepAlgoAPI_Splitter），返回所有碎片组成的几何。
+ * @group 特征
+ * @inputs 2
+ * @async true
+ * @qual ok
+ * @name split
+ * @note BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。切分产生的截面 / 被切细的侧面
+ *       片记 `splinter(#j)`（Phase 3 L4 抗重放词汇）。
+ * @returns Shape 切分后的几何（compound of pieces）。
+ * @param input - 目标几何。type:Shape required:true
+ * @param tools - 切刀几何（数组）。type:Shape[] required:true
+ * @example
+ * const pieces = await cad.split(part0, [part1])
+ */
+export const split = defineOp({
+    brep(input, tools) {
+        return splitBrep(input, tools);
+    },
+    naming: { kind: 'subdivide' },
+});
+//# sourceMappingURL=split.js.map

package/dist/api/split.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"split.js","sourceRoot":"","sources":["../../src/api/split.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * stdlib split — split（手写覆盖生成投影，Phase 3: L4 `splinter(#j)` 角色表）\n *\n * 生成投影是 brep-only compatOp，不带角色表；本文件手写 defineOp，BREP 路径\n * 用内核原生 split（BRepAlgoAPI_Splitter）切分，存活面（hash 逐字不变）回投原\n * role，新造面（截面 + 被切细的侧面片）记 `splinter(#j)`，片序按质心排序保证跨\n * 重放稳定。\n *\n * 机制（无 splitWithHistory，纯 hash 比对 + 几何排序）：`subdivide` 类零声明，\n * 新造面不对应任何输入面的因果坐标，故挂消费它的那条语句、用稳定的片序 `#j` 区分。\n */\n\nimport type { Shape } from '../mesh/types'\nimport { solidToShape } from '../brep/brep-ops'\nimport { getFaceHashes } from '../brep/face-evolution'\nimport { getBackends, getCurrentStmt } from '../runtime-state'\nimport { fromBrep, brepOf, inputRoleTable } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport type { RoleTable } from '../topology/naming/types'\nimport type { BrepHandle } from '../brep/engine/types'\nimport type { BrepEngineApi } from '../brep/engine/primitives'\n\n/** BREP 路径：用 tools 切分 input，存活面回投、新造面记 `splinter(#j)`。 */\nfunction splitBrep(input: Shape, tools: Shape[]): Shape {\n  const kernel = getBackends().kernel.brep as BrepEngineApi | null\n  if (!kernel) throw new Error('[stdlib/split] no OCCT kernel')\n  const inputSolid = brepOf(input) as BrepHandle | undefined\n  if (!inputSolid) throw new Error('[stdlib/split] input is not BREP')\n  const toolSolids = tools\n    .map((t) => brepOf(t) as BrepHandle | undefined)\n    .filter((s): s is BrepHandle => !!s)\n  if (toolSolids.length === 0) return input\n\n  // Phase 1.6：origin = 本次语句 StmtId。\n  const outStmt = String(getCurrentStmt()?.id ?? '')\n  const inputTable = inputRoleTable(input) as RoleTable | undefined\n\n  const inputHashes = getFaceHashes(kernel, inputSolid)\n  const inputHashSet = new Set(inputHashes)\n  const inputHashToRole = new Map<number, string>()\n  if (inputTable) {\n    for (const roles of inputTable.values()) {\n      for (const [role, hashes] of roles) for (const h of hashes) inputHashToRole.set(h, role)\n    }\n  }\n\n  // 内核原生 split（BRepAlgoAPI_Splitter）返回包含所有碎片的 compound\n  const resultSolid = (kernel as unknown as {\n    split(s: BrepHandle, tools: BrepHandle[]): BrepHandle\n  }).split(inputSolid, toolSolids)\n\n  const resultHashes = getFaceHashes(kernel, resultSolid)\n  const resultFaces = kernel.getSubShapes(resultSolid, 'face')\n  const resultCentroids = resultFaces.map((f) => kernel.getSurfaceCenterOfMass(f))\n\n  const roleTable = new Map<string, Map<string, number[]>>()\n  const inner = new Map<string, number[]>()\n\n  // 存活面（hash 逐字不变）→ 回投原 role；其余 = 新造面 → splinter(#j)\n  const newFaces: { hash: number; c: { x: number; y: number; z: number } }[] = []\n  for (let i = 0; i < resultHashes.length; i++) {\n    const h = resultHashes[i]!\n    if (inputHashSet.has(h)) {\n      const role = inputHashToRole.get(h)\n      if (role) {\n        if (!inner.has(role)) inner.set(role, [])\n        inner.get(role)!.push(h)\n      }\n    } else {\n      newFaces.push({ hash: h, c: resultCentroids[i]! })\n    }\n  }\n  // 按质心 (x,y,z) 排序保证片序跨重放稳定\n  newFaces.sort((a, b) => a.c.x - b.c.x || a.c.y - b.c.y || a.c.z - b.c.z)\n  for (let j = 0; j < newFaces.length; j++) {\n    const role = `splinter(#${j})`\n    inner.set(role, [newFaces[j].hash])\n  }\n  roleTable.set(outStmt, inner)\n\n  return fromBrep(solidToShape(kernel, resultSolid), { solid: resultSolid, roleTable })\n}\n\n/**\n * 用工具几何切分目标几何（BRepAlgoAPI_Splitter），返回所有碎片组成的几何。\n * @group 特征\n * @inputs 2\n * @async true\n * @qual ok\n * @name split\n * @note BREP-only：非 BREP 输入抛 E_MESH_UNSUPPORTED。切分产生的截面 / 被切细的侧面\n *       片记 `splinter(#j)`（Phase 3 L4 抗重放词汇）。\n * @returns Shape 切分后的几何（compound of pieces）。\n * @param input - 目标几何。type:Shape required:true\n * @param tools - 切刀几何（数组）。type:Shape[] required:true\n * @example\n * const pieces = await cad.split(part0, [part1])\n */\nexport const split = defineOp({\n  brep(input: Shape, tools: Shape[]) {\n    return splitBrep(input, tools)\n  },\n  naming: { kind: 'subdivide' } as Provenance,\n})\n"]}

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

@@ -28,6 +28,8 @@
  */
 /** 生成器可用的投影方式。 */
 export type ProjectionKind = 'brep-op' | 'query' | 'pure' | 'type' | 'skip' | 'faijs';
+import type { Provenance } from '../../topology/naming/lineage.js';
+export type { Provenance } from '../../topology/naming/lineage.js';
 /** brep-op / query 的时间线消费声明（透传 defineOp 元数据，G3/G4）。 */
 /**
  * faijs 面 query 形参描述（P14 机器签名：生成器按此产出函数签名 + JSDoc @param）。
@@ -101,6 +103,13 @@ export interface ArgSpecEntry {
      * 生成器据此产出 api/generated/script-face.ts + script-face-manifest.ts。
      */
     scriptFace?: boolean;
+    /**
+     * Topology identity provenance declaration (plan §4.4 / Phase 2.1).
+     * Required for `kind==='brep-op' && scriptFace===true` (generator guard, 2.2);
+     * encodes the op's face-mapping category + new-face vocabulary.
+     * `import type` from lineage.ts — pure type, no runtime circular dep.
+     */
+    naming?: Provenance;
 }
 /**
  * 首批机制验证样本（P13a）。每个样本都选了 faijs 无同名、brepjs 有完整实现的符号，

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,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;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,YAAY,EAs+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;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"}

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

@@ -48,6 +48,7 @@ export const ARG_SPEC = [
         params: ['majorRadius', 'minorRadius', 'options'],
         formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' },
     },
     {
         name: 'fuse',
@@ -60,6 +61,7 @@ export const ARG_SPEC = [
         params: ['a', 'b', 'options'],
         formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'getBounds',
@@ -1425,30 +1427,35 @@ export const ARG_SPEC = [
         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',
         params: ['face', 'height'], formClass: 'A',
+        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',
         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',
         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',
         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',
         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',
@@ -1456,6 +1463,7 @@ export const ARG_SPEC = [
         args: 'linearPattern(shape: Shape, direction: Vec3, count: number, spacing: number): Shape',
         params: ['shape', 'direction', 'count', 'spacing'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'replicate', k: 0 },
     },
     {
         name: 'circularPattern', source: 'operations/patternFns.js#circularPattern', kind: 'brep-op', module: 'operations',
@@ -1463,6 +1471,7 @@ export const ARG_SPEC = [
         args: 'circularPattern(shape: Shape, axis: Vec3, count: number, fullAngle?: number, center?: Vec3): Shape',
         params: ['shape', 'axis', 'count', 'fullAngle', 'center'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'replicate', k: 0 },
     },
     {
         name: 'gridPattern', source: 'operations/patternFns.js#gridPattern', kind: 'brep-op', module: 'operations',
@@ -1470,12 +1479,14 @@ export const ARG_SPEC = [
         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',
         scriptFace: true,
+        naming: { kind: 'replicate', k: 0 },
     },
     {
         name: 'roof', source: 'operations/roofFns.js#roof', kind: 'brep-op', 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',
@@ -1483,6 +1494,7 @@ export const ARG_SPEC = [
         args: 'drill(shape: Shape, options: DrillOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'pocket', source: 'operations/compoundOpsFns.js#pocket', kind: 'brep-op', module: 'operations',
@@ -1490,6 +1502,7 @@ export const ARG_SPEC = [
         args: 'pocket(shape: Shape, options: PocketOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'boss', source: 'operations/compoundOpsFns.js#boss', kind: 'brep-op', module: 'operations',
@@ -1497,6 +1510,7 @@ export const ARG_SPEC = [
         args: 'boss(shape: Shape, options: BossOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'mirrorJoin', source: 'operations/compoundOpsFns.js#mirrorJoin', kind: 'brep-op', module: 'operations',
@@ -1504,6 +1518,7 @@ export const ARG_SPEC = [
         args: 'mirrorJoin(shape: Shape, options?: MirrorJoinOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'replicate', k: 2 },
     },
     {
         name: 'rectangularPattern', source: 'operations/compoundOpsFns.js#rectangularPattern', kind: 'brep-op', module: 'operations',
@@ -1511,12 +1526,14 @@ export const ARG_SPEC = [
         args: 'rectangularPattern(shape: Shape, options: RectangularPatternOptions): Shape',
         params: ['shape', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'replicate', k: 0 },
     },
     {
         name: 'thread', source: 'operations/threadFns.js#thread', kind: 'brep-op', 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',
@@ -1524,6 +1541,7 @@ export const ARG_SPEC = [
         args: 'convexHull(points: Vec3[]): Shape',
         params: ['points'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' },
     },
     {
         // ---- skip：状态 DSL/多产物/数组入参/host IO/kernel 入参 ----
@@ -2215,6 +2233,7 @@ export const ARG_SPEC = [
         returnsResult: false,
         params: ['xLength', 'yLength', 'zLength'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' },
     },
     // 47 × skip（状态化草图/绘图 DSL 族）
     {
@@ -2472,32 +2491,23 @@ export const ARG_SPEC = [
     // 投影到 brepjs 契约，但**不投 scriptFace**（faijs 侧由手写 dual-op 覆盖，生成模块
     // 符号为孤儿 by design）。
     {
-        name: 'box', source: 'topology/primitiveFns.js#box', kind: 'brep-op',
-        geometryArgs: [], returnsResult: false,
+        name: 'box', source: 'topology/primitiveFns.js#box', kind: 'skip',
         args: 'box(width: number, depth: number, height: number, options?: BoxOptions): Shape',
-        reason: 'faijs 侧由手写 dual-op 覆盖（§4.1 A 决策，mesh+brep 双实现）；本条目仅投影到 vendored 盒契约，生成模块符号为孤儿 by design，scriptFace 不投（避免与手写 box 撞名）。',
-        params: ['width', 'depth', 'height', 'options'], formClass: 'A',
-        scriptFace: false,
+        reason: 'overridden by handwritten api/primitives.ts (box dual-op, mesh+brep)',
     },
     {
         name: 'sphere', source: 'topology/primitiveFns.js#sphere', kind: 'skip',
         reason: 'faijs 同名 sphere（§5.1 双形态同 box），生成层不重复投影',
     },
     {
-        name: 'cylinder', source: 'topology/primitiveFns.js#cylinder', kind: 'brep-op',
-        geometryArgs: [], returnsResult: false,
+        name: 'cylinder', source: 'topology/primitiveFns.js#cylinder', kind: 'skip',
         args: 'cylinder(radius: number, height: number, options?: CylinderOptions): Shape',
-        reason: 'faijs 侧由手写 dual-op 覆盖（§4.3 A 决策，mesh+brep 双实现，at/centered BASE 语义）；本条目仅投影到 vendored 圆柱契约，生成模块符号为孤儿 by design，scriptFace 不投（避免与手写 cylinder 撞名）。',
-        params: ['radius', 'height', 'options'], formClass: 'A',
-        scriptFace: false,
+        reason: 'overridden by handwritten api/primitives.ts (cylinder dual-op, mesh+brep)',
     },
     {
-        name: 'cone', source: 'topology/primitiveFns.js#cone', kind: 'brep-op',
-        geometryArgs: [], returnsResult: false,
+        name: 'cone', source: 'topology/primitiveFns.js#cone', kind: 'skip',
         args: 'cone(radiusBottom: number, radiusTop: number, height: number, options?: ConeOptions): Shape',
-        reason: 'faijs 侧由手写 dual-op 覆盖（§4.1 P 决策，mesh+brep 双实现，at/centered BASE 语义）；本条目仅投影到 vendored 圆锥契约，生成模块符号为孤儿 by design，scriptFace 不投（避免与手写 cone 撞名）。',
-        params: ['radiusBottom', 'radiusTop', 'height', 'options'], formClass: 'A',
-        scriptFace: false,
+        reason: 'overridden by handwritten api/primitives.ts (cone dual-op, mesh+brep)',
     },
     {
         name: 'ellipsoid', source: 'topology/primitiveFns.js#ellipsoid', kind: 'brep-op',
@@ -2506,6 +2516,7 @@ export const ARG_SPEC = [
         reason: '纯数值整件构造（rx/ry/rz → ValidSolid），brep-op',
         params: ['rx', 'ry', 'rz', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'unmodeled', reason: 'construct vocabulary pending Phase 3' },
     },
     {
         name: 'addHoles', source: 'topology/primitiveFns.js#addHoles', kind: 'skip',
@@ -2606,14 +2617,12 @@ export const ARG_SPEC = [
             + '3d_editor UI 不得暴露；将来暴露前必须先补 mesh 实现。',
         params: ['shape', 'angle', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
-        name: 'scale', source: 'topology/api.js#scale', kind: 'brep-op',
-        geometryArgs: [0], returnsResult: false,
+        name: 'scale', source: 'topology/api.js#scale', kind: 'skip',
         args: 'scale(shape: Shape, factor: number, options?: { center?: Vec3 }): Shape',
-        reason: 'faijs 侧由手写 dual-op 覆盖（§4.6 裁决 4/2：scale = vendored 等比 + center 不动点，mesh+brep 双实现）；本条目仅投影到 vendored scale 契约，生成模块符号为孤儿 by design，scriptFace 不投（避免与手写 scale 撞名）。',
-        params: ['shape', 'factor', 'options'], formClass: 'A',
-        scriptFace: false,
+        reason: 'overridden by handwritten api/transform.ts (scale dual-op, mesh+brep)',
     },
     {
         name: 'mirror', source: 'topology/api.js#mirror', kind: 'brep-op',
@@ -2622,6 +2631,7 @@ export const ARG_SPEC = [
         reason: 'faijs 无同名 mirror，整件反射 → brep-op',
         params: ['shape', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'clone', source: 'topology/api.js#clone', kind: 'brep-op',
@@ -2630,6 +2640,7 @@ export const ARG_SPEC = [
         reason: 'faijs 用 copy（不同名），整件克隆（Result<T>）→ brep-op',
         params: ['shape'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'identity' },
     },
     {
         name: 'applyMatrix', source: 'topology/api.js#applyMatrix', kind: 'brep-op',
@@ -2638,6 +2649,7 @@ export const ARG_SPEC = [
         reason: 'faijs 用 applyTransform（不同名），整件矩阵变换 → brep-op',
         params: ['shape', 'matrix'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'identity' },
     },
     {
         name: 'transformCopy', source: 'topology/api.js#transformCopy', kind: 'brep-op',
@@ -2646,6 +2658,7 @@ export const ARG_SPEC = [
         reason: 'faijs 无同名，克隆+复合变换 → brep-op',
         params: ['shape', 'composed'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'identity' },
     },
     {
         name: 'locate', source: 'topology/api.js#locate', kind: 'brep-op',
@@ -2654,18 +2667,20 @@ export const ARG_SPEC = [
         reason: 'faijs 无同名，整件定位变换 → brep-op',
         params: ['shape', 'placement'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'identity' },
     },
     {
         name: 'composeTransforms', source: 'topology/api.js#composeTransforms', kind: 'pure',
         reason: '变换函数组合器（纯数据，无 Shape 参数）',
     },
     {
-        name: 'cut', source: 'topology/api.js#cut', kind: 'brep-op',
+        name: 'cut', source: 'topology/api.js#cut', kind: 'skip',
         geometryArgs: [0, 1], returnsResult: true,
         args: 'cut(base: Shape, tool: Shape, options?: BooleanOptions): Shape',
-        reason: 'faijs 用 subtract（不同名），布尔减 → brep-op',
+        reason: 'overridden by handwritten boolean.ts:cut (Phase 3 roleTable propagation)',
         params: ['base', 'tool', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'fuseAll', source: 'topology/api.js#fuseAll', kind: 'skip',
@@ -2686,8 +2701,8 @@ export const ARG_SPEC = [
         name: 'section', source: 'topology/api.js#section', kind: 'brep-op',
         geometryArgs: [0], returnsResult: true,
         args: 'section(shape: Shape, plane: PlaneInput): Shape',
-        reason: 'faijs 无同名截面查询（平面入参非几何）→ brep-op',
         params: ['shape', 'plane'], formClass: 'A',
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'sectionToFace', source: 'topology/api.js#sectionToFace', kind: 'skip',
@@ -2700,18 +2715,16 @@ export const ARG_SPEC = [
         reason: 'faijs split 已更名 fai_split，上游工具切件 split 空出 → brep-op（§5.1 D-SPLIT；tools 暂登记几何首参，数组切件经 faijs 侧适配）',
         params: ['shape', 'tools'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'subdivide' },
     },
     {
         name: 'slice', source: 'topology/api.js#slice', kind: 'skip',
         reason: 'planes 数组入参且返回 AnyShape[]（多产物），skip',
     },
     {
-        name: 'fillet', source: 'topology/api.js#fillet', kind: 'brep-op',
-        geometryArgs: [0], returnsResult: true,
+        name: 'fillet', source: 'topology/api.js#fillet', kind: 'skip',
         args: 'fillet(shape: Shape, edges?, radius | [r1,r2]): Shape',
-        reason: 'D-FILLET：faijs 侧由手写 dual-op 覆盖（§2.1 等半径 + filletWithHistory roleTable 传播）；本条目仅投影到 vendored fillet 契约，生成模块符号为孤儿 by design，scriptFace 不投（避免与手写 fillet 撞名）。',
-        params: ['shape', 'edges', 'radius'], formClass: 'A',
-        scriptFace: false,
+        reason: 'overridden by handwritten api/fillet.ts (fillet dual-op, roleTable propagation)',
     },
     {
         name: 'chamfer', source: 'topology/api.js#chamfer', kind: 'skip',
@@ -2721,8 +2734,8 @@ export const ARG_SPEC = [
         name: 'shell', source: 'topology/api.js#shell', kind: 'brep-op',
         geometryArgs: [0], returnsResult: true,
         args: 'shell(shape: Shape, faces?: Shape[], thickness: number): Shape',
-        reason: 'faijs 无同名抽壳 → brep-op（faces 可选，整件抽壳可表达）',
         params: ['shape', 'faces', 'thickness'], formClass: 'A',
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'offset', source: 'topology/api.js#offset', kind: 'brep-op',
@@ -2731,6 +2744,7 @@ export const ARG_SPEC = [
         reason: 'faijs 无同名偏置 → brep-op',
         params: ['shape', 'distance'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'thicken', source: 'topology/api.js#thicken', kind: 'skip',
@@ -2747,6 +2761,7 @@ export const ARG_SPEC = [
         reason: 'faijs 无同名整件修复 → brep-op',
         params: ['shape'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'simplify', source: 'topology/api.js#simplify', kind: 'brep-op',
@@ -2755,6 +2770,7 @@ export const ARG_SPEC = [
         reason: 'faijs 无同名整件简化 → brep-op',
         params: ['shape'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'mesh', source: 'topology/api.js#mesh', kind: 'skip',
@@ -3050,6 +3066,7 @@ export const ARG_SPEC = [
         reason: '整件自动修复（Result<Shape>），brep-op',
         params: ['shape', 'options'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'fixShape', source: 'topology/healingFns.js#fixShape', kind: 'brep-op',
@@ -3058,6 +3075,7 @@ export const ARG_SPEC = [
         reason: '整件修复（Result<Shape>），brep-op',
         params: ['shape'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'healSolid', source: 'topology/healingFns.js#healSolid', kind: 'brep-op',
@@ -3066,13 +3084,14 @@ export const ARG_SPEC = [
         reason: 'Solid 修复（Result<ValidSolid>），brep-op',
         params: ['solid'], formClass: 'A',
         scriptFace: true,
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'fixSelfIntersection', source: 'topology/healingFns.js#fixSelfIntersection', kind: 'brep-op',
         geometryArgs: [0], returnsResult: true,
         args: 'fixSelfIntersection(shape: Shape): Shape',
-        reason: '整件自交修复（Result<Shape>），brep-op',
         params: ['shape'], formClass: 'A',
+        naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
     },
     {
         name: 'healFace', source: 'topology/healingFns.js#healFace', kind: 'skip',