psxrecomp/docs/internal

Internal dev-logs & design notes

These are the working design documents and burn-down logs the project was built from. They are historical/working notes, not contributor onboarding docs — they capture decisions, phased plans, and deep subsystem investigations in the order they happened, and some sections are superseded by later ones.

If you're new here, start with the top-level README.md, then docs/ARCHITECTURE.md, docs/EXECUTION_MODEL.md, docs/BUILDING.md, and CONTRIBUTING.md. Come here when you need the why behind a specific subsystem.

Plans & roadmap

• PLAN.md — the original phased build plan (P1–P6).
• FAITHFUL_TIMING_PLAN.md — the authoritative cycle-accuracy north-star plan and status log.
• FIRST_MILESTONE.md — the first-boot milestone gate.
• STUBS_TO_FIX.md — hardware-stub burn-down (pre-game gate).

Cycle accuracy & timing

• PRECISE_IRQ_SLICE.md — exact-instruction IRQ delivery.
• CYCLE_MODEL_BEETLE.md — the Beetle-derived cycle model.
• ACCURACY_BURNDOWN.md — full accuracy burn-down across all axes (semantics, cycle, IRQ, MMIO, peripherals, determinism).
• COSIM_ORACLE.md — the first-divergence co-sim oracle.

BIOS / scheduler

• HLE_SCHEDULER_CARVEOUT_PLAN.md — the cooperative-thread scheduler HLE carve-out.
• WEDGE_load4_shell_rootcause.md — a specific boot-shell wedge root-cause writeup.

Renderer / widescreen

• GL_RENDERER_HANDOFF.md — OpenGL renderer design.
• NATIVE_WIDE_PLAN.md — native-wide 16:9 (GTE FOV) plan.
• BACKDROP_PRELOAD.md — widescreen backdrop preload.

Project conventions & tracking

• PRINCIPLES.md — this repo's debugging and enhancement principles (first-divergence, verified-enhancement HLE). Source comments cite it as docs/internal/PRINCIPLES.md; a "recomp-template PRINCIPLES.md" citation means a different repo's file.
• ISSUES.md — the historical framework issue log. Live framework work is tracked in Beads (epic beads-eio.3), not here.
• DEBUG.md — the debugging playbook behind the TCP debug server; the command reference itself is ../TCP_COMMANDS.md.
• audit_inventory.md — what the codegen/GTE audit pipeline covers and why.

Overlay design & discovery

• overlay-recompilation-design.md — the design and rationale for overlay recompilation.
• overlay-plan.md — the phased overlay implementation plan.
• overlay-discovery.md — how overlays are discovered on disc and at runtime.
• overlay-status.md — living what-works / what's-broken status for the overlay capture/compile/cache path.
• CASE_A_AOT_GAP.md — the Case-A AOT dispatch-miss gap; cited by the rationale fields in recompiler/seeds/*.json.

BIOS / boot hardening

• bios-hardening.md — BIOS boot hardening notes.

GTE / CPU investigations

• GTE_LM_FIX.md — the GTE lm saturation-flag fix writeup.
• TOMBA2_EXC_CONSULT_RESPONSE.md — exception -path consultation response for the Tomba 2 bring-up.

Upstream contributor reviews

upstream/ holds per-PR review notes for community contributions, one file per change, named <contributor>-<pr>-<topic>.md.

• upstream/UPSTREAM_2026-08-20.md — the 2026-08-20 upstreaming sweep: which contributed changes are framework-general and which are title configuration.

Overlay cache internals

• SLJIT_PERSIST_CACHE.md — removed. It described the persisted shard cache of the sljit Tier-2 backend, which was deleted in 5b7e69b4 (2026-07-15). For the current model see runtime/src/overlay_loader.c (per-entry candidate validity), tools/compile_overlays.py (shard formation and the .ranges manifest), and ../COMPILING_OVERLAYS.md.

Removed

• CYCLE_TIMING_ARCH.md — removed. Its cycle-timing architecture sketch was superseded and nothing linked to it. For the current model see FAITHFUL_TIMING_PLAN.md (the authoritative plan), CYCLE_MODEL_BEETLE.md (the Beetle-derived cycle model), and PRECISE_IRQ_SLICE.md (exact-instruction IRQ delivery).