Design decisions

← POPSLoader docs · view on GitHub ↗

Last updated: 2026-07-13 (R3Z3N settings-review round 2 — profiles system dropped, START settings menu, region-native confirm button, keyboard rework; see the entry at the top of the log. Earlier: the 1.0.0 release + dev rename; the 2026-07-09 feature wave — Adaptive BDMA semantics, partition-installed games gated on the IMAGE0.VCD probe, the 22.05 kHz boot-chime re-encode; the 2026-07-07 full-repo audit fix waves; selectable cover/details folder (ART_LOCATION), default SMB port 1111, MX4SIO enumeration settle restore; POPSTARTER resolution reorder; exFAT/ATA isolation; frame-counted nav/desc-scroll, analog-fold gate, layered cover art, OPL-style overscan, boot-sound toggle, HDD (exFAT)/BDMA-ATA backend, µs-as-ms timer sweep). Released line: 1.0.1 (2026-07-13; previously 1.0.0 2026-07-10); active dev / rolling branch dev. Shared volatile facts (Known Issues, Preservation Contracts, Settings behavior, Invariants, Hardware Status) live in STATE.md — this log records the decisions, not the current-state snapshot. The current experimental goal state (device-layer rebuild, cover art, defaults) is STATE.md's Experimental channel (EXP32–EXP34) section; entries below that predate it are historical.

DECISIONS

Decision Log Format

Each entry records:
- Date (YYYY-MM-DD)
- Decision
- Rationale
- Implications
- Evidence

Decision Log

2026-07-15 — R3Z3N review round 3: footers advertise less, Credits into Settings, one save menu

• Decision: act on R3Z3N's PCSX2 pass (seconded by Berion on the buttons). (1) Footers carry the primary action plus the way out and nothing else: main menu = Select/Settings/Exit, game list = Launch/Back, Settings drops Hide Text. The bindings are untouched — Square still toggles cover art, START still opens Settings — only the legend clutter goes. (2) Credits moves into Settings (new About section) and the Triangle->Credits binding is deleted everywhere. (3) Back and START open the identical Save Changes / Reset Defaults / Discard & Exit menu; the old X-Save/O-Cancel/Triangle-Don't-Save prompt is deleted. (4) "Carousel Devices" -> "Device List". (5) Keyboard default ABC -> QWERTY (normalizer fallback too). (6) Cover/details folder values spell the device prefix (device:/POPS/ART). (7) The Hidden-games row gains a dimmed "How to hide a game / L3 on the game list" hint.
• Rationale: verbatim tester feedback — "select. settings, exit"; "I would drop credits, settings and game art buttons in games list"; "get rid of hid text here"; "put credits in settings imo"; "the back button prompt is differnt than the start prompt ... they should be the same"; "carousel is actually device list"; "Keyboard layout default should be QWERTY"; "I presume you mean device:/POPS/ART?"; "I dont know how to hide games...". Each is a case of the UI lying, hiding, or shouting.
• Implications: hiding a binding without removing it is a discoverability trade accepted deliberately (the tester asked for exactly that, and README/TESTING still document the bindings). Credits reuses the existing CreditsReturnScene mechanism, so it returns to Settings with staged drafts intact (returning via SceneChange does not re-run SyncSettingsDraftFromRuntime; only the START-entry handler does). A minimal action row kind came back, but INSIDE a section this time so it obeys the accordion — that placement was the objection to the old Save/Reset/Discard rows, not the concept. The two save routes keep ONE deliberate difference, the save target, because it matches user intent: Back exits to where it came from and tolerates a failed save (the user was already leaving), START stays put on failure so drafts survive a retry. labels.triangle, labels.select_toggle and Modal.OpenSaveSettings are deleted as dead. i18n: +4 keys x 5 languages, -35 dead keys, guarded by a checker that refuses to drop a key still referenced in code (comments excluded).
• Evidence: bin/POPSLDR/ui.lua, bin/POPSLDR/system.lua; Lua parse-check + host harness 18/18 (T16 extended to pin the new keys) + a real ps2dev/ps2dev:v2.0.0 build with the identity markers passing, the new strings present in the ELF and the dropped ones absent. Two injection traps hit and fixed: a globally-deduped inserter put all 4 keys in French only, and json.dumps defaults to ensure_ascii=True, emitting \uXXXX — valid JSON, INVALID Lua (Lua needs \u{XXXX} with braces, and this table stores raw UTF-8; verified the repaired bytes are real UTF-8, c3 80 for A-grave). NOT hardware-tested.

2026-07-13 — R3Z3N settings-review round 2: profiles dropped, START menu, region-native confirm, keyboard rework

• Decision: implement R3Z3N's second settings-UI review wholesale (maintainer agreed in the review chat): (1) the 16-preset POPSTARTER profile system is REMOVED — pops_profiles.lua deleted, PLDR.POPSTARTER_PATH is the single value ("" = Automatic = the launch ladder; a set path = custom-first with silent fallback; warn only when nothing resolves anywhere); (2) Save/Reset/Discard moved off the settings list to a START-opened modal menu; (3) region-native confirm: rom0:ROMVER byte 5 == 'J' flips CIRCLE=confirm/CROSS=cancel across the pad map, footer glyphs, modal hints and blocking prompts, and the confirm action renders far-left in every footer; (4) keyboard: number row on top, opens UPPERCASE on the letter row, the in-keyboard layout strip removed (Settings row is the one chooser), Case/Symbols label names the target state, held-CONFIRM keeps the key pressed; (5) accordion sections reveal over ~6 frames; headers get their own color, read-only rows dim, Hide UI Text reads On/Off.
• Rationale: R3Z3N: the profile presets duplicated what the resolution ladder already does, exposed pfs partition numbers users should never see, and confused the CWD case; the inline Save/Reset rows sat oddly above Memory Card; "confirm should always be far left" and Japanese consoles expect circle-confirm; the keyboard duplicated the layout setting and mislabeled the case toggle.
• Implications: PROFILE=/POPSTARTER_MODE= config keys are no longer written; on load, an empty path + a legacy PROFILE=N in the mapping table migrates to that preset's absolute path — the adversarial review refuted the initial "no migration needed" claim. The load-bearing entries are the hdd0:__common presets (2-5): an HDD-resident POPSTARTER driving removable-device games is the supported D-14 setup, and the Automatic ladder probes __common only for HDD-policy launches, so those users would have lost their POPSTARTER; the cross-device removable presets (6-12) likewise. The old mc?:/POPS presets 13/14 are deliberately NOT migrated (a memory card never carries a POPS folder — maintainer, 2026-07-13 — so migrating them could only pin a phantom path); they land on Automatic like preset 1. The mc:/POPSTARTER presets 15/16 migrate faithfully (real locations, also ladder-covered). ResolveLaunchPopstarterPath and the D-10/D-15 partition machinery are untouched (UI/config layer only). The C-side embed tables/Makefile/CI Lua lists dropped pops_profiles.lua. The harness gained T17 (path round-trip + legacy-key ignore) and a false-PASS fix: check() treated Lua false, "reason" tuple returns as truthy, so two-value failures were reported as PASS — discovered because T16 kept passing after its hint keys were deliberately removed.
• Evidence: the 2026-07-13 commit run on dev (settings polish → accordion animation → ROMVER confirm swap → keyboard rework → profiles drop); tools/host_harness.py 18/18; R3Z3N review chat 2026-07-12.

2026-07-10 — 1.0.0 released; dev/rolling branch renamed BETA-13-PLAY -> dev

• Decision: the BETA-13 candidate graduated straight to a 1.0.0 public release (tag 1.0.0 at bb15a45, a tree-adopting merge of BETA-13-PLAY onto master; GitHub Release live + latest with POPSLOADER-1.0.0.zip). The dev/rolling branch was then renamed BETA-13-PLAY -> dev (generic name; the version-suffixed *-PLAY convention was tied to a specific beta and no longer fits post-1.0.0).
• Rationale: the feature set is broadly hardware-confirmed on the core (multiple testers) and the newer opt-in features degrade gracefully, so 1.0.0 was the maintainer's call for release momentum. Renaming to a version-independent dev means the rolling branch never needs renaming again per release.
• Implications: the ONLY load-bearing reference was .github/workflows/rolling-release.yml's push trigger (now dev); CI (compilation.yml) triggers on "*" so it is name-independent, master is the default branch (unaffected), and the MEGA badge + rolling-download point at the MEGA folder + the rolling-release tag (not the branch). Forward-looking doc references were retargeted to dev; dated/historical mentions of BETA-13-PLAY (changelog, this log's older entries, the QA ledger rows, docs/archive/RELEASE_BETA13.md) are left accurate. Backups pushed before the cut: backup/master-pre-1.0.0 (10777a9), backup/BETA-13-PLAY-pre-1.0.0 (9441b7d).
• Evidence: tag 1.0.0, master bb15a45, prep 62ee7a5; rolling-release.yml trigger; the rename commit on dev.

2026-07-09 — Adaptive BDMA semantics: saved-mode-as-USB-preference, launch-cancel on staging failure, adaptive-off restage (800ac9c, 3eff270)

