pokemon/gen1recomp
1
0
Fork 0
mirror of https://github.com/bryanthaboi/gen1recomp.git synced 2026-08-12 08:21:02 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
a8f3a3155c8c12f7742d5f258c7fb17e28254780
gen1recomp/.specs/STATE.md
T
Andrew Quenehen a8f3a3155c fix(nx): harden save inbox against slot clones 
Retire successful imports to *.sav.imported and record content hashes so
re-pressing Import save (or the same bytes under a new name) cannot clone
slots. Surface multi-import counts and the active game tab in the notice.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-03 08:26:56 -03:00

8.6 KiB
Raw Blame History

STATE

Decisions

AD-001

  • Decision: The Nintendo Switch port runs on pinned love-nx (initially tag 11.5-nx1 with SHA-256-pinned love.nro/love.elf), not a native libnx/NVK rewrite.
  • Reason: Gen1Recomp already boots under love-nx; video/audio/input/FS are provided; keeps the patch small and upstreamable.
  • Trade-off: Native defects may later require a love-nx fork; deferred until a minimal probe proves the bug is below Lua.
  • Scope: All Switch packaging, runtime, and diagnostics work
  • Date: 2026-08-01
  • Status: active

AD-002

  • Decision: Platform differences are expressed as capability queries in src/core/Platform.lua (e.g. romImportMode, canSpawnProcess, networkValidated), never by overloading Android flags for NX.
  • Reason: Reusing self.android would trigger mobile side effects such as deleting a user-copied ROM.
  • Trade-off: Slightly more refactor in RomImporter than a one-line OS check.
  • Scope: Import, updater, shell, conf, any getOS branching
  • Date: 2026-08-01
  • Status: active

AD-003

  • Decision: On NX, ROM import uses a writable inbox under love.filesystem.getSaveDirectory()/imports/ with explicit rescan; no Horizon native file picker.
  • Reason: love-nx/Gen1Recomp have no usable Switch picker; issue #531 fails before gameplay.
  • Trade-off: Users must copy dumps via MTP into the shown path.
  • Scope: RomImporter UI and scan logic on Switch
  • Date: 2026-08-01
  • Status: active

AD-004

  • Decision: All Mac↔Switch file transfer for NROs, game.love, ROMs, logs, and crash reports uses OpenMTP + DBI Run MTP responder on 1: SD Card only (no SD removal, Finder mount, FTP, or nxlink artifact transport).
  • Reason: Keeps the SD in-console and matches the operator’s established workflow; avoids false POSIX assumptions.
  • Trade-off: Transfers are manual/UI-driven; scripts verify hashes locally, not via /Volumes.
  • Scope: Development runbooks, release deploy, diagnostics collection
  • Date: 2026-08-01
  • Status: superseded by AD-009

AD-005

  • Decision: Release ships a single fused gen1recomp.nro (game.love in romfs); loose nro+game.love is development-only. Payload must never contain ROM, extracted cache, or saves; CI/release pins love-nx and fails on checksum/payload violations.
  • Reason: Prevents version skew for players and preserves the project’s legal/technical model.
  • Trade-off: Fused builds need devkitPro/container (nacptool/elf2nro).
  • Scope: scripts/build_switch.sh, verify gates, release artifacts
  • Date: 2026-08-01
  • Status: active

AD-006

  • Decision: On NX, community mod .zip import uses a writable inbox at love.filesystem.getSaveDirectory()/imports/mods/ with explicit rescan; separate from ROM imports/.
  • Reason: Mirrors AD-003 without mixing ROM dumps and mod archives; no Horizon picker.
  • Trade-off: Users must MTP zips into the shown path; FIND MODS remains off (networkValidated).
  • Scope: RomImporter MODS tab, Switch docs, related NX tests
  • Date: 2026-08-01
  • Status: active

AD-007

  • Decision: Switch fused packaging uses host nacptool/elf2nro when available (including via $DEVKITPRO/tools/bin), then falls back to Docker using the image pin in scripts/switch/dkp-docker.image (override GEN1_DKP_IMAGE); CI never compiles love-nx from source.
  • Reason: Matches contributor decision 2B and Mac self-hosted release (3A) while staying portable when only Docker exists.
  • Trade-off: Two packaging paths to maintain; Docker bind-mount quirks on some Windows bash setups.
  • Scope: scripts/build_switch.sh, scripts/switch/build_fused.sh, release Switch artifact, switch-build docs
  • Date: 2026-08-01
  • Status: active

AD-008

  • Decision: Switch packaging entrypoints remain bash scripts; supported Windows hosts are Git Bash, MSYS2 (devkitPro), or WSL — not cmd.exe or PowerShell-native rewrites.
  • Reason: All existing pack/release scripts are bash; a parallel PowerShell stack would diverge.
  • Trade-off: Windows contributors must use a bash environment (documented in switch-build.md).
  • Scope: Switch build scripts and docs; any future NX packaging helpers
  • Date: 2026-08-01
  • Status: active

