SpeculativeSequencer

val speculative = SpeculativeSequencer(
    sequencer = TurnSequencer(node, Move.serializer()),
    game = myGame,          // SpeculativeGame<GameState, Move>
    initialState = state0,
    scope = viewModelScope, // or a scope tied to session lifetime
)

// Observe for UI — always up to date with speculative state:
speculative.speculativeState.collect { render(it) }

// Propose a local player's move (suspends until quorum confirms):
try {
    speculative.propose(myMove)
} catch (e: LeadershipLostException) { /* retry */}

// Durable propose with a caller-owned request ID for cross-crash exactly-once:
try {
    speculative.propose(myMove, requestId = nextSerial)
} catch (e: LeadershipLostException) { /* retry with same requestId */}

runTest(timeout = 5.seconds) {
    // A trivially pure game: state is a list of committed integers.
    val counterGame = object : SpeculativeGame<List<Int>, Int> {
        override fun apply(state: List<Int>, action: Int): List<Int> = state + action
        override fun snapshot(state: List<Int>): List<Int> = state.toList()
        override fun restore(snapshot: List<Int>): List<Int> = snapshot.toList()
    }

    val node = FakeRaftNode()
    node.setRole(RaftRole.Leader)
    val sequencer = TurnSequencer(node, Int.serializer())

    val speculative = SpeculativeSequencer(
        sequencer = sequencer,
        game = counterGame,
        initialState = emptyList(),
        scope = backgroundScope,
    )

    // Optimistic apply: speculativeState reflects 42 immediately, before quorum.
    val proposed = async { speculative.propose(42) }
    assertEquals(listOf(42), speculative.speculativeState.value)

    // Once quorum confirms, pending count drops to 0.
    val indexed = proposed.await()
    assertEquals(42, indexed.action)
    speculative.awaitConfirmedCount(1)
    assertEquals(0, speculative.pendingCount)
    assertEquals(listOf(42), speculative.speculativeState.value)
}