psxrecomp/docs/audit_inventory.md

# Audit Inventory — psxrecomp-v4

Baseline as of 2026-05-12. Captures what audit / test tooling exists, what
scope it covers, what each tool currently reports, and where the gaps are.

This document is the input for Phase B (codegen-audit expansion) and
Phase C (L2-semantic execute tier).

## Tier structure

```
Layer 5  Runtime behavioral differential vs Beetle (continuous RAM diff)    NONE
Layer 4  Hardware-sim conformance (SIO/DMA/MDEC/GTE vs no$psx)              PARTIAL
Layer 3  Codegen / discovery audits (static analysis of generated C)        PARTIAL
Layer 2b L2-semantic — execute emitted code and verify register state       NONE
Layer 2a L2-structural — emit pattern matching on generated C               HAVE
Layer 1  Per-instruction decode correctness vs Rabbitizer                   HAVE
Layer 0  Build & link integrity                                             HAVE
```

## Tools inventory

### Layer 1 — Decode conformance

**`recompiler/tests/l1_decoder_test.cpp`** (built: `recompiler/build/l1_decoder_test.exe`)
- Scope: BIOS only. Code regions Boot `0x00000-0x0DC60`, Kernel
  `0x10000-0x16760`, Shell `0x18000-0x42800`.
- Compares `MipsDecoder::decode()` mnemonic vs Rabbitizer for every word
  in those regions.
- Buckets mismatches by `oracle_mnem -> our_mnem`.

**Baseline result:** widespread mismatches. Notable buckets:
| Count | Rabbitizer says | We say     | First addr   | Comment |
|------:|-----------------|------------|--------------|---------|
|   181 | `cache`         | `???`      | 0xBFC04300   | **Real gap.** CACHE (op 0x2F) is an R3000A instruction we don't decode. |
|    31 | `mvmva`         | `gte`      | 0xBFC34FF8   | Granularity. We map all GTE cmds to generic `gte`. |
|    13 | `rtpt`          | `gte`      | 0xBFC35DF0   | Same. |
|    13 | `nclip`         | `gte`      | 0xBFC361B4   | Same. |
|    11 | `tge`           | `special?` | 0xBFC10190   | R4000 trap — likely data-in-code or kernel trap encoding. |
|    10 | `dadd`          | `special?` | 0xBFC101D4   | 64-bit (R4000+), likely data. |
|     9 | `rtps`          | `gte`      | 0xBFC35DAC   | GTE granularity. |
|     ~ | `mov.d, mtc1, lwc1, add.d` | `???` | 0xBFC02358 | FP — R3000A has no FPU; likely data-in-code in Boot region. |

Two distinct classes:
- **Real decode gap:** `cache` (op 0x2F). 181 sites. Decoder needs a case.
- **Granularity gap:** GTE sub-mnemonics. Not a correctness bug — our
  emit treats all GTE cmds via `gte_execute`. But audit clarity benefits
  from matching Rabbitizer's specificity.
- **False positives (data-in-code):** dadd, dmult, dsll32, mov.d, mtc1,
  c.eq.d, etc. These are R4000+ / FPU instructions that don't exist on
  R3000A. They appear because we scan the entire region without skipping
  inline data or jump tables. Filter improvement, not a decoder bug.

### Layer 2a — Structural emit conformance

**`recompiler/tests/l2_structural_test.cpp`** (built: `l2_structural_test.exe`)
- For each MIPS instruction form, build word, translate via
  `StrictTranslator`, verify emitted C contains expected patterns
  (e.g., `gpr[2]`, `gpr[4]`, `<< 1u`).
- Snesrecomp-style. Note in source: "does NOT verify semantic
  correctness (that requires L2-semantic with actual execution)."

**Baseline result:** `42/42 ok`.

**Gap:** 42 forms / ~150 R3000A instructions ≈ 28% coverage. No
coverage for: load-delay-slot semantics, mult/div HI-LO timing, LWL/
LWR/SWL/SWR unaligned partial-word, JALR same-source/dest, shift-by-32
edge case, COP0 RFE / SR-bit semantics.

### Layer 2b — Semantic execute conformance

**Status:** does not exist.

The gap. To know "does our emit *do* the right thing when run", we'd:
1. Build a tiny test harness that takes MIPS bytes + initial CPUState,
   runs the recompiler → C → execute, returns final CPUState.
2. For each instruction, supply known input registers and assert output
   matches the R3000A spec.
