@kradle/challenges-sdk 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -17,6 +17,53 @@ also hand-edit this file or the [Unreleased] section at any time.
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-09-15
+
+### Added
+
+- The runtime SDK: a challenge is one `defineChallenge(config, spec)` call that returns a reducer, `reduce(state, event) -> { state, actions }`. Kradle feeds it the facts the server reports and applies the effects it returns; the reducer decides the scores, the zones, the votes and the end state. State types come from the initializers (`game()`, `player()`, per-role players) and `ContextOf` types the helpers, so you never write a type argument. Observations are frozen and applied whole per tick, so every player's zone membership is complete before a tick's handlers run. A throw in one of your callbacks ends the run as `error_challenge` and never loses `game_over`. See the runtime chapters of `README.md` and `LLM_README.md`.
+- The world mirror in the state: a palette of block states, sparse chunk sections, entities with rotation and equipment, and the other players. A rule reads blocks and entities without asking the server.
+- The test harness (`@kradle/challenges-sdk/runtime/harness`): `Game` feeds events, checks that `reduce` does not mutate its input, and replays a game from its start on request; `Fake` scripts a player; `terrain`, `setBlocks`, `spawnEntity`, `moveEntities` and `other` feed the mirror.
+- The sandbox for tests (`@kradle/challenges-sdk/runtime/sandbox`): `lockdownOnce()` applies the SES lockdown, `loadBundle()`/`loadBundleFile()` evaluate a built bundle in an empty `Compartment` and return the challenge, and `sandboxed(challenge)` swaps an imported challenge for the bundle named by `KRADLE_CHALLENGE_BUNDLE`. With that variable set, a `Game` on the imported source throws, so `kradle challenge test` proves your tests ran on the built bundle (no clock, no random, no timers). The loaders are async.
+- Reference challenges with tests: Climb, Capture the Flag, Four Bridges, Skywars and Herding.
+- Durations: `addDuration`, `subtractDuration`, `asSeconds`, `asMinutes`; `seconds()`, `minutes()`, `ticks()` and `toTicks()` reject a negative or non-finite value and round a fraction to the nearest tick.
+- `onOver(g, result)`: `result.winnerPlayers` and `result.isWinner(p)` next to the names; `result.endState` is typed (a declared end state, an SDK error state, or "").
+- `ContextOfChallenge<typeof challenge>`: the context type of a built challenge, for tests.
+- Harness: `begin` takes a position per roster entry (`{ role, at }`) so `start` sees it; `sample(players, entities?)` is one tick with several samples; `after`/`at` land on the exact tick; `walkResult` selects a pending walk by player or id; `replay()` starts from the checkpoint after `resume`; a fake player's item slots belong to one game.
+- Declared containers: `containers: { [name]: Vec3 }` in the spec, `g.contents(name | at)` for the item counts, `on.container({ at, items, changes, by? })` on every change, `Game.container(at, items, opts?)` in the harness. The engine reports the contents (capability `containers`); a delivery rule reads the chest instead of guessing from an inventory decrease. A report for a position that is not declared is ignored. Each half of a double chest is its own container; a broken container reports its slots as emptied.
+- `g.store(name, value, player?)`: a stored variable whose last value reaches the run result (`customVars`) and the `runs get` columns.
+- `on.gamemode(g, { player, gamemode })`, and joins that carry `uuid` and `gamemode`. New capabilities `lifecycle` and `requests`: `configured.online` is the operational roster, and `requests` names the `/kradle give|trade|vote` commands for humans.
+- The player vote: `votes: { player: {...} }` opens the vote `skills.voteForPlayer` casts in; its options are the other participants (`PLAYER_VOTE`, `OptionFor`).
+
+### Changed
+
+- `@kradle/challenges-sdk` (the main entry) is the reducer API, the same as `@kradle/challenges-sdk/runtime`. Both imports work.
+- The options of a vote are typed by its id: after `if (voteId === "room")`, `option`, `g.votes("room")` and `g.vote(p, "room")` carry that vote's options only (`OptionFor`, `g.votes<V>`, `g.vote<V>`).
+- Every SDK field on a player except `score`, every entity and every other player are read-only for a rule (the engine writes them).
+- **Breaking:** `g.goTo` of a phase that is not declared throws (the run ends as `error_challenge`) instead of an unknown phase state.
+
+### Removed
+
+- **Breaking:** The Sandstone datapack API (`createChallenge`, `Actions`, `forEveryPlayer`, the `sandstone` peer dependency, the datapack chapters of the docs). Kradle runs reducer challenges only. A challenge that still imports the old API fails `kradle challenge build` with a message; the Kradle team migrates existing challenges.
+- **Breaking:** `world.clearInventory`: players start with an empty inventory, so the start no longer sends a `clear` effect.
+
+## [0.10.0] - 2026-07-17
+
+### Changed
+
+- `start_challenge` now performs all setup in a single tick. The separate `init_participants` function that ran one second later is removed; its handler (if defined) runs in the same tick, immediately after the `start_challenge` handler.
+- The implicit inventory clear now runs before user events, so items given in `start_challenge` survive it.
+
+### Deprecated
+
+- `init_participants` event. Use `start_challenge` instead. Using `init_participants` logs a build-time deprecation warning.
+
+### Fixed
+
+- `.end_condition()` now defers callback evaluation to `build()`, fixing the documented bridge pattern where a variable captured from an event handler was always `undefined` at chain time.
+- **Breaking:** `.end_condition()` callbacks that return `undefined` now throw at build time instead of silently falling back to the tick-limit end condition. Either omit `.end_condition()` entirely or return a `ConditionType`.
+- `LLM_README.md` now documents that the `.end_condition()` callback must return a `ConditionType`.
+
 ## [0.9.0] - 2026-07-16
 
 ### Removed
@@ -71,7 +118,9 @@ also hand-edit this file or the [Unreleased] section at any time.
 - Voting primitives (`votedFor`, `promptVote`, `allVotesIn`, `assignDefaultVotes`) for challenges that use discuss-then-vote-then-act phases as an alternative to pad-based voting.
 - Build-time validation of vote IDs and options against `KRADLE_CHALLENGE_VOTING_OPTIONS` (when set), matching the existing `getLocation`/`setEndState` pattern. `promptVote` also validates each announced option against the declared `votingOptions`.
 
-[Unreleased]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.9.0...HEAD
+[Unreleased]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.8.1...v0.9.0
 [0.8.1]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/Kradle-ai/challenges-sdk/compare/v0.7.2...v0.8.0