@faicad/faijs 0.13.0

package/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Faicad contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Third-party components bundled in this distribution retain their own licenses:
+
+- `src/vendored/brepjs` (compiled into `dist/vendored/**`): ported from the
+  brepjs project, licensed under the Apache License 2.0. See NOTICE for the
+  full attribution. Apache-2.0 text: https://www.apache.org/licenses/LICENSE-2.0

package/NOTICE

@@ -0,0 +1,29 @@
+faijs — @faicad/faijs NOTICE
+============================
+
+This product includes code ported from the `brepjs` project
+(https://github.com/OpenCascade/brepjs), licensed under the Apache
+License 2.0. Ported as of brepjs commit 8685273a (locked upstream
+reference; no two-way sync). The ported files retain their original
+Apache-2.0 attribution; see the vendored NOTICE in the source
+repository (packages/core/src/vendored/brepjs/NOTICE).
+
+Full Apache-2.0 text: https://www.apache.org/licenses/LICENSE-2.0
+
+Runtime dependencies (not distributed inside this package)
+----------------------------------------------------------
+
+The following optional/peer dependencies are loaded by the host at
+runtime and are NOT distributed inside this tarball. They carry their
+own licenses:
+
+- `occt-wasm` — JS glue: MIT OR Apache-2.0; the compiled WASM output is
+  LGPL-2.1-only (inherited from OCCT, https://dev.opencascade.org).
+  The LGPL replacement obligation is satisfied because the host loads
+  the `.wasm` from a URL that can be overridden
+  (`OcctKernel.init({ wasm: '...' })`).
+- `manifold-3d` — Apache-2.0.
+
+`@salusoft89/planegcs` (LGPL-2.0-or-later) is used only by the
+non-shipped `src/fcstd` module and is intentionally not a dependency of
+the published package.

package/dist/api/api-namespace.d.ts

@@ -0,0 +1,27 @@
+/**
+ * api-namespace — 把 L3 API 面（api/ 层的 fp操作）装配为 cad 命名空间（统一 ABI，B2 消灭）
+ *
+ *
+ * 库函数签名 = .fai.js 源码形态（无隐式参数）；本文件无任何 per-函数逻辑。
+ *
+ * 归属（monorepo P5/E-a-1）：本文件随 stdlib 出包，是 faijs 默认标准库
+ * （cad 命名空间）的装配点。K5（引擎零函数知识）的准确含义是：parser / compile /
+ * runtime 不按函数名分支、不区分函数类别，函数信息统一以 defineOp 元数据（均匀数据）
+ * 承载。把 cad 这套库数据内置进引擎，与第三方库走完全相同的 registerLib 路径，
+ * 引擎并未对 cad 特判，因此不构成 K5 违反。cad 在 core 的 createRuntime 包装中
+ * 被注册为 default 命名空间（见 cad-runtime/createRuntimeWithCad.ts）。
+ */
+import type { StdlibNamespace } from '../runtime-state.js';
+/**
+ * Assemble stdlib functions into the cad namespace.
+ *
+ * P23（§4.2 ②，B1 三源一致）：cad 面 = faijs 特有 dual op（下方字面量）+
+ * 生成脚本面 op（`scriptFaceOps`——`api/generated/script-face.ts` 按 arg-spec
+ * 的 `scriptFace: true` 条目生成，经 `compatOp(projectBrepOp(…))` 包装的
+ * brep-only 语句级 op）。`check()` 符号表（`gen-symbol-table.ts`）与
+ * `api/index.ts` 导出面同源于同一份清单。
+ *
+ * @returns the assembled StdlibNamespace ready for runtime injection.
+ */
+export declare function createApiNamespace(): StdlibNamespace;
+//# sourceMappingURL=api-namespace.d.ts.map

package/dist/api/api-namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-namespace.d.ts","sourceRoot":"","sources":["../../src/api/api-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgCH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAsBpD"}

package/dist/api/api-namespace.js

@@ -0,0 +1,78 @@
+/**
+ * api-namespace — 把 L3 API 面（api/ 层的 fp操作）装配为 cad 命名空间（统一 ABI，B2 消灭）
+ *
+ *
+ * 库函数签名 = .fai.js 源码形态（无隐式参数）；本文件无任何 per-函数逻辑。
+ *
+ * 归属（monorepo P5/E-a-1）：本文件随 stdlib 出包，是 faijs 默认标准库
+ * （cad 命名空间）的装配点。K5（引擎零函数知识）的准确含义是：parser / compile /
+ * runtime 不按函数名分支、不区分函数类别，函数信息统一以 defineOp 元数据（均匀数据）
+ * 承载。把 cad 这套库数据内置进引擎，与第三方库走完全相同的 registerLib 路径，
+ * 引擎并未对 cad 特判，因此不构成 K5 违反。cad 在 core 的 createRuntime 包装中
+ * 被注册为 default 命名空间（见 cad-runtime/createRuntimeWithCad.ts）。
+ */
+import { box, sphere, cylinder, cone, wedge } from './primitives.js';
+import { translate, rotate_euler, scale, scale3d } from './transform.js';
+// DEPRECATED（../3d_editor 特有，将来迁出并从 faijs 删除；见各 op 的 @deprecated）。
+import { fai_extrude } from './fai_extrude.js';
+// cad.extrude 是平台手写 op（承载 upTo；长度形态委托 generated/operations 的投影），
+// 见 api/extrude.ts 的分层说明——up-to 不落在 fai_extrude。
+import { extrude } from './extrude.js';
+import { knurl } from './knurl.js';
+import { sdf } from './sdf.js';
+import { text } from './text.js';
+import { screw } from './screw.js';
+import { svgExtrude } from './svgExtrude.js';
+import { sketch } from './sketch.js';
+import { load } from './load.js';
+import { fai_drill } from './fai_drill.js';
+import { fai_split } from './fai_split.js';
+import { union, subtract, intersect } from './boolean.js';
+import { engrave } from './engrave.js';
+import { chamfer } from './chamfer.js';
+import { fillet } from './fillet.js';
+import { group, assembly } from './compound.js';
+import { copy } from './copy.js';
+import { faceNormal, bboxCenter, bboxMin, bboxMax } from './geom.js';
+import { edgeRef } from './edge-ref.js';
+import { faceRef } from './face-ref.js';
+import { jointTrajectory, inverseKinematics, mechanismDOF } from './assembly/index.js';
+import { asset } from './asset.js';
+import { scriptFaceOps } from './generated/script-face.js';
+import { revolve } from './generated/operations.js';
+import { CONTRACT_VERSION } from '../runtime-state.js';
+/**
+ * Assemble stdlib functions into the cad namespace.
+ *
+ * P23（§4.2 ②，B1 三源一致）：cad 面 = faijs 特有 dual op（下方字面量）+
+ * 生成脚本面 op（`scriptFaceOps`——`api/generated/script-face.ts` 按 arg-spec
+ * 的 `scriptFace: true` 条目生成，经 `compatOp(projectBrepOp(…))` 包装的
+ * brep-only 语句级 op）。`check()` 符号表（`gen-symbol-table.ts`）与
+ * `api/index.ts` 导出面同源于同一份清单。
+ *
+ * @returns the assembled StdlibNamespace ready for runtime injection.
+ */
+export function createApiNamespace() {
+    // D-4 strict assembly check: the cad namespace now exports dual-op functions
+    // (defineOp), so registerLib requires a matching contractVersion. Cast is
+    // needed because StdlibNamespace is an index-signature type.
+    return {
+        contractVersion: CONTRACT_VERSION,
+        box, sphere, cylinder, cone, wedge,
+        text, screw, svgExtrude, sketch, sdf, load,
+        translate, rotate_euler, scale, scale3d,
+        // fai_drill / fai_extrude（本行）与 fai_split（下方）均 DEPRECATED：../3d_editor
+        // 项目特有，将来迁出并从 faijs 删除。
+        fai_drill, fai_extrude, engrave, chamfer, fillet, knurl,
+        union, subtract, intersect,
+        extrude, revolve,
+        fai_split, group, assembly, copy,
+        faceNormal, bboxCenter, bboxMin, bboxMax,
+        edgeRef,
+        faceRef,
+        jointTrajectory, inverseKinematics, mechanismDOF,
+        asset,
+        ...scriptFaceOps,
+    };
+}
+//# sourceMappingURL=api-namespace.js.map

package/dist/api/api-namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-namespace.js","sourceRoot":"","sources":["../../src/api/api-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AACjE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACrE,mEAAmE;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,iEAAiE;AACjE,iDAAiD;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AACpC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC7E,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAGnD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB;IAChC,6EAA6E;IAC7E,0EAA0E;IAC1E,6DAA6D;IAC7D,OAAO;QACL,eAAe,EAAE,gBAAgB;QACjC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK;QAClC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI;QAC1C,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO;QACvC,sEAAsE;QACtE,wBAAwB;QACxB,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK;QACvD,KAAK,EAAE,QAAQ,EAAE,SAAS;QAC1B,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI;QAChC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO;QACxC,OAAO;QACP,OAAO;QACP,eAAe,EAAE,iBAAiB,EAAE,YAAY;QAChD,KAAK;QACL,GAAG,aAAa;KACa,CAAA;AACjC,CAAC","sourcesContent":["/**\n * api-namespace — 把 L3 API 面（api/ 层的 fp操作）装配为 cad 命名空间（统一 ABI，B2 消灭）\n *\n *\n * 库函数签名 = .fai.js 源码形态（无隐式参数）；本文件无任何 per-函数逻辑。\n *\n * 归属（monorepo P5/E-a-1）：本文件随 stdlib 出包，是 faijs 默认标准库\n * （cad 命名空间）的装配点。K5（引擎零函数知识）的准确含义是：parser / compile /\n * runtime 不按函数名分支、不区分函数类别，函数信息统一以 defineOp 元数据（均匀数据）\n * 承载。把 cad 这套库数据内置进引擎，与第三方库走完全相同的 registerLib 路径，\n * 引擎并未对 cad 特判，因此不构成 K5 违反。cad 在 core 的 createRuntime 包装中\n * 被注册为 default 命名空间（见 cad-runtime/createRuntimeWithCad.ts）。\n */\n\nimport { box, sphere, cylinder, cone, wedge } from './primitives'\nimport { translate, rotate_euler, scale, scale3d } from './transform'\n// DEPRECATED（../3d_editor 特有，将来迁出并从 faijs 删除；见各 op 的 @deprecated）。\nimport { fai_extrude } from './fai_extrude'\n// cad.extrude 是平台手写 op（承载 upTo；长度形态委托 generated/operations 的投影），\n// 见 api/extrude.ts 的分层说明——up-to 不落在 fai_extrude。\nimport { extrude } from './extrude'\nimport { knurl } from './knurl'\nimport { sdf } from './sdf'\nimport { text } from './text'\nimport { screw } from './screw'\nimport { svgExtrude } from './svgExtrude'\nimport { sketch } from './sketch'\nimport { load } from './load'\nimport { fai_drill } from './fai_drill'\nimport { fai_split } from './fai_split'\nimport { union, subtract, intersect } from './boolean'\nimport { engrave } from './engrave'\nimport { chamfer } from './chamfer'\nimport { fillet } from './fillet'\nimport { group, assembly } from './compound'\nimport { copy } from './copy'\nimport { faceNormal, bboxCenter, bboxMin, bboxMax } from './geom'\nimport { edgeRef } from './edge-ref'\nimport { faceRef } from './face-ref'\nimport { jointTrajectory, inverseKinematics, mechanismDOF } from './assembly'\nimport { asset } from './asset'\nimport { scriptFaceOps } from './generated/script-face'\nimport { revolve } from './generated/operations'\nimport { CONTRACT_VERSION } from '../runtime-state'\nimport type { StdlibNamespace } from '../runtime-state'\n\n/**\n * Assemble stdlib functions into the cad namespace.\n *\n * P23（§4.2 ②，B1 三源一致）：cad 面 = faijs 特有 dual op（下方字面量）+\n * 生成脚本面 op（`scriptFaceOps`——`api/generated/script-face.ts` 按 arg-spec\n * 的 `scriptFace: true` 条目生成，经 `compatOp(projectBrepOp(…))` 包装的\n * brep-only 语句级 op）。`check()` 符号表（`gen-symbol-table.ts`）与\n * `api/index.ts` 导出面同源于同一份清单。\n *\n * @returns the assembled StdlibNamespace ready for runtime injection.\n */\nexport function createApiNamespace(): StdlibNamespace {\n  // D-4 strict assembly check: the cad namespace now exports dual-op functions\n  // (defineOp), so registerLib requires a matching contractVersion. Cast is\n  // needed because StdlibNamespace is an index-signature type.\n  return {\n    contractVersion: CONTRACT_VERSION,\n    box, sphere, cylinder, cone, wedge,\n    text, screw, svgExtrude, sketch, sdf, load,\n    translate, rotate_euler, scale, scale3d,\n    // fai_drill / fai_extrude（本行）与 fai_split（下方）均 DEPRECATED：../3d_editor\n    // 项目特有，将来迁出并从 faijs 删除。\n    fai_drill, fai_extrude, engrave, chamfer, fillet, knurl,\n    union, subtract, intersect,\n    extrude, revolve,\n    fai_split, group, assembly, copy,\n    faceNormal, bboxCenter, bboxMin, bboxMax,\n    edgeRef,\n    faceRef,\n    jointTrajectory, inverseKinematics, mechanismDOF,\n    asset,\n    ...scriptFaceOps,\n  } as unknown as StdlibNamespace\n}\n"]}

package/dist/api/assembly/entities.d.ts

@@ -0,0 +1,55 @@
+/**
+ * api/assembly/entities — EntityRef → SolverEntity 实体抽取（P1，方案 §3.6 / §5.2）
+ *
+ * 三要素范式（与 chamfer 同构，方案 §3.5）：
+ * 1. 引用可序列化：EntityRef 进 .fai.js；
+ * 2. 解析在执行期：TopoRef 复用 topo-resolve 的解析通道（BREP 现场 / mesh 行快照）；
+ * 3. 句柄是瞬态：解析出的几何立即转成纯数据 SolverEntity，句柄不跨语句。
+ *
+ * 输出契约对齐 brepjs solverAdapter 的 SolverEntity：{ type: 'plane'|'axis'|'point',
+ * origin, normal?/direction? }。dependent 侧填本地坐标（部件自身坐标系），
+ * reference 侧世界变换由 solverAdapter 的 transformEntity 负责——本层不做。
+ *
+ * 缺轴（mesh 行快照无宿主注入的 axis、sphere 等无轴面类型）→ 抛
+ * E_TOPO_NOT_FOUND（方案 R4/P0 验收③：绝不静默降级）。
+ */
+import type { Shape } from '../../mesh/types.js';
+import type { BrepEngineApi } from '../../brep/engine/primitives.js';
+import type { SolverEntity } from '../../vendored/brepjs/kernel/solverAdapter.js';
+import { type ResolvedFaceGeometry } from '../topo-resolve.js';
+import type { EntityRef } from './types.js';
+/** 实体抽取环境：内核（null = mesh/primitive 行快照路径）+ 成员查找。 */
+export interface EntityResolutionEnv {
+    kernel: BrepEngineApi | null;
+    /** part 变量名 → 成员 Shape。 */
+    memberOf: (part: string) => Shape | undefined;
+}
+/**
+ * 面几何 → SolverEntity（方案 §5.2 抽取规则表）。
+ * 平面 → plane；圆柱/圆锥（有轴）→ axis；其它/缺轴 → E_TOPO_NOT_FOUND。
+ *
+ * @param geom - the resolved face geometry (live BREP or mesh row snapshot).
+ * @returns the solver entity (plane or axis).
+ * @throws TopoRefError with code E_TOPO_NOT_FOUND when the surface has no usable axis or is unsupported.
+ */
+export declare function faceGeometryToSolverEntity(geom: ResolvedFaceGeometry): SolverEntity;
+/**
+ * 解析一个 EntityRef 的面几何（mate/align 降级路径用：只需 center + normal，
+ * 圆柱面轴不参与贴合——方案 §3.7.4 适用边界）。
+ *
+ * @param ref - the entity reference (must be a face reference).
+ * @param env - the resolution environment.
+ * @returns the resolved face geometry.
+ * @throws Error when the ref is not a face reference or the part is unknown.
+ */
+export declare function resolveFaceGeometryOfRef(ref: EntityRef, env: EntityResolutionEnv): ResolvedFaceGeometry;
+/**
+ * 解析一个 EntityRef → SolverEntity（coincident/concentric/distance/angle 直译路径）。
+ *
+ * @param ref - the entity reference.
+ * @param env - the resolution environment.
+ * @returns the solver entity (pure data).
+ * @throws TopoRefError / Error on unresolvable or unsupported references.
+ */
+export declare function resolveSolverEntity(ref: EntityRef, env: EntityResolutionEnv): SolverEntity;
+//# sourceMappingURL=entities.d.ts.map

package/dist/api/assembly/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/entities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAEjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAG9E,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAA;AAEtD,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IAC5B,2BAA2B;IAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,GAAG,SAAS,CAAA;CAC9C;AAQD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,oBAAoB,GAAG,YAAY,CAiBnF;AAOD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,mBAAmB,GAAG,oBAAoB,CAcvG;AAqCD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,mBAAmB,GAAG,YAAY,CA4C1F"}

package/dist/api/assembly/entities.js

@@ -0,0 +1,158 @@
+/**
+ * api/assembly/entities — EntityRef → SolverEntity 实体抽取（P1，方案 §3.6 / §5.2）
+ *
+ * 三要素范式（与 chamfer 同构，方案 §3.5）：
+ * 1. 引用可序列化：EntityRef 进 .fai.js；
+ * 2. 解析在执行期：TopoRef 复用 topo-resolve 的解析通道（BREP 现场 / mesh 行快照）；
+ * 3. 句柄是瞬态：解析出的几何立即转成纯数据 SolverEntity，句柄不跨语句。
+ *
+ * 输出契约对齐 brepjs solverAdapter 的 SolverEntity：{ type: 'plane'|'axis'|'point',
+ * origin, normal?/direction? }。dependent 侧填本地坐标（部件自身坐标系），
+ * reference 侧世界变换由 solverAdapter 的 transformEntity 负责——本层不做。
+ *
+ * 缺轴（mesh 行快照无宿主注入的 axis、sphere 等无轴面类型）→ 抛
+ * E_TOPO_NOT_FOUND（方案 R4/P0 验收③：绝不静默降级）。
+ */
+import { TopoRefError } from '../../topology/naming/index.js';
+import { resolveTopoRef, captureEdgeAxis, captureFaceHint } from '../../topology/naming/index.js';
+import { buildShapeResolutionContext, buildEdgeResolutionContext, resolveFaceGeometry, } from '../topo-resolve.js';
+/** 无轴可用的报错信息后缀（E_TOPO_NOT_FOUND）。 */
+function missingAxisReason(geom) {
+    return `face needs an axis (surfaceType=${geom.surfaceType ?? 'unknown'}) but none is available ` +
+        `(BREP path: captureFaceHint; mesh path: host must inject axis into the naming row)`;
+}
+/**
+ * 面几何 → SolverEntity（方案 §5.2 抽取规则表）。
+ * 平面 → plane；圆柱/圆锥（有轴）→ axis；其它/缺轴 → E_TOPO_NOT_FOUND。
+ *
+ * @param geom - the resolved face geometry (live BREP or mesh row snapshot).
+ * @returns the solver entity (plane or axis).
+ * @throws TopoRefError with code E_TOPO_NOT_FOUND when the surface has no usable axis or is unsupported.
+ */
+export function faceGeometryToSolverEntity(geom) {
+    const st = geom.surfaceType;
+    if (st === 'cylinder' || st === 'cone') {
+        if (!geom.axis) {
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', missingAxisReason(geom));
+        }
+        return { type: 'axis', origin: geom.axis.origin, direction: geom.axis.direction };
+    }
+    if (!st || st === 'plane') {
+        return { type: 'plane', origin: geom.center, normal: geom.normal };
+    }
+    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `unsupported surface type for an assembly entity: ${st}` +
+        (geom.axis ? '' : ` (${missingAxisReason(geom)})`));
+}
+/** 快照形态 FaceRef → ResolvedFaceGeometry（无 axis——贴合语义只需 center+normal）。 */
+function snapshotFaceGeometry(face) {
+    return { surfaceType: face.surfaceType, center: face.center, normal: face.normal };
+}
+/**
+ * 解析一个 EntityRef 的面几何（mate/align 降级路径用：只需 center + normal，
+ * 圆柱面轴不参与贴合——方案 §3.7.4 适用边界）。
+ *
+ * @param ref - the entity reference (must be a face reference).
+ * @param env - the resolution environment.
+ * @returns the resolved face geometry.
+ * @throws Error when the ref is not a face reference or the part is unknown.
+ */
+export function resolveFaceGeometryOfRef(ref, env) {
+    if (!('face' in ref)) {
+        throw new Error('[assembly] mate/align constraints require face references on both sides');
+    }
+    const shape = env.memberOf(ref.part);
+    if (!shape)
+        throw new Error(`[assembly] constraint references unknown part: ${ref.part}`);
+    const face = ref.face;
+    if (face.topoRef) {
+        return resolveFaceGeometry(env.kernel, shape, face.topoRef);
+    }
+    if (!face.center || !face.normal) {
+        throw new Error('[assembly] face snapshot requires center and normal');
+    }
+    return snapshotFaceGeometry(face);
+}
+/** 边 TopoRef → 轴（BREP 现场；mesh 无邻接能力 → E_TOPO_NOT_FOUND）。 */
+function resolveEdgeAxisFromTopoRef(kernel, shape, edgeTopoRef, part) {
+    const ctx = buildEdgeResolutionContext(kernel, shape);
+    if (!ctx) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', `edge entity needs a BREP naming context (part=${part}); mesh parts have no edge adjacency`);
+    }
+    const resolved = resolveTopoRef(edgeTopoRef, ctx);
+    const entry = ctx.edges?.[resolved.ordinal - 1];
+    if (!entry?.handle) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', `resolved edge ordinal ${resolved.ordinal} has no live handle (part=${part})`);
+    }
+    const axis = captureEdgeAxis(kernel, entry.handle);
+    if (!axis) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', `edge ordinal ${resolved.ordinal} is not a line or circle — no axis entity available`);
+    }
+    return axis;
+}
+/**
+ * 解析一个 EntityRef → SolverEntity（coincident/concentric/distance/angle 直译路径）。
+ *
+ * @param ref - the entity reference.
+ * @param env - the resolution environment.
+ * @returns the solver entity (pure data).
+ * @throws TopoRefError / Error on unresolvable or unsupported references.
+ */
+export function resolveSolverEntity(ref, env) {
+    const shape = env.memberOf(ref.part);
+    if (!shape)
+        throw new Error(`[assembly] constraint references unknown part: ${ref.part}`);
+    if ('point' in ref) {
+        return { type: 'point', origin: ref.point };
+    }
+    if ('face' in ref) {
+        return faceGeometryToSolverEntity(resolveFaceGeometryOfRef(ref, env));
+    }
+    if ('faceIndex' in ref) {
+        // 序号简写（1 起，调试用）：直接按 ordinal 取候选面几何（不走 TopoRef 打分）
+        const ctx = buildShapeResolutionContext(env.kernel, shape);
+        if (!ctx) {
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceIndex ${ref.faceIndex} has no naming context on part ${ref.part}`);
+        }
+        const entry = ctx.faces[ref.faceIndex - 1];
+        if (!entry) {
+            throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceIndex ${ref.faceIndex} out of range (part ${ref.part} has ${ctx.faces.length} faces)`);
+        }
+        return faceGeometryToSolverEntity(faceGeometryFromContextEntry(env, entry, ref.part));
+    }
+    // edge 引用
+    const edge = ref.edge;
+    if (edge.axis) {
+        return { type: 'axis', origin: edge.axis.origin, direction: edge.axis.direction };
+    }
+    if (!env.kernel) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'edge', `edge TopoRef needs a live kernel (part=${ref.part}); mesh path supports only axis snapshots`);
+    }
+    const axis = resolveEdgeAxisFromTopoRef(env.kernel, shape, edge.topoRef, ref.part);
+    return { type: 'axis', origin: axis.origin, direction: axis.direction };
+}
+/**
+ * faceIndex 简写的面几何（从解析上下文候选行直接取）：
+ * BREP 候选（活句柄）→ captureFaceHint 现场；行快照候选 → 行几何。
+ */
+function faceGeometryFromContextEntry(env, entry, part) {
+    if (entry.handle && env.kernel) {
+        const hint = captureFaceHint(env.kernel, entry.handle);
+        return {
+            surfaceType: hint.surfaceType,
+            center: hint.center ?? [0, 0, 0],
+            normal: hint.normal ?? [0, 0, 1],
+            ...(hint.axis ? { axis: hint.axis } : {}),
+        };
+    }
+    const hint = entry.row;
+    if (!hint?.center || !hint?.normal) {
+        throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceIndex row has no geometry (part=${part})`);
+    }
+    return {
+        surfaceType: hint.surfaceType,
+        center: hint.center,
+        normal: hint.normal,
+        ...(hint.axis ? { axis: hint.axis } : {}),
+    };
+}
+//# sourceMappingURL=entities.js.map

package/dist/api/assembly/entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/api/assembly/entities.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/entities — EntityRef → SolverEntity 实体抽取（P1，方案 §3.6 / §5.2）\n *\n * 三要素范式（与 chamfer 同构，方案 §3.5）：\n * 1. 引用可序列化：EntityRef 进 .fai.js；\n * 2. 解析在执行期：TopoRef 复用 topo-resolve 的解析通道（BREP 现场 / mesh 行快照）；\n * 3. 句柄是瞬态：解析出的几何立即转成纯数据 SolverEntity，句柄不跨语句。\n *\n * 输出契约对齐 brepjs solverAdapter 的 SolverEntity：{ type: 'plane'|'axis'|'point',\n * origin, normal?/direction? }。dependent 侧填本地坐标（部件自身坐标系），\n * reference 侧世界变换由 solverAdapter 的 transformEntity 负责——本层不做。\n *\n * 缺轴（mesh 行快照无宿主注入的 axis、sphere 等无轴面类型）→ 抛\n * E_TOPO_NOT_FOUND（方案 R4/P0 验收③：绝不静默降级）。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { PartName } from '../../identity'\nimport type { SolverEntity } from '../../vendored/brepjs/kernel/solverAdapter'\nimport { TopoRefError, type AxisHint } from '../../topology/naming'\nimport { resolveTopoRef, captureEdgeAxis, captureFaceHint } from '../../topology/naming'\nimport {\n  buildShapeResolutionContext,\n  buildEdgeResolutionContext,\n  resolveFaceGeometry,\n  type ResolvedFaceGeometry,\n} from '../topo-resolve'\nimport type { EntityRef, AssemblyVec3 } from './types'\n\n/** 实体抽取环境：内核（null = mesh/primitive 行快照路径）+ 成员查找。 */\nexport interface EntityResolutionEnv {\n  kernel: BrepEngineApi | null\n  /** part 变量名 → 成员 Shape。 */\n  memberOf: (part: string) => Shape | undefined\n}\n\n/** 无轴可用的报错信息后缀（E_TOPO_NOT_FOUND）。 */\nfunction missingAxisReason(geom: ResolvedFaceGeometry): string {\n  return `face needs an axis (surfaceType=${geom.surfaceType ?? 'unknown'}) but none is available ` +\n    `(BREP path: captureFaceHint; mesh path: host must inject axis into the naming row)`\n}\n\n/**\n * 面几何 → SolverEntity（方案 §5.2 抽取规则表）。\n * 平面 → plane；圆柱/圆锥（有轴）→ axis；其它/缺轴 → E_TOPO_NOT_FOUND。\n *\n * @param geom - the resolved face geometry (live BREP or mesh row snapshot).\n * @returns the solver entity (plane or axis).\n * @throws TopoRefError with code E_TOPO_NOT_FOUND when the surface has no usable axis or is unsupported.\n */\nexport function faceGeometryToSolverEntity(geom: ResolvedFaceGeometry): SolverEntity {\n  const st = geom.surfaceType\n  if (st === 'cylinder' || st === 'cone') {\n    if (!geom.axis) {\n      throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', missingAxisReason(geom))\n    }\n    return { type: 'axis', origin: geom.axis.origin, direction: geom.axis.direction }\n  }\n  if (!st || st === 'plane') {\n    return { type: 'plane', origin: geom.center, normal: geom.normal }\n  }\n  throw new TopoRefError(\n    'E_TOPO_NOT_FOUND',\n    'face',\n    `unsupported surface type for an assembly entity: ${st}` +\n      (geom.axis ? '' : ` (${missingAxisReason(geom)})`),\n  )\n}\n\n/** 快照形态 FaceRef → ResolvedFaceGeometry（无 axis——贴合语义只需 center+normal）。 */\nfunction snapshotFaceGeometry(face: { surfaceType?: string; center: AssemblyVec3; normal: AssemblyVec3 }): ResolvedFaceGeometry {\n  return { surfaceType: face.surfaceType, center: face.center, normal: face.normal }\n}\n\n/**\n * 解析一个 EntityRef 的面几何（mate/align 降级路径用：只需 center + normal，\n * 圆柱面轴不参与贴合——方案 §3.7.4 适用边界）。\n *\n * @param ref - the entity reference (must be a face reference).\n * @param env - the resolution environment.\n * @returns the resolved face geometry.\n * @throws Error when the ref is not a face reference or the part is unknown.\n */\nexport function resolveFaceGeometryOfRef(ref: EntityRef, env: EntityResolutionEnv): ResolvedFaceGeometry {\n  if (!('face' in ref)) {\n    throw new Error('[assembly] mate/align constraints require face references on both sides')\n  }\n  const shape = env.memberOf(ref.part)\n  if (!shape) throw new Error(`[assembly] constraint references unknown part: ${ref.part}`)\n  const face = ref.face as { topoRef?: unknown; center?: AssemblyVec3; normal?: AssemblyVec3; surfaceType?: string }\n  if (face.topoRef) {\n    return resolveFaceGeometry(env.kernel, shape, face.topoRef as Parameters<typeof resolveFaceGeometry>[2])\n  }\n  if (!face.center || !face.normal) {\n    throw new Error('[assembly] face snapshot requires center and normal')\n  }\n  return snapshotFaceGeometry(face as { surfaceType?: string; center: AssemblyVec3; normal: AssemblyVec3 })\n}\n\n/** 边 TopoRef → 轴（BREP 现场；mesh 无邻接能力 → E_TOPO_NOT_FOUND）。 */\nfunction resolveEdgeAxisFromTopoRef(\n  kernel: BrepEngineApi,\n  shape: Shape,\n  edgeTopoRef: Parameters<typeof resolveTopoRef>[0],\n  part: PartName,\n): AxisHint {\n  const ctx = buildEdgeResolutionContext(kernel, shape)\n  if (!ctx) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge entity needs a BREP naming context (part=${part}); mesh parts have no edge adjacency`,\n    )\n  }\n  const resolved = resolveTopoRef(edgeTopoRef, ctx)\n  const entry = ctx.edges?.[resolved.ordinal - 1]\n  if (!entry?.handle) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `resolved edge ordinal ${resolved.ordinal} has no live handle (part=${part})`,\n    )\n  }\n  const axis = captureEdgeAxis(kernel, entry.handle)\n  if (!axis) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge ordinal ${resolved.ordinal} is not a line or circle — no axis entity available`,\n    )\n  }\n  return axis\n}\n\n/**\n * 解析一个 EntityRef → SolverEntity（coincident/concentric/distance/angle 直译路径）。\n *\n * @param ref - the entity reference.\n * @param env - the resolution environment.\n * @returns the solver entity (pure data).\n * @throws TopoRefError / Error on unresolvable or unsupported references.\n */\nexport function resolveSolverEntity(ref: EntityRef, env: EntityResolutionEnv): SolverEntity {\n  const shape = env.memberOf(ref.part)\n  if (!shape) throw new Error(`[assembly] constraint references unknown part: ${ref.part}`)\n\n  if ('point' in ref) {\n    return { type: 'point', origin: ref.point }\n  }\n  if ('face' in ref) {\n    return faceGeometryToSolverEntity(resolveFaceGeometryOfRef(ref, env))\n  }\n  if ('faceIndex' in ref) {\n    // 序号简写（1 起，调试用）：直接按 ordinal 取候选面几何（不走 TopoRef 打分）\n    const ctx = buildShapeResolutionContext(env.kernel, shape)\n    if (!ctx) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `faceIndex ${ref.faceIndex} has no naming context on part ${ref.part}`,\n      )\n    }\n    const entry = ctx.faces[ref.faceIndex - 1]\n    if (!entry) {\n      throw new TopoRefError(\n        'E_TOPO_NOT_FOUND',\n        'face',\n        `faceIndex ${ref.faceIndex} out of range (part ${ref.part} has ${ctx.faces.length} faces)`,\n      )\n    }\n    return faceGeometryToSolverEntity(faceGeometryFromContextEntry(env, entry, ref.part))\n  }\n  // edge 引用\n  const edge = ref.edge as { topoRef?: unknown; axis?: { origin: AssemblyVec3; direction: AssemblyVec3 } }\n  if (edge.axis) {\n    return { type: 'axis', origin: edge.axis.origin, direction: edge.axis.direction }\n  }\n  if (!env.kernel) {\n    throw new TopoRefError(\n      'E_TOPO_NOT_FOUND',\n      'edge',\n      `edge TopoRef needs a live kernel (part=${ref.part}); mesh path supports only axis snapshots`,\n    )\n  }\n  const axis = resolveEdgeAxisFromTopoRef(env.kernel, shape, edge.topoRef as Parameters<typeof resolveTopoRef>[0], ref.part)\n  return { type: 'axis', origin: axis.origin, direction: axis.direction }\n}\n\n/**\n * faceIndex 简写的面几何（从解析上下文候选行直接取）：\n * BREP 候选（活句柄）→ captureFaceHint 现场；行快照候选 → 行几何。\n */\nfunction faceGeometryFromContextEntry(\n  env: EntityResolutionEnv,\n  entry: { handle?: unknown; row?: unknown },\n  part: PartName,\n): ResolvedFaceGeometry {\n  if (entry.handle && env.kernel) {\n    const hint = captureFaceHint(env.kernel, entry.handle as Parameters<typeof captureFaceHint>[1])\n    return {\n      surfaceType: hint.surfaceType,\n      center: hint.center ?? [0, 0, 0],\n      normal: hint.normal ?? [0, 0, 1],\n      ...(hint.axis ? { axis: hint.axis } : {}),\n    }\n  }\n  const hint = entry.row as\n    | { surfaceType?: string; center?: AssemblyVec3; normal?: AssemblyVec3; axis?: AxisHint }\n    | undefined\n  if (!hint?.center || !hint?.normal) {\n    throw new TopoRefError('E_TOPO_NOT_FOUND', 'face', `faceIndex row has no geometry (part=${part})`)\n  }\n  return {\n    surfaceType: hint.surfaceType,\n    center: hint.center,\n    normal: hint.normal,\n    ...(hint.axis ? { axis: hint.axis } : {}),\n  }\n}\n"]}

package/dist/api/assembly/golden-mate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Golden 基准：`mate` 约束的旧实现输出冻结（P2-f5 前置 a，《09-07 方案 §2.8 ①-a》）
+ *
+ * ⚠️ 这组数值是 brepjs 迁移前 faijs 旧实现在 2026-09-07 的产出，旧实现删除后它们就是
+ * `mate` 语义的唯一回归基准——改动它们等于改动存量装配行为。
+ *
+ * 生成方式：删除前用 faijs 旧装配实现（已删）跑下述输入
+ * 打印固化（临时脚本 packages/core/scripts/tmp-golden-mate.ts，跑完即弃，不入库）。
+ *
+ * 比对规则（方案 §2.8 ①-a）：
+ * - `rotationMatrix` + `pivot` + `translation`：逐分量 1e-9；
+ * - `quaternion`（faijs [x,y,z,w] 序）：按同旋转等价类判定 `|dot(q, q_golden)| ≈ 1`
+ *   （G3/E1 的 dot=−1 分支有符号双解，逐分量比会随机红）。
+ */
+export interface GoldenMateCase {
+    /** 用例标签（G1–G4 是 09-06 方案 §4.3 验收数据；E1/E2 是 T4 退化分支补充）。 */
+    label: string;
+    /** fixed face center（world） */
+    p1: [number, number, number];
+    /** fixed face normal（world） */
+    n1: [number, number, number];
+    /** moving face center（world） */
+    p2: [number, number, number];
+    /** moving face normal（world） */
+    n2: [number, number, number];
+    /** 3x3 旋转矩阵（row-major，9 元） */
+    rotationMatrix: number[];
+    /** 旋转 pivot（= moving face center，旧实现 `p' = R·(p−pivot)+pivot+translation`） */
+    pivot: [number, number, number];
+    /** 平移 = fixedCenter − movingCenter（旧实现 `vec3Sub(p1, p2)`） */
+    translation: [number, number, number];
+    /** 四元数（faijs [x,y,z,w] 序；仅做同旋转等价类判定） */
+    quaternion: [number, number, number, number];
+}
+/**
+ * 面贴合 golden 基准用例（G1–G4 面向同向/异向/斜交；E1–E2 面向误差容差）。
+ * 每个用例含输入双平面（p/n）与期望解（旋转矩阵、枢轴、平移、四元数），
+ * 供约束求解器与自有实现的一致性回归比对（固定快照）。
+ */
+export declare const GOLDEN_MATE_CASES: GoldenMateCase[];
+/**
+ * 按标签取一个 golden 用例；未知标签抛错（防测试里 typos 静默跳过）。
+ *
+ * @param label - 用例标签（G1–G4 / E1–E2）。
+ * @returns 匹配的 golden 用例对象。
+ * @throws Error 未知标签。
+ */
+export declare function goldenMateCase(label: string): GoldenMateCase;
+//# sourceMappingURL=golden-mate.d.ts.map

