kernbench2/docs/adr/ADR-0006-dev-topology-compilation-distance-diagram.md

ADR-0006: Topology Compilation, Distance Extraction, and Automatic Diagram Generation

Status

Accepted

Context

The simulator compiles topology configuration (e.g., topology.yaml) into an explicit model graph, and computes routing and accumulated latency (distance). Diagrams should be generated from these authoritative artifacts to ensure consistency and avoid hand-maintained topology drawings.

Additionally, for usability, diagrams should be emitted automatically into a stable location so that developers can preview them immediately in the repository.

---

Decision

D1. Topology compilation is the single source of truth

• topology.yaml (or equivalent config) is compiled into:
  • an explicit system graph,
  • node/link attributes,
  • routing policies. This compiled graph is the authoritative representation of the system.

D2. Distance extraction during compilation

• During or immediately after topology compilation, the simulator MUST compute distance metadata (accumulated latency) consistent with ADR-0002.
• Distance metadata MUST be sufficient to support distance-aware diagram layout as defined in ADR-0005.
• Distributed fabric segments (e.g., NOC) MAY have distance_mm = 0 per ADR-0002 D4; layout placement for such nodes uses explicit position metadata rather than distance buckets.

D3. Diagram generation is a derived artifact

• Diagrams MUST be generated from:
  • the compiled topology graph,
  • extracted distance metadata,
  • view/layout rules defined in ADR-0005.
• Diagram generation MUST NOT require additional hand-written topology descriptions.

D4. Automatic diagram emission to the repository

• As part of topology compilation, the implementation MUST produce the following diagrams by default:
  • SIP-level diagram (representative, distance-aware)
  • CUBE-level diagram (representative, distance-aware)
  • PE-level diagram (representative, distance-aware)
• The default output directory is:
  • docs/diagrams/
• The generator MUST overwrite/update only when the compiled topology (or diagram rules) changes.

D5. View-specific projection and layout

For each view (SIP / CUBE / PE):

• The generator MUST project the compiled graph into a reduced view graph:
  • hide/collapse nodes according to ADR-0005,
  • preserve connectivity semantics relevant to that view,
  • compute distance buckets and assign layout layers deterministically.
• CUBE-level projection MUST include:
  • Router mesh (from cube_mesh.yaml), HBM_CTRL, shared SRAM, M_CPU, UCIe ports, and PEs as opaque blocks.
  • All paths (HBM, non-HBM, command) route through the same router mesh (ADR-0017).
• Default anchors are implicit (ADR-0005) and MUST NOT require instance indices.

D6. Output formats and determinism

• The generator MUST output at least one of:
  • Mermaid (Markdown-native)
  • Graphviz DOT (rank-based control)
  • SVG (mm-accurate layout, no external dependencies)
• SVG is preferred when mm-accurate position metadata is available from the compiled topology.
• Output MUST be deterministic:
  • same topology + same rules → identical diagram text
• File naming MUST be deterministic and stable (see "Output Conventions").

D7. Performance and caching

• Diagram generation MAY be lazy and/or cached, as long as the outputs in docs/diagrams/ remain consistent with the compiled topology.
• The implementation SHOULD use a cache key based on:
  • topology content hash,
  • routing policy version,
  • diagram rules version,
  • view type (SIP/CUBE/PE).

---

Output Conventions

Directory

• docs/diagrams/ is the canonical output directory for generated diagrams.

File names (recommended, deterministic)

• system_view.svg / system_view.mmd / system_view.dot
• sip_view.svg / sip_view.mmd / sip_view.dot
• cube_view.svg / cube_view.mmd / cube_view.dot
• pe_view.svg / pe_view.mmd / pe_view.dot

Optionally, for multi-topology workflows:

• sip_view__{topology_id}.svg
• cube_view__{topology_id}.svg
• pe_view__{topology_id}.svg

Repository policy

• Generated diagram files MAY be committed to the repository to enable diff-based review.
• If committed, they MUST be reproducible from topology compilation.

---

Consequences

• Diagrams are always consistent with simulator behavior.
• Architectural changes automatically propagate to visualizations.
• Diagram diffs become meaningful indicators of architectural change.

---

Links

• SPEC Section 4 (Output, Debuggability, and Diagrams)
• ADR-0002 (Distance semantics)
• ADR-0005 (Diagram views and layout rules)