# Validation Contract

Status: `Draft`

## Purpose

Define how subsystem correctness is judged before and during implementation.

## Principles

- Traces are first-class outputs.
- Small directed tests beat giant software workloads early.
- Every major subsystem should have a "stub-valid" test mode before a "real"
  implementation exists.
- At least one software golden reference should be selected before large RTL
  effort begins.

## Proposed validation ladder

### Level 0: structural

- modules elaborate,
- resets are deterministic,
- key registers can be written/read in simulation,
- traces are emitted.

### Level 1: directed block tests

- memory map tests,
- DMAC register tests,
- GIF packet intake tests,
- SIF mailbox tests,
- VIF packet decode tests.

### Level 2: subsystem behavior tests

- BIOS fetch trace agreement,
- GS stub/test-pattern agreement,
- simple DMA-to-endpoint transfers,
- IOP boot-progress markers.

### Level 3: software-facing tests

- tiny EE code payloads,
- tiny IOP payloads,
- `gsKit`-style graphics tests,
- minimal inter-processor coordination tests.

### Level 4: comparative reference

- compare selected traces against a golden emulator/reference,
- resolve disagreements against authoritative docs where available.

## Artifacts to maintain

- `sim/vectors/`: deterministic stimulus inputs
- `sim/traces/`: captured reference traces
- `sim/golden/`: scripts/notes for emulator-side comparison
- `software/tests/`: minimal payloads for EE/IOP/graphics/audio/device paths

## Required early decisions

- primary golden reference,
- trace format,
- first three block-level regression tests,
- policy for "spec disagrees with emulator" cases.