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:
2026-05-20 08:17:56 -07:00
parent a796c1d2f7
commit 168b0c89f0
29 changed files with 2631 additions and 2651 deletions
@@ -1,4 +1,4 @@
# ADR-0010: Command Line Interface and Execution Semantics
# ADR-0010: 명령줄 인터페이스 및 실행 시맨틱
## Status
@@ -6,126 +6,120 @@ Accepted
## Context
The `kernbench` CLI is the user-facing entry point of the simulator. It
exposes three subcommands:
`kernbench` CLI는 시뮬레이터의 사용자 대면 진입점이다. 세 개의 서브명령을
노출한다:
- `run`execute a benchmark against a topology.
- `probe`diagnostic utility for latency / BW measurement.
- `web`interactive topology viewer.
- `run`토폴로지에 대해 벤치마크를 실행한다.
- `probe`레이턴시 / 대역폭 측정을 위한 진단 유틸리티.
- `web`인터랙티브 토폴로지 뷰어.
Device enumeration is centralized in the CLI; neither the runtime API
nor the simulation engine enumerates devices. Benchmarks remain
single-device by design and accept a device identifier as input.
디바이스 열거는 CLI에 중앙 집중화되어 있다. runtime API와 시뮬레이션 엔진
모두 디바이스를 열거하지 않는다. 벤치마크는 설계상 단일 디바이스를
유지하며 입력으로 디바이스 식별자를 받는다.
## Decision
### D1. Benchmark contract — single-device by design
### D1. 벤치마크 계약 — 설계상 단일 디바이스
- A benchmark MUST define behavior for a single device only.
- A benchmark MUST accept a device identifier as input.
- Benchmarks MUST NOT enumerate or loop over multiple devices.
- 벤치마크는 반드시 단일 디바이스에 대한 동작만 정의해야 한다.
- 벤치마크는 반드시 디바이스 식별자를 입력으로 받아야 한다.
- 벤치마크는 다중 디바이스를 열거하거나 루프해서는 안 된다.
Multi-device execution is the CLI's concern (D3), not the benchmark's.
다중 디바이스 실행은 벤치마크의 관심사가 아니라 CLI의 관심사이다(D3).
### D2. `kernbench run` — benchmark execution
### D2. `kernbench run` — 벤치마크 실행
Required arguments:
필수 인자:
- `--topology <path>`: topology YAML file path. Loaded via
`resolve_topology()`.
- `--bench <name>`: benchmark name. Resolved via
`benches.loader.resolve_bench()`.
- `--topology <path>`: 토폴로지 YAML 파일 경로. `resolve_topology()`
통해 로드된다.
- `--bench <name>`: 벤치마크 이름. `benches.loader.resolve_bench()`
통해 해석된다.
Optional arguments:
선택 인자:
- `--device <selector>` (default: `all`):
- `all`run once per discovered SIP (see D3).
- `sip:<N>`run only on SIP N.
- Parsed via `resolve_device()`.
- `--verify-data` (default: off) — enable Phase 2 data verification
(see ADR-0020). When set, `engine_factory` constructs the engine
with `enable_data=True`. After the benchmark runs, a diagnostic
summary of recorded ops is printed.
- `--device <selector>` (기본값: `all`):
- `all`발견된 SIP마다 한 번씩 실행한다(D3 참고).
- `sip:<N>`SIP N에서만 실행한다.
- `resolve_device()`를 통해 파싱된다.
- `--verify-data` (기본값: off) — Phase 2 데이터 검증을 활성화한다
(ADR-0020 참고). 설정되면 `engine_factory`가 엔진을
`enable_data=True`로 구성한다. 벤치마크 실행 후, 기록된 op들의 진단
요약이 출력된다.
Each invocation runs the benchmark once within a single simulation
instance.
각 호출은 단일 시뮬레이션 인스턴스 내에서 벤치마크를 한 번 실행한다.
### D3. Multi-device execution is logically parallel
### D3. 다중 디바이스 실행은 논리적으로 병렬이다
When `--device all` (or omitted) and the topology has multiple SIPs:
`--device all`(또는 생략) 상태이며 토폴로지에 SIP가 여러 개일 때:
- Benchmark executions are submitted to a single simulation engine
instance.
- Executions are logically parallel in simulation time.
- Inter-device contention is naturally modeled (shared fabric
bandwidth, cross-SIP traffic, etc.).
- 벤치마크 실행은 단일 시뮬레이션 엔진 인스턴스에 제출된다.
- 시뮬레이션 시간 상에서 실행은 논리적으로 병렬이다.
- 디바이스 간 경합(공유 패브릭 대역폭, SIP 간 트래픽 등)이 자연스럽게
모델링된다.
The CLI does NOT spawn multiple OS processes or independent
simulation runs — parallelism is internal to one simulation instance.
CLI는 여러 OS 프로세스나 독립된 시뮬레이션 실행을 생성하지 **않는다**
병렬성은 단일 시뮬레이션 인스턴스 내부에서 일어난다.
### D4. `kernbench probe` — latency / BW diagnostic utility
### D4. `kernbench probe` — 레이턴시 / 대역폭 진단 유틸리티
Required argument:
필수 인자:
- `--topology <path>`: topology YAML file path.
- `--topology <path>`: 토폴로지 YAML 파일 경로.
Optional argument:
선택 인자:
- `--case <name>` (default: `all`) — run a predefined traffic
pattern, or `all` to run every defined case.
- `--case <name>` (기본값: `all`) — 미리 정의된 트래픽 패턴을 실행하거나,
`all`로 정의된 모든 케이스를 실행한다.
Probe runs each pattern through the simulation engine and reports
per case:
Probe는 시뮬레이션 엔진을 통해 각 패턴을 실행하고 케이스별로 다음을
보고한다:
- End-to-end latency (ns).
- Effective bandwidth (nbytes / total_ns).
- Bottleneck bandwidth (min edge BW along the chosen path).
- Utilization (effective / bottleneck).
- 종단 간 레이턴시(ns).
- 유효 대역폭(nbytes / total_ns).
- 병목 대역폭(선택된 경로상의 최소 엣지 BW).
- 활용률(유효 / 병목).
Probe additionally validates monotonicity invariants — for example
that local-HBM access ≤ cross-PE-within-cube ≤ cross-cube ≤
cross-SIP — and reports violations. Probe is a developer tool for
verifying the latency / BW model; it is not a benchmark.
Probe는 추가로 단조성 불변식을 검증한다 — 예를 들어 local-HBM 접근 ≤
큐브 내 PE 간 ≤ 큐브 간 ≤ SIP 간 — 그리고 위반을 보고한다. Probe는
레이턴시 / 대역폭 모델을 검증하기 위한 개발자 도구이다; 벤치마크가
아니다.
### D5. `kernbench web` — topology viewer
### D5. `kernbench web` — 토폴로지 뷰어
Optional arguments:
선택 인자:
- `--port <N>` (default: `8765`) — HTTP port.
- `--no-open`do not auto-open the browser.
- `--port <N>` (기본값: `8765`) — HTTP 포트.
- `--no-open`브라우저를 자동으로 열지 않는다.
Launches a local HTTP server that renders the compiled topology in
the browser. Distinct from the static `docs/diagrams/` artifacts:
컴파일된 토폴로지를 브라우저에서 렌더링하는 로컬 HTTP 서버를 띄운다.
정적인 `docs/diagrams/` 산출물과는 구별된다:
- `docs/diagrams/` files are derived at topology-compile time
(ADR-0006).
- `kernbench web` is interactive — pan/zoom, hover for component
attributes, switch between SIP / CUBE / PE views.
- `docs/diagrams/` 파일은 토폴로지 컴파일 시점에 파생된다(ADR-0006).
- `kernbench web`은 인터랙티브이다 — 팬/줌, 컴포넌트 속성 호버,
SIP / CUBE / PE 뷰 간 전환.
### D6. Runtime API and simulation engine remain device-scoped
### D6. runtime API와 시뮬레이션 엔진은 디바이스 스코프를 유지한다
- Runtime API calls operate on one device per invocation.
- The simulation engine schedules all requests deterministically.
- Neither layer enumerates devices.
- runtime API 호출은 호출당 하나의 디바이스에서 동작한다.
- 시뮬레이션 엔진은 모든 요청을 결정론적으로 스케줄링한다.
- 어느 레이어도 디바이스를 열거하지 않는다.
This invariant keeps each layer testable in isolation; device
enumeration and multi-device fan-out live only in the CLI's `run`
command (D3).
이 불변식은 각 레이어를 독립적으로 테스트 가능하게 유지한다; 디바이스
열거와 다중 디바이스 팬아웃은 오직 CLI `run` 명령에만 존재한다(D3).
## Consequences
- Benchmark authors write single-device logic; multi-device behavior
emerges from the CLI dispatching across SIPs.
- Adding a new subcommand (e.g., trace export, replay) does not
require benchmark or runtime-API changes — the CLI is the
extension point.
- `probe` and `web` are diagnostic / visualization tools, not
benchmarks; they bypass the benchmark loader path.
- 벤치마크 작성자는 단일 디바이스 로직을 작성한다; 다중 디바이스 동작은
CLI가 SIP들에 걸쳐 디스패치함으로써 자연스럽게 도출된다.
- 새로운 서브명령(예: 트레이스 내보내기, 리플레이) 추가는 벤치마크나
runtime API 변경을 요구하지 않는다 — CLI가 확장 포인트이다.
- `probe``web`은 진단/시각화 도구이며 벤치마크가 아니다; 벤치마크 로더
경로를 우회한다.
## Links
- SPEC R7, R8, R9
- ADR-0007 (Runtime API and Simulation Engine Boundaries)
- ADR-0020 (Two-pass data execution`--verify-data`)
- ADR-0006 (Topology compilation and diagram generation —
background for `kernbench web`)
- ADR-0007 (Runtime API와 시뮬레이션 엔진 경계)
- ADR-0020 (Two-pass 데이터 실행`--verify-data`)
- ADR-0006 (토폴로지 컴파일과 다이어그램 생성 — `kernbench web`의 배경)