02. Spec Validation

Every eulernpu workflow starts with a YAML spec. Before compile, runtime, or silicon deployment, that spec is checked for both formal and semantic validity. This validation step is the early-fail gate for every downstream stage.

Two-Stage Validation

Stage	What	Tool
1. schema	YAML structure, key names, types	JSON Schema (Draft 7)
2. semantic	Meaning consistency, component-op relations, board limits	20 rules S01–S23 (S03–S05 reserved)

Schema asks "is this YAML well-formed?". Semantic asks "is this combination physically and logically possible?".

Running

eulernpu validate path/to/spec.yaml

Success:

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

Failure is always in the 3-line format:

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 Rules (20)

Representative ones:

Rule	What it prevents
S01	gru/lstm without a `recurrent_unit` component
S02	`vector_alu` referencing a disabled op
S07	accumulator_bits < activation_bits (overflow risk)
S08	backend/board mismatch (zynq_ps + non-Xilinx board)
S10	weight + activation totals exceed board SRAM
S11	systolic_size that is not a power of 2
S17	flash_attention without a `sparse_attn_unit`
S18	ddim_step without a `diffusion_unit`
S20	token_acceptance not in decode mode
S22	board capability matrix violation (op not in board profile)
S23	quantize/dequantize adjacency mismatch

Full list + error messages at docs/specs/spec_schema.md.

Fixture Policy

Valid fixtures (tests/fixtures/valid_yamls/) — specs that must pass. New valid fixtures require updating docs/fixtures/fixtures_index.md.

Invalid fixtures (tests/fixtures/invalid_yamls/) — specs that must be blocked. They are regression assets.

Rules:

❌ Never delete existing invalid fixtures
❌ Never weaken validation rules
✅ Specs that used to pass but should now fail are preserved as invalid fixtures
✅ New semantic rules ship with corresponding invalid fixtures

i18n

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

The error body is translated. These are not translated:

Rule codes (S01, S22)
Key paths (components[0].vector_alu)
op/backend/dtype names

Default language is ko. Missing translations fall back to Korean.

Tiny Example — 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

Tiny Example — Invalid (S10 violation)

spec_version: "0.1"
target_backend: zynq_ps
target_board: xc7z020
components:
  - sram: {size_kb: 1024}    # XC7Z020 caps at 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

Once the spec passes → 03. compile_run.