@faicad/faijs 0.22.2 → 0.29.5

package/dist/brepkit-kernel/brepkitKernel.js

@@ -18,12 +18,55 @@
  * - 链纪律：kernel.meshFallbackCount 计数差 > 0 → getMeshFallbackCount 暴露给宿主，
  *   由宿主标记 BREP 链中断（不在此层静默处理）。
  */
-import { initBrepkitWasm } from './brepkitWasm.js';
+import { initBrepkitWasm, resetBrepkitWasm } from './brepkitWasm.js';
 import { DEFAULT_LINEAR_DEFLECTION } from '../tolerance.js';
 import { mm } from '../units.js';
-// ── 句柄桥接：brepkit number 句柄 ↔ BrepHandle（零运行时成本，与 occt 适配器同构） ──
+import { BREP_HASH_BOUND } from '../brep/engine/types.js';
+// ── 句柄桥接：brepkit number 句柄 ↔ BrepHandle ──
+//
+// GOTCHA（2026-10-01 实测，本文件最容易踩的坑）：brepkit 句柄是**按类型分命名空间的裸 u32**
+// ——同一个 box 上 solid=0、face=0..5、edge=0..11 同时存在，且**内核没有任何可靠的类型判别式**：
+//   getEdgeCurveType(0) / edgeLength(0)     → 命中 edge 0
+//   getFaceEdges(0) / getFaceNormal(0)      → 命中 face 0
+//   getSolidFaces(0)                        → 命中 solid 0
+// 三者对同一个数字 0 各自返回「自己命名空间里 0 号」的数据，谁都不抛错（`getSolidFaces(1)` 才抛）。
+// 因此「拿句柄去问内核它是什么类型」在 brepkit 上**不可能实现**。
+//
+// 但 L1 契约里 `hashCode(handle)` 只收到一个数字，必须知道类型才能选面/边指纹函数。
+// 解法：适配器在**出口**把类型编进句柄高位。类型随句柄流动，`asNum()` 剥掉标签后仍是内核
+// 裸句柄号——内部集合（knownFaces/knownEdges/…）、hashRegistry、全部 `kernel.*` 调用语义不变。
+// 高 3 位（bit 26..28）放类型；虚拟 compound 句柄从 bit 29（0x20000000）起分配，互不干扰。
+// 注意 `asNum` 用**算术减法**而非 `& ~KIND_MASK`：后者把 ≥2^31 的虚拟句柄按 int32 截断成负数。
+const KIND_SHIFT = 26;
+const KIND_MASK = 7 << KIND_SHIFT;
+const KIND_SOLID = 0 << KIND_SHIFT; // 也是 compound / 未登记句柄的默认类
+const KIND_FACE = 1 << KIND_SHIFT;
+const KIND_EDGE = 2 << KIND_SHIFT;
+const KIND_WIRE = 3 << KIND_SHIFT;
+const KIND_VERTEX = 4 << KIND_SHIFT;
+/** 句柄类型标签（0 = SOLID/COMPOUND 默认类）。 */
+const kindOf = (h) => h & KIND_MASK;
+/** 剥掉类型标签，得到 brepkit 内核裸句柄号——所有 `kernel.*` 调用必须用这个。 */
+const asNum = (h) => {
+    const n = h;
+    return n - (n & KIND_MASK);
+};
+/** 实体/compound 句柄（默认类，保持历史行为：无标签 ⇒ 内核按 solid 路径分发）。 */
 const asHandle = (n) => n;
-const asNum = (h) => h;
+const asFace = (n) => (n | KIND_FACE);
+const asEdge = (n) => (n | KIND_EDGE);
+const asWire = (n) => (n | KIND_WIRE);
+const asVertex = (n) => (n | KIND_VERTEX);
+/** 按已有类型标签给裸句柄重新打标签（copy/transform 族保持入参类型）。 */
+const withKind = (kind, n) => {
+    switch (kind) {
+        case KIND_FACE: return asFace(n);
+        case KIND_EDGE: return asEdge(n);
+        case KIND_WIRE: return asWire(n);
+        case KIND_VERTEX: return asVertex(n);
+        default: return asHandle(n);
+    }
+};
 const arr = (x) => Array.from(x);
 /** 适配器内部的显式失败（替代旧 unsupported 桩：能力缺失一律在静态判定拦截，不在实现体里伪装）。 */
 function fail(detail) {
@@ -79,6 +122,26 @@ function toNumArray(v) {
     }
     return [];
 }
