02. 스펙 검증 (validate)

eulernpu의 모든 흐름은 YAML 스펙에서 시작합니다. 컴파일/런타임/silicon 배포 이전에 그 스펙이 형식적으로도, 의미적으로도 유효한지 먼저 검증합니다. 이 검증 단계가 모든 후속 단계의 일찍 실패(early-fail) 게이트입니다.

2단계 validation

단계	무엇	도구
1. schema	YAML 구조, 키 이름, 타입	JSON Schema (Draft 7)
2. semantic	의미 일관성, 컴포넌트-op 관계, 보드 한계	20개 규칙 S01–S23 (S03–S05 reserved)

schema는 "이 YAML이 문법적으로 맞나"를 봅니다. semantic은 "이 조합이 물리적으로/논리적으로 가능한가"를 봅니다.

실행

eulernpu validate path/to/spec.yaml

성공:

Validation OK: 14 operators · 5 components · backend=cpu_ref

실패는 항상 3줄 포맷입니다:

SemanticError: gru_cell present but no recurrent_unit component declared
Fix: Add `components: [recurrent_unit: {...}]` to spec
See: docs/specs/spec_schema.md#S01

semantic 규칙 (20개)

대표적인 것들:

규칙	무엇을 막는가
S01	gru/lstm 사용 시 `recurrent_unit` 컴포넌트 필수
S02	`vector_alu`가 비활성화된 op 참조
S07	accumulator_bits < activation_bits (overflow 위험)
S08	backend/board 불일치 (zynq_ps + xilinx 외 보드)
S10	weight+activation 총량이 board SRAM 초과
S11	systolic_size가 2의 거듭제곱이 아님
S17	flash_attention 사용 시 `sparse_attn_unit` 필수
S18	ddim_step 사용 시 `diffusion_unit` 필수
S20	token_acceptance가 decode 모드가 아님
S22	board capability matrix 위반 (board profile에 없는 op)
S23	quantize/dequantize 인접 불일치

전체 목록 + 위반 시 표시되는 에러는 docs/specs/spec_schema.md에 있습니다.

fixture 정책

Valid fixture (tests/fixtures/valid_yamls/) — 통과해야 하는 스펙. 새 valid fixture 추가 시 docs/fixtures/fixtures_index.md 도 갱신합니다.

Invalid fixture (tests/fixtures/invalid_yamls/) — 차단되어야 하는 스펙. 회귀 자산입니다.

규칙:

❌ 기존 invalid fixture 삭제 금지
❌ validation 규칙 약화 금지
✅ 과거 허용되었으나 이제 금지해야 하는 스펙은 invalid fixture로 보존
✅ 새 semantic 규칙 추가 시 invalid fixture도 추가

i18n

eulernpu --lang en validate path/to/spec.yaml
eulernpu --lang ko validate path/to/spec.yaml

에러 본문은 번역됩니다. 다만 다음은 번역하지 않습니다:

규칙 코드 (S01, S22)
key path (components[0].vector_alu)
op/backend/dtype 이름

기본 언어는 ko. 누락된 번역은 한국어로 fallback.

작은 예제 — minimal valid

spec_version: "0.1"
target_backend: cpu_ref
operators:
  - linear
  - relu
components:
  - vector_alu: {ops: [linear, relu]}
quantization:
  mode: fp32

$ eulernpu validate minimal.yaml
Validation OK: 2 operators · 1 component · backend=cpu_ref

작은 예제 — invalid (S10 위반)

spec_version: "0.1"
target_backend: zynq_ps
target_board: xc7z020
components:
  - sram: {size_kb: 1024}    # XC7Z020은 256KB까지

$ eulernpu validate huge_sram.yaml
SemanticError: sram size 1024 KB exceeds board xc7z020 (max 256 KB)
Fix: Reduce sram.size_kb to ≤ 256, or pick a larger board (xczu7ev etc)
See: docs/specs/spec_schema.md#S10

다음 단계

스펙이 통과하면 → 03. compile_run으로.