package/dist/api/assembly/golden-mate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden-mate.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/golden-mate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAA;IACb,+BAA+B;IAC/B,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,+BAA+B;IAC/B,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,gCAAgC;IAChC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,gCAAgC;IAChC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,8BAA8B;IAC9B,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,8EAA8E;IAC9E,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,6DAA6D;IAC7D,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,wCAAwC;IACxC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7C;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAAc,EAmE7C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAI5D"}

package/dist/api/assembly/golden-mate.js

@@ -0,0 +1,101 @@
+/**
+ * Golden 基准：`mate` 约束的旧实现输出冻结（P2-f5 前置 a，《09-07 方案 §2.8 ①-a》）
+ *
+ * ⚠️ 这组数值是 brepjs 迁移前 faijs 旧实现在 2026-09-07 的产出，旧实现删除后它们就是
+ * `mate` 语义的唯一回归基准——改动它们等于改动存量装配行为。
+ *
+ * 生成方式：删除前用 faijs 旧装配实现（已删）跑下述输入
+ * 打印固化（临时脚本 packages/core/scripts/tmp-golden-mate.ts，跑完即弃，不入库）。
+ *
+ * 比对规则（方案 §2.8 ①-a）：
+ * - `rotationMatrix` + `pivot` + `translation`：逐分量 1e-9；
+ * - `quaternion`（faijs [x,y,z,w] 序）：按同旋转等价类判定 `|dot(q, q_golden)| ≈ 1`
+ *   （G3/E1 的 dot=−1 分支有符号双解，逐分量比会随机红）。
+ */
+/**
+ * 面贴合 golden 基准用例（G1–G4 面向同向/异向/斜交；E1–E2 面向误差容差）。
+ * 每个用例含输入双平面（p/n）与期望解（旋转矩阵、枢轴、平移、四元数），
+ * 供约束求解器与自有实现的一致性回归比对（固定快照）。
+ */
+export const GOLDEN_MATE_CASES = [
+    {
+        label: 'G1',
+        p1: [0, 0, 10],
+        n1: [0, 0, 1],
+        p2: [5, 0, 0],
+        n2: [1, 0, 0],
+        rotationMatrix: [2.220446049250313e-16, 0, 0.9999999999999998, 0, 1, 0, -0.9999999999999998, 0, 2.220446049250313e-16],
+        pivot: [5, 0, 0],
+        translation: [-5, 0, 10],
+        quaternion: [0, 0.7071067811865475, 0, 0.7071067811865475],
+    },
+    {
+        label: 'G2',
+        p1: [0, 0, 10],
+        n1: [0, 0, 1],
+        p2: [0, 0, 10],
+        n2: [0, 0, -1],
+        rotationMatrix: [1, 0, 0, 0, 1, 0, 0, 0, 1],
+        pivot: [0, 0, 10],
+        translation: [0, 0, 0],
+        quaternion: [0, 0, 0, 1],
+    },
+    {
+        label: 'G3',
+        p1: [0, 0, 10],
+        n1: [0, 0, 1],
+        p2: [0, 0, 10],
+        n2: [0, 0, 1],
+        rotationMatrix: [-1, 0, 0, 0, 1, 0, 0, 0, -1],
+        pivot: [0, 0, 10],
+        translation: [0, 0, 0],
+        quaternion: [0, 1, 0, 0],
+    },
+    {
+        label: 'G4',
+        p1: [0, 0, 10],
+        n1: [0, 0, 1],
+        p2: [0, 0, 10],
+        n2: [1, 0, 0],
+        rotationMatrix: [2.220446049250313e-16, 0, 0.9999999999999998, 0, 1, 0, -0.9999999999999998, 0, 2.220446049250313e-16],
+        pivot: [0, 0, 10],
+        translation: [0, 0, 0],
+        quaternion: [0, 0.7071067811865475, 0, 0.7071067811865475],
+    },
+    {
+        label: 'E1',
+        p1: [0, 0, 0],
+        n1: [0, 0, 1],
+        p2: [0, 0, 4],
+        n2: [0, 0, 1],
+        rotationMatrix: [-1, 0, 0, 0, 1, 0, 0, 0, -1],
+        pivot: [0, 0, 4],
+        translation: [0, 0, -4],
+        quaternion: [0, 1, 0, 0],
+    },
+    {
+        label: 'E2',
+        p1: [0, 0, 0],
+        n1: [0, 0, 1],
+        p2: [1, 2, 3],
+        n2: [0, 1, 0],
+        rotationMatrix: [1, 0, 0, 0, 2.220446049250313e-16, 0.9999999999999998, 0, -0.9999999999999998, 2.220446049250313e-16],
+        pivot: [1, 2, 3],
+        translation: [-1, -2, -3],
+        quaternion: [-0.7071067811865475, 0, 0, 0.7071067811865475],
+    },
+];
+/**
+ * 按标签取一个 golden 用例；未知标签抛错（防测试里 typos 静默跳过）。
+ *
+ * @param label - 用例标签（G1–G4 / E1–E2）。
+ * @returns 匹配的 golden 用例对象。
+ * @throws Error 未知标签。
+ */
+export function goldenMateCase(label) {
+    const found = GOLDEN_MATE_CASES.find((c) => c.label === label);
+    if (!found)
+        throw new Error(`golden-mate: unknown case "${label}"`);
+    return found;
+}
+//# sourceMappingURL=golden-mate.js.map

