# ADR-0006: 토폴로지 컴파일, 거리 추출, 그리고 자동 다이어그램 생성

## Status

Accepted

## Context

시뮬레이터는 토폴로지 설정(예: topology.yaml)을 명시적인 모델 그래프로 컴파일하고,
라우팅 및 누적 레이턴시(거리)를 계산한다.
정합성을 보장하고 수작업으로 유지되는 토폴로지 도면을 피하기 위해,
다이어그램은 이 권위 있는 산출물로부터 생성되어야 한다.

또한 사용성을 위해, 다이어그램은 안정적인 위치로 자동 방출되어
개발자가 저장소 내에서 즉시 미리볼 수 있어야 한다.

---

## Decision

### D1. 토폴로지 컴파일은 유일한 진실 공급원이다

- topology.yaml(또는 동등한 설정)은 다음으로 컴파일된다:
  - 명시적인 시스템 그래프,
  - 노드/링크 속성,
  - 라우팅 정책.
이 컴파일된 그래프가 시스템의 권위 있는 표현이다.

### D2. 컴파일 중 거리 추출

- 토폴로지 컴파일 중 또는 그 직후, 시뮬레이터는 ADR-0002와 정합되는
  거리 메타데이터(누적 레이턴시)를 계산해야 한다.
- 거리 메타데이터는 ADR-0005에서 정의한 거리 기반 다이어그램 레이아웃을 지원하기에 충분해야 한다.
- 분산된 패브릭 세그먼트(예: NoC)는 ADR-0002 D4에 따라 distance_mm = 0을 가질 수 있다.
  이러한 노드의 레이아웃 배치는 거리 버킷이 아닌 명시적 위치 메타데이터를 사용한다.

### D3. 다이어그램 생성은 파생 산출물이다

- 다이어그램은 다음으로부터 생성되어야 한다:
  - 컴파일된 토폴로지 그래프,
  - 추출된 거리 메타데이터,
  - ADR-0005에 정의된 뷰/레이아웃 규칙.
- 다이어그램 생성은 추가적인 수작업 토폴로지 기술을 요구해서는 안 된다.

### D4. 저장소로의 자동 다이어그램 방출

- 토폴로지 컴파일의 일부로서, 구현은 기본적으로 다음 다이어그램을 생성해야 한다:
  - SIP 수준 다이어그램 (대표, 거리 인식)
  - CUBE 수준 다이어그램 (대표, 거리 인식)
  - PE 수준 다이어그램 (대표, 거리 인식)
- 기본 출력 디렉터리는 다음과 같다:
  - `docs/diagrams/`
- 생성기는 컴파일된 토폴로지(또는 다이어그램 규칙)가 변경되었을 때에만 덮어쓰기/업데이트해야 한다.

### D5. 뷰별 투영 및 레이아웃

각 뷰(SIP / CUBE / PE)에 대해:

- 생성기는 컴파일된 그래프를 축소된 뷰 그래프로 투영해야 한다:
  - ADR-0005에 따라 노드를 숨기거나 축약하고,
  - 해당 뷰와 관련된 연결성 의미를 보존하고,
  - 거리 버킷을 계산하여 레이아웃 레이어를 결정론적으로 할당한다.
- CUBE 수준 투영은 다음을 포함해야 한다:
  - 라우터 메시 (cube_mesh.yaml로부터), HBM_CTRL, 공유 SRAM, M_CPU, UCIe 포트,
    그리고 불투명 블록으로 표현된 PE.
  - 모든 경로(HBM, 비-HBM, 명령)는 동일한 라우터 메시를 통해 라우팅된다 (ADR-0017).
- 기본 앵커는 암묵적이며 (ADR-0005) 인스턴스 인덱스를 요구해서는 안 된다.

### D6. 출력 포맷과 결정론

- 생성기는 다음 중 최소 하나를 출력해야 한다:
  - Mermaid (Markdown 네이티브)
  - Graphviz DOT (rank 기반 제어)
  - SVG (mm 단위 정확도 레이아웃, 외부 의존성 없음)
- 컴파일된 토폴로지로부터 mm 단위 정확도의 위치 메타데이터가 가용한 경우 SVG가 선호된다.
- 출력은 결정론적이어야 한다:
  - 동일한 토폴로지 + 동일한 규칙 → 동일한 다이어그램 텍스트
- 파일 이름은 결정론적이고 안정적이어야 한다 (아래의 "출력 컨벤션" 참조).

### D7. 성능 및 캐싱

- 다이어그램 생성은 지연(lazy) 및/또는 캐시될 수 있으며, `docs/diagrams/`의 출력이
  컴파일된 토폴로지와 정합을 유지하는 한 그렇다.
- 구현은 다음을 기반으로 한 캐시 키를 사용해야 한다(SHOULD):
  - 토폴로지 콘텐츠 해시,
  - 라우팅 정책 버전,
  - 다이어그램 규칙 버전,
  - 뷰 유형 (SIP/CUBE/PE).

---

## 출력 컨벤션

### 디렉터리

- `docs/diagrams/`는 생성된 다이어그램의 표준 출력 디렉터리이다.

### 파일 이름 (권장, 결정론적)

- `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`

선택적으로, 멀티 토폴로지 워크플로우용:

- `sip_view__{topology_id}.svg`
- `cube_view__{topology_id}.svg`
- `pe_view__{topology_id}.svg`

### 저장소 정책

- 생성된 다이어그램 파일은 diff 기반 리뷰가 가능하도록 저장소에 커밋될 수 있다.
- 커밋된 경우, 이는 토폴로지 컴파일로부터 재현 가능해야 한다.

---

## Consequences

- 다이어그램은 항상 시뮬레이터 동작과 정합한다.
- 아키텍처 변경이 시각화에 자동으로 전파된다.
- 다이어그램 diff는 아키텍처 변경의 의미 있는 지표가 된다.

---

## Links

- SPEC Section 4 (Output, Debuggability, and Diagrams)
- ADR-0002 (거리 의미)
- ADR-0005 (다이어그램 뷰 및 레이아웃 규칙)