feat(kit): the event contract, taught and built (chapter 5)

The fifth chapter, and the template code it teaches out of. Events is the first
thing in the book that goes the other way — chapters 1-4 move data out of the
game and onto a page; an event changes a live world on a schedule, unattended.

**Chapter 5** covers the four declarations (budgets, option sources, leases,
actions), leads with the lease because EVENTS.md §H is right that it is the
primitive that travels and the spawn is the special case, and gives one section
each to the four things that are invisible until an outage: the envelope's
failure default, the idempotency passthrough, recording a resource before
confirming it, and under-declaring `cost`.

**Chapters 3 and 4 gain one section each** for the command plane, because
without them chapter 5 teaches a module to send an idempotency key to a sidecar
the book never told anyone to build a command path in. Both say at the top that
they are skippable until you want chapter 5.

**The template ships one of each declaration**, with `server/sidecarClient.js`
as the near end — a real timeout, a real key passthrough, a simulated transport
in one function marked for replacement. That file is named for the filename
`noGameConnection.test.js` already anticipated, so the test stays green now and
fires correctly the moment `deliver()` becomes a request.

Two things writing it found, both now in the chapter and beside the code:

  * **An idempotency key belongs on a command, never on a question.** The first
    draft keyed every call including the reads; an at-most-once store then
    answers every future read with the first one's reply, forever. The lease
    applied correctly and the module could no longer see it. Hence `ask` and
    `send` as two functions.

  * **A refusal's reason goes in `error`; core reads no other name.** The first
    draft used `detail`, on the strength of the one place EVENTS.md §H mentions
    it, and every refusal it produced was anonymous on the run console.

Proved by running the template's real declarations through core's real registry
at `edge` (all four accepted) and its real envelopes through the real
`events/dispatch.js` classifier.

**CI is RED on `checkCoreApi` and that is the mechanism working.** The template
now declares `coreApi: ^1.10.0` and `ci/core-ref.json` pins the engagement
cutover, where `main` is still 1.9.0. Equality is the check, a bump is meant to
turn this repo red until someone re-reads the chapters, and the pin move rides
in the events cutover (EVENTS_PLAN.md P16) as its own commit. Do not "fix" it.

Refs EVENTS_PLAN.md Phase 15, EVENTS.md §F, MODULE_API.md 1.10.0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

book/04-game-plugin.md

@@ -103,6 +103,53 @@ escape into a game code path. `BridgeLink` wraps the inbound handler and logs
 anything it throws, because the alternative is an exception unwinding somewhere in
 the engine's main loop.
 
+## A command that changes the world runs at most once
+
+Skip this until you want [chapter 5](05-events.md). Everything above assumes an
+inbound line either asks a question or is a one-off an operator typed. An **event**
+is neither: it is unattended, it is retried, and what it does is permanent.
+
+Three obligations, and they all live on this side of the wire because this is the
+side that has the world.
+
+**Keep a key store, and persist it.** Every command an event sends carries an
+idempotency key — a function of the step's identity, never of the attempt, so a
+retry carries the one the first attempt did. Before executing, look the key up:
+
+- **not seen** — execute, then record the key *with the reply you are about to
+  send*;
+- **seen and finished** — send that stored reply back, unchanged. Do not re-run;
+- **seen and still running** — answer "busy". It is transient by construction, and
+  the caller will retry; running it concurrently with itself is the failure.
+
+The stored reply matters as much as the guard. A repeat that re-ran and returned a
+*new* serial would be two things in the world and one in the website's ledger,
+which is the exact failure the key exists to prevent, arrived at by a longer route.
+
+**Persist it in the world save, not in memory**, if what the command creates
+survives a restart. The case this whole mechanism exists for is a game restarting
+mid-event, and a key store that dies with the process is a store that is empty in
+precisely that case.
+
+**Own what an event made, and expire what it borrowed.**
+
+An event-created thing has to be findable again later, because the website will ask
+you to remove it after the event and may ask more than once. That means a registry
+— a persisted map from the website's reference to the object — and it means
+`remove` is idempotent: **removing something that is not there is a success.** The
+website records a resource *before* it is confirmed, so it will ask you about
+things that may never have existed, and neither end can tell the difference.
+
+A borrowed value is the mirror. It arrives with a duration, and you arm a timer that
+puts the baseline back when it expires. If the borrowed value lives in the save
+file, persist the hold and **re-arm the timer at load** — a restart preserves the
+change and destroys only the thing that would have undone it. Restore with a
+compare-and-set against what you applied: if a staff member has moved it by hand
+since, report that rather than overwriting them.
+
+The through-line: **the game enforces the expiry, not the website.** If the website
+is never heard from again, every borrowed value still comes back on its own.
+
 ## Reconnect, and what to send on connect
 
 Your sidecar restarts independently of your game. It comes back with an empty
@@ -173,12 +220,25 @@ Two practical notes from that file, both general:
 If all eight hold, the worst a broken sidecar can do to your game is nothing at
 all — which is the entire point of the arrangement.
 
+Three more, and only if you took commands (chapter 5):
+
+9. A command's idempotency key is looked up before it is executed, and a repeat is
+   answered with the stored reply rather than re-run.
+10. What an event made is in a persisted registry, and removing something absent is
+    a success.
+11. A borrowed value's expiry is armed by this side, re-armed at load, and restored
+    with a compare-and-set.
+
 ---
 
 That is the book. The three parts are a module core loads, a sidecar that owns the
 game connection and the durable copy of what it said, and a plugin that feeds the
 sidecar without ever waiting on it.
 
+[Chapter 5](05-events.md) is the optional fifth part: what to declare if you want
+the website to be able to change your world on a schedule, and the four mistakes
+that make that unsafe.
+
 If you got this far and built something, the places you got stuck are the most
 valuable thing this repo can receive — [tell us][issues], and please say where you
 left the kit and what you did next.