3. Cross-check against mednafen-PSX's CPU as a reference impl.

This is Phase C.

### Layer 3 — Codegen / discovery audits

**`tools/_codegen_audit.py`** (BIOS only)
- 6 passes against `generated/SCPH1001_full.c` + `_dispatch.c`:
  1. Predicate-init audit (verifies 2026-05-04 fix).
  2. Direct `psx_dispatch(cpu, 0xXXXX)` targets in dispatch table.
  3. Indirect `psx_dispatch(cpu, gpr[N])` distribution.
  4. Tail-call `cpu->pc = ...; return;` targets in dispatch table.
  5. Chained-branch-with-delay-slot-label population.
  6. Highest-frequency missing dispatch targets.

**Baseline result:**
- Predicate decl audit: `buggy=0 zero_init=6104 assigns=6104` ✓
- Direct psx_dispatch: 796 unique, 0 missing ✓
- Indirect sites: 88 (across many registers)
- Tail-call missing: **1 site → `0x00000CF0`** — the install-at-runtime
  SIO data-byte handler stub. Expected, handled by dirty-RAM
  interpreter. Not a regression.
- Chained-branch with delay-slot label: 27 sites, all protected ✓

**`tools/gte_audit.py`** (BIOS only)
- Scans ROM for COP2/GTE instructions, compares against generated code.

**Baseline result:** "missing" hits in `0xBFC75xxx..0xBFC7Fxxx`. These
are in the BIOS DATA region (code ends at `0xBFC42800`). All false
positives from scanning data bytes that happen to decode as COP2 ops.
Need to filter by code region.

**`tools/scan_branch_delay_hazards.py`** (BIOS only)
- For every conditional branch in walked code, checks whether the
  delay slot writes to the branch's rs/rt operand.
- Verifies `strict_translator.cpp` uses the snapshot pattern.

**Baseline result:**
- Branches scanned: 4617
- Delay slot writes branch operand: 441 (intrinsic, informational)
- **Incorrect in current translator: 0 ✓**
- Delay-slot unreachable in walk: 0 ✓

**`tools/check_dispatch.py`** — one-off probe with hardcoded address
list. Not generally useful. **Skip from active inventory.**

### Layer 4 — Hardware-sim conformance

**`runtime/tests/test_sio_card_protocol.c`**
- Drives `sio.c` TX/RX state machine through a 137-byte memcard READ
  command, asserts each RX byte matches no$psx.
- Not run as part of this Phase A pass (built but not invoked here).

**Gap:** other MMIO regions — DMA, MDEC, GPU command stream, timers,
IRQ controller — have no protocol conformance tests.

### Layer 5 — Runtime differential

Does not exist. Both psx-runtime (port 4370) and psx-beetle (port 4380)
speak the same wire protocol, so the infrastructure for paired wtrace
queries is present; what's missing is the diff-and-cluster tool itself.

## Tool generalization status

**All five Layer 1-3 tools are hardcoded to BIOS paths.** They were
written during Phase 1-3 BIOS bring-up and have not been generalized
to game code. For Phase B, generalize them via:
- Argument: `--full-c PATH --dispatch-c PATH --rom PATH` (or read from
  `game.toml`-style config).
- Run each tool once for BIOS, once for Tomba.

## Phase A findings — what to do with them

| Finding | Class | Priority | Phase |
|---------|-------|---------:|-------|
| L1: `cache` (op 0x2F) not decoded — 181 sites | Real decoder gap | High | Phase B |
| L1: GTE sub-mnemonic granularity | Audit clarity | Low | Phase B |
| L1: FPU / 64-bit FPs in data regions | Audit filter | Low | Phase B |
| L2: 42 forms / ~150 instructions = 28% coverage | Test gap | High | Phase C |
| L2-semantic tier does not exist | Architectural | High | Phase C |
| All audits BIOS-only | Tool scope | High | Phase B |
| gte_audit.py false-positives in data region | Audit filter | Low | Phase B |
| Tail-call miss at 0x00000CF0 | Expected stub | None | — |

## Progress log

### Phase B2 (2026-05-12) — First audit pass against Tomba

Ran all three Python audits against Tomba's `SCUS_942.36`. Mixed
outcome — tool gaps surfaced and real bugs surfaced.

**Initial run findings:**
- `codegen_audit.py` returned all zeros — its regexes are BIOS-emit-
  specific and don't match the game `full_function_emitter` shape
  (direct `func_X(cpu)` calls, switch-based dispatch, `_bc_X` branch
  conds). **Required a sibling tool.**
