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-0012: Host ↔ IO_CPU Message Schema (PA-first, PE-tagged)
# ADR-0012: Host ↔ IO_CPU 메시지 스키마 (PA-우선, PE-태깅)
## Status
@@ -6,63 +6,65 @@ Accepted
## Context
Phase 0 uses a PA-first memory model (ADR-0011):
Phase 0은 PA-우선 메모리 모델을 사용한다(ADR-0011):
- memory operations use device physical addresses (PA) only,
- VA/MMU/IOMMU is not modeled.
- 메모리 연산은 디바이스 물리 주소(PA)만 사용한다,
- VA/MMU/IOMMU는 모델링하지 않는다.
The host-facing runtime API interacts with the device via the IO_CPU endpoint.
We define stable, minimal message schemas for Host ↔ IO_CPU so that:
호스트 대면 runtime API는 IO_CPU 엔드포인트를 통해 디바이스와
상호작용한다. 다음을 보장하기 위해 Host ↔ IO_CPU에 대한 안정적이고
최소한의 메시지 스키마를 정의한다:
- benchmarks remain stable,
- IO_CPU-internal fan-out/aggregation can evolve independently,
- completion and failure propagation is deterministic.
- 벤치마크는 안정적으로 유지된다,
- IO_CPU 내부의 팬아웃/집계는 독립적으로 진화할 수 있다,
- 완료와 실패 전파는 결정론적이다.
We also require PE-tagging (A 방식): each shard explicitly carries (sip,cube,pe)
so IO_CPU can deterministically route/fan-out without relying on PA decoding.
또한 PE-태깅(A 방식)을 요구한다: 각 샤드는 (sip,cube,pe)를 명시적으로
운반하여, IO_CPU가 PA 디코딩에 의존하지 않고 결정론적으로
라우팅/팬아웃할 수 있도록 한다.
---
## Decision
### D1. Contract scope
### D1. 계약 범위
This schema is the stable contract ONLY for Host ↔ IO_CPU.
본 스키마는 오직 Host ↔ IO_CPU에 대해서만 안정적인 계약이다.
Messages beyond IO_CPU (to M_CPU, PE_CPU, schedulers, engines) are component-internal
and are NOT part of this host contract in Phase 0.
IO_CPU를 넘어선 메시지(M_CPU, PE_CPU, 스케줄러, 엔진으로 가는 것)는
컴포넌트 내부 사항이며 Phase 0에서 이 호스트 계약의 일부가 아니다.
---
### D2. Required message set
### D2. 필수 메시지 집합
The runtime API MUST use only these message types for Host ↔ IO_CPU:
runtime API는 Host ↔ IO_CPU에 대해 오직 다음 메시지 타입만 사용해야 한다:
- MemoryWrite
- MemoryRead
- KernelLaunch
All operations required by benchmarks (tensor init/copy, kernel run) MUST be expressible
with these messages.
벤치마크가 필요로 하는 모든 연산(텐서 초기화/복사, 커널 실행)은 이
메시지들로 표현 가능해야 한다.
---
### D3. Common envelope (mandatory for all requests)
### D3. 공통 envelope (모든 요청에 필수)
All Host ↔ IO_CPU requests MUST include:
모든 Host ↔ IO_CPU 요청은 반드시 다음을 포함해야 한다:
- `msg_type: str`
- `correlation_id: str`
- generated by the host
- used to match responses deterministically
- 호스트에서 생성
- 응답을 결정론적으로 매칭하는 데 사용
- `request_id: str`
- unique within a correlation_id
- correlation_id 내에서 고유함
- `target_device: str`
- device identifier (e.g., "sip:0")
- `timestamp_tag: str | None` (optional)
- debug tag only; MUST NOT affect determinism
- 디바이스 식별자(예: "sip:0")
- `timestamp_tag: str | None` (선택)
- 디버그 태그 전용; 결정성에 영향을 주어서는 안 됨
All Host ↔ IO_CPU responses MUST include:
모든 Host ↔ IO_CPU 응답은 반드시 다음을 포함해야 한다:
- `correlation_id: str`
- `request_id: str`
@@ -70,120 +72,123 @@ All Host ↔ IO_CPU responses MUST include:
---
### D4. Completion schema (mandatory)
### D4. Completion 스키마 (필수)
`Completion` MUST have:
`Completion`은 반드시 다음을 가져야 한다:
- `ok: bool`
- `error_code: str | None`
- `error_message: str | None`
Rules:
규칙:
- If `ok == true` then `error_code` and `error_message` MUST be null.
- If `ok == false` then `error_code` MUST be non-null.
- Completion semantics MUST be deterministic.
- `ok == true`이면 `error_code` `error_message`는 반드시 null이어야 한다.
- `ok == false`이면 `error_code`는 반드시 null이 아니어야 한다.
- 완료 시맨틱은 결정론적이어야 한다.
---
### D5. MemoryWrite schema (PA-first, PE-tagged)
### D5. MemoryWrite 스키마 (PA-우선, PE-태깅)
`MemoryWrite` represents a host-initiated write/initialize operation to device memory.
`MemoryWrite`는 호스트에서 시작된 디바이스 메모리 쓰기/초기화 연산을
나타낸다.
Mandatory fields:
필수 필드:
- common envelope fields (D3)
- destination placement tags (A 방식):
- 공통 envelope 필드 (D3)
- 목적지 배치 태그 (A 방식):
- `dst_sip: int`
- `dst_cube: int`
- `dst_pe: int`
- `dst_pa: int`
- destination physical address in the destination PE's address space
- 목적지 PE의 주소 공간 내 목적지 물리 주소
- `nbytes: int`
- `src_kind: "pattern" | "host_buffer_ref"`
- Phase 0 MUST support "pattern"
- Phase 0은 반드시 "pattern"을 지원해야 한다
- `pattern: Pattern | None`
- required if `src_kind == "pattern"`
- `src_kind == "pattern"`인 경우 필수
`Pattern` (Phase 0 mandatory support):
`Pattern` (Phase 0 필수 지원):
- `pattern_kind: "zero" | "fill_u8" | "fill_u16" | "fill_u32" | "fill_fp16" | "fill_fp32"`
- `value: number | None`
- required for fill_*; ignored for zero
- fill_*에 필요; zero에서는 무시됨
Optional fields:
선택 필드:
- `dst_mem_kind: "HBM" | "TCM" | "AUTO"` (default "AUTO")
- `dst_mem_kind: "HBM" | "TCM" | "AUTO"` (기본값 "AUTO")
- `debug_label: str | None`
Notes:
비고:
- This message MUST NOT embed bulk tensor data in Phase 0.
- All latency MUST come from explicit graph traversal and modeled components.
- 이 메시지는 Phase 0에서 대용량 텐서 데이터를 임베드해서는 안 된다.
- 모든 레이턴시는 명시적인 그래프 순회 및 모델링된 컴포넌트로부터
발생해야 한다.
---
### D6. MemoryRead schema (PA-first, PE-tagged)
### D6. MemoryRead 스키마 (PA-우선, PE-태깅)
`MemoryRead` represents a host-initiated read from device memory.
`MemoryRead`는 호스트에서 시작된 디바이스 메모리 읽기를 나타낸다.
Mandatory fields:
필수 필드:
- common envelope fields (D3)
- source placement tags (A 방식):
- 공통 envelope 필드 (D3)
- 소스 배치 태그 (A 방식):
- `src_sip: int`
- `src_cube: int`
- `src_pe: int`
- `src_pa: int`
- `nbytes: int`
Optional fields:
선택 필드:
- `dst_kind: "host_sink" | "discard"` (default "host_sink")
- `dst_kind: "host_sink" | "discard"` (기본값 "host_sink")
- `debug_label: str | None`
Response payload:
응답 페이로드:
- actual bytes are NOT required in Phase 0 (latency/traces focus)
- implementations MAY return lightweight stats or hashes later via a new ADR
- Phase 0에서는 실제 바이트는 필요하지 않다(레이턴시/트레이스 중심)
- 구현은 추후 새로운 ADR을 통해 가벼운 통계나 해시를 반환할 수 있다
---
### D7. KernelLaunch schema (PA-first, PE-tagged shards)
### D7. KernelLaunch 스키마 (PA-우선, PE-태깅된 샤드)
`KernelLaunch` represents launching a kernel on a target device via IO_CPU.
`KernelLaunch`는 IO_CPU를 통해 대상 디바이스에서 커널을 런치하는 것을
나타낸다.
Mandatory fields:
필수 필드:
- common envelope fields (D3)
- 공통 envelope 필드 (D3)
- `kernel_ref: KernelRef`
- `args: list[KernelArg]`
`KernelRef` MUST have:
`KernelRef`는 반드시 다음을 가져야 한다:
- `name: str`
- `kind: "deployed" | "builtin"`
- `deploy_pa: int | None`PA where kernel binary was deployed (required for "deployed")
- `deploy_sip: int`SIP where binary resides
- `deploy_cube: int`cube where binary resides
- `deploy_pe: int`PE where binary resides
- `nbytes_code: int`kernel binary size (for BW modeling)
- `deploy_pa: int | None`커널 바이너리가 배치된 PA("deployed"에 필수)
- `deploy_sip: int`바이너리가 위치한 SIP
- `deploy_cube: int`바이너리가 위치한 큐브
- `deploy_pe: int`바이너리가 위치한 PE
- `nbytes_code: int`커널 바이너리 크기(BW 모델링용)
Kernel binaries MUST be pre-deployed to device memory via MemoryWrite.
KernelLaunch MUST NOT embed kernel source code or IR in the launch message.
커널 바이너리는 MemoryWrite를 통해 디바이스 메모리에 사전 배치되어야 한다.
KernelLaunch는 커널 소스 코드나 IR을 런치 메시지에 임베드해서는 안 된다.
`KernelArg` supports tensor args by PA mapping and scalars by value.
`KernelArg`는 PA 매핑을 통한 텐서 인자와 값을 통한 스칼라 인자를 지원한다.
Tensor arg (mandatory):
텐서 인자 (필수):
- `arg_kind: "tensor"`
- `tensor_pa_map: TensorPAMap`
`TensorPAMap` MUST have:
`TensorPAMap`은 반드시 다음을 가져야 한다:
- `shards: list[TensorShard]`
`TensorShard` MUST have (A 방식 강제):
`TensorShard`는 반드시 다음을 가져야 한다 (A 방식 강제):
- `sip: int`
- `cube: int`
@@ -192,42 +197,43 @@ Tensor arg (mandatory):
- `nbytes: int`
- `offset_bytes: int`
Scalar arg (mandatory):
스칼라 인자 (필수):
- `arg_kind: "scalar"`
- `dtype: "i32" | "i64" | "fp16" | "fp32" | "bool"`
- `value: number | bool`
Optional KernelLaunch fields:
KernelLaunch 선택 필드:
- `grid: dict | None`
- `meta: dict | None`
- `failure_policy: "fail_fast" | "collect_all"` (default "fail_fast")
- `failure_policy: "fail_fast" | "collect_all"` (기본값 "fail_fast")
- `debug_label: str | None`
Notes:
비고:
- KernelLaunch MUST NOT embed bulk tensor data.
- KernelLaunch MUST be submitted only to the IO_CPU endpoint.
- IO_CPU MUST fan-out work internally using the shard (sip,cube,pe) tags.
- KernelLaunch는 대용량 텐서 데이터를 임베드해서는 안 된다.
- KernelLaunch는 오직 IO_CPU 엔드포인트에만 제출되어야 한다.
- IO_CPU는 샤드의 (sip,cube,pe) 태그를 사용하여 내부적으로 작업을
팬아웃해야 한다.
---
## Verification Notes
Tests SHOULD validate:
테스트는 다음을 검증해야 한다:
- schema validation rejects missing mandatory fields,
- deterministic correlation/response matching,
- MemoryWrite/Read/KernelLaunch produce explicit hop traces,
- all routed requests incur latency > 0.
- 스키마 검증이 필수 필드 누락을 거부함,
- 결정론적 correlation/응답 매칭,
- MemoryWrite/Read/KernelLaunch가 명시적인 홉 트레이스를 생성함,
- 라우팅된 모든 요청은 레이턴시 > 0을 가짐.
---
## Links
- ADR-0011 (Memory Addressing — PA / VA / LA)
- ADR-0007 (runtime_api vs sim_engine boundaries)
- ADR-0009 (kernel execution fan-out/aggregation)
- ADR-0013 (Verification strategy — V1 message schema validation)
- ADR-0011 (메모리 주소 지정 — PA / VA / LA)
- ADR-0007 (runtime_api sim_engine 경계)
- ADR-0009 (커널 실행 팬아웃/집계)
- ADR-0013 (검증 전략 — V1 메시지 스키마 검증)
- SPEC R2, R7, R8