shufflecom-calculations 4.2.0 → 4.2.1

package/src/games/floor-is-lava/floor-is-lava-rules.ts

@@ -0,0 +1,217 @@
+import BigNumber from 'bignumber.js';
+import { calculateEdgeMultiplier } from '../../utils/edge';
+
+export const BOARD_SIZE = 49;
+export const LEVELS_PER_DIFFICULTY = 3;
+
+export enum FloorIsLavaDifficulty {
+  EASY = 'EASY',
+  MEDIUM = 'MEDIUM',
+  HARD = 'HARD',
+  TOXIC = 'TOXIC',
+}
+
+export interface FloorIsLavaLevelConfig {
+  dropsPerRound: number;
+  roundsPerLevel: number;
+}
+
+// Same (dropsPerRound, rounds) reused for all 3 levels of a difficulty - only the random board
+// differs per level, not the round/drop shape. dropsPerRound * rounds + survivingTiles = 49.
+export const DIFFICULTY_LEVEL_MAP: Readonly<Record<FloorIsLavaDifficulty, FloorIsLavaLevelConfig>> = {
+  [FloorIsLavaDifficulty.EASY]: { dropsPerRound: 7, roundsPerLevel: 6 },
+  [FloorIsLavaDifficulty.MEDIUM]: { dropsPerRound: 11, roundsPerLevel: 4 },
+  [FloorIsLavaDifficulty.HARD]: { dropsPerRound: 23, roundsPerLevel: 2 },
+  [FloorIsLavaDifficulty.TOXIC]: { dropsPerRound: 48, roundsPerLevel: 1 },
+};
+
+// Fails loudly at import time if a config is malformed - a static invariant, not a per-request check.
+const computeSurvivingTiles = (difficulty: FloorIsLavaDifficulty): number => {
+  const { dropsPerRound, roundsPerLevel } = DIFFICULTY_LEVEL_MAP[difficulty];
+  const survivingTiles = BOARD_SIZE - dropsPerRound * roundsPerLevel;
+  if (survivingTiles < 1) {
+    throw new Error(`FloorIsLava - ${difficulty} config leaves ${survivingTiles} surviving tiles; must be >= 1`);
+  }
+  return survivingTiles;
+};
+
+export const SURVIVING_TILES_MAP: Readonly<Record<FloorIsLavaDifficulty, number>> = Object.fromEntries(
+  Object.values(FloorIsLavaDifficulty).map(difficulty => [difficulty, computeSurvivingTiles(difficulty)]),
+) as Record<FloorIsLavaDifficulty, number>;
+
+export enum FloorIsLavaActionPhase {
+  START = 'START',
+  PICK = 'PICK',
+  CASHOUT = 'CASHOUT',
+}
+
+export enum FloorIsLavaGameStatus {
+  IN_PROGRESS = 'IN_PROGRESS',
+  LEVEL_COMPLETE = 'LEVEL_COMPLETE',
+  COMPLETED = 'COMPLETED',
+  LOST = 'LOST',
+}
+
+export interface FloorIsLavaStartAction {
+  phase: FloorIsLavaActionPhase.START;
+  difficulty: FloorIsLavaDifficulty;
+}
+
+export type FloorIsLavaPickAction = {
+  phase: FloorIsLavaActionPhase.PICK;
+  level: number;
+  selectedTile: number;
+  droppedTiles: number[];
+  gameStatus: FloorIsLavaGameStatus;
+  multiplier: BigNumber;
+};
+
+export interface FloorIsLavaCashoutAction {
+  phase: FloorIsLavaActionPhase.CASHOUT;
+  level: number;
+  multiplier: BigNumber;
+}
+
+export type FloorIsLavaGameAction = FloorIsLavaStartAction | FloorIsLavaPickAction | FloorIsLavaCashoutAction;
+
+interface FloorIsLavaBaseState {
+  difficulty: FloorIsLavaDifficulty;
+  currentLevel: number;
+  roundsSurvivedInCurrentLevel: number;
+  droppedTilesByLevel: number[][];
+}
+
+export interface FloorIsLavaInProgressState extends FloorIsLavaBaseState {
+  status: 'in-progress';
+}
+
+interface FloorIsLavaCompletedState extends FloorIsLavaBaseState {
+  status: 'completed';
+}
+
+// reconstructState never throws on a legitimately finished game (LOST/COMPLETED/CASHOUT) - only on
+// structurally corrupt histories. FloorIsLava.fromActions() is the one place that then insists on
+// 'in-progress', since only an active game can be resumed; the frontend can read either variant.
+type FloorIsLavaReconstructedState = FloorIsLavaInProgressState | FloorIsLavaCompletedState;
+
+export interface FloorIsLavaMultipliers {
+  currentMultiplier: BigNumber;
+  nextMultiplier: BigNumber;
+}
+
+export class FloorIsLavaRules {
+  public static tilesRemaining(roundsSurvivedInCurrentLevel: number, dropsPerRound: number): number {
+    return BOARD_SIZE - roundsSurvivedInCurrentLevel * dropsPerRound;
+  }
+
+  public static isValidTile(tile: number): boolean {
+    return Number.isInteger(tile) && tile >= 0 && tile <= BOARD_SIZE - 1;
+  }
+
+  // multiplier = edgeMultiplier * 49^(levelsCleared+1) / (tilesRemainingInLevel * survivingTiles^levelsCleared)
+  public static multiplier(difficulty: FloorIsLavaDifficulty, levelsCleared: number, tilesRemainingInLevel: number, edge: number): BigNumber {
+    const survivingTiles = SURVIVING_TILES_MAP[difficulty];
+    return calculateEdgeMultiplier(edge)
+      .multipliedBy(BigNumber(BOARD_SIZE).pow(levelsCleared + 1))
+      .dividedBy(BigNumber(tilesRemainingInLevel).multipliedBy(BigNumber(survivingTiles).pow(levelsCleared)));
+  }
+
+  // currentLevel never needs to advance for "next" - clearing the level and starting fresh one
+  // level deeper is the same multiplier by construction (see the continuity property above), so
+  // roundsSurvivedInCurrentLevel + 1 alone is enough even on the level's final round.
+  public static multipliers(state: FloorIsLavaInProgressState, edge: number): FloorIsLavaMultipliers {
+    const { difficulty, currentLevel, roundsSurvivedInCurrentLevel } = state;
+    const { dropsPerRound } = DIFFICULTY_LEVEL_MAP[difficulty];
+
+    return {
+      currentMultiplier: FloorIsLavaRules.multiplier(
+        difficulty,
+        currentLevel,
+        FloorIsLavaRules.tilesRemaining(roundsSurvivedInCurrentLevel, dropsPerRound),
+        edge,
+      ),
+      nextMultiplier: FloorIsLavaRules.multiplier(
+        difficulty,
+        currentLevel,
+        FloorIsLavaRules.tilesRemaining(roundsSurvivedInCurrentLevel + 1, dropsPerRound),
+        edge,
+      ),
+    };
+  }
+
+  public static reconstructState(gameActions: FloorIsLavaGameAction[]): FloorIsLavaReconstructedState {
+    const first = gameActions[0];
+    if (!first || first.phase !== FloorIsLavaActionPhase.START) {
+      throw new Error('First action must be START');
+    }
+
+    const { difficulty } = first;
+    const { roundsPerLevel } = DIFFICULTY_LEVEL_MAP[difficulty];
+    let currentLevel = 0;
+    let roundsSurvivedInCurrentLevel = 0;
+    const droppedTilesByLevel: number[][] = Array.from({ length: LEVELS_PER_DIFFICULTY }, () => []);
+
+    for (let i = 1; i < gameActions.length; i++) {
+      const action = gameActions[i];
+      const isLastAction = i === gameActions.length - 1;
+
+      switch (action.phase) {
+        case FloorIsLavaActionPhase.START: {
+          throw new Error('START action can only appear as the first action');
+        }
+
+        case FloorIsLavaActionPhase.CASHOUT: {
+          if (!isLastAction) {
+            throw new Error('A CASHOUT action can only appear as the last action');
+          }
+
+          return { status: 'completed', difficulty, currentLevel, roundsSurvivedInCurrentLevel, droppedTilesByLevel };
+        }
+
+        case FloorIsLavaActionPhase.PICK: {
+          switch (action.gameStatus) {
+            case FloorIsLavaGameStatus.IN_PROGRESS: {
+              droppedTilesByLevel[currentLevel].push(...action.droppedTiles);
+              roundsSurvivedInCurrentLevel++;
+              if (roundsSurvivedInCurrentLevel > roundsPerLevel) {
+                throw new Error(`Reconstructed rounds (${roundsSurvivedInCurrentLevel}) exceeds level max rounds (${roundsPerLevel})`);
+              }
+              break;
+            }
+
+            case FloorIsLavaGameStatus.LEVEL_COMPLETE: {
+              droppedTilesByLevel[currentLevel].push(...action.droppedTiles);
+              currentLevel++;
+              roundsSurvivedInCurrentLevel = 0;
+              if (currentLevel > LEVELS_PER_DIFFICULTY - 1) {
+                throw new Error(`Reconstructed level (${currentLevel}) exceeds max level index (${LEVELS_PER_DIFFICULTY - 1})`);
+              }
+              break;
+            }
+
+            case FloorIsLavaGameStatus.COMPLETED:
+            case FloorIsLavaGameStatus.LOST: {
+              if (!isLastAction) {
+                throw new Error(`A PICK action with gameStatus ${action.gameStatus} can only appear as the last action`);
+              }
+              droppedTilesByLevel[currentLevel].push(...action.droppedTiles);
+              if (action.gameStatus === FloorIsLavaGameStatus.COMPLETED) {
+                roundsSurvivedInCurrentLevel++;
+              }
+              return { status: 'completed', difficulty, currentLevel, roundsSurvivedInCurrentLevel, droppedTilesByLevel };
+            }
+
+            default:
+              action.gameStatus satisfies never;
+          }
+          break;
+        }
+
+        default:
+          action satisfies never;
+      }
+    }
+
+    return { status: 'in-progress', difficulty, currentLevel, roundsSurvivedInCurrentLevel, droppedTilesByLevel };
+  }
+}