+/**
+ * brepkit 无任何 hash API（228 个方法里没有 hashCode/subShapeHashes）——faijs 侧的
+ * 面/边 hash 全部由适配器**合成指纹**，因此「合成函数」与「消费函数的取模上界」
+ * 必须同源：
+ * - 消费端 `topologyExt.buildSelectorManifestCore` 用
+ *   `kernel.hashCode(subShape, BREP_HASH_BOUND)` 回查 faceGroups/edgeGroups 里的 hash；
+ * - 生产端（本文件的 solidMesh / faceMesh / compoundMesh / wireframe）必须用**同一个**
+ *   `BREP_HASH_BOUND` 生成，否则查表恒 miss。
+ *
+ * GOTCHA（2026-10-01 实测修复）：本文件此前生产端用 1e9、消费端用 2147483647，
+ * 导致 brepkit 引擎下面行的 triStart/triCount 恒为 0（面积/法向随之丢失）。
+ */
+function fnv1a(basis, upperBound) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < basis.length; i++) {
+        h ^= basis.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return upperBound > 0 ? h % upperBound : h;
+}
 /** 面稳定指纹：解析曲面参数 + 面积 → FNV-1a → 取模上界（跨操作可追溯，与句柄无关）。 */
 function faceFingerprint(kernel, face, upperBound) {
     let params = '';
@@ -91,13 +154,45 @@ function faceFingerprint(kernel, face, upperBound) {
         area = Number(kernel.faceArea?.(face, 0.1) ?? 0);
     }
     catch { /* 查询失败用 0 */ }
-    const basis = `${params}|${area.toFixed(6)}`;
-    let h = 0x811c9dc5;
-    for (let i = 0; i < basis.length; i++) {
-        h ^= basis.charCodeAt(i);
-        h = Math.imul(h, 0x01000193) >>> 0;
+    return fnv1a(`${params}|${area.toFixed(6)}`, upperBound);
+}
+/**
+ * 边稳定指纹：曲线类型 + 参数区间 + 两端/中点采样 + 长度 → FNV-1a。
+ *
+ * 为什么不能用 `faceFingerprint`：它对边恒得同一个值（`getAnalyticSurfaceParams`
+ * 与 `faceArea` 对 edge 句柄都抛错）——旧实现在 box 上 12 条边 hash 全同，
+ * 使 `topologyExt` 的 edgeGroupByHash 只留最后一条折线（实测 2026-10-01）。
+ *
+ * 为什么不能只用端点：整圆（圆柱端盖）首末点重合，z 不同的两个圆会撞 —
+ * 故补 UV 中点采样。`getBoundingBox(edge)` 在 brepkit 上抛错，不可用。
+ */
+function edgeFingerprint(kernel, edge, upperBound) {
+    let curveType = '';
+    try {
+        curveType = String(kernel.getEdgeCurveType(edge) ?? '');
     }
-    return upperBound > 0 ? h % upperBound : h;
+    catch { /* 非边 */ }
+    let range = '';
+    let mid = '';
+    try {
+        // 方言：`getEdgeCurveParameters` 返回 **Float64Array**（如 [0, 10]），不是 JSON 字符串
+        // （见本文件头的返回值归一化说明）。曾误用 JSON.parse → 恒定抛错 → range/mid 恒空，
+        // 于是所有同类型同长度的边（box 的 12 条棱）挤成同一个指纹（2026-10-01 实测）。
+        const p = toNumArray(kernel.getEdgeCurveParameters(edge));
+        const first = p[0] ?? 0;
+        const last = p[1] ?? 0;
+        range = `${first.toFixed(9)},${last.toFixed(9)}`;
+        const midT = (first + last) / 2;
+        const sample = (t) => toNumArray(kernel.evaluateEdgeCurve(edge, t)).map((x) => x.toFixed(6)).join(',');
+        mid = `${sample(first)}|${sample(midT)}|${sample(last)}`;
+    }
+    catch { /* 采样失败 → 退化为类型 + 空几何 */ }
+    let length = 0;
+    try {
+        length = Number(kernel.edgeLength(edge) ?? 0);
+    }
+    catch { /* 长度不可用用 0 */ }
+    return fnv1a(`${curveType}|${range}|${mid}|${length.toFixed(6)}`, upperBound);
 }
 /** 面演化数据（BrepEvolutionData）：brepkit evolution JSON → hash 编码三元组。 */
 function mapEvolution(kernel, raw, resultHandle, inputFaceHashes, hashUpperBound) {
@@ -148,7 +243,18 @@ function mapEvolution(kernel, raw, resultHandle, inputFaceHashes, hashUpperBound
 }
 /** per-kernel 的 hash↔handle 登记表（fuseWithHistory 溯源对齐用）。 */
 const hashRegistry = new WeakMap();
-/** 三点外接圆（makeArcEdge 方言消化：occt 吃 3 点，brepkit 吃圆心+轴）。 */
+/**
+ * 三点外接圆（makeArcEdge 方言消化：occt 吃 3 点，brepkit 吃圆心+轴）。
+ *
+ * 圆心偏移取标准式 `d = ( |ab|²·(ac×n) + |ac|²·(n×ab) ) / (2·|n|²)`，`n = ab×ac`。
+ * GOTCHA（弧缺陷，2026-09-30 实证）：旧式 `( |ac|²·(ab×n) + |ab|²·(n×ac) ) / (2·|n|²)`
+ * 把两项的系数对调，等于整体取反——圆心落到弦的另一侧（实测 quarter arc 圆心 (20,0,0)
+ * 而非 (0,0,0)，三点不等距），brepkit 据此生成 333° 的补弧（弧长 58.195 而非 πr/2）。
+ * 判据是等距不变量 `|center−a| = |center−b| = |center−c|`。
+ *
+ * axis = n/|n| 即三点逆时针扫掠方向的右手法向；brepkit `makeCircleArc3d` 语义为
+ * "沿法向看从 start 逆时针到 end"，故该轴向同时正确表达 ccw 与 cw 弧。
+ */
 function circumcircle(a, b, c) {
     const abx = b.x - a.x, aby = b.y - a.y, abz = b.z - a.z;
     const acx = c.x - a.x, acy = c.y - a.y, acz = c.z - a.z;
@@ -160,16 +266,16 @@ function circumcircle(a, b, c) {
         fail('makeArcEdge: 3 points are collinear (no circumscribed circle)');
     const ab2 = abx * abx + aby * aby + abz * abz;
     const ac2 = acx * acx + acy * acy + acz * acz;
-    // center = a + ( ac2·(ab×n) + ab2·(n×ac) ) / (2·n²)
-    const abxnx = aby * nz - abz * ny, abxny = abz * nx - abx * nz, abxnz = abx * ny - aby * nx;
-    const nxacx = ny * acz - nz * acy, nxacy = nz * acx - nx * acz, nxacz = nx * acy - ny * acx;
+    // center = a + ( ab2·(ac×n) + ac2·(n×ab) ) / (2·n²)
+    const acxnx = acy * nz - acz * ny, acxny = acz * nx - acx * nz, acxnz = acx * ny - acy * nx;
+    const nxabx = ny * abz - nz * aby, nxaby = nz * abx - nx * abz, nxabz = nx * aby - ny * abx;
     const denom = 2 * n2;
     const len = Math.sqrt(n2);
     return {
         center: {
-            x: a.x + (ac2 * abxnx + ab2 * nxacx) / denom,
-            y: a.y + (ac2 * abxny + ab2 * nxacy) / denom,
-            z: a.z + (ac2 * abxnz + ab2 * nxacz) / denom,
+            x: a.x + (ab2 * acxnx + ac2 * nxabx) / denom,
+            y: a.y + (ab2 * acxny + ac2 * nxaby) / denom,
+            z: a.z + (ab2 * acxnz + ac2 * nxabz) / denom,
         },
         axis: { x: nx / len, y: ny / len, z: nz / len },
     };
@@ -192,6 +298,13 @@ function flattenPoints(points) {
  */
 export async function createBrepkitPrimitives() {
     const kernel = await initBrepkitWasm();
+    // GOTCHA（2026-10-01）：本函数此前每次调用都新建一套闭包（knownFaces/knownSolids/
+    // derivedFaces…）——即**新建一套句柄桥接层**。句柄号虽然对同一个 wasm 内核全局有效，
+    // 但桥接层侧的类型登记表不同：A 层枚举出的面句柄交给 B 层做 getSubShapes，会被当
+    // 实体走 tessellateSolidGrouped。BREP 引擎装配点与网格后端装配点都调本函数，必须
+    // 拿到**同一个**对象。故按内核实例 memo 化（disposeBrepkit 会清掉）。
+    if (memoizedPrimitives && memoizedKernel === kernel)
+        return memoizedPrimitives;
     liveKernel = kernel;
     let lastFallbackCount = 0;
     // 已知面句柄集合：getSubShapes(shape,'face') / makeRectangle / makeFace / buildTriFace
@@ -225,14 +338,45 @@ export async function createBrepkitPrimitives() {
     // （实测 box makeBox 返回 solid 2，撞 profile 早先的 face 2 → cloneShape 走 copyFace 崩溃）。
     // 建 solid 时必须从 knownFaces/knownWires/knownEdges/derivedFaces 抹掉该编号，让默认 solid 路径生效。
     // derivedFaces 也必须清：getSubShapes(solid,'edge') 会查 derivedFaces.has(s) 误走 getFaceEdges。
+    // GOTCHA（2026-10-01 实测）：`derivedFaces` 是**全局**面句柄号集合，枚举 solid A 的面会把
+    // 面号 0..N 写进去；此后对**裸句柄号恰好相同的另一个 solid**做 getSubShapes(...,'edge')
+    // 时，`derivedFaces.has(s)` 为真 → isFaceLike 误判 → 走 getFaceEdges 只拿到一张面的 4 条边
+    // （实测 box：12 条边变 4 条）。故必须显式登记 solid 句柄：实体永远不是 face-like。
+    const knownSolids = new Set();
     const markSolid = (h) => {
         knownFaces.delete(h);
         knownWires.delete(h);
         knownEdges.delete(h);
         knownCompounds.delete(h);
         derivedFaces.delete(h);
+        knownSolids.add(h);
         return h;
     };
+    /** 实体数组批量登记（阵列族返回多个实体）。 */
+    const markSolids = (list) => list.map(markSolid);
+    /**
+     * 句柄类型解析：**标签优先**，无标签时退回已知集合（历史行为）。
+     *
+     * 标签是权威来源——集合的 key 是**裸句柄号**，face 3 与 edge 3 会共存于不同集合，
+     * 靠集合无法区分。故有标签（非 0）时直接用标签，集合里的同名条目一律忽略；
+     * 只有无标签句柄（实体/compound/构造 API 外传入）才走集合分发，行为与加标签前一致。
+     */
+    const resolveKind = (shape, s) => {
+        const tagged = kindOf(shape);
+        if (tagged !== KIND_SOLID)
+            return tagged;
+        // 已登记的实体优先：knownFaces/knownEdges 的 key 是裸句柄号，历史登记（如
+        // getSubShapes(face,'edge') 写 knownEdges）与后来新建的 solid 号同号时会把实体判成边。
+        if (knownSolids.has(s))
+            return KIND_SOLID;
+        if (knownFaces.has(s))
+            return KIND_FACE;
+        if (knownWires.has(s))
+            return KIND_WIRE;
+        if (knownEdges.has(s))
+            return KIND_EDGE;
+        return KIND_SOLID;
+    };
     const readFallback = () => {
         try {
             return typeof kernel.meshFallbackCount === 'function' ? Number(kernel.meshFallbackCount()) : 0;
@@ -264,7 +408,7 @@ export async function createBrepkitPrimitives() {
             indices: new Uint32Array(indices),
             vertexCount: positions.length / 3,
             triangleCount: triCount,
-            faceGroups: new Int32Array([0, triCount, faceFingerprint(kernel, f, 1e9)]),
+            faceGroups: new Int32Array([0, indices.length, faceFingerprint(kernel, f, BREP_HASH_BOUND)]),
             faceCount: 1,
         };
     };
@@ -304,21 +448,24 @@ export async function createBrepkitPrimitives() {
     const solidMesh = (solid, deflection, angular) => {
         const raw = kernel.tessellateSolidGrouped(solid, deflection, angular);
         const m = JSON.parse(raw);
-        // faceOffsets 形如 [start0, start1, ..., totalEnd]：以「索引数组单位」计的每面偏移（2026-09-19 实测），
-        // 除以 3 换算为 faijs 契约的三角形单位 [triStart, triCount, faceHash]
+        // faceOffsets 形如 [start0, start1, ..., totalEnd]：以「索引数组单位」计的每面偏移
+        // （2026-09-19 实测）。**L1 契约的 faceGroups 就是索引单位**（与 OCCT 一致，
+        // 见 brep/engine/types.BrepMeshResult）——此处原样透传，不得再除以 3。
+        // GOTCHA（2026-10-01）：旧实现除以 3 换成三角形单位，与 topologyExt 的 `/3`
+        // 叠加 → 面行区间缩小 3 倍。
         const fo = m.faceOffsets;
         const faceCount = Math.max(0, fo.length - 1);
         const faceHashes = [];
         try {
             const faces = arr(kernel.getSolidFaces(solid));
             for (let i = 0; i < faceCount && i < faces.length; i++)
-                faceHashes.push(faceFingerprint(kernel, faces[i], 1e9));
+                faceHashes.push(faceFingerprint(kernel, faces[i], BREP_HASH_BOUND));
         }
         catch { /* 非实体：faceHash 置 0 */ }
         const faceGroups = new Int32Array(faceCount * 3);
         for (let i = 0; i < faceCount; i++) {
-            faceGroups[i * 3] = fo[i] / 3;
-            faceGroups[i * 3 + 1] = (fo[i + 1] - fo[i]) / 3;
+            faceGroups[i * 3] = fo[i];
+            faceGroups[i * 3 + 1] = fo[i + 1] - fo[i];
             faceGroups[i * 3 + 2] = faceHashes[i] ?? 0;
         }
         return {
@@ -337,7 +484,7 @@ export async function createBrepkitPrimitives() {
         const normals = [];
         const indices = [];
         const faceGroups = [];
-        let triOffset = 0;
+        let indexOffset = 0;
         for (const c of children) {
             let sub;
             if (knownFaces.has(c)) {
@@ -362,10 +509,10 @@ export async function createBrepkitPrimitives() {
                 indices.push(sub.indices[i] + vOffset);
             if (sub.faceGroups) {
                 for (let i = 0; i < sub.faceGroups.length; i += 3) {
-                    faceGroups.push((sub.faceGroups[i] ?? 0) + triOffset, sub.faceGroups[i + 1] ?? 0, sub.faceGroups[i + 2] ?? 0);
+                    faceGroups.push((sub.faceGroups[i] ?? 0) + indexOffset, sub.faceGroups[i + 1] ?? 0, sub.faceGroups[i + 2] ?? 0);
                 }
             }
-            triOffset += sub.triangleCount;
+            indexOffset += sub.indices.length;
         }
         return {
             positions: new Float32Array(positions),
@@ -382,13 +529,15 @@ export async function createBrepkitPrimitives() {
     // 传错即崩溃；transformSolid/transformFace/transformWire 均为「原地修改」void。
     // place/translate 等会作用在 profile 产出的 face 上（sew 用例 place 两张 face），
     // 故必须按 knownFaces/knownWires 分发，不能一律 copySolid。
-    const cloneShape = (shape) => {
-        if (knownFaces.has(shape)) {
+    // kind 为调用方句柄的类型标签（0 = solid）：句柄标签是**权威判定**，knownFaces/knownWires
+    // 只作无标签时的兜底（枚举出的面句柄只进 derivedFaces，不在 knownFaces 里）。
+    const cloneShape = (shape, kind = KIND_SOLID) => {
+        if (kind === KIND_FACE || knownFaces.has(shape)) {
             const c = kernel.copyFace(shape);
             knownFaces.add(c);
             return c;
         }
-        if (knownWires.has(shape)) {
+        if (kind === KIND_WIRE || knownWires.has(shape)) {
             const c = kernel.copyWire(shape);
             knownWires.add(c);
             return c;
@@ -396,12 +545,12 @@ export async function createBrepkitPrimitives() {
         return markSolid(kernel.copySolid(shape));
     };
     /** 深拷贝 + 原地仿射变换（matrix 已经 toKernelMatrix 归一为 16 元素 4×4）。 */
-    const cloneAndTransform = (shape, matrix16) => {
-        const c = cloneShape(shape);
+    const cloneAndTransform = (shape, matrix16, kind = KIND_SOLID) => {
+        const c = cloneShape(shape, kind);
         const m = Float64Array.from(matrix16);
-        if (knownFaces.has(c))
+        if (kind === KIND_FACE || knownFaces.has(c))
             kernel.transformFace(c, m);
-        else if (knownWires.has(c))
+        else if (kind === KIND_WIRE || knownWires.has(c))
             kernel.transformWire(c, m);
         else
             kernel.transformSolid(c, m);
@@ -435,11 +584,11 @@ export async function createBrepkitPrimitives() {
         makeRectangle(width, height) {
             const f = kernel.makeRectangle(width, height);
             knownFaces.add(f);
-            return asHandle(f);
+            return asFace(f);
         },
         makeEllipsoid(rx, ry, rz) { return asHandle(markSolid(kernel.makeEllipsoid(rx, ry, rz))); },
         makeTorus(majorRadius, minorRadius) { return asHandle(markSolid(kernel.makeTorus(majorRadius, minorRadius, 64))); },
-        makeVertex(x, y, z) { return asHandle(kernel.makeVertex(x, y, z)); },
+        makeVertex(x, y, z) { return asVertex(kernel.makeVertex(x, y, z)); },
         // ── 造型运算 ──
         extrude(shape, dx, dy, dz) {
             // 方言归一（§3.6-1）：L1 口径是挤出向量；brepkit 原生吃 (face, dir, distance)。
@@ -461,7 +610,7 @@ export async function createBrepkitPrimitives() {
             return asHandle(markSolid(kernel.revolve(s, center.x, center.y, center.z, direction.x, direction.y, direction.z, angleDeg)));
         },
         sew(shapesList, tolerance) {
-            return asHandle(kernel.sewFaces(Uint32Array.from(shapesList.map(asNum)), tolerance ?? 1e-6));
+            return asHandle(markSolid(kernel.sewFaces(Uint32Array.from(shapesList.map(asNum)), tolerance ?? 1e-6)));
         },
         sewAndSolidify(faces, _tolerance) {
             // brepkit 的 makeSolid 即「缝合并固化成实体」（sewFaces + 建 solid）。
@@ -469,10 +618,10 @@ export async function createBrepkitPrimitives() {
         },
         shell(solid, facesToRemove, thickness, _tolerance) {
             // brepkit 参数序 (solid, thickness, open_faces)；tolerance 内核固定。
-            return asHandle(kernel.shell(asNum(solid), thickness, Uint32Array.from(facesToRemove.map(asNum))));
+            return asHandle(markSolid(kernel.shell(asNum(solid), thickness, Uint32Array.from(facesToRemove.map(asNum)))));
         },
         hullFromPoints(points, _tolerance) {
-            return asHandle(kernel.convexHull(flattenPoints(points)));
+            return asHandle(markSolid(kernel.convexHull(flattenPoints(points))));
         },
         // ── 布尔与分割 ──
         fuse(a, b) { return asHandle(markSolid(trackFallback(kernel.fuse(asNum(a), asNum(b))))); },
@@ -481,7 +630,7 @@ export async function createBrepkitPrimitives() {
             // brepkit 无 `common` 原生名；交集语义由 `intersect` 承担（method-map: dialect）。
             return asHandle(markSolid(trackFallback(kernel.intersect(asNum(a), asNum(b)))));
         },
-        intersect(a, b) { return asHandle(trackFallback(kernel.intersect(asNum(a), asNum(b)))); },
+        intersect(a, b) { return asHandle(markSolid(trackFallback(kernel.intersect(asNum(a), asNum(b))))); },
         fuseAll(shapesList) {
             return asHandle(markSolid(trackFallback(kernel.fuseAll(Int32Array.from(shapesList.map(asNum))))));
         },
@@ -515,24 +664,24 @@ export async function createBrepkitPrimitives() {
         },
         // ── 倒角与圆角（Q7：只对齐等距 + 距角两种粒度）──
         chamfer(solid, edges, distance) {
-            return asHandle(trackFallback(kernel.chamfer(asNum(solid), Uint32Array.from(edges.map(asNum)), distance)));
+            return asHandle(markSolid(trackFallback(kernel.chamfer(asNum(solid), Uint32Array.from(edges.map(asNum)), distance))));
         },
         chamferDistAngle(solid, edges, distance, angleDeg) {
             // 方言映射：L1 chamferDistAngle ↔ brepkit chamferDistanceAngle。
             // ⚠️ 单位方言：L1 口径是**度**（`AddDA(distance, angleDeg, E, F)`），brepkit 内核吃**弧度**
             // （2026-09-25 实证：传 45 抛 "angle must be less than π/2"；传 π/4 正常倒角）。
             const angleRad = (angleDeg * Math.PI) / 180;
-            return asHandle(trackFallback(kernel.chamferDistanceAngle(asNum(solid), Uint32Array.from(edges.map(asNum)), distance, angleRad)));
+            return asHandle(markSolid(trackFallback(kernel.chamferDistanceAngle(asNum(solid), Uint32Array.from(edges.map(asNum)), distance, angleRad))));
         },
         fillet(solid, edges, radius) {
-            return asHandle(trackFallback(kernel.fillet(asNum(solid), Uint32Array.from(edges.map(asNum)), radius)));
+            return asHandle(markSolid(trackFallback(kernel.fillet(asNum(solid), Uint32Array.from(edges.map(asNum)), radius))));
         },
         filletVariable(solid, edge, startRadius, endRadius) {
             // 方言映射：L1 filletVariable(solid, edge, startRadius, endRadius)（单边变半径）
             // ↔ brepkit filletVariable(solid, json) 吃**序列** `[{edge, radius1, radius2}, ...]`。
             // ⚠️ 直接传 4 个位置参数会触发 wasm memory out of bounds（2026-09-25 实证）。
             const spec = JSON.stringify([{ edge: asNum(edge), radius1: startRadius, radius2: endRadius }]);
-            return asHandle(trackFallback(kernel.filletVariable(asNum(solid), spec)));
+            return asHandle(markSolid(trackFallback(kernel.filletVariable(asNum(solid), spec))));
         },
         filletWithHistory(solid, edges, radius, inputFaceHashes, hashUpperBound) {
             const raw = kernel.filletWithEvolution(asNum(solid), Int32Array.from(edges.map(asNum)), radius);
@@ -545,61 +694,62 @@ export async function createBrepkitPrimitives() {
         // brepkit transformSolid 吃 4×4 行主序 16 元素。所有 transformSolid 调用一律经
         // toKernelMatrix 归一（下方唯一转换点），禁止直出 16 元素旁路。
         translate(shape, dx, dy, dz) {
-            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(translationMatrix(dx, dy, dz))));
+            return withKind(kindOf(shape), cloneAndTransform(asNum(shape), toKernelMatrix(translationMatrix(dx, dy, dz)), kindOf(shape)));
         },
         scale(shape, center, factor) {
-            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(scaleMatrix(center, factor))));
+            return withKind(kindOf(shape), cloneAndTransform(asNum(shape), toKernelMatrix(scaleMatrix(center, factor)), kindOf(shape)));
         },
         transform(shape, matrix) {
-            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(matrix)));
+            return withKind(kindOf(shape), cloneAndTransform(asNum(shape), toKernelMatrix(matrix), kindOf(shape)));
         },
         located(shape, matrix) {
-            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(matrix)));
+            return withKind(kindOf(shape), cloneAndTransform(asNum(shape), toKernelMatrix(matrix), kindOf(shape)));
         },
         locate(shape, matrix) {
-            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(matrix)));
+            return withKind(kindOf(shape), cloneAndTransform(asNum(shape), toKernelMatrix(matrix), kindOf(shape)));
         },
         generalTransform(shape, matrix) {
-            return asHandle(cloneAndTransform(asNum(shape), toKernelMatrix(matrix)));
+            return withKind(kindOf(shape), cloneAndTransform(asNum(shape), toKernelMatrix(matrix), kindOf(shape)));
         },
-        copy(shape) { return asHandle(cloneShape(asNum(shape))); },
-        copyShape(shape) { return asHandle(cloneShape(asNum(shape))); },
+        copy(shape) { return withKind(kindOf(shape), cloneShape(asNum(shape), kindOf(shape))); },
+        copyShape(shape) { return withKind(kindOf(shape), cloneShape(asNum(shape), kindOf(shape))); },
         composeTransform(m1, m2) {
             // 方言：L1 是 3×4 行主序 12 元素；brepkit composeTransforms 吃/回 4×4 16 元素。
             const r = kernel.composeTransforms(Float64Array.from(toKernelMatrix(m1)), Float64Array.from(toKernelMatrix(m2)));
             return Array.from(r).slice(0, 12);
         },
         mirror(shape, point, normal) {
-            return asHandle(kernel.mirror(asNum(shape), point.x, point.y, point.z, normal.x, normal.y, normal.z));
+            return withKind(kindOf(shape), kernel.mirror(asNum(shape), point.x, point.y, point.z, normal.x, normal.y, normal.z));
         },
         // ── 阵列 ──
         // brepkit wasm 的 pattern 内核函数都返回 compound（含全部副本）→ 经 getCompoundSolids 拆成数组。
         linearPattern(shape, direction, spacing, count) {
             const compound = kernel.linearPattern(asNum(shape), direction.x, direction.y, direction.z, spacing, count);
-            return arr(kernel.getCompoundSolids(compound)).map(asHandle);
+            // 阵列内核返回 compound（原始句柄）→ 拆成实体数组并逐个登记（见 markSolid GOTCHA）。
+            return markSolids(arr(kernel.getCompoundSolids(compound))).map(asHandle);
         },
         circularPattern(shape, _center, axis, _angleStep, count) {
             // ⚠️ brepkit wasm circularPattern(solid, ax, ay, az, count) 无 center/angle 参数：
             // 固定整圆均分（每份 360°/count）。fullAngle=360 时与 vendored/occt 语义一致；
             // 其它角度跨度无法表达（语义限制记录于此，parity 测试用整圆）。
             const compound = kernel.circularPattern(asNum(shape), axis.x, axis.y, axis.z, count);
-            return arr(kernel.getCompoundSolids(compound)).map(asHandle);
+            return markSolids(arr(kernel.getCompoundSolids(compound))).map(asHandle);
         },
         gridPattern(shape, directionX, directionY, spacingX, spacingY, countX, countY) {
-            return asHandle(kernel.gridPattern(asNum(shape), directionX.x, directionX.y, directionX.z, directionY.x, directionY.y, directionY.z, spacingX, spacingY, countX, countY));
+            return asHandle(markSolid(kernel.gridPattern(asNum(shape), directionX.x, directionX.y, directionX.z, directionY.x, directionY.y, directionY.z, spacingX, spacingY, countX, countY)));
         },
         // ── 曲线构造 ──
         makeLineEdge(start, end) {
             const e = kernel.makeLineEdge(start.x, start.y, start.z, end.x, end.y, end.z);
             knownEdges.add(e);
-            return asHandle(e);
+            return asEdge(e);
         },
         makeArcEdge(start, mid, end) {
             // 方言消化：occt 吃 3 点；brepkit makeCircleArc3d 吃 (start,end,center,axis)。
             const { center, axis } = circumcircle(start, mid, end);
             const e = kernel.makeCircleArc3d(start.x, start.y, start.z, end.x, end.y, end.z, center.x, center.y, center.z, axis.x, axis.y, axis.z);
             knownEdges.add(e);
-            return asHandle(e);
+            return asEdge(e);
         },
         makeBezierEdge(controlPoints) {
             // 方言消化：L1 吃控制点（Bezier）；brepkit 原生 makeNurbsEdge 吃
@@ -617,34 +767,59 @@ export async function createBrepkitPrimitives() {
             const last = controlPoints[n - 1];
             const e = kernel.makeNurbsEdge(first.x, first.y, first.z, last.x, last.y, last.z, degree, knots, flattenPoints(controlPoints), weights);
             knownEdges.add(e);
-            return asHandle(e);
+            return asEdge(e);
+        },
+        makeBSplineEdge(poles, weights, knots, multiplicities, degree, periodic = false) {
+            // 方言消化：L1 吃 occt 形态 (poles, weights, knots, multiplicities, degree),
+            // brepkit makeNurbsEdge 吃 (start,end,degree, **展开后** knots, control_points, weights)。
+            // 两侧 knots 的表示不同：occt 给「去重值 + 多重度」两个平行数组，brepkit 要
+            // 逐项重复后的整条节点向量（与 makeBezierEdge 里手工铺 [0]×n+[1]×n 同一口径）。
+            const controlPoints = [];
+            for (let i = 0; i + 2 < poles.length; i += 3) {
+                controlPoints.push({ x: poles[i], y: poles[i + 1], z: poles[i + 2] });
+            }
+            const n = controlPoints.length;
+            if (n < 2)
+                fail('makeBSplineEdge: need at least 2 poles');
+            const expanded = [];
+            for (let i = 0; i < knots.length; i++) {
+                const rep = multiplicities[i] ?? 1;
+                for (let j = 0; j < rep; j++)
+                    expanded.push(knots[i]);
+            }
+            const first = controlPoints[0];
+            const last = controlPoints[n - 1];
+            const e = kernel.makeNurbsEdge(first.x, first.y, first.z, last.x, last.y, last.z, degree, Float64Array.from(expanded), flattenPoints(controlPoints), weights.length === n ? Float64Array.from(weights) : new Float64Array(n).fill(1));
+            void periodic;
+            knownEdges.add(e);
+            return asEdge(e);
         },
         makeCircleEdge(center, normal, radius) {
             const e = kernel.makeCircleEdge(center.x, center.y, center.z, normal.x, normal.y, normal.z, radius);
             knownEdges.add(e);
-            return asHandle(e);
+            return asEdge(e);
         },
         // ── 拓扑构造 ──
         makeWire(edges) {
             const w = kernel.makeWire(Int32Array.from(edges.map(asNum)), false);
             knownWires.add(w);
-            return asHandle(w);
+            return asWire(w);
         },
         makeFace(wire) {
             const f = kernel.makeFaceFromWire(asNum(wire));
             knownFaces.add(f);
-            return asHandle(f);
+            return asFace(f);
         },
         makeCompound(shapesList) {
             const kids = arr(shapesList.map(asNum));
             // GOTCHA（2026-09-26）：brepkit makeCompound 只接受 **solid** 句柄——把 face/wire
             // （sectionByPlane 截面面组）塞进去即抛 "invalid solid handle"。非实体子句柄时
-            // 不调内核，改用高段虚拟句柄（0x80000000+），仅靠 knownCompounds 表分发
+            // 不调内核，改用高段虚拟句柄（0x20000000+，避开类型标签 bit26..28），仅靠 knownCompounds 表分发
             // meshShape/wireframe/getSubShapes/getBoundingBox，不触达内核。
             const hasNonSolid = kids.some((k) => knownFaces.has(k) || knownWires.has(k) || knownEdges.has(k) || knownCompounds.has(k));
             if (hasNonSolid) {
                 virtualCompoundCounter++;
-                const v = 0x80000000 + virtualCompoundCounter;
+                const v = 0x20000000 + virtualCompoundCounter;
                 knownCompounds.set(v, kids);
                 return asHandle(v);
             }
@@ -657,25 +832,26 @@ export async function createBrepkitPrimitives() {
             // 否则 profile(op) 带孔面送 meshShape 会落到 solid 路径崩溃。
             const f = kernel.addHolesToFace(asNum(face), Int32Array.from(holeWires.map(asNum)));
             knownFaces.add(f);
-            return asHandle(f);
+            return asFace(f);
         },
         buildTriFace(a, b, c) {
             const f = kernel.makePolygon(flattenPoints([a, b, c]));
             knownFaces.add(f);
-            return asHandle(f);
+            return asFace(f);
         },
         // ── 三角化（BREP→mesh 唯一出口） ──
         meshShape(shape, options) {
             const deflection = options?.linearDeflection ?? DEFAULT_LINEAR_DEFLECTION.as(mm);
             const angular = options?.angularDeflection ?? 0.5;
             const s = asNum(shape);
-            // 非实体句柄按已知集合静态分发（见文件头 GOTCHA：brepkit 无 shape-type 分类 API）。
+            // 非实体句柄按类型静态分发（标签优先，见文件头 GOTCHA：brepkit 无 shape-type 分类 API）。
             // 顺序：face → wire → edge → compound → solid。实体创建不入任何集合，天然落 solid 路径。
-            if (knownFaces.has(s))
+            const kind = resolveKind(shape, s);
+            if (kind === KIND_FACE)
                 return faceMesh(s, deflection, angular);
-            if (knownWires.has(s))
+            if (kind === KIND_WIRE)
                 return wireMesh(s, deflection);
-            if (knownEdges.has(s))
+            if (kind === KIND_EDGE)
                 return edgesToLineMesh([s], deflection);
             const compoundChildren = knownCompounds.get(s);
             if (compoundChildren)
@@ -690,11 +866,12 @@ export async function createBrepkitPrimitives() {
             // 产物调 wireframe(...)，传入非实体句柄即抛 "invalid solid handle"。按已知集合分发：
             // face -> getFaceEdges；wire -> getWireEdges；edge -> [self]；否则 solid 走 meshEdgesAll。
             let edgeHandles = null;
-            if (knownFaces.has(s))
+            const kind = resolveKind(shape, s);
+            if (kind === KIND_FACE)
                 edgeHandles = arr(kernel.getFaceEdges(s));
-            else if (knownWires.has(s))
+            else if (kind === KIND_WIRE)
                 edgeHandles = arr(kernel.getWireEdges(s));
-            else if (knownEdges.has(s))
+            else if (kind === KIND_EDGE)
                 edgeHandles = [s];
             else if (knownCompounds.has(s)) {
                 // compound（sectionByPlane 面组）：逐子面收集边。
@@ -711,20 +888,22 @@ export async function createBrepkitPrimitives() {
             if (edgeHandles) {
                 const nPts = Math.max(12, Math.round(4 / Math.max(d, 0.01)));
                 const positions = [];
+                // offsets 为**浮点单位**（L1 契约：edgeGroups = [pointStart_float, pointCount_float, hash]）
                 const offsets = [0];
                 for (const e of edgeHandles) {
                     const pts = arr(kernel.tessellateEdge(e, nPts));
                     for (const p of pts)
                         positions.push(p);
-                    offsets.push(positions.length / 3);
+                    offsets.push(positions.length);
                 }
                 const edgeGroups = new Int32Array(edgeHandles.length * 3);
                 for (let i = 0; i < edgeHandles.length; i++) {
                     edgeGroups[i * 3] = offsets[i] ?? 0;
-                    edgeGroups[i * 3 + 1] = (offsets[i + 1] ?? positions.length / 3) - (offsets[i] ?? 0);
-                    edgeGroups[i * 3 + 2] = i;
+                    edgeGroups[i * 3 + 1] = (offsets[i + 1] ?? positions.length) - (offsets[i] ?? 0);
+                    // hash 必须与 hashCode(edge, BREP_HASH_BOUND) 同源，否则 topologyExt 查不到折线。
+                    edgeGroups[i * 3 + 2] = edgeFingerprint(kernel, edgeHandles[i], BREP_HASH_BOUND);
                 }
-                return { points: new Float32Array(positions), edgeGroups, pointCount: positions.length / 3, edgeCount: edgeHandles.length };
+                return { points: new Float32Array(positions), edgeGroups, pointCount: positions.length, edgeCount: edgeHandles.length };
             }
             // solid（或未登记句柄）：走原 meshEdgesAll 路径。
             // JsEdgeLines：edgeCount/offsets/positions 均为属性（offsets/positions 为 TypedArray，2026-09-19 实测）
@@ -732,13 +911,25 @@ export async function createBrepkitPrimitives() {
             const edgeCount = Number(me.edgeCount);
             const offsets = arr(me.offsets);
             const positions = arr(me.positions);
+            // hash：meshEdgesAll 与 getSolidEdges 同序（同一次遍历），据此回填真实边指纹；
+            // 取不到（数量不符）时退化为序号——此时 topologyExt 查不到折线，曲面边走
+            // 曲线采样兜底（功能可用，只是丢掉内核线框数据）。
+            let solidEdges = null;
+            try {
+                const es = arr(kernel.getSolidEdges(s));
+                if (es.length === edgeCount)
+                    solidEdges = es;
+            }
+            catch { /* 非实体 */ }
             const edgeGroups = new Int32Array(edgeCount * 3);
             for (let i = 0; i < edgeCount; i++) {
                 const start = offsets[i] ?? 0;
-                const count = (offsets[i + 1] ?? positions.length / 3) - start;
+                const count = (offsets[i + 1] ?? positions.length) - start;
                 edgeGroups[i * 3] = start;
                 edgeGroups[i * 3 + 1] = count;
-                edgeGroups[i * 3 + 2] = i; // 线框 hash 用序号（wireframe 不参与跨操作溯源）
+                edgeGroups[i * 3 + 2] = solidEdges
+                    ? edgeFingerprint(kernel, solidEdges[i], BREP_HASH_BOUND)
+                    : i;
             }
             return { points: new Float32Array(positions), edgeGroups, pointCount: positions.length, edgeCount };
         },
@@ -751,49 +942,104 @@ export async function createBrepkitPrimitives() {
         // edge/vertex 查询时按句柄是否在 knownFaces 里分发到 face 级或 solid 级 API。
         getSubShapes(shape, type) {
             const s = asNum(shape);
+            // 出口一律按 **type 参数**打类型标签（`type` 就是调用方声明的子形类型，是权威来源；
+            // 不用内核反查——brepkit 无法反查类型，见文件头句柄桥接 GOTCHA）。
+            const tag = (list) => {
+                switch (type) {
+                    case 'face': return list.map(asFace);
+                    case 'edge': return list.map(asEdge);
+                    case 'vertex': return list.map(asVertex);
+                    case 'wire': return list.map(asWire);
+                    default: return list.map(asHandle);
+                }
+            };
+            // ── A. 有类型标签：按标签分发，**不登记 knownEdges** ──
+            // GOTCHA（2026-10-01 实测回归）：历史分支里 `es.forEach(e => knownEdges.add(e))` 会把
+            // 面/线的边号写进 knownEdges，而 knownEdges 的 key 是**裸句柄号**、会与后来新建的
+            // solid 号相撞 → resolveKind 把实体判成边 → getBoundingBox 返回边的退化 bbox
+            // （实测 8 个 op 的 AABB 全错）。标签句柄自带类型，登记已无必要，故这里一律不登记。
+            const tagged = kindOf(shape);
+            if (tagged === KIND_FACE) {
+                if (type === 'face')
+                    return [asFace(s)];
+                if (type === 'edge')
+                    return tag(arr(kernel.getFaceEdges(s)));
+                if (type === 'vertex')
+                    return tag(arr(kernel.getFaceVertices(s)));
+                return [];
+            }
+            if (tagged === KIND_WIRE) {
+                if (type === 'edge')
+                    return tag(arr(kernel.getWireEdges(s)));
+                return [];
+            }
+            if (tagged === KIND_EDGE) {
+                // input is itself an edge (wire.ts smooth path: interpolatePoints returns edge)
+                if (type === 'edge')
+                    return [asEdge(s)];
+                return [];
+            }
+            // ── B. 无标签：逐字沿用历史集合分发（含 knownEdges 登记），行为与加标签前一致 ──
             // GOTCHA（2026-09-26 非实体句柄修复）：buildTopologyFromMesh 会对**面产物**
             // 调 getSubShapes(face,'face')。brepkit 的 getSolidFaces/getShellFaces 是 solid-only，
             // 对面句柄一个抛 "invalid solid handle"、catch 里再抛 "invalid shell handle"——
-            // 两跳都不被捕获即崩溃。brepkit 无 shape-type 分类 API，必须靠已知集合先分发：
-            // 输入本身就是 knownFaces 里的一张面时，'face' 返回 [s]，edge/vertex 走 face 级 API。
+            // 两跳都不被捕获即崩溃。无标签时靠已知集合先分发。
             if (knownFaces.has(s)) {
                 if (type === 'face')
-                    return [asHandle(s)];
+                    return [asFace(s)];
                 if (type === 'edge') {
                     const es = arr(kernel.getFaceEdges(s));
                     es.forEach((e) => knownEdges.add(e));
-                    return es.map(asHandle);
+                    return tag(es);
                 }
                 if (type === 'vertex')
-                    return arr(kernel.getFaceVertices(s)).map(asHandle);
+                    return tag(arr(kernel.getFaceVertices(s)));
                 return [];
             }
             if (knownWires.has(s)) {
                 if (type === 'edge') {
                     const es = arr(kernel.getWireEdges(s));
                     es.forEach((e) => knownEdges.add(e));
-                    return es.map(asHandle);
+                    return tag(es);
                 }
                 return [];
             }
             if (knownEdges.has(s)) {
-                // input is itself an edge (wire.ts smooth path: interpolatePoints returns edge)
                 if (type === 'edge')
-                    return [asHandle(s)];
+                    return [asEdge(s)];
                 return [];
             }
             const compKids = knownCompounds.get(s);
             if (compKids) {
                 // compound（sectionByPlane 面组 / makeCompound 多实体 / importStep 多实体）：
-                // 'face' 返回子面，'solid' 返回子实体，其余空。
+                // 'face' 返回子面，'solid' 返回子实体，'edge' 返回各子句柄的边，其余空。
                 if (type === 'face')
-                    return compKids.filter((k) => knownFaces.has(k)).map(asHandle);
+                    return tag(compKids.filter((k) => knownFaces.has(k)));
                 if (type === 'solid')
-                    return compKids.filter((k) => !knownFaces.has(k) && !knownWires.has(k) && !knownEdges.has(k)).map(asHandle);
+                    return tag(compKids.filter((k) => !knownFaces.has(k) && !knownWires.has(k) && !knownEdges.has(k)));
+                if (type === 'edge') {
+                    // 2026-10-02 补：此前 compound 的边查询落到 `return []`，会让归一化后的
+                    // getLength(compound) 静默变 0。按子句柄的已知类型分发，与 occt 的
+                    // getSubShapes(compound,'edge')（返回全部子边）对齐。
+                    const out = [];
+                    for (const kid of compKids) {
+                        if (knownFaces.has(kid))
+                            out.push(...arr(kernel.getFaceEdges(kid)));
+                        else if (knownWires.has(kid))
+                            out.push(...arr(kernel.getWireEdges(kid)));
+                        else if (knownEdges.has(kid))
+                            out.push(kid);
+                        else
+                            out.push(...arr(kernel.getSolidEdges(kid)));
+                    }
+                    return tag(out);
+                }
                 return [];
             }
             let list;
-            const isFaceLike = knownFaces.has(s) || derivedFaces.has(s);
+            // 实体句柄（knownSolids）永远不是 face-like——`derivedFaces` 只装「枚举出来的面号」，
+            // 与 solid 号共用一个裸数字空间，不排除会造成误判（见 knownSolids 注释）。
+            const isFaceLike = knownFaces.has(s) || (derivedFaces.has(s) && !knownSolids.has(s));
             if (type === 'face') {
                 // 输入可能是 solid 或 shell。枚举到的子面登记到 derivedFaces（不进 knownFaces，
                 // 避免与 solid 句柄撞号——见 derivedFaces 注释）。
@@ -831,18 +1077,19 @@ export async function createBrepkitPrimitives() {
             else {
                 fail(`getSubShapes(${type}): unsupported sub-shape type`);
             }
-            return list.map(asHandle);
+            return tag(list);
         },
         subShapeHashes(shape, type, hashUpperBound) {
             if (type !== 'face')
                 fail(`subShapeHashes(${type}): only 'face' is supported by brepkit`);
             const s = asNum(shape);
             // GOTCHA：buildTopologyFromMesh 会对面产物调 subShapeHashes(face,'face')；
-            // getSolidFaces 是 solid-only，对面句柄崩溃。输入本身是已知面时，哈希即其自身指纹。
-            if (knownFaces.has(s))
+            // getSolidFaces 是 solid-only，对面句柄崩溃。输入本身是面时，哈希即其自身指纹。
+            const kind = resolveKind(shape, s);
+            if (kind === KIND_FACE)
                 return [faceFingerprint(kernel, s, hashUpperBound)];
             // wire/edge 无面；compound（sectionByPlane 面组）的子句柄即面。
-            if (knownWires.has(s) || knownEdges.has(s))
+            if (kind === KIND_WIRE || kind === KIND_EDGE)
                 return [];
             const compKids = knownCompounds.get(s);
             if (compKids) {
@@ -858,9 +1105,25 @@ export async function createBrepkitPrimitives() {
             return hashes;
         },
         hashCode(shape, upperBound) {
-            return faceFingerprint(kernel, asNum(shape), upperBound);
+            // 类型由句柄标签决定（见文件头句柄桥接 GOTCHA）：brepkit 无法反查句柄类型，
+            // 而面指纹与边指纹必须落在**互不相交**的取值域，否则 edgeGroups 的 hash 会
+            // 命中面的指纹（实测：box 的 edge 0..5 句柄号与 face 0..5 相同）。
+            // 生产端（faceMesh/solidMesh/compoundMesh → faceFingerprint；wireframe →
+            // edgeFingerprint）与消费端（本函数）用同一组函数、同一个上界，查表才命中。
+            const raw = asNum(shape);
+            return kindOf(shape) === KIND_EDGE
+                ? edgeFingerprint(kernel, raw, upperBound)
+                : faceFingerprint(kernel, raw, upperBound);
+        },
+        isSame(a, b) {
+            // 裸句柄号相同还不够：brepkit 的 face 3 与 edge 3 是**两个不同的形**。
+            // 两侧都带标签时必须同类型；任一侧无标签（历史调用方）时退回纯数字比较，
+            // 保证加标签不改变既有行为。
+            if (asNum(a) !== asNum(b))
+                return false;
+            const ka = kindOf(a), kb = kindOf(b);
+            return ka === kb || ka === KIND_SOLID || kb === KIND_SOLID;
         },
-        isSame(a, b) { return asNum(a) === asNum(b); },
         isSolid(shape) {
             try {
                 return arr(kernel.getSolidFaces(asNum(shape))).length > 0;
@@ -892,10 +1155,10 @@ export async function createBrepkitPrimitives() {
             return kernel.edgeToFaceMap(asNum(shape));
         },
         adjacentFaces(shape, face) {
-            return arr(kernel.adjacentFaces(asNum(shape), asNum(face))).map(asHandle);
+            return arr(kernel.adjacentFaces(asNum(shape), asNum(face))).map(asFace);
         },
         sharedEdges(a, b) {
-            return arr(kernel.sharedEdges(asNum(a), asNum(b))).map(asHandle);
+            return arr(kernel.sharedEdges(asNum(a), asNum(b))).map(asEdge);
         },
         // ── 几何求值 ──
         curveType(edge) { return String(kernel.getEdgeCurveType(asNum(edge))); },
@@ -968,21 +1231,42 @@ export async function createBrepkitPrimitives() {
         getNurbsCurveData(edge) {
             try {
                 const p = JSON.parse(kernel.getNurbsCurveData(asNum(edge)));
-                if (p && typeof p.degree === 'number')
-                    return { degree: p.degree, periodic: !!p.periodic, rational: !!p.rational };
+                if (p && typeof p.degree === 'number') {
+                    return {
+                        degree: p.degree,
+                        periodic: !!p.periodic,
+                        rational: !!p.rational,
+                        knots: (p.knots ?? []).map(Number),
+                        multiplicities: (p.multiplicities ?? []).map(Number),
+                        poles: (p.poles ?? []).map(Number),
+                        weights: (p.weights ?? []).map(Number),
+                    };
+                }
             }
             catch { /* 非 Nurbs 边 */ }
             return null;
         },
+        curveSplit(edge, param) {
+            // brepkit 原生返回 Uint32Array 两元素（occt 返回 [ShapeHandle, ShapeHandle]）——
+            // 适配器统一为二元组。两个碎片都必须登记进 knownEdges，否则下游 meshShape 分发不到。
+            const parts = kernel.curveSplit(asNum(edge), param);
+            if (parts.length !== 2)
+                fail(`curveSplit: expected 2 edges, got ${parts.length}`);
+            const a = parts[0];
+            const b = parts[1];
+            knownEdges.add(a);
+            knownEdges.add(b);
+            return [asEdge(a), asEdge(b)];
+        },
         interpolatePoints(points, degree) {
             // GOTCHA：interpolatePoints 返回 **edge** 句柄（不是 wire）——wire.ts smooth 路径把它
             // 直接当 wire 送 solidToShape。登记进 knownEdges，meshShape 才能走 tessellateEdge 路径。
             const e = kernel.interpolatePoints(flattenPoints(points), degree);
             knownEdges.add(e);
-            return asHandle(e);
+            return asEdge(e);
         },
         defeature(shape, faces) {
-            return asHandle(kernel.defeature(asNum(shape), Uint32Array.from(faces.map(asNum))));
+            return asHandle(markSolid(kernel.defeature(asNum(shape), Uint32Array.from(faces.map(asNum)))));
         },
         draft(shape, faces, pull, neutral, angleDeg) {
             return asHandle(kernel.draft(asNum(shape), Uint32Array.from(faces.map(asNum)), pull.x, pull.y, pull.z, neutral.x, neutral.y, neutral.z, angleDeg));
@@ -991,10 +1275,10 @@ export async function createBrepkitPrimitives() {
             // removeHolesFromFace 返回**新 face 句柄**（去掉内孔的同曲面 face），必须登记进 knownFaces。
             const f = kernel.removeHolesFromFace(asNum(face));
             knownFaces.add(f);
-            return asHandle(f);
+            return asFace(f);
         },
         reverseShape(shape) {
-            return asHandle(kernel.reverseShape(asNum(shape)));
+            return withKind(kindOf(shape), kernel.reverseShape(asNum(shape)));
         },
         projectEdges(shape, origin, direction, xAxis, hiddenLines, deflection) {
             // brepkit 返回 JSON 字符串 {"visible":[[x,y,…]],"hidden":[[…]]}；L1 契约是 unknown。
@@ -1054,11 +1338,12 @@ export async function createBrepkitPrimitives() {
             }
             // GOTCHA：kernel.boundingBox 是 solid-only。face/wire/edge 句柄必须走 tessellation 采样，
             // 否则 measure() 对 wire/profile 调 getBoundingBox 即崩 "invalid solid handle"。
-            if (knownFaces.has(s))
+            const kind = resolveKind(shape, s);
+            if (kind === KIND_FACE)
                 return bboxFromPoints(arr(kernel.tessellateFace(s, 0.1, 1).positions));
-            if (knownWires.has(s))
+            if (kind === KIND_WIRE)
                 return bboxFromPoints(arr(kernel.getWireEdges(s)).flatMap((e) => arr(kernel.tessellateEdge(e, 16))));
-            if (knownEdges.has(s))
+            if (kind === KIND_EDGE)
                 return bboxFromPoints(arr(kernel.tessellateEdge(s, 16)));
             return solidBbox(s);
         },
@@ -1072,17 +1357,15 @@ export async function createBrepkitPrimitives() {
             return Number(kernel.surfaceArea(asNum(shape), 0.05));
         },
         getLength(shape) {
-            // 方言映射：L1 getLength ↔ brepkit edgeLength(edge) / wireLength(wire)。
-            // wire 与 edge 的入参差异在适配器内判别（D6）：edgeLength 只吃 edge 句柄，
-            // 对 wire 会抛错；据此分发，两条路径都失败时如实抛出（不静默返回 0）。
-            const s = asNum(shape);
-            try {
-                kernel.getEdgeCurveType(s);
-                return Number(kernel.edgeLength(s));
-            }
-            catch {
-                return Number(kernel.wireLength(s));
-            }
+            // 唯一 edge 弧长之和（与 occt 适配器同口径，D5）。
+            // 旧实现用 `try { getEdgeCurveType } catch { wireLength }` 判别入参差异，但
+            // getEdgeCurveType 对 solid / face / wire **也不抛错**，于是统一走 edgeLength，
+            // 返回「首条边」长度——值随构建历史漂移（盒 20 vs 10；两边的 wire 真长 15 却给 20），
+            // 且与 occt 的 Σ 面周长（280）不同口径。改为按 topo 去重枚举边后求和。
+            let total = 0;
+            for (const e of api.getSubShapes(shape, 'edge'))
+                total += api.curveLength(e);
+            return total;
         },
         // ── 校验与修复 ──
         // ⚠️ brepkit 的修复类内核函数全部是「**原地修改入参实体 + 返回修复计数**」，不是返回新句柄：
@@ -1113,12 +1396,12 @@ export async function createBrepkitPrimitives() {
             return asHandle(c);
         },
         fixFaceOrientations(shape) {
-            const c = kernel.copySolid(asNum(shape));
+            const c = markSolid(kernel.copySolid(asNum(shape)));
             kernel.fixFaceOrientations(c);
             return asHandle(c);
         },
         removeDegenerateEdges(shape, tolerance) {
-            const c = kernel.copySolid(asNum(shape));
+            const c = markSolid(kernel.copySolid(asNum(shape)));
             kernel.removeDegenerateEdges(c, tolerance ?? 1e-6);
             return asHandle(c);
         },
@@ -1130,7 +1413,10 @@ export async function createBrepkitPrimitives() {
             const solids = arr(kernel.importStep(bytes));
             if (solids.length === 0)
                 fail('importStep: kernel returned no solid');
-            return asHandle(solids.length === 1 ? solids[0] : kernel.makeCompound(Uint32Array.from(solids)));
+            const c = solids.length === 1 ? solids[0] : kernel.makeCompound(Uint32Array.from(solids));
+            if (solids.length > 1)
+                knownCompounds.set(c, solids);
+            return asHandle(markSolid(c));
         },
         exportStep(shape) {
             // brepkit exportStep 返回 UTF-8 字节（Uint8Array），需解码为 STEP 文本（2026-09-19 实测）
@@ -1139,14 +1425,39 @@ export async function createBrepkitPrimitives() {
         },
         importStl(data) {
             const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
-            return asHandle(kernel.importStl(bytes));
+            return asHandle(markSolid(kernel.importStl(bytes)));
         },
         fromBREP(data) {
             // ⚠️ brepkit fromBREP 吃字符串（STEP 文本或 toBREP/toBrepJson 输出，内核自动判别），
             // 与 serializeSolid/deserializeSolid 的**二进制 arena** 是两套机制。
             // 旧实现误用 `deserializeSolid(atob(data))`：base64 解码破坏了 STEP 文本 → 往返必失败
             // （2026-09-25 实证：fromBREP(STEP)、fromBREP(toBREP)、fromBREP(toBrepJson) 均成功）。
-            return asHandle(kernel.fromBREP(data));
+            return asHandle(markSolid(kernel.fromBREP(data)));
+        },
+        // ── 网格实体原语（方案 2026-10-01 §3.3；内核私有，不在 L1 契约面） ──
+        // 规范构造顺序**不可交换**：importMesh → weld → unify。
+        // 实测（brepkit-kernel/mesh-solid-topology.test.ts）：先 unify 后 weld 会把实体做坏
+        // （体积归零、validate 非 0）。本对象只暴露原语，顺序由 `normalizeMeshSolid` 驱动。
+        meshSolid: {
+            importMesh(positions, indices) {
+                // 方言：importIndexedMesh 吃 **Float64Array**（坐标）+ **Uint32Array**（索引），
+                // 返回裸 solid 号。逐三角形建面、顶点按坐标焊接、边不共享（不是真流形）。
+                const coords = new Float64Array(positions.length);
+                for (let i = 0; i < positions.length; i++)
+                    coords[i] = positions[i];
+                return asHandle(markSolid(kernel.importIndexedMesh(coords, indices)));
+            },
+            weld(faces, tolerance) {
+                // weldShellsAndFaces 吃**裸面号数组**（Uint32Array），返回新 solid 号；
+                // 把重复边缝成共享边 → 真流形（实测 10mm 立方体 36 边 → 18 边、validate 0）。
+                return asHandle(markSolid(kernel.weldShellsAndFaces(Uint32Array.from(faces.map((f) => asNum(f))), tolerance)));
+            },
+            unify(solid) {
+                // GOTCHA：unifyFaces 是**原地修改**入参实体，返回值是**被合并掉的面数**
+                // （不是新句柄）。写成 `const s = unify(...)` 会拿到一个落在合法句柄区间的
+                // 数字，后续全部查询打在一个无关实体上且不报错。
+                return Number(kernel.unifyFaces(asNum(solid)));
+            },
         },
         // ── 面演化（L1 三员 + filletWithHistory，双方都有对齐实现） ──
         cutWithHistory(a, b, inputFaceHashes, hashUpperBound) {
@@ -1162,6 +1473,8 @@ export async function createBrepkitPrimitives() {
             return mapEvolution(kernel, raw, JSON.parse(raw).solid, inputFaceHashes, hashUpperBound);
         },
     };
+    memoizedKernel = kernel;
+    memoizedPrimitives = api;
     return api;
 }
 // ── 工具 ──
@@ -1206,6 +1519,9 @@ function vec3Of(p) {
 }
 /** 已初始化的 brepkit 内核单例（createBrepkitPrimitives 时赋值）。 */
 let liveKernel = null;
+/** 已构建的 L1 契约面对象（按内核实例 memo；见 createBrepkitPrimitives 的 GOTCHA）。 */
+let memoizedPrimitives = null;
+let memoizedKernel = null;
 /**
  * 原生 brepkit 内核面（D3）：平台特定代码访问 brepkit 独有能力的唯一入口
  * （chamfer2d/chamferV2/filletV2/sketch* 族、serializeSolid、meshBoolean 等）。
@@ -1221,7 +1537,14 @@ export function getBrepkitKernel() {
     }
     return liveKernel;
 }
-/** 释放内核单例（测试收尾用；宿主常驻不需调用）。 */
+/**
+ * 释放内核单例（测试收尾用；宿主常驻不需调用）。
+ *
+ * GOTCHA（2026-10-01 修复）：旧实现只 `free()` 内核、**不重置** brepkitWasm.ts 里
+ * 缓存的 `initPromise`，也不丢 memo 化的原语对象 → 第二次 `createBrepkitPrimitives()`
+ * 拿到**已释放**的内核，随后一切内核调用报 `null pointer passed to rust`
+ * （实测：`BrepKernel.makeBox`）。现在三样一起清：内核、initPromise、memo 原语。
+ */
 export function disposeBrepkit() {
     try {
         if (liveKernel?.free)
@@ -1229,5 +1552,8 @@ export function disposeBrepkit() {
     }
     catch { /* 已释放 */ }
     liveKernel = null;
+    memoizedPrimitives = null;
+    memoizedKernel = null;
+    resetBrepkitWasm();
 }
 //# sourceMappingURL=brepkitKernel.js.map