package/dist/api/assembly/golden-mate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden-mate.js","sourceRoot":"","sources":["../../../src/api/assembly/golden-mate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Golden 基准：`mate` 约束的旧实现输出冻结（P2-f5 前置 a，《09-07 方案 §2.8 ①-a》）\n *\n * ⚠️ 这组数值是 brepjs 迁移前 faijs 旧实现在 2026-09-07 的产出，旧实现删除后它们就是\n * `mate` 语义的唯一回归基准——改动它们等于改动存量装配行为。\n *\n * 生成方式：删除前用 faijs 旧装配实现（已删）跑下述输入\n * 打印固化（临时脚本 packages/core/scripts/tmp-golden-mate.ts，跑完即弃，不入库）。\n *\n * 比对规则（方案 §2.8 ①-a）：\n * - `rotationMatrix` + `pivot` + `translation`：逐分量 1e-9；\n * - `quaternion`（faijs [x,y,z,w] 序）：按同旋转等价类判定 `|dot(q, q_golden)| ≈ 1`\n *   （G3/E1 的 dot=−1 分支有符号双解，逐分量比会随机红）。\n */\n\nexport interface GoldenMateCase {\n  /** 用例标签（G1–G4 是 09-06 方案 §4.3 验收数据；E1/E2 是 T4 退化分支补充）。 */\n  label: string\n  /** fixed face center（world） */\n  p1: [number, number, number]\n  /** fixed face normal（world） */\n  n1: [number, number, number]\n  /** moving face center（world） */\n  p2: [number, number, number]\n  /** moving face normal（world） */\n  n2: [number, number, number]\n  /** 3x3 旋转矩阵（row-major，9 元） */\n  rotationMatrix: number[]\n  /** 旋转 pivot（= moving face center，旧实现 `p' = R·(p−pivot)+pivot+translation`） */\n  pivot: [number, number, number]\n  /** 平移 = fixedCenter − movingCenter（旧实现 `vec3Sub(p1, p2)`） */\n  translation: [number, number, number]\n  /** 四元数（faijs [x,y,z,w] 序；仅做同旋转等价类判定） */\n  quaternion: [number, number, number, number]\n}\n\n/**\n * 面贴合 golden 基准用例（G1–G4 面向同向/异向/斜交；E1–E2 面向误差容差）。\n * 每个用例含输入双平面（p/n）与期望解（旋转矩阵、枢轴、平移、四元数），\n * 供约束求解器与自有实现的一致性回归比对（固定快照）。\n */\nexport const GOLDEN_MATE_CASES: GoldenMateCase[] = [\n  {\n    label: 'G1',\n    p1: [0, 0, 10],\n    n1: [0, 0, 1],\n    p2: [5, 0, 0],\n    n2: [1, 0, 0],\n    rotationMatrix: [2.220446049250313e-16, 0, 0.9999999999999998, 0, 1, 0, -0.9999999999999998, 0, 2.220446049250313e-16],\n    pivot: [5, 0, 0],\n    translation: [-5, 0, 10],\n    quaternion: [0, 0.7071067811865475, 0, 0.7071067811865475],\n  },\n  {\n    label: 'G2',\n    p1: [0, 0, 10],\n    n1: [0, 0, 1],\n    p2: [0, 0, 10],\n    n2: [0, 0, -1],\n    rotationMatrix: [1, 0, 0, 0, 1, 0, 0, 0, 1],\n    pivot: [0, 0, 10],\n    translation: [0, 0, 0],\n    quaternion: [0, 0, 0, 1],\n  },\n  {\n    label: 'G3',\n    p1: [0, 0, 10],\n    n1: [0, 0, 1],\n    p2: [0, 0, 10],\n    n2: [0, 0, 1],\n    rotationMatrix: [-1, 0, 0, 0, 1, 0, 0, 0, -1],\n    pivot: [0, 0, 10],\n    translation: [0, 0, 0],\n    quaternion: [0, 1, 0, 0],\n  },\n  {\n    label: 'G4',\n    p1: [0, 0, 10],\n    n1: [0, 0, 1],\n    p2: [0, 0, 10],\n    n2: [1, 0, 0],\n    rotationMatrix: [2.220446049250313e-16, 0, 0.9999999999999998, 0, 1, 0, -0.9999999999999998, 0, 2.220446049250313e-16],\n    pivot: [0, 0, 10],\n    translation: [0, 0, 0],\n    quaternion: [0, 0.7071067811865475, 0, 0.7071067811865475],\n  },\n  {\n    label: 'E1',\n    p1: [0, 0, 0],\n    n1: [0, 0, 1],\n    p2: [0, 0, 4],\n    n2: [0, 0, 1],\n    rotationMatrix: [-1, 0, 0, 0, 1, 0, 0, 0, -1],\n    pivot: [0, 0, 4],\n    translation: [0, 0, -4],\n    quaternion: [0, 1, 0, 0],\n  },\n  {\n    label: 'E2',\n    p1: [0, 0, 0],\n    n1: [0, 0, 1],\n    p2: [1, 2, 3],\n    n2: [0, 1, 0],\n    rotationMatrix: [1, 0, 0, 0, 2.220446049250313e-16, 0.9999999999999998, 0, -0.9999999999999998, 2.220446049250313e-16],\n    pivot: [1, 2, 3],\n    translation: [-1, -2, -3],\n    quaternion: [-0.7071067811865475, 0, 0, 0.7071067811865475],\n  },\n]\n\n/**\n * 按标签取一个 golden 用例；未知标签抛错（防测试里 typos 静默跳过）。\n *\n * @param label - 用例标签（G1–G4 / E1–E2）。\n * @returns 匹配的 golden 用例对象。\n * @throws Error 未知标签。\n */\nexport function goldenMateCase(label: string): GoldenMateCase {\n  const found = GOLDEN_MATE_CASES.find((c) => c.label === label)\n  if (!found) throw new Error(`golden-mate: unknown case \"${label}\"`)\n  return found\n}"]}

package/dist/api/assembly/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * api/assembly — 装配约束求解层（P1）
+ *
+ * 分层（方案 §4.1）：normalize（规范化 + face_mate 兼容）→ lower（直译降级，
+ * mate/align 寄生在 concentric 上）→ entities（TopoRef → SolverEntity，双链路）
+ * → solve（委派 brepjs solveConstraints）→ pose（位姿转换契约）。
+ */
+export * from './types.js';
+export * from './normalize.js';
+export * from './entities.js';
+export * from './lower.js';
+export * from './pose.js';
+export * from './solve.js';
+export * from './preview.js';
+export * from './joints.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/assembly/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,SAAS,CAAA;AACvB,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA"}