@faicad/faijs 0.13.1 → 0.14.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"lineage-resolve.js","sourceRoot":"","sources":["../../../src/topology/naming/lineage-resolve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * lineage-resolve.ts — 回走推进器（1.10 前置②，计划 §4.5）。\n *\n * 「产物上的 roleTable 只是缓存」的重算引擎：缓存 miss 时沿血缘 DAG\n * 从身份原点 `(origin, role)` 走到目标 part，产出该 role 在目标 part 上的\n * 面 hash 集合——与 `slot.roleTable.get(origin)?.get(role)` 语义等价。\n *\n * ## 推进载体：序号（ordinal），不是 hash\n *\n * hash 是内存指针哈希，跨 Shape 实例必变（copy 一个新 handle，hash 全换），\n * **不能**作为跨节点推进的载体。跨节点稳定的是两样东西：\n * - role（因果坐标，本机制的存在理由）；\n * - 面枚举序号（`slot.faceEvolution` 记录的正是 ordinal→ordinal[] 的演化，\n *   1.10 前置①已把每个 brep op 的演化挂到血缘节点）。\n *\n * 推进三步：\n * 1. **锚定**：root 语句的输出 part 上，role → hash 集合（读 root 的现存\n *    roleTable——它现在是缓存，读它是合法的），再换算成 root 上的序号集合；\n * 2. **逐节点推进**：沿 DAG 每个节点用其 `evolution`（ordinal 键）把序号集合\n *    映射到输出序号（`evo.get(o) ?? [o]`——\"未变\"的两种上报形态都容纳）；\n * 3. **落地**：目标 part 上把最终序号集合换算回 hash 集合。\n *\n * 任一步数据缺失 → 返回结构化失败原因（不静默返回空集——空集会被上层当成\n * \"面被删除\"，那是另一个语义）。\n */\n\nimport type { PartName, StmtId } from '../../identity'\nimport type { LineageGraph } from './lineage'\nimport { parseRoleName, formatRoleName } from './role-name'\n\n/** 回走所需的外部读口（由调用方注入：runtime 持有 kernel 与 slots）。 */\nexport interface LineageResolveDeps {\n  /** part 的 BREP 句柄（回走链上的中间产物经 solidCache 存活）。 */\n  brepOf: (part: PartName) => unknown | undefined\n  /** 句柄的全部面 hash（枚举序 = ordinal 1 起，与 faceEvolution 同序）。 */\n  faceHashes: (handle: unknown) => readonly number[]\n  /** 读某 part 的 roleTable 缓存（root 锚定用；返回 origin→role→hash[]）。 */\n  roleTableOf: (part: PartName) => ReadonlyMap<string, ReadonlyMap<string, readonly number[]>> | undefined\n}\n\n/** 回走失败原因（结构化，不静默）。 */\nexport type LineageResolveFailure =\n  | { readonly reason: 'no-lineage-node'; readonly stmt: string }\n  | { readonly reason: 'no-root-part'; readonly stmt: string }\n  | { readonly reason: 'no-handle'; readonly part: string }\n  | { readonly reason: 'no-role-table'; readonly part: string }\n  | { readonly reason: 'role-not-in-table'; readonly origin: string; readonly role: string }\n  | { readonly reason: 'hash-not-found'; readonly part: string; readonly count: number }\n  | { readonly reason: 'no-evolution'; readonly stmt: string; readonly op: string }\n\n/** 回走成功：role 在目标 part 上的面 hash 集合。 */\nexport interface LineageResolveSuccess {\n  readonly hashes: readonly number[]\n}\n\n/**\n * 沿血缘 DAG 回走：`(origin, role)` → 目标 part 上的 hash 集合。\n *\n * @param graph - the lineage graph (registered per execution).\n * @param origin - the origin statement id of the identity.\n * @param roleLine - the role in wire format (as stored in TopoRef).\n * @param targetPart - the part whose snapshot we resolve against.\n * @param deps - external readers (handles / hashes / role-table cache).\n * @returns success with the hash set, or a structured failure.\n */\nexport function resolveViaLineage(\n  graph: LineageGraph,\n  origin: StmtId,\n  roleLine: string,\n  targetPart: PartName,\n  deps: LineageResolveDeps,\n): LineageResolveSuccess | LineageResolveFailure {\n  const role = parseRoleName(roleLine)\n  if (!role) return { reason: 'role-not-in-table', origin, role: roleLine }\n\n  // ── 链收集：origin 节点 →（经消费者边）→ 产出 targetPart 的节点 ──\n  // 行走方向是「origin → 谁消费了我的输出 → 谁又消费了它的输出」：\n  // 中间 part 的产出方是 origin 自己（stmtOf 指回原点），不能用产出方找下一步。\n  const chain: { stmt: StmtId; part: PartName; evolution?: Map<number, number[]> }[] = []\n  {\n    const start = graph.node(origin)\n    if (!start) return { reason: 'no-lineage-node', stmt: String(origin) }\n    const rootPart = start.outputs[0]\n    if (!rootPart) return { reason: 'no-root-part', stmt: String(origin) }\n    const startEvo = start.evolution && !('modified' in start.evolution) ? (start.evolution as Map<number, number[]>) : undefined\n    chain.push({ stmt: origin, part: rootPart, evolution: startEvo })\n    let currentPart: PartName = rootPart\n    while (!chain[chain.length - 1]!.part || true) {\n      if (currentPart === targetPart) break\n      const consumer = graph.nodeConsuming(currentPart)\n      if (!consumer) return { reason: 'no-lineage-node', stmt: String(currentPart) }\n      const evo = consumer.evolution && !('modified' in consumer.evolution) ? (consumer.evolution as Map<number, number[]>) : undefined\n      // 承载 part：消费者的输出里选一个（单输出链取第一个；多输出如 split 取含\n      // targetPart 的那个，否则取第一个——多输出分支的精确选择由调用方语义决定）。\n      const carry = consumer.outputs.includes(targetPart) ? targetPart : consumer.outputs[0]!\n      chain.push({ stmt: consumer.stmt, part: carry, evolution: evo })\n      currentPart = carry\n    }\n  }\n\n  // ── 锚定：root part 上 role → hash → ordinal ──\n  const root = chain[0]!\n  const rootHandle = deps.brepOf(root.part)\n  if (rootHandle === undefined) return { reason: 'no-handle', part: root.part }\n  const rootTable = deps.roleTableOf(root.part)\n  if (!rootTable) return { reason: 'no-role-table', part: root.part }\n  // root 的 roleTable 键形：origin（StmtId 串）→ role 线格式 → hashes。\n  const rootHashes = rootTable.get(String(origin))?.get(roleLine)\n  if (rootHashes === undefined || rootHashes.length === 0) {\n    return { reason: 'role-not-in-table', origin, role: roleLine }\n  }\n  const rootAll = deps.faceHashes(rootHandle)\n  let ordinals: number[] = []\n  for (const h of rootHashes) {\n    const idx = rootAll.indexOf(h)\n    if (idx < 0) return { reason: 'hash-not-found', part: root.part, count: rootHashes.length }\n    ordinals.push(idx + 1) // ordinal 1 起\n  }\n\n  // ── 逐节点推进（ordinal 键演化；链上首节点是原点，其演化作用于其输入，\n  //     因此推进从链的第二个节点开始）──\n  for (let i = 1; i < chain.length; i++) {\n    const node = chain[i]!\n    if (!node.evolution) {\n      // identity 类 op（copy/place/transform）登记时 slot 里有 identityEvolution；\n      // 演化缺失说明该节点未按 1.10 前置①挂接 —— 显式失败，不默认恒等。\n      const g = graph.node(node.stmt)\n      return { reason: 'no-evolution', stmt: node.stmt, op: g?.op ?? '?' }\n    }\n    ordinals = ordinals.flatMap((o) => node.evolution!.get(o) ?? [o])\n  }\n\n  // ── 落地：目标 part 上 ordinal → hash ──\n  const last = chain[chain.length - 1]!\n  const targetHandle = deps.brepOf(last.part)\n  if (targetHandle === undefined) return { reason: 'no-handle', part: last.part }\n  const targetAll = deps.faceHashes(targetHandle)\n  const hashes: number[] = []\n  for (const o of ordinals) {\n    const h = targetAll[o - 1]\n    if (h === undefined) return { reason: 'hash-not-found', part: last.part, count: ordinals.length }\n    hashes.push(h)\n  }\n  return { hashes }\n}\n\n// formatRoleName 在 API 面保留导出（role 线格式与 TopoRef 序列化的唯一权威），\n// 本模块仅经 parseRoleName 校验线格式合法性。\nexport { formatRoleName }\n"]}

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

