[Recompiler] Recompiler coverage / Runtime integration roadmap

[mao2009]

概要

PSXRecompStudio の Recompiler を、すでに成立した 最小Vertical Slice / 最初のreal-ROM function proof から、実タイトル入力・coverage拡大・Runtime/Hardware統合・再現可能なtitle execution へ進めるための親Roadmap Issue。

今後の主要KPIは、proofの存在そのものではなく、どの実コードまで安全にrecompileできるか、どこで止まるか、Runtimeへどう接続するか、そして実タイトルの画面を実pipelineから再現できるかとする。

完了済みの基盤

Synthetic Vertical Slice — 完了

#209 で以下の最小経路を成立済み。

MIPS
  -> validated IR
  -> deterministic host C
  -> host build
  -> bounded execution
  -> State Snapshot
  -> Interpreter diff

First real-ROM function — 完了

#225 で、保守的に選択した実PS1 executable由来のbounded functionについて、real-ROM analysis → IR → host code → execute → interpreter comparison を成立済み。

これは「ゲーム全体がrecompile可能」という意味ではなく、実ROM由来コードをproof pathへ接続できることの確認。

Full-title execution orchestration — 基盤成立

#366 / PR #373 以降、segment単位のexecution orchestrationとstate continuityの基盤が存在する。

#380 / ADR-015 以降、production execution composition root が存在し、現時点のproduction pathは概ね:

Application entry point
  -> TitleExecutionService
  -> ExecutionOrchestrator
  -> InterpreterTitleExecutionEngine

Real analyzed executable -> production execution — 完了

#409 / PR #425 で、legal user-supplied real PS-X EXE / disc analysis resultをproduction execution pathへ投入し、次のunsupported boundaryまでclassified executionできる経路が成立済み。

v0.1.0 方針 — CLI/headless first

#351 の Persona title-screen gateでは、Avalonia/Studio上のゲーム画面表示を必須にしない。

まず以下を実pipelineで再現可能にすることを優先する:

legal user input
  -> analysis
  -> recompilation / build
  -> production Runtime
  -> required BIOS/HLE + Hardware
  -> GPU / framebuffer
  -> deterministic frame capture (PNG/raw/hash)
  -> CLI/headless verification

CLIは別のexecution/runtime実装を持たず、既存Application/Core/Runtimeサービスの薄いadapterとする (#15)。Studio GUIは同じframe/runtime境界を後から利用する。

このため、GUI project/workspace、解析画面、設定画面、ゲームframeのAvalonia presentationはv0.1のcritical pathから外す。

現在の最重要KPI

KPI 1 — Real executable enters the production path — 完了

user-supplied real PS-X EXE / disc analysis resultを、production title execution pathへ安全に投入できるか。

#409 / PR #425 で完了。

KPI 2 — Measure coverage, not only successful proof candidates

実タイトルの解析対象全体のうち、現在どこまでlower/recompile可能で、残りはなぜ拒否されるのかを説明できるか。

主対象: #410 / #215

KPI 3 — Explicit observable-effect semantics

MMIO / BIOS / runtime transfer / indirect control flow / exception-producing operationをordinary RAM/control-flowと混同せずfail-closedに扱えるか。

主対象: #411

KPI 4 — Runtime blockers are evidence-driven

実タイトル実行で遭遇した最初のunsupported boundaryを分類し、必要なCPU/BIOS/MMIO/Hardware supportだけをgenericに実装できるか。

主対象: #279 / #386 / #440 / #442 / #441 / 関連focused Issues

KPI 5 — Persona title-screen gate

#351 のrelease gateとして、Personaがfake/test-only pathではなく実pipelineでtitle screen frameを生成できるか。

GUI表示ではなく、CLI/headlessで実Runtimeが生成したframebuffer/frame evidenceを再現・検証できればv0.1 gateを満たせる。Core/RecompilerへのPersona固有hackは禁止。

現行ロードマップ

Phase A — Correctness / boundary hardening

• [Recompiler] Define and enforce generated-host execution budget semantics #375 — generated-host execution budget semantics — completed
• [Security] ChdReader/ChdHeader and Iso9660Reader allocate from untrusted length fields with no bound check #394 — hostile CHD/ISO length-field allocation hardening
• auditで発見された既知correctness gapを優先的に解消

原則: proof/test infrastructure自体が誤った結果を「一致」と判定しないことを先に守る。

Phase B — Real input -> production execution — 完了

• [Runtime] Connect analyzed real PS-X EXE input to the production title execution path #409 — analyzed PS-X EXEをproduction execution requestへ接続 — completed via PR feat(runtime): connect analyzed real PS-X EXE to production title execution path (#409) #425
• existing loader/parser/analysis modelを再利用
• unsupported boundaryで明示的に停止する

Gate B: achieved. legal user-supplied real executableがproduction engineへ入り、実際のunsupported boundaryをclassified resultとして返せる。

Phase C — Recompiler coverage measurement

• [Analysis/Recompiler] Add real-ROM recompilation coverage analysis separate from proof candidate selection #410 — proof candidate selectionとは別にwhole analyzed corpusのcoverageを測定
• [Analysis] Define deterministic real-ROM analysis report and snapshot format #215 — deterministic real-ROM report/artifactへ接続

Gate C: 「選べば動く」だけでなく、「全体の何が動かず、なぜか」を再現可能に説明できる。

Phase D — Effect semantics / lowering safety

• [Recompiler/IR] Define observable side-effect semantics for MMIO, runtime transfers, and indirect control flow #411 — observable side-effect semantics

MMIO/device access、BIOS/runtime transfer、indirect/unresolved flow、exception-producing operation、unsupported effectをordinary guest RAM/control-flowと混同しない。

Gate D: 未対応effectはsilent loweringされず、明示的にunsupported/transferとして残る。

Phase E — Runtime / Hardware bring-up

実タイトルから得た依存グラフを根拠に進める。

主要scope:

• [Runtime/BIOS] Make BIOS-less execution the default via BIOS HLE #279 — BIOS-less execution / BIOS HLE
• [Guest Memory/DMA] Managed Dma MMIO layer is unreachable from any real execution path; scratchpad and RAM mirror unimplemented #386 — DMA/MMIO wiring、scratchpad、RAM mirror
• [Runtime/Scheduling] Implement CPU-cycle-driven device tick/IRQ scheduling contract (Timer/DMA/VBlank) #442 — CPU-cycle-driven timer/DMA/VBlank scheduling
• [Runtime/GPU] Define GPU MMIO register contract, GPUSTAT/GP0/GP1 model, and VRAM buffer (no rasterization) #440 — GPU MMIO / GP0 / GP1 / GPUSTAT / VRAM / DMA2
• [Runtime/GPU] Implement minimal GPU rasterization and headless frame output for title-screen bring-up #441 — minimal rasterization + deterministic headless frame output
• [Test Harness] HostTitleExecutionEngine doesn't round-trip DMA/timer/interrupt state across per-segment process forks #387 — host differential harness DMA/timer/interrupt state continuity
• [Runtime/SIO] Implement SIO0 register model and controller/memory-card serial protocol #443/[Runtime/CD-ROM] Define CD-ROM command/status/FIFO register contract, DMA3, and IRQ2 (child of #14) #444/[Runtime/SPU] Define SPU register/MMIO model (register contract only, no audio output) #445/[Runtime/GTE] Implement GTE/COP2 command execution (follow-up to #377, evidence-gated) #447 等はreal execution evidenceで必要になった時点で昇格

GPU/SPU/CD-ROM/GTE等を番号順に全面実装せず、現在のreal execution blockerを前進させる最小generic scopeを優先する。

Phase F — Minimal first-class CLI

• [CLI] 第一級CLIとJSON/MCP連携基盤を実装する #15 — first-class CLI / JSON

v0.1ではCLI全機能の完成を待たない。production executionを起動し、machine-readable outcome/diagnosticsを返し、#441のframe evidenceを保存/検証できる最小sliceを優先する。

CLIは既存Application/Core/Runtimeを再利用し、第二のruntime architectureを作らない。

Phase G — Dynamic / overlay code

• [Recompiler/Runtime] Support runtime-loaded overlays and dynamic code safely #249

static main EXE pathでoverlay/dynamic codeが実際のblockerになった時点で着手する。addressだけでなくcontent identityを基準にし、stale native mappingを実行しない。

Phase H — v0.1.0 title-screen evidence

• [v0.1.0] Persona title screen end-to-end verification gate #351 — Persona title-screen end-to-end verification gate

成功条件:

legal user input
  -> analysis
  -> recomp/runtime pipeline
  -> required BIOS/hardware services
  -> GPU/framebuffer
  -> deterministic captured title-screen frame
  -> CLI/headless reproducible evidence

fake screenshot、test-only shortcut、title-specific Core hackは不可。Avalonia/Studio game-frame presentationはv0.1後でもよい。

継続して守るcontract

• Interpreter / differential referenceを使い、recompiled semanticsの変更を比較可能にする
• unsupported behaviorを推測で実装せずfail closedにする
• deterministic IR / generated source / analysis/frame evidenceを維持する
• copyrighted ROM/ISO/EXEをGitへコミットしない
• title-specific workaroundをgeneric Core/Recompilerへ埋め込まない
• coverage percentageとcorrectness proofを混同しない
• CPU semanticsを複数経路で独立再実装しない
• CLI/GUIはApplication/Core/Runtime semanticsを共有し、別々のruntimeを持たない

この親Issueの完了条件

• Synthetic MIPS -> host-code Vertical Sliceが成立 ([Recompiler] Build and execute the first MIPS→host-code vertical slice #209)
• 最初のreal-ROM function differential proofが成立 ([Recompiler] Recompile and differentially validate the first real-ROM function #225)
• full-title execution orchestration基盤が存在する ([Runtime] No full-title execution orchestrator: recompiled guest cannot be driven through a complete CPU execution loop #366 / PR feat(execution): add full-title execution orchestrator #373)
• production execution composition rootが存在する ([Architecture] No production implementation of IRecompiledExecutionEngine exists — Studio cannot run a recompiled title #380 / ADR-015)
• real analyzed PS-X EXEをproduction execution pathへ投入できる ([Runtime] Connect analyzed real PS-X EXE input to the production title execution path #409 / PR feat(runtime): connect analyzed real PS-X EXE to production title execution path (#409) #425)
• real-ROM lowerable coverageをcandidate-selection biasなしで測定できる ([Analysis/Recompiler] Add real-ROM recompilation coverage analysis separate from proof candidate selection #410)
• observable effect / MMIO / runtime-transfer semanticsが明示される ([Recompiler/IR] Define observable side-effect semantics for MMIO, runtime transfers, and indirect control flow #411)
• 実タイトルbring-upで必要なBIOS/runtime/hardware gapがevidence-drivenに解消される
• CLI/headlessでproduction execution + machine-readable result + frame evidenceを再現できる ([CLI] 第一級CLIとJSON/MCP連携基盤を実装する #15/[Runtime/GPU] Implement minimal GPU rasterization and headless frame output for title-screen bring-up #441)
• [v0.1.0] Persona title screen end-to-end verification gate #351 のtitle-screen E2E gateへ到達する、または次の明確なrelease gateへRoadmapを更新する

Non-goals

• 最初から全MIPS I / 全PS1 hardwareを完成させること
• coverage percentageだけでcompatibilityを主張すること
• Persona固有コードをCoreへ追加すること
• dynamic overlay supportをstatic pathより先に完成させること
• v0.1 title-screen proofより先にStudio GUIを完成させること
• AI/GUI/Analyzer基盤拡張をRuntime/Recompilerの前進より優先すること

Related

• [v0.1.0] Persona title screen end-to-end verification gate #351 — Persona title-screen E2E gate
• [CLI] 第一級CLIとJSON/MCP連携基盤を実装する #15 — CLI / JSON / headless v0.1 entry point
• [Security] ChdReader/ChdHeader and Iso9660Reader allocate from untrusted length fields with no bound check #394 — disc-image parser hardening
• [Analysis/Recompiler] Add real-ROM recompilation coverage analysis separate from proof candidate selection #410 — real-ROM recompilation coverage analysis
• [Recompiler/IR] Define observable side-effect semantics for MMIO, runtime transfers, and indirect control flow #411 — IR observable-effect semantics
• [Analysis] Define deterministic real-ROM analysis report and snapshot format #215 — deterministic real-ROM report
• [Runtime/BIOS] Make BIOS-less execution the default via BIOS HLE #279 — BIOS-less execution / HLE
• [Guest Memory/DMA] Managed Dma MMIO layer is unreachable from any real execution path; scratchpad and RAM mirror unimplemented #386 — DMA/MMIO integration
• [Runtime/GPU] Define GPU MMIO register contract, GPUSTAT/GP0/GP1 model, and VRAM buffer (no rasterization) #440 — GPU register/VRAM substrate
• [Runtime/Scheduling] Implement CPU-cycle-driven device tick/IRQ scheduling contract (Timer/DMA/VBlank) #442 — Runtime scheduling/VBlank
• [Runtime/GPU] Implement minimal GPU rasterization and headless frame output for title-screen bring-up #441 — rasterization/headless frame evidence
• [Recompiler/Runtime] Support runtime-loaded overlays and dynamic code safely #249 — dynamic/overlay code

[mao2009]

Open-Issue triage snapshot — 2026-09-04

Repository-wide open-Issue review completed. Until #209 is Green, use the following priority model.

NOW — critical path to #209

1. [Recompiler] Implement MIPS→IR lowering for minimal instruction subset #207 — finish MIPS→IR Memory / Control Flow semantics
   • Phase 2A already implemented
   • remaining focus: load delay, delay-slot control flow, JAL/JALR/JR semantics, Interpreter cross-check
2. [Recompiler] Implement deterministic host code generation from Recompiler IR #208 — finish host backend/runtime-helper boundary
   • Phase 3A substantially implemented
   • remaining focus: fixed build/execute recipe, memory helpers, multi-block/control flow
3. [Recompiler] Add interpreter-vs-recompiled differential correctness harness #211 — Stage A differential harness
   • common fixture/state snapshot
   • generated-host executor
   • state diff + intentional-mismatch negative proof
4. [Recompiler] Build and execute the first MIPS→host-code vertical slice #209 — integrate Build → Execute → Diff and complete arithmetic + memory + control-flow vertical slice

NEXT — after #209

• [Recompiler] Recompile and differentially validate the first real-ROM function #225 — first real-ROM function differential proof
• [Analysis] Define deterministic real-ROM analysis report and snapshot format #215 — canonical deterministic real-ROM report/snapshot format
• [Recompiler/Runtime] Support runtime-loaded overlays and dynamic code safely #249 — overlays/dynamic code only after static function path is proven

DEFERRED by the #205 freeze

Do not prioritize these before #209 unless they remove a concrete #209 blocker:

• Analyzer / quality expansion: [Governance] Promote recurring review findings into SSOT, focused rules, and regression gates #23, [Security] Security Analyzer Architecture & Rule Specification #54–[Analyzer] Testability / Test Coverage Contract Analyzer #64, docs: Analyzer・品質ルール導入と段階的ルール強化のSkillを整備 #98, [Quality Gate 2] SonarAnalyzer.CSharp によるバグ・Code Smell品質ゲートの検証 #103, [Quality Gate 3] セキュリティAnalyzerの適用可否評価 #104, [Quality] Consolidate the analyzer / quality-gate stack and add new rules only from evidence #106
• AI Harness / development infrastructure: [AI Harness] Contract / Invariant Engine #65–[Development/Future] Add lightweight machine-readable change provenance only if GitHub evidence is insufficient #74, [Skills/Future] Keep repository Skills agent-agnostic; add a lightweight catalog/validation only when needed #81, [Future] 高性能モデルによるプロジェクト解析結果のKnowledge / Skill蒸留 #101, [Application] Game Analysis Agent Task / Context / Result Contract #134, test(batch): verify preflight and lifecycle conformance for the Markdown-only Batch protocol #167
• GUI / Studio expansion: [Studio Architecture] GUI / Application boundary and workflow foundation #40, docs(gui): establish GUI/UX architecture and design SSOT #75, [Studio] User-Driven Game Analysis & Recompilation Workflow #128, [Application] User-Driven Analysis Workspace & Unresolved Work Queue #133, [Test] Add critical GUI workflow automated tests #179
• AI/Studio integration: [AI/Development] README_AI.md によるAI開発向けプロジェクトコンテキストの整備 #31, [AI/Studio] Recomp時のAIゲーム解析とタイトル固有YAML生成・共有 #37, [AI Agent] Codex / Claude Code / API / Local AI Integration Architecture #41, [Studio] User-Driven Game Analysis & Recompilation Workflow #128, [Application] Game Analysis Agent Task / Context / Result Contract #134
• Compatibility / Feedback / Registry: [Compatibility] タイトル別 Compatibility Registry / 検証到達点を管理する #33–[Feedback] Compatibility到達点に応じたAdaptive Feedback Policy #35, [QA] Compatibility & Regression Testing #51, [Registry] Analysis Sharing / Registry Client Integration #52
• broader documentation/localization automation: [Documentation] READMEの国際化・多言語化とプロジェクト入口の整備 #36, [Docs/Automation] Adopt DataBoySu Readme Translator for automated README translation maintenance #120, [Docs] Migrate documentation SSOTs to English Canonical incrementally #122
• broader runtime/product architecture: [Disc] PS1ディスクイメージ抽象化とCHD/BIN+CUE/ISO対応 #10–[Logging] 構造化・詳細ロギングとTrace/Session IDを導入する #16, Add first-class internationalization and localization support #21, Support standard PS1 memory cards and interoperability with existing emulators #22, [Architecture] managed Infrastructure I/O / Adapter境界を現行AARC SSOTで整理する #38, [Project] Project / Workspace / Analysis Persistence #42–[Analysis] Title-specific Override / Patch Architecture #50, [Build] Enable cross-platform development and native test execution #80, [Architecture] Title-Agnostic / Multi-Region Recompilation Architecture #127
• process E2E hardening not blocking Recompiler work: test(e2e): Conflict scenario E2E verification for Merge Skill #153, test(integration): verify current Merge Skill safety and SHA-bound merge lifecycle #154, test(batch): verify preflight and lifecycle conformance for the Markdown-only Batch protocol #167

Responsibility clarifications

• [Recompiler] Add interpreter-vs-recompiled differential correctness harness #211 owns current Interpreter vs Recompiled differential work. [AI Harness] Differential Testing #67 is deferred as a broader generic differential-testing umbrella and must not duplicate [Recompiler] Add interpreter-vs-recompiled differential correctness harness #211.
• [Application] Game Analysis Agent Task / Context / Result Contract #134 supersedes the game-analysis protocol design work from closed [AI] Agent-Agnostic Recompilation Analysis Interface #129.
• [Recompiler/Runtime] Support runtime-loaded overlays and dynamic code safely #249 is explicitly not a [Recompiler] Build and execute the first MIPS→host-code vertical slice #209/[Recompiler] Recompile and differentially validate the first real-ROM function #225 prerequisite unless real reachable code proves otherwise.
• [Analysis] Define deterministic real-ROM analysis report and snapshot format #215's full public schema is not a [Recompiler] Build and execute the first MIPS→host-code vertical slice #209 blocker; use only the minimum provenance needed by [Recompiler] Recompile and differentially validate the first real-ROM function #225.

Closed during this triage

• [Architecture] loach.PureSharpによる純粋性ルールを導入する #9 — PureSharp adoption already delivered by PR feat: introduce PureSharp 0.1.6 quality rules #99
• [CI] Fix CodeRabbit review trigger from GitHub Actions bot comments #229 — CodeRabbit Review Gate already delivered by PR [CI] Add fail-closed CodeRabbit Review Gate (Issue #229) #230 and bootstrap/follow-up work
• [AI] Agent-Agnostic Recompilation Analysis Interface #129 — design scope concretized/superseded by [Application] Game Analysis Agent Task / Context / Result Contract #134
• [Research] Reference implementation gap analysis: psxrecomp / N64Recomp #248 — reference implementation gap analysis completed earlier in this triage session

Rule

If a proposed task is not in NOW, require evidence that it directly shortens #209 or removes a current blocker before promoting it ahead of the critical path.

[mao2009]

Roadmap checkpoint — synthetic vertical slice completed

The core synthetic Recompiler milestone chain has now reached a stable checkpoint on main:

• [Recompiler] Define Recompiler IR and CPU semantic contract #206 — IR / semantic contract: completed
• [Recompiler] Implement MIPS→IR lowering for minimal instruction subset #207 — MIPS→IR staged lowering: completed
• [Recompiler] Implement deterministic host code generation from Recompiler IR #208 — deterministic host code generation: completed
• [Recompiler] Build and execute the first MIPS→host-code vertical slice #209 — first complete synthetic MIPS→host vertical slice: completed
• [Recompiler] Add interpreter-vs-recompiled differential correctness harness #211 — differential correctness harness Stage A/B: completed

The immediate validation step is #266 (post-Phase 2A / post-integration smoke test), which is now unblocked.

After that checkpoint, #225 remains the next major Recompiler milestone: recompile and differentially validate the first selected real-ROM function. #215 supplies the relevant real-ROM provenance/snapshot work as needed, while broader runtime/overlay work such as #249 remains later-stage and is not a blocker for #225.

Keeping this parent roadmap Issue open because later roadmap phases remain intentionally unfinished.

[mao2009]

Roadmap status update — synthetic vertical slice complete

Current Recompiler milestone status:

• [Recompiler] Define Recompiler IR and CPU semantic contract #206 — IR / semantic contract: COMPLETED
• [Recompiler] Implement MIPS→IR lowering for minimal instruction subset #207 — MIPS → IR lowering: COMPLETED
• [Recompiler] Implement deterministic host code generation from Recompiler IR #208 — deterministic host code generation: COMPLETED
• [Recompiler] Build and execute the first MIPS→host-code vertical slice #209 — first executable synthetic vertical slice: COMPLETED
• [Recompiler] Add interpreter-vs-recompiled differential correctness harness #211 — differential correctness harness: COMPLETED
• test: run post-synthetic-vertical-slice integration smoke test #266 — post-synthetic-vertical-slice integration smoke checkpoint: COMPLETED with SMOKE_PASS_WITH_KNOWN_LIMITATIONS

#266 validated the current MIPS → IR → host C → build → bounded execution → interpreter diff path on main, including arithmetic, memory, unaligned access, load delay, control flow/delay slots, checkpoint traces, diagnostics, failure artifacts, and deterministic behavior.

The known boundary after the smoke checkpoint is that real-ROM-derived inputs are still analysis-stage inputs and are not yet wired into the recompiler differential/execution path. That is now the intended next milestone rather than a synthetic-pipeline blocker.

Current execution order

1. [Recompiler] Recompile and differentially validate the first real-ROM function #225 — first real-ROM function recompilation + differential validation — NEXT major Recompiler milestone
2. [Analysis] Define deterministic real-ROM analysis report and snapshot format #215 — deterministic real-ROM report/snapshot/provenance — provide the minimum selected-function identity/provenance needed by [Recompiler] Recompile and differentially validate the first real-ROM function #225 without blocking it on the complete reporting schema
3. test: RealRomAnalysis full-suite tests race on shared reports/real-rom and logs/real-rom paths #276 — RealRomAnalysis local-fixture test isolation race — follow-up found by test: run post-synthetic-vertical-slice integration smoke test #266; fix independently from Recompiler semantics
4. [Recompiler/Runtime] Support runtime-loaded overlays and dynamic code safely #249 — dynamic overlays / runtime-loaded code — post-[Recompiler] Recompile and differentially validate the first real-ROM function #225 future work; explicitly not a [Recompiler] Recompile and differentially validate the first real-ROM function #225 blocker

Until #225 is green, new Analyzer/AI Harness/GUI/registry expansions should remain secondary unless they directly unblock this real-ROM bridge.

[mao2009]

2026-09-16棚卸しで親Issueを現状へ更新しました。#209 synthetic Vertical Slice と #225 first real-ROM function proof は完了済みとして明示し、今後は #409 real executable→production execution、#410 coverage、#411 effect semantics、#279/#386 runtime/hardware、#351 title-screen gate を中心とするRoadmapへ再定義しています。