RandomizedToroidalWildFirstPaths

本页所有地址都适用于来自 libtpu-0.0.40-cp314-cp314-manylinux_2_31_x86_64 wheel 的 libtpu.so（build-id md5 89edbbe81c5b328a958fe628a9f2207d，781,691,048 字节，未 strip）。在整个 .text 中 VA == file offset。其他版本会有差异。

摘要

RandomizedToroidalWildFirstPaths 是 per-(src,dst) route generator，在有故障的 3D ICI torus 上生成 deadlock-free、fault-avoiding paths。它是 resilient-routing 层的 live fallback：当 bring-up 找不到匹配 slice 已发现 fault pattern 的预烘焙 ToroidalRouteCache 时，deduplicator 会为每个 chip pair 运行这个 generator，并即时构建 routing table。85 个预烘焙 caches 是同一算法离线计算得到的输出，因此本页同时记录 cache-hit producer 和 cache-miss fast path。产生它的 source unit 是 platforms/accel_ssw/deepsea/slice_builder/tools/lib/toroidal_wild_first_paths.cc 及其 randomized_* subclass 文件（二者都由二进制中的字符串锚定）。

该算法是 dimension-order routing (DOR) 加 “wild-first” 扰动。对每个 (src,dst)，它先尝试 minimal DOR path：严格 total-order axis traversal，这是教科书式的 torus deadlock-free base。如果 minimal path 穿过故障链路，它进入 wild loop：先在某个 axis 走一次刻意非最短 hop（“wild first”），然后对剩余部分恢复严格 DOR。wild hop 将路径推离故障 lattice cell；DOR remainder 保持 channel-dependency graph 无环。熟悉 Glass–Ni turn-model routing 或 dateline virtual-channel torus DOR 的重新实现者会认出这个形状：一个受限的 non-DOR turn，经 half-turn symmetry constraint 验证，就是全部 fault-avoidance 自由度。

NOTE — 这里的 “Randomized” 不是带 seed 的运行时 PRNG。它是确定性的 multi-path policy。RandomizedToroidalWildFirstPaths（PathType=1）将每一条 fault-free wild path 保留为等成本 candidate set，使 all-reduce/runtime 层可以在其中做 load-balance；NonRandomizedToroidalWildFirstPaths（PathType=0）只保留第一条有效路径。路由层用于“randomize”的“seed”是确定性的 WildFirstDimensionOrder（dimensions 的 introsort，0x1fbefc20）加上 install time 应用的 runtime spreading hash；generator 中没有随机状态。见 § Randomized vs Non-Randomized。

确定性的 single static path（GetStaticPath，单数）和 per-color route schedule 由同级页面负责；本页负责 *ToroidalWildFirstPaths 算法、wild-first exploration、toroidal wrap handling、periodic fault lattice，以及生成的 candidate set 如何馈入 route table。

对重新实现而言，契约是：

• Paths(src,dst) dispatch：self-route short-circuit（内联构造 trivial all-ones path），然后 general-case 按 fault set 分裂到 PathsWithoutFaults（空）/ PathsWithFaults（非空）。
• DOR base：PathFromDistance + AppendHopsToPath：对 torus-reduced distance vector 进行严格 dimension-order traversal。
• wild-first loop：一个 non-minimal Walk hop，WildHopToPath remainder（forward+reverse split），IsFaultFreePath validation，以及 keep-all-vs-keep-first policy。
• periodic fault model：IsFaultFreeLink：一个物理 fault 是一个逻辑故障链路 lattice，通过 per-dimension modular comparison 与 symmetry period 测试。
• toroidal wrap / deadlock guarantee：严格 dimension order 加 HalfwayDirections / UpdateSymmetryForHalfway（dateline/half-turn symmetry phase）。
• construction gate：CreateInternal：每个 dimension 上 topology_size[dim] % fault_symmetry == 0，否则不存在 resilient route。

