@faicad/faijs 0.13.1 → 0.14.1

package/dist/topology/naming/role-name.d.ts

@@ -0,0 +1,176 @@
+/**
+ * role-name.ts — `RoleName` 契约与序列化（计划 §4.2）。
+ *
+ * 一条语句对自己产出的每个面起的**局部名**。作用域 = 那条语句；
+ * 全局唯一性由 `(origin, role)` 提供（`origin` 是 `StmtId`，见 `types.ts`）。
+ *
+ * ## 为什么 role 不能是一个裸字符串
+ *
+ * 旧实现在位置兜底时产出 `box:top` / `extrude:face_3` / `cylinder:lateral`
+ * ——**名字里塞了 origin**。这带来两个后果，都是致命的：
+ * 1. 同一个 role 在不同语句下**不是同一个名字**（`box:top` vs `extrude:top`），
+ *    于是「role 词汇表」无法按 op 封闭枚举，生成器无法把词汇表产出到 `.d.ts`；
+ * 2. 前缀是**位置兜底**的伪装——`extrude:face_3` 有名字却不承载任何设计意图，
+ *    按「有名/无名」统计会得出假的"全覆盖"（Phase 0.8 基线实测）。
+ *
+ * ⇒ role 只描述**在那条语句内的局部语义**，origin 由 `(StmtId)` 单独承载。
+ *
+ * ## 七个 kind 是封闭集
+ *
+ * `semantic`（op 词汇表封闭）/ `wall`（profile 第 i 条边扫出）/ `hole`（内环子结构）/
+ * `replica`（pattern 第 k 份）/ `splinter`（split 第 j 片）/ `generated`（倒角过渡面）/
+ * `imported`（import_brep 原始面序）。**新增 kind = 破坏性变更，须版本化。**
+ *
+ * ## 四条约束（分析文档 §5.1.1 R1–R4）
+ *
+ * 局部唯一 / 封闭可枚举 / **抗参数变化** / 结构化可分解。
+ * 第三、四条正是本文件的序列化设计目标：`wall:3` 在 profile 边数变化后**仍然是第 3 条边**
+ * （不是"第 3 张面"这种随面序漂移的地址），且 `replica[2]/hole:1/wall:3` 可逐层分解回结构。
+ *
+ * ## 序列化（进 `.fai.js` 的参数）
+ *
+ * ```
+ * semantic   top                        （裸名）
+ * wall       wall:3
+ * hole       hole:1/wall:2              （前缀包裹 inner）
+ * replica    replica[2]/wall:3          （前缀包裹 inner）
+ * splinter   splinter(top)#1            （包裹 inner + 后缀）
+ * generated  gen:fillet:0
+ * imported   imported:5
+ * ```
+ *
+ * `parseRoleName` 与 `formatRoleName` **互为逆**（值级 round-trip），
+ * 且 `parseRoleName` 是**单射**的（不接受前导零、不接受保留字作 semantic）——
+ * 否则两个不同的 RoleName 会序列化成同一个串，`.fai.js` 里的引用会静默指向错的面。
+ */
+/**
+ * 一条语句对某个产出面的局部名（计划 §4.2）。
+ *
+ * - `semantic`：op 声明的封闭词汇（`top` / `bottom` / `lateral` / `start` / `end` …）
+ * - `wall`：由输入 profile 第 `index` 条边扫出/旋出的侧面
+ * - `hole`：第 `index` 个内环下的同名子结构（`inner` 递归该内环下的局部名）
+ * - `replica`：pattern 的第 `k` 份（`inner` 递归该份内的局部名）
+ * - `splinter`：split 的第 `index` 片（`inner` 递归原面的局部名）
+ * - `generated`：`op` 造出的过渡面（`fillet` / `chamfer`）第 `index` 张
+ * - `imported`：`import_brep` 的原始面序第 `index` 张
+ */
+export type RoleName = {
+    readonly kind: 'semantic';
+    readonly name: string;
+} | {
+    readonly kind: 'wall';
+    readonly index: number;
+} | {
+    readonly kind: 'hole';
+    readonly index: number;
+    readonly inner: RoleName;
+} | {
+    readonly kind: 'replica';
+    readonly k: number;
+    readonly inner: RoleName;
+} | {
+    readonly kind: 'splinter';
+    readonly inner: RoleName;
+    readonly index: number;
+} | {
+    readonly kind: 'generated';
+    readonly op: string;
+    readonly index: number;
+} | {
+    readonly kind: 'imported';
+    readonly index: number;
+};
+/** 七个 kind 的名字，供审计测试枚举（`RoleName` 是封闭集，新增 kind 必须同步此处）。 */
+export declare const ROLE_NAME_KINDS: readonly ["semantic", "wall", "hole", "replica", "splinter", "generated", "imported"];
+/** `ROLE_NAME_KINDS` 的元素类型。 */
+export type RoleNameKind = (typeof ROLE_NAME_KINDS)[number];
+/** RoleName 序列化/校验失败（格式不合法、保留字冲突、索引非法）。 */
+export declare class RoleNameError extends Error {
+    /** 稳定的错误码（供 args 校验与宿主识别）。 */
+    readonly code = "E_TOPO_ROLE_INVALID";
+    /**
+     * @param message - what is wrong with the role name.
+     */
+    constructor(message: string);
+}
+/**
+ * 把一个 `RoleName` 序列化成进 `.fai.js` 的串。
+ *
+ * 结果**不含 origin**：身份是 `(StmtId, RoleName)` 两元组，串只承载后半。
+ *
+ * @param role - the role name to serialize.
+ * @returns the wire form (e.g. `top`, `wall:3`, `replica[2]/wall:3`).
+ * @throws RoleNameError when the value violates the contract (reserved name, bad index).
+ */
+export declare function formatRoleName(role: RoleName): string;
+/**
+ * 把串解析回 `RoleName`（`formatRoleName` 的逆）。非法输入返回 `null`，不抛错。
+ *
+ * 只返回 `null` 而不抛错，是因为解析发生在读 `.fai.js` 参数时：
+ * 调用方需要区分「这不是一个 role 串」（→ 走迁移器/报缺失）与「这是坏的 role 串」。
+ *
+ * @param text - the wire form.
+ * @returns the parsed role, or null when the text is not a valid RoleName.
+ */
+export declare function parseRoleName(text: string): RoleName | null;
+/**
+ * 造一个 `semantic` role（op 声明的封闭词汇）。
+ *
+ * @param name - the op's closed-vocabulary name.
+ * @returns the role.
+ * @throws RoleNameError when the name is malformed or shadows a structural keyword.
+ */
+export declare function semantic(name: string): RoleName;
+/**
+ * 造一个 `wall` role（输入 profile 第 i 条边扫出/旋出的侧面）。
+ *
+ * @param index - zero-based profile-edge index.
+ * @returns the role.
+ * @throws RoleNameError when the index is not a non-negative integer.
+ */
+export declare function wall(index: number): RoleName;
+/**
+ * 造一个 `hole` role（第 j 个内环下的同名子结构）。
+ *
+ * @param index - zero-based inner-loop index.
+ * @param inner - the local role inside that loop.
+ * @returns the role.
+ * @throws RoleNameError when the index is not a non-negative integer.
+ */
+export declare function hole(index: number, inner: RoleName): RoleName;
+/**
+ * 造一个 `replica` role（pattern 的第 k 份）。
+ *
+ * @param k - zero-based replica index.
+ * @param inner - the local role inside that replica.
+ * @returns the role.
+ * @throws RoleNameError when k is not a non-negative integer.
+ */
+export declare function replica(k: number, inner: RoleName): RoleName;
+/**
+ * 造一个 `splinter` role（split 的第 j 片）。
+ *
+ * @param inner - the local role of the face being split.
+ * @param index - zero-based splinter index.
+ * @returns the role.
+ * @throws RoleNameError when the index is not a non-negative integer.
+ */
+export declare function splinter(inner: RoleName, index: number): RoleName;
+/**
+ * 造一个 `generated` role（fillet/chamfer 过渡面）。
+ *
+ * @param op - the producing op ('fillet' / 'chamfer').
+ * @param index - zero-based index among that op's generated faces.
+ * @returns the role.
+ * @throws RoleNameError when op or index violates the contract.
+ */
+export declare function generated(op: string, index: number): RoleName;
+/**
+ * 造一个 `imported` role（`import_brep` 的原始面序）。
+ *
+ * @param index - zero-based face index in the imported shape's enumeration order.
+ * @returns the role.
+ * @throws RoleNameError when the index is not a non-negative integer.
+ */
+export declare function imported(index: number): RoleName;
+//# sourceMappingURL=role-name.d.ts.map

