feat: module 03 death step

Deferred death: damage and destroy only mark minions; the Death Creation
Step removes them when the outermost Phase ends, and Death Phases resolve
Deathrattles in order of play until no new deaths occur. Deathrattle
summons use the board position the Death Event remembered. Harness adds
destroy(target). Expansion Drop: Twisting Nether as content only.

test_02_mortally_wounded_still_triggers no longer asserts the Acolyte is
still on the board: from Module 3 on it leaves at the end of the Sequence,
and verify-references runs Module 2's tests against the Module 3 reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

course/03-death-step/reference/ts/src/engine/card.ts

@@ -0,0 +1,69 @@
+// Card definitions as the engine sees them. The definitions themselves live in `content`.
+
+import type { Action, Ctx } from "./queue";
+
+/**
+ * A card's behaviour: given where and for whom it runs, the actions to perform.
+ * Module 2 writes these as functions in `content`; Module 5 turns them into data.
+ */
+export type EffectFn = (ctx: Ctx) => Action[];
+
+/** What a triggered ability listens for. */
+export type TriggerOn =
+  | "selfDamaged" // this minion takes damage
+  | "friendlyMinionDamaged" // a minion with the same owner (this one included) takes damage
+  | "anyMinionDamaged" // any minion takes damage
+  | "heroDamaged" // either hero takes damage
+  | "deathrattle"; // this minion dies (it resolves after the minion has left play)
+
+/** The trigger's family name, as reported in `Triggered` events. */
+export function triggerLabel(on: TriggerOn): string {
+  switch (on) {
+    case "selfDamaged":
+    case "friendlyMinionDamaged":
+    case "anyMinionDamaged":
+    case "heroDamaged":
+      return "damaged";
+    case "deathrattle":
+      return "deathrattle";
+  }
+}
+
+export interface Trigger {
+  on: TriggerOn;
+  effect: EffectFn;
+}
+
+/** What the engine needs to know about a card. */
+export interface CardDef {
+  name: string;
+  attack: number;
+  health: number;
+  /** Triggered abilities, in printed order. */
+  triggers: Trigger[];
+  /** A spell's effect when cast; absent for minions. */
+  onCast?: EffectFn;
+}
+
+export function minion(name: string, attack: number, health: number, triggers: Trigger[] = []): CardDef {
+  return { name, attack, health, triggers };
+}
+
+export function spell(name: string, onCast: EffectFn): CardDef {
+  return { name, attack: 0, health: 0, triggers: [], onCast };
+}
+
+/** Every card the game can create, looked up by name. */
+export class CardLibrary {
+  private readonly cards = new Map<string, CardDef>();
+
+  constructor(defs: CardDef[]) {
+    for (const def of defs) this.cards.set(def.name, def);
+  }
+
+  get(name: string): CardDef {
+    const def = this.cards.get(name);
+    if (!def) throw new Error(`unknown card "${name}": define it in src/content`);
+    return def;
+  }
+}

course/03-death-step/reference/ts/src/engine/death.ts

@@ -0,0 +1,21 @@
+// The Death Creation Step: the one place minions leave play.
+//
+// Damage and destroy effects only mark a minion (0 or less Health, or pending
+// destroy). It stays in play, and keeps triggering, until the outermost Phase
+// ends. Then this step removes every marked minion at once.
+
+import type { Event } from "./event";
+import type { World } from "./world";
+
+/**
+ * Remove every mortally wounded or pending-destroy minion from play, simultaneously.
+ * Returns their Death Events in order of play; empty if nothing died.
+ */
+export function deathCreationStep(world: World): Event[] {
+  const dying = world.minionsInPlay().filter((id) => world.isDoomed(id));
+  // Every position is read before anything moves: removal is simultaneous, and each
+  // Death Event remembers where its minion stood when the step began.
+  const deaths = dying.map((id) => ({ type: "Destroyed" as const, id, position: world.boardIndex(id)! }));
+  for (const { id, position } of deaths) world.kill(id, position);
+  return deaths;
+}

course/03-death-step/reference/ts/src/engine/event.ts