Entry point (Randomized)	RandomizedToroidalWildFirstPaths::Paths 0x1fbe9fc0
Fault-aware generator	PathsWithFaults 0x1fbea380
No-fault short path	PathsWithoutFaults 0x213dc800
DOR base	PathFromDistance 0x1fbeea20 + AppendHopsToPath 0x1fbeb600
Wild remainder (Randomized)	WildHopToPath 0x1fbeb2c0
Fault lattice	IsFaultFreeLink 0x1fbede40, IsFaultFreePath 0x1fbee0c0
Deadlock phase	HalfwayDirections 0x1fbee280, UpdateSymmetryForHalfway 0x1fbee7c0
Construction gate	CreateInternal 0x1fbeb720; factories CreateRandomized 0x1fbedc20 / CreateNonRandomized 0x1fbedc00
Source units	…/slice_builder/tools/lib/toroidal_wild_first_paths.cc 和 randomized_toroidal_wild_first_paths.cc（字符串锚定）
vtables	base 0x21f57bd8, Randomized 0x21f57c00, Non 0x21f57b88
Return type	StatusOr<vector<vector<proto::Direction>>> — 一组 candidate paths

---

Class Family 和 Object Layout

目的

三个 classes 共享一个算法和一种 object layout；它们只在 wild-first selection policy 上不同。抽象基类 ToroidalWildFirstPaths 持有共享机制（DOR base、fault model、deadlock phase、construction gate）。两个具体 subclasses 只 override Paths 和 wild-path policy。

Function Map

Class	vtable	PathType	Overrides
ToroidalWildFirstPaths（abstract）	0x21f57bd8	—	PathFromDistance, AppendHopsToPath, IsFaultFreeLink, IsFaultFreePath, HalfwayDirections, UpdateSymmetryForHalfway, CreateInternal, ctor
RandomizedToroidalWildFirstPaths	0x21f57c00	1	Paths 0x1fbe9fc0, PathsWithFaults 0x1fbea380, PathsWithoutFaults 0x213dc800, WildHopToPath 0x1fbeb2c0
NonRandomizedToroidalWildFirstPaths	0x21f57b88	0	Paths 0x1fbe6ae0, WildFirstHops 0x1fbe81e0, WildHopToPath 0x1fbe95a0, AddWildHopPathIfValid 0x1fbe8f20, GenerateFirstValidPathOnRing 0x1fbe7ac0

Object Layout

0x1fbedc40 处的 ctor ToroidalWildFirstPaths(…) 将参数存入一个单一 flat object。layout 从 ctor store sequence 恢复：

Field	Offset	Type	Meaning
vptr	+0x00	ptr	vtable
topology	+0x08	ToroidalTopologyInterface*	已发现 topology（distance/walk oracle）
faults	+0x10/+0x18/+0x20	vector<IciLink>	复制的 seed-fault set，每个 0x58 B
ctor coords a..d	+0x28,+0x44,+0x60,+0x7c	Coordinates	endpoint/box parameters
dimension_order	+0x98/+0xa0/+0xa8	vector<int>	DOR index list（per-instance copy）
symmetry	+0xb0	Coordinates	fault symmetry period S
path_type	+0xcc	int	1 = Randomized，0 = Non
wild_mask	+0xd0/+0xd8/+0xe0	vector<bool>	per-dim “wild-eligible” bitmap（由 bt 读取）

topology object 只通过其 vtable 访问。算法使用的 slots（由 call pattern 解析）：

Slot	Method
+0x48	num_dimensions() → 对 3D torus 为 3
+0xa0	Walk(coord, direction) — one-hop walk，返回到达的 Coordinates
+0xb8	GetDistances(src, dst) — per-dim signed shortest distance（torus-wrap-reduced，包含 twist）

NOTE — 0x1fbe9fc0 处的 Paths 调用 topology vtable +0x48（反编译为 (*(...)(*(_QWORD*)v9 + 72LL))(v9)，即 byte offset 72 = 0x48）来获取 dimension count，然后分配 distance seed。该 offset 已在反编译中按字节确认。

---

Paths — Top-Level Dispatch

目的

Paths(src,dst) 是 public entry。它归一化 degenerate self-route，为 general case 构造“每个 dimension 向前一步”的 distance seed，并 dispatch 到 fault-aware 或 no-fault generator。它始终返回 candidate paths 的vector，从不返回 single path；这是 randomized mode 下 GetStaticPath（单数）无效的结构性原因。

