@faicad/faijs 0.13.0

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

@@ -0,0 +1,115 @@
+/**
+ * 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 { facesForQualifier } from './resolve-edge.js';
+/** 一个角至少需要这么多面才能钉住唯一顶点。 */
+const MIN_VERTEX_FACES = 3;
+/** Hint 距离比这更近视为不可区分（→ ambiguous）。 */
+const HINT_MARGIN = 1e-6;
+/** 顶点序号 → 顶点候选。 */
+function vertexOf(ctx, ordinal) {
+    return ctx.vertices?.find((v) => v.ordinal === ordinal);
+}
+/**
+ * 解析顶点 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 function resolveVertexTopo(ref, ctx) {
+    if (ref.faces.length < MIN_VERTEX_FACES) {
+        return { ok: false, reason: 'not-found' };
+    }
+    // 各 role 的面集合
+    const faceSets = [];
+    for (const qualifier of ref.faces) {
+        const faces = facesForQualifier(qualifier, ctx);
+        if (faces.length === 0)
+            return { ok: false, reason: 'not-found' };
+        faceSets.push(faces);
+    }
+    // 面顶点交集（face→vertex 邻接）
+    let common;
+    for (const faces of faceSets) {
+        const verts = new Set();
+        for (const f of faces) {
+            for (const v of ctx.faceVertexAdjacency?.[f.ordinal - 1] ?? [])
+                verts.add(v);
+        }
+        common = common === undefined ? verts : intersect(common, verts);
+        if (common.size === 0)
+            return { ok: false, reason: 'not-found' };
+    }
+    if (common === undefined || common.size === 0) {
+        return { ok: false, reason: 'not-found' };
+    }
+    const unique = [...common];
+    if (unique.length === 1) {
+        const [only] = unique;
+        if (only !== undefined) {
+            const v = vertexOf(ctx, only);
+            return { ok: true, entity: { handle: v?.handle }, ordinal: only, confidence: 'exact' };
+        }
+    }
+    if (unique.length > 1) {
+        const best = nearestVertex(unique, ref.hint.position, ctx);
+        if (best !== undefined) {
+            return { ok: true, entity: { handle: best.handle }, ordinal: best.ordinal, confidence: 'geometric-fallback' };
+        }
+        return { ok: false, reason: 'ambiguous', candidatesOrdinal: unique };
+    }
+    return { ok: false, reason: 'not-found' };
+}
+/** 集合交集。 */
+function intersect(a, b) {
+    const out = new Set();
+    for (const h of a)
+        if (b.has(h))
+            out.add(h);
+    return out;
+}
+/** 距 hint 位置最近的候选顶点；并列/无信号 → undefined（ambiguous）。 */
+function nearestVertex(ordinals, position, ctx) {
+    if (position === undefined)
+        return undefined;
+    let best;
+    let bestDist = Infinity;
+    let secondDist = Infinity;
+    for (const ord of ordinals) {
+        const v = vertexOf(ctx, ord);
+        const p = v?.position;
+        if (p === undefined)
+            continue;
+        const d = distance(p, position);
+        if (d < bestDist) {
+            secondDist = bestDist;
+            bestDist = d;
+            best = v;
+        }
+        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-vertex.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-vertex.js","sourceRoot":"","sources":["../../../src/topology/naming/resolve-vertex.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * resolve-vertex.ts — 顶点 TopoRef 解析（移植 brepjs vertexRefFns，§4.4）\n *\n * 顶点 = ≥3 邻面之交。VertexTopoRef.faces 是 RoleQualifier[]（faijs 扩展带 origin）。\n *\n * 解析 = 各 role 解析到当前面 → 面顶点交集（face→vertex 邻接）→ 公共顶点：\n * - 1 个 → exact\n * - 多个 → position hint 裁决\n * - 无 / role 缺失 → not-found\n *\n * 顶点类型在 M3 一并移植但**不接 UI、不进 manifest**（选择器无 vertex 表），\n * 仅为倒角/定位类 op 的内部参数预留（§4.4）。\n */\n\nimport type { BrepHandle } from '../../brep/engine/types'\nimport type { TopoResolution, VertexTopoRef } from './types'\nimport type { FaceCandidateEntry, ResolutionContext, VertexCandidateEntry } from './resolve-face'\nimport { facesForQualifier } from './resolve-edge'\n\n/** 一个角至少需要这么多面才能钉住唯一顶点。 */\nconst MIN_VERTEX_FACES = 3\n/** Hint 距离比这更近视为不可区分（→ ambiguous）。 */\nconst HINT_MARGIN = 1e-6\n\n/** 顶点序号 → 顶点候选。 */\nfunction vertexOf(ctx: ResolutionContext, ordinal: number): VertexCandidateEntry | undefined {\n  return ctx.vertices?.find((v) => v.ordinal === ordinal)\n}\n\n/**\n * 解析顶点 TopoRef 到当前快照的顶点序号。\n *\n * @param ref - the vertex TopoRef to resolve.\n * @param ctx - the resolution context (needs faceVertexAdjacency for lineage).\n * @returns the three-state TopoResolution with the vertex ordinal.\n */\nexport function resolveVertexTopo(\n  ref: VertexTopoRef,\n  ctx: ResolutionContext,\n): TopoResolution<{ handle?: BrepHandle }> {\n  if (ref.faces.length < MIN_VERTEX_FACES) {\n    return { ok: false, reason: 'not-found' }\n  }\n\n  // 各 role 的面集合\n  const faceSets: FaceCandidateEntry[][] = []\n  for (const qualifier of ref.faces) {\n    const faces = facesForQualifier(qualifier, ctx)\n    if (faces.length === 0) return { ok: false, reason: 'not-found' }\n    faceSets.push(faces)\n  }\n\n  // 面顶点交集（face→vertex 邻接）\n  let common: Set<number> | undefined\n  for (const faces of faceSets) {\n    const verts = new Set<number>()\n    for (const f of faces) {\n      for (const v of ctx.faceVertexAdjacency?.[f.ordinal - 1] ?? []) verts.add(v)\n    }\n    common = common === undefined ? verts : intersect(common, verts)\n    if (common.size === 0) return { ok: false, reason: 'not-found' }\n  }\n  if (common === undefined || common.size === 0) {\n    return { ok: false, reason: 'not-found' }\n  }\n\n  const unique = [...common]\n  if (unique.length === 1) {\n    const [only] = unique\n    if (only !== undefined) {\n      const v = vertexOf(ctx, only)\n      return { ok: true, entity: { handle: v?.handle }, ordinal: only, confidence: 'exact' }\n    }\n  }\n\n  if (unique.length > 1) {\n    const best = nearestVertex(unique, ref.hint.position, ctx)\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: unique }\n  }\n\n  return { ok: false, reason: 'not-found' }\n}\n\n/** 集合交集。 */\nfunction intersect(a: Set<number>, b: Set<number>): Set<number> {\n  const out = new Set<number>()\n  for (const h of a) if (b.has(h)) out.add(h)\n  return out\n}\n\n/** 距 hint 位置最近的候选顶点；并列/无信号 → undefined（ambiguous）。 */\nfunction nearestVertex(\n  ordinals: readonly number[],\n  position: readonly number[] | undefined,\n  ctx: ResolutionContext,\n): VertexCandidateEntry | undefined {\n  if (position === undefined) return undefined\n  let best: VertexCandidateEntry | undefined\n  let bestDist = Infinity\n  let secondDist = Infinity\n  for (const ord of ordinals) {\n    const v = vertexOf(ctx, ord)\n    const p = v?.position\n    if (p === undefined) continue\n    const d = distance(p, position)\n    if (d < bestDist) {\n      secondDist = bestDist\n      bestDist = d\n      best = v\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/resolver.d.ts

@@ -0,0 +1,40 @@
+/**
+ * resolver.ts — 统一 ResolutionContext + resolveTopoRef（§2.5/§3.6）
+ *
+ * 四类 TopoRef 的统一入口。解析上下文来自「输入 Shape 的命名槽」：
+ * - BREP：roleTable（hash 键）+ 活句柄（kernel 现场几何）
+ * - mesh/primitive：面 hint 快照（setTopology 注入时提炼写入 Shape 槽）
+ *
+ * M2 只接 face（§4.1 最高优先）；edge/vertex/derived 的解析在 M3 接入
+ * （resolve-edge.ts / resolve-vertex.ts / resolve-derived.ts）。
+ *
+ * 任何一步定不了案 → 抛 TopoRefError（三态错误码），绝不静默拿序号硬取。
+ */
+import { TopoRefError, type TopoRef } from './types.js';
+import { type ResolutionContext } from './resolve-face.js';
+export type { ResolutionContext };
+/** 解析结果（实体 = 序号 + 可选活句柄）。 */
+export type ResolvedTopoEntity = {
+    handle?: unknown;
+    ordinal: number;
+};
+/**
+ * 解析一个 TopoRef 到当前快照的实体（序号 + 句柄）。
+ *
+ * 失败抛 TopoRefError（带错误码），由调用方纳入 args 校验——禁止静默降级。
+ *
+ * @param ref - the TopoRef to resolve.
+ * @param ctx - the resolution context for the input shape the ref targets.
+ * @returns the resolved entity (ordinal + optional live handle).
+ */
+export declare function resolveTopoRef(ref: TopoRef, ctx: ResolutionContext): ResolvedTopoEntity;
+/**
+ * 三态失败 → TopoRefError（§3.6 错误码）。
+ *
+ * @param reason - the failure reason.
+ * @param kind - the TopoRef kind.
+ * @param candidates - optional tied candidate ordinals (ambiguous).
+ * @returns the TopoRefError with the proper error code.
+ */
+export declare function buildTopoError(reason: 'deleted' | 'ambiguous' | 'not-found', kind: TopoRef['kind'], candidates?: readonly number[]): TopoRefError;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/topology/naming/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../../src/topology/naming/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAsB,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AACxE,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAKxE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAEjC,6BAA6B;AAC7B,MAAM,MAAM,kBAAkB,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtE;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,kBAAkB,CAevF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,EAC7C,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,EACrB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAC7B,YAAY,CAEd"}

package/dist/topology/naming/resolver.js

@@ -0,0 +1,71 @@
+/**
+ * resolver.ts — 统一 ResolutionContext + resolveTopoRef（§2.5/§3.6）
+ *
+ * 四类 TopoRef 的统一入口。解析上下文来自「输入 Shape 的命名槽」：
+ * - BREP：roleTable（hash 键）+ 活句柄（kernel 现场几何）
+ * - mesh/primitive：面 hint 快照（setTopology 注入时提炼写入 Shape 槽）
+ *
+ * M2 只接 face（§4.1 最高优先）；edge/vertex/derived 的解析在 M3 接入
+ * （resolve-edge.ts / resolve-vertex.ts / resolve-derived.ts）。
+ *
+ * 任何一步定不了案 → 抛 TopoRefError（三态错误码），绝不静默拿序号硬取。
+ */
+import { TopoRefError } from './types.js';
+import { resolveFaceTopo } from './resolve-face.js';
+import { resolveEdgeTopo } from './resolve-edge.js';
+import { resolveVertexTopo } from './resolve-vertex.js';
+import { resolveDerivedFaceTopo } from './resolve-derived.js';
+/**
+ * 解析一个 TopoRef 到当前快照的实体（序号 + 句柄）。
+ *
+ * 失败抛 TopoRefError（带错误码），由调用方纳入 args 校验——禁止静默降级。
+ *
+ * @param ref - the TopoRef to resolve.
+ * @param ctx - the resolution context for the input shape the ref targets.
+ * @returns the resolved entity (ordinal + optional live handle).
+ */
+export function resolveTopoRef(ref, ctx) {
+    let resolution;
+    if (ref.kind === 'face') {
+        resolution = resolveFaceTopo(ref, ctx);
+    }
+    else if (ref.kind === 'edge') {
+        resolution = resolveEdgeTopo(ref, ctx);
+    }
+    else if (ref.kind === 'vertex') {
+        resolution = resolveVertexTopo(ref, ctx);
+    }
+    else {
+        resolution = resolveDerivedFaceTopo(ref, ctx);
+    }
+    if (!resolution.ok) {
+        throw buildTopoError(resolution.reason, ref.kind, resolution.candidatesOrdinal);
+    }
+    return { handle: resolution.entity.handle, ordinal: resolution.ordinal };
+}
+/**
+ * 三态失败 → TopoRefError（§3.6 错误码）。
+ *
+ * @param reason - the failure reason.
+ * @param kind - the TopoRef kind.
+ * @param candidates - optional tied candidate ordinals (ambiguous).
+ * @returns the TopoRefError with the proper error code.
+ */
+export function buildTopoError(reason, kind, candidates) {
+    return new TopoRefError(codeFor(reason), kind, `topo ref (${kind}) ${messageFor(reason)}`, candidates);
+}
+function codeFor(reason) {
+    if (reason === 'deleted')
+        return 'E_TOPO_DELETED';
+    if (reason === 'ambiguous')
+        return 'E_TOPO_AMBIGUOUS';
+    return 'E_TOPO_NOT_FOUND';
+}
+function messageFor(reason) {
+    if (reason === 'deleted')
+        return 'was deleted by an upstream edit';
+    if (reason === 'ambiguous')
+        return 'matched multiple candidates (ambiguous)';
+    return 'not found in the current shape';
+}
+//# sourceMappingURL=resolver.js.map

package/dist/topology/naming/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/topology/naming/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAoC,MAAM,SAAS,CAAA;AACxE,OAAO,EAAE,eAAe,EAA0B,MAAM,gBAAgB,CAAA;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAO1D;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,GAAsB;IACjE,IAAI,UAAU,CAAA;IACd,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACxB,UAAU,GAAG,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACxC,CAAC;SAAM,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC/B,UAAU,GAAG,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACxC,CAAC;SAAM,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACjC,UAAU,GAAG,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC1C,CAAC;SAAM,CAAC;QACN,UAAU,GAAG,sBAAsB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC/C,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC;QACnB,MAAM,cAAc,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAA;IACjF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,MAA6B,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,CAAA;AACjG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,MAA6C,EAC7C,IAAqB,EACrB,UAA8B;IAE9B,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,aAAa,IAAI,KAAK,UAAU,CAAC,MAAM,CAAC,EAAE,EAAE,UAAU,CAAC,CAAA;AACxG,CAAC;AAED,SAAS,OAAO,CAAC,MAA6C;IAC5D,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,gBAAgB,CAAA;IACjD,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,kBAAkB,CAAA;IACrD,OAAO,kBAAkB,CAAA;AAC3B,CAAC;AAED,SAAS,UAAU,CAAC,MAA6C;IAC/D,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,iCAAiC,CAAA;IAClE,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,yCAAyC,CAAA;IAC5E,OAAO,gCAAgC,CAAA;AACzC,CAAC","sourcesContent":["/**\n * resolver.ts — 统一 ResolutionContext + resolveTopoRef（§2.5/§3.6）\n *\n * 四类 TopoRef 的统一入口。解析上下文来自「输入 Shape 的命名槽」：\n * - BREP：roleTable（hash 键）+ 活句柄（kernel 现场几何）\n * - mesh/primitive：面 hint 快照（setTopology 注入时提炼写入 Shape 槽）\n *\n * M2 只接 face（§4.1 最高优先）；edge/vertex/derived 的解析在 M3 接入\n * （resolve-edge.ts / resolve-vertex.ts / resolve-derived.ts）。\n *\n * 任何一步定不了案 → 抛 TopoRefError（三态错误码），绝不静默拿序号硬取。\n */\n\nimport { TopoRefError, type TopoErrorCode, type TopoRef } from './types'\nimport { resolveFaceTopo, type ResolutionContext } from './resolve-face'\nimport { resolveEdgeTopo } from './resolve-edge'\nimport { resolveVertexTopo } from './resolve-vertex'\nimport { resolveDerivedFaceTopo } from './resolve-derived'\n\nexport type { ResolutionContext }\n\n/** 解析结果（实体 = 序号 + 可选活句柄）。 */\nexport type ResolvedTopoEntity = { handle?: unknown; ordinal: number }\n\n/**\n * 解析一个 TopoRef 到当前快照的实体（序号 + 句柄）。\n *\n * 失败抛 TopoRefError（带错误码），由调用方纳入 args 校验——禁止静默降级。\n *\n * @param ref - the TopoRef to resolve.\n * @param ctx - the resolution context for the input shape the ref targets.\n * @returns the resolved entity (ordinal + optional live handle).\n */\nexport function resolveTopoRef(ref: TopoRef, ctx: ResolutionContext): ResolvedTopoEntity {\n  let resolution\n  if (ref.kind === 'face') {\n    resolution = resolveFaceTopo(ref, ctx)\n  } else if (ref.kind === 'edge') {\n    resolution = resolveEdgeTopo(ref, ctx)\n  } else if (ref.kind === 'vertex') {\n    resolution = resolveVertexTopo(ref, ctx)\n  } else {\n    resolution = resolveDerivedFaceTopo(ref, ctx)\n  }\n  if (!resolution.ok) {\n    throw buildTopoError(resolution.reason, ref.kind, resolution.candidatesOrdinal)\n  }\n  return { handle: resolution.entity.handle as unknown | undefined, ordinal: resolution.ordinal }\n}\n\n/**\n * 三态失败 → TopoRefError（§3.6 错误码）。\n *\n * @param reason - the failure reason.\n * @param kind - the TopoRef kind.\n * @param candidates - optional tied candidate ordinals (ambiguous).\n * @returns the TopoRefError with the proper error code.\n */\nexport function buildTopoError(\n  reason: 'deleted' | 'ambiguous' | 'not-found',\n  kind: TopoRef['kind'],\n  candidates?: readonly number[],\n): TopoRefError {\n  return new TopoRefError(codeFor(reason), kind, `topo ref (${kind}) ${messageFor(reason)}`, candidates)\n}\n\nfunction codeFor(reason: 'deleted' | 'ambiguous' | 'not-found'): TopoErrorCode {\n  if (reason === 'deleted') return 'E_TOPO_DELETED'\n  if (reason === 'ambiguous') return 'E_TOPO_AMBIGUOUS'\n  return 'E_TOPO_NOT_FOUND'\n}\n\nfunction messageFor(reason: 'deleted' | 'ambiguous' | 'not-found'): string {\n  if (reason === 'deleted') return 'was deleted by an upstream edit'\n  if (reason === 'ambiguous') return 'matched multiple candidates (ambiguous)'\n  return 'not found in the current shape'\n}\n"]}

package/dist/topology/naming/roles.d.ts

@@ -0,0 +1,111 @@
+/**
+ * roles.ts — RoleTable 的生命周期纯逻辑（§3.2/§3.3/§3.4 移植 + 改造）
+ *
+ * - `assignRoles`：链根建表。语义优先（box/cylinder/cone/sphere 按法向/曲面类型
+ *   给稳定名）、位置兜底（`${opType}:face_${i}`，保证每面必有 role）。
+ * - `propagateRoles`：沿一次 hash 演化推进表（移植 brepjs updateRoles/nextHashes：
+ *   deleted 丢弃、modified 全部后继替换、未变保留；generated 刻意不消费）。
+ * - `mergeRoleTables`：布尔合流——A/B 两个来源的表各自传播后合并，缝面以本次
+ *   语句 LHS 为新 origin 给位置名（§3.4）。
+ * - `roleOfOrdinal`：序号 → role 反查（§3.7 生成 ExecutionResult.naming 用）。
+ */
+import type { BrepEngineApi } from '../../brep/engine/primitives.js';
+import type { BrepHandle } from '../../brep/engine/types.js';
+import type { HashEvolution } from '../../brep/face-evolution.js';
+import type { PartName } from '../../identity.js';
+import type { RoleTable } from './types.js';
+/** 主轴判定阈值：abs(component) > 0.9 视为轴对齐。 */
+export declare const AXIS_THRESHOLD = 0.9;
+/** Re-export：hash 键演化（decodeHashEvolution 产出，见 brep/face-evolution.ts §2.4）。 */
+export type { HashEvolution };
+/**
+ * box 面：按外法向主轴给语义名。
+ *
+ * @param n - the outward normal of the face (unit length expected).
+ * @returns the cardinal role ('box:top' etc.), or undefined when no axis dominates.
+ */
+export declare function boxRoleFromNormal(n: readonly [number, number, number]): string | undefined;
+/**
+ * 给链根 shape 建 RoleTable（单个 origin 的表；§3.2）。
+ *
+ * 语义优先、位置兜底；assign 时只保留 hash + hint，不保留面句柄
+ * （避免 wasm 句柄生命周期泄漏——读完几何量即弃）。
+ *
+ * @param kernel - the OCCT kernel.
+ * @param shape - the chain-root solid (primitive / load STEP 产物).
+ * @param opType - the chain-root operation type ('box'/'cylinder'/... 或 part 变量名).
+ * @returns RoleTable — 只有 origin=opType 一个键（调用方负责包装成多 origin 表）。
+ */
+export declare function assignRoles(kernel: BrepEngineApi, shape: BrepHandle, opType: string): Map<string, number[]>;
+/**
+ * 把一个 role 的 hash 列表推进一个演化步（移植 brepjs nextHashes）：
+ * deleted 丢弃、modified 全部后继替换（1→多保留全部分片）、未变保留。
+ *
+ * @param hashes - the role's current face hashes.
+ * @param evolution - the hash-keyed evolution record.
+ * @returns the successor hashes.
+ */
+export declare function nextHashes(hashes: readonly number[], evolution: HashEvolution): number[];
+/**
+ * 沿一次 hash 演化推进某个 origin 的 role 表（移植 brepjs updateRoles）。
+ *
+ * generated 刻意不消费（§1.3 事实：occt 系 generated hash 指向中间形、实测 0 存活）；
+ * 生成面由 DerivedFaceTopoRef 以 lineage 命名。
+ *
+ * @param roles - the input role table (may be the single-origin map or full table).
+ * @param origin - the origin whose roles to advance.
+ * @param evolution - the hash-keyed evolution record for this op.
+ * @returns a NEW RoleTable with the origin's roles advanced (immutable style).
+ */
+export declare function propagateRoles(roles: RoleTable, origin: PartName, evolution: HashEvolution): RoleTable;
+/**
+ * 沿一次 hash 演化推进 RoleTable 的**所有** origin（单父 op 用，§3.3）。
+ *
+ * 变换/倒角等单输入 op 只产生一份演化，作用在输入表的所有 origin 上
+ * （布尔合流后的表含多个 origin，刚体变换下面 1:1 保留全部）。
+ *
+ * @param roles - the input role table (possibly multi-origin after a merge).
+ * @param evolution - the hash-keyed evolution record for this op.
+ * @returns a NEW RoleTable with every origin's roles advanced.
+ */
+export declare function propagateAllOrigins(roles: RoleTable, evolution: HashEvolution): RoleTable;
+/**
+ * 布尔合流：合并两个来源的 role 表（§3.4，faijs 对 brepjs 的必要扩展）。
+ *
+ * 对 A、B 两张 hash 演化分别传播各自的表后合并；布尔新生成的缝面/刃面
+ * 以本次布尔语句的 LHS 变量名（= outPart）为新 origin，位置名命名。
+ *
+ * @param targetTable - the target part's role table.
+ * @param targetEvo - the target-side hash evolution (A 的 inHash 去向).
+ * @param toolTable - the tool part's role table.
+ * @param toolEvo - the tool-side hash evolution (B 的 inHash 去向).
+ * @param outPart - the boolean statement's LHS variable name (new origin for seam faces).
+ * @param seamCount - how many seam/generated faces to name positionally (0 表示不补).
+ * @returns the merged RoleTable.
+ */
+export declare function mergeRoleTables(targetTable: RoleTable, targetEvo: HashEvolution, toolTable: RoleTable, toolEvo: HashEvolution, outPart: PartName, seamCount: number): RoleTable;
+/**
+ * 布尔缝面/刃面的位置名角色表（§3.4：以本次语句 LHS 为新 origin）。
+ * 缝面的 hash 来自结果形状的 subShapeHashes（按生成序），此处仅分配 role 名——
+ * hash 由调用方在拿到结果 shape 后填入（seam 面 hash 需结果 subShapeHashes 对照）。
+ *
+ * @param outPart - the boolean statement's LHS variable name.
+ * @param count - the number of seam faces to name.
+ * @returns a single-origin role map with positional roles.
+ */
+export declare function assignGeneratedPositionalRoles(outPart: string, count: number): Map<string, number[]>;
+/**
+ * 序号 → role 反查（§3.7 生成 ExecutionResult.naming 用）。
+ *
+ * 反查需要「序号 → hash」对照：subShapeHashes(shape,'face',B) 的数组下标 i 对应
+ * 序号 i+1（§1.1 事实：getSubShapes ↔ subShapeHashes 同走 TopExp::MapShapes、
+ * 逐位同序）。调用方传入该对照数组 + 该 origin 的 role 表，返回第 ordinal 个面
+ * 的 role 名；不在表中 → undefined。
+ *
+ * @param roles - the role table for a single origin (role → hash list).
+ * @param ordinalToHash - subShapeHashes(shape,'face') 数组：下标 i ↔ 序号 i+1 的 hash。
+ * @param ordinal - the face ordinal (1-based).
+ * @returns the role name, or undefined when the ordinal isn't tracked.
+ */
+export declare function roleOfOrdinal(roles: ReadonlyMap<string, readonly number[]>, ordinalToHash: readonly number[], ordinal: number): string | undefined;
+//# sourceMappingURL=roles.d.ts.map

package/dist/topology/naming/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../../src/topology/naming/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAGxC,yCAAyC;AACzC,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC,gFAAgF;AAChF,YAAY,EAAE,aAAa,EAAE,CAAA;AAI7B;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAQ1F;AAiCD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CA2BvB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,aAAa,GAAG,MAAM,EAAE,CASxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,aAAa,GACvB,SAAS,CAaX;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,aAAa,GACvB,SAAS,CAMX;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,SAAS,EACtB,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,QAAQ,EACjB,SAAS,EAAE,MAAM,GAChB,SAAS,CAwCX;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAIpG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAC7C,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAOpB"}

package/dist/topology/naming/roles.js

@@ -0,0 +1,271 @@
+/**
+ * roles.ts — RoleTable 的生命周期纯逻辑（§3.2/§3.3/§3.4 移植 + 改造）
+ *
+ * - `assignRoles`：链根建表。语义优先（box/cylinder/cone/sphere 按法向/曲面类型
+ *   给稳定名）、位置兜底（`${opType}:face_${i}`，保证每面必有 role）。
+ * - `propagateRoles`：沿一次 hash 演化推进表（移植 brepjs updateRoles/nextHashes：
+ *   deleted 丢弃、modified 全部后继替换、未变保留；generated 刻意不消费）。
+ * - `mergeRoleTables`：布尔合流——A/B 两个来源的表各自传播后合并，缝面以本次
+ *   语句 LHS 为新 origin 给位置名（§3.4）。
+ * - `roleOfOrdinal`：序号 → role 反查（§3.7 生成 ExecutionResult.naming 用）。
+ */
+import { captureFaceHint } from './geom-hint.js';
+/** 主轴判定阈值：abs(component) > 0.9 视为轴对齐。 */
+export const AXIS_THRESHOLD = 0.9;
+// ── 语义命名器（§3.2：faijs 单位/轴向契约，mm、+Z 向上）──
+/**
+ * box 面：按外法向主轴给语义名。
+ *
+ * @param n - the outward normal of the face (unit length expected).
+ * @returns the cardinal role ('box:top' etc.), or undefined when no axis dominates.
+ */
+export function boxRoleFromNormal(n) {
+    if (n[2] > AXIS_THRESHOLD)
+        return 'box:top';
+    if (n[2] < -AXIS_THRESHOLD)
+        return 'box:bottom';
+    if (n[1] > AXIS_THRESHOLD)
+        return 'box:back';
+    if (n[1] < -AXIS_THRESHOLD)
+        return 'box:front';
+    if (n[0] > AXIS_THRESHOLD)
+        return 'box:right';
+    if (n[0] < -AXIS_THRESHOLD)
+        return 'box:left';
+    return undefined;
+}
+/** Z 轴端盖名：'+Z → :top'、'-Z → :bottom'（仅平面）。 */
+function axialCapName(prefix, surfaceType, z) {
+    if (surfaceType !== 'plane')
+        return undefined;
+    if (z > AXIS_THRESHOLD)
+        return `${prefix}:top`;
+    if (z < -AXIS_THRESHOLD)
+        return `${prefix}:bottom`;
+    return undefined;
+}
+/** cylinder（Z 轴）：端盖 + 侧立面。 */
+function cylinderRole(surfaceType, z) {
+    return surfaceType === 'cylinder' ? 'cylinder:lateral' : axialCapName('cylinder', surfaceType, z);
+}
+/** cone（Z 轴）：端盖 + 侧立面。 */
+function coneRole(surfaceType, z) {
+    return surfaceType === 'cone' ? 'cone:lateral' : axialCapName('cone', surfaceType, z);
+}
+/** sphere：单球面。 */
+function sphereRole(surfaceType) {
+    return surfaceType === 'sphere' ? 'sphere:surface' : undefined;
+}
+/** 每基本体的语义命名器，按 opType 键控。 */
+const ROLE_ASSIGNERS = {
+    box: (_surfaceType, normal) => boxRoleFromNormal(normal),
+    cylinder: (surfaceType, normal) => cylinderRole(surfaceType, normal[2]),
+    cone: (surfaceType, normal) => coneRole(surfaceType, normal[2]),
+    sphere: (surfaceType, _normal) => sphereRole(surfaceType),
+};
+/**
+ * 给链根 shape 建 RoleTable（单个 origin 的表；§3.2）。
+ *
+ * 语义优先、位置兜底；assign 时只保留 hash + hint，不保留面句柄
+ * （避免 wasm 句柄生命周期泄漏——读完几何量即弃）。
+ *
+ * @param kernel - the OCCT kernel.
+ * @param shape - the chain-root solid (primitive / load STEP 产物).
+ * @param opType - the chain-root operation type ('box'/'cylinder'/... 或 part 变量名).
+ * @returns RoleTable — 只有 origin=opType 一个键（调用方负责包装成多 origin 表）。
+ */
+export function assignRoles(kernel, shape, opType) {
+    const roles = new Map();
+    const assigner = ROLE_ASSIGNERS[opType];
+    const faceHandles = kernel.getSubShapes(shape, 'face');
+    try {
+        const hashes = kernel.subShapeHashes(shape, 'face', 2147483647);
+        let index = 0;
+        for (let i = 0; i < faceHandles.length; i++) {
+            const hint = captureFaceHint(kernel, faceHandles[i]);
+            const normal = hint.normal ?? [0, 0, 1];
+            const surfaceType = hint.surfaceType ?? '';
+            const semantic = assigner?.(surfaceType, normal);
+            const role = semantic !== undefined && !roles.has(semantic)
+                ? semantic
+                : `${opType}:face_${index}`;
+            roles.set(role, [hashes[i]]);
+            index++;
+        }
+        return roles;
+    }
+    finally {
+        // getSubShapes 返回的每个子形都是独立 arena 句柄——读完几何量即释放，
+        // 否则每次链根建表泄漏 faceCount 个存活句柄（arena 无界增长）。
+        for (const h of faceHandles) {
+            try {
+                kernel.release(h);
+            }
+            catch { /* 已释放 */ }
+        }
+    }
+}
+/**
+ * 把一个 role 的 hash 列表推进一个演化步（移植 brepjs nextHashes）：
+ * deleted 丢弃、modified 全部后继替换（1→多保留全部分片）、未变保留。
+ *
+ * @param hashes - the role's current face hashes.
+ * @param evolution - the hash-keyed evolution record.
+ * @returns the successor hashes.
+ */
+export function nextHashes(hashes, evolution) {
+    const successors = [];
+    for (const hash of hashes) {
+        if (evolution.deleted.has(hash))
+            continue;
+        const modified = evolution.modified.get(hash);
+        const targets = modified !== undefined && modified.length > 0 ? modified : [hash];
+        for (const h of targets)
+            if (!successors.includes(h))
+                successors.push(h);
+    }
+    return successors;
+}
+/**
+ * 沿一次 hash 演化推进某个 origin 的 role 表（移植 brepjs updateRoles）。
+ *
+ * generated 刻意不消费（§1.3 事实：occt 系 generated hash 指向中间形、实测 0 存活）；
+ * 生成面由 DerivedFaceTopoRef 以 lineage 命名。
+ *
+ * @param roles - the input role table (may be the single-origin map or full table).
+ * @param origin - the origin whose roles to advance.
+ * @param evolution - the hash-keyed evolution record for this op.
+ * @returns a NEW RoleTable with the origin's roles advanced (immutable style).
+ */
+export function propagateRoles(roles, origin, evolution) {
+    const originRoles = roles.get(origin);
+    if (!originRoles)
+        return roles;
+    const updated = new Map();
+    for (const [role, hashes] of originRoles) {
+        const successors = nextHashes(hashes, evolution);
+        if (successors.length > 0)
+            updated.set(role, successors);
+    }
+    const result = new Map();
+    for (const [key, value] of roles) {
+        result.set(key, key === origin ? updated : value);
+    }
+    return result;
+}
+/**
+ * 沿一次 hash 演化推进 RoleTable 的**所有** origin（单父 op 用，§3.3）。
+ *
+ * 变换/倒角等单输入 op 只产生一份演化，作用在输入表的所有 origin 上
+ * （布尔合流后的表含多个 origin，刚体变换下面 1:1 保留全部）。
+ *
+ * @param roles - the input role table (possibly multi-origin after a merge).
+ * @param evolution - the hash-keyed evolution record for this op.
+ * @returns a NEW RoleTable with every origin's roles advanced.
+ */
+export function propagateAllOrigins(roles, evolution) {
+    let result = roles;
+    for (const origin of roles.keys()) {
+        result = propagateRoles(result, origin, evolution);
+    }
+    return result;
+}
+/**
+ * 布尔合流：合并两个来源的 role 表（§3.4，faijs 对 brepjs 的必要扩展）。
+ *
+ * 对 A、B 两张 hash 演化分别传播各自的表后合并；布尔新生成的缝面/刃面
+ * 以本次布尔语句的 LHS 变量名（= outPart）为新 origin，位置名命名。
+ *
+ * @param targetTable - the target part's role table.
+ * @param targetEvo - the target-side hash evolution (A 的 inHash 去向).
+ * @param toolTable - the tool part's role table.
+ * @param toolEvo - the tool-side hash evolution (B 的 inHash 去向).
+ * @param outPart - the boolean statement's LHS variable name (new origin for seam faces).
+ * @param seamCount - how many seam/generated faces to name positionally (0 表示不补).
+ * @returns the merged RoleTable.
+ */
+export function mergeRoleTables(targetTable, targetEvo, toolTable, toolEvo, outPart, seamCount) {
+    const result = new Map();
+    for (const [origin, roles] of targetTable) {
+        const advanced = new Map();
+        for (const [role, hashes] of roles) {
+            const successors = nextHashes(hashes, targetEvo);
+            if (successors.length > 0)
+                advanced.set(role, successors);
+        }
+        result.set(origin, advanced);
+    }
+    for (const [origin, roles] of toolTable) {
+        if (result.has(origin)) {
+            // 同一 origin 出现在两侧（理论上罕见：同一变量两次输入）——按 tool 侧演化推进后合并。
+            const existing = result.get(origin);
+            const advanced = new Map();
+            for (const [role, hashes] of roles) {
+                const successors = nextHashes(hashes, toolEvo);
+                if (successors.length > 0)
+                    advanced.set(role, successors);
+            }
+            const merged = new Map(existing);
+            for (const [role, hs] of advanced) {
+                const prev = merged.get(role);
+                merged.set(role, prev ? [...new Set([...prev, ...hs])] : hs);
+            }
+            result.set(origin, merged);
+        }
+        else {
+            const advanced = new Map();
+            for (const [role, hashes] of roles) {
+                const successors = nextHashes(hashes, toolEvo);
+                if (successors.length > 0)
+                    advanced.set(role, successors);
+            }
+            result.set(origin, advanced);
+        }
+    }
+    if (seamCount > 0) {
+        const seamRoles = new Map();
+        for (let i = 0; i < seamCount; i++)
+            seamRoles.set(`${outPart}:face_${i}`, []);
+        result.set(outPart, seamRoles);
+    }
+    return result;
+}
+/**
+ * 布尔缝面/刃面的位置名角色表（§3.4：以本次语句 LHS 为新 origin）。
+ * 缝面的 hash 来自结果形状的 subShapeHashes（按生成序），此处仅分配 role 名——
+ * hash 由调用方在拿到结果 shape 后填入（seam 面 hash 需结果 subShapeHashes 对照）。
+ *
+ * @param outPart - the boolean statement's LHS variable name.
+ * @param count - the number of seam faces to name.
+ * @returns a single-origin role map with positional roles.
+ */
+export function assignGeneratedPositionalRoles(outPart, count) {
+    const roles = new Map();
+    for (let i = 0; i < count; i++)
+        roles.set(`${outPart}:face_${i}`, []);
+    return roles;
+}
+/**
+ * 序号 → role 反查（§3.7 生成 ExecutionResult.naming 用）。
+ *
+ * 反查需要「序号 → hash」对照：subShapeHashes(shape,'face',B) 的数组下标 i 对应
+ * 序号 i+1（§1.1 事实：getSubShapes ↔ subShapeHashes 同走 TopExp::MapShapes、
+ * 逐位同序）。调用方传入该对照数组 + 该 origin 的 role 表，返回第 ordinal 个面
+ * 的 role 名；不在表中 → undefined。
+ *
+ * @param roles - the role table for a single origin (role → hash list).
+ * @param ordinalToHash - subShapeHashes(shape,'face') 数组：下标 i ↔ 序号 i+1 的 hash。
+ * @param ordinal - the face ordinal (1-based).
+ * @returns the role name, or undefined when the ordinal isn't tracked.
+ */
+export function roleOfOrdinal(roles, ordinalToHash, ordinal) {
+    const hash = ordinalToHash[ordinal - 1];
+    if (hash === undefined)
+        return undefined;
+    for (const [role, hashes] of roles) {
+        if (hashes.includes(hash))
+            return role;
+    }
+    return undefined;
+}
+//# sourceMappingURL=roles.js.map