- `gte_audit.py` reported **29 findings** in Tomba text segment
  (8 GTE + 21 LWC2/SWC2). See TombaRecomp ISSUES Issue #2.
- `scan_branch_delay_hazards.py` correctly skipped walker (no
  function_starts file for Tomba) and ran translator-source check.

**`codegen_audit_game.py` created** (per the principle: separate tool
sharing patterns only at the margins). Audits the 6 passes that
matter for game-emit style. After fixing my dispatch-table regex
(Tomba uses `case 0xADDRu: func_X(cpu); return 1;` not BIOS's array
form) and adding code-region filtering for `call_by_address` literals
(331 of 333 are RAM-loaded overlays handled by `dirty_ram_dispatch`,
expected):

| Pass | Result |
|------|--------|
| 1. Direct func_X(cpu) calls | 2,973 calls, 840 unique → **all resolve** ✓ |
| 2. Literal call_by_address  | 333 unique → **2 in-code misses** ⚠ |
| 3. Indirect call_by_address | 360 sites (informational) |
| 4. Tail-call cpu->pc=X      | **0 sites** (game emit doesn't use this idiom) ✓ |
| 5. Branch-cond declarations | 6,708 (informational) |
| 6. goto block_X resolution  | 20,172 sites, **all resolve** ✓ |

**Real bug surfaced: Issue #5 — mid-function split targets not
registered in dispatch table.** Three emit sites in
`code_generator.cpp` (lines 970, 981, 998) emit `call_by_address` for
mid-func continuations without calling `register_cross_function_target`.
This is the same bug class as today's jump-table fix. Tomba has 2
manifestations (`0x800905E4`, `0x80090600` inside `func_800905DC`).
**B2's first pass against Tomba found a real recompiler bug.**

### Phase B0 (2026-05-12) — Audit-config schema

Defined a TOML schema for audit configs. Both BIOS and games consume
the same shape; field names are tolerant (`[program]` or `[game]`,
`rom` or `exe`).

Artifacts:
- `tools/audit_config.py` — shared loader.
- `tools/verify_audit_schema.py` — schema validator.
- `bios/SCPH1001.toml` — BIOS config (3 regions, 2 address remaps).
- `TombaRecomp/game.toml` — extended with `[audit]` block (1 region,
  0 remaps).

### Phase B1 (2026-05-12) — Python audit generalization

Migrated three Python audits to consume the audit-config schema. All
three pass BIOS regression with output matching the Phase A baseline.

| Tool                          | Status   | BIOS regression                                                |
|-------------------------------|----------|----------------------------------------------------------------|
| `tools/codegen_audit.py`      | migrated | identical to Phase A (CLEAN, 0 real findings)                  |
| `tools/gte_audit.py`          | migrated | 73 false-positives eliminated by code-region filter; 7 real findings surfaced |
| `tools/scan_branch_delay_hazards.py` | migrated | identical to Phase A (CLEAN); also runs translator-source check for non-BIOS configs that lack a function_starts file |
| `recompiler/tests/l1_decoder_test.cpp`     | **deferred** | C++ TOML parsing not yet wired; the test still runs against hardcoded BIOS `kRegions[]`. Generalize in a later sub-phase. |
| `recompiler/tests/l2_structural_test.cpp`  | not needed | no per-program input; already generic.                          |

Side effects of generalization:
- `gte_audit.py` surfaced 7 previously-masked findings in Shell code:
  4 missing `gte_execute` emits at `0xBFC34FF8`, `0xBFC3502C`,
  `0xBFC35064`, `0xBFC350C4` (all `0x4A480012` = MVMVA), plus
  3 missing LWC2/SWC2 emits. None of these PCs appear in
  `generated/SCPH1001_full.c` — either a discovery gap (function
  containing them not recompiled) or an emit gap. Investigate in
  Phase B3 or B4.

## Methodology going forward

Every new bug class encountered should follow:
1. Reproduce / characterize the class (not the single instance).
2. **Build the audit FIRST** — find every instance of the class in the
   codebase via tooling, not by manual repro of each.
3. Fix the underlying recompiler / runtime issue.
4. Re-run the audit, confirm class is now empty.
5. Add the audit to the standing audit suite so the class can't
   regress.

The audit suite forms the regression net: "0 findings, audited N sites"
is the only acceptable state for a known class.