package/dist/topology/naming/role-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-name.d.ts","sourceRoot":"","sources":["../../../src/topology/naming/role-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAqBH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEzD,2DAA2D;AAC3D,eAAO,MAAM,eAAe,uFAQlB,CAAA;AAEV,+BAA+B;AAC/B,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3D,2CAA2C;AAC3C,qBAAa,aAAc,SAAQ,KAAK;IACtC,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,yBAAwB;IAErC;;OAEG;gBACS,OAAO,EAAE,MAAM;CAI5B;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAyBrD;AAqCD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA0D3D;AAQD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAG/C;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAG5C;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAG7D;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAG5D;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAGhD"}

package/dist/topology/naming/role-name.js

@@ -0,0 +1,344 @@
+/**
+ * role-name.ts — `RoleName` 契约与序列化（计划 §4.2）。
+ *
+ * 一条语句对自己产出的每个面起的**局部名**。作用域 = 那条语句；
+ * 全局唯一性由 `(origin, role)` 提供（`origin` 是 `StmtId`，见 `types.ts`）。
+ *
+ * ## 为什么 role 不能是一个裸字符串
+ *
+ * 旧实现在位置兜底时产出 `box:top` / `extrude:face_3` / `cylinder:lateral`
+ * ——**名字里塞了 origin**。这带来两个后果，都是致命的：
+ * 1. 同一个 role 在不同语句下**不是同一个名字**（`box:top` vs `extrude:top`），
+ *    于是「role 词汇表」无法按 op 封闭枚举，生成器无法把词汇表产出到 `.d.ts`；
+ * 2. 前缀是**位置兜底**的伪装——`extrude:face_3` 有名字却不承载任何设计意图，
+ *    按「有名/无名」统计会得出假的"全覆盖"（Phase 0.8 基线实测）。
+ *
+ * ⇒ role 只描述**在那条语句内的局部语义**，origin 由 `(StmtId)` 单独承载。
+ *
+ * ## 七个 kind 是封闭集
+ *
+ * `semantic`（op 词汇表封闭）/ `wall`（profile 第 i 条边扫出）/ `hole`（内环子结构）/
+ * `replica`（pattern 第 k 份）/ `splinter`（split 第 j 片）/ `generated`（倒角过渡面）/
+ * `imported`（import_brep 原始面序）。**新增 kind = 破坏性变更，须版本化。**
+ *
+ * ## 四条约束（分析文档 §5.1.1 R1–R4）
+ *
+ * 局部唯一 / 封闭可枚举 / **抗参数变化** / 结构化可分解。
+ * 第三、四条正是本文件的序列化设计目标：`wall:3` 在 profile 边数变化后**仍然是第 3 条边**
+ * （不是"第 3 张面"这种随面序漂移的地址），且 `replica[2]/hole:1/wall:3` 可逐层分解回结构。
+ *
+ * ## 序列化（进 `.fai.js` 的参数）
+ *
+ * ```
+ * semantic   top                        （裸名）
+ * wall       wall:3
+ * hole       hole:1/wall:2              （前缀包裹 inner）
+ * replica    replica[2]/wall:3          （前缀包裹 inner）
+ * splinter   splinter(top)#1            （包裹 inner + 后缀）
+ * generated  gen:fillet:0
+ * imported   imported:5
+ * ```
+ *
+ * `parseRoleName` 与 `formatRoleName` **互为逆**（值级 round-trip），
+ * 且 `parseRoleName` 是**单射**的（不接受前导零、不接受保留字作 semantic）——
+ * 否则两个不同的 RoleName 会序列化成同一个串，`.fai.js` 里的引用会静默指向错的面。
+ */
+/** 结构关键字：出现在串首即被解释成结构 kind，故不得作为 semantic 名。 */
+const RESERVED_KEYWORDS = ['wall', 'hole', 'replica', 'splinter', 'gen', 'imported'];
+/**
+ * semantic 名的合法形态。
+ *
+ * 限成 `[A-Za-z_][A-Za-z0-9_]*`：op 词汇表是**封闭可枚举**的
+ * （`top` / `bottom` / `lateral` / `start` / `end` …），不需要更宽的字符集；
+ * 收紧后串首不会与任何结构关键字歧义。
+ */
+const SEMANTIC_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** 非负整数，**禁止前导零**（`0` 合法，`01` 不合法）——保证 format/parse 单射。 */
+const INDEX_SOURCE = '0|[1-9][0-9]*';
+const LEADING_INDEX_RE = new RegExp(`^(${INDEX_SOURCE})$`);
+/** `generated` 的 op 名：与 semantic 同字符集，保证 `gen:<op>:<i>` 无歧义。 */
+const OP_NAME_RE = SEMANTIC_NAME_RE;
+/** 七个 kind 的名字，供审计测试枚举（`RoleName` 是封闭集，新增 kind 必须同步此处）。 */
+export const ROLE_NAME_KINDS = [
+    'semantic',
+    'wall',
+    'hole',
+    'replica',
+    'splinter',
+    'generated',
+    'imported',
+];
+/** RoleName 序列化/校验失败（格式不合法、保留字冲突、索引非法）。 */
+export class RoleNameError extends Error {
+    /** 稳定的错误码（供 args 校验与宿主识别）。 */
+    code = 'E_TOPO_ROLE_INVALID';
+    /**
+     * @param message - what is wrong with the role name.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'RoleNameError';
+    }
+}
+/** 校验非负整数索引。 @throws RoleNameError when out of contract. */
+function assertIndex(value, what) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RoleNameError(`${what} must be a non-negative integer, got ${String(value)}`);
+    }
+}
+/**
+ * 校验 semantic 名：形态合法且不与结构关键字冲突。
+ *
+ * @param name - the candidate semantic name.
+ * @throws RoleNameError when empty, malformed, or shadowing a structural keyword.
+ */
+function assertSemanticName(name) {
+    if (!SEMANTIC_NAME_RE.test(name)) {
+        throw new RoleNameError(`semantic name must match ${SEMANTIC_NAME_RE.source}, got ${JSON.stringify(name)}`);
+    }
+    if (RESERVED_KEYWORDS.includes(name)) {
+        throw new RoleNameError(`semantic name ${JSON.stringify(name)} is a structural keyword; ` +
+            `serializing it would parse back as kind '${name}' (use the structural kind instead)`);
+    }
+}
+/** 校验 generated 的 op 名（保证 `gen:<op>:<i>` 三段可切）。 */
+function assertOpName(op) {
+    if (!OP_NAME_RE.test(op)) {
+        throw new RoleNameError(`generated op must match ${OP_NAME_RE.source}, got ${JSON.stringify(op)}`);
+    }
+}
+/**
+ * 把一个 `RoleName` 序列化成进 `.fai.js` 的串。
+ *
+ * 结果**不含 origin**：身份是 `(StmtId, RoleName)` 两元组，串只承载后半。
+ *
+ * @param role - the role name to serialize.
+ * @returns the wire form (e.g. `top`, `wall:3`, `replica[2]/wall:3`).
+ * @throws RoleNameError when the value violates the contract (reserved name, bad index).
+ */
+export function formatRoleName(role) {
+    switch (role.kind) {
+        case 'semantic':
+            assertSemanticName(role.name);
+            return role.name;
+        case 'wall':
+            assertIndex(role.index, 'wall index');
+            return `wall:${role.index}`;
+        case 'hole':
+            assertIndex(role.index, 'hole index');
+            return `hole:${role.index}/${formatRoleName(role.inner)}`;
+        case 'replica':
+            assertIndex(role.k, 'replica k');
+            return `replica[${role.k}]/${formatRoleName(role.inner)}`;
+        case 'splinter':
+            assertIndex(role.index, 'splinter index');
+            return `splinter(${formatRoleName(role.inner)})#${role.index}`;
+        case 'generated':
+            assertOpName(role.op);
+            assertIndex(role.index, 'generated index');
+            return `gen:${role.op}:${role.index}`;
+        case 'imported':
+            assertIndex(role.index, 'imported index');
+            return `imported:${role.index}`;
+    }
+}
+/**
+ * 读一个非负整数前缀（禁止前导零）。
+ *
+ * @param text - the candidate integer text.
+ * @returns the parsed value, or null when it is not a canonical non-negative integer.
+ */
+function readIndex(text) {
+    if (!LEADING_INDEX_RE.test(text))
+        return null;
+    return Number(text);
+}
+/**
+ * 切出 balanced 的 `(...)` 段：返回内层文本与剩余文本。
+ *
+ * `splinter` 的 inner 自身可能含括号（`splinter(splinter(top)#1)#2`），
+ * 故不能用最后一个 `)` 定位。
+ *
+ * @param text - text starting with `(`.
+ * @returns the inner text and the remainder after the matching `)`, or null when unbalanced.
+ */
+function readBalancedParen(text) {
+    if (!text.startsWith('('))
+        return null;
+    let depth = 0;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '(')
+            depth++;
+        else if (ch === ')') {
+            depth--;
+            if (depth === 0)
+                return { inner: text.slice(1, i), rest: text.slice(i + 1) };
+            if (depth < 0)
+                return null;
+        }
+    }
+    return null;
+}
+/**
+ * 把串解析回 `RoleName`（`formatRoleName` 的逆）。非法输入返回 `null`，不抛错。
+ *
+ * 只返回 `null` 而不抛错，是因为解析发生在读 `.fai.js` 参数时：
+ * 调用方需要区分「这不是一个 role 串」（→ 走迁移器/报缺失）与「这是坏的 role 串」。
+ *
+ * @param text - the wire form.
+ * @returns the parsed role, or null when the text is not a valid RoleName.
+ */
+export function parseRoleName(text) {
+    if (text === '')
+        return null;
+    if (text.startsWith('wall:')) {
+        const index = readIndex(text.slice('wall:'.length));
+        return index === null ? null : { kind: 'wall', index };
+    }
+    if (text.startsWith('imported:')) {
+        const index = readIndex(text.slice('imported:'.length));
+        return index === null ? null : { kind: 'imported', index };
+    }
+    if (text.startsWith('gen:')) {
+        const parts = text.split(':');
+        if (parts.length !== 3)
+            return null;
+        const op = parts[1];
+        if (!OP_NAME_RE.test(op))
+            return null;
+        const index = readIndex(parts[2]);
+        return index === null ? null : { kind: 'generated', op, index };
+    }
+    if (text.startsWith('splinter(')) {
+        const balanced = readBalancedParen(text.slice('splinter'.length));
+        if (!balanced)
+            return null;
+        const inner = parseRoleName(balanced.inner);
+        if (!inner)
+            return null;
+        if (!balanced.rest.startsWith('#'))
+            return null;
+        const index = readIndex(balanced.rest.slice(1));
+        return index === null ? null : { kind: 'splinter', inner, index };
+    }
+    if (text.startsWith('hole:')) {
+        // `hole:<i>/<inner>`：先切 index，再整体递归 inner（inner 内还可有 `/`）。
+        const remainder = text.slice('hole:'.length);
+        const slash = remainder.indexOf('/');
+        if (slash < 0)
+            return null;
+        const index = readIndex(remainder.slice(0, slash));
+        if (index === null)
+            return null;
+        const inner = parseRoleName(remainder.slice(slash + 1));
+        return inner ? { kind: 'hole', index, inner } : null;
+    }
+    if (text.startsWith('replica[')) {
+        const close = text.indexOf(']');
+        if (close < 0)
+            return null;
+        const k = readIndex(text.slice('replica['.length, close));
+        if (k === null)
+            return null;
+        const rest = text.slice(close + 1);
+        if (!rest.startsWith('/'))
+            return null;
+        const inner = parseRoleName(rest.slice(1));
+        return inner ? { kind: 'replica', k, inner } : null;
+    }
+    // 兜底：semantic（保留字已在上面被结构分支吃掉，故此处不会歧义）
+    if (!SEMANTIC_NAME_RE.test(text))
+        return null;
+    if (RESERVED_KEYWORDS.includes(text))
+        return null;
+    return { kind: 'semantic', name: text };
+}
+// ── 构造子（七个 kind 各一个）──
+//
+// 存在理由：把「契约校验」收在一处。调用点直接写字面量会绕过 `assertIndex` /
+// `assertSemanticName`，于是不合法的 role 在 `formatRoleName` 才炸——
+// 那时已经离出错点很远（可能跨了一次执行）。构造子让非法值**在产生点**就报错。
+/**
+ * 造一个 `semantic` role（op 声明的封闭词汇）。
+ *
+ * @param name - the op's closed-vocabulary name.
+ * @returns the role.
+ * @throws RoleNameError when the name is malformed or shadows a structural keyword.
+ */
+export function semantic(name) {
+    assertSemanticName(name);
+    return { kind: 'semantic', name };
+}
+/**
+ * 造一个 `wall` role（输入 profile 第 i 条边扫出/旋出的侧面）。
+ *
+ * @param index - zero-based profile-edge index.
+ * @returns the role.
+ * @throws RoleNameError when the index is not a non-negative integer.
+ */
+export function wall(index) {
+    assertIndex(index, 'wall index');
+    return { kind: 'wall', index };
+}
+/**
+ * 造一个 `hole` role（第 j 个内环下的同名子结构）。
+ *
+ * @param index - zero-based inner-loop index.
+ * @param inner - the local role inside that loop.
+ * @returns the role.
+ * @throws RoleNameError when the index is not a non-negative integer.
+ */
+export function hole(index, inner) {
+    assertIndex(index, 'hole index');
+    return { kind: 'hole', index, inner };
+}
+/**
+ * 造一个 `replica` role（pattern 的第 k 份）。
+ *
+ * @param k - zero-based replica index.
+ * @param inner - the local role inside that replica.
+ * @returns the role.
+ * @throws RoleNameError when k is not a non-negative integer.
+ */
+export function replica(k, inner) {
+    assertIndex(k, 'replica k');
+    return { kind: 'replica', k, inner };
+}
+/**
+ * 造一个 `splinter` role（split 的第 j 片）。
+ *
+ * @param inner - the local role of the face being split.
+ * @param index - zero-based splinter index.
+ * @returns the role.
+ * @throws RoleNameError when the index is not a non-negative integer.
+ */
+export function splinter(inner, index) {
+    assertIndex(index, 'splinter index');
+    return { kind: 'splinter', inner, index };
+}
+/**
+ * 造一个 `generated` role（fillet/chamfer 过渡面）。
+ *
+ * @param op - the producing op ('fillet' / 'chamfer').
+ * @param index - zero-based index among that op's generated faces.
+ * @returns the role.
+ * @throws RoleNameError when op or index violates the contract.
+ */
+export function generated(op, index) {
+    assertOpName(op);
+    assertIndex(index, 'generated index');
+    return { kind: 'generated', op, index };
+}
+/**
+ * 造一个 `imported` role（`import_brep` 的原始面序）。
+ *
+ * @param index - zero-based face index in the imported shape's enumeration order.
+ * @returns the role.
+ * @throws RoleNameError when the index is not a non-negative integer.
+ */
+export function imported(index) {
+    assertIndex(index, 'imported index');
+    return { kind: 'imported', index };
+}
+//# sourceMappingURL=role-name.js.map

