[Roxas2712]

A portable mod registering an AI class with item = "POTION" currently leaves that symbolic name in Gen2Recomped's native registry. Imported Gen-2/GBA data uses keys such as ITEM_018 or ITEM_013, so the same mod fails reference validation. AI-class read/write results also bypass the detached unified-content boundary.

Resolve optional class item references through the mounted item registry before recording operations, and project common IDs in detached get, each, register, override and patch results. Keep native schemas, rollback, deletion and load-time freezing authoritative. Add one unchanged public example, real-loader contract fixtures, an isolated imported-data smoke driver, documentation and a pinned cross-engine CI workflow.

This is stacked on #173 as part of the portability series; the incremental scope is the AI-class content adapter and its tests/documentation. It does not enable the unfinished battle.enemy_switch_or_item hook or claim identical native AI behavior.

Compatibility

• API 3 is the common detached-record contract for Gen1–3.
• Gen2Recomped API 2 with explicit unified content opts into that contract; comparisons use Gen1Recomp API 3 as the reference.
• Gen1Recomp API-2 AI-class reads are live passthroughs, so equivalent API-2 aliasing semantics are not claimed. Native API-1/2 formats retain their existing handles and physical keys.

Validation

• Unified content: 442/442; real-loader metadata checks: 670/670.
• Each host mode (API 3 and API 2/unified): 16 isolated engine workers / 56 paired observations, eight versions, same consumer, clean Gen1 reference 535a5ec088c1ae1bf4d91dd3e35a56f64cf46d91.
• Unchanged Preserve native trainer AI metadata during ROM import #173 negative controls fail the same consumer in Gold and FireRed with unresolved item references.
• Complete feature: 139/149 engine suites, 3/3 SDK suites, B30 passed. All 26 FAIL lines exactly match the parent's ten known baseline suites; their separate repair PRs test: repair Gen2 updater asset fixtures #128–134 are outside this feature branch.
• Native LÖVE 11.5 with imported Red, Gold, FireRed and Emerald: title and in-memory New Game, public/native item resolution, detached metadata and frozen writes. Temporary example removed with hash guards. No normal SAVE, battle-policy, complete-playthrough or fresh full-ROM-import claim.
• New workflow passes actionlint. Local results are separate from hosted CI approval/execution.

The incremental changes relative to #173 are available separately for review.

The combined Roxas2712:codex/portability-testing runtime 4975ca8337faa27dde511fa5c6cb93c6210c7bab, including the separate baseline repairs, passes 194/194 engine suites, 3/3 SDK suites and B30. Both shared contract modes and the four imported-data metadata smoke sessions also pass at that clean runtime. Later commits only record validation documentation.

All 34 hosted PR workflows currently report action_required pending maintainer approval. The AI-class content workflow has zero executed jobs; these hosted results are not presented as passing CI.