Update GaCy-GO

docs/currency-wars-route-factory.md

@@ -0,0 +1,63 @@
+# Currency Wars generated route continuation
+
+The route continuation uses the extracted FFGO `gfPendingAdvanceNode` ->
+`gfFxHEnterNode` flow and `gfRouteCreateNode` configuration. Reference executable
+and Excel-dump hashes are recorded in `CurrencyWarsReferenceNodes.json`; its 493
+normalized templates are data, not snapshots of another player's run.
+
+`cwAdvanceRouteNode` operates only on the caller's detached run. It finds the
+next ordered chapter/section in the catalog, retains the run's existing route
+display (including dynamic Tea Break replacements), and asks the reference
+enemy factory to construct the destination layer using that run's saved
+chapter boss/camp. It validates the destination before changing the source.
+It then emits finish-old-queue, level change, and typed RoundBegin updates.
+It neither awards rewards nor writes a save. The caller commits rewards and
+continuation together with its existing revision/CAS check.
+
+`cwNextRound` keeps the existing captured transitions and uses typed generated
+pending actions when a new enemy node has no captured RoundWire. It refreshes
+the finite-pool shop and creates ReturnPreparation, Spotlight, or Encounter
+selection through the existing handlers. Queue values increase from the
+active queue; battle settlement must seed that queue from its persisted
+revision before calling the factory when no pending action remains.
+
+Current integration target is the dynamic Tea Break at 1-5 followed by the
+saved route's Boss at 1-6. General augment effects, non-enemy layer creation,
+and end-of-route finalization require their own state handlers; this module
+does not claim to implement all run effects or replace those handlers.
+
+Validation: Go compilation only. No unit tests, live probes, deployment or
+player-save writes were performed by this implementation task. Client
+continuation and combat remain to be checked after the parent integration.
+
+## Current Boss entry correction
+
+Live logs now confirm take-drop, RoundBegin and ReturnPreparation succeeded:
+the user's run reached 1-6, revision 545, without resetting the run. Boss start
+was rejected by the new helper's `CW validated battle scalar parameters missing`.
+That guard incorrectly required Level and HardLevelGroup to be nonzero. Decoding
+the proven first-node BattleTemplates wire shows both are omitted/zero, while
+formation is 5. Updated FFGO `gfBattleMonsterWave` (RVA 0xc62b00) initializes its
+wave param with formation and elite only, independently confirming omission.
+
+The helper now preserves those captured zero values and validates the required
+formation. It does not replace them with older recipes' explicit 90/1 constants.
+Saved boss/camp, wave ordinals, stars, penalty and mode identity still validate.
+No claim of live Boss entry is made until the patched request is observed.
+
+## Monster and EliteBranch battle projection
+
+The reference battle projection also accepts a previously created Monster or
+EliteBranch layer: it validates the saved camp membership and wave ordering,
+and EliteBranch's selected penalty against the extracted penalty table. This
+does not generate those layers or establish that the Client accepts the fight.
+
+The reference `gfRouteCreateNode` uses a run-specific neutral camp for Monster
+nodes. `gfRoutePlanForRun` reads that camp from an internal FFGO run field; it
+is not represented by the saved Client stage's boss camp list. The captured
+first battle's monster IDs match more than one native season camp, so they do
+not uniquely recover the saved run's neutral camp. The reference uses one wave
+of three monsters for the first Monster node and five thereafter, filtering by
+the captured maximum tier; determining the run camp is still required before
+constructing that layer. EliteBranch generation additionally needs its option,
+difficulty and reward contract. No player save was modified by this audit.