package/src/games/floor-is-lava/floor-is-lava.spec.ts

@@ -0,0 +1,455 @@
+import BigNumber from 'bignumber.js';
+import { calculateEdgeMultiplier } from '../../utils/edge';
+import { FixedSequenceRng } from '../rng/fixed-rng';
+import { FloorIsLava } from './floor-is-lava';
+import { FloorIsLavaBoard } from './floor-is-lava-board';
+import {
+  BOARD_SIZE,
+  DIFFICULTY_LEVEL_MAP,
+  FloorIsLavaActionPhase,
+  FloorIsLavaDifficulty,
+  FloorIsLavaGameAction,
+  FloorIsLavaGameStatus,
+  FloorIsLavaPickAction,
+  FloorIsLavaRules,
+  FloorIsLavaStartAction,
+  LEVELS_PER_DIFFICULTY,
+  SURVIVING_TILES_MAP,
+} from './floor-is-lava-rules';
+
+const ALL_DIFFICULTIES = [FloorIsLavaDifficulty.EASY, FloorIsLavaDifficulty.MEDIUM, FloorIsLavaDifficulty.HARD, FloorIsLavaDifficulty.TOXIC];
+
+const EDGE_BPS = 200;
+
+const ASCENDING_BOARD = Array.from({ length: BOARD_SIZE }, (_, i) => i);
+
+const startAction = (difficulty: FloorIsLavaDifficulty): FloorIsLavaStartAction => ({ phase: FloorIsLavaActionPhase.START, difficulty });
+
+const pickAction = (overrides: Partial<FloorIsLavaPickAction> = {}): FloorIsLavaPickAction => ({
+  phase: FloorIsLavaActionPhase.PICK,
+  level: 0,
+  selectedTile: 0,
+  droppedTiles: [],
+  gameStatus: FloorIsLavaGameStatus.IN_PROGRESS,
+  multiplier: new BigNumber(0),
+  ...overrides,
+});
+
+// Builds a game that has cleared `levelsCleared` levels and survived `roundsSurvivedInCurrentLevel` rounds
+// of the current one.
+const gameAtState = (difficulty: FloorIsLavaDifficulty, levelsCleared: number, roundsSurvivedInCurrentLevel: number): FloorIsLava => {
+  const actions: FloorIsLavaGameAction[] = [startAction(difficulty)];
+  for (let level = 0; level < levelsCleared; level++) {
+    actions.push(pickAction({ level, gameStatus: FloorIsLavaGameStatus.LEVEL_COMPLETE }));
+  }
+  for (let i = 0; i < roundsSurvivedInCurrentLevel; i++) {
+    actions.push(pickAction({ level: levelsCleared }));
+  }
+  return FloorIsLava.fromActions(actions);
+};
+
+const expectOk = <T extends { ok: boolean }>(result: T): Extract<T, { ok: true }> => {
+  if (!result.ok) {
+    throw new Error(`Expected an ok result but got: ${JSON.stringify(result)}`);
+  }
+  return result as Extract<T, { ok: true }>;
+};
+
+const expectedMultiplier = (difficulty: FloorIsLavaDifficulty, levelsCleared: number, tilesRemainingInLevel: number, edgeBps: number = EDGE_BPS) =>
+  calculateEdgeMultiplier(edgeBps)
+    .multipliedBy(new BigNumber(BOARD_SIZE).pow(levelsCleared + 1))
+    .dividedBy(new BigNumber(tilesRemainingInLevel).multipliedBy(new BigNumber(SURVIVING_TILES_MAP[difficulty]).pow(levelsCleared)));
+
+// A full 49-tile board whose leading entries are `prefix`, in order.
+const boardWithPrefix = (prefix: number[]): number[] => [...prefix, ...ASCENDING_BOARD.filter(tile => !prefix.includes(tile))];
+
+// Builds a FloorIsLavaBoard from 3 explicit per-level boards (each a permutation of 0..48), so a
+// given level's drops can be controlled precisely in tests.
+const boardFromLevelBoards = (level0: number[], level1: number[], level2: number[]): FloorIsLavaBoard =>
+  FloorIsLavaBoard.draw(new FixedSequenceRng([...level0, ...level1.map(t => t + BOARD_SIZE), ...level2.map(t => t + BOARD_SIZE * 2)]));
+
+// Convenience for tests that only care about level 0's drops - levels 1/2 get an arbitrary filler board.
+const boardForLevel0 = (level0Board: number[]): FloorIsLavaBoard => boardFromLevelBoards(level0Board, ASCENDING_BOARD, ASCENDING_BOARD);
+
+describe('FloorIsLava.createAction', () => {
+  it('returns a START action carrying the difficulty', () => {
+    expect(FloorIsLava.createAction(FloorIsLavaDifficulty.MEDIUM)).toEqual({ phase: 'START', difficulty: FloorIsLavaDifficulty.MEDIUM });
+  });
+});
+
+describe('FloorIsLava.fromActions', () => {
+  describe('valid histories', () => {
+    it('a start-only history cannot be cashed out', () => {
+      expect(gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 0).canCashout()).toBe(false);
+    });
+
+    it('accumulates surviving rounds within a level into cashout eligibility', () => {
+      expect(gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 3).canCashout()).toBe(true);
+    });
+
+    it('having cleared a level makes cashout eligible even with zero rounds in the new level', () => {
+      expect(gameAtState(FloorIsLavaDifficulty.MEDIUM, 1, 0).canCashout()).toBe(true);
+    });
+
+    it('accepts a history at exactly the level max round count', () => {
+      const { roundsPerLevel } = DIFFICULTY_LEVEL_MAP[FloorIsLavaDifficulty.EASY];
+      expect(gameAtState(FloorIsLavaDifficulty.EASY, 0, roundsPerLevel).canCashout()).toBe(true);
+    });
+  });
+
+  describe('validation errors', () => {
+    it('throws on an empty history', () => {
+      expect(() => FloorIsLava.fromActions([])).toThrow('First action must be START');
+    });
+
+    it('throws when the first action is not START', () => {
+      expect(() => FloorIsLava.fromActions([pickAction()])).toThrow('First action must be START');
+    });
+
+    it('throws when a START action appears after the first position', () => {
+      expect(() =>
+        FloorIsLava.fromActions([startAction(FloorIsLavaDifficulty.MEDIUM), pickAction(), startAction(FloorIsLavaDifficulty.MEDIUM)]),
+      ).toThrow('START action can only appear as the first action');
+    });
+
+    it('throws when the history contains a CASHOUT action (game already ended)', () => {
+      expect(() =>
+        FloorIsLava.fromActions([
+          startAction(FloorIsLavaDifficulty.MEDIUM),
+          pickAction(),
+          { phase: FloorIsLavaActionPhase.CASHOUT, level: 0, multiplier: new BigNumber(1) },
+        ]),
+      ).toThrow('FloorIsLava - cannot resume a game that has already ended (status: completed)');
+    });
+
+    it('throws when the history contains a LOST PICK action (game already ended)', () => {
+      expect(() =>
+        FloorIsLava.fromActions([startAction(FloorIsLavaDifficulty.MEDIUM), pickAction({ gameStatus: FloorIsLavaGameStatus.LOST })]),
+      ).toThrow('FloorIsLava - cannot resume a game that has already ended (status: completed)');
+    });
+
+    it('throws when the history contains a COMPLETED PICK action (game already ended)', () => {
+      expect(() =>
+        FloorIsLava.fromActions([startAction(FloorIsLavaDifficulty.MEDIUM), pickAction({ gameStatus: FloorIsLavaGameStatus.COMPLETED })]),
+      ).toThrow('FloorIsLava - cannot resume a game that has already ended (status: completed)');
+    });
+
+    it('throws when survived rounds exceed the level max', () => {
+      // TOXIC drops all 48 in one round, so its level max is 1 round
+      expect(() => FloorIsLava.fromActions([startAction(FloorIsLavaDifficulty.TOXIC), pickAction(), pickAction()])).toThrow(
+        'Reconstructed rounds (2) exceeds level max rounds (1)',
+      );
+    });
+
+    it('throws when more levels are cleared than exist', () => {
+      const clear = (level: number) => pickAction({ level, gameStatus: FloorIsLavaGameStatus.LEVEL_COMPLETE });
+      expect(() => FloorIsLava.fromActions([startAction(FloorIsLavaDifficulty.MEDIUM), clear(0), clear(1), clear(2)])).toThrow(
+        'Reconstructed level (3) exceeds max level index (2)',
+      );
+    });
+  });
+});
+
+describe('FloorIsLava.getDetailedState', () => {
+  it('returns the reconstructed in-progress state', () => {
+    expect(gameAtState(FloorIsLavaDifficulty.MEDIUM, 1, 2).getDetailedState()).toMatchObject({
+      status: 'in-progress',
+      difficulty: FloorIsLavaDifficulty.MEDIUM,
+      currentLevel: 1,
+      roundsSurvivedInCurrentLevel: 2,
+    });
+  });
+});
+
+describe('FloorIsLava.getMultipliers', () => {
+  it('matches FloorIsLavaRules.multipliers computed from the same reconstructed state', () => {
+    const game = gameAtState(FloorIsLavaDifficulty.MEDIUM, 1, 2);
+
+    const result = game.getMultipliers(EDGE_BPS);
+    const expected = FloorIsLavaRules.multipliers(game.getDetailedState(), EDGE_BPS);
+
+    expect(result.currentMultiplier.isEqualTo(expected.currentMultiplier)).toBe(true);
+    expect(result.nextMultiplier.isEqualTo(expected.nextMultiplier)).toBe(true);
+  });
+
+  it.each([100, 500, 1000])('applies the given edge (%i bps), not a hardcoded value', edgeBps => {
+    const { dropsPerRound } = DIFFICULTY_LEVEL_MAP[FloorIsLavaDifficulty.MEDIUM];
+    const result = gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 2).getMultipliers(edgeBps);
+
+    expect(
+      result.currentMultiplier.isEqualTo(
+        expectedMultiplier(FloorIsLavaDifficulty.MEDIUM, 0, FloorIsLavaRules.tilesRemaining(2, dropsPerRound), edgeBps),
+      ),
+    ).toBe(true);
+    expect(
+      result.nextMultiplier.isEqualTo(
+        expectedMultiplier(FloorIsLavaDifficulty.MEDIUM, 0, FloorIsLavaRules.tilesRemaining(3, dropsPerRound), edgeBps),
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('FloorIsLava.next', () => {
+  const anyValidBoard = boardFromLevelBoards(ASCENDING_BOARD, ASCENDING_BOARD, ASCENDING_BOARD);
+
+  it.each([-1, 49, 1.5, NaN])('rejects an out-of-range selectedTile (%s)', tile => {
+    expect(gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 0).next(tile, anyValidBoard, EDGE_BPS)).toEqual({ ok: false, error: 'invalid-tile' });
+  });
+
+  it('a surviving first pick keeps the game open and pays the 1-round multiplier', () => {
+    const board = boardForLevel0(boardWithPrefix([10, 11, 12, 13, 14, 15, 16])); // EASY: dropsPerRound 7
+    const result = expectOk(gameAtState(FloorIsLavaDifficulty.EASY, 0, 0).next(5, board, EDGE_BPS));
+
+    expect(result).toMatchObject({
+      tilesDroppedInCurrentLevel: 7,
+      gameAction: {
+        phase: 'PICK',
+        level: 0,
+        gameStatus: 'IN_PROGRESS',
+        selectedTile: 5,
+        droppedTiles: [10, 11, 12, 13, 14, 15, 16],
+      },
+    });
+    expect(result.multiplier.isEqualTo(expectedMultiplier(FloorIsLavaDifficulty.EASY, 0, 42))).toBe(true);
+  });
+
+  it('a pick that lands on a dropped tile zeroes the multiplier and reports LOST', () => {
+    const board = boardForLevel0(boardWithPrefix([10, 11, 12, 13, 14, 15, 16]));
+    const result = expectOk(gameAtState(FloorIsLavaDifficulty.EASY, 0, 0).next(12, board, EDGE_BPS));
+
+    expect(result).toMatchObject({
+      multiplier: new BigNumber(0),
+      tilesDroppedInCurrentLevel: 7,
+      gameAction: {
+        phase: 'PICK',
+        level: 0,
+        gameStatus: 'LOST',
+        selectedTile: 12,
+        droppedTiles: [10, 11, 12, 13, 14, 15, 16],
+        multiplier: new BigNumber(0),
+      },
+    });
+  });
+
+  it('drops this round from the level board and excludes prior-round drops', () => {
+    const priorRounds = Array.from({ length: 14 }, (_, i) => i); // 2 rounds of 7 already survived
+    const thisRound = [20, 21, 22, 23, 24, 25, 26];
+    const board = boardForLevel0(boardWithPrefix([...priorRounds, ...thisRound]));
+
+    const result = expectOk(gameAtState(FloorIsLavaDifficulty.EASY, 0, 2).next(30, board, EDGE_BPS));
+
+    expect(result).toMatchObject({ tilesDroppedInCurrentLevel: 21, gameAction: { droppedTiles: thisRound } });
+    expect(result.multiplier.isEqualTo(expectedMultiplier(FloorIsLavaDifficulty.EASY, 0, 28))).toBe(true);
+  });
+
+  it('a pick on a tile dropped in an earlier round of this level is rejected', () => {
+    const priorRounds = Array.from({ length: 14 }, (_, i) => i); // 2 rounds of 7 already survived
+    const thisRound = [20, 21, 22, 23, 24, 25, 26];
+    const board = boardForLevel0(boardWithPrefix([...priorRounds, ...thisRound]));
+
+    // Built manually (not via gameAtState) so droppedTilesByLevel actually contains the prior drops -
+    // next()'s already-dropped check reads from reconstructed history, not from the board.
+    const game = FloorIsLava.fromActions([
+      startAction(FloorIsLavaDifficulty.EASY),
+      pickAction({ selectedTile: 30, droppedTiles: priorRounds.slice(0, 7) }),
+      pickAction({ selectedTile: 31, droppedTiles: priorRounds.slice(7, 14) }),
+    ]);
+
+    expect(game.next(2, board, EDGE_BPS)).toEqual({ ok: false, error: 'tile-already-dropped' });
+  });
+
+  it('returns no-tiles-remaining once the level rounds are exhausted', () => {
+    const { roundsPerLevel } = DIFFICULTY_LEVEL_MAP[FloorIsLavaDifficulty.EASY];
+    expect(gameAtState(FloorIsLavaDifficulty.EASY, 0, roundsPerLevel).next(0, anyValidBoard, EDGE_BPS)).toEqual({
+      ok: false,
+      error: 'no-tiles-remaining',
+    });
+  });
+
+  it('clearing the final round of a non-final level emits LEVEL_COMPLETE', () => {
+    const difficulty = FloorIsLavaDifficulty.EASY;
+    const { dropsPerRound, roundsPerLevel } = DIFFICULTY_LEVEL_MAP[difficulty];
+    const priorRoundsDrops = Array.from({ length: (roundsPerLevel - 1) * dropsPerRound }, (_, i) => i); // rounds 1-5
+    const lastRoundDrops = [40, 41, 42, 43, 44, 45, 46];
+    const board = boardForLevel0(boardWithPrefix([...priorRoundsDrops, ...lastRoundDrops]));
+
+    const result = expectOk(gameAtState(difficulty, 0, roundsPerLevel - 1).next(35, board, EDGE_BPS));
+
+    expect(result).toMatchObject({
+      tilesDroppedInCurrentLevel: roundsPerLevel * dropsPerRound,
+      gameAction: { phase: 'PICK', level: 0, gameStatus: 'LEVEL_COMPLETE', selectedTile: 35, droppedTiles: lastRoundDrops },
+    });
+    expect(result.multiplier.isEqualTo(expectedMultiplier(difficulty, 0, SURVIVING_TILES_MAP[difficulty]))).toBe(true);
+  });
+
+  it('clearing the final round of the final level emits COMPLETED', () => {
+    const difficulty = FloorIsLavaDifficulty.EASY;
+    const { dropsPerRound, roundsPerLevel } = DIFFICULTY_LEVEL_MAP[difficulty];
+    const priorRoundsDrops = Array.from({ length: (roundsPerLevel - 1) * dropsPerRound }, (_, i) => i);
+    const lastRoundDrops = [40, 41, 42, 43, 44, 45, 46];
+    const board = boardFromLevelBoards(ASCENDING_BOARD, ASCENDING_BOARD, boardWithPrefix([...priorRoundsDrops, ...lastRoundDrops]));
+
+    const result = expectOk(gameAtState(difficulty, LEVELS_PER_DIFFICULTY - 1, roundsPerLevel - 1).next(35, board, EDGE_BPS));
+
+    expect(result).toMatchObject({
+      tilesDroppedInCurrentLevel: roundsPerLevel * dropsPerRound,
+      gameAction: {
+        phase: 'PICK',
+        level: LEVELS_PER_DIFFICULTY - 1,
+        gameStatus: 'COMPLETED',
+        selectedTile: 35,
+        droppedTiles: lastRoundDrops,
+      },
+    });
+    expect(result.multiplier.isEqualTo(expectedMultiplier(difficulty, LEVELS_PER_DIFFICULTY - 1, SURVIVING_TILES_MAP[difficulty]))).toBe(true);
+  });
+
+  it('draws an independent board per level - no leakage across a level transition', () => {
+    const level0Board = boardWithPrefix([10, 11, 12, 13, 14, 15, 16]);
+    const level1Board = boardWithPrefix([30, 31, 32, 33, 34, 35, 36]); // deliberately different pattern
+    const board = boardFromLevelBoards(level0Board, level1Board, ASCENDING_BOARD);
+
+    const level0Result = expectOk(gameAtState(FloorIsLavaDifficulty.EASY, 0, 0).next(20, board, EDGE_BPS));
+    expect(level0Result.gameAction.droppedTiles).toEqual([10, 11, 12, 13, 14, 15, 16]);
+
+    const level1Result = expectOk(gameAtState(FloorIsLavaDifficulty.EASY, 1, 0).next(20, board, EDGE_BPS));
+    expect(level1Result.gameAction.droppedTiles).toEqual([30, 31, 32, 33, 34, 35, 36]);
+    expect(level1Result.gameAction.droppedTiles).not.toEqual(level0Result.gameAction.droppedTiles);
+  });
+});
+
+describe('FloorIsLava — chained real sessions (fromActions replay of actual next()/cashout() output)', () => {
+  it('threads real next() output through fromActions across rounds and a level transition', () => {
+    const difficulty = FloorIsLavaDifficulty.HARD; // dropsPerRound 23, roundsPerLevel 2, survivingTiles 3
+    const level0Board = ASCENDING_BOARD; // rounds: [0-22], [23-45], remaining [46,47,48]
+    const level1Board = [...ASCENDING_BOARD].reverse(); // round 0: [48..26]
+    const board = boardFromLevelBoards(level0Board, level1Board, ASCENDING_BOARD);
+
+    const game0 = FloorIsLava.fromActions([startAction(difficulty)]);
+    const round1 = expectOk(game0.next(46, board, EDGE_BPS));
+    expect(round1).toMatchObject({ gameAction: { level: 0, gameStatus: 'IN_PROGRESS', droppedTiles: level0Board.slice(0, 23) } });
+
+    const game1 = FloorIsLava.fromActions([startAction(difficulty), round1.gameAction]);
+    const round2 = expectOk(game1.next(47, board, EDGE_BPS));
+    expect(round2).toMatchObject({ gameAction: { level: 0, gameStatus: 'LEVEL_COMPLETE', droppedTiles: level0Board.slice(23, 46) } });
+
+    const game2 = FloorIsLava.fromActions([startAction(difficulty), round1.gameAction, round2.gameAction]);
+    expect(game2.canCashout()).toBe(true);
+
+    const level1Round1 = expectOk(game2.next(0, board, EDGE_BPS));
+    expect(level1Round1).toMatchObject({ gameAction: { level: 1, gameStatus: 'IN_PROGRESS', droppedTiles: level1Board.slice(0, 23) } });
+    expect(level1Round1.gameAction.droppedTiles).not.toEqual(round1.gameAction.droppedTiles);
+
+    const game3 = FloorIsLava.fromActions([startAction(difficulty), round1.gameAction, round2.gameAction, level1Round1.gameAction]);
+    const cashoutResult = expectOk(game3.cashout(EDGE_BPS));
+    expect(cashoutResult.gameAction).toEqual({ phase: FloorIsLavaActionPhase.CASHOUT, level: 1, multiplier: cashoutResult.multiplier });
+    expect(cashoutResult.multiplier.isEqualTo(expectedMultiplier(difficulty, 1, FloorIsLavaRules.tilesRemaining(1, 23)))).toBe(true);
+  });
+
+  it('threads a real survived pick into a second round that busts', () => {
+    const difficulty = FloorIsLavaDifficulty.EASY; // dropsPerRound 7
+    const board = boardForLevel0(boardWithPrefix([0, 1, 2, 3, 4, 5, 6, 10, 11, 12, 13, 14, 15, 16]));
+
+    const game0 = FloorIsLava.fromActions([startAction(difficulty)]);
+    const round1 = expectOk(game0.next(20, board, EDGE_BPS));
+    expect(round1.gameAction.gameStatus).toBe('IN_PROGRESS');
+
+    const game1 = FloorIsLava.fromActions([startAction(difficulty), round1.gameAction]);
+    const round2 = expectOk(game1.next(12, board, EDGE_BPS));
+
+    expect(round2).toMatchObject({
+      multiplier: new BigNumber(0),
+      gameAction: { level: 0, gameStatus: 'LOST', selectedTile: 12, droppedTiles: [10, 11, 12, 13, 14, 15, 16] },
+    });
+  });
+});
+
+describe('FloorIsLava.cashout', () => {
+  it.each([
+    [FloorIsLavaDifficulty.MEDIUM, 0, 1],
+    [FloorIsLavaDifficulty.MEDIUM, 0, 3],
+    [FloorIsLavaDifficulty.HARD, 0, 2],
+    [FloorIsLavaDifficulty.MEDIUM, 1, 0],
+    [FloorIsLavaDifficulty.MEDIUM, 1, 4],
+    [FloorIsLavaDifficulty.EASY, 2, 3],
+  ])('cashing out %s after clearing %i level(s) and %i round(s) pays the telescoped multiplier', (difficulty, levelsCleared, rounds) => {
+    const { dropsPerRound } = DIFFICULTY_LEVEL_MAP[difficulty];
+    const result = expectOk(gameAtState(difficulty, levelsCleared, rounds).cashout(EDGE_BPS));
+
+    const tilesRemainingInLevel = FloorIsLavaRules.tilesRemaining(rounds, dropsPerRound);
+    expect(result.multiplier.isEqualTo(expectedMultiplier(difficulty, levelsCleared, tilesRemainingInLevel))).toBe(true);
+    expect(result.gameAction).toEqual({ phase: FloorIsLavaActionPhase.CASHOUT, level: levelsCleared, multiplier: result.multiplier });
+    expect(result.tilesDroppedInCurrentLevel).toBe(rounds * dropsPerRound);
+  });
+
+  it('returns no-tiles-selected with zero rounds survived at level 0', () => {
+    expect(gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 0).cashout(EDGE_BPS)).toEqual({ ok: false, error: 'no-tiles-selected' });
+  });
+});
+
+describe('FloorIsLava — edge parameter', () => {
+  it.each([100, 500, 1000])('cashout applies the given edge (%i bps), not a hardcoded value', edgeBps => {
+    const { dropsPerRound } = DIFFICULTY_LEVEL_MAP[FloorIsLavaDifficulty.MEDIUM];
+    const result = expectOk(gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 3).cashout(edgeBps));
+    expect(
+      result.multiplier.isEqualTo(expectedMultiplier(FloorIsLavaDifficulty.MEDIUM, 0, FloorIsLavaRules.tilesRemaining(3, dropsPerRound), edgeBps)),
+    ).toBe(true);
+  });
+
+  it.each([100, 500, 1000])('next applies the given edge (%i bps) to a surviving pick', edgeBps => {
+    const board = boardForLevel0(boardWithPrefix([10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20])); // MEDIUM: dropsPerRound 11
+    const result = expectOk(gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 0).next(5, board, edgeBps));
+    expect(result.multiplier.isEqualTo(expectedMultiplier(FloorIsLavaDifficulty.MEDIUM, 0, BOARD_SIZE - 11, edgeBps))).toBe(true);
+  });
+
+  it('rejects an edge below the platform minimum (100 bps) on cashout', () => {
+    expect(() => gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 3).cashout(99)).toThrow('Exceeded Minimum edge allowed on platform');
+  });
+
+  it('rejects an edge below the platform minimum (100 bps) on a surviving next()', () => {
+    const board = boardForLevel0(boardWithPrefix([10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]));
+    expect(() => gameAtState(FloorIsLavaDifficulty.MEDIUM, 0, 0).next(5, board, 99)).toThrow('Exceeded Minimum edge allowed on platform');
+  });
+});
+
+describe('FloorIsLava — exhaustive multiplier & RTP across every level and round', () => {
+  const houseEdge = calculateEdgeMultiplier(EDGE_BPS); // 0.98 == 98% RTP
+
+  // Win chance derived independently, round by round within a level, as the product of each round's
+  // survival probability. Makes no assumption about telescoping.
+  const roundsWinChance = (rounds: number, dropsPerRound: number): BigNumber => {
+    let chance = new BigNumber(1);
+    for (let r = 1; r <= rounds; r++) {
+      const standingBefore = BOARD_SIZE - (r - 1) * dropsPerRound;
+      chance = chance.multipliedBy(standingBefore - dropsPerRound).dividedBy(standingBefore);
+    }
+    return chance;
+  };
+
+  it.each(ALL_DIFFICULTIES)('%s: every reachable (levelsCleared, round) endpoint pays fair odds and returns 98%% RTP', difficulty => {
+    const { dropsPerRound, roundsPerLevel } = DIFFICULTY_LEVEL_MAP[difficulty];
+    const levelClearChance = roundsWinChance(roundsPerLevel, dropsPerRound); // equals survivingTiles/49, derived independently
+
+    for (let levelsCleared = 0; levelsCleared < LEVELS_PER_DIFFICULTY; levelsCleared++) {
+      const priorLevelsChance = levelClearChance.pow(levelsCleared);
+
+      for (let k = 0; k <= roundsPerLevel; k++) {
+        const tilesRemainingInLevel = FloorIsLavaRules.tilesRemaining(k, dropsPerRound);
+        const chance = priorLevelsChance.multipliedBy(roundsWinChance(k, dropsPerRound));
+        const multiplier = FloorIsLavaRules.multiplier(difficulty, levelsCleared, tilesRemainingInLevel, EDGE_BPS);
+
+        // fair payout inverts the win chance and applies the edge once: houseEdge / chance
+        expect(multiplier.toNumber()).toBeCloseTo(houseEdge.dividedBy(chance).toNumber(), 9);
+
+        // the game surface (fromActions + cashout) returns the same endpoint multiplier, except at
+        // levelsCleared=0,k=0 which has nothing selected yet and cannot be cashed out
+        if (levelsCleared > 0 || k > 0) {
+          expect(expectOk(gameAtState(difficulty, levelsCleared, k).cashout(EDGE_BPS)).multiplier.isEqualTo(multiplier)).toBe(true);
+        }
+
+        // RTP == winChance * payout is the house edge at EVERY endpoint, not just on average
+        expect(chance.multipliedBy(multiplier).toNumber()).toBeCloseTo(houseEdge.toNumber(), 9);
+      }
+    }
+  });
+});