算法

function Paths(this, src, dst):              // RandomizedToroidalWildFirstPaths::Paths @ 0x1fbe9fc0
    if Coordinates::operator==(src, dst):    // 0x20c0bac0 — self-route (line 43)
        n    = topology->num_dimensions()    // vtable +0x48 (byte 72, line 56)
        seed = Coordinates(filled with 1, length n)  // all-ones, length n (line 171)
        return [ trivial 1-element path ]    // degenerate result built inline; no generator call
    // general case (src != dst):
    if this.faults == empty:                 // this+0x18 == 0 (a2+3, line 177)
        return PathsWithoutFaults(this, src, dst)   // tail @ 0x213dc800 (line 180)
    return PathsWithFaults(this, src, dst)   // 0x1fbea380 (line 210)
```text

`PathsWithoutFaults`（`0x213dc800`）是 no-fault path：它构建单个 minimal DOR path，成本与未修改 routing-table generator 相同。它携带 `.rodata` warning **“RandomizedToroidalWildFirstPaths may have degraded performance on non-faulty topologies”**（字符串位于该函数中）：在健康 slice 上运行 resilient generator 是浪费，因为它会考虑永远不需要的 wild detours。

> **GOTCHA —** `Paths` 内部构造的 all-ones、length-`n` vector **只**用于 degenerate self-route case（`src == dst`）；它是内联构造并作为 trivial one-element path 返回的，两个 generator 都不会在 self-route branch 上被调用。general case（`src != dst`）绝不会构造 all-ones seed：它会直接按 fault set dispatch（空时 `PathsWithoutFaults`，否则 `PathsWithFaults`），而真实 distance 在这些函数内部通过 `topology->GetDistances` 计算。重新实现者不得把 all-ones vector 喂给 general route generator。

---

## PathsWithFaults — DOR Base + Wild-First Perturbation

### 目的

这是算法核心：先尝试 minimal dimension-order path，只有当它穿过 fault lattice 时，才搜索六个 torus directions，以一个 wild first hop 打开一条干净 route。source unit `randomized_toroidal_wild_first_paths.cc`（在反编译中由源行 73–119 的字符串锚定）。

### 算法

```c
function PathsWithFaults(this, src, dst):    // 0x1fbea380
    dist = topology->GetDistances(src, dst)  // vtable +0xb8, torus-reduced (twist-aware)
    dor  = PathFromDistance(dist)            // 0x1fbeea20 — strict dimension order
    if IsFaultFreePath(src, dor, dst):       // 0x1fbee0c0 — DOR avoids the lattice
        return [dor]                         // common case: minimal path is clean

    paths = []
    for d in 6 torus directions:             // per-dim eligibility via wild_mask bt-test (+0xd0)
        if not wild_eligible[d]: continue
        wild = topology->Walk(src, d)        // vtable +0xa0 — ONE non-minimal hop ("wild first")
        remainder_dist = GetDistances(wild, dst)
        rem  = WildHopToPath(wild, remainder_dist)   // 0x1fbeb2c0 — DOR remainder, fwd+rev split
        full = [direction d] ++ rem
        if IsFaultFreePath(src, full, dst):  // 0x1fbee0c0 — whole {wild + remainder} clean
            half  = HalfwayDirections(dist, full)        // 0x1fbee280 — per-dim +-1 at midpoint
            phase = UpdateSymmetryForHalfway(src, full, dst)  // 0x1fbee7c0 — dateline phase / cache key
            paths.append(full)               // RANDOMIZED: keep ALL fault-free wild paths
            // NON-RANDOMIZED: break here — keep only the FIRST (GenerateFirstValidPathOnRing)
    return paths                             // StatusOr<vector<vector<Direction>>>

反编译交叉校验（函数 0x1fbea380）：line 196 调用 PathFromDistance，line 210 在 DOR path 上调用 IsFaultFreePath，line 364 在 wild-loop 中调用 WildHopToPath，line 382 调用 post-wild IsFaultFreePath，line 396 调用 HalfwayDirections，line 424 调用 UpdateSymmetryForHalfway；顺序与上面完全一致。AddSourceLocationImpl 中的 source-line anchors（73、74、76、101、103、105、107、112、119）确认了该 unit。