package/dist/topology/naming/role-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-name.js","sourceRoot":"","sources":["../../../src/topology/naming/role-name.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * role-name.ts — `RoleName` 契约与序列化（计划 §4.2）。\n *\n * 一条语句对自己产出的每个面起的**局部名**。作用域 = 那条语句；\n * 全局唯一性由 `(origin, role)` 提供（`origin` 是 `StmtId`，见 `types.ts`）。\n *\n * ## 为什么 role 不能是一个裸字符串\n *\n * 旧实现在位置兜底时产出 `box:top` / `extrude:face_3` / `cylinder:lateral`\n * ——**名字里塞了 origin**。这带来两个后果，都是致命的：\n * 1. 同一个 role 在不同语句下**不是同一个名字**（`box:top` vs `extrude:top`），\n *    于是「role 词汇表」无法按 op 封闭枚举，生成器无法把词汇表产出到 `.d.ts`；\n * 2. 前缀是**位置兜底**的伪装——`extrude:face_3` 有名字却不承载任何设计意图，\n *    按「有名/无名」统计会得出假的\"全覆盖\"（Phase 0.8 基线实测）。\n *\n * ⇒ role 只描述**在那条语句内的局部语义**，origin 由 `(StmtId)` 单独承载。\n *\n * ## 七个 kind 是封闭集\n *\n * `semantic`（op 词汇表封闭）/ `wall`（profile 第 i 条边扫出）/ `hole`（内环子结构）/\n * `replica`（pattern 第 k 份）/ `splinter`（split 第 j 片）/ `generated`（倒角过渡面）/\n * `imported`（import_brep 原始面序）。**新增 kind = 破坏性变更，须版本化。**\n *\n * ## 四条约束（分析文档 §5.1.1 R1–R4）\n *\n * 局部唯一 / 封闭可枚举 / **抗参数变化** / 结构化可分解。\n * 第三、四条正是本文件的序列化设计目标：`wall:3` 在 profile 边数变化后**仍然是第 3 条边**\n * （不是\"第 3 张面\"这种随面序漂移的地址），且 `replica[2]/hole:1/wall:3` 可逐层分解回结构。\n *\n * ## 序列化（进 `.fai.js` 的参数）\n *\n * ```\n * semantic   top                        （裸名）\n * wall       wall:3\n * hole       hole:1/wall:2              （前缀包裹 inner）\n * replica    replica[2]/wall:3          （前缀包裹 inner）\n * splinter   splinter(top)#1            （包裹 inner + 后缀）\n * generated  gen:fillet:0\n * imported   imported:5\n * ```\n *\n * `parseRoleName` 与 `formatRoleName` **互为逆**（值级 round-trip），\n * 且 `parseRoleName` 是**单射**的（不接受前导零、不接受保留字作 semantic）——\n * 否则两个不同的 RoleName 会序列化成同一个串，`.fai.js` 里的引用会静默指向错的面。\n */\n\n/** 结构关键字：出现在串首即被解释成结构 kind，故不得作为 semantic 名。 */\nconst RESERVED_KEYWORDS = ['wall', 'hole', 'replica', 'splinter', 'gen', 'imported'] as const\n\n/**\n * semantic 名的合法形态。\n *\n * 限成 `[A-Za-z_][A-Za-z0-9_]*`：op 词汇表是**封闭可枚举**的\n * （`top` / `bottom` / `lateral` / `start` / `end` …），不需要更宽的字符集；\n * 收紧后串首不会与任何结构关键字歧义。\n */\nconst SEMANTIC_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/\n\n/** 非负整数，**禁止前导零**（`0` 合法，`01` 不合法）——保证 format/parse 单射。 */\nconst INDEX_SOURCE = '0|[1-9][0-9]*'\nconst LEADING_INDEX_RE = new RegExp(`^(${INDEX_SOURCE})$`)\n\n/** `generated` 的 op 名：与 semantic 同字符集，保证 `gen:<op>:<i>` 无歧义。 */\nconst OP_NAME_RE = SEMANTIC_NAME_RE\n\n/**\n * 一条语句对某个产出面的局部名（计划 §4.2）。\n *\n * - `semantic`：op 声明的封闭词汇（`top` / `bottom` / `lateral` / `start` / `end` …）\n * - `wall`：由输入 profile 第 `index` 条边扫出/旋出的侧面\n * - `hole`：第 `index` 个内环下的同名子结构（`inner` 递归该内环下的局部名）\n * - `replica`：pattern 的第 `k` 份（`inner` 递归该份内的局部名）\n * - `splinter`：split 的第 `index` 片（`inner` 递归原面的局部名）\n * - `generated`：`op` 造出的过渡面（`fillet` / `chamfer`）第 `index` 张\n * - `imported`：`import_brep` 的原始面序第 `index` 张\n */\nexport type RoleName =\n  | { readonly kind: 'semantic'; readonly name: string }\n  | { readonly kind: 'wall'; readonly index: number }\n  | { readonly kind: 'hole'; readonly index: number; readonly inner: RoleName }\n  | { readonly kind: 'replica'; readonly k: number; readonly inner: RoleName }\n  | { readonly kind: 'splinter'; readonly inner: RoleName; readonly index: number }\n  | { readonly kind: 'generated'; readonly op: string; readonly index: number }\n  | { readonly kind: 'imported'; readonly index: number }\n\n/** 七个 kind 的名字，供审计测试枚举（`RoleName` 是封闭集，新增 kind 必须同步此处）。 */\nexport const ROLE_NAME_KINDS = [\n  'semantic',\n  'wall',\n  'hole',\n  'replica',\n  'splinter',\n  'generated',\n  'imported',\n] as const\n\n/** `ROLE_NAME_KINDS` 的元素类型。 */\nexport type RoleNameKind = (typeof ROLE_NAME_KINDS)[number]\n\n/** RoleName 序列化/校验失败（格式不合法、保留字冲突、索引非法）。 */\nexport class RoleNameError extends Error {\n  /** 稳定的错误码（供 args 校验与宿主识别）。 */\n  readonly code = 'E_TOPO_ROLE_INVALID'\n\n  /**\n   * @param message - what is wrong with the role name.\n   */\n  constructor(message: string) {\n    super(message)\n    this.name = 'RoleNameError'\n  }\n}\n\n/** 校验非负整数索引。 @throws RoleNameError when out of contract. */\nfunction assertIndex(value: number, what: string): void {\n  if (!Number.isInteger(value) || value < 0) {\n    throw new RoleNameError(`${what} must be a non-negative integer, got ${String(value)}`)\n  }\n}\n\n/**\n * 校验 semantic 名：形态合法且不与结构关键字冲突。\n *\n * @param name - the candidate semantic name.\n * @throws RoleNameError when empty, malformed, or shadowing a structural keyword.\n */\nfunction assertSemanticName(name: string): void {\n  if (!SEMANTIC_NAME_RE.test(name)) {\n    throw new RoleNameError(\n      `semantic name must match ${SEMANTIC_NAME_RE.source}, got ${JSON.stringify(name)}`,\n    )\n  }\n  if ((RESERVED_KEYWORDS as readonly string[]).includes(name)) {\n    throw new RoleNameError(\n      `semantic name ${JSON.stringify(name)} is a structural keyword; ` +\n        `serializing it would parse back as kind '${name}' (use the structural kind instead)`,\n    )\n  }\n}\n\n/** 校验 generated 的 op 名（保证 `gen:<op>:<i>` 三段可切）。 */\nfunction assertOpName(op: string): void {\n  if (!OP_NAME_RE.test(op)) {\n    throw new RoleNameError(\n      `generated op must match ${OP_NAME_RE.source}, got ${JSON.stringify(op)}`,\n    )\n  }\n}\n\n/**\n * 把一个 `RoleName` 序列化成进 `.fai.js` 的串。\n *\n * 结果**不含 origin**：身份是 `(StmtId, RoleName)` 两元组，串只承载后半。\n *\n * @param role - the role name to serialize.\n * @returns the wire form (e.g. `top`, `wall:3`, `replica[2]/wall:3`).\n * @throws RoleNameError when the value violates the contract (reserved name, bad index).\n */\nexport function formatRoleName(role: RoleName): string {\n  switch (role.kind) {\n    case 'semantic':\n      assertSemanticName(role.name)\n      return role.name\n    case 'wall':\n      assertIndex(role.index, 'wall index')\n      return `wall:${role.index}`\n    case 'hole':\n      assertIndex(role.index, 'hole index')\n      return `hole:${role.index}/${formatRoleName(role.inner)}`\n    case 'replica':\n      assertIndex(role.k, 'replica k')\n      return `replica[${role.k}]/${formatRoleName(role.inner)}`\n    case 'splinter':\n      assertIndex(role.index, 'splinter index')\n      return `splinter(${formatRoleName(role.inner)})#${role.index}`\n    case 'generated':\n      assertOpName(role.op)\n      assertIndex(role.index, 'generated index')\n      return `gen:${role.op}:${role.index}`\n    case 'imported':\n      assertIndex(role.index, 'imported index')\n      return `imported:${role.index}`\n  }\n}\n\n/**\n * 读一个非负整数前缀（禁止前导零）。\n *\n * @param text - the candidate integer text.\n * @returns the parsed value, or null when it is not a canonical non-negative integer.\n */\nfunction readIndex(text: string): number | null {\n  if (!LEADING_INDEX_RE.test(text)) return null\n  return Number(text)\n}\n\n/**\n * 切出 balanced 的 `(...)` 段：返回内层文本与剩余文本。\n *\n * `splinter` 的 inner 自身可能含括号（`splinter(splinter(top)#1)#2`），\n * 故不能用最后一个 `)` 定位。\n *\n * @param text - text starting with `(`.\n * @returns the inner text and the remainder after the matching `)`, or null when unbalanced.\n */\nfunction readBalancedParen(text: string): { inner: string; rest: string } | null {\n  if (!text.startsWith('(')) return null\n  let depth = 0\n  for (let i = 0; i < text.length; i++) {\n    const ch = text[i]\n    if (ch === '(') depth++\n    else if (ch === ')') {\n      depth--\n      if (depth === 0) return { inner: text.slice(1, i), rest: text.slice(i + 1) }\n      if (depth < 0) return null\n    }\n  }\n  return null\n}\n\n/**\n * 把串解析回 `RoleName`（`formatRoleName` 的逆）。非法输入返回 `null`，不抛错。\n *\n * 只返回 `null` 而不抛错，是因为解析发生在读 `.fai.js` 参数时：\n * 调用方需要区分「这不是一个 role 串」（→ 走迁移器/报缺失）与「这是坏的 role 串」。\n *\n * @param text - the wire form.\n * @returns the parsed role, or null when the text is not a valid RoleName.\n */\nexport function parseRoleName(text: string): RoleName | null {\n  if (text === '') return null\n\n  if (text.startsWith('wall:')) {\n    const index = readIndex(text.slice('wall:'.length))\n    return index === null ? null : { kind: 'wall', index }\n  }\n\n  if (text.startsWith('imported:')) {\n    const index = readIndex(text.slice('imported:'.length))\n    return index === null ? null : { kind: 'imported', index }\n  }\n\n  if (text.startsWith('gen:')) {\n    const parts = text.split(':')\n    if (parts.length !== 3) return null\n    const op = parts[1]\n    if (!OP_NAME_RE.test(op)) return null\n    const index = readIndex(parts[2])\n    return index === null ? null : { kind: 'generated', op, index }\n  }\n\n  if (text.startsWith('splinter(')) {\n    const balanced = readBalancedParen(text.slice('splinter'.length))\n    if (!balanced) return null\n    const inner = parseRoleName(balanced.inner)\n    if (!inner) return null\n    if (!balanced.rest.startsWith('#')) return null\n    const index = readIndex(balanced.rest.slice(1))\n    return index === null ? null : { kind: 'splinter', inner, index }\n  }\n\n  if (text.startsWith('hole:')) {\n    // `hole:<i>/<inner>`：先切 index，再整体递归 inner（inner 内还可有 `/`）。\n    const remainder = text.slice('hole:'.length)\n    const slash = remainder.indexOf('/')\n    if (slash < 0) return null\n    const index = readIndex(remainder.slice(0, slash))\n    if (index === null) return null\n    const inner = parseRoleName(remainder.slice(slash + 1))\n    return inner ? { kind: 'hole', index, inner } : null\n  }\n\n  if (text.startsWith('replica[')) {\n    const close = text.indexOf(']')\n    if (close < 0) return null\n    const k = readIndex(text.slice('replica['.length, close))\n    if (k === null) return null\n    const rest = text.slice(close + 1)\n    if (!rest.startsWith('/')) return null\n    const inner = parseRoleName(rest.slice(1))\n    return inner ? { kind: 'replica', k, inner } : null\n  }\n\n  // 兜底：semantic（保留字已在上面被结构分支吃掉，故此处不会歧义）\n  if (!SEMANTIC_NAME_RE.test(text)) return null\n  if ((RESERVED_KEYWORDS as readonly string[]).includes(text)) return null\n  return { kind: 'semantic', name: text }\n}\n\n// ── 构造子（七个 kind 各一个）──\n//\n// 存在理由：把「契约校验」收在一处。调用点直接写字面量会绕过 `assertIndex` /\n// `assertSemanticName`，于是不合法的 role 在 `formatRoleName` 才炸——\n// 那时已经离出错点很远（可能跨了一次执行）。构造子让非法值**在产生点**就报错。\n\n/**\n * 造一个 `semantic` role（op 声明的封闭词汇）。\n *\n * @param name - the op's closed-vocabulary name.\n * @returns the role.\n * @throws RoleNameError when the name is malformed or shadows a structural keyword.\n */\nexport function semantic(name: string): RoleName {\n  assertSemanticName(name)\n  return { kind: 'semantic', name }\n}\n\n/**\n * 造一个 `wall` role（输入 profile 第 i 条边扫出/旋出的侧面）。\n *\n * @param index - zero-based profile-edge index.\n * @returns the role.\n * @throws RoleNameError when the index is not a non-negative integer.\n */\nexport function wall(index: number): RoleName {\n  assertIndex(index, 'wall index')\n  return { kind: 'wall', index }\n}\n\n/**\n * 造一个 `hole` role（第 j 个内环下的同名子结构）。\n *\n * @param index - zero-based inner-loop index.\n * @param inner - the local role inside that loop.\n * @returns the role.\n * @throws RoleNameError when the index is not a non-negative integer.\n */\nexport function hole(index: number, inner: RoleName): RoleName {\n  assertIndex(index, 'hole index')\n  return { kind: 'hole', index, inner }\n}\n\n/**\n * 造一个 `replica` role（pattern 的第 k 份）。\n *\n * @param k - zero-based replica index.\n * @param inner - the local role inside that replica.\n * @returns the role.\n * @throws RoleNameError when k is not a non-negative integer.\n */\nexport function replica(k: number, inner: RoleName): RoleName {\n  assertIndex(k, 'replica k')\n  return { kind: 'replica', k, inner }\n}\n\n/**\n * 造一个 `splinter` role（split 的第 j 片）。\n *\n * @param inner - the local role of the face being split.\n * @param index - zero-based splinter index.\n * @returns the role.\n * @throws RoleNameError when the index is not a non-negative integer.\n */\nexport function splinter(inner: RoleName, index: number): RoleName {\n  assertIndex(index, 'splinter index')\n  return { kind: 'splinter', inner, index }\n}\n\n/**\n * 造一个 `generated` role（fillet/chamfer 过渡面）。\n *\n * @param op - the producing op ('fillet' / 'chamfer').\n * @param index - zero-based index among that op's generated faces.\n * @returns the role.\n * @throws RoleNameError when op or index violates the contract.\n */\nexport function generated(op: string, index: number): RoleName {\n  assertOpName(op)\n  assertIndex(index, 'generated index')\n  return { kind: 'generated', op, index }\n}\n\n/**\n * 造一个 `imported` role（`import_brep` 的原始面序）。\n *\n * @param index - zero-based face index in the imported shape's enumeration order.\n * @returns the role.\n * @throws RoleNameError when the index is not a non-negative integer.\n */\nexport function imported(index: number): RoleName {\n  assertIndex(index, 'imported index')\n  return { kind: 'imported', index }\n}\n"]}

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

