feat(kit): the engagement contract, taught and built (cutover 5 of 7)

The kit was pinned to website 963d734 -- MODULE_API 1.6.0, the Teams cutover --
and the platform is on 1.9.0. Three registrations and two calls arrived in
between, and a reader building against this book would have found no mention of
any of them: a module can now declare what its game can announce, and never who
is told.

Moving `ci/core-ref.json` is the mechanism for exactly this. The pin is now
66bb3b9a (website `main`, the engagement cutover) and `template/module.json`
declares `^1.9.0`.

What chapter 2 gained, under "Telling core something happened":

  * a TRIGGER is a payload contract, not a notification stream -- the two share
    one id namespace and are constantly confused;
  * `ceiling` is required, has no default, and is a CONTAINMENT tree rather than
    a size ladder (a `staff` ceiling does not permit `owner`);
  * an AUDIENCE resolver returns user ids and nothing else, resolves to NOBODY
    on failure, and takes CONSTANT params -- the constraint worth knowing before
    you design around it;
  * templates re-ensure per seedVersion, rule groups are offered ONCE per group
    key, so a rule appended to an existing group reaches fresh installs only;
  * `ctx.events.emit` binds the owner and is fire-and-forget; `ctx.inbox.push`
    is the direct write, for when there is nothing for an operator to decide.

The template builds all of it: one trigger, one audience over the clan roster it
already had, one seeded body and one seeded rule group, and an emitter in
`boot.js` that fires on the TRANSITION rather than on the poll. Seven new tests,
including the audience that resolves to nobody when its query throws.

Three claims were wrong and are corrected here rather than shipped:

  * core validates `subjectKey` against the declared variables and refuses the
    module; the draft taught a cooldown keyed on `undefined`, which the check
    exists to prevent and a reader will never see.
  * `emit` throws OUTSIDE production and only drops-and-logs inside it. Teaching
    the second half alone leaves a developer meeting a throw the book says
    cannot happen.
  * the seeded body itself was malformed -- heading `level: 2` where the block
    registry takes 'h2', and no block ids at all.

The third is the one worth keeping: `registerEngagementSeeds` checks that
`blocks` is a non-empty array and stops, so that body would have registered,
seeded, and failed the first time an operator opened it. Found by running the
template's `register()` through core's real registry at the pinned ref -- which
CI does not do, and cannot: the template job checks the version and runs the
template against fakes. A fake accepts what core refuses. The gap is now named
in the chapter, beside the code, and in the pin's own comment, and the rule that
bit has a test that fails on it.

Also: `checkLinks` skipped `.core/`. Bumping this pin means cloning core into
that directory first, and the walk then reported nine broken links in someone
else's README. CI never saw it -- the clone happens in the `template` job and
the check runs in `prose` -- so it was a failure only a person could meet.

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

template/server/index.js

@@ -103,6 +103,165 @@ module.exports = function register(ctx, api) {
   // optional ones is an edit to the provider and not to this file.
   api.registerTeamProvider(clanProvider)
 
+  // ── Engagement: declaring what your game can announce ────────────────────
+  //
+  // The three calls below are one seam, and it is the one where a module is most
+  // tempted to reach past the boundary. **You declare what CAN happen; core
+  // decides who is told.** A module never names a person, a channel or an
+  // address, and never sends anything (MODULE_API 1.7.0 and 1.9.0; §2.7).
+  //
+  // A TRIGGER is not a notification stream, and the two are easy to confuse
+  // because both are catalogs of things that happen. A stream is a subscribe
+  // toggle you publish to yourself. A trigger is a PAYLOAD CONTRACT an operator
+  // writes rules against — it says what variables the event carries and how wide
+  // an audience it may ever be given, and core does the sending. Their ids share
+  // one namespace, so declaring both for one id is legal and is one event with a
+  // toggle and a contract; taking an id another module owns is not.
+  api.registerEventTriggers([
+    {
+      id: 'examplegame.world.status_changed',
+      label: 'World came up or went down',
+      description: 'The game server changed between online and offline.',
+      kind: 'event',
+      // The cooldown subject: "once per world", not "once per user". It must
+      // NAME one of the variables below — core refuses the registration
+      // otherwise, with this trigger's id in the message, and the module does not
+      // load. That check exists because the failure it prevents is silent: a
+      // subjectKey naming nothing keys every subject on `undefined`, which looks
+      // exactly like the feature working right up until two worlds share it.
+      subjectKey: 'worldName',
+      audience: 'authenticated',   // what a rule is CREATED with
+      // ...and the widest it may EVER be given. Required, with no default,
+      // because there is no safe value to guess: `owner` would silently break a
+      // broadcast and `authenticated` would silently widen a staff-only event.
+      // The values are ordered by CONTAINMENT, not by size — see chapter 2.
+      ceiling: 'authenticated',
+      version: 1,
+      variables: [
+        // Every variable needs an `example`, and it is not decoration: it is what
+        // lets an operator preview and test-send a template without waiting for a
+        // real game event, which is the reason template systems ship untested.
+        { name: 'worldName', type: 'string', required: true, example: 'Example World' },
+        { name: 'status', type: 'string', required: true, example: 'online' },
+        { name: 'players', type: 'int', required: false, example: 42 },
+        // A `url` is validated SITE-RELATIVE, because it ends up in an href in a
+        // mail somebody opens days later. Never a full URL of your own.
+        { name: 'url', type: 'url', required: false, example: '/world' },
+      ],
+    },
+  ])
+
+  // An AUDIENCE is a named set of PEOPLE this module can resolve over its own
+  // data, for an operator to point a rule at. "This clan's members" is one;
+  // "everyone who opened the last mail" is not, and nothing here builds it.
+  //
+  // **The resolver returns user ids and nothing else.** It is not handed a
+  // template, a channel or an address and it cannot enumerate them — core maps
+  // ids to addresses on its own side, after preferences, suppression and the
+  // verification gate. That is what stops this becoming the back door §2.7 spends
+  // a section closing.
+  //
+  // Audiences are their OWN id space, unlike triggers and streams: an audience
+  // names a set of people and a trigger names an event, so the two may share a
+  // name without colliding.
+  api.registerAudiences([
+    {
+      id: 'examplegame.clan.members',
+      label: 'Members of a clan',
+      // `int` or `string` only, and CONSTANT — an operator fills these in when
+      // they save the rule. There is no way to say "the clan this event was
+      // about"; if a rule needs that, the EVENT carries its own recipients
+      // instead. Finding that out late is a phase's worth of rework.
+      params: [{ id: 'clanId', type: 'string', required: true }],
+      ceiling: 'members',
+      resolve: async ({ clanId }) => clanProvider.listClanMemberUserIds({ clanId }),
+    },
+  ])
+
+  // Finally the CONTENT: the bodies your messages use, and the rules that decide
+  // when one is sent. Both arrive **switched off** — `enabled` is not a parameter
+  // and there is no call that sets it. An operator turns a module's mail on;
+  // installing a module never does.
+  //
+  // The two halves have different lifetimes, and the asymmetry is the contract:
+  //
+  //   • **Templates are re-ensured on every boot**, under `seedVersion`, so
+  //     improving a default body reaches deployments that never edited it — and
+  //     one an operator HAS edited is marked customized and left alone. Bump
+  //     `seedVersion` when the body changes; never for a comment.
+  //   • **Rule groups are offered ONCE, per named group key.** Re-offering would
+  //     resurrect a rule an operator deleted and reset one they enabled. So a rule
+  //     appended to an existing group reaches FRESH INSTALLS ONLY. That is the
+  //     guarantee rather than a limitation to work around: a rule that has to
+  //     reach existing deployments takes a NEW group key, and you choose that
+  //     knowingly because you name the groups.
+  //
+  // Core's generic bodies are a first-class answer, not a fallback: point a
+  // channel at `notify.event` / `inapp.event` / `notify.digest` and author
+  // nothing. Ship a body of your own when the message has something to say that a
+  // structural projection of the payload cannot. Below, the mail does — a world
+  // coming back deserves a sentence — and the in-app item does not, so it uses
+  // core's.
+  //
+  // Note the two casings, which are not a slip: a TEMPLATE is an object this call
+  // shapes (`triggerId`), and a RULE is a row (`trigger_id`). Copy them as they
+  // are.
+  api.registerEngagementSeeds({
+    templates: [
+      {
+        // MUST be namespaced `<moduleId>.` — the key column is unique across the
+        // whole table, and an unprefixed `notify.event` from a module would
+        // collide with core's own body and win.
+        key: 'examplegame.world-status-changed',
+        name: 'World — status changed',
+        channel: 'email',
+        subject: '{{worldName}} is {{status}}',
+        triggerId: 'examplegame.world.status_changed',
+        triggerVersion: 1,
+        seedVersion: 1,
+        // The same block objects the template editor writes, so an operator can
+        // open this in the admin panel and keep editing from here.
+        //
+        // **This is the one thing in this file core does not check for you.**
+        // `registerEngagementSeeds` asserts that `blocks` is a non-empty array and
+        // stops; the BODY is validated by the block registry, which runs in the
+        // editor and in the renderer. So a malformed block registers, seeds, and
+        // first shows itself when an operator opens the body or a rule fires.
+        // Two that are easy to get wrong: every block carries its own `id`, and
+        // `email.heading`'s `level` is 'h1' | 'h2' | 'h3' — not a number.
+        blocks: [
+          { id: 'h', type: 'email.heading', props: { level: 'h2', text: '{{worldName}} is {{status}}' } },
+          { id: 'intro', type: 'email.text', props: { text: 'There are {{players}} players online right now.' } },
+          { id: 'cta', type: 'email.button', props: { label: 'Open the world page', url: '{{url}}' } },
+        ],
+      },
+    ],
+    ruleGroups: [
+      {
+        key: 'world-v1',
+        note: 'the world status rule, seeded once',
+        rules: [
+          {
+            trigger_id: 'examplegame.world.status_changed',
+            name: 'World status changes',
+            audience: 'authenticated',
+            channels: ['email', 'inapp'],
+            template_keys: {
+              email: 'examplegame.world-status-changed',
+              inapp: 'inapp.event',
+            },
+            // Two ceilings on volume, and they answer different questions. The
+            // cooldown is per SUBJECT — one mail per world per hour, however many
+            // times it flaps. The hourly cap is per RULE, and is the thing that
+            // keeps a misconfiguration from becoming a mail storm.
+            cooldown_seconds: 3600,
+            max_sends_per_hour: 200,
+          },
+        ],
+      },
+    ],
+  })
+
   // The lifecycle hooks (§2.5). `onBoot` runs after core's schema, after this
   // module's schema fragment, and BEFORE the HTTP listener binds — so a module
   // that must not serve traffic until it has warmed a cache gets that for free.