fix(ghost-battle): gate combat start on complete native board setup

[pengx17]

Background

Ghost Battle playback has been fixed repeatedly, but the same failure still occurs intermittently: combat begins while cards are only partially present on the board. Another speculative delay or one more local readiness check is not acceptable without stage-level evidence.

Current problem

Verified from the user-provided screenshot on 2026-08-25:

• Game build: 1.0.11980-prod-macos-arm64-d75a8ee9
• Mod build: BPP 5.2.1.prod
• Saved Ghost Battle playback is already at 0:22.00 and resolving combat effects.
• The local board is visibly incomplete: most card bodies are absent while several cooldown labels remain over empty board regions.
• This is therefore a start-gate/readiness failure, not merely a loading screen that lingers before combat.

Still unverified:

• Whether the missing objects were never instantiated, were instantiated but not activated/render-ready, or were invalidated by a stale playback session.
• Which owner actually authorizes combat start in the failing run.

Candidate cause mechanisms

Treat these as alternatives to falsify, not conclusions:

1. Readiness is too shallow: the gate observes a populated DTO/controller/list before each native card's asynchronous SetUp and visual activation have completed.
2. Expected-count mismatch: readiness compares against a filtered or transient count, so missing cards are accepted as a complete board.
3. Lost ordering: an auto-start callback is armed before board construction finishes and is not cancelled/revalidated when asynchronous setup is still pending.
4. Cross-session completion: a task/callback from a previous replay generation releases or bypasses the current replay's gate.
5. Timeout fail-open: a bounded wait expires and intentionally starts combat without recording exactly what remained incomplete.
6. Non-transactional application: payload/state application and native board construction publish partial state that combat consumes before the final reconciliation pass.

Verification method

Before changing behavior, add a temporary probe on the real Ghost Battle playback path. Every event must carry one playback/session generation and monotonic elapsed time.

Capture:

• payload accepted: expected hero, item, skill, and board-slot counts for both sides;
• native construction requested/completed per stable card id and slot;
• asynchronous card SetUp requested/completed/failed and final activeInHierarchy/visibility state;
• every readiness evaluation with expected vs completed vs visible counts;
• every start authorization with owner, reason (ready, timeout, or other bypass), session generation, and unresolved ids/slots;
• cancellation/disposal and any callback rejected as stale.

Reproduce at least once from a cold asset/cache state and once on a warm repeat of the same Ghost Battle. The hypothesis is considered proven only when one start-authorization event precedes the missing cards' terminal setup state (or shows an incorrect expected set/session generation).

Fix acceptance

• Combat cannot enter its running state until all payload-required native board entities for the active playback generation have reached a terminal setup outcome.
• A setup failure has an explicit user-visible/logged terminal policy; it cannot silently look ready.
• Timeout, if retained, does not silently start a partial battle.
• Stale callbacks cannot mutate or release a newer playback generation.
• Pure tests pin the discovered ordering invariant and the failure/timeout policy.
• Runtime probe/log evidence from cold and warm playback shows start authorization only after the final required setup completion.

[pengx17]

Verified root cause and local fix

The 2026-08-25 runtime log identifies the screenshot replay as gh_d1725. It emitted combat_replay.playback.started and later combat_replay.playback.succeeded with degradation_count=0, so the existing tracker did not observe a failed or pending setup task.

The remaining race is a second, native visibility boundary:

• Native ReplayState.OnEnter starts SpawnCombatCards() without awaiting it (decompiled/TheBazaarRuntime/TheBazaar/ReplayState.cs:65-83).
• The existing BPP fix now correctly waits that task and every ItemController.Setup task.
• However, native BoardManager.SpawnCard deliberately calls itemController.ShowCard(false) when Data.CanWeDisplaySequenceNodes is false and appends the controller to _playerCardsOnBoard (decompiled/TheBazaarRuntime/BoardManager.cs:2884-2894). The setup/spawn tasks still complete successfully.
• The only native flush for that hidden-art queue is BoardManager.ShowPlayerCards, which shows entries one by one and then clears the list (decompiled/TheBazaarRuntime/BoardManager.cs:1225-1237). The ReplayState transition tick does not await this flush (decompiled/TheBazaarRuntime/TheBazaar.SequenceFramework.VisualSequences/TransitionInComponent.cs:454-463).