QUIRK — “wild-first” 指第一个 hop 是非最短 hop，而且只有这一个 hop。detour 被限制为在一个 axis 上的单个 off-minimal step；其余部分是严格 DOR。这就是保持 deadlock-freedom 的原因：一个受限的 non-DOR turn 经 symmetry phase 验证后不能闭合 channel-dependency cycle，而 multi-hop detour 则可能。

六个方向是什么

3D torus 暴露六个 unit directions：±X、±Y、±Z。wild loop 遍历它们，由 this+0xd0 处 per-dimension wild_mask bitmap gate（用 bt bit-test 读取），并受 this+0x98 处 per-instance dimension index list（count 在 this+0xa0）限制。eligibility mask 用来排除无助的 axis 上的 wild hops（例如 fault 限于一个 dimension）。dimensions 的考虑顺序是确定性的 WildFirstDimensionOrder（introsort 0x1fbefc20），因此 non-randomized variant 中的 “first valid” tie-break 是可复现的。

---

PathFromDistance + AppendHopsToPath — DOR Base

目的

PathFromDistance 将 signed distance vector 转换为严格 dimension-order hop sequence；AppendHopsToPath 为一个 axis 发出 |distance| 个重复 directional hops。二者共同构成整个算法所依托的 deadlock-free base path。

算法

function PathFromDistance(this, dist):       // 0x1fbeea20
    path = []
    for dim in this.dimension_order:         // +0x98 list, length +0xa0
        d = dist.GetCoordinate(dim)          // signed per-axis distance
        AppendHopsToPath(dim, d, &path)      // 0x1fbeb600
    return path                              // axes traversed dim_order[0], then [1], then [2]

function AppendHopsToPath(dim, signed_d, *path):   // 0x1fbeb600
    n           = |signed_d|                 // number of hops
    orientation = Direction::DimensionToOrientation(dim)   // 0x20c02700
    sign        = (signed_d > 0) ? POS : NEG // polarity of the hop
    repeat n times:
        path.push(Direction{orientation, sign})    // emplace_back per hop
```text

反编译交叉校验：`PathFromDistance`（`0x1fbeea20`）循环执行 `GetCoordinate`（line 51）→ `AppendHopsToPath`（line 55）。`AppendHopsToPath`（`0x1fbeb600`）在 `a2 > 0` 上 guard（line 25），调用 `DimensionToOrientation`（line 33），`emplace_back` `Direction`（line 45），并携带 line 62 处的 source path `toroidal_wild_first_paths.cc`。在进入下一个 axis 前遍历完当前 axis，是教科书式 DOR；只要 dateline edge 固定 wrap，它在 torus 上天然 deadlock-free（见 [§ Toroidal Wrap & Deadlock Freedom](#toroidal-wrap--deadlock-freedom)）。

### WildHopToPath — Wild Hop 之后的 Remainder

`WildHopToPath`（Randomized override `0x1fbeb2c0`）以**两个 segment** 构建 post-wild-hop remainder：一次 forward dimension-order pass，然后对 residual distance 做一次 reverse dimension-order pass。这个 split 确保 wild detour 及其 remainder 不共享返回边，从而保持 dependency graph 无环。它将 remainder 的 `ManhattanNorm` 记录为 path cost（`0x20c0ba00`，存储在 `PathCost` element 上），使 cache/AR 层可以排序等长度 candidates。

反编译交叉校验（`0x1fbeb2c0`）：line 46 调用 `ManhattanNorm(a3)`，line 71 是 forward `AppendHopsToPath`，line 130 是 reverse-pass `AppendHopsToPath`（两个不同的 `while` loops 遍历 `GetCoordinate`）。

---

## Periodic Fault Model — IsFaultFreeLink

### 目的

fault **不是**单条 dead link。算法推理的 fault set 是一个*lattice*：位于 coordinate `c`、direction `d` 的一个物理 seed fault 被复制到每条位于 `c + k·S`（componentwise，所有整数 `k`）的 link，其中 `S` 是 per-axis fault-symmetry period。`IsFaultFreeLink` 用 modular comparison 强制这一 lattice。该周期性使 route table 能够在整个 pod 内复用：slice 平铺成 `S`-periodic cells，每个 cell 看到同一 fault pattern，所以一个 route scheme 覆盖同一 residue class 中的所有 `(src,dst)` pairs。

### 算法

```c
function IsFaultFreeLink(this, link, period):        // 0x1fbede40
    // `period` is the single per-instance symmetry Coordinates passed by the
    // caller (object field +0x28), NOT a per-fault field — same modulus for every fault.
    for f in this.faults:                            // this+0x10 array, +0x18 count, 0x58 B each
        matches = true
        for i in 0 .. num_dimensions-1:              // topology vtable +0x48
            a = link.GetCoordinate(i)                // link tail coord            (line 59 -> v12)
            b = f.coord.GetCoordinate(i)             // this fault's coord         (line 64 -> v15)
            m = period.GetCoordinate(i)              // per-dim period S[i]        (line 70 -> v29)
            if (a % m) != (b % m):                   // MODULAR REDUCTION
                matches = false
        matches &= Direction::IsSame(link.dir, f.dir)   // 0x20c025e0
        if matches:
            return NOT-fault-free                    // link coincides with the lattice
    return fault-free

