@faicad/faijs 0.13.0

package/dist/topology/naming/resolve-derived.js

@@ -0,0 +1,128 @@
+/**
+ * resolve-derived.ts — 生成面（倒角/圆角过渡面）TopoRef 解析
+ * （移植 brepjs derivedFaceRefFns，§4.5）
+ *
+ * 生成面没有稳定 hash（操作前不存在，fillet/chamfer 演化为空），
+ * 以「桥接的两面」lineage 命名：解析 = 重找被桥接的两面 → 取同时邻接
+ * 两者的面 → 法向混合过滤（过渡面法向同时正比于两条被桥接法向，
+ * 正交的侧面被拒绝）→ 边中点裁决并列。
+ */
+import { facesForQualifier } from './resolve-edge.js';
+/** 面法向与捕获法向几乎一致才视为「重导出被桥接面」。 */
+const NORMAL_MATCH = 0.99;
+/** 过渡面法向须对两条被桥接法向都有正分量。 */
+const BLEND_THRESHOLD = 0.1;
+/** 并列距离容差。 */
+const HINT_MARGIN = 1e-6;
+/** 法向点积。 */
+function dot(a, b) {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/** 面候选的法向（row 快照；无则 undefined）。 */
+function normalOf(face) {
+    return face.row?.normal;
+}
+/**
+ * 解析生成面 TopoRef 到当前快照的面序号。
+ *
+ * @param ref - the derived-face TopoRef to resolve.
+ * @param ctx - the resolution context (needs faceAdjacency for lineage).
+ * @returns the three-state TopoResolution with the face ordinal.
+ */
+export function resolveDerivedFaceTopo(ref, ctx) {
+    const [qualA, qualB] = ref.between;
+    let facesA = facesForQualifier(qualA, ctx);
+    if (facesA.length === 0)
+        facesA = facesByNormal(ctx, ref.hint.normalA);
+    let facesB = facesForQualifier(qualB, ctx);
+    if (facesB.length === 0)
+        facesB = facesByNormal(ctx, ref.hint.normalB);
+    if (facesA.length === 0 || facesB.length === 0) {
+        return { ok: false, reason: 'not-found' };
+    }
+    // 同时邻接 A 面与 B 面的面（排除 A/B 自身）
+    const blended = betweenFaces(ctx, facesA, facesB).filter((f) => {
+        const n = normalOf(f);
+        if (!n)
+            return false;
+        return dot(n, ref.hint.normalA) > BLEND_THRESHOLD && dot(n, ref.hint.normalB) > BLEND_THRESHOLD;
+    });
+    if (blended.length === 1) {
+        const [only] = blended;
+        if (only !== undefined) {
+            return { ok: true, entity: { handle: only.handle }, ordinal: only.ordinal, confidence: 'geometric-fallback' };
+        }
+    }
+    if (blended.length > 1) {
+        const best = ref.hint.edgeMidpoint && nearestByMidpoint(blended, ref.hint.edgeMidpoint);
+        if (best !== undefined) {
+            return { ok: true, entity: { handle: best.handle }, ordinal: best.ordinal, confidence: 'geometric-fallback' };
+        }
+        return { ok: false, reason: 'ambiguous', candidatesOrdinal: blended.map((f) => f.ordinal) };
+    }
+    return { ok: false, reason: 'not-found' };
+}
+/** 法向与目标法向几乎一致的面（重导出被桥接面）。 */
+function facesByNormal(ctx, normal) {
+    return ctx.faces.filter((f) => {
+        const n = normalOf(f);
+        return n !== undefined && dot(n, normal) > NORMAL_MATCH;
+    });
+}
+/** 同时邻接 A、B 面集合的面（排除 A/B 自身，face→face 邻接交集）。 */
+function betweenFaces(ctx, aFaces, bFaces) {
+    const exclude = new Set([...aFaces, ...bFaces].map((f) => f.ordinal));
+    const adjacentToA = new Set();
+    for (const a of aFaces) {
+        for (const n of ctx.faceAdjacency?.[a.ordinal - 1] ?? [])
+            adjacentToA.add(n);
+    }
+    const betweenOrdinals = new Set();
+    for (const b of bFaces) {
+        for (const n of ctx.faceAdjacency?.[b.ordinal - 1] ?? []) {
+            if (!exclude.has(n) && adjacentToA.has(n))
+                betweenOrdinals.add(n);
+        }
+    }
+    if (betweenOrdinals.size === 0)
+        return [];
+    const byOrdinal = new Map(ctx.faces.map((f) => [f.ordinal, f]));
+    const result = [];
+    for (const ord of betweenOrdinals) {
+        const f = byOrdinal.get(ord);
+        if (f)
+            result.push(f);
+    }
+    return result;
+}
+/** 距边中点最近的面；并列 → undefined（ambiguous）。 */
+function nearestByMidpoint(faces, point) {
+    let best;
+    let bestDist = Infinity;
+    let secondDist = Infinity;
+    for (const f of faces) {
+        const c = f.row?.center;
+        if (c === undefined)
+            continue;
+        const d = distance(c, point);
+        if (d < bestDist) {
+            secondDist = bestDist;
+            bestDist = d;
+            best = f;
+        }
+        else if (d < secondDist) {
+            secondDist = d;
+        }
+    }
+    if (best === undefined || secondDist - bestDist < HINT_MARGIN)
+        return undefined;
+    return best;
+}
+/** 两点欧氏距离。 */
+function distance(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    const dz = a[2] - b[2];
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+//# sourceMappingURL=resolve-derived.js.map

package/dist/topology/naming/resolve-derived.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-derived.js","sourceRoot":"","sources":["../../../src/topology/naming/resolve-derived.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * resolve-derived.ts — 生成面（倒角/圆角过渡面）TopoRef 解析\n * （移植 brepjs derivedFaceRefFns，§4.5）\n *\n * 生成面没有稳定 hash（操作前不存在，fillet/chamfer 演化为空），\n * 以「桥接的两面」lineage 命名：解析 = 重找被桥接的两面 → 取同时邻接\n * 两者的面 → 法向混合过滤（过渡面法向同时正比于两条被桥接法向，\n * 正交的侧面被拒绝）→ 边中点裁决并列。\n */\n\nimport type { BrepHandle } from '../../brep/engine/types'\nimport type { DerivedFaceTopoRef, TopoResolution } from './types'\nimport type { FaceCandidateEntry, ResolutionContext } from './resolve-face'\nimport { facesForQualifier } from './resolve-edge'\n\n/** 面法向与捕获法向几乎一致才视为「重导出被桥接面」。 */\nconst NORMAL_MATCH = 0.99\n/** 过渡面法向须对两条被桥接法向都有正分量。 */\nconst BLEND_THRESHOLD = 0.1\n/** 并列距离容差。 */\nconst HINT_MARGIN = 1e-6\n\n/** 法向点积。 */\nfunction dot(a: readonly number[], b: readonly number[]): number {\n  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]\n}\n\n/** 面候选的法向（row 快照；无则 undefined）。 */\nfunction normalOf(face: FaceCandidateEntry): readonly number[] | undefined {\n  return face.row?.normal\n}\n\n/**\n * 解析生成面 TopoRef 到当前快照的面序号。\n *\n * @param ref - the derived-face TopoRef to resolve.\n * @param ctx - the resolution context (needs faceAdjacency for lineage).\n * @returns the three-state TopoResolution with the face ordinal.\n */\nexport function resolveDerivedFaceTopo(\n  ref: DerivedFaceTopoRef,\n  ctx: ResolutionContext,\n): TopoResolution<{ handle?: BrepHandle }> {\n  const [qualA, qualB] = ref.between\n  let facesA = facesForQualifier(qualA, ctx)\n  if (facesA.length === 0) facesA = facesByNormal(ctx, ref.hint.normalA)\n  let facesB = facesForQualifier(qualB, ctx)\n  if (facesB.length === 0) facesB = facesByNormal(ctx, ref.hint.normalB)\n  if (facesA.length === 0 || facesB.length === 0) {\n    return { ok: false, reason: 'not-found' }\n  }\n\n  // 同时邻接 A 面与 B 面的面（排除 A/B 自身）\n  const blended = betweenFaces(ctx, facesA, facesB).filter((f) => {\n    const n = normalOf(f)\n    if (!n) return false\n    return dot(n, ref.hint.normalA) > BLEND_THRESHOLD && dot(n, ref.hint.normalB) > BLEND_THRESHOLD\n  })\n\n  if (blended.length === 1) {\n    const [only] = blended\n    if (only !== undefined) {\n      return { ok: true, entity: { handle: only.handle }, ordinal: only.ordinal, confidence: 'geometric-fallback' }\n    }\n  }\n\n  if (blended.length > 1) {\n    const best = ref.hint.edgeMidpoint && nearestByMidpoint(blended, ref.hint.edgeMidpoint)\n    if (best !== undefined) {\n      return { ok: true, entity: { handle: best.handle }, ordinal: best.ordinal, confidence: 'geometric-fallback' }\n    }\n    return { ok: false, reason: 'ambiguous', candidatesOrdinal: blended.map((f) => f.ordinal) }\n  }\n\n  return { ok: false, reason: 'not-found' }\n}\n\n/** 法向与目标法向几乎一致的面（重导出被桥接面）。 */\nfunction facesByNormal(ctx: ResolutionContext, normal: readonly number[]): FaceCandidateEntry[] {\n  return ctx.faces.filter((f) => {\n    const n = normalOf(f)\n    return n !== undefined && dot(n, normal) > NORMAL_MATCH\n  })\n}\n\n/** 同时邻接 A、B 面集合的面（排除 A/B 自身，face→face 邻接交集）。 */\nfunction betweenFaces(\n  ctx: ResolutionContext,\n  aFaces: readonly FaceCandidateEntry[],\n  bFaces: readonly FaceCandidateEntry[],\n): FaceCandidateEntry[] {\n  const exclude = new Set<number>([...aFaces, ...bFaces].map((f) => f.ordinal))\n  const adjacentToA = new Set<number>()\n  for (const a of aFaces) {\n    for (const n of ctx.faceAdjacency?.[a.ordinal - 1] ?? []) adjacentToA.add(n)\n  }\n  const betweenOrdinals = new Set<number>()\n  for (const b of bFaces) {\n    for (const n of ctx.faceAdjacency?.[b.ordinal - 1] ?? []) {\n      if (!exclude.has(n) && adjacentToA.has(n)) betweenOrdinals.add(n)\n    }\n  }\n  if (betweenOrdinals.size === 0) return []\n  const byOrdinal = new Map(ctx.faces.map((f) => [f.ordinal, f]))\n  const result: FaceCandidateEntry[] = []\n  for (const ord of betweenOrdinals) {\n    const f = byOrdinal.get(ord)\n    if (f) result.push(f)\n  }\n  return result\n}\n\n/** 距边中点最近的面；并列 → undefined（ambiguous）。 */\nfunction nearestByMidpoint(faces: readonly FaceCandidateEntry[], point: readonly number[]): FaceCandidateEntry | undefined {\n  let best: FaceCandidateEntry | undefined\n  let bestDist = Infinity\n  let secondDist = Infinity\n  for (const f of faces) {\n    const c = f.row?.center\n    if (c === undefined) continue\n    const d = distance(c, point)\n    if (d < bestDist) {\n      secondDist = bestDist\n      bestDist = d\n      best = f\n    } else if (d < secondDist) {\n      secondDist = d\n    }\n  }\n  if (best === undefined || secondDist - bestDist < HINT_MARGIN) return undefined\n  return best\n}\n\n/** 两点欧氏距离。 */\nfunction distance(a: readonly number[], b: readonly number[]): number {\n  const dx = a[0] - b[0]\n  const dy = a[1] - b[1]\n  const dz = a[2] - b[2]\n  return Math.sqrt(dx * dx + dy * dy + dz * dz)\n}\n"]}

package/dist/topology/naming/resolve-edge.d.ts

@@ -0,0 +1,36 @@
+/**
+ * resolve-edge.ts — 边 TopoRef 解析（移植 brepjs edgeRefFns，§4.2/§4.3）
+ *
+ * 边 = 两邻面之交。EdgeTopoRef.faces 是两个 RoleQualifier（带 origin，faijs 扩展：
+ * 布尔合流后两面可能来自不同 origin）。
+ *
+ * 解析 = 两 role 解析到当前面 → 取公共边：
+ * - 1 条公共边 → exact
+ * - 多条（两邻面沿多边相接，如圆角面）→ hint（length/midpoint）裁决
+ * - 无公共边 / role 缺失 → not-found
+ *
+ * mesh 无 face→edge 邻接（build-mesh-topology.ts:262，§5.3 能力边界）→
+ * lineage 不可用，只能给边 hint；此时解析降级为「纯 hint 匹配」并显式标注。
+ */
+import type { BrepHandle } from '../../brep/engine/types.js';
+import type { EdgeTopoRef, RoleQualifier, TopoResolution } from './types.js';
+import { type FaceCandidateEntry, type ResolutionContext } from './resolve-face.js';
+/**
+ * 解析一个 RoleQualifier 到当前面候选（exact 优先，几何兜底）。
+ *
+ * @param qualifier - the face role qualifier (origin + role).
+ * @param ctx - the resolution context.
+ * @returns the face candidates for the role (possibly several after a split).
+ */
+export declare function facesForQualifier(qualifier: RoleQualifier, ctx: ResolutionContext): FaceCandidateEntry[];
+/**
+ * 解析边 TopoRef 到当前快照的边序号。
+ *
+ * @param ref - the edge TopoRef to resolve.
+ * @param ctx - the resolution context (needs faceEdgeAdjacency for lineage).
+ * @returns the three-state TopoResolution with the edge ordinal.
+ */
+export declare function resolveEdgeTopo(ref: EdgeTopoRef, ctx: ResolutionContext): TopoResolution<{
+    handle?: BrepHandle;
+}>;
+//# sourceMappingURL=resolve-edge.d.ts.map

package/dist/topology/naming/resolve-edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-edge.d.ts","sourceRoot":"","sources":["../../../src/topology/naming/resolve-edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACzE,OAAO,EAAmB,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAajG;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,GAAG,EAAE,iBAAiB,GACrB,kBAAkB,EAAE,CAgBtB;AAuBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,iBAAiB,GACrB,cAAc,CAAC;IAAE,MAAM,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC,CAwCzC"}

package/dist/topology/naming/resolve-edge.js

@@ -0,0 +1,138 @@
+/**
+ * resolve-edge.ts — 边 TopoRef 解析（移植 brepjs edgeRefFns，§4.2/§4.3）
+ *
+ * 边 = 两邻面之交。EdgeTopoRef.faces 是两个 RoleQualifier（带 origin，faijs 扩展：
+ * 布尔合流后两面可能来自不同 origin）。
+ *
+ * 解析 = 两 role 解析到当前面 → 取公共边：
+ * - 1 条公共边 → exact
+ * - 多条（两邻面沿多边相接，如圆角面）→ hint（length/midpoint）裁决
+ * - 无公共边 / role 缺失 → not-found
+ *
+ * mesh 无 face→edge 邻接（build-mesh-topology.ts:262，§5.3 能力边界）→
+ * lineage 不可用，只能给边 hint；此时解析降级为「纯 hint 匹配」并显式标注。
+ */
+import { resolveFaceTopo } from './resolve-face.js';
+/** Hint 距离比这更近视为不可区分（→ ambiguous）。 */
+const HINT_MARGIN = 1e-6;
+/** 两点的欧氏距离。 */
+function distance(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    const dz = a[2] - b[2];
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+/**
+ * 解析一个 RoleQualifier 到当前面候选（exact 优先，几何兜底）。
+ *
+ * @param qualifier - the face role qualifier (origin + role).
+ * @param ctx - the resolution context.
+ * @returns the face candidates for the role (possibly several after a split).
+ */
+export function facesForQualifier(qualifier, ctx) {
+    const targetHashes = ctx.roleTable?.get(qualifier.origin)?.get(qualifier.role);
+    if (targetHashes !== undefined && targetHashes.length > 0) {
+        const survivors = ctx.faces.filter((f) => f.hash !== undefined && targetHashes.includes(f.hash));
+        if (survivors.length > 0)
+            return survivors;
+    }
+    // role 缺失/未命中 → 几何兜底（只取最优面，与 resolveFaceTopo 同口径）
+    const resolution = resolveFaceTopo({ kind: 'face', origin: qualifier.origin, role: qualifier.role, hint: { kind: 'face' } }, ctx);
+    if (resolution.ok) {
+        const hit = ctx.faces.find((f) => f.ordinal === resolution.ordinal);
+        if (hit)
+            return [hit];
+    }
+    return [];
+}
+/** 两面的公共边 ordinal（face→edge 邻接交集）。 */
+function sharedEdgeOrdinals(faceA, faceB, ctx) {
+    const aEdges = new Set(ctx.faceEdgeAdjacency?.[faceA.ordinal - 1] ?? []);
+    const bEdges = new Set(ctx.faceEdgeAdjacency?.[faceB.ordinal - 1] ?? []);
+    const shared = [];
+    for (const e of aEdges)
+        if (bEdges.has(e))
+            shared.push(e);
+    return shared;
+}
+/** 候选边 hint 与 ref hint 的距离分（越小越匹配）。 */
+function edgeHintScore(edge, refHint) {
+    let score = 0;
+    if (refHint.length !== undefined && edge.hint?.length !== undefined) {
+        score += Math.abs(edge.hint.length - refHint.length);
+    }
+    if (refHint.midpoint !== undefined && edge.hint?.midpoint !== undefined) {
+        score += distance(edge.hint.midpoint, refHint.midpoint);
+    }
+    return score;
+}
+/**
+ * 解析边 TopoRef 到当前快照的边序号。
+ *
+ * @param ref - the edge TopoRef to resolve.
+ * @param ctx - the resolution context (needs faceEdgeAdjacency for lineage).
+ * @returns the three-state TopoResolution with the edge ordinal.
+ */
+export function resolveEdgeTopo(ref, ctx) {
+    const [qualA, qualB] = ref.faces;
+    const facesA = facesForQualifier(qualA, ctx);
+    const facesB = facesForQualifier(qualB, ctx);
+    if (facesA.length === 0 || facesB.length === 0) {
+        return { ok: false, reason: 'not-found' };
+    }
+    // 收集所有 (a, b) 面对的公共边
+    const shared = new Set();
+    for (const a of facesA) {
+        for (const b of facesB) {
+            for (const e of sharedEdgeOrdinals(a, b, ctx))
+                shared.add(e);
+        }
+    }
+    const unique = [...shared];
+    if (unique.length === 1) {
+        const [only] = unique;
+        if (only !== undefined) {
+            const edge = ctx.edges?.find((e) => e.ordinal === only);
+            return { ok: true, entity: { handle: edge?.handle }, ordinal: only, confidence: 'exact' };
+        }
+    }
+    if (unique.length > 1) {
+        // 多公共边 → hint 裁决
+        const best = bestEdgeByHint(unique, ref.hint, ctx);
+        if (best !== undefined)
+            return { ok: true, entity: { handle: best.handle }, ordinal: best.ordinal, confidence: 'geometric-fallback' };
+        return { ok: false, reason: 'ambiguous', candidatesOrdinal: unique };
+    }
+    // 无公共边：face→edge 邻接缺失（mesh）→ 纯 hint 匹配整个边表；否则 not-found
+    if (!ctx.faceEdgeAdjacency && ctx.edges && ctx.edges.length > 0) {
+        const best = bestEdgeByHint(ctx.edges.map((e) => e.ordinal), ref.hint, ctx);
+        if (best !== undefined)
+            return { ok: true, entity: { handle: best.handle }, ordinal: best.ordinal, confidence: 'geometric-fallback' };
+        return { ok: false, reason: 'not-found' };
+    }
+    return { ok: false, reason: 'not-found' };
+}
+/** 在候选 ordinal 中按 hint 取最优边；无法区分 → undefined（ambiguous）。 */
+function bestEdgeByHint(ordinals, hint, ctx) {
+    if (hint.length === undefined && hint.midpoint === undefined)
+        return undefined;
+    let best;
+    let bestScore = Infinity;
+    let secondScore = Infinity;
+    for (const ord of ordinals) {
+        const edge = ctx.edges?.find((e) => e.ordinal === ord);
+        const score = edgeHintScore(edge ?? {}, hint);
+        if (score < bestScore) {
+            secondScore = bestScore;
+            bestScore = score;
+            best = { ordinal: ord, handle: edge?.handle };
+        }
+        else if (score < secondScore) {
+            secondScore = score;
+        }
+    }
+    if (best === undefined || secondScore - bestScore < HINT_MARGIN)
+        return undefined;
+    return best;
+}
+//# sourceMappingURL=resolve-edge.js.map

package/dist/topology/naming/resolve-edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-edge.js","sourceRoot":"","sources":["../../../src/topology/naming/resolve-edge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,eAAe,EAAmD,MAAM,gBAAgB,CAAA;AAEjG,sCAAsC;AACtC,MAAM,WAAW,GAAG,IAAI,CAAA;AAExB,eAAe;AACf,SAAS,QAAQ,CAAC,CAAoB,EAAE,CAAoB;IAC1D,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACtB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACtB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;IACtB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAA;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAwB,EACxB,GAAsB;IAEtB,MAAM,YAAY,GAAG,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAC9E,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QAChG,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,SAAS,CAAA;IAC5C,CAAC;IACD,kDAAkD;IAClD,MAAM,UAAU,GAAG,eAAe,CAChC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EACxF,GAAG,CACJ,CAAA;IACD,IAAI,UAAU,CAAC,EAAE,EAAE,CAAC;QAClB,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,UAAU,CAAC,OAAO,CAAC,CAAA;QACnE,IAAI,GAAG;YAAE,OAAO,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED,sCAAsC;AACtC,SAAS,kBAAkB,CAAC,KAAyB,EAAE,KAAyB,EAAE,GAAsB;IACtG,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IACxE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,iBAAiB,EAAE,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAA;IACxE,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACzD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,uCAAuC;AACvC,SAAS,aAAa,CAAC,IAAkE,EAAE,OAA4B;IACrH,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QACpE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACtD,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS,EAAE,CAAC;QACxE,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACzD,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAgB,EAChB,GAAsB;IAEtB,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC,KAAK,CAAA;IAChC,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAC5C,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAC5C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;IAC3C,CAAC;IAED,qBAAqB;IACrB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;IAChC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,IAAI,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC;gBAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QAC9D,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAA;IAC1B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAA;QACrB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,CAAA;YACvD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAA;QAC3F,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,iBAAiB;QACjB,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAClD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAA;QACrI,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,EAAE,CAAA;IACtE,CAAC;IAED,wDAAwD;IACxD,IAAI,CAAC,GAAG,CAAC,iBAAiB,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAC3E,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAA;QACrI,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;IAC3C,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;AAC3C,CAAC;AAED,4DAA4D;AAC5D,SAAS,cAAc,CACrB,QAA2B,EAC3B,IAAyB,EACzB,GAAsB;IAEtB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAC9E,IAAI,IAA0D,CAAA;IAC9D,IAAI,SAAS,GAAG,QAAQ,CAAA;IACxB,IAAI,WAAW,GAAG,QAAQ,CAAA;IAC1B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,GAAG,CAAC,CAAA;QACtD,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,IAAI,EAAE,EAAE,IAAI,CAAC,CAAA;QAC7C,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,WAAW,GAAG,SAAS,CAAA;YACvB,SAAS,GAAG,KAAK,CAAA;YACjB,IAAI,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;QAC/C,CAAC;aAAM,IAAI,KAAK,GAAG,WAAW,EAAE,CAAC;YAC/B,WAAW,GAAG,KAAK,CAAA;QACrB,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,WAAW,GAAG,SAAS,GAAG,WAAW;QAAE,OAAO,SAAS,CAAA;IACjF,OAAO,IAAI,CAAA;AACb,CAAC","sourcesContent":["/**\n * resolve-edge.ts — 边 TopoRef 解析（移植 brepjs edgeRefFns，§4.2/§4.3）\n *\n * 边 = 两邻面之交。EdgeTopoRef.faces 是两个 RoleQualifier（带 origin，faijs 扩展：\n * 布尔合流后两面可能来自不同 origin）。\n *\n * 解析 = 两 role 解析到当前面 → 取公共边：\n * - 1 条公共边 → exact\n * - 多条（两邻面沿多边相接，如圆角面）→ hint（length/midpoint）裁决\n * - 无公共边 / role 缺失 → not-found\n *\n * mesh 无 face→edge 邻接（build-mesh-topology.ts:262，§5.3 能力边界）→\n * lineage 不可用，只能给边 hint；此时解析降级为「纯 hint 匹配」并显式标注。\n */\n\nimport type { BrepHandle } from '../../brep/engine/types'\nimport type { EdgeTopoRef, RoleQualifier, TopoResolution } from './types'\nimport { resolveFaceTopo, type FaceCandidateEntry, type ResolutionContext } from './resolve-face'\n\n/** Hint 距离比这更近视为不可区分（→ ambiguous）。 */\nconst HINT_MARGIN = 1e-6\n\n/** 两点的欧氏距离。 */\nfunction distance(a: readonly number[], b: readonly number[]): number {\n  const dx = a[0] - b[0]\n  const dy = a[1] - b[1]\n  const dz = a[2] - b[2]\n  return Math.sqrt(dx * dx + dy * dy + dz * dz)\n}\n\n/**\n * 解析一个 RoleQualifier 到当前面候选（exact 优先，几何兜底）。\n *\n * @param qualifier - the face role qualifier (origin + role).\n * @param ctx - the resolution context.\n * @returns the face candidates for the role (possibly several after a split).\n */\nexport function facesForQualifier(\n  qualifier: RoleQualifier,\n  ctx: ResolutionContext,\n): FaceCandidateEntry[] {\n  const targetHashes = ctx.roleTable?.get(qualifier.origin)?.get(qualifier.role)\n  if (targetHashes !== undefined && targetHashes.length > 0) {\n    const survivors = ctx.faces.filter((f) => f.hash !== undefined && targetHashes.includes(f.hash))\n    if (survivors.length > 0) return survivors\n  }\n  // role 缺失/未命中 → 几何兜底（只取最优面，与 resolveFaceTopo 同口径）\n  const resolution = resolveFaceTopo(\n    { kind: 'face', origin: qualifier.origin, role: qualifier.role, hint: { kind: 'face' } },\n    ctx,\n  )\n  if (resolution.ok) {\n    const hit = ctx.faces.find((f) => f.ordinal === resolution.ordinal)\n    if (hit) return [hit]\n  }\n  return []\n}\n\n/** 两面的公共边 ordinal（face→edge 邻接交集）。 */\nfunction sharedEdgeOrdinals(faceA: FaceCandidateEntry, faceB: FaceCandidateEntry, ctx: ResolutionContext): number[] {\n  const aEdges = new Set(ctx.faceEdgeAdjacency?.[faceA.ordinal - 1] ?? [])\n  const bEdges = new Set(ctx.faceEdgeAdjacency?.[faceB.ordinal - 1] ?? [])\n  const shared: number[] = []\n  for (const e of aEdges) if (bEdges.has(e)) shared.push(e)\n  return shared\n}\n\n/** 候选边 hint 与 ref hint 的距离分（越小越匹配）。 */\nfunction edgeHintScore(edge: { hint?: { length?: number; midpoint?: readonly number[] } }, refHint: EdgeTopoRef['hint']): number {\n  let score = 0\n  if (refHint.length !== undefined && edge.hint?.length !== undefined) {\n    score += Math.abs(edge.hint.length - refHint.length)\n  }\n  if (refHint.midpoint !== undefined && edge.hint?.midpoint !== undefined) {\n    score += distance(edge.hint.midpoint, refHint.midpoint)\n  }\n  return score\n}\n\n/**\n * 解析边 TopoRef 到当前快照的边序号。\n *\n * @param ref - the edge TopoRef to resolve.\n * @param ctx - the resolution context (needs faceEdgeAdjacency for lineage).\n * @returns the three-state TopoResolution with the edge ordinal.\n */\nexport function resolveEdgeTopo(\n  ref: EdgeTopoRef,\n  ctx: ResolutionContext,\n): TopoResolution<{ handle?: BrepHandle }> {\n  const [qualA, qualB] = ref.faces\n  const facesA = facesForQualifier(qualA, ctx)\n  const facesB = facesForQualifier(qualB, ctx)\n  if (facesA.length === 0 || facesB.length === 0) {\n    return { ok: false, reason: 'not-found' }\n  }\n\n  // 收集所有 (a, b) 面对的公共边\n  const shared = new Set<number>()\n  for (const a of facesA) {\n    for (const b of facesB) {\n      for (const e of sharedEdgeOrdinals(a, b, ctx)) shared.add(e)\n    }\n  }\n\n  const unique = [...shared]\n  if (unique.length === 1) {\n    const [only] = unique\n    if (only !== undefined) {\n      const edge = ctx.edges?.find((e) => e.ordinal === only)\n      return { ok: true, entity: { handle: edge?.handle }, ordinal: only, confidence: 'exact' }\n    }\n  }\n\n  if (unique.length > 1) {\n    // 多公共边 → hint 裁决\n    const best = bestEdgeByHint(unique, ref.hint, ctx)\n    if (best !== undefined) return { ok: true, entity: { handle: best.handle }, ordinal: best.ordinal, confidence: 'geometric-fallback' }\n    return { ok: false, reason: 'ambiguous', candidatesOrdinal: unique }\n  }\n\n  // 无公共边：face→edge 邻接缺失（mesh）→ 纯 hint 匹配整个边表；否则 not-found\n  if (!ctx.faceEdgeAdjacency && ctx.edges && ctx.edges.length > 0) {\n    const best = bestEdgeByHint(ctx.edges.map((e) => e.ordinal), ref.hint, ctx)\n    if (best !== undefined) return { ok: true, entity: { handle: best.handle }, ordinal: best.ordinal, confidence: 'geometric-fallback' }\n    return { ok: false, reason: 'not-found' }\n  }\n\n  return { ok: false, reason: 'not-found' }\n}\n\n/** 在候选 ordinal 中按 hint 取最优边；无法区分 → undefined（ambiguous）。 */\nfunction bestEdgeByHint(\n  ordinals: readonly number[],\n  hint: EdgeTopoRef['hint'],\n  ctx: ResolutionContext,\n): { ordinal: number; handle?: BrepHandle } | undefined {\n  if (hint.length === undefined && hint.midpoint === undefined) return undefined\n  let best: { ordinal: number; handle?: BrepHandle } | undefined\n  let bestScore = Infinity\n  let secondScore = Infinity\n  for (const ord of ordinals) {\n    const edge = ctx.edges?.find((e) => e.ordinal === ord)\n    const score = edgeHintScore(edge ?? {}, hint)\n    if (score < bestScore) {\n      secondScore = bestScore\n      bestScore = score\n      best = { ordinal: ord, handle: edge?.handle }\n    } else if (score < secondScore) {\n      secondScore = score\n    }\n  }\n  if (best === undefined || secondScore - bestScore < HINT_MARGIN) return undefined\n  return best\n}\n"]}

package/dist/topology/naming/resolve-face.d.ts

@@ -0,0 +1,89 @@
+/**
+ * resolve-face.ts — 面 TopoRef 解析（移植 brepjs shapeRefFns.resolveRef，§2.5）
+ *
+ * 解析策略：
+ * 1. 精确：roleTable[origin][role] 的 hash 命中当前面
+ *    - 恰好 1 → exact；0 → deleted；多个（1→多分裂）→ 只在这几个候选间用 hint 打分
+ * 2. 几何兜底（role 缺失 / 分裂打分未命中）：在当前全部面上按 hint 打分
+ *    - BREP：kernel 现场几何；mesh/primitive：命名槽面 hint 快照
+ * 3. 最优分 > MIN_SCORE 且与次优差 ≥ AMBIGUITY_THRESHOLD → geometric-fallback；
+ *    否则 ambiguous（并列）/ not-found（无超阈值候选）
+ *
+ * 任何一步定不了案就返回三态（调用方抛 TopoRefError），绝不静默拿序号硬取。
+ */
+import type { BrepEngineApi } from '../../brep/engine/primitives.js';
+import type { BrepHandle } from '../../brep/engine/types.js';
+import type { FaceTopoRef, RoleTable, TopoResolution } from './types.js';
+/** 单个面候选：枚举序号 + 会话内 hash +（BREP 句柄 或 面行快照）。 */
+export interface FaceCandidateEntry {
+    /** 面枚举序号（1 起，TopExp::MapShapes 序；与 FaceRow.id 的 `o1.fN` 同序）。 */
+    ordinal: number;
+    /** 会话内 hash（BREP：subShapeHashes；exact 匹配用）。 */
+    hash?: number;
+    /** BREP 现场句柄（存在 → 打分走 kernel 现场几何）。 */
+    handle?: BrepHandle;
+    /** mesh/primitive 面行快照（存在 → 打分走 scoreCandidate row 路径）。 */
+    row?: Readonly<{
+        surfaceType?: string;
+        normal?: readonly number[];
+        center?: readonly number[];
+        area?: number;
+    }>;
+}
+/** 面解析上下文：候选表 + role 表 + kernel（BREP 现场打分用，可为 null）+ 邻接（M3）。 */
+export interface ResolutionContext {
+    /** OCCT 内核（mesh/primitive 路径为 null——打分走 row 快照）。 */
+    readonly kernel: BrepEngineApi | null;
+    /** 当前快照的全部面候选（按枚举序，ordinal 1 起）。 */
+    readonly faces: readonly FaceCandidateEntry[];
+    /** 该 part 的 RoleTable（BREP 链上的 part 有；mesh/primitive 无 → 只走几何兜底）。 */
+    readonly roleTable?: RoleTable;
+    /** 边候选表（ordinal 1 起 ↔ 数组下标 0 起；edge lineage 解析用，M3）。 */
+    readonly edges?: readonly EdgeCandidateEntry[];
+    /** 顶点候选表（ordinal 1 起 ↔ 数组下标 0 起；vertex lineage 解析用，M3）。 */
+    readonly vertices?: readonly VertexCandidateEntry[];
+    /** face ordinal(1 起) → 邻接 face ordinal 列表（derived/布尔缝解析用，M3）。 */
+    readonly faceAdjacency?: ReadonlyArray<readonly number[]>;
+    /** face ordinal(1 起) → 邻接 edge ordinal 列表（edge lineage 用，M3；mesh 为空 → 边 lineage 不可用）。 */
+    readonly faceEdgeAdjacency?: ReadonlyArray<readonly number[]>;
+    /** edge ordinal(1 起) → 邻接 face ordinal 列表（edge lineage 用，M3）。 */
+    readonly edgeFaceAdjacency?: ReadonlyArray<readonly number[]>;
+    /** face ordinal(1 起) → 邻接 vertex ordinal 列表（vertex lineage 用，M3）。 */
+    readonly faceVertexAdjacency?: ReadonlyArray<readonly number[]>;
+}
+/** 边候选：序号 + length/midpoint hint（edge lineage 解析用，M3）。 */
+export interface EdgeCandidateEntry {
+    /** 边枚举序号（1 起）。 */
+    ordinal: number;
+    /** 会话内 hash（exact 匹配预留）。 */
+    hash?: number;
+    /** BREP 现场句柄（存在 → 打分走 kernel 现场几何）。 */
+    handle?: BrepHandle;
+    /** 边几何 hint（length/midpoint；候选裁决用）。 */
+    hint?: {
+        length?: number;
+        midpoint?: readonly number[];
+    };
+}
+/** 顶点候选：序号 + position hint（vertex lineage 解析用，M3）。 */
+export interface VertexCandidateEntry {
+    /** 顶点枚举序号（1 起）。 */
+    ordinal: number;
+    /** 会话内 hash。 */
+    hash?: number;
+    /** BREP 现场句柄。 */
+    handle?: BrepHandle;
+    /** 顶点坐标。 */
+    position?: readonly number[];
+}
+/**
+ * 解析面 TopoRef 到当前快照的序号/句柄。
+ *
+ * @param ref - the face TopoRef to resolve.
+ * @param ctx - the resolution context (candidates + role table + kernel).
+ * @returns the three-state TopoResolution.
+ */
+export declare function resolveFaceTopo(ref: FaceTopoRef, ctx: ResolutionContext): TopoResolution<{
+    handle?: BrepHandle;
+}>;
+//# sourceMappingURL=resolve-face.d.ts.map

package/dist/topology/naming/resolve-face.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-face.d.ts","sourceRoot":"","sources":["../../../src/topology/naming/resolve-face.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAY,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAG/E,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;IACf,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,QAAQ,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QAC1B,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;KACd,CAAC,CAAA;CACH;AAED,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IACrC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC9C,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACnD,iEAAiE;IACjE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IACzD,yFAAyF;IACzF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,aAAa,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IAC7D,iEAAiE;IACjE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,aAAa,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;IAC7D,qEAAqE;IACrE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,aAAa,CAAC,SAAS,MAAM,EAAE,CAAC,CAAA;CAChE;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,uCAAuC;IACvC,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAC7B,CAAA;CACF;AAED,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,gBAAgB;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iBAAiB;IACjB,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,YAAY;IACZ,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAkDD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,iBAAiB,GACrB,cAAc,CAAC;IAAE,MAAM,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC,CA4CzC"}

package/dist/topology/naming/resolve-face.js

@@ -0,0 +1,107 @@
+/**
+ * resolve-face.ts — 面 TopoRef 解析（移植 brepjs shapeRefFns.resolveRef，§2.5）
+ *
+ * 解析策略：
+ * 1. 精确：roleTable[origin][role] 的 hash 命中当前面
+ *    - 恰好 1 → exact；0 → deleted；多个（1→多分裂）→ 只在这几个候选间用 hint 打分
+ * 2. 几何兜底（role 缺失 / 分裂打分未命中）：在当前全部面上按 hint 打分
+ *    - BREP：kernel 现场几何；mesh/primitive：命名槽面 hint 快照
+ * 3. 最优分 > MIN_SCORE 且与次优差 ≥ AMBIGUITY_THRESHOLD → geometric-fallback；
+ *    否则 ambiguous（并列）/ not-found（无超阈值候选）
+ *
+ * 任何一步定不了案就返回三态（调用方抛 TopoRefError），绝不静默拿序号硬取。
+ */
+import { scoreCandidate, MIN_SCORE, AMBIGUITY_THRESHOLD } from './score.js';
+/** 打分候选 → 候选条目（handle 优先、row 兜底，与 score.ts FaceCandidate 同构）。 */
+function toScoringCandidate(c) {
+    return c.handle !== undefined ? { handle: c.handle } : { row: c.row };
+}
+/** 一组候选对 hint 打分：best / secondBest / scored。 */
+function scoreCandidates(hint, candidates, ctx) {
+    let bestScore = -Infinity;
+    let secondBestScore = -Infinity;
+    let best;
+    const scored = [];
+    for (const c of candidates) {
+        const score = scoreCandidate(ctx.kernel, hint, toScoringCandidate(c));
+        if (score > MIN_SCORE)
+            scored.push({ candidate: c, score });
+        if (score > bestScore) {
+            secondBestScore = bestScore;
+            bestScore = score;
+            best = c;
+        }
+        else if (score > secondBestScore) {
+            secondBestScore = score;
+        }
+    }
+    return { scored, best, bestScore, secondBestScore };
+}
+/** 打分结果 → 三态（match / ambiguous / none）。 */
+function outcomeOf(hint, candidates, ctx) {
+    const { scored, best, bestScore, secondBestScore } = scoreCandidates(hint, candidates, ctx);
+    if (best !== undefined && bestScore > MIN_SCORE) {
+        if (bestScore - secondBestScore < AMBIGUITY_THRESHOLD && scored.length > 1) {
+            const competitive = scored
+                .filter((e) => e.score >= bestScore - AMBIGUITY_THRESHOLD)
+                .map((e) => e.candidate);
+            return { kind: 'ambiguous', candidates: competitive };
+        }
+        return { kind: 'match', candidate: best };
+    }
+    return { kind: 'none' };
+}
+/**
+ * 解析面 TopoRef 到当前快照的序号/句柄。
+ *
+ * @param ref - the face TopoRef to resolve.
+ * @param ctx - the resolution context (candidates + role table + kernel).
+ * @returns the three-state TopoResolution.
+ */
+export function resolveFaceTopo(ref, ctx) {
+    // 1. 精确：role 的追踪 hash 在候选面中命中
+    const targetHashes = ctx.roleTable?.get(ref.origin)?.get(ref.role);
+    if (targetHashes !== undefined && targetHashes.length > 0) {
+        const survivors = ctx.faces.filter((f) => f.hash !== undefined && targetHashes.includes(f.hash));
+        if (survivors.length === 1) {
+            const [only] = survivors;
+            if (only) {
+                return { ok: true, entity: { handle: only.handle }, ordinal: only.ordinal, confidence: 'exact' };
+            }
+        }
+        else if (survivors.length === 0) {
+            return { ok: false, reason: 'deleted' };
+        }
+        else {
+            // 1→多分裂：只在后继内裁决，不与全形状竞争
+            const split = outcomeOf(ref.hint, survivors, ctx);
+            if (split.kind === 'match') {
+                return {
+                    ok: true,
+                    entity: { handle: split.candidate.handle },
+                    ordinal: split.candidate.ordinal,
+                    confidence: 'geometric-fallback',
+                };
+            }
+            if (split.kind === 'ambiguous') {
+                return { ok: false, reason: 'ambiguous', candidatesOrdinal: split.candidates.map((c) => c.ordinal) };
+            }
+            // 'none' → 落到全形状几何兜底
+        }
+    }
+    // 2. 几何兜底：全形状打分
+    const all = outcomeOf(ref.hint, ctx.faces, ctx);
+    if (all.kind === 'match') {
+        return {
+            ok: true,
+            entity: { handle: all.candidate.handle },
+            ordinal: all.candidate.ordinal,
+            confidence: 'geometric-fallback',
+        };
+    }
+    if (all.kind === 'ambiguous') {
+        return { ok: false, reason: 'ambiguous', candidatesOrdinal: all.candidates.map((c) => c.ordinal) };
+    }
+    return { ok: false, reason: 'not-found' };
+}
+//# sourceMappingURL=resolve-face.js.map

package/dist/topology/naming/resolve-face.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-face.js","sourceRoot":"","sources":["../../../src/topology/naming/resolve-face.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * resolve-face.ts — 面 TopoRef 解析（移植 brepjs shapeRefFns.resolveRef，§2.5）\n *\n * 解析策略：\n * 1. 精确：roleTable[origin][role] 的 hash 命中当前面\n *    - 恰好 1 → exact；0 → deleted；多个（1→多分裂）→ 只在这几个候选间用 hint 打分\n * 2. 几何兜底（role 缺失 / 分裂打分未命中）：在当前全部面上按 hint 打分\n *    - BREP：kernel 现场几何；mesh/primitive：命名槽面 hint 快照\n * 3. 最优分 > MIN_SCORE 且与次优差 ≥ AMBIGUITY_THRESHOLD → geometric-fallback；\n *    否则 ambiguous（并列）/ not-found（无超阈值候选）\n *\n * 任何一步定不了案就返回三态（调用方抛 TopoRefError），绝不静默拿序号硬取。\n */\n\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { BrepHandle } from '../../brep/engine/types'\nimport type { FaceHint, FaceTopoRef, RoleTable, TopoResolution } from './types'\nimport { scoreCandidate, MIN_SCORE, AMBIGUITY_THRESHOLD } from './score'\n\n/** 单个面候选：枚举序号 + 会话内 hash +（BREP 句柄 或 面行快照）。 */\nexport interface FaceCandidateEntry {\n  /** 面枚举序号（1 起，TopExp::MapShapes 序；与 FaceRow.id 的 `o1.fN` 同序）。 */\n  ordinal: number\n  /** 会话内 hash（BREP：subShapeHashes；exact 匹配用）。 */\n  hash?: number\n  /** BREP 现场句柄（存在 → 打分走 kernel 现场几何）。 */\n  handle?: BrepHandle\n  /** mesh/primitive 面行快照（存在 → 打分走 scoreCandidate row 路径）。 */\n  row?: Readonly<{\n    surfaceType?: string\n    normal?: readonly number[]\n    center?: readonly number[]\n    area?: number\n  }>\n}\n\n/** 面解析上下文：候选表 + role 表 + kernel（BREP 现场打分用，可为 null）+ 邻接（M3）。 */\nexport interface ResolutionContext {\n  /** OCCT 内核（mesh/primitive 路径为 null——打分走 row 快照）。 */\n  readonly kernel: BrepEngineApi | null\n  /** 当前快照的全部面候选（按枚举序，ordinal 1 起）。 */\n  readonly faces: readonly FaceCandidateEntry[]\n  /** 该 part 的 RoleTable（BREP 链上的 part 有；mesh/primitive 无 → 只走几何兜底）。 */\n  readonly roleTable?: RoleTable\n  /** 边候选表（ordinal 1 起 ↔ 数组下标 0 起；edge lineage 解析用，M3）。 */\n  readonly edges?: readonly EdgeCandidateEntry[]\n  /** 顶点候选表（ordinal 1 起 ↔ 数组下标 0 起；vertex lineage 解析用，M3）。 */\n  readonly vertices?: readonly VertexCandidateEntry[]\n  /** face ordinal(1 起) → 邻接 face ordinal 列表（derived/布尔缝解析用，M3）。 */\n  readonly faceAdjacency?: ReadonlyArray<readonly number[]>\n  /** face ordinal(1 起) → 邻接 edge ordinal 列表（edge lineage 用，M3；mesh 为空 → 边 lineage 不可用）。 */\n  readonly faceEdgeAdjacency?: ReadonlyArray<readonly number[]>\n  /** edge ordinal(1 起) → 邻接 face ordinal 列表（edge lineage 用，M3）。 */\n  readonly edgeFaceAdjacency?: ReadonlyArray<readonly number[]>\n  /** face ordinal(1 起) → 邻接 vertex ordinal 列表（vertex lineage 用，M3）。 */\n  readonly faceVertexAdjacency?: ReadonlyArray<readonly number[]>\n}\n\n/** 边候选：序号 + length/midpoint hint（edge lineage 解析用，M3）。 */\nexport interface EdgeCandidateEntry {\n  /** 边枚举序号（1 起）。 */\n  ordinal: number\n  /** 会话内 hash（exact 匹配预留）。 */\n  hash?: number\n  /** BREP 现场句柄（存在 → 打分走 kernel 现场几何）。 */\n  handle?: BrepHandle\n  /** 边几何 hint（length/midpoint；候选裁决用）。 */\n  hint?: {\n    length?: number\n    midpoint?: readonly number[]\n  }\n}\n\n/** 顶点候选：序号 + position hint（vertex lineage 解析用，M3）。 */\nexport interface VertexCandidateEntry {\n  /** 顶点枚举序号（1 起）。 */\n  ordinal: number\n  /** 会话内 hash。 */\n  hash?: number\n  /** BREP 现场句柄。 */\n  handle?: BrepHandle\n  /** 顶点坐标。 */\n  position?: readonly number[]\n}\n\n/** 打分候选 → 候选条目（handle 优先、row 兜底，与 score.ts FaceCandidate 同构）。 */\nfunction toScoringCandidate(c: FaceCandidateEntry): { handle?: BrepHandle; row?: FaceCandidateEntry['row'] } {\n  return c.handle !== undefined ? { handle: c.handle } : { row: c.row }\n}\n\n/** 一组候选对 hint 打分：best / secondBest / scored。 */\nfunction scoreCandidates(\n  hint: FaceHint,\n  candidates: readonly FaceCandidateEntry[],\n  ctx: ResolutionContext,\n): { scored: Array<{ candidate: FaceCandidateEntry; score: number }>; best?: FaceCandidateEntry; bestScore: number; secondBestScore: number } {\n  let bestScore = -Infinity\n  let secondBestScore = -Infinity\n  let best: FaceCandidateEntry | undefined\n  const scored: Array<{ candidate: FaceCandidateEntry; score: number }> = []\n  for (const c of candidates) {\n    const score = scoreCandidate(ctx.kernel, hint, toScoringCandidate(c))\n    if (score > MIN_SCORE) scored.push({ candidate: c, score })\n    if (score > bestScore) {\n      secondBestScore = bestScore\n      bestScore = score\n      best = c\n    } else if (score > secondBestScore) {\n      secondBestScore = score\n    }\n  }\n  return { scored, best, bestScore, secondBestScore }\n}\n\n/** 打分结果 → 三态（match / ambiguous / none）。 */\nfunction outcomeOf(\n  hint: FaceHint,\n  candidates: readonly FaceCandidateEntry[],\n  ctx: ResolutionContext,\n): { kind: 'match'; candidate: FaceCandidateEntry } | { kind: 'ambiguous'; candidates: FaceCandidateEntry[] } | { kind: 'none' } {\n  const { scored, best, bestScore, secondBestScore } = scoreCandidates(hint, candidates, ctx)\n  if (best !== undefined && bestScore > MIN_SCORE) {\n    if (bestScore - secondBestScore < AMBIGUITY_THRESHOLD && scored.length > 1) {\n      const competitive = scored\n        .filter((e) => e.score >= bestScore - AMBIGUITY_THRESHOLD)\n        .map((e) => e.candidate)\n      return { kind: 'ambiguous', candidates: competitive }\n    }\n    return { kind: 'match', candidate: best }\n  }\n  return { kind: 'none' }\n}\n\n/**\n * 解析面 TopoRef 到当前快照的序号/句柄。\n *\n * @param ref - the face TopoRef to resolve.\n * @param ctx - the resolution context (candidates + role table + kernel).\n * @returns the three-state TopoResolution.\n */\nexport function resolveFaceTopo(\n  ref: FaceTopoRef,\n  ctx: ResolutionContext,\n): TopoResolution<{ handle?: BrepHandle }> {\n  // 1. 精确：role 的追踪 hash 在候选面中命中\n  const targetHashes = ctx.roleTable?.get(ref.origin)?.get(ref.role)\n  if (targetHashes !== undefined && targetHashes.length > 0) {\n    const survivors = ctx.faces.filter((f) => f.hash !== undefined && targetHashes.includes(f.hash))\n    if (survivors.length === 1) {\n      const [only] = survivors\n      if (only) {\n        return { ok: true, entity: { handle: only.handle }, ordinal: only.ordinal, confidence: 'exact' }\n      }\n    } else if (survivors.length === 0) {\n      return { ok: false, reason: 'deleted' }\n    } else {\n      // 1→多分裂：只在后继内裁决，不与全形状竞争\n      const split = outcomeOf(ref.hint, survivors, ctx)\n      if (split.kind === 'match') {\n        return {\n          ok: true,\n          entity: { handle: split.candidate.handle },\n          ordinal: split.candidate.ordinal,\n          confidence: 'geometric-fallback',\n        }\n      }\n      if (split.kind === 'ambiguous') {\n        return { ok: false, reason: 'ambiguous', candidatesOrdinal: split.candidates.map((c) => c.ordinal) }\n      }\n      // 'none' → 落到全形状几何兜底\n    }\n  }\n\n  // 2. 几何兜底：全形状打分\n  const all = outcomeOf(ref.hint, ctx.faces, ctx)\n  if (all.kind === 'match') {\n    return {\n      ok: true,\n      entity: { handle: all.candidate.handle },\n      ordinal: all.candidate.ordinal,\n      confidence: 'geometric-fallback',\n    }\n  }\n  if (all.kind === 'ambiguous') {\n    return { ok: false, reason: 'ambiguous', candidatesOrdinal: all.candidates.map((c) => c.ordinal) }\n  }\n  return { ok: false, reason: 'not-found' }\n}\n"]}

package/dist/topology/naming/resolve-vertex.d.ts

@@ -0,0 +1,27 @@
+/**
+ * resolve-vertex.ts — 顶点 TopoRef 解析（移植 brepjs vertexRefFns，§4.4）
+ *
+ * 顶点 = ≥3 邻面之交。VertexTopoRef.faces 是 RoleQualifier[]（faijs 扩展带 origin）。
+ *
+ * 解析 = 各 role 解析到当前面 → 面顶点交集（face→vertex 邻接）→ 公共顶点：
+ * - 1 个 → exact
+ * - 多个 → position hint 裁决
+ * - 无 / role 缺失 → not-found
+ *
+ * 顶点类型在 M3 一并移植但**不接 UI、不进 manifest**（选择器无 vertex 表），
+ * 仅为倒角/定位类 op 的内部参数预留（§4.4）。
+ */
+import type { BrepHandle } from '../../brep/engine/types.js';
+import type { TopoResolution, VertexTopoRef } from './types.js';
+import type { ResolutionContext } from './resolve-face.js';
+/**
+ * 解析顶点 TopoRef 到当前快照的顶点序号。
+ *
+ * @param ref - the vertex TopoRef to resolve.
+ * @param ctx - the resolution context (needs faceVertexAdjacency for lineage).
+ * @returns the three-state TopoResolution with the vertex ordinal.
+ */
+export declare function resolveVertexTopo(ref: VertexTopoRef, ctx: ResolutionContext): TopoResolution<{
+    handle?: BrepHandle;
+}>;
+//# sourceMappingURL=resolve-vertex.d.ts.map

package/dist/topology/naming/resolve-vertex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-vertex.d.ts","sourceRoot":"","sources":["../../../src/topology/naming/resolve-vertex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,KAAK,EAAsB,iBAAiB,EAAwB,MAAM,gBAAgB,CAAA;AAajG;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,iBAAiB,GACrB,cAAc,CAAC;IAAE,MAAM,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC,CA6CzC"}