Merge pull request '✨Feature: implement run state management with combat resolution and room entry' (#7) from feature/run-state-flow into staging/features

Reviewed-on: #7

src/rules/combatTurns.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "vitest";
+
+import { sampleContentPack } from "@/data/sampleContentPack";
+
+import { createStartingAdventurer } from "./character";
+import { startCombatFromRoom } from "./combat";
+import { resolveEnemyTurn, resolvePlayerAttack } from "./combatTurns";
+import { createRoomStateFromTemplate } from "./rooms";
+
+function createSequenceRoller(values: number[]) {
+  let index = 0;
+
+  return () => {
+    const next = values[index];
+    index += 1;
+    return next;
+  };
+}
+
+function createGuardCombat() {
+  const adventurer = createStartingAdventurer(sampleContentPack, {
+    name: "Aster",
+    weaponId: "weapon.short-sword",
+    armourId: "armour.leather-vest",
+    scrollId: "scroll.lesser-heal",
+  });
+  const room = createRoomStateFromTemplate(
+    sampleContentPack,
+    "room.level1.guard-room",
+    1,
+    "room.level1.normal.guard-room",
+  );
+  room.encounter = {
+    id: `${room.id}.encounter`,
+    sourceTableCode: "L1G",
+    creatureIds: ["a", "b"],
+    creatureNames: ["Guard", "Warrior"],
+    resultLabel: "Guard and Warrior",
+    resolved: true,
+  };
+
+  return {
+    adventurer,
+    ...startCombatFromRoom({
+      content: sampleContentPack,
+      adventurer,
+      room,
+      at: "2026-03-15T13:00:00.000Z",
+    }),
+  };
+}
+
+describe("combat turns", () => {
+  it("lets the player hit an enemy and pass initiative", () => {
+    const { adventurer, combat } = createGuardCombat();
+    const targetId = combat.enemies[0]!.id;
+
+    const result = resolvePlayerAttack({
+      content: sampleContentPack,
+      combat,
+      adventurer,
+      manoeuvreId: "manoeuvre.exact-strike",
+      targetEnemyId: targetId,
+      roller: createSequenceRoller([6, 6]),
+      at: "2026-03-15T13:01:00.000Z",
+    });
+
+    expect(result.combat.actingSide).toBe("enemy");
+    expect(result.combat.selectedManoeuvreId).toBe("manoeuvre.exact-strike");
+    expect(result.combat.enemies[0]?.hpCurrent).toBeLessThan(result.combat.enemies[0]!.hpMax);
+    expect(result.logEntries[0]?.text).toContain("deals");
+  });
+
+  it("marks an enemy defeated when the player deals lethal damage", () => {
+    const { adventurer, combat } = createGuardCombat();
+    combat.enemies[0]!.hpCurrent = 1;
+
+    const result = resolvePlayerAttack({
+      content: sampleContentPack,
+      combat,
+      adventurer,
+      manoeuvreId: "manoeuvre.guard-break",
+      targetEnemyId: combat.enemies[0]!.id,
+      roller: createSequenceRoller([6, 5]),
+      at: "2026-03-15T13:02:00.000Z",
+    });
+
+    expect(result.defeatedEnemyIds).toEqual([combat.enemies[0]!.id]);
+    expect(result.logEntries.map((entry) => entry.text)).toContain("Guard is defeated.");
+  });
+
+  it("lets an enemy attack the player and advances the round", () => {
+    const { adventurer, combat } = createGuardCombat();
+    const afterPlayer = resolvePlayerAttack({
+      content: sampleContentPack,
+      combat,
+      adventurer,
+      manoeuvreId: "manoeuvre.exact-strike",
+      targetEnemyId: combat.enemies[0]!.id,
+      roller: createSequenceRoller([4, 4]),
+      at: "2026-03-15T13:03:00.000Z",
+    });
+
+    const result = resolveEnemyTurn({
+      content: sampleContentPack,
+      combat: afterPlayer.combat,
+      adventurer,
+      roller: createSequenceRoller([6, 6]),
+      at: "2026-03-15T13:04:00.000Z",
+    });
+
+    expect(result.combat.round).toBe(2);
+    expect(result.combat.actingSide).toBe("player");
+    expect(result.combat.player.hpCurrent).toBeLessThan(result.combat.player.hpMax);
+    expect(result.logEntries[0]?.text).toContain("attacks");
+  });
+
+  it("rejects player turns that target a defeated enemy", () => {
+    const { adventurer, combat } = createGuardCombat();
+    combat.enemies[0]!.hpCurrent = 0;
+
+    expect(() =>
+      resolvePlayerAttack({
+        content: sampleContentPack,
+        combat,
+        adventurer,
+        manoeuvreId: "manoeuvre.exact-strike",
+        targetEnemyId: combat.enemies[0]!.id,
+      }),
+    ).toThrow("Unknown or defeated target");
+  });
+});

src/rules/combatTurns.ts

@@ -0,0 +1,255 @@
+import type {
+  ArmourDefinition,
+  ContentPack,
+  ManoeuvreDefinition,
+  WeaponDefinition,
+} from "@/types/content";
+import type { AdventurerState, CombatState, CombatantState } from "@/types/state";
+import type { LogEntry } from "@/types/rules";
+
+import { roll2D6, type DiceRoller } from "./dice";
+
+export type ResolvePlayerAttackOptions = {
+  content: ContentPack;
+  combat: CombatState;
+  adventurer: AdventurerState;
+  manoeuvreId: string;
+  targetEnemyId: string;
+  roller?: DiceRoller;
+  at?: string;
+};
+
+export type ResolveEnemyTurnOptions = {
+  content: ContentPack;
+  combat: CombatState;
+  adventurer: AdventurerState;
+  roller?: DiceRoller;
+  at?: string;
+};
+
+export type CombatTurnResult = {
+  combat: CombatState;
+  logEntries: LogEntry[];
+  defeatedEnemyIds: string[];
+  combatEnded: boolean;
+};
+
+const BASE_TARGET_NUMBER = 7;
+
+function requireWeapon(content: ContentPack, weaponId: string): WeaponDefinition {
+  const weapon = content.weapons.find((entry) => entry.id === weaponId);
+
+  if (!weapon) {
+    throw new Error(`Unknown weapon id: ${weaponId}`);
+  }
+
+  return weapon;
+}
+
+function requireManoeuvre(content: ContentPack, manoeuvreId: string): ManoeuvreDefinition {
+  const manoeuvre = content.manoeuvres.find((entry) => entry.id === manoeuvreId);
+
+  if (!manoeuvre) {
+    throw new Error(`Unknown manoeuvre id: ${manoeuvreId}`);
+  }
+
+  return manoeuvre;
+}
+
+function findArmour(content: ContentPack, armourId?: string): ArmourDefinition | undefined {
+  if (!armourId) {
+    return undefined;
+  }
+
+  return content.armour.find((entry) => entry.id === armourId);
+}
+
+function cloneCombatant(combatant: CombatantState): CombatantState {
+  return {
+    ...combatant,
+    statuses: [...combatant.statuses],
+    traits: [...combatant.traits],
+  };
+}
+
+function cloneCombat(combat: CombatState): CombatState {
+  return {
+    ...combat,
+    player: cloneCombatant(combat.player),
+    enemies: combat.enemies.map(cloneCombatant),
+    combatLog: combat.combatLog.map((entry) => ({
+      ...entry,
+      relatedIds: entry.relatedIds ? [...entry.relatedIds] : undefined,
+    })),
+  };
+}
+
+function createLogEntry(
+  id: string,
+  at: string,
+  text: string,
+  relatedIds: string[],
+): LogEntry {
+  return {
+    id,
+    at,
+    type: "combat",
+    text,
+    relatedIds,
+  };
+}
+
+function getPlayerArmourValue(content: ContentPack, adventurer: AdventurerState) {
+  return findArmour(content, adventurer.armourId)?.armourValue ?? 0;
+}
+
+function isAlive(combatant: CombatantState) {
+  return combatant.hpCurrent > 0;
+}
+
+function getLivingEnemies(combat: CombatState) {
+  return combat.enemies.filter(isAlive);
+}
+
+export function resolvePlayerAttack(
+  options: ResolvePlayerAttackOptions,
+): CombatTurnResult {
+  if (options.combat.actingSide !== "player") {
+    throw new Error("It is not currently the player's turn.");
+  }
+
+  const combat = cloneCombat(options.combat);
+  const at = options.at ?? new Date().toISOString();
+  const weapon = requireWeapon(options.content, options.adventurer.weaponId);
+  const manoeuvre = requireManoeuvre(options.content, options.manoeuvreId);
+
+  if (!options.adventurer.manoeuvreIds.includes(manoeuvre.id)) {
+    throw new Error(`Adventurer cannot use manoeuvre ${manoeuvre.id}.`);
+  }
+
+  if (!manoeuvre.weaponCategories.includes(weapon.category)) {
+    throw new Error(`Manoeuvre ${manoeuvre.id} is not compatible with ${weapon.id}.`);
+  }
+
+  const target = combat.enemies.find((enemy) => enemy.id === options.targetEnemyId);
+
+  if (!target || !isAlive(target)) {
+    throw new Error(`Unknown or defeated target enemy: ${options.targetEnemyId}`);
+  }
+
+  const roll = roll2D6(options.roller);
+  const accuracy =
+    (roll.total ?? 0) +
+    combat.player.precision +
+    (manoeuvre.precisionModifier ?? 0);
+  const targetNumber = BASE_TARGET_NUMBER + (target.armourValue ?? 0);
+  const hit = accuracy >= targetNumber;
+  const rawDamage = hit
+    ? weapon.baseDamage +
+      Math.max(0, combat.player.discipline + (manoeuvre.damageModifier ?? 0))
+    : 0;
+  const damage = hit ? Math.max(1, rawDamage) : 0;
+
+  if (hit) {
+    target.hpCurrent = Math.max(0, target.hpCurrent - damage);
+  }
+
+  combat.selectedManoeuvreId = manoeuvre.id;
+  combat.lastRoll = roll;
+  combat.actingSide = getLivingEnemies(combat).length === 0 ? "player" : "enemy";
+
+  const logEntries: LogEntry[] = [
+    createLogEntry(
+      `${combat.id}.player.${combat.combatLog.length + 1}`,
+      at,
+      hit
+        ? `${combat.player.name} uses ${manoeuvre.name} on ${target.name}, rolls ${roll.total}, and deals ${damage} damage.`
+        : `${combat.player.name} uses ${manoeuvre.name} on ${target.name}, rolls ${roll.total}, and misses.`,
+      [combat.player.id, target.id],
+    ),
+  ];
+
+  const defeatedEnemyIds = !isAlive(target) ? [target.id] : [];
+
+  if (defeatedEnemyIds.length > 0) {
+    logEntries.push(
+      createLogEntry(
+        `${combat.id}.player.${combat.combatLog.length + 2}`,
+        at,
+        `${target.name} is defeated.`,
+        [target.id],
+      ),
+    );
+  }
+
+  combat.combatLog.push(...logEntries);
+
+  return {
+    combat,
+    logEntries,
+    defeatedEnemyIds,
+    combatEnded: getLivingEnemies(combat).length === 0,
+  };
+}
+
+export function resolveEnemyTurn(
+  options: ResolveEnemyTurnOptions,
+): CombatTurnResult {
+  if (options.combat.actingSide !== "enemy") {
+    throw new Error("It is not currently the enemy's turn.");
+  }
+
+  const combat = cloneCombat(options.combat);
+  const at = options.at ?? new Date().toISOString();
+  const attacker = getLivingEnemies(combat)[0];
+
+  if (!attacker) {
+    throw new Error("No living enemies are available to act.");
+  }
+
+  const roll = roll2D6(options.roller);
+  const armourValue = getPlayerArmourValue(options.content, options.adventurer);
+  const accuracy = (roll.total ?? 0) + attacker.precision;
+  const targetNumber = BASE_TARGET_NUMBER + armourValue;
+  const hit = accuracy >= targetNumber;
+  const rawDamage = hit ? Math.max(1, 1 + attacker.discipline) : 0;
+
+  if (hit) {
+    combat.player.hpCurrent = Math.max(0, combat.player.hpCurrent - rawDamage);
+  }
+
+  combat.lastRoll = roll;
+  combat.actingSide = combat.player.hpCurrent > 0 ? "player" : "enemy";
+  combat.round += 1;
+
+  const logEntries: LogEntry[] = [
+    createLogEntry(
+      `${combat.id}.enemy.${combat.combatLog.length + 1}`,
+      at,
+      hit
+        ? `${attacker.name} attacks ${combat.player.name}, rolls ${roll.total}, and deals ${rawDamage} damage.`
+        : `${attacker.name} attacks ${combat.player.name}, rolls ${roll.total}, and misses.`,
+      [attacker.id, combat.player.id],
+    ),
+  ];
+
+  if (combat.player.hpCurrent === 0) {
+    logEntries.push(
+      createLogEntry(
+        `${combat.id}.enemy.${combat.combatLog.length + 2}`,
+        at,
+        `${combat.player.name} is defeated.`,
+        [combat.player.id],
+      ),
+    );
+  }
+
+  combat.combatLog.push(...logEntries);
+
+  return {
+    combat,
+    logEntries,
+    defeatedEnemyIds: [],
+    combatEnded: combat.player.hpCurrent === 0,
+  };
+}

src/rules/runState.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "vitest";
+
+import { sampleContentPack } from "@/data/sampleContentPack";
+
+import { createStartingAdventurer } from "./character";
+import {
+  createRunState,
+  enterCurrentRoom,
+  resolveRunEnemyTurn,
+  resolveRunPlayerTurn,
+  startCombatInCurrentRoom,
+} from "./runState";
+
+function createSequenceRoller(values: number[]) {
+  let index = 0;
+
+  return () => {
+    const next = values[index];
+    index += 1;
+    return next;
+  };
+}
+
+function createAdventurer() {
+  return createStartingAdventurer(sampleContentPack, {
+    name: "Aster",
+    weaponId: "weapon.short-sword",
+    armourId: "armour.leather-vest",
+    scrollId: "scroll.lesser-heal",
+  });
+}
+
+describe("run state flow", () => {
+  it("creates a run anchored in the start room", () => {
+    const run = createRunState({
+      content: sampleContentPack,
+      campaignId: "campaign.1",
+      adventurer: createAdventurer(),
+      at: "2026-03-15T14:00:00.000Z",
+    });
+
+    expect(run.currentLevel).toBe(1);
+    expect(run.currentRoomId).toBe("room.level1.start");
+    expect(run.dungeon.levels["1"]?.rooms["room.level1.start"]).toBeDefined();
+  });
+
+  it("enters the current room and appends room logs", () => {
+    const run = createRunState({
+      content: sampleContentPack,
+      campaignId: "campaign.1",
+      adventurer: createAdventurer(),
+      at: "2026-03-15T14:00:00.000Z",
+    });
+
+    const result = enterCurrentRoom({
+      content: sampleContentPack,
+      run,
+      at: "2026-03-15T14:01:00.000Z",
+    });
+
+    expect(result.run.log).toHaveLength(1);
+    expect(result.run.log[0]?.text).toContain("Re-entered Entry Chamber");
+  });
+
+  it("starts combat from the current room and stores the active combat state", () => {
+    const run = createRunState({
+      content: sampleContentPack,
+      campaignId: "campaign.1",
+      adventurer: createAdventurer(),
+      at: "2026-03-15T14:00:00.000Z",
+    });
+    const levelState = run.dungeon.levels["1"]!;
+    const room = levelState.rooms["room.level1.start"]!;
+
+    room.encounter = {
+      id: `${room.id}.encounter`,
+      sourceTableCode: "L1G",
+      creatureIds: ["a", "b"],
+      creatureNames: ["Guard", "Warrior"],
+      resultLabel: "Guard and Warrior",
+      resolved: true,
+    };
+
+    const result = startCombatInCurrentRoom({
+      content: sampleContentPack,
+      run,
+      at: "2026-03-15T14:02:00.000Z",
+    });
+
+    expect(result.run.activeCombat?.enemies).toHaveLength(2);
+    expect(result.run.log.at(-1)?.text).toContain("Combat begins");
+  });
+
+  it("resolves player and enemy turns through run state", () => {
+    const run = createRunState({
+      content: sampleContentPack,
+      campaignId: "campaign.1",
+      adventurer: createAdventurer(),
+      at: "2026-03-15T14:00:00.000Z",
+    });
+    const levelState = run.dungeon.levels["1"]!;
+    const room = levelState.rooms["room.level1.start"]!;
+
+    room.encounter = {
+      id: `${room.id}.encounter`,
+      sourceTableCode: "L1G",
+      creatureIds: ["a", "b"],
+      creatureNames: ["Guard", "Warrior"],
+      resultLabel: "Guard and Warrior",
+      resolved: true,
+    };
+
+    const withCombat = startCombatInCurrentRoom({
+      content: sampleContentPack,
+      run,
+      at: "2026-03-15T14:02:00.000Z",
+    }).run;
+    const targetEnemyId = withCombat.activeCombat!.enemies[0]!.id;
+
+    const afterPlayer = resolveRunPlayerTurn({
+      content: sampleContentPack,
+      run: withCombat,
+      manoeuvreId: "manoeuvre.exact-strike",
+      targetEnemyId,
+      roller: createSequenceRoller([6, 6]),
+      at: "2026-03-15T14:03:00.000Z",
+    }).run;
+
+    expect(afterPlayer.activeCombat?.actingSide).toBe("enemy");
+    expect(afterPlayer.log.at(-1)?.text).toContain("deals");
+
+    const afterEnemy = resolveRunEnemyTurn({
+      content: sampleContentPack,
+      run: afterPlayer,
+      roller: createSequenceRoller([6, 6]),
+      at: "2026-03-15T14:04:00.000Z",
+    }).run;
+
+    expect(afterEnemy.activeCombat?.actingSide).toBe("player");
+    expect(afterEnemy.adventurerSnapshot.hp.current).toBeLessThan(
+      createAdventurer().hp.current,
+    );
+  });
+
+  it("clears the room and ends active combat when the last enemy falls", () => {
+    const run = createRunState({
+      content: sampleContentPack,
+      campaignId: "campaign.1",
+      adventurer: createAdventurer(),
+      at: "2026-03-15T14:00:00.000Z",
+    });
+    const room = run.dungeon.levels["1"]!.rooms["room.level1.start"]!;
+
+    room.encounter = {
+      id: `${room.id}.encounter`,
+      sourceTableCode: "L1G",
+      creatureIds: ["a"],
+      creatureNames: ["Guard"],
+      resultLabel: "Guard",
+      resolved: true,
+    };
+
+    const withCombat = startCombatInCurrentRoom({
+      content: sampleContentPack,
+      run,
+      at: "2026-03-15T14:02:00.000Z",
+    }).run;
+
+    withCombat.activeCombat!.enemies[0]!.hpCurrent = 1;
+
+    const result = resolveRunPlayerTurn({
+      content: sampleContentPack,
+      run: withCombat,
+      manoeuvreId: "manoeuvre.guard-break",
+      targetEnemyId: withCombat.activeCombat!.enemies[0]!.id,
+      roller: createSequenceRoller([6, 6]),
+      at: "2026-03-15T14:03:00.000Z",
+    });
+
+    expect(result.run.activeCombat).toBeUndefined();
+    expect(result.run.dungeon.levels["1"]!.rooms["room.level1.start"]!.discovery.cleared).toBe(true);
+    expect(result.run.dungeon.levels["1"]!.rooms["room.level1.start"]!.encounter?.rewardPending).toBe(
+      false,
+    );
+  });
+});

src/rules/runState.ts

@@ -0,0 +1,335 @@
+import type { ContentPack } from "@/types/content";
+import type {
+  AdventurerState,
+  CombatState,
+  DungeonState,
+  RunState,
+} from "@/types/state";
+import type { LogEntry } from "@/types/rules";
+
+import { startCombatFromRoom } from "./combat";
+import {
+  resolveEnemyTurn,
+  resolvePlayerAttack,
+  type ResolveEnemyTurnOptions,
+  type ResolvePlayerAttackOptions,
+} from "./combatTurns";
+import { initializeDungeonLevel } from "./dungeon";
+import type { DiceRoller } from "./dice";
+import { enterRoom } from "./roomEntry";
+
+export type CreateRunOptions = {
+  content: ContentPack;
+  campaignId: string;
+  adventurer: AdventurerState;
+  runId?: string;
+  at?: string;
+};
+
+export type EnterCurrentRoomOptions = {
+  content: ContentPack;
+  run: RunState;
+  roller?: DiceRoller;
+  at?: string;
+};
+
+export type StartCurrentCombatOptions = {
+  content: ContentPack;
+  run: RunState;
+  at?: string;
+};
+
+export type ResolveRunPlayerTurnOptions = {
+  content: ContentPack;
+  run: RunState;
+  manoeuvreId: string;
+  targetEnemyId: string;
+  roller?: DiceRoller;
+  at?: string;
+};
+
+export type ResolveRunEnemyTurnOptions = {
+  content: ContentPack;
+  run: RunState;
+  roller?: DiceRoller;
+  at?: string;
+};
+
+export type RunTransitionResult = {
+  run: RunState;
+  logEntries: LogEntry[];
+};
+
+function cloneCombat(combat: CombatState): CombatState {
+  return {
+    ...combat,
+    player: {
+      ...combat.player,
+      statuses: [...combat.player.statuses],
+      traits: [...combat.player.traits],
+    },
+    enemies: combat.enemies.map((enemy) => ({
+      ...enemy,
+      statuses: [...enemy.statuses],
+      traits: [...enemy.traits],
+    })),
+    combatLog: combat.combatLog.map((entry) => ({
+      ...entry,
+      relatedIds: entry.relatedIds ? [...entry.relatedIds] : undefined,
+    })),
+  };
+}
+
+function cloneRun(run: RunState): RunState {
+  return {
+    ...run,
+    adventurerSnapshot: {
+      ...run.adventurerSnapshot,
+      hp: { ...run.adventurerSnapshot.hp },
+      stats: { ...run.adventurerSnapshot.stats },
+      favour: { ...run.adventurerSnapshot.favour },
+      statuses: run.adventurerSnapshot.statuses.map((status) => ({ ...status })),
+      inventory: {
+        ...run.adventurerSnapshot.inventory,
+        carried: run.adventurerSnapshot.inventory.carried.map((entry) => ({ ...entry })),
+        equipped: run.adventurerSnapshot.inventory.equipped.map((entry) => ({ ...entry })),
+        stored: run.adventurerSnapshot.inventory.stored.map((entry) => ({ ...entry })),
+        currency: { ...run.adventurerSnapshot.inventory.currency },
+        lightSources: run.adventurerSnapshot.inventory.lightSources.map((entry) => ({ ...entry })),
+      },
+      progressionFlags: [...run.adventurerSnapshot.progressionFlags],
+      manoeuvreIds: [...run.adventurerSnapshot.manoeuvreIds],
+    },
+    dungeon: {
+      levels: Object.fromEntries(
+        Object.entries(run.dungeon.levels).map(([level, levelState]) => [
+          level,
+          {
+            ...levelState,
+            rooms: Object.fromEntries(
+              Object.entries(levelState.rooms).map(([roomId, room]) => [
+                roomId,
+                {
+                  ...room,
+                  position: { ...room.position },
+                  dimensions: { ...room.dimensions },
+                  exits: room.exits.map((exit) => ({ ...exit })),
+                  discovery: { ...room.discovery },
+                  encounter: room.encounter
+                    ? {
+                        ...room.encounter,
+                        creatureIds: [...room.encounter.creatureIds],
+                        creatureNames: room.encounter.creatureNames
+                          ? [...room.encounter.creatureNames]
+                          : undefined,
+                      }
+                    : undefined,
+                  objects: room.objects.map((object) => ({
+                    ...object,
+                    effects: object.effects ? [...object.effects] : undefined,
+                  })),
+                  notes: [...room.notes],
+                  flags: [...room.flags],
+                },
+              ]),
+            ),
+            discoveredRoomOrder: [...levelState.discoveredRoomOrder],
+          },
+        ]),
+      ) as DungeonState["levels"],
+      revealedPercentByLevel: { ...run.dungeon.revealedPercentByLevel },
+      globalFlags: [...run.dungeon.globalFlags],
+    },
+    activeCombat: run.activeCombat ? cloneCombat(run.activeCombat) : undefined,
+    log: run.log.map((entry) => ({
+      ...entry,
+      relatedIds: entry.relatedIds ? [...entry.relatedIds] : undefined,
+    })),
+    pendingEffects: run.pendingEffects.map((effect) => ({ ...effect })),
+  };
+}
+
+function requireCurrentLevel(run: RunState) {
+  const levelState = run.dungeon.levels[run.currentLevel];
+
+  if (!levelState) {
+    throw new Error(`Run is missing level ${run.currentLevel}.`);
+  }
+
+  return levelState;
+}
+
+function requireCurrentRoomId(run: RunState) {
+  if (!run.currentRoomId) {
+    throw new Error("Run does not have a current room.");
+  }
+
+  return run.currentRoomId;
+}
+
+function syncPlayerToAdventurer(run: RunState) {
+  if (!run.activeCombat) {
+    return;
+  }
+
+  run.adventurerSnapshot.hp.current = run.activeCombat.player.hpCurrent;
+  run.adventurerSnapshot.statuses = run.activeCombat.player.statuses.map((status) => ({ ...status }));
+}
+
+function appendLogs(run: RunState, logEntries: LogEntry[]) {
+  run.log.push(...logEntries);
+}
+
+export function createRunState(options: CreateRunOptions): RunState {
+  const at = options.at ?? new Date().toISOString();
+  const levelState = initializeDungeonLevel({
+    content: options.content,
+    level: 1,
+  });
+
+  return {
+    id: options.runId ?? "run.active",
+    campaignId: options.campaignId,
+    status: "active",
+    startedAt: at,
+    currentLevel: 1,
+    currentRoomId: "room.level1.start",
+    dungeon: {
+      levels: {
+        1: levelState,
+      },
+      revealedPercentByLevel: {
+        1: 0,
+      },
+      globalFlags: [],
+    },
+    adventurerSnapshot: options.adventurer,
+    log: [],
+    pendingEffects: [],
+  };
+}
+
+export function enterCurrentRoom(
+  options: EnterCurrentRoomOptions,
+): RunTransitionResult {
+  const run = cloneRun(options.run);
+  const levelState = requireCurrentLevel(run);
+  const roomId = requireCurrentRoomId(run);
+  const entry = enterRoom({
+    content: options.content,
+    levelState,
+    roomId,
+    roller: options.roller,
+    at: options.at,
+  });
+
+  run.dungeon.levels[run.currentLevel] = entry.levelState;
+  appendLogs(run, entry.logEntries);
+
+  return {
+    run,
+    logEntries: entry.logEntries,
+  };
+}
+
+export function startCombatInCurrentRoom(
+  options: StartCurrentCombatOptions,
+): RunTransitionResult {
+  const run = cloneRun(options.run);
+  const levelState = requireCurrentLevel(run);
+  const roomId = requireCurrentRoomId(run);
+  const room = levelState.rooms[roomId];
+
+  if (!room) {
+    throw new Error(`Unknown room id: ${roomId}`);
+  }
+
+  const started = startCombatFromRoom({
+    content: options.content,
+    adventurer: run.adventurerSnapshot,
+    room,
+    at: options.at,
+  });
+
+  levelState.rooms[roomId] = started.room;
+  run.activeCombat = started.combat;
+  appendLogs(run, started.logEntries);
+
+  return {
+    run,
+    logEntries: started.logEntries,
+  };
+}
+
+export function resolveRunPlayerTurn(
+  options: ResolveRunPlayerTurnOptions,
+): RunTransitionResult {
+  const run = cloneRun(options.run);
+
+  if (!run.activeCombat) {
+    throw new Error("Run does not have an active combat.");
+  }
+
+  const result = resolvePlayerAttack({
+    content: options.content,
+    combat: run.activeCombat,
+    adventurer: run.adventurerSnapshot,
+    manoeuvreId: options.manoeuvreId,
+    targetEnemyId: options.targetEnemyId,
+    roller: options.roller,
+    at: options.at,
+  } satisfies ResolvePlayerAttackOptions);
+
+  run.activeCombat = result.combat;
+  syncPlayerToAdventurer(run);
+  appendLogs(run, result.logEntries);
+
+  if (result.combatEnded) {
+    const levelState = requireCurrentLevel(run);
+    const roomId = requireCurrentRoomId(run);
+    const room = levelState.rooms[roomId];
+
+    if (room?.encounter) {
+      room.encounter.rewardPending = false;
+      room.discovery.cleared = true;
+    }
+
+    run.activeCombat = undefined;
+  }
+
+  return {
+    run,
+    logEntries: result.logEntries,
+  };
+}
+
+export function resolveRunEnemyTurn(
+  options: ResolveRunEnemyTurnOptions,
+): RunTransitionResult {
+  const run = cloneRun(options.run);
+
+  if (!run.activeCombat) {
+    throw new Error("Run does not have an active combat.");
+  }
+
+  const result = resolveEnemyTurn({
+    content: options.content,
+    combat: run.activeCombat,
+    adventurer: run.adventurerSnapshot,
+    roller: options.roller,
+    at: options.at,
+  } satisfies ResolveEnemyTurnOptions);
+
+  run.activeCombat = result.combat;
+  syncPlayerToAdventurer(run);
+  appendLogs(run, result.logEntries);
+
+  if (result.combatEnded) {
+    run.status = "failed";
+  }
+
+  return {
+    run,
+    logEntries: result.logEntries,
+  };
+}