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>
4.5 KiB
4.5 KiB
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.dotsip_view.svg/sip_view.mmd/sip_view.dotcube_view.svg/cube_view.mmd/cube_view.dotpe_view.svg/pe_view.mmd/pe_view.dot
Optionally, for multi-topology workflows:
sip_view__{topology_id}.svgcube_view__{topology_id}.svgpe_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)