feat: module 02 action queue

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

course/02-action-queue/reference/ts/.course.json

@@ -0,0 +1 @@
+{ "track": "ts", "engineDirs": ["src/engine"], "contentDirs": ["src/content"], "module": "02" }

course/02-action-queue/reference/ts/.gitignore

@@ -0,0 +1 @@
+node_modules/

course/02-action-queue/reference/ts/README.md

@@ -0,0 +1,13 @@
+# Module 2 reference engine (TypeScript)
+
+The course's own engine as of the end of Module 2. It adds heroes, Health, Attack and Armor, triggered abilities, an event log, and the action queue that resolves one player action depth-first. Module 1's reference was the starting point, so a diff between the two shows what this module adds. Module 3's reference starts from this one.
+
+- `src/engine/`: generic machinery. Names no cards.
+  - `queue.ts`: actions, the context an effect sees, and the resolver. Area damage creates every Damage Event before any trigger is queued; a Queue is filled once, oldest listener first, then locked; each trigger resolves completely before the next.
+  - `world.ts`: entities, zones, order of play, heroes, stats, Armor and the log. Every state change records its event.
+  - `card.ts`: card definitions (stats, triggers, a spell's effect) and the library.
+  - `event.ts`: the engine's events. `src/harness.ts` translates them into the course's `GameEvent`.
+- `src/content/index.ts`: card definitions. Each effect is a small function that returns actions; Module 5 turns them into data.
+- `src/harness.ts`: the adapter the course tests call. `play` is still the Module 1 Expansion Drop stub.
+
+Run it with the module's tests: `node tools/verify-references.mjs 02` from the course repository.

course/02-action-queue/reference/ts/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "systemic-design-workspace",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

course/02-action-queue/reference/ts/src/content/index.ts

@@ -0,0 +1,30 @@
+// Content: card definitions. Only this directory may name specific cards.
+//
+// Each effect is a small function that returns engine actions. Module 5
+// replaces these functions with card data the engine interprets.
+
+import { CardLibrary, minion, spell } from "../engine";
+
+/** Every card this game knows. */
+export function library(): CardLibrary {
+  return new CardLibrary([
+    // Fictional test minion with no text.
+    minion("Test Filler", 1, 1),
+    // "Whenever a friendly minion takes damage, gain 1 Armor."
+    minion("Armorsmith", 1, 4, [
+      { on: "friendlyMinionDamaged", effect: (c) => [{ type: "gainArmor", player: c.owner, amount: 1 }] },
+    ]),
+    // "Whenever this minion takes damage, draw a card."
+    minion("Acolyte of Pain", 1, 4, [{ on: "selfDamaged", effect: (c) => [{ type: "draw", player: c.owner }] }]),
+    // Fictional: "Whenever a minion takes damage, deal 1 damage to the enemy hero."
+    minion("Test Echo", 1, 5, [
+      { on: "anyMinionDamaged", effect: (c) => [{ type: "damage", targets: [c.enemyHero()], amount: 1 }] },
+    ]),
+    // Fictional: "Whenever a hero takes damage, gain +1 Attack."
+    minion("Test Reactor", 1, 5, [
+      { on: "heroDamaged", effect: (c) => [{ type: "gainAttack", id: c.minion(), amount: 1 }] },
+    ]),
+    // "Deal 1 damage to ALL minions."
+    spell("Whirlwind", (c) => [{ type: "damage", targets: c.world.minionsInPlay(), amount: 1 }]),
+  ]);
+}

course/02-action-queue/reference/ts/src/engine/card.ts

@@ -0,0 +1,66 @@
+// 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
+
+/** 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";
+  }
+}
+
+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/02-action-queue/reference/ts/src/engine/event.ts

@@ -0,0 +1,14 @@
+// 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 };

course/02-action-queue/reference/ts/src/engine/index.ts

@@ -0,0 +1,22 @@
+// 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.
+
+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/02-action-queue/reference/ts/src/engine/queue.ts

@@ -0,0 +1,116 @@
+// 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.
+
+import type { Trigger, TriggerOn } from "./card";
+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 };
+
+/** 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 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);
+  // Module 3: when the outermost Phase ends, deaths are processed here.
+}
+
+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 "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][] = [];
+  for (const event of events) {
+    for (const listener of world.minionsInPlay()) {
+      for (const trigger of world.card(world.cardName(listener)).triggers) {
+        if (responds(world, trigger.on, listener, event)) queue.push([listener, trigger]);
+      }
+    }
+  }
+  // The Queue is now locked: nothing that happens below adds to it.
+  for (const [source, trigger] of queue) {
+    world.record({ type: "Triggered", source, on: trigger.on });
+    const actions = trigger.effect(new Ctx(world, world.ownerOf(source), source));
+    // Depth-first: each action, and every reaction it causes, finishes before the next.
+    for (const action of actions) perform(world, action);
+  }
+}
+
+/** 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 !== "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;
+  }
+}

course/02-action-queue/reference/ts/src/engine/world.ts

@@ -0,0 +1,189 @@
+// 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. It can drop to 0 or below: Module 2 has no death step. */
+  health: number;
+}
+
+/** 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,
+      });
+      // 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` at the end of `zone` (the right end for the board). */
+  create(card: string, owner: PlayerId, zone: Zone): 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 });
+    this.enter(id, zone);
+    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): void {
+    const entity = this.entity(id);
+    this.sides[entity.owner][zone].push(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;
+  }
+
+  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 });
+  }
+
+  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 });
+  }
+}