@@ -0,0 +1,349 @@
+/**
+ * lineage.ts — 血缘图登记（计划 §4.3）。
+ *
+ * 每个 op 执行完登记一条 `LineageNode`：**谁（`StmtId`）用什么 op、吃了哪些
+ * part、产出哪些 part、属哪个 provenance 类别**。两张表：
+ *
+ * | 表 | 键 → 值 | 用途 |
+ * |---|---|---|
+ * | `lineage` | `StmtId` → `LineageNode` | 从身份原点沿 DAG 前进 |
+ * | `partToStmt` | `PartName` → `StmtId` | 从 part 名字反查是哪条语句造的 |
+ *
+ * ## 为什么这一层必须存在
+ *
+ * 现状把身份表达成 **hash**（`face-evolution.ts` 的内存指针哈希），于是每次查询都在
+ * 付「对齐 hash」的利息：谁改了几何，谁的 hash 就变，身份就断。正确形态是
+ * `(StmtId, RoleName)` 的**因果坐标**——`StmtId` 说「哪条语句产生」，`RoleName` 说
+ * 「那条语句把它当作什么」。因果坐标不随几何变化，**也不需要知道中间过了几个 op**。
+ *
+ * ## 登记口只能有一个（但调用点有两个）
+ *
+ * 手写 op 走 `wrapBrepOne`（`define-op.ts`），生成投影走 `compatOp`
+ * （`api/internal/compat-op.ts`）——**两条路径都必须登记**，否则 42 条投影永远无名。
+ * 但两条路径共用一个 `register()`，规则才只有一处。
+ *
+ * ## 三条硬规则（这是「未来漏洞最少」的核心）
+ *
+ * | # | 规则 | 违反时 |
+ * |---|---|---|
+ * | **N1** | inputs 里任一 Shape 查不到 `PartName` → 报错 | `E_TOPO_UNTRACKED_INPUT` |
+ * | **N2** | 当前语句锚点缺失，或与声明的 `stmt` 不符 → 报错 | `E_TOPO_NO_ANCHOR` |
+ * | **N3** | 同一 `StmtId` 重复登记且**身份内容**不同 → 报错 | `E_TOPO_DUPLICATE_STMT` |
+ *
+ * **N1 为什么必须是错误而不是"默认成链根"**：op 内部常临时造 Shape（中间产物、
+ * 工具件）。若给它们默认一个 origin，「看起来对但语义错」的身份就诞生了——
+ * 引用能解析成功，但解析到**别的面**。这类错误不会在测试里暴露（测试用的参数恰好
+ * 让两者重合），只会在用户改参数、改尺寸时暴露。**宁可在执行期就炸。**
+ *
+ * **N2 为什么现在才敢做**：它依赖 `getCurrentStmt()` 是"当前语句的权威读法"。
+ * 这一点由约束 **C1（禁止并发多 runtime）** 保证（见 §4.7.1）——不是"全局态凑合能用"。
+ *
+ * ## 依赖注入，不读全局
+ *
+ * `register()` 收一个 `LineageDeps`（`nameOf` / `currentStmt`）而不是 import
+ * `runtime-state`。理由有两条：其一，`topology/` 现有模块（如 `roles.ts`）都是
+ * "把依赖当参数"的风格，读全局会破坏它；其二，N1/N2/N3 的测试不想去摆弄全局态。
+ */
+import type { PartName, StmtId } from '../../identity.js';
+import type { HashEvolution } from '../../brep/face-evolution.js';
+import { type RoleName } from './role-name.js';
+/**
+ * 新造面的获取方式（只有 `kernel` / `construct` 需要）。
+ *
+ * - `byAdjacency`：靠结果形状与输入的**邻接关系**推出哪个面是新造的
+ *   （布尔/倒角等：新面必然与已知面相邻，而幸存面有自己的坐标）
+ * - `explicit`：op 直接给出词汇表（构造类：底面 = profile、侧面 i = 第 i 条边扫掠）
+ *
+ * ⚠️ **不能靠内核的 `generated` 桶**（Phase 0.4 实测）：它与 `modified` 同构分段、
+ * 键集相同，值是各输入面派生的**中间形**——`cut` 里 12 个 hash 结果里 0 存活，
+ * `fillet`/`fuse` 里整桶为空。故 `byAdjacency` / `explicit` 是**必填**。
+ */
+export type NewFaceRule = {
+    readonly via: 'byAdjacency';
+} | {
+    readonly via: 'explicit';
+    readonly vocab: readonly RoleName[];
+};
+/**
+ * 六个 provenance 类别（计划 §4.4，封闭集）。
+ *
+ * **继承面的处置完全由类别决定，op 不写**；只有 `construct` 和 `kernel` 会造新面，
+ * 才有词汇这一项 ⇒ `identity` / `subdivide` / `replicate(k)` **零声明**。
+ *
+ * 本表是**类别归属**，不是接线状态（例：`sweep` 属 `construct` 类但未接线，见 §1 D10）。
+ */
+export type Provenance = 
+/** 内核给历史：boolean / fillet / chamfer / shell / offset / 刚体变换 */
+{
+    readonly kind: 'kernel';
+    readonly newFaces: NewFaceRule;
+}
+/** 输出面 ↔ 输入的构造规则：extrude / revolve / sweep / loft / primitives / sketch / import_brep */
+ | {
+    readonly kind: 'construct';
+    readonly newFaces: Extract<NewFaceRule, {
+        via: 'explicit';
+    }>;
+}
+/** 1:1，第 i 面 → 第 i 面：copy / place / clone / locate / applyMatrix */
+ | {
+    readonly kind: 'identity';
+}
+/** 每输入面 → 若干片：split / section */
+ | {
+    readonly kind: 'subdivide';
+}
+/** 第 k 份第 i 面 ← 第 i 面：linearPattern / circularPattern / gridPattern / rectangularPattern / mirrorJoin */
+ | {
+    readonly kind: 'replicate';
+    readonly k: number;
+}
+/** 显式记账：算不出来。应趋近于 0；审计测试必须列出全部并给出理由 */
+ | {
+    readonly kind: 'unmodeled';
+    readonly reason: string;
+};
+/** `Provenance` 的类别标签（封闭六值）。 */
+export type ProvenanceKind = Provenance['kind'];
+/** 六个类别标签，供审计测试枚举（新增类别必须同步此处）。 */
+export declare const PROVENANCE_KINDS: readonly ["kernel", "construct", "identity", "subdivide", "replicate", "unmodeled"];
+/**
+ * 演化记录（`kind='kernel'` 时执行期补挂）。
+ *
+ * 两种形态并存（1.10 前置①实测）：
+ * - **序号键**（`slot.faceEvolution` 的实际存储形态，`Map<ordinal, ordinal[]>`）：
+ *   boolean/fillet/chamfer 走 `decodeEvolution`（逐句柄 hashCode），copy/transform/place
+ *   走 `identityEvolution`（恒等）。回走推进 identity 类与"序号不变"的 kernel 路径用它。
+ * - **哈希键**（`HashEvolution`，`decodeHashEvolution` 的输出）：只在 booleanWithRoleTable
+ *   等组合函数内部瞬时存在，不落 slot。回走按哈希集合推进时用它。
+ */
+export type EvolutionRecord = Map<number, number[]> | HashEvolution;
+/**
+ * 判断演化记录是否为哈希键形态（`HashEvolution` 有 `modified`/`deleted` 字段）。
+ *
+ * @param e - the evolution record to test.
+ * @returns true when the record is the hash-key form (`HashEvolution`).
+ */
+export declare function isHashEvolution(e: EvolutionRecord): e is HashEvolution;
+/**
+ * 血缘图的一个节点 = 一条语句的登记记录。
+ *
+ * `inputs`/`outputs` 是 `PartName`（不是 Shape）：Shape 是执行期的活对象，
+ * 身份层必须只留**可序列化、可比较**的东西，否则节点会随 arena 释放而失去意义。
+ */
+export interface LineageNode {
+    /** 该语句的 id（`ExecutionAnchor.id`），全局唯一。 */
+    readonly stmt: StmtId;
+    /** op 名（如 `cad.fillet`）——用于报错信息与审计。 */
+    readonly op: string;
+    /** 输入 part 名（`inputs.map(nameOf)` 的结果，已保证全部有名字）。 */
+    readonly inputs: readonly PartName[];
+    /** 产出 part 名（至少一个）。 */
+    readonly outputs: readonly PartName[];
+    /** provenance 类别 + 该类别的载荷。 */
+    readonly provenance: Provenance;
+    /** `kind='kernel'` 时执行期记录的 hash 演化（`attachEvolution` 事后补上）。 */
+    readonly evolution?: EvolutionRecord;
+}
+/**
+ * 登记入参（尚未解析成 `PartName` 的形态）。
+ *
+ * `inputs` 故意收 **Shape 句柄**而不是 `PartName`：N1 的判据就是
+ * "这个 Shape 有没有名字"，若调用方先自己 map 成名字，就正好把
+ * "查不到名字"这一步跳过/默认了——那正是 N1 要防的。
+ */
+export interface LineageDraft {
+    /** 声明本条语句的 id（N2 会与当前锚点核对）。 */
+    readonly stmt: StmtId;
+    /** op 名。 */
+    readonly op: string;
+    /** 输入 Shape 句柄（N1 在 register 内解析）。 */
+    readonly inputs: readonly object[];
+    /** 产出 part 名（非空；调用方从锚点/nameOf 拿到）。 */
+    readonly outputs: readonly [PartName, ...PartName[]];
+    /** provenance 类别 + 载荷。 */
+    readonly provenance: Provenance;
+}
+/** 登记所需的外部读口（由调用点注入，见文件头「依赖注入」）。 */
+export interface LineageDeps {
+    /** Shape → PartName（`runtime-state` 的 `nameOf`）。 */
+    readonly nameOf: (shape: object) => PartName | undefined;
+    /** 当前执行语句锚点（`runtime-state` 的 `getCurrentStmt`）。 */
+    readonly currentStmt: () => {
+        readonly id: string;
+    } | undefined;
+}
+/** 血缘登记错误码（三条规则 N1/N2/N3）。 */
+export type LineageErrorCode = 'E_TOPO_UNTRACKED_INPUT' | 'E_TOPO_NO_ANCHOR' | 'E_TOPO_DUPLICATE_STMT';
+/** 血缘登记失败。带稳定错误码，禁止静默兜底。 */
+export declare class LineageError extends Error {
+    /** 稳定错误码（宿主/args 校验按码识别）。 */
+    readonly code: LineageErrorCode;
+    /** 出错的语句 id（若能确定）。 */
+    readonly stmt?: string;
+    /**
+     * @param code - the stable error code.
+     * @param message - what went wrong, with the offending statement named.
+     * @param stmt - the statement id, when known.
+     */
+    constructor(code: LineageErrorCode, message: string, stmt?: string);
+}
+/**
+ * 两个 `RoleName` 是否相等（按值、递归）。
+ *
+ * 手写而不是 `JSON.stringify` 比较：键序会随写字面量的顺序变化
+ * （`{index, op}` 与 `{op, index}` 是同一个值、不同的 JSON），
+ * 而这两个函数是 N3「内容不同才报错」的判据——键序敏感会**误报冲突**。
+ *
+ * @param a - one role name.
+ * @param b - the other role name.
+ * @returns true when the two roles are structurally identical.
+ */
+export declare function roleNameEquals(a: RoleName, b: RoleName): boolean;
+/**
+ * 两条新造面规则是否相等（词汇表**逐项按序**比较——顺序是构造语义的一部分：
+ * 侧面 i 对应第 i 条 profile 边，重排就是换了一个 role）。
+ *
+ * @param a - one rule.
+ * @param b - the other rule.
+ * @returns true when the two rules are structurally identical.
+ */
+export declare function newFaceRuleEquals(a: NewFaceRule, b: NewFaceRule): boolean;
+/**
+ * 两个 `Provenance` 是否相等（按值）。
+ *
+ * @param a - one provenance.
+ * @param b - the other provenance.
+ * @returns true when they are structurally identical.
+ */
+export declare function provenanceEquals(a: Provenance, b: Provenance): boolean;
+/**
+ * 血缘图：两张表 + 一个登记函数。
+ *
+ * 实例化而非全局单例，是为了让 N1/N2/N3 的测试各用各的图、互不污染；
+ * 执行期由 `runtime-state` 侧持有唯一实例（C1 保证单 runtime，不存在两图并存）。
+ */
+export declare class LineageGraph {
+    private readonly nodes;
+    private readonly partOwner;
+    /**
+     * 执行期旁挂：语句输出 part 的 roleTable（1.10 前置③）。
+     *
+     * 回走锚定需要 root 语句的「origin→role→hash[]」表；它本来只存在
+     * `slot.roleTable`（解析缓存）里，删字段后唯一落点就是这里。
+     * 不进 `LineageNode`（节点是身份数据，N3 比较不含它）。
+     */
+    private readonly outputTables;
+    /**
+     * 执行期旁挂：语句输出 part 的 BREP 句柄（回走锚定/落地做 ordinal↔hash 换算用）。
+     * 句柄是活对象不进节点；随 `clear()` 一起清（句柄生命周期由 solidCache 管）。
+     */
+    private readonly outputHandles;
+    /**
+     * 执行期旁挂：**part 名键**的 roleTable（1.10 前置③，op 读输入表用）。
+     *
+     * 为什么有语句键还要 part 键：op 实现读的是「输入 part 的表」。按语句反查
+     * （stmtOf(part)）在重赋值下会指到**本语句**——register 先于 impl 执行，
+     * `part0 = translate(part0)` 的 partOwner 已被 s2 覆盖，impl 读输入表时
+     * 拿到的是自己的输出。part 键表只在 `recordOutput`（impl 内 fromBrep 时）
+     * 才覆盖 ⇒ impl 读表时看到的仍是上一条语句记录的旧表——时序天然正确。
+     */
+    private readonly outputTablesByPart;
+    /**
+     * 登记一条语句（N1/N2/N3 全在这里校验）。
+     *
+     * @param draft - the statement's lineage facts (inputs still as Shape handles).
+     * @param deps - the injected readers (`nameOf` / `currentStmt`).
+     * @returns the stored node.
+     * @throws LineageError on N1 (untracked input), N2 (anchor mismatch), or N3 (conflicting re-register).
+     */
+    register(draft: LineageDraft, deps: LineageDeps): LineageNode;
+    /**
+     * 事后补挂 hash 演化（`kind='kernel'` 用）。
+     *
+     * 与 `register` 分开是因为演化记录发生在几何算完之后，而登记发生在调用边界；
+     * 合成一个操作会让 N3 的"内容比较"必须处理"evolution 可能晚到"的时序问题。
+     *
+     * @param stmt - the statement whose evolution to attach.
+     * @param evolution - the hash evolution produced by this statement.
+     * @throws LineageError when the statement was never registered.
+     */
+    attachEvolution(stmt: StmtId, evolution: EvolutionRecord): void;
+    /**
+     * 按语句 id 取节点。
+     *
+     * @param stmt - the statement id to look up.
+     * @returns the statement's LineageNode, or undefined when not registered.
+     */
+    node(stmt: StmtId): LineageNode | undefined;
+    /**
+     * 按 part 名反查产出它的语句 id。
+     *
+     * @param part - the part name to look up.
+     * @returns the producing statement id, or undefined when unowned.
+     */
+    stmtOf(part: PartName): StmtId | undefined;
+    /**
+     * 按 part 名反查产出它的节点。
+     *
+     * @param part - the part name to look up.
+     * @returns the producing node, or undefined when unowned.
+     */
+    nodeOfPart(part: PartName): LineageNode | undefined;
+    /**
+     * 找把 `part` 作为输入的下游节点（回走推进用，1.10 前置②）。
+     *
+     * 链行走的方向是「origin → 消费者 → 消费者的消费者」：中间 part 的产出方
+     * 是 origin 自己（`stmtOf` 指回原点），不能用产出方找下一步。
+     *
+     * @param part - the part name consumed by the wanted node.
+     * @returns the first (registration-order) node whose inputs contain the part.
+     */
+    nodeConsuming(part: PartName): LineageNode | undefined;
+    /** 已登记的语句数。 */
+    get size(): number;
+    /** 清空（每次执行开始时调用——一次执行内 `StmtId` 稳定）。 */
+    clear(): void;
+    /**
+     * 记录语句输出 part 的 roleTable 与句柄（1.10 前置③，执行期旁挂）。
+     *
+     * 调用点：`define-op.wrapped` 的 brep 分支——登记血缘时（或补挂演化时）
+     * 顺手记录，读口是 `getSlot(outShape)`。表/句柄都可选（构造类 op 可能两者皆无）。
+     *
+     * @param stmt - the statement whose output is recorded.
+     * @param roleTable - the output part's role table (origin→role→hash[]), if any.
+     * @param solid - the output part's BREP handle, if any.
+     * @param part - the output part name to also key the table under (part-key authority), if any.
+     */
+    recordOutput(stmt: StmtId, roleTable?: ReadonlyMap<string, ReadonlyMap<string, readonly number[]>>, solid?: unknown, part?: PartName): void;
+    /** 读语句输出 part 的 roleTable（回走锚定用）。
+     *
+     * @param stmt - the statement whose output table to read.
+     * @returns the statement-keyed role table, or undefined when none was recorded.
+     */
+    outputTableOf(stmt: StmtId): ReadonlyMap<string, ReadonlyMap<string, readonly number[]>> | undefined;
+    /** 读语句输出 part 的 BREP 句柄（回走 ordinal↔hash 换算用）。
+     *
+     * @param stmt - the statement whose output handle to read.
+     * @returns the statement-keyed BREP handle, or undefined when none was recorded.
+     */
+    outputHandleOf(stmt: StmtId): unknown | undefined;
+    /**
+     * 读 part 名键的 roleTable（op 实现读**输入**表用，1.10 前置③）。
+     *
+     * 语义 = 旧 `getSlot(input)?.roleTable`：impl 执行时刻，该 part 的表是
+     * 上一条语句 `recordOutput` 记录的那份（本语句的覆盖发生在 impl 内
+     * fromBrep 时，晚于任何输入读）。未记录（mesh 产物 / 未接血缘）→ undefined。
+     *
+     * @param part - the output part name whose role table to read.
+     * @returns the part-keyed role table, or undefined when not recorded.
+     */
+    tableOfPart(part: PartName): ReadonlyMap<string, ReadonlyMap<string, readonly number[]>> | undefined;
+}
+/**
+ * 执行期共用的血缘图实例。
+ *
+ * 唯一性由约束 C1（禁止并发多 runtime）保证；测试请自建 `new LineageGraph()`。
+ */
+export declare const runtimeLineage: LineageGraph;
+//# sourceMappingURL=lineage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lineage.d.ts","sourceRoot":"","sources":["../../../src/topology/naming/lineage.ts"],"names":[],"mappings":"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"}