Scenario engine and exact solver

// The board result is produced by the shared primitive `drop7::applyGravity`;
// only the latent permutation is computed here, with the identical loop shape,
// so the two arrays can never drift apart.  `scenario-parity.cpp` additionally
// asserts the permutation agrees with `drop7::applyGravity` on random boards.
inline void applyGravityPaired(const Board& board, const LatentBoard& latent,
                               Board& out_board, LatentBoard& out_latent) {
  out_latent.fill(0);
  for (int column = 0; column < kBoardSize; ++column) {
    int destination = kBoardSize - 1;
    for (int row = kBoardSize - 1; row >= 0; --row) {
      const int index = indexOf(row, column);
      if (board[index] == kEmpty) continue;
      out_latent[indexOf(destination--, column)] = latent[index];
    }
  }
  out_board = applyGravity(board);
}

// Board legality and the row shift come from `drop7::raiseCoveredRow`.
inline bool raiseCoveredRowPaired(const Board& board, const LatentBoard& latent,
                                  const RiseRow& rise_latent, Board& out_board,
                                  LatentBoard& out_latent) {
  Board raised{};
  if (!raiseCoveredRow(board, raised)) return false;
  out_latent.fill(0);
  for (int row = 0; row < kBoardSize - 1; ++row) {
    for (int column = 0; column < kBoardSize; ++column) {
      out_latent[indexOf(row, column)] = latent[indexOf(row + 1, column)];
    }
  }
  for (int column = 0; column < kBoardSize; ++column) {
    out_latent[indexOf(kBoardSize - 1, column)] = rise_latent[column];
  }
  out_board = raised;
  return true;

// Reproduces `drop7::playMove` exactly: reveal values and the next visible disc
// both come from one Mulberry32 stream, in the engine's consumption order.
struct StreamRevealSource {
  Mulberry32* random = nullptr;

  std::uint8_t reveal(int /*index*/, const LatentBoard& /*latent*/) {
    return random->nextDisc();
  }
  std::uint8_t nextVisibleDisc() { return random->nextDisc(); }
  RiseRow riseValues() { return RiseRow{}; }  // latent unused in stream mode
  bool exhausted() const { return false; }
};

// Consumes the fixed hidden value that already sits under each covered cell.
// Cells introduced by a row rise take their values from `rise_rows`, and the
// visible disc sequence is read from `tape`.
struct LatentRevealSource {
  const std::uint8_t* tape = nullptr;
  int tape_length = 0;
  int tape_index = 0;
  const RiseRow* rise_rows = nullptr;
  int rise_count = 0;
  int rise_index = 0;
  bool tape_exhausted = false;
  bool rise_exhausted = false;
  bool invalid_latent = false;

  std::uint8_t reveal(int index, const LatentBoard& latent) {
    const std::uint8_t value = latent[index];
    if (value < 1 || value > kBoardSize) {
      invalid_latent = true;
      return 1;
    }
    return value;
  }
  // Beyond the tape the scenario is undefined; callers stop at the horizon, so
  // a 0 here marks "no further disc is specified" rather than a legal disc.
  std::uint8_t nextVisibleDisc() {
    if (tape_index >= tape_length) {
      tape_exhausted = true;
      return 0;
    }
    return tape[tape_index++];
  }
  RiseRow riseValues() {
    if (rise_index >= rise_count) {
      rise_exhausted = true;
      return RiseRow{};
    }
    return rise_rows[rise_index++];
  }
  bool exhausted() const { return tape_exhausted || rise_exhausted; }
};

// Applies one move of a scenario at search depth `depth`.  Everything the
// reveal source needs is a function of the depth alone: the tape index, the
// rise index, and the number of moves left before the next rise.  This is what
// makes a scenario node exactly (board, latent, depth).
inline bool applyScenarioMove(const Scenario& scenario, const SearchNode& node,
                              int depth, int column, SearchNode& child,
                              std::int64_t& delta, bool& game_over,
                              MoveResult& scratch) {
  State state;
  state.board = node.board;
  state.next_disc = scenario.disc_tape[static_cast<std::size_t>(depth)];
  state.score = 0;
  state.level = 1;
  state.moves_remaining = movesRemainingAt(scenario.moves_remaining, depth);
  state.moves_played = depth;
  state.game_over = false;

  LatentRevealSource source;
  source.tape = scenario.disc_tape.data();
  source.tape_length = static_cast<int>(scenario.disc_tape.size());
  source.tape_index = depth + 1;
  source.rise_rows = scenario.rise_latent.data();
  source.rise_count = static_cast<int>(scenario.rise_latent.size());
  source.rise_index = risesConsumed(depth, scenario.moves_remaining);

  if (!playScenarioMove(state, node.latent, column, source, scratch,
                        child.latent)) {
    return false;
  }
  child.board = scratch.state.board;
  delta = scratch.score_delta;
  game_over = scratch.state.game_over;
  return true;
}