ywkang
a796c1d2f7
Establish English as the canonical ADR language with Korean translations held in a parallel docs/adr-ko/ tree as derived artifacts (1:1 mirror). Promotion from adr-proposed/ to adr/ now writes English to adr/ and the Korean to adr-ko/; bidirectional sync rule documented in CLAUDE.md. - Migrate 30 ADRs in docs/adr/: 28 Korean-only translated to English, 2 bilingual pairs (ADR-0020, ADR-0023) consolidated (.en.md suffix dropped). ADR-0023 EN regenerated against KO source which had newer HW Realization Notes (D16-D23) section. - docs/adr-history/ left frozen by design (transitional state). - CLAUDE.md (Part 2): update ADR Lifecycle for 4-folder layout, mark docs/adr-ko/ as a Derived Artifact, add ADR Translation Discipline section covering bidirectional sync, conflict resolution (EN wins), and proposed-language freedom. - tools/verify_adr_lang_pairs.py: new verification tool checking pair completeness, filename mirroring, ADR-ID match, Status byte-equality. Pre-commit hook intentionally not added; run on demand or in CI. - tests/test_verify_adr_lang_pairs.py: 11 cases including CRLF/LF normalization, em-dash title separator, underscore-slug edge case. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
# 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)
|