# CW Orb implementation from the updated reference

The reference binary SHA-256 is
`235f5c3567f281cc99613ed84694ef23f492c15298dc868a8e78e6529f0cda86`.
The original binary was read without execution. Its embedded protobuf
descriptor, Excel tables and authored declarative configs were extracted under
`battle_diagnostics/ffgo-20261026/`.

`tools/export_ffgo_orb_recipes.py` reproducibly creates
`resources/CurrencyWarsOrbRecipes.json` from the explicitly selected extracted
Excel/custom JSON files and reference binary digest. The resource retains both
input JSON hashes and separates native table identities from the reference's
authored reward recipes. It does not claim captured official reward odds.

## Proven protocol contract

The current Client sender and reference descriptor agree on the request:

| Current name | Reference name | CmdID | Fields |
|---|---|---:|---|
| IKMOCJBMGOJ | GridFightUseOrbCsReq | 8623 | repeated UID tag4, get-all bool tag9 |
| PNHDGCBLPGD | GridFightUseOrbScRsp | 8659 | retcode tag3 |
| GDHFMHKFEAL | GridFightUseOrbNotify | 8745 | UID tag14, DropList tag5 |

The implementation registers only the current named request. It introduces no
numeric alias or fallback response. The reference handler at RVA `0xca4740`
replies through 8659; the called `gfItemUseOrbs` (`0xca2a40`) sends 8745 before
the reward sync. The reference's `gfRewardDropProto` (`0xcd3640`) does not set a
drop ID for coin/EXP/refresh drops. It writes a role/item ID for those types.
Role-star presentation maps exactly to `AOHKKFHDALO.role_star` tag101; the other
ChooseParam arm is unused.

The current native OrbSummarizer proof in
`currency-wars-current-consumer-notes.md` establishes source enum1 and the first
context uint equal to the opened Orb UID. Each opened Orb has its own grouped
sync containing the actual reward changes and the remove-Orb arm tag1503
(`GOHHJLAPMBB`).

## Implemented scope

Opening one or all selected owned Orbs uses a detached snapshot and saves the
removal and actual rewards in one revision-checked transaction. Duplicate or
unowned UIDs, stale revisions, malformed recipes, exhausted pools and unsupported
bonuses do not consume an Orb. Network errors after a committed payout are
reported as send failures; reconnect restores the saved result.

Sixteen reference recipes are identified among 532 native Orb rows:
102, 103, 197, 199, 203–208, 120031, 200001, 200005, 200013, 200015 and 200027.
The effect dispatcher supports gold, EXP, free refresh, lineup HP, captured
equipment/consumable/forge items, random captured equipment categories and
random available captured role rarities/stars. Random role rewards reserve
owned copies and unsold shop cards using captured merge rules, reject disabled
full-star roles, and use existing acquisition/merge/property projection paths.
Equipment categories require all reference category entries to exist in the
captured equipment catalog; no silently reduced category pool is substituted.
Inventory/effect prerequisites can still reject a particular identified recipe.

Orb opening is currently restricted to Preparation without another pending
action or active Battle, using the same revision guard as purchases. Native
bonus-pool budget/weighted recursion, role modifiers and general `OnOrbOpened`
trait/effect hooks remain separate work. For example ordinary Orb100's bonus
20001 has no supported fixed recipe yet, and returns a configuration error
without removal. The handler must not be described as complete coverage of all
532 Orbs or original game odds.

No unit tests, live probes or deployment were performed for this change.
`go build ./internal/gameserver` passed; Client Orb presentation and gameplay
acceptance remain unverified.

## Post-battle drops audit

The reference workflow includes `gfRouteRewardNodeOrbs` (RVA `0xce0c00`),
which calls `gfRouteRandomCreepOrbs` (`0xcdf4a0`) and `gfPoolRandomOrb`
(`0xccaec0`). Its `gfBattleTraitDrops` also calls `gfBattleDropReward`
(`0xc63e80`), which checks the configured Orb row before processing an Orb
drop. These are separate paths; the reference dump does not itself establish
the current Client's complete wire or success behavior.

The current settlement reads progress and damage but does not generate
post-battle Orb drops. `MGMJOPHJCNL.ODMCMPIDJNH` is a repeated drop-shaped
field in the current protocol; its relationship to a server-issued battle's
drop list and the matching reference fields has not been demonstrated.
Accepting it as a grant without that validation would trust unverified Client
input. Likewise, restricting random rewards to the small set of implemented
recipes would change the reference distribution. A complete implementation
still needs the current Client's battle drop contract, the reference pool
membership and selection parameters, and usable implementations for the
resulting Orb recipes. The audited save and server were not modified.