function IsFaultFreePath(this, src, dirs, period):   // 0x1fbee0c0
    pos = src
    for d in dirs:
        if not IsFaultFreeLink(IciLink{pos, d}, period): return false  // line 40; period = this+0x28
        pos = topology->Walk(pos, d)                 // vtable +0xa0 (byte 160)
    return true                                      // every hop avoids the lattice

反编译交叉校验（0x1fbede40，lattice test）：三次 GetCoordinate 读取（lines 59/64/70 —— a、b、m），然后是 modular comparison

LODWORD(v9) = v15 % v29;            // line 75 — fault_coord % m  (v15=fault, v29=m)
v33 &= v12 % v29 == v15 % v29;      // line 76 — AND across dims: (link % m) == (fault % m)
v17 = 4 * (v12 % v29 != v15 % v29); // line 77 — per-dim mismatch advances the loop
...
Direction::IsSame(...)              // line 143 — directions must match too
```text

`%` operator 在每个 dimension 中把坐标按 symmetry period 取模；candidate link 当且仅当其 reduced coordinate 在**所有** dimensions 中等于某个 fault 的 reduced coordinate，**且** direction 匹配时才是 faulty。这就是代码中的 periodic fault lattice，已按字节确认。

> **GOTCHA —** modulus **不是**按每个 fault 读取的。它是作为第二个 `Coordinates&` argument 传入的单个 per-instance symmetry（由 `PathsWithFaults`/`IsFaultFreePath` 从 object field `+0x28` 提供）；`v29` 每个 dimension 从这个 period vector 加载一次，同一个 `m` 应用于 loop 中的每个 fault。重新实现者应将 symmetry period **一次性存储在 route generator 上**，而不是存到每个 `IciLink` 上。（所有已发布 cache 中 period 都统一为 `4_4_4`。）

---

## Toroidal Wrap & Deadlock Freedom

### 目的

两个互补保证使每条生成路径在 wrap-around torus 上 deadlock-free。

**(A) Strict dimension order — 结构性保证。** 每条路径，包括 minimal `PathFromDistance` 和 `WildHopToPath` remainder，都按固定 total order 遍历 axes。torus 上的 DOR 只要为每条 wrap（dateline）edge 分配方式使 channel-dependency graph 保持无环，就是 deadlock-free。单个 wild hop 是唯一 non-DOR edge，被限制为 one hop，并经 symmetry phase 验证，所以它不能创建 cycle。

**(B) Halfway / dateline symmetry — wrap-around 保证。** `HalfwayDirections` 走完整条 path，并在每个 dimension traversal 的**中点**记录 per-dimension `±1` symmetry value，即该 axis traversal 使用了 torus wrap 的哪一侧。`UpdateSymmetryForHalfway` 随后对 axis coordinate 做 GCD reduction，得到归一化的分数 “phase”（对 2 做 binary-GCD），产生 `(src,dst)` pair 在 symmetry cell 内的 canonical per-axis position。

### 算法

```c
function UpdateSymmetryForHalfway(this, src, path, dst):   // 0x1fbee7c0
    half  = HalfwayDirections(dist, path)        // 0x1fbee280 — per-dim +-1 at the midpoint
    phase = Coordinates()
    for i in dims:
        if half[i] > 0:                          // positive half-turn on axis i
            c        = dst.GetCoordinate(i)
            phase[i] = 2 * (c / gcd(c, 2))        // binary-GCD reduce, doubled
    return phase