@@ -0,0 +1,20 @@
+// What happened, in order. The engine records an event each time it changes the game.
+
+import type { TriggerOn } from "./card";
+import type { EntityId, PlayerId } from "./world";
+
+export type Event =
+  | { type: "Summoned"; id: EntityId }
+  | { type: "Damaged"; target: EntityId; amount: number }
+  | { type: "Triggered"; source: EntityId; on: TriggerOn }
+  | { type: "Drew"; player: PlayerId; id: EntityId }
+  | { type: "Fatigue"; player: PlayerId }
+  | { type: "ArmorGained"; player: PlayerId; amount: number }
+  | { type: "StatsChanged"; id: EntityId; attack: number; health: number }
+  | { type: "SpellCast"; card: string }
+  /**
+   * A Death Event: the Death Creation Step moved `id` from play to the graveyard.
+   * `position` is the board index it had when the step began; its Deathrattle summons there.
+   */
+  | { type: "Destroyed"; id: EntityId; position: number }
+  | { type: "DeathPhase"; round: number };

course/03-death-step/reference/ts/src/engine/index.ts

@@ -0,0 +1,26 @@
+// Engine core: generic rules machinery. Never name a specific card here.
+//
+// Module 1: every card in the game is an entity addressed by an id handle.
+// The engine knows which zone each entity is in, who owns it, and when it
+// entered play.
+//
+// Module 2: heroes, Health, Attack and Armor; triggered abilities; and the
+// action queue that resolves a Sequence depth-first, recording an event log.
+//
+// Module 3: deferred death. Damage and destroy effects only mark minions; the
+// Death Creation Step removes them when the outermost Phase ends, and Death
+// Phases resolve their Deathrattles until no new deaths occur.
+
+export {
+  CardLibrary,
+  minion,
+  spell,
+  triggerLabel,
+  type CardDef,
+  type EffectFn,
+  type Trigger,
+  type TriggerOn,
+} from "./card";
+export type { Event } from "./event";
+export { Ctx, runSequence, type Action } from "./queue";
+export { HERO_HEALTH, World, type EntityId, type PlayerId, type Zone } from "./world";

course/03-death-step/reference/ts/src/engine/queue.ts

