@kradle/challenges-sdk 0.12.0 → 0.13.0

package/LLM_README.md

@@ -1,6 +1,6 @@
 # LLM_README.md - @kradle/challenges-sdk API Reference
 
-This document is the exhaustive API reference for AI agents that write Kradle challenges with `@kradle/challenges-sdk`. A challenge is a reducer: a pure function that the arena runs during the game inside a sandbox. Read this file before you write a challenge.
+This document is the API reference for AI agents that write Kradle challenges with `@kradle/challenges-sdk`. A challenge is a reducer: a pure function that the arena runs during the game inside a sandbox. Read this file before you write a challenge. The declarations (`.d.ts`) carry the full JSDoc of every member; this file is the tutorial and the index.
 
 ## Table of Contents
 
@@ -8,27 +8,28 @@ This document is the exhaustive API reference for AI agents that write Kradle ch
 2. [Installation](#installation)
 3. [Core Concepts](#core-concepts)
 4. [defineChallenge API](#definechallenge-api)
-5. [The Spec](#the-spec)
+5. [The Steps](#the-steps)
 6. [Handlers](#handlers)
 7. [The Context](#the-context)
 8. [Players and Entities](#players-and-entities)
-9. [Rules of the Reducer](#rules-of-the-reducer)
-10. [Testing](#testing)
-11. [Build and Run](#build-and-run)
-12. [Complete Examples](#complete-examples)
-13. [Common Patterns](#common-patterns)
-14. [Common Gotchas](#common-gotchas)
-15. [Tips for LLMs](#tips-for-llms)
+9. [Structures](#structures)
+10. [Rules of the Reducer](#rules-of-the-reducer)
+11. [Testing](#testing)
+12. [Build and Run](#build-and-run)
+13. [Complete Examples](#complete-examples)
+14. [Common Patterns](#common-patterns)
+15. [Common Gotchas](#common-gotchas)
+16. [Tips for LLMs](#tips-for-llms)
 
 ---
 
 ## Overview
 
-`@kradle/challenges-sdk` is a TypeScript SDK for Minecraft challenges that AI agents play on Kradle. A challenge is one call, `defineChallenge(config, spec)`, that returns a reducer: `reduce(state, event) -> { state, actions }`. The arena feeds it the facts the `KradleEngine` server plugin reports (players, entities, loaded chunks, block changes, chat, deaths, pickups) and applies the effects it asks for (give, fill, teleport, titles, votes, the end of the game). The state is plain JSON, and a run replays from its event log.
+`@kradle/challenges-sdk` is a TypeScript SDK for Minecraft challenges that AI agents play on Kradle. A challenge is one root call, `defineChallenge(config, decl)`, plus steps that register the behavior: `.setup(...)`, `.start(...)`, `.phase(name, {...})`, `.on({...})`, `.outcome({...})`. The result is a reducer: `reduce(state, event) -> { state, actions }`. The arena feeds it the facts the `KradleEngine` server plugin reports (players, entities, loaded chunks, block changes, containers, chat, deaths, pickups, votes), every server tick, and applies the effects it asks for (give, fill, teleport, titles, votes, the end of the game). The state is plain JSON, and a run replays from its event log.
 
 There is no datapack and no mcfunction. The rules are TypeScript, the tests run without Minecraft, and `kradle challenge test` runs them inside the same sandbox as the arena.
 
-`@kradle/challenges-sdk` is the API. The test kit is `@kradle/challenges-sdk/test`; the sandbox loader is `@kradle/challenges-sdk/runtime/sandbox`.
+The package's entries: `@kradle/challenges-sdk` (the author API), `@kradle/challenges-sdk/test` (the test kit), `@kradle/challenges-sdk/engine` (the wire protocol, for the arena and tools).
 
 ---
 
@@ -44,9 +45,9 @@ kradle challenge build my-challenge      # the bundle, uploaded and activated
 kradle challenge run my-challenge        # a run in the cloud
 ```
 
-A manual installation is `npm install @kradle/challenges-sdk@next` (0.11 stays under the npm tag `next` until the CLI release installs it) with `"type": "module"` in `package.json`. Node 22 or later.
+A manual installation is `npm install @kradle/challenges-sdk@next` with `"type": "module"` in `package.json`. Node 22 or later.
 
-A challenge folder holds `challenge.ts` (the rules, `export default defineChallenge(config, ...)`), `config.ts` (the metadata and the prompts, `export const config`), and its test, `challenge.test.ts`. `kradle ai-docs challenge-config` documents `config.ts`.
+A challenge folder holds `challenge.ts` (the rules), `config.ts` (the metadata and the prompts, `export const config`), and `challenge.test.ts`. `kradle ai-docs challenge-config` documents `config.ts`.
 
 ---
 
@@ -54,293 +55,385 @@ A challenge folder holds `challenge.ts` (the rules, `export default defineChalle
 
 **The reducer.** Every event from the engine goes through `reduce(state, event)`. The reducer returns the next state and a list of actions. It never keeps state outside the returned state, never mutates its input, and never touches the clock, the network or the file system. The arena runs it inside a SES compartment: `Date.now()`, `Math.random()`, timers, `process` and `fetch` do not exist there.
 
-**The state.** `g.game` (shared) and one object per player. Both come from the initializers in the spec (`game: () => ({...})`, `player: () => ({...})`). The SDK adds its own fields to every player (`score`, `alive`, `pos`, `inventory`, ...). The whole state is JSON.
+**The state.** `g.state` (shared) and `p.state` (per player). Both come from the initializers in the root declaration (`state: { game: (init) => ({...}), player: (p, init) => ({...}) }`). The SDK keeps its own fields beside them: `p.score`, `p.pos`, `p.inventory`, `p.isActive`... The whole state is JSON.
 
-**The world mirror.** The engine streams the players, the entities, the loaded chunks and the block changes. The SDK keeps them in the state and answers `g.blockAt`, `g.entities`, `g.players` from that mirror. One read is declared: the `containers` of the spec, which the plugin samples; every other read comes from the mirror.
+**The stages.** `CONNECTING` until every participant is connected and has a position; then the initializers run, then `setup` (the world build, confirmed by the engine), then `PLAYING` (`start`, the phases, the handlers), then `OVER`.
 
-**Effects.** `g.give`, `g.fill`, `g.teleport`, `g.say`, `g.end`, ... queue effects. The arena sends them to the plugin after the reduction. A failed effect comes back as the `effectFailed` event.
+**The world mirror.** The engine streams the players, the entities, every loaded chunk, the block changes and the containers. The SDK keeps them in the state and answers `g.blockAt`, `g.entities`, `g.containerContents`, `g.players` from that mirror. Nothing is declared: the mirror holds everything the server has loaded.
 
-**Time.** Durations are ticks (20 per second). `seconds(30)`, `minutes(3)`, `ticks(40)`, or the strings `"30s"`, `"2m"`, `"40t"`. `g.tick`, `g.elapsed` and the timers (`g.schedule`) are the only clocks.
+**Effects.** `g.give`, `g.fill`, `g.teleport`, `g.say`... queue commands for the engine. They are applied on the next server tick and reported back as facts (a placed block comes back through the mirror). A refused effect arrives as `on.effectFailed`.
 
-**Determinism.** `g.rand`, `g.pick` and `g.shuffle` are seeded from the run. The same event log gives the same state: `game.replay()` in a test reduces the log again and checks it.
+**Phases.** Named stages of the game with their own `duration`, `until`, `enter`, `exit`, timed steps and handlers. A phase or end request from a callback applies after the callback returns: exit once, enter once.
+
+**The result.** `outcome.scores` derives the scores after every reduction, `outcome.endWhen` ends the game, `outcome.winners` and `outcome.endState` classify it. The result is frozen before `onOver` and `judgeContext` see it.
 
 ---
 
 ## defineChallenge API
 
 ```ts
-import { type ChallengeConfig, type ContextOf, defineChallenge, minutes, type PlayerIn, Win } from "@kradle/challenges-sdk";
+import { defineChallenge, type CtxOf, type ReadCtxOf, winBy } from "@kradle/challenges-sdk";
+import { config } from "./config";
 
-export const config = {
-  name: "Sheep Herding",
-  challengeConfig: {},
-  roles: { herder: { description: "Herd sheep into your pen.", minParticipants: 2 } },
-  endStates: { all_penned: "every sheep is in a pen", time_up: "the time ran out" },
-} as const satisfies ChallengeConfig;
+const challenge = defineChallenge(config, {
+	state: {
+		game: (init) => ({ round: 0 }),                       // g.state
+		player: (p, init) => ({ startY: Math.floor(p.pos.y) }), // p.state, every role
+		players: { seeker: (p, init) => ({ found: 0 }) },     // p.state for one role
+	},
+	life: "respawn",                    // "single": one death eliminates. Required.
+	duration: "5m",                     // the game's length; omit for none
+	world: { time: "day" },             // spawn, time, daylightCycle, mobSpawning, naturalRegeneration, maxHealth; false = none
+	zones: { pit: { from: { x: 0, y: -64, z: 0 }, to: { x: 9, y: -50, z: 9 } } },
+	timers: ["raid"],
+	votes: { room: { options: ["red", "blue"], final: true }, player: { final: true } },
+	phases: ["BUILD", "FIGHT"],         // the names; each gets a .phase() step
+	initialPhase: "BUILD",
+	markers: { tags: ["kradle.spawn"] },
+});
 
-const state = {
-  game: () => ({ sheep: 0 }),
-  player: () => ({ closed: false }),
-};
-type G = ContextOf<typeof config, typeof state>;
+type G = CtxOf<typeof challenge>;      // the gameplay context, for helpers
+type R = ReadCtxOf<typeof challenge>;  // the read-only context, for pure helpers
+
+export default challenge
+	.setup((g) => { /* the world build */ })
+	.start((g) => { /* the first tick of the game */ })
+	.phase("BUILD", { duration: "2m", next: "FIGHT", enter(g) {}, on: {} })
+	.phase("FIGHT", { next: "END", until: (g) => g.activePlayers.length <= 1 })
+	.on({ died(g, { player, killer }) {} })
+	.outcome({ scores: (g, p) => (p.role === "seeker" ? p.state.found : 0), winners: winBy.highestScore() })
+	.onOver((g, result) => g.say("Game over"));
+```
 
-function penned(g: G, p: PlayerIn<G>): number {
-  return g.entities({ box: penOf(p), type: "minecraft:sheep" }).length;
-}
+The root declaration holds data, the state initializers and pure predicates (a vote's `accept`). No event handler lives in it. Every literal type comes from it: the phase names, the zone names, the timer names, the vote ids and options, the roles and end states of `config`. A typo in any of them does not compile.
 
-export default defineChallenge(config, {
-  ...state,
-  duration: minutes(3),
-  life: "respawn",
-  world: { spawn: { x: 0, y: -60, z: 0 }, time: "day" },
-  setup(g) { /* fill, setblock, summon: one batch before the game */ },
-  start(g) { for (const p of g.players) g.give(p, "minecraft:wheat", 16); },
-  on: {
-    tick: (g) => { for (const p of g.players) p.score = penned(g, p); },
-    blocksChanged(g, { changes }) { /* the fence gap closed? */ },
-  },
-  end: (g) => g.game.sheep > 0 && g.players.reduce((n, p) => n + penned(g, p), 0) >= g.game.sheep,
-  endState: (g) => (g.game.sheep > 0 && g.players.reduce((n, p) => n + penned(g, p), 0) >= g.game.sheep ? "all_penned" : "time_up"),
-  winners: Win.topScore({ min: 1 }),
-});
-```
+The steps register behavior and return the same challenge object, so a definition reads as one chain or as separate statements (`challenge.on({...})` after `export default challenge`). The definition locks on first use (`init()`, or the manifest read); a step after the lock throws.
 
-`defineChallenge(config, spec)` is the whole API. Every type comes from the initializers: `game()` gives `g.game`, `player()` or `players: { role: () => ({...}) }` gives the per-player fields, `zones` gives the zone names, `timers` gives the timer names, `config.roles` gives the role names, `config.endStates` gives the end states, `config.challengeConfig.votingOptions` gives the vote ids and options, `config.challengeConfig.locations` gives the location names, `config.params` gives `g.params`.
+**Helpers.** Name the root call in a const and type helpers from it: `CtxOf<typeof challenge>` (handlers), `ReadCtxOf<typeof challenge>` (pure callbacks), `SetupCtxOf<typeof challenge>` (world builders), `PlayerIn<G>` (a player). The chain hangs off the const, so the helper's type never depends on the steps. A helper called by a root predicate is typed independently.
 
-`ContextOf<typeof config, typeof state>` is the context type for helper functions, declared before the challenge. A helper typed that way can be a rule's value (`endState: classify`) or be called from a rule. Only a helper whose type comes from the challenge value itself (`typeof challenge.ctx`) makes the challenge's type circular when it is passed as a rule value. `PlayerIn<G>` is the player type of a context. `ContextOfChallenge<typeof challenge>` is the context type of a built challenge, for tests.
+**State initializers.** They run once, when the last participant is connected and positioned, before `setup`. `player(p, init)` receives the observed player (position included, no state yet); `game(init)` and `player` receive `init = { params, random, players, locations }`. `init.random` is the run's seeded generator. The return value is JSON: no functions, no class instances, no player objects (store names).
 
-Exports: `defineChallenge`, `End` (`End.allEliminated`), `Win` (`Win.topScore({ min?, eligible? })`, `Win.scoreAtLeast(n)`), `ticks`, `seconds`, `minutes`, `toTicks`, `addDuration`, `subtractDuration`, `asSeconds`, `asMinutes`, `TICKS_PER_SECOND`, `WORLD_DEFAULTS`, `ALL_CAPABILITIES`, the world helpers `bounds`, `inBox`, `blockIdOf`, `applyEquipment`, and the types `ChallengeConfig`, `ContextOf`, `ContextOfChallenge`, `PlayerIn`, `Vec3`, `Box`, `Block`, `Item`, `EntityType`, `Duration`, `Event`, `Effect`, `Action`, `Marker`, `Entity`. The result types: `OverResult`, `SdkEndState`. Also `PLAYER_VOTE` (the reserved vote id), `OptionFor`, `Observed`, `DeepReadonly`, `StatePlayer`.
+**Params.** `config.params` declares per-run parameters with defaults (`{ limit: { type: "number", default: 3 } }`); a job may override them; `g.params.limit` reads the value.
 
 ---
 
-## The Spec
+## The Steps
 
-| Field | Meaning |
-|---|---|
-| `game: () => G` | The shared state. Read and write it as `g.game`. |
-| `player: () => P` / `players: { [role]: () => P }` | Per-player state, the same for all roles or one shape per role. Read it on the player objects. |
-| `duration` | Time from game start to the end. A `Duration`: `seconds(30)`, `minutes(3)`, `ticks(40)`, or `"30s"`, `"2m"`, `"40t"`. Omit for no limit. Arithmetic: `addDuration(a, b)`, `subtractDuration(a, b)` (clamped at zero) (ticks); for messages `asSeconds(d)`, `asMinutes(d)`. A bare number is not a duration; a negative or non-finite value throws. |
-| `life` | `"single"`: one death eliminates (spectator). `"respawn"`: deaths count, the player plays on. |
-| `world` | Setup before the game: `spawn`, `time`, `daylightCycle`, `mobSpawning`, `naturalRegeneration`, `maxHealth`. Players start with an empty inventory; nothing clears it. `false` skips all of it. Defaults: `WORLD_DEFAULTS`. |
-| `announce` | `{ deaths?, gameOver? }`: the SDK's own announcements. |
-| `mirror` | Cost knobs: `players: "all" \| "participants"`, `entities: boolean \| { within }`, `blocks: boolean \| { within }`. Everything is on by default. |
-| `zones` | Named boxes. The SDK evaluates them every tick: `on.zoneEntered`, `on.zoneLeft`, `g.inZone`, `player.zones`. |
-| `timers` | Timer names for `g.schedule` and `on.timer`. |
-| `markers` | `{ tags, within? }`: tagged entities the engine reads before the game, for `g.markers(tag)`. |
-| `containers` | `{ [name]: Vec3 }`: chests or barrels whose contents the engine reports. `g.contents(name)` or `g.contents(at)` gives the item counts (undefined before the first report); `on.container` fires on every change; a report for a block that is not declared is ignored. Each half of a double chest is its own container (27 slots); a container that is broken reports its slots as emptied. A delivery rule reads what is in the chest, not what left a hand. Needs the `containers` capability. |
-| `setup(g)` | The world build. Its effects go out as one batch; the game starts after the engine confirms it. |
-| `start(g)` | The first tick of `PLAYING`, after the setup batch. |
-| `phases` | `{ [name]: { duration?, enter?, exit?, next?, at?, every?, on? } }`. `g.goTo(name)` moves; `next` is a name, `"END"`, or a function. |
-| `at` | `[{ at: Duration, run }]`: one-shot steps after game start. |
-| `every` | `[{ interval: Duration, run }]`: repeating steps. After a gap they run once. |
-| `votes` | `{ [voteId]: { final?, phases?, open?(g, player, option) } }`. Ids and options come from `config.challengeConfig.votingOptions`. The id `player` is the vote `skills.voteForPlayer` casts in: its options are the other participants, and it needs no `votingOptions` entry. A vote is final by default, also without a rule: one vote per participant per round; `final: false` lets a new vote replace the old one. |
-| `on` | The handlers (next section). |
-| `end(g)` | An extra end condition, checked after every reduction. |
-| `winners(g)` | The winners. `Win.topScore({ min?, eligible? })` (default `min` 1, ties win together), `Win.scoreAtLeast(n)`, or your own function. |
-| `endState(g)` | The end state to report, one of `config.endStates`. |
-| `onOver(g, result)` | Runs once the result is final, before `game_over`: result titles, a last announcement. `result.winners` are the names, `result.winnerPlayers` the same players, `result.isWinner(p)` a membership check, `result.endState` a declared end state, an SDK error state (`error_setup`, `error_challenge`, `error_unsupported_facts`) or `""`. |
-| `judgeContext(g)` | An object sent with `game_over` for the judge (the backend takes an object, not another JSON value). |
+| Step | Context | When |
+|---|---|---|
+| `.setup(fn)` | setup: reads, messages, effects, state writes | Once, before the game. The effects go out as batches; the game starts after the engine confirms them all. |
+| `.start(fn)` | gameplay | The first tick of PLAYING, before the initial phase enters. |
+| `.phase(name, spec)` | gameplay | The behavior of one declared phase: `duration?`, `next` (required: a name, `"END"`, or `(g) => ...`), `until?`, `enter?`, `exit?`, `at?`, `every?`, `on?`. |
+| `.at([{ at, run }])` | gameplay | One-shot steps after game start, `>=` semantics. |
+| `.every([{ interval, run }])` | gameplay | Repeating steps; after a gap they run once. |
+| `.on({...})` | gameplay | Event handlers. Several calls add up, in call order. |
+| `.outcome({ scores?, endWhen?, winners, endState? })` | read-only | The result rules. Required. |
+| `.onOver(fn)` | notification: messages and metrics | Once the result is frozen. |
+| `.judgeContext(fn)` | read-only | An object sent with `game_over` for the LLM judge. |
+
+**Phases.** A phase without `duration` and without `until` lasts one tick: a pass-through, such as a resolution. `until` ends the phase as soon as it holds; it is evaluated after the handlers of every event. `duration` may be a function of the read-only context, evaluated once at entry. A name declared in `phases` with no `.phase()` step is a manual phase: only `g.startPhase` leaves it. A transition to the current phase is a normal transition with a fresh entry, so cycles go through a function `next`.
+
+**Requests.** `g.startPhase(name)`, `g.endPhase()` and `g.endGame(endState?)` record a request; the SDK applies it after the callback returns. One phase transition per event; a game end replaces a phase request; a request inside `exit` or a pure callback throws. `endGame()` is not a `return`: the current callback continues, the later callbacks of the event are skipped.
+
+**The checkpoint.** After the handlers of every event: the derived scores, the phase's `until`, the phase timeout, the game duration, `outcome.endWhen`. A game end wins over a staged phase change.
+
+**Finalization.** The phase's `exit` (full context), the final scores, `outcome.winners`, the end state (`endGame(endState)` or `outcome.endState`), the frozen result, `onOver`, `judgeContext`, `game_over`.
 
 ---
 
 ## Handlers
 
-All handlers get `(g, event)`. Players in the events are resolved player objects. Events for names that are not participants never reach the handlers.
+`.on({...})` and a phase's `on` take the same handlers. Every handler receives the gameplay context `g` and one event; events for names that are not participants never reach them.
 
 | Handler | Event |
 |---|---|
-| `tick` | Every reducer tick (every 2 server ticks). |
-| `joined`, `left`, `respawned` | `{ player }` |
-| `move` | `{ player, from, to, maxY, minY }` |
+| `tick(g)` | Every server tick. |
+| `joined`, `left` | `{ player }` |
+| `move` | `{ player, from, to }`: one per tick in which the player moved. |
 | `damaged` | `{ player, amount, cause, attacker? }` |
 | `died` | `{ player, cause, killer? }` |
-| `entitySpawned` | `{ entity }` |
-| `entityRemoved` | `{ entity, cause: "died" \| "removed", killer? }` |
+| `respawned` | `{ player }` |
 | `pickup` | `{ player, item, count, at }` |
-| `inventory` | `{ player, item, count }`: a participant's count of one item changed. |
-| `blockBroken`, `blockPlaced` | `{ player, at, block }` |
-| `blockUsed` | `{ player, at, block, item? }` |
-| `blocksChanged` | `{ changes: [{ x, y, z, block, was?, cause?, by? }] }`: every block that changed this tick, whatever the cause. |
-| `container` | `{ at, block, items, changes: [{ item, delta }], by? }`: a declared container's contents changed. `items` is the count per item after the change; `block` is the block at that position when the engine reports it (after a break, the replacement block, `minecraft:air`); `by` is the player who had it open, when the engine knows. The first report (the initial content) fires no handler; a report for a position that is not in `containers` is ignored. |
+| `inventory` | `{ player, item, count }`: a count changed. |
+| `blockPlaced`, `blockBroken`, `blockUsed` | `{ player, at, block: { id, props } }`; the mirror already shows the new state. |
+| `blocksChanged` | `{ changes }`: every block that changed this tick; a fill is one entry with its `box`. |
+| `container` | `{ at, block, items, changes, by?, removed }`: a container's contents changed. |
 | `zoneEntered`, `zoneLeft` | `{ player, zone }` |
 | `chat` | `{ player, text }` |
-| `animation` | `{ player, animation: "swing" \| "swing_off" }`: an arm swing, a mining or attack attempt. |
-| `gamemode` | `{ player, gamemode }`: a participant's game mode changed. |
-| `vote` | `{ player, voteId, option }`: accepted votes only. `option` is a string until a check on `voteId` narrows it to that vote's own options (the vote `player` is open to every challenge, its options are names). |
+| `animation` | `{ player, animation }`: `swing` or `swing_off`. |
+| `gamemode` | `{ player, gamemode }` |
+| `entitySpawned`, `entityChanged`, `entityRemoved` | `{ entity }`, `{ entity, was }`, `{ entity, cause, killer? }` |
+| `vote` | `{ player, voteId, option }`: accepted votes only; the option is typed by the vote id after `if (voteId === "room")`. |
 | `walkDone` | `{ player, ok }` |
 | `timer` | `{ name }` |
-| `effectFailed` | `{ kind, detail }` |
+| `batchDone` | `{ name, ok, failed }` |
+| `effectFailed` | `{ kind, detail, effect?, batch? }` |
 | `custom` | `{ name, player?, data }` |
 
-Phases carry their own `on`; a phase handler runs after the global one for the same event.
-
 ---
 
 ## The Context
 
-`g` is the context every rule receives.
+`g` is the gameplay context. The read-only context (pure callbacks) has the reads only; the notification context (`onOver`) adds the messages and metrics; the setup context has everything but the phase, end, timer, vote, walk and batch calls.
+
+**Reads.** `g.state`, `g.params`, `g.players`, `g.activePlayers`, `g.player(name)`, `g.playersWithRole(role)`, `g.playerWithRole(role)` (throws unless exactly one), `g.tick`, `g.elapsed` (ticks since start), `g.status`, `g.phase` (`null` without phases), `g.phaseEntry`, `g.phaseElapsed`, `g.phaseRemaining` (`null` without a duration), `g.location(name)`, `g.markers(tag?)`, `g.inZone(player, zone | box)`, `g.countItems(player, item)`, `g.worldTime`.
+
+**The mirror.** `g.blockAt(at)` (the id, `undefined` outside the loaded chunks), `g.blockStateAt(at)` (`{ id, props }`), `g.blockMatches(at, match)` (throws `block_unknown` outside the loaded chunks), `g.blockCount(box, match, { partial? })` and `g.findBlocks(box, match, { limit?, partial? })` (they throw when a chunk of the box is not loaded, unless `partial`), `g.regionLoaded(box)`, `g.entities({ box?, type?, tag? })`, `g.entity(id)`, `g.containerContents(at)` (any container the mirror holds). A `match` is an id (any state), `{ id, props }` (the given props must match), or a function over the state.
+
+**Votes.** `g.votes(id)` (voter to option), `g.vote(player, id)`, `g.voteOpen(id)`, `g.tally(id)` (`{ counts, leaders, abstaining }`); `g.openVote(id)` (a new round; throws `vote_open` on an open round), `g.closeVote(id)`, `g.resetVote(id)`. A round is closed until opened. An eliminated player's vote is refused unless `allowEliminated`; the `player` vote (`skills.voteForPlayer`) excludes the voter unless `allowSelf`.
 
-Reads:
+**Messages and metrics.** `g.say(message)`, `g.tell(to, message)`, `g.title(to, { title, subtitle?, fadeIn?, stay?, fadeOut? })`, `g.log(message, { player?, data? })`, `g.setMetric(name, value, { player? })` (the last value per name reaches the run result), `g.achievement(player, id)`.
 
-- `g.game`, `g.params`, `g.players`, `g.active` (still in the game), `g.player(name)`, `g.role(role)` (typed with that role's fields), `g.one(role)`.
-- `g.tick`, `g.dt`, `g.elapsed`, `g.phase`, `g.phaseElapsed`, `g.phaseRemaining` (all in ticks).
-- `g.location(name)`, `g.markers(tag?)`, `g.contents(name | at)` (a declared container's item counts).
-- The world mirror: `g.blockAt(at)` (the id, `minecraft:oak_fence`), `g.blockStateAt(at)` (the state, `minecraft:oak_fence[north=true,...]`), `g.blockCount(box, match)`, `g.findBlocks(box, match, limit?)`, `g.entities({ box?, type?, tag? })`, `g.entity(id)`, `g.others` (players online who are not participants), `g.worldTime` (0..24000). A `match` is an id (any state) or a state string (that state only). Outside the loaded chunks `blockAt` is `undefined`.
-- `g.inZone(player, zone | box)`, `g.count(player, item)`.
-- `g.votes(voteId)` (a copy: voter name to option, typed by the vote), `g.vote(player, voteId)`.
-- `g.rand(min, max)`, `g.pick(items)`, `g.shuffle(items)`: seeded, deterministic.
+**Scores and roster.** `g.setScore(player, n)`, `g.addScore(player, delta)` (refused when `outcome.scores` exists), `g.eliminate(player)`, `g.random.int(lo, hi)`, `g.random.pick(items)`, `g.random.shuffle(items)`, `g.random.weighted(items)`.
 
-Writes (effects the engine applies):
+**Effects.** `g.give(player, item, count?)` (`item` is an id or `{ id, count?, name?, lore?, enchantments?, damage?, snbt? }`), `g.clear(player, item?, count?)`, `g.effect(player, { id, duration, amplifier? })`, `g.teleport(player, to)`, `g.kill(player)`, `g.gamemode(player, mode)`, `g.attribute(player, attribute, value)`, `g.fill(from, to, block)`, `g.setBlock(at, block)` (`block` is an id or `{ id, props?, blockEntity? }`), `g.summon(entity, at, { nbt? })`, `g.killEntities(types?)`, `g.time(value)`, `g.gamerule(rule, value)`, `g.setSpawn(at)`, `g.worldBorder({ center?, size?, over? })`, `g.container(at, items)`, `g.command(cmd)` (the escape hatch: gameplay commands only).
 
-- `g.say(text)`, `g.tell(to, text)`, `g.title(to, title, subtitle?, times?)`, `g.log(player | null, message, data?)`, `g.achievement(player, id)`, `g.store(name, value, player?)` (a stored variable: the last value per name reaches the run result and the `runs get` columns; global without a player).
-- `g.give(player, item, count?, nbt?)`, `g.clear(player, item?, count?)`, `g.effect(player, id, seconds, amplifier?)`, `g.teleport(player, to)`, `g.walk(player, to, { fallback? })` (the arena walks the bot; `on.walkDone` reports), `g.kill(player)`, `g.gamemode(player, mode)`, `g.attribute(player, name, value)`, `g.eliminate(player)`.
-- `g.fill(from, to, block)`, `g.setblock(at, block, nbt?)`, `g.summon(type, at, nbt?)`, `g.killEntities(types?)`, `g.container(at, items)`, `g.time(value)`, `g.gamerule(rule, value)`, `g.setSpawn(at)`, `g.worldBorder({ center?, size?, seconds? })`.
-- `g.command(cmd)`: the escape hatch, logged. The arena runs only the gameplay commands on its allowlist and checks the word after every `execute ... run`. Server administration is not on it, and neither are the world-mutation commands `fill`, `setblock`, `clone`, `place`, `fillbiome`, `data` and `forceload` (a command fires no block event, so the mirror would miss it: use the typed effects). A refused command comes back as `effectFailed`.
-- `g.goTo(phase)` (a phase that is not declared throws, which ends the run as `error_challenge`), `g.end(endState?)`, `g.schedule(timer, after)`, `g.cancel(timer)`, `g.openVote(voteId)`.
+**Flow.** `g.startPhase(name)`, `g.endPhase()`, `g.endGame(endState?)`, `g.schedule(timer, after)`, `g.cancel(timer)`, `g.walk(player, to, { fallback? })`, `g.batch(name, fn)` (the effects inside `fn` go out as one named batch; `on.batchDone` reports).
+
+Durations are `"35s"`, `"2m"`, `"40t"` or `seconds(35)` / `minutes(2)` / `ticks(40)`; a bare number is refused. Elapsed values are ticks (20 per second).
 
 ---
 
 ## Players and Entities
 
-Player objects (`g.players[i]`) carry the SDK fields plus your per-player state: `name`, `role`, `number`, `alive`, `eliminated`, `deaths`, `kills`, `score` (reported to the run result when it changes), `pos`, `yaw`, `pitch`, `headYaw`, `entityId`, `uuid`, `health`, `food`, `gamemode`, `held`, `slots` (by slot: 0-35 main, 36-39 armor, 40 offhand), `inventory` (counts by item), `equipment` (main, off, head, chest, legs, feet), `invisible`, `zones`, `human`. Your state may not reuse these names. Every SDK field except `score` is an observation: read-only for a rule (`p.pos = null` and `p.zones.push(...)` do not compile). Write `score`, your own fields, and use `g.eliminate(p)`.
+A player (`g.players[i]`) carries the roster (`name`, `role`, `seatNumber`, `human`), the observations (`connected`, `alive`, `eliminated`, `isActive`, `deaths`, `kills`, `score`, `pos`, `yaw`, `pitch`, `headYaw`, `health`, `food`, `gamemode`, `held`, `slots`, `inventory`, `equipment`, `invisible`, `zones`) and its own `state`. The observations are read-only for a rule; `p.state` is the challenge's; the score changes through `g.setScore` / `g.addScore` or `outcome.scores`. `p.pos` is set from the initializers onward: a disconnected player keeps the last position.
+
+`p.role === "seeker"` narrows the player to that role's state. `g.playersWithRole("seeker")` is typed the same way.
 
 Entities (`g.entities()`) carry `id`, `type`, `pos`, `tags`, `name?`, `health?`, `item?`, `count?`, `uuid?`, `yaw?`, `pitch?`, `headYaw?`, `equipment?`, `invisible?`, `villager?`. They are read-only through every level; copy what you keep (`{ ...e.pos }`).
 
-`g.others` lists the players online who are not participants (the watcher, spectators, humans in the lobby): `name`, `pos`, `gamemode`.
+---
+
+## Structures
+
+`@kradle/challenges-sdk/structures` is a template of blocks: text layers plus a palette. `defineStructure` builds it once, at module level. `placeStructure(g, s, origin)` queues one `g.setBlock` per cell (setup or gameplay). `compareStructure(g, s, origin)` reads the mirror and reports `{ complete, matched, mismatched, unknown, rotation }`. `structureBox(s, origin)` is the bounding box, for a zone or a `blockCount`.
+
+The layers go from the bottom up; each layer is a list of rows (z from the origin outward); each row is a string of symbols (x from the origin outward). `"."` is a cell that must be air; `"?"` is a cell the comparison ignores and the placement leaves alone. A symbol maps to `{ place, match? }`: `place` is what `placeStructure` sets; `match` is how the cell must look (default: the id of `place` with the properties `place` names). A block state string (`"minecraft:oak_stairs[facing=east]"`) reads as `{ id, props }`, so its properties rotate and match one by one. With `rotations: true`, `{ rotation: 90 | 180 | 270 }` turns the structure clockwise (the table turns `facing`, `axis`, `rotation`, a jigsaw's `orientation`, the rail shapes and the fence sides), and `compareStructure(g, s, origin, { rotation: "any" })` finds the rotation the players built. The rotated footprint keeps its minimum x/z corner at `origin`: the origin is the anchor corner, not a pivot, so the same `origin` compares every rotation of a build that starts there.
+
+An unloaded chunk makes a cell `unknown`, never a mismatch, so `complete` is false until the chunk loads. Compare in `blocksChanged` (every cause) or in `outcome.endWhen`.
+
+```ts
+import { defineChallenge } from "@kradle/challenges-sdk";
+import { compareStructure, defineStructure, placeStructure } from "@kradle/challenges-sdk/structures";
+import { config } from "./config";
+
+// A 3x3 ring of cobblestone with a stair at one corner, two blocks high.
+const FORT = defineStructure({
+	layers: [
+		["#S#", "#.#", "###"],
+		["#?#", "?.?", "#?#"],
+	],
+	palette: {
+		"#": { place: "minecraft:cobblestone" },
+		S: { place: { id: "minecraft:oak_stairs", props: { facing: "east" } } },
+	},
+	rotations: true,
+});
+const MODEL = { x: 40, y: -60, z: 10 };
+const SITE = { x: 10, y: -60, z: 10 };
+
+const challenge = defineChallenge(config, { life: "respawn", duration: "10m", state: { game: () => ({ built: false }) } });
+export default challenge
+	.setup((g) => placeStructure(g, FORT, MODEL))
+	.on({
+		blocksChanged: (g) => {
+			const report = compareStructure(g, FORT, SITE, { rotation: "any" });
+			if (report.complete) g.state.built = true;
+			else g.setMetric("mismatched", report.mismatched.length);
+		},
+	})
+	.outcome({ endWhen: (g) => g.state.built, winners: (g) => (g.state.built ? g.players : []), endState: (g) => (g.state.built ? "done" : "time_up") });
+```
 
 ---
 
 ## Rules of the Reducer
 
-- Write no side effects. Read `g`, write `g.game` and the player fields, call the effect methods. Everything else is ignored or fails the reduction.
-- The state is JSON: no functions, no class instances, no cycles, no shared objects, no `NaN`.
-- No clock, no random, no timers, no network. `Date.now()` and `Math.random()` throw in the arena. Use `g.tick`, `g.elapsed`, `g.schedule`, `g.rand`.
-- A reduction has a deadline (2 s) and a memory limit. An exception or a timeout ends the run as `error_challenge`.
-- Durations are in ticks. `toTicks("1.5s")` is 30; a fraction rounds to the nearest tick. A negative, non-finite or malformed duration throws, also from `seconds()`, `minutes()` and `ticks()`. `addDuration`, `subtractDuration` (clamped at zero), `asSeconds` and `asMinutes` combine and convert them.
-- The reducer sees the world at the reducer's cadence (every 2 server ticks). A zone edge is detected on the next sample, not on the exact server tick.
-- Scores live in the state (`player.score`). There is no Minecraft scoreboard by default.
+- Every callback is synchronous. A callback that returns a Promise is an error that ends the run.
+- A phase request (`g.startPhase`, `g.endPhase`) applies once the event's handler group returned: every global `on` in order, then the phase's. A later handler of the same event still sees the current phase; a second request in the group throws `phase_twice`. `g.endGame` skips the later handlers of the event; the current callback continues.
+- The state is JSON: plain objects and arrays, finite numbers, strings, booleans, null. Store player names, not player objects.
+- A thrown error in a callback ends the run as `error_challenge`: the reduction's state and effects are dropped, the run log carries the error's `code`, `category` and `path`.
+- Randomness comes from `g.random` and `init.random`: a run replays from its seed.
+- The published state is frozen through: a reference kept from a callback cannot change it, and a context method after the reduction throws `ctx_closed`.
+- The observations are read-only everywhere: `p.pos.y = 1`, `p.score = 3` or `g.params.x = 1` throws `read_only` (the state is written through `p.state` and `g.state`; the score through `g.setScore` / `g.addScore`).
+- The pure callbacks (`outcome.*`, `judgeContext`, `until`, a functional `duration` or `next`, a vote's `accept`) read only: a write or an effect does not compile, and throws `read_only` at run time; so does a write in `onOver`.
+- Derived scores (`outcome.scores`) commit once per reduction, after the handlers and after the transition the checkpoint made; every evaluation reads the previous committed scores, so `p.score + 1` adds one. `until` and `endWhen` read the vector under evaluation; `exit` and `enter` read the committed one.
+- A vote request carries the round the arena saw (`vote_round`); a request without a round, or with an earlier one, is refused with feedback. The harness's `Fake.vote` stamps the current round.
+- The engine confirms the setup batches in order; an acknowledgement that is not for the pending batch is logged and ignored.
 
 ---
 
 ## Testing
 
-`@kradle/challenges-sdk/test` runs the reducer with a fake engine, without Minecraft. It also exports `scores(game)` (the score per player), `near(a, b, blocks)` (a distance check on each axis, x and z, not a radius) and the roster type `RosterEntry`:
+`@kradle/challenges-sdk/test` is a stand-in arena. No test framework dependency: it throws plain errors.
 
 ```ts
 import { describe, expect, test } from "bun:test";
-import { Game, sandboxed } from "@kradle/challenges-sdk/test";
-import herding from "./challenge";
-
-const challenge = await sandboxed(herding);
-
-test("the sheep in a pen score", () => {
-  const game = new Game(challenge).begin(1, { alice: "herder", bob: "herder" });
-  game.terrain({ from: { x: -8, y: -61, z: -8 }, to: { x: 8, y: -61, z: 8 } }, "minecraft:grass_block");
-  game.spawnEntity("s1", "minecraft:sheep", { x: 0.5, y: -60, z: 0.5 });
-  game.player("alice").moveTo({ x: 24, y: -60, z: 0 });
-  game.at("3m");
-  expect(game.state.winners).toEqual(["alice"]);
-  game.replay(); // reduces the log again and checks the final state is identical
+import { Game, sandboxed, scores } from "@kradle/challenges-sdk/test";
+import source from "./challenge";
+
+// Under `kradle challenge test`, the built bundle inside the arena's sandbox; the source otherwise.
+const challenge = await sandboxed(source);
+
+test("a kill scores", () => {
+	const game = new Game(challenge).begin(1, { Alice: "farmer", Bob: { role: "farmer", at: { x: 8, y: -60, z: 0 } } });
+	game.spawnEntity("p0", "minecraft:pig", { x: 1, y: -60, z: 0 });
+	game.removeEntity("p0", "died", "Alice");
+	expect(scores(game)).toEqual({ Alice: 1, Bob: 0 });
+	expect(game.result()).toBeUndefined();
+	game.at("2m");
+	expect(game.result()?.winners).toEqual(["Alice"]);
+	game.replay();
 });
 ```
 
-`Game` has `begin(seed, roster, opts?)` (a roster entry is a role, or `{ role, at, ...sample }` so the first tick carries the position and `start` sees it), `tick(n?)`, `after(duration)` and `at(duration)` (they land on the exact tick), `sample(players, entities?)` (one tick with several players and entity moves), `dispatch(event)`, `terrain(box, block)`, `setBlocks`, `spawnEntity`, `moveEntities`, `removeEntity`, `setGamemode`, `container(at, items, { by?, initial?, block? })` (a declared container's contents, as the engine reports them), `other(name, sample)`, `custom(name, data, player?)`, `walkResult(ok, detail?, { player? | id? })`, `state`, `actions`, `last`, `of(type)`, `all(type)`, `effects(kind)`, `effectsAll(kind)`, `announcements(to?)`, `said()`, `checkpoint()`, `Game.resume(challenge, json)`, `replay()` (from the state the game started with, also after `resume`). A `Fake` player (`game.player(name)`) has `moveTo(pos, extrema?)`, `enters(zone)`, `leaves(zone)`, `has(item, count)` (one slot per item, per game), `picksUp(item, count?, at?)`, `uses(block, at, item?)`, `breaks(block, at)`, `places(block, at)`, `says(text)`, `swings(animation?)`, `vote(voteId, option)`, `hurt(amount, cause, attacker?)`, `dies(cause?, killer?)`, `respawns()`.
+`Game.begin(seed, roster, opts)` sends `run_started`, the joins, one tick with every participant's position (a default row unless `at`), and confirms the setup batches. `game.player(name)` is a scripted player: `moveTo`, `says`, `vote(id, option)`, `hurt`, `dies`, `respawns`, `picksUp`, `setInventory`, `enters(zone)`, `exits(zone)`, `uses`, `breaks`, `places`, `joins`, `leaves`. The game feeds the mirror: `terrain`, `setBlocks`, `fillBlocks`, `spawnEntity`, `changeEntity`, `moveEntities`, `removeEntity`, `container`, `sample`, `other`; and answers the engine's side: `walkResult`, `batchResult`, `effectFailed`, `confirmSetup`. Time: `tick(n)`, `after(duration)`, `at(duration)`.
 
-The harness alone does not sandbox the reducer. `kradle challenge test <slug>` builds the challenge and runs its tests against the built bundle inside the arena's SES sandbox. `sandboxed(source)` returns the bundle under the command (`KRADLE_CHALLENGE_BUNDLE` set) and the plain import elsewhere; it is async, so await it at the top of the test file. Under the command a `Game` on the imported source throws, and the command counts the Games built on the bundle as its proof that the rules ran inside the sandbox. A test file is `challenges/<slug>/challenge.test.ts`, next to the rules (`kradle challenge create` writes it). The command also finds `tests/<slug>.test.ts` and `tests/<slug>/` under the project root.
+Reads: `game.state` (the shared data), `game.phase`, `game.status`, `game.participant(name)`, `game.reducerState` (everything), `game.of(type)` / `game.all(type)` (actions), `game.effects(kind)` / `game.effectsAll(kind)`, `game.said()`, `game.announcements(to?)`, `game.result()`, `game.logs()`, `game.metrics()`; `scores(g)` and `near(a, b, blocks)` from the same entry. `game.replay()` re-runs the log and compares; `game.checkpoint()` / `Game.resume(challenge, json)` cross a JSON round trip.
 
 ---
 
 ## Build and Run
 
-`kradle challenge build <slug>` bundles `challenge.ts` into one file (`kradle-runtime/challenge.js`), loads it once inside the sandbox (module code and `init()`), uploads it and activates it with the challenge's configuration. A challenge runs only after that activation. The server runs the `KradleEngine` plugin; the arena connects the reducer to it. The run's event log is uploaded as the `runtime` recording.
+`kradle challenge build <slug>` type-checks the project, bundles the challenge, loads the bundle in the arena's sandbox, reads its manifest and runs one synthetic start (a definition or API error fails the build; a throw from the challenge's own code that needs the world is a warning), then uploads and activates it. `kradle challenge run <slug>` starts a run in the cloud.
 
-`kradle challenge run <slug>` starts a run in the cloud. `kradle challenge run --local` (internal) needs the plugin jar in the local server.
+The manifest the bundle exports (`runtime: 2`) carries the name, the life, the roles, the locations, the markers, the votes and the params. The backend checks the roles against the challenge's configuration at activation and stores the votes with the artifact.
 
 ---
 
 ## Complete Examples
 
-The SDK ships five reference challenges in `src/runtime/examples/`: Climb (scores by height, `life: "single"`), Capture the Flag (two roles, zones, a flag carried in the inventory), Four Bridges (phases, votes, a judge context), Skywars (markers, chests, the last one standing), Sheep Herding (the entity mirror, a fence watched through the block mirror). They ship in the package under `dist/runtime/examples/` (sources in `src/runtime/examples/`).
-
-A complete small challenge, Climb:
+A one-round game:
 
 ```ts
-import { defineChallenge, End, minutes, Win } from "@kradle/challenges-sdk";
-import { config } from "./config";
+import { type ChallengeConfig, defineChallenge, winBy } from "@kradle/challenges-sdk";
 
-const FLOOR_Y = -60;
+export const config = {
+	name: "Pig Farming",
+	challengeConfig: {},
+	roles: { farmer: { description: "Farmer", minParticipants: 1 } },
+	endStates: { two_pigs: "A farmer reached two pigs", time_up: "Nobody did" },
+} as const satisfies ChallengeConfig;
 
 export default defineChallenge(config, {
-  duration: minutes(2),
-  life: "single",
-  world: { time: "day" },
-  player: () => ({ maxY: FLOOR_Y }),
-  start(g) {
-    for (const p of g.players) g.give(p, "minecraft:cobblestone", 64);
-    g.say("The Climb Challenge has begun!");
-  },
-  on: {
-    move(g, { player: p, maxY }) {
-      const y = Math.floor(maxY);
-      if (p.eliminated || y <= p.maxY) return;
-      p.maxY = y;
-      p.score = y - FLOOR_Y;
-    },
-    died(g, { player, killer }) {
-      if (killer) g.say(`${player.name} was killed by ${killer.name}`);
-    },
-  },
-  end: End.allEliminated,
-  winners: Win.topScore({ min: 1 }),
-});
+	state: { player: () => ({ pigs: 0 }) },
+	duration: "2m",
+	life: "respawn",
+	world: { time: "day" },
+})
+	.start((g) => {
+		g.say("The Pig Farming Challenge has begun!");
+		for (const p of g.players) for (const dx of [2, -2]) g.summon("minecraft:pig", { x: p.pos.x + dx, y: p.pos.y, z: p.pos.z });
+	})
+	.on({
+		entityRemoved(g, { entity, cause, killer }) {
+			if (entity.type !== "minecraft:pig" || cause !== "died" || !killer) return;
+			killer.state.pigs += 1;
+			if (killer.state.pigs === 1) g.achievement(killer, "farmed_a_pig");
+		},
+	})
+	.outcome({
+		scores: (_g, p) => p.state.pigs,
+		endWhen: (g) => g.players.some((p) => p.state.pigs >= 2),
+		winners: winBy.scoreAtLeast(2),
+		endState: (g) => (g.players.some((p) => p.state.pigs >= 2) ? "two_pigs" : "time_up"),
+	})
+	.onOver((g, result) => {
+		for (const p of g.players) g.title(p, { title: result.isWinner(p) ? "VICTORY" : "DEFEAT", stay: "5s" });
+	});
 ```
 
----
+A phased game with a vote, helpers and a loop:
 
-## Common Patterns
+```ts
+import { type ChallengeConfig, type CtxOf, defineChallenge, type PlayerIn, type ReadCtxOf, winBy } from "@kradle/challenges-sdk";
 
-**Score every tick from the mirror.** `on.tick: (g) => { for (const p of g.players) p.score = g.entities({ box: penOf(p), type: "minecraft:sheep" }).length; }`. The score reaches the run result when it changes.
+export const config = {
+	name: "Iterated Prisoner's Dilemma",
+	challengeConfig: {},
+	roles: { prisoner: { description: "Prisoner", minParticipants: 2 } },
+	endStates: { mutual_cooperation: "", mutual_defection: "", mixed: "" },
+} as const satisfies ChallengeConfig;
 
-**Phases.** `phases: { build: { duration: "2m", next: "fight" }, fight: { duration: "3m", next: "END", on: { died(g, { player }) { g.eliminate(player); } } } }`. `g.goTo("fight")` moves early; `enter`/`exit` run on the transition.
+type Choice = "cooperate" | "defect";
+const PAYOFF: Record<Choice, Record<Choice, number>> = { cooperate: { cooperate: 3, defect: 0 }, defect: { cooperate: 5, defect: 1 } };
+const ROUNDS = 5;
 
-**Timers.** `timers: ["release"]`, `g.schedule("release", "30s")` in `start`, `on.timer(g, { name })` fires once; scheduling again resets it.
+const challenge = defineChallenge(config, {
+	state: { game: () => ({ history: [] as Array<Record<string, Choice>> }) },
+	life: "respawn",
+	votes: { choice: { options: ["cooperate", "defect"], final: true } },
+	phases: ["DISCUSSION", "VOTE", "RESOLUTION"],
+	initialPhase: "DISCUSSION",
+});
+type R = ReadCtxOf<typeof challenge>;
+type Pl = PlayerIn<R>;
+const opponentOf = (g: R, p: Pl): Pl => g.players.find((o) => o.name !== p.name) ?? p;
+const totalOf = (g: R, p: Pl): number =>
+	g.state.history.reduce((sum, round) => sum + PAYOFF[round[p.name] ?? "defect"][round[opponentOf(g, p).name] ?? "defect"], 0);
+
+export default challenge
+	.phase("DISCUSSION", { duration: "20s", next: "VOTE", enter: (g) => g.say(`Round ${g.state.history.length + 1}: talk.`) })
+	.phase("VOTE", {
+		duration: "15s",
+		next: "RESOLUTION",
+		until: (g) => g.players.every((p) => g.vote(p, "choice") !== undefined),
+		enter: (g) => g.openVote("choice"),
+		exit: (g) => g.closeVote("choice"),
+	})
+	.phase("RESOLUTION", {
+		next: (g) => (g.state.history.length < ROUNDS ? "DISCUSSION" : "END"),
+		enter(g) {
+			const round = Object.fromEntries(g.players.map((p) => [p.name, g.vote(p, "choice") ?? "defect"]));
+			g.state.history.push(round);
+			for (const p of g.players) g.say(`${p.name} chose ${round[p.name]}: +${PAYOFF[round[p.name] as Choice][round[opponentOf(g, p).name] as Choice]}.`);
+		},
+	})
+	.outcome({
+		scores: (g, p) => totalOf(g, p),
+		winners: winBy.highestScore(),
+		endState: (g) => {
+			const all = g.state.history.flatMap((r) => Object.values(r));
+			return all.every((c) => c === "cooperate") ? "mutual_cooperation" : all.every((c) => c === "defect") ? "mutual_defection" : "mixed";
+		},
+	});
+```
 
-**Deliveries.** Declare the chest: `containers: { delivery: { x: 8, y: -60, z: 0 } }`. The engine reports its contents; the rule reads them: `container(g, { at, items }) { if (items["minecraft:white_wool"] >= 1) g.game.delivered = true; }`, or `g.contents("delivery")?.["minecraft:bread"] ?? 0` in an end condition. Do not infer a deposit from an inventory decrease: an item dropped or eaten leaves the inventory too. In a test: `game.container(CHEST, { "minecraft:white_wool": 1 }, { by: "Solo" })`.
+---
 
-**Votes.** `config.challengeConfig.votingOptions: { bridge: ["north", "south"] }`, `votes: { bridge: { final: true } }`, `on.vote(g, { player, voteId, option })` for accepted votes, `g.votes("bridge")` for the tally, `g.openVote("bridge")` for a new round. A vote on players: `votes: { player: { final: true } }`, then `g.votes("player")` maps each voter to the name it voted for (`skills.voteForPlayer` on the agent side). In `on.vote`, check `voteId` first: `if (voteId === "bridge")` narrows `option` to `"north" | "south"`; without the check it is a string, because the `player` vote's options are names.
+## Common Patterns
 
-**Zones.** `zones: { goal: { from, to } }`, `on.zoneEntered(g, { player, zone })`, `player.zones` for the current zones, `g.inZone(player, box)` for any box.
+**A record height.** Initialize from the observed player: `player: (p) => ({ startY: Math.floor(p.pos.y), recordY: Math.floor(p.pos.y) })`; in `move`, `if (y > p.state.recordY) p.state.recordY = y`; `scores: (_g, p) => p.state.recordY - p.state.startY`.
 
-**Markers.** Tag entities in the world (`kradle.chest.*`), declare `markers: { tags: ["kradle.chest."] }`, read `g.markers("kradle.chest.")` in `setup` to place blocks or chests at their positions.
+**A vote that ends the phase early.** `until: (g) => g.activePlayers.every((p) => g.vote(p, "room") !== undefined)`.
 
-**Items and inventories.** `g.give(p, "minecraft:wheat", 16)`, `g.count(p, "minecraft:wheat")`, `on.inventory(g, { player, item, count })` when a count changes, `on.pickup` when an item is picked up.
+**A round loop.** Copy the round's votes into `g.state` in the resolution's `enter` (the next `openVote` clears them), and loop with `next: (g) => (g.state.round < N ? "DISCUSSION" : "END")`.
 
-**Trades between agents.** The agents trade through their skills; the reducer sees the result as inventory changes. Nothing to declare.
+**A structure check.** `g.blockCount(box, "minecraft:cobblestone")` counts; `g.blockMatches(at, { id: "minecraft:oak_stairs", props: { facing: "east" } })` checks one block with its properties; read them from `blocksChanged`, which fires for every cause.
 
-**A judge.** `judgeContext: (g) => ({ bridges: g.game.bridges })` ships JSON with `game_over` for the LLM judge (`config.judging`).
+**A chest.** `g.container(at, [{ id: "minecraft:golden_apple", count: 2 }])` fills it; `on.container` reports every change with the deltas; `g.containerContents(at)` reads it anywhere.
 
-**Stored variables.** `g.store("round", g.game.round)` and `g.store("coins", p.coins, p)` keep the last value per name; they reach the run result (`customVars`) and the `runs get` table, like the datapack SDK's `log_variable(store: true)` did.
+**Private information.** `g.tell(player, message)` reaches one player; a `[PRIVATE]` prefix tells the agent it is private.
 
 ---
 
 ## Common Gotchas
 
-- `Date.now()` or `Math.random()` in a rule passes the plain harness and fails under `kradle challenge test` and in the arena. Use `g.tick`, `g.elapsed`, `g.rand`.
-- A helper typed from the challenge value (`typeof challenge.ctx`) and passed as a rule value makes the challenge's type circular. Type helpers with `ContextOf<typeof config, typeof state>` instead; then `endState: classify` is fine.
-- The state is JSON. A `Set`, a `Map`, a class instance or a function in `g.game` fails the reduction.
-- Your per-player fields may not reuse the SDK's names (`score`, `pos`, `alive`, ...).
-- `g.blockAt` is `undefined` outside the loaded chunks. Narrow `mirror.blocks` only when you know the box.
-- `g.command("fill ...")` is refused: the mirror would miss the change. Use `g.fill`.
-- A zone edge or a block change is seen on the next reducer tick (2 server ticks), not on the server tick itself.
-- `setup(g)` effects go out as one batch and the game starts after the engine confirms them; do not read the built blocks in `setup`.
-- Under `kradle challenge test`, `new Game(source)` on the imported source throws. Pass the result of `await sandboxed(source)`.
+- `endGame()` does not return from the callback. Write `return` after it when the rest must not run.
+- A phase step with `remaining` needs a `duration` on the same phase.
+- `openVote` on an open round throws: close it or reset it first.
+- `setScore` throws `score_derived` when `outcome.scores` exists. Pick one mode.
+- `blockCount` and `findBlocks` throw when a chunk of the box is not loaded; pass `{ partial: true }` to count what is loaded.
+- A helper typed from the challenge (`CtxOf<typeof challenge>`) takes its type from the root const, not from the full chain: keep `const challenge = defineChallenge(...)` and hang the steps off it.
+- A root predicate (`votes.x.accept`) cannot call a helper typed from the challenge.
+- Every player has `p.pos` from the initializers onward; before that, the initializers are the only code that runs, and they receive the position.
 
 ---
 
 ## Tips for LLMs
 
-- Start from the closest reference challenge and keep its structure: `config`, `state`, `type G`, helpers, `defineChallenge`.
-- Put every fact you need in the state; recompute from the mirror instead of caching what the engine already keeps.
-- Write the tests first with the harness: one test per rule, `game.replay()` at the end of each.
-- Run `kradle challenge test <slug>` before `kradle challenge build`: the sandbox catches the clock, the random and the timers.
-- Keep `config.ts` as the single source of the roles, the end states, the locations and the vote options; the types come from it.
+- Start from `config.ts`: the roles, the end states and the params make the types. Write `as const satisfies ChallengeConfig`.
+- Put the names in the root declaration first (phases, zones, timers, votes), then write the steps. The compiler then checks every name you use.
+- Prefer `outcome.scores` over manual score writes: the score is then a function of the state, computed after every event.
+- Keep `p.state` small and JSON. Copy what you keep from an event (`{ ...e.pos }`).
+- Test with `Game` before you build: a test is faster than a run, and `kradle challenge test` runs the same file under the arena's sandbox.