course/02-action-queue/reference/ts/src/harness.ts

@@ -0,0 +1,84 @@
+// Test harness: the thin adapter the course tests call. It translates each
+// call into engine operations and holds no rules of its own.
+
+import { library } from "./content";
+import { runSequence, triggerLabel, World, type Event, type Zone } from "./engine";
+
+export type { Zone };
+
+export type Id = number;
+export type Player = 0 | 1;
+
+/** The events the tests read from `log()` (see course/harness.md). */
+export type GameEvent =
+  | { type: "Summoned"; id: Id }
+  | { type: "Damaged"; target: Id; amount: number }
+  | { type: "Triggered"; source: Id; trigger: string }
+  | { type: "Destroyed"; id: Id }
+  | { type: "DeathPhase"; round: number }
+  | { type: "Drew"; player: Player; id: Id }
+  | { type: "Fatigue"; player: Player }
+  | { type: "ArmorGained"; player: Player; amount: number }
+  | { type: "StatsChanged"; id: Id; attack: number; health: number }
+  | { type: "SpellCast"; card: string };
+
+function toGameEvent(event: Event): GameEvent {
+  if (event.type === "Triggered") return { type: "Triggered", source: event.source, trigger: triggerLabel(event.on) };
+  return { ...event };
+}
+
+export interface Game {
+  summon(card: string, player?: Player): Id; // to right end of board
+  addToHand(card: string, player?: Player): Id;
+  addToDeck(card: string, player?: Player): Id;
+  play(handId: Id): void; // Expansion Drop
+  zoneOf(id: Id): Zone;
+  board(player: Player): Id[]; // left to right
+  hand(player: Player): Id[];
+  orderOfPlay(id: Id): number;
+  nameOf(id: Id): string;
+  // Module 2
+  hero(player: Player): Id;
+  dealDamage(target: Id, amount: number): void; // one Sequence
+  cast(card: string, player?: Player, target?: Id): void;
+  health(id: Id): number;
+  attack(id: Id): number;
+  armor(player: Player): number;
+  log(): GameEvent[];
+  clearLog(): void;
+}
+
+export function newGame(opts?: { decks?: [string[], string[]] }): Game {
+  const world = new World(library());
+  opts?.decks?.forEach((deck, player) => {
+    for (const card of deck) world.create(card, player as Player, "deck");
+  });
+
+  return {
+    summon: (card, player = 0) => world.create(card, player, "board"),
+    addToHand: (card, player = 0) => world.create(card, player, "hand"),
+    addToDeck: (card, player = 0) => world.create(card, player, "deck"),
+    // Module 1 Expansion Drop: see course/01-handles/expansion/README.md.
+    play: () => {
+      throw new Error("not implemented: Module 1 Expansion Drop");
+    },
+    zoneOf: (id) => world.zoneOf(id),
+    board: (player) => [...world.zone(player, "board")],
+    hand: (player) => [...world.zone(player, "hand")],
+    orderOfPlay: (id) => {
+      const order = world.orderOfPlay(id);
+      if (order === undefined) throw new Error(`entity ${id} has not entered play`);
+      return order;
+    },
+    nameOf: (id) => world.cardName(id),
+
+    hero: (player) => world.hero(player),
+    dealDamage: (target, amount) => runSequence(world, { type: "damage", targets: [target], amount }),
+    cast: (card, player = 0, target) => runSequence(world, { type: "cast", card, player, target }),
+    health: (id) => world.health(id),
+    attack: (id) => world.attack(id),
+    armor: (player) => world.armor(player),
+    log: () => world.log().map(toGameEvent),
+    clearLog: () => world.clearLog(),
+  };
+}

course/02-action-queue/reference/ts/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true
+  },
+  "include": ["src", "tests"]
+}

course/02-action-queue/reference/ts/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { include: ["tests/**/*.test.ts"], passWithNoTests: true },
+});