@@ -0,0 +1,166 @@
+// The action queue: how one player action (a Sequence) resolves.
+//
+// Performing an action changes the world and produces events. Every trigger that
+// responds to those events goes into one Queue, oldest listener first, and the Queue
+// is locked. Each queued trigger then resolves completely, including everything
+// its own actions cause, before the next one starts: depth-first.
+//
+// Module 3: nothing leaves play mid-Sequence. When the outermost Phase ends, the
+// Death Creation Step removes the dead, and a Death Phase resolves their
+// Deathrattles. That repeats until a step finds no new deaths.
+
+import type { Trigger, TriggerOn } from "./card";
+import { deathCreationStep } from "./death";
+import type { Event } from "./event";
+import type { EntityId, PlayerId, World } from "./world";
+
+/** Something the engine can do. Card effects return these instead of changing the world. */
+export type Action =
+  /** Deal `amount` to each target at once: all damage first, then the reactions. */
+  | { type: "damage"; targets: EntityId[]; amount: number }
+  | { type: "draw"; player: PlayerId }
+  | { type: "gainArmor"; player: PlayerId; amount: number }
+  | { type: "gainAttack"; id: EntityId; amount: number }
+  | { type: "cast"; card: string; player: PlayerId; target?: EntityId }
+  /** Mark each target pending destroy. They leave play in the next Death Creation Step. */
+  | { type: "destroy"; targets: EntityId[] }
+  /** Summon `card` for `player` at board index `at`, or at the right end if `at` is undefined. */
+  | { type: "summon"; card: string; player: PlayerId; at?: number };
+
+/** What an effect may look at when it runs. */
+export class Ctx {
+  constructor(
+    readonly world: World,
+    /** The player the effect works for. */
+    readonly owner: PlayerId,
+    /** The minion whose trigger is resolving; undefined for a spell. */
+    readonly source?: EntityId,
+    /** The chosen target, if any. */
+    readonly target?: EntityId,
+    /**
+     * The source's board position. For a Deathrattle, the source has left play,
+     * and this is the position its Death Event remembered.
+     */
+    readonly position?: number,
+  ) {}
+
+  /** The minion whose trigger is resolving. */
+  minion(): EntityId {
+    if (this.source === undefined) throw new Error("only a triggered ability has a source");
+    return this.source;
+  }
+
+  enemyHero(): EntityId {
+    return this.world.hero(this.owner === 0 ? 1 : 0);
+  }
+}
+
+/** Run one Sequence: a player action and everything it causes. */
+export function runSequence(world: World, action: Action): void {
+  perform(world, action);
+  // The outermost Phase has ended. Each Death Phase is itself an outermost
+  // Phase, so the end-of-Phase steps run again after it, until nothing dies.
+  let deaths = endOfOutermostPhase(world);
+  for (let round = 1; deaths.length > 0; round++) {
+    world.record({ type: "DeathPhase", round });
+    react(world, deaths);
+    deaths = endOfOutermostPhase(world);
+  }
+}
+
+/**
+ * The steps that run only when the outermost Phase ends; returns the Death Events.
+ * Module 4 adds an Aura Update (Health/Attack) before the Death Creation Step
+ * and an Aura Update (Other) after it, here.
+ */
+function endOfOutermostPhase(world: World): Event[] {
+  return deathCreationStep(world);
+}
+
+function perform(world: World, action: Action): void {
+  switch (action.type) {
+    case "damage": {
+      // Area damage: every Damage Event is created, in order of play, before any reaction.
+      const targets = [...action.targets].sort((a, b) => world.orderOfPlay(a)! - world.orderOfPlay(b)!);
+      const events: Event[] = [];
+      for (const target of targets) {
+        world.damage(target, action.amount);
+        events.push({ type: "Damaged", target, amount: action.amount });
+      }
+      react(world, events);
+      break;
+    }
+    case "draw":
+      world.draw(action.player);
+      break;
+    case "gainArmor":
+      world.gainArmor(action.player, action.amount);
+      break;
+    case "gainAttack":
+      world.gainAttack(action.id, action.amount);
+      break;
+    case "destroy":
+      for (const target of action.targets) world.markDestroyed(target);
+      break;
+    case "summon":
+      world.create(action.card, action.player, "board", action.at);
+      break;
+    case "cast": {
+      const effect = world.card(action.card).onCast;
+      if (!effect) throw new Error(`"${action.card}" is not a spell`);
+      world.record({ type: "SpellCast", card: action.card });
+      for (const next of effect(new Ctx(world, action.player, undefined, action.target))) perform(world, next);
+      break;
+    }
+  }
+}
+
+/** A Phase: queue every trigger that responds to `events`, then resolve them one by one. */
+function react(world: World, events: Event[]): void {
+  // Fill the Queue: for each event (already in order of play), each listener in order of play.
+  const queue: [EntityId, Trigger, Event][] = [];
+  for (const event of events) {
+    for (const listener of listeners(world, event)) {
+      for (const trigger of world.card(world.cardName(listener)).triggers) {
+        if (responds(world, trigger.on, listener, event)) queue.push([listener, trigger, event]);
+      }
+    }
+  }
+  // The Queue is now locked: nothing that happens below adds to it.
+  for (const [source, trigger, event] of queue) {
+    world.record({ type: "Triggered", source, on: trigger.on });
+    const position = event.type === "Destroyed" && event.id === source ? event.position : world.boardIndex(source);
+    const actions = trigger.effect(new Ctx(world, world.ownerOf(source), source, undefined, position));
+    // Depth-first: each action, and every reaction it causes, finishes before the next.
+    for (const action of actions) perform(world, action);
+  }
+}
+
+/**
+ * Who may respond to `event`, in order of play: every minion in play and, for a
+ * Death Event, the minion that died. It has left play, but its Deathrattle still answers.
+ */
+function listeners(world: World, event: Event): EntityId[] {
+  const inPlay = world.minionsInPlay();
+  if (event.type !== "Destroyed") return inPlay;
+  return [...inPlay, event.id].sort((a, b) => world.orderOfPlay(a)! - world.orderOfPlay(b)!);
+}
+
+/** Does a trigger listening for `on`, belonging to `listener`, respond to `event`? */
+function responds(world: World, on: TriggerOn, listener: EntityId, event: Event): boolean {
+  if (event.type === "Destroyed") return on === "deathrattle" && event.id === listener;
+  if (event.type !== "Damaged") return false;
+  const isMinion = !world.isHero(event.target);
+  switch (on) {
+    case "selfDamaged":
+      return event.target === listener;
+    case "friendlyMinionDamaged":
+      return isMinion && world.ownerOf(event.target) === world.ownerOf(listener);
+    case "anyMinionDamaged":
+      return isMinion;
+    case "heroDamaged":
+      return !isMinion;
+    case "deathrattle":
+      return false;
+  }
+}