@@ -12,8 +12,9 @@
 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 { StmtId } from '../../identity.js';
 import type { RoleTable } from './types.js';
+import { type RoleName } from './role-name.js';
 /** 主轴判定阈值：abs(component) > 0.9 视为轴对齐。 */
 export declare const AXIS_THRESHOLD = 0.9;
 /** Re-export：hash 键演化（decodeHashEvolution 产出，见 brep/face-evolution.ts §2.4）。 */
@@ -22,19 +23,24 @@ 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.
+ * @returns the cardinal role (semantic 'top' etc.), or undefined when no axis dominates.
  */
-export declare function boxRoleFromNormal(n: readonly [number, number, number]): string | undefined;
+export declare function boxRoleFromNormal(n: readonly [number, number, number]): RoleName | undefined;
 /**
- * 给链根 shape 建 RoleTable（单个 origin 的表；§3.2）。
+ * 给链根 shape 建 role 子表（单 origin；§3.2）。
  *
- * 语义优先、位置兜底；assign 时只保留 hash + hint，不保留面句柄
+ * 语义命名优先；**位置兜底已删**（Phase 1.7，计划 §4.2 R3：`${opType}:face_${i}`
+ * 里的 index 是 OCCT 枚举序号，OCCT 不承诺面序稳定，改参即漂——真正抗重放的
+ * 只有语义 role）。无语义名的面**不进表**：缺身份是显式状态（naming 行 role=null），
+ * 不是可伪造的名字。R1（局部唯一）由构造保证：同语句内一个 role 只指一个面。
+ *
+ * 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 表）。
+ * @param opType - the chain-root operation type ('box'/'cylinder'/...)。
+ * @returns role → hash 子表（role 为 RoleName 线格式串；仅语义命中的面）。
  */
 export declare function assignRoles(kernel: BrepEngineApi, shape: BrepHandle, opType: string): Map<string, number[]>;
 /**
@@ -57,7 +63,7 @@ export declare function nextHashes(hashes: readonly number[], evolution: HashEvo
  * @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;
+export declare function propagateRoles(roles: RoleTable, origin: StmtId, evolution: HashEvolution): RoleTable;
 /**
  * 沿一次 hash 演化推进 RoleTable 的**所有** origin（单父 op 用，§3.3）。
  *
@@ -73,27 +79,19 @@ export declare function propagateAllOrigins(roles: RoleTable, evolution: HashEvo
  * 布尔合流：合并两个来源的 role 表（§3.4，faijs 对 brepjs 的必要扩展）。
  *
  * 对 A、B 两张 hash 演化分别传播各自的表后合并；布尔新生成的缝面/刃面
- * 以本次布尔语句的 LHS 变量名（= outPart）为新 origin，位置名命名。
+ * 以本次布尔**语句的 StmtId** 为新 origin（Phase 1.6：不再用 LHS 变量名）。
+ * 缝面**不再给位置名**（Phase 1.7：位置兜底已删）——登记空子表占位，
+ * 面身份待 Phase 3 的 kernel/byAdjacency 词汇补齐；naming 行将显式 role=null。
  *
  * @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 表示不补).
+ * @param outStmt - the boolean statement's StmtId (new origin for seam faces).
+ * @param seamCount - how many seam/generated faces to register (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[]>;
+export declare function mergeRoleTables(targetTable: RoleTable, targetEvo: HashEvolution, toolTable: RoleTable, toolEvo: HashEvolution, outStmt: StmtId, seamCount: number): RoleTable;
 /**
  * 序号 → role 反查（§3.7 生成 ExecutionResult.naming 用）。
  *