phase 有双重作用：

• Deadlock constraint：所有共享一个 phase 的 paths 以相同方式打断 wrap cycle（consistent dateline side）。
• Cache key：对称的 (src,dst) pairs 折叠到同一个 RouteScheme，这是 4_4_4 fault-symmetry tiling 的基础，也是只有约 85 个 cache files 就能覆盖整个 shape/fault cross-product 的原因。

dateline-edge predicate 本身是 ResilientToroidalTopology::CheckOnEdge(coord, orientation)（0x1fbe36e0）：它告诉 topology 哪些 coordinates 位于 wrap boundary。实际的 one-hop wrap math（越过某个 axis 的最后一个 coordinate 后回到 0）位于 topology 的 Walk（0x1fbe3640 / vtable +0xa0）和 GetDistances（0x1fbe36c0 / vtable +0xb8）中，generator 将它们视作 black-box oracles。_twisted shapes 的 twist adjustments 被烘进 GetDistances；见 GetDistances 和 Twist Overview。

NOTE — phase 只为 halfway symmetry 为正的 axes 计算（反编译 0x1fbea380 line 414 遍历 while (*(int*)&v48[v53] >= 0)）。GCD-reduce + doubling 是 canonicalization，使两个物理上不同但 symmetry-equivalent 的 pairs hash 到同一个 scheme。（对 GCD-against-2 形状置信度 HIGH；doubled fraction 的精确 rounding 是从 tzcnt/shr binary-GCD idiom 推断的。）

---

Randomized vs Non-Randomized

目的

两个 subclasses 实现同一个 DOR + wild-first search，但在保留多少条有效 wild paths 上不同。这个单一差异就是 “randomized” 的含义：multi-path policy，而不是 stochastic state。

Policy Comparison

Aspect	Randomized (PathType=1)	Non-Randomized (PathType=0)
Wild-path policy	保留所有 fault-free wild paths	保留第一条 fault-free wild path
Emitted RouteScheme	RandomHop（等成本 directions 的 set）	StaticPath（一条 direction sequence）
Path enumerator	PathsWithFaults 中的 inline loop	GenerateFirstValidPathOnRing 0x1fbe7ac0, AddWildHopPathIfValid 0x1fbe8f20
Valid accessor	GetStaticPaths（复数）0x1fbe1e20	GetStaticPath（单数）0x1fbe1ce0
Factory	CreateRandomized 0x1fbedc20	CreateNonRandomized 0x1fbedc00

GetStaticPath（单数，0x1fbe1ce0）会以字符串 “GetStaticPath … is not defined when randomized_paths is enabled, use GetStaticPaths (plural)” hard-error；已按字节确认该字符串位于 0x1fbe1ce0。randomized policy 下没有单条 canonical path，只有 candidate set。

QUIRK — “randomization” 存在于两个确定性位置，二者都不是运行时 random number：（1）存于 RandomHop scheme 的 per-(src,dst) candidate set；（2）install-time / all-reduce spreading，通过 deterministic hash 为每次 transfer 选择一个 candidate。generator 完全可复现；同一个 fault pattern 总会以同一个 WildFirstDimensionOrder 生成同一个 candidate set。重新实现者必须复现ordering（dimensions 的 introsort，0x1fbefc20）才能 bit-for-bit 匹配 baked caches。（精确的 runtime spreading hash，即它是否复用 MapSrcDstCoreToRoutingTableIndex，是结构性判断而非按字节确认：LOW。）

---

Construction Gate — CreateInternal

目的

CreateInternal 是 constructor gate，在生成任何 path 之前决定 slice 是否可能存在 resilient route。它按 symmetry model 验证 fault set，并强制 tiling condition。

算法