AD-009

  • Decision: Canonical Switch file transfer for NROs, loose game.love, ROM inbox, mod zips, logs, and crash pulls is any method that lands bytes at the documented SD / save-dir paths: MTP (e.g. DBI Run MTP responder + an MTP client), direct SD (Hekate UMS and/or physical microSD reader), or FTP (any Switch-side FTP homebrew that exposes the SD). macOS + OpenMTP is one documented example, not the product contract. nxlink / hbmenu netloader remains deferred — not a supported path yet (future contributor fast-loop only).
  • Reason: Contributors on Linux/Windows (and Mac users who prefer UMS/FTP) must not be blocked by an OpenMTP-only narrative; destinations matter, not the host tool.
  • Trade-off: More transfer recipes to maintain; FTP/SD details stay destination-first with example apps only. No automated push scripts in this decision.
  • Scope: Switch transfer/install/development docs, contributor runbooks, future deploy tooling decisions
  • Date: 2026-08-01
  • Status: active

AD-010

  • Decision: Switch CI mirrors the iOS safety net: path-gated offline selftest on ubuntu-latest for all repos (forks included); fused --fetch --fused + artifact gen1recomp-switch-nro only on the canonical repo (bryanthaboi/gen1recomp) self-hosted Mac runner; PR artifact comment mirrors iOS (switch-build-result); release Switch remains a hard-fail gate (no continue-on-error).
  • Reason: Catch packaging regressions before merge without requiring Switch toolchain on hosted runners for forks; keep ship integrity on main while giving maintainers a downloadable fused NRO on path-gated PRs.
  • Trade-off: Extra self-hosted Mac CI when Switch paths change on the canonical repo; forks never get a fused CI artifact.
  • Scope: .github/workflows/ci.yml, switch-artifact-comment.yml, release.yml Switch step, Switch CI docs
  • Date: 2026-08-02
  • Status: active (amended by AD-011 for fork→canonical PRs)

AD-011

  • Decision: Switch fused CI (switch-build) runs on the canonical self-hosted Mac only when the workflow head is the canonical repo: same-repo push/PR. Fork→canonical pull requests skip Switch fused (ubuntu selftest still runs). iOS ios-build eligibility is unchanged by this decision.
  • Reason: Avoid executing untrusted fork head packaging scripts on the self-hosted Mac while keeping offline Switch verification for external PRs.
  • Trade-off: Reviewers do not get a Switch NRO artifact on fork PRs; they still get selftest + (when iOS paths change) iOS artifacts as before.
  • Scope: .github/workflows/ci.yml switch-build if:, Switch CI docs
  • Date: 2026-08-02
  • Status: active

AD-012

  • Decision: On NX, raw Gen1 .sav import uses a writable inbox at love.filesystem.getSaveDirectory()/imports/saves/ with Import save ensuring the dir and rescanning into the active game tab; export success surfaces exports/ via an MTP path notice (no openURL / Open folder). Resilience guards RES-01..11 apply. After a successful import the live .sav is retired to *.sav.imported and its content hash is recorded in imports/saves/.imported-sha1 so re-press / same-bytes-new-name cannot clone slots; failures leave the original file.
  • Reason: love-nx has no usable Horizon file picker (same scar as AD-003/AD-006); players need MTP/SD/FTP parity for continuing cart/PC saves and pulling slots off-console. Unlimited re-import of a retained .sav was a slot-clone footgun.
  • Trade-off: Users must copy .sav into the shown inbox and pull exports manually; desktop/Android picker paths stay unchanged; retired .imported files may accumulate until the player deletes them.
  • Scope: RomImporter SAVE FILES on Switch, Switch install/transfer/development/launcher docs, tests/rom_importer_nx_saves_inbox_test.lua
  • Date: 2026-08-03
  • Status: active (amended 2026-08-03 — retire + hash dedupe)

Handoff

  • Feature: switch-save-sav-inbox / .specs/features/switch-save-sav-inbox
  • Phase / Task: Execute COMPLETE — Verifier PASS ✅
  • Completed: T1–T6 + fix fe4491a; commits 3c62814 5d1e7ff 74f6b68 4afb54c 7e0c64c 8120f11 fe4491a 62ef647
  • In-progress: none
  • Next step: Push / include in Switch PR when ready; HW smoke optional (P2)
  • Blockers: none
  • Branch: feat/switch-nx
  • Report: .specs/features/switch-save-sav-inbox/validation.md
Reference in New Issue View Git Blame Copy Permalink