ADR: translate adr-ko/ to Korean, fix ADR-0013 slug, refine Status check
Follow-up to the bilingual-structure commit: docs/adr-ko/ now holds only Korean versions (24 files translated from English placeholders), ADR-0013 slug uses kebab-case in both folders, and the verify tool allows translated parenthetical commentary in the Status block. - Translate 24 English files in docs/adr-ko/ to Korean. The previous bilingual-structure commit had left these as English copies because their source content was already English; this commit fulfills the policy that docs/adr-ko/ contains only Korean. - Rename ADR-0013 in both adr/ and adr-ko/ from ver-verification_strategy.md to ver-verification-strategy.md (kebab-case consistency with other ADRs). - CLAUDE.md (ADR Translation Discipline): clarify that only the Status lifecycle keyword (Accepted / Proposed / Stub / Draft / Superseded by ADR-NNNN / Merged into ADR-NNNN) must match across EN and KO; parenthetical commentary and trailing list items may be translated. - tools/verify_adr_lang_pairs.py: replace byte-equal Status check with normalize_status_keyword() which strips parenthetical commentary and takes only the first non-empty line. - tests/test_verify_adr_lang_pairs.py: update existing test names, add coverage for translated parenthetical, translated trailing list, and Superseded-by-NNNN keyword equality. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
# ADR-0006: Topology Compilation, Distance Extraction, and Automatic Diagram Generation
|
||||
# ADR-0006: 토폴로지 컴파일, 거리 추출, 그리고 자동 다이어그램 생성
|
||||
|
||||
## Status
|
||||
|
||||
@@ -6,125 +6,125 @@ 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.
|
||||
시뮬레이터는 토폴로지 설정(예: topology.yaml)을 명시적인 모델 그래프로 컴파일하고,
|
||||
라우팅 및 누적 레이턴시(거리)를 계산한다.
|
||||
정합성을 보장하고 수작업으로 유지되는 토폴로지 도면을 피하기 위해,
|
||||
다이어그램은 이 권위 있는 산출물로부터 생성되어야 한다.
|
||||
|
||||
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
|
||||
### D1. 토폴로지 컴파일은 유일한 진실 공급원이다
|
||||
|
||||
- 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.
|
||||
- topology.yaml(또는 동등한 설정)은 다음으로 컴파일된다:
|
||||
- 명시적인 시스템 그래프,
|
||||
- 노드/링크 속성,
|
||||
- 라우팅 정책.
|
||||
이 컴파일된 그래프가 시스템의 권위 있는 표현이다.
|
||||
|
||||
### D2. Distance extraction during compilation
|
||||
### D2. 컴파일 중 거리 추출
|
||||
|
||||
- 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.
|
||||
- 토폴로지 컴파일 중 또는 그 직후, 시뮬레이터는 ADR-0002와 정합되는
|
||||
거리 메타데이터(누적 레이턴시)를 계산해야 한다.
|
||||
- 거리 메타데이터는 ADR-0005에서 정의한 거리 기반 다이어그램 레이아웃을 지원하기에 충분해야 한다.
|
||||
- 분산된 패브릭 세그먼트(예: NoC)는 ADR-0002 D4에 따라 distance_mm = 0을 가질 수 있다.
|
||||
이러한 노드의 레이아웃 배치는 거리 버킷이 아닌 명시적 위치 메타데이터를 사용한다.
|
||||
|
||||
### D3. Diagram generation is a derived artifact
|
||||
### D3. 다이어그램 생성은 파생 산출물이다
|
||||
|
||||
- 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.
|
||||
- 다이어그램은 다음으로부터 생성되어야 한다:
|
||||
- 컴파일된 토폴로지 그래프,
|
||||
- 추출된 거리 메타데이터,
|
||||
- ADR-0005에 정의된 뷰/레이아웃 규칙.
|
||||
- 다이어그램 생성은 추가적인 수작업 토폴로지 기술을 요구해서는 안 된다.
|
||||
|
||||
### D4. Automatic diagram emission to the repository
|
||||
### D4. 저장소로의 자동 다이어그램 방출
|
||||
|
||||
- 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:
|
||||
- 토폴로지 컴파일의 일부로서, 구현은 기본적으로 다음 다이어그램을 생성해야 한다:
|
||||
- SIP 수준 다이어그램 (대표, 거리 인식)
|
||||
- CUBE 수준 다이어그램 (대표, 거리 인식)
|
||||
- PE 수준 다이어그램 (대표, 거리 인식)
|
||||
- 기본 출력 디렉터리는 다음과 같다:
|
||||
- `docs/diagrams/`
|
||||
- The generator MUST overwrite/update only when the compiled topology (or diagram rules) changes.
|
||||
- 생성기는 컴파일된 토폴로지(또는 다이어그램 규칙)가 변경되었을 때에만 덮어쓰기/업데이트해야 한다.
|
||||
|
||||
### D5. View-specific projection and layout
|
||||
### D5. 뷰별 투영 및 레이아웃
|
||||
|
||||
For each view (SIP / CUBE / PE):
|
||||
각 뷰(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.
|
||||
- 생성기는 컴파일된 그래프를 축소된 뷰 그래프로 투영해야 한다:
|
||||
- ADR-0005에 따라 노드를 숨기거나 축약하고,
|
||||
- 해당 뷰와 관련된 연결성 의미를 보존하고,
|
||||
- 거리 버킷을 계산하여 레이아웃 레이어를 결정론적으로 할당한다.
|
||||
- CUBE 수준 투영은 다음을 포함해야 한다:
|
||||
- 라우터 메시 (cube_mesh.yaml로부터), HBM_CTRL, 공유 SRAM, M_CPU, UCIe 포트,
|
||||
그리고 불투명 블록으로 표현된 PE.
|
||||
- 모든 경로(HBM, 비-HBM, 명령)는 동일한 라우터 메시를 통해 라우팅된다 (ADR-0017).
|
||||
- 기본 앵커는 암묵적이며 (ADR-0005) 인스턴스 인덱스를 요구해서는 안 된다.
|
||||
|
||||
### D6. Output formats and determinism
|
||||
### D6. 출력 포맷과 결정론
|
||||
|
||||
- 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").
|
||||
- 생성기는 다음 중 최소 하나를 출력해야 한다:
|
||||
- Mermaid (Markdown 네이티브)
|
||||
- Graphviz DOT (rank 기반 제어)
|
||||
- SVG (mm 단위 정확도 레이아웃, 외부 의존성 없음)
|
||||
- 컴파일된 토폴로지로부터 mm 단위 정확도의 위치 메타데이터가 가용한 경우 SVG가 선호된다.
|
||||
- 출력은 결정론적이어야 한다:
|
||||
- 동일한 토폴로지 + 동일한 규칙 → 동일한 다이어그램 텍스트
|
||||
- 파일 이름은 결정론적이고 안정적이어야 한다 (아래의 "출력 컨벤션" 참조).
|
||||
|
||||
### D7. Performance and caching
|
||||
### D7. 성능 및 캐싱
|
||||
|
||||
- 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).
|
||||
- 다이어그램 생성은 지연(lazy) 및/또는 캐시될 수 있으며, `docs/diagrams/`의 출력이
|
||||
컴파일된 토폴로지와 정합을 유지하는 한 그렇다.
|
||||
- 구현은 다음을 기반으로 한 캐시 키를 사용해야 한다(SHOULD):
|
||||
- 토폴로지 콘텐츠 해시,
|
||||
- 라우팅 정책 버전,
|
||||
- 다이어그램 규칙 버전,
|
||||
- 뷰 유형 (SIP/CUBE/PE).
|
||||
|
||||
---
|
||||
|
||||
## Output Conventions
|
||||
## 출력 컨벤션
|
||||
|
||||
### Directory
|
||||
### 디렉터리
|
||||
|
||||
- `docs/diagrams/` is the canonical output directory for generated diagrams.
|
||||
- `docs/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.
|
||||
- 생성된 다이어그램 파일은 diff 기반 리뷰가 가능하도록 저장소에 커밋될 수 있다.
|
||||
- 커밋된 경우, 이는 토폴로지 컴파일로부터 재현 가능해야 한다.
|
||||
|
||||
---
|
||||
|
||||
## Consequences
|
||||
|
||||
- Diagrams are always consistent with simulator behavior.
|
||||
- Architectural changes automatically propagate to visualizations.
|
||||
- Diagram diffs become meaningful indicators of architectural change.
|
||||
- 다이어그램은 항상 시뮬레이터 동작과 정합한다.
|
||||
- 아키텍처 변경이 시각화에 자동으로 전파된다.
|
||||
- 다이어그램 diff는 아키텍처 변경의 의미 있는 지표가 된다.
|
||||
|
||||
---
|
||||
|
||||
## Links
|
||||
|
||||
- SPEC Section 4 (Output, Debuggability, and Diagrams)
|
||||
- ADR-0002 (Distance semantics)
|
||||
- ADR-0005 (Diagram views and layout rules)
|
||||
- ADR-0002 (거리 의미)
|
||||
- ADR-0005 (다이어그램 뷰 및 레이아웃 규칙)
|
||||
|
||||
Reference in New Issue
Block a user