Merge pull request 'feat(engagement): declare 24 shard triggers and 3 audiences (Phase 11a)' (#22) from feature/engagement-triggers into edge

Reviewed-on: #22

README.md

@@ -101,7 +101,7 @@ server/index.js          the entry point — register(ctx, api), synchronous, no
 server/router/           routers + controllers, one directory per tier
 server/model/            one directory per table family; nothing crosses the boundary
 server/utils/            sidecar client, visibility, ingest, town crier, cliloc, atlas
-server/config/           the push stream catalog
+server/config/           the push stream catalog, the engagement triggers and audiences
 server/db/schema.sql     idempotent fragment, replayed by core's ensureSchema()
 server/db/purge.sql      destructive; only ever run by an explicit purge
 server/scripts/          the three checks: imports, the fragment, the frozen manifest
@@ -112,6 +112,14 @@ client/vite.config.js    the library build, the aliases, the not-bundled guard
 client/dist/             PREBUILT ESM chunk, built by CI — never by an operator
 ```
 
+**What this module registers with core, beyond its routes.** Seven push streams, one announce leg
+(the in-game town crier), a Team provider (a UO guild is a Team), one slash command, and — since
+ENGAGEMENT.md Phase 11 — **24 engagement triggers and 3 audiences**. A trigger is a payload contract:
+what a rule may fire on, what a template may interpolate, and the widest audience an operator may ever
+give it. Core learns none of the vocabulary; it holds ids, labels and ceilings. Declaring a trigger
+sends nobody anything — every rule ships disabled. The catalogue, the four rows deliberately absent
+and the reasons are in [`docs/modules/uo/API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/uo/API.md) §5.
+
 **The three generated files are committed on purpose.** Two of them are what core reads instead of
 looking at this source — it never has it — and the third records which core they were proved against.
 A generated file nobody reviews is a generated file nobody notices going wrong, so each lands in a

module.json

@@ -1,8 +1,8 @@
 {
   "id": "uo",
   "name": "Ultima Online",
-  "version": "0.3.0",
-  "coreApi": "^1.3.0",
+  "version": "0.4.0",
+  "coreApi": "^1.8.0",
   "server": "server/index.js",
   "client": { "entry": "client/dist/entry.js" },
   "schema": "server/db/schema.sql",

server/config/shardAudiences.js

@@ -0,0 +1,99 @@
+// ── module-uo's registered audiences ───────────────────────────────────────
+//
+// ENGAGEMENT.md §5.1a, and this module's first three. An audience is a NAMED SET
+// OF PEOPLE an operator can point a rule at, or compose into a saved segment with
+// and/or/not — "the members of guild 1042", "the governors", "everyone who has
+// linked a game account".
+//
+// **This is a different mechanism from the `members` audience the guild triggers
+// use, and the difference is worth stating because the words are the same.** A
+// guild event is about the members of THAT guild, which is a different answer for
+// every firing; a segment's parameters are CONSTANTS, so it cannot express it,
+// and the access-checked set travels on the envelope as `recipientUserIds`
+// instead (Phase 6, decision 2). What is here answers the same question every
+// time it is asked, which is exactly what makes it composable and storable.
+//
+// **Four rules, all of them from §5.1a:**
+//
+//   1. **Core learns no game vocabulary.** It knows an id, a label, a parameter
+//      list and a `resolve` it may call. It has never heard of a guild.
+//   2. **The resolver returns user ids and NOTHING else.** It is not handed a
+//      template, a channel or an address and cannot enumerate them. A module still
+//      cannot send mail, and this must not become the door that lets it — core
+//      maps ids to addresses on its own side, after preferences, suppression and
+//      the verification gate.
+//   3. **Composition narrows, never widens.** The `ceiling` below is the widest
+//      this audience can EVER resolve to; a segment takes the narrowest ceiling it
+//      contains, and the result is still checked against the trigger's own.
+//   4. **An uninstalled module's audience goes dormant**, resolving empty, rather
+//      than erroring or silently reaching a different set of people.
+//
+// All three ceiling at `members`, and none higher. `members` is the lattice value
+// for "a module-declared list", and it is the honest one here: these sets are not
+// "everyone signed in" narrowed down, they are lists this module happens to know.
+//
+// Every resolver is bounded by `shardLinks.MAX_AUDIENCE` through the queries it
+// calls, and every one of them fails to the EMPTY set rather than throwing — a
+// dormant audience is a rule that reaches nobody, which is §5.1a rule 4's
+// behaviour and much better than a rule that 500s the engine.
+
+const shardLinks = require('../model/shardLinks/shardLinks.model')
+const shardState = require('../model/shardState/shardState.model')
+const core = require('../core')
+
+const log = core.logger('shard-audiences')
+
+// One wrapper, so every resolver has the same failure behaviour and none of them
+// has to remember it. A resolver that throws would fail the whole enqueue for
+// every other audience in the same segment.
+const safely = (id, fn) => async (params) => {
+  try {
+    return await fn(params || {})
+  } catch (err) {
+    log.warn('audience resolve failed — treating as empty', { audience: id, message: err.message })
+    return []
+  }
+}
+
+const AUDIENCES = [
+  {
+    // `namespaced()` requires the module's own prefix, so these are declared with
+    // it rather than relying on core to add one. Audiences have their own id
+    // space — an audience names a set of PEOPLE and a trigger names an EVENT — so
+    // `uo.guild.members` here does not collide with any trigger id.
+    id: 'uo.guild.members',
+    label: 'Members of a guild',
+    description: 'Everyone with a linked game account on one guild\'s roster.',
+    params: [{ id: 'guildId', type: 'int', required: true }],
+    ceiling: 'members',
+    resolve: safely('uo.guild.members', async ({ guildId }) => {
+      if (guildId == null) return []
+      const accounts = await shardState.listGuildMemberAccounts(guildId)
+      return shardLinks.userIdsForAccounts(accounts)
+    }),
+  },
+  {
+    id: 'uo.governors',
+    label: 'Town governors',
+    description: 'Everyone with a linked game account currently holding a city governorship.',
+    params: [],
+    ceiling: 'members',
+    resolve: safely('uo.governors', async () => {
+      const accounts = await shardState.listGovernorAccounts()
+      return shardLinks.userIdsForAccounts(accounts)
+    }),
+  },
+  {
+    id: 'uo.linked.accounts',
+    label: 'Players with a linked game account',
+    // The set an operator reaches for first, and — more usefully — the one a
+    // `not` composes against: "everyone who has NOT linked" is the audience for
+    // the message that asks them to.
+    description: 'Every website user who has linked at least one game account.',
+    params: [],
+    ceiling: 'members',
+    resolve: safely('uo.linked.accounts', () => shardLinks.allLinkedUserIds()),
+  },
+]
+
+module.exports = { AUDIENCES }

server/config/shardTriggers.js

@@ -0,0 +1,690 @@
+// ── module-uo's engagement triggers ────────────────────────────────────────
+//
+// ENGAGEMENT.md §8.6 and Phase 11. The twin of `config/shardStreams.js`: that
+// file declares which shard events a player may get a content-free PUSH tickle
+// for, and this one declares the PAYLOAD CONTRACT behind an event — what a rule
+// may fire on, what a template may interpolate, and the widest audience an
+// operator may ever give it.
+//
+// **One namespace, two facets** (§7.2, the org lead's Phase 2 decision). A
+// trigger id and a stream id live in the same space and an id has exactly one
+// owner across both, so the seven grandfathered stream ids in `shardStreams.js`
+// (`idoc.warning`, `house.idoc`, …) are ALSO this module's for trigger purposes.
+// Nothing below reuses one: the trigger ids here are the `uo.*`-prefixed names
+// §8.6 specifies, and they are new. A trigger-only id gets email and in-app
+// preferences and no push toggle, which is correct — `allStreams()` serves the
+// stream facet only, so the shipped Android client's catalog is unchanged.
+//
+// **Every ✅ row of §8.6 is here except four, and each carve-out is recorded**
+// in ENGAGEMENT.md §8.6 with its reason rather than being silently absent:
+//
+//   • `uo.market.item_listed` — a saved SEARCH, not a trigger. Its audience is
+//     "users whose stored query matches this listing" and no per-user query store
+//     exists anywhere in the tree.
+//   • `uo.guild.joined` — core's `team.member.joined` already fires for it. A UO
+//     guild IS a Team and this module is the Team provider, so `teamSync` emits
+//     on every roster reconcile; a second trigger would be two mails for one join.
+//     `uo.guild.left` and `uo.guild.disbanded` DO ship — core has neither.
+//   • `uo.link.requested` — no addressable recipient by construction (the account
+//     is not yet linked, which is the point of the event) and a ~5-minute TTL no
+//     channel can beat.
+//   • `uo.points.rank_changed`'s personal half — `points.board`'s `top[]` names a
+//     mobile SERIAL and `shard_account_links` is keyed by ACCOUNT. The board-change
+//     feed ships at `subscribers`; "you were pushed out" does not.
+//
+// **Three rules every declaration below obeys, all of them enforced at
+// registration** (`registries.js`), so a mistake here is a boot failure rather
+// than a defect discovered in someone's mailbox:
+//
+//   1. **`ceiling` is required and there is no default.** It is the widest
+//      audience a rule may ever be given (G24), re-checked at save AND at send.
+//      `uo.cheat.detected` is why the lattice exists: `owner` would mail the
+//      cheat report to the player who was detected, and `staff` is the answer.
+//   2. **Every variable carries an `example`.** It is what the template editor
+//      previews and test-sends with; without one, testing a template needs a live
+//      game event, which is how template systems ship untested (§4.3 property 3).
+//   3. **A `url` variable is site-RELATIVE** and validated as such. A payload
+//      value ends up in an href in an email, and `//evil.test/x` passes an "is it
+//      rooted" check while being protocol-relative.
+//
+// **Nothing here emits.** `utils/shardEngagement.js` is the mapper that turns a
+// wire frame into a call; this file is only the contract. Keeping them apart is
+// what lets the declarations be read as a catalogue and diffed against §8.6.
+
+// Every trigger's `version`. Bumped per declaration when a variable's MEANING
+// changes, not when one is added — an added optional is what `required: false`
+// is for, and a stored rule keeps working across it.
+const V1 = 1
+
+// ── Owned asset at risk — the flagship family ──────────────────────────────
+//
+// All three resolve through the frame's `ownerAcct` → `shard_account_links` →
+// a website user, which is what `ownerUserId` on the envelope carries. A house
+// or vendor whose owner never linked an account is nobody to notify, and the
+// mapper drops it rather than treating it as an error.
+
+const OWNED_ASSET = [
+  {
+    id: 'uo.house.idoc_warning',
+    label: 'Your house is decaying',
+    description: 'One of your houses reached a late decay stage and will collapse if it is not refreshed.',
+    kind: 'event',
+    // The house, not the owner. A player with three decaying houses should hear
+    // about all three; a cooldown keyed on them would report one and swallow the
+    // rest. This is the case that makes `subjectKey` worth having at all.
+    subjectKey: 'houseSerial',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'houseSerial', type: 'string', required: true, example: '0x400142F9',
+        description: 'The house, as the shard names it. Also the cooldown subject.' },
+      { name: 'houseName', type: 'string', required: false, example: 'Millrace',
+        description: 'The house sign\'s name, when it has one.' },
+      { name: 'stage', type: 'string', required: true, example: 'Greatly',
+        description: 'The decay stage it just entered: Slightly, Somewhat, Fairly, Greatly or IDOC.' },
+      { name: 'previousStage', type: 'string', required: false, example: 'Fairly',
+        description: 'The stage it was in before.' },
+      { name: 'region', type: 'string', required: false, example: 'Britain',
+        description: 'The named region the house stands in.' },
+      { name: 'location', type: 'string', required: false, example: 'Felucca 1480, 1600',
+        description: 'Facet and coordinates, already formatted for reading.' },
+      // **Protocol 5, and both are `required: false` on purpose.** A shard still
+      // running a v4 overlay emits no `schedule` at all, and a dynamic-decay shard
+      // omits `estimatedCollapse` at every stage before IDOC because ServUO draws
+      // each stage's duration at random when the stage is entered. So the mail has
+      // to read correctly without them — which is exactly what an optional
+      // variable and a template that omits an absent one give you.
+      { name: 'nextStage', type: 'datetime', required: false, example: '2026-09-01T20:33:15Z',
+        description: 'When it leaves this stage. Absent under static decay, which keeps no stage clock.' },
+      { name: 'estimatedCollapse', type: 'datetime', required: false, example: '2026-09-06T20:33:15Z',
+        description: 'When it collapses — present ONLY when the shard can state it exactly. Absent is "not knowable", never "not yet read".' },
+      { name: 'lastRefreshed', type: 'datetime', required: false, example: '2026-08-25T17:21:14Z',
+        description: 'When the house was last refreshed.' },
+      { name: 'houseUrl', type: 'url', required: false, example: '/shard/houses',
+        description: 'Site-relative path to the IDOC page.' },
+    ],
+  },
+  {
+    id: 'uo.house.collapsed',
+    label: 'Your house collapsed',
+    description: 'One of your houses fell — the bad news, so that it is not a surprise.',
+    kind: 'event',
+    subjectKey: 'houseSerial',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'houseSerial', type: 'string', required: true, example: '0x400142F9',
+        description: 'The house, as the shard names it. Also the cooldown subject.' },
+      { name: 'houseName', type: 'string', required: false, example: 'Millrace',
+        description: 'The house sign\'s name, when it had one.' },
+      { name: 'region', type: 'string', required: false, example: 'Britain',
+        description: 'The named region it stood in.' },
+      { name: 'location', type: 'string', required: false, example: 'Felucca 1480, 1600',
+        description: 'Facet and coordinates, already formatted for reading.' },
+    ],
+  },
+  {
+    id: 'uo.vendor.expiring',
+    label: 'Your vendor is about to be dismissed',
+    description: 'One of your player vendors is running out of gold for its fees and will be dismissed.',
+    kind: 'event',
+    subjectKey: 'vendorSerial',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'vendorSerial', type: 'string', required: true, example: '0x40001234',
+        description: 'The vendor, as the shard names it. Also the cooldown subject.' },
+      { name: 'shopName', type: 'string', required: false, example: 'Darrow\'s Bargains',
+        description: 'The shop\'s name.' },
+      { name: 'dismissalAt', type: 'datetime', required: true, example: '2026-09-08T21:01:21Z',
+        description: 'When the vendor is destroyed if nothing is deposited. Exact — unlike a house\'s collapse, there is no randomness in it.' },
+      // **The int an operator narrows with**, because `conditions.js` compares a
+      // declared variable against a LITERAL and has no relative-time operator:
+      // "within 24 hours of dismissal" is not expressible as `dismissalAt < now +
+      // 24h`. So the hours are computed at emit and the operator writes
+      // `hoursRemaining is at most 24`. The mapper additionally fires only on a
+      // threshold CROSSING, because `vendor.listing` is a sweep frame re-emitted
+      // on any price change.
+      { name: 'hoursRemaining', type: 'int', required: true, example: 22,
+        description: 'Whole hours until dismissal at the moment this fired. The value to write a rule condition against.' },
+      { name: 'periodsRemaining', type: 'int', required: false, example: 1,
+        description: 'Pay ticks the vendor survives. NOT days — under the old vendor system a period is one UO day (~2 real hours).' },
+      { name: 'funds', type: 'int', required: false, example: 8204,
+        description: 'Gold available to pay the fees.' },
+      { name: 'chargePerPeriod', type: 'int', required: false, example: 10548,
+        description: 'What each tick deducts.' },
+      { name: 'location', type: 'string', required: false, example: 'Trammel 1421, 1699 (Britain)',
+        description: 'Where the shop stands, already formatted for reading.' },
+      { name: 'marketUrl', type: 'url', required: false, example: '/shard/market',
+        description: 'Site-relative path to the market page.' },
+    ],
+  },
+]
+
+// ── Passive income ─────────────────────────────────────────────────────────
+
+const PASSIVE_INCOME = [
+  {
+    id: 'uo.vendor.sale',
+    label: 'Your vendor sold something',
+    // **The tier caveat belongs in the operator-facing text, not only in a
+    // comment.** `vendor.sale` is emitted by a `PlayerVendorSale` EventSink that
+    // lives in `servuo-plugins/patches/` — the opt-in patch tier — and is verified
+    // only against ServUO 57.4. A shard that declined the tier emits this kind
+    // never, so a rule on it is silently dormant rather than broken, and the only
+    // way an operator finds out is if something says so where they are looking.
+    description:
+      'One of your player vendors made a sale. Requires the optional ServUO patch tier — a shard that '
+      + 'declined it never emits this event, and a rule on it stays silent.',
+    kind: 'event',
+    subjectKey: 'vendorSerial',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'vendorSerial', type: 'string', required: true, example: '0x2E1',
+        description: 'The vendor that made the sale. Also the cooldown subject.' },
+      { name: 'itemName', type: 'string', required: true, example: 'Longsword',
+        description: 'What was sold.' },
+      { name: 'amount', type: 'int', required: false, example: 1,
+        description: 'How many.' },
+      { name: 'price', type: 'int', required: true, example: 100,
+        description: 'What it sold for, in gold.' },
+      { name: 'commission', type: 'int', required: false, example: 0,
+        description: 'Commission taken, on a commission vendor.' },
+    ],
+  },
+]
+
+// ── Personal security ──────────────────────────────────────────────────────
+
+const PERSONAL_SECURITY = [
+  {
+    id: 'uo.account.login_failed',
+    label: 'A failed login to your game account',
+    description: 'Someone tried to log into your game account and was refused.',
+    kind: 'event',
+    // The account, so a burst of attempts against one account is one mail and
+    // attempts against two accounts are two.
+    subjectKey: 'account',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'account', type: 'string', required: true, example: 'seed_000',
+        description: 'The game account that was tried. Also the cooldown subject.' },
+      { name: 'reason', type: 'string', required: false, example: 'BadPass',
+        description: 'The shard\'s refusal reason: BadPass, Invalid, Blocked, InUse or BadComm.' },
+      { name: 'ip', type: 'string', required: false, example: '203.0.113.9',
+        description: 'Where the attempt came from.' },
+    ],
+  },
+  {
+    id: 'uo.account.unlinked',
+    label: 'Your game account was unlinked',
+    description: 'Someone severed the tie between this game account and your website account, from in game.',
+    kind: 'event',
+    subjectKey: 'account',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'account', type: 'string', required: true, example: 'seed_000',
+        description: 'The game account that was unlinked. Also the cooldown subject.' },
+      { name: 'characterName', type: 'string', required: false, example: 'Zara Crowe',
+        description: 'The character who ran the command.' },
+    ],
+  },
+]
+
+// ── Personal milestone ─────────────────────────────────────────────────────
+//
+// The two death triggers are a killfeed some players want and most do not.
+// Every rule ships disabled anyway (Q3), and 11b's seeded rules for these two
+// additionally default their channels `off` rather than relying on the rule
+// switch alone.
+
+const PERSONAL_MILESTONE = [
+  {
+    id: 'uo.skill.capped',
+    label: 'You capped a skill',
+    description: 'One of your characters reached the cap in a skill.',
+    kind: 'event',
+    subjectKey: 'skill',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'characterName', type: 'string', required: true, example: 'Zara Crowe',
+        description: 'The character who capped it.' },
+      { name: 'skill', type: 'string', required: true, example: 'Blacksmithy',
+        description: 'The skill. Also the cooldown subject — capping two skills is two events.' },
+      { name: 'cap', type: 'float', required: true, example: 100,
+        description: 'The cap that was reached.' },
+    ],
+  },
+  {
+    id: 'uo.quest.complete',
+    label: 'You completed a quest',
+    description: 'One of your characters finished a quest.',
+    kind: 'event',
+    subjectKey: 'quest',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'characterName', type: 'string', required: true, example: 'Zara Crowe',
+        description: 'The character who finished it.' },
+      { name: 'quest', type: 'string', required: true, example: 'The Ancient Tome',
+        description: 'The quest. Also the cooldown subject.' },
+    ],
+  },
+  {
+    id: 'uo.character.death',
+    label: 'Your character died',
+    description: 'One of your characters was killed. Opt-in — most players do not want this.',
+    kind: 'event',
+    subjectKey: 'characterName',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'characterName', type: 'string', required: true, example: 'Zara Crowe',
+        description: 'Who died. Also the cooldown subject.' },
+      { name: 'killerName', type: 'string', required: false, example: 'an ogre lord',
+        description: 'What killed them, when the shard names it.' },
+    ],
+  },
+  {
+    id: 'uo.character.murdered',
+    label: 'Your character was murdered',
+    description: 'One of your characters was killed by another player. Opt-in — most players do not want this.',
+    kind: 'event',
+    subjectKey: 'characterName',
+    audience: 'owner',
+    ceiling: 'owner',
+    version: V1,
+    variables: [
+      { name: 'characterName', type: 'string', required: true, example: 'Zara Crowe',
+        description: 'Who was murdered. Also the cooldown subject.' },
+      { name: 'murdererName', type: 'string', required: false, example: 'Darrow',
+        description: 'Who did it, when the shard names them.' },
+    ],
+  },
+]
+
+// ── Social / civic ─────────────────────────────────────────────────────────
+//
+// The two guild triggers ceiling at `members` and resolve through the recipient
+// set the emit carries, not through a saved segment: "the members of THIS guild"
+// is a different answer for every firing, which a segment's constant params
+// cannot express. That is Phase 6's decision 2, and the Team fan-out is the
+// precedent it was built for.
+
+const SOCIAL_CIVIC = [
+  {
+    id: 'uo.guild.left',
+    label: 'A member left your guild',
+    description: 'Someone left a guild you are in.',
+    kind: 'event',
+    subjectKey: 'guildName',
+    audience: 'members',
+    ceiling: 'members',
+    version: V1,
+    variables: [
+      { name: 'guildName', type: 'string', required: true, example: 'The Silver Hand',
+        description: 'The guild. Also the cooldown subject.' },
+      // `guild.leave`'s `who` is a bare SERIAL string, not an actor object — the
+      // mobile has already left, so the shard has nothing to attribute. The name
+      // comes from this module's own roster mirror (`shard_guild_members`), and
+      // is optional because a member the sweep never saw has no row there.
+      { name: 'memberName', type: 'string', required: false, example: 'Bran',
+        description: 'Who left, when the roster mirror still knows their name.' },
+      { name: 'guildUrl', type: 'url', required: false, example: '/shard/guilds',
+        description: 'Site-relative path to the guilds page.' },
+    ],
+  },
+  {
+    id: 'uo.guild.disbanded',
+    label: 'Your guild disbanded',
+    description: 'A guild you are in was disbanded or removed.',
+    kind: 'event',
+    subjectKey: 'guildName',
+    audience: 'members',
+    ceiling: 'members',
+    version: V1,
+    variables: [
+      { name: 'guildName', type: 'string', required: true, example: 'The Silver Hand',
+        description: 'The guild that is gone. Also the cooldown subject.' },
+      { name: 'abbreviation', type: 'string', required: false, example: 'TSH',
+        description: 'Its abbreviation.' },
+    ],
+  },
+  {
+    id: 'uo.governor.elected',
+    label: 'A town elected a governor',
+    description: 'A city has a new governor.',
+    kind: 'event',
+    subjectKey: 'city',
+    audience: 'subscribers',
+    ceiling: 'authenticated',
+    version: V1,
+    variables: [
+      { name: 'city', type: 'string', required: true, example: 'Britain',
+        description: 'The city. Also the cooldown subject.' },
+      { name: 'governorName', type: 'string', required: true, example: 'Darrow',
+        description: 'The new governor.' },
+      { name: 'previousGovernorName', type: 'string', required: false, example: 'Mireille',
+        description: 'Who held the seat before, when there was someone.' },
+      { name: 'governorsUrl', type: 'url', required: false, example: '/shard/governors',
+        description: 'Site-relative path to the governors page.' },
+    ],
+  },
+  {
+    id: 'uo.election.opened',
+    label: 'Voting opened in a town',
+    // **The first trigger whose call to action genuinely expires**, which is why
+    // `autoPickAt` is required rather than decorative: a mail saying "vote" with
+    // no deadline is a mail nobody acts on, and one delivered after the deadline
+    // is worse than none. 11b's template says the date, and the seeded rule uses
+    // no delay for the same reason.
+    description: 'A city\'s election entered its nomination or voting phase, with a deadline.',
+    kind: 'event',
+    subjectKey: 'city',
+    audience: 'subscribers',
+    ceiling: 'authenticated',
+    version: V1,
+    variables: [
+      { name: 'city', type: 'string', required: true, example: 'Britain',
+        description: 'The city. Also the cooldown subject.' },
+      { name: 'phase', type: 'string', required: true, example: 'vote',
+        description: 'Which phase opened: nominate or vote.' },
+      { name: 'autoPickAt', type: 'datetime', required: true, example: '2026-09-04T00:00:00Z',
+        description: 'When the game decides for itself — the real deadline.' },
+      { name: 'candidates', type: 'int', required: false, example: 3,
+        description: 'How many candidates stand.' },
+      { name: 'governorsUrl', type: 'url', required: false, example: '/shard/governors',
+        description: 'Site-relative path to the governors page.' },
+    ],
+  },
+]
+
+// ── Come online now ────────────────────────────────────────────────────────
+
+const COME_ONLINE = [
+  {
+    id: 'uo.champ.started',
+    label: 'A champion spawn started',
+    description: 'A champion spawn became active.',
+    kind: 'event',
+    subjectKey: 'spawnSerial',
+    audience: 'subscribers',
+    ceiling: 'authenticated',
+    version: V1,
+    variables: [
+      { name: 'spawnSerial', type: 'string', required: true, example: '0x40012345',
+        description: 'The spawn controller. Also the cooldown subject.' },
+      { name: 'spawnName', type: 'string', required: true, example: 'Abyss',
+        description: 'What is spawning.' },
+      { name: 'category', type: 'string', required: false, example: 'champion',
+        description: 'champion, mini or sea.' },
+      { name: 'location', type: 'string', required: false, example: 'Felucca 5187, 570',
+        description: 'Where, already formatted for reading.' },
+      { name: 'champsUrl', type: 'url', required: false, example: '/shard/champs',
+        description: 'Site-relative path to the champions page.' },
+    ],
+  },
+  {
+    id: 'uo.champ.boss_up',
+    label: 'A champion boss is up',
+    description: 'A champion spawn reached its boss.',
+    kind: 'event',
+    subjectKey: 'spawnSerial',
+    audience: 'subscribers',
+    ceiling: 'authenticated',
+    version: V1,
+    variables: [
+      { name: 'spawnSerial', type: 'string', required: true, example: '0x40012345',
+        description: 'The spawn controller. Also the cooldown subject.' },
+      { name: 'spawnName', type: 'string', required: true, example: 'Abyss',
+        description: 'The spawn.' },
+      { name: 'bossName', type: 'string', required: false, example: 'Semidar',
+        description: 'The boss, when the shard names it.' },
+      { name: 'location', type: 'string', required: false, example: 'Felucca 5187, 570',
+        description: 'Where, already formatted for reading.' },
+      { name: 'champsUrl', type: 'url', required: false, example: '/shard/champs',
+        description: 'Site-relative path to the champions page.' },
+    ],
+  },
+  {
+    id: 'uo.server.up',
+    label: 'The shard came online',
+    description: 'The game server started or came back after an outage.',
+    kind: 'event',
+    // **No `subjectKey`, and that is the whole point of this pair.** There is one
+    // shard, so the subject a cooldown counts is the RECIPIENT — "do not tell me
+    // the shard bounced more than once an hour". Keying it on a boot id would make
+    // every restart a new subject and every cooldown a no-op, which is precisely
+    // the mail loop §8.6 warns a flapping shard produces. 11b's seeded rules carry
+    // a hard cooldown; this declaration is what makes that cooldown mean anything.
+    audience: 'subscribers',
+    ceiling: 'authenticated',
+    version: V1,
+    variables: [
+      { name: 'shardName', type: 'string', required: false, example: 'UOMysticmoon',
+        description: 'What the shard calls itself.' },
+      { name: 'statusUrl', type: 'url', required: false, example: '/shard',
+        description: 'Site-relative path to the shard status page.' },
+    ],
+  },
+  {
+    id: 'uo.server.down',
+    label: 'The shard went offline',
+    description: 'The game server shut down or crashed.',
+    kind: 'event',
+    audience: 'subscribers',
+    ceiling: 'authenticated',
+    version: V1,
+    variables: [
+      { name: 'shardName', type: 'string', required: false, example: 'UOMysticmoon',
+        description: 'What the shard calls itself.' },
+      { name: 'clean', type: 'boolean', required: false, example: true,
+        description: 'Whether it was a clean shutdown rather than a crash.' },
+      { name: 'statusUrl', type: 'url', required: false, example: '/shard',
+        description: 'Site-relative path to the shard status page.' },
+    ],
+  },
+]
+
+// ── Leaderboard ────────────────────────────────────────────────────────────
+
+const LEADERBOARD = [
+  {
+    id: 'uo.points.rank_changed',
+    label: 'A leaderboard top spot changed',
+    // §8.6 originally described this firing both ways — "you entered a top N" and
+    // "you were pushed out". The personal half is carved out: `points.board`'s
+    // `top[]` entries are `{rank, serial, name, points}` and `shard_account_links`
+    // is keyed by game ACCOUNT, so a serial resolves to a person only for someone
+    // currently online (`shard_online`) or in a guild (`shard_guild_members`). A
+    // leaderboard mail that reaches half the board reads as favouritism, so the
+    // board feed ships and the personal one waits for a serial→account map.
+    description: 'The top of a leaderboard changed hands.',
+    kind: 'event',
+    subjectKey: 'system',
+    audience: 'subscribers',
+    ceiling: 'authenticated',
+    version: V1,
+    variables: [
+      { name: 'system', type: 'string', required: true, example: 'QueensLoyalty',
+        description: 'The points system. Also the cooldown subject.' },
+      { name: 'systemName', type: 'string', required: false, example: 'Queen\'s Loyalty',
+        description: 'Its display name, when the shard gives one.' },
+      { name: 'leaderName', type: 'string', required: true, example: 'Darrow',
+        description: 'Who is first now.' },
+      { name: 'previousLeaderName', type: 'string', required: false, example: 'Mireille',
+        description: 'Who was first before.' },
+      { name: 'points', type: 'int', required: false, example: 29500,
+        description: 'The new leader\'s points.' },
+    ],
+  },
+]
+
+// ── Staff-facing ───────────────────────────────────────────────────────────
+//
+// These are why the ceiling exists. Phase 3 already filters a role-ceilinged
+// trigger out of a player's preferences catalogue AND gates it on write, so this
+// family is the production proof of that work rather than new mechanism.
+
+const STAFF_FACING = [
+  {
+    id: 'uo.page.new',
+    label: 'A player opened a help page',
+    description: 'A player raised a support ticket in game.',
+    kind: 'event',
+    subjectKey: 'pageType',
+    audience: 'staff',
+    ceiling: 'staff',
+    version: V1,
+    variables: [
+      { name: 'pageType', type: 'string', required: true, example: 'Stuck',
+        description: 'Bug, Stuck, Account, Question, Suggestion, Other, VerbalHarassment or PhysicalHarassment. Also the cooldown subject.' },
+      { name: 'senderName', type: 'string', required: false, example: 'Zara Crowe',
+        description: 'Who raised it.' },
+      { name: 'message', type: 'string', required: false, example: 'I am stuck under the Britain bank.',
+        description: 'What they wrote.' },
+      { name: 'location', type: 'string', required: false, example: 'Trammel 1421, 1699',
+        description: 'Where they are, already formatted for reading.' },
+      { name: 'pagesUrl', type: 'url', required: false, example: '/admin/shard',
+        description: 'Site-relative path to the help-page queue.' },
+    ],
+  },
+  {
+    id: 'uo.cheat.detected',
+    label: 'The cheat detector fired',
+    description: 'The shard\'s own speed-hack detector flagged a player.',
+    kind: 'event',
+    // **`staff`, and never `owner`.** This is the declaration the whole lattice
+    // was written for: under a flat "fewer people is narrower" ordering a
+    // `staff` ceiling would also permit `owner`, and the rule an operator would
+    // then be able to save mails the cheat report to the player who was detected.
+    subjectKey: 'characterName',
+    audience: 'staff',
+    ceiling: 'staff',
+    version: V1,
+    variables: [
+      { name: 'characterName', type: 'string', required: true, example: 'Zara Crowe',
+        description: 'Who was flagged. Also the cooldown subject.' },
+      { name: 'account', type: 'string', required: false, example: 'seed_000',
+        description: 'Their game account.' },
+      { name: 'ip', type: 'string', required: false, example: '203.0.113.9',
+        description: 'Where they were connected from.' },
+      { name: 'detector', type: 'string', required: false, example: 'fastwalk',
+        description: 'Which detector fired.' },
+    ],
+  },
+]
+
+// ── Operator-facing ────────────────────────────────────────────────────────
+//
+// `admin`, the ceiling Phase 11 added to the lattice (decision 1). The narrowest
+// value before it was `staff` — admin, editor AND moderator — so ceilinging a
+// digest of what moderators did at `staff` would have sent it to the moderators.
+// All three are digest-shaped by nature; none should ever be instant, which is a
+// property of 11b's seeded rules rather than of these declarations.
+
+const OPERATOR_FACING = [
+  {
+    id: 'uo.audit.staff_action',
+    label: 'A staff member acted in game',
+    description: 'A staff command, a property change, or a moderation action.',
+    kind: 'event',
+    subjectKey: 'staffName',
+    audience: 'admin',
+    ceiling: 'admin',
+    version: V1,
+    variables: [
+      { name: 'staffName', type: 'string', required: false, example: 'Mireille',
+        description: 'Who acted. Absent when the shard cannot attribute it. Also the cooldown subject.' },
+      { name: 'action', type: 'string', required: true, example: 'set',
+        description: 'What kind of action: set, command, ban, kick, mute…' },
+      { name: 'detail', type: 'string', required: false, example: 'Str 100 → 125 on Zara Crowe',
+        description: 'The action in one line, already formatted for reading.' },
+      { name: 'target', type: 'string', required: false, example: 'Zara Crowe',
+        description: 'Who or what it was applied to.' },
+      { name: 'origin', type: 'string', required: false, example: 'in-game',
+        description: 'web or in-game — where the action was issued from.' },
+    ],
+  },
+  {
+    id: 'uo.economy.milestone',
+    label: 'The economy crossed a threshold',
+    description: 'The shard\'s total gold supply or account count crossed one of the module\'s reporting thresholds.',
+    kind: 'event',
+    subjectKey: 'metric',
+    audience: 'admin',
+    ceiling: 'admin',
+    version: V1,
+    variables: [
+      { name: 'metric', type: 'string', required: true, example: 'gold',
+        description: 'gold or accounts. Also the cooldown subject.' },
+      { name: 'value', type: 'int', required: true, example: 1000000000,
+        description: 'The value that crossed.' },
+      { name: 'threshold', type: 'int', required: true, example: 1000000000,
+        description: 'The threshold it crossed.' },
+      { name: 'direction', type: 'string', required: true, example: 'up',
+        description: 'up or down.' },
+      { name: 'economyUrl', type: 'url', required: false, example: '/shard',
+        description: 'Site-relative path to the shard status page.' },
+    ],
+  },
+  {
+    id: 'uo.world.saved',
+    label: 'The world saved',
+    description: 'A world save completed, with the item and mobile counts it wrote.',
+    kind: 'event',
+    audience: 'admin',
+    ceiling: 'admin',
+    version: V1,
+    variables: [
+      { name: 'items', type: 'int', required: false, example: 1482301,
+        description: 'Items written.' },
+      { name: 'mobiles', type: 'int', required: false, example: 41022,
+        description: 'Mobiles written.' },
+    ],
+  },
+]
+
+const TRIGGERS = [
+  ...OWNED_ASSET,
+  ...PASSIVE_INCOME,
+  ...PERSONAL_SECURITY,
+  ...PERSONAL_MILESTONE,
+  ...SOCIAL_CIVIC,
+  ...COME_ONLINE,
+  ...LEADERBOARD,
+  ...STAFF_FACING,
+  ...OPERATOR_FACING,
+]
+
+// The ids, as a Set, for the mapper's own guard: `shardEngagement.js` refuses to
+// emit an id this file does not declare, so a typo there is a boot-time-visible
+// mistake rather than a dropped event nobody notices.
+const TRIGGER_IDS = new Set(TRIGGERS.map((t) => t.id))
+
+module.exports = {
+  TRIGGERS,
+  TRIGGER_IDS,
+  OWNED_ASSET,
+  PASSIVE_INCOME,
+  PERSONAL_SECURITY,
+  PERSONAL_MILESTONE,
+  SOCIAL_CIVIC,
+  COME_ONLINE,
+  LEADERBOARD,
+  STAFF_FACING,
+  OPERATOR_FACING,
+}

server/core.js

@@ -93,6 +93,19 @@ module.exports = {
   },
   auth: { getUserFromRequest: (...args) => need().auth.getUserFromRequest(...args) },
   push: { publish: (...args) => need().push.publish(...args) },
+
+  // The engagement seam (MODULE_API 1.7.0, ENGAGEMENT.md §5.1). `emit` says an
+  // event this module DECLARED has happened; the engine decides whether anyone is
+  // told, on which channel, subject to which rule and preference. `inbox.push`
+  // writes an in-app item with no rule at all, for the cases that are not events.
+  //
+  // Both are fire-and-forget and return undefined by contract — a module calls
+  // them from inside a game-event handler and there is nothing it could correctly
+  // do with a storage failure of core's. `inbox.push` additionally does not report
+  // "the user has this switched off", because a module that could see that would
+  // be a module that could enumerate people's preferences one write at a time.
+  events: { emit: (...args) => need().events.emit(...args) },
+  inbox: { push: (...args) => need().inbox.push(...args) },
   secretBox: {
     encrypt: (...args) => need().secretBox.encrypt(...args),
     decrypt: (...args) => need().secretBox.decrypt(...args),

server/db/schema.sql

@@ -47,7 +47,7 @@ CREATE TABLE IF NOT EXISTS uo_link_config (
   base_url          VARCHAR(255) NULL,
   ws_url            VARCHAR(255) NULL,
   auth_token_enc    TEXT         NULL,
-  protocol          INT          NOT NULL DEFAULT 4,
+  protocol          INT          NOT NULL DEFAULT 5,
   enabled           TINYINT(1)   NOT NULL DEFAULT 0,
   status            VARCHAR(20)  NOT NULL DEFAULT 'disconnected',
   status_detail     VARCHAR(500) NULL,
@@ -727,3 +727,62 @@ ALTER TABLE shard_guild_members ADD COLUMN IF NOT EXISTS `rank` TINYINT NULL;
 ALTER TABLE shard_guild_members ADD COLUMN IF NOT EXISTS rank_cliloc INT NULL;
 ALTER TABLE shard_guild_members ADD COLUMN IF NOT EXISTS rank_name VARCHAR(64) NULL;
 ALTER TABLE shard_guild_members ADD INDEX IF NOT EXISTS idx_shard_guild_members_rank (guild_id, `rank`);
+
+-- ── Protocol 5 ───────────────────────────────────────────────────────────────
+--
+-- Three wire enrichments, bumped together (link/sidecar/src/main.rs, overlay.toml).
+-- Two of them land as columns here; the third is a new event kind and needs none.
+--
+-- 1. house.decay's decay SCHEDULE. `shard_houses` could say what stage a house was
+--    at and when it was last refreshed, but nothing about WHEN the next thing
+--    happens — which is the only part a player can act on. `estimated_collapse` is
+--    nullable and stays null far more often than not, deliberately: under dynamic
+--    decay (Core.ML) ServUO draws each stage's duration at random when the stage is
+--    entered, so collapse is exactly knowable only once the house is already at
+--    IDOC. A null here means "not knowable", never "not yet read".
+ALTER TABLE shard_houses ADD COLUMN IF NOT EXISTS next_stage DATETIME NULL;
+ALTER TABLE shard_houses ADD COLUMN IF NOT EXISTS estimated_collapse DATETIME NULL;
+ALTER TABLE shard_houses ADD COLUMN IF NOT EXISTS decay_period_sec INT NULL;
+ALTER TABLE shard_houses ADD COLUMN IF NOT EXISTS dynamic_decay TINYINT(1) NULL;
+
+-- 2. vendor.listing's owner account and fee state.
+--
+--    `owner_acct` is the one that matters structurally: the table has carried
+--    `owner_name` since Protocol 3, but a character name is not an identity — only
+--    the game ACCOUNT joins to shard_account_links, so until now a vendor row named
+--    an owner the site could not resolve to a user.
+--
+--    The fee columns describe PlayerVendor.PayTimer's dismissal rule: at each tick
+--    the charge is compared with the funds and the vendor is destroyed when the
+--    charge wins. `dismissal_at` is that comparison resolved into an instant, which
+--    is what any surface actually wants; the parts are kept alongside it so a
+--    display can explain the number rather than only state it.
+--
+--    `fees_exempt` marks a commission vendor: it has no pay timer at all and is
+--    never dismissed for fees, which is a different thing from having a long time
+--    left and must not render as one.
+ALTER TABLE shard_vendors ADD COLUMN IF NOT EXISTS owner_acct VARCHAR(120) NULL;
+ALTER TABLE shard_vendors ADD COLUMN IF NOT EXISTS fees_exempt TINYINT(1) NOT NULL DEFAULT 0;
+ALTER TABLE shard_vendors ADD COLUMN IF NOT EXISTS charge_per_period INT NULL;
+ALTER TABLE shard_vendors ADD COLUMN IF NOT EXISTS funds INT NULL;
+ALTER TABLE shard_vendors ADD COLUMN IF NOT EXISTS pay_interval_sec INT NULL;
+ALTER TABLE shard_vendors ADD COLUMN IF NOT EXISTS next_pay_at DATETIME NULL;
+ALTER TABLE shard_vendors ADD COLUMN IF NOT EXISTS periods_remaining INT NULL;
+ALTER TABLE shard_vendors ADD COLUMN IF NOT EXISTS dismissal_at DATETIME NULL;
+-- Both of these exist for the same reader: the Phase 11 trigger that has to find
+-- "vendors about to be dismissed" without scanning every shop, and the owner join
+-- that turns one into a person.
+ALTER TABLE shard_vendors ADD INDEX IF NOT EXISTS idx_shard_vendors_dismissal (dismissal_at);
+ALTER TABLE shard_vendors ADD INDEX IF NOT EXISTS idx_shard_vendors_owner_acct (owner_acct);
+
+-- 3. The protocol pin, one step on from the Protocol 4 block above and for exactly
+--    the reasons it spells out. `protocol < 5` rather than `= 4`, so an install that
+--    missed an earlier migration is carried the whole way; the one-shot marker is
+--    written here in the module's own fragment, because core's schema is replayed in
+--    full BEFORE any module fragment and a marker left in core would already exist
+--    when this UPDATE read it.
+ALTER TABLE uo_link_config MODIFY COLUMN protocol INT NOT NULL DEFAULT 5;
+UPDATE uo_link_config SET protocol = 5
+  WHERE id = 1 AND protocol < 5
+    AND NOT EXISTS (SELECT 1 FROM settings WHERE `key` = 'uo_link_protocol_5_migrated');
+INSERT IGNORE INTO settings (`key`, value) VALUES ('uo_link_protocol_5_migrated', '1');

server/index.js

@@ -44,6 +44,8 @@ module.exports = function register(ctx, api) {
   const usersShardExtension = require('./router/admin/usersShard.router')
 
   const shardStreams = require('./config/shardStreams')
+  const shardTriggers = require('./config/shardTriggers')
+  const shardAudiences = require('./config/shardAudiences')
   const townCrierLeg = require('./utils/shardAnnounce')
   const teamProvider = require('./model/teamProvider/teamProvider.model')
   const guildCommand = require('./commands/guild.command')
@@ -88,6 +90,31 @@ module.exports = function register(ctx, api) {
   api.registerNotificationStreams(shardStreams.STREAMS)
   api.registerAnnounceLeg(townCrierLeg.leg)
 
+  // The engagement contract (MODULE_API 1.7.0, ENGAGEMENT.md Phase 11). Triggers
+  // are PAYLOAD contracts: what a rule may fire on, what a template may
+  // interpolate, and — the part that is a security boundary — the widest audience
+  // an operator may ever give each one. `uo.cheat.detected` ceilings at `staff`
+  // and the three operator-facing ones at `admin` (added to the lattice in 1.8.0),
+  // and core refuses a rule that widens either.
+  //
+  // **Triggers and notification streams share ONE id namespace** (§7.2), so this
+  // registration and the one above are two facets of one space and core enforces
+  // that an id has exactly one owner across both. None of the ids below reuses a
+  // stream id: the stream catalog keeps its seven grandfathered names and these
+  // are the `uo.*`-prefixed ones §8.6 specifies. A trigger-only id gets email and
+  // in-app preferences and no push toggle, which is correct — there is nothing to
+  // push it to, and the shipped Android client's catalog is unchanged.
+  api.registerEventTriggers(shardTriggers.TRIGGERS)
+
+  // Audiences are named sets of PEOPLE an operator composes rules and segments
+  // out of (§5.1a). Their own id space, and their own ceiling arithmetic: a
+  // composition takes the narrowest ceiling it contains, never the widest.
+  //
+  // Registration is a claim; nothing resolves until the engine asks, which is
+  // after `onBoot` — and it must be, because every resolver reads the database
+  // and registration must not (§2.2 rule 1).
+  api.registerAudiences(shardAudiences.AUDIENCES)
+
   // Teams: a UO guild is a Team, and this module is the authoritative source of
   // them for this deployment (MODULE_API 1.6.0). Core asks the three questions;
   // everything about what a guild IS stays here.
@@ -114,5 +141,7 @@ module.exports = function register(ctx, api) {
     version: require('../module.json').version,
     routes: 'public:/shard,/atlas admin:/shard,/uo-link player:/shard',
     streams: shardStreams.STREAMS.length,
+    triggers: shardTriggers.TRIGGERS.length,
+    audiences: shardAudiences.AUDIENCES.length,
   })
 }

server/model/shardLinks/shardLinks.db.js

@@ -39,4 +39,56 @@ const remove = (account, userId) =>
 const removeByAccount = (account) =>
   query('DELETE FROM shard_account_links WHERE account = ?', [account])
 
-module.exports = { upsert, getByAccount, listByUser, isOwnedBy, remove, removeByAccount }
+
+// A bound on every "resolve a set of people" read below. It mirrors core's own
+// `MAX_AUDIENCE` (engagementRecipients.db.js) rather than importing it: a module
+// cannot reach into core's models, and the number this file has to respect is
+// "no more ids than core will accept" whatever core calls it.
+const MAX_AUDIENCE = 5000
+
+// **Website user ids for a set of game accounts.** The bulk form of
+// `getByAccount`, and the one the engagement mapper needs: a guild event's
+// audience is its members, and turning a roster into a set of people is one join
+// rather than one query per member (Phase 11).
+//
+// DISTINCT because two characters on one guild roster can share an account, and
+// the caller wants people rather than characters.
+async function userIdsForAccounts(accounts) {
+  const wanted = [...new Set((accounts || []).filter((a) => typeof a === 'string' && a))]
+  if (!wanted.length) return []
+  const capped = wanted.slice(0, MAX_AUDIENCE)
+  const marks = capped.map(() => '?').join(', ')
+  const rows = await query(
+    `SELECT DISTINCT user_id FROM shard_account_links WHERE account IN (${marks})`,
+    capped,
+  )
+  return rows.map((r) => Number(r.user_id)).filter((n) => Number.isInteger(n) && n > 0)
+}
+
+// **Every website user with a linked game account** — the `uo.linked.accounts`
+// audience (ENGAGEMENT.md §5.1a). The set an operator reaches for first, and the
+// one a `not` composes against ("everyone who has NOT linked").
+//
+// It returns ids and nothing else: §5.1a rule 2 is that a module's resolver
+// never sees an address, a channel or a template, and core maps ids to addresses
+// on its own side after preferences, suppression and the verification gate.
+async function allLinkedUserIds(limit = MAX_AUDIENCE) {
+  const rows = await query(
+    'SELECT DISTINCT user_id FROM shard_account_links ORDER BY user_id LIMIT ?',
+    [limit],
+  )
+  return rows.map((r) => Number(r.user_id)).filter((n) => Number.isInteger(n) && n > 0)
+}
+
+module.exports = {
+  upsert,
+  getByAccount,
+  listByUser,
+  isOwnedBy,
+  remove,
+  removeByAccount,
+  userIdsForAccounts,
+  allLinkedUserIds,
+  MAX_AUDIENCE,
+}
+

server/model/shardLinks/shardLinks.model.js

@@ -34,4 +34,20 @@ const unlink = (account, userId) => db.remove(account, userId)
 // Drop the local mirror for an account (source-of-truth severed elsewhere).
 const removeByAccount = (account) => db.removeByAccount(account)
 
-module.exports = { link, listForUser, ownsAccount, getByAccount, unlink, removeByAccount }
+// The bulk resolvers the engagement audiences and the guild mapper need
+// (Phase 11). Thin pass-throughs, like `ownsAccount` above: there is no logic to
+// put here, and a module's audience resolver returning ids and nothing else is
+// the contract (§5.1a rule 2).
+const userIdsForAccounts = (accounts) => db.userIdsForAccounts(accounts)
+const allLinkedUserIds = (limit) => db.allLinkedUserIds(limit)
+
+module.exports = {
+  link,
+  listForUser,
+  ownsAccount,
+  getByAccount,
+  unlink,
+  removeByAccount,
+  userIdsForAccounts,
+  allLinkedUserIds,
+}

server/model/shardMarket/shardMarket.db.js

@@ -41,14 +41,25 @@ async function replaceVendor(vendor, items) {
 
     await conn.query(
       `INSERT INTO shard_vendors
-         (serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house,
-          item_count, item_total, truncated, t)
-       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+         (serial, shop_name, owner_serial, owner_name, owner_acct, map, x, y, z, region, house,
+          item_count, item_total, truncated, t,
+          fees_exempt, charge_per_period, funds, pay_interval_sec, next_pay_at,
+          periods_remaining, dismissal_at)
+       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
        ON DUPLICATE KEY UPDATE shop_name = VALUES(shop_name), owner_serial = VALUES(owner_serial),
-         owner_name = VALUES(owner_name), map = VALUES(map), x = VALUES(x), y = VALUES(y),
+         owner_name = VALUES(owner_name), owner_acct = VALUES(owner_acct),
+         map = VALUES(map), x = VALUES(x), y = VALUES(y),
          z = VALUES(z), region = VALUES(region), house = VALUES(house),
          item_count = VALUES(item_count), item_total = VALUES(item_total),
          truncated = VALUES(truncated), t = VALUES(t),
+         -- Protocol 5. Written back unconditionally, INCLUDING when they are null:
+         -- a shard downgraded to a pre-v5 overlay stops sending the fees object, and
+         -- leaving the last v5 values in place would leave a dismissal date standing
+         -- that nothing is maintaining any more. A stale deadline is worse than none.
+         fees_exempt = VALUES(fees_exempt), charge_per_period = VALUES(charge_per_period),
+         funds = VALUES(funds), pay_interval_sec = VALUES(pay_interval_sec),
+         next_pay_at = VALUES(next_pay_at), periods_remaining = VALUES(periods_remaining),
+         dismissal_at = VALUES(dismissal_at),
          -- Touched explicitly rather than left to ON UPDATE CURRENT_TIMESTAMP:
          -- MariaDB does not fire that when every column is written back
          -- unchanged, and a shop that is re-published identically is still
@@ -60,6 +71,7 @@ async function replaceVendor(vendor, items) {
         vendor.shopName ?? null,
         vendor.ownerSerial ?? null,
         vendor.ownerName ?? null,
+        vendor.ownerAcct ?? null,
         vendor.map ?? null,
         Number.isFinite(vendor.x) ? vendor.x : null,
         Number.isFinite(vendor.y) ? vendor.y : null,
@@ -70,6 +82,13 @@ async function replaceVendor(vendor, items) {
         Number.isFinite(vendor.itemTotal) ? vendor.itemTotal : items.length,
         vendor.truncated ? 1 : 0,
         Number.isFinite(vendor.t) ? vendor.t : null,
+        vendor.feesExempt ? 1 : 0,
+        Number.isFinite(vendor.chargePerPeriod) ? vendor.chargePerPeriod : null,
+        Number.isFinite(vendor.funds) ? vendor.funds : null,
+        Number.isFinite(vendor.payIntervalSec) ? vendor.payIntervalSec : null,
+        vendor.nextPayAt ?? null,
+        Number.isFinite(vendor.periodsRemaining) ? vendor.periodsRemaining : null,
+        vendor.dismissalAt ?? null,
       ],
     )
 

server/model/shardMarket/shardMarket.model.js

@@ -31,6 +31,7 @@ const MAX_OWNER = 64
 const MAX_MAP = 40
 const MAX_REGION = 80
 const MAX_SERIAL = 20
+const MAX_ACCT = 120
 
 const clip = (value, max) => {
   if (value == null) return null
@@ -43,6 +44,42 @@ const int = (value, fallback = 0) => {
   return Number.isFinite(n) ? Math.trunc(n) : fallback
 }
 
+// A wire timestamp -> a Date the DB layer can bind, or null. The shard emits ISO-8601
+// (`DateTime.ToString("o")`); anything else is a plugin we do not recognise and is
+// dropped rather than stored as an Invalid Date, which MariaDB rejects in strict mode
+// and which would fail the whole vendor over one bad field.
+const when = (value) => {
+  if (!value) return null
+  const d = new Date(value)
+  return Number.isNaN(d.getTime()) ? null : d
+}
+
+// Protocol 5. The vendor's fee state, normalised out of the frame's `fees` object.
+//
+// Two things this deliberately does NOT do. It does not recompute `dismissalAt` from
+// the parts -- the shard resolved it against ServUO's own two vendor systems (the
+// charge, the funds and the interval all differ between them) and re-deriving it here
+// would be a second implementation of a rule that lives in PlayerVendor.PayTimer. And
+// it does not treat a missing `fees` object as zero: a pre-v5 overlay simply omits it,
+// and nulls are how a v5 website says "this shard has not told me" rather than
+// "this vendor is broke", which is the difference between silence and a false alarm.
+const fees = (f) => {
+  if (!f || typeof f !== 'object') return { feesExempt: false, chargePerPeriod: null, funds: null, payIntervalSec: null, nextPayAt: null, periodsRemaining: null, dismissalAt: null }
+  // A commission vendor has no pay timer and is never dismissed for fees. Reporting it
+  // as exempt with no schedule is not the same as reporting a very long one, and a
+  // surface that renders "never" must be able to tell them apart.
+  if (f.exempt === true) return { feesExempt: true, chargePerPeriod: null, funds: null, payIntervalSec: null, nextPayAt: null, periodsRemaining: null, dismissalAt: null }
+  return {
+    feesExempt: false,
+    chargePerPeriod: Number.isFinite(f.chargePerPeriod) ? Math.trunc(f.chargePerPeriod) : null,
+    funds: Number.isFinite(f.funds) ? Math.trunc(f.funds) : null,
+    payIntervalSec: Number.isFinite(f.payIntervalSec) ? Math.trunc(f.payIntervalSec) : null,
+    nextPayAt: when(f.nextPayAt),
+    periodsRemaining: Number.isFinite(f.periodsRemaining) ? Math.trunc(f.periodsRemaining) : null,
+    dismissalAt: when(f.dismissalAt),
+  }
+}
+
 // ── Ingest ─────────────────────────────────────────────────────────────────
 
 /**
@@ -64,6 +101,10 @@ function flattenFrame(ev) {
     shopName: clip(ev.shopName, MAX_SHOP),
     ownerSerial: clip(ev.ownerSerial, MAX_SERIAL),
     ownerName: clip(ev.ownerName, MAX_OWNER),
+    // Protocol 5. The character name has been here since v3, but only the game
+    // ACCOUNT joins to shard_account_links -- so this is the field that makes a
+    // vendor row resolvable to a person at all.
+    ownerAcct: clip(ev.ownerAcct, MAX_ACCT),
     map: clip(loc.map, MAX_MAP),
     x: Number.isFinite(loc.x) ? Math.trunc(loc.x) : null,
     y: Number.isFinite(loc.y) ? Math.trunc(loc.y) : null,
@@ -76,6 +117,7 @@ function flattenFrame(ev) {
     itemTotal: int(ev.total, int(ev.count, 0)),
     truncated: ev.truncated === true,
     t: Number.isFinite(ev.t) ? ev.t : null,
+    ...fees(ev.fees),
   }
 }
 

server/model/shardState/shardState.db.js

@@ -98,7 +98,12 @@ async function latestEconomy() {
 
 // ── Houses / IDOC ────────────────────────────────────────────────────────
 const HOUSE_COLS =
-  'serial, stage, map, x, y, z, region, name, owner_serial, owner_acct, built_on, last_refreshed, is_idoc, updated_at'
+  'serial, stage, map, x, y, z, region, name, owner_serial, owner_acct, built_on, last_refreshed, is_idoc, updated_at' +
+  // Protocol 5's decay schedule. Added to the BASE column list rather than to
+  // HOUSE_REG_COLS because it arrives on house.decay, so a decay-only row -- one the
+  // registry sweep has never seen -- carries it too, and the public IDOC page reads
+  // exactly those rows.
+  ', next_stage, estimated_collapse, decay_period_sec, dynamic_decay'
 
 const upsertHouse = (serial, fields) => upsertRow('shard_houses', 'serial', serial, fields)
 
@@ -215,6 +220,26 @@ const listGuildMembers = (guildId) =>
     guildId,
   ])
 
+
+// **The game accounts on one guild's roster** — the input to
+// `shardLinks.userIdsForAccounts`, and therefore to the `members` audience a
+// guild event carries (Phase 11). Accounts rather than `web_id`, deliberately:
+// `web_id` is a value MIRRORED off the wire actor, and `shard_account_links` is
+// the authoritative map. A mirror that has drifted would mail the wrong person,
+// and a mirror that is behind would mail nobody, so the query that decides who
+// is told reads the table whose job that is.
+const listGuildMemberAccounts = (guildId) =>
+  query(
+    'SELECT DISTINCT acct FROM shard_guild_members WHERE guild_id = ? AND acct IS NOT NULL',
+    [guildId],
+  )
+
+// The accounts of every sitting governor — the `uo.governors` audience.
+// `governor_acct` is NULL on a city with no governor and on one whose governor's
+// mobile has no account, and both are simply nobody.
+const listGovernorAccounts = () =>
+  query('SELECT DISTINCT governor_acct FROM shard_governors WHERE governor_acct IS NOT NULL')
+
 // The guild an actor LEADS — matched on the current board (leader_serial or the
 // linked leader_acct), so it reflects live state. Guild MEMBERSHIP for non-leaders
 // is not modelled (the board carries only counts + leader), so we don't guess it.
@@ -391,6 +416,8 @@ module.exports = {
   removeGuildMember,
   clearAllGuildMembers,
   listGuildMembers,
+  listGuildMemberAccounts,
+  listGovernorAccounts,
   findGuildLedByActor,
   listGuildsLedByAccounts,
   upsertGovernor,

server/model/shardState/shardState.model.js

@@ -124,10 +124,39 @@ async function upsertHouse(data) {
     built_on: data.builtOn ? new Date(data.builtOn) : null,
     last_refreshed: data.lastRefreshed ? new Date(data.lastRefreshed) : null,
     is_idoc: String(data.stage).toUpperCase() === 'IDOC' ? 1 : 0,
+    // Protocol 5. `ownerName` is written back only when the frame carries one, and
+    // that asymmetry is deliberate: house.update also writes this column, from a
+    // different sweep, and a pre-v5 overlay's house.decay frame has no ownerName at
+    // all. Coalescing to null here would let every decay transition ERASE a name the
+    // registry had already resolved.
+    ...(data.ownerName ? { owner_name: String(data.ownerName).slice(0, 120) } : {}),
+    ...decayScheduleFields(data.schedule),
   }
   await db.upsertHouse(data.serial, fields)
 }
 
+// Protocol 5's `schedule` object, flattened into its columns.
+//
+// Unlike ownerName above, these are written back UNCONDITIONALLY, including as nulls.
+// A schedule is a claim about the future and it goes stale on its own: if a shard is
+// rolled back to a pre-v5 overlay, or a house leaves IDOC so its collapse time stops
+// being knowable, the right stored value is "nothing" rather than the last thing we
+// were told. A dated promise nobody is maintaining is worse than no promise.
+function decayScheduleFields(schedule) {
+  const s = schedule && typeof schedule === 'object' ? schedule : {}
+  const when = (v) => {
+    if (!v) return null
+    const d = new Date(v)
+    return Number.isNaN(d.getTime()) ? null : d
+  }
+  return {
+    next_stage: when(s.nextStage),
+    estimated_collapse: when(s.estimatedCollapse),
+    decay_period_sec: Number.isFinite(s.decayPeriodSec) ? Math.trunc(s.decayPeriodSec) : null,
+    dynamic_decay: typeof s.dynamicDecay === 'boolean' ? (s.dynamicDecay ? 1 : 0) : null,
+  }
+}
+
 function shapeHouse(r) {
   return {
     serial: r.serial,
@@ -149,6 +178,16 @@ function shapeHouse(r) {
     inRegistry: r.in_registry == null ? undefined : Boolean(r.in_registry),
     builtOn: r.built_on,
     lastRefreshed: r.last_refreshed,
+    // Protocol 5. Re-nested on read for the reason shardMarket re-nests `location`:
+    // the visibility projection matches literal JSON keys, so the stored read model
+    // and the live wire frame have to spell this the same way or the one admin rule
+    // covers only one of the two paths.
+    schedule: {
+      dynamicDecay: r.dynamic_decay == null ? null : Boolean(r.dynamic_decay),
+      nextStage: r.next_stage,
+      decayPeriodSec: r.decay_period_sec,
+      estimatedCollapse: r.estimated_collapse,
+    },
     isIdoc: Boolean(r.is_idoc),
     updatedAt: r.updated_at,
   }
@@ -423,6 +462,19 @@ async function listGuildMembers(guildId) {
   }))
 }
 
+
+// **Just the accounts, for the engagement audiences** (Phase 11). Deliberately
+// NOT `listGuildMembers().map(m => m.acct)`: that shape exists to be projected
+// through `shardVisibility`, which strips `acct` for anyone below admin, so
+// building an audience out of it would either leak the projection's job into
+// this one or silently resolve to nobody depending on who asked. These two go to
+// the database for exactly the column they need and pass nothing else on.
+const listGuildMemberAccounts = async (guildId) =>
+  (await db.listGuildMemberAccounts(guildId)).map((r) => r.acct).filter(Boolean)
+
+const listGovernorAccounts = async () =>
+  (await db.listGovernorAccounts()).map((r) => r.governor_acct).filter(Boolean)
+
 function shapeGuild(r) {
   const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload
   return payload || {
@@ -703,6 +755,8 @@ module.exports = {
   upsertGuildRoster,
   removeGuildMember,
   listGuildMembers,
+  listGuildMemberAccounts,
+  listGovernorAccounts,
   replaceGuilds,
   findGuildForActor,
   listGuildsLedForAccounts,

server/model/uoLinkConfig/uoLinkConfig.model.js

@@ -11,13 +11,16 @@ const { secretBox } = require('../../core')
 // Only used before an admin has saved anything — the stored row wins once it exists,
 // and UOLINK_PROTOCOL still overrides for an operator running an older sidecar.
 //
-// This says 4 because this build handles protocol 4's frames: `guild.roster` and
-// `guild.leave` ingest landed with the Teams cutover. It said 3 for a while after
-// that, which is the bug this constant is now the fix for — a FRESH install pinned
-// 3, the sidecar answered `409 protocol version mismatch` to every REST call, and a
-// new deployment read nothing from its shard until an admin edited the number by
-// hand in Admin → Shard. See the matching cutover in db/schema.sql.
-const DEFAULT_PROTOCOL = Number(process.env.UOLINK_PROTOCOL) || 4
+// This says 5 because this build handles protocol 5's frames: house.decay's `schedule`,
+// vendor.listing's `ownerAcct` + `fees`, and the new `account.login.result` kind.
+//
+// It said 4 before that, and 3 for a while after protocol 4 shipped — which is the bug
+// this constant is now the fix for. A FRESH install pinned 3, the sidecar answered
+// `409 protocol version mismatch` to every REST call, and a new deployment read nothing
+// from its shard until an admin edited the number by hand in Admin → Shard. Bumping it
+// in the SAME change as the emitters is the discipline that prevents a repeat; see the
+// matching cutover in db/schema.sql.
+const DEFAULT_PROTOCOL = Number(process.env.UOLINK_PROTOCOL) || 5
 
 function toSafe(row) {
   if (!row) {
@@ -92,4 +95,7 @@ async function recordStatus({ status, statusDetail, pluginConnected, lastEventAt
   return toSafe(row)
 }
 
-module.exports = { getSafe, getWithToken, save, recordStatus }
+// DEFAULT_PROTOCOL is exported for the schema test, which asserts that this constant
+// and schema.sql's two declarations of the same number AGREE, rather than asserting a
+// hardcoded version at each site -- which is what let them drift apart before.
+module.exports = { getSafe, getWithToken, save, recordStatus, DEFAULT_PROTOCOL }

server/test/_fakes.js

@@ -47,6 +47,11 @@ function fakeCtx(overrides = {}) {
     settings: { get: spy(Promise.resolve(null)), set: spy(Promise.resolve()), getInstanceName: spy(Promise.resolve('Test')) },
     auth: { getUserFromRequest: spy(null) },
     push: { publish: spy(Promise.resolve()) },
+    // MODULE_API 1.7.0. Both are fire-and-forget and return undefined by
+    // contract — a module gets no delivery answer back, deliberately — so the
+    // spies return undefined rather than a promise, which is what core does.
+    events: { emit: spy(undefined) },
+    inbox: { push: spy(undefined) },
     secretBox: { encrypt: spy('enc'), decrypt: spy('dec') },
     middleware: {
       requireAuth: (req, res, next) => next(),
@@ -97,6 +102,8 @@ function fakeApi() {
     legs: [],
     teamProvider: null,
     slashCommands: [],
+    triggers: null,
+    audiences: null,
     hooks: {},
   }
   const called = new Set()
@@ -117,6 +124,11 @@ function fakeApi() {
     // takes it: a second call is a module changing its mind halfway through
     // register(), which core rejects.
     registerSlashCommands(commands) { once('registerSlashCommands'); record.slashCommands = commands },
+    // MODULE_API 1.7.0, live since ENGAGEMENT.md Phase 11. `once` on both, for
+    // the reason above: core stages a registrant's whole batch and applies it as
+    // one, so a second call is a module changing its mind mid-register().
+    registerEventTriggers(triggers) { once('registerEventTriggers'); record.triggers = triggers },
+    registerAudiences(audiences) { once('registerAudiences'); record.audiences = audiences },
     onBoot(fn) { once('onBoot'); record.hooks.onBoot = fn },
     onShutdown(fn) { once('onShutdown'); record.hooks.onShutdown = fn },
   }

server/test/schemaFragment.test.js

@@ -144,12 +144,23 @@ test('both settings seeds are INSERT IGNORE, so a replay never resets a value',
 // sidecar, which 409s every REST call — an install that reads nothing from its
 // shard, with the cause only in the log. These tests are the guard.
 
+// The protocol this build speaks, read from the model rather than written here.
+//
+// Hardcoding the number in this test is what the protocol-4 bug looked like from the
+// other side: the emitters moved, one declaration site did not, and every site agreed
+// with itself. Reading DEFAULT_PROTOCOL makes the assertion "the three declarations
+// AGREE" rather than "they all say 4", so a bump that misses one of them fails here
+// instead of on an operator's install.
+const { DEFAULT_PROTOCOL } = require('../model/uoLinkConfig/uoLinkConfig.model')
+
 test('the column default pins the protocol this build speaks', () => {
+  assert.ok(Number.isInteger(DEFAULT_PROTOCOL) && DEFAULT_PROTOCOL > 0, 'no protocol pin exported')
+
   const create = statements.find((s) => /CREATE TABLE.*uo_link_config/is.test(s))
   assert.ok(create, 'uo_link_config is gone')
   assert.match(
     create,
-    /protocol\s+INT\s+NOT NULL DEFAULT 4/i,
+    new RegExp('protocol +INT +NOT NULL DEFAULT ' + DEFAULT_PROTOCOL + '(?![0-9])', 'i'),
     'the CREATE TABLE default must name the protocol this build speaks',
   )
 
@@ -159,7 +170,34 @@ test('the column default pins the protocol this build speaks', () => {
     /^ALTER TABLE\s+uo_link_config\s+MODIFY COLUMN protocol/i.test(s),
   )
   assert.ok(modifies.length > 0, 'the default-fixing MODIFY is gone')
-  assert.match(modifies[modifies.length - 1], /DEFAULT 4/i)
+  assert.match(
+    modifies[modifies.length - 1],
+    new RegExp('DEFAULT ' + DEFAULT_PROTOCOL + '(?![0-9])', 'i'),
+  )
+})
+
+// The one-shot migration for the CURRENT protocol, whatever it is. Same argument as
+// above: these three assertions used to be written once per version by hand, so the
+// version that mattered — the newest — was the one with no test until someone
+// remembered to copy the block.
+test('the current protocol has a one-shot migration, correctly ordered and guarded', () => {
+  const marker = `uo_link_protocol_${DEFAULT_PROTOCOL}_migrated`
+
+  const update = statements.findIndex(
+    (s) => /^UPDATE\s+uo_link_config/i.test(s) && s.includes(marker),
+  )
+  const insert = statements.findIndex((s) => /^INSERT/i.test(s) && s.includes(`'${marker}'`))
+
+  assert.ok(update >= 0, `no migration to protocol ${DEFAULT_PROTOCOL}`)
+  assert.ok(insert >= 0, `no one-shot marker for protocol ${DEFAULT_PROTOCOL}`)
+  assert.ok(insert > update, 'the marker is written before the UPDATE reads it')
+
+  // `protocol < N`, never `= N-1`: an install that missed an earlier migration has to
+  // be carried the whole way rather than one step.
+  assert.match(
+    statements[update],
+    new RegExp('protocol *< *' + DEFAULT_PROTOCOL + '(?![0-9])'),
+  )
 })
 
 test('the protocol-4 marker is written AFTER the update that reads it', () => {

server/test/shardEngagement.test.js

@@ -0,0 +1,504 @@
+// ── The wire-kind → engagement-trigger mapper (ENGAGEMENT.md Phase 11) ─────
+//
+// Two halves, tested separately for the reason the file splits them: `mapShardEvent`
+// is pure given a tracker and needs no database, and `fromShardEvent` is the half
+// that resolves an account into a person and therefore does.
+//
+// What is asserted here is deliberately not "each field is copied". It is the
+// three things a rule cannot express and a plain mapping would get wrong —
+// transitions, thresholds, and who an event is ABOUT — plus the four places §8.6
+// or the protocol docs say the obvious implementation is the wrong one.
+
+const { test, beforeEach } = require('node:test')
+const assert = require('node:assert/strict')
+
+const engagement = require('../utils/shardEngagement')
+const { TRIGGERS, TRIGGER_IDS } = require('../config/shardTriggers')
+
+let tracker
+beforeEach(() => { tracker = engagement.createTracker() })
+
+const map = (event) => engagement.mapShardEvent(event, tracker)
+const ids = (event) => map(event).map((t) => t.triggerId)
+const one = (event) => {
+  const out = map(event)
+  assert.equal(out.length, 1, `expected exactly one target, got ${out.length}`)
+  return out[0]
+}
+
+// ── The catalogue itself ───────────────────────────────────────────────────
+
+test('the declared set is the one ENGAGEMENT.md §8.6 commits to, carve-outs included', () => {
+  assert.equal(TRIGGERS.length, 24)
+  // The four rows that do NOT ship, each with its reason recorded in §8.6. This
+  // assertion is the guard on the carve-outs: adding one back is a decision, and
+  // a decision should have to edit a test that says so.
+  for (const carved of [
+    'uo.market.item_listed', // a saved SEARCH; no per-user query store exists
+    'uo.guild.joined', //       core's team.member.joined already fires for it
+    'uo.link.requested', //     no addressable recipient, and a ~5-minute TTL
+  ]) {
+    assert.equal(TRIGGER_IDS.has(carved), false, `${carved} is carved out`)
+  }
+  // Every id is this module's, which is what `namespaced()` enforces at
+  // registration — asserted here too so the failure names the id rather than
+  // arriving as a boot error.
+  for (const t of TRIGGERS) assert.ok(t.id.startsWith('uo.'), `${t.id} is namespaced`)
+})
+
+test('every variable carries an example, because a template is previewed with it', () => {
+  for (const t of TRIGGERS) {
+    for (const v of t.variables) {
+      assert.ok(v.example !== undefined && v.example !== '', `${t.id}.${v.name} has an example`)
+      assert.ok(v.description, `${t.id}.${v.name} has a description`)
+    }
+    // A subjectKey that is not one of the trigger's own variables is refused at
+    // registration; catching it here names the trigger instead of the boot.
+    if (t.subjectKey) {
+      assert.ok(
+        t.variables.some((v) => v.name === t.subjectKey),
+        `${t.id} subjectKey "${t.subjectKey}" is one of its variables`,
+      )
+    }
+  }
+})
+
+test('a url variable is site-RELATIVE — an absolute one ends up in an href', () => {
+  for (const t of TRIGGERS) {
+    for (const v of t.variables.filter((x) => x.type === 'url')) {
+      assert.ok(v.example.startsWith('/'), `${t.id}.${v.name} example is rooted`)
+      // Not protocol-relative: `//evil.test/x` passes an "is it rooted" check.
+      assert.ok(!v.example.startsWith('//'), `${t.id}.${v.name} is not protocol-relative`)
+    }
+  }
+})
+
+// The declaration that the whole ceiling lattice exists for.
+test('uo.cheat.detected ceilings at staff and NEVER at owner', () => {
+  const cheat = TRIGGERS.find((t) => t.id === 'uo.cheat.detected')
+  assert.equal(cheat.ceiling, 'staff')
+  assert.equal(cheat.audience, 'staff')
+  // The three operator-facing ones sit a rung lower still: `staff` means admin,
+  // editor AND moderator, so a digest of what moderators did must not ceiling there.
+  for (const id of ['uo.audit.staff_action', 'uo.economy.milestone', 'uo.world.saved']) {
+    assert.equal(TRIGGERS.find((t) => t.id === id).ceiling, 'admin', `${id} ceilings at admin`)
+  }
+})
+
+// ── Houses ─────────────────────────────────────────────────────────────────
+
+const DECAY = {
+  kind: 'house.decay',
+  serial: '0x400142F9',
+  from: 'Fairly',
+  to: 'Greatly',
+  name: 'Millrace',
+  ownerAcct: 'seed_002',
+  region: 'Britain',
+  map: 'Felucca',
+  x: 1480,
+  y: 1600,
+  lastRefreshed: '2026-08-25T17:21:14Z',
+}
+
+test('a late decay stage warns the owner; an early one says nothing', () => {
+  const t = one(DECAY)
+  assert.equal(t.triggerId, 'uo.house.idoc_warning')
+  assert.equal(t.ownerAccount, 'seed_002')
+  assert.equal(t.data.stage, 'Greatly')
+  assert.equal(t.data.location, 'Felucca 1480, 1600 (Britain)')
+  // A house being refreshed is the normal case. Mailing it would make the
+  // warning worthless.
+  assert.deepEqual(ids({ ...DECAY, to: 'LikeNew' }), [])
+  assert.deepEqual(ids({ ...DECAY, to: 'Slightly' }), [])
+})
+
+test('the v5 schedule rides along when present and is simply absent when not', () => {
+  const withSchedule = one({
+    ...DECAY,
+    schedule: {
+      dynamicDecay: true,
+      nextStage: '2026-09-01T20:33:15Z',
+      estimatedCollapse: '2026-09-06T20:33:15Z',
+    },
+  })
+  assert.equal(withSchedule.data.nextStage, '2026-09-01T20:33:15Z')
+  assert.equal(withSchedule.data.estimatedCollapse, '2026-09-06T20:33:15Z')
+
+  // **A dynamic-decay shard omits `estimatedCollapse` at every stage before
+  // IDOC, and a v4 overlay omits the whole block.** `docs/link/v5.md` is explicit
+  // that absence means "not knowable", never "not yet read" — so the mapper must
+  // pass the absence through rather than computing a fallback, which would
+  // republish exactly the guess the shard refused to make.
+  const dynamic = one({ ...DECAY, schedule: { dynamicDecay: true, nextStage: '2026-09-01T20:33:15Z' } })
+  assert.equal(dynamic.data.nextStage, '2026-09-01T20:33:15Z')
+  assert.equal('estimatedCollapse' in dynamic.data, false)
+
+  const v4 = one(DECAY)
+  assert.equal('nextStage' in v4.data, false)
+  assert.equal('estimatedCollapse' in v4.data, false)
+})
+
+test('Collapsed is its own trigger, not a louder warning', () => {
+  const t = one({ ...DECAY, to: 'Collapsed' })
+  assert.equal(t.triggerId, 'uo.house.collapsed')
+  assert.equal(t.ownerAccount, 'seed_002')
+})
+
+test('house.remove carries only a serial, so the owner is looked up later', () => {
+  const t = one({ kind: 'house.remove', serial: '0x400142F9' })
+  assert.equal(t.triggerId, 'uo.house.collapsed')
+  assert.equal(t.ownerAccount, undefined)
+  assert.equal(t.houseSerial, '0x400142F9')
+})
+
+// ── Vendors: the threshold, and the two ways there is nothing to warn about ──
+
+const listing = (fees) => ({
+  kind: 'vendor.listing',
+  serial: '0x40001234',
+  shopName: "Darrow's Bargains",
+  ownerAcct: 'darrow_acct',
+  location: { map: 'Trammel', x: 1421, y: 1699, region: 'Britain' },
+  ...(fees === undefined ? {} : { fees }),
+})
+
+const inHours = (h) => new Date(Date.now() + h * 3_600_000).toISOString()
+
+const FEES = (h) => ({
+  exempt: false,
+  newVendorSystem: true,
+  chargePerPeriod: 10548,
+  funds: 8204,
+  payIntervalSec: 86400,
+  periodsRemaining: 1,
+  dismissalAt: inHours(h),
+})
+
+test('a vendor entering the warning window fires ONCE, not on every sweep frame', () => {
+  // `vendor.listing` is re-emitted on any price change, so without the crossing
+  // check a vendor inside the window mails its owner every time somebody
+  // reprices a longsword.
+  const first = one(listing(FEES(20)))
+  assert.equal(first.triggerId, 'uo.vendor.expiring')
+  assert.equal(first.ownerAccount, 'darrow_acct')
+  assert.equal(first.data.hoursRemaining, 19) // floor of 20h minus the tick spent here
+  assert.deepEqual(ids(listing(FEES(19))), [])
+  assert.deepEqual(ids(listing(FEES(18))), [])
+})
+
+test('a deposit that leaves the window re-arms the warning', () => {
+  assert.deepEqual(ids(listing(FEES(20))), ['uo.vendor.expiring'])
+  assert.deepEqual(ids(listing(FEES(400))), []) // paid up — out of the window
+  assert.deepEqual(ids(listing(FEES(10))), ['uo.vendor.expiring']) // and back in
+})
+
+test('exempt and absent fees are both "nothing to warn about", not "no money"', () => {
+  // A commission vendor has no PayTimer and is NEVER dismissed for fees.
+  // Conflating that with a distant date is how a vendor that cannot expire ends
+  // up in an expiry warning (docs/link/v5.md).
+  assert.deepEqual(ids(listing({ exempt: true })), [])
+  // A pre-v5 overlay sends no `fees` block at all.
+  assert.deepEqual(ids(listing(undefined)), [])
+})
+
+test('a vendor already past its dismissal tick reports 0 hours, never a negative', () => {
+  const t = one(listing(FEES(-3)))
+  assert.equal(t.data.hoursRemaining, 0)
+})
+
+test('an unowned listing is nobody to notify', () => {
+  const { ownerAcct, ...anonymous } = listing(FEES(10))
+  assert.deepEqual(ids(anonymous), [])
+})
+
+// ── Logins: the inversion protocol 5 exists to fix ─────────────────────────
+
+test('only a FAILED login warns — a successful one produces nothing', () => {
+  const failed = one({ kind: 'account.login.result', acct: 'seed_000', ip: '203.0.113.9', accepted: false, reason: 'BadPass' })
+  assert.equal(failed.triggerId, 'uo.account.login_failed')
+  assert.equal(failed.data.reason, 'BadPass')
+  assert.deepEqual(ids({ kind: 'account.login.result', acct: 'seed_000', accepted: true }), [])
+})
+
+test('the pre-decision attempt kind is not mapped at all', () => {
+  // `account.login.attempt` fires from a sink that runs BEFORE the auth decision
+  // and whose args default `Accepted = true`, so a rule on it would have mailed a
+  // security alert on every successful login. That is why v5 added a second kind
+  // and why this one must stay unmapped.
+  assert.deepEqual(ids({ kind: 'account.login.attempt', acct: 'seed_000', ip: '203.0.113.9' }), [])
+})
+
+// ── Transitions ────────────────────────────────────────────────────────────
+
+const champ = (over) => ({ kind: 'champ.update', serial: '0x40012345', name: 'Abyss', category: 'champion', map: 'Felucca', x: 5187, y: 570, ...over })
+
+test('a first sighting is never a transition — a reconnect is not twenty spawns starting', () => {
+  assert.deepEqual(ids(champ({ active: true })), [])
+  assert.deepEqual(ids(champ({ active: true })), []) // still no change
+  assert.deepEqual(ids(champ({ active: false })), [])
+  assert.deepEqual(ids(champ({ active: true })), ['uo.champ.started'])
+})
+
+test('the boss is its own transition, tracked separately from active', () => {
+  map(champ({ active: true, bossUp: false }))
+  assert.deepEqual(ids(champ({ active: true, bossUp: true })), ['uo.champ.boss_up'])
+  assert.deepEqual(ids(champ({ active: true, bossUp: true })), [])
+})
+
+test('champ.remove forgets the spawn, so its next appearance is a first sighting', () => {
+  map(champ({ active: false }))
+  map({ kind: 'champ.remove', serial: '0x40012345' })
+  assert.deepEqual(ids(champ({ active: true })), [])
+})
+
+const city = (over) => ({ kind: 'city.update', city: 'Britain', electionPhase: 'none', ...over })
+
+test('a governor change is a transition, and never on first sight', () => {
+  assert.deepEqual(ids(city({ governor: { serial: '0x1', name: 'Mireille' } })), [])
+  const t = one(city({ governor: { serial: '0x2', name: 'Darrow' } }))
+  assert.equal(t.triggerId, 'uo.governor.elected')
+  assert.equal(t.data.governorName, 'Darrow')
+  assert.deepEqual(ids(city({ governor: { serial: '0x2', name: 'Darrow' } })), [])
+})
+
+test('an election opening needs its deadline, or it does not fire', () => {
+  map(city({ electionPhase: 'none' }))
+  // **A "vote now" mail with nothing to act by is worse than none**, and
+  // `autoPickAt` is declared required, so a phase change without one is dropped
+  // here rather than refused by `emit` later.
+  assert.deepEqual(ids(city({ electionPhase: 'vote' })), [])
+
+  const fresh = engagement.createTracker()
+  engagement.mapShardEvent(city({ electionPhase: 'none' }), fresh)
+  const out = engagement.mapShardEvent(
+    city({ electionPhase: 'vote', autoPickAt: '2026-09-04T00:00:00Z', candidates: 3 }),
+    fresh,
+  )
+  assert.deepEqual(out.map((t) => t.triggerId), ['uo.election.opened'])
+  assert.equal(out[0].data.autoPickAt, '2026-09-04T00:00:00Z')
+})
+
+// ── The shard's own up/down, which is the cooldown table's stress test ─────
+
+test('a sidecar reconnect is not a restart — server.hello only fires on a real change', () => {
+  // `server.hello` is sent on EVERY sidecar reconnect, not only on a shard
+  // restart, which is exactly the flapping this trigger must not amplify.
+  assert.deepEqual(ids({ kind: 'server.hello', shard: 'UOMysticmoon', bootId: 'a' }), ['uo.server.up'])
+  assert.deepEqual(ids({ kind: 'server.hello', shard: 'UOMysticmoon', bootId: 'a' }), [])
+  assert.deepEqual(ids({ kind: 'server.hello', shard: 'UOMysticmoon', bootId: 'b' }), [])
+})
+
+test('down fires once per outage, and a crash is told apart from a clean stop', () => {
+  map({ kind: 'server.hello', shard: 'UOMysticmoon' })
+  const down = one({ kind: 'server.shutdown' })
+  assert.equal(down.triggerId, 'uo.server.down')
+  assert.equal(down.data.clean, true)
+  assert.deepEqual(ids({ kind: 'server.crashed' }), []) // already down
+  map({ kind: 'server.hello' })
+  assert.equal(one({ kind: 'server.crashed' }).data.clean, false)
+})
+
+// ── Thresholds ─────────────────────────────────────────────────────────────
+
+const supply = (gold, accounts = 50) => ({ kind: 'economy.supply', gold, accounts })
+
+test('an economy milestone fires on a crossing, in both directions, never on first sight', () => {
+  // A sidecar reconnect on a mature shard must not announce a line it crossed
+  // months ago.
+  assert.deepEqual(ids(supply(900_000_000)), [])
+  const up = one(supply(1_200_000_000))
+  assert.equal(up.triggerId, 'uo.economy.milestone')
+  assert.equal(up.data.direction, 'up')
+  assert.equal(up.data.threshold, 1_000_000_000)
+  assert.deepEqual(ids(supply(1_300_000_000)), []) // same band
+  const down = one(supply(800_000_000))
+  assert.equal(down.data.direction, 'down')
+  assert.equal(down.data.threshold, 1_000_000_000) // the line it fell back through
+})
+
+// ── Leaderboards ───────────────────────────────────────────────────────────
+
+const board = (serial, name) => ({
+  kind: 'points.board',
+  system: 'QueensLoyalty',
+  nameString: "Queen's Loyalty",
+  top: [{ rank: 1, serial, name, points: 29500 }, { rank: 2, serial: '0xFF', name: 'Mireille', points: 21000 }],
+})
+
+test('a leaderboard change names the new leader and nobody personally', () => {
+  assert.deepEqual(ids(board('0x1A2B', 'Darrow')), [])
+  const t = one(board('0x1A2C', 'Bran'))
+  assert.equal(t.triggerId, 'uo.points.rank_changed')
+  assert.equal(t.data.leaderName, 'Bran')
+  // The personal half is carved out: `top[]` names a mobile SERIAL and links are
+  // keyed by ACCOUNT, so there is deliberately no owner on this target.
+  assert.equal(t.ownerAccount, undefined)
+  assert.deepEqual(ids(board('0x1A2C', 'Bran')), [])
+})
+
+// ── Milestones ─────────────────────────────────────────────────────────────
+
+test('only a capped skill is a milestone', () => {
+  const who = { serial: '0x1', name: 'Zara Crowe', acct: 'seed_000' }
+  assert.deepEqual(ids({ kind: 'skill.gain', who, skill: 'Blacksmithy', base: 99.8, cap: 100 }), [])
+  const t = one({ kind: 'skill.gain', who, skill: 'Blacksmithy', base: 100, cap: 100 })
+  assert.equal(t.triggerId, 'uo.skill.capped')
+  assert.equal(t.ownerAccount, 'seed_000')
+  // A mobile with no account is nobody's character.
+  assert.deepEqual(ids({ kind: 'skill.gain', who: { serial: '0x2', name: 'A Guard' }, base: 100, cap: 100 }), [])
+})
+
+test('both deaths address the victim, never the killer', () => {
+  const victim = { serial: '0x1', name: 'Zara Crowe', acct: 'seed_000' }
+  const murderer = { serial: '0x2', name: 'Darrow', acct: 'seed_001' }
+  const death = one({ kind: 'player.death', who: victim, killer: { name: 'an ogre lord' } })
+  assert.equal(death.ownerAccount, 'seed_000')
+  assert.equal(death.data.killerName, 'an ogre lord')
+  const murder = one({ kind: 'player.murdered', victim, murderer })
+  assert.equal(murder.triggerId, 'uo.character.murdered')
+  assert.equal(murder.ownerAccount, 'seed_000')
+  assert.equal(murder.data.murdererName, 'Darrow')
+})
+
+// ── Guilds ─────────────────────────────────────────────────────────────────
+
+test('a guild leave and a disband are members-shaped; a join is not mapped at all', () => {
+  const left = one({ kind: 'guild.leave', id: 1042, name: 'The Silver Hand', who: '0x77' })
+  assert.equal(left.triggerId, 'uo.guild.left')
+  assert.equal(left.guildId, 1042)
+  assert.equal(left.memberSerial, '0x77')
+
+  assert.equal(one({ kind: 'guild.remove', id: 1042 }).triggerId, 'uo.guild.disbanded')
+
+  // Core's `team.member.joined` already fires for this, on every roster
+  // reconcile, because a UO guild IS a Team and this module is the provider.
+  // A second trigger would be two mails for one join (§8.6).
+  assert.deepEqual(ids({ kind: 'guild.join', id: 1042, who: { serial: '0x77', name: 'Bran' } }), [])
+})
+
+// ── Staff and operator ─────────────────────────────────────────────────────
+
+test('the staff-facing pair carry no account of the person they are about, except where it is the point', () => {
+  const page = one({ kind: 'page.new', type: 'Stuck', sender: { name: 'Zara Crowe', acct: 'seed_000' }, message: 'help', map: 'Trammel', x: 1, y: 2 })
+  assert.equal(page.triggerId, 'uo.page.new')
+  assert.equal(page.ownerAccount, undefined) // it is a STAFF audience, not the player's
+
+  const cheat = one({ kind: 'cheat.fastwalk', who: { name: 'Zara Crowe', acct: 'seed_000' }, ip: '203.0.113.9' })
+  assert.equal(cheat.triggerId, 'uo.cheat.detected')
+  assert.equal(cheat.ownerAccount, undefined) // never addressed to the player detected
+  assert.equal(cheat.data.account, 'seed_000') // but staff are told which account
+})
+
+test('the three audit kinds fold into one operator trigger', () => {
+  assert.deepEqual(ids({ kind: 'audit.set', staff: 'Mireille', prop: 'Str', old: 100, new: 125, target: 'Zara' }), ['uo.audit.staff_action'])
+  assert.deepEqual(ids({ kind: 'audit.command', staff: 'Mireille', command: '[go', args: 'britain' }), ['uo.audit.staff_action'])
+  const admin = one({ kind: 'admin.audit', origin: 'web', action: 'ban', actor: 'web:9931', target: 'seed_000', reason: 'macroing' })
+  assert.equal(admin.data.action, 'ban')
+  assert.equal(admin.data.origin, 'web')
+})
+
+test('world.save.after reports what it wrote', () => {
+  const t = one({ kind: 'world.save.after', items: 1482301, mobiles: 41022 })
+  assert.equal(t.triggerId, 'uo.world.saved')
+  assert.equal(t.data.items, 1482301)
+  // `before` is a boundary, not news.
+  assert.deepEqual(ids({ kind: 'world.save.before' }), [])
+})
+
+// ── The guard ──────────────────────────────────────────────────────────────
+
+test('an unmapped kind and a malformed frame both produce nothing', () => {
+  assert.deepEqual(ids({ kind: 'char.vitals', serial: '0x1' }), [])
+  assert.deepEqual(ids({ kind: 'region.enter' }), [])
+  assert.deepEqual(engagement.mapShardEvent(null, tracker), [])
+  assert.deepEqual(engagement.mapShardEvent({}, tracker), [])
+  assert.deepEqual(engagement.mapShardEvent({ kind: 42 }, tracker), [])
+})
+
+// ── Resolution: the half that reaches the database ─────────────────────────
+
+function deps(over = {}) {
+  const emitted = []
+  return {
+    emitted,
+    emit: (triggerId, envelope) => emitted.push({ triggerId, envelope }),
+    tracker,
+    shardLinks: {
+      getByAccount: async (acct) => (acct === 'seed_002' ? { account: acct, user_id: 7 } : null),
+      userIdsForAccounts: async (accounts) => (accounts.includes('seed_002') ? [7, 9] : []),
+      ...over.shardLinks,
+    },
+    shardState: {
+      listHouses: async () => [{ serial: '0x400142F9', ownerAcct: 'seed_002', name: 'Millrace', region: 'Britain' }],
+      listGuilds: async () => [{ id: 1042, name: 'The Silver Hand', abbr: 'TSH' }],
+      listGuildMembers: async () => [{ serial: '0x77', name: 'Bran' }],
+      listGuildMemberAccounts: async () => ['seed_002'],
+      ...over.shardState,
+    },
+  }
+}
+
+test('an owner-keyed event resolves the game account to a website user', async () => {
+  const d = deps()
+  await engagement.fromShardEvent(DECAY, d)
+  assert.equal(d.emitted.length, 1)
+  assert.equal(d.emitted[0].triggerId, 'uo.house.idoc_warning')
+  assert.equal(d.emitted[0].envelope.ownerUserId, 7)
+})
+
+test('an UNLINKED owner is nobody to notify, and that is not an error', async () => {
+  // The common case on every shard: most game accounts have never been linked.
+  const d = deps()
+  await engagement.fromShardEvent({ ...DECAY, ownerAcct: 'nobody' }, d)
+  assert.deepEqual(d.emitted, [])
+})
+
+test('house.remove fills the owner and the name in from the registry mirror', async () => {
+  const d = deps()
+  await engagement.fromShardEvent({ kind: 'house.remove', serial: '0x400142F9' }, d)
+  assert.equal(d.emitted.length, 1)
+  assert.equal(d.emitted[0].envelope.ownerUserId, 7)
+  assert.equal(d.emitted[0].envelope.data.houseName, 'Millrace')
+})
+
+test('a guild event carries its own access-checked recipient set, not an ownerUserId', async () => {
+  // §5.1a: "the members of THIS guild" is a different answer every firing, so a
+  // saved segment cannot express it and the set travels on the envelope
+  // (Phase 6, decision 2 — the mechanism the Team fan-out was built on).
+  const d = deps()
+  await engagement.fromShardEvent({ kind: 'guild.leave', id: 1042, name: 'The Silver Hand', who: '0x77' }, d)
+  assert.equal(d.emitted.length, 1)
+  assert.deepEqual(d.emitted[0].envelope.recipientUserIds, [7, 9])
+  assert.equal(d.emitted[0].envelope.ownerUserId, undefined)
+  // The two names the frames do not carry come from the mirrors.
+  assert.equal(d.emitted[0].envelope.data.memberName, 'Bran')
+})
+
+test('guild.remove names the guild from the board, because the frame carries only an id', async () => {
+  const d = deps()
+  await engagement.fromShardEvent({ kind: 'guild.remove', id: 1042 }, d)
+  assert.equal(d.emitted[0].envelope.data.guildName, 'The Silver Hand')
+  assert.equal(d.emitted[0].envelope.data.abbreviation, 'TSH')
+})
+
+test('a guild whose members have all unlinked reaches nobody rather than everybody', async () => {
+  const d = deps({ shardLinks: { userIdsForAccounts: async () => [] } })
+  await engagement.fromShardEvent({ kind: 'guild.leave', id: 1042, who: '0x77' }, d)
+  assert.deepEqual(d.emitted, [])
+})
+
+test('a subscribers-shaped event needs no resolution at all', async () => {
+  const d = deps()
+  engagement.mapShardEvent(champ({ active: false }), tracker) // establish the transition
+  await engagement.fromShardEvent(champ({ active: true }), d)
+  assert.equal(d.emitted.length, 1)
+  assert.equal(d.emitted[0].envelope.ownerUserId, undefined)
+  assert.equal(d.emitted[0].envelope.recipientUserIds, undefined)
+})
+
+test('a failing lookup costs that one target and never the ingest feed', async () => {
+  const d = deps({ shardLinks: { getByAccount: async () => { throw new Error('db is down') } } })
+  await assert.doesNotReject(() => engagement.fromShardEvent(DECAY, d))
+  assert.deepEqual(d.emitted, [])
+})

server/test/shardMarket.model.test.js

@@ -261,3 +261,91 @@ test('the cliloc resolver is the path shapeItems resolves through', async () =>
   const found = await clilocs.resolveMany([1023721])
   assert.equal(found.get(1023721), 'quarter staff')
 })
+
+// ── Protocol 5: owner account and fee state ────────────────────────────────
+
+const V5_FEES = {
+  exempt: false,
+  newVendorSystem: true,
+  chargePerPeriod: 148,
+  funds: 2960,
+  holdGold: 2960,
+  bankAccount: 0,
+  payIntervalSec: 86400,
+  nextPayAt: '2026-09-01T00:00:00.000Z',
+  periodsRemaining: 20,
+  dismissalAt: '2026-09-21T00:00:00.000Z',
+}
+
+test('flattenFrame lifts ownerAcct, the field that makes a shop resolvable to a person', () => {
+  // ownerName has been on the frame since v3, but a character name joins to nothing:
+  // shard_account_links is keyed by the game ACCOUNT.
+  const row = market.flattenFrame({ ...FRAME, ownerAcct: 'darrow_acct', fees: V5_FEES })
+  assert.equal(row.ownerAcct, 'darrow_acct')
+  assert.equal(row.ownerName, 'Darrow', 'the character name is still carried too')
+})
+
+test('flattenFrame normalises the fee block, dates included', () => {
+  const row = market.flattenFrame({ ...FRAME, fees: V5_FEES })
+  assert.equal(row.feesExempt, false)
+  assert.equal(row.chargePerPeriod, 148)
+  assert.equal(row.funds, 2960)
+  assert.equal(row.payIntervalSec, 86400)
+  assert.equal(row.periodsRemaining, 20)
+  assert.ok(row.nextPayAt instanceof Date)
+  assert.equal(row.dismissalAt.toISOString(), '2026-09-21T00:00:00.000Z')
+})
+
+// The shard resolved dismissalAt against ServUO's two vendor systems, whose charge,
+// funds and pay interval all differ. Re-deriving it here would be a second
+// implementation of a rule that lives in PlayerVendor.PayTimer.
+test('flattenFrame trusts the shard dismissal date instead of recomputing it', () => {
+  const row = market.flattenFrame({
+    ...FRAME,
+    fees: { ...V5_FEES, dismissalAt: '2026-12-25T00:00:00.000Z' },
+  })
+  assert.equal(row.dismissalAt.toISOString(), '2026-12-25T00:00:00.000Z')
+})
+
+// A commission vendor has no pay timer and is never dismissed for fees. That is a
+// different thing from having a long time left, and a surface rendering "never" has
+// to be able to tell them apart.
+test('an exempt vendor reports exempt with no schedule at all', () => {
+  const row = market.flattenFrame({ ...FRAME, fees: { exempt: true } })
+  assert.equal(row.feesExempt, true)
+  assert.equal(row.dismissalAt, null)
+  assert.equal(row.periodsRemaining, null)
+  assert.equal(row.chargePerPeriod, null)
+})
+
+// A pre-v5 overlay omits `fees` entirely, and a shard can be rolled back to one.
+// Nulls have to mean "this shard has not told me", never "this vendor is broke" —
+// the difference between silence and a false alarm in a rule that mails an owner.
+test('a pre-v5 frame yields nulls, not zeroes', () => {
+  const row = market.flattenFrame(FRAME)
+  assert.equal(row.feesExempt, false)
+  for (const key of ['chargePerPeriod', 'funds', 'payIntervalSec', 'periodsRemaining']) {
+    assert.equal(row[key], null, `${key} must be null, not 0`)
+  }
+  assert.equal(row.nextPayAt, null)
+  assert.equal(row.dismissalAt, null)
+  assert.equal(row.ownerAcct, null)
+})
+
+test('an unparseable fee date is dropped rather than stored as an Invalid Date', () => {
+  const row = market.flattenFrame({
+    ...FRAME,
+    fees: { ...V5_FEES, dismissalAt: 'next tuesday', nextPayAt: null },
+  })
+  assert.equal(row.dismissalAt, null)
+  assert.equal(row.nextPayAt, null)
+  assert.equal(row.funds, 2960, 'one bad field must not discard the rest of the block')
+})
+
+test('a malformed fees value is treated as absent, not as a crash', () => {
+  for (const fees of ['', 0, 'nope', []]) {
+    const row = market.flattenFrame({ ...FRAME, fees })
+    assert.equal(row.feesExempt, false)
+    assert.equal(row.dismissalAt, null)
+  }
+})

server/test/shardState.model.test.js

@@ -251,3 +251,74 @@ test('listGovernorHistory coerces started/ended timestamps to numbers and clamps
   assert.equal(typeof out[0].startedAt, 'number')
   assert.equal(out[0].endedAt, null) // an open term stays null, not coerced to 0
 })
+
+// ── Protocol 5: the decay schedule ─────────────────────────────────────────
+
+test('upsertHouse flattens the nested schedule into its four columns', async () => {
+  await shardState.upsertHouse({
+    serial: 1,
+    stage: 'IDOC',
+    schedule: {
+      dynamicDecay: true,
+      nextStage: '2026-09-02T04:00:00.000Z',
+      decayPeriodSec: 432000,
+      estimatedCollapse: '2026-09-02T04:00:00.000Z',
+    },
+  })
+  const [, fields] = calls.upsertHouse[0]
+  assert.equal(fields.dynamic_decay, 1)
+  assert.equal(fields.decay_period_sec, 432000)
+  assert.ok(fields.next_stage instanceof Date)
+  assert.equal(fields.estimated_collapse.toISOString(), '2026-09-02T04:00:00.000Z')
+})
+
+// The whole point of the field: under dynamic decay ServUO draws each stage's
+// duration at random on entry, so the shard omits estimatedCollapse everywhere but
+// IDOC. A stored null has to mean "not knowable", which it cannot if a partial
+// schedule silently keeps the previous value.
+test('a schedule without a collapse time stores null, it does not keep the old one', async () => {
+  await shardState.upsertHouse({
+    serial: 1,
+    stage: 'Greatly',
+    schedule: { dynamicDecay: true, nextStage: '2026-09-01T00:00:00.000Z', decayPeriodSec: 432000 },
+  })
+  const [, fields] = calls.upsertHouse[0]
+  assert.equal(fields.estimated_collapse, null)
+  assert.ok('estimated_collapse' in fields, 'must be WRITTEN as null, not omitted')
+})
+
+// A pre-v5 overlay sends no schedule at all, and a shard can be rolled back to one.
+// Every column is still written, so a dismissal date nobody is maintaining cannot
+// be left standing.
+test('a frame with no schedule nulls all four columns rather than omitting them', async () => {
+  await shardState.upsertHouse({ serial: 1, stage: 'Fairly' })
+  const [, fields] = calls.upsertHouse[0]
+  for (const col of ['next_stage', 'estimated_collapse', 'decay_period_sec', 'dynamic_decay']) {
+    assert.ok(col in fields, `${col} must be written`)
+    assert.equal(fields[col], null)
+  }
+})
+
+test('an unparseable schedule date is dropped, not stored as an Invalid Date', async () => {
+  await shardState.upsertHouse({
+    serial: 1,
+    stage: 'IDOC',
+    schedule: { nextStage: 'soon-ish', estimatedCollapse: '' },
+  })
+  const [, fields] = calls.upsertHouse[0]
+  assert.equal(fields.next_stage, null)
+  assert.equal(fields.estimated_collapse, null)
+})
+
+// house.update writes owner_name from its own sweep. If house.decay coalesced a
+// missing ownerName to null, every decay transition on a pre-v5 shard would erase
+// a name the registry had already resolved.
+test('house.decay never erases an owner_name it was not given', async () => {
+  await shardState.upsertHouse({ serial: 1, stage: 'IDOC', ownerAcct: 'cadmus' })
+  const [, fields] = calls.upsertHouse[0]
+  assert.ok(!('owner_name' in fields), 'owner_name must not be written when absent')
+
+  await shardState.upsertHouse({ serial: 1, stage: 'IDOC', ownerName: 'Cadmus' })
+  const [, withName] = calls.upsertHouse[1]
+  assert.equal(withName.owner_name, 'Cadmus')
+})

server/test/shardVisibility.test.js

@@ -476,3 +476,109 @@ test('a link lookup failure downgrades rather than escalating', async () => {
   visibility.forgetUser(6)
   assert.equal(await visibility.viewerLevel({ user: { id: 6, role: 'player' } }), 'logged_in')
 })
+
+// ── Protocol 5 ─────────────────────────────────────────────────────────────
+//
+// Two new nested field groups and one new kind. All three exist as visibility
+// questions before they exist as features, which is the order this framework's
+// rule 2 is designed to force: a v5 field that nobody classified would either
+// leak (if it fell open) or be silently invisible (if it fell closed and nobody
+// noticed). These tests pin the three answers that were actually chosen.
+
+test('a vendor fee block is admin-only, and it is the whole block', async () => {
+  const config = await visibility.getConfig()
+  // The frame as BridgeMarket emits it: the shop's public parts, plus the money.
+  const frame = {
+    serial: '0x40001234',
+    shopName: "Darrow's Bargains",
+    ownerName: 'Darrow',
+    location: { map: 'Trammel', x: 1421, y: 1699, region: 'Britain' },
+    fees: {
+      exempt: false,
+      chargePerPeriod: 148,
+      funds: 2960,
+      periodsRemaining: 20,
+      dismissalAt: '2026-09-20T00:00:00.0000000Z',
+    },
+  }
+
+  for (const level of ['anonymous', 'logged_in', 'player', 'staff']) {
+    const out = visibility.projectFeature('market', frame, level, config)
+    assert.equal('fees' in out, false, `fees reached ${level}`)
+    // The rest of the shop is untouched — this is a field rule, not a feature one.
+    assert.equal(out.shopName, "Darrow's Bargains", `${level} lost the shop name`)
+    assert.equal(out.location.region, 'Britain', `${level} lost the location`)
+  }
+
+  const asAdmin = visibility.projectFeature('market', frame, 'admin', config)
+  assert.equal(asAdmin.fees.funds, 2960)
+  assert.equal(asAdmin.fees.dismissalAt, '2026-09-20T00:00:00.0000000Z')
+})
+
+// The nesting is the point, not a style choice: projectValue matches literal JSON
+// keys, so seven flat fee keys would be seven rules an admin has to keep in step
+// and a v6 field would default to visible. One nested key cannot drift.
+test('the fee rule is one nested key, so a new fee field inherits the gate', async () => {
+  const config = await visibility.getConfig()
+  const frame = { serial: '0x1', fees: { exempt: false, somethingAddedLater: 'secret' } }
+  const out = visibility.projectFeature('market', frame, 'staff', config)
+  assert.equal('fees' in out, false, 'a field added inside fees must not fall out of the gate')
+})
+
+// The opposite call, and it is deliberate: the decay countdown is the public IDOC
+// page's entire content, and a house at IDOC is already announced in game.
+test('the decay schedule is anonymous by default but remains configurable', async () => {
+  const frame = {
+    serial: '0x1',
+    to: 'IDOC',
+    name: 'Marble Tower',
+    schedule: {
+      dynamicDecay: true,
+      nextStage: '2026-09-02T04:00:00.0000000Z',
+      decayPeriodSec: 432000,
+      estimatedCollapse: '2026-09-02T04:00:00.0000000Z',
+    },
+  }
+
+  const config = await visibility.getConfig()
+  const anon = visibility.projectFeature('houses', frame, 'anonymous', config)
+  assert.equal(anon.schedule.estimatedCollapse, '2026-09-02T04:00:00.0000000Z')
+
+  // A shard that considers a precise collapse time an unfair advantage can raise it,
+  // and raising the one nested rule takes the whole schedule with it.
+  withRows([
+    {
+      feature: 'houses',
+      enabled: true,
+      audience: 'anonymous',
+      stream: true,
+      fieldRules: { schedule: 'staff' },
+    },
+  ])
+  const tightened = await visibility.getConfig()
+  assert.equal('schedule' in visibility.projectFeature('houses', frame, 'player', tightened), false)
+  assert.equal(
+    visibility.projectFeature('houses', frame, 'staff', tightened).schedule.decayPeriodSec,
+    432000,
+  )
+  // Tightening the schedule must not have disturbed the owner rules beside it.
+  assert.equal(visibility.projectFeature('houses', frame, 'anonymous', tightened).name, 'Marble Tower')
+})
+
+// Rule 2, exercised on the kind it was added for. account.login.result says whether
+// a password was accepted and from which IP; it is admin-only by OMISSION, and the
+// omission is the decision. If someone maps it to a feature to "make it visible",
+// this fails and says why.
+test('account.login.result is admin-only, like the attempt it completes', async () => {
+  const config = await visibility.getConfig()
+  assert.equal(
+    visibility.KIND_FEATURE.has('account.login.result'),
+    false,
+    'mapping this kind to a feature would let an admin widen an IP + auth verdict below admin',
+  )
+  for (const level of ['anonymous', 'logged_in', 'player', 'staff']) {
+    assert.equal(visibility.kindVisibleTo('account.login.result', level, config), false)
+  }
+  assert.equal(visibility.kindVisibleTo('account.login.result', 'admin', config), true)
+  assert.equal(visibility.PUBLIC_KINDS.has('account.login.result'), false)
+})

server/utils/shardEngagement.js

@@ -0,0 +1,781 @@
+// ── Shard event → engagement trigger ───────────────────────────────────────
+//
+// ENGAGEMENT.md Phase 11. The third fan-out off `shardIngest.ingest`, beside the
+// SSE broadcast and the push tickle, and the one that produces a PER-PERSON
+// notification subject to a rule, a preference and a suppression. It is the twin
+// of `shardPush.js` and reads deliberately like it:
+//
+//   • `shardStreams.mapShardEvent` turns a frame into push targets;
+//     `mapShardEvent` here turns a frame into engagement events.
+//   • Owner resolution is why neither can be a pure mapper: an owner-keyed target
+//     names a GAME ACCOUNT, and turning that into a website user needs
+//     `shardLinks`. An unlinked account is simply nobody to notify.
+//
+// **Nothing here decides who is told.** It says what happened and (for an
+// owner- or members-shaped event) who it is ABOUT; the engine applies the rules,
+// the ceiling, the preferences and the suppression list. That split is the
+// module boundary: a module cannot send mail (§1.2) and this is not the back door.
+//
+// **Never throws, never blocks ingest.** `ingest()` calls this fire-and-forget
+// exactly as it calls the broadcast and the push dispatch, and every mapper below
+// is wrapped so one bad frame cannot stop the feed. This is the same reason the
+// C# side's `Emit()` enqueues and returns rather than touching the socket from the
+// Core thread.
+//
+// ── Three things that are NOT a plain field mapping ────────────────────────
+//
+// Most of §8.6's rows are "read four fields off the frame and emit". Three are
+// not, and each is here rather than in a rule because a rule cannot express it:
+//
+//   1. **Transitions.** `champ.update` and `city.update` are full-state UPSERTS
+//      re-emitted on any change, not discrete "started"/"elected" events. Without
+//      a per-process transition tracker, a reconnect snapshot is read as twenty
+//      champion spawns starting at once. `shardStreams.js` already solved this for
+//      push and this file uses the same shape — and the same rule that a FIRST
+//      sighting is never a transition.
+//   2. **Thresholds.** `uo.vendor.expiring` and `uo.economy.milestone` fire when a
+//      value CROSSES a line. `conditions.js` compares a declared variable against
+//      a literal and has no relative-time or previous-value operator, so
+//      "within 24 hours of dismissal" and "gold passed a billion" are not
+//      expressible as conditions — and `vendor.listing` is a sweep frame
+//      re-emitted on every price change, so emitting per frame would flood. The
+//      crossing is tracked here; the operator still narrows with
+//      `hoursRemaining is at most N`.
+//   3. **Audience resolution for `members`.** A guild event is about the members
+//      of THAT guild, which is a different answer for every firing and therefore
+//      cannot be a saved segment (whose params are constants). The access-checked
+//      set travels on the envelope as `recipientUserIds` — Phase 6's decision 2,
+//      and the mechanism the Team fan-out was built on.
+
+const shardLinks = require('../model/shardLinks/shardLinks.model')
+const shardState = require('../model/shardState/shardState.model')
+const { TRIGGER_IDS } = require('../config/shardTriggers')
+const core = require('../core')
+
+const log = core.logger('shard-engagement')
+
+// ── Thresholds ─────────────────────────────────────────────────────────────
+
+// When a vendor becomes "expiring". Hours rather than pay periods, because a pay
+// period is a real day under the new vendor system and a UO day (~2 real hours)
+// under the old one — the exact factor-of-twelve trap `docs/link/v5.md` records,
+// and the reason the wire carries `dismissalAt` as an instant.
+//
+// 48 hours is one full real day of warning even on a shard whose owner logs in
+// daily, and it is the OUTER edge: the mapper fires once on the way in, and the
+// operator narrows further with `hoursRemaining is at most 24` if they want less.
+const VENDOR_WARN_HOURS = 48
+
+// Gold-supply reporting lines, ascending. Crossing one in either direction is one
+// `uo.economy.milestone`. They are the module's rather than the operator's for
+// now: an admin-configurable ladder is a settings surface, and this phase's job
+// is the trigger. An operator who wants a different line writes a rule condition
+// on `value`.
+const GOLD_THRESHOLDS = [
+  100_000_000, 250_000_000, 500_000_000, 1_000_000_000,
+  2_500_000_000, 5_000_000_000, 10_000_000_000,
+]
+
+// The same, for account count.
+const ACCOUNT_THRESHOLDS = [100, 250, 500, 1000, 2500, 5000, 10_000]
+
+// Which line a value sits above, as an index. -1 means "below the first".
+const bandOf = (value, thresholds) => {
+  let band = -1
+  for (let i = 0; i < thresholds.length; i += 1) if (value >= thresholds[i]) band = i
+  return band
+}
+
+// ── The transition tracker ─────────────────────────────────────────────────
+
+/**
+ * Per-process state for the upsert kinds and the threshold kinds.
+ *
+ * Injectable so a test gets a fresh one; a module-level default backs the live
+ * dispatcher. It is deliberately NOT persisted: its whole job is to say "has
+ * this process seen a previous value", and a value restored from a database
+ * would make the first frame after a restart a transition against state the
+ * shard may have left behind hours ago.
+ */
+function createTracker() {
+  return {
+    champActive: new Map(), // spawn serial → boolean
+    champBossUp: new Map(), // spawn serial → boolean
+    cityGovernor: new Map(), // city → governor serial or null
+    cityPhase: new Map(), // city → electionPhase
+    vendorWarned: new Map(), // vendor serial → boolean (already inside the window)
+    pointsLeader: new Map(), // points system → leader serial
+    economyBand: new Map(), // metric → band index
+    serverUp: null, // boolean or null (never seen)
+  }
+}
+const defaultTracker = createTracker()
+
+/** Reset the module-level tracker. For tests and for `shardIngest.reset()`. */
+function reset() {
+  const fresh = createTracker()
+  for (const key of Object.keys(fresh)) defaultTracker[key] = fresh[key]
+}
+
+// ── Small shared shapes ────────────────────────────────────────────────────
+
+// "Felucca 1480, 1600" — one string rather than four variables, because a
+// template that has to assemble coordinates is a template every author gets
+// slightly differently. Returns undefined when there is nothing to format, so it
+// drops out of an optional variable rather than rendering "undefined , ".
+function place(ev) {
+  const map = ev.map || (ev.location && ev.location.map)
+  const x = ev.x ?? (ev.location && ev.location.x)
+  const y = ev.y ?? (ev.location && ev.location.y)
+  if (!map && x == null) return undefined
+  const coords = x == null || y == null ? '' : ` ${x}, ${y}`
+  const region = ev.region || (ev.location && ev.location.region)
+  const suffix = region ? ` (${region})` : ''
+  return `${map || ''}${coords}${suffix}`.trim() || undefined
+}
+
+// An actor object's display name, whichever of the shard's shapes it arrives in.
+const actorName = (actor) => (actor && typeof actor === 'object' ? actor.name : undefined) || undefined
+const actorAcct = (actor) => (actor && typeof actor === 'object' ? actor.acct : undefined) || undefined
+
+// Drop the undefined values before they reach `emit`. A declared OPTIONAL
+// variable that arrives as `undefined` is dropped by `validatePayload` anyway,
+// but building the object without them keeps the emit log's `variables` list
+// honest about what the frame actually carried.
+const defined = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined))
+
+// ── The mappers ────────────────────────────────────────────────────────────
+//
+// Each returns an array of `{ triggerId, data, ownerAccount?, guildId?, subject?,
+// dedupeKey? }`. Resolution — account → user id, guild → member ids — happens in
+// `dispatch` below, because it needs the database and these must not.
+//
+// `ownerAccount` is the same field name `shardStreams.js` uses for the same idea,
+// so the two mappers can be read side by side.
+
+const decayName = (ev) => ev.name || undefined
+
+const MAPPERS = {
+  // ── Owned asset at risk ────────────────────────────────────────────────
+  'house.decay': (ev, tracker, out) => {
+    const to = String(ev.to || '').toUpperCase()
+    const serial = ev.serial == null ? null : String(ev.serial)
+    if (!serial) return
+    // COLLAPSED is its own trigger; the late stages are the warning. `LikeNew`
+    // and the early stages are not news — a house being refreshed is the normal
+    // case and mailing it would make the warning worthless.
+    if (to === 'COLLAPSED') {
+      out.push({
+        triggerId: 'uo.house.collapsed',
+        ownerAccount: ev.ownerAcct,
+        data: defined({
+          houseSerial: serial,
+          houseName: decayName(ev),
+          region: ev.region || undefined,
+          location: place(ev),
+        }),
+      })
+      return
+    }
+    if (!['FAIRLY', 'GREATLY', 'IDOC'].includes(to)) return
+    const schedule = ev.schedule && typeof ev.schedule === 'object' ? ev.schedule : {}
+    out.push({
+      triggerId: 'uo.house.idoc_warning',
+      ownerAccount: ev.ownerAcct,
+      data: defined({
+        houseSerial: serial,
+        houseName: decayName(ev),
+        stage: ev.to,
+        previousStage: ev.from || undefined,
+        region: ev.region || undefined,
+        location: place(ev),
+        // **Both optional, and both genuinely absent much of the time.** A v4
+        // overlay sends no `schedule` at all; a dynamic-decay shard omits
+        // `estimatedCollapse` at every stage before IDOC because ServUO draws
+        // each stage's duration at random when the stage is entered. Passing
+        // `undefined` through is the honest thing — `docs/link/v5.md` is explicit
+        // that absence means "not knowable", never "not yet read", and computing
+        // a fallback here would republish exactly the guess the shard refused to.
+        nextStage: schedule.nextStage || undefined,
+        estimatedCollapse: schedule.estimatedCollapse || undefined,
+        lastRefreshed: ev.lastRefreshed || undefined,
+      }),
+    })
+  },
+
+  // `house.remove` carries ONLY a serial — the house is gone, so the frame has
+  // nothing else to say. The owner comes from this module's own registry mirror,
+  // which is a database read and therefore happens in `dispatch`.
+  'house.remove': (ev, tracker, out) => {
+    if (ev.serial == null) return
+    out.push({
+      triggerId: 'uo.house.collapsed',
+      houseSerial: String(ev.serial),
+      data: { houseSerial: String(ev.serial) },
+    })
+  },
+
+  'vendor.listing': (ev, tracker, out) => {
+    const serial = ev.serial == null ? null : String(ev.serial)
+    if (!serial || !ev.ownerAcct) return
+    const fees = ev.fees && typeof ev.fees === 'object' ? ev.fees : null
+    // A pre-v5 overlay sends no `fees`; a commission vendor sends `{exempt:true}`
+    // and is NEVER dismissed for them. Both mean "nothing to warn about", and
+    // conflating exempt with a distant date is how a vendor that cannot expire
+    // ends up in an expiry warning (`docs/link/v5.md`).
+    if (!fees || fees.exempt === true || !fees.dismissalAt) {
+      tracker.vendorWarned.delete(serial)
+      return
+    }
+    const at = new Date(fees.dismissalAt)
+    if (Number.isNaN(at.getTime())) return
+    const hours = Math.floor((at.getTime() - Date.now()) / 3_600_000)
+    const inWindow = hours <= VENDOR_WARN_HOURS
+    const wasWarned = tracker.vendorWarned.get(serial) === true
+    tracker.vendorWarned.set(serial, inWindow)
+    // **Only the CROSSING.** The sweep re-emits a shop on any price change, so
+    // without this a vendor inside the window mails its owner every time somebody
+    // reprices a longsword. Leaving the window (a deposit) clears the flag above,
+    // so the next approach warns again — which is the behaviour an owner wants.
+    if (!inWindow || wasWarned) return
+    out.push({
+      triggerId: 'uo.vendor.expiring',
+      ownerAccount: ev.ownerAcct,
+      data: defined({
+        vendorSerial: serial,
+        shopName: ev.shopName || undefined,
+        dismissalAt: fees.dismissalAt,
+        // Never negative: a vendor already past its dismissal tick is being
+        // destroyed, and "-3 hours remaining" in a mail is worse than "0".
+        hoursRemaining: Math.max(0, hours),
+        periodsRemaining: Number.isFinite(fees.periodsRemaining) ? fees.periodsRemaining : undefined,
+        funds: Number.isFinite(fees.funds) ? fees.funds : undefined,
+        chargePerPeriod: Number.isFinite(fees.chargePerPeriod) ? fees.chargePerPeriod : undefined,
+        location: place(ev),
+      }),
+    })
+  },
+
+  'vendor.listing.remove': (ev, tracker) => {
+    if (ev.serial != null) tracker.vendorWarned.delete(String(ev.serial))
+  },
+
+  // ── Passive income ─────────────────────────────────────────────────────
+  'vendor.sale': (ev, tracker, out) => {
+    if (!ev.ownerAcct) return
+    out.push({
+      triggerId: 'uo.vendor.sale',
+      ownerAccount: ev.ownerAcct,
+      data: defined({
+        vendorSerial: String(ev.vendorSerial ?? ''),
+        itemName: ev.itemType || 'an item',
+        amount: Number.isFinite(ev.amount) ? ev.amount : undefined,
+        price: Number.isFinite(ev.price) ? ev.price : 0,
+        commission: Number.isFinite(ev.commission) ? ev.commission : undefined,
+      }),
+    })
+  },
+
+  // ── Personal security ──────────────────────────────────────────────────
+  //
+  // **`account.login.result` and NOT `account.login.attempt`.** The attempt fires
+  // from `EventSink.AccountLogin`, which runs before the auth decision — the
+  // emitter's own comment says so — and `AccountLoginEventArgs` constructs with
+  // `Accepted = true`, so a rule on it would have mailed a security alert every
+  // time the player logged in successfully. That inversion is why protocol 5 adds
+  // this kind and why the trigger is named `login_failed` rather than `attempt`.
+  'account.login.result': (ev, tracker, out) => {
+    if (!ev.acct) return
+    if (ev.accepted !== false) return
+    out.push({
+      triggerId: 'uo.account.login_failed',
+      ownerAccount: ev.acct,
+      data: defined({
+        account: String(ev.acct),
+        reason: ev.reason || undefined,
+        ip: ev.ip || undefined,
+      }),
+    })
+  },
+
+  // **Resolved BEFORE ingest drops the link mirror**, which is the whole reason
+  // this file is called from `ingest()` ahead of the state write rather than
+  // after it. `applyStateChange` removes the `shard_account_links` row for this
+  // account, so an owner lookup that ran afterwards would find nobody and the one
+  // person who needs to know their account was unlinked would never be told.
+  'account.unlinked': (ev, tracker, out) => {
+    if (!ev.account) return
+    out.push({
+      triggerId: 'uo.account.unlinked',
+      ownerAccount: ev.account,
+      data: defined({
+        account: String(ev.account),
+        characterName: ev.char || undefined,
+      }),
+    })
+  },
+
+  // ── Personal milestone ─────────────────────────────────────────────────
+  'skill.gain': (ev, tracker, out) => {
+    // The cap, and only the cap. `skill.gain` fires on every tenth of a point;
+    // `base >= cap` is the milestone and everything else is noise.
+    if (!Number.isFinite(ev.base) || !Number.isFinite(ev.cap) || ev.base < ev.cap) return
+    const acct = actorAcct(ev.who)
+    if (!acct) return
+    out.push({
+      triggerId: 'uo.skill.capped',
+      ownerAccount: acct,
+      data: defined({
+        characterName: actorName(ev.who) || 'your character',
+        skill: String(ev.skill || 'a skill'),
+        cap: ev.cap,
+      }),
+    })
+  },
+
+  'quest.complete': (ev, tracker, out) => {
+    const acct = actorAcct(ev.who)
+    if (!acct) return
+    out.push({
+      triggerId: 'uo.quest.complete',
+      ownerAccount: acct,
+      data: defined({
+        characterName: actorName(ev.who) || 'your character',
+        quest: String(ev.quest || 'a quest'),
+      }),
+    })
+  },
+
+  'player.death': (ev, tracker, out) => {
+    const acct = actorAcct(ev.who)
+    if (!acct) return
+    out.push({
+      triggerId: 'uo.character.death',
+      ownerAccount: acct,
+      data: defined({
+        characterName: actorName(ev.who) || 'your character',
+        killerName: actorName(ev.killer),
+      }),
+    })
+  },
+
+  'player.murdered': (ev, tracker, out) => {
+    const acct = actorAcct(ev.victim)
+    if (!acct) return
+    out.push({
+      triggerId: 'uo.character.murdered',
+      ownerAccount: acct,
+      data: defined({
+        characterName: actorName(ev.victim) || 'your character',
+        murdererName: actorName(ev.murderer),
+      }),
+    })
+  },
+
+  // ── Social / civic ─────────────────────────────────────────────────────
+  //
+  // `uo.guild.joined` is NOT here: core's `team.member.joined` already fires for
+  // it on every roster reconcile, because a UO guild is a Team and this module is
+  // the Team provider. See ENGAGEMENT.md §8.6 for the carve-out.
+  'guild.leave': (ev, tracker, out) => {
+    if (ev.id == null) return
+    out.push({
+      triggerId: 'uo.guild.left',
+      guildId: ev.id,
+      // `who` is a bare SERIAL string here, not an actor object — the mobile has
+      // already left, so there is nothing for the shard to attribute. The name is
+      // looked up from the roster mirror in `dispatch`.
+      memberSerial: ev.who == null ? null : String(ev.who),
+      data: defined({ guildName: ev.name || `guild ${ev.id}` }),
+    })
+  },
+
+  'guild.remove': (ev, tracker, out) => {
+    if (ev.id == null) return
+    out.push({
+      triggerId: 'uo.guild.disbanded',
+      guildId: ev.id,
+      // The frame carries ONLY the id, so the name comes from the board mirror in
+      // `dispatch` — and it has to be read there before `applyStateChange` drops
+      // the row, the same ordering `account.unlinked` depends on.
+      data: {},
+    })
+  },
+
+  'city.update': (ev, tracker, out) => {
+    const { city } = ev
+    if (!city) return
+
+    // A new governor. Never on FIRST sight (`prev === undefined`), so a reconnect
+    // snapshot is not read as eight simultaneous elections.
+    const gov = ev.governor && ev.governor.serial != null ? String(ev.governor.serial) : null
+    const prevGov = tracker.cityGovernor.get(city)
+    tracker.cityGovernor.set(city, gov)
+    if (prevGov !== undefined && gov && gov !== prevGov) {
+      out.push({
+        triggerId: 'uo.governor.elected',
+        data: defined({
+          city: String(city),
+          governorName: actorName(ev.governor) || 'a new governor',
+          previousGovernorName: undefined,
+        }),
+      })
+    }
+
+    // An election opening. `autoPickAt` is REQUIRED on the trigger, so a phase
+    // change that arrives without one is not emitted at all rather than emitted
+    // as a deadline-less call to action — which is what a "vote now" mail with
+    // nothing to act by would be.
+    const phase = ev.electionPhase || 'none'
+    const prevPhase = tracker.cityPhase.get(city)
+    tracker.cityPhase.set(city, phase)
+    if (
+      prevPhase !== undefined
+      && phase !== prevPhase
+      && (phase === 'nominate' || phase === 'vote')
+      && ev.autoPickAt
+    ) {
+      out.push({
+        triggerId: 'uo.election.opened',
+        data: defined({
+          city: String(city),
+          phase,
+          autoPickAt: ev.autoPickAt,
+          candidates: Number.isFinite(ev.candidates) ? ev.candidates : undefined,
+        }),
+      })
+    }
+  },
+
+  // ── Come online now ────────────────────────────────────────────────────
+  'champ.update': (ev, tracker, out) => {
+    const serial = ev.serial == null ? null : String(ev.serial)
+    if (!serial) return
+    const isActive = ev.active === true
+    const wasActive = tracker.champActive.get(serial)
+    tracker.champActive.set(serial, isActive)
+
+    const base = defined({
+      spawnSerial: serial,
+      spawnName: ev.name || ev.type || 'a champion spawn',
+      category: ev.category || undefined,
+      location: place(ev),
+    })
+
+    if (wasActive !== undefined && isActive && wasActive !== true) {
+      out.push({ triggerId: 'uo.champ.started', data: base })
+    }
+
+    const bossUp = ev.bossUp === true
+    const wasBossUp = tracker.champBossUp.get(serial)
+    tracker.champBossUp.set(serial, bossUp)
+    if (wasBossUp !== undefined && bossUp && wasBossUp !== true) {
+      out.push({
+        triggerId: 'uo.champ.boss_up',
+        data: defined({ ...base, bossName: ev.boss || undefined }),
+      })
+    }
+  },
+
+  'champ.remove': (ev, tracker) => {
+    if (ev.serial == null) return
+    tracker.champActive.delete(String(ev.serial))
+    tracker.champBossUp.delete(String(ev.serial))
+  },
+
+  // **`server.hello` fires on every sidecar reconnect, not only on a shard
+  // restart** — which is exactly the flapping this trigger must not amplify. The
+  // tracker's `serverUp` is the guard: a hello while we already believe the shard
+  // is up is a reconnect and emits nothing. The seeded rule's hard cooldown is the
+  // second line of defence, for a shard genuinely bouncing.
+  'server.hello': (ev, tracker, out) => {
+    const wasUp = tracker.serverUp
+    tracker.serverUp = true
+    if (wasUp === true) return
+    out.push({
+      triggerId: 'uo.server.up',
+      data: defined({ shardName: ev.shard || undefined }),
+    })
+  },
+
+  'server.shutdown': (ev, tracker, out) => {
+    if (tracker.serverUp === false) return
+    tracker.serverUp = false
+    out.push({ triggerId: 'uo.server.down', data: { clean: true } })
+  },
+
+  'server.crashed': (ev, tracker, out) => {
+    if (tracker.serverUp === false) return
+    tracker.serverUp = false
+    out.push({ triggerId: 'uo.server.down', data: { clean: false } })
+  },
+
+  // ── Leaderboard ────────────────────────────────────────────────────────
+  //
+  // `subscribers` only. `top[]` names a mobile SERIAL and `shard_account_links`
+  // is keyed by game ACCOUNT, so the "you were pushed out" half of §8.6's row is
+  // carved out rather than resolved for whoever happens to be online.
+  'points.board': (ev, tracker, out) => {
+    const system = ev.system
+    const top = Array.isArray(ev.top) ? ev.top : []
+    if (!system || !top.length) return
+    const leader = top.find((e) => e && e.rank === 1) || top[0]
+    if (!leader || leader.serial == null) return
+    const serial = String(leader.serial)
+    const prev = tracker.pointsLeader.get(system)
+    tracker.pointsLeader.set(system, serial)
+    if (prev === undefined || prev === serial) return
+    out.push({
+      triggerId: 'uo.points.rank_changed',
+      data: defined({
+        system: String(system),
+        systemName: ev.nameString || undefined,
+        leaderName: leader.name || 'a new leader',
+        points: Number.isFinite(leader.points) ? leader.points : undefined,
+      }),
+    })
+  },
+
+  // ── Staff-facing ───────────────────────────────────────────────────────
+  'page.new': (ev, tracker, out) => {
+    out.push({
+      triggerId: 'uo.page.new',
+      data: defined({
+        pageType: String(ev.type || 'Other'),
+        senderName: actorName(ev.sender),
+        message: ev.message || undefined,
+        location: place(ev),
+      }),
+    })
+  },
+
+  'cheat.fastwalk': (ev, tracker, out) => {
+    out.push({
+      triggerId: 'uo.cheat.detected',
+      data: defined({
+        characterName: actorName(ev.who) || 'an unnamed character',
+        account: actorAcct(ev.who),
+        ip: ev.ip || undefined,
+        detector: 'fastwalk',
+      }),
+    })
+  },
+
+  // ── Operator-facing ────────────────────────────────────────────────────
+  'audit.set': (ev, tracker, out) => {
+    out.push({
+      triggerId: 'uo.audit.staff_action',
+      data: defined({
+        staffName: actorName(ev.staff) || (typeof ev.staff === 'string' ? ev.staff : undefined),
+        action: 'set',
+        detail: ev.prop ? `${ev.prop}: ${ev.old ?? '?'} → ${ev.new ?? '?'}` : undefined,
+        target: ev.target || undefined,
+        origin: 'in-game',
+      }),
+    })
+  },
+
+  'audit.command': (ev, tracker, out) => {
+    out.push({
+      triggerId: 'uo.audit.staff_action',
+      data: defined({
+        staffName: actorName(ev.staff) || (typeof ev.staff === 'string' ? ev.staff : undefined),
+        action: 'command',
+        detail: ev.command ? `${ev.command} ${ev.args || ''}`.trim() : undefined,
+        origin: 'in-game',
+      }),
+    })
+  },
+
+  'admin.audit': (ev, tracker, out) => {
+    out.push({
+      triggerId: 'uo.audit.staff_action',
+      data: defined({
+        staffName: typeof ev.actor === 'string' ? ev.actor : actorName(ev.actor),
+        action: String(ev.action || 'action'),
+        detail: ev.reason || undefined,
+        target: ev.target || undefined,
+        origin: ev.origin || undefined,
+      }),
+    })
+  },
+
+  'economy.supply': (ev, tracker, out) => {
+    for (const [metric, value, thresholds] of [
+      ['gold', ev.gold, GOLD_THRESHOLDS],
+      ['accounts', ev.accounts, ACCOUNT_THRESHOLDS],
+    ]) {
+      if (!Number.isFinite(value)) continue
+      const band = bandOf(value, thresholds)
+      const prev = tracker.economyBand.get(metric)
+      tracker.economyBand.set(metric, band)
+      // First sighting establishes the band and reports nothing. Otherwise a
+      // sidecar reconnect on a mature shard announces "gold passed a billion"
+      // about a line it crossed months ago.
+      if (prev === undefined || prev === band) continue
+      // The line that was crossed is the HIGHER of the two bands under a rise and
+      // the one just left under a fall, so both directions name the line the
+      // reader is thinking about.
+      const crossed = band > prev ? thresholds[band] : thresholds[prev]
+      out.push({
+        triggerId: 'uo.economy.milestone',
+        data: defined({
+          metric,
+          value: Math.round(value),
+          threshold: crossed,
+          direction: band > prev ? 'up' : 'down',
+        }),
+      })
+    }
+  },
+
+  'world.save.after': (ev, tracker, out) => {
+    out.push({
+      triggerId: 'uo.world.saved',
+      data: defined({
+        items: Number.isFinite(ev.items) ? ev.items : undefined,
+        mobiles: Number.isFinite(ev.mobiles) ? ev.mobiles : undefined,
+      }),
+    })
+  },
+}
+
+/**
+ * Map one shard event to zero or more engagement events. Pure given `tracker`.
+ *
+ * Exported so the mapping can be tested without a database, exactly as
+ * `shardStreams.mapShardEvent` is.
+ */
+function mapShardEvent(event, tracker = defaultTracker) {
+  if (!event || typeof event.kind !== 'string') return []
+  const mapper = MAPPERS[event.kind]
+  if (!mapper) return []
+  const out = []
+  mapper(event, tracker, out)
+  // **Defence in depth, and the exact counterpart of `shardStreams.js`'s
+  // public-allowlist filter.** A target naming an id this module does not declare
+  // cannot be delivered — `emit` would refuse it anyway, throwing in dev and
+  // logging in prod — so catching it here turns a typo into one warning with the
+  // id in it rather than an exception on the ingest path.
+  return out.filter((t) => {
+    if (TRIGGER_IDS.has(t.triggerId)) return true
+    log.warn('mapper produced an undeclared trigger id', { kind: event.kind, triggerId: t.triggerId })
+    return false
+  })
+}
+
+// ── Resolution and dispatch ────────────────────────────────────────────────
+
+/**
+ * Turn one mapped target into the envelope `ctx.events.emit` takes, or null when
+ * there is nobody to tell.
+ *
+ * This is the half that reaches the database, and it is why the mapping above is
+ * separate: an owner-keyed target names a GAME ACCOUNT and a members-keyed one
+ * names a GUILD, and neither is a website user until something asks.
+ */
+async function resolveTarget(target, deps) {
+  const { links, state } = deps
+  const data = { ...target.data }
+
+  // `owner` — one account, one user. An unlinked account is nobody to notify,
+  // which is a normal outcome and not an error: most game accounts on most shards
+  // have never been linked.
+  if (target.ownerAccount) {
+    const link = await links.getByAccount(target.ownerAccount)
+    if (!link || link.user_id == null) return null
+    return { data, ownerUserId: Number(link.user_id) }
+  }
+
+  // `uo.house.collapsed` off `house.remove`, whose frame carries only a serial.
+  // The owner comes from this module's registry mirror — and this read has to
+  // happen before `applyStateChange` drops the row, which is why ingest calls the
+  // engagement fan-out ahead of the state write.
+  if (target.houseSerial) {
+    const houses = await state.listHouses()
+    const house = houses.find((h) => String(h.serial) === target.houseSerial)
+    if (!house || !house.ownerAcct) return null
+    const link = await links.getByAccount(house.ownerAcct)
+    if (!link || link.user_id == null) return null
+    if (house.name) data.houseName = house.name
+    if (house.region) data.region = house.region
+    return { data, ownerUserId: Number(link.user_id) }
+  }
+
+  // `members` — the guild's roster, resolved to website users through
+  // `shard_account_links` rather than through the roster's mirrored `web_id`.
+  // The mirror is a copy of what the wire said; the links table is the answer.
+  if (target.guildId != null) {
+    const accounts = await state.listGuildMemberAccounts(target.guildId)
+    const userIds = await links.userIdsForAccounts(accounts)
+    if (!userIds.length) return null
+
+    // Fill in the two names the frames do not carry, from the board mirror.
+    if (!data.guildName || !data.abbreviation) {
+      const guilds = await state.listGuilds()
+      const guild = guilds.find((g) => String(g.id) === String(target.guildId))
+      if (guild) {
+        if (!data.guildName) data.guildName = guild.name || `guild ${target.guildId}`
+        if (guild.abbr && data.abbreviation === undefined) data.abbreviation = guild.abbr
+      }
+    }
+    if (!data.guildName) data.guildName = `guild ${target.guildId}`
+
+    // Who left, from the roster mirror — the departing member's row is still
+    // there, because `guild.leave`'s state write has not run yet.
+    if (target.memberSerial) {
+      const members = await state.listGuildMembers(target.guildId)
+      const gone = members.find((m) => String(m.serial) === target.memberSerial)
+      if (gone && gone.name) data.memberName = gone.name
+    }
+    return { data, recipientUserIds: userIds }
+  }
+
+  // Everything else — `subscribers`, `staff`, `admin` — has no per-event
+  // audience to resolve. The rule's audience is the whole answer.
+  return { data }
+}
+
+/**
+ * Fan one shard event out to the engagement engine.
+ *
+ * Never throws. Called fire-and-forget from `shardIngest.ingest`, beside the SSE
+ * broadcast and the push dispatch, and held to the same promise all three make:
+ * a slow or failing notification path must never delay or fail ingest.
+ */
+async function fromShardEvent(event, deps = {}) {
+  const d = {
+    links: deps.shardLinks || shardLinks,
+    state: deps.shardState || shardState,
+    emit: deps.emit || core.events.emit,
+    tracker: deps.tracker || defaultTracker,
+  }
+
+  for (const target of mapShardEvent(event, d.tracker)) {
+    try {
+      const resolved = await resolveTarget(target, d)
+      // Nobody to tell. Not an error and deliberately not logged at warn: an
+      // unlinked house owner is the common case on every shard.
+      if (!resolved) continue
+      d.emit(target.triggerId, {
+        data: resolved.data,
+        ...(resolved.ownerUserId ? { ownerUserId: resolved.ownerUserId } : {}),
+        ...(resolved.recipientUserIds ? { recipientUserIds: resolved.recipientUserIds } : {}),
+        ...(target.dedupeKey ? { dedupeKey: target.dedupeKey } : {}),
+        occurredAt: Number.isFinite(event.t) ? new Date(event.t) : undefined,
+      })
+    } catch (err) {
+      log.warn('engagement target failed', { triggerId: target.triggerId, message: err.message })
+    }
+  }
+}
+
+module.exports = {
+  fromShardEvent,
+  mapShardEvent,
+  createTracker,
+  reset,
+  VENDOR_WARN_HOURS,
+  GOLD_THRESHOLDS,
+  ACCOUNT_THRESHOLDS,
+}

server/utils/shardIngest.js

@@ -20,6 +20,7 @@ const uoLinkConfigModel = require('../model/uoLinkConfig/uoLinkConfig.model')
 const { settings: settingsModel } = require('../core')
 const broadcaster = require('./shardBroadcast')
 const shardPush = require('./shardPush')
+const shardEngagement = require('./shardEngagement')
 const defaultLog = require('../core').logger('shard-ingest')
 
 // Notable kinds appended to the shard_events log. High-frequency/session kinds
@@ -62,6 +63,11 @@ const LOGGED_KINDS = new Set([
 const state = { bootId: null }
 function reset() {
   state.bootId = null
+  // The engagement mapper's transition/threshold tracker is per-process state of
+  // exactly the same kind as `bootId`, so it is reset by the same call. A test
+  // that reset one and not the other would see a champion spawn that started in
+  // the previous test.
+  shardEngagement.reset()
 }
 
 // Should this event be written to the append-only log?
@@ -169,8 +175,14 @@ async function applyStateChange(event, deps) {
         name: event.name,
         ownerSerial: event.ownerSerial,
         ownerAcct: event.ownerAcct,
+        // Protocol 5. `ownerName` used to arrive only on house.update, so a house
+        // that had decayed but never been swept into the registry named an account
+        // and no character. It rides house.decay now, which is the frame the IDOC
+        // page is actually built from.
+        ownerName: event.ownerName,
         builtOn: event.builtOn,
         lastRefreshed: event.lastRefreshed,
+        schedule: event.schedule,
       })
       return
     case 'champ.update':
@@ -279,6 +291,7 @@ function resolveDeps(deps) {
     settings: deps.settings || settingsModel,
     broadcast: deps.broadcast || broadcaster.broadcast,
     pushDispatch: deps.pushDispatch || shardPush.fromShardEvent,
+    engagement: deps.engagement || shardEngagement.fromShardEvent,
     log: deps.log || defaultLog,
   }
 }
@@ -294,6 +307,34 @@ async function ingest(event, deps = {}) {
   let stored = false
   let logged = false
 
+  // **The engagement fan-out runs BEFORE the state write, and that ordering is
+  // load-bearing rather than incidental** (ENGAGEMENT.md Phase 11). Three of the
+  // mappings read a row that `applyStateChange` is about to delete or replace:
+  //
+  //   • `account.unlinked` drops the `shard_account_links` row — the row that
+  //     turns the account into the one person who needs to be told it was
+  //     unlinked. Resolving afterwards finds nobody, every time.
+  //   • `house.remove` drops the house, whose stored `ownerAcct` is the only place
+  //     the owner of a collapsed house is named (the frame carries a serial alone).
+  //   • `guild.leave` / `guild.remove` need the roster and the board mirror to
+  //     name who left and which guild it was.
+  //
+  // Awaited, unlike the broadcast and the push tickle below, and this is the one
+  // place this file waits on a notification path. It has to: the whole point is
+  // that the read happens first, and a fire-and-forget promise would race the
+  // DELETE it is trying to precede. `fromShardEvent` never throws and never opens
+  // a socket — it resolves ids and hands the engine an envelope, which does its
+  // own work off the caller's stack (`emit` is deliberately not awaited inside).
+  // Backfilled frames are excluded for the same reason the broadcast is: a
+  // reconnect replay must not re-notify anyone about events from hours ago.
+  if (!deps.fromBackfill) {
+    try {
+      await d.engagement(event)
+    } catch (err) {
+      d.log.warn('engagement fan-out failed', { kind: event.kind, message: err.message })
+    }
+  }
+
   try {
     await applyStateChange(event, d)
   } catch (err) {

server/utils/shardVisibility.js

@@ -91,9 +91,22 @@ const FEATURES = {
   // `ownerName`/`ownerSerial` are the flattened spellings shapeHouse emits on the
   // REST read models. Both are listed so one rule covers the wire and the read
   // model — the flattened `ownerAcct` needs no entry, being locked by rule 1.
+  // Protocol 5 adds `schedule` — when the next stage lands and, where ServUO can
+  // actually know it, when the house collapses. It defaults to `anonymous` because
+  // that is what the public IDOC page is FOR: the countdown is the content, and a
+  // house at IDOC is already announced in game. It is listed rather than left
+  // unconfigurable so a shard that considers a precise collapse time an unfair
+  // advantage can raise it, and it is one NESTED key so raising it hides the whole
+  // schedule rather than three of its four parts.
   houses: {
     audience: 'anonymous',
-    fields: { owner: 'staff', ownerName: 'staff', ownerSerial: 'staff', price: 'staff' },
+    fields: {
+      owner: 'staff',
+      ownerName: 'staff',
+      ownerSerial: 'staff',
+      price: 'staff',
+      schedule: 'anonymous',
+    },
   },
   // /public/shard/online listed linked staff to everyone but gated location to
   // admin+moderator — which is exactly the `staff` rung.
@@ -124,9 +137,25 @@ const FEATURES = {
   // `ownerSerial` is listed alongside `ownerName` for the same reason `houses`
   // lists both: an admin who hides the owner's name and is left with a serial
   // that every other board resolves back to that name has not hidden anything.
+  // Protocol 5 adds `fees`, and it does NOT follow the rest of this feature's
+  // defaults. The shop name, the owner and the location are already visible to any
+  // player through the stock in-game Vendor Search gump, which is the whole argument
+  // for publishing them. A vendor's held gold, daily charge and dismissal date are
+  // not: in game they are visible to the OWNER, on that vendor's own gump. Publishing
+  // them anonymously would be a genuinely new disclosure and a targeting aid — it
+  // says which shops are about to be abandoned and how much coin is sitting in each.
+  // So it defaults to `admin`, the only default here that does not reproduce prior
+  // behaviour, because there is no prior behaviour to reproduce.
+  //
+  // Nested for the same reason `location` is: one rule covers all seven parts.
   market: {
     audience: 'anonymous',
-    fields: { ownerName: 'anonymous', ownerSerial: 'anonymous', location: 'anonymous' },
+    fields: {
+      ownerName: 'anonymous',
+      ownerSerial: 'anonymous',
+      location: 'anonymous',
+      fees: 'admin',
+    },
   },
 }
 
@@ -177,6 +206,13 @@ const KIND_FEATURE = new Map(
     // registry (house.update / house.remove — owner, price, co-owners) stays
     // off the map deliberately, so it remains admin-only exactly as before.
     'house.decay': 'houses',
+    // Protocol 5's `account.login.result` is deliberately NOT here, and the omission
+    // is the decision rather than an oversight. Rule 2 fails an unmapped kind closed
+    // to admin-only, which is the right answer for a frame that carries an IP address
+    // and says whether a password was accepted — the same reasoning that keeps
+    // house.update and account.login.attempt off this map. Adding it would mean
+    // choosing a feature an admin could then widen, and there is no rung below admin
+    // this frame belongs on.
     // v3
     'world.ruleset': 'ruleset',
     'points.board': 'leaderboards',