Last updated: 2026-05-20

# STATE

## Project Identity
POPSLoader is a PS2 launcher for POPStarter built on Enceladus runtime pieces, with behavior primarily orchestrated by embedded Lua modules (`system.lua`, `ui.lua`, `images.lua`, `pops_profiles.lua`).

`QA_REGRESSION_MATRIX.md` is the detailed run ledger. This file summarizes the stable current repo state and the latest materially relevant hardware outcomes.

## Repo-Verified Runtime State
- Boot/runtime uses embedded Lua scripts.
- `bin/POPSLDR/IMG/default.png` is optional for GitHub Actions artifact builds; if it is absent, `IMG.default` falls back to the required embedded `MISSING.png` asset.
- Settings are persisted at `mc0:/POPSTARTER/.pldrs`.
- Settings edits are staged and committed on Settings/Profile confirm/leave.
- Persisted settings include:
  - POPSTARTER path,
  - DKWDRV path,
  - video standard,
  - hide-text mode,
  - keyboard layout,
  - BDMA mode.
- Startup backend auto-init exists and uses:
  - boot path information,
  - configured executable paths,
  - selected profile path.
- HDD startup targets now run the same `PLDR.LoadHDDModules()` path used by the HDD page instead of only the lower-level exec helper.
- USB vs MX4SIO split is based on mount-driver identity, not path-prefix guessing.
- Runtime device access is not gated by the old device-lock system.
- Main menu can show a boot-device label.
- Exit modal exposes:
  - `OSDSYS`
  - `Cancel`
  - `BOOT.ELF`
- `BOOT.ELF` lookup order is:
  - `mc0:/BOOT/BOOT.ELF`
  - `mc1:/BOOT/BOOT.ELF`
- Current cover sources are:
  - sidecar PNG next to the selected `.VCD`,
  - `hdd0:__common/POPS/ART/<title>.png` for HDD titles.
- Release packaging policy in CI is `PS1_POPSLOADER/*` + `POPS/PATCH_5.BIN` with strict manifest validation.
- Current CI package also includes `PS1_POPSLOADER/BUILD_INFO.txt`, and the build/package workflow fails if the built ELF is missing key embedded runtime markers or if the generated embedded-loader blob was not regenerated.
- Repository automation also includes `.github/workflows/opencode.yml`, a comment-triggered AI-assistance workflow; it is not part of the build/package validation contract.

## Potential Settings/Path Integrity Risks
- Repo-verified: `bin/POPSLDR/ui.lua` stages the Settings/Profile POPSTARTER path editor draft and now carries an explicit POPSTARTER mode into `PLDR.CommitSettingsChanges()`: manual path edits use `CUSTOM`, while explicit profile/default selection uses `PROFILE_DEFAULT`.
- Repo-verified: `bin/POPSLDR/system.lua` `CommitSettingsChanges()` normalizes the incoming `popstarter_mode`, applies the normalized state, and then `EncodeSettings()` persists `POPSTARTER_MODE=<mode>` plus `POPSTARTER_PATH=<path>`; when the normalized mode is profile-default, `EncodeSettings()` intentionally writes an empty `POPSTARTER_PATH` and relies on the selected profile path at load time.
- Hardware status: the settings/path mode correction is source-verified only until a memory-card `.pldrs` write plus reboot/load cycle is recorded in `QA_REGRESSION_MATRIX.md`; it is not a hardware claim for HDD-backed ELF execution.
- Scope guard: this potential settings/path integrity risk is not claimed as the cause of `D-10`, `D-14`, or `U-10`; those remain tracked through the detailed hardware chronology in `QA_REGRESSION_MATRIX.md` and the decision notes in `DECISIONS.md`.

## Main Menu Feature Status
- `MMCE`: implemented in code.
- `MX4SIO`: implemented in code.
- `HDD (PFS)`: implemented in code.
- `USB`: implemented in code.
- `Disc (DKWDRV)`: implemented in code.
- `HDD (exFAT)`: not implemented.
- `SMB (v1)`: not implemented.
- `ILINK`: not implemented.

