Unify bets playback, market parity, and keeper recovery

[rndrntwrk]

Table of Contents

• Summary
• Problems Addressed
• Approach
• Methodology
• Impact
• Validation
• Acceptance Checklist
• Repository Checks
• Associated Pull Requests

Summary

This PR brings the unified bets playback, market-parity, and keeper recovery work from enoomian/staging into main review scope.

The branch consolidates the bets experience around a single stream session model, aligns public market state with chain-confirmed parity state, and hardens the keeper paths that prepare, lock, resolve, and recover multi-chain duel bundles. It also carries the contract and program updates required for those flows to settle against the same canonical lifecycle.

Problems Addressed

Area	Problem	User-facing or operational consequence
Stream playback	The app surfaces were not consistently mounting the same playback/session model across chains.	Bets UI could diverge by chain and drift handling was inconsistent.
Market parity	Public market surfaces could remain pinned to stale duel state while parity receipts lagged or recovered.	Users could see the wrong duel, wrong phase, or stale market status.
Keeper recovery	Restart windows and missed events could strand prepare/lock/resolve transitions.	Operators had to intervene to unstick parity bundles.
Cross-chain consistency	EVM, BSC, Solana, and Avax app and keeper paths had drifted apart.	Fixes had to be reimplemented repeatedly and behavior was not uniform.
Contract/program finality	Oracle and market contracts/programs needed matching finality behavior for the hardened keeper flow.	Mainline review would be incomplete without the settlement-side changes.

Approach

1. Unify the bets playback surface

• Add the shared HLS player shell and stream session plumbing used by the chain apps.
• Align app configuration so the playback layer resolves through the same authority and player bootstrap path across BSC, EVM, Solana, and Avax.
• Tighten the React app roots and stream-player integration so the unified surface is exercised the same way on each chain app.

2. Make public market state follow canonical parity state

• Extend keeper parity logic so public prediction-market surfaces resolve from canonical duel/parity state instead of stale cached state.
• Add explicit helpers and tests for market parity projection, stream-phase unmasking, canonical delivery, and public perps/public market surfaces.
• Carry the same lifecycle rules into the chain-specific keeper service layers instead of treating parity as an EVM-only concern.

3. Harden keeper recovery and replay

• Add bet-sync persistence and replay logic where it was missing or incomplete.
• Tighten bundle lifecycle handling in the main keeper bot/service flows so prepare, lock, resolve, and catch-up paths share the same invariants.
• Cover the recovery work with targeted service, db, bet-sync, and parity tests.

4. Align settlement contracts and generated interfaces

• Update the EVM contracts and Solana programs that participate in duel outcome finality.
• Regenerate the corresponding IDLs/ABI-driven artifacts so app and keeper code review against the actual contract/program interfaces shipped in this branch.

Methodology

This branch was prepared by diffing enoomian/staging against main, then removing deployment-specific and environment-specific work so the review scope stays on reusable repository behavior:

1. Start from origin/main.
2. Cherry-pick the application, keeper, contract, and test changes required for unified playback and canonical parity.
3. Exclude branch-local deployment wiring and runtime process management.
4. Re-run repository checks on the isolated branch before opening review.

The result is a review surface that keeps the substantive betting, parity, and settlement changes intact while avoiding unrelated staging-only operations work.

Impact

Product impact

• Bets playback is reviewed as one unified surface instead of chain-by-chain drift.
• Public market state tracks the same canonical duel lifecycle that the keepers enforce.
• Recovery behavior for missed or delayed lifecycle events moves from operator-dependent to code-driven.

Engineering impact

• Cross-chain keeper logic is closer in structure and therefore easier to maintain.
• Mainline contract/program review can happen against the same lifecycle assumptions the applications and keepers now rely on.
• The test surface around stream session handling and parity projection is materially broader than what main has today.

Validation

Validated locally in /tmp/hyperbet-main-pr-prep:

Check	Result
/Users/mac/.bun/bin/bun install	pass
bunx turbo run typecheck	pass (11/11 tasks successful)
bun test packages/hyperbet-ui/tests/streamSession.test.ts packages/hyperbet-ui/tests/streamPlayer.test.ts packages/hyperbet-ui/tests/hlsPlayerLoader.test.ts	pass (55 tests)
bun test packages/hyperbet-evm/keeper/src/marketParity.test.ts packages/hyperbet-evm/keeper/src/predictionMarketsSurface.test.ts packages/hyperbet-evm/keeper/src/streamPhaseUnmask.test.ts	pass (26 tests)

Acceptance Checklist

• Bets playback mounts through the unified session/player path on each supported chain app.
• Public prediction-market surfaces follow canonical duel/parity state across cycle transitions.
• Keeper replay and catch-up paths resolve missed lifecycle events without manual intervention.
• EVM and Solana settlement-side changes match the application and keeper expectations in this branch.
• Main CI remains green on the unchanged workflow surface.

Repository Checks

These branch boundaries were re-checked before opening review:

• .github/workflows: unchanged
• Deployment/runtime scripts: unchanged
• Process manager/runtime secret wiring: unchanged
• Review scope is concentrated in app, keeper, contract/program, generated interface, and test code

Associated Pull Requests

• Companion Hyperscape PR: HyperscapeAI/hyperscape#1178