Implement native GBA Mirror Move and native battle-effect controllers

.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/charge-required-contract.yml

@@ -0,0 +1,44 @@
+name: portable charge-required contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: charge-required-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 battle charge decisions and compatibility
+        run: |
+          luajit tests/engine/charge_required_contract.lua
+          luajit tests/engine/api3_compat.lua
+          luajit tests/engine/unified_mod_callbacks.lua
+      - name: Compare both engines in every SDK mode
+        run: |
+          mkdir -p /tmp/charge-required-contract
+          python3 tools/charge-required-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 1 --format native --report /tmp/charge-required-contract/api1-native.json
+          python3 tools/charge-required-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 2 --format native --report /tmp/charge-required-contract/api2-native.json
+          python3 tools/charge-required-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 2 --format unified --report /tmp/charge-required-contract/api2-unified.json
+          python3 tools/charge-required-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --report /tmp/charge-required-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: charge-required-contract
+          path: /tmp/charge-required-contract
+          if-no-files-found: ignore

.github/workflows/critical-order-contract.yml

@@ -0,0 +1,37 @@
+name: native critical/type ordering
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: critical-order-${{ 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: 535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91
+          path: .contract-reference/gen1
+      - name: Install runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check critical/type boundaries
+        run: |
+          luajit tests/engine/gen3_critical_order.lua
+          luajit tests/engine/critical_order_contract.lua
+      - name: Compare unchanged public consumer
+        run: |
+          mkdir -p /tmp/critical-order
+          python3 tools/critical-order-contract-check/check.py --gen1 .contract-reference/gen1 --host-api 3 --report /tmp/critical-order/api3.json
+          python3 tools/critical-order-contract-check/check.py --gen1 .contract-reference/gen1 --host-api 2 --report /tmp/critical-order/api2.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: critical-order
+          path: /tmp/critical-order
+          if-no-files-found: ignore

.github/workflows/enemy-action-contract.yml

@@ -0,0 +1,95 @@
+name: Enemy move choice contracts
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/enemy-action-contract.yml'
+      - 'src/**'
+      - 'examples/portable_enemy_action/**'
+      - 'tests/enemy_actions/**'
+      - 'tests/engine/portable_enemy_action_*.lua'
+      - 'tests/engine/portable_enemy_move_records.lua'
+      - 'tests/engine/portable_enemy_targets.lua'
+      - 'tests/engine/gen3_follow_me.lua'
+      - 'tests/engine/gen3_helping_hand.lua'
+      - 'tests/engine/gen3_spit_up.lua'
+      - 'tests/engine/gen3_beat_up.lua'
+      - 'tests/engine/gen3_beat_up_adjustment.lua'
+      - 'tests/engine/gen3_beat_up_side_party.lua'
+      - 'tests/engine/gen3_critical_context.lua'
+      - 'tests/engine/gen3_constrained_party.lua'
+      - 'tests/engine/gen3_native_accuracy.lua'
+      - 'tests/engine/gen3_native_secondary.lua'
+      - 'tests/engine/gen3_battle_protocol.lua'
+      - 'tests/engine/gen3_party_codec.lua'
+      - 'tests/engine/gen3_party_transport.lua'
+      - 'tests/engine/gen3_lock_on.lua'
+      - 'tests/engine/gen3_lock_on_link.lua'
+      - 'tests/engine/gen3_baton_pass*.lua'
+      - 'tests/engine/gen3_encore*.lua'
+      - 'tests/engine/gen3_disable*.lua'
+      - 'tests/engine/gen3_multi_hit*.lua'
+      - 'tests/engine/gen3_rage*.lua'
+      - 'tests/engine/gen3_triple_kick*.lua'
+      - 'tests/engine/gen3_sleep_talk*.lua'
+      - 'tests/engine/gen3_choice*.lua'
+      - 'tests/engine/gen3_move_used*.lua'
+      - 'tests/engine/gen3_post_hit*.lua'
+      - 'tests/engine/gen3_nature_power*.lua'
+      - 'tests/engine/gen3_assist*.lua'
+      - 'tests/engine/gen3_mirror*.lua'
+      - 'tests/engine/gen3_substitute*.lua'
+      - 'tests/engine/gen3_effect_presentation.lua'
+      - 'tests/engine/gen3_native_sound.lua'
+      - 'tests/native_sound/**'
+      - 'tests/substitute_art/**'
+      - 'tests/tools/test_gba_substitute_art.py'
+      - 'tools/gba_substitute_art.py'
+      - 'tools/gen3_discover.py'
+      - 'tools/rom_manifest_firered.json'
+      - 'tools/rom_manifest_emerald.json'
+      - 'tests/post_hit_items/**'
+      - 'tests/held_item/**'
+      - 'tests/charge_required/**'
+      - 'tools/enemy-action-contract-check/**'
+  push:
+    branches: [main, dev]
+permissions:
+  contents: read
+concurrency:
+  group: enemy-action-contract-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  compare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: gen2
+      - uses: actions/checkout@v7
+        with:
+          repository: bryanthaboi/gen1recomp
+          ref: 535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91
+          path: gen1-reference
+      # Pin the maintained VM: the local 2.1.1700008891 ARM64 runtime
+      # produces JIT-dependent Thick Fat results in unchanged reference code.
+      - uses: actions/checkout@v7
+        with:
+          repository: LuaJIT/LuaJIT
+          ref: a4c064539ea931274d407e1249b4bb575424a0f4
+          path: luajit-runtime
+      - name: Build pinned LuaJIT
+        run: make -C luajit-runtime -j2
+      - name: Validate owned Substitute import locator inputs
+        run: nice -n 19 python3 -m unittest discover -s gen2/tests/tools -p test_gba_substitute_art.py
+      - name: Actual public hook and native move execution
+        run: >-
+          python3 gen2/tools/enemy-action-contract-check/check.py
+          --gen1 gen1-reference --gen2 gen2
+          --lua "${{ github.workspace }}/luajit-runtime/src/luajit"
+          --report "${{ runner.temp }}/enemy-action-report.json"
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: enemy-action-contract-report
+          path: ${{ runner.temp }}/enemy-action-report.json
+          if-no-files-found: error

.github/workflows/gba-damage-base-contract.yml

@@ -0,0 +1,38 @@
+name: ordinary GBA base damage
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: gba-damage-base-${{ 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: 535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91
+          path: .contract-reference/gen1
+      - name: Install runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check GBA damage and older-profile retention
+        run: |
+          luajit tests/engine/gba_damage_base.lua
+          luajit tests/engine/gen3_held_damage.lua
+          luajit tests/engine/gen3_held_damage_link.lua
+      - name: Compare actual ordinary damage calculators
+        run: |
+          mkdir -p /tmp/gba-damage-base
+          python3 tools/gba-damage-base-contract-check/check.py --gen1 .contract-reference/gen1 --report /tmp/gba-damage-base/records.json
+          python3 tools/held-damage-contract-check/check.py --gen1 .contract-reference/gen1 --report /tmp/gba-damage-base/held-records.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: gba-damage-base
+          path: /tmp/gba-damage-base
+          if-no-files-found: ignore

.github/workflows/gen3-ai-item-knowledge-contract.yml

@@ -0,0 +1,34 @@
+name: native GBA AI item knowledge
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: gen3-ai-item-knowledge-${{ 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: Roxas2712/gen1recomp-Mac-fix
+          ref: 12c9e5b5a2325470d6bb266c9a1f37b7954b698e
+          path: .contract-reference/gen1
+      - name: Install runtime
+        run: sudo apt-get update && sudo apt-get install -y luajit
+      - name: Check native item queries and observation producers
+        run: luajit tests/engine/gen3_ai_item_knowledge.lua
+      - name: Compare actual native AI and effect paths
+        run: |
+          mkdir -p /tmp/gen3-ai-item-knowledge
+          python3 tools/gen3-ai-item-knowledge-contract-check/check.py --gen1 .contract-reference/gen1 --report /tmp/gen3-ai-item-knowledge/records.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: gen3-ai-item-knowledge
+          path: /tmp/gen3-ai-item-knowledge
+          if-no-files-found: ignore

.github/workflows/gen3-ai-order-contract.yml

@@ -0,0 +1,41 @@
+name: native GBA AI order
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: gen3-ai-order-${{ 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: pret/pokefirered
+          ref: ce6406d8c2eaf46d543c8a2606de0c3cb1951982
+          path: .contract-reference/firered
+      - uses: actions/checkout@v7
+        with:
+          repository: pret/pokeemerald
+          ref: 731ad5bfd6e6f265508d0efcca0ba42f9dcf5881
+          path: .contract-reference/emerald
+      - name: Install runtime and compiler
+        run: sudo apt-get update && sudo apt-get install -y luajit build-essential
+      - name: Check real AI queries and battle planning
+        run: luajit tests/engine/gen3_ai_order.lua
+      - name: Compare actual VMs and sorting with original native C
+        run: |
+          python3 tools/gen3-ai-order-check/check.py \
+            --firered-main .contract-reference/firered/src/battle_main.c \
+            --emerald-main .contract-reference/emerald/src/battle_main.c \
+            --report /tmp/gen3-ai-order/records.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: gen3-ai-order
+          path: /tmp/gen3-ai-order
+          if-no-files-found: ignore

.github/workflows/held-item-contract.yml

@@ -0,0 +1,46 @@
+name: portable held-item contract
+on:
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: held-item-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 held readers, metadata authority and SDK compatibility
+        run: |
+          luajit tests/engine/held_item_contract.lua
+          luajit tests/engine/held_item_authority.lua
+          luajit tests/engine/held_item_scheduling.lua
+          luajit tests/engine/api3_compat.lua
+          luajit tests/engine/unified_mod_callbacks.lua
+      - name: Compare both engines in every SDK mode
+        run: |
+          mkdir -p /tmp/held-item-contract
+          python3 tools/held-item-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 1 --format native --require-native-schedule-parity --report /tmp/held-item-contract/api1-native.json
+          python3 tools/held-item-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 2 --format native --require-native-schedule-parity --report /tmp/held-item-contract/api2-native.json
+          python3 tools/held-item-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 2 --format unified --require-native-schedule-parity --report /tmp/held-item-contract/api2-unified.json
+          python3 tools/held-item-contract-check/check.py --gen1 .contract-reference/gen1 \
+            --api 3 --format unified --require-native-schedule-parity --report /tmp/held-item-contract/api3.json
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: held-item-contract
+          path: /tmp/held-item-contract
+          if-no-files-found: ignore