## Reported Hardware Status
- Shared default/Profile 1 local POPSTARTER baseline:
  - 2026-03-27 hardware report initially failed with `Cant find POPSTARTER ELF` when booted from USB with USB `POPSTARTER.ELF` sidecar/cwd/Profile 1.
  - comparison against `BETA-10-play-CHECKPOINT2` showed that branch's shared POPSTARTER resolution path worked without the later unverified common-path resolver/settings changes.
  - current source was rolled back to the checkpoint branch's shared resolver behavior for this path.
  - user confirmed that rolled-back source restored the shared baseline on hardware.
- `U-05` OSDSYS exit:
  - reported fixed on hardware.
- `D-12` startup backend auto-init:
  - a 2026-03-27 hardware report said booting from HDD did not auto-init the HDD driver stack.
  - current source now routes HDD startup targets through `PLDR.LoadHDDModules()` instead of only `EnsureHddRuntimeReadyForExec()`.
  - current source now keeps that startup HDD path limited to runtime readiness; it no longer scans HDD POPS partitions or builds the HDD game list during boot.
  - HDD page entry still performs the partition scan and game-list build, and optional HDD cache writing now reuses the page-built list instead of rebuilding at startup.
  - user previously confirmed the earlier HDD startup auto-init correction on hardware, but later 2026-03-28 reports on the narrowed boot-time split sources said HDD-backed startup/Profile POPSTARTER could still not be found after entering the USB page before the HDD page.
  - the raw boot `APP_DIR` fallback alone did not restore that case.
  - current source now also pre-resolves any HDD-backed startup/configured exec paths immediately after `PLDR.LoadHDDModules()` so HDD POPSTARTER/Profile paths are mounted and recorded without reintroducing HDD page work at boot.
  - current source also routes on-demand HDD path mounts through `PLDR.LoadHDDModules()` instead of only the lower-level `EnsureHddRuntimeReadyForExec()` gate, so HDD POPSTARTER/Profile probes from USB or other pages use the same runtime init path as HDD page entry.
  - current source also fixes the startup warm-path classification for Profile 1/default relative `POPSTARTER.ELF`, which had previously been skipped because only explicit `hdd:` / `pfs:` paths were being marked for HDD warm-up.
  - because `etc/boot.lua` establishes HDD boot on a dedicated `pfs1:` mount before `system.lua` runs, current source now also carries that exact boot partition/slot metadata into `system.lua`, seeds the HDD mount tracker from it, and rebuilds HDD sidecar/partition context from mounted `pfs1:` candidates instead of relying only on later rediscovery.
  - user later confirmed on 2026-03-28 that the exact-boot-mount/source-context source restored the USB-before-HDD-page startup/Profile repro on hardware.
  - latest recorded hardware on this line is therefore `PASS`; preserve that behavior through further `D-10` work.
- `D-16` first-entry USB backend discovery:
  - a 2026-03-27 hardware report said the first USB page entry reported no backend, but backing out and re-entering then worked.
  - current source now adds a bounded wait between failed USB root probes in `BuildUsbIdentityDeferred()`.
  - MX4SIO discovery code was not changed by this correction.
  - user later confirmed that corrected source fixed the first-entry USB issue on hardware.
