@faicad/faijs 0.29.5 → 0.30.9

package/dist/api/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/api/shell.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api shell — 抽壳：按面移除生成等厚薄壁（手写中立 op，Phase 5）\n *\n * 中立 op：L1 `shell(solid, facesToRemove, thickness, tolerance)` 在 occt 与\n * brepkit 两侧均有真实现（engine-method-map 实测 `dialect`）⇒ 走 `getBrepApi()`\n * （D12），不声明 engines（中立 op：实现只经 L1 契约面）。相对现状是\n * 能力升级——vendored 版是 occt 平台 op（arg-spec `engines:['occt']`，skip）。\n *\n * 选面口径（设计原则 4）：`openFaces: FaceTopoRef[]`（`cad.faceRef` 产物），\n * 与 `fillet` 的 `EdgeTopoRef[]` / `extrude` 的 `upTo` 同族；不复刻 vendored 的\n * `Face[]` 句柄入参。解析在 op 内一处完成（`buildEdgeResolutionContext` 现场枚举\n * + `resolveTopoRef`）。\n *\n * 网格链（方案 2026-10-01 §4 Phase 4 / B3 批）：`mesh:` 实现走网格后端，面按\n * **序号或 FaceTopoRef** 解析（近似拓扑没有 role 层），产物是新的网格零件。\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 { brepOf, fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { FaceTopoRef } from '../topology/naming'\nimport { resolveTopoRef, TopoRefError } from '../topology/naming'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { buildEdgeResolutionContext } from './topo-resolve'\nimport { meshKernelFailure, meshSolidBasicEntry, meshSolidProduct, resolveMeshFaces } from './internal/mesh-solid-op'\n\n/** 抽壳时移除的面选择器：精度链用 `FaceTopoRef`；网格链也可用 1 起序号。 */\nexport type ShellFaceSelector = number | FaceTopoRef\n\n/** `cad.shell` 参数。 */\nexport interface ShellParams {\n  /** 抽壳时移除的面（FaceTopoRef[]，`cad.faceRef` 产物；空数组 = 全封闭薄壁）。 */\n  openFaces: ShellFaceSelector[]\n  /** 壁厚（mm，>0，向内偏置）。 */\n  thickness: number\n  /** 容差（mm，可选；默认走内核约定值）。 */\n  tolerance?: number\n}\n\n/** 参数共校验（两条路径共用；`openFaces` 为空数组合法 = 全封闭薄壁）。 */\nfunction assertShellParams(params: ShellParams): void {\n  const { openFaces, thickness } = params ?? ({} as ShellParams)\n  if (!Array.isArray(openFaces)) {\n    throw new Error('E_SHELL_BAD_OPEN_FACES: shell.openFaces must be an array of FaceTopoRef or ordinals')\n  }\n  if (typeof thickness !== 'number' || !Number.isFinite(thickness) || thickness <= 0) {\n    throw new Error('E_SHELL_BAD_THICKNESS: shell.thickness must be a positive number')\n  }\n}\n\n/** BREP 路径：解析面引用 → L1 shell → 收养。 */\nfunction shellBrep(input: Shape, params: ShellParams): Shape {\n  const { openFaces, thickness, tolerance } = params\n  assertShellParams(params)\n  const kernel = getBrepApi()\n  const solid = brepOf(input) as BrepHandle | undefined\n  if (!solid) throw new Error('E_SHELL_NO_BREP: shell input is not BREP')\n\n  const ctx = buildEdgeResolutionContext(kernel, input as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'shell: input has no BREP naming context')\n  const faceHandles = openFaces.map((ref) => {\n    // 精度链不开序号口子：BREP 的面身份是 `(origin, role)`，序号只是本次枚举序。\n    if (typeof ref === 'number') {\n      throw new Error(\n        'E_SHELL_BAD_OPEN_FACES: an ordinal face selector is only available on the mesh chain — ' +\n        'a precision-chain face is identified by its role line (cad.faceRef)',\n      )\n    }\n    if (!ref || (ref as { kind?: unknown }).kind !== 'face') {\n      throw new Error('E_SHELL_BAD_OPEN_FACES: every openFaces entry must be a FaceTopoRef (cad.faceRef)')\n    }\n    const r = resolveTopoRef(ref, ctx)\n    if (r.handle === undefined) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `shell: face resolved without handle (${ref.origin}/${ref.role})`)\n    }\n    return r.handle as BrepHandle\n  })\n\n  const result = kernel.shell(solid, faceHandles, thickness, tolerance ?? 1e-6)\n  return fromBrep(solidToShape(kernel, result), { solid: result })\n}\n\n/**\n * 网格实体路径：按序号或几何选出要开口的面，交网格后端抽壳。\n *\n * 与 BREP 路径同一条 L1 契约面（`shell(solid, faces, thickness, tolerance)`），\n * 差别只在选面方式：近似拓扑没有 role 层，面靠**序号**（拓扑 `faces` 数组下标 + 1）\n * 或 `FaceTopoRef` 的几何匹配（法向/中心/面积）指认。产物是新网格零件，\n * 近似拓扑由 `meshSolidProduct` 重建。\n *\n * @param input - the mesh-solid input.\n * @param params - the shell parameters.\n * @returns the shelled mesh solid as a new mesh part.\n */\nfunction shellMeshSolid(input: Shape, params: ShellParams): Shape {\n  const { openFaces, thickness, tolerance } = params\n  assertShellParams(params)\n  const entry = meshSolidBasicEntry(input, 'shell')\n  const faceHandles = resolveMeshFaces(entry.kernel, input, openFaces, 'shell')\n\n  let result: BrepHandle\n  try {\n    result = entry.kernel.shell(entry.solid, faceHandles, thickness, tolerance ?? 1e-6)\n  } catch (cause) {\n    throw meshKernelFailure(\n      'shell',\n      'E_SHELL_FAILED',\n      `shell(thickness=${thickness}) removing ${faceHandles.length} face(s)`,\n      cause,\n    )\n  }\n  return meshSolidProduct(entry, result)\n}\n\n/**\n * 抽壳：移除指定面并把余下面偏置成等厚薄壁。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name shell\n * @note 中立 op：L1 shell 两引擎同实现。`openFaces` 为空数组时生成全封闭薄壁。\n *       精度链按 role 线路选面（`cad.faceRef`）；网格链按序号或几何选面——网格零件\n *       没有 role 层，序号是唯一无歧义的指认方式。\n * @returns Shape 抽壳后的薄壁体。\n * @param input - 目标几何。type:Shape required:true\n * @param params.openFaces - 要移除的面（FaceTopoRef[]，cad.faceRef 产物；网格链可用 1 起序号）。type:FaceTopoRef[] required:true\n * @param params.thickness - 壁厚（mm，>0）。type:number required:true\n * @param params.tolerance - 容差（mm）。type:number required:false\n * @example\n * const sh = await cad.shell(part0, { openFaces: [cad.faceRef(part0, 1)], thickness: 2 })\n * const sm = await cad.shell(meshPart, { openFaces: [4], thickness: 2 })\n */\nexport const shell = defineOp({\n  capabilities: ['directEdit'],\n  meshEngines: ['brepkit'],\n  mesh(input: Shape, params: ShellParams) {\n    return shellMeshSolid(input, params)\n  },\n  brep(input: Shape, params: ShellParams) {\n    return shellBrep(input, params)\n  },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/api/shell.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,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAerH,gDAAgD;AAChD,SAAS,iBAAiB,CAAC,MAAmB;IAC5C,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,IAAK,EAAkB,CAAA;IAC9D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,qFAAqF,CAAC,CAAA;IACxG,CAAC;IACD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAA;IACrF,CAAC;AACH,CAAC;AAED,qCAAqC;AACrC,SAAS,SAAS,CAAC,KAAY,EAAE,MAAmB;IAClD,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IAClD,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAA2B,CAAA;IACrD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;IAEvE,MAAM,GAAG,GAAG,0BAA0B,CAAC,MAAM,EAAE,KAAe,CAAC,CAAA;IAC/D,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,yCAAyC,CAAC,CAAA;IACvG,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACxC,mDAAmD;QACnD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,yFAAyF;gBACzF,qEAAqE,CACtE,CAAA;QACH,CAAC;QACD,IAAI,CAAC,GAAG,IAAK,GAA0B,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACxD,MAAM,IAAI,KAAK,CAAC,mFAAmF,CAAC,CAAA;QACtG,CAAC;QACD,MAAM,CAAC,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QAClC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,wCAAwC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,CAAA;QACvH,CAAC;QACD,OAAO,CAAC,CAAC,MAAoB,CAAA;IAC/B,CAAC,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,CAAA;IAC7E,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AAClE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,cAAc,CAAC,KAAY,EAAE,MAAmB;IACvD,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IAClD,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,KAAK,GAAG,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IACjD,MAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,CAAA;IAE7E,IAAI,MAAkB,CAAA;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,CAAA;IACrF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,iBAAiB,CACrB,OAAO,EACP,gBAAgB,EAChB,mBAAmB,SAAS,cAAc,WAAW,CAAC,MAAM,UAAU,EACtE,KAAK,CACN,CAAA;IACH,CAAC;IACD,OAAO,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,CAAC;IAC5B,YAAY,EAAE,CAAC,YAAY,CAAC;IAC5B,WAAW,EAAE,CAAC,SAAS,CAAC;IACxB,IAAI,CAAC,KAAY,EAAE,MAAmB;QACpC,OAAO,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACtC,CAAC;IACD,IAAI,CAAC,KAAY,EAAE,MAAmB;QACpC,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IACjC,CAAC;IACD,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,EAAgB;CAC3E,CAAC,CAAA","sourcesContent":["/**\n * api shell — 抽壳：按面移除生成等厚薄壁（手写中立 op，Phase 5）\n *\n * 中立 op：L1 `shell(solid, facesToRemove, thickness, tolerance)` 在 occt 与\n * brepkit 两侧均有真实现（engine-method-map 实测 `dialect`）⇒ 走 `getBrepApi()`\n * （D12），不声明 engines（中立 op：实现只经 L1 契约面）。相对现状是\n * 能力升级——旧版是 occt 平台 op（arg-spec `engines:['occt']`，skip）。\n *\n * 选面口径（设计原则 4）：`openFaces: FaceTopoRef[]`（`cad.faceRef` 产物），\n * 与 `fillet` 的 `EdgeTopoRef[]` / `extrude` 的 `upTo` 同族；不复刻旧\n * `Face[]` 句柄入参。解析在 op 内一处完成（`buildEdgeResolutionContext` 现场枚举\n * + `resolveTopoRef`）。\n *\n * 网格链（方案 2026-10-01 §4 Phase 4 / B3 批）：`mesh:` 实现走网格后端，面按\n * **序号或 FaceTopoRef** 解析（近似拓扑没有 role 层），产物是新的网格零件。\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 { brepOf, fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { FaceTopoRef } from '../topology/naming'\nimport { resolveTopoRef, TopoRefError } from '../topology/naming'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { buildEdgeResolutionContext } from './topo-resolve'\nimport { meshKernelFailure, meshSolidBasicEntry, meshSolidProduct, resolveMeshFaces } from './internal/mesh-solid-op'\n\n/** 抽壳时移除的面选择器：精度链用 `FaceTopoRef`；网格链也可用 1 起序号。 */\nexport type ShellFaceSelector = number | FaceTopoRef\n\n/** `cad.shell` 参数。 */\nexport interface ShellParams {\n  /** 抽壳时移除的面（FaceTopoRef[]，`cad.faceRef` 产物；空数组 = 全封闭薄壁）。 */\n  openFaces: ShellFaceSelector[]\n  /** 壁厚（mm，>0，向内偏置）。 */\n  thickness: number\n  /** 容差（mm，可选；默认走内核约定值）。 */\n  tolerance?: number\n}\n\n/** 参数共校验（两条路径共用；`openFaces` 为空数组合法 = 全封闭薄壁）。 */\nfunction assertShellParams(params: ShellParams): void {\n  const { openFaces, thickness } = params ?? ({} as ShellParams)\n  if (!Array.isArray(openFaces)) {\n    throw new Error('E_SHELL_BAD_OPEN_FACES: shell.openFaces must be an array of FaceTopoRef or ordinals')\n  }\n  if (typeof thickness !== 'number' || !Number.isFinite(thickness) || thickness <= 0) {\n    throw new Error('E_SHELL_BAD_THICKNESS: shell.thickness must be a positive number')\n  }\n}\n\n/** BREP 路径：解析面引用 → L1 shell → 收养。 */\nfunction shellBrep(input: Shape, params: ShellParams): Shape {\n  const { openFaces, thickness, tolerance } = params\n  assertShellParams(params)\n  const kernel = getBrepApi()\n  const solid = brepOf(input) as BrepHandle | undefined\n  if (!solid) throw new Error('E_SHELL_NO_BREP: shell input is not BREP')\n\n  const ctx = buildEdgeResolutionContext(kernel, input as object)\n  if (!ctx) throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', 'shell: input has no BREP naming context')\n  const faceHandles = openFaces.map((ref) => {\n    // 精度链不开序号口子：BREP 的面身份是 `(origin, role)`，序号只是本次枚举序。\n    if (typeof ref === 'number') {\n      throw new Error(\n        'E_SHELL_BAD_OPEN_FACES: an ordinal face selector is only available on the mesh chain — ' +\n        'a precision-chain face is identified by its role line (cad.faceRef)',\n      )\n    }\n    if (!ref || (ref as { kind?: unknown }).kind !== 'face') {\n      throw new Error('E_SHELL_BAD_OPEN_FACES: every openFaces entry must be a FaceTopoRef (cad.faceRef)')\n    }\n    const r = resolveTopoRef(ref, ctx)\n    if (r.handle === undefined) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `shell: face resolved without handle (${ref.origin}/${ref.role})`)\n    }\n    return r.handle as BrepHandle\n  })\n\n  const result = kernel.shell(solid, faceHandles, thickness, tolerance ?? 1e-6)\n  return fromBrep(solidToShape(kernel, result), { solid: result })\n}\n\n/**\n * 网格实体路径：按序号或几何选出要开口的面，交网格后端抽壳。\n *\n * 与 BREP 路径同一条 L1 契约面（`shell(solid, faces, thickness, tolerance)`），\n * 差别只在选面方式：近似拓扑没有 role 层，面靠**序号**（拓扑 `faces` 数组下标 + 1）\n * 或 `FaceTopoRef` 的几何匹配（法向/中心/面积）指认。产物是新网格零件，\n * 近似拓扑由 `meshSolidProduct` 重建。\n *\n * @param input - the mesh-solid input.\n * @param params - the shell parameters.\n * @returns the shelled mesh solid as a new mesh part.\n */\nfunction shellMeshSolid(input: Shape, params: ShellParams): Shape {\n  const { openFaces, thickness, tolerance } = params\n  assertShellParams(params)\n  const entry = meshSolidBasicEntry(input, 'shell')\n  const faceHandles = resolveMeshFaces(entry.kernel, input, openFaces, 'shell')\n\n  let result: BrepHandle\n  try {\n    result = entry.kernel.shell(entry.solid, faceHandles, thickness, tolerance ?? 1e-6)\n  } catch (cause) {\n    throw meshKernelFailure(\n      'shell',\n      'E_SHELL_FAILED',\n      `shell(thickness=${thickness}) removing ${faceHandles.length} face(s)`,\n      cause,\n    )\n  }\n  return meshSolidProduct(entry, result)\n}\n\n/**\n * 抽壳：移除指定面并把余下面偏置成等厚薄壁。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name shell\n * @note 中立 op：L1 shell 两引擎同实现。`openFaces` 为空数组时生成全封闭薄壁。\n *       精度链按 role 线路选面（`cad.faceRef`）；网格链按序号或几何选面——网格零件\n *       没有 role 层，序号是唯一无歧义的指认方式。\n * @returns Shape 抽壳后的薄壁体。\n * @param input - 目标几何。type:Shape required:true\n * @param params.openFaces - 要移除的面（FaceTopoRef[]，cad.faceRef 产物；网格链可用 1 起序号）。type:FaceTopoRef[] required:true\n * @param params.thickness - 壁厚（mm，>0）。type:number required:true\n * @param params.tolerance - 容差（mm）。type:number required:false\n * @example\n * const sh = await cad.shell(part0, { openFaces: [cad.faceRef(part0, 1)], thickness: 2 })\n * const sm = await cad.shell(meshPart, { openFaces: [4], thickness: 2 })\n */\nexport const shell = defineOp({\n  capabilities: ['directEdit'],\n  meshEngines: ['brepkit'],\n  mesh(input: Shape, params: ShellParams) {\n    return shellMeshSolid(input, params)\n  },\n  brep(input: Shape, params: ShellParams) {\n    return shellBrep(input, params)\n  },\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}

package/dist/api/solid-from-faces.d.ts

@@ -0,0 +1,45 @@
+/**
+ * api solidFromFaces — 面集一次成型为实体（手写平台 op engines:['occt']）
+ *
+ * @platform occt — 本文件 import occt-kernel（`getOcctKernel().buildSolidFromFaces`）：
+ * 该原生方法在 L1 契约 `brep/engine/primitives.ts` 里**没有对应成员**（L1 只有
+ * `sewAndSolidify`），故 op 声明 `engines: ['occt']`（D11）。守卫 ① 要求平台
+ * import 自证身份（本头注）；调用方 op 声明 `engines` 由守卫 ② 校验。
+ *
+ * 与 `sewAndSolidify` / `sew` 的分工（方案 §4.5 去重表）：
+ * - `sewAndSolidify(faces, {tolerance})` — **中立** op，走 L1 契约的
+ *   「面 → 缝合 → 固化」两步链，两引擎（occt / brepkit）同实现；
+ * - `solidFromFaces(faces, {tolerance})` — **平台** op，直调 occt 原生一次性
+ *   构造器 `buildSolidFromFaces`（`BRepBuilderAPI_*` 单次成型，自带缝合容差）。
+ *
+ * 二者并存不是双轨：一个是引擎中立的可切换路径，一个是 occt 原生的一次成型
+ * 入口（真值来源是 occt-wasm 的两个不同内核方法）。新增 op 前已对照 §4.5 表。
+ *
+ * 产物形态：实体（solid），经 `fromBrep` 收养；面演化由内核给出 ⇒
+ * `naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } }`（同 sew 族口径）。
+ */
+import type { Shape } from '../mesh/types.js';
+/** `cad.solidFromFaces` 参数。 */
+export interface SolidFromFacesParams {
+    /** 缝合容差（mm，可选；缺省 = occt 原生默认 1e-6）。 */
+    tolerance?: number;
+}
+/**
+ * 面集一次成型为实体：把一组共享边界的面缝合成一个实体（occt 原生一次构造）。
+ * @group 特征
+ * @inputs 1
+ * @async true
+ * @qual ok
+ * @name solidFromFaces
+ * @note 平台 op：仅 occt 引擎（原生 buildSolidFromFaces，L1 契约无对应成员）。
+ *       非 occt 引擎执行前报错；brep_mock 不拦截。中立路径见 `sewAndSolidify`。
+ * @returns Shape 缝合固化后的实体。
+ * @param faces - 面集合（共享边界、构成闭合壳）。type:Shape[] required:true
+ * @param params.tolerance - 缝合容差（mm，默认 occt 1e-6）。type:number required:false
+ * @example
+ * const solid = await cad.solidFromFaces([f0, f1, f2, f3, f4, f5])
+ */
+export declare const solidFromFaces: ((faces: Shape[], params?: SolidFromFacesParams | undefined) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../define-op.js").DualOpMeta;
+};
+//# sourceMappingURL=solid-from-faces.d.ts.map

package/dist/api/solid-from-faces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solid-from-faces.d.ts","sourceRoot":"","sources":["../../src/api/solid-from-faces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AAS1C,+BAA+B;AAC/B,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA0BD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc;;CAQzB,CAAA"}

package/dist/api/solid-from-faces.js

@@ -0,0 +1,72 @@
+/**
+ * api solidFromFaces — 面集一次成型为实体（手写平台 op engines:['occt']）
+ *
+ * @platform occt — 本文件 import occt-kernel（`getOcctKernel().buildSolidFromFaces`）：
+ * 该原生方法在 L1 契约 `brep/engine/primitives.ts` 里**没有对应成员**（L1 只有
+ * `sewAndSolidify`），故 op 声明 `engines: ['occt']`（D11）。守卫 ① 要求平台
+ * import 自证身份（本头注）；调用方 op 声明 `engines` 由守卫 ② 校验。
+ *
+ * 与 `sewAndSolidify` / `sew` 的分工（方案 §4.5 去重表）：
+ * - `sewAndSolidify(faces, {tolerance})` — **中立** op，走 L1 契约的
+ *   「面 → 缝合 → 固化」两步链，两引擎（occt / brepkit）同实现；
+ * - `solidFromFaces(faces, {tolerance})` — **平台** op，直调 occt 原生一次性
+ *   构造器 `buildSolidFromFaces`（`BRepBuilderAPI_*` 单次成型，自带缝合容差）。
+ *
+ * 二者并存不是双轨：一个是引擎中立的可切换路径，一个是 occt 原生的一次成型
+ * 入口（真值来源是 occt-wasm 的两个不同内核方法）。新增 op 前已对照 §4.5 表。
+ *
+ * 产物形态：实体（solid），经 `fromBrep` 收养；面演化由内核给出 ⇒
+ * `naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } }`（同 sew 族口径）。
+ */
+import { solidToShape } from '../brep/brep-ops.js';
+import { getBrepApi } from '../brep/handle-bridge.js';
+import { brepOf, fromBrep } from '../shape.js';
+import { defineOp } from '../sdk.js';
+import { getOcctKernel } from '../occt-kernel/occtKernel.js';
+/** BREP 路径：借入面句柄 → occt 原生 buildSolidFromFaces（一次成型）→ fromBrep 收养。 */
+function solidFromFacesBrep(faces, params) {
+    if (!Array.isArray(faces) || faces.length === 0) {
+        throw new Error('E_SOLID_FROM_FACES_NO_FACES: solidFromFaces requires a non-empty array of faces');
+    }
+    const tolerance = params?.tolerance;
+    if (tolerance !== undefined && (typeof tolerance !== 'number' || !(tolerance > 0))) {
+        throw new Error('E_SOLID_FROM_FACES_BAD_TOLERANCE: tolerance must be a positive number');
+    }
+    const handles = faces.map((s) => {
+        const h = brepOf(s);
+        if (!h)
+            throw new Error('E_SOLID_FROM_FACES_NO_BREP: solidFromFaces input shape is not BREP');
+        return h;
+    });
+    const kernel = getBrepApi();
+    const occt = getOcctKernel();
+    const handle = (tolerance === undefined
+        ? occt.buildSolidFromFaces(handles)
+        : occt.buildSolidFromFaces(handles, tolerance));
+    return fromBrep(solidToShape(kernel, handle), { solid: handle });
+}
+/**
+ * 面集一次成型为实体：把一组共享边界的面缝合成一个实体（occt 原生一次构造）。
+ * @group 特征
+ * @inputs 1
+ * @async true
+ * @qual ok
+ * @name solidFromFaces
+ * @note 平台 op：仅 occt 引擎（原生 buildSolidFromFaces，L1 契约无对应成员）。
+ *       非 occt 引擎执行前报错；brep_mock 不拦截。中立路径见 `sewAndSolidify`。
+ * @returns Shape 缝合固化后的实体。
+ * @param faces - 面集合（共享边界、构成闭合壳）。type:Shape[] required:true
+ * @param params.tolerance - 缝合容差（mm，默认 occt 1e-6）。type:number required:false
+ * @example
+ * const solid = await cad.solidFromFaces([f0, f1, f2, f3, f4, f5])
+ */
+export const solidFromFaces = defineOp({
+    name: 'solidFromFaces',
+    paramDims: { 'params.tolerance': 'length' },
+    brep(faces, params) {
+        return solidFromFacesBrep(faces, params);
+    },
+    engines: ['occt'],
+    naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } },
+});
+//# sourceMappingURL=solid-from-faces.js.map

package/dist/api/solid-from-faces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solid-from-faces.js","sourceRoot":"","sources":["../../src/api/solid-from-faces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAQzD,sEAAsE;AACtE,SAAS,kBAAkB,CAAC,KAAc,EAAE,MAA6B;IACvE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAA;IACpG,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,EAAE,SAAS,CAAA;IACnC,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAA;IAC1F,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAA2B,CAAA;QAC7C,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAA;QAC7F,OAAO,CAAC,CAAA;IACV,CAAC,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,IAAI,GAAG,aAAa,EAAE,CAAA;IAC5B,MAAM,MAAM,GAAG,CACb,SAAS,KAAK,SAAS;QACrB,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAgB,CAAC;QAC5C,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAgB,EAAE,SAAS,CAAC,CACjC,CAAA;IAC1B,OAAO,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;AAClE,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;IACrC,IAAI,EAAE,gBAAgB;IACtB,SAAS,EAAE,EAAE,kBAAkB,EAAE,QAAQ,EAAE;IAC3C,IAAI,CAAC,KAAc,EAAE,MAA6B;QAChD,OAAO,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC1C,CAAC;IACD,OAAO,EAAE,CAAC,MAAM,CAAC;IACjB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,EAAgB;CAC3E,CAAC,CAAA","sourcesContent":["/**\n * api solidFromFaces — 面集一次成型为实体（手写平台 op engines:['occt']）\n *\n * @platform occt — 本文件 import occt-kernel（`getOcctKernel().buildSolidFromFaces`）：\n * 该原生方法在 L1 契约 `brep/engine/primitives.ts` 里**没有对应成员**（L1 只有\n * `sewAndSolidify`），故 op 声明 `engines: ['occt']`（D11）。守卫 ① 要求平台\n * import 自证身份（本头注）；调用方 op 声明 `engines` 由守卫 ② 校验。\n *\n * 与 `sewAndSolidify` / `sew` 的分工（方案 §4.5 去重表）：\n * - `sewAndSolidify(faces, {tolerance})` — **中立** op，走 L1 契约的\n *   「面 → 缝合 → 固化」两步链，两引擎（occt / brepkit）同实现；\n * - `solidFromFaces(faces, {tolerance})` — **平台** op，直调 occt 原生一次性\n *   构造器 `buildSolidFromFaces`（`BRepBuilderAPI_*` 单次成型，自带缝合容差）。\n *\n * 二者并存不是双轨：一个是引擎中立的可切换路径，一个是 occt 原生的一次成型\n * 入口（真值来源是 occt-wasm 的两个不同内核方法）。新增 op 前已对照 §4.5 表。\n *\n * 产物形态：实体（solid），经 `fromBrep` 收养；面演化由内核给出 ⇒\n * `naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } }`（同 sew 族口径）。\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 { brepOf, fromBrep } from '../shape'\nimport { defineOp } from '../sdk'\nimport type { Provenance } from '../topology/naming/lineage'\nimport { getOcctKernel } from '../occt-kernel/occtKernel'\n\n/** `cad.solidFromFaces` 参数。 */\nexport interface SolidFromFacesParams {\n  /** 缝合容差（mm，可选；缺省 = occt 原生默认 1e-6）。 */\n  tolerance?: number\n}\n\n/** BREP 路径：借入面句柄 → occt 原生 buildSolidFromFaces（一次成型）→ fromBrep 收养。 */\nfunction solidFromFacesBrep(faces: Shape[], params?: SolidFromFacesParams): Shape {\n  if (!Array.isArray(faces) || faces.length === 0) {\n    throw new Error('E_SOLID_FROM_FACES_NO_FACES: solidFromFaces requires a non-empty array of faces')\n  }\n  const tolerance = params?.tolerance\n  if (tolerance !== undefined && (typeof tolerance !== 'number' || !(tolerance > 0))) {\n    throw new Error('E_SOLID_FROM_FACES_BAD_TOLERANCE: tolerance must be a positive number')\n  }\n  const handles = faces.map((s) => {\n    const h = brepOf(s) as BrepHandle | undefined\n    if (!h) throw new Error('E_SOLID_FROM_FACES_NO_BREP: solidFromFaces input shape is not BREP')\n    return h\n  })\n  const kernel = getBrepApi()\n  const occt = getOcctKernel()\n  const handle = (\n    tolerance === undefined\n      ? occt.buildSolidFromFaces(handles as never)\n      : occt.buildSolidFromFaces(handles as never, tolerance)\n  ) as unknown as BrepHandle\n  return fromBrep(solidToShape(kernel, handle), { solid: handle })\n}\n\n/**\n * 面集一次成型为实体：把一组共享边界的面缝合成一个实体（occt 原生一次构造）。\n * @group 特征\n * @inputs 1\n * @async true\n * @qual ok\n * @name solidFromFaces\n * @note 平台 op：仅 occt 引擎（原生 buildSolidFromFaces，L1 契约无对应成员）。\n *       非 occt 引擎执行前报错；brep_mock 不拦截。中立路径见 `sewAndSolidify`。\n * @returns Shape 缝合固化后的实体。\n * @param faces - 面集合（共享边界、构成闭合壳）。type:Shape[] required:true\n * @param params.tolerance - 缝合容差（mm，默认 occt 1e-6）。type:number required:false\n * @example\n * const solid = await cad.solidFromFaces([f0, f1, f2, f3, f4, f5])\n */\nexport const solidFromFaces = defineOp({\n  name: 'solidFromFaces',\n  paramDims: { 'params.tolerance': 'length' },\n  brep(faces: Shape[], params?: SolidFromFacesParams) {\n    return solidFromFacesBrep(faces, params)\n  },\n  engines: ['occt'],\n  naming: { kind: 'kernel', newFaces: { via: 'byAdjacency' } } as Provenance,\n})\n"]}

package/dist/api/solid-offset/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * api solid-offset — 实体与偏置族（S4 剩余：draftPrism / pipe，平台 op engines:['occt']）
+ *
+ * @platform occt — 本目录 import occt-kernel：`draftPrism`（拔模棱柱）与 `pipe`
+ * （沿脊柱的管）直调 occt 原生（occt-wasm 原生有）。这两个原生方法**不在** L1 契约
+ * `BrepEngineApi` 里（L1 只有 `offset` / `sweepPipeShell` 等，见
+ * brep/engine/primitives.ts）⇒ 平台 op：defineOp 声明 `engines: ['occt']`（D11）。
+ *
+ * 方案落点：docs/plans/2026-10-07-occt-wasm-op-enablement-plan.md §3.4.4
+ * （该族 5 项中 `offsetWire2d` / `buildSolidFromFaces` / `halfSpace` 已由 S3 落地）。
+ * 与既有 op 的边界（§4.5 去重表）：
+ * - `pipe` vs `sweep`：pipe = `BRepOffsetAPI_MakePipe`（沿脊柱的管，单截面裸管线）；
+ *   sweep = `sweepPipeShell` / `simplePipe`（截面扫掠，带 Frenet/平滑选项）；
+ * - `draftPrism` vs `extrude`：前者带拔模角（上下截面渐变），后者平行拔出；
+ * - `draftPrism` vs `draft`：draft 对已有实体面加拔模斜度；draftPrism 是拔模挤出。
+ *
+ * 角度约定（实测钉住，见 test/api/occt-s4-solid-offset.test.ts）：occt 原生
+ * `draftPrism` 的形参名即 `angleDeg`（**度**，facade 内部自行换算弧度）——脚本面
+ * 直传度，不做二次换算。
+ */
+import type { Shape } from '../../mesh/types.js';
+type Vec3 = [number, number, number];
+/**
+ * 拔模棱柱：把平面基底（face 或 wire）沿方向挤出，并施加拔模角（上下截面渐变）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name draftPrism
+ * @note 平台 op：仅 occt 引擎（原生 draftPrism，形参即 angleDeg——角度单位是**度**，
+ *       原生内部换算）。角度为 0 时等价普通挤出。
+ * @returns Shape 拔模挤出体。
+ * @param base - 平面基底（face 或闭合 wire）。type:Shape required:true
+ * @param direction - 挤出方向 [dx,dy,dz]（非零；长度即挤出距离）。type:Vec3 required:true
+ * @param angleDeg - 拔模角（度）。type:number required:true
+ * @example
+ * const s = cad.draftPrism(squareFace, [0, 0, 10], 5)
+ */
+export declare const draftPrism: ((base: Shape, direction: Vec3, angleDeg: number) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../../define-op.js").DualOpMeta;
+};
+/**
+ * 沿脊柱扫出管：把截面沿脊柱 wire 扫掠（`BRepOffsetAPI_MakePipe` 裸管线；
+ * 带过渡/方向控制的扫掠见 `sweep`）。
+ *
+ * 产物类型随截面类型（实测钉住，test/api/occt-s4-solid-offset.test.ts A3/A4）：
+ * **截面 face → 实体；截面 wire/edge → 壳（管面，体积无意义）**。要实体管，
+ * 喂面截面（如 `cad.profile` 的圆盘轮廓）。
+ * @group 创建
+ * @inputs 2
+ * @async false
+ * @qual ok
+ * @name pipe
+ * @note 平台 op：仅 occt 引擎（原生 pipe，L1 契约无对应成员）。脊柱须为 wire。
+ *       非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @returns Shape 扫出的管（截面 face → 实体；wire/edge → 壳）。
+ * @param profile - 截面（face → 实体；wire/edge → 壳）。
+ *                  type:Shape required:true
+ * @param spine - 脊柱 wire。type:Shape required:true
+ * @example
+ * const tube = cad.pipe(diskFace, spineWire)
+ */
+export declare const pipe: ((profile: Shape, spine: Shape) => Promise<Shape>) & {
+    __faijs__dualOp?: import("../../define-op.js").DualOpMeta;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/api/solid-offset/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/solid-offset/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAS7C,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAsCpC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU;;CAWrB,CAAA;AAuBF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,IAAI;;CAUf,CAAA"}

package/dist/api/solid-offset/index.js

@@ -0,0 +1,132 @@
+/**
+ * api solid-offset — 实体与偏置族（S4 剩余：draftPrism / pipe，平台 op engines:['occt']）
+ *
+ * @platform occt — 本目录 import occt-kernel：`draftPrism`（拔模棱柱）与 `pipe`
+ * （沿脊柱的管）直调 occt 原生（occt-wasm 原生有）。这两个原生方法**不在** L1 契约
+ * `BrepEngineApi` 里（L1 只有 `offset` / `sweepPipeShell` 等，见
+ * brep/engine/primitives.ts）⇒ 平台 op：defineOp 声明 `engines: ['occt']`（D11）。
+ *
+ * 方案落点：docs/plans/2026-10-07-occt-wasm-op-enablement-plan.md §3.4.4
+ * （该族 5 项中 `offsetWire2d` / `buildSolidFromFaces` / `halfSpace` 已由 S3 落地）。
+ * 与既有 op 的边界（§4.5 去重表）：
+ * - `pipe` vs `sweep`：pipe = `BRepOffsetAPI_MakePipe`（沿脊柱的管，单截面裸管线）；
+ *   sweep = `sweepPipeShell` / `simplePipe`（截面扫掠，带 Frenet/平滑选项）；
+ * - `draftPrism` vs `extrude`：前者带拔模角（上下截面渐变），后者平行拔出；
+ * - `draftPrism` vs `draft`：draft 对已有实体面加拔模斜度；draftPrism 是拔模挤出。
+ *
+ * 角度约定（实测钉住，见 test/api/occt-s4-solid-offset.test.ts）：occt 原生
+ * `draftPrism` 的形参名即 `angleDeg`（**度**，facade 内部自行换算弧度）——脚本面
+ * 直传度，不做二次换算。
+ */
+import { solidToShape } from '../../brep/brep-ops.js';
+import { getBrepApi } from '../../brep/handle-bridge.js';
+import { brepOf, fromBrep } from '../../shape.js';
+import { defineOp } from '../../sdk.js';
+import { getOcctKernel } from '../../occt-kernel/occtKernel.js';
+/** 输入 Shape → 内核句柄（无 BREP 槁报错）。 */
+function handleOf(shape, op, which) {
+    const h = brepOf(shape);
+    if (!h) {
+        throw new Error(`E_${op.toUpperCase()}_NO_BREP: ${op} requires a BREP handle for ${which} (mesh-only shape has none)`);
+    }
+    return h;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// draftPrism — 拔模棱柱（带角度挤出）
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 draftPrism（angleDeg 度，原生内部换算弧度）。 */
+function draftPrismBrep(base, direction, angleDeg) {
+    if (!base) {
+        throw new Error('E_DRAFTPRISM_NO_BASE: draftPrism requires a planar base (face or wire)');
+    }
+    if (!Array.isArray(direction) ||
+        direction.length !== 3 ||
+        direction.some((n) => typeof n !== 'number' || !Number.isFinite(n)) ||
+        (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)) {
+        throw new Error('E_DRAFTPRISM_BAD_DIRECTION: direction must be a non-zero [dx,dy,dz]');
+    }
+    if (typeof angleDeg !== 'number' || !Number.isFinite(angleDeg)) {
+        throw new Error('E_DRAFTPRISM_BAD_ANGLE: angleDeg must be a finite number (degrees)');
+    }
+    const bh = handleOf(base, 'draftPrism', 'base shape');
+    const handle = getOcctKernel().draftPrism(bh, direction[0], direction[1], direction[2], angleDeg);
+    return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle });
+}
+/**
+ * 拔模棱柱：把平面基底（face 或 wire）沿方向挤出，并施加拔模角（上下截面渐变）。
+ * @group 创建
+ * @inputs 0
+ * @async false
+ * @qual ok
+ * @name draftPrism
+ * @note 平台 op：仅 occt 引擎（原生 draftPrism，形参即 angleDeg——角度单位是**度**，
+ *       原生内部换算）。角度为 0 时等价普通挤出。
+ * @returns Shape 拔模挤出体。
+ * @param base - 平面基底（face 或闭合 wire）。type:Shape required:true
+ * @param direction - 挤出方向 [dx,dy,dz]（非零；长度即挤出距离）。type:Vec3 required:true
+ * @param angleDeg - 拔模角（度）。type:number required:true
+ * @example
+ * const s = cad.draftPrism(squareFace, [0, 0, 10], 5)
+ */
+export const draftPrism = defineOp({
+    name: 'draftPrism',
+    paramDims: { direction: 'length', angleDeg: 'angle' },
+    brep(base, direction, angleDeg) {
+        return draftPrismBrep(base, direction, angleDeg);
+    },
+    engines: ['occt'],
+    naming: {
+        kind: 'unmodeled',
+        reason: 'tapered prism face vocabulary not defined',
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// pipe — 沿脊柱的管（BRepOffsetAPI_MakePipe）
+// ─────────────────────────────────────────────────────────────────────────────
+/** BREP 路径：occt 原生 pipe。脊柱须 wire（原生 TopoDS::Wire 转换）；截面原样透传
+ *  ——**face 截面产实体，wire/edge 截面产壳**（BRepOffsetAPI_MakePipe 语义，
+ *  实测钉在 test/api/occt-s4-solid-offset.test.ts A3/A4），故不做面→外环适配
+ *  （那会把实体口径降级成壳）。 */
+function pipeBrep(profile, spine) {
+    if (!profile || !spine) {
+        throw new Error('E_PIPE_MISSING_ARG: pipe requires a profile and a spine (wire)');
+    }
+    const profileHandle = handleOf(profile, 'pipe', 'profile');
+    const spineHandle = handleOf(spine, 'pipe', 'spine wire');
+    const kernel = getBrepApi();
+    const handle = getOcctKernel().pipe(profileHandle, spineHandle);
+    return fromBrep(solidToShape(kernel, handle), { solid: handle });
+}
+/**
+ * 沿脊柱扫出管：把截面沿脊柱 wire 扫掠（`BRepOffsetAPI_MakePipe` 裸管线；
+ * 带过渡/方向控制的扫掠见 `sweep`）。
+ *
+ * 产物类型随截面类型（实测钉住，test/api/occt-s4-solid-offset.test.ts A3/A4）：
+ * **截面 face → 实体；截面 wire/edge → 壳（管面，体积无意义）**。要实体管，
+ * 喂面截面（如 `cad.profile` 的圆盘轮廓）。
+ * @group 创建
+ * @inputs 2
+ * @async false
+ * @qual ok
+ * @name pipe
+ * @note 平台 op：仅 occt 引擎（原生 pipe，L1 契约无对应成员）。脊柱须为 wire。
+ *       非 occt 引擎执行前报错；brep_mock 不拦截。
+ * @returns Shape 扫出的管（截面 face → 实体；wire/edge → 壳）。
+ * @param profile - 截面（face → 实体；wire/edge → 壳）。
+ *                  type:Shape required:true
+ * @param spine - 脊柱 wire。type:Shape required:true
+ * @example
+ * const tube = cad.pipe(diskFace, spineWire)
+ */
+export const pipe = defineOp({
+    name: 'pipe',
+    brep(profile, spine) {
+        return pipeBrep(profile, spine);
+    },
+    engines: ['occt'],
+    naming: {
+        kind: 'unmodeled',
+        reason: 'pipe face vocabulary not defined',
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/api/solid-offset/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/api/solid-offset/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api solid-offset — 实体与偏置族（S4 剩余：draftPrism / pipe，平台 op engines:['occt']）\n *\n * @platform occt — 本目录 import occt-kernel：`draftPrism`（拔模棱柱）与 `pipe`\n * （沿脊柱的管）直调 occt 原生（occt-wasm 原生有）。这两个原生方法**不在** L1 契约\n * `BrepEngineApi` 里（L1 只有 `offset` / `sweepPipeShell` 等，见\n * brep/engine/primitives.ts）⇒ 平台 op：defineOp 声明 `engines: ['occt']`（D11）。\n *\n * 方案落点：docs/plans/2026-10-07-occt-wasm-op-enablement-plan.md §3.4.4\n * （该族 5 项中 `offsetWire2d` / `buildSolidFromFaces` / `halfSpace` 已由 S3 落地）。\n * 与既有 op 的边界（§4.5 去重表）：\n * - `pipe` vs `sweep`：pipe = `BRepOffsetAPI_MakePipe`（沿脊柱的管，单截面裸管线）；\n *   sweep = `sweepPipeShell` / `simplePipe`（截面扫掠，带 Frenet/平滑选项）；\n * - `draftPrism` vs `extrude`：前者带拔模角（上下截面渐变），后者平行拔出；\n * - `draftPrism` vs `draft`：draft 对已有实体面加拔模斜度；draftPrism 是拔模挤出。\n *\n * 角度约定（实测钉住，见 test/api/occt-s4-solid-offset.test.ts）：occt 原生\n * `draftPrism` 的形参名即 `angleDeg`（**度**，facade 内部自行换算弧度）——脚本面\n * 直传度，不做二次换算。\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 { brepOf, fromBrep } from '../../shape'\nimport { defineOp } from '../../sdk'\nimport type { Provenance } from '../../topology/naming/lineage'\nimport { getOcctKernel } from '../../occt-kernel/occtKernel'\n\ntype Vec3 = [number, number, number]\n\n/** 输入 Shape → 内核句柄（无 BREP 槁报错）。 */\nfunction handleOf(shape: Shape, op: string, which: string): BrepHandle {\n  const h = brepOf(shape) as BrepHandle | undefined\n  if (!h) {\n    throw new Error(`E_${op.toUpperCase()}_NO_BREP: ${op} requires a BREP handle for ${which} (mesh-only shape has none)`)\n  }\n  return h\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// draftPrism — 拔模棱柱（带角度挤出）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 draftPrism（angleDeg 度，原生内部换算弧度）。 */\nfunction draftPrismBrep(base: Shape, direction: Vec3, angleDeg: number): Shape {\n  if (!base) {\n    throw new Error('E_DRAFTPRISM_NO_BASE: draftPrism requires a planar base (face or wire)')\n  }\n  if (\n    !Array.isArray(direction) ||\n    direction.length !== 3 ||\n    direction.some((n) => typeof n !== 'number' || !Number.isFinite(n)) ||\n    (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)\n  ) {\n    throw new Error('E_DRAFTPRISM_BAD_DIRECTION: direction must be a non-zero [dx,dy,dz]')\n  }\n  if (typeof angleDeg !== 'number' || !Number.isFinite(angleDeg)) {\n    throw new Error('E_DRAFTPRISM_BAD_ANGLE: angleDeg must be a finite number (degrees)')\n  }\n  const bh = handleOf(base, 'draftPrism', 'base shape')\n  const handle = getOcctKernel().draftPrism(\n    bh as never, direction[0], direction[1], direction[2], angleDeg,\n  ) as unknown as BrepHandle\n  return fromBrep(solidToShape(getBrepApi(), handle), { solid: handle })\n}\n\n/**\n * 拔模棱柱：把平面基底（face 或 wire）沿方向挤出，并施加拔模角（上下截面渐变）。\n * @group 创建\n * @inputs 0\n * @async false\n * @qual ok\n * @name draftPrism\n * @note 平台 op：仅 occt 引擎（原生 draftPrism，形参即 angleDeg——角度单位是**度**，\n *       原生内部换算）。角度为 0 时等价普通挤出。\n * @returns Shape 拔模挤出体。\n * @param base - 平面基底（face 或闭合 wire）。type:Shape required:true\n * @param direction - 挤出方向 [dx,dy,dz]（非零；长度即挤出距离）。type:Vec3 required:true\n * @param angleDeg - 拔模角（度）。type:number required:true\n * @example\n * const s = cad.draftPrism(squareFace, [0, 0, 10], 5)\n */\nexport const draftPrism = defineOp({\n  name: 'draftPrism',\n  paramDims: { direction: 'length', angleDeg: 'angle' },\n  brep(base: Shape, direction: Vec3, angleDeg: number) {\n    return draftPrismBrep(base, direction, angleDeg)\n  },\n  engines: ['occt'],\n  naming: {\n    kind: 'unmodeled',\n    reason: 'tapered prism face vocabulary not defined',\n  } as Provenance,\n})\n\n// ─────────────────────────────────────────────────────────────────────────────\n// pipe — 沿脊柱的管（BRepOffsetAPI_MakePipe）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** BREP 路径：occt 原生 pipe。脊柱须 wire（原生 TopoDS::Wire 转换）；截面原样透传\n *  ——**face 截面产实体，wire/edge 截面产壳**（BRepOffsetAPI_MakePipe 语义，\n *  实测钉在 test/api/occt-s4-solid-offset.test.ts A3/A4），故不做面→外环适配\n *  （那会把实体口径降级成壳）。 */\nfunction pipeBrep(profile: Shape, spine: Shape): Shape {\n  if (!profile || !spine) {\n    throw new Error('E_PIPE_MISSING_ARG: pipe requires a profile and a spine (wire)')\n  }\n  const profileHandle = handleOf(profile, 'pipe', 'profile')\n  const spineHandle = handleOf(spine, 'pipe', 'spine wire')\n  const kernel = getBrepApi()\n  const handle = getOcctKernel().pipe(\n    profileHandle as never, spineHandle as never,\n  ) as unknown as BrepHandle\n  return fromBrep(solidToShape(kernel, handle), { solid: handle })\n}\n\n/**\n * 沿脊柱扫出管：把截面沿脊柱 wire 扫掠（`BRepOffsetAPI_MakePipe` 裸管线；\n * 带过渡/方向控制的扫掠见 `sweep`）。\n *\n * 产物类型随截面类型（实测钉住，test/api/occt-s4-solid-offset.test.ts A3/A4）：\n * **截面 face → 实体；截面 wire/edge → 壳（管面，体积无意义）**。要实体管，\n * 喂面截面（如 `cad.profile` 的圆盘轮廓）。\n * @group 创建\n * @inputs 2\n * @async false\n * @qual ok\n * @name pipe\n * @note 平台 op：仅 occt 引擎（原生 pipe，L1 契约无对应成员）。脊柱须为 wire。\n *       非 occt 引擎执行前报错；brep_mock 不拦截。\n * @returns Shape 扫出的管（截面 face → 实体；wire/edge → 壳）。\n * @param profile - 截面（face → 实体；wire/edge → 壳）。\n *                  type:Shape required:true\n * @param spine - 脊柱 wire。type:Shape required:true\n * @example\n * const tube = cad.pipe(diskFace, spineWire)\n */\nexport const pipe = defineOp({\n  name: 'pipe',\n  brep(profile: Shape, spine: Shape) {\n    return pipeBrep(profile, spine)\n  },\n  engines: ['occt'],\n  naming: {\n    kind: 'unmodeled',\n    reason: 'pipe face vocabulary not defined',\n  } as Provenance,\n})\n"]}

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

@@ -1,22 +1,23 @@
 /**
  * arg-spec — L3 投影签名适配表（E5 唯一人工维护点）
  *
- * 设计文档：docs/plans/2026-09-02-faijs-api-surface-completion.md §E5 / §5.2
- *
- * 输入：brepjs `src/index.ts`（upstream-surface.json 已按 §2.6 排除）。
  * 作用：为每个保留符号声明「faijs 面投影方式」。生成器
- * `scripts/gen-l3-surface.ts` 读取本表 + surface 清单，产出
- * `api/generated/<module>.ts`（E5：不手写 699 个；本表之外符号按默认规则推导）。
+ * `packages/core/scripts/gen-l3-surface.ts` 读取本表，按
+ * PROJECTED_MODULES 分片产出 `api/generated/<module>.ts`；未列入本表的符号不进生成。
+ *
+ * 产出类别（生成器按此判别；完整定义见 gen-l3-surface.ts 头部）：
+ *   brep-op : defineOp({ brep: __own_* }) —— Solid 进出，直连 core 自有实现（api/brep-operations/）
+ *   query   : 普通导出函数（getBrepApi().* 直连引擎，返回纯数据，不进 defineOp——先例 api/geom.ts）
+ *   faijs   : re-export 自手写 api/ 模块
+ *   skip    : 仅登记不生成（divergence：语义 faijs 面无法表达 / 已由既有 op 覆盖），带 reason
+ *   （历史 kind 'type' / 'pure' 已无条目，出现即抛错）
  *
- * 产出类别（对齐 §5.2 / E5 分类表；生成器按本类判别产出）：
- *   brep-op : defineOp({ brep }) —— Solid 进出（构造/变换/布尔/修饰）
- *   query   : 普通导出函数（输入 Shape 借入 brepjs handle → 调 vendored → 返回纯数据；
- *             返回非 Shape，不进 defineOp——先例 api/geom.ts，generated/topology.ts getBounds）
- *   pure    : 无 Shape 参数的纯函数 → 直接 re-export（不进 defineOp，不是 op）
- *   type    : `export type { … } from '<vendored>'` re-export
- *   skip    : 登记跳过（divergence：语义 faijs 面无法表达 / 已由 faijs 既有 op 覆盖），带 reason
+ * A6（2026-10-06）口径指认：本表 + 生成的 generated/*.ts 是 L3 投影面的
+ * **增量**清单；cad 脚本面的**全集**清单权威来源是 generated/script-face.ts
+ * （scriptFace: true 条目）与 lang/symbol-table.generated.ts（95 op）。两个清单
+ * 回答不同问题、互不为超集——禁止互相反推。
  *
- * 双形态（E2）：同名符号由生成器注入 `normalizeArgs` 判别器（faijs 对象形态 ↔ brepjs
+ * 双形态（E2）：同名符号由生成器注入 `normalizeArgs` 判别器（faijs 对象形态 ↔
  * 位置形态），适配表给 faijs 形参映射；本文件首批样本聚焦「faijs 无同名」的纯新增符号，
  * 双形态条目随 §5.1 同名处置逐批加入（P14 分批）。
  *
@@ -41,7 +42,7 @@ export interface QueryParam {
     name: string;
     /** 非几何位的类型（如 `number`）；几何位由生成器覆写为 `Shape`。 */
     type: string;
-    /** 是否为可选参数（faijs 面签名 `?`），函数缺省值由 vendored 承担。 */
+    /** 是否为可选参数（faijs 面签名 `?`），函数缺省值由来源实现承担。 */
     optional?: boolean;
     /** JSDoc 补充说明。 */
     docs?: string;
@@ -50,15 +51,15 @@ export interface QueryParam {
  * D11 参数双形态分类。
  *
  * - A  : 单名双形态（位置形态首参非 plain object，判别式有效，如 box/fuse/torus）。
- * - B1 : 单名单形态（brepjs options 对象即唯一对象形态，无需拆名，如 thread）。
- * - B2 : 双名（brepjs 形态占正名，faijs 对象形态加描述性后缀，如 rotate_euler）。
+ * - B1 : 单名单形态（来源 options 对象即唯一对象形态，无需拆名，如 thread）。
+ * - B2 : 双名（来源形态占正名，faijs 对象形态加描述性后缀，如 rotate_euler）。
  */
 export type FormClass = 'A' | 'B1' | 'B2';
 /**
  * 单条投影适配。
  *
- * - `name`   faijs 面导出名（= brepjs 符号名；同名冲突已在 §5.1 处置后，寻表登记双形态或改名）。
- * - `source` vendored 树内的来源符号，`<相对 vendored 根的模块路径>#<导出名>`（默认同名）。
+ * - `name`   faijs 面导出名（= 来源符号名；同名冲突已在 §5.1 处置后，寻表登记双形态或改名）。
+ * - `source` 来源树内的来源符号，`<相对 api/ 的模块路径>#<导出名>`（默认同名）。
  * - `kind`   投影类别（见文件头）。
  * - `module` 分片归属（缺省 'topology'，P13 兼容；P14 起逐模块登记）。
  * - `args`   brep-op/query：调用约定描述，供生成器产出 JSDoc 与 normalizeArgs 占位；
@@ -79,20 +80,19 @@ export interface ArgSpecEntry {
     /**
      * Machine bridge hints (P13a mechanism sample).
      * For 'brep-op'/'query': which positional parameters are geometry inputs
-     * (0-based indices into the brepjs positional-arg list) that the generated
-     * code must borrow via `borrowBrepjsShape`. Non-listed params pass through
-     * untouched (numbers / option objects are value params).
+     * (0-based indices into the positional-arg list). Non-listed params pass
+     * through untouched (numbers / option objects are value params).
      */
     geometryArgs?: number[];
     /**
-     * P14: 几何数组位（query）——该索引是 Shape 数组形参，逐元素借入 brepjs handle。
+     * P14: 几何数组位（query）——该索引是 Shape 数组形参；query 函数体内经 brepOf 逐元素直读内核句柄。
      */
     geometryCollectionArgs?: number[];
     /** For brep-op/query: whether a bool `Result` must be unwrapped (err → throw). Default true for ops/query. */
     returnsResult?: boolean;
     /** P14: query 侧 faijs 面形参列表（without the case for pure/type；brep-op 保持位置透传 `...args`）。 */
     queryParams?: QueryParam[];
-    /** For query only: the vendored return type name (re-exportable from the entry's module) so the generated function can annotate its return type (the export-JSDoc gate requires an explicit annotation + @returns). */
+    /** For query only: the source module's return type name (re-exportable from the entry's module) so the generated function can annotate its return type (the export-JSDoc gate requires an explicit annotation + @returns). */
     returnType?: string;
     /** P20: 机器参数名表（按位置顺序），供 dual-form-args resolveArgs 映射对象形态→位置数组。 */
     params?: string[];
@@ -105,7 +105,7 @@ export interface ArgSpecEntry {
     capabilities?: BrepCapabilityName[];
     /**
      * Phase 5（narrowing plan D11）：平台身份声明——该 brep-op 只在列出的引擎上
-     * 实现（如 vendored op 调 occt-only 方法 isNull/section/loft → ['occt']）。
+     * 实现（如 compat op 调 occt-only 方法 isNull/section/loft → ['occt']）。
      * 缺省 = 全平台中立。可与 capabilities 并存（2026-09-24 撤销 D11-7 互斥）：
      * engines 是引擎白名单，capabilities 是能力依赖，判定 engines 在先（D11-2）。
      * 生成器透传给 compatOp → defineOp engines，并写进 script-face-manifest。
@@ -127,13 +127,6 @@ export interface ArgSpecEntry {
      * `import type` from lineage.ts — pure type, no runtime circular dep.
      */
     naming?: Provenance;
-    /**
-     * Phase 3（core-decouple plan §5.4）：core 自有实现标记——source 指向
-     * pi/brep-mirror/<file>.ts#<fn>（core 第一方实现），生成器走 selfhost 分支
-     * （defineOp({ brep: __own_<fn>, … })，无 vendored import、无 compatOp/
-     * projectBrepOp 桥；D11 归一在自有实现内部完成）。
-     */
-    selfhost?: boolean;
     /** Named multi-product outputs（defineOp 的 outputs 选项，分片 op 用）。 */
     outputs?: string[];
     /** L3 schema per named parameter（G1 codegen + UI panel）。 */
@@ -148,10 +141,19 @@ export interface ArgSpecEntry {
     paramDims?: Record<string, import('../../units.js').DimName>;
     /** P26 (unit-system D8): 返回值量纲声明（函数调用结果携带的量纲）。 */
     retDim?: import('../../units.js').DimName;
+    /**
+     * B1：手册直达注解——`scripts/gen-ops-api-inventory.ts` 会把这句话原样渲染成
+     * 派生章节里的一条注解。
+     *
+     * 生成 op 的 JSDoc 由本文件生成（`api/generated/*.ts` 禁手改），`reason` 又只
+     * 解释「为什么这样投影」；于是**读者最容易误判的语义**（如 `applyMatrix` 的
+     * 矩阵序约定）在手册里无处安放。需要时写这里，别写进生成文件。
+     */
+    manualNote?: string;
 }
 /**
- * 首批机制验证样本（P13a）。每个样本都选了 faijs 无同名、brepjs 有完整实现的符号，
- * 生成产物可立即 typecheck 并桥接 vendored 跑通（E5 模板：句柄借入 → 调 vendored →
+ * 首批机制验证样本（P13a）。每个样本都选了 faijs 无同名、来源有完整实现的符号，
+ * 生成产物可立即 typecheck 并桥接来源实现跑通（E5 模板：输入原样直传 → 调来源实现 →
  * Result 翻转 → fromBrep 所有权转入）。
  */
 export declare const ARG_SPEC: ArgSpecEntry[];

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;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,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;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IACjC,iDAAiD;IACjD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,mCAAmC,EAAE,OAAO,CAAA;IAC7D;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,aAAa,EAAE,OAAO,CAAC,CAAA;IACzD,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,aAAa,EAAE,OAAO,CAAA;CACvC;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,YAAY,EA+zHlC,CAAA"}
+{"version":3,"file":"arg-spec.d.ts","sourceRoot":"","sources":["../../../src/api/surface/arg-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,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,2CAA2C;IAC3C,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;;;;;OAKG;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,8NAA8N;IAC9N,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,kBAAkB,EAAE,CAAA;IACnC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IACjC,iDAAiD;IACjD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IAEnB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,mCAAmC,EAAE,OAAO,CAAA;IAC7D;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,aAAa,EAAE,OAAO,CAAC,CAAA;IACzD,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,aAAa,EAAE,OAAO,CAAA;IACtC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,YAAY,EA4zHlC,CAAA"}