This exactly matches the screenshot: controller-owned cooldown labels are present over empty slots, while the item art controlled by ShowCard is absent.

The local fix adds the missing visibility transaction after tracked spawn/setup completion:

1. wait for an actually registered native display (Data.TransitionIn != null) to report ready;
2. await the native BoardManager.ShowPlayerCards() queue drain;
3. require expected == registered == active == visible == positioned item counts across two render boundaries;
4. timeout aborts/rolls back the saved replay instead of calling Replay() on a partial board;
5. emit combat_replay.saved_playback.presentation_gate_resolved with battle id and all five counts.

Validation:

• ./run.sh test: passed (all default suites, including 110 FeatureLogging, 97 Architecture, and 45 process-isolated scenarios).
• scoped CSharpier check: passed for all changed C# files.
• ./run.sh build --fast -p:BPPInstallerSourcePath=...: succeeded, 0 warnings / 0 errors, DLL copied to the live BepInEx plugin directory.

Runtime acceptance remains: restart the currently running game so it loads the new DLL, then replay cold and warm Ghost Battles and inspect the new gate event before combat_replay.playback.started.

[pengx17]

Recurrence after the visibility-gate fix — 2026-08-28

The bug reproduced locally again after the previous fix.

Verified from the new screenshot:

• Game build: 1.0.11980-prod-macos-arm64-d75a8ee9
• Mod build: BPP 5.2.1.t20260826.102148.dev
• Combat is already running at 0:06.90.
• The opponent board is fully populated while the local board shows only a small subset of item bodies over a much wider occupied combat layout.

The previous hypothesis is therefore incomplete. Do not add another delay. Use the permanent combat_replay.saved_playback.presentation_gate_resolved event to distinguish these alternatives:

1. Fix absent/bypassed: no saved-playback gate event exists for this battle before combat_replay.playback.started.
2. Expected-set undercount: the gate reports ready, but expected_items already excludes payload/snapshot-required items.
3. Post-gate concealment: the gate reports equal complete counts, then Replay() or another later native callback calls ShowCard(false) / disables art before or during simulation.
4. Gate failure bypass: the gate reports timed_out, yet another path still starts simulation.
5. Not an item-visibility failure: counts remain complete because the missing visual is a later child-art/animation state not represented by IsCardVisible and activeInHierarchy.

Verification order for this recurrence:

• correlate the latest saved-playback gate event, playback-start event, and battle id from BepInEx/LogOutput.log;
• compare gate expected/registered/active/visible/positioned counts against the saved manifest item ids for both hands;
• only after that, inspect the exact post-gate native calls that can conceal or replace an item visual;
• add a main-path probe at the first contradicted boundary and reproduce, rather than patching another candidate mechanism.

[pengx17]

2026-08-28 local recurrence triage result

The recurrence screenshot did not exercise the new saved-replay presentation gate.

Verified runtime evidence:

• LogOutput.log contains six imported-ghost combat_replay.playback.started events (gh_735f3 through gh_ea9ad) and zero combat_replay.saved_playback.presentation_gate_resolved events.
• The running game loaded BPP 5.2.1.t20260826.102148.dev; the installed plugin before rebuild was timestamped 2026-08-26 10:21 and did not contain the new SavedReplayPresentationReadiness type.
• Rebuilding the current worktree succeeded with 0 warnings / 0 errors and copied a byte-identical workspace DLL into BepInEx/plugins; the installed DLL now contains SavedReplayPresentationReadinessSnapshot / ObserveSavedReplayPresentationReadiness.
• The game process is still alive, so Mono has the old assembly loaded until a full game restart.

Conclusion: this screenshot is a deployment/restart miss, not evidence that the new gate itself failed. Next valid reproduction must occur after restarting The Bazaar and must include the new gate event; only then should we evaluate expected-count undercount or post-gate concealment.