- `D-10` HDD POPSTARTER on HDD:
  - reported failing on hardware.
  - repro: boot from HDD, launch HDD title with HDD `POPSTARTER.ELF` sidecar/CWD.
  - result: black-screen hang.
  - 2026-03-27 re-test of the current source still failed when booted from HDD with default/Profile 1/cwd/sidecar `POPSTARTER.ELF` on HDD and game device HDD.
  - current source also exposes an `R2` alternate HDD launch path for HDD-resident `POPSTARTER.ELF` that swaps only the selector contract to `hdd0:PART:pfs0:/GAME.ELF`.
  - later 2026-03-27 experimental sources also black-screened after direct-load, Memory Card staging, and stripped-handoff changes.
  - user later confirmed on 2026-03-28 that the narrowed source restored `D-15`, so this remaining blocker is again isolated to HDD-backed `POPSTARTER.ELF`.
  - a later 2026-03-28 re-test still black-screened on the narrowed Lua-side HDD-backed source with no visible positive change.
  - a later 2026-03-28 re-test on the loader-side no-auto-exec-slot-preserve source still black-screened on both `X` and `R2`.
  - a later 2026-03-28 re-test on the forced-`reboot_iop = 1` source still black-screened on both `X` and `R2`.
  - a later 2026-03-28 re-test on the direct-`hdd0:PART:pfsN:/POPSTARTER.ELF` preference source still black-screened on `X`.
  - a later 2026-03-28 re-test on the mounted-`pfs0:` embedded-loader source still black-screened on `X`.
  - follow-up repo comparison showed that earlier source-context work had still been incomplete because Lua had usually already normalized HDD POPSTARTER to mounted `pfs1:` / `pfs3:` paths before the reboot loader saw it.
  - a later 2026-03-28 re-test on that exact-boot-mount/source-context source still black-screened on `X`.
  - current source now replaces the earlier ad hoc HDD source-context reboot handoff with an explicit partition-aware contract across Lua, `src/luasystem.cpp`, `src/elf_loader/src/elf.c`, and the embedded loader.
  - on that contract, the parent passes exact HDD partition context separately from the mounted load path, normalizes the partition-aware exec filename to generic `pfs:/...`, remounts `pfs0:` from that partition while reusing the mounted relpath Lua already resolved, and no longer preserves the old tracked `pfsN:` mount into exec.
  - a 2026-03-29 `D-10` run on the prior partition-aware source no longer black-screened, but the launcher regained control with `rc=-1 (returned after 22618 ms)`, which narrowed the remaining failure to the embedded-loader or target-`ExecPS2` handoff instead of HDD path discovery on that specific artifact.
  - a later 2026-03-29 GitHub artifact re-test on that broader partition-aware/current-source line black-screened again, so the returned-rc boundary is not yet stable enough to treat as the new steady state.
  - current source also reports the actual exec filename separately from the probed/opened POPSTARTER path in the launcher popup so mounted-slot probe paths do not masquerade as the real load target.
  - current source now restores more of the original parent-side embedded-loader jump contract in `src/elf_loader/src/elf.c`: BRAM wipe plus `SifInitRpc`/`SifLoadFileInit`/`SifLoadFileExit` before the copy, and `SifExitIopHeap`/`SifExitRpc`/`SifExitCmd` before the final `ExecPS2`.
  - current source also returns the actual embedded-loader `ExecPS2` result instead of collapsing it to `-1`, keeps legacy `System.loadELF(path, reboot_iop, selector)` on POPSTARTER's normal one-argument selector contract, routes partition-aware HDD launches through the explicit `System.loadELFWithPartition(path, reboot_iop, partition_context, selector)` API and mounted-`pfs0:` `SifLoadElf` in the embedded loader so they match the reference loaders more closely once the parent has already remounted the target partition, normalizes stale canonical profile-path state so Profile 1/default no longer silently keeps another profile's HDD path, and keeps the older iomanX-aware `fileXio` load path only as the fallback for direct `pfs:` / `hdd:` loads with no HDD partition context.
  - 2026-05-19 source audit found remaining handoff defects before new hardware retests: Lua mounted-PFS fallback can leave stale launch context, normal HDD game labels can fail fallback partition parsing, the fallback path can skip the pre-exec gate even when reconstruction failed, `System.loadELF(..., args..., partition_context)` can leak the partition context into target argv, and the child loader still uses `snprintf`/`strncat` despite older docs claiming that risk was avoided. See `HDD_POPSTARTER_HANDOFF.md`.
  - 2026-05-19 source change addresses the audit defects (excluding child-loader `snprintf` cleanup which would require regenerating the embedded loader blob): `ResolveFallbackMountedPfsExecPath` now accepts bare partition labels via `NormalizeHddPartitionLabelForMount`, `RunPOPStarterGame` syncs `context.exec_path`/`exec_partition_context`/`exec_*_slot`/`cold_external_launch`/`keep_hdd_slots*` and `launch_diagnostics` after a successful fallback, the HDD pre-exec gate is skipped only when the fallback actually reconstructed a path, `src/luasystem.cpp` exposes a dedicated `System.loadELFWithPartition(path, reboot_iop, partition_context, args...)` binding instead of overloading `System.loadELF` with a trailing partition_context (the trailing detection was removed so partition_context can no longer leak into target argv), `LaunchEngine` calls the new binding when `context.exec_partition_context` is set, and `ExecuteViaEmbeddedLoader` no longer rejects `argc == 0` so the child loader's documented default-argv synthesis is reachable. The POPSTARTER-specific `argv[0]` guard in `ExecuteHddBackedViaEmbeddedLoader` is unchanged.
  - 2026-05-20 hardware screenshot from the latest `BETA-12-PLAY` artifact returned to the launcher with `POPSTARTER HDD pre-exec gate failed: Cannot resolve HDD partition context` for `POP:pfs3:/POPS/POPSTARTER.ELF` and `APP:hdd0:+OPL:pfs:/APPS/PS1_POPSLOADER/`.
  - 2026-05-20 source follow-up keeps the selector `argv[0]` contract unchanged, fixes argument-shifted failure-popup route/gate diagnostics, lets Lua parse `hdd0:PART:` partition-context strings, allows safe bare HDD partition labels in the shared recovery candidate builder, and makes mounted-PFS fallback recover the actual POPSTARTER source partition before falling back to the selected HDD game partition.
  - a later readable 2026-05-20 screenshot showed the next pre-exec gate failure: the gate checked generic `pfs:/POPS/POPSTARTER.ELF` even though the real mounted path was `pfs3:/POPS/POPSTARTER.ELF`. Current source now probes a real mounted path in the gate while preserving the generic exec path for the partition-aware C loader.
  - current source now makes that partition-aware path non-default for normal HDD-backed POPSTARTER attempts. Normal `X` uses the real resolved executable path, clears Lua partition context, skips the Lua HDD pre-exec gate/remount fallback, and calls the direct non-reboot legacy `System.loadELF(path, 0, selector)` contract.
  - after the direct non-reboot artifact still black-screened before POPSTARTER debug screens, current source removes the HDD-only parent cleanup immediately before `ExecPS2` in `LoadELFFromFileExecPS2()` so the direct HDD handoff no longer exits SIF heap/RPC/CMD or unmounts PFS slots differently from the working non-HDD POPSTARTER path.
  - latest recorded hardware result on this `D-10` line is still FAIL on the previous artifact; the 2026-05-20 source follow-up is repo-verified only and `D-10` remains `Unknown (verify on hardware)` for the next artifact.