• Decision: Adaptive BDMA (issue #509, PLDR.BDMA_ADAPTIVE, default Off — SUPERSEDED 2026-07-28: the default is now On, see the 2026-07-28 entry below) stages the launched device's BDMA variant at launch with an equipped-check-before-write. Three deliberate semantics: (1) the USB page resolves from the saved BDMA Mode — saved USBEXFAT keeps the exFAT pair, any other saved mode means FAT32 (modules removed); (2) a staging failure cancels the launch with a warn toast; (3) turning adaptive off restages the user's chosen mode in the same save (equipped-gated).
• Rationale: (1) FAT32-vs-exFAT USB is not detectable from the launcher (identical BDM driver name, no fs-type binding), and a user whose drive needs the exFAT modules necessarily has that mode saved — it never worked any other way; (2) nothing queued after exec can render, and launching on wrong/half-written modules black-screens inside POPStarter with zero diagnostics — cancelling returns to the menu loop where the toast is visible (adversarial-review finding); (3) with adaptive on, bdma_mode.txt tracks the LAST LAUNCH, so without a restage the off-transition's marker reconcile would silently clobber the saved preference with whatever launched last (review finding).
• Implications: the marker-override in ReconcileBdmaModeWithEffectiveState is gated on BDMA_ADAPTIVE ~= true; the marker file format is unchanged (mSAS reads it); no success toast exists — the tester pass signal is both-device launches booting; staging runs AFTER the cheap launch validations so a blocked launch costs no card writes; the POPSTARTER-folder interlock extends to the adaptive flag both ways.
• Evidence: bin/POPSLDR/system.lua (MaybeApplyAdaptiveBdma/ResolveAdaptiveBdmaTarget/IsBdmaModeEquipped, the CommitSettingsChanges ON→OFF arm), bin/POPSLDR/ui.lua (Storage row + interlocks), review workflow wf_563626bc-4fe (8 confirmed findings, all actioned in 3eff270).

2026-07-09 — Partition-installed games are gated on an IMAGE0.VCD mount-probe, not partition name alone (198bae5)

• Decision: the HDD (PFS) page lists HDDOSD/PSBBN partition-installed games (PP.<name> / __.<name>, image at pfs:/IMAGE0.VCD) discovered via the new HDD.ListPartitions() APA enumerator — but a candidate is listed ONLY if a read-only mount-probe finds IMAGE0.VCD at its root.
• Rationale: name alone is a proven false-positive trap — HDDOSD apps also ship as PP.* partitions (e.g. CodeBreaker); the wLaunchELF source carries the same warning. The probe cost (one tracked RDONLY mount per candidate, once per boot under the HAS_CHECKED gate) buys a list with no phantom entries.
• Implications: entries reuse the standard "PART|rel" encoding so cache/hide/R1/R3/launch routing flow unchanged; display + art/txt base = partition name minus the 3-char prefix (matches POPStarter's own __common/POPS/<name> convention); launch argv0 = the literal partition label + .ELF (case-sensitive, unsanitized); HDD sorts key on the DISPLAYED name (CompareGameEntriesByDisplay) since raw-encoded order put every PP.* above every __.POPS*. HW-unproven: the PP.<name>.ELF argv0 contract against the shipped r13 beta, and the wiki-documented old-launch-type __common asset bug (VMC scope).
• Evidence: .research/wiki/hdd-mode.md + .research/firstparty/partition-games.md (R3Z3N); src/luaHDD.cpp ListPartitions; bin/POPSLDR/system.lua DiscoverPartitionGames.

2026-07-09 — Boot chime re-encoded at 22.05 kHz (e27103f; −190.9 KB, zero code changes)

• Decision: bin/POPSLDR/boot.adp re-encoded 44.1 kHz → 22.05 kHz mono (390,912 → 195,472 bytes), full 15.51 s length kept.
• Rationale: the audsrv APCM header carries the pitch; nothing in the C/Lua chain hardcodes the ADPCM rate, so the swap is code-free. Spectral analysis of the decoded original showed only 0.04 % of its energy above 11.025 kHz — the chime was a 44.1 k container around ~10 kHz content, so the halved rate discards nothing audible. Encoder = a faithful Python port of ps2sdk adpenc (roundtrip-verified: 34.6 dB codec SNR, flat per-band spectrum, exact frame math).
• Implications: replacements need git add -f past the *.adp gitignore; keep the asset MONO (audsrv ADPCM is single-voice — a stereo file plays L-then-R sequentially); a hardware EAR check is still the only proof for SPU2 pitch handling — if it sounds wrong on a console, revert this one commit. A/B WAV previews live in the gitignored .research/_audio_preview/.
• Evidence: Makefile embed rule (unchanged); src/sound.cpp / ps2sdk audsrv header semantics; the analysis pipeline in the session scratchpad (adp_pipeline.py).

2026-07-07 — SMB default Port = 1111 is DELIBERATE (rationale for 75e1a84)

• Decision: PLDR.SMB_FIELDS ships PORT default "1111" (changed from 445 in 75e1a84 at the maintainer's request), and it stays.
• Rationale: the maintainer runs SMB servers on custom ports via his PS2-Servers repository; 1111 is the intended ecosystem default for those setups. Standard SMB servers listen on 445 — that is a documentation concern (README's SMB section + TESTING both tell users to set the Port to their server's real port), NOT a reason to change the default. The 2026-07-07 audit flagged this independently 14 times; this entry exists so no future audit re-flags it.
• Implications: ~~RenderSmbConfig keeps the 445-implied convention~~ — SUPERSEDED 2026-07-28: the port is now written EXPLICITLY, always, including :445. Once SMBCONFIG.DAT became a file POPSLoader READS BACK as well as writes, a suppressed port was a value that silently changed meaning on the round trip. The maintainer's reference format in issue #560 is explicit (192.168.4.47:445 PS2). Connect failures still name the failing step so a port mismatch is self-diagnosable. Do NOT migrate persisted SMB_PORT values.
• Evidence: maintainer statement 2026-07-06 ("Port 1111 should not be the issue, I use custom ports all the time thanks to my PS2-Servers repository"); bin/POPSLDR/system.lua SMB_FIELDS.

2026-07-07 — The audit fix waves (61 findings actioned across 5 code commits)

• Decision: Execute the docs/REPO_AUDIT_2026-07-07.md fix plan in 6 waves, each independently revertable: Wave 1 SMB core (d2496ec), Wave 2 settings correctness (4665b19), Wave 3 SMB UX/guards (a546d45), Wave 4 cwd/pack-root defaults (8809925), Wave 5 runtime traps/polish (7ec708a), Wave 6 docs (this commit). Checkpoint branch checkpoint/pre-audit-fixes @ f5f73dd is the pre-fix restore point.
• Headline: the SMB connect root cause (audit U02) — EnsureNet stood up the EE-side lwip stack while smbman runs on the IOP-side stack, so IP config/DHCP never reached the stack doing the networking; connect failed on hardware regardless of settings. Fixed by binding via ps2ip_init() (the ps2ips RPC), mirroring OPL; -lps2ip dropped from EE_LIBS. Also: System.smbNetUp split for per-phase connect progress; honest error mapping (IPCFG_FAIL/PROT_FAIL); GETSHARELIST cache flush; trim + shape validation on SMB fields; OSK symbol shift-map; SMB-modules launch gate; boot-time .DAT heal; Boot Page exFAT wiring; Reset-Defaults/dirty-aggregate completeness; CRLF sidecar normalize; drafts survive failed saves; POPSTARTER pack root resolves mc0→mc1; usb:/smb: boot sidecar exclusion; DKWDRV cwd probe; launch-diagnostic format-crash fix; line-preserving Lua minifier; Exit→OSDSYS pfs teardown; make package deleted.
• Implications: every fix was pre-checked against the preservation contracts (D-10/D-14/D-15, EnsureBootPartitionWritable, exit/DKWDRV routes, embedded loader, reboot_iop) — none touched. All five code waves are CI+Rolling green. The whole SMB chain plus the wave-2/4/5 behavior changes need the hardware round: connect → browse → launch → disconnect on a real PS2 + SMBv1 share is the headline test.
• Evidence: docs/REPO_AUDIT_2026-07-07.md (findings U01-U62 with per-fix solutions); commits above on BETA-13-PLAY.

2026-06-30 — Selectable Cover/Details Folder (ART_LOCATION); the open()-vs-fopen() cover theory was DISPROVEN (7f9b5fa, 6641860, BETA-13-PLAY)

• Decision: On REMOVABLE devices the cover .png + details .txt lookup folder is user-selectable via a new ART_LOCATION setting (Settings > Game List > "Cover/details folder"): pops_art (default) tries <device>:/POPS/ART/ first, pops uses the game's own POPS/ folder beside the .vcd, art tries a top-level <device>:/ART/. The game's own POPS/ folder is ALWAYS appended as a final fallback. HDD/PFS is unchanged (fixed hdd0:__common/POPS/ART/). CoverCache:GetOrLoad also drops its doesFileExist/open() existence pre-probe and lets Graphics.loadImage (fopen) open the file directly.
• Rationale: a tester (FifthFox) reported covers not showing from a POPS/ART subfolder on USB/MX4SIO while a cover/.txt beside the .vcd worked. I first hypothesised an open()-vs-fopen() difference on nested paths. A source investigation (workflow w0ucpisvc, 4 agents, high confidence) DISPROVED that: in ps2sdk open() and fopen() both funnel through the SAME libcglue _open (ee/libcglue/src/glue.c -> __path_absolute in cwd.c; newlib fopen->_fopen_r->_open_r->_open, open->_open_r->_open), so they resolve mass:/POPS/ART/x.png byte-identically. Nested subfolder reads WORK on the BDM/FAT drivers: OPL reads mass0:/ART/<name>_COV.png + mass:/CFG/*.cfg with plain open() (.research/opl bdmsupport.c:585/588, textures.c:563, opl.c:2016, util.c:177), and ps2sdk FatFs follow_path() walks /-segments with no depth cap. POPSLoader's BuildCoverCandidates builds a correct mass:/POPS/ART/<name>.png for USB and MX4SIO. So the pre-probe drop is an INERT cleanup (one fewer redundant open() before the identical fopen()), NOT a fix; a POPS/ART cover that does not show is a filename/location/build-version issue, not a read-path limitation. The setting stands on its own as a usability feature (users pick where art lives). A directory-listing existence check was rejected (only proves existence; reads work anyway).
• Implications: the pre-probe drop is behavior-neutral (loadImage still returns nil for a genuinely missing file, memoized in CoverCache.failed). Because open()==fopen(), a .txt in POPS/ART also reads fine when present (no separate limitation). To stop this costing test cycles, UpdateSelection stores the primary missed path (last_cover_probe) and the list view prints a "No cover. Looked for: " caption under the placeholder when preview is ON, text is shown, and no details occupy that space, so a tester self-checks the .png name/folder. ART_LOCATION sits between DETAILS_ALIGN and HDD_FS in EncodeSettings; persisted-key count is 22 + the appended SMB block.
• Evidence: bin/POPSLDR/ui.lua BuildCoverCandidates (~190) + CoverCache:GetOrLoad (344, no pre-probe, corrected comment) + the missing-cover caption (list-view render); bin/POPSLDR/system.lua ART_LOCATION plumbing (encode 3339, default 3584, load 3703/3770). SDK/OPL proof: workflow w0ucpisvc (newlib mirror fopen.c/openr.c/sysopen.c; ps2sdk ee/libcglue glue.c + cwd.c; OPL .research/opl; fjtrujy/FatFs iop-r0.16 ff.c follow_path). Setting 7f9b5fa, inert pre-probe drop 6641860, correction + diagnostic + docs this push.

2026-06-29 — Deterministic Removable-Device POPSTARTER Resolution: custom → cwd → device (BETA-13-PLAY)

• Decision: For REMOVABLE devices (USB / exFAT-ATA / MX4SIO / MMCE), PLDR.ResolveLaunchPopstarterPath resolves POPSTARTER.ELF in one deterministic order: (1) an explicit user-configured absolute path (the custom-path setting, or any absolute Profile selection) when it actually resolves; (2) the game's own <device>:/POPS/POPSTARTER.ELF when it exists (lets a per-device build be used without enforcing it); (3) the launcher's own folder ("cwd") via the new ResolveCwdSidecarPopstarter (probes APP_DIR_LOCAL / live CWD / BOOT_ARGV0 / BOOT_PATH / APP_DIR_RAW, skipping HDD/pfs candidates); (4) the existing mc0:/mc1:/POPSTARTER + configured-default fallback net. (Initial cut was custom→cwd→device; flipped same-day to device-before-cwd so per-device POPSTARTER builds actually win — see the FifthFox USB-delay report.) This SUPERSEDES the ee4cba0 "prefer device-local first" precedence — device-local drops from first to step 3, so a configured custom path now wins as intended. Profiles need no UI change: an absolute Profile selection IS the step-1 custom path, so they act as presets that fill the custom field.
• Rationale: eliminate new-user confusion / "cover them out of the box" — a launcher + POPSTARTER dropped together (cwd) just works, the per-device POPS/ folder is the catch-all, and an explicit custom path is always honored. Custom is existence-gated so a stale/typo'd path falls through to cwd/device instead of stranding a launch.
• Implications: HDD/APA (internal PFS) resolution is INTENTIONALLY UNCHANGED — HDD games hit the colocated == nil early return and fall straight into the unchanged ResolvePopstarterPath, preserving the D-10/D-15 partition-context + embedded-loader path byte-for-byte (adversarially verified: HDD-equivalence + order-correctness PASS). The prior 2070a65 games-only-exFAT fix survives (the cwd/net still finds the MC-resident POPSTARTER). NEW behavior for removable devices → needs HW validation across USB/exFAT-ATA/MX4SIO/MMCE; device-local is ordered AHEAD of cwd so a per-device POPSTARTER build (e.g. a USB-delay build on the USB drive, a faster one elsewhere) wins for that device's games, while cwd + the mc-net still cover everyone else — intended (FifthFox USB-launch report). APA/internal-PFS now has its OWN ordered resolution (custom → hdd0:__common/POPS/POPSTARTER.ELF → cwd → net): the __common step resolves through the SAME path as the shipped bare-pfs __common profile (#2), so the D-10/D-15 partition-context + reboot_iop=1 + embedded-loader handoff is byte-identical to selecting that profile (3-skeptic verify PASS, no real bug); on a miss it releases the probe's slot-3 mount and falls to the unchanged boot-sidecar+mc resolver. Landed as a SEPARATE commit so it can be reverted alone — NEEDS a real-PS2 D-10/D-15 check before trust. The BDMA "modules located" picker idea was dropped: the driver variants are embedded in the ELF (no external source), and POPStarter reads them only from mc0:→mc1: ("Mass is not supported").
• Evidence: bin/POPSLDR/system.lua ResolveLaunchPopstarterPath + new ResolveCwdSidecarPopstarter (~1786). 3-skeptic adversarial verify wf: HDD byte-identical + order-correct PASS; one unqualified-call bug caught pre-push (PopstarterProbeWithEnsure → PLDR.PopstarterProbeWithEnsure) and fixed. Landed on BETA-13-PLAY 2026-06-29; CI+Rolling green.

2026-06-22 — HDD (exFAT) / BDMA-ATA Backend (df2eb9d, 6fd2142, afa1c09)

• Decision: Add an internal-HDD exFAT (BDMA-ATA) backend that scans + launches games as a mass: device, classified by the EXACT ioctl driver-name ata (strcmp==0 && strlen==3, mirroring OPL bdmsupport.c — never substring, so it can't leak into USB/MX4SIO). Carousel opt 3 = exFAT page (scene GBDMHDD, gamelocation = mass:/POPS); opt 4 stays the classic PFS page. lua_ata_init/initATA loads ata_bd.irx after EnsureUsbMass (mirrors lua_mx4sio_init); ApplyBdmaMode stages the distinct R3Z3N usbd.irx.ata/usbhdfsd.irx.ata (stripped) to mc?:/POPSTARTER/. saildot4k credited for the backend (fixes/feedback/oversight); R3Z3N for the ATA BDM Assault drivers.
• Implications: CI+Rolling green; NOT yet hardware-tested (needs an exFAT internal drive). STATUS: implemented / validating on hardware.
• Evidence: bin/POPSLDR/system.lua CAROUSEL_DEVICE_KEYS + EXFAT/ATA→GBDMHDD; src/luasystem.cpp ClassifyMassBackend exact-ata + lua_ata_init; Makefile ata_bd.o. Commits df2eb9d/6fd2142/afa1c09.

2026-06-22 — -page=ata Routes to the exFAT Page, not PFS (3d89631)

• Decision: NormalizeLaunchPage maps ata/ata0/ataN → EXFAT (exFAT page, opt 3, GBDMHDD); hdd/hdd0/apa/apa0/any pfs → HDD (PFS page, opt 4). page_to_opt includes EXFAT=3, ATA=3, HDD=4. -mode shares the alias path; bare bdma stays a no-op page value. Un-deads the previously-unreachable EXFAT/ATA branches in page_to_opt + AutoLaunchFromLaunchArgs.
• Rationale: the exFAT backend (above) had no reachable launch-arg target; ata is NHDDL's token for the internal ATA drive, and maintainer spec is ata→exFAT / hdd·apa·pfs→PFS.
• Implications: launchers can open POPSLoader straight to the exFAT page; NEW launch path → needs HW (TESTING.md P1). A DS4-over-BT memset fix (ds34bt.c, full PS4_11_REPORT_LEN+2 zero, no more uninitialized bytes on the wire) rode along.
• Evidence: bin/POPSLDR/system.lua NormalizeLaunchPage (ata→EXFAT), page_to_opt. Commit 3d89631.

2026-06-22 — Layer C lazy-IRX: ds34bt/usbd Deferral DECLINED; Layer C Closed

• Decision: Keep usbd/ds34usb/ds34bt EAGER. Both ds34* hard-import usbd, and the boot-device hint is not a pad-transport signal, so deferring them would strand USB/BT controller input unrecoverably for a tiny boot-time gain. The mmceman deferral (PR #471, shipped) was the only safe Layer-C win.
• Implications: Layer C is closed; do not re-propose the ds34/usbd deferral (STATE.md Known Open Work #3, ROADMAP §4 — both marked DECLINED).
• Evidence: src/main.cpp IRX bring-up order (usbd → ds34usb/ds34bt eager); modules/ds34{bt,usb}/iop/imports.lst usbd_IMPORTS.

2026-06-22 — Ruthless Audit: Dead-Symbol Cleanup + Bug Fixes (2735229)

• Decision: Remove verified-dead symbols (recursive_mkdir, readPad+pad.h extern, max() in fntsys, modulePath/setModulePath, HDD_DIAG_BYPASS, Footer.order_with_r2/order_settings, NormalizeDirPathCompat/APP_DIR_LOCAL in pops_profiles, registered_count in images, the sound.cpp commented demo) and land behavior-preserving fixes (lua_dir path[255]→256, lua_writefile size-clamp, lua_sleep label, GLYPH_PAGE_OK macro, lua_destroy return 0, image-magic fread check, FREAD not O_RDONLY, system.lua boot_sound/overscan un-nested from the gamelist_cache guard).
• Implications: No intended behavior change; hardened crash/leak edges. SHIFTED line numbers in luasystem.cpp/ui.lua/system.lua/fntsys.cpp/sound.cpp/pad.cpp — re-verify any file:line anchor into those files. From a 13-cluster adversarial find→verify→synth audit; report-only items (elf-loader OOB guards declined, keep_slots array-vs-set, etc.) tracked in memory reference-code-audit-2026-06-22.
• Evidence: Commit 2735229; CI+Rolling green.

2026-06-21 — Frame-Count Nav Auto-Repeat Instead of the Wall Clock (d128779)

• Decision: Drive UI navigation auto-repeat by counting frames, never by reading Timer.getTime(). In resolve_nav inside UI.Pad.Listen (bin/POPSLDR/ui.lua): nav_fps = ((UI.SCR.Y or 448) >= 512) and 50 or 60; NAV_DELAY_FRAMES = ceil(nav_fps * 0.6); NAV_RATE_FRAMES = ceil(nav_fps * 0.2); a per-direction UI.Pad.NavHoldFrames[dir] counter increments once per UI.Pad.Listen frame. The press edge fires immediately; only UP/DOWN repeat (after ~0.6s, then ~0.2s ≈ 5/sec) — LEFT/RIGHT stay edge-only so holding never page-jumps or spins the carousel.
• Rationale: Timer.getTime() returns raw clock() ticks, which are MICROSECONDS on the PS2 EE toolchain (CLOCKS_PER_SEC == 1e6; the binding is clock() - tick, byte-identical to Enceladus src/luatimer.cpp). The UI historically treated that value as milliseconds, so every comparison against a _ms-named constant cleared its gate every frame and UP/DOWN auto-repeated ~60×/sec ("one click = 5 lines", up/down only, on ANY device including a keyboard — nuno6573 / LVD14 #504). The canonical Enceladus idiom is frame-counting: the sibling launchers OSDMenu-Configurator (ui_common.lua) and RETROLauncher (funciones.lua) both frame-count nav and never read the wall clock. UI.Pad.Listen runs once per vblank-paced frame, so one increment == one frame: frame-rate independent and unit-safe.
• Implications: Nav feel is correct and identical in real seconds on PAL (50Hz) and NTSC (60Hz). HW-CONFIRMED 2026-06-21 (oldman63: up/down + analog-stick nav land on individual items, continuous scroll fine). The intermediate "treat the µs value as µs" stopgap (adaa8ee) was superseded by this frame-count approach. (Update a8e61f3, 2026-06-22: the µs-as-ms sweep was later COMPLETED — the MIN_ACTION_MS action debounce was removed entirely (edge-triggering is the gate) and the transition / carousel / boot-fade timers were frame-paced; nothing remains parked. See the SUPERSEDED parked entry below.)
• Evidence: bin/POPSLDR/ui.lua resolve_nav (~line 4583), nav_fps/NAV_DELAY_FRAMES/NAV_RATE_FRAMES (4580–4582), UI.Pad.NavHoldFrames (4430). src/luatimer.cpp lua_time (clock() - tick, line 41). Commit d128779. See STATE.md > Hardware Status.

2026-06-21 — os.clock() Sweep for the Remaining µs-as-ms Timers PARKED (not done) — SUPERSEDED (a8e61f3, 2026-06-22)

• SUPERSEDED: the sweep was completed, not parked. MIN_ACTION_MS was removed entirely (edge-triggering pressed = GPAD & ~OLDPAD is the gate); PathEditor key-flash/caret-blink + the launch-watchdog label were made unit-correct (Timer.getTime()/1000); the scene-fade/boot-fade/carousel were frame-paced (behavior-preserving). No µs-as-ms timer remains. (Original parked rationale kept below for history.)
• Decision: Do not convert the remaining wall-clock timers (the MIN_ACTION_MS action debounce and the transition/carousel timers) in this session. Record os.clock() as the intended fix and leave it parked.
• Rationale: Those sites still compare Timer.getTime() µs against ms-named constants, but a per-frame max_step clamp masks the 1000× error so they are not visibly broken. os.clock() (stock Lua, returns seconds) is the only pre-converted Lua time source and is currently unused in bin/POPSLDR/*.lua; a future sweep should move the remaining _ms sites to either os.clock() seconds or frame-counting (the nav + desc-scroll paths are already frame-counted). Doing it now would be unverifiable churn outside the BETA-13 nav fix.
• Implications: A known, bounded debt — not a regression. Any future edit to debounce/transition timing should land the os.clock() (or frame-count) conversion rather than perpetuate the µs-as-ms pattern.
• Evidence: bin/POPSLDR/ui.lua UI.InputConfig.MIN_ACTION_MS (622) consumed by emit_action (now - UI.Pad.LastActionEventMs < MIN_ACTION_MS, ~4547); no os.clock() call exists in bin/POPSLDR/*.lua.

2026-06-21 — Description Right-Stick Scroll Is Frame-Counted Too (c8fce10)

• Decision: Gate the game-description right-stick scroll on a frame counter, not the wall clock. In bin/POPSLDR/ui.lua the scroll steps once every step_frames = ceil(_secs * fps) frames (fps = (UI.SCR.Y>=512) and 50 or 60), with speeds expressed in seconds: slow (default) 0.9s, medium 0.3s, fast 0.15s, read from the "Description scroll speed" setting (PLDR.DESC_SCROLL_SPEED). The per-frame counter is UI.GameList.DescScrollFrames.
• Rationale: The old gate compared Timer.getTime() (µs) against a _ms value, so it was sub-frame and scrolled every frame regardless of the setting — all three speeds felt identical (oldman63). Frame-counting makes the Fast/Med/Slow setting actually take effect and keeps the feel identical in real seconds on PAL and NTSC. Same root cause and fix shape as the nav auto-repeat decision above.
• Implications: DescScrollAt (the old wall-clock timestamp field) is replaced by DescScrollFrames. Desc-scroll feel is still pending a hardware eyeball (keep as pending, not broken).
• Evidence: bin/POPSLDR/ui.lua desc-scroll block (~2669–2699): step_frames = math.ceil(_secs * fps), _secs = 0.9 / 0.3 / 0.15, UI.GameList.DescScrollFrames, PLDR.DESC_SCROLL_SPEED. Commit c8fce10.
• Superseded (2026-06-24, 6004bf8): the Fast/Medium/Slow setting was removed (provato + maintainer: Fast is best). The right-stick scroll is now hardcoded to the Fast pace (_secs = 0.15); the frame-counting decision and rationale above still stand.

2026-06-21 — Gate the Analog-Stick→D-Pad Fold on Real Analog Mode + Hysteresis (d233069, 9b8a38e)

• Decision: Fold the left analog stick into the d-pad direction bits in UI.Pad.Listen (bin/POPSLDR/ui.lua) only when Pads.getMode() reports analog/DualShock (md == PAD_ANALOG or md == PAD_DUALSHOCK), and apply a per-axis hysteresis latch (assert a direction at |v| > 64, release only below |v| < 40, latch the asserted side). When not analog this frame, drop any latched stick direction (UI.Pad.StickV/StickH = 0). Add a new C binding Pads.getMode() = padInfoMode(port, 0, PAD_MODECURID, 0) — the live negotiated controller mode.
• Rationale: An ungated fold read a digital/non-analog pad's stale/zero analog bytes (getLeftStick = ljoy - 127 ≈ -127), injecting a phantom PAD_UP|PAD_LEFT every frame and breaking up/down nav (Nuno6573 #BETA-13). The fix mirrors OPL src/pad.c:201 (if ((pad->buttons.mode >> 4) == 0x07)). The pre-existing Pads.getType() is miswired to PAD_MODETABLE (a capability-table entry) and is unusable for this gate; PAD_MODECURID is the only authoritative live-mode source. Hysteresis stops a stick parked at the deadzone boundary from dithering across the threshold and edge-spamming the immediate-fire nav branch. lua_getleft/lua_getright were also hardened (zero-init + neutral 127 default, gate on padRead's return) so an unread/failed frame yields centered (0,0) instead of stack garbage or a phantom -127.
• Implications: Digital pads and keyboards navigate correctly; analog sticks still fold. HW-CONFIRMED 2026-06-21 (oldman63: analog-stick nav lands on individual items). Pads.getMode is the binding to use for any future analog-mode gate; do not use Pads.getType for that. The C hardening only removes uninitialized/failed-read phantoms — a successful read on a digital-mode pad still returns a phantom -127, which is why the Lua getMode gate is load-bearing.
• Evidence: src/luacontrols.cpp lua_getmode (PAD_MODECURID, line 78; registered getMode, 278), lua_gettype (PAD_MODETABLE, 17; getType, 277), lua_getleft/lua_getright neutral-default hardening (99–146), PAD_ANALOG/PAD_DUALSHOCK globals (PAD_TYPE_ANALOG/PAD_TYPE_DUALSHOCK, 342–346). bin/POPSLDR/ui.lua fold gate + hysteresis (4470–4511). Commits d233069, 9b8a38e. See STATE.md > Hardware Status.

2026-06-21 — Boot Sound On/Off Setting (6eba9e7, save fixed 9b8a38e)

• Decision: Add a Boot sound On/Off setting (default On) in Settings that gates the splash chime, persisted through the full settings chain.
• Rationale: Let users silence the boot chime; it's a low-cost, expected toggle. 9b8a38e fixed the save path (the #501 regression where the toggle did not persist).
• Implications: New persisted settings key BOOT_SOUND (plumbed through EncodeSettings, PLDR.CommitSettingsChanges via next_boot_sound / next_state.boot_sound, and parse-back in LoadSettings). HW-CONFIRMED 2026-06-21 (oldman63: boot-sound saves and survives reboot). See STATE.md > Settings for the canonical key list.
• Evidence: bin/POPSLDR/ui.lua "Boot sound" AddCycle (3624–3630), UI.BootSound (2307), boot-chime gate (UI.BOOT_SOUND.ENABLED / PLDR.BOOT_SOUND, 1103–1104). bin/POPSLDR/system.lua EncodeSettings BOOT_SOUND= (3098), CommitSettingsChanges next_boot_sound (3566–3567) / next_state.boot_sound (3592), parse-back (3436, 3506). Commits 6eba9e7, 9b8a38e.

2026-06-21 — OPL-Style Overscan (CRT Inset): Identity Render-Transform at Permille 0 (1ac15ad C core, 6f0d742 UI, 73f0933 reset)

• Decision: Add an OPL-style render-coordinate overscan inset. src/graphics.cpp wraps its gsKit_prim_* draw sites in OVX() / OVY(), which scale the whole UI uniformly toward screen center by an overscan permille; at permille 0 the transform is the identity, so the default render is byte-for-byte unchanged. New C bindings Screen.setOverscan(permille) / Screen.getOverscan() (src/luaScreen.cpp). A Settings entry "Overscan (CRT inset)" is a live ±5-step adjuster (Off/value, live preview via Screen.setOverscan; discard restores). Reset Defaults zeroes it.
• Rationale: CRT users lose UI to overscan; OPL solves this with a render inset and we adopt its exact math (margin = W*permille/2000 per edge, scale = 1 - permille/1000, OVX(x) = x*scale + margin, matching OPL renderman.c rmSetOverscan). Making permille 0 the identity guarantees a zero-risk default — nothing changes unless the user opts in.
• Implications: New persisted settings key OVERSCAN (through EncodeSettings, CommitSettingsChanges next_overscan/next_state.overscan, parse-back). NOT yet hardware/CRT-eyeballed — keep as pending, not broken. See STATE.md > Settings and Hardware Status.
• Evidence: src/graphics.cpp OVX/OVY + recompute_overscan/set_overscan/get_overscan (1128–1166), wrapping the gsKit_prim_* draw sites. src/luaScreen.cpp lua_set_overscan/lua_get_overscan (64–74; registered setOverscan/getOverscan, 162–163). bin/POPSLDR/ui.lua "Overscan (CRT inset)" AddCycle ±5 step (3631–3643), live apply (3071–3072), Reset Defaults zero (3356–3358). bin/POPSLDR/system.lua OVERSCAN= (3099), next_overscan (3568–3569)/next_state.overscan (3593), parse-back (3437). Commits 1ac15ad, 6f0d742, 73f0933.

2026-06-21 — Layered Cover-Art Placeholder Replaces the Single MISSING.png (56a5ad5)

• Decision: Replace the single combined no-cover placeholder image with two layered assets: bin/POPSLDR/IMG/cover_default.png (base) + cover_missing.png (overlay). In the game-list preview box (bin/POPSLDR/ui.lua): a live cover draws unchanged in its own COVER_W inset; with no live cover, cover_default.png is drawn in the frame's aspect-corrected, right-anchored rect, and cover_missing.png is overlaid only when the preview is enabled (cover_enabled) and the game has no cover. The old "Cover disabled" text label is removed — preview-off now shows the plain default cover. The default, the overlay, and frame.png all share the same right-anchored rect so they register with the jewel-case window on both NTSC and PAL.
• Rationale: A layered default+overlay reads better than one combined image and cleanly distinguishes "preview off" (plain default) from "preview on, no art" (default + missing mark), without a text label.
• Implications: MISSING.png is fully removed (-62KB ELF: bin/POPSLOADER.ELF is now 1739428 bytes, down from 1802052). Any doc that names MISSING.png as the cover placeholder, or the "Cover disabled" text label, is stale. This supersedes the 2026-05-19 "default cover is optional, MISSING.png required" decision (see that entry's superseded-by note). The frame-registration alignment was pre-existing-since-#496 (BETA-12), not a new BETA-13 regression (fa2d899). Cover registration on NTSC+PAL is still pending a hardware eyeball.
• Evidence: assets bin/POPSLDR/IMG/cover_default.png, cover_missing.png (and frame.png). bin/POPSLDR/ui.lua placeholder block (2577–2592): IMG.cover_default, if cover_enabled and IMG.cover_missing, IMG.frame. Commit 56a5ad5. See the 2026-06-21 "Embedded-Asset Add/Remove" entry below for the removal mechanics.

2026-06-21 — Embedded-Asset Add/Remove Is Three Explicit Coordinated Places (not auto-glob)

• Decision: Document and follow the rule that embedding (or dropping) a runtime asset touches three explicit, hand-coordinated locations — there is no glob: (a) Makefile — a BIN2S rule for asset_<name>_png.c plus the .o listed in EMBEDDED_RSC; (b) src/embed_assets.cpp — an extern declaration plus an ASSET_ENTRY in both the bare-name table and the POPSLDR/IMG/-prefixed table; (c) bin/POPSLDR/images.lua IMG_REGISTRATIONS, which looks up the bare filename.
• Rationale: The MISSING.png removal and the cover_default/cover_missing additions both had to hit all three places in lockstep; missing any one leaves a dangling extern, an unembedded asset, or a nil IMG.x. Recording the contract keeps future asset edits from half-landing.
• Implications: Reusable checklist for ARCHITECTURE / CONTRIBUTING / AGENTS. MISSING.png was cleanly removed from all three (no leftover .o, extern, ASSET_ENTRY, or images.lua registration; the only remaining "MISSING" strings are comments referencing cover_missing.png).
• Evidence: Makefile BIN2S rules (179–182) + EMBEDDED_RSC (96–101, asset_cover_default_png.o asset_cover_missing_png.o). src/embed_assets.cpp externs (62–63) + ASSET_ENTRY in bare-name (120) and POPSLDR/IMG/ (167) tables. bin/POPSLDR/images.lua {"cover_missing", "cover_missing.png"} (36).

2026-06-21 — Steer the HDD Game Scan Off the Boot PFS Slot (Proposal A, b159a43; save-after-scan liveness 8d1e67a)

• Decision: When POPSLoader is HDD-resident, the game-partition scan must never mount onto the live boot PFS slot. GetHddGameSlotCandidates (bin/POPSLDR/system.lua) starts from the historical order {HDD_SLOT_GAME=1, HDD_SLOT_BOOT=0}, drops whatever slot GetBootHddMountSlot() reports as the live boot slot, and appends HDD_SLOT_COMMON=2 as the off-boot fallback (so for a slot-1 boot the scan uses slots {0, 2}). On a non-HDD boot GetBootHddMountSlot() is nil and the full historical list is returned unchanged so the scan still fires. Separately (8d1e67a), the settings save path liveness-validates the boot RW mount via doesFolderExist before trusting the BOOT_PARTITION_RW flag.
• Rationale: The HDD boot/settings partition stays mounted on its boot slot (pfs1: per boot.lua:48 "NEVER USE IT FOR ANYTHING ELSE"). Mounting a game partition onto that occupied slot fails at the C layer (luaHDD's warm single-attempt mount) and collaterally unmounts the boot partition, stranding the settings cwd — so after a scan a settings save failed "...may be read-only" with a never-cleared BOOT_PARTITION_RW flag (Nuno 2026-06-20). The doesFolderExist liveness check fixes the immediate save failure; Proposal A removes the root cause by keeping the scan off the boot slot. Do not re-introduce the reverted bec5e90 gate on whether the scan fires based on boot source.
• Implications: Settings save survives an HDD game scan. Proposal A still wants a deliberate HDD hardware test (Nuno to verify game partitions still mount/list when forced off the boot slot) — NOT yet hardware-tested. See STATE.md > Known Issues / Behavioral Invariants and the HDD pfs-slot-model memory note.
• Evidence: bin/POPSLDR/system.lua slot constants HDD_SLOT_BOOT=0/HDD_SLOT_GAME=1/HDD_SLOT_COMMON=2 (261–263), GetBootHddMountSlot (271–277), GetHddGameSlotCandidates steering (750–787), EnsureBootPartitionWritable BOOT_PARTITION_RW liveness (2159–2170), doesFolderExist save-path guard (2001). Commits b159a43, 8d1e67a.

2026-06-21 — Codex BETA-13 Audit: 6 Findings Verified Real and Fixed (ec81de3)

• Decision: Accept and fix all six Codex BETA-13 audit findings (each independently verified real): PromoteTmpToDest requires the backup to exist before truncating the destination; BMP pixel-size/stride validation; a PNG dimension cap; stale mc0: probe cleanup; two System.writeFile full-byte-count checks; and no R3 success-toast on a failed save.
• Rationale: All six were confirmed against source rather than taken on the report's word (consistent with the project's "Codex reports are reference, not fact" stance); none changed intended behavior, they hardened crash/leak/corruption edges.
• Implications: Report lives at docs/AUDIT_CODEX_2026-06-20.md. Earlier graphics-decoder hardening (loadpng/loadjpeg/loadbmp NULL-checks + leak/overflow fixes) is BETA-12-era and already documented; do not re-attribute it to this audit.
• Evidence: docs/AUDIT_CODEX_2026-06-20.md; commit ec81de3 (and report commit afe4227).

2026-06-21 — POPSTARTER.ELF Ships in Both Release Zips

• Decision: Ship the redistributable POPSTARTER.ELF homebrew launcher in both release packages. rolling-release.yml places it at the zip root next to POPSLOADER.ELF and under POPS/. The formal install zip (compilation.yml) ships it under PS1_POPSLOADER/ (next to POPSLOADER.ELF) and POPS/. The POPSTARTER/ SMB/BDMA pack folder and POPS/PATCH_5.BIN also ship at the rolling root.
• Rationale: POPSTARTER.ELF is redistributable (the POPS engine binaries are not), so bundling it makes the rolling/install zips self-sufficient for the launcher side.
• Implications: Testers and installers get POPSTARTER.ELF without sourcing it separately; the POPS engine binaries still must be supplied by the user. See STATE.md > CI / release.
• Evidence: .github/workflows/rolling-release.yml (POPSTARTER pack at zip root ~168–174; bin/POPSLDR/POPSTARTER.ELF copied to zip root ~177–182). .github/workflows/compilation.yml (PS1_POPSLOADER/ + POPS/). Commits 6631a57, 44ea070, 91315a0, 61fb2a2/915c4ce/aeb2469.

2026-06-17 — PLDR.HDD Attach-Before-Init Load-Order Boot Fix (d4b04be)

• Decision: Move the PLDR.HDD.* method definitions so they run after PLDR.HDD exists (after the table merge/init), unbricking cold boot.
• Rationale: The recent HDD-feature rolling builds defined PLDR.HDD methods before PLDR.HDD itself existed, so every cold boot hit a runtime error (system.lua:953, reproduced under PCSX2) — the .hide / HDD-cwd settings rolling builds were never actually cold-bootable. This is a load-order error: luac -p and the new CI syntax gate parse it as valid Lua, and markers can't see it; it is only fatal at runtime. CI / luac structurally cannot catch load-order (attach-before-init) bugs.
• Implications: HDD-feature builds boot again. The HDD features need a full hardware retest once boot is confirmed, because they were never reachable on the bricked builds. See STATE.md > Known Issues ("Load-order boot brick", Recently resolved) and the embedded-Lua load-order trap note in MEMORY.
• Evidence: commit d4b04be (2026-06-17), bin/POPSLDR/system.lua.

2026-06-17 — BDMA Marker File Renamed .pldr_bdma_mode → bdma_mode.txt (Legacy Names Still Read)

• Decision: Write the installed BDMA mode key to a plain-text marker named bdma_mode.txt in the POPSTARTER pack folder. The legacy .pldr_bdma_mode / .pldr_bdma names remain read for back-compat; the current name is always written.
• Rationale: A clearer, shared, non-dotfile name (mSAS reads the same file). BDMA mode keys are FAT32 / USBEXFAT / MX4SIO / MMCE.
• Implications: Existing installs keep working (legacy read path); new writes go to bdma_mode.txt. See STATE.md > "BDMA mode / POPSTARTER memory-card folder".
• Evidence: commit 7afdac3 (2026-06-17), bin/POPSLDR/system.lua.

2026-06 — POPSTARTER Memory Card Folder Toggle + BDMA Interlock

• Decision: Add a POPSTARTER Memory Card Folder toggle in Settings (below Discard). Disabling it deletes mc:/POPSTARTER behind a destructive-action confirm. Add a BDMA ⟺ folder interlock: the folder can't be disabled while BDMA mode is on, and BDMA can't be enabled while the folder is off. Persisted via the new POPSTARTER_MC_FOLDER settings key.
• Rationale: BDMA (mass-storage backend) depends on the POPSTARTER MC folder being present; letting a user delete the folder while BDMA is on, or enable BDMA after deleting it, would leave an inconsistent install. The interlock makes the dependency unbreakable from the UI.
• Implications: EncodeSettings now carries POPSTARTER_MC_FOLDER (one of the persisted settings keys; the schema has since grown further — BOOT_SOUND and OVERSCAN were added in the BETA-13 session — see STATE.md > Settings for the canonical key list and count). New behavioral invariant — see STATE.md > Behavioral Invariants (#9, BDMA ⟺ folder interlock). STATUS: implemented / boots on PCSX2 / validating on hardware.
• Evidence: bin/POPSLDR/system.lua, bin/POPSLDR/ui.lua. See STATE.md > "BDMA mode / POPSTARTER memory-card folder".

2026-06 — PAL Renders Natively at 640×512 (Supersedes the 640×448 PAL Layout)

• Decision: On PAL the UI now renders natively at 640×512 so it fills the screen with no letterbox (NTSC stays 640×448). The display-change confirm prompt auto-reverts if not confirmed (the OPL pattern); hold START during boot to skip past a bad video mode; the boot screen is centered. Video Standard gains an Auto default (matches the console region) alongside NTSC / PAL.
• Rationale: The old 640×448-on-PAL layout (2026-03-26 decision) deliberately kept the NTSC raster to avoid vertical squish, but left PAL letterboxed rather than filling the screen. Rendering natively at 640×512 fills the PAL frame; the auto-revert confirm protects against a bad mode locking the user out.
• Implications: Supersedes the 2026-03-26 "PAL UI uses 640×448" decision (see that entry's superseded-by note). STATUS: implemented / boots on PCSX2 / PAL hardware validation pending. See STATE.md > "Video standard".
• Evidence: bin/POPSLDR/system.lua, bin/POPSLDR/ui.lua.

2026-06 — HDD Boot-Partition RW Take-Over for Settings + In-App .hide (EnsureBootPartitionWritable)

• Decision: HDD-installed POPSLoader now persists settings on the HDD boot partition itself, and writes per-game .hide markers in-app on HDD too. PLDR.HDD.EnsureBootPartitionWritable takes over the launcher's boot pfs mount — it explicitly unmounts the boot pfs slot and remounts the same partition read-write at the same slot ("own your mount", the OPL pattern) — so the .pldrs sidecar and .hide files are written on-HDD. There is no mc0: fallback for an HDD-cwd install. Single-device parity with USB / MX4SIO / MMCE. In-app hide is now L3 (toggle hide/show) on every device page including HDD, with unhide via Settings → Game List → Hidden games → Visible (manage); the "add the .hide from a PC" message is now only a write-failure fallback.
• Rationale: This directly supersedes the 2026-05-27 PR #466 premise ("HDD saves to mc0: because the bundled ps2hdd-osd.irx can't reliably write PFS, and an IRX swap would risk D-10"). The boot-partition remount take-over achieves HDD read-write without an IRX swap, so it doesn't touch the D-10 launch path. provato confirmed the HDD is RW-writable on real hardware, which validated the approach.
• Implications: New load-bearing preservation contract — EnsureBootPartitionWritable (the boot pfs-slot unmount→remount-RW take-over) must not be broken by any future launch-path / mount change; see STATE.md > Preservation Contracts. New invariants: settings persistence is per-device including HDD (no mc0: HDD exception), and .hide is in-app on every device (STATE.md > Behavioral Invariants #2, #10). The old "ps2hdd-osd.irx → ps2hdd.irx driver-swap probe" investigation item is retired. STATUS: implemented / boots on PCSX2 / HDD RW confirmed on hardware (provato) / full settings + .hide flow validating on hardware (not yet broadly hardware-confirmed). NOTE: the recent HDD-feature rolling builds that carried this work were bricked by an unrelated load-order bug until d4b04be (see the 2026-06-17 entry above), so the on-hardware full-flow validation post-dates that fix.
• Evidence: bin/POPSLDR/system.lua (PLDR.HDD.EnsureBootPartitionWritable, ComputeSettingsSidecarPath, HDD .hide write path), bin/POPSLDR/ui.lua (L3 hide-toggle handler; R3 reveal/hide-toggle handler at ui.lua:2816, GLOBAL_HIDE toggle ui.lua:2820). provato hardware confirmation 2026-06 (HDD RW-writable). See STATE.md > "Settings (single-device parity)" and "Per-game hide layer".

2026-06 — Embedded-Lua Syntax Gate (luac5.4 -p) Is Now Live in CI

• Decision: The CI workflows now apk add lua5.4 and run luac5.4 -p over bin/POPSLDR/*.lua + etc/boot.lua, hard-failing on a syntax error.
• Rationale: The gate had been silently skipping because the pinned ps2dev image ships no luac — every "syntax check" was a no-op. Installing lua5.4 in the workflow makes it actually run.
• Implications: SYNTAX errors are now caught pre-merge. It catches syntax only — runtime nil-global / type / load-order errors stay invisible to CI (the d4b04be attach-before-init boot brick was exactly such a case and passed the gate). See STATE.md > "CI / release".
• Evidence: .github/workflows/compilation.yml / rolling-release.yml (lua5.4 install + luac5.4 -p step). Run #492 green.

2026-05-31 — U-10 (BOOT.ELF from HDD-Booted POPSLoader) Resolved by PR #479 (reboot_iop=0)

• Decision: Mark U-10 as PASS / resolved. Launch BOOT.ELF from an HDD-booted POPSLoader with reboot_iop=0 (PR #479).
• Rationale: This supersedes the 2026-05-28 PM late walk-back below, which (correctly for that build) returned U-10 to known-broken after the partial-sweep PASS was reversed. PR #479 then actually fixed the path: launching BOOT.ELF without rebooting the IOP from the HDD-booted context avoids the post-reset SIF-handshake hang that black-screened the HDD-launch case. Nuno confirmed PASS on hardware 2026-05-31. (Recorded here as the latest U-10 decision so this log's most-recent U-10 state is the resolution, not the walk-back-to-broken entry.)
• Implications: U-10 leaves the known-broken list and becomes a preservation contract; the related Class-A HOSDmenu / some-wLE launch failures were separately maintainer-confirmed resolved 2026-06-15. See STATE.md > Preservation Contracts and the Reported Hardware Status table (U-10 PASS, 2026-05-31, PR #479).
• Evidence: PR #479 (reboot_iop=0 for HDD-booted BOOT.ELF); QA_REGRESSION_MATRIX.md U-10 row; Nuno 2026-05-31. Investigation chain preserved in docs/archive/U10_INVESTIGATION.md.

2026-05-29 — MX4SIO Settings Save Fixed by PR #476 + PR #477 (Hardware-Confirmed)

• Decision: Merge PR #477 to lock in the MX4SIO settings save fix. PR #476 (already merged) added the boot.lua mass-slot scan via dynamic ioctl driver lookup (sdc/mx4); PR #477 wrapped the scan in a 3-attempt retry pattern with sleep(1) between failures, plus a BOOT_MX4SIO_PROBE_RESULT diagnostic trace appended to the settings save error toast for future debugging.
• Rationale: PR #476's single-shot scan didn't catch the MX4SIO SD card on real hardware (Nuno 2026-05-28 PM retest). PLDR.InitMX4SIOPopsRoot was already using a 3-attempt retry pattern for the same MX4SIO double-ping reason; the boot.lua scan needed to mirror that. Nuno confirmed PASS on 2026-05-29 02:58Z after PR #477 was merged.
• Implications: MX4SIO-rooted POPSLoader now saves settings to the per-device sidecar at <mass*>:/<install path>/.pldrs like USB / MC / MMCE installs do. If the retry ever misses on future hardware, the mx4sio probe: a1:...;a2:...;a3:... diagnostic appears in the error toast and tells us what attempts hit what slot/driver.
• Evidence: etc/boot.lua MX4SIO branch + retry loop; bin/POPSLDR/system.lua ResolveAppDirLocal mx4sio→mass override; bin/POPSLDR/ui.lua error toast diagnostic append. PR #476 merged 2026-05-28; PR #477 merged 2026-05-29 02:58Z.

2026-05-28 PM late (correction 2) — Class A vs Class B: HOSDmenu/wLE Fail to Launch POPSLoader is Distinct from U-10

• Decision: Document the broken launcher scenarios as TWO distinct failure classes, not one. Update STATE.md / README.md / ROADMAP.md / TRUTHSHEET.md / QA matrix / U10_INVESTIGATION.md accordingly.
• Rationale: Maintainer's correction after closer reading of Nuno's Discord report. "HOSDmenu → POPSLoader = black screen, we don't even get to the splash" is fundamentally different from U-10. U-10 is about exit-to-BOOT.ELF from a successfully-running HDD-launched POPSLoader; the HOSDmenu / some-wLE failures are about POPSLoader never starting in the first place.
• Implications: Class A (POPSLoader fails to launch under HOSDmenu / some wLE builds) is the same class as the CosmicScale 2026-05-25 wLE issue that PR #458 Layer A targeted. Layer A's _ps2sdk_memory_init fileXio teardown resolved Layer A for the common case but didn't fully resolve it for HOSDmenu or specific wLE builds. Class B (U-10) is unchanged from prior status. Documenting them separately gives future investigations a cleaner target (Class A = parent-launcher IOP-state hygiene before POPSLoader main runs; Class B = POPSLoader's own IOP-state hygiene before BOOT.ELF ExecPS2). Workarounds: Class A → use a different launcher; Class B → Exit → OSDSYS or reboot.
• Evidence: Discord screenshot showing Nuno's tests: "Mmm... loaded from hosdmenu popsloader in hdd and exit to boot.elf give me black screen" (POPSLoader never reached splash); "Loading popsloader (hdd) from wle also results in black screen" (same); "Other devices memory card, usb and mx4sio exit boot.elf OK" (Class B test conditions met, BOOT.ELF works from those); maintainer correction "HOSDmenu black screens when launching POPSLoader, we don't even get to the splash" and "Some builds of wLE blackscreen as well when booting POPSLoader."

2026-05-28 PM late — U-10 PASS Claim Walked Back; Remains Known-Broken Accepted

• Decision: Reverse the earlier 2026-05-28 PM doc walk-down that marked U-10 (BOOT.ELF from HDD-booted POPSLoader) as PASS. U-10 remains known-broken-accepted in BETA-10-5, same as before, with the workaround Exit → OSDSYS or reboot.
• Rationale: Nuno's earlier 2026-05-28 PM "BOOT.ELF working across the board" report turned out to be a partial hardware sweep that didn't explicitly cover the HDD-booted launch context. A fuller sweep later that day (with the cat keeping him company while his wife was on night shift) explicitly retested HOSDmenu → HDD-POPSloader → BOOT.ELF and wLE → HDD-POPSloader → BOOT.ELF — both black-screen. MC / USB / MX4SIO-rooted BOOT.ELF still work. The maintainer's "U-10 unexpectedly PASS" doc commit (in PR #475) was based on the partial sweep and is hereby reversed.
• Implications: U-10 stays in STATE.md / README.md / ROADMAP.md / TRUTHSHEET.md known-broken sections. docs/U10_INVESTIGATION.md status reverted from "PASS unexpectedly resolved" to "known broken — accepted". The hypothesis catalog in that doc is preserved. Maintainer hypothesis to investigate next (post-walkback): "maybe I need to reset IOP on boot or something before anything else" — aligns with H1 (DEV9 state survives SifIopReset) and H5 (stale pfs1: mount blocks the reset). claude/diag-u10 branch is preserved if a future agent wants to ship a diagnostic build.
• Evidence: QA_REGRESSION_MATRIX.md row "2026-05-28 PM late | Nuno (full hardware sweep)". Maintainer Discord/chat exchange 2026-05-28 PM: Nuno reported HDD-booted BOOT.ELF failures while testing exit conditions across devices ("Other devices memory card, usb and mx4sio exit boot.elf OK").

2026-05-28 PM — U-10 Unexpectedly Resolved; Known-Broken List Reduced to DKWDRV-HDD-Custom (WALKED BACK 2026-05-28 PM late — see entry above)

• Decision: Mark U-10 (BOOT.ELF from HDD-booted POPSLoader) as PASS in STATE.md, README.md, ROADMAP.md, TRUTHSHEET.md, and QA_REGRESSION_MATRIX.md. Remove the known-broken-accepted entry for U-10. Preserve docs/U10_INVESTIGATION.md and claude/diag-u10 branch in case of regression.
• Rationale: Nuno's 2026-05-28 PM hardware test on the rolling-release artifact built post-PR-#470/#472/#473 reports BOOT.ELF exit working "across the board" including HDD-booted POPSLoader. None of those PRs architecturally touch the U-10 path; the cause is not obvious. Candidate explanations: (a) C-layer EnsureUsbMass-first ordering in PR #472 incidentally cleans IOP state; (b) earlier "U-10 fails" reports were partially obscured by the now-fixed PR #473 boot crash; (c) test environment shifted. None of these is conclusive without further investigation.
• Implications: The only confirmed-broken edge case in BETA-10-5 + post-release work is DKWDRV from custom HDD path (re-confirmed broken by Nuno same session). HDD-install settings save to MC fallback is by design (PR #466), not a bug. The previously-noted wLE → USB POPSLoader → BOOT.ELF latent failure is covered by the "across the board" PASS.
• Implications (continued): Since the root cause of the resolution is not understood, treat U-10 as conditionally PASS. Any future change touching IOP teardown, mass-backend ordering, or BOOT.ELF launch routes should retest U-10 explicitly.
• Evidence: QA_REGRESSION_MATRIX.md row "2026-05-28 PM | Nuno on rolling-release". Maintainer report 2026-05-28 PM: "Everything is working except saving settings, and hdd custom path dkwdrv."

2026-05-28 PM — PR #470, #472, #473 Hardware-Verified

• Decision: Promote PR #470 (LAUNCH_ARGS consumers), PR #472 (MX4SIO evidence-based classification), and PR #473 (forward-reference hotfix) from Unknown (verify on hardware) to PASS in STATE.md and TRUTHSHEET.md.
• Rationale: Nuno's 2026-05-28 PM hardware test on the rolling-release artifact (commit 860ae26 from PR #471 branch, includes all merged BETA-12-PLAY changes plus Layer C mmceman defer) confirms: MX4SIO and USB working as intended, BOOT.ELF exit working across the board, DKWDRV from MC working regardless of POPSLoader boot source, USB sidecar settings save working. No boot crash.
• Implications: The post-release backbone is now hardware-validated. PR #471 (Layer C mmceman defer, currently DRAFT) is indirectly hardware-PASS for general boot + pad input; MMCE-specific device access from deferred-load state is the one untested case. Recommend an explicit MMCE test before promoting PR #471 from DRAFT.
• Evidence: QA_REGRESSION_MATRIX.md row "2026-05-28 PM | Nuno on rolling-release".

2026-05-28 — Layer C mmceman Lazy Load (PR #471, DRAFT)

• Decision: mmceman.irx is eagerly loaded at boot only when boot_device_hint == "MMCE"; for USB / MC / MX4SIO / HDD boots (all HDD root variants — hdd*, pfs*, ata*, apa*) the IRX is deferred and loaded on demand via System.ensureMmceman from PLDR.EnsureMmceReadyOnce.
• Rationale: MMCE third-party adapters (mmce0:/, mmce1:/) are a small subset of installs; loading the IRX eagerly for all boot types wastes ~50-100ms. MC (mc0:/, mc1:/, standard PS2 memory cards) is a distinct device handled by mcman/mcserv which are always loaded — MMCE and MC are not the same device.
• Implications: PR #471 is DRAFT. Hardware test must verify pad input survives on USB / HDD / MC boots (no IRX load order regression) and that MMCE-page entry from a deferred state correctly lazy-loads.
• Evidence: src/main.cpp line 446+, src/luasystem.cpp EnsureMmceman/MarkMmcemanLoaded, bin/POPSLDR/system.lua PLDR.EnsureMmceReadyOnce. PR #471, branch claude/curious-noether-3f2a8.

2026-05-28 — Lua Forward-Reference Hotfix (PR #473)

• Decision: Move local function ClassifyMassRootDriver declaration above ClassifyStartupMassTargets. Remove the duplicate later declaration.
• Rationale: Lua's local function f() is sugar for local f; f = function()...end; the local doesn't exist in scope until its declaration line. A caller declared above can't capture it as an upvalue and falls through to a global lookup (nil) at call time. Hardware regression 2026-05-28: rolling-release crashed on Enceladus boot with attempt to call a nil value (global 'ClassifyMassRootDriver'). Source-valid; runtime-broken; Lua syntax check did not catch it.
• Implications: Body unchanged. No behavior change other than the crash going away.
• Evidence: bin/POPSLDR/system.lua post-PR #473 has ClassifyMassRootDriver at line 3135, ClassifyStartupMassTargets at line 3146. PR #473 (claude/hotfix-classify-mass-root-driver), merged 2026-05-28T17:20Z.

2026-05-28 — MX4SIO Evidence-Based Mass: Classification (PR #472 + refinement 7b587fe)

• Decision: At boot, mass:/-prefixed devices are classified by the ioctl driver name returned by System.getMassMountDriver. sdc/mx4 → MX4SIO; any other non-empty driver → USB; empty ioctl → fall through to legacy markers, then USB default. mx4sio_bd.irx is only loaded on explicit MX4SIO evidence: mx4sio:/ prefix, sdc/mx4 ioctl driver, or .boot_mx4sio marker. AutoInitStartupBackends loads only usbmass_bd before the first classification pass; mx4sio_bd loads conditionally on the second pass when an ambiguous mass slot remains (mass_probe_needed).
• Rationale: Per maintainer 2026-05-28: "If ioctl/devctl is ANYTHING OTHER THAN sdc or mx4, and it's a mass device, then it is USB; if a mass device is sdc/mx4 on ioctl/devctl, then it must be MX4SIO." "MX4SIO should only init on startup if it came from mx4sio:/ or mass with sdc devctl." Mass mounting is volatile — the same path (mass:/, massN:/, mx4sio:/, usb:/) can be either backend depending on hotplug + IRX load order, and the ioctl driver name is the only authoritative classifier.
• Implications: USB boots never load mx4sio_bd. MX4SIO boots load mx4sio_bd conditionally after the ambiguity is detected. The .boot_mx4sio/.boot_usb markers remain as legacy fallback for extreme hardware quirks where ioctl never returns a driver.
• Evidence: bin/POPSLDR/system.lua classify_mass_boot, AutoInitStartupBackends, ClassifyStartupMassTargets. Maintainer refinement commit 7b587fe. PR #472 merged 2026-05-28T11:22Z.

2026-05-28 — mx4sio_bd Depends on usbmass_bd (Enforced at C Layer)

• Decision: lua_mx4sio_init in src/luasystem.cpp calls EnsureUsbMass() before loading mx4sio_bd.irx. The order is unviolatable from Lua.
• Rationale: Per maintainer 2026-05-28: "mx4sio will need the usb drivers to activate before it with it. USB will never need MX4SIO drivers." Multiple Lua call sites previously could load mx4sio_bd without first ensuring usbmass_bd was up; enforcing the order at the lowest level removes a class of bugs.
• Implications: Pure USB boots still never load mx4sio_bd (per the evidence-based classification rule above). When mx4sio_bd does load, EnsureUsbMass() is a cheap idempotent call (gated by usbmass_irx_loaded).
• Evidence: src/luasystem.cpp lua_mx4sio_init. PR #472 commit 357e3b8.

2026-05-28 — PLDR.LAUNCH_ARGS.game and -debug Consumers Wired (PR #470)

• Decision: Add PLDR.AutoLaunchFromLaunchArgs() — when both -page=<kind> and -game=<selector> are set, auto-launch via RunPOPStarterGame after AutoInitStartupBackends. Supports HDD (PARTITION|relpath), USB (FILE.VCD relative to mass:/POPS), MX4SIO, MMCE. Add PLDR.SurfaceLaunchArgsDebug() — when -debug is set, queue a boot-context toast showing kind, boot_path, sidecar_path, settings, and parsed launch args.
• Rationale: PR #458 / PR #462 shipped the LAUNCH_ARGS infrastructure (parser + carousel auto-nav) but the game and debug values were parsed without consumers. This PR completes the loop so NHDDL-style shortcuts (e.g. wLaunchELF entries launching POPSLoader with a specific HDD game) work end-to-end.
• Implications: On launch failure, AutoLaunchFromLaunchArgs falls through to the main menu with an error toast — default behavior unchanged when no -game= is passed. -debug is a low-cost runtime diagnostic that doesn't require rebuilding with DPRINTF enabled.
• Evidence: bin/POPSLDR/system.lua near line 5087+. PR #470 merged 2026-05-28T10:12Z.

2026-05-28 — Rolling Release Workflow Operational

• Decision: .github/workflows/rolling-release.yml publishes a POPSLOADER-rolling-release.zip asset to the canonical rolling-release GitHub Release on every push to BETA-12-PLAY and on every pull-request event (opened, synchronize, reopened, ready_for_review). The tag floats; testers grab the latest asset URL.
• Rationale: Testers (Nuno, CosmicScale) consume builds from a single stable URL. Manual artifact hosting is fragile. Last-write-wins semantics are acceptable because tester traffic is coordinated.
• Implications: PR builds AND the tracked-branch push builds both overwrite the same asset. Multiple in-flight PRs can churn the asset; the maintainer must coordinate which PR's build is current when sending a tester to the URL. Per-PR per-tag releases were considered and rejected in favor of the single-URL workflow.
• Evidence: .github/workflows/rolling-release.yml (added commit 761129a). Rolling Release URL: https://github.com/NathanNeurotic/POPSLoader/releases/download/rolling-release/POPSLOADER-rolling-release.zip.
• UPDATED (2026-06-21): the push trigger was repiped from BETA-12-PLAY to BETA-13-PLAY (.github/workflows/rolling-release.yml on.push.branches), since BETA-12-PLAY is now archival/frozen. The PR-event triggers (opened/synchronize/reopened/ready_for_review) and the single-asset/floating-tag mechanics are unchanged.

2026-05-28 — BETA-10-5 Hardware Confirmation (Nuno)

• Decision: BETA-10-5 release artifact at commit 9a0ebe2 is hardware-confirmed clean.
• Rationale: 2026-05-28 09:04 AM hardware test by Nuno verified: (a) BOOT.ELF exit OK, (b) HDD games load OK (D-10), (c) settings save from HDD-installed POPSLoader to MC works (sidecar fallback by design), (d) DKWDRV launch from default MC path OK. Known-broken items match documented expectations (DKWDRV-from-HDD-custom-path, U-10 BOOT.ELF-from-HDD-boot).
• Implications: D-10, D-14, D-15, DKWDRV-MC, BOOT.ELF (USB-booted), and HDD-install-settings-to-MC are now preservation contracts. Any future work must not regress these.
• Evidence: QA_REGRESSION_MATRIX.md row dated 2026-05-28.

2026-05-27 — BETA-10-5 Release Cut (v1.0.0-rev5, commit 9a0ebe2)

• Decision: Tag the stable backbone of post-March work as BETA-10-5 (v1.0.0-rev5). Publish GitHub release at https://github.com/NathanNeurotic/POPSLoader/releases/tag/BETA-10-5.
• Rationale: D-10/D-14/D-15 hardware-passing (B2 fix), DKWDRV-MC hardware-passing, BOOT.ELF (USB-booted) working via V2 route, per-device settings sidecar working for USB/MC/MMCE. The remaining items (DKWDRV-HDD-custom, U-10 BOOT.ELF-from-HDD-boot) had been investigated repeatedly without a stable fix; pragmatically accept them with workarounds rather than block the release.
• Implications: bin/changelog v1.0.0-rev5 entry; etc/boot.lua POPSLDR_VER bumped; STATE.md known-broken list refined.
• Evidence: PR #468 merged 2026-05-27. Tag BETA-10-5 at 9a0ebe2.

2026-05-27 — HDD Sidecar Disabled; Known-Broken Edge Cases Accepted (PR #466)

• Decision: HDD-installed POPSLoader saves settings to mc0:/POPSTARTER/.pldrs rather than pfs1:/<install dir>/.pldrs. ResolveBootContext returns sidecar_path = nil for any HDD-rooted APP_DIR (pfs%d*, hdd%d*, ata%d*, apa%d*). Document DKWDRV-from-HDD-custom-path and U-10 BOOT.ELF-from-HDD-boot as known-broken accepted for the release.
• Rationale: PR #459 had added pfs1: write support assuming etc/boot.lua's RW mount worked; Nuno's 2026-05-27 hardware test on PR #464 confirmed that pfs1:/.../.pldrs writes still fail with "may be read-only" despite the boot.lua path normalization. The bundled ps2hdd-osd.irx driver has read-write limitations we can't reliably work around without an IRX swap that risks regressing D-10. Per Nuno + maintainer 2026-05-27: "rollout dkwdrv; vast majority of users will have other devices for DKWDRV, small percentage have HDD installs". Shift from chasing edge-case bugs to shipping the stable backbone.
• Implications: HDD-installed POPSLoader is back to pre-PR-#459 settings-save behavior (no regression vs. legacy). Non-HDD installs (USB / MX4SIO / MMCE / MC) keep per-device sidecar. In-flight diag PR #463 and HDD r/w probe PR #465 closed as superseded; branches preserved.
• Evidence: bin/POPSLDR/system.lua ResolveBootContext (lines 1764+), PR #466 merged 2026-05-27.
• SUPERSEDED-BY (2026-06): the "HDD saves to mc0:" premise no longer holds. HDD installs now persist on the HDD boot partition via the EnsureBootPartitionWritable RW take-over (no mc0: fallback); provato confirmed HDD RW on hardware. See the 2026-06 "HDD Boot-Partition RW Take-Over" entry above and STATE.md > "Settings (single-device parity)".

2026-05-25 — NHDDL-Style Launch Argument Parsing (PR #458)

• Decision: main.cpp parseLaunchArgs() recognizes -page=<kind>, -mode=<kind> (NHDDL alias), -game=<selector>, -debug. System.getLaunchArgs() exposes parsed values to Lua. PLDR.LAUNCH_ARGS = {page, page_raw, game, debug} is normalized at module load.
• Rationale: CosmicScale requested -mode=ata for NHDDL parity. Generalizing to -page=/-game= lets users wire wLaunchELF entries directly to a specific device page or game. Page-only consumer (carousel auto-nav) landed in PR #462; game and debug consumers landed in PR #470.
• Implications: Default behavior unchanged when no flags are passed.
• Evidence: src/main.cpp parseLaunchArgs, src/luasystem.cpp lua_getLaunchArgs, bin/POPSLDR/system.lua LAUNCH_ARGS parser. PR #458, #462, #470.

2026-05-25 — Unified ResolveBootContext Resolver (PR #458)

• Decision: A single canonical Lua resolver ResolveBootContext() combines the C-side argv[0] classification hint (detectBootDeviceHintFromArgv0 / System.getBootDeviceHint), Lua-side prefix matching (mass/mmce/mx4sio/pfs/hdd/smb/host/usb/ata/apa), and the mx4sio mass:/ driver-identity refinement. DetectBootDevice, PLDR.GetBootContext, PLDR.GetBootKind, and the settings sidecar path all consume this one resolver.
• Rationale: Previously three near-duplicate detection paths drifted out of sync. Unification eliminates a class of "boot detection says X but settings think Y" bugs.
• Implications: Future device-detection changes happen in one place. New ps2sdk device-kind prefixes (usb, ata, apa) added without breaking the legacy mass/mmce/mx4sio/pfs/hdd/smb/host detection.
• Evidence: bin/POPSLDR/system.lua lines 1694+, src/main.cpp detectBootDeviceHintFromArgv0, src/luasystem.cpp lua_getBootDeviceHint. PR #458.

2026-05-25 — Per-Device Settings Sidecar with First-Run Migration (PR #459, PR #462)

• Decision: Settings persist at PLDR.SETTINGS_PATH, resolved at load time by LoadSettingsNonFatal. Sidecar at APP_DIR_LOCAL/.pldrs is preferred; legacy mc0:/POPSTARTER/.pldrs is fallback. First-run migration: when settings load from MC but a sidecar path is computable, pin PLDR.SETTINGS_PATH to the sidecar so the next save migrates. HDD-rooted APP_DIRs are excluded per the PR #466 decision above.
• Rationale: Old design hardcoded mc0:/POPSTARTER/.pldrs regardless of where POPSLoader was installed. Users with USB / MX4SIO / MMCE installs got their settings written back to the boot card unconditionally.
• Implications: USB / MX4SIO / MMCE installs keep their own settings without ever touching mc0:/POPSTARTER. HDD installs fall back to MC by design.
• Evidence: bin/POPSLDR/system.lua LoadSettingsNonFatal (migration via migrate_to_sidecar), SaveSettingsAtomic, ResolveBootContext (sidecar path computation). PR #459, #462.

2026-05-22 — Minimal B2 Dynamic PFS Unmount Production Fix

• Decision: Apply the B2 dynamic PFS unmount fix to the child loader pre-ExecPS2 sequence for HDD-backed POPSTARTER paths, bypassing the child loader's post-load IOP reset and re-initialization.
• Rationale: Target-side diagnostic sentinel testing proved that resetting the IOP post-load in the HDD-backed loader environment causes subsequent RPC/SIF handshake initialization (SifInitRpc) to hang due to the target partition remaining mounted. Dynamically unmounting only the exact target PFS mount prefix (e.g., pfs0:) resolved the hang and restored the handshake without needing a loader-side reset.
• Implications: HDD-backed POPSTARTER launches proceed with the standard SifLoadElf path but with PFS slot cleanup before ExecPS2. Non-HDD paths remain completely unaffected.
• Evidence: src/elf_loader/src/loader/src/loader.c, B2 diagnostic variant (artifacts/local-d10/20260522-122000-popsloader-hdd-preexec-unmount-target-pfs/POPSLOADER.ELF).

2026-03-06 — Lua runtime is embedded-only at boot

• Decision: boot and required runtime Lua modules are loaded from embedded blobs, not loose filesystem Lua files.
• Rationale: deterministic startup and fewer layout-dependent failures.
• Implications: editing runtime Lua requires rebuilding the ELF.
• Evidence: src/luaplayer.cpp, etc/boot.lua, Makefile.

2026-03-06 — Settings persist as a transaction on Settings/Profile exit

• Decision: settings edits are staged in UI draft state and committed on confirm/leave.
• Rationale: avoid repeated writes while navigating and keep save/apply failure handling explicit.
• Implications: runtime/UI state sync must still happen if save/apply fails.
• Evidence: bin/POPSLDR/ui.lua, bin/POPSLDR/system.lua.

2026-03-26 — USB vs MX4SIO identity is authoritative by mount driver

• Decision: mounted mass roots are classified by driver identity, not by path spelling.
• Rationale: real hardware can expose both USB and MX4SIO through mass*:/.
• Implications: startup auto-init, boot-device labeling, and page list building must continue to use mount-driver queries.
• Evidence: bin/POPSLDR/system.lua, src/luasystem.cpp.

2026-03-26 — Runtime device locks are no longer enforced

• Decision: the old per-session device lock system is no longer an active runtime constraint.
• Rationale: device access should not be blocked by stale lock state.
• Implications: docs must not claim that switching devices requires restart; future changes must not silently reintroduce that gate.
• Evidence: bin/POPSLDR/ui.lua (canEnterDevice, setDeviceLock).

2026-03-26 — Startup backend initialization is path-driven

• Decision: startup backend auto-init considers boot paths and configured executable/profile paths, not just the page the user opens first.
• Rationale: a configured POPSTARTER/DKWDRV/profile path can require backend drivers before any device page is visited.
• Implications: startup docs and validation must cover boot source plus configured paths, and HDD startup targets must run the full HDD module-load path rather than only low-level exec initialization.
• Evidence: bin/POPSLDR/system.lua (CollectStartupBackendTargets, AutoInitStartupBackends).

2026-03-26 — PAL UI uses the same 640x448 raster layout as NTSC-authored UI assets

• Decision: PAL mode keeps the UI raster at 640x448 instead of stretching the authored layout vertically.
• Rationale: reduce PAL squish on menus and authored UI assets.
• Implications: final on-TV proportions still require hardware confirmation.
• Evidence: bin/POPSLDR/system.lua, bin/POPSLDR/ui.lua.
• SUPERSEDED-BY (2026-06): PAL now renders natively at 640×512 (fills the screen, no letterbox) with an auto-reverting display-change confirm and an Auto Video-Standard default. See the 2026-06 "PAL Renders Natively at 640×512" entry above and STATE.md > "Video standard".

2026-03-26 — Release ZIP contract is strict and PATCH_5-based

• Decision: CI package includes exact PS1_POPSLOADER/* launcher files plus POPS/PATCH_5.BIN, now including PS1_POPSLOADER/BUILD_INFO.txt, and rejects legacy POPS/*.tm2 payloads.
• Rationale: prevent release drift and ambiguous installation instructions.
• Implications: docs and workflow validation must stay synchronized, and GitHub-built hardware candidates now carry a visible build stamp while CI also checks for expected embedded runtime markers before packaging.
• Evidence: .github/workflows/compilation.yml.

2026-03-29 — QA_REGRESSION_MATRIX.md is the detailed run ledger

• Decision: keep per-artifact hardware/CI chronology in QA_REGRESSION_MATRIX.md, while README.md, STATE.md, and ROADMAP.md summarize the stable current state and constraints.
• Rationale: repeated experiment history had started drifting across the root docs and obscuring the actual current handoff state.
• Implications: root docs should point to the matrix for detailed chronology instead of carrying their own competing mini-ledgers.
• Evidence: repository documentation audit on 2026-03-29.

2026-05-13 — Separate build/package CI from comment-triggered AI automation

• Decision: treat .github/workflows/compilation.yml as the build/package validation source of truth, and document .github/workflows/opencode.yml separately as comment-triggered repository automation.
• Rationale: the opencode workflow can affect repository collaboration but does not build artifacts, enforce the release ZIP contract, or prove runtime/hardware behavior.
• Implications: source-truth audits should include both workflow files, while CI/package claims should continue to cite only the compilation workflow unless the automation contract changes.
• Evidence: .github/workflows/compilation.yml, .github/workflows/opencode.yml.

2026-05-19 — Default cover image is optional at compile time

• Decision: bin/POPSLDR/IMG/default.png is optional. CI/artifact builds without it omit asset_default_png and fall back to the required MISSING.png asset for IMG.default.
• Rationale: default cover art should only be embedded when the PNG is present in the checkout used by GitHub Actions.
• Implications: at the time, MISSING.png remained required; default.png could be removed without breaking artifact builds.
• SUPERSEDED (2026-06-21, 56a5ad5 — see the layered cover-art decision above): MISSING.png was removed entirely. IMG.default no longer falls back to it (IMG_FALLBACKS is now empty); default.png stays an optional compile-time embed but with no fallback target, and the no-cover / preview-off states use cover_default.png + cover_missing.png.
• Evidence: Makefile, src/embed_assets.cpp, bin/POPSLDR/images.lua, bin/POPSLDR/ui.lua.
• SUPERSEDED-BY (2026-06-21): MISSING.png is removed entirely (−62KB). The no-cover placeholder is now the layered cover_default.png (base) + cover_missing.png (overlay-when-preview-enabled); the default.png-optional / asset_default_png mechanism is unchanged (default.png is still optional, embedded only when present). See the 2026-06-21 "Layered Cover-Art Placeholder" entry above.

Archived Investigations

The investigations below were active during the March–May 2026 development cycle and are now largely resolved by the BETA-10-5 release. They are preserved verbatim for historical context and to document the diagnostic chain that produced the B2 fix at commit 4ae6679 (D-10) and the V2 BOOT.ELF route at commit d23520a (L-07). For the current state, see STATE.md (current state, hardware status, and known issues) and QA_REGRESSION_MATRIX.md.

• HDD startup auto-init on HDD boot/configured paths:
• a 2026-03-27 hardware report said booting from HDD did not auto-init the HDD driver stack.
• current code had detected HDD startup targets correctly but only called EnsureHddRuntimeReadyForExec(), which stops at low-level HDD.Initialize().
• current source now routes HDD startup targets through PLDR.LoadHDDModules() so startup uses the same HDD status/partition/cache initialization path as the HDD page.
• a later boot-time report showed that using the full HDD page path at startup also caused large HDD libraries to spend boot time scanning partitions and building the games list.
• current source therefore keeps startup HDD auto-init limited to runtime readiness only; partition scanning and game-list building remain page-entry work.
• optional HDD cache writing now reuses the page-built game list instead of rebuilding one during startup.
• later 2026-03-28 hardware reports on that narrowed boot-time split source still said HDD-backed startup/Profile POPSTARTER could disappear after entering the USB page before the HDD page.
• the raw boot APP_DIR fallback alone did not restore that case.
• current source therefore 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 later POPSTARTER/Profile resolution from USB or other pages uses the same runtime init path as HDD page entry.
• repo inspection also showed the startup HDD warm-path list had been skipping Profile 1/default relative POPSTARTER.ELF because it only recorded explicit hdd: / pfs: paths, so current source now includes that default-relative case when boot source is HDD.
• repo inspection of etc/boot.lua also showed HDD boot is established on a dedicated pfs1: mount before system.lua runs, so current source now 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 assuming low-level HDD readiness alone preserves the boot-side path contract.
• 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, so the remaining blocker is no longer startup/Profile lookup.
• USB first-entry 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 code already had bounded retry loops for USB root discovery, but all retries happened back-to-back with no yield for the backend to become visible.
• current source now adds a bounded wait only in BuildUsbIdentityDeferred(), leaving MX4SIO discovery logic unchanged.
• user later confirmed the corrected source on hardware.
• HDD POPSTARTER.ELF when launcher/sidecar/CWD is on HDD:
• current reported hardware result is still a black-screen hang.
• path/mount/CWD mitigations plus the HDD-backed non-reboot ExecPS2 cleanup are present in current code.
• a 2026-03-27 hardware re-test of the current source still black-screened with boot source HDD, default/Profile 1/cwd/sidecar POPSTARTER.ELF on HDD, and game device HDD.
• a second 2026-03-27 hardware report also black-screened while launching a USB game with Profile 2 pointing POPSTARTER.ELF to HDD, so the remaining failure is now treated as the HDD-backed POPSTARTER exec path itself rather than only HDD game routing.
• a later 2026-03-27 hardware report also said booting from another device and launching an HDD title with sidecar POPSTARTER.ELF on that boot device black-screened, and the user identified it as a regression.
• the EE-side HDD direct-load workaround in src/elf_loader/src/elf.c has therefore been reverted; it did not fix D-10 and is no longer supported by hardware evidence.
• later 2026-03-27 Memory Card staging, stripped-handoff, CWD/selector, and HDD-init-state experiments in bin/POPSLDR/system.lua did not fix D-10 / D-14 and coincided with repeated D-15 failures.
• user later confirmed on 2026-03-28 that USB boot + USB sidecar/cwd POPSTARTER.ELF + HDD game passes on the narrowed source, so the remaining blocker is again isolated to HDD-backed POPSTARTER.ELF.
• a later 2026-03-28 re-test still black-screened on that narrowed Lua-side source with no visible positive change, so the next shared preservation step tested was the loader's automatic post-load exec-slot keep in src/elf_loader/src/elf.c.
• that loader-side no-auto-exec-slot-preserve source still left non-HDD POPSTARTER HDD-game launches on the restored selector-only handoff, while R2 could still request the explicit hdd0:PART:pfs0:/GAME.ELF selector.
• a later 2026-03-28 re-test on that loader-side source still black-screened for D-10 on both X and R2, and the user clarified the other same-day success result was another D-15 run rather than D-14.
• a later 2026-03-28 re-test on that forced-reboot_iop = 1 source still black-screened for D-10 and D-14, so reboot mode alone did not separate the remaining failure.
• a later 2026-03-28 re-test on that direct-hdd0:PART:pfsN:/POPSTARTER.ELF preference source still black-screened for both D-10 and D-14, so exec-path form alone did not separate the remaining failure.
• follow-up repo inspection then found BuildDirectHddExecPathFromMounted() had been generating malformed direct aliases without the colon after pfsN, so that earlier direct-path experiment was not a clean control.
• inspection of wLaunchELF and PlayStation2-Basic-BootLoader-Extended showed the common HDD ELF pattern is to mount the target partition explicitly and feed SifLoadElf a mounted pfs0:/... path rather than a direct hdd0: path.
• a later 2026-03-28 re-test on that mounted-pfs0: embedded-loader source still black-screened for D-10.
• broader comparison then showed current HEAD had drifted away from this repo's own March 24 partitioned-loader diagnostics by reintroducing SifExitRpc() immediately before the parent ExecPS2 into the embedded loader.
• this repo's earlier HDD diagnostics also recorded that the embedded-loader boundary only became stable once EE-side SIF teardown before ExecPS2 was removed from the parent handoff.
• comparison against wLaunchELF and PlayStation2-Basic-BootLoader-Extended also showed another remaining mismatch: this repo's embedded loader had no separate original HDD source-context argument, so it could only make reset decisions from the mounted pfs0:/... load target.
• follow-up repo comparison then showed the remaining source-context gap was broader than the loader alone: Lua had usually already normalized HDD POPSTARTER to mounted pfs1: / pfs3: paths before the reboot loader saw it, so the loader was still not being given the original HDD path it needed to force the pfs0: remount pattern used by wLaunchELF.
• broader comparison against wLaunchELF also showed the remaining ownership mismatch was not just reset policy: the parent/loader boundary there does not pre-unmount PFS state and the embedded loader calls SifLoadElf directly after SifInitRpc(0), without SifLoadFileInit/Exit.
• a later 2026-03-28 re-test on that exact-boot-mount/source-context source still black-screened for D-10, so full raw-source reconstruction alone was still not the missing link.
• repo comparison against the local ps2sdk tree then showed the remaining drift was structural: the header still documented a partition-aware loader contract, but the live reboot path was still using a custom source-context channel instead of the same partition/load-path/argv split.
• current source therefore keeps the restored non-HDD POPSTARTER path, seeds the exact boot pfs1: mount metadata from etc/boot.lua into Lua-side HDD mount tracking, and replaces that ad hoc reboot handoff with an explicit partition-aware contract across bin/POPSLDR/system.lua, src/luasystem.cpp, src/elf_loader/src/elf.c, and src/elf_loader/src/loader/src/loader.c.
• on that contract, Lua passes exact HDD partition context separately from the mounted load path, normalizes the partition-aware exec filename back to generic pfs:/..., routes HDD partition-aware launches through cold external-launch prep so the old tracked pfsN: mount is not preserved into exec, and the parent remounts pfs0: from that partition while reusing the mounted relpath Lua already resolved.
• a 2026-03-29 hardware result on the prior partition-aware source no longer black-screened, but the launcher regained control with rc=-1 (returned after 22618 ms), which meant that specific artifact had moved the remaining failure past the old black-screen boundary and into the embedded-loader or target-ExecPS2 handoff.
• 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.
• repo history comparison then showed that this partition-aware reboot path had drifted away from the original parent-side embedded-loader jump contract in src/elf_loader/src/elf.c: it no longer performed the BRAM wipe or the original SifInitRpc/SifLoadFileInit/SifLoadFileExit and SifExitIopHeap/SifExitRpc/SifExitCmd sequence around that final ExecPS2.
• repo history comparison also showed that earlier child-loader fileXio experiments had never been retested after the later parent-side jump-contract fixes, so they were not a clean control for the current boundary.
• later repo audit also showed that POPSLoader's normal POPSTARTER launch path passes only the selector as target argv[0], while the newer HDD child-loader path had started prepending a replacement executable path; that changed the HDD-backed POPSTARTER argv layout away from the working non-HDD path.
• repo audit also found that selected-profile state and stored canonical profile paths could drift apart, so a chosen Profile 1/default path could still launch another profile's canonical HDD POPSTARTER path without the user realizing it.
• current source restores that original parent-side jump contract, 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, aligns the child loader closer to wLaunchELF / PlayStation2-Basic-BootLoader-Extended by removing the post-reset MC module reload and exiting SIF command state before the final target ExecPS2, routes partition-aware HDD launches through the explicit System.loadELFWithPartition(path, reboot_iop, partition_context, selector) API and mounted-pfs0: SifLoadElf once the parent has already remounted the target partition, normalizes stale canonical profile-path state before launch/save, keeps the older iomanX-aware fileXio path only for direct pfs: / hdd: loads with no partition-aware HDD context, and now exposes the real exec filename separately from the probe/open path in the launcher popup.
• 2026-05-19 source audit found that several current-source defects must be fixed before treating new hardware results as clean controls: 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, the generic embedded-loader default-argv contract is unreachable, and the child loader still uses snprintf/strncat despite older docs claiming that risk was avoided. See docs/archive/HDD_POPSTARTER_HANDOFF.md.
• 2026-05-19 source change applies the handoff's recommended fixes (except for the child-loader snprintf/strncat cleanup, which would require regenerating the embedded loader blob and was intentionally deferred):
  1. bin/POPSLDR/system.lua adds NormalizeHddPartitionLabelForMount so ResolveFallbackMountedPfsExecPath accepts the bare partition labels (e.g. __.POPS) returned by ParseHddGameEntry. Previously the fallback parsed only hdd0:-prefixed labels and always failed for normal HDD game entries.
  2. RunPOPStarterGame now resyncs context.exec_path/exec_partition_context/exec_mounted_path/exec_original_slot/exec_pfs_slot/source_pfs_slot/cold_external_launch/keep_hdd_slots/keep_hdd_slots_after_load and the matching launch_diagnostics fields after a successful fallback, so LaunchEngine no longer consumes stale pre-fallback values.
  3. The HDD pre-exec gate is skipped only when the fallback actually reconstructed a partition-aware path; if reconstruction failed in non-strict mode, the gate now runs so its own partition-recovery logic can succeed or fail loudly instead of silently launching with stale context.
  4. src/luasystem.cpp exposes System.loadELFWithPartition(path, reboot_iop, partition_context, args...). The legacy System.loadELF trailing partition_context detection has been removed; partition_context can no longer be copied into target argv. LaunchEngine calls the new binding when context.exec_partition_context is set.
  5. src/elf_loader/src/elf.c ExecuteViaEmbeddedLoader no longer rejects argc == 0, so the documented child-loader default-argv synthesis (build_default_target_arg0) is reachable. The HDD POPSTARTER-specific argv[0] guard in ExecuteHddBackedViaEmbeddedLoader is intentionally left in place.
• a 2026-05-20 artifact screenshot then showed D-10 returning to the launcher with POPSTARTER HDD pre-exec gate failed: Cannot resolve HDD partition context, POP:pfs3:/POPS/POPSTARTER.ELF, and APP:hdd0:+OPL:pfs:/APPS/PS1_POPSLOADER/.
• 2026-05-20 source follow-up fixes the argument-shifted failure popup call sites, lets Lua parse hdd0:PART: partition-context strings, lets shared HDD recovery candidates accept safe bare labels such as __.POPS, and changes mounted-PFS fallback to recover the actual mounted POPSTARTER source partition before falling back to the selected HDD game partition. It does not change the POPSTARTER selector argv[0] contract.
• a 2026-05-20 latest-artifact D-15 report then showed USB boot with USB sidecar/cwd POPSTARTER.ELF plus an HDD title black-screening. Current source follow-up restores legacy System.loadELF(path, reboot_iop, selector) one-argument selector behavior for normal/non-HDD POPSTARTER launches and keeps HDD partition context on System.loadELFWithPartition(...).
• a later 2026-05-20 readable-diagnostic screenshot then showed the pre-exec gate failing on the loader-facing generic exec path pfs:/POPS/POPSTARTER.ELF; source now derives a real mounted probe path for ValidateHddPopstarterExecGate() while keeping the generic pfs:/... exec path for the partition-aware C loader contract.
• a later 2026-05-20 report narrowed the non-HDD POPSTARTER regression to default/cwd sidecar resolution: explicit mass:/POPS/POPSTARTER.ELF launches, but default POPSTARTER.ELF can stop at Cant find POPSTARTER ELF. Current source now includes the live current directory in sidecar lookup and derives fallback sidecar paths from boot/app directories instead of blindly appending to raw boot strings.
• 2026-05-20 simplification pass addresses the over-engineering risk: normal HDD-backed POPSTARTER launches no longer use Lua partition context, generic pfs:/... exec rewriting, the Lua HDD pre-exec gate, the mounted-PFS fallback remount path, or the embedded-loader reboot path by default. They keep the resolved executable path and call legacy System.loadELF(path, 0, selector).
• a 2026-05-20 hardware result on that direct non-reboot artifact still black-screened before POPSTARTER debug screens, so the next source pass removes the remaining HDD-only parent-side pre-ExecPS2 cleanup from LoadELFFromFileExecPS2() (fileXioUmount, SifExitIopHeap, SifExitRpc, SifExitCmd) to match the working non-HDD POPSTARTER handoff more closely.
• hardware status after the 2026-05-20 source follow-up remains Unknown (verify on hardware). The handoff doc verification sequence (D-15 first, then D-10 X, then D-10 R2, then D-14, then D-12 sanity, then U-10 separately) still applies.
• current source still keeps the R2 selector-path experiment for HDD game launches, but that remains secondary to restoring and preserving the non-HDD POPSTARTER baseline for HDD titles.
• BOOT.ELF after HDD page init:
• repo history shows the BOOT.ELF modal originally used a simpler non-reboot System.loadELF(elf_path, 0, elf_path) path without launch-CWD setup, and later source changed it to reboot_iop = 1 plus launch-CWD.
• a later 2026-03-29 hardware report said BOOT.ELF still behaved incorrectly once HDD runtime had been initialized, which points more narrowly at carried HDD/IOP state than BOOT.ELF lookup itself.
• current working inference is that this U-10 failure may share the same underlying handoff/state-poisoning boundary as D-10, but that remains an inference rather than a proven shared root cause.
• current source therefore 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 hardware status on that conditional-reboot/cold-prep source is still Unknown (verify on hardware).
• PAL asset proportions:
• code compensates for PAL layout,
• final display result still needs hardware confirmation.
• 2026-05-22 Diagnostic Sentinels & USB Control Test Decision:
• A series of targeted sentinels were executed to debug the post-load/post-reset SIF RPC handshake hang (Teal/Blue freeze) on D-10.
• SifLoadFile (SENTINEL_SIFLOADFILE_POPSTARTER.ELF) and fileXioInit (SENTINEL_FILEXIOINIT_POPSTARTER.ELF) sentinels passed on hardware, showing that initial target-side setup and fileXio services are fully stable post-handoff.
• Post-reset SifInitRpc sentinels (TARGET-IOPRESET, POST-RESET INITCMD SPLIT, and POSTINITCMD RPCMODE1) hung, proving the rebooted IOP fails to respond to RPC initialization.
• Manual RPCINIT handshake probing and retry sentinels timed out, confirming the IOP does not signal SIF_SREG_RPCINIT after resetting.
• Resetting the IOP with UDNL arguments (SifIopReset("rom0:UDNL rom0:EELOADCNF", 0)) via SENTINEL_TARGET_IOPRESET_UDNL_RPCINIT_POPSTARTER.ELF also timed out (PURPLE/MAGENTA loop), ruling out the blank reset argument as the sole cause of the SIF handshake hang.
• The USB control path (USB POPSLOADER.ELF + USB sidecar/CWD POPSTARTER.ELF) was verified on hardware to work successfully, including when selecting games from the HDD listing.
• Source/Device Boundary established:
  • Known-good: USB POPSLOADER.ELF + USB sidecar/CWD POPSTARTER.ELF works, including when selecting HDD games.
  • Known-bad: HDD POPSLOADER.ELF + HDD sidecar/CWD POPSTARTER.ELF fails. HDD POPSTARTER.ELF fails regardless of selected game device/listing.
  • Interpretation: The failure does not follow the selected game device or the HDD game listing by itself. The failure follows the HDD-backed POPSTARTER / HDD-backed loader-origin state.
• Updated Diagnostic Boundary: The next investigation focuses on what differs when POPSTARTER.ELF is resolved, loaded, and executed from HDD versus USB sidecar/CWD, including file-open/mount state, current working directory/source device state, argv/environment passed to POPSTARTER, and IOP module state left behind by loading the target ELF from HDD.

2026-07-28 — Adaptive BDMA now defaults ON, and -bdma=<mode> can pin the variant

• Decision: PLDR.BDMA_ADAPTIVE ships On, superseding the 2026-07-09 "default Off, user opts in" call. A new launch argument -bdma=fat32|usbexfat|mx4sio|mmce|ata pins the staged variant for that session and overrides Adaptive's per-device choice.
• Rationale: CosmicScale (2026-07-28) reported that POPSLoader never installs the BDM Assault drivers for ATA. It never installs them for anything: MaybeApplyAdaptiveBdma returns immediately unless BDMA_ADAPTIVE is true, and it shipped false, so the entire feature was inert on a stock install. The machinery was complete and correct — ATA has its .ata suffix and both asset_usbd_irx_ata/asset_usbhdfsd_irx_ata embeds — it was one boolean away from working, gated behind a setting users had no reason to know existed. The half-created state (folder + .icn/icon.sys present, drivers absent) reads as a broken feature rather than an unconfigured one. Verified identical between 2270cec (1.1.0) and dev, so this was never a regression — it has never worked out of the box.
• Implications: every launch now stages a variant unless the user opts OUT (Settings → Adaptive BDMA), including the exFAT pair on a FAT32 USB stick — that pair reads FAT32 too, which is why one variant serves every stick. The maintainer flagged rumours of games (Soul Blade) disliking any BDMA variant; the mitigation is per-game fixes or 32KB clusters, and opting out remains one toggle. -bdma= is normalised by NormalizeBdmaModeKey, so an unrecognised value is IGNORED rather than pinning something bogus. Reset-to-defaults in ui.lua now restores On.
• Evidence: bin/POPSLDR/system.lua (PLDR.BDMA_ADAPTIVE, PLDR.LaunchArgBdmaMode, ResolveAdaptiveBdmaTarget), src/main.cpp (-bdma= parse), src/luasystem.cpp (lua_getLaunchArgs), harness T48.