[Roxas2712]

Depends on #107 and its API ancestors; merge those first and rebase before merging. Implementation-only commit 569b78980a0586b1ed8ee9662e0a94da134f254a (focused diff).

API-3 getFlag/setFlag now resolve validated cartridge symbols/numbers to the exact flag keys used by this host's VM and save converter. Red/Blue and Yellow use their own named bit catalogs; Gold/Silver reuse Gen2Flags; Crystal retains the pinned reference's numeric-only contract. FireRed/Emerald use version-specific symbols/aliases and numeric ranges. Unknown/hack mappings decline; private mod flags remain available without assuming Gold numbering for Prism/Polished Crystal.

Preserve the host's false-versus-untouched native clear semantics. Gen3 flag writes target only affected active object templates through native visibility synchronization. Flags remain usable from menus/scripts with a current save. Add the common mod.. private alias and refuse foreign namespaces. Retire retained setters on owner unload/rollback/reload; refuse recursive writes during the flag event/visibility callback.

Identifier catalogs contain data only, not Gen1 engine code or ROMs. A deterministic pinned-reference generator/checker verifies every shipped catalog and all 1235 Gold/Silver symbol mappings. CI verifies provenance.

Public contract, event labels and reproduction. For cross-engine Gen3 flag identity use event.id: the pinned Gen1 native emitter uses its base FireRed labels on Emerald, so labels are not normalized as a false equivalence. The identical shared mod consumes event.id or event.name on both engines.

Validation

• 18,348/18,348 targeted checks: every shipped alias/named numeric entry against native VM keys, all2048 Gen2 bits, native storage booleans/clears, malformed stores/arguments, reentry, retired owners and targeted visibility dispatch. Compatibility103/103.
• Provenance checker passes on both feature and integration trees; generated catalogs reproduce exactly against clean Gen1 79ea62f45fb2ea8f65d081a109431e4eb1bbdb36.
• 72 cross-engine comparisons /144 isolated loader runs, same public-only mod on Red, Blue, Yellow, Gold, Silver, Crystal, FireRed and Emerald. Compare preflight, aliases, booleans, change-only event identity/value and private ownership. All prior shared cases retained; reports capture clean exact commit heads and fixture hashes.
• Full ROM-free run: 82/92 engine, SDK3/3, B30 PASS. All 27 complete FAIL lines remain exactly equal to the fresh series baseline, in order.
• All-PR integration through Add guarded API 3 native map invalidation #107 plus this commit (f56b126e970283139a9e7194e243eef5e6dd3bc5): 87/97 engine, SDK3/3, B30 PASS; identical baseline failures. All72 comparisons/144runs and provenance checks pass there too.
• Modern Lua formatting, Python parsing and diff checks pass; deterministic generated catalogs retain generator formatting. Tests use synthetic stores/worlds and instrumented visibility entry, not a ROM story/visual playthrough. Native visibility failure after a flag write is not transactional rollback.

Unchanged failing suites: gate_fingerprint, gate_meta_coverage, quit_thread_shutdown, rebind_capture_bug510, rebind_swap_clear_bug589, soft_reset_bug563, tool_mod_hooks, update_check_tests, update_tests, wide_battle_layout. Full test entry remains nonzero because of these baseline failures.

Hosted CI

Published open/non-draft at the tested head. API 3 contracts and ci currently conclude action_required pending maintainer fork-workflow approval. Hosted CI is not green; validation above ran locally.