- `D-14` HDD-backed POPSTARTER with non-HDD game:
  - reported failing on hardware.
  - repro: launch a non-HDD title while `POPSTARTER.ELF` itself is configured on HDD.
  - 2026-03-27 user hardware also black-screened when launching a USB game with Profile 2 pointing `POPSTARTER.ELF` to HDD.
  - the user later clarified that the other same-day 2026-03-28 success report referred to `D-15`, not this case.
  - a later 2026-03-28 re-test on the forced-`reboot_iop = 1` source still black-screened on `X`; `R2` produced no response in that non-HDD-game repro.
  - a later 2026-03-28 re-test on the direct-`hdd0:PART:pfsN:/POPSTARTER.ELF` preference source still black-screened on `X`.
  - current source now uses the same partition-aware HDD reboot contract as `D-10`, rather than the earlier ad hoc source-context handoff or whichever mounted `pfsN:` path Lua happened to resolve first.
  - latest recorded hardware remains `FAIL`; current exact-line result is still `Unknown (verify on hardware)`.
- `D-15` HDD game with non-HDD sidecar POPSTARTER:
  - reported as a regression on hardware.
  - repro: boot from a non-HDD device with sidecar `POPSTARTER.ELF` on that same device, then launch an HDD title.
  - 2026-03-27 user hardware reported a black screen on the EE-side HDD direct-load attempt.
  - a later 2026-03-27 hardware report also black-screened on the broader stripped-handoff HDD-game path.
  - current source now removes Lua-side HDD game pre-mount/CWD preservation from this path and passes only the normal selector handoff unless `POPSTARTER.ELF` itself is HDD/PFS-backed.
  - user later confirmed on 2026-03-28 that USB boot + USB sidecar/cwd `POPSTARTER.ELF` + HDD game passes on hardware.
  - user reported a 2026-05-20 latest-artifact regression: USB boot with USB sidecar/cwd `POPSTARTER.ELF`, then launching an HDD title, black-screened.
  - current source follow-up restores legacy `System.loadELF(path, reboot_iop, selector)` one-argument selector behavior for normal/non-HDD POPSTARTER launches and keeps partition context on the explicit HDD API; hardware result is `Unknown (verify on hardware)`.
  - user then reported the narrowed default/cwd sidecar failure: explicit `mass:/POPS/POPSTARTER.ELF` launches, but default `POPSTARTER.ELF` can stop at `Cant find POPSTARTER ELF`. Current source expands default sidecar lookup to include the live current directory plus boot/app directories; hardware result is `Unknown (verify on hardware)`.
