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

template/server/boot.js

@@ -31,6 +31,7 @@ const core = require('./core')
 
 const worldStatusDb = require('./model/worldStatus/worldStatus.db')
 const clanDb = require('./model/clans/clanProvider.db')
+const sidecar = require('./sidecarClient')
 
 const log = core.logger('boot')
 
@@ -39,6 +40,10 @@ const log = core.logger('boot')
 // so that there is something for the shutdown hook to actually do.
 let refreshTimer = null
 
+// The last boot id the game reported. `null` means "never observed", which is not
+// the same as "changed" — see `checkForRestart`.
+let lastBootId = null
+
 const REFRESH_MS = 30 * 1000
 
 /**
@@ -70,6 +75,9 @@ async function refresh() {
     const previous = await worldStatusDb.getStatus()
     await worldStatusDb.setStatus(next)
 
+    // Same poll, different question: did the thing we lit beacons in restart?
+    checkForRestart()
+
     // `previous === null` is the first boot on a fresh install, not a change.
     // Treating it as one would announce the world coming online to everyone the
     // first time an operator started the site.
@@ -96,6 +104,42 @@ async function refresh() {
   }
 }
 
+/**
+ * Notice that the game restarted, and tell core.
+ *
+ * **Core has no concept of the game being up.** It sees `{ ok: false, retry: true }`
+ * from a dispatch and cannot tell a wedged sidecar from a game that rebooted and
+ * lost every beacon an event lit. Only this module knows, because only this
+ * module watches the feed the boot id arrives on — which is also how you tell a
+ * game restart from a sidecar reconnect, and they are not the same event: the
+ * second loses nothing.
+ *
+ * So core asks once, at its own boot — the one reconnect it can see — and
+ * otherwise waits to be told. `core.reconcileEvents()` is being told. It returns
+ * at once and core sweeps its resource ledger on its own time, putting the
+ * question back to this module as `reconcile({ runId, resources })` in
+ * `config/eventActions.js`.
+ *
+ * Called from the same poll as everything else here, because a boot id is just
+ * another thing the feed carries. In a real module this is a frame handler rather
+ * than a comparison against a remembered value.
+ */
+function checkForRestart() {
+  const bootId = sidecar.currentBootId()
+  if (lastBootId === null) {
+    // First observation is not a restart. Recording it as one would ask core to
+    // reconcile every ledgered resource on every website deploy, which is a sweep
+    // that costs a round trip per action for no news.
+    lastBootId = bootId
+    return
+  }
+  if (bootId === lastBootId) return
+
+  lastBootId = bootId
+  log.info('game restarted, asking core to reconcile', { bootId })
+  core.reconcileEvents()
+}
+
 /**
  * Two clans, so that the Team provider has something to be authoritative about.
  *
@@ -162,7 +206,8 @@ async function onBoot() {
 async function onShutdown() {
   if (refreshTimer) clearInterval(refreshTimer)
   refreshTimer = null
+  lastBootId = null
   log.info('shut down')
 }
 
-module.exports = { onBoot, onShutdown, refresh, seedClans, REFRESH_MS }
+module.exports = { onBoot, onShutdown, refresh, seedClans, checkForRestart, REFRESH_MS }