course/03-death-step/reference/ts/src/engine/world.ts

@@ -0,0 +1,227 @@
+// Entities, zones, order of play, stats and the event log: the game's state.
+// The rules for resolving actions live in `queue.ts`.
+
+import type { CardDef, CardLibrary } from "./card";
+import type { Event } from "./event";
+
+/** A handle to an entity. Ids are never reused and stay valid when the entity changes zone. */
+export type EntityId = number;
+export type PlayerId = 0 | 1;
+export type Zone = "deck" | "hand" | "board" | "graveyard";
+
+/** Starting Health of each hero. */
+export const HERO_HEALTH = 30;
+
+interface Entity {
+  card: string;
+  owner: PlayerId;
+  zone: Zone;
+  /** Stamped each time the entity enters the board; undefined until it first does. */
+  orderOfPlay?: number;
+  attack: number;
+  /** Current Health. At 0 or below the entity is mortally wounded: still in play until the Death Creation Step. */
+  health: number;
+  /** Hit by a destroy effect: still in play until the Death Creation Step. */
+  pendingDestroy: boolean;
+}
+
+/** One player's zones (each an ordered list of ids; the board is left to right), hero and Armor. */
+type Side = Record<Zone, EntityId[]> & { hero: EntityId; armor: number };
+
+export class World {
+  /** Indexed by EntityId. */
+  private readonly entities: Entity[] = [];
+  private readonly sides: [Side, Side];
+  private nextOrderOfPlay = 0;
+  private events: Event[] = [];
+
+  /** A new game: both heroes are in play from the start, so they are the oldest entities. */
+  constructor(private readonly library: CardLibrary) {
+    const side = (owner: PlayerId): Side => {
+      const hero = this.entities.length;
+      this.entities.push({
+        card: "Hero",
+        owner,
+        zone: "board",
+        orderOfPlay: ++this.nextOrderOfPlay,
+        attack: 0,
+        health: HERO_HEALTH,
+        pendingDestroy: false,
+      });
+      // In play, but not on the board list: the board holds minions only.
+      return { deck: [], hand: [], board: [], graveyard: [], hero, armor: 0 };
+    };
+    this.sides = [side(0), side(1)];
+  }
+
+  /**
+   * Create an entity of `card` for `owner` in `zone`: at the end (the right end for the board),
+   * or at index `at` when given (clamped to the zone's length).
+   */
+  create(card: string, owner: PlayerId, zone: Zone, at?: number): EntityId {
+    if (owner !== 0 && owner !== 1) throw new Error(`no player ${owner}`);
+    const def = this.library.get(card);
+    const id = this.entities.length;
+    this.entities.push({
+      card: def.name,
+      owner,
+      zone,
+      attack: def.attack,
+      health: def.health,
+      pendingDestroy: false,
+    });
+    this.enter(id, zone, at);
+    return id;
+  }
+
+  /** Move an entity to the end of `zone` on its owner's side, keeping its id. */
+  moveTo(id: EntityId, zone: Zone): void {
+    const { owner, zone: from } = this.entity(id);
+    const list = this.sides[owner][from];
+    list.splice(list.indexOf(id), 1);
+    this.enter(id, zone);
+  }
+
+  /** The single place an entity arrives in a zone. Entering the board starts a new order of play. */
+  private enter(id: EntityId, zone: Zone, at?: number): void {
+    const entity = this.entity(id);
+    const list = this.sides[entity.owner][zone];
+    list.splice(at === undefined ? list.length : Math.min(at, list.length), 0, id);
+    entity.zone = zone;
+    if (zone === "board") {
+      entity.orderOfPlay = ++this.nextOrderOfPlay;
+      this.record({ type: "Summoned", id });
+    }
+  }
+
+  private entity(id: EntityId): Entity {
+    const entity = this.entities[id];
+    if (!entity) throw new Error(`unknown entity id ${id}`);
+    return entity;
+  }
+
+  // ---- Queries ----
+
+  card(name: string): CardDef {
+    return this.library.get(name);
+  }
+
+  zoneOf(id: EntityId): Zone {
+    return this.entity(id).zone;
+  }
+
+  cardName(id: EntityId): string {
+    return this.entity(id).card;
+  }
+
+  ownerOf(id: EntityId): PlayerId {
+    return this.entity(id).owner;
+  }
+
+  /** When the entity last entered the board (larger is later); undefined if it never has. */
+  orderOfPlay(id: EntityId): number | undefined {
+    return this.entity(id).orderOfPlay;
+  }
+
+  /** The ids in one player's zone, in zone order (left to right for the board). */
+  zone(owner: PlayerId, zone: Zone): readonly EntityId[] {
+    if (owner !== 0 && owner !== 1) throw new Error(`no player ${owner}`);
+    return this.sides[owner][zone];
+  }
+
+  hero(owner: PlayerId): EntityId {
+    if (owner !== 0 && owner !== 1) throw new Error(`no player ${owner}`);
+    return this.sides[owner].hero;
+  }
+
+  isHero(id: EntityId): boolean {
+    return this.sides.some((s) => s.hero === id);
+  }
+
+  /** Every minion on either board, oldest first (order of play). */
+  minionsInPlay(): EntityId[] {
+    return [...this.sides[0].board, ...this.sides[1].board].sort(
+      (a, b) => this.orderOfPlay(a)! - this.orderOfPlay(b)!,
+    );
+  }
+
+  attack(id: EntityId): number {
+    return this.entity(id).attack;
+  }
+
+  health(id: EntityId): number {
+    return this.entity(id).health;
+  }
+
+  /** Mortally wounded (0 or less Health) or pending destroy: it leaves play at the next Death Creation Step. */
+  isDoomed(id: EntityId): boolean {
+    const entity = this.entity(id);
+    return entity.health <= 0 || entity.pendingDestroy;
+  }
+
+  /** Index of a minion on its owner's board, left to right; undefined if it is not on the board. */
+  boardIndex(id: EntityId): number | undefined {
+    const index = this.sides[this.ownerOf(id)].board.indexOf(id);
+    return index < 0 ? undefined : index;
+  }
+
+  armor(owner: PlayerId): number {
+    return this.sides[owner].armor;
+  }
+
+  log(): readonly Event[] {
+    return this.events;
+  }
+
+  // ---- Changes: each one records its event ----
+
+  record(event: Event): void {
+    this.events.push(event);
+  }
+
+  clearLog(): void {
+    this.events = [];
+  }
+
+  damage(target: EntityId, amount: number): void {
+    this.entity(target).health -= amount;
+    this.record({ type: "Damaged", target, amount });
+  }
+
+  /**
+   * Draw the top card of `player`'s deck (the first in the list). An empty deck
+   * records `Fatigue` and changes nothing else.
+   */
+  draw(player: PlayerId): void {
+    const id = this.zone(player, "deck")[0];
+    if (id === undefined) {
+      this.record({ type: "Fatigue", player });
+      return;
+    }
+    this.moveTo(id, "hand");
+    this.record({ type: "Drew", player, id });
+  }
+
+  /** Mark for destruction. Nothing leaves play until the Death Creation Step. */
+  markDestroyed(id: EntityId): void {
+    this.entity(id).pendingDestroy = true;
+  }
+
+  /** Move a minion from play to its owner's graveyard, recording its Death Event. */
+  kill(id: EntityId, position: number): void {
+    this.entity(id).pendingDestroy = false;
+    this.moveTo(id, "graveyard");
+    this.record({ type: "Destroyed", id, position });
+  }
+
+  gainArmor(player: PlayerId, amount: number): void {
+    this.sides[player].armor += amount;
+    this.record({ type: "ArmorGained", player, amount });
+  }
+
+  gainAttack(id: EntityId, amount: number): void {
+    const entity = this.entity(id);
+    entity.attack += amount;
+    this.record({ type: "StatsChanged", id, attack: entity.attack, health: entity.health });
+  }
+}