- `U-10` BOOT.ELF after HDD page init:
  - one prior artifact was reported good,
  - repo history shows the BOOT.ELF modal later moved from its older non-reboot direct `System.loadELF(elf_path, 0, elf_path)` path to a reboot-I/O path with launch-CWD setup.
  - a later 2026-03-29 hardware report said BOOT.ELF still behaved incorrectly after HDD runtime had been initialized.
  - current working inference is that `U-10` may share the same underlying handoff/state-poisoning boundary as `D-10`, but that remains unproven and `U-10` still requires separate hardware confirmation.
  - current source now keeps the no-launch-CWD rollback, re-enables `reboot_iop = 1` for BOOT.ELF only when HDD runtime has already been loaded, and uses a BOOT.ELF-specific cold external-launch prep that clears the exec keep mask and unmounts tracked HDD slots instead of preserving boot PFS state.
  - current-source hardware status on this conditional-reboot/cold-prep line is `Unknown (verify on hardware)`.
- `U-06` PAL asset aspect:
  - current code compensates for PAL UI layout,
  - hardware result is still `Unknown (verify on hardware)`.

## Known Open Work
- Preserve the reported `D-12` HDD startup auto-init fix while iterating on HDD launch-path regressions.
- Preserve the dedicated HDD boot `pfs1:` mount contract from `etc/boot.lua` while iterating on startup/Profile resolution.
- Preserve the reported `D-16` USB first-entry fix and confirm MX4SIO behavior remains unchanged on future retests.
- Resolve HDD-backed `POPSTARTER.ELF` handoff when POPSTARTER itself is on HDD, including non-HDD game launches.
- Preserve the restored `D-15` path where HDD titles launch correctly when POPSTARTER stays on the non-HDD boot device.
- Re-verify `BOOT.ELF` after HDD page init on current source.
- Record concrete run logs in `QA_REGRESSION_MATRIX.md`.
- Implement HDD exFAT menu flow.
- Implement SMB menu flow.
- Implement ILINK menu flow.
- Decide whether a broader ART system is still needed beyond current sidecar/HDD-common cover support.

## Verification Status
- Code/build/package statements above are repository-verified.
- Hardware behavior is `Unknown (verify on hardware)` unless explicitly recorded as a reported result.