function CreateInternal(top, faults, symmetry, path_type):   // 0x1fbeb720
    require faults non-empty                  // else MakeErrorImpl<3> "ICI resiliency only supports
                                              //   non-empty faulty link sets with super-pod fault symmetry"
    require top.num_dimensions() == symmetry.dims     // else "Faulty symmetry and topology must have a
                                                      //   matching number of dimensions"
    for f in faults:
        for dim:
            require f.coord[dim] consistent mod symmetry[dim]   // seed faults lie on the lattice
            require fault_dim < num_dimensions  // "Fault dimension outside specified number of dimensions"
    for dim:
        require top.size[dim] % symmetry[dim] == 0   // THE GATE
            else MakeErrorImpl<3> "The topology size must be a multiple of the fault symmetry"
    return WildFirstPaths(top, faults, ..., symmetry, path_type, wild_mask)
```text

反编译交叉校验（`0x1fbeb720`）：

| Check | Decompile evidence | String |
|---|---|---|
| dimension agreement | line 260 | `"Faulty symmetry and topology must have a matching number of dimensions"` |
| fault dim in range | line 1452 | `"Fault dimension outside specified number of dimensions"` |
| per-fault lattice consistency | lines 983/1031/1072（`v % m`） |（无字符串 — silent reject path） |
| **the gate** | line 1532 `if (v17 % v250[0])` → line 1534 | `"The topology size must be a multiple of the fault symmetry"` |

> **NOTE —** dimension-agreement check（topology dimension count 必须匹配 symmetry vector 的维数）会发出逐字诊断 **“Faulty symmetry and topology must have a matching number of dimensions”**（`0x1fbeb720` line 260）。

### 当不存在 Resilient Route 时（Chip Isolation）

当以下情况发生时，gate 会失败，bring-up 也会失败：（1）fault set 不在干净 lattice 上（破坏 super-pod symmetry），（2）slice size 在某个 dimension 上不是 `S` 的倍数，或（3）即使 lattice 有效，generator 也为某个 `(src,dst)` 找不到 fault-free path，表现为 **“No route solution for topology %s.”**。不存在“隔离一个芯片并继续”；slice 会被移除。seed fault 在 generation 前由 `AddFaultsFromSeed`（`0x20bfab00`）平铺到完整 lattice，`MaximumPathSymmetry`（`0x1fbed440`）计算 gate 使用的 period `S`。

---

## 相关组件

| Name | Relationship |
|---|---|
| `ResilientToroidalTopology::InitRouteSolution` `0x1fbdf8a0` | Orchestrator：先尝试 cache，否则 `PopulateUnoptimizedRouteCache` `0x1fbe0a20` → this generator |
| `PopulateUnoptimizedRouteCache` `0x1fbe0a20` | Live fallback：`CreateRandomized`/`CreateNonRandomized` + 对所有 pairs 调用 `Paths(s,d)` |
| `RouteCacheDeduplicator::Find` `0x20b59000` | 选择预烘焙 cache；miss 时运行 live generator |
| `ToroidalRouteCache::RouteScheme`（`StaticPath`/`RandomHop`） | 一个已生成 `(src,dst)` route class 的 wire form |
| `WildFirstDimensionOrder` `0x1fbefc20`（introsort） | 确定性的 dimension ordering，即 wild search 的 “seed” |

---

## 交叉引用

- [Routing Overview](overview.md) — 该 generator 馈入的 route-generation → route-cache → emission pipeline
- [GetStaticPath & Multipod](get-static-path.md) — deterministic single static path accessor（单数），在 randomized mode 下无效
- [CreateRoutingSchedule Solver](create-routing-schedule.md) — 从生成的 path set 构建的 per-hop schedule
- [Route-Table Generation](route-table-generation.md) — 消费 schemes 的 physmap 和 route-table emission
- [GetDistances](get-distances.md) — wild-first loop 调用的 nK twisted-torus distance metric（`vtable +0xb8`）
- [Twist Overview](../twist/overview.md) — 为 `_twisted` shapes 烘进 `GetDistances` 的 twisted-torus wrap handling
- [ICI Topology Discovery](../ici/topology-discovery.md) — topology 和 seed fault set 的来源