Expose live native GSC model RNG domains and stable source roller

docs/native-gen2-model-boundary.md

@@ -0,0 +1,38 @@
+# Native Gen2 model boundary
+
+`src.battle.gen2.Battle` is a distinct model class attached to the shared
+native battle controller by `Gen2BattleView`. It is not a name alias for
+`BattleState`, a second controller, or a detached copy of the saved party.
+Methods resolve through the class so an SDK-owned decoration also reaches
+already-created models and is restored by loader retirement.
+
+The boundary supplies live `moveDef`, `speciesDef`, `sideOf`, raw `battleStat`
+and `endBattle` operations. Damage, speed, status immunity, weather and shared
+move effects consult the native bound reads. Stages, badge/status/item
+modifiers, RNG and PP stay with their existing native owners. With no
+decoration the read returns the original native table, without a copy.
+Temporary stat/type answers do not replace a species registry row, party
+statistics, wrapper identity or checkpoint data. Explicit native
+Conversion/Transform types keep their priority over a species decoration.
+
+The native finish path invokes the model's end operation, including the
+skipped battle path. It raises one finish notification and permits transient
+cleanup before subscribers observe it. `completeBattle` runs the existing
+screen finish/return path, with repeated completion prevented from popping
+another screen. Existing native consumers retain the screen in the event's
+`battle`; the distinct model is available in `model`.
+
+This is an implemented boundary, not complete source-model parity. The split
+Gen2 model contract was inspected at Gen1Recomp `535a5ec0` and its current
+`e46d1eb2` counterpart. That model additionally has constructors and a pure
+turn/event API, which are not guessed from screen methods here. Its inspected
+class has no `battleStat` method; the raw-stat operation above is an explicit
+native extension, not a claim that all source versions expose it. Source
+event payload normalization and the remaining model operations still require
+separate implementation and acceptance. Existing project and third-party
+credits remain applicable.
+
+ROM-free coverage uses an SDK-loaded generic decorator and actual native
+damage, speed, status, switch, Transform and completion calls. It also checks
+restoration and direct table identity in other generations. It does not prove
+an unchanged client, GPU presentation, a full story run or a release package.

docs/native-gen2-model-rng.md

@@ -0,0 +1,31 @@
+# Native Gen2 model RNG
+
+Expose `rng`, `random` and `roller()` on the live source model, backed by the
+existing native controller's current function. LOVE-style ranges normalize
+missing/small bounds and reversed ranges; the source random/roller domain is
+zero-based for positive integer bounds. Queries consume no randomness and
+retained adapters follow native function replacement, including link setup.
+
+The source random field and decorated roller method stay distinct. The native
+read-only reader policy remains in effect. Model-owned function caches do not
+enter party mons or serialized battlers, and no second generator is created.
+Standalone constructor/RNG-injection and complete source-model parity remain
+separate work.
+
+Reference: read-only Gen1Recomp Gen2 revision
+`535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91`, `Battle.new`, its LOVE-style RNG
+view and `Battle:roller`. This older host's native model, volatile-state and
+protection prerequisites are offered separately. The fork-only semantic
+checkpoint backend is absent here, so its checkpoint result is not inherited.
+
+Native integration/tests by Roxas2712, offered to Cedric / UNDERdecoded under
+the specific PR contribution permission, with existing rights intact.
+Independent validation on this offered host passes 7951 native RNG checks,
+174 actual host/guest/spectator source-callback checks, model (262), volatile
+(423) and protection-link (66) regressions. A separately executed frozen Gen1
+comparison passes 9471 comparisons / 7020 draw cases over actual seeded native
+LinkBattle backends; reference hashes remain unchanged. The exact official
+whole-host command passes 71/82 engine suites and SDK3/3, with the same eleven
+pre-existing failures as its protection base (69/80). It adds two passing suites
+without adding a whole-host failure; this older prerequisite stack is not
+entirely green. Full model/mod/GPU/release acceptance remains separate.

docs/native-gen2-move-priority.md

@@ -0,0 +1,32 @@
+# Native GSC move priority
+
+Older native GSC caches mark priority-hit moves explicitly, but leave Protect,
+Endure, Mirror Coat and other priority classes without a `priority` field.
+The shared comparator then treated them as ordinary moves. A slow Pokemon
+could take damage before its Protect action; the live Gen2 model also reported
+neutral priority for these moves.
+
+`Gen2MovePriority` supplies the cartridge's missing priority classes at the
+actual native comparator and live-model query. Protect/Endure use +3;
+Counter/Mirror Coat and Vital Throw use -1. Roar/Whirlwind use -1 by their
+native IDs because the existing cache combines their effect with Teleport;
+Teleport remains neutral. Explicit native cartridge/mod priority values,
+including zero, take precedence. Other generations retain their own rules.
+This does not require a re-import, change a move record or registry fingerprint,
+or replace the native battle engine. It adds no RNG draw.
+
+The reference is the GSC `GetMovePriority`/effect-priority table also represented
+by the read-only Gen1Recomp Gen2 model at
+`535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91`. This is an implementation in the
+native shared controller, not an alias to a second combat simulator.
+
+The exact old-source regression reproduces 57 failed assertions, including
+actual HP loss before slow Protect. The corrected 83-check contract exercises
+Gold/Silver/Crystal, renamed effect-equivalent moves, explicit overrides,
+unknown moves and the public model. It executes the real queued native actions
+and verifies Protect/Endure state and PP; the enemy's real attack is blocked
+after Protect. Cross-generation comparator checks and existing battle/model,
+queue and held-item regressions remain separate checks. These ROM-free fixtures
+are not a claim of complete move parity, unchanged-mod story/window behavior,
+or release acceptance. Full model-constructor and other Gen1 behavior gaps
+remain open.

docs/native-gen2-protection.md

@@ -0,0 +1,38 @@
+# Native GSC Protect and Endure
+
+Run GSC protection on the real shared-controller battler, with the source
+model's nonzero-byte odds (`255 >> prior successes`), first-side and Substitute
+restrictions. Actual action entry records the first side for that round,
+including switches and failed/recharge actions; called effects retain it.
+The next round replaces it. GSC self-protection bypasses the generic incoming
+status gate so the real handler can clear its failed-use counter.
+
+Changed command/RNG semantics advertise `gsc-1` in link hello and a separate
+GSC fingerprint domain. Older rules cannot enter the changed lockstep battle;
+the compatibility screen names the native rules difference. Other generations
+retain their existing handlers and fingerprints. This older host does not
+carry the fork's semantic-checkpoint backend, so no checkpoint result is
+claimed here.
+
+References: read-only Gen1Recomp Gen2 revision
+`535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91`, its protection handlers and
+`Effects.protectSucceeds`; `pret/pokecrystal`
+`5c877ef55197039c9676e8e3eec6d254b1c40fe8`,
+`engine/battle/move_effects/protect.asm`. The nonzero-domain native RNG call
+matches the source model convention; this does not emulate a hardware PRNG or
+claim raw zero-rejection trace parity.
+
+The native model/volatile/priority prerequisites remain separate offered PRs.
+Independent results on this offered host: 3796 native effect/queued-order/PP/
+switch checks, 66 host/guest/spectator and admission checks, 37 actual protocol/
+cache/digest checks, 423 volatile checks and 83 priority checks pass. The frozen
+Gen1 comparison independently passes 30,624 actual effect cases / 165,336
+comparisons. A separate Python integer-FNV audit confirms this host's legacy
+fixture digest e33d251961f2a41d and GSC digest 40df18dc503213c8. Tests drive this
+older host's actual queue-row closures; they do not assume the newer fork's
+runQueueAction or beginTurn helpers exist. Fork-only checkpoint and complete
+release acceptance are not inherited. GPU, complete called-move/turn mechanics,
+unchanged-mod gameplay and full Gen1 feature parity remain separate work.
+
+Native integration/tests by Roxas2712, offered to Cedric / UNDERdecoded under
+the fork's specific PR contribution permission, with existing rights intact.

docs/native-gen2-volatile-state.md

@@ -0,0 +1,35 @@
+# Native GSC volatile state
+
+The live Gen2 battle model exposes `volatile(mon)` as a view of its existing
+native battler, rather than a disconnected metadata table. Canonical source
+names `confuseCount`, `flinched`, `endure`, `recharge`, `protectCount`,
+`focusEnergy` and `xAccuracy` address the native confusion counter, admission,
+damage, action-lock, protection, critical and hit-check owners. Substitute,
+protect and mist aliases are also supported. Unknown keys remain transient
+consumer metadata, not newly implemented mechanics.
+
+Views are cached on the transient model only. Module-global weak-key caches can
+retain retired battlers on LuaJIT when value closures reference the key. The
+same active native owner has a stable view; withdrawn entries retire on query
+and incoming wrappers get new views. No view or metadata is stored in a party
+mon or serialized battler.
+
+GSC consecutive-protection retention follows the actual PROTECT/ENDURE effect,
+including renamed moves; an old PROTECT ID with another effect resets it.
+Protection RNG, opponent-first and Substitute rules are addressed by the
+separate [native protection work](native-gen2-protection.md).
+No second battle simulator is introduced.
+
+On this older host, 423 real native state/mechanics/ownership/collection checks,
+262 model checks and 83 move-priority checks pass independently. The fixture
+loads an actual API2 source consumer and covers Gold/Silver/Crystal, Prism and
+Polished Crystal. The fork's additional semantic-checkpoint backend is absent
+here, so its checkpoint result is not claimed for this offered branch.
+These ROM-free CPU checks do not establish complete source-model, GPU,
+unchanged-mod or release acceptance. Depends on the native model boundary and
+move-priority contributions offered separately.
+
+Source-field names were inspected against Gen1Recomp Gen2 revision
+`535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91`. Native integration and tests are
+contributions by Roxas2712, offered to Cedric / UNDERdecoded under the fork's
+specific PR contribution permission, with existing third-party rights intact.