Add playthrough storage and legacy selected-save access

.github/workflows/api3-contract.yml

@@ -0,0 +1,56 @@
+name: API 3 contracts
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/api3-contract.yml'
+      - 'src/**'
+      - 'tests/api3_contract/**'
+      - 'tests/engine/api3_*.lua'
+      - 'tools/api3-contract-check/**'
+  push:
+    branches: [main, dev]
+    paths:
+      - '.github/workflows/api3-contract.yml'
+      - 'src/**'
+      - 'tests/api3_contract/**'
+      - 'tests/engine/api3_*.lua'
+      - 'tools/api3-contract-check/**'
+permissions:
+  contents: read
+concurrency:
+  group: api3-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  compare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: gen2
+          sparse-checkout: |
+            src
+            data
+            tests
+            tools/api3-contract-check
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36
+          path: gen1-reference
+          sparse-checkout: |
+            src
+            data
+            tests
+            assets/fonts
+      - name: install LuaJIT
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: identical mod contracts on both engines
+        run: >-
+          python3 gen2/tools/api3-contract-check/check.py
+          --gen1 gen1-reference --gen2 gen2
+          --report "${{ runner.temp }}/api3-report.json"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: api3-contract-report
+          path: ${{ runner.temp }}/api3-report.json
+          if-no-files-found: error

.github/workflows/battle-auxiliary-contract.yml

@@ -0,0 +1,50 @@
+name: portable battle.menu_auxiliary contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: battle-auxiliary-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36
+          path: .contract-reference/gen1
+      - name: Install ROM-free test runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check native auxiliary battle dispatch and SDK contracts
+        run: |
+          luajit tests/engine/battle_auxiliary.lua
+          luajit tests/engine/trainer_preparation.lua
+          luajit tests/engine/trainer_preparation_native.lua
+          luajit tests/engine/trainer_party_scope.lua
+      - name: Validate pinned native Gen1 auxiliary battle contracts
+        working-directory: .contract-reference/gen1
+        run: |
+          luajit tests/modkit/cases/unified_gen2_hooks.lua
+          luajit tests/modkit/cases/unified_gen3_hooks.lua
+      - name: Compare both engines in every SDK mode
+        run: |
+          mkdir -p /tmp/battle-auxiliary-contract
+          python3 tools/battle-auxiliary-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 1 --report /tmp/battle-auxiliary-contract/api1-native.json
+          python3 tools/battle-auxiliary-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --report /tmp/battle-auxiliary-contract/api2-native.json
+          python3 tools/battle-auxiliary-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --format unified --report /tmp/battle-auxiliary-contract/api2-unified.json
+          python3 tools/battle-auxiliary-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --report /tmp/battle-auxiliary-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: battle-auxiliary-contract
+          path: /tmp/battle-auxiliary-contract
+          if-no-files-found: ignore

.github/workflows/battle-bottom-ui-contract.yml

@@ -0,0 +1,49 @@
+name: portable battle.bottom_ui_visible contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: battle-bottom-ui-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36
+          path: .contract-reference/gen1
+      - name: Install ROM-free test runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check bottom UI, inherited overlays and native battle composition
+        run: |
+          luajit tests/engine/battle_bottom_ui.lua
+          luajit tests/engine/battle_bottom_ui_routing.lua
+          luajit tests/engine/battle_bottom_ui_composition.lua
+      - name: Validate pinned native Gen1 GBA battle UI
+        working-directory: .contract-reference/gen1
+        run: luajit tests/modkit/cases/unified_gen3_battle_hooks.lua
+      - name: Compare native API 1 and 2
+        run: |
+          mkdir -p /tmp/battle-bottom-ui-contract
+          python3 tools/battle-bottom-ui-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 1 --report /tmp/battle-bottom-ui-contract/api1-native.json
+          python3 tools/battle-bottom-ui-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --report /tmp/battle-bottom-ui-contract/api2-native.json
+      - name: Compare unified callbacks and API 3
+        run: |
+          python3 tools/battle-bottom-ui-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --format unified --report /tmp/battle-bottom-ui-contract/api2-unified.json
+          python3 tools/battle-bottom-ui-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --report /tmp/battle-bottom-ui-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: battle-bottom-ui-contract
+          path: /tmp/battle-bottom-ui-contract
+          if-no-files-found: ignore

.github/workflows/battle-grid-contract.yml

@@ -0,0 +1,51 @@
+name: portable battle.move_grid_navigation contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: battle-grid-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36
+          path: .contract-reference/gen1
+      - name: Install ROM-free test runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check native move navigation dispatch and SDK contracts
+        run: |
+          luajit tests/engine/battle_grid_navigation.lua
+          luajit tests/engine/battle_auxiliary.lua
+          luajit tests/engine/trainer_preparation.lua
+          luajit tests/engine/trainer_preparation_native.lua
+          luajit tests/engine/trainer_party_scope.lua
+      - name: Validate pinned native Gen1 move navigation contracts
+        working-directory: .contract-reference/gen1
+        run: |
+          luajit tests/modkit/cases/unified_gen2_hooks.lua
+          luajit tests/modkit/cases/unified_gen3_hooks.lua
+      - name: Compare both engines in every SDK mode
+        run: |
+          mkdir -p /tmp/battle-grid-contract
+          python3 tools/battle-grid-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 1 --report /tmp/battle-grid-contract/api1-native.json
+          python3 tools/battle-grid-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --report /tmp/battle-grid-contract/api2-native.json
+          python3 tools/battle-grid-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --format unified --report /tmp/battle-grid-contract/api2-unified.json
+          python3 tools/battle-grid-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --report /tmp/battle-grid-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: battle-grid-contract
+          path: /tmp/battle-grid-contract
+          if-no-files-found: ignore

.github/workflows/core-update-contract.yml

@@ -0,0 +1,43 @@
+name: portable core.update contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: core-update-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36
+          path: .contract-reference/gen1
+      - name: Install ROM-free test runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check frame dispatch and native host routing
+        run: |
+          luajit tests/engine/core_update.lua
+          luajit tests/engine/core_update_routing.lua
+      - name: Compare both native engines through the same mod
+        run: |
+          mkdir -p /tmp/core-update-contract
+          python3 tools/core-update-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --report /tmp/core-update-contract/api2-native.json
+      - name: Check unified callback and API-3 integration
+        run: |
+          python3 tools/core-update-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --format unified --report /tmp/core-update-contract/api2-unified.json
+          python3 tools/core-update-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --report /tmp/core-update-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: core-update-contract
+          path: /tmp/core-update-contract
+          if-no-files-found: ignore

.github/workflows/input-hook-contract.yml

@@ -0,0 +1,43 @@
+name: portable input hook contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: input-hook-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36
+          path: .contract-reference/gen1
+      - name: Install ROM-free test runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check native input and host routing
+        run: |
+          luajit tests/engine/portable_input_hooks.lua
+          luajit tests/engine/portable_input_routing.lua
+      - name: Compare both native engines through the same mod
+        run: |
+          mkdir -p /tmp/input-hook-contract
+          python3 tools/input-hook-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --report /tmp/input-hook-contract/api2-native.json
+      - name: Check unified callback and API-3 integration
+        run: |
+          python3 tools/input-hook-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --format unified --report /tmp/input-hook-contract/api2-unified.json
+          python3 tools/input-hook-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --report /tmp/input-hook-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: input-hook-contract
+          path: /tmp/input-hook-contract
+          if-no-files-found: ignore

.github/workflows/level-visible-contract.yml

@@ -0,0 +1,49 @@
+name: portable pokemon.level_visible contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: level-visible-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36
+          path: .contract-reference/gen1
+      - name: Install ROM-free test runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check native level rendering and SDK contracts
+        run: |
+          luajit tests/engine/level_visible.lua
+          luajit tests/engine/level_visible_contract.lua
+          luajit tests/engine/level_visible_renderers.lua
+      - name: Validate pinned native Gen1 level contracts
+        working-directory: .contract-reference/gen1
+        run: |
+          luajit tests/modkit/cases/unified_gen2_hooks.lua
+          luajit tests/modkit/cases/unified_gen3_hooks.lua
+      - name: Compare both engines in every SDK mode
+        run: |
+          mkdir -p /tmp/level-visible-contract
+          python3 tools/level-visible-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 1 --report /tmp/level-visible-contract/api1-native.json
+          python3 tools/level-visible-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --report /tmp/level-visible-contract/api2-native.json
+          python3 tools/level-visible-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --format unified --report /tmp/level-visible-contract/api2-unified.json
+          python3 tools/level-visible-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --report /tmp/level-visible-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: level-visible-contract
+          path: /tmp/level-visible-contract
+          if-no-files-found: ignore

.github/workflows/logic-speed-contract.yml

@@ -0,0 +1,46 @@
+name: portable core.logic_speed contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: logic-speed-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36
+          path: .contract-reference/gen1
+      - name: Install ROM-free test runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check native speed dispatch, ownership and clocks
+        run: |
+          luajit tests/engine/logic_speed.lua
+          luajit tests/engine/logic_speed_routing.lua
+          luajit tests/engine/logic_speed_clock.lua
+      - name: Compare native API 1 and 2
+        run: |
+          mkdir -p /tmp/logic-speed-contract
+          python3 tools/logic-speed-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 1 --report /tmp/logic-speed-contract/api1-native.json
+          python3 tools/logic-speed-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --report /tmp/logic-speed-contract/api2-native.json
+      - name: Compare unified callbacks and API 3
+        run: |
+          python3 tools/logic-speed-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --format unified --report /tmp/logic-speed-contract/api2-unified.json
+          python3 tools/logic-speed-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --report /tmp/logic-speed-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: logic-speed-contract
+          path: /tmp/logic-speed-contract
+          if-no-files-found: ignore