docs: add ecosystem fork watch ledger

2026-10-25 18:05:12 -04:00 · 2026-07-13 21:30:13 -07:00
parent dde268dc0f
commit 6aada214e8
2 changed files with 380 additions and 0 deletions
@@ -95,6 +95,11 @@ Known game repos:
 - [MegaManX6Recomp](https://github.com/mstan/MegaManX6Recomp) — *Mega Man X6*
 - [ApeEscapeRecomp](https://github.com/mstan/ApeEscapeRecomp) — *Ape Escape*

+Maintainers record evaluated external branches, game repos, exact revisions,
+and reusable upstream candidates in the
+[`ecosystem watch`](docs/ecosystem-watch.md). Check it before porting work from
+an older framework fork.
+
 ### Framework changes and the pin

 Because each game pins an exact framework commit (its `psxrecomp/` submodule
@@ -0,0 +1,375 @@
+# PSXRecomp ecosystem watch
+
+This is a recurring upstream/fork audit, not a merge queue. It records the
+exact external state that was inspected, separates reusable framework work from
+title-specific work, and prevents an old fork from silently replacing newer
+framework fixes.
+
+## Audit baseline and rules
+
+- Evaluated through `2026-07-13T21:25:28-07:00` (America/Los_Angeles), against `mstan/psxrecomp`
+  `master` at `dde268dc0fb9daf8fe6529f4aebfe80995350334` (committed
+  `2026-07-13T12:54:28-07:00`).
+- Investigation worktree: `audit/ecosystem-2026-07-13`.
+- This audit inspected diffs and history but did not import external code or
+  reproduce the contributors' game builds.
+- A candidate must be game-agnostic or explicitly configured by the game repo,
+  hardware-backed where it claims correctness, independently testable, and one
+  focused PR. Hard-coded title behavior, generated output, local paths, and
+  `printf`/log diagnostics do not belong in the framework.
+- Cherry-picking preserves the original author. If a change must be
+  reconstructed, use the contributor's exact `Co-authored-by` trailer and cite
+  the source PR and commit in the PR description.
+
+## Evaluation ledger
+
+Update a row whenever its source head changes. `Metadata only` means the source
+was discovered but its diff was not evaluated.
+
+| Source | Owner | Evaluated ref and commit | Commit time | Last evaluated | State |
+|---|---|---|---|---|---|
+| [PR #13: stb launcher and accumulated runtime work](https://github.com/mstan/psxrecomp/pull/13) | NyperYuhgard | `feat/launcher-stb-revamp` `812ce6f50c52c5c0fe86adf74ad302f3063b4f7f` | `2026-07-13T16:47:04-05:00` | `2026-07-13` | Fully inspected; split required |
+| [PR #14: WebAssembly and compatibility](https://github.com/mstan/psxrecomp/pull/14) | Kareem Olim (`kem0x`) | `agent/add-web-runtime-and-compatibility-fixes` `a99a8fc14e26be3c48806ca85f15068a2c6801ae` | `2026-07-14T04:30:04+03:00` | `2026-07-13` | Fully inspected; split required |
+| [PR #15: config-driven game tweaks](https://github.com/mstan/psxrecomp/pull/15) | `douglasjv` | `agent/game-tweak-framework` `31cdfb4f4dac305e98661dfdbf8e685533fd7ca4` | `2026-07-11T15:56:20Z` | `2026-07-13` | Fully inspected; see Douglas section |
+| [PR #16: SmackDown 2 framework changes](https://github.com/mstan/psxrecomp/pull/16) | Martin Penkava (`shaneomac1337`) | `smackdown2-fixes` `d05d14bb11caafad2963abe824f249249a80cb11` | `2026-07-12T19:16:19+02:00` | `2026-07-13` | Fully inspected; split required |
+| [douglasjv/mm8](https://github.com/douglasjv/mm8) | `douglasjv` | `main` `4eae0f952df9a527d18ff1916d373619fbb1a391` | `2026-07-13T21:28:50Z` | `2026-07-13` | Fully inspected; see Douglas section |
+| [douglasjv/r4](https://github.com/douglasjv/r4) | `douglasjv` | `main` `e4262718269879ef2e9b11e2fa428301082117b8` | `2026-07-13T15:22:57Z` | `2026-07-13` | Fully inspected; see Douglas section |
+| [douglasjv/psxrecomp-tweaks](https://github.com/douglasjv/psxrecomp-tweaks) | `douglasjv` | PR branch above; fork default `master` is `0cb2a77bff02e90f25d2791072a94b6ce73039f4` | `2026-07-09T20:50:09Z` | `2026-07-13` | Fully inspected; default branch is 59 commits behind baseline |
+| [wowjinxy/psxrecomp](https://github.com/wowjinxy/psxrecomp) | `wowjinxy` | `master` `46c664713c12cf719b3b5e44aa18eea63dca13af` | `2026-06-17T23:32:22Z` | `2026-07-13` | Metadata only; 8 ahead / 402 behind |
+| [seedlord/psxrecomp](https://github.com/seedlord/psxrecomp) | `seedlord` | `master` `4ea9ecd2a2d9db60d23e39091a53f12a2b2e751b` | `2026-06-12T22:29:02Z` | `2026-07-13` | Metadata only; 467 behind, no unique commits |
+| [chrisking1981/psxrecomp_kula_world](https://github.com/chrisking1981/psxrecomp_kula_world) | `chrisking1981` | `master` `80c33a8903c36df44d331b8a38ad64e591fd7b0a` | `2026-06-26T21:03:42Z` | `2026-07-13` | Metadata only; merged contribution branches already tracked in upstream PRs |
+| [Creesic/psxrecomp](https://github.com/Creesic/psxrecomp) | `Creesic` | `master` `3c2b87cb883d67db984fcabed30c5195f39ee3cd` | `2026-03-28T02:33:18Z` | `2026-07-13` | Metadata only; legacy history has no common ancestor with v4 |
+
+The fork comparison counts above are snapshots, not quality judgments. Old game
+repos are expected to pin old framework commits; the point is to avoid copying
+their whole framework back over current `master`.
+
+## Consolidated ecosystem gaps
+
+The strongest missing shared capabilities found in this pass are:
+
+1. Faithful CD-DA playback and CUE pregap/index behavior. Current master already
+   has multi-file CUE support, but not the complete Red Book playback path in
+   PR #14.
+2. A supported WebAssembly target: reproducible Emscripten toolchain, browser
+   audio, persistence/input shell, hosting requirements, and a diagnostic story.
+3. Declarative, opcode-verified game enhancement patches and typed widescreen
+   extension points, so title repos stop editing framework source.
+4. Cross-platform, source-only game-repo scaffolding with an exact framework pin
+   and repeatable extraction/regeneration steps.
+5. Renderer and SPU accuracy work that is presently being discovered during
+   individual game bring-up: exclusive triangle edges, complete primitive-size
+   rejection, SPU end/mute behavior, Gaussian interpolation, and reverb.
+6. A first-class downstream compatibility signal. A game repo currently pins a
+   commit, but there is no automated report saying how far behind it is, which
+   framework capabilities it carries locally, or whether its pin has a known
+   security/correctness supersession.
+
+## NyperYuhgard branch / PR #13
+
+Snapshot: 13 branch commits, 35 changed files, `+8,631/-1,914`; six current
+master commits are absent, the PR conflicts, and it has no checks. The PR body
+describes a three-commit launcher replacement, but the branch has since
+accumulated CD, SPU, overlay, recompiler, tooling, documentation, FPS, traps,
+and Crash Bash diagnostics.
+
+### Keep under review
+
+- The self-contained stb launcher removes RmlUi and adds persisted UI scaling.
+  It remains blocked by the missing GL loader and visual/layout review, as the PR
+  itself records. Continue on the existing branch only after those prerequisites
+  are explicit; do not use its runtime changes to justify merging the launcher.
+- `a39ab37` contains Linux shared-library overlay discovery, ABI preflight, and
+  cache loading work. Re-derive the smallest useful parts on top of master's
+  newer exact overlay dispatch (`b39387e`) and test save/load plus stale-cache
+  behavior.
+- `b49548e` adds an FPS counter and overlay status. Keep only product-facing
+  telemetry that uses the normal UI/debug surfaces.
+- `b24d685` adds runtime flag and debug-command indexes. Regenerate or verify
+  them against current master before a docs-only PR.
+- The dirty-text write path in `b07cb79` also marks the page dirty, closing a
+  plausible gap where native dispatch is blocked but interpreter dispatch never
+  activates. Isolate and oracle-test that few-line behavior.
+
+### Do not upstream as written
+
+- The branch's CD/multi-file reader is older than and superseded by master's
+  `5a2c6fd` implementation.
+- The simplified floating-point reverb is not a faithful PS1 SPU model.
+- Hard-coded Crash Bash write addresses, large `stderr` crash dumps, and local
+  log/watchpoint behavior conflict with the framework's game-agnostic and TCP
+  observability rules.
+- The recompiler additions accept branch-likely and `MOVN`/`MOVZ` instructions
+  that are not part of the PS1's MIPS I CPU, risking data being classified as
+  code. Its BC2T decoding also treats `rs=9` as BC2T; COP2 branches use the BC
+  format under `rs=8` with the condition in `rt`. This code needs a new ISA-led
+  design, not a transplant.
+- The shell build helpers are thin local conveniences rather than the
+  cross-platform documented build workflow.
+
+## Kem0x branch / PR #14
+
+Snapshot: 12 branch commits (10 feature commits and two upstream merges), 34
+files, `+1,991/-395`, clean against the audit baseline, but no reviews, CI
+checks, or added regression tests.
+
+### High-value isolated fixes
+
+- `dd9e5c6`: CD interrupt matching should test the encoded low interrupt bits
+  with `irq_enable & irq_flag`. This is a small hardware-backed correctness PR.
+- Generic subset of `b2597df`: an ADPCM END without REPEAT jumps to the repeat
+  address, sets ENDX/Release, and immediately mutes the envelope. Exclude the
+  Pepsiman duplicate-effect timing guard.
+- `91a654f`: exclusive bottom/right software-rasterizer edge coverage. Add
+  renderer regressions for winding, clipping, adjacent triangles,
+  semitransparency, and flat top/bottom cases.
+- CD-DA/pregap subset of `0e9df70`: layer 2,352-byte audio sector streaming,
+  track transitions, Play/GetlocP/autopause/DataEnd, and save-state coverage on
+  top of master's reader. The PR currently omits `cdda_data_end_pending` from
+  the serialized CD state.
+
+### Larger capabilities
+
+- `78128bf`, `9d8550c`, and `67207b4` establish an Emscripten pthread runtime,
+  WebAudio bridge, stable key mapping, and vblank-safe pause. Before calling it
+  supported, pin the toolchain, document a reproducible build and
+  cross-origin-isolated hosting, supply the browser persistence shell, revisit
+  the fixed 384 MiB/1 GiB memory policy, and retain useful diagnostics.
+- Generic portions of `ec889d6` explore subpixel projection provenance,
+  perspective-correct software texturing, and duplicate-frame presentation.
+  They instrument generated code and hot stores and must be separated into
+  experiments with performance and image-quality evidence.
+
+### Already superseded or title-specific
+
+- `01155a6` exact compiled ranges are absorbed and broadened by master's
+  `b39387e`; the head also drops a newer Crash Bash clean-text fallback. Never
+  merge the branch wholesale.
+- Hard-coded Pepsiman/SLPS-01762 RAM addresses, menu chord injection, lives,
+  level restart, and track-based controls belong in its game repo. The
+  `PEPSIMAN_SFX_RETRIGGER_GUARD` masks a timing issue and does not belong in the
+  shared SPU.
+
+## Martin Penkava branch / PR #16
+
+Snapshot: seven commits, 18 files, `+1,129/-96`, and six master commits behind.
+The game build was reported successful, but there are no checks and the generic
+BIOS-only framework link is reported failing.
+
+### Candidate work
+
+- `df4cc5c`: MSVC portability for bit scans, C linkage, and generated static
+  initializers. Validate generated BIOS and game units with MSVC plus the
+  existing GCC/Clang matrix.
+- The `s_active` guards from `e6809cc` are a small overlay-loader lifecycle fix.
+  The same commit's "decodable word above overlay floor" discovery fallback is
+  much riskier and needs independent proof; it can classify data as executable.
+- `cfc5d0e`: extend the PS1 1023x511 primitive-size rejection to every polygon,
+  quad half, line, and polyline path. Master has a partial triangle reject, so
+  port and test the missing coverage rather than replacing `gpu.c` wholesale.
+- Split Gaussian interpolation from reverb in `e069c8a`. Verify the 512-entry
+  table's provenance/licensing and compare both output and state transitions
+  with the in-tree Beetle oracle before import.
+- The Vulkan synchronization, staging-buffer reuse, coalesced submission, and
+  presentation work may be useful after the known AMD corruption is resolved.
+  Keep performance/synchronization fixes separate from CRT shaders and debug
+  environment flags.
+
+### Reject or relocate
+
+- `4517bd5` labels the AMD corruption unresolved and carries temporary Vulkan
+  diagnostics; it is not merge-ready.
+- The three batch scripts hard-code one contributor's Visual Studio and
+  `D:\tools` layout, and two directly regenerate SmackDown 2. They belong in a
+  game repo or should be replaced by parameterized build documentation.
+- The new shader describes itself as "CRT-Royale-inspired" while master already
+  has attributed CRT/composite/Trinitron color models. Establish exact
+  provenance and license, then evaluate a shader as a separate presentation
+  feature.
+
+## Douglas game repos and tweak framework
+
+### Revision shape
+
+Both game repos pin Douglas's framework fork as a submodule, and both pins are
+based on upstream `c94fcd5` rather than current master:
+
+| Game | Game head | Framework pin | Compared with audit baseline |
+|---|---|---|---|
+| Mega Man 8 | `4eae0f952df9a527d18ff1916d373619fbb1a391` | `3c316fc781ba645cca60125211299de0e879d770` | Pin has 16 unique commits; master has 6 absent commits |
+| R4: Ridge Racer Type 4 | `e4262718269879ef2e9b11e2fa428301082117b8` | `19233f496fe810fb57afc226b4ff4509c812bc8f` | Pin has 10 unique commits; master has 6 absent commits |
+
+Those six master commits include multi-file CUE support, exact native/static
+overlay dispatch, audio reserve/catch-up hardening, release hygiene, and analog
+stick/D-pad decoupling. Every port must start from `dde268dc`; neither game pin
+is a safe integration base.
+
+### Reusable game-project pattern
+
+The repos are good source-only title skeletons: top-level CMake using
+`psxrecomp_add_runtime_target`, a minimal seed, typed `game.toml`, exact
+framework pin, CHD/PS-X EXE extraction, macOS prerequisites/build helpers,
+research notes, and aggressive ignores for discs, BIOS, generated output,
+caches, and runtime state. Neither has CI.
+
+That repeated structure is evidence for an official game-project template or
+scaffolder with standardized extract, configure, build, pin-status, and smoke
+test jobs. Reimplement the workflow in a licensed upstream template; do not
+copy the standalone repos' unlicensed scripts.
+
+### Mega Man 8 findings
+
+- The source-only project targets SLUS-00453. Its title-owned config uses
+  reachable discovery, a verified smaller analysis bound, full-2D native wide,
+  a scene-word gate, packet-proven HUD range, three background-2D sites, and a
+  ring-refill option. Addresses, hashes, state gates, and policy stay in `mm8`.
+- Its baseline notes report that whole-image discovery grew from 1,975
+  candidates to 6,815 entries, 5.4 million C lines, and 176 MiB of generated C,
+  while reachable discovery produced 132 entries and roughly 87,000 lines.
+  That is strong motivation for a bounded/reachable discovery API.
+- The documented real-disc/headless Debug run reached controllable opening-stage
+  play for 17,425 consecutive frames with no unknown dispatch; Release linked.
+  The repo correctly rejected a guessed 60 FPS patch after motion/timing
+  evidence contradicted it. This is useful integration evidence, but no CI
+  reproduces it.
+- Framework pin `3c316fc` extends existing background-2D support with a gameplay
+  RAM gate, ring-refill/signed-column behavior, interpreter parity, and SLJIT
+  decline for affected fragments. Upstream only generic typed pieces and test
+  4:3 identity plus mutated opcodes; do not import the MM8 addresses.
+
+### R4 findings
+
+- The source-only project targets SLUS-00797. Its title config owns race callback
+  split addresses, projection squash, cull widening, hybrid analog, and exact
+  polygon/HUD packet sources. `game-android.toml` selects a reduced software
+  rendering profile.
+- The repo records 2,982 strict functions, Apple Silicon Release linking, real
+  LLE boot/attract, GL 4.1, 60 simulation steps and 60 unique frames in two
+  seconds, correct wall-clock timers, and live analog bytes. Fourteen HUD
+  evidence PNGs are tracked. Android build/install material exists, but there
+  is no documented device result.
+- Commit `0f10098` adds configurable polygon/line HUD regions guarded by packet
+  source, bounds, and pivot. It is inert unless configured and has unusually
+  concrete visual evidence; it is a good standalone typed extension after
+  parser, bounds, and default-identity tests.
+- Commit `7abbfdf` mixes a generic frame-split callback mechanism with POSIX
+  overlay loading, interpreter-page controls, and SPU CD-capture/IRQ changes.
+  The frame split is promising but high-risk: review save/reset state, nested
+  callbacks, interrupts, cycles, audio, and replay before a design branch.
+- The same ancestry supplies the missing POSIX cache scan and manifest-driven
+  `dlsym(func_%08X)` registration. Current master still logs that POSIX export
+  scanning is TODO. Rebase this narrowly onto the current loader, validate both
+  address and CRC, ABI cleanup, rescan, and handle lifetime on Linux and macOS.
+- Android support adds an arm64 SDLActivity target, app-private paths, software
+  renderer stubs, AArch64 fiber context switching, and raw SDK/NDK packaging.
+  It is API-26/arm64/debug-only, clones SDL during build, exports the activity,
+  and lacks controller/audio/suspend/device evidence. Treat it as an experiment,
+  splitting runtime portability from APK tooling.
+
+### PR #15 findings
+
+PR #15 is six commits, 23 files, `+644/-25`; current master has nine unique
+commits not in it. A synthetic merge was clean, but the PR has no checks or
+automated tests. It introduces three useful inert-by-default configuration
+families:
+
+1. `[[recompiler.patch]]`: named address/expected/replacement patches with
+   duplicate checks, fatal main-EXE mismatch, and guarded overlay variants.
+2. `[[widescreen.signed_x_bound]]`: signed Q16 gameplay bounds wired through
+   static generation, captured overlays, SLJIT, and the interpreter.
+3. Typed textured-edge expansion/full mirror options for finite arena and
+   background geometry.
+
+It also bundles macOS GL 3.3 core context setup, CPU-copied overlay discovery,
+analog debug injection/observability, client commands, and a thorough
+`GAME_TWEAKS.md`. The overall architectural direction is strong: exact guest
+instruction changes remain game data, typed framework behavior is off by
+default, and the shared code contains no title addresses.
+
+Fix these before proposing merge:
+
+- Software rendering treats the textured-edge return code as a boolean and
+  stretches the whole primitive, unlike the GL-specific outside-edge meaning.
+- Runtime signed-bound registration silently truncates after 64 sites while
+  codegen accepts more, allowing backend divergence.
+- Signed-bound scaling includes cull-guard pixels through
+  `psx_ws_x_margin()`, coupling a gameplay bound to renderer safety margin.
+- Treating every dispatch above `g_overlay_region_floor` as dirty is broad and
+  can turn data targets into interpreter candidates.
+- Loading the same config through `--config` and `--ws-config` can append
+  duplicates without cross-source validation; address alias semantics and the
+  linear per-instruction patch lookup also need definition.
+- Split patches, signed bounds, textured edges, platform GL, overlay discovery,
+  debug input, and final docs into focused reviews.
+
+PR #15's public body reports AppleClang/Ninja, Tobal generation/runtime link,
+Einhander regeneration/frame tests, and Mega Man Legends generation/link/boot.
+No attached checks or artifacts independently reproduce those claims. MM8 and
+R4 descend from the PR but do not currently consume its guarded-patch,
+signed-bound, or textured-edge entries; they instead demonstrate that the typed
+profile pattern is continuing to grow.
+
+## Proposed upstream branch queue
+
+No implementation branch has been created yet. The first wave below is small,
+hardware-backed, and suitable for maintainer approval before code is moved.
+
+| Priority | Proposed branch | Source credit | Scope / gate |
+|---|---|---|---|
+| 1 | `fix/cdrom-encoded-interrupts-kem0x` | Kareem Olim, `dd9e5c6` | CD IRQ encoding; PSX-SPX + focused tests |
+| 1 | `fix/spu-end-mute-kem0x` | Kareem Olim, subset of `b2597df` | Generic END/mute only; Beetle comparison |
+| 1 | `fix/overlay-init-guard-shaneomac` | Martin Penkava, subset of `e6809cc` | Lifecycle guards only; boot/save/load regressions |
+| 1 | `fix/msvc-generated-init-shaneomac` | Martin Penkava, `df4cc5c` | MSVC portability; three-compiler build evidence |
+| 1 | `fix/posix-overlay-export-scan-douglas` | Douglas, portions of `df7d1fa`/`7abbfdf` | Linux/macOS overlay loading on current ABI/cache code |
+| 1 | `feat/config-guarded-mips-patches-douglas` | Douglas, `19001c0` | Opcode-verified game-owned data; parser/codegen tests |
+| 1 | `feat/reachable-main-discovery-douglas` | Douglas, `8415f3a` | Bounded/reachable discovery; indirect-target safety |
+| 2 | `fix/sw-raster-exclusive-edges-kem0x` | Kareem Olim, `91a654f` | Edge rules; image/oracle suite |
+| 2 | `fix/gpu-primitive-size-reject-shaneomac` | Martin Penkava, `cfc5d0e` | Complete existing partial hardware rule |
+| 2 | `fix/dirty-text-page-mark-nyper` | NyperYuhgard, subset of `b07cb79` | Dirty/native dispatch invariant; no Crash Bash logging |
+| 2 | `feat/cdda-playback-kem0x` | Kareem Olim, subset of `0e9df70` | Extend master's CUE reader; save-state and track tests |
+| 2 | `feat/widescreen-hud-regions-douglas` | Douglas, `0f10098` | Typed polygon/line HUD regions; GL/SW identity tests |
+| 2 | `feat/widescreen-signed-bounds-douglas` | Douglas, `f44f365` | Remove 64-site/cull-margin hazards; all backend tests |
+| 2 | `fix/macos-core-gl-context-douglas` | Douglas, subset of `df7d1fa` | Context setup only; macOS launcher/game smoke tests |
+| 3 | `feat/web-runtime-core-kem0x` | Kareem Olim, `78128bf` | Reproducible platform target, no title hooks |
+| 3 | `feat/web-runtime-controls-kem0x` | Kareem Olim, generic web-control commits | Keybind/pause API and persistence contract |
+| 3 | `feat/game-project-template` | Douglas-inspired workflow | New licensed template/scaffolder; pin-status + CI |
+| Hold | Existing `feat/launcher-stb-revamp` | NyperYuhgard | First solve GL loading and visual acceptance |
+| Hold | `exp/vulkan-frame-delivery-shaneomac` | Martin Penkava | Only after AMD corruption and provenance gates |
+| Design | `design/runtime-frame-split-douglas` | Douglas, generic subset of `7abbfdf` | State/cycle/audio/replay design before code PR |
+| Experiment | `exp/android-runtime-douglas` | Douglas, `19233f4`/`6238330` | Separate runtime from packaging; on-device gates |
+
+## Attribution and licensing checklist
+
+| Contributor | Exact author identity to preserve |
+|---|---|
+| NyperYuhgard | `NyperYuhgard <93950153+NyperYuhgard@users.noreply.github.com>` |
+| Kareem Olim | `Kareem Olim <kareemolim@gmail.com>` |
+| Martin Penkava | `Martin Penkava <mpenkava1337@gmail.com>` |
+| Douglas | `douglasjv <vanderveerdouglas@gmail.com>` |
+
+- Prefer a clean cherry-pick when a whole source commit is acceptable. For a
+  subset/reimplementation, add the exact human contributor as co-author and
+  cite the original commit/PR. Preserve any existing co-author trailers too.
+- The contribution guide says submitted contributions use PSXRecomp's
+  PolyForm Noncommercial license. Standalone `mm8` and `r4` currently declare
+  no repository license, so do not copy fork-only material from them without
+  an upstream PR or explicit permission/licensing confirmation from Douglas.
+- Resolve third-party provenance before moving tables, shaders, emulator-derived
+  algorithms, or copied constants. Attribution is required even when the final
+  implementation is license-compatible.
+
+## Repeat-audit procedure
+
+1. Record the current upstream baseline SHA and local audit time.
+2. Resolve each tracked ref's current SHA. If unchanged, update nothing except
+   an explicit recheck date when needed.
+3. Compare from the fork's true merge base and separately compare its pinned
+   framework commit with current master. Do not treat a submodule as local game
+   code.
+4. Classify deltas as shared correctness, opt-in framework capability,
+   game-owned configuration/tooling, generated/artifact content, superseded
+   work, or policy/provenance risk.
+5. Verify claimed correctness against PSX-SPX, in-tree Beetle, hardware tests,
+   or another independent source. A successful game build is integration
+   evidence, not hardware proof.
+6. Update this ledger before proposing or creating focused branches.