docs/website/ENGAGEMENT.md

The Engagement System — findings and plan

Status: design of record. The workstream is COMPLETE (2026-09-01). Phases 0 through 14 are done and on main in every repository, and Phase 13's acceptance walk passed — a clean install from main, released artefacts only, one email and one in-app item to the linked owner and nothing to anyone else. It found two defects in shipped core; both are recorded in Phase 13's as-built and both were fixed afterwards (website#181). Phase 14 (retention) is BUILT — the last phase, and the one that gave the engagement schema a bound. Each phase carries its own as-built section below, and the PRs are named there rather than here.

The cutover cut link v2.1.0, the plugin overlay v1.1.0, module-uo v1.1.0 and the paired bundle 2026.09.01 (protocol 5); MODULE_API_VERSION is 1.9.0. Two of Phase 13's seven steps were missed in the window and landed afterwards — see its as-built, which is also where the four findings of the cutover itself are recorded.

Phases 10 and 11 were both widened on 2026-08-31, by the org lead, before any code: the protocol bump carries three wire enrichments rather than one, and Phase 11 ships every ✅ row of §8.6 rather than a single rule. Phase 11 was then scoped on the same day — six decisions, three carve-outs, a seventh value in the ceiling lattice and an 11a/11b split; see its own decision block. The scope decisions below are settled; all nine questions in §7.1 are answered — Q1, Q3, Q5 and Q7 on 2026-08-28, Q6 on 2026-08-29 at the start of Phase 2 (which also settled §7.2's namespace question), Q2 and Q4 on 2026-08-29 at the start of Phase 4, and Q8 on 2026-08-31 at the start of Phase 8. Q1's answer added a whole phase (Phase 1b, unique email addresses); Q4's answer and the phase's size split Phase 4 into 4a and 4b; Q9 (core's own news.post emitter) was answered 2026-08-31 at the start of Phase 11, along with five further decisions that changed what that phase ships — see its own decision block. Per CLAUDE.md § Conventions, no implementation starts without the org lead's approval of the phase it belongs to; Phase 14's six decisions were settled on 2026-09-01 before any of its code, and two of the four horizon answers widened it — see its as-built.

Branching: every phase landed on edge in its repo, and main was touched once, by the cutover (Phase 13). §6.0a records the blocking precondition it opened with — six edge branches stale, three repos with none — and Phase 13's as-built records how it closed: every edge was deleted on merge rather than fast-forwarded, which is the convention now. Phase 14 comes after the cutover and so goes to main through an ordinary feature branch.

Scope decisions, settled by the org lead (2026-08-28):

1. The in-app channel is in scope. It does not exist today and has to be built, not adapted.
2. The Teams notification pipeline is generalized and migrated onto the new system, not built beside it.
3. The house.decay protocol enrichment is in scope, as a coordinated four-repo PROTOCOL_VERSION bump. Widened 2026-08-31: that single bump now carries three enrichments (house decay, player-vendor fee state, and a post-decision login result), because a second bump would cost another release + bundle + operator update. See Phase 10.
4. Gmail OAuth2 is removed, not retained as a transport. SMTP is the baseline; the OAuth2 consent flow, its two routes, its borrowed Google client and its stored refresh token all go. See §1.2a for what that deletes and §6/Phase 1 for the operator cutover it forces.
5. The system ships with a seeded set of working templates and an editor, so a fresh deployment sends correctly-branded mail before anyone opens the editor. See §4.6.

Four further decisions, settled 2026-08-28 (recorded in full at §7.1, with the findings that shaped them in §0.6):

6. Engagement mail is opt-in only, and users.email becomes UNIQUE. Standard marketing-email practice applies: explicit opt-in, working unsubscribe, suppression. Uniqueness is not a detail — it is Phase 1b, because the column is nullable-and-duplicated by design today and three code paths break the moment an index is added. Whether an unverified address may receive opt-in mail is an admin setting, defaulting on for fresh installs and off for upgrades.
7. There is no campaigns surface. No operator-authored send screen, no free-form list building. An admin's expressive power lives in trigger conditions and rules.
8. Audiences are module-declared and operator-composable. A module registers named, queryable audiences over its own data (uo.team.members, uo.governors); core exposes the same registration surface to every module and learns no game vocabulary. An operator may compose declared audiences with and/or/not into a saved segment — and the composed result is still bounded by the trigger's G24 audience ceiling. See §5.1a.

---

Part 0 — Six findings that contradict the brief

Stated up front because the rest of the document is shaped by them.

0.1 There is no In-app channel. The target diagram's "existing In-app / Push" is one channel, not two

Core has exactly one notification sink: content-free push tickles to ntfy/UnifiedPush (website/server/src/utils/pushDispatch.js). There is no notification table, no read API, no mark-read, and no in-app list on either client. android-app/.../ui/notifications/NotificationsScreen.kt is a preferences screen. module-uo's SSE stream (server/utils/shardBroadcast.js) is a live game feed, not an inbox.

So "add Email as a third channel" is really add two channels to a system that has one, and the in-app one needs its own storage, read API and two client surfaces.

0.2 Email is already two-thirds of an engagement system — scoped to Teams

The brief frames the current email implementation as "the Gmail OAuth2 code". Gmail OAuth2 is only the transport. Sitting on top of it, utils/teamNotify.js + utils/teamDigestWorker.js + team_notification_prefs already implement:

Engagement concern	Where it already lives
Trigger → recipient selection	teamNotify.js:recipientIds / emailRecipients via the Team access resolver
Per-user opt-in, per-scope	team_notification_prefs.email_mode ENUM('off','digest','immediate') (schema.sql:1285)
Immediate vs. digest scheduling	teamNotify.emailImmediate and teamDigestWorker.tick
Digest windowing + clamping	teamDigestWorker.clampSince, MAX_LOOKBACK_MS, MAX_ITEMS
One-click unsubscribe	utils/unsubscribeToken.js (stateless HMAC) + RFC 8058 List-Unsubscribe-Post
"Off unless configured" gate	mailer.isConfigured() checked before the recipient query
Multi-sink fan-out from one computed audience	teamNotify.forumPost → push + email + Discord bridge

This is the prototype of the system being scoped. Building beside it would give the deployment two unsubscribe mechanisms and two digest workers. Hence decision 2.

0.3 The uo.house.idoc_warning payload does not exist on the wire, and one field of it is not knowable

house.decay carries (docs/link/INTEGRATION.md:207, servuo-plugins/overlay/Scripts/Custom/Bridge/BridgeSweeps.cs:199):

serial, from, to, map, x, y, z, region, name, ownerSerial, ownerAcct, ban{x,y,z}, builtOn, lastRefreshed

Against the brief's example payload:

Brief field	Reality
house	✅ name (from the house sign)
location	✅ map, x/y/z, region, plus ban (where you stand to read the sign)
decay_status	✅ to
character	❌ not emitted — but trivially available: WriteDecay already reads house.Owner, so owner.Name is one line
shard	❌ not an event field, and should not become one — one deployment is one shard; core already has ctx.settings.getInstanceName()
next_stage	❌ not emitted — obtainable, see below
estimated_collapse	❌ not emitted, and not exactly knowable in advance — see below

Why estimated_collapse is the hard one. ServUO runs the dynamic decay system on any modern shard (Scripts/Multis/DynamicDecay.cs: Enabled => Core.ML). Under it, each stage's duration is drawn at random when that stage is entered (GetRandomDuration, e.g. Greatly = 1–2 days, IDOC = 12–24 h). BaseHouse.NextDecayStage (BaseHouse.cs:37) is therefore an exact, already-persisted timestamp for the next transition — but a collapse time two stages out does not exist yet, even inside the game.

Consequences for the design:

• next_stage is exact and cheap — emit NextDecayStage.
• estimated_collapse is exact only once the house is at IDOC, where NextDecayStage is the collapse time. Before that it can only be an envelope (min/max from the remaining stage table). Emit it as estimatedCollapse only when to == "IDOC", plus an optional estimatedCollapseMin/Max envelope earlier — never a single number that reads as a promise.
• Under the legacy static path (GetOldDecayLevel, BaseHouse.cs:205) decay is a pure function of lastRefreshed + DecayPeriod, and lastRefreshed is already on the wire. The decayPeriod is not, and should be added so a consumer can compute stages without hardcoding 5 days.

And the current mapping fires at the wrong stage for the brief's own example. The brief's story is "house becomes greatly damaged". module-uo/server/config/shardStreams.js maps house.decay to a stream only when String(event.to).toUpperCase() === 'IDOC' — the final stage, which is 12–24 h from collapse. A "greatly damaged" warning needs a Greatly transition mapping. That part needs no protocol change at all and can ship long before the bump lands.

0.4 Event-name collision handling already exists — the brief's §6 forward-compat note is already satisfied

The brief asks for a one-line note that a module-id prefix would be needed if multi-module ever happens. It already happened:

• modules/registries.js:namespaced() requires every stream id and announce-leg id to start with <owner>., with a small grandfathering allowlist (LEGACY_STREAM_IDS, LEGACY_LEGS) for the seven pre-module-system ids.
• registries.apply() throws on any collision, naming the current holder, before it commits a single claim.
• modules/loader.js cross-checks mounts, tables and slots across all loaded modules (for (const other of modules.values())), so N modules is a supported configuration, not a future one.

uo.house.idoc_warning is therefore already the house style, and the trigger registry gets collision handling for free by reusing namespaced() verbatim. This is a resolved item, not a forward-compat note. The genuine forward-compat note is elsewhere — see §7.3.

0.5 MODULE_API_VERSION 1.6.0 is on main now, so this needs a real bump

MODULE_API.md §1.1 currently argues that additions may join 1.6.0 in place because "1.6.0 has only ever been on edge". That is stale: git show main:server/src/modules/version.js reads 1.6.0. The Teams cutover landed it.

So the engagement additions take 1.7.0 — additions only (api.registerEventTriggers, ctx.events.emit, ctx.inbox.push), no removal, no changed signature, so minor by the §1.1 table. module-uo's coreApi: "^1.3.0" still resolves.

---

0.6 A UNIQUE email is not a one-line ALTER — it breaks three paths and can stop a boot

Decision 6 (opt-in only, unique addresses) reads like a schema tweak. It is not. users.email is VARCHAR(255) NULL with no unique index, and schema.sql:24 says so deliberately: "Optional contact email (players). Not unique — SSO emails may repeat." Adding the index touches registration, SSO provisioning and the upgrade path. All four findings below were read out of the tree on 2026-08-28.

1. The boot-time ALTER is how schema reaches a deployment, and it would fail loudly. Upgrades ride the idempotent ALTER TABLE … IF NOT EXISTS block at schema.sql:1409+, executed by ensureSchema() on every boot (server/src/server.js:66). ADD UNIQUE INDEX against a table that already holds duplicate addresses errors, ensureSchema() throws, and the site does not start. A de-duplication step must run before the index, in the same release — see Phase 1b.

2. isDuplicateUsername() does not inspect which index collided. users.model.js:24 is err.code === 'ER_DUP_ENTRY' || err.errno === 1062 and nothing more. Two callers misread an email collision as a username collision the instant the index exists:

Site	Today	After UNIQUE(email), unfixed
auth.controller.js:137 (register)	409 "That username is already taken." on a genuine username race	Same message for a duplicate email — wrong, and it misattributes the conflict to the one field the user did not collide on
sso.controller.js:197 (provisionSsoPlayer)	Retries the next username suffix on collision	Retries usernames for an email conflict, which can never clear; burns PROVISION_MAX_TRIES and returns null, so SSO sign-up fails opaquely with the log blaming usernames

The fix is to distinguish the constraint (read the index name off the driver error) before Phase 1b adds the index — not after.

Amended 2026-08-29 (Phase 1b, as built). This table names two callers of isDuplicateUsername(). There are five, and the three it omits fail worse than the two it names — invite.controller.js accepts an invite to an address already held and fails after the invitee has clicked the link and chosen a password, while admin.controller.js createUser and updateUser had no catch at all and turned a duplicate address into an opaque 500 for an admin who could see nothing wrong with the form. (auth/account.controller.js changeUsername is the fifth and is username-only, so it was already correct.) All five are handled; each answers differently on purpose, because a public form, an authenticated IdP callback, a half-completed invite and an admin screen do not owe the same person the same amount of truth.

The index name is available only in the driver's message text — the mariadb connector exposes no structured field for it — so the discrimination is a regex over for key '…', with its own test. That message also embeds the bound parameters, so on an email collision it contains the address: a second, independent reason these errors must never be echoed to a client.

3. SSO auto-provisioning is the source of the duplicates, and CLAUDE.md is stale about it. CLAUDE.md states "identities are never auto-provisioned". provisionSsoPlayer (sso.controller.js:197) does exactly that whenever player_registration ∈ {sso, both}, writing profile.email straight into users.email. It also sets emailVerified: Boolean(profile.email) — verified because an address was present, not because the IdP asserted email_verified. That matters twice over: it manufactures the duplicates Phase 1b must clean up, and it makes email_verified too weak a signal to arbitrate which duplicate wins (which is why §7.1 Q1's answer is oldest-wins, not verified-wins).

4. There is no self-serve email flow at all. No route lets a user set or change their own address after signup — router/v1/auth/me.routes.js, the self-service surface, has none, and users.model.js:72's update() is reached only by admin user management. An address is captured once, at registration or SSO provisioning, and is thereafter unchangeable by its owner. A verification gate presupposes a change-and-verify flow, so Phase 1b builds one; it is not an add-on to an existing screen.

Read out of the tree on 2026-08-28, when self-service had three URL surfaces onto one controller (/auth/me/account/*, /player/account/*, /admin/account/*), so a new field meant writing it three times. The two smaller ones were deleted on 2026-08-29 — see Phase 1a below. Phase 1b's change-and-verify routes are written once, on /auth/me/account.

One consequence for the error surface. A unique constraint needs a user-facing failure, and the obvious wording ("that email is already registered") makes account existence queryable — a step back from a posture the codebase holds deliberately elsewhere (passwordReset.controller.js answers a generic 200 "to avoid account enumeration"). §7.1 Q1 settles it: the message stays generic, the real reason is logged not returned, the endpoint stays rate-limited, and the failure is not fed to the bot scorer — an honest typo on a taken address must not push a legitimate user toward an IP ban.

---

Part 1 — Current-state map

1.1 Notification system, end to end

                                    registerNotificationStreams()          [modules/registries.js]
                                                 │
   config/coreStreams.js  (news.post, team.*)  ──┤  ← core, via registerCore()
   module-uo/config/shardStreams.js (7 ids)    ──┘  ← module, via api.*

                                          catalog read back through registries.allStreams()
                                                 │
                     GET /auth/me/notifications/streams  ──────────────────► web + Android
                     GET·PUT /auth/me/notifications/subscriptions ─────────► notification_subscriptions
                                                 │
   shard event ──► module-uo/utils/shardPush.js ─┤
   news publish ─► posts controller ─────────────┤──► pushDispatch.publish(streamId,{ref,ownerUserId})
   team event ───► utils/teamNotify.js ──────────┘──► pushDispatch.publishToUsers(streamId,{ref,userIds})
                                                 │
                                          push_devices rows (SSRF-gated endpoints)
                                                 │
                                    POST {stream, ref}  ──► ntfy / UnifiedPush ──► app wakes, PULLS content

Files.

Concern	File
Catalog registry (core + modules)	server/src/modules/registries.js — registerNotificationStreams, allStreams, isValidStream, personalStreams
Core's own streams	server/src/config/coreStreams.js — news.post + four team.*
Module streams	module-uo/server/config/shardStreams.js — seven grandfathered ids + mapShardEvent
Fan-out	server/src/utils/pushDispatch.js — publish (all-subscribers / one-owner), publishToUsers (computed set), isAllowedEndpoint (SSRF gate)
Shard → push adapter	module-uo/server/utils/shardPush.js — resolves ownerAcct → website user via shardLinks
Team fan-out	server/src/utils/teamNotify.js — one audience, three sinks
Self-service API	server/src/router/v1/auth/notifications.controller.js + notifications.routes.js
Subscriptions model	server/src/model/notificationSubs/
Devices model	server/src/model/pushDevices/
Android surface	android-app/.../data/api/NotificationsApi.kt, dto/NotificationsDto.kt, ui/notifications/

Data model.

-- schema.sql:411
push_devices(id, user_id, transport ENUM('unifiedpush','fcm'), endpoint, platform, created_at, last_seen_at)
-- schema.sql:428
notification_subscriptions(user_id, stream_id VARCHAR(64), created_at, PRIMARY KEY(user_id, stream_id))
-- schema.sql:1285
team_notification_prefs(user_id, team_id, muted, email_mode ENUM('off','digest','immediate'), last_digest_at, updated_at)

Can it cleanly take Email as a third channel? Partly — and the coupling is in one place.

• ✅ The catalog is channel-neutral. A stream entry is { id, label, description, personal, requiresLinkedAccount }. Nothing in it is push-specific. It can describe an email or in-app subscription unchanged.
• ✅ The registry mechanism generalizes. stage() / apply() / namespaced() are about claims and collisions, not about push.
• ❌ notification_subscriptions has no channel dimension. PRIMARY KEY (user_id, stream_id) means a subscription is a boolean, and "subscribed" currently means exactly "push me a tickle".
• ❌ The wire shape is frozen by a shipped client. NotificationSubscriptionsDto is { streams: List<String> } and the app PUTs the whole set. Turning that array into objects breaks every installed app. (The DTO ignores unknown keys, so purely additive fields are safe — this is recorded in the app's own comments.) A per-channel model must therefore arrive as a new endpoint, with the old one preserved as the push projection.
• ❌ Email opt-in semantics differ from push, deliberately. team_notification_prefs documents the asymmetry in its own DDL comment: push is opt-out (muted defaults 0), email is opt-IN (email_mode defaults 'off'), because digest-by-default would start mailing everyone the moment an operator connects a mailbox. Any unified model must keep per-channel defaults, not one shared default.

Self-hosted ntfy / UnifiedPush integration points (email must sit beside these, not duplicate them):

• pushDispatch.isAllowedEndpoint — HTTPS-only, private-host denylist, plus an origin allow-set from NTFY_ALLOWED_ORIGINS / NTFY_BASE_URL. There is no hardcoded default host. Empty allow-set is the dev fallback.
• NTFY_PUBLISH_TOKEN — optional bearer for the relay.
• The content-free tickle invariant: { stream, ref } and nothing else, because ntfy is treated as an untrusted relay. Email deliberately breaks that rule (a mailbox is a destination the recipient chose) and teamNotify.js's header comment is the standing argument for why the asymmetry is the security model rather than an inconsistency. The engagement system must preserve this per channel, not flatten it.

1.2 Current email implementation

Transport. server/src/utils/mailer.js (267 lines). nodemailer over smtp.gmail.com:465 with auth.type: 'OAuth2'. Client id/secret are reused from the google auth_providers row; only the refresh token is email-specific. buildTransport() returns null when unconfigured, and every sender handles that itself.

Config. email_config singleton (schema.sql:336) — provider (already a VARCHAR(20) defaulting 'gmail_oauth2', so the column is ready for a second provider), enabled, sender_email, sender_name, refresh_token_enc (AES-256-GCM via utils/secretBox.js), status, status_detail, last_verified_at. Admin-managed, never env — docs/website/BACKEND_DESIGN.md §7.

Admin API. router/v1/admin/email.router.js — six routes: GET·PUT /config, GET /connect/start, GET /connect/callback, POST /test, POST /disconnect. Client: client/src/routes/admin/views/EmailDelivery.jsx.

Every caller — the full migration surface. Six call sites, five sender functions:

Caller	Function	Failure contract
router/v1/public/public.controller.js:156 (contact form)	sendContactMessage	Never throws when unconfigured — returns {sent:false, fallback:'mailto', email} and the client renders a mailto: link
router/v1/admin/emailConfig.controller.js:188 (admin "Send test")	sendTest	Throws NOT_CONFIGURED / NO_RECIPIENT; 502 to the admin
router/v1/admin/invites.controller.js:46	sendInvite	Returns {sent:false, reason:'NOT_CONFIGURED'} so the admin gets the accept link to share by hand
router/v1/auth/passwordReset.controller.js:49	sendPasswordReset	Returns {sent:false, …}; caller still answers a generic 200 to avoid account enumeration
utils/teamNotify.js:234 (immediate)	sendTeamNotification	Never throws at all — logged and swallowed; the forum write already returned
utils/teamDigestWorker.js:73 (digest)	sendTeamNotification	Same; return value gates the last_digest_at stamp

Nothing in website/bot, module-uo, or any other repo sends mail. mailer is not on ctx — modules already cannot send email, which matches the target architecture.

Hardcoded assumptions the abstraction has to remove:

1. One provider, compiled in. The Gmail host, port and OAuth2 auth type are literals in buildTransport(). email_config.provider exists but nothing reads it.
2. The credential shape is Gmail's. One refresh_token_enc column plus a borrowed OAuth client. SMTP needs host/port/secure/user/password; SES needs a region and IAM keys; Mailgun/SendGrid need a domain and an API key. None of those fit the current column set.
3. One transport built per send. buildTransport() runs on every call — a fresh DB read, a fresh decrypt and a fresh nodemailer transport per message, with no pooling. Fine for a password reset; the serial per-recipient loop in emailImmediate is explicitly a rate-limit workaround for it.
4. Text-only, composed inline. Every body is a template literal inside mailer.js. There is no HTML part anywhere and no template storage. sendTeamNotification builds its body by pushing lines into an array.
5. Synchronous send, no queue, no retry. A send either succeeds inside the request/tick or is lost. recordStatus writes the last outcome to a singleton column — there is no per-message record, so "did user X get the IDOC mail?" is unanswerable today.
6. recordStatus is global. One transient failure sets email_config.status='error' for the whole deployment, from any of six unrelated call sites.
7. No suppression, no bounce handling, no verification gate. users.email is not unique (SSO addresses repeat) and users.email_verified is set to 1 only on invite-accept (invite.controller.js:55) and SSO (sso.controller.js:208). Self-registration accepts an address and leaves it unverified (auth.controller.js:124). Today only transactional mail goes out, so this is tolerable; the moment game events drive volume it is a deliverability and complaint problem.

1.2a Removing Gmail OAuth2 — the deletion inventory (decision 4)

Gmail OAuth2 is not a transport we keep beside SMTP. It goes. That is a subtraction with a live deployment behind it, so the exact surface is worth writing down before anyone starts.

Server — deleted:

Thing	Where
GET /admin/email/connect/start	router/v1/admin/email.router.js
GET /admin/email/connect/callback	same
connectStart / connectCallback	router/v1/admin/emailConfig.controller.js (~half the file's 211 lines)
The email_oauth_tx signed cookie, the PKCE verifier and CSRF nonce plumbing	same controller
EMAIL_SCOPE = 'https://mail.google.com/ openid email'	same
googleClient() — the borrowed google auth_providers credential read	same
The OAuth2 nodemailer transport (auth.type: 'OAuth2', smtp.gmail.com:465 literals)	utils/mailer.js:buildTransport
emailConfig.getWithSecret()'s refreshToken decrypt	model/emailConfig/emailConfig.model.js

Client — deleted: the "Connect Gmail" button and connect() handler, the ?email_connected / ?email_error redirect-banner handling, and the five Gmail-specific error strings (bad_state, no_client, no_refresh_token, …) in client/src/routes/admin/views/EmailDelivery.jsx. Replaced by an ordinary credential form driven by the transport's credentialFields (§3.1).

Database — deprecated, not dropped. email_config.refresh_token_enc and provider stay as columns (additive-only discipline; core's schema.sql contains exactly one DROP and it is documented as such). They stop being read. A later cleanup PR may drop them once every deployment has booted past the cutover.

Three consequences worth naming:

1. SSO is unaffected. The google auth_providers row exists for SSO in its own right; email merely borrowed its client id/secret. Removing the borrow removes a coupling — one of the better side effects of this decision, since today an admin who rotates the Google SSO secret silently breaks outbound mail with no indication that the two are related.
2. sender_email changes meaning. Today it is read back from Google's userinfo and is therefore guaranteed to be an address the mailbox owns. Under SMTP it is operator-typed, so nothing stops a mismatch between the envelope sender and what the SMTP account is permitted to send as — which is a silent deliverability failure (SPF/DMARC), not an error. The admin "Send test" path has to become the real verification, and its failure text has to be specific enough to diagnose a rejected From.
3. The live deployment goes dark at cutover unless the operator acts. UOMysticmoon is connected via Gmail OAuth2 today. On upgrade, transport backfills to smtp with no credentials, so isConfigured() returns false and every sink politely does nothing — the contact form falls back to mailto, invites surface a copyable link, password resets still answer a generic 200. Nothing breaks loudly, which is precisely the risk: email silently stops and nobody is told. Phase 1 therefore owes three things: an admin dashboard warning when transport='smtp' and credentials are absent, a release note naming the required action, and INSTALL.md-style operator guidance. Gmail itself remains usable as plain SMTP (smtp.gmail.com:587 with an app password), which is the shortest migration path for the existing deployment and should be the documented one.

1.3 Module contract fit

The registration surface, as it stands (modules/registries.js, MODULE_API.md §2.4):

Call	Shape	Cardinality
registerRoutes	tier → prefix → router	declared in module.json, cross-checked
registerExtension(slot, router)	fills a core-declared slot	one filler per slot
registerNotificationStreams([…])	push catalog entries	many, <owner>.-prefixed
registerAnnounceLeg({leg, label, dispatch, classify})	a delivery leg with retry classification	many, <owner>.-prefixed
registerPostHook({onSaved, onDeleted})	idempotent state mirroring	one per owner
registerTeamProvider({…})	core calls the module and waits	one per deployment
registerSlashCommands([…])	definition travels, handler stays	many, not namespaced (Discord grammar)

Is there a natural extension point? Yes — and registerAnnounceLeg is the closest structural match, but for the delivery half, not the trigger half.

The engagement system needs two things a module does not have today:

1. A way to declare a domain event and its data contract — nothing like this exists. registerNotificationStreams declares a subscription toggle; it carries a label and two booleans, and no statement whatsoever about payload. A module cannot tell core what a uo.house.idoc_warning contains.
2. A way to emit one. Today ctx.push.publish(streamId, {ref, ownerUserId}) is the only outbound path, and it is deliberately content-free. A module that wanted to send a rendered message has to go through pushDispatch, which will not carry the data.

So this needs a new registration surface, not a reuse. It should be modelled on registerNotificationStreams (shape-checked at the call, collision-checked at apply(), <owner>.-prefixed) rather than on registerAnnounceLeg (which is a core-calls-module dispatch with retry classification — the wrong direction: a module reports an event, it does not deliver one).

What module-uo exposes to core today. Only what the registries take: seven stream ids, one announce leg, one extension router, a Team provider, one slash command, five route mounts. Everything else — 27 shard_* tables, the sidecar client, the visibility framework — is module-internal (MODULE_API.md §1.2). There is no data channel from a module into core carrying structured game data. ctx.teams.activity.push is the nearest thing, and it is instructive: core stores summary already rendered by the module, because core cannot phrase a sentence in a vocabulary it does not know, and kind/payload are opaque.

The engagement system deliberately takes the opposite position — core does interpolate module data into a template — which is only safe because the operator authors the template and the module declares the variables. That is the whole reason §4.3's variable contract has to exist rather than being optional.

1.4 Job, scheduling and queue infrastructure that already exists

There is no cron. There is no Redis, no BullMQ. The stack has exactly two patterns:

(a) In-process setInterval + unref() + stop(), wired into server.js start/shutdown. Six of them: announceWorker, teamDigestWorker, teamActivityPrune, teamForumUploadSweep, teamVoiceSync, and middleware/botScore's sweeper.

(b) A durable job table with per-leg backoff — announce_jobs + announce_job_legs (schema.sql:737/757), swept by announceWorker.tick. This is a real outbox: status, attempts, last_error, next_attempt_at, INDEX idx_announce_leg_due (status, next_attempt_at), and a classify() that maps a delivery result to done / retry / terminal. It was explicitly designed so a module can add a delivery leg without altering a core table — the child-table shape and the VARCHAR (not ENUM) leg column are both justified in the DDL comment on exactly those grounds.

Which of the brief's two scheduling use cases each pattern serves:

• (a) Delayed send per event — "wait 30 min in case the player fixes it". Needs a durable row with a due_at, and — the part the brief does not name but which is the actual point — the ability to cancel a pending row when a later event resolves the condition. announce_jobs is the exact precedent; this needs its own table because a module cannot alter a core one and the payload differs.
• (b) Batched / digest — teamDigestWorker already does this, and its header comment is the design argument: it computes at send time and keeps no queue, whose three consequences are (1) a deployment down for two days sends one digest, not a replay, (2) content hidden after it was written is not in the query so not in the mail, and (3) a user who lost access between the post and the send is no longer in the recipient set — which it calls out as the one that would have been a security bug.

That split is the answer to the brief's §4 scheduling question: (a) is a queue, (b) must not be. Copying (a) for digests would reintroduce all three problems.

One gap in both patterns: neither is multi-instance safe. No advisory lock, no leader election, no SELECT … FOR UPDATE SKIP LOCKED. Two app containers means two digest sweeps and two announce workers. The current deployment is single-instance (website/docker-compose.yml), so this is latent — but an engagement mailer doubles messages rather than doubling reads, so it becomes visible here first.

Reusable primitives worth naming:

• utils/unsubscribeToken.js — a stateless HMAC whose whole capability is "set muted for one (user, Team) pair". Generalizes to (user, channel, trigger) with no structural change.
• utils/settingsJson.js — the fail-safe JSON-settings parse (malformed ⇒ absent, never an error).
• blocks/registry.js + blocks/types/* + sanitizeBlocks.js + validateBlocks.js — a versioned, schema-validated, sanitize-on-save visual block system already driving pages.blocks (MEDIUMTEXT JSON). This is the template editor's foundation; see §4.4.
• utils/secretBox.js — AES-256-GCM for provider credentials at rest.
• model/settings/settings.model.js + the settings key/value table — right for a handful of scalars, wrong for cooldowns (see §4.1).

---

Part 2 — Gap list against the target architecture

Game Module ──► Domain Events + Data ──► Core ──► Engagement ──► Preferences ──► Template ──► Delivery

#	Layer	Gap	Severity
G1	Module → events	No way for a module to declare a domain event or its payload contract	Blocking
G2	Module → events	No way for a module to emit one carrying data (ctx.push.publish is content-free by design)	Blocking
G3	Events → Core	No event catalog surface for the admin UI to enumerate triggers	Blocking
G4	Engagement	No rules concept at all — today a trigger's consequence is hardcoded in the emitting file	Blocking
G5	Engagement	No cooldown / rate-limit state of any kind, per-recipient or otherwise	Blocking (brief calls this out as pre-first-trigger)
G6	Engagement	No delayed-send queue and no cancellation	High
G7	Engagement	Digest exists but is Team-shaped, not generic (last_digest_at lives on team_notification_prefs)	High
G8	Preferences	notification_subscriptions has no channel dimension; the shipped app's wire shape is frozen	Blocking
G9	Preferences	Per-channel defaults differ (push opt-out, email opt-in) and there is nowhere to express that generically	High
G10	Preferences	Unsubscribe is Team-scoped (unsubscribeToken.sign(userId, teamId))	Medium
G11	Template	No template storage, no HTML part, no renderer, no preview, no plain-text fallback. Every body is a string literal in mailer.js	Blocking
G12	Template	No variable contract — nothing declares what a template may interpolate	Blocking (see §4.3)
G13	Delivery	One hardcoded provider; email_config.provider is written but never read	Blocking
G14	Delivery	Credential schema is Gmail-shaped (one refresh token + a borrowed OAuth client)	Blocking
G15	Delivery	No per-message record — no send log, no delivery status, no audit	High
G16	Delivery	No suppression list, no bounce/complaint handling, no unverified-address policy	High
G17	Channels	In-app channel does not exist — no table, no read API, no web surface, no app surface	Blocking (in scope)
G18	Infra	Workers are not multi-instance safe — latent today, doubles messages under engagement	Medium
G19	Contract	MODULE_API_VERSION must go 1.6.0 → 1.7.0 (§0.5)	Process
G20	Wire	house.decay lacks ownerName, nextStage, decayPeriod, collapse estimate (§0.3)	High (in scope)
G21	Ops	No preview/test-send path for a template against a real trigger payload	Medium
G22	Delivery	Removing Gmail OAuth2 leaves the live deployment silently unconfigured — every sink degrades quietly, so email stops with no signal (§1.2a)	High (in scope)
G23	Template	No seeded default templates — without them, "add a trigger" implies "and now author a template", and a fresh install mails nothing (§4.6.1)	High (in scope)
G24	Engagement	An audience ceiling per trigger. shardStreams.js already filters sensitive kinds off the public push path; the engine needs the equivalent or a rule can widen a staff-only trigger to everyone (§8.6)	Blocking (security)
G25	Engagement	No time-based trigger kind — "nothing happened for 30 days" is a periodic evaluator, not an event (§8.5)	Medium (design in Phase 2, build later)

---

Part 3 — The delivery abstraction (brief §5)

3.1 Name it DeliveryChannel, and split channel from transport

The brief asks whether the interface should be EmailProvider or something more generic. Neither alone. Two axes are being conflated, and the current code conflates them too:

• A channel is what kind of sink this is — email, push, in-app, later Discord DM. It determines the address kind (mailbox / endpoint URL / user id / snowflake), the render contract (subject + HTML + text vs. {stream, ref} vs. an embed), the preference semantics, and whether content may ride at all.
• A transport is how one channel actually delivers — SMTP / Gmail-OAuth2 / Mailgun / SES / SendGrid for email; ntfy-UnifiedPush / FCM for push.

Push already has this shape and nobody named it: push_devices.transport ENUM('unifiedpush','fcm') is a transport column on a channel that has exactly one implementation today.

Recommended surface:

// core-internal registry, mirroring modules/registries.js's shape
registerDeliveryChannel({
  id: 'email',                    // 'email' | 'push' | 'inapp' | later 'discord.dm'
  label: 'Email',
  carriesContent: true,           // false for push — enforces the tickle invariant structurally
  defaultMode: 'off',             // G9, expressed here once. All three are opt-IN as built —
                                  // 'push opt-OUT' was wrong; see Phase 3's as-built
  supportsDigest: true,           // in-app and push are instant-only in v1
  addressFor(userId),             // → [{ address, meta }] ; email reads users.email, push reads push_devices
  render(template, vars, ctx),    // → the channel's own payload shape
  deliver(address, payload),      // → { ok, retryable, error } — never throws
})

registerMailTransport({
  id: 'smtp',                     // 'smtp' | 'mailgun' | 'ses' | 'sendgrid' — NOT gmail_oauth2 (removed)
  label: 'SMTP',
  credentialFields: [...],        // drives the admin form AND the encrypted credential blob
  build(config),                  // → a nodemailer transport (or an API client)
  verify(config),                 // → the admin "Send test" path
})

Answering the brief's actual question: no, this will not need a breaking rename when Discord DM arrives. A Discord DM is a registerDeliveryChannel({ id: 'discord.dm', carriesContent: true, … }) whose deliver calls utils/botInternalClient.js — the bot-internal API already exists and utils/teamBridge.js is the working precedent for core handing a composed message to the bot. Nothing in the interface above says "email".

One vocabulary warning. The announce pipeline already calls a delivery a leg (registerAnnounceLeg, announce_job_legs.leg). channel and leg will coexist and mean nearly the same thing. They should stay distinct rather than being unified: a leg is a one-shot delivery of one artifact with retry and terminal classification; a channel is a per-recipient sink with preferences, addresses and digest semantics. teamBridge.js's header already argues this distinction for the Discord case ("one-shot, not queued… a notification is the moment it describes"). The design doc should say so explicitly so nobody "tidies" them together later.

3.2 No phone-home — the existing posture is already correct, and the registry must preserve it

Confirmed, and there is nothing to fix — only something to not break:

• email_config is DB-backed and admin-managed, never env (BACKEND_DESIGN.md §7). There is no default host, no default sender, and status starts 'unconfigured'.
• pushDispatch.allowedOrigins() reads NTFY_ALLOWED_ORIGINS / NTFY_BASE_URL and returns empty when neither is set. No Runic Gateway host appears anywhere in it.
• mailer.isConfigured() gates every sink, and teamNotify.emailImmediate checks it before the recipient query so an unconfigured deployment pays nothing. As of Phase 6 that sink is the engine's and the gate moved with it: mailer.sendNotification returns a retryable failure when mail is unconfigured, so an operator midway through typing SMTP credentials finds the outbox drains rather than a backlog the worker gave up on. The digest worker still checks isConfigured() up front, before any query that costs anything.

Rules to carry into the abstraction:

1. No transport may ship a default host, endpoint, API base or sender. A transport with no operator configuration is unconfigured and its channel is off, not defaulting to anything.
2. No engagement code may read an env var naming an external service that the operator did not set.
3. The "off unless configured" gate is checked before recipient resolution, per channel.
4. A CI guardrail: extend scripts/checkModuleIdentifiers.js's sibling pattern with a check that no file under server/src/engagement/ contains a bare external hostname literal. (Cheap; the check pattern and its self-test discipline already exist — see test/checkModuleIdentifiers.test.js, which feeds the checker code it must reject precisely so a check cannot silently stop checking.)

---

Part 4 — Proposed schema additions

All additive. All CREATE TABLE IF NOT EXISTS / ALTER … ADD COLUMN IF NOT EXISTS, replayed on every boot, per MODULE_API.md §2.6's rules (which core's own schema.sql follows too). Core tables, no prefix — every one of these is game-agnostic.

MariaDB trap, already learned twice in this codebase: a PRIMARY KEY column is coerced NOT NULL, so "NULL means the default row" is unrepresentable in a PK. team_integration_config (schema.sql:1335) and teams.active_key both work around it with a surrogate key plus a generated column folding NULL onto a sentinel. Two tables below need the same treatment; both are flagged.

4.1 Cooldowns — its own table, not settings

The brief asks whether the settings.model.js JSON-value pattern is a reasonable fit. No. settings is (key VARCHAR(64) PRIMARY KEY, value TEXT) — a single-row-per-key store read whole. Cooldown state is high-cardinality (recipients × rules × subjects), written on every fire, and queried as "is this one pair still cooling?". A JSON blob under one key would be a read-modify-write of the entire deployment's cooldown state on every event, with a lost-update race between two concurrent triggers. It is the wrong shape by an order of magnitude.

CREATE TABLE IF NOT EXISTS engagement_cooldowns (
  rule_id      INT          NOT NULL,
  user_id      INT          NOT NULL,
  -- The SUBJECT the cooldown is about, opaque to core: a house serial, a vendor id, ''.
  -- NOT NULL with a '' default, because this is a PRIMARY KEY column and MariaDB
  -- would coerce a NULL one anyway. '' is "this rule cools per user, not per subject".
  subject_key  VARCHAR(190) NOT NULL DEFAULT '',
  last_fired_at DATETIME    NOT NULL,
  fire_count   INT          NOT NULL DEFAULT 1,
  PRIMARY KEY (rule_id, user_id, subject_key),
  CONSTRAINT fk_engc_rule FOREIGN KEY (rule_id) REFERENCES engagement_rules(id) ON DELETE CASCADE,
  CONSTRAINT fk_engc_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  INDEX idx_engc_sweep (last_fired_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Why subject_key is not optional. "One IDOC mail per player per day" is the wrong rule — a player with four houses decaying should hear about all four, once each. Cooling per (rule, user) alone silently drops three of them. The module supplies subject on emit; core stores it opaquely.

INDEX idx_engc_sweep (last_fired_at) exists so a prune worker can drop rows older than the longest configured cooldown — otherwise this table grows without bound, which is the failure mode teamActivityPrune was written for.

The check must not be a read-then-write, or two concurrent emits both see an expired cooldown and both send. The obvious single statement — INSERT … ON DUPLICATE KEY UPDATE with the interval guard in the assignments, reading the answer out of affectedRows — does not work against this codebase's pool, and Phase 4a is where that was found: the mariadb connector defaults foundRows: true, so a no-op update reports 1 rather than 0 and every cooldown passes. What ships instead is a guarded UPDATE (the interval in a WHERE clause, where a row either matches or does not) falling back to an INSERT IGNORE for the first fire. See Phase 4a's as-built for the statements and the races.

4.2 Scheduling — a queue for delay, and deliberately no queue for digest

(a) Delayed send ⇒ engagement_outbox. Modelled on announce_jobs/announce_job_legs.

CREATE TABLE IF NOT EXISTS engagement_outbox (
  id           BIGINT AUTO_INCREMENT PRIMARY KEY,
  rule_id      INT          NOT NULL,
  trigger_id   VARCHAR(96)  NOT NULL,       -- denormalized; survives a rule edit
  user_id      INT          NOT NULL,
  channel      VARCHAR(32)  NOT NULL,       -- 'email' | 'push' | 'inapp' | …  VARCHAR, never ENUM
  subject_key  VARCHAR(190) NOT NULL DEFAULT '',
  payload      JSON         NOT NULL,       -- the module's declared variables, snapshotted at emit
  -- Idempotent enqueue. A sidecar reconnect that replays the same event must not
  -- produce a second mail. Same reasoning as ctx.teams.activity.push's dedupeKey.
  dedupe_key   VARCHAR(190) NULL,
  status       ENUM('scheduled','sending','sent','failed','cancelled','suppressed') NOT NULL DEFAULT 'scheduled',
  due_at       DATETIME     NOT NULL,
  attempts     SMALLINT     NOT NULL DEFAULT 0,
  last_error   TEXT         NULL,
  created_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  sent_at      DATETIME     NULL,
  CONSTRAINT fk_engo_rule FOREIGN KEY (rule_id) REFERENCES engagement_rules(id) ON DELETE CASCADE,
  CONSTRAINT fk_engo_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  -- SCOPED, not global. One event legitimately becomes one row per (rule, user,
  -- channel); a global unique index would admit the first recipient's row and
  -- silently ignore every other. Corrected in Phase 4a — see its as-built.
  UNIQUE KEY uq_engo_dedupe (rule_id, user_id, channel, dedupe_key),
  INDEX idx_engo_due (status, due_at),
  INDEX idx_engo_cancel (rule_id, user_id, subject_key, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Three things this buys that a straight send does not:

• due_at is the 30-minute grace window. The worker sweeps status='scheduled' AND due_at <= now.
• status='cancelled' is the actual point of that window. idx_engo_cancel is what a resolving event queries: a house.decay back up to LikeNew cancels every scheduled row for that (rule, user, house). Without cancellation, a delay is just a late mail.
• dedupe_key UNIQUE per (rule, user, channel) makes replay safe. The sidecar has no schema-migration mechanism and a reconnect backfills; an at-least-once feed must not become an at-least-once mailer. The scope matters as much as the constraint: a dedupe key names the event, and the event fans out to every recipient of every channel of every matching rule.

channel is VARCHAR(32) and not an ENUM for exactly the reason announce_job_legs.leg is — the channel set is data, and a module (or a later core channel) must not require an ALTER.

(b) Digest ⇒ no queue. Keep teamDigestWorker's compute-at-send-time design and generalize its state, not its absence of one:

CREATE TABLE IF NOT EXISTS engagement_digest_state (
  user_id        INT         NOT NULL,
  channel        VARCHAR(32) NOT NULL,
  scope_key      VARCHAR(190) NOT NULL DEFAULT '',   -- '' = deployment-wide; a Team id for the Teams case
  last_digest_at DATETIME    NULL,
  PRIMARY KEY (user_id, channel, scope_key),
  CONSTRAINT fk_engd_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  INDEX idx_engd_due (channel, last_digest_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

team_notification_prefs.last_digest_at backfills into this with channel='email', scope_key = CONCAT('team:', team_id). The three properties from teamDigestWorker's header comment must be preserved verbatim by the generic worker, and the third one (a user who lost access is no longer in the recipient set) should get its own named test, the way the Teams phase-5 work gave the leader-can't-see-reports rule its own test.

Phase 6 as built, and it corrects §4.2a rather than only implementing this. Keeping compute-at-send-time means a digest-mode recipient must get no outbox row at all: Phase 4a's subscribedTo enqueued them ("what changes in Phase 6 is who drains it") and what changed in Phase 6 is that nothing drains it. An outbox row holds a payload snapshotted at emit time and therefore has none of the three properties above — including the security one. The engine now enqueues instant only. Two more things landed with it: engagement_outbox gained a scope_key column (what a preference and an unsubscribe are keyed on, which is not subject_key — see Phase 6's as-built), and the backfill's replay-safety is a property of the PRIMARY KEY rather than of a flag, so a window the worker has since moved forward is never dragged backwards by a restart.

4.3 The template variable contract — a code-declared schema, mirrored to a checked-in manifest

The brief asks whether anything in the codebase already does this. Two things do, and they are the two halves of the right answer:

• blocks/registry.js — a registered definition carries version (a prop-schema version, bumped when props change so a migration can transform older blocks), schema: (props) => [errors], and sanitize: (props) => props run on save after validation. That is the validation half.
• server/scripts/routeManifest.js + routes.manifest.json, checked in CI with --check — a generated artifact committed to the repo, whose diff is the review signal. That is the drift half. (module-uo carries its own routes.manifest.json for the same reason, and ships a prebuilt swagger-fragment.json because core never has its sources to analyse — MODULE_API.md §6.1a.)

Proposal: the trigger declaration carries its variables, and a generated manifest freezes them.

api.registerEventTriggers([{
  id: 'uo.house.idoc_warning',        // <owner>.-prefixed, checked by the existing namespaced()
  label: 'House approaching collapse',
  description: 'A player house dropped into a late decay stage.',
  kind: 'event',                      // 'event' | 'scheduled' (G25); default 'event'
  subjectKey: 'house',                // which variable identifies the subject, for cooldowns
  audience: 'owner',                  // the DEFAULT a rule is created with
  ceiling: 'owner',                   // the widest a rule may EVER be given (G24, §5.1a)
  version: 1,                         // bumped on a rename or a type change
  variables: [
    { name: 'character',        type: 'string',   required: true,  example: 'Darrow' },
    { name: 'house',            type: 'string',   required: true,  example: 'The Silver Anvil' },
    { name: 'location',         type: 'string',   required: true,  example: 'Britain, Trammel (1119, 1794)' },
    { name: 'decayStatus',      type: 'string',   required: true,  example: 'Greatly' },
    { name: 'nextStage',        type: 'datetime', required: false, example: '2026-08-30T04:00:00Z' },
    { name: 'estimatedCollapse',type: 'datetime', required: false, example: '2026-09-01T04:00:00Z' },
  ],
}])

Four properties, each with a reason:

1. Validated at emit, not at render. ctx.events.emit checks the payload against the declaration. A missing required variable or a wrong type is dropped and logged in production, thrown in development — the same posture ctx.teams.activity.push takes ("a malformed item is dropped and logged"), because this is called from inside a game-event handler and a storage problem of core's must not become the module's control flow.
2. The editor reads it, so autocomplete is real. GET /admin/engagement/triggers serves the declarations; the template editor offers exactly those names and refuses to save a template referencing one that is not declared. That is G12 closed — the editor never blindly interpolates module JSON.
3. example is not decoration — it is the preview and the test-send. Without it, previewing a template requires a live game event, which is the reason template systems go untested.
4. Drift is caught by a committed manifest. npm run engagement:manifest writes server/engagement-triggers.json (core's) and CI runs it with --check, exactly as routes:manifest -- --check already gates the URL surface. Changing a variable's name or type without regenerating is a red build; the diff is what a reviewer reads. A module ships its own prebuilt engagement-triggers.json in its bundle, for the same reason it ships a prebuilt swagger fragment: core never has its sources.

Two corrections from building it (Phase 2). audience and ceiling are two fields, not one: the first is the default a rule is created with, the second is the maximum it may be raised to, and the registry refuses a default that the ceiling does not permit. And 'computed' is gone from the audience vocabulary — a rule pointing at a composed segment says so by naming the segment, so a third pseudo-value that means "look elsewhere" would be a value the ceiling arithmetic cannot compare. Both fields take the same six-value vocabulary (§5.1a).

example is enforced, not encouraged. A variable without one is refused at registration. Property 3 above is right and a soft version of it is worth nothing: the moment one variable has no example, previewing that template needs a live game event again.

Versioning. A variable's addition is additive and needs nothing. A rename or a type change breaks every stored template referencing it, so a trigger declaration carries version, bumped like a block's prop-schema version, and templates store the trigger version they were authored against. A template pinned to an older version renders with a warning in the admin list rather than silently interpolating undefined.

4.4 Templates — reuse the block registry, do not build a second editor

CREATE TABLE IF NOT EXISTS engagement_templates (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  `key`          VARCHAR(96)  NOT NULL UNIQUE,       -- stable id a rule points at
  name           VARCHAR(160) NOT NULL,
  trigger_id     VARCHAR(96)  NULL,                  -- NULL = a reusable/shared template
  trigger_version INT         NULL,                  -- what its variables were authored against (§4.3)
  channel        VARCHAR(32)  NOT NULL,              -- one template per channel; a rule names a set
  subject        VARCHAR(300) NULL,                  -- email only; may interpolate
  blocks         MEDIUMTEXT   NOT NULL,              -- JSON array — the pages.blocks pattern
  text_body      MEDIUMTEXT   NULL,                  -- authored plain-text override; else generated
  status         ENUM('draft','published') NOT NULL DEFAULT 'draft',
  -- A seeded template that the system itself depends on (password reset, invite).
  -- Editable, NOT deletable — the pages.protected flag, for the same reason.
  protected      TINYINT(1)   NOT NULL DEFAULT 0,
  -- Which seed revision this row came from, and whether an operator has since
  -- touched it. Together they let a later release ship an improved default
  -- WITHOUT overwriting an operator's edits. See §4.6.
  seed_key       VARCHAR(96)  NULL,
  seed_version   INT          NULL,
  customized     TINYINT(1)   NOT NULL DEFAULT 0,
  updated_by     INT          NULL,
  created_at     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  CONSTRAINT fk_engt_user FOREIGN KEY (updated_by) REFERENCES users(id) ON DELETE SET NULL,
  INDEX idx_engt_trigger (trigger_id, channel, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Why blocks and not raw HTML. The brief asks for a visual editor taking inspiration from the CMS page builder and the hero editor. The CMS builder is already a registry-driven block system with server-side prop validation and sanitize-on-save (blocks/registry.js, blocks/types/*, sanitizeBlocks.js). Storing raw operator HTML would give up all of that and hand the renderer an injection surface.

But email needs its own block set, not the page one. Page blocks emit modern CSS that mail clients do not support. Register a parallel family — email.heading, email.text, email.button, email.divider, email.image, email.itemList — that render to table-based, inline-styled HTML. The registry is designed for exactly this: "adding a block later means adding ONE entry".

Plain-text fallback is generated by default, overridable per template. Every block type gets a toText(props) alongside its renderer, so a text part always exists. teamNotify.excerpt() is the existing markup-to-text helper and should move into that family rather than being duplicated.

A text_body that is empty for a published template is a save-time error, not a runtime one — a mail with no text part is a spam-filter signal, and finding out at send time means finding out from a deliverability report.

4.5 Rules, channel preferences, send log, suppression

-- What an operator actually configures: trigger → audience → template → timing.
CREATE TABLE IF NOT EXISTS engagement_rules (
  id              INT AUTO_INCREMENT PRIMARY KEY,
  trigger_id      VARCHAR(96)  NOT NULL,
  name            VARCHAR(160) NOT NULL,
  enabled         TINYINT(1)   NOT NULL DEFAULT 0,   -- OFF by default; an operator turns it on
  audience        VARCHAR(32)  NOT NULL DEFAULT 'owner',
  audience_segment_id INT      NULL,                 -- a composed segment (§5.1a); NULL = the plain audience above
  -- §7.1 Q3: the hard stop that makes operator-editable rules safe to choose over
  -- code-registered ones. Counted in engagement_sends, enforced before the outbox
  -- row is written, never overridable from the rule editor beyond this column.
  max_sends_per_hour INT       NOT NULL DEFAULT 100,
  channels        JSON         NOT NULL,             -- ['email','inapp'] — a rule may span channels
  template_keys   JSON         NOT NULL,             -- { email: 'idoc-warning', inapp: 'idoc-warning-short' }
  conditions      JSON         NULL,                 -- declared-variable predicates, e.g. decayStatus in [Greatly, IDOC]
  cooldown_seconds INT         NOT NULL DEFAULT 0,
  delay_seconds   INT          NOT NULL DEFAULT 0,   -- the grace window (§4.2a)
  cancel_on       JSON         NULL,                 -- trigger ids that cancel a pending row for the same subject
  updated_by      INT          NULL,
  created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  CONSTRAINT fk_engr_user FOREIGN KEY (updated_by) REFERENCES users(id) ON DELETE SET NULL,
  INDEX idx_engr_trigger (trigger_id, enabled)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- §5.1a: an operator-composed segment over module-declared audiences. Stored as a
-- boolean tree of audience ids + params; `ceiling` is DERIVED at save time as the
-- NARROWEST ceiling in the tree and re-checked against the trigger's own ceiling,
-- so composition can never widen. It is a column rather than a runtime computation
-- so an audit can read what a rule was allowed to reach without re-resolving it.
CREATE TABLE IF NOT EXISTS engagement_audience_segments (
  id          INT AUTO_INCREMENT PRIMARY KEY,
  name        VARCHAR(160) NOT NULL,
  expression  JSON         NOT NULL,   -- { op: 'and'|'or'|'not', nodes: [...] | { audienceId, params } }
  ceiling     VARCHAR(32)  NOT NULL,   -- derived, never operator-typed
  updated_by  INT          NULL,
  created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  CONSTRAINT fk_engseg_user FOREIGN KEY (updated_by) REFERENCES users(id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- G8/G9: the channel dimension notification_subscriptions lacks.
CREATE TABLE IF NOT EXISTS notification_channel_prefs (
  user_id    INT          NOT NULL,
  stream_id  VARCHAR(64)  NOT NULL,   -- a stream OR a trigger id; one namespace, see §7.2
  channel    VARCHAR(32)  NOT NULL,
  mode       ENUM('off','instant','digest') NOT NULL DEFAULT 'off',
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (user_id, stream_id, channel),
  CONSTRAINT fk_ncp_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  INDEX idx_ncp_channel (channel, mode)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- G15: per-message record. Today "did user X get the mail?" is unanswerable.
CREATE TABLE IF NOT EXISTS engagement_sends (
  id           BIGINT AUTO_INCREMENT PRIMARY KEY,
  outbox_id    BIGINT       NULL,
  rule_id      INT          NULL,
  trigger_id   VARCHAR(96)  NOT NULL,
  user_id      INT          NULL,                   -- SET NULL, so the log survives an account deletion
  channel      VARCHAR(32)  NOT NULL,
  transport    VARCHAR(32)  NULL,                   -- which mail transport actually carried it
  address_hash CHAR(64)     NULL,                   -- sha256; the log must not be a second address book
  status       ENUM('sent','failed','suppressed','bounced','complained') NOT NULL,
  detail       VARCHAR(500) NULL,
  created_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT fk_engs_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE SET NULL,
  INDEX idx_engs_trigger (trigger_id, created_at),
  INDEX idx_engs_user (user_id, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- G16. Keyed on the ADDRESS, not the user. That was written when users.email was
-- not unique; after Phase 1b it stays, for a better reason: a bounce arrives as
-- an ADDRESS, does not know which account was behind it, and stays true after
-- that account changed its address or was deleted.
--
-- **`address_masked` and `created_by` are Phase 9's additions to this DDL.** The
-- hash-only table cannot be operated: an operator reading sha256 digests cannot
-- tell three typos from a whole domain refusing mail, and un-suppressing somebody
-- who fixed their mailbox is the one action the table must support. The domain
-- survives so a domain-wide failure is visible; the local part is DESTROYED
-- rather than shortened, so the column can never be read back as an address book.
-- `created_by` is what separates a row an admin typed from one the outbox worker
-- wrote (NULL).
CREATE TABLE IF NOT EXISTS engagement_suppressions (
  address_hash   CHAR(64)     NOT NULL PRIMARY KEY,   -- sha256 of the lowercased address
  address_masked VARCHAR(190) NULL,                   -- d***@example.com; never the local part
  channel        VARCHAR(32)  NOT NULL DEFAULT 'email',
  reason         ENUM('bounce','complaint','manual','unverified') NOT NULL,
  detail         VARCHAR(500) NULL,
  created_by     INT          NULL,                   -- the admin, for a manual row; NULL if automatic
  created_at     DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT fk_engsup_user FOREIGN KEY (created_by) REFERENCES users(id) ON DELETE SET NULL,
  INDEX idx_engsup_created (created_at),
  INDEX idx_engsup_reason (reason, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- G17: the in-app inbox. Core, game-agnostic, content-carrying.
CREATE TABLE IF NOT EXISTS user_notifications (
  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
  user_id     INT          NOT NULL,
  trigger_id  VARCHAR(96)  NOT NULL,
  title       VARCHAR(300) NOT NULL,
  body        TEXT         NULL,                    -- rendered by the inapp template, sanitized on write
  url         VARCHAR(500) NULL,                    -- relative only, validated like pageUrlTemplate
  dedupe_key  VARCHAR(190) NULL,
  read_at     DATETIME     NULL,
  created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  CONSTRAINT fk_un_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
  UNIQUE KEY uq_un_dedupe (user_id, dedupe_key),
  INDEX idx_un_unread (user_id, read_at, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

email_config grows rather than being replaced (additive-only discipline):

ALTER TABLE email_config ADD COLUMN IF NOT EXISTS transport      VARCHAR(32) NOT NULL DEFAULT 'smtp';
ALTER TABLE email_config ADD COLUMN IF NOT EXISTS credential_enc TEXT NULL;   -- AES-GCM JSON blob, transport-shaped
ALTER TABLE email_config ADD COLUMN IF NOT EXISTS reply_to       VARCHAR(255) NULL;

transport defaults to 'smtp' because Gmail OAuth2 is gone (§1.2a) — there is no longer a transport for an existing provider='gmail_oauth2' row to backfill into, so the upgrade lands every deployment on SMTP with empty credentials and an explicit admin warning rather than on a transport that no longer exists. provider and refresh_token_enc stay as dead columns (additive-only) and stop being read.

A single opaque credential_enc JSON blob is better than one column per provider field: SMTP, SES and Mailgun have disjoint credential shapes and the transport's credentialFields already describes its own. It also means adding Mailgun later is a registration plus an admin form, with no schema change at all.

The backfill of notification_subscriptions → notification_channel_prefs follows the precedent already in schema.sql:770 (the announce_jobs → announce_job_legs migration): an INSERT IGNORE … SELECT guarded so replay on every boot is a no-op after the first.

INSERT IGNORE INTO notification_channel_prefs (user_id, stream_id, channel, mode)
  SELECT user_id, stream_id, 'push', 'instant' FROM notification_subscriptions;

4.6 Basic templates and the editor (decision 5)

Two halves, and the first is the one that decides whether the second gets used.

4.6.1 The seeded set — a fresh deployment mails correctly before anyone opens the editor

Today every message body is a template literal inside mailer.js. Phase 5 moves them into engagement_templates as seeded rows, so the migration is a relocation rather than a regression: nothing that sends mail today starts depending on an operator authoring something first.

Seeded on boot by an idempotent seeder alongside db/seed.js's admin seed — INSERT … ON DUPLICATE KEY UPDATE keyed on seed_key, and it refuses to overwrite a row whose customized flag is set.

Transactional (protected = 1, editable but not deletable — the system breaks without them):

seed_key	Replaces	Variables
auth.password-reset	mailer.sendPasswordReset	username, resetUrl, expiresIn, siteName
auth.invite	mailer.sendInvite	acceptUrl, role, invitedByName, siteName
auth.email-verify	(new — Phase 9)	username, verifyUrl, expiresIn
admin.contact-message	mailer.sendContactMessage	fromName, fromEmail, message
admin.test	mailer.sendTest	siteName, transport, sentAt

Notification (protected = 0, replaceable):

seed_key	Replaces	Variables
notify.event	the generic single-event mail	title, intro, items[], actionUrl, unsubscribeUrl
notify.digest	teamDigestWorker's body	intro, periodLabel, items[], moreCount, scopeUrl, unsubscribeUrl
notify.team-post	mailer.sendTeamNotification immediate	teamName, authorName, threadTitle, excerpt, postUrl — postUrl, not threadUrl: it has to be the name team.forum.post DECLARES, or the mail links nowhere. Renamed in Phase 6 (seedVersion 2)
inapp.event	(new) — the in-app channel's short form	title, body, url

Three properties of the seeded set that are design, not packaging:

1. notify.event and notify.digest are generic on purpose. A new trigger — from core or from any module — renders through them with no authoring at all, because their variables are structural (title, intro, items[]) rather than domain-specific. An operator who wants a bespoke IDOC mail writes one; an operator who does not still gets a sane one. This is what stops "add a trigger" from meaning "and now write a template."
2. They are branded from data, not hardcoded. BRAND_* env and the theme_visual / brand_assets settings already drive the site's colours and logo (THEMING_AND_NAV.md §4.4); the seeded templates read the same resolved values, so one prebuilt image running as any shard mails in that shard's colours. No template contains a literal hex code or a logo URL.
3. A later release can improve a default without stealing an operator's work. seed_version + customized is the whole mechanism: on boot, a seed whose version is newer updates rows where customized = 0 and skips rows where it is 1, surfacing "an updated default is available" in the admin list instead. Same posture settingsJson takes — a stored value that is unusable is treated as absent, never as an error.

4.6.2 The editor

Built on the existing block machinery (blocks/registry.js, the prop panels, sanitizeBlocks.js), with an email.* block family (§4.4) — not a second editor. What it adds over the page builder:

• A variable palette from the trigger declaration. The right-hand panel lists exactly the variables §4.3 declares for this template's trigger, with type and example. Inserting one writes a token; it is never free-text. A template referencing an undeclared variable is refused at save, naming the variable — the editor validates, it does not blindly interpolate module JSON.
• Live preview from example values. No live game event needed. This is the reason example is a required part of the trigger declaration rather than documentation.
• A side-by-side HTML / plain-text view. The text part is generated from each block's toText, and is overridable per template. A published template with an empty text part is a save-time error.
• Test send to an address of the admin's choosing, through the configured transport, recorded in engagement_sends like any other message.
• Three preview widths (desktop / mobile / plain-text) and a dark-mode preview, because mail clients invert backgrounds and a light-only template renders as unreadable dark-on-dark in about a third of inboxes.
• A duplicate action, which is how an operator customizes a protected template safely: duplicate, edit, point the rule at the copy, leave the original intact.

Security posture, stated because this is the one new place operator HTML reaches a rendered surface: blocks are validated and sanitized on write (the existing validateBlocks → sanitize order), the preview renders in a sandboxed iframe with no allow-scripts, and variable interpolation is HTML-escaped by default with no raw-HTML variable type in v1. A module supplies data; it does not supply markup.

---

Part 5 — The module registration mechanism

5.1 Three additions to the contract, all modelled on what already works

// api — what the module registers (MODULE_API.md §2.4). Modelled on
// registerNotificationStreams: shape-checked at the call, collision-checked at
// apply(), <owner>.-prefixed by the existing namespaced() helper.
api.registerEventTriggers([{ id, label, description, variables, subjectKey, audience, version }])

// ctx — what core hands the module (§2.3). Modelled on ctx.teams.activity.push:
// fire-and-forget, never throws, never rejects, malformed input dropped and logged.
ctx.events.emit(triggerId, { subject, data, ownerUserId?, dedupeKey?, occurredAt? })

// ctx — the in-app sink, for a module that wants to write the inbox directly
// without a rule. Optional; most modules will only emit.
ctx.inbox.push(userId, { triggerId, title, body, url, dedupeKey })

// api — the audiences a module can resolve over its own data (decision 8).
// Same registration discipline as the triggers above; see §5.1a.
api.registerAudiences([{ id, label, description, ceiling, resolve }])

Why a new surface rather than extending registerNotificationStreams. A stream entry is a subscription toggle — label plus two booleans, with no statement about payload. A trigger is a data contract. Overloading the stream entry with a variables array would make every existing push stream look like it has an (empty) payload contract, and would put the emit path for content-free tickles and content-carrying events through one function whose behaviour depends on which fields the caller filled in. The two should stay separate for the same reason registerPostHook was kept out of registerAnnounceLeg ("a leg is a one-shot DELIVERY with retry and classification; a post hook maintains idempotent STATE" — registries.js).

What core reuses verbatim: stage() / apply()'s validate-then-commit-per-registrant discipline, namespaced() for the <owner>. prefix, the collision message that names the current holder, and the rule that nothing a registrant claims takes effect until the whole registrant is known good.

Core registers its own triggers through the same door, in registerCore(), exactly as it does for streams and the Discord leg. That is not ceremony — registries.js's header states the reason: "a registry only core's hardcoded base bypasses is a registry whose first real exercise is a module, which is the drift this PR exists to prevent."

5.1a Audiences — module-declared, operator-composable (decision 8)

The org lead's correction to Q7 is precise and worth stating exactly: there is no campaign surface, but lists exist — powered by game data, through the module, on a surface every module shares. "Team X's members" and "the governors" are legitimate audiences; "everyone who opened the last mail" is not, and nothing here builds it.

api.registerAudiences([{
  id: 'team.members',          // namespaced() prefixes it → 'uo.team.members'
  label: 'Members of a team',
  params: [{ id: 'teamId', type: 'int', required: true }],
  ceiling: 'members',          // the widest this audience can EVER resolve to (G24)
  resolve: async (params, ctx) => [/* user ids */],
}])

Four rules, each of which exists because of something already in the tree:

1. Core learns no game vocabulary. Core never knows what a governor is; it knows an id, a label and a resolve it may call. This is the same boundary registerNotificationStreams holds, and check:modules already proves core's own ids name no game concept.
2. The resolver returns user ids and nothing else. It is not handed a template, a channel or an address, and it cannot enumerate them — a module still cannot send mail (§1.2), and this must not become the back door that lets it. The engine maps ids to addresses on core's side, after preferences, suppression and the verification gate.
3. A composed segment is bounded by the narrowest ceiling it contains, not the widest. Operators may combine declared audiences with and/or/not into a saved segment. That is real power and it is the part with a security edge: composition must never widen. A OR B takes the tighter of the two ceilings, and the result is still checked against the trigger's own G24 ceiling before a rule using it can be saved. Union-widens is the intuitive implementation and it is the wrong one.
4. An audience whose module is uninstalled goes dormant, exactly as a rule does (§7.3). It resolves to the empty set and the rule referring to it shows as dormant — never an error, never auto-deleted, never a silent send to a different set of people because the id stopped resolving.

The lattice itself — settled in Phase 2, because this document named it everywhere and defined it nowhere. "Narrowest" needs an ordering, and the obvious one is wrong:

everyone                     anyone at all, signed in or not
  └── authenticated          any signed-in user
        ├── subscribers      signed-in users who opted into this id
        ├── members          a module-declared list (a Team, the governors)
        ├── staff            admin / editor / moderator
        │     └── admin      admins only          ← added in Phase 11
        └── owner            the one user the event is about

admin is the one node that was added after Phase 2 shipped the lattice, and the reason is worth recording (org lead, 2026-08-31, at the start of Phase 11). Phase 11's §8.6 table describes three triggers as admin-audience — uo.audit.staff_action, uo.economy.milestone, uo.world.saved — and account.login.result is classified by ../link/v5.md §4 as admin, by omission, "there is no rung below admin that a frame carrying an IP address and an auth verdict belongs on". The lattice had no such rung: its narrowest staff-ish value was staff, which ceilings.js defines as admin / editor / moderator, so ceilinging the operator-facing family there would have let a rule mail the staff audit digest to every editor. It is the only true refinement in the tree — an admin is staff, unlike any other pair of leaves — so it is a child rather than a seventh leaf, and permits/meet/meetAll need no change at all beyond the new PARENT entry. It is a contract change (a module may now declare ceiling: 'admin') and takes MODULE_API_VERSION to 1.8.0. Cheap in Phase 11 because no row anywhere stores an admin audience yet; expensive after cutover.

It is containment, not size. The tempting model is a flat total order — self < owner < staff < members < authenticated < everyone, compared with <= — and under it a trigger ceilinged at staff also permits owner, so a rule could mail uo.cheat.detected to the player it detected. Fewer people is not less exposure; the question is always which people.

So the four branches are mutually incomparable, deliberately: owner is not a subset of subscribers (an owner need not have subscribed), staff is not a subset of members, and no pair of them has a common descendant. admin is the single exception and it proves the rule — it is narrower than staff because every admin is staff, which is exactly the containment the other pairs lack. Three consequences:

• permits(ceiling, candidate) is "walk candidate up the tree and see whether you reach ceiling", and it fails closed on anything it does not recognise.
• meet(a, b) — the narrower of two — exists only when one is an ancestor of the other. Two incomparable ceilings have no bound at all, and the composition is REFUSED rather than resolved to a guess. Union-widens is the intuitive implementation and it is the wrong one; picking a side when there is no answer is the second-wrong one.
• The direction of the boolean operator is irrelevant. A AND B takes the tighter ceiling exactly as A OR B does, because a ceiling states what an expression is allowed to reach, not what it will resolve to. An empty composition has no bound and is null, never everyone.

The vocabulary travels with the trigger catalog (GET /admin/engagement/triggers serves it), so the rule editor never offers an audience the server will refuse. The server is still the boundary: Phase 4 re-checks every rule save.

Where it lands. The registration surface and the ceiling arithmetic belong in Phase 2, with the trigger declaration — G24's reasoning applies unchanged, and both are cheap now and expensive to retrofit into a rule model that already has rows in it. The composition UI belongs with the rules screen in Phase 4. module-uo's first real audiences come in Phase 11.

The composition UI, as built in Phase 4b. Its own nav entry, Admin → Engagement → Audiences, rather than a tab of the rules screen: a segment is reusable, independently edited, and deleted by a refusal that has to say how many rules still point at it. The composer offers one top-level all-of/any-of over audience leaves, each leaf rendering the params its declaration names (an int param is sent as a number, because the server type-checks it). Three things it does that follow from the rules above rather than from taste:

• “Exclude” appears only under “all of”. not is legal only as a child of and, so switching the group to “any of” drops the exclusions rather than composing a tree the server will refuse — and says so, because keeping them and failing at save would be worse than either.
• The stored ceiling is displayed, never chosen. The list shows what each saved audience may reach beside what it does reach right now (on demand, as a count), which is the pair an operator needs in order to understand a refusal.
• A tree nested deeper than the composer renders is not editable, and says so rather than being flattened — the same posture the rule editor takes with a nested condition. The stored grammar allows more nesting than any screen should offer.

The rule editor's half is the other side of the same rule: it offers only the audiences and saved segments the trigger's ceiling permits, derived from the permits list GET /admin/engagement/triggers serves. That is an affordance and not a boundary — the client must not hold a second copy of the lattice — and the save re-checks every time.

5.2 The seam, end to end

module-uo                                     core
─────────                                     ────
register(ctx, api)
  api.registerEventTriggers([...])  ─────────► registries: shape-check, namespace-check, collide-check
                                               │
shard event arrives (uoLinkSocket)             │  GET /admin/engagement/triggers ──► the rule + template editors
  shardIngest → mapper                         │
  ctx.events.emit('uo.house.idoc_warning', {   │
    subject: serial,                           │
    data: { character, house, location, … },   │
    ownerUserId: <resolved via shardLinks>     ▼
  })  ───────────────────────────────────────► engagement engine
                                                 1. validate payload against the declaration (§4.3)
                                                 2. find enabled rules for this trigger, eval conditions
                                                 3. resolve audience → user ids
                                                 4. per user: check notification_channel_prefs per channel
                                                 5. check engagement_cooldowns (rule, user, subject)
                                                 6. delay_seconds ? enqueue engagement_outbox : deliver now
                                                 7. cancel_on: cancel pending rows for the same subject
                                                       │
                                                       ▼
                                                 render template (blocks → HTML + text)
                                                       │
                                                       ▼
                                                 DeliveryChannel.deliver → transport → engagement_sends

Owner resolution stays in the module. module-uo/server/utils/shardPush.js already turns an ownerAcct into a website user via shardLinks — core has no idea what a game account is and must not learn. The module resolves and passes ownerUserId; core never sees ownerAcct.

5.3 What this costs the contract

MODULE_API_VERSION 1.6.0 → 1.7.0. Additions only (registerEventTriggers, registerAudiences, ctx.events.emit, ctx.inbox.push), no removal, no changed signature ⇒ minor by §1.1's table. module-uo's coreApi: "^1.3.0" still resolves, so no module is broken by the bump.

Knock-on obligations:

• client/src/modules/version.js carries the same number and a test asserts they agree.
• integration-kit/ci/core-ref.json pins a website main sha and scripts/checkCoreApi.js asserts equality with MODULE_API_VERSION. A bump turns the integration kit red on purpose — that is the mechanism, not a bug: someone must re-read the chapters and move the pin. Budget a kit PR.
• docs/website/MODULE_API.md §1.1, §2.3 and §2.4 need the new members, and §1.1's "1.6.0 has only ever been on edge" paragraph needs correcting (§0.5).

---

Part 6 — The phased plan

Same shape as the API v2 router-split plan: grouped, reviewable increments, one acceptance check per phase, and an explicit note on which guardrails apply.

Every phase carries the standing obligations — npm test --prefix server green, npm run swagger regenerated when a route changes, npm run routes:manifest -- --check clean, npm run check:modules clean, the documentation edits §6.0b assigns it, Conventional Commits, the AI-disclosure trailer, and a branch cut from a freshly-pulled base.

Stage A (1–1b–2) is prerequisite. Stage B (3–6) is the engagement system. Stage C (7–8) is the in-app channel. Stage D (9) is deliverability. Stage E (10–11) is the shard enrichment and runs in parallel from day one. Stage F (12–13) is the public site and the cutover.

6.0a The branching model — everything lands on edge, then one cutover to main

Every phase PR in every repo targets edge. main is touched exactly once, by the cutover (Phase 13). This is the model the module system, protocol v3, Teams and the M12 theming workstream each used, and it is the right one here for a specific reason: this workstream changes a wire protocol, a module API version and the mail path simultaneously, and those three land in different repos on different days. main must never hold a half-applied set of them.

Two operational findings, both checked on 2026-08-28 and both blocking before Phase 1:

1. Every existing edge is stale. git rev-list --left-right --count origin/main...origin/edge says edge is 0 ahead and behind main by: docs 16, module-uo 9, installer 7, servuo-plugins 7, website 5, link 3. They are leftovers from previous cutovers that were never refreshed after merging. Fast-forward each edge to main before the first phase PR — it is lossless (0 ahead), and skipping it means the cutover diff carries stale content or conflicts that have nothing to do with this workstream.
2. Three repos have no edge at all and need one cut from main: android-app (its M12 branch was deleted after that cutover), runicgateway.com, and Integration-kit.

Phase -1, executed 2026-08-28. Five fast-forwards — module-uo 9 behind, installer 7, servuo-plugins 7, website 5, link 3 — plus three branches cut from main (android-app, runicgateway.com, Integration-kit). docs' edge was fast-forwarded earlier and is ahead. Every fast-forward was 0 ahead, so all were lossless. Phase -1 is complete.

One trap worth recording, because it produced a wrong answer here first. git fetch origin does not prune, so a refs/remotes/origin/edge left over from a branch that was deleted server-side after a previous cutover still resolves. git rev-parse --verify origin/edge succeeds and git rev-list --left-right --count origin/main...origin/edge returns a plausible count — for android-app it reported "1 behind", which read exactly like a stale-but-present branch and is why this section was briefly "corrected" to say two repos rather than three. The branch had not existed on the server since the M12 cutover. Use git ls-remote --heads origin edge (or fetch with --prune) to ask whether a remote branch exists; a remote-tracking ref is a cache, not an answer.

Android CI does not run on edge. android-app/.gitea/workflows/pr-checks.yml triggers only on PRs into main, so every Phase 8 PR lands with zero CI and the cutover is the first real run. That was true of all nine M12 phase PRs and it is true again here. Either fix the trigger as Phase 8's first commit or budget for the cutover being the first honest build — decide deliberately rather than discovering it.

The cutover is per-repo but not independent. Phase 13 names the order, because a main that has the v5 sidecar and the v4 overlay is a shard that cannot pair.

6.0b Documentation is a phase deliverable, not an appendix

Every phase below owes specific documentation, and the phase is not done until it lands in the same PR (or, for cross-repo docs, a companion PR in the same review window). CLAUDE.md's rule — "a code change is not complete until docs/ reflects it" — is the floor; this table is the assignment.

Phase	docs/	Other repos
1 Remove Gmail OAuth2, SMTP	website/BACKEND_DESIGN.md §7 rewritten (not amended — it documents Gmail OAuth2 as the mechanism); route tables lose /admin/email/connect/*	website/README.md + .env.example wherever they point at Connect Gmail · runicgateway.com: notifications-and-email.mdx (its "There is no SMTP option" aside is now false), configuration.mdx:62, troubleshooting.mdx:101, system-architecture.mdx:117 · a release note
1a One self surface	website/BACKEND_DESIGN.md — the /auth/me prose and the /player+/admin router trees · api-route-inventory.json regenerated · website/ENGAGEMENT.md this phase	android/PLAN.md §6.4/§8 — the "routes stay for web back-compat" note is now false · website/API_V2_PLAN.md historical tables get a pointer
1b Unique email	website/BACKEND_DESIGN.md — the users table (the "not unique" note is now false), the new change/verify routes, and the de-dupe migration as an operator-visible upgrade step	website/README.md upgrade notes · a release note naming the admin report and the verification-gate default
2 Trigger registry	website/MODULE_API.md §1.1 (1.7.0 + correct the stale "1.6.0 has only ever been on edge" paragraph), §2.3 (ctx.events, ctx.inbox), §2.4 (registerEventTriggers, registerAudiences), the dormant-rule note (landed as §6.8) · website/ENGAGEMENT.md §4.3 and §5.1a kept true · BACKEND_DESIGN.md route table	Both deferred to the Phase 13 cutover window, deliberately — see Phase 2's as-built. Integration-kit's ci/core-ref.json pins a main sha, so the equality check stays green (and must stay green) for the whole edge period; runicgateway.com's checkFacts.mjs fetches from main, so setting platform.json.moduleApi → 1.7.0 now would turn that repo red immediately
3 Channel preferences	website/BACKEND_DESIGN.md route table · android/PLAN.md §11	—
4a Engine	website/ENGAGEMENT.md (rules/cooldown/outbox as built, and the two §4 defects it corrects) · BACKEND_DESIGN.md table inventory	—
4b Rules screen ✅	website/BACKEND_DESIGN.md route table (the twelve routes, incl. the PATCH …/enabled argument and the count-only preview) · website/ENGAGEMENT.md §5.1a composition UI	Landed with the phase (docs#184)
5a Templates ✅	website/ENGAGEMENT.md §4.6 as built · BACKEND_DESIGN.md — the engagement_templates table, the two block registries, the token grammar, and §7's multipart/subject changes	Landed with the phase
5b The editor	website/ENGAGEMENT.md §4.6.2 as built · BACKEND_DESIGN.md route table	runicgateway.com: a new admin docs page for the template editor
6 Email channel + Teams migration ✅	website/TEAMS.md §6.3/§6.4 rewritten — the Team pipeline it describes no longer exists as its own thing · website/ENGAGEMENT.md §4.2b + this phase as built · BACKEND_DESIGN.md route table and table inventory	runicgateway.com: administration/teams.mdx notification section. Landed with the phase
7 In-app channel (core+web) ✅	website/BACKEND_DESIGN.md routes + tables (the four inbox routes, user_notifications) · website/ENGAGEMENT.md this phase as built	runicgateway.com: notifications-and-email.mdx gains the in-app channel. Landed with the phase
8 In-app (Android) ✅	android/PLAN.md §7 (the Room exception) + §11 (the inbox as built) · website/ENGAGEMENT.md this phase as built	android-app/README.md. Landed with the phase
9 Deliverability	website/BACKEND_DESIGN.md §7 · a suppression/bounce operator section (the verification flow is Phase 1b's)	runicgateway.com: troubleshooting.mdx gains bounce/suppression · PLAY_DATA_SAFETY.md + /privacy — see Phase 12
10 Protocol bump	link/INTEGRATION.md §Housing and §Market (tables + examples) + the new account.login.result row · link/PLAN.md §5/§7 · a link/v5.md — the bump now carries three enrichments across three subsystems, which is what earned v3 and v4 their own design docs	servuo-plugins/overlay.toml · servuo-plugins/patches/README.md — vendor.sale stays in the tier and the docs must say what that costs · runicgateway.com: platform.json.protocol → 5, bundle.*, architecture/protocol-versions.mdx
11a module-uo triggers	modules/uo/API.md — the full trigger catalogue, its audiences and its ceilings, not one entry · modules/uo/README.md · website/ENGAGEMENT.md §8.6 kept true as rows ship · website/MODULE_API.md §1.1 (1.8.0) and the ceiling vocabulary wherever it is enumerated · BACKEND_DESIGN.md — the news.post publish path now runs through the engine	module-uo/README.md
11b Seeded rules + templates	website/ENGAGEMENT.md this phase as built · a release note naming the seeded-disabled news.post rule as an upgrade step (decision 5) — without it a deployment loses news push silently	runicgateway.com: capabilities.mjs and the notifications page — "one rule" and "the whole catalogue" are different marketing claims
12 Public site	website/ENGAGEMENT.md this phase as built, incl. the 12a/12b split and Phase 13's fill-in step	runicgateway.com, in full — see the phase. Two PRs: 12a (#26) mergeable now, 12b (#27) a draft held for the cutover window
13 Cutover ✅	README.md index rows · every doc's status line · this phase as built, incl. the two steps the window missed	.profile/README.md — the org lead called this a headline capability, so it landed
14 Retention	website/ENGAGEMENT.md this phase as built · BACKEND_DESIGN.md table inventory · the settings keys it adds	runicgateway.com: /privacy + PLAY_DATA_SAFETY.md, both generated from src/data/collection.mjs, whose deploy-engagement row says "nothing here expires on its own" and stops being true

One thing this table is protecting against. runicgateway.com appears in eight rows, and it is the only repo here whose checks are fetching these values rather than being told them — see Phase 12.

---

Phase 0 — Design of record ✅

This document, landed as docs/website/ENGAGEMENT.md with the five settled decisions recorded at the top. No code.

Acceptance: merged into docs/; §7.1's open questions each answered or explicitly deferred before the phase that depends on them starts. Q1, Q3, Q5 and Q7 were answered on 2026-08-28 (§7.1), which unblocked Phases 1, 2 and 4 and added Phase 1b; Q6 and §7.2 were answered on 2026-08-29, at the start of Phase 2 and before a line of it was written. Still outstanding: Q2 before Phase 4, Q4 before Phase 5b, Q8 before Phase 8.

This acceptance criterion has now paid for itself twice. Q6 and §7.2 were both tagged "decide in Phase 2", and §7.2's answer went against the recommendation in the text — which is exactly the outcome that is cheap to act on before the registry exists and expensive afterwards.

---

Phase 1 — Remove Gmail OAuth2; the transport registry + SMTP ✅

This phase is a subtraction and a replacement in one PR, because leaving the OAuth2 flow half-wired across a release is worse than either end state.

Delete everything in §1.2a's inventory. Extract utils/mailer.js behind the §3.1 interface with smtp as the sole registered transport. Admin → Email becomes a credential form driven by credentialFields. email_config gains transport / credential_enc / reply_to, defaulting to smtp with no credentials. All six existing call sites keep their exact failure contracts — the contact form's mailto fallback, the invite's copyable-link fallback, the password reset's generic 200, and sendTeamNotification's never-throws.

Ships with the cutover safety net §1.2a demands: an admin dashboard warning when the transport is configured but credential-less, a release note naming the operator action, and the smtp.gmail.com:587 + app-password migration path documented as the shortest route for the existing deployment.

Acceptance: test/mailer.test.js and test/emailConfig.model.test.js pass (amended only where they assert OAuth2 specifics); a fresh install with SMTP configured sends every one of the five current message types; an upgraded install with no SMTP credentials degrades exactly as an unconfigured deployment does today — contact form falls back to mailto, invites surface the link, resets answer 200 — and shows the warning; grep -r "smtp.gmail.com\|mail.google.com" server/src returns nothing. Guardrails: swagger regen + routes:manifest --check (two routes removed); no-hardcoded-host check (§3.2 rule 4) — which the deleted smtp.gmail.com literal is the first real test of.

As built (website#165, docs#178)

Delivered as specified, with four things worth recording because they are not what the plan above says.

1. Only half of §3.1 was built, deliberately. registerMailTransport ships; registerDeliveryChannel does not. Phase 1 has no consumer for addressFor/render/deliver — the engine that calls them is Phase 4 — and a registered channel nothing calls is a shape frozen before anything tried to use it. It arrives with the phase that consumes it. credentialFields is the piece that mattered here, since it is what makes the admin form generic.
2. enabled now gates every sender, which it did not before. buildTransport() used to test only "is there a refresh token and a sender", so the contact form kept sending after an admin unticked Enable email sending — isConfigured() honoured the toggle but the five direct senders bypassed it. The connect flow used to set enabled as a side effect of a consent redirect; with a credential form it has to mean what it says, so the gate moved onto the one path every sender shares. A deliberate behaviour change, not a refactor, and the only one in the phase.
3. The G22 warning reads the deprecated column. refresh_token_enc stays unread as configuration, but its presence is exactly "this deployment had working mail before the upgrade", which is the warning's whole condition. hadLegacyConnection && !hasCredential fires for the one deployment this happens to and stays silent on a fresh install, which has never had mail and would only learn to ignore the banner. The warning clears itself once a credential is saved — nothing has to remember to dismiss it.
4. npm run swagger was already broken and had to be fixed first (website#164, its own PR). It died with swagger-autogen's "invalid array length" runaway on a pristine edge, under Node 20 and 24, and at the commit whose own PR last regenerated the spec — so no phase that touches a route could have met the standing obligation. Bisected to one statement in teams.router.js: param('teamId').custom((v) => v === 'default' || TEAM_ID.test(v)). The rule is that nothing reaching .test( may sit inside a route statement, and the "per-file route limit" that phases 8 and 9 recorded does not exist — a three-route file carrying only that one route dies too. Worth knowing for every later phase in this workstream, all of which add routes.

Two smaller decisions: the credential is one encrypted JSON blob rather than a column per field, so adding a transport is never a schema change; and a blob that will not decrypt reads as absent rather than raising, so a rotated SECRET_ENC_KEY lands an admin on an "unconfigured" screen instead of a 500 that takes the contact form with it.

---

Phase 1a — One self-service surface: /auth/me/account ✅

Not in the original plan. It was added on 2026-08-29, ahead of Phase 1b, when mapping Phase 1b's ground truth turned up that self-service account security had three URL surfaces onto one controller — /auth/me/account/*, /player/account/* and /admin/account/*, all mounting the same account.controller handlers. Phase 1b adds a self-service field (email), Phase 3 adds another (channel preferences), and each would otherwise have been written three times.

/auth/me/account was already a strict superset, which is what settled which one to keep: it was the only surface carrying recovery codes, and /admin/account carried no username or password change at all. The web client already reached into /auth/me for two calls on a screen it otherwise served from /admin/account — the split was leaking before anyone touched it. Gating was equivalent where it overlapped: /player and /auth/me apply byte-identical noindex, requireAuth, and staffOnly on /admin/account was strictly narrower while buying nothing, since every handler is self-scoped to req.user.id.

14 routes deleted, 0 added, no handler changed. account.controller.js moved from router/v1/admin/ to router/v1/auth/, beside the one router that still reaches it. The web client's 14 call sites moved onto the root-level api.myAccount / api.changeUsername / … group. The Android app needed nothing — MeApi.kt was already 100% /auth/me/account/*.

It is a breaking change to the published OpenAPI surface, accepted deliberately: both consumers are in this org, and deprecating-then-deleting would have meant Phase 1b deciding whether to add its email routes to surfaces already marked for removal.

As built: routes.manifest.json shows exactly 14 deletions and 0 additions; the OpenAPI spec loses the same 14 paths with zero surviving path definitions changed and identical components (its large textual diff is pure reordering — removing the first-mounted router shifts every later path). Two swagger tags — Admin · Account and Player — were declared only by the deleted routes and went with them. 1203 server tests and 288 client tests green.

One thing this phase did not fix, on purpose: docs/website/api-route-inventory.json, the docs mirror of the route manifest, had drifted badly on its own (168 entries against the manifest's 203 — missing every Teams route, and still listing the two Gmail connect routes Phase 1 deleted). It is a generated mirror with no CI gate, so it was regenerated wholesale here rather than partially updated. A mirror nothing checks will drift again — a gate for it belongs in a later phase.

---

Phase 1b — Unique, changeable, verifiable email addresses ✅ (decision 6)

Lands alone, between 1 and 2, and before any engagement mail exists. It touches registration, SSO provisioning and the boot-time schema path — three security-sensitive surfaces — and retrofitting uniqueness after a send log and a suppression list hold rows is strictly worse than doing it now. §0.6 is the finding this phase discharges.

Four pieces, in this order within the PR:

1. Distinguish the constraint before adding one. Replace isDuplicateUsername()'s bare ER_DUP_ENTRY/1062 test with a check that reads the violated index off the driver error, and give its two callers (auth.controller.js:137, sso.controller.js:197) separate branches. This must be in the tree before the index is, or the register path starts lying and SSO sign-up starts failing opaquely the moment the ALTER runs.
2. De-duplicate, then index. A migration step that runs before the ALTER: for each duplicated address, the earliest-created account keeps it; every later duplicate has email set to NULL and email_verified to 0. Multiple NULLs are legal under a UNIQUE index, so nobody loses an account and nothing cascades. The affected accounts are written to an admin-visible report — who was cleared and what address they lost — because they are exactly the users who must be contacted. Then a UNIQUE index — on a generated email_norm column, not on email. The reasoning above (Foo@x.com and foo@x.com are one mailbox; folding belongs in the index rather than in bypassable application code) is right, but the collation this originally named is not: see the amendment below.
3. A self-serve change-and-verify flow, which does not exist today (§0.6 finding 4). Set/change address, a signed time-boxed verification link, email_verified set only on link use. It lands on /auth/me/account and nowhere else — Phase 1a made that the single self-service surface. SSO's emailVerified: Boolean(profile.email) is corrected at the same time to honour the IdP's actual email_verified claim rather than the mere presence of an address.
4. The verification gate as an admin setting — on for fresh installs, off for upgrades, so the live deployment does not silently stop mailing its existing opted-in users on the day it upgrades. The asymmetry is deliberate and is the same lesson as G22: a safe default must not be applied retroactively to a running system without telling anyone.

The error surface stays anti-enumeration. A collision returns a generic failure, the real reason is logged and not returned, the endpoint keeps its rate limit, and the failure is not scored by the bot detector — a legitimate user typing a colleague's address must not be pushed toward an IP ban for it.

Acceptance: a DB seeded with three accounts sharing an address boots clean, keeps the oldest, nulls two, and lists both in the admin report; registering with a taken address returns the generic failure, logs the specific one, increments no bot score, and does not say "username"; SSO sign-up with an address already held by another account fails with a distinguishable reason rather than exhausting PROVISION_MAX_TRIES; a user can change their address and it stays email_verified = 0 until the link is used; Foo@x.com collides with foo@x.com; an upgraded install has the gate off and a fresh one on. Guardrails: swagger regen + routes:manifest --check (the change/verify routes are new); the migration is idempotent and re-running ensureSchema() is a no-op; no destructive DDL — the de-dupe nulls a column, it never deletes a row.

As built (2026-08-29)

The index is on a generated column, because every _ci collation is also accent-insensitive. Step 2 above said to pin email to a case-insensitive collation "for the same reason username was". Tested against the deployment's own MariaDB 11.8, that is wrong in a way that would have destroyed data: under both utf8mb4_general_ci and the server-default utf8mb4_uca1400_ai_ci, josé@x.com and jose@x.com compare EQUAL. They are different mailboxes. A UNIQUE index over either collation refuses the second address forever, and the de-duplication below would have nulled a legitimate account's address and reported it as a duplicate that never was.

The accent-sensitive, case-insensitive collations that would be exactly right (utf8mb4_general1400_as_ci, utf8mb4_0900_as_ci) are MariaDB 11.4+ only, so pinning one moves the "a UNIQUE email can stop a boot" failure of §0.6 to a different trigger. What shipped instead:

email      VARCHAR(255) NULL,
email_norm VARCHAR(255) COLLATE utf8mb4_bin AS (LOWER(email)) STORED,
UNIQUE KEY uq_users_email_norm (email_norm)

LOWER() under a _bin collation folds case without folding accents — verified, not assumed. The fold still lives in the schema rather than in bypassable application code, which was the point of the original rule. Multiple NULLs remain legal, which is what lets the de-dupe clear an address without deleting an account. No foreign key references users.email, so the STORED-generated-column trap from TEAMS.md phase 2 (ER_GENERATED_COLUMN_FUNCTION_IS_NOT_ALLOWED on ON DELETE SET NULL) does not apply.

The de-dupe must group on that same column, and the first version did not. Written as LOWER(u2.email) = LOWER(u.email), the comparison uses the column's collation — accent-insensitive — so it over-folds even when the index does not. A seeded fixture caught it nulling jose@x.com as a "duplicate" of josé@x.com: the exact defect the index change was made to prevent, reintroduced one statement later. The migration therefore adds email_norm before de-duplicating and groups on it, so the two agree by construction rather than by a hand-matched COLLATE clause a later edit can get wrong. Order in schema.sql is load-bearing and commented as such.

Four decisions taken at build time, all approved before any code:

	Decision	Why
Index folding	generated LOWER() column + _bin index	above
Change flow	pending column, live address untouched	a typo cannot silently redirect account-recovery mail. Cost: a pending address reserves nothing, so two users may both be pending on one address and the second to confirm loses — with the same generic failure
Re-auth	currentPassword required, SSO carve-out	an address is where recovery lands, so repointing it is credential-grade; mirrors changePassword
Report surface	table + dashboard warning + read route	reuses the Phase 1 G22 shape: narrow, self-clearing, silent on installs it does not concern

One deviation from the text above, deliberate: step 3 says a "signed" link. Every comparable flow in this codebase (user_invites, password_resets, mobile_refresh_tokens) uses an opaque random token with only its sha256 at rest, and email_verifications matches them rather than introducing a second token mechanism for one caller.

provisionSsoPlayer now returns { user } or { error } instead of the user or a bare null. Two ways to fail need two things said to the person at the browser; the two call sites map error straight onto the sso_error code the login pages already render.

Verified on a live rig, not only in unit tests — a real MariaDB 11.8 seeded with the pre-upgrade schema plus three accounts sharing an address, upgraded by booting the real server, with a real SMTP send into a mail catcher (which also discharges Phase 1's outstanding "no live SMTP send"):

• the upgrade boots clean; oldest kept the address, two were nulled and reported with the exact addresses they lost; josé@ and jose@ both survived
• the gate seeded off on the upgrade and on on a fresh install
• the dashboard warning fired with the right count and cleared on acknowledge
• a change request staged the address and left the live one receiving mail; the link went only to the new address; opening it from a session-less client installed the address and set no cookie
• a replayed link, and a second account confirming an address the first had just taken, both returned the byte-identical generic 404 — the real reason logged, never returned
• NEWMAIL@RIG.TEST was refused at registration as a duplicate of newmail@rig.test, while néwmail@rig.test registered successfully beside it

Left for later, deliberately: nothing consumes email_verification_required yet — the engine that would honour it is Phase 4 and the deliverability rules are Phase 9. It is seeded and editable now because the fresh-vs-upgrade distinction is only knowable at the migration that adds it, and reconstructing "was this install fresh?" afterwards is guesswork.

---

Phase 2 — The trigger registry and the variable contract ✅

api.registerEventTriggers + ctx.events.emit in modules/registries.js and modules/loader.js; MODULE_API_VERSION → 1.7.0 on both halves; core registers its own triggers (news, the four Team events) through registerCore(). npm run engagement:manifest + the CI --check. No delivery yet — emit validates, logs and stops.

A trigger declaration also carries its audience ceiling (G24) — the widest audience a rule may ever give it — and its kind (event now, scheduled reserved for G25). Both are cheap here and expensive to retrofit into the rule model later.

Phase 2 also lands api.registerAudiences and the ceiling arithmetic (§5.1a) — the same registration discipline, and the same "cheap now, expensive later" argument G24 makes for the trigger ceiling.

Acceptance: core's triggers appear in GET /admin/engagement/triggers; a module registering an un-namespaced trigger or audience fails to load with the holder named; an A OR B composition takes the narrower of the two ceilings, not the wider; an audience whose module is uninstalled resolves empty and shows dormant rather than erroring; a payload missing a required variable throws in dev and is dropped+logged in prod; a rule cannot be saved with an audience wider than its trigger's ceiling; engagement-triggers.json diffs zero in CI. Guardrails: the new manifest --check (this is where the "manifest-style guardrail" the brief asks about belongs); check:modules proves core's own trigger ids name no game concept.

As built (2026-08-29)

Three design questions were settled by the org lead before any code, and two of them the plan had deferred to this phase on purpose:

	Question	Decision
§7.2	one namespace, or two?	ONE. A trigger is a payload contract attached to an id that may also carry a subscription toggle
§7.1 Q6	time-based triggers	declare now, build after Phase 9 — kind: 'scheduled' is in the contract, the manifest and every stored declaration from today. The evaluator was assigned on 2026-09-01 (EVENTS.md §N3): the Event System runner becomes it, built in that workstream P2
—	what "narrower" means for a ceiling	an explicit subset lattice; two incomparable ceilings have no bound and the save is REFUSED, never guessed

One namespace was the more invasive of the two options and it is worth stating what it bought and what it cost. It buys notification_channel_prefs.stream_id staying single-keyed (§4.5): under two namespaces its primary key would have needed a kind discriminator, and news.post would have named two different things forever. It costs a new rule in registries.js — an id has exactly one owner across both facets — enforced in both directions, so a module cannot attach a payload contract to another module's stream and cannot claim a stream id another module declared a trigger for. Core's five trigger ids are its five stream ids, so the same-owner upgrade case is exercised on every boot rather than only by a module.

Three consequences fell out of it that the §7.2 text did not anticipate:

• The id grammar had to be relaxed, not just shared. STREAM_ID did not admit _, and §4.3's own worked example is uo.house.idoc_warning. Two grammars over one namespace would mean an id that is legal as a trigger and illegal as the stream it is the same event as. It is a relaxation only — every id valid before is valid now, and no stored id changes.
• The legacy allowlist had to be shared too. The seven grandfathered uo.* stream ids are exempt from the prefix rule for triggers as well, and it cannot be otherwise: under one namespace idoc.warning is a single id, so if uo may hold it unprefixed as a stream it may hold it unprefixed as a trigger. Any other answer means those seven could never gain a payload contract.
• The push catalog is unchanged. allStreams() still serves the stream facet only, so a trigger-only id (uo.house.idoc_warning) does not appear in the catalog the shipped Android client reads. A trigger-only id gets email and in-app preferences in Phase 3 and no push toggle, which is correct — there is nothing to push it to.

The ceiling lattice is the one thing this plan named everywhere and defined nowhere, and getting it wrong would have been a security defect rather than a rough edge. §5.1a now carries the definition; the short version is that the tempting flat ordering — self < owner < staff < members < authenticated < everyone — permits a staff-ceilinged trigger to be given an owner audience, which is a rule that mails uo.cheat.detected to the player it detected. Fewer people is not less exposure.

What landed:

• server/src/modules/ceilings.js — the six-value lattice, permits, meet, meetAll (Phase 11 adds a seventh, admin, as a child of staff. See §5.1a for why it was not there from the start and why the arithmetic is unchanged.)
• registerEventTriggers / registerAudiences on the existing stage() + apply() discipline, with the cross-facet collision checks and the shared legacy allowlist
• ctx.events.emit (utils/engagementEmit.js) — validate, log, stop; throws in dev, drops and logs in prod; the owner is bound by core and never read from the arguments
• ctx.inbox.push — present and throws until Phase 7, the shape 1.6.0 settled on (Phase 7 filled it in. Not a version bump: the signature is the one 1.7.0 declared.)
• config/coreTriggers.js — core's five, registered through registerCore()
• GET /admin/engagement/{triggers,audiences} — admin-only, served from the registries, no table
• npm run engagement:manifest (+ --check in CI) and the committed engagement-triggers.json
• MODULE_API_VERSION → 1.7.0 on both halves; MODULE_API.md §1.1, §2.3, §2.4 and a new §6.8

Two things §6.0b's Phase 2 row assigns that deliberately do NOT land in this window, and neither is a slip:

• integration-kit's ci/core-ref.json. The pin names a website main sha and checkCoreApi.js asserts equality with what that sha declares. 1.7.0 is on edge, main still says 1.6.0, so the kit is green and moving the pin now would pin the book to a commit that is still in flight — which the pin's own prose forbids ("the kit is written against what shipped"). The re-pin and chapter 2's "registering a trigger" section belong in the Phase 13 cutover window.
• runicgateway.com's platform.json.moduleApi → 1.7.0. scripts/checkFacts.mjs fetches the authority from the source repo's main. Setting it to 1.7.0 today turns that repo red immediately and for the whole edge period. It is Phase 12's, in the cutover window, exactly as the phase says.

Four smaller decisions taken at build time:

	Decision	Why
ceiling required, no default	registration fails without one	there is no safe value to guess: owner silently breaks a broadcast, authenticated silently widens a staff-only event
example required per variable	registration fails without one	§4.3 property 3 is right and a soft version of it is worthless — without an example, preview needs a live game event, which is how template systems ship untested
audiences get their own id space	not the trigger/stream namespace	an audience names a set of PEOPLE, a trigger names an EVENT; uo.team.members as both is not a collision
url variables are site-relative	validated like pageUrlTemplate	a payload variable ends up in an href in an email; //evil.test/x passes an "is it rooted" check and is protocol-relative

One acceptance criterion is only half-dischargeable here, and that is not a slip. "A rule cannot be saved with an audience wider than its trigger's ceiling" needs engagement_rules, which is Phase 4's. What Phase 2 owes and delivers is the arithmetic that check will call (permits / meet / meetAll, with tests for the incomparable cases a total order would have waved through) and the same rule applied where a row already exists: a declaration whose default audience is wider than — or incomparable with — its own ceiling is refused at registration. Phase 4 adds the second call site, not the second implementation.

Left for later, deliberately: nothing consumes an emitted event yet. emit validates and logs, and Phase 4 replaces that log line with the engine call. Core's five declarations are registered but not yet emitted — the Team pipeline keeps its hardcoded mail until Phase 6 migrates it onto the engine, and this is what it migrates onto.

---

Phase 3 — Channel preferences ✅

notification_channel_prefs + the idempotent backfill from notification_subscriptions. New GET·PUT /auth/me/notifications/channels. /auth/me/notifications/subscriptions keeps its exact wire shape and becomes the push projection — writes fan out to both.

Acceptance: the shipped Android app's flat {streams:[…]} PUT still round-trips, including the empty-array case the app's DTO comment warns about; a per-channel PUT sets email without touching push; a fresh user's email mode defaults off and push defaults instant push defaults off too (§4.5's defaultMode — the struck text was wrong; see the as-built below). Guardrails: swagger + route manifest; a test pinning the legacy wire shape byte-for-byte.

---

As built (2026-08-29)

Three decisions were settled by the org lead before any code, and one of them corrects this phase's own acceptance criterion.

	Question	Decision
—	how much of §3.1's registerDeliveryChannel lands now	the declarative half only — id, label, carriesContent, defaultMode, supportsDigest. addressFor / render / deliver wait for the phases that can exercise them
—	push's defaultMode	off. The acceptance line below said instant; it could not be
—	whole-set PUT or sparse	sparse, on the (id, channel) pair — deliberately unlike the two whole-set PUTs either side of it

The acceptance line was wrong, and it is worth saying exactly how. "A fresh user's email mode defaults off and push defaults instant" reads naturally beside §3.1's "email opt-IN, push opt-OUT", and §3.1 got that from team_notification_prefs, where no row genuinely does mean notified. But push stream subscriptions have never worked that way: notification_subscriptions holds a row only when a user opted in, so no row means not subscribed. A defaultMode of instant would have projected the entire catalog into GET /auth/me/notifications/subscriptions for every existing user, and the shipped Android client would have shown every toggle switched on after an upgrade nobody asked for. It is a live behaviour change dressed as a default. All three channels declare off, and a test asserts the legacy GET returns {streams:[]} for a fresh user so it cannot drift back.

Why the channel registry could not wait for Phase 6. §3.1 says defaultMode is expressed once, and reading a preference means knowing it — a row exists only where a user has said something. The alternative was a constant list beside the prefs model, i.e. that expression in a second place, two phases before the registry replaced it. What did not land is the behavioural half: registering a deliver nothing calls freezes a signature before anything has tried to use it, which is the reason transports/index.js deferred the whole file in Phase 1. Core's three channels are declared, and inapp is declared off for a reason particular to it — the inbox does not exist until Phase 7, and a default of instant would mean every user is opted into a surface with no rows, so the first thing Phase 7 shipped would be a backlog. Phase 7 changed it to instant once there was a surface to look at: an inbox item wakes no device and leaves no building, and the backlog this paragraph feared cannot happen against an empty table. See Phase 7's decision 1.

The sparse PUT is the one place this phase leaves the router's idiom, and it buys two things. A whole-set body forces a client that only manages email to send every push row back or wipe them. And off becomes a mode rather than an omission — which means this endpoint has no empty-array case at all, so the kotlinx gotcha putTeamPrefs had to document (a defaulted array field is dropped from the body, and "clear the last one" arrives as no array) simply cannot arise here. prefs is still required, so a request DTO with no default is still the right shape on the app side.

The projection, stated as an invariant. notification_subscriptions stays exactly what utils/pushDispatch reads, so this phase touches no delivery path at all. Both endpoints maintain: a push pref with mode <> 'off' ⟺ a notification_subscriptions row — the legacy PUT with a whole-set sweep, the channels PUT one pair at a time. An explicit off is stored rather than deleted, because folding "I turned this off" back into "I never said" is only harmless while the default happens to be off.

One thing landed that the phase did not name, and it is a G24 consequence rather than scope creep. A trigger whose ceiling is staff can never reach a non-staff user, so offering them a toggle is offering a control that does nothing and disclosing that the event exists — uo.cheat.detected would otherwise appear by name in every player's preferences screen the moment Phase 11 declared it. It is filtered from the catalog and gated on write, not merely hidden. members is deliberately not filtered: membership is a runtime resolver's answer, and a preference set before joining a Team should already be in place when you join. This gave ceilings.js its first consumer for the staff label's long-standing claim of "admin / editor / moderator", now written down as STAFF_CEILING_ROLES — and deliberately not teamGrants.STAFF_ROLES (['admin','moderator']), which answers the different question of who may act on a Team they are not in.

What landed:

• server/src/engagement/channels.js — registerDeliveryChannel, MODES, defaultMode, modesFor, acceptsMode; coreChannels.js declares push / email / inapp, registered through the subsystem's one door (require('./engagement') from app.js, beside registerCore())
• notification_channel_prefs + the replay-safe INSERT IGNORE … SELECT backfill, copying the announce_jobs → announce_job_legs precedent
• model/notificationChannelPrefs/ — the catalog union, effective-mode resolution, the sparse apply, and mirrorPushSet for the legacy path; two single-row helpers on notificationSubs.db
• GET · PUT /auth/me/notifications/channels, swagger schemas, route manifest
• ceilings.STAFF_CEILING_ROLES / isStaffRole

Left for later, deliberately: no web or app surface. The endpoint exists and is documented (../android/PLAN.md §11); the screens are Phase 7 (web) and Phase 8 (app), which is where a user can see something a preference actually governs.

---

Phase 4 — The engine: rules, cooldowns, outbox ✅

Split into 4a and 4b at the start of the phase, on the same argument that split Phase 5: the half that first makes this system capable of sending is worth reviewing without a React screen in the same diff, and the ceiling arithmetic that decides who a rule may reach is worth reading on its own.

4a — the engine (server only) ✅

engagement_rules, engagement_audience_segments, engagement_cooldowns, engagement_outbox, engagement_sends, the sweep worker (setInterval + unref + stop, wired into server.js like its five siblings), audience resolution, condition evaluation, delay and cancellation, and the save-path validation the admin surface will call. No HTTP surface at all — provably done when a fired trigger produces an outbox row and a send-log entry with no UI in the picture.

4b — the admin surface ✅

Admin → Engagement → Rules, the §5.1a segment composition UI, and the routes underneath them. Q4's answer places it in its own top-level nav group (below), so 4b also creates the group that Triggers, Templates and the send log join in Phase 5.

Acceptance: a trigger fired twice inside cooldown_seconds for the same (rule, user, subject) sends once; the same trigger for a different subject sends again; a scheduled row is cancelled by a cancel_on trigger and never sends; a restart mid-window still sends exactly once; a duplicate dedupe_key is a successful no-op. Guardrails: swagger + route manifest (4b — 4a adds no routes); a named test for the multi-house cooldown case (§4.1).

---

As built — 4a (2026-08-29)

Three decisions were settled by the org lead before any code, and two of them are §7.1 questions this phase was blocked on.

	Question	Decision
Q2	multi-instance: SKIP LOCKED, or document single-instance	Neither, exactly: a compare-and-set claim — UPDATE … SET status='sending' WHERE id=? AND status='scheduled', the winner being whoever the server reports affectedRows = 1 to. It is what §4.2a's ENUM was already shaped for (nothing else needs a sending state), it needs no open transaction and no MariaDB version floor, and it delivers Q2's intent
Q4	where the engagement admin surface lives	its own top-level nav group, "Engagement", beside Content / Moderation / System — Rules now, Triggers / Templates / Send Log in Phase 5. Email Delivery stays a section of Settings for now
—	one PR or two	4a / 4b, as above

What Q2's answer does and does not buy. It makes the outbox safe for two app instances. It does not make the deployment multi-instance: announceWorker, teamDigestWorker, teamForumUploadSweep and teamActivityPrune are all still written for one, and widening them is not this phase's scope. What it buys is that the one table that will carry mail is ready for the day it is, which is cheap now and expensive after mail has doubled once.

Two defects in this document's own §4, both found by building it.

1. §4.2a's UNIQUE KEY uq_engo_dedupe (dedupe_key) was a data-loss bug, not a style question. A dedupe key names the EVENT — "house 0x4001 entered IDOC" — and one event legitimately becomes many outbox rows: an audience of fifty users is fifty rows, a rule spanning email and in-app doubles that, and a second rule on the same trigger doubles it again. Under a global unique index the first of those inserts wins and every other one is silently ignored, so ninety-nine recipients are dropped by the mechanism that exists to stop a replayed event becoming a second mail. Shipped as UNIQUE (rule_id, user_id, channel, dedupe_key), which keeps exactly the replay guarantee and nothing more. A test asserts one key fans out to six rows.

2. §4.1's single INSERT … ON DUPLICATE KEY UPDATE cooldown claim does not work against this codebase's pool, and the way it fails is silent. Its answer is read out of affectedRows on the usual contract — 1 inserted, 2 updated-and-changed, 0 for a duplicate key whose update changed nothing, that 0 being "still cooling". The mariadb Node connector defaults foundRows: true, which makes affectedRows report rows matched rather than rows changed, and utils/db.js does not override it. Under that pool the no-op returns 1 and is indistinguishable from a fresh insert: every cooldown passes, always. Shipped as two statements instead, each of which is its own atomic decision and neither of which asks affectedRows to mean two things:

   -- 1. claim by moving the row, guarded in a WHERE clause where a row either matches or does not
   UPDATE engagement_cooldowns SET last_fired_at = ?, fire_count = fire_count + 1
    WHERE rule_id = ? AND user_id = ? AND subject_key = ?
      AND last_fired_at <= ? - INTERVAL ? SECOND;
   -- 2. matched nothing? then the row is absent or cooling; INSERT IGNORE separates the two
   INSERT IGNORE INTO engagement_cooldowns (rule_id, user_id, subject_key, last_fired_at, fire_count)
   VALUES (?, ?, ?, ?, 1);
   

   Still race-free, and each race resolves the right way: two concurrent first fires both fall to the INSERT and the primary key picks one; two concurrent fires after expiry serialise on the row lock and the second re-evaluates its guard against the committed last_fired_at.

The second defect is the reason this phase has a second test file. engagementEngine.test.js stubs the five tables and runs the engine's logic against in-memory stand-ins, which is right for everything the engine decides — and it was green against the broken cooldown claim, because a stub can only agree with whoever wrote it, and the same misreading produced both. The statements whose correctness is a server contract now run against a real MariaDB in engagementEngineSql.test.js, which creates a throwaway database, drops it, and skips when there is none so CI stays green without one. The general lesson: a stub is a fine stand-in for a table and a poor one for a protocol.

The gate order is the design. Enabled rules → conditions → audience → ceiling re-check → per-channel preference → per-rule hourly ceiling → cooldown → deduped enqueue. Two of those placements are load-bearing:

• The G24 ceiling is re-checked at SEND time, not only at save. The save path already ran the same ceilings.permits, so the only way this can fail is the case it exists for — a module upgrade that narrows its trigger's declaration underneath a rule saved when it was wider. Without it, a rule written against yesterday's declaration keeps reaching yesterday's population forever. This is the second call site §5.1a promised, not a second implementation.
• The hourly ceiling is checked before the cooldown, because the ceiling is about the rule and the cooldown is about one recipient. A rule that has hit its ceiling should not also burn every recipient's cooldown slot on sends that never happen.

Segments (§5.1a) as built, with one rule the design did not state. not is legal only as a child of and. A complement needs a universe, and the only one available that does not widen is the set its siblings produced: A AND NOT B is "A, less B", which is what an operator wants and cannot be composed into a broadcast. A bare NOT B — or A OR NOT B — would have to mean "everyone except…", which is a way to build the whole deployment out of one narrow audience and is precisely the widening rule 3 forbids. It is refused at save with that sentence.

The other half of that: a not contributes no ceiling to the meet. Excluding people cannot widen who an expression reaches, so folding the excluded audience's ceiling in would refuse safe segments — members AND NOT staff would hit meet('members','staff') = null and be rejected even though it reaches strictly fewer people than members alone.

Dormancy, three ways, and none of them deletes anything (§7.3, §5.1a rule 4). A rule naming an unregistered trigger, a rule whose channel is gone, and a rule whose segment was deleted are all listed, flagged and left alone. In particular engagement_rules.audience_segment_id deliberately carries no foreign key: ON DELETE CASCADE would delete an operator's rules and ON DELETE SET NULL would silently fall the rule back to its plain audience column — and that fallback reaches a different set of people, which is the exact failure §5.1a rule 4 exists to prevent. Deleting a segment that a rule still uses is refused in the model, with the count.

Conditions are a small closed grammar, not an expression language: and/or/not over comparisons of one declared variable against a literal, every operator renderable as a dropdown, bounded in list length and nesting depth because the tree comes out of a JSON column an admin can write and is walked on the emit path. Two properties worth keeping:

• An absent variable makes every comparison false, including ne. "Not equal to IDOC" reads as satisfied by nothing at all, and treating it that way would fire a rule on every event that omits an optional variable. present / absent are the honest way to ask.
• A tree that no longer parses evaluates false, never "no conditions". Failing closed stops the mail; failing open mails everyone the rule could ever reach.

ctx.events.emit does not await the engine. It is called from inside a game-event handler, and the caller's job is to say the event happened — not to wait on rule lookups, audience resolution and a dozen inserts to find out whether it is allowed to carry on. That is the same argument the C# side's Emit() makes about the Core thread. dispatch catches everything internally and never rejects. The consequence a caller must know: emit returns before the outbox rows exist, so a test that wants the delivery decision calls engine.dispatch directly.

Nothing is delivered, and that is visible rather than pretended. A channel's deliver arrives with email in Phase 6 and the in-app inbox in Phase 7. Until then the worker claims the row, finds no deliver, finishes it failed, and writes a send-log row saying so in as many words. Recording sent would be a lie in the one table whose entire purpose is answering "did they get it"; leaving the row scheduled would mean an IDOC warning queued today arriving three weeks later on the deploy that first shipped a mailer. On a real deployment the path is unreachable anyway — core seeds no rules and enabled defaults to 0, so nothing enqueues until 4b's screen exists and an operator uses it.

Three smaller things the phase settled:

• everyone and authenticated resolve identically. A signed-out visitor has no address, no device and no inbox, so the widest set the engine can deliver to is the active user table. The lattice still distinguishes them — a trigger ceilinged everyone permits an authenticated rule and not the reverse — and only the resolution coincides.
• A plain members audience with no segment reaches nobody. members is the ceiling for "a module-declared list"; without a segment there is no list, and core knows no game vocabulary with which to guess. Inert and visible, rather than quietly falling back to something wider.
• Every audience is filtered through users.status = 'active', including a module's. A module's resolver returns ids over its own store and has no notion of account status; a banned account must not be mailable by a module returning its id.

---

As built — 4b (2026-08-29)

The admin surface over the Phase 4a engine: Admin → Engagement → Rules, Admin → Engagement → Audiences, the twelve routes under them and the reach preview. Nothing in the engine changed; what changed is that an operator can now reach it, which is what makes every rule in 4a's model a rule a person will actually meet.

Four decisions the org lead settled before any code, all four the recommendation:

	Question	Decision
Segments	a fifth nav entry, a sub-tab, or inline in the rule editor	its own nav entry, "Audiences" — a segment is a reusable object with its own list, its own edit and a delete that is refused with a count, and none of those has anywhere to live inside a screen about rules
The switch	a PATCH …/enabled route, or a full PUT	its own route, writing that column and no other
Preview	count only, count plus a sample, or none in 4b	count only, on demand
Delete	hard delete with a confirm, or disable-only	hard delete — the send log survives it

The enable switch is the decision with the most content in it, and it is a correctness argument rather than a convenience one. A PUT re-validates, and validation is against the registries as they are now. So the rules a re-validating toggle cannot switch off are exactly: a rule whose module has been uninstalled, a rule naming a channel that is gone, and a rule whose trigger has since narrowed its ceiling underneath a saved audience. Those are the three rules an operator most urgently wants stopped. PATCH …/enabled writes one column and always works. Switching a rule on without re-validation is safe for a different reason: audiences.permitted runs again at send time, so an enabled-but-no-longer-permitted rule resolves to nobody rather than to the wrong people.

The reach preview calls the engine's own resolver, audiences.resolveForRule, rather than a second query that agrees with it today — a preview built out of its own SQL can be wrong about the one thing it exists to say. It answers a count and nothing else: not a sample, not names. The resolver's output for a module-declared segment is a set of players derived from game data, and an editor that rendered them would be a user-enumeration surface reached from a screen about mail scheduling. Three fields exist because the bare number would otherwise be a lie:

• capped — every audience query is bounded at MAX_AUDIENCE (5000), so a count landing exactly on the bound is a floor. The screen says "at least 5000", never "5000".
• reason — an owner audience resolves per event from an id the event carries, so it has no advance answer. It reports 0 with the reason, because a bare 0 reads as "nobody".
• permitted — whether the trigger's G24 ceiling allows the reach just counted. Without it the editor shows a healthy number beside a save the server will refuse, which reads as a bug in the save rather than as the ceiling doing its job.

Two defects found by walking it against a live server, neither of which any test in the tree would have caught, and both of them in Phase 4a's code rather than 4b's:

1. A rule pointing at a dormant segment was reported as healthy. listAnnotated asked only whether the segment ROW still existed (§7.3's case: the segment was deleted). The other shape of the same failure is §5.1a rule 4's: the segment row is exactly where it was, and every audience in it belongs to a module that has been uninstalled. Both leave the rule reaching nobody; only one leaves nothing behind. Uninstalling a module under an enabled rule produced a rule the screen showed as on, healthy and firing, which is the one thing this screen exists not to do. The walk over the expression now lives in engagement/segments.js as missingAudiences, and both the segment list and the rule list ask it, so the two cannot disagree about what dormant means.
2. "1 rule still use this segment." The delete refusal pluralised the noun and not the verb. It is a one-word fix and it is in the sentence an operator reads at the moment they are being told no.

Six more defects came out of driving the two screens in a browser, after the API walk above had already found the two in Phase 4a's code. None of them is visible from a test or from curl, and two of them cost an operator something real:

1. The Audience dropdown rendered empty before a trigger was chosen. audienceChoicesFor(null) answers [] — correctly, because without a trigger there is no ceiling and therefore nothing it may legitimately offer. But a <select> with zero options reads as a control that is broken, not one that is waiting. It now carries "Choose a trigger first…" and is disabled.
2. A members audience with no saved audience reaches nobody, and only the preview button said so. This is the design (§5.1a: members is the ceiling for "a module-declared list", and without a list core cannot guess) — but it is also the default the instant an operator picks any members-ceiling trigger, which turns a documented property into a trap: the rule saves, gets switched on, and mails nobody, with nothing on the screen saying so unless the operator happens to press Preview. The editor now says it inline, before the save, and stands down once a preview has answered the same question more precisely.
3. The composer offered "exclude" on the only row, which builds an and whose every child is a complement. The server refuses that correctly — "has nothing but complements, there is no set to exclude from" — but only after a save. It is one checkbox away at all times, so the composer now refuses it inline, in the operator's words.
4. The template-key input truncated its own placeholder and the text said "optional until Phase 5", which is a sentence about this document rather than about the operator's deployment.
5. "segment" leaked into a screen that says "saved audience" everywhere else. The API, the schema and this document should keep saying segment — one word for one table — but an operator meets the concept under a heading that reads "Audiences", and a sentence that switches vocabulary mid-screen reads as a sentence about something else. Translated at the point of display only.
6. The composer repeated its "AUDIENCE" heading above every row; the heading belongs to the group.

And one thing that is worth knowing but is not a defect in this phase: rebuilding client/dist while the server is running blanks the whole SPA. The HTML shell resolves core's hashed bundle filename at boot, so after a rebuild it still points at a filename that no longer exists; core's bundle 404s, window.__rg is never published, and modules/uo/entry.js throws the "core did not publish its shared dependencies" error from MODULE_API.md §3.1 into a blank page. Restart the server after every client build. The error names core, and core is not at fault.

A window.confirm freezes browser automation. The two destructive actions here use it, matching InvitesAdmin and ModulesAdmin, and that is the right call for the product — but a native dialog blocks CDP entirely, so a delete cannot be driven from a script and a session that opens one is stuck until a human dismisses it. Exercise those two paths over the API instead.

Three smaller things the screens decided:

• A rule's trigger is fixed once the rule exists. engagementRules.db.update never carried trigger_id, and 4b is where that becomes a stated rule rather than an omission: a rule's cooldown rows, its pending outbox rows and its send-log history are all about one trigger id, and re-pointing the rule silently re-attributes all three. The editor renders the field read-only and says why; changing the trigger means a new rule.
• A condition tree the editor cannot render is shown, not flattened. The editor offers the flat half of the grammar — one and/or over a list of comparisons, every operator a dropdown narrowed to the picked variable's declared type. A AND (B OR C) flattened to A AND B AND C fires on different events and the operator would have no way to know the save had done it, so such a rule opens read-only with its JSON visible and one honest choice: leave it, or clear it and start again.
• Literals are coerced to the type the trigger declared, in the client, before the save. Every value in an HTML input is a string and the server rightly refuses {cmp: 'gt', value: "5"} against an int. A value that does not parse is passed through unchanged rather than becoming NaN or false, so the refusal names the variable instead of the rule saving cleanly having compared against a number nobody typed.

Where the logic lives. client/src/lib/engagementRules.js — plain JS, 25 tests — holds everything the two screens decide: the form↔payload mapping, which audiences a trigger permits (derived from the permits list the server sends, never a second copy of the lattice), the reach sentence, the not-placement check, the condition round trip. None of it is a boundary; the server decides and the engine re-checks. It is in a .js because the test runner cannot reach a .jsx, and because a client-side copy of a security rule is a copy that drifts — so the client holds the affordance (do not offer what will be refused) and the server holds the answer.

The rig that made the live walk possible, and worth reusing. Core declares no audiences — it knows no game vocabulary — and module-uo 0.3.0 declares none either, so on a stock local stack the whole segment half of this phase is untestable. A ~20-line throwaway module dropped into website/modules/rig/ (a module.json plus a server/index.js calling api.registerAudiences) declares four audiences at three different ceilings and makes the entire §5.1a arithmetic walkable: OR taking the tighter ceiling, two incomparable ceilings being refused rather than guessed, members AND NOT staff being allowed, a parameterised audience, the 409 on a segment in use, and — by deleting the directory and restarting — dormancy. modules/* is gitignored, and the module needs its ids namespaced to its own id (rig.roster.governors, not roster.governors); the registry refuses anything else, and it also refuses an id with no dot in it at all.

---

Phase 5 — Templates: the seeded set, then the editor ✅

Two slices, landing in this order on purpose — the seeded set has to exist before the editor, so the editor is opening something rather than facing a blank page.

5a — storage, blocks, renderer, seeds. ✅ engagement_templates, the email.* block family with toText, the HTML + plain-text renderer, brand-value resolution, and the §4.6.1 seeded set. The five transactional bodies move out of mailer.js into seeded rows and mailer renders them. No editor yet — this slice is provably done when the same mail goes out from a template that used to come from a string literal.

5b — the editor. ✅ The §4.6.2 surface: variable palette from the trigger declaration, live preview from example values, side-by-side HTML/text, preview widths plus dark mode, test send, duplicate. Built on the existing block/prop-panel machinery, not a second one — and, because a mail body is rendered by the SERVER, the preview is rendered there too and framed rather than redrawn in React. It also lands the other two screens Q4 promised Phase 5: Triggers (read-only, from the registries) and the Send Log (G15).

Acceptance (5a): every one of the five current message types renders byte-comparably from its seeded template; re-running the seeder is a no-op; a seeder bump updates a customized = 0 row and skips a customized = 1 one; two deployments with different BRAND_* produce differently-branded mail from the same seed. Acceptance (5b): a template referencing an undeclared variable is refused at save with the variable named; preview renders from examples with no live event; a published template with an empty text part is refused; a protected template cannot be deleted but can be duplicated; a template pinned to an older trigger_version is flagged in the admin list; an interpolated variable containing <script> renders escaped. Guardrails: CSP — this is the one genuinely new CSP surface. The preview renders operator-authored HTML; it must be sandboxed (<iframe sandbox> with no allow-scripts, srcdoc, about:blank origin) so it never executes under the site's origin, and sanitizeHtml runs on write as well as on render. Worth a test/csp.test.js sibling asserting the preview frame's attributes.

As built — 5a (2026-08-29)

Built as website#TBD. Three decisions were settled by the org lead before any code, each because the tree contradicted something the plan assumed.

	Question the survey raised	Decision
The HTML part	Not one existing mail has one. All six senders in mailer.js set text: only, so "renders byte-comparably" is a statement about a text body and whether 5a introduces HTML to live mail was an open choice	Multipart now, text byte-identical. The text part is byte-for-byte what went out before; the HTML alternative is new. The renderer is therefore exercised by real mail in the phase that builds it rather than shipping dead until 5b
The block registry	The server block registry has no renderer of any kind. Page blocks are drawn by React on the client; registerBlock freezes a fixed field set and would silently DROP a toHtml/toText	A sibling registry, with the machinery shared by binding. §4.4's "do not build a second editor" is about the editor, and 5b still drives these through the existing block/prop-panel machinery
The seed scope	§4.6.1 lists nine seeds but teamNotify/teamDigestWorker are explicitly Phase 6's to rewrite	Seed all nine, wire the six transactional. Phases 6 and 7 open something rather than each shipping seeds of their own

And a correction to §4.6.1 itself: it lists auth.email-verify as "(new — Phase 9)". Phase 1b already shipped mailer.sendEmailVerification, so it is a current message type, not a future one — six bodies moved, not five, and all six are pinned by the byte-comparison test.

The two registries are siblings, and that is an argument rather than a preference

Sharing one Map would have cost three things. Email blocks render on the server and so carry toHtml/toText, which the page registry's frozen entry shape has nowhere to put. One Map is one namespace, and the page registry's only server consumer is pages.model.js — so email.heading in it means a CMS page containing an email block validates and saves, with nothing on the client able to draw it. And the entry shapes genuinely differ: cacheTTL and container mean nothing to a mail body.

What is the same rule for both is shared by binding, not by copy. blocks/validateBlocks.js and sanitizeBlocks.js became factories over a registry lookup (makeValidateBlocks / makeSanitizeBlocks), each exporting the page-bound instance every existing caller already imports, and emailBlocks/ binds the same walk to its own registry. The envelope rules, id uniqueness, schema dispatch and the validate-then-sanitize order therefore cannot drift between the families. There is a test asserting both directions of the isolation: an email.heading fails page validation, and a plain heading fails email validation.

The token grammar has no conditional, so the ternaries stayed at the call site

{{ name }}, a bare declared variable, and nothing else — no filters, conditionals, loops or dotted paths. Repetition is a block (email.itemList renders a declared list variable), which is the one place a template needs "for each" and it already has a typed, validated home.

That has a visible consequence. mailer built for the account “Darrow” with a ternary, and a logic-free template cannot. So the ternary stays where a ternary belongs and its result arrives as a variable — forWhom, roleLabel, invitedBy, moreNote — each declared with an example showing exactly what it produces, leading space and quotes included. It is not pretty in the editor and it is the price of not giving operator-authored data a conditional to get wrong. Both branches of every ternary are asserted, because the empty one is what a template language with a conditional would most likely get wrong.

Where a conditional would otherwise be reached for, "nothing in, nothing out" stands in: a block whose content interpolates to nothing renders nothing, in both parts. {{moreNote}} on its own line is a line the caller can decline to supply.

Three properties of the renderer that are load-bearing

• The shell contributes structure and no content. No appended footer, no injected logo, no "sent by" line. An unsubscribe line is a variable inside the template, so an operator can move it, reword it, or see that a transactional mail correctly has none — and, more importantly, the HTML and text parts say the same things. A footer in one and not the other is a deliverability signal and means the text reader is told less than the HTML reader.
• Only the accent comes from the theme. Every shipped preset is a DARK palette, and §4.6.2 already names the failure: a light-only template "renders as unreadable dark-on-dark in about a third of inboxes", because clients invert or force their own background. Deriving a light palette from a dark one is a guess at six colours; taking the one colour that carries the brand is exact. §4.6.1's property 2 holds either way — no seeded template contains a hex code, asserted by a test.
• A URL built from a variable is re-checked after substitution. A stored {{resetUrl}} says nothing about where it points. Checking only the literal would let a variable carrying javascript: become an href; a substituted value that fails isSafeUrl loses its href and renders as inert text rather than vanishing, because silently dropping it would hide from the reader that the mail meant to offer them something.

A missing row renders the shipped default, which is what makes the whole move safe

renderByKey falls back to the in-code seed whenever the row is absent or its blocks will not parse: before the first seed runs, after a restore that dropped the table, on a row hand-edited in the database. Without it, moving a password-reset body into a table would have made every failure mode of that table a failure mode of account recovery. protected = 1 stops the last of those from being reachable through the API at all.

The seed guard is in the SQL, not in a read-then-write

INSERT IGNORE, then UPDATE … WHERE seed_key = ? AND customized = 0 AND seed_version < ?. A check in JavaScript followed by an UPDATE leaves a window in which a concurrent boot overwrites an edit an operator made a moment earlier, and a deployment can start two app processes at once. MariaDB's ON DUPLICATE KEY UPDATE cannot carry a WHERE, which is why this is two statements rather than the upsert §4.6.1 sketches.

Related, and recorded because Phase 4a was bitten by the same thing: the connector defaults foundRows: true, so affectedRows on an UPDATE counts matched rows. For the seeder that is harmless (its WHERE only matches a row that will change); for an operator's save it is the semantics wanted — re-saving a template unchanged is a success, not a 404. Both are now stated in the code rather than relied on.

Two behaviour changes an operator will notice

1. Mail is multipart. A client that prefers HTML now shows a branded body where it used to show plain text. Nothing a text-only reader sees has changed.
2. Subjects resolve the deployment's own name. They interpolate {{siteName}}, which is settings.getInstanceName() — the admin-set site_title falling back to BRAND_NAME, rather than BRAND_NAME alone. On an instance that never set a site title nothing changes; on one that did, the subject finally says what the site calls itself.

Also inherited rather than introduced, and now visible: admin.contact-message declares both fromLabel and fromName — the same missing name with the two different fallbacks the literal used ('a visitor' in the subject, 'unknown' in the body). Kept exactly, asserted, and now editable by whoever wants one word.

One defect this phase found in a Phase 1 check

npm run check:hosts (§3.2 rule 4) read the template key auth.email-verify as the hostname auth.email. .email is a real TLD and the pattern's trailing \b matches between l and -, so any engagement identifier whose label happens to end in a TLD tripped it — and §4.6.1 names that key. Fixed with a (?![-\w]) after the TLD: a real hostname's TLD is its last label, so a following - or word character means the match is a truncation of a longer identifier. Everything a host is followed by (a quote, /, :, ?) still matches, and the checker's own suite gained both the identifiers it must now accept and two real .email hosts it must still catch.

Verification

• 31 new server tests (test/emailTemplates.test.js) and 3 added to the host-check suite. Full server suite green: 1388 passing, with the one known Windows CRLF artifact (engagement-triggers.json byte comparison) and honeypot.test.js's 10-second pool-acquire flake under full-suite parallelism, both of which reproduce on clean edge. routes.manifest / routes.guards need modules/uo moved aside, as ever; 5a adds no routes.
• The seeder's SQL against a real MariaDB, because the unit tests stub seedOne and therefore prove the loop rather than the statements — the exact shape of Phase 4a's foundRows trap, where a stub agreed with a broken query. First run 9 inserted; second 9 skipped; after a seedVersion bump 8 updated and the customized row skipped, keeping both its words and its old version, and surfaced by staleCustomized. The blocks JSON round-tripped through MEDIUMTEXT, and update() twice with identical values returned true both times.
• Real mail, end to end, through nodemailer and SMTP into a mailpit catcher: all five senders, the message arriving as multipart/alternative; charset=utf-8 with the curly quotes correctly quoted-printable-encoded, the button rendering with its bare URL beneath it, and the text part matching the deleted literal.
• The same seed rows, two deployments. Run as UOMysticmoon with a gold accent and as Vesper Isle with a blue one, changing only stored settings: the subjects and the button colour follow the deployment, from identical rows. §5a's fourth acceptance criterion, proved rather than argued.
• A contact message carrying <script>alert(1)</script> & <img src=x onerror=…>, sent for real: escaped in the HTML part, raw in the text part, no live tag in the delivered message.
• One accidental proof worth keeping: an early rig run had a settings table missing updated_at, and ambient() degraded to the BRAND_* env values with a warning and sent the mail anyway. That path is not otherwise easy to reach.

Still 5b's: the editor, the admin Templates screen, the template CRUD routes, the save-time undeclared-variable refusal (variablesFor is in place and is what it will ask), the sandboxed preview and its CSP test, and the runicgateway.com admin docs page §6.0b assigns the pair.

As built — 5b (2026-08-29)

Built as website#TBD. Q4 was already settled (Phase 4a), so the only thing needing a decision before code was the scope: §Phase 5's body names the editor and nothing else, but Q4's answer and §6.2 both promise "Triggers, Templates and the send log" in Phase 5. All three shipped. Triggers is a read-only render of two endpoints Phase 2 already serves and cost no server work; the send log is one paged route over a table that has been filling since Phase 4a and whose index was built for it. Leaving either out would have left the nav group half-built and G15 — "no send log, no delivery status, no audit" — open with the rows already on disk.

Five more decisions were settled by the org lead before any code, each because the tree contradicted the plan or the plan contradicted itself.

	What the tree said	Decision
Where the preview comes from	The client block registry mirrors the server's, but its entry shape carries a React component — page blocks are drawn in the browser. Email blocks are drawn on the SERVER; a mail body is a string this process produces	A server preview route, rendered into a sandboxed iframe. A React preview would be a second renderer for one artifact, agreeing with the send path on the day it was written and drifting from the first Outlook fix onward
status was unenforced	draft/published shipped in 5a and nothing read it — getByKey returns any row, so an operator who saved a template as a draft kept mailing it	renderByKey requires published and otherwise falls back to the shipped seed, the posture 5a already built for a missing or unusable row. A draft now means what the word means
Test send vs. trigger_id NOT NULL	§4.6.2 wants a test send "recorded in engagement_sends like any other message", but every transactional template has trigger_id NULL and there was nothing honest to put in the column	A synthetic core.admin.test-send id. No schema change, no nullable column, and the log keeps meaning one thing. It is deliberately not a registered trigger, and the screen renders it by name so nobody goes looking for it in the catalog
Deleting	protected blocks deletion. Nothing stopped deleting a template a rule's template_keys points at	409 while a rule uses it, naming the rules — the answer Phase 4b already gives for a segment in use, for the same reason: the alternative is a rule that silently stops producing mail
Creating	§4.6.2 names duplicate and never mentions a blank create	Duplicate only. Every template on a deployment descends from a shipped one that renders, which is the whole reason 5a landed first

The correction that changed the most code

§4.6.2 introduces duplicate as "how an operator customizes a protected template safely: duplicate, edit, point the rule at the copy, leave the original intact". The schema comment written in 5a says the opposite — "Editable, NOT deletable" — and the org lead's ruling is the schema's: a default template is edited in place. customized = 1 is what stops the next seed bump from taking that edit back, and it has been in the UPDATE's own WHERE since 5a. So protected now blocks deletion and nothing else, and duplicate is how a NEW template comes into being rather than how an existing one is customized.

Three things the plan did not know, found by building it

1. The variable check cannot be a token scan, because of one block. §4.6.2's refusal — "a template referencing an undeclared variable is refused at save with the variable named" — reads as a scan for {{name}}. It is not sufficient. email.itemList.variable holds a bare name (items), because the block iterates the value rather than interpolating it; a token scan sees nothing there. A digest pointed at itmes would have saved clean and arrived empty, which is the one variable mistake a reader of the template cannot see. Blocks now optionally declare variables(props) in the registry — itemList is the only one that does — and emailBlocks/variables.js walks tokens and declarations across the subject, the text override and every block prop. The editor makes that field a <select> over the trigger's list variables rather than a text input, so the mistake is unavailable in the first place.

2. A duplicate that drops its seed reference cannot be saved. The obvious shape for create was seed_key = NULL — a copy is not a seed and must never be adopted by the seeder. But templates.variablesFor() resolves the palette from the trigger or, for the generic templates tied to no trigger, from the seed, so a seedless, triggerless copy has only the four ambient variables, and duplicating notify.event would have been refused for the {{title}} and {{intro}} it was copied with — the one action §4.6.2 offers, refusing itself. The copy inherits seed_key, and it is safe to because customized = 1 is what the seeder actually reads: seedOne's UPDATE carries AND customized = 0, so it can only ever match the seeded row. staleCustomized does match a copy, and should — "the default you duplicated has been improved" is worth telling someone.

3. validateEmailBlocks returns { valid, errors }, not an array — and the first version of the model tested it with .length, which is undefined on an object, so block validation never ran at all. Unvalidated props would have reached both the renderer and the row. Nothing about the code looked wrong; the test that caught it was the one asserting a preview refuses a block with an unknown prop. pages.model.js destructures it, which is why that caller has never had the bug.

The one genuinely new CSP surface, and how it is held

§4.6.2 called the preview out as "the one genuinely new CSP surface", and it is: operator-authored HTML reaching a rendered surface. Three things hold it, in order of what they cost to remove:

• The preview renders in <iframe sandbox="" srcDoc={…}> — every restriction on, nothing granted back, from an opaque origin. No allow-scripts, no allow-same-origin.
• The HTML crosses as a JSON string, never as a document served from this origin. That is not a convenience: served as a document it would run under the site's own CSP with access to its cookies.
• Blocks are validated then sanitized on write, against the email.* registry, so the stored row is already through the gate before any of the above matters.

The sibling test §4.6.2 asked for is client/test/emailTemplates.test.js. It reads the attribute, not the file — the first version searched the source for allow-scripts and failed on the comment above the iframe explaining that there is no allow-scripts. A check a correct file fails is worse than no check, because the way to make it pass is to delete the explanation.

What was verified

• 23 model tests (server/test/engagementTemplatesAdmin.test.js), one per acceptance criterion plus the two the tree made necessary. Server suite 1403, client 324, both green.
• The drift check was verified by breaking it both ways — a client version: 2 against the server's 1, and deleting a registration outright — because a pairing check that spans a process boundary is the kind that silently stops checking.
• renderByKey's draft arm has its own test, asserting the seed goes out and the draft's words do not; the 5a fixture that carried no status was updated rather than the rule being softened.

Still Phase 6's: the email channel's deliver on the engine, and the teamNotify / teamDigestWorker migration onto the four notify.* templates this phase can now edit.

---

Phase 6 — The email channel on the engine, and the Teams migration ✅

Email becomes a DeliveryChannel driven by rules. teamNotify.js and teamDigestWorker.js are rewritten onto the generic pipeline; engagement_digest_state backfills from team_notification_prefs.last_digest_at; unsubscribeToken generalizes from (userId, teamId) to (userId, channel, scopeKey) while still verifying old two-part tokens, because tokens are already in people's mailboxes.

This is the highest-risk phase. It touches live behaviour that people receive by email.

Acceptance: every existing Team notification test passes against the new pipeline; a pre-existing email_mode='digest' row produces exactly one daily digest with the same window clamping; an unsubscribe link from a mail sent before the migration still works; teamDigestWorker's three compute-at-send-time properties are each covered by a named test, especially a user who lost access between the post and the send is not mailed; List-Unsubscribe + List-Unsubscribe-Post still both present. Guardrails: route manifest (the unsubscribe routes move); a migration test asserting the backfill is replay-safe.

---

As built — 6 (2026-08-29)

The email channel gained a deliver, and the Team pipeline stopped being its own thing. Concretely: teamNotify.emailImmediate and mailer.sendTeamNotification are gone, teamNotify.forumPost emits an event instead, and a rule decides who is mailed. One end-to-end walk on a live rig now goes forum write → events.emit → rule → outbox → worker → email channel → template → SMTP → mailbox, with the send recorded in engagement_sends like everything else the platform sends.

Seven decisions the org lead settled before any code, because the tree contradicted the phase body in every one of them:

	Question	Decision
Sinks	teamNotify has three sinks; which move onto the engine	email only. The tickle and the Discord bridge stay direct calls in teamNotify.js
Audience	how a Team event reaches that Team's members, when members resolves to nobody and a segment takes constant params	the event carries the set — the same access-checked list teamNotify.recipientIds has always computed
Continuity	rules default off and core seeds none, so a straight migration stops Team email silently	seed the four rules DISABLED, plus an admin banner and a release note. The invariant is honoured, not excepted
Prefs	per-Team granularity has nowhere to live in notification_channel_prefs	keep team_notification_prefs, consulted by the engine as a scoped preference
Templates	§4.6.1 property 1 promises a generic template renders any trigger, and nothing implemented it	payload wins, a structural projection fills gaps
Digest	§4.2b says compute at send time; the engine snapshots at emit time	keep compute-at-send-time; generalize only the state
Unsubscribe	a v1 token set muted, silencing push as well as email	turn off the channel the token names, and nothing else

The audience problem, which is the one that shaped the phase

The engine could not express "the members of the Team this post was in", and the reason is structural rather than an oversight. A rule names its audience two ways: a plain ceiling name resolved from core's own tables, or a saved segment composing module-declared audiences with constant parameters. A Team forum post needs neither — the recipient list is different for every firing, and it is the answer to an access question (teamAccess.forumAccess's two tables) that core already knows how to ask and a segment has no way to ask at all. audiences.js said as much in its own comment: "core knows no game vocabulary and cannot guess which members were meant."

So the event names it. engagementEmit's envelope gained recipientUserIds, and a rule whose audience is members resolves to exactly that set. Three properties make it a narrowing input rather than a hole in the ceiling lattice, and all three are tested:

• the carried set is still filtered through users.status = 'active', so a banned account is not mailable by an emitter that forgot;
• the ceiling returned is still members, so G24 still runs — a rule cannot be given authenticated on a trigger that ceilings at members, carried set or no carried set;
• the list is bounded at MAX_AUDIENCE (5000) at the emit boundary, so an emitter cannot assert an audience larger than the engine would have loaded from a query.

A rule with any other audience ignores it entirely. This is not "the emitter decides who gets mailed": it is the emitter answering the one question core cannot, and the rule deciding everything else.

scope_key is not subject_key, and Phase 6 is where that stopped being theoretical

Both are per-event strings on the outbox row and they are keyed on different things:

• subject_key is what a cooldown counts. It comes from the trigger's declared subjectKey, which for all four Team triggers is teamName — a display string, which is fine, because a cooldown only ever compares it with itself.
• scope_key is what a preference and an unsubscribe are keyed on, and it has to be a stable identifier. team:12 survives a rename; The Silver Anvil does not. Signing an unsubscribe token over a display name would orphan every link in every mailbox the first time staff renamed a guild — and those links have no expiry, so "the first time" means "ever".

engagement_digest_state.scope_key already used that vocabulary in §4.2b, so the outbox column is the same vocabulary in the same shape rather than a second one.

The scoped preference, and the one place the decision as phrased could not ship

Decision 4 was recorded as "a suppression below the channel preference". Building it showed that reading is the one that cannot ship, and the reason is worth stating because it is a second instance of the G22 pattern — a migration that degrades silently:

notification_channel_prefs holds a row only where a user has expressed something; absence means the channel's defaultMode; and email's is off. Nobody has ever expressed a stream-level opinion about team.forum.post — the screen that would let them is Phase 3's and the preference predates it by a year. So intersecting the two preferences would resolve every existing Team-email subscriber to off, and the deploy that migrated the pipeline would be the deploy that silenced it.

What shipped is replacement: where a scope has an opinion, that opinion is the preference. engagement/scopedPrefs.js is a small registry keyed on the scope-key prefix; engagement/coreScopePrefs.js registers team and maps the two columns:

• muted → off on every channel. That is what the toggle has always meant on the account screen, and narrowing it to email would be a behaviour change nobody asked for.
• email_mode → the engine's vocabulary (immediate → instant), and only for the email channel. On push or in-app the provider returns no opinion and the stream-level preference decides.
• absence of a row means off for email, which is why the provider answers for every user in the set rather than only the rows it finds. The column defaults to 'off' and both recipient queries COALESCE to it: no row has always meant "has not asked for Team email". Deferring to the stream-level preference instead would mean somebody who once switched on team.forum.post email in the channels screen starts receiving mail from every Team on the deployment — a widening produced by a migration, of a preference expressed about something else.

The cost, stated so nobody rediscovers it: a user cannot turn Team email off for every Team at once from the channels screen. That control lives on the per-Team screen, which is where it has always lived and where the unsubscribe link points.

The provider fails open — a lookup that throws leaves the stream-level preference in charge, which for every core channel is off. So a failure means nothing is sent rather than that everybody is mailed, and it does not drop an unrelated IDOC warning because a Team preference query timed out.

The projection: what §4.6.1 property 1 actually required

Property 1 says a new trigger renders through notify.event with no authoring at all. Nothing implemented it, and building the channel is what made the hole visible: trigger payloads are domain-named (teamName, threadTitle, postUrl) and the generic seeds are structural (title, intro, items, actionUrl). The two vocabularies never met.

engagement/projection.js is the meeting, and its rule is one line: a name the payload already carries is left exactly as emitted; only a name it does not carry is supplied. news.post and team.announcement both declare their own title, and a projection that overwrote it would replace a real headline with a category label — on the one variable every generic template puts in the subject.

What it fills comes from the declaration, never from a table of domain synonyms:

	Filled from	Why not something cleverer
title	the trigger's label	a mapping of threadTitle → title is one game's vocabulary compiled into core, and it is wrong on the first module that names the same thing differently
intro	the trigger's description	same
actionUrl	the first declared url-typed variable holding a value	it is the only structural fact available: the declaration says which variables are links
items	[]	set rather than left absent, so a generic mail does not report items as a missing variable in the editor's preview

The consequence, seen on the live rig and accepted: an unauthored team.forum.post mail is titled "Team — new forum post" rather than the thread's title. That is a plain mail, not a wrong one, and the operator's answer is the bespoke template shipped beside it. A projection clever enough to do better is a projection that is confidently wrong on the first module that does not follow core's naming.

The digest: the state generalizes, the design does not

§4.2b's instruction was to keep teamDigestWorker's compute-at-send-time design and generalize its state. Doing that meant correcting the engine, not just the worker: Phase 4a's subscribedTo enqueued digest-mode recipients with a comment reading "what changes in Phase 6 is who drains it", and what changed in Phase 6 is that nothing drains it. A digest is re-derived from the source tables when it goes out; an outbox row carries a snapshot taken at emit time, and a snapshot has none of the three properties the design exists for. So the engine now enqueues instant only, and each of the three properties has its own named test:

1. a two-day outage sends ONE digest, not two days of replay;
2. a post a moderator hid after it was written is not in the query, so it is not in the mail;
3. a user who lost forum access between the post and the send is not mailed — the security one.

engagement_digest_state replaces team_notification_prefs.last_digest_at, keyed (user_id, channel, scope_key) so a second digest — on another channel, or over another scope — needs no second column on somebody's preferences row. The backfill is an INSERT IGNORE … SELECT in schema.sql, and it is replay-safe by construction rather than by a flag: the primary key rejects the second run, so a window the new worker has since moved forward is never dragged backwards by a restart. Verified on the rig by restarting the server after a digest had gone out — the stamped row kept its stamp, and the unstamped row was added.

The digest is gated on an enabled email rule, which is the part that was not in the phase body. Without it, disabling the rule would stop the instant mail and leave a daily summary arriving indefinitely, which reads to an operator as the switch being broken.

The unsubscribe: a narrowing, and a path that can never move

The token is now (userId, channel, scopeKey), signed as 2.<uid>.<channel>.<scope>.<mac>. v1 tokens still verify, permanently, and read as { channel: 'email', scopeKey: 'team:<id>' } — which is a reading of what they always meant, since a v1 token could only ever have arrived in an email.

Two things about it are deliberate and easy to undo by accident:

• The route did not move, even though the phase body said the unsubscribe routes would. The canonical pair is now /api/v1/public/engagement/unsubscribe/:token, and /api/v1/public/teams/unsubscribe/:token stays forever, handing straight to the same handlers. Mail sent before this phase carries the old path in its List-Unsubscribe header and in its body; mail is not editable once sent, so a route that moves is a person who cannot unsubscribe. Both paths are in the route manifest.
• A v1 token now turns off email and no longer mutes push. That is the live behaviour change decision 7 accepted: a link labelled "stop these emails" was quietly stopping notifications on somebody's phone. Verified on the rig — POSTing a v1 token to the old path set email_mode = 'off' and left muted = 0.

A channel id may legally contain a dot (discord.dm is §3.1's own example) and the token's separator is a dot, so sign refuses such a channel rather than producing a token that verifies as a different one. A scope the format cannot carry costs the mail its unsubscribe link, not the mail.

Two defects the phase found in code it did not write

1. email.button never absolutized its href. email.image and email.itemList both call ctx.absolute; the button called ctx.safeHref alone. It had never mattered, because every caller before this phase passed an absolute URL. A trigger's url variables are validated site-relative by construction (engagementEmit.RELATIVE_URL exists so a variable cannot carry a recipient off-site), so every rule-driven call-to-action would have interpolated to /guilds/x — a path a mail client has no origin to resolve, i.e. a dead link in every notification the engine sends. Fixed in both parts, with a test either side of the relative/absolute split.
2. The digest's send-log row had no address_hash. The instant path wrote one and the digest path did not, so half the deployment's mail would have been uncorrelatable when Phase 9's bounce handling arrives. Found by reading engagement_sends on the live rig, where the two rows sat next to each other. Both paths now hash through the same function, lower-cased and trimmed — a bounce reported for Darrow@ has to match the row written for darrow@.

A naming inconsistency left alone, on purpose

team.forum.post declares its title as threadTitle and team.announcement declares it as title, though both describe a thread in a Team forum. A template can only name one of them, so notify.team-post's {{threadTitle}} renders empty for an announcement — which is why the seeded announcement rule points at notify.event instead, where the projection gets it right.

Reconciling the two declarations is a variable rename, which §4.3 makes a version bump, and this phase did not take that on its own authority. A test pins the current shape so that reconciling it is a deliberate act rather than a silent rename that empties somebody's subject line.

What an operator sees at cutover, which is the whole of decision 3

Core seeds four rules — one per Team trigger — all enabled = 0, all audience: 'members', all on the email channel. Team email is off until an operator switches one on. Three things make that survivable rather than a silent regression:

• Admin → Engagement → Rules carries a banner whenever every Team rule is off, saying that these used to send automatically, that they arrived switched off so nothing starts mailing on its own, and that per-member preferences and unsubscribe links still work above them. It reads the rules rather than a flag, so it disappears the moment one is enabled and returns if they are all switched off again. A deployment that deleted them sees nothing, which is right — they made that choice.
• The release note names it, alongside the v1-token narrowing.
• The push tickle and the Discord bridge are unaffected. Only email moved, so the app and the Discord channel keep working exactly as before while the rules are off.

The rules are seeded once, guarded by a settings key rather than ensured on every boot: an operator who deletes a rule must not find it back after a restart, and one they enabled must not be reset to off. The guard is stamped even after a partial run — re-running would duplicate the rules that did insert, and a duplicate rule is two mails per event, which is worse than one missing rule an operator can add from the screen.

What was verified

• 97 tests: 35 in teamNotifyDispatch.test.js (rewritten — the mail-body assertions moved down to the channel and what is asserted here is now the envelope), 31 in the new engagementEmail.test.js, 23 in teamNotify.test.js, plus the mailer, engine and block-renderer additions. Server suite 1447 green, client 324 green.
• A live rig, which is where three of the findings above came from: MariaDB + Mailpit + a booted server + a real Team with three members. The walk covered an instant mail with both List-Unsubscribe headers, a digest gathering two posts and stamping engagement_digest_state, the generic notify.event path rendering an announcement with no authoring, a pre-migration v1 token unsubscribing through the old path, and a restart proving the backfill replay-safe.
• The route manifest and swagger carry the two new routes; the two legacy ones are unchanged.

Still later phases': the push and in-app channels' deliver (Phase 7), whether an unverified address may receive opt-in mail (§7.1 Q1's narrower half, Phase 9), and the address_hash this phase started writing, which is the column Phase 9's bounce correlation reads.

---

Phase 7 — The in-app channel (core + web) ✅

user_notifications, the in-app DeliveryChannel, GET /auth/me/notifications + mark-read, and the web surface (bell + list). Push tickles gain a ref that deep-links into the inbox.

Acceptance: one event delivered to inapp produces exactly one row; a duplicate dedupeKey is a no-op; mark-read is idempotent; a user cannot read another user's row (asserted at the route, not only the model); url is relative-only, validated by the same character-class rule pageUrlTemplate uses. Guardrails: swagger + route manifest; the sanitize path for body.

As built — 7 (2026-08-31)

The third channel gets behaviour, the oldest one gets a deliver at last, and the preferences endpoint Phase 3 shipped with no surface gets one. Four decisions were settled by the org lead before any code, two of them widening the phase past its own acceptance line.

Decision 1 — inapp defaults to instant, and it is the only channel that does

coreChannels.js deferred this in as many words: "whether the inbox is opt-out once it is real is a Phase 7 decision with a live surface to look at." The surface exists now, and the answer is opt-OUT.

The argument for opt-IN was never about in-app. §7.1 Q1 is standard marketing-email practice and Phase 3's push default is about a device somebody is holding; an inbox item wakes nothing and leaves nothing — it is a row on a page the user chose to open, on this deployment, costing one glance. Left at off the channel would ship dead: no rule could reach anybody until every user found a toggle for a channel they had never seen deliver anything. The backlog Phase 3 worried about cannot happen either — the table is empty at cutover, rules default to enabled = 0, and every rule carries a per-hour ceiling.

Decision 2 — the phase takes the two pieces its acceptance line omitted

Two earlier phases assigned work here that Phase 7's own bullets never mention, and both were taken:

• push gets its deliver (§2603's "the push and in-app channels' deliver"). Without it a rule naming push still finished failed in the send log — the oldest sink in the system, unreachable from the engine. It is the channel that got behaviour last because until the inbox existed there was nothing for a content-free tickle to point at.
• The web per-channel preferences screen (Phase 3's as-built: "the screens are Phase 7 (web) and Phase 8 (app)"). The endpoint had shipped with no consumer on either platform.

Decision 3 — the inbox takes /notifications; the preferences move under it

/auth/me/notifications/* was already the preferences namespace — streams, subscriptions, channels, teams — and /account/notifications was already the preferences page, with a bell icon in the portal nav. Content and settings are different kinds of thing, and the plain word belongs to the content: it is what a person means when they say "notifications", and what the bell opens.

So the inbox is GET /auth/me/notifications and the page is /account/notifications; the preferences screen moved to /account/notifications/settings and gained its own nav row. Route order is not incidental and is commented as such: the four named preference sub-paths are declared above, and the one parameterised path added below them is a POST whose :id is digits-only, so nothing can shadow streams or channels.

Decision 4 — ctx.inbox.push respects a preference where one exists

The rule-less sink has no trigger declaration to project from, no rule to pick a template and no audience to resolve. It now writes the inbox directly unless triggerId names a registered trigger and that user's effective inapp mode is not instant: a toggle somebody switched off must not be walkable around by the module that owns the trigger behind it. An id nothing has registered has no toggle on any screen, so there is no preference to protect and the item is written.

Scoped preferences are deliberately not consulted — a scope is a property of an event (team:12), and a caller with no declaration has no scope to name. The engine's path, which does, still applies them.

The block → column mapping, which is the whole of how a template becomes a row

user_notifications has title / body / url where email has a subject and a document. The in-app renderer (templates.renderInappByKey) maps by block role: the first email.heading is the title, the first email.button is the url, everything else is the body. A second heading or button is ordinary body content, which is what an operator who added one meant.

The body is TEXT, not the email HTML, and that is load-bearing rather than a shortcut. The email.* renderer produces markup built for mail clients — table rows, inline hex colours, a light-only palette declared with color-scheme — which dropped into a page that follows the viewer's theme renders as a pale card floating in a dark one. toText is the same content with none of that, and it is the part every block already promises. The consequence worth stating: there is no operator markup on this surface to sanitize, and no way for one to appear. The phase's "sanitize path for body" guardrail is discharged by the column never holding markup in the first place, which is a stronger guarantee than a sanitizer.

Five things the tree contradicted, or the build found

• The shipped inapp.event seed named variables nothing supplies. Phase 5a wrote it before the channel that renders it existed, declaring body and url — but a trigger declares domain names (teamName, threadTitle) and projection.project fills the gaps with the structural ones (title, intro, actionUrl). Every rendering would have produced a title and nothing else. Renamed to notify.event's vocabulary at seedVersion 2, which is §4.6.1 property 1 restated for this channel: a new trigger must render with no authoring at all.
• The dedupe index is scoped to the USER, which is narrower than the outbox's. engagement_outbox scopes to (rule, user, channel) because one event legitimately becomes one row per channel; an inbox has no channel dimension, so two rows for one event would be one item shown twice. Same family of defect as the global index Phase 4a found in §4.2a, in the opposite direction.
• The push tickle's ref needed an ordering to be worth anything. A rule spanning inapp and push enqueues two independent rows and the outbox sweeps ORDER BY due_at, id, so the ref only resolves if the in-app row was enqueued first. engine.liveChannels now sorts inapp ahead of the rest (CHANNEL_ORDER) — an ordering, not a dependency: the ref is a hint, null when there is no row, and the app's contract stays wake-and-pull.
• There was no retention policy for this table at all, and neither the outbox nor the send log bounds it (both hold one row per delivery; an inbox item outlives its delivery by design). utils/userNotificationsPrune.js is teamActivityPrune's shape with one policy difference: read items only. Age alone would delete the evidence for "I was never told", which is the complaint this table answers. The horizon is settings.user_notifications_retain_days, default 90.
• Staff had no reachable inbox, and only the live rig could see it. /auth/me/notifications is role-agnostic — behind requireAuth only, like every /auth/me route — so the server, the tests and the API all agreed a staff member had an inbox. On the web they did not: RequirePlayer sends anyone who is not a player out of /account (staff manage their own account under /admin/account), so the bell pointed at a page that redirects. Signed in as an admin, the feature was unreachable. Fixed by mounting the same two components at /admin/notifications and /admin/notifications/settings, adding the bell to the admin header, and putting the one mapping in client/src/lib/notificationPaths.js with its own test. One trap inside the fix worth keeping: allowedPathsFor turns an end: true nav row into an EXACT match, so marking the admin row exact left /admin/notifications/settings outside the allowlist and bounced staff off their own preferences screen — the row has to cover its sub-routes.

What an operator and a user actually see

• The bell sits in the public site header and in the player portal's own header, renders nothing when signed out, and polls its badge once a minute — pausing while the tab is hidden and refreshing the moment it comes back. There is nothing to push over: the site's two SSE streams are the shard's, neither is per-user, and a third authenticated stream carrying one integer would mean an open connection per signed-in tab forever.
• The preferences screen is now a matrix, not a checkbox list. The push-only stream list it replaced was a strict subset: /notifications/channels already returns every push stream and every event trigger with the effective mode on each channel that applies, so a trigger-only id simply has no push cell and core never has to explain which kind of id a row is. The two legacy whole-set endpoints are untouched and are that surface's push projection, so the shipped Android app keeps its wire shape.

What was verified

• 28 new tests: 23 in engagementInapp.test.js (the five acceptance criteria, the role mapping, the four ctx.inbox.push cases, the tickle's exact key set, and the route-level ownership check) and 5 in userNotificationsSql.test.js — a throwaway MariaDB, because three properties here are a server contract rather than a reading of this code: a UNIQUE index admitting many NULLs, INSERT IGNORE reporting affectedRows = 0 on a duplicate, and read_at IS NULL making mark-read idempotent.
• Two existing tests moved with the behaviour, and both moves are the point. engagementEngine's "a channel with no deliver() finishes failed" named inapp (and email before it) and so was rewritten by every phase that gave a channel behaviour; it now registers a throwaway channel, because the property was never about a particular one. notificationChannelPrefs's defaults assertion carries decision 1.
• Swagger and the route manifest carry the four new routes, with four new component schemas.
• A live rig: MariaDB + a booted server + the real outbox worker + a browser. The walk is where the staff-reachability defect came from, and it also proved the three things unit tests cannot — that liveChannels' ordering really does put the in-app row first (a rule stored as ["push","inapp"] enqueued outbox 2 = inapp before outbox 3 = push, and the tickle carried ref: "notification:2"); that two rules on one event produce three outbox rows and exactly ONE inbox item, with the send log saying "already in this inbox (duplicate dedupe key)" rather than claiming a second delivery; and that the retention worker drops an aged READ row while leaving an equally aged UNREAD one. The preferences matrix wrote exactly one row for the one cell that changed.

One thing this phase did NOT wire, and it is worth knowing before Phase 11. news.post is a declared trigger that nothing emits through the engine — coreTriggers.js says so in as many words ("these declare; nothing here emits yet") and Phase 6 migrated only the four team.* ones, so the admin publish path still fires a raw pushDispatch.publish beside the engine rather than through it. The consequence for this phase: on a real deployment the only in-app items a rule can produce today come from the four Team triggers. Wiring the news emitter is a one-line ctx.events.emit-shaped change that belongs with whoever owns that decision, not smuggled into the channel's own phase. Written up as §7.1 Q9, which sets out the three other things a publish already fires (an announce leg, a module's post hook, the raw tickle), which of them the engine replaces and which it must not touch, and the continuity question that has to be answered before anyone writes the line. Recommended home: Phase 11.

Still later phases': the app's inbox screen and the tickle → pull → inbox path (Phase 8), and the suppression list, which this channel has no equivalent of — there is no address to suppress.

---

Phase 8 — The in-app channel (Android) ✅

Inbox screen, unread badge, and the tickle → pull → inbox path. App-store cadence, separate repo, separate release.

Acceptance: a tickle wakes the app, which pulls and shows the item; the inbox works offline from cache; the existing preferences screen gains the per-channel toggles from Phase 3. Note: android-app's pr-checks.yml triggers only on PRs into main, so phase PRs onto a working branch get no CI — the cutover PR is the first real run. Plan for that. Resolved: §7.1 Q8 was answered "fix it" and the trigger now runs on PRs into edge too, as this phase's first commit.

As built — 8 (2026-08-31)

The four inbox routes Phase 7 shipped had no consumer on either platform; this is the Android one. Four decisions were settled by the org lead before any code, and one of them resolves a contradiction the phase carried from the day it was written.

1. §7.1 Q8 — fix the CI trigger, as the first commit. pr-checks.yml now runs on PRs into edge as well as main. All nine M12 phase PRs merged with no CI at all and engagement Phase 8 was about to repeat it; the alternative was finding a Kotlin compile error inside the cutover window with a whole workstream's diff to bisect. sonarqube.yml is untouched — it is a push-on-main analysis, not a PR gate, so no phase PR was ever expected to run it.
2. The offline snapshot is a JSON blob, not Room. This phase's acceptance line ("the inbox works offline from cache") contradicted a decision already recorded in docs/android/PLAN.md §7: "Offline caching is not a v1 requirement (decided)… does not ship a Room cache in v1. No Room dependency in the initial build." §7's decision stands and this is its one named exception. An inbox is a short, read-only, newest-first list with a server-side cursor and no joins, so what "works offline" needs is the newest page and the badge — one blob in the DataStore the push code already uses, capped at the server's own default page size.
3. The drawer's "Notifications" is the inbox; the settings are behind its gear. Exactly the arrangement Phase 7 shipped on the web (the bare path is the content, …/settings the preferences), and what a person means when they tap the word.
4. The settings screen moved onto /notifications/channels, rendering a control per channel that applies to each id and per mode that channel accepts.

The one thing the app must do that no plan said: resolve the item's url. Phase 7's acceptance specifies url is relative-only and validates it as such — right for a browser already on the site, and a dead link on a phone. The live rig caught it: every item came back as /guilds/the-silver-anvil/forum/403, and the app's first cut only opened http(s)-prefixed strings, so every link in the inbox did nothing. It now resolves against the configured base with OkHttp's HttpUrl.resolve, which absolutises the path and returns null for anything that would not end up http(s) — so a javascript: or intent: url in a notification body opens nothing at all. The relative-only contract did not change; the client half of it was simply never written down.

Three further things the build settled:

• The tickle's ref is what routes it, not its stream. An engagement rule's tickle carries the TRIGGER id as stream (§7.2's one namespace), and the app's shipped forStream map knows only the eight push streams — so team.forum.post would have landed on Home. Routes.forTickle(stream, ref) sends anything whose ref starts with notification: to the inbox and leaves every other tickle on the route it has always had. The ref is not decoded past that prefix and is never rendered: it is a hint that a row exists, and the contract stays wake-and-pull, exactly as pushChannel.js says.
• The snapshot is scoped to (base URL, user id), and that is the security property — not the clear-on-logout beside the push deregistration. A cache is only ever handed back to the pair that wrote it, so the teardown paths that never reach a logout at all (a dead refresh token, a server switch) cannot surface one person's notifications under another's session.
• Reads are optimistic and are not rolled back. The row flips locally, the server's post-write unread replaces the local guess, and a failure is left alone: un-reading a row under someone's finger looks like a bug, and the next refresh corrects it. A local read also rewrites the snapshot, without which going offline right after reading everything would bring the badge back on the next cold open.

Verified on the live rig (throwaway emulator + the real server on edge + real rows emitted through ctx.events.emit → engine → outbox → inappChannel, never hand-written):

• the drawer badge showed 3, the inbox listed the three items newest-first with unread dots and local-zone timestamps, and a tap marked one read (3 → 2, server-side row updated);
• tapping an item opened its resolved link in a Custom Tab at the configured shard;
• one email chip wrote exactly one row — (35, news.post, email, instant) — and disturbed nothing else, which is the sparse PUT's whole point;
• the push controls were absent, correctly, because the rig's shard advertises no relay, with the reason in a note beside the list rather than replacing the screen (email and on-site preferences are still worth setting on a shard with no push);
• with the network cut, the inbox rendered all five items from the snapshot under "Offline — showing what was saved on this device.", unread count and read flags intact;
• a simulated tapped tickle (STREAM=team.forum.post, REF=notification:5 — the exact extras PushNotifier builds) landed on the inbox rather than Home.

One finding this phase did NOT fix, deliberately. Offline works in a running app, not on a cold start — and the reason is the app shell, not the inbox. MainActivity gates the whole of RunicApp on loading the site's appearance (M12), so an offline launch shows "Can't reach the site / Retry" and never reaches the drawer at all. Widening this phase into the shell's startup model is the kind of out-of-scope blocker that is a reason to ask, not a licence to widen the PR, so it is written up here for the org lead. The acceptance line holds for the case the cache exists to serve — the app you were just using, on a train — and fails for the case where the app was killed first.

Still later phases': nothing of this channel. The app now consumes every route Phase 7 built.

---

Phase 9 — Deliverability: suppression and bounces ✅

engagement_suppressions and bounce/complaint capture per transport (SMTP has none — this is where the API-based providers earn their place).

The verification flow is no longer part of this phase. §7.1 Q1's answer moved it forward into Phase 1b, along with the admin gate setting that decides whether an unverified address is excluded. Phase 9 therefore consumes email_verified rather than introducing a writer for it, and — the reason this reshuffle is worth it — Phase 9 no longer blocks Phase 11. The first real rule can ship on the verification mechanism 1b already built, with bounces following.

Acceptance: a suppressed address is skipped with status='suppressed' in engagement_sends and no transport call; a hard bounce suppresses the address; with the Phase 1b gate on, an unverified address is excluded from engagement rules but still receives password resets; with it off, it receives both.

As built (2026-08-31)

Four decisions, settled by the org lead before any code:

1. Mechanism plus SMTP's real signal; no API transport. The phase's own text says "SMTP has none — this is where the API-based providers earn their place", and that is too strong. SMTP has no asynchronous bounce or complaint feed, but a single-recipient send refused at RCPT TO throws synchronously with the reply code intact — the highest-value deliverability signal there is, and mailer.js was already catching it as a PERMANENT_CODE and throwing it away. So this phase reads it. A transport MAY declare a bounce handler; none does, and no webhook route ships — a route with no producer is §7.1 Q9's problem in a different costume.
2. Suppression scopes to engagement rules only. Password resets, invites, verification mail and the contact form still attempt. This is the posture passwordReset.controller.js already stated for the verification gate, and the argument carries: user-initiated mail must not be blocked by a background system's opinion, and one reset to a dead mailbox is not a reputation problem.
3. address_masked is added to §4.5's DDL. The hash-only table cannot be operated — an operator staring at sha256 digests cannot tell three typos from a whole domain refusing mail, and un-suppressing somebody who fixed their mailbox is the one action the table must support.
4. The verification gate filters at ENQUEUE, not at delivery.

The defect this phase exists to have avoided: PERMANENT_CODES is not a bounce classifier. The obvious implementation is "the mailer already tells us a failure is terminal, so suppress on that". mailer.PERMANENT_CODES is {550, 553, 554, EENVELOPE, EAUTH}, and it answers a different question — is retrying pointless? EAUTH is the operator's password being wrong and 554 is a relay-wide policy refusal; neither says anything about the recipient. Under that implementation one stale SMTP credential suppresses every address the outbox worker touches, with a clean send log, no warning, and a mailing list that has to be rebuilt by hand. So bounceClassify.js is its own judge:

• the RFC 3463 enhanced status decides on its own where there is one — 5.1.1, 5.1.2, 5.1.3, 5.1.6, 5.1.10 and 5.2.1 suppress, and 5.3.x, 5.5.x and 5.7.x explicitly never do, being about the server or about our standing with it;
• without one, a phrase match applies only after 550/551/553 has already narrowed the failure to the recipient address, and only past a veto list — 552 and 554 are excluded from even that, because a full mailbox gets emptied and "transaction failed" is what a relay says when it does not want to say why;
• anything it is unsure about is not suppressed. A false negative costs one retry next month; a false positive costs a person who silently stops hearing from the deployment and cannot find out.

sendNotification now returns an smtp: { code, responseCode, response } triple so this is answerable at all: retry and detail cannot distinguish 550 5.1.1 from 550 5.7.1, which are an identical retry: false and mean completely different things.

The two mechanisms sit at different points, and the split is the design. A suppression can appear inside a rule's delay_seconds grace window, so the only correct check is the one taken immediately before the transport call — which is also what produces the status='suppressed' row with no transport call that the acceptance line asks for. Being unverified is a standing property, stable across that window, so excluding at delivery would write an outbox row purely to throw it away — and on a deployment that upgraded before verifying anybody, one rule firing would write thousands of suppressed rows nobody can read.

The gate is a channel hook, not an engine branch. It hangs off a new optional registerDeliveryChannel({ eligible }), and email is the only channel that declares one. Both alternatives were wrong in a way the build made obvious: filtering the shared audience before the per-channel loop silences the wrong sink — a rule spanning email and in-app must still put an item in an unverified user's inbox, since being unverified is a reason not to mail somebody and no reason at all to hide their notifications — and an if (channel === 'email') in engine.js puts one channel's rule inside the generic engine. Its excluded counts flow into summary.ineligible and into the admin reach preview, which until now reported an audience size that was never the number of people who would get a mail.

Both new checks fail OPEN, and the try/catch in eligible is load-bearing rather than habit: applyRule awaits it before the per-user loop, so an uncaught throw abandons the whole rule for every channel it names — a rule that silently sent nothing, with a clean log and an empty outbox. That is G22's shape again, and the recoverable mistake is mail going out.

The live rig found the one defect the stubs could not. Against a real MariaDB, a real SMTP conversation (mailpit) and the real engine and worker, a hard bounce was recorded as status='failed' — honest, but engagement_sends.status has carried bounced since §4.5 and nothing had ever written it, so the Send Log's "Bounced" filter matched nothing and always would have. It is now a distinct outcome, because "the relay would not take this" and "this mailbox does not exist" send an operator to two different places. engagement_outbox.status still records it as failed: that ENUM has no bounced, and from the queue's point of view a bounced row is one that finished unsuccessfully. complained still has no writer, and cannot have one without a provider feedback loop.

Verified on the live rig, seven rungs, each one a real send or a real refusal:

1. baseline — three recipients, three mails in mailpit, three sent rows;
2. one address suppressed by hand — two mails, and a suppressed row naming the reason;
3. suppression lifted — three mails again;
4. gate on — two mails, ineligible: { unverified: 1 }, and no send-log row at all for the excluded user, which is what enqueue-time exclusion means;
5. a 550 5.1.1 from the relay — two mails, one bounced row, and b***@example.test written to the suppression list with detail: hard bounce: 5.1.1;
6. the same rule again — that address suppressed, with no transport call;
7. a password reset to the suppressed address still arrived, which is decision 2 proved rather than asserted.

The three admin routes were then driven over real HTTP: created_by records the admin on a manual row and stays NULL on the worker's automatic one, which is what separates them in the list; a repeat POST answers 200 {created:false} rather than a 409; DELETE matches case-insensitively, which is the whole point of hashing a folded address; no response contains address_hash; and all three refuse a signed-out caller.

Still later phases': an API-based transport with a signed webhook receiver, which is what would bring asynchronous bounces and complained to life. Nothing here blocks it — a transport may declare a bounce handler today.

---

Phase 10 — Protocol bump: three wire enrichments ✅ (parallel from day one)

Scope widened 2026-08-31, by the org lead, before any code. The phase was written as the house.decay enrichment alone. It now carries three enrichments, for one reason that is a property of this phase and of no other: a protocol bump costs a sidecar release, a republished bundle and an operator update on every shard. A field left out here does not cost a follow-up commit — it costs a second bump with the same three-part lead time, and an operator population split across two protocol versions in the meantime. So everything the engagement workstream is known to need from the wire is decided now and rides the single v4 → v5 bump.

The two additions come from Phase 11's expanded trigger set (below). Each was verified against the emitters rather than assumed, and each closes a gap that §8.6 did not know it had:

• Player-vendor fee state. uo.vendor.expiring is the same shape as the flagship — an owned asset at risk, with a real deadline — and is the second-strongest driver in the catalogue. But vendor.listing carries ownerSerial and ownerName and no ownerAcct and no fee state at all, so the trigger can today neither be addressed to a person nor know that anything is expiring.
• A login outcome. EventSink.AccountLogin is a pre-decision veto hook — the emitter's own comment says so ("Fires before the auth decision, so this is an attempt, not a result"). It therefore fires on every successful login too, and uo.account.login_attempt as §8.6 describes it ("someone tried to log into your game account") cannot be built on it: it would mail a security alert every time the player themselves logged in. This is the one addition that is a new emitter rather than new fields on an existing one.

Explicitly NOT in this bump: moving vendor.sale out of the opt-in patch tier. It stays where it is (see §8.6's corrected row), which leaves uo.vendor.sale dormant on a shard that declined the patches — a documentation obligation, not a protocol one.

Repo	Change
servuo-plugins/	(a) BridgeSweeps.WriteDecay gains ownerName (house.Owner.Name), nextStage (BaseHouse.NextDecayStage), decayPeriod, and estimatedCollapse only when to == "IDOC" (§0.3) · (b) BridgeMarket's vendor.listing gains ownerAcct, holdGold, chargePerDay, daysRemaining · (c) a new post-decision account.login.result (acct, accepted, rejectReason, ip) beside the existing pre-decision attempt
servuo-plugins/overlay.toml	protocol = 4 → 5, in the same PR as the emitters
link/	PROTOCOL_VERSION: u32 = 4 → 5 (sidecar/src/main.rs:55); the houses board carries the new decay fields; account.login.result is a forwarded kind like any other — the sidecar stays a dumb forwarder
website/ (module-uo)	ingest maps the new fields; uoLinkConfig protocol version; shardVisibility.js's KIND_FEATURE gains account.login.result — rule 2 fails an unmapped kind closed to admin-only, which is the right answer for a frame carrying an IP, but it must be chosen here rather than inherited by accident
docs/	docs/link/INTEGRATION.md §Housing and §Market tables + examples, docs/link/PLAN.md §5/§7

Two things the emitter work must not get wrong, both following from §0.3's finding about how ServUO actually decays:

• estimatedCollapse is exact only at IDOC, because dynamic decay draws each stage's duration at random when the stage is entered. Emitting it at an earlier stage would publish a guess as a fact.
• daysRemaining for a vendor is exact (HoldGold / ChargePerDay), unlike the house. The two fields must not be documented as though they carried the same confidence — a template that says "your house collapses on the 4th" and one that says "your vendor is dismissed in 2 days" are making very different promises.

Acceptance: a live run on the local rig (C:\Users\colby\Desktop\ServUO + the Rust sidecar, not the PowerShell stub) shows (a) a real decay transition carrying the new fields, (b) a seeded player vendor whose listing carries a fee state that falls as its held gold is drawn down, and (c) a failed game login producing account.login.result accepted:false where a successful one produces accepted:true; a v4 overlay paired with a v5 sidecar is refused by the installer, not mis-parsed; CI publishes a bundle whose manifest pairs v5 with v5; and the five-rung shard visibility walk still shows no leak, with account.login.result reaching admin only. Note: this phase's lead time is a release plus a bundle plus an operator update, which is why it starts early and lands independently.

---

Phase 10 as built (2026-08-31)

Design of record: ../link/v5.md. All three enrichments shipped as scoped, and the phase found nothing that changed its shape — which is itself worth noting, because the two additions to this phase existed only because reading the emitters had already contradicted §8.6 twice.

Two design decisions taken during the build, neither of them in the phase text:

• Both new field groups are NESTED (house.decay.schedule, vendor.listing.fees) rather than eleven sibling keys. The visibility projection matches literal JSON keys, so a nested group is ONE admin rule that governs the whole group — and, more importantly, a field added inside it later inherits the gate instead of defaulting to visible. Eleven flat keys would have been eleven rules to keep in step. There is a test that adds an imaginary future fee field and asserts it is still gated.
• There is no daysRemaining. The obvious name is wrong: under ServUO's old vendor system a pay period is a UO day (Clock.MinutesPerUODay, ≈2 real hours), so the field would have been off by a factor of twelve on exactly the shards least likely to notice. The wire carries periodsRemaining plus the interval, and resolves the arithmetic into dismissalAt — an instant, which needs no units.

Three visibility classifications, each chosen rather than inherited (v5.md §4): the decay schedule is anonymous (the countdown is the public IDOC page's content), fees is admin — the only default in the market feature that does not reproduce prior behaviour, because a vendor's held gold is owner-only in game and publishing it is both a new disclosure and a targeting aid — and account.login.result is admin-only by omission, since KIND_FEATURE is the map of kinds an admin may widen and there is no rung below admin an IP-plus-auth-verdict belongs on.

The REST reads deliberately did not change. shard_vendors' eight new columns are in no read model's column list: they exist for Phase 11's server-side trigger and reach no client at all.

One improvement to the pin, which is the protocol-4 bug seen from the other side. module-uo's schema test asserted DEFAULT 4 at each declaration site — so when the emitters moved and one site was left behind, every site still agreed with itself and the test passed. It now reads DEFAULT_PROTOCOL from the model, making the assertion "the declarations agree" rather than "they all say 4", and the one-shot migration test is written once against the current version instead of being hand-copied per bump.

Acceptance, all met. 470 tests in module-uo/server (16 new) and 39 in the sidecar; the C# compiles against real ServUO 57.4 assemblies. On the live rig — real ServUO, seeded world, the release sidecar — a house walked Fairly → Greatly → IDOC produced estimatedCollapse on the IDOC frame and only there; every observed vendor's periodsRemaining matched funds / chargePerPeriod, including one at 0 whose dismissalAt equals its next tick; and a real socket login produced accepted:false reason:BadPass for a wrong password and accepted:true for the right one. The installer needed no change — its pairing refusal is version-agnostic and already tested (bundle.rs::a_protocol_disagreement_inside_one_bundle_is_refused).

Two rig traps, both of which fake a broken emitter by producing silence (v5.md §6.1): an in-process login probe can never produce accepted:true, because AccountHandler calls HasAccess(e.State) before it checks the password and a null NetState fails it; and forcing a decay stage on a house that cannot decay emits nothing at all, because an AutoRefresh house — and the owner's newest house is always AutoRefresh — resets the forced stage on the next read. Both are recorded in servuo-plugins/tools/scaffolding/README.md beside the new BridgeProtocol5Probe.cs.

Deferred, deliberately: runicgateway.com's platform.json.protocol → 5 stays Phase 12's, since checkFacts.mjs fetches from main and setting it during the edge period turns that repo red at once.

---

Phase 11 — module-uo's triggers: the full catalogue, and core's news.post ✅

Scope widened 2026-08-31, by the org lead, before any code. This phase used to say module-uo registers uo.house.idoc_warning "(and siblings)", and Part 8's preamble used to say "Phase 11 ships exactly one rule". Both are now wrong on purpose: Phase 11 ships every ✅ row in §8.6, with the carve-outs named below. §8.6 was written as "a catalogue, not a commitment" — it is now the commitment, and the burden of proof has inverted: a row that does not ship needs a reason recorded here. Four rows do not ship, and all four reasons are recorded — one in this section (uo.market.item_listed) and three in the decision block below.

What that is worth, and it is not "more mail". One trigger proves that a module can register a trigger. Twenty-odd triggers spanning five audience kinds are the first real test of the things Parts 3–5 asserted and nothing has yet stressed: that the ceiling lattice holds when most triggers are not public, that check:modules still finds no UO identifier in core when the module is this large, and that a player's preferences screen stays legible when the catalogue is real rather than a demo. Every rule ships enabled = 0 (Q3), so this is a catalogue an operator turns on, not a switch that floods anyone.

The carve-out: uo.market.item_listed does not ship here, for the reason §8.6 already gives — it is 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. It is its own workstream on top of this one. vendor.listing remains ingested; nothing is lost by waiting.

Six decisions settled by the org lead before any code (2026-08-31)

Phase 2's precedent, and for the same reason: each of these is cheap now and expensive to retrofit, and two of them are security boundaries. Three came out of checking §8.6's rows against what the website can address rather than against what the wire carries — a different question, and the one nobody had asked.

	Question	Decision
1	the operator-facing family ceilings at admin, and there is no admin in the lattice	add it, as a child of staff; MODULE_API_VERSION → 1.8.0 (§5.1a)
2	uo.guild.joined/left overlap core's team.member.joined	ship left + disbanded only; joins stay core's (§8.6)
3	uo.points.rank_changed cannot address an owner	subscribers only; the personal half carved out (§8.6)
4	uo.link.requested has no recipient and a 5-minute TTL	carved out (§8.6)
5	§7.1 Q9 — news.post continuity	replace the raw tickle, seed the rule DISABLED; news push stops on upgrade, deliberately (§7.1 Q9)
6	the 11a / 11b split this phase's last paragraph asks to confirm	confirmed, and split as below

Decision 1 is the one with a version number attached, so state what it costs. ceilings.js gains one PARENT entry, one label, and a recipients query; permits, meet and meetAll are untouched, because admin is the only pair in the whole tree that is a genuine refinement — every admin is staff. The bump to 1.8.0 is real and both halves take it. Decision 5 is the one with a migration note attached: EngagementRules.jsx's existing "Team email resumes when you switch a rule on" banner must name news too, and Phase 13's release note must carry it as an upgrade step, or a deployment loses news push silently.

Two mechanisms this phase needs that no earlier phase built, neither of which is a decision so much as a consequence. uo.vendor.expiring and uo.economy.milestone are threshold events, and rule conditions compare a declared variable against a literal only (conditions.js — no arithmetic, no relative time), so "within 24 hours of dismissal" is not expressible as a condition. Nor can the trigger simply fire per frame: vendor.listing is a sweep frame re-emitted on any price change, and economy.supply arrives every five minutes. So the threshold crossing is tracked module-side, in the in-process tracker shardStreams.js already uses for champActive and cityGovernor, and the trigger declares periodsRemaining / hoursRemaining as ints so an operator can still narrow with lte. The seeded rule carries a subjectKey cooldown keyed per vendor. Same shape for the economy milestone, whose thresholds are the module's.

Two rows ship only because Phase 10 does. uo.house.idoc_warning's enrichment and uo.vendor.expiring both need v5 fields; uo.account.login_attempt needs v5's new account.login.result emitter and is renamed uo.account.login_failed to say what it actually is. Everything else is mapping-only and can ship whether or not the bump has landed — the flagship's Greatly mapping included, which needs no protocol change and can ship with Phase 6 if Phase 10 is still in flight, the trigger simply omitting nextStage/estimatedCollapse until the v5 overlay is deployed, exactly as the required: false declaration already permits.

The set, grouped by the audience kind each family exercises — which is the point of grouping them this way, since the audience kind is the thing being tested:

Family	Triggers	Audience kind	Notes
Owned asset at risk	uo.house.idoc_warning, uo.house.refreshed, uo.house.collapsed, uo.vendor.expiring	owner (linked account)	The flagship family. All four resolve through ownerAcct → shard_links. uo.house.refreshed was added by decision 11 during the live walk: it is what CANCELS the warning's delayed row, and without it a fifteen-minute delay was just a late mail
Passive income	uo.vendor.sale	owner	Patch-tier only — see §8.6's corrected row; dormant on a shard that declined the patches, and the seeded rule's description must say so
Personal security	uo.account.login_failed, uo.account.unlinked	owner, ceiling owner	uo.link.requested was a third here and is carved out (decision 4)
Personal milestone	uo.skill.capped, uo.quest.complete, uo.character.death, uo.character.murdered	owner, opt-in	The two death triggers are a killfeed some players want and most do not — both ship enabled = 0 and default off per channel
Social / civic	uo.guild.left, uo.guild.disbanded, uo.governor.elected, uo.election.opened	members, subscribers	uo.guild.joined is core's team.member.joined (decision 2). uo.election.opened carries autoPickAt — a real deadline, so it is the first trigger whose template has a genuine call to action with an expiry
Come online now	uo.champ.started, uo.champ.boss_up, uo.server.up, uo.server.down	subscribers	uo.server.up/down is the cooldown table's stress test — a flapping shard emits both repeatedly. Hard per-rule cooldown, not a per-send one
Leaderboard	uo.points.rank_changed	subscribers	The board's top N changed. The owner half is carved out — top[] names a serial, and links are keyed by account (decision 3)
Staff-facing	uo.page.new, uo.cheat.detected	ceiling staff	These are why the ceiling exists. Phase 3 already filters a staff-ceiling trigger out of a player's catalogue and gates it on write, so this family is the production proof of that work rather than new mechanism
Operator-facing	uo.audit.staff_action, uo.economy.milestone, uo.world.saved	ceiling admin (new — decision 1)	Digest-shaped by nature; neither of the last two should ever be instant. uo.audit.staff_action moved down from staff: a digest of what moderators did is not for moderators

Also core's own news.post emitter, which this phase's title has always understated (§7.1 Q9). news.post is declared with no caller, so a rule naming it can never fire; wiring it is one ctx.events.emit-shaped call in announceIfNewlyPublished, gated on the same job-id transition signal the push already uses. The announce legs and the post hooks are untouched — a module's town-crier leg is a delivery to a channel of the deployment and its news-gump hook is state mirroring, neither of which is a per-person notification. What the emit replaces is the raw pushDispatch.publish beside them — and it does replace it (decision 5), with core seeding a news.post rule enabled = 0 beside the four Team ones. News push therefore stops on upgrade until an operator switches that rule on. That is the deliberate answer rather than the comfortable one; §7.1 Q9 records why, and the two obligations it creates — the admin banner and the release note — are 11a's and 11b's respectively.

Also module-uo's first registered audiences (§5.1a: "module-uo's first real audiences come in Phase 11"). These are the operator-composable lists — named sets with constant parameters that an admin points a rule or a segment at — and they are a different mechanism from the members audience the guild triggers use. A guild event resolves to "the members of this guild", which is different for every firing and therefore travels on the envelope as recipientUserIds, exactly as the Team fan-out does (Phase 6, decision 2); a registered audience answers a question with the same answer every time it is asked. Three ship: uo.guild.members (param guildId, ceiling members), uo.governors (no params, ceiling members) and uo.linked.accounts (no params, ceiling members) — every website user with a linked game account, which is the set an operator reaches for first and the one a not composes against.

On the size of this phase, and the split — confirmed by the org lead (decision 6). It is the largest in the workstream: 24 trigger declarations after the three carve-outs, their audiences and ceilings, their shardIngest mappings, three registered audiences, and a seeded rule and template each — against Phase 5a's nine seeded bodies in total. It lands as two PRs per repo, on the 4a/4b and 5a/5b precedent:

• 11a — declarations, mappings, ceilings. Server only, and no template or rule is seeded. module-uo: server/config/shardTriggers.js (the 24 declarations, every variable carrying its required example), server/utils/shardEngagement.js (the wire-kind → ctx.events.emit mapper and its transition/threshold trackers), hung off shardIngest.ingest beside the existing broadcast and push fan-outs and fire-and-forget like both; owner resolution through shardLinks.getByAccount → ownerUserId on the envelope, the shardPush.js precedent unchanged; server/core.js gains events; registerEventTriggers + registerAudiences in server/index.js. website: the admin ceiling (decision 1), the news.post emitter and its seeded-disabled rule (decision 5), the banner text, MODULE_API_VERSION → 1.8.0, and engagement-triggers.json regenerated. The acceptance that belongs here is the catalogue-shaped half: no staff- or admin-ceiling trigger appears by name in a player's preferences catalogue, and check:modules proves core gained no UO identifier.
• 11b — the seeded templates, the seeded rules, and the live walk. 26 rules, all enabled = 0 — the twenty-fifth is uo.governor.appointed (decision 10 below) and the twenty-sixth is uo.house.refreshed, which the walk itself added (decision 11). Seventeen in-universe bodies on two channels each (decisions 8 and 9), and core's notify.event + inapp.event + the structural projection for the nine that stay plain — §4.6.1 property 1 is precisely the claim that a trigger needs no authoring, and the nine are the test of it that means something. All of it reaches the database through registerEngagementSeeds, which decision 7 adds because no mechanism for a module-supplied template or rule existed. Everything in the acceptance list below that needs a running shard is 11b's.

Four more decisions, settled by the org lead before any 11b code (2026-09-01)

Phase 11a shipped the declarations and stopped exactly where the plan said it would. Standing it up raised four questions the plan had not asked, two of which are mechanism and two of which are voice. All four were settled the same day, before any code, and three of them changed what 11b builds.

	Question	Decision
7	a module cannot ship a template or a rule — core's seeders are core's	add api.registerEngagementSeeds({ templates, ruleGroups }); MODULE_API_VERSION → 1.9.0
8	the register the game-powered bodies are written in	in-universe, with a per-family in-fiction sender — the crown writes about the crown's business, and nothing else
9	which bodies stay plain	the nine security and operational ones; the other sixteen go in-universe
10	the newly-elected governor is addressable and receives no letter	add uo.governor.appointed — a 25th trigger, owner-audienced, beside the existing broadcast

Decision 7 is the one 11a could not have discovered, because 11a seeded nothing. templateSeeds.js and coreRules.js are core files with core arrays in them, and there is no registerTemplates or registerRules anywhere in registries.js. So the sentence above — "24 rules, all enabled = 0; bespoke template bodies" — described work with no mechanism to land in. A module could have reached engagement_templates through the ctx.query it already holds, and that was rejected for the reason every raw-SQL-into-core-tables shortcut is rejected: it would re-implement seedOne's customized skip, its seed_version comparison and its block validation outside the file that owns them, and the copy would drift the first time core improved the original. The registry keeps every one of those in core and lets a module supply data — which is the same split registerEventTriggers already makes, and the same reason it makes it.

Templates are re-ensured every boot; rule groups are one-shot. That asymmetry is not an oversight, it is the two mechanisms this system already has, applied unchanged. A template row carries seed_key + seed_version + customized, so re-ensuring is how a better default reaches a deployment without stealing an operator's edit (§4.6.1 property 3) — and a template added in a later module version reaches every deployment, not only fresh ones. A rule is the opposite: re-ensuring one would resurrect a rule an operator deleted and reset one they enabled. So rules arrive in named groups, each with its own one-shot settings guard, which is 11a's seed-key finding stated as an API rather than as a warning. A rule added to an existing group reaches fresh installs only; a rule that must reach existing deployments takes a new group. The module names its groups, so the module owns that choice, and gets a docs paragraph telling it which one it is making.

Where it runs is load-bearing, and it is not seedDefaults(). server.js calls seedDefaults() before it requires app.js, and requiring app.js is what scans the volume and runs the loader — so at the moment core seeds its own templates, no module has registered anything. Module seeds therefore run in modules/lifecycle.js boot(), after the installed_modules reconcile and before the onBoot dispatch: a module whose onBoot warms a cache may assume its rules exist, and a module the operator has disabled or that failed to load is skipped rather than seeded. Failure is safe()'d like every other step there — a template that would not seed costs the shipped default, never the boot.

Decision 8 is why the bodies are the module's and could not have been core's even with a mechanism. "A letter from Lord Blackthorn" is Britannian canon; §5.2's rule is that core stays ignorant of every word of a module's domain. check:modules would not have caught it — it reads identifiers, imports and route literals, never prose (checkModuleIdentifiers.js says so in its own header, and says why) — and that is precisely the argument for taking the boundary seriously here rather than leaning on the checker. A templateSeeds.js in core containing uo.house.idoc_warning and the word Britannia would defeat the extraction while passing every check in the repo.

The sender is per family, not one voice across all sixteen. The crown was the tempting answer and it is the wrong one: a shard where Blackthorn writes to you personally about a champion spawn is a shard where the letter about your governorship means nothing. So the court writes about the crown's business — the governorship, the elections — and everything else has the sender its own subject implies:

Family	In-fiction sender
uo.governor.appointed, uo.governor.elected, uo.election.opened	Lord Blackthorn's court — the seat, the ballot, the realm's offices
uo.house.idoc_warning, uo.house.collapsed	the Office of Deeds — a clerk with a ledger and a duty to warn
uo.vendor.expiring, uo.vendor.sale	the Merchants' Guild — a factor rendering accounts
uo.guild.left, uo.guild.disbanded	a guild herald
uo.champ.started, uo.champ.boss_up	the town crier — which is also the leg a module already owns
uo.skill.capped, uo.quest.complete	the guildmaster of that craft
uo.character.death, uo.character.murdered	the Chronicler of the Dead
uo.points.rank_changed	the keeper of the rolls

Decision 9 draws the line at the two places fiction costs something real. A security notice must be distinguishable from flavour — a failed-login mail written as "a stranger sought entry to thy account" is indistinguishable in register from the phishing mail it is warning about, and that is not a trade worth making for atmosphere. And an operator reading uo.cheat.detected at two in the morning wants a name, a rule, a location and a timestamp, not a scroll. So nine stay plain and use core's generic bodies:

PLAIN (9, core's notify.event / inapp.event)
  uo.account.login_failed   uo.account.unlinked      ← security
  uo.server.up              uo.server.down           ← infrastructure
  uo.page.new               uo.cheat.detected        ← staff ceiling
  uo.audit.staff_action     uo.economy.milestone
  uo.world.saved                                     ← admin ceiling

IN-UNIVERSE (16, module-uo's own bodies)
  house ×2   vendor ×2   skill/quest/death ×4
  guild ×2   civic ×3    champ ×2   points ×1

Both channels, and the digest is deliberately not one of them. Each in-universe trigger ships an email body — the letter — and an inapp body in the same voice, because a rule fires on both channels at once and a player who reads the inbox item and then the mail must not find two different narrators. Thirty-two rows, which is data rather than design. The digest stays core's generic notify.digest: a day of events rolled into one list is not a letter from anyone, and dressing a bulleted summary as correspondence is where this device stops being charming.

Decision 10 exists because a fact in the plan was wrong by omission. §8.6 records that uo.points.rank_changed cannot address a person, because points.board.top[] names a mobile serial and links are keyed by account — and the same reasoning was silently assumed to cover the governor. It does not. city.update's governor field is written by BridgeJson.Actor(), which emits serial, name, acct and even webId when the account is linked. The new governor is addressable today, with no protocol change and no new wire field. So the letter the whole voice decision was chosen to make possible has a recipient, and 11b ships it:

• uo.governor.elected stays exactly as 11a declared it — subscribers, ceiling authenticated, the town-square announcement that a city has a new governor.
• uo.governor.appointed is new — audience: 'owner', ceiling: 'owner', subjectKey: 'city', resolved through ownerAccount: ev.governor.acct on the same city.update frame, in the same transition branch, guarded by the same never-on-first-sight rule. It is the letter.

Widening the existing trigger to two audiences was considered and refused for a reason worth keeping: one trigger means one rule means one template, and the town's bulletin and the governor's letter are not the same text. Two triggers is also what lets an operator run the announcement and leave the letter off, or the reverse.

This takes the phase to 25 triggers, and the count in §8.6 and in 11a's summary should be read that way from here — 26 after decision 11 below added uo.house.refreshed. It does not take another MODULE_API bump: a trigger declaration is module data, and 1.9.0 is decision 7's.

What building it found

Four things, and the first two are the ones a reader of this section should not have to re-derive.

A template has no conditionals, and an in-universe body is a sentence. That combination is the whole engineering content of decision 8, and it is not obvious until a body is written. An unset optional interpolates to the empty string (interpolate.js — no filters, no ternaries, by design), which is exactly right for notify.event, whose variables are structural and each sit on their own line. It is wrong for a letter: "Be it known that , recorded to thy name, is this day found ." So the ternary stays at the call site and its result arrives as a declared optional, which is Phase 5a's forWhom precedent unchanged — and the module now declares two shapes of them:

• a LABEL always has a value and can carry a sentence's spine. houseLabel is the house's name and region, falling back to its seal number, because a warning has to name something the owner can act on and a seal number is worse prose and better than a blank.
• a TRAILING FRAGMENT may be empty and leads with its own space, so the sentence closes cleanly without it: {{slainBy}}. renders "has fallen." or "has fallen at the hands of a lich lord."

The labels are declared required: false deliberately, and that is a real trade rather than an oversight: a required variable missing refuses the emit, and a dropped notification is worse than a cosmetic hole. Which leaves nothing at runtime to notice a mapper that forgot one — so engagementSeeds.test.js asserts every label is supplied on every path that emits its trigger. That test is the guarantee the declaration deliberately does not make.

A render sweep over all 32 bodies is what found the defects, and none of them were visible in the source. Every body was rendered twice — once with every declared example, once with required variables only — and scanned for the punctuation a vanished token leaves behind. Three real defects, none of which any existing check could see:

1. An optional variable in a SUBJECT LINE. A notice concerning thy house at {{region}} renders "…thy house at " for a house outside a named region. A subject is the one place a hole is unmissable, and it is also the one place no block validator looks.
2. Multi-optional detail lines. "On hand: gold. Charged each period: gold. Periods remaining: ." on a pre-v5 vendor frame, where the whole fee block is absent. Fixed the way place() already argues for coordinates: the line is assembled in the mapper from the parts actually present, and a frame with nothing to report produces no line rather than a punctuated empty one.
3. A trailing fragment used as a leading one, opening an in-app body with a stray space.

A trigger-bound template could not reference its own unsubscribe link. emailChannel.deliver computes an unsubscribe token per recipient and merges it last over the projection, so {{unsubscribeUrl}} always rendered — but variablesFor takes a trigger-bound template's variable list from the trigger's declaration, and a trigger has no business declaring a fact about how the mail was delivered. So the token was undeclared, and the save-time undeclared-variable check would have refused the first operator who tried to edit one of the sixteen bodies. Rendering right and then refusing the edit is the worst of both. Core gains DELIVERY_VARIABLES beside AMBIENT_VARIABLES — declared separately because they apply to a different set: ambient facts are about the deployment and reach every body, delivery facts are about the send and reach the trigger-bound ones, which is precisely the set that is engagement mail. Nothing had ever taken this path, because core's notify.event declares the variable in its own seed and is bound to no trigger.

A trigger id and a template key have different grammars, and one of these ids uses both characters. uo.champ.boss_up is a legal trigger id (§7.2 relaxed the id grammar to admit _ inside a segment, precisely so uo.house.idoc_warning could exist) and an illegal template key — engagement_templates.key is matched by templates.KEY_RE, which admits . and - and not _. So the body for that trigger is keyed uo.champ.boss-up. Caught at registration as a boot failure, which is the right place, and asserted in the module's tests so the next person meets it as a test name rather than as a puzzle.

Acceptance: the five-rung shard visibility walk still shows no leak, and no staff- or admin-ceiling trigger appears by name in a player's preferences catalogue; a house transitioning to Greatly on the live rig produces one email to the linked owner and nothing to anyone else; a second transition inside the cooldown produces nothing; a refresh back to LikeNew inside the delay window cancels the pending mail; a player vendor drawn down to its last day produces one uo.vendor.expiring to its owner; a failed game login produces one uo.account.login_failed and a successful one produces none; a shard restarted three times in a minute produces one downtime mail, not six; and a news post published on the rig reaches a rule, with the town-crier leg and every registered post hook still firing exactly as they did — and, decision 5's other half, with the seeded news.post rule switched on, a publish tickles the same subscribers it tickled before this phase; with it off, it tickles nobody and the admin screen says why. Two more the new ceiling owes: a rule cannot be saved giving an admin-ceiling trigger a staff audience, and an editor is not a recipient of uo.audit.staff_action while an admin is. Four more the 2026-09-01 decisions owe: a module's seeded rule group is seeded once and only once — an operator who deletes one does not find it back after a restart, and one they enabled is still enabled — while a module template whose seedVersion moved is re-ensured unless the operator edited it; an election on the live rig produces a letter to the new governor AND the announcement to subscribers, from two rules either of which can be switched off alone; and check:modules is still clean with sixteen Britannian bodies in the tree, which is the decision-8 boundary stated as a check rather than as a promise. Guardrails: check:modules proves core gained no UO identifier across every phase to this point — which is a materially stronger claim now that the module registers two dozen UO-named triggers.

Three decisions taken during the live walk (2026-09-01), and what it found

The walk is the last piece of 11b and it was not a formality: it found six defects, four of them in code shipped by earlier phases, and three of the fixes were decisions rather than repairs. None of the six was visible in a unit test, and the reason is the same every time — each is a disagreement between two things that agree with each other in a fixture.

	Question the walk raised	Decision
11	uo.house.idoc_warning ships delay_seconds: 900 and nothing could cancel it	add uo.house.refreshed — a 26th trigger, with a body and a seeded rule of its own
12	a rule with a cooldown delivered on exactly ONE of its channels	channel joins the cooldown key — a cooldown is per delivery, not per occasion
13	uo.vendor.expiring could not fire, because the market sweep does not diff fees	widen BridgeMarket.Signature() with exempt + periodsRemaining

Decision 11 — the delay had no cancel path for the GOOD outcome. §4.2a is explicit that a delay without a cancellation is just a late mail, and the fifteen minutes on the warning exist so a player who repairs the house is never told it is in peril. The rule's cancel_on named only uo.house.collapsed — the outcome where the warning is pointless — and nothing named the outcome where it is wrong, because the mapper deliberately returned early on every transition that was not a late stage, so a refresh reached the engine as silence. The wire had carried it all along. It ships with a body as well as the cancellation (the org lead's call): an office that only ever writes when something is wrong teaches its reader to dread the seal, and a notice that the ledger is set right is the cheapest possible way not to. The cancellation is read off the WARNING's rule, so an operator who wants it without the reassurance simply leaves the new rule off — which, every seeded rule shipping disabled, is the default.

Ageless, not only LikeNew, and this is a ServUO fact worth not re-deriving. A condemned house cannot be refreshed at all — BaseHouse.RefreshDecay() returns false for DecayType.Condemned — so the rescue is the owner logging back in. Their NEWEST house then becomes AutoRefresh and reads Ageless; an older one becomes ManualRefresh and reads LikeNew. Both mean "out of danger", and reading only the second misses the common case. The live rig produced Ageless.

Decision 12 is the one with the widest blast radius, and it had been latent since Phase 4a. cooldownsDb.claim is called INSIDE the engine's per-channel loop and its key was (rule, user, subject), so the first channel of a rule claimed the cooldown and every later one was reported as cooled. inapp is ranked first on purpose (so push can reference the inbox row it writes), which means a rule naming email + in-app delivered the inbox item and silently never the mail — including core's own news.post rule, which names three channels and carries an hour's cooldown. Decision 8 requires the letter and the inbox item to fire together, so every in-universe body this phase wrote was unreachable behind its own in-app twin.

Claiming once per user before the channel loop was the alternative and was refused: it makes the cooldown a per-occasion limit, and an operator who sets "one a day about this house" means one mail and one inbox item, not one of the two. So channel joins the PRIMARY KEY, migrated in place behind a guarded DROP PRIMARY KEY — MariaDB has no conditional form of a key change, so replaying the schema file would fail on every boot after the first without the information_schema guard. Existing rows keep channel = '' and expire on their own interval: one stale cooldown per (rule, user, subject) is a better trade than dropping the table, which would let a storm through.

Decision 13 is a defect in the shard plugin, and Phase 10 is where it was introduced by omission. BridgeMarket.Signature() diffs shop name, owner, map, coordinates and the item/price list — and v5 added a fees block that it never learned about. So a vendor quietly running out of gold changes nothing the sweep compares, emits no frame, and the trigger whose entire subject is a vendor running out of gold can fire only by coincidence: when somebody happens to reprice an item on a shop that is already broke. Proved on the rig by setting a vendor's held gold to zero and watching no frame follow. The fix carries the DERIVED values (exempt, periodsRemaining) rather than the raw ones — an integer division moves only when the shard's own answer to "is this vendor in danger" moves, while holdGold changes on every sale and nextPayAt on every tick, either of which would re-emit a fat listing frame for a shop whose listings did not change. No new wire field and no PROTOCOL_VERSION bump: it changes when an existing frame is sent, not its shape.

Four more defects, each fixed without a decision because the right answer was a fact rather than a choice:

• Every module-seeded rule failed to insert. checkSeedRule validated max_sends_per_hour and then dropped it from the normalized rule; the column is NOT NULL, so all 25 rules failed at boot — loudly, on a real database, and on no fixture. The registry test asserted the REJECTION of a bad ceiling and never that a good one survives. It now asserts the normalized rule against the insert's own column list, so the next field added is covered the day it is added.
• Every owner-audienced trigger resolved to nobody. resolveTarget read link.user_id where the model's toSafe returns userId, so the flagship family — houses, vendors, logins, unlinks, deaths, the governor's letter — reached no one, and looked exactly like the ordinary unlinked-account case, which the code treats as normal and deliberately does not log. The test fake returned user_id and therefore agreed with the bug, while shardStreams.test.js's fake next door — same model, and the path shardEngagement.js says it copies — returned userId. The fake is now built by running the real toSafe over a stubbed row.
• Every call-to-action in every in-universe body was a dead link, from two independent mistakes with one symptom. The client router prefixes a module's routes with its ID (/uo/houses), not with module.json's mounts (/shard/…), so every declared example and every hard-coded href was a 404 — and not one of the eight url variables was ever populated by the mapper, so the buttons rendered with an empty href and vanished from the text part altogether. Both now read config/clientPaths.js, and two tests close it: every url example must name a route the module mounts, and every declared url variable must actually be supplied on the path that emits its trigger.
• A raw wire timestamp was signing off the Merchants' Guild's letter — 2026-09-02T04:06:43.8397548Z, mid-sentence. Core has no interpolation filters by design, so the readable form is assembled in the mapper and arrives as its own variable; the machine value stays exactly as it was, because an operator writes is at most conditions against it.

What the walk proved, rung by rung, against real ServUO + the release sidecar + a live SMTP catcher. A Greatly transition produced one notification to the linked owner on both channels and nothing to a second linked player who was subscribed; the next transition inside the day was cooled; the owner logging back in cancelled both pending rows and sent the reassurance letter; a vendor drawn to its last period warned its owner once and was cooled on the second crossing; a failed game login over a real socket produced one notice and a successful one produced none; three genuine shutdown/boot cycles produced one downtime fan-out and two fully-cooled ones; a governor seated on a live city.update produced both the town's bulletin (six subscribers) and the crown's letter (the winner alone); a real staff action driven through the sidecar reached the admin and neither the editor nor the moderator, both of whom were subscribed; and the rule editor refused staff, authenticated and everyone on an admin-ceiling trigger while accepting admin.

The three cycles took about three minutes rather than the acceptance's "one minute", because a real ServUO boot is roughly fifty seconds. The property is unchanged: the rule's cooldown is an hour.

The walk is repeatable. servuo-plugins/tools/scaffolding/BridgeRigDriver.cs drives the shard from outside the game over a polled command file, which is what a walk needs and what no existing probe gave — every other one runs a fixed script at boot or from an in-game client, and ServUO's console takes a fixed verb set, so [p5probe cannot be typed at a headless shard at all.

---

Phase 12 — runicgateway.com: the public site and the docs journey ✅

This phase is not optional polish, and it is not "update the marketing copy". Two of its checks will fail the build on their own, and they read from main, which fixes exactly when this has to land (see the timing note below).

The mechanical half — the site's own checks go red at cutover. scripts/checkFacts.mjs fetches each value's authority from the main branch of the source repo and fails the build on any disagreement (link main:sidecar/src/main.rs, servuo-plugins main:overlay.toml, website main:server/src/modules/version.js, Module-uo main:module.json, and the bundles branch). So src/data/platform.json needs:

• protocol: 4 → 5 (Phase 10) — asserted three times over: the sidecar, the overlay, the bundle.
• moduleApi: "1.6.0" → "1.7.0" (Phase 2).
• bundle.tag / bundle.sidecar / bundle.overlay — whatever Phase 10's republished bundle carries.
• verifiedOn moved, and the page that quotes each value re-read rather than the JSON edited to make the check pass — which is what the file's own header comment tells you in as many words.

The content half — the site currently documents the opposite of what Phase 1 ships. src/content/docs/docs/administration/notifications-and-email.mdx carries an <Aside type="note" title="There is no SMTP option"> and the sentence "Gmail over OAuth2 is the only supported delivery path today." Also configuration.mdx:62 ("it is Gmail over OAuth2, it reuses the Google authentication client"), troubleshooting.mdx:101 ("Connect Gmail in Settings → Email delivery"), and system-architecture.mdx:117 ("the Gmail refresh token"). All four become false the day Phase 1 merges to main.

The capability claim to fix while here. src/data/capabilities.mjs's Notifications item already says "Web, push and email, chosen per stream by each person" — "Web" is not true today (§0.1) and becomes true at Phase 7. One list feeds /, /features/ and /modules/, so this is one edit, and assertDetailCoverage() will make sure the detail line comes with it.

Legal and Play Data Safety. PLAY_DATA_SAFETY.md and /privacy are generated from one inventory (scripts/playDataSafety.mjs, src/data/legal.mjs), and an engagement mailer changes what that inventory has to say: an email address is now used for more than account function, there is a send log (engagement_sends, address hashes) and a suppression list. Play's Data Safety form distinguishes "app functionality" from "communications/marketing", and getting that wrong is a store review problem rather than a doc nit. Phase 9's decisions are the input, so this lands with or after Phase 9 — and it is the one part of Phase 12 with an external deadline attached to it.

New docs pages for the admin docs journey: the engagement rules screen, the template editor, and per-channel notification preferences. scripts/checkSidebar.mjs and checkQuickstart.mjs both hold this to the actual site, and checkQuickstart is a two-way drift check against the website repo's own setup — Phase 1 changes email setup, so expect it to have an opinion.

Timing — this is the sequencing trap. Because checkFacts reads main, the site stays green for the entire edge period and goes red the instant the cutover lands. So Phase 12's work must be written and reviewed before the cutover and merged inside the same window — not "after we ship". Left until afterwards, the public site is broken and publishing false statements about the product at exactly the moment anyone would look at it.

Acceptance: node scripts/checkFacts.mjs, checkLinks, checkSidebar, checkQuickstart, checkReference, checkA11y, checkCsp, checkBrand and npm test all green against the post-cutover main of every source repo; grep -ri "gmail" src/ returns only historical/legal references; /privacy and PLAY_DATA_SAFETY.md regenerate from the amended inventory with no manual edit; the Notifications capability line is true of the shipped system.

As built (2026-09-01) — split 12a / 12b, because the facts cannot be green and correct at once

The org lead's decision: split the phase. The timing note above says Phase 12's work is "written and reviewed before the cutover and merged inside the same window", and building it made the reason sharper than the sentence. checkFacts.mjs fetches from main, so the moment platform.json says protocol: 5 the repo is red — and it stays red for the whole edge window. Worse, three of its values cannot be written at all today: bundle.tag / bundle.sidecar / bundle.overlay name an artefact that does not exist until Phase 13 has landed link + servuo-plugins on main and CI has republished the bundle. So:

• 12a — runicgateway.com#26, mergeable on edge today. The Engagement rules page, the Troubleshooting symptom that points at it, the cross-links, and the /privacy + Play Data Safety inventory. Every check green.
• 12b — runicgateway.com#27, a DRAFT, deliberately red. platform.json protocol → 5 and moduleApi → 1.9.0, plus the protocol page. Held for the Phase 13 window; the fill-in step is in Phase 13's order below.

Two of this section's own statements were already stale, both because Phase 11 moved after it was written: moduleApi is 1.9.0, not 1.7.0 (1.8.0 for the admin ceiling, 1.9.0 for the module seed API), and the capabilities.mjs "Web" claim was already corrected in Phase 7's rg.com#24. The Gmail sweep is likewise already done — grep -ri gmail src/ returns only the migration note Phase 1 wrote and the historical reference in Troubleshooting, which is what the acceptance line asks for.

The page the phase actually owed. "New docs pages … the engagement rules screen, the template editor, and per-channel notification preferences" — the second and third landed in Phases 5b and 7. The first had not, and it was the largest hole on the site: there was a page for where a message goes and a page for what it says, and nothing for what makes one get sent, which is the entire admin surface this workstream built. One page — Rules, Audiences, the trigger catalog and the send log — between the two it joins up. Suppressions stays in Troubleshooting (Phase 9) and Templates keeps its own page (Phase 5b).

Two things it exists to state, because both are things a reader gets wrong by reasoning:

• Every rule ships disabled, including the ones a module brings. "Installed" is not "on".
• The ceiling is a tree, not a ladder (§7.2's lattice). The ladder reading says a staff-only event could obviously also go to one person; "one person" for uo.cheat.detected is the player it was detected on.

Three findings, none of them in the phase's own text

1. /privacy had been publishing a false sentence since Phase 8. The app-content row claimed "Nothing is cached for offline use and nothing is duplicated anywhere else", and Phase 8 shipped a DataStore snapshot of the inbox. That row is an input to the generated Play Data Safety answers, so it is a store-review matter and not a doc nit. The snapshot now has its own row and its own Play mapping (Messages / Other in-app messages; not collected by us, stored on the device), and the old claim is narrowed rather than softened.

2. Nothing in the engagement schema has a retention sweep. engagementCooldowns.db.prune() exists and has no caller; a finished engagement_outbox row is never deleted; the send log and the suppression list grow forever. The deploy-engagement privacy row therefore says "kept until the operator removes them; nothing here expires on its own", which is the true answer rather than the one a reader assumes. Recorded, not fixed — a sweep is a website change and outside this phase.

3. The one page whose whole subject is the protocol number was the one page that hardcoded it. platform.json's header says no version number is ever hardcoded in prose; protocol-versions.mdx wrote 4 three times. It now imports the JSON like every other page that quotes a fact. Note for whoever does this again: MDX does not evaluate an expression inside backticks, so the interpolation has to sit outside the code span or the braces reach the published page.

---

Phase 13 — The cutover: edge → main, in order ✅

One PR per repo, all in one window. The order is not cosmetic — a main holding a v5 sidecar and a v4 overlay is a shard that cannot pair, and the installer refuses it by design.

1. docs — the design of record and every doc the phases produced, so the reference exists before the code that needs it.
2. servuo-plugins and link together — the emitter and overlay.toml and PROTOCOL_VERSION are one protocol bump with three declaration sites (CLAUDE.md). Then CI publishes the paired bundle.
3. website — core: the transport abstraction, the trigger registry, MODULE_API_VERSION 1.9.0, the engine, the templates, the in-app channel, the Teams migration.
4. module-uo — its coreApi range and its triggers, after the core it declares against.
5. Integration-kit — ci/core-ref.json to the new website main sha. Its equality check is red until this lands, on purpose; moving the pin is the acknowledgement that someone re-read the chapters.
6. android-app — the in-app inbox. First real CI run (§6.0a).
7. runicgateway.com — last, because every fact it fetches has to be true on main first. Two merges, in this order: 12a (#26) into edge at any time, then edge → main, then 12b (#27) with its three unknowable values filled in. Filling them in is mechanical, because the check names them: run GITEA_TOKEN=<token> node scripts/checkFacts.mjs and copy what it prints in the "says" column — bundle.tag, bundle.sidecar, bundle.overlay from installer bundles:current.json, releases.Module-uo if the cutover cut a new module release, and verifiedOn as the date it was run. Then re-read the two pages that quote the bundle (getting-started/connect-a-game-server, administration/the-shard-connection) before merging — §12's own rule is that a value is never edited to make the check pass.
8. .profile/README.md — only if this is a headline capability.

Acceptance: a clean install from main alone stands the whole stack up — installer pairs a v5 sidecar with a v5 overlay, the site boots, SMTP is configured, a Greatly house transition on the local rig produces exactly one email and one in-app item to the linked owner and nothing to anyone else, and runicgateway.com builds green with no fact disagreeing with its authority. Every edge is then fast-forwarded to main again so the next workstream starts from a clean one — the step §6.0a found had been skipped after every previous cutover.

As built (2026-09-01)

The window ran in the order above and missed two steps. Steps 1 (docs#200), 2a (servuo-plugins#20), 2b (link#35), 3 (website#180), 4 (Module-uo#26) and 6 (Android-app#43) merged together; 5 and 7 did not, and were done afterwards as Integration-kit#9 and runicgateway.com#28, with Module-uo#27 clearing a leftover from step 4. What the window cut: link v2.1.0, the plugin overlay v1.1.0, module-uo v1.1.0, and the paired bundle 2026.09.01 (protocol 5). website releases nothing by design.

Every edge was deleted rather than fast-forwarded, in seven repos. The acceptance line above asks for the fast-forward so the next workstream starts from a clean branch; deleting reaches the same place more bluntly, since §6.0a's Phase -1 cuts edge fresh anyway — and a branch that does not exist cannot be the stale one somebody branches from, which was the actual failure. Only Integration-kit ended up in the state §6.0a warns about, one commit behind main once its own step landed late; fast-forwarded on the day. The convention is now delete-on-merge, and Phase -1 cuts edge rather than trusting one it finds.

1. Gitea's raw API route is CDN-cached for six hours, and a stale read fails BOTH ways. checkFacts.mjs failed runicgateway.com for a moduleApi that was correct: it had been served website's version.js from a fortnight earlier (Cache-Control: public, max-age=21600, cf-cache-status: HIT, Age: 15713), and no edit in that repository could have made it pass. The false red is the cheap half. The same run reported the already-republished bundle triple as still current — a stale read is just as able to say "nothing has moved", and that repo's whole bargain is that it goes red when the platform moves. All three cross-repository checks now read the contents endpoint, which answers private, must-revalidate and is not cached; a request Cache-Control: no-cache header does not bust the CDN, and a cache-busting query param was rejected as papering over the mechanism rather than choosing the right one.

2. The Integration-kit equality check never goes red on its own, and step 5 is the only thing that makes anyone look. It clones the ref the kit itself pins, so a core that moves past that pin changes nothing there. The kit sat three minor versions behind the platform for the whole workstream — teaching a 1.6.0 contract with no triggers, audiences or seeds in it — and was green throughout. Between cutovers the kit is not wrong, it is dated, and ci/core-ref.json is where the date is written down. Read step 5's obligation as someone re-reads the chapters, never as CI will tell us.

3. registerEngagementSeeds does not validate the body it seeds, and the kit's own example was malformed. The call checks that blocks is a non-empty array and stops; the body is validated by the block registry, which runs in the template editor and in the renderer and nowhere else. The draft template shipped a heading level: 2 — the registry takes 'h1' | 'h2' | 'h3' — and no block ids at all, so it would have registered cleanly, seeded cleanly, and failed the first time an operator opened it. It was found by running the template's register() through core's real stage() validators at the pinned ref, which the kit's CI does not do and cannot: it runs the template against test/_fakes.js, and a fake accepts what core refuses. Two smaller corrections came out of the same run — core does validate subjectKey against the declared variables and refuses the module, and ctx.events.emit throws outside production rather than only dropping and logging. Both had been written into the chapter the other way round.

The general lesson is §5.3's, arriving from the other side: a registration surface is only as teachable as the thing that checks it. Where the registry validates, the book can describe the error; where it does not — and blocks is the one place it does not — the book has to say so, and the template needs a test of its own. It has one now, verified by breaking it.

4. runicgateway.com's pr-checks.yml triggers on PRs into main only, so not one of the seven site PRs in this workstream was gated, and the cutover was their first CI run in eight phases. Same shape as android-app's trigger before Q8 fixed it (§6.0a), and left alone rather than fixed: that repo's checks read the source repos' main, so running them on an edge PR would have been red for the whole window by design. Phase 12's split exists for the same reason. What it costs is real though — 12b's fill-in was verified locally and merged on that evidence alone.

The acceptance walk — run 2026-09-01, PASSED

Every clause of the acceptance line above, on a rig built the way an operator would build one rather than the way a developer would.

A clean install from main alone. The released installer v0.1.1, downloaded and checked against its SHA256SUMS — the trust anchor the docs name, since releases are unsigned — resolved bundle 2026.09.01 and reported the pair it was about to deploy: overlay v1.1.0 protocol 5, sidecar v2.1.0 protocol 5. --verify first (add=23 change=1, nothing written), then the real run. dotnet build on the synced tree: 0 errors — the released overlay compiles against stock ServUO 57.4. The shard booted, printed [Bridge] enabled=True, and dialled the sidecar; the site reported status=connected pluginConnected=true. The website was a fresh main clone and module-uo v1.1.0 installed from its release manifest through the MODULES declaration — sha verified and unpacked by core, never copied in by hand. SMTP was configured against a mail catcher and its test send arrived.

One email and one in-app item, to the linked owner, and nothing to anyone else. Forcing 0x400143DB from IDOC to Greatly produced event dispatched {rules:1, enqueued:2, deduped:0, cooled:0, capped:0, cancelled:0}, and after the rule's grace window both rows sent on the first attempt. Every row in every delivery table names the linked user and no other — send log 2, outbox 2, inbox 1, and nothing for the admin or for the second, unlinked player. The mail was the in-universe body, correctly rendered: "A notice concerning “Yewcross”", the stage in words, the detail line, an absolute link to /uo/houses and a working unsubscribe link — no empty href, which is the Phase 11b defect class staying fixed.

Two defects it found, both in shipped core, neither visible to any test:

1. The one-shot rule-group guard is not atomic. moduleSeeds.js seedRuleGroup() reads its settings stamp, inserts the whole group, and writes the stamp after the loop. Two processes booting within the same moment both read "not seeded" and both insert: the rig ended up with 52 UO rules where the module ships 26, under one stamp. The function's own comment states the cost — "a duplicate rule is two mails per event" — which is exactly what its guard fails to prevent. It was reached here by two app processes starting milliseconds apart, which is what a --scale app=2 or a rolling restart does on purpose. The fix is to claim before inserting: an atomic conditional write of the stamp, or an insert idempotent per (owner, group, trigger). Same shape as Phase 4a's foundRows finding — a guard that reads before it claims.
2. A module-seeded rule that ships a digest body cannot be saved from the Rules screen. checkSeedRule permits digest explicitly, in as many words — "a template slot rather than a channel … allowed here and absent from channels" — and sixteen in-universe UO rules ship one. engagementRules.model.js then rejects any templateKeys entry that is not one of the rule's channels, so an operator who opens House — decay warning and presses Save gets a 400 naming a key they never typed. The only way to save is to delete the digest body, which silently removes digest support from that rule. The two validators have to agree about what digest is.

Both are fixed in website#181. settings.db gained claim(key, value) — the same INSERT IGNORE as seedDefault, reporting its own affectedRows, so exactly one caller can win a key — and both seeders now claim before inserting rather than stamping after. The trade the code already documented is unchanged, only its order: a process that dies mid-loop leaves the group stamped and partly seeded, which both functions already called the better failure. The stubs are claim-shaped now and each suite gained a test that runs two seeders under Promise.all; reverting the fix makes the module one report every rule inserted twice, which is how the fix was checked. And engagementRules.model.js now admits digest as the one key that is a slot rather than a channel, so the two validators agree; anything else is still refused, with a test in each direction.

Also still open: nothing else. .profile/README.md (step 8) landed — the org lead called the engagement system a headline capability — and Phase 12's second finding became Phase 14.

---

Phase 14 — Retention: the engagement schema has no sweep

Status: BUILT, 2026-09-01. Phase 12 found this and recorded it without fixing it (finding 2 of its as-built), on the grounds that a sweep is a website change and outside a documentation phase. Nothing after it picked the finding up, so it was stated here as the phase it always was — and this is that phase. Six decisions were settled by the org lead before any code; the as-built is at the end of this section.

Four tables grow without bound, and they are not one problem with one horizon:

Table	What accumulates	The constraint on a horizon
engagement_cooldowns	one row per (rule, user, subject, channel) per fire, read once per fire	engagementCooldowns.db.prune(olderThan) already exists and has no caller. The horizon must exceed the longest cooldown_seconds on any enabled rule, or a pruned row makes the next fire a first fire — the model says so and leaves it to the caller
engagement_outbox	every enqueued delivery, including terminal sent / failed / cancelled / suppressed rows	only terminal rows are eligible; a scheduled row may be days out by design (delay_seconds)
engagement_sends (the send log)	one row per delivery attempt	two live readers. The per-rule hourly cap reads idx_engs_rule_window (rule_id, created_at), so a horizon under an hour breaks Q3's ceiling; Admin → Engagement → Send Log is the operator's only answer to "was this person told", so a short one blinds the screen that exists to be looked at
engagement_suppressions	one row per suppressed address, forever	the odd one out, and probably correct as it is. A suppression is a standing decision; ageing out a bounce row means the next send re-mails an address that already hard-bounced, which is exactly how a sender loses a domain's reputation. If anything expires here it is unverified, and that is a decision to take rather than a default to assume

The shape is already in the tree, twice. utils/teamActivityPrune.js and utils/userNotificationsPrune.js are the same worker — setInterval + unref + stop(), a horizon read from a *_retain_days setting, started and stopped in server.js. Phase 7 wrote the second one for user_notifications after finding that table had no policy either, with one policy difference worth carrying: it deletes read items only, because age alone would destroy the evidence for "I was never told". The same question has to be answered per table here rather than assumed.

Documentation this owes. runicgateway.com again, and for Phase 12's reason: /privacy and the generated Play Data Safety answers currently publish, for the deploy-engagement row, "kept until the operator removes them; nothing here expires on its own". That is the true answer today and becomes false the moment this lands, and it is generated from one inventory (src/data/collection.mjs) rather than written twice. Also BACKEND_DESIGN.md's table inventory, and an operator-facing note for whichever settings keys this adds.

For the org lead, before any code: the four horizons (or three, plus "suppressions do not expire"), and whether the send log's retention is allowed to be shorter than the operator screen's usefulness — the alternative is that the screen learns to say "older entries have been swept" rather than showing a silently truncated history.

Acceptance: every one of the four tables has a stated policy — a sweep with a horizon, or a recorded decision that it does not expire and why; the cooldown horizon is checked against the longest enabled rule's cooldown rather than picked; /privacy and the Play answers are regenerated from the inventory; and a rig run shows the sweep deleting terminal rows while leaving a scheduled outbox row and an in-window send-log row alone.

Phase 14 as built

The six decisions, settled by the org lead before any code. Four horizons were put with the facts the tree supplied, and two of the four answers went past what was offered:

1. engagement_cooldowns — 30 days, plus the runtime guard. (MAX_COOLDOWN_SECONDS is a validated 86 400, so even 2 days is provably safe; 30 was chosen for headroom.)
2. engagement_outbox — terminal rows only, 30 days, plus a stuck-sending reaper. The reaper half turned out to be half-built already — see finding 2.
3. engagement_sends — admin-configurable, 90 / 180 / 365 / custom. This is the answer that widened the phase: none of the three offered options had a UI, and the other two retention workers in this codebase (teamActivityPrune, userNotificationsPrune) keep their horizons in invisible settings rows. It bought the phase a screen, and the screen took the other two horizons with it — "what does this deployment keep" is one question.
4. engagement_suppressions — never expires, plus an admin purge. The purge half also went past the offer, and cost a Phase 9 decision — see finding 1.

As built. utils/engagementRetentionPrune.js (one worker, three sweeps, batched 1000 × 50, each table's failure caught on its own), model/engagement/engagementRetention.model.js (the policy, its bounds and the cooldown check), two .db additions (outbox.pruneTerminal, sends.prune) and a limit on the cooldown prune that already existed and had never had a caller. Three routes (GET/PUT /admin/engagement/retention, DELETE /admin/engagement/suppressions/by-hash/:hash), a new Admin → Engagement → Retention screen, a per-row Lift button on Suppressions, and one line under the Send Log's pager. Two indexes (idx_engo_sweep, idx_engs_sweep) — every existing index on those tables has created_at in second position, which serves a per-rule window and is useless to a whole-table horizon. Reference: BACKEND_DESIGN.md § Engagement retention. PRs: website#182 · docs#205 · runicgateway.com#29.

Three findings.

1. The per-row purge cost a Phase 9 decision, and there was no way to have it otherwise. Phase 9 deliberately stripped address_hash from every listed row — a sha256 of every address on the deployment is an offline dictionary attack waiting to be run — and the consequence, which its own screen shows, is that the only way out of the list was a window.prompt asking the operator to retype the full address. They do not have it: the screen stores and shows a mask. So the row had no handle at all, and a per-row button was not a UI change but a reversal. Taken knowingly: the route is admin-only and an admin can already suppress and unsuppress any address they can name, so the hash grants no capability they lack. GET /sends still strips its own.

2. reclaimStale could not give up, so the outbox sweep would not have been a bound. The stuck-sending reaper decision 2 asked for already existed and already ran every worker tick — but it returned every stale row to scheduled, and MAX_ATTEMPTS is consulted only on a graceful retry outcome. A send that killed the process mid-flight therefore cycled sending → scheduled → sending forever: never terminal, therefore never eligible for the terminal-only sweep this phase was adding. Fixed by failing an exhausted row before reclaiming the rest; the order is the fix, and engagementRetentionSql.test.js runs the wrong order deliberately to show what it avoids.

3. The cooldown warning is unreachable through the UI, by construction. MAX_COOLDOWN_SECONDS (86 400) is smaller than the cooldown horizon's floor (2 days), so no rule that can be saved can trip the guard. It is not therefore dead: it fires for a hand-edited row, and it is the thing that catches a future raise of MAX_COOLDOWN_SECONDS that forgets this floor. Proved live by setting a 5-day cooldown by hand — the screen and the sweep both warned, and the sweep ran anyway.

The acceptance line, discharged. All four tables have a stated policy (three sweeps and one recorded refusal). The cooldown horizon is checked rather than picked. /privacy is regenerated from collection.mjs — and the Play answers correctly did not move, which the phase text did not expect: deploy-engagement is scope: 'deployment', and PLAY_DATA_SAFETY.md is generated from the app-scoped entries only, because Play asks what the app collects rather than what a self-hosted deployment keeps. npm run play:datasafety rewrites the file byte-identically and check:datasafety stays green. The rig run happened twice: engagementRetentionSql.test.js against a throwaway database (7 tests), and the live stack, where a 90-day-old cancelled row was swept and a 90-day-old scheduled row survived.

One rig trap worth not re-deriving. The first live run appeared to delete the scheduled row — the acceptance case, apparently failing. It had not: the outbox worker was running in the same server, the planted row's due_at was 90 days in the past, so the worker legitimately claimed and sent it before the sweep saw it. Plant the scheduled row with a FUTURE due_at, or the worker, not the sweep, is what the test is measuring.

---

Sequencing

Phase -1  fast-forward every edge to main; create edge in android-app,
          runicgateway.com and Integration-kit           ← blocking, §6.0a

Stage A   1 ── 1b ── 2
Stage B        └─ 3 ── 4 ── 5a ── 5b ── 6
Stage C                                 └─ 7 ── 8   (8 = app-store cadence)
Stage D                                      └─ 9
Stage E   10 ──────────────────────────────────── 11a ── 11b   (10 parallel from day one; 11 needs 6 + 10)
Stage F                                        12 ── 13   (12 written before 13, merged in its window)
Stage G                                              └─ 14   (retention; after the cutover, so straight to `main`)

                                    ── all of the above onto `edge` ──
                                    13 is the only thing that touches `main`
                                    ...and 14, which comes after it

Phase -1 is blocking and takes minutes. Every edge is 0 ahead / 3–16 behind main (§6.0a), so the fast-forward is lossless; skipping it means the cutover diff carries other workstreams' leftovers.

Phases 1, 1b and 10 can start immediately and in parallel; Phase 2 now follows 1b rather than 1, because a trigger's audience resolves to users and the identity those users are mailed at should be unique and verifiable before anything resolves an audience over it. Phase 1 and Phase 6 are the two that touch mail people actually receive and should each land alone: Phase 1 because it can silently stop email for the live deployment (§1.2a), Phase 6 because it rewrites the pipeline behind notifications going out today. Both get the local rig exercised before merge, not only tests.

5a can land before 4 if that sequencing is more convenient — the seeded templates and renderer have no dependency on the engine, only on Phase 1's channel interface. The order above simply keeps the engine provable before anything renders through it.

Phase 12 is the one with a deadline rather than a dependency. runicgateway.com's checks read the source repos' main, so the site stays green through the whole edge period and breaks at the cutover. Its work therefore has to be finished before Phase 13 and merged inside the same window — the failure mode of leaving it until after is a public site making false claims about the product on the day it ships.

---

Part 7 — Open questions and forward-compat notes

7.1 Questions for the org lead — all nine answered

1. ✅ ANSWERED — may unverified addresses receive engagement mail? "Emails need to be unique and verification blocking sending is an admin setting." Combined with the opt-in answer, this settles three things at once and creates Phase 1b:

   • Opt-in only, following standard marketing-email practice — explicit consent, working unsubscribe, suppression. This matches the team_notification_prefs pattern already in use.
   • users.email becomes UNIQUE. Not a schema tweak — see §0.6 for the three code paths it breaks and the boot it can stop, and Phase 1b for the work. Duplicates are resolved oldest-wins: the earliest account keeps the address, later ones are nulled and listed in an admin report.
   • The verification gate is an admin setting, default on for fresh installs, off for upgrades, so a running deployment does not silently stop mailing its opted-in users at cutover.
   • The collision error stays generic and anti-enumeration, rate-limited but not bot-scored.

   Consequence for ordering: Phase 9 no longer blocks Phase 11 — the verification mechanism moves forward into 1b, and Phase 9 keeps only bounces and suppression.

   The narrower half is settled (2026-08-31, at the start of Phase 9): an unverified address is excluded at ENQUEUE, and only from the email channel. With the gate on, emailChannel.eligible drops the user before an outbox row is written, so nothing is queued only to be thrown away and the admin reach preview can report the exclusion. It is email-only because a rule spanning channels must still put an item in that person's in-app inbox. Transactional mail — resets, invites, verification itself — is unaffected either way.

2. ✅ ANSWERED — multi-instance. Neither of the two the question offered, and the third is better than both: the outbox sweep claims each row with a compare-and-set — UPDATE … SET status='sending' WHERE id=? AND status='scheduled' — and the instance the server reports affectedRows = 1 to owns it. §4.2a's status ENUM already carried a sending state that nothing else needed, so this is what the schema was shaped for; it needs no open transaction (which nothing else in this codebase's workers does) and no MariaDB version floor. It makes the outbox safe for two app instances and does not, on its own, make the deployment multi-instance — the four existing workers are still written for one. Built in Phase 4a.

3. ✅ ANSWERED — rules as data vs. rules as code. Data, as recommended: rules are operator-editable rows, enabled defaults to 0, and every rule carries a hard per-rule hourly send ceiling. The ceiling is not a nicety — it is the thing that keeps a misconfigured rule from becoming a mail storm, and it is what makes "data" safe enough to choose over "code". Phase 4 builds both.

4. ✅ ANSWERED — the engagement admin surface gets its own top-level nav group, "Engagement", beside Content / Moderation / System. Four screens is too much to bury: Settings is already one long page of sections, and a send log is a paged table rather than a settings section. Rules lands with Phase 4b; Triggers, Templates and the send log join it in Phase 5. Email Delivery stays a section of Settings for now — moving it is not part of either phase.

5. ✅ ANSWERED — which SMTP posture is the documented default? Document all three; lead with a relay (Mailgun/SES/Postmark); name Gmail-with-an-app-password (smtp.gmail.com:587) explicitly as the migration path off OAuth2 for the existing deployment (§1.2a). Phase 1 owes all three in runicgateway.com's notifications-and-email.mdx as well as BACKEND_DESIGN.md §7.

6. ✅ ANSWERED — time-based triggers (G25), design now, build when? As recommended: the declaration lands in Phase 2 so kind: 'scheduled' is in the contract, the manifest and every stored declaration from day one; the evaluator is built after Phase 9. Registration accepts scheduled today and ctx.events.emit refuses to fire one — an evaluator's trigger is not a caller's — so kind means something from the moment it is declarable rather than from the moment it is honoured. The lifecycle uses in §8.5 are the highest-value non-game triggers on the list and the first thing anyone will ask for after the IDOC mail works.

   The evaluator now has an owner, decided 2026-09-01 (EVENTS.md §N3). The Event System runner becomes the kind: 'scheduled' evaluator rather than a ninth poller being written for it — the runner already materialises due occurrences on a tick, and a second timer doing the same shape of work is how a codebase acquires two schedulers that disagree. It is built in that workstream's P2. Nothing in this phase's contract changes: a scheduled declaration means today exactly what it meant on 2026-08-29, and ctx.events.emit still refuses to fire one.

7. ✅ ANSWERED — manual/operator-authored sends. "There is no campaign in the normal sense of email marketing. But admins can create all sorts of trigger conditions", and separately: "lists can be built if they are powered by game data — say team X members or governors or whatever — thru the uo module; same surface will be exposed to all modules."

   So: no campaigns surface, no operator-authored send screen, no free-form list building. An admin's expressive power lives in trigger conditions and rules. kind: 'scheduled' therefore stays in the Phase 2 contract as an admin-definable condition, not as a campaign.

   Lists do exist, module-declared. A module registers named audiences over its own data on a surface core exposes to every module, and an operator may compose them with and/or/not into a saved segment. Composition must narrow, never widen — the segment takes the tightest ceiling it contains and is still checked against the trigger's G24 ceiling. §5.1a is the design; Phase 2 owns the surface, Phase 4 the composition UI, Phase 11 module-uo's first real audiences.

8. Android CI on edge (§6.0a). ANSWERED 2026-08-31 (org lead), at the start of Phase 8: fix it, as the phase's first commit. pr-checks.yml triggered only on PRs into main, so Phase 8 would have landed with zero CI and Phase 13 would have been its first real build — as happened to all nine M12 phase PRs. pull_request.branches is now [main, edge]. sonarqube.yml was deliberately left alone: it is a push-on-main analysis rather than a PR gate, so no phase PR was ever expected to run it.

9. ✅ ANSWERED (2026-08-31, at the start of Phase 11) — core's own news.post emitter, and the three other things a publish already fires. The three sub-questions below are all settled: the emit REPLACES pushDispatch.publish, and core seeds a news.post rule DISABLED — the Phase 6 Team precedent, applied unchanged. It gates on enqueueIfNeeded's job id, the existing transition signal, re-read nowhere. Phase 11 owns it, in the 11a half.

   State the consequence plainly, because it is the cost of the answer and it is deliberate: news push stops on upgrade. A deployment that ships this and does nothing else tickles nobody on the next publish, until an operator opens Admin → Engagement → Rules and switches the seeded rule on. The alternative — keeping the raw tickle beside the emit for one release — was considered and refused for the same reason Phase 6 refused seeding enabled: an exception carved for the one pipeline that predates the engine is an exception that has to be re-argued every time somebody reads the invariant, and "the tickle stays for one release" is an exception with a deadline nobody owns. The mitigations are the ones Phase 6 already built and they are obligations of Phase 11, not nice-to-haves: EngagementRules.jsx's banner must name news alongside Teams, and Phase 13's release note must name it as an upgrade step.

   The original question and its analysis follow, because the table below is still the map of what must not be disturbed.

   config/coreTriggers.js declares core's five triggers and says in as many words that nothing here emits yet; Phase 6 migrated only the four team.* ones onto the engine. So news.post is a declared payload contract with no caller, and on a real deployment the only in-app or email items a rule can produce today come from Teams. Phase 7 found this and deliberately did not wire it, on the grounds that a channel's own phase is not the place to give another phase's trigger an emitter.

   The call itself is one line. The care is entirely in what it must not disturb. admin.controller.js's announceIfNewlyPublished already fans one publish four ways, and they are different in kind — three of them are not the engagement engine's business:

   What fires on a publish	Whose	What kind of thing it is	The engine's?
   announceJobs.enqueueIfNeeded → announce_job_legs	core, with legs registered by modules — module-uo owns towncrier	a one-shot delivery to a channel of the deployment, with retry and classification	No
   registries.dispatchPostHook('onSaved')	modules, via registerPostHook (API 1.1.0)	idempotent state mirroring — it also runs on delete, and refreshes silently on an edit	No
   pushDispatch.publish('news.post', { ref })	core	a per-person notification, to whoever subscribed	Yes — this is the one that should become an emit
   (missing) engagementEmit.emit('core', 'news.post', …)	core	rules → email / in-app / push	Yes

   registries.js already states the first two apart and why they were not folded together ("a leg is a one-shot DELIVERY with retry and classification; a post hook maintains idempotent STATE, has to run on delete as well as save, and refreshes silently on an edit"). Adding the engine makes a third distinction of the same kind, not a replacement for either. A module's town-crier leg and a module's news gump must keep firing exactly as they do; what changes is only that the raw tickle stops being the one person-facing sink and becomes one channel of a rule.

   What a module gets out of this, stated so nobody widens it by accident. A module already has two doors onto a news publish — the announce leg and the post hook — and it keeps both. What it does not get is the ability to fire news.post itself: the id's owner is core, ctx.events.emit binds the owner at the call and never reads it from the arguments, and §7.2's one namespace means an id has exactly one owner across both facets. A module that wants a person-facing notification of its own declares its own trigger through registerEventTriggers. That is the whole of "modules can use it".

   Three things to settle before anyone writes the line — all three settled above:

   • Continuity, and it is the same shape as G22 and Phase 6's decision 3. Today publishing news tickles every news.post subscriber directly. If the emit replaces that call, push stops the moment this lands and stays stopped until an operator enables a rule — silently, because enabled defaults to 0. Either core seeds a news.post rule (and then: enabled, against the standing default, or disabled with a banner as the Team rules got?), or the raw tickle stays beside the emit for one release and is removed once a rule is known to exist.
   • The transition signal must be reused, not re-derived. enqueueIfNeeded returning a truthy job id is the single "newly published news" test, and the push call already piggybacks on it deliberately so an edit or a re-publish does not re-fire. The emit must gate on the same value; a second reading of the transition is a second chance to disagree with the first.
   • Which phase owns it. Recommendation: Phase 11, which already ships "the first real rule" and is where a declared trigger first gets a caller. It is core work rather than module-uo's, so that phase's title understates it — say so there rather than inventing a phase for one call site.

7.2 One namespace, or two?

notification_channel_prefs.stream_id above holds either a push stream id or a trigger id. Streams and triggers are close enough to collide conceptually — idoc.warning (a stream) and uo.house.idoc_warning (a trigger) would describe the same game moment. Two options:

• One namespace: a trigger is a stream with a payload contract; the seven grandfathered ids stay as contract-free triggers. Cleanest long-term, but touches the shipped app's catalog.
• Two namespaces: streams stay exactly as they are (push only), triggers are new and separate. Zero risk now, permanent duplication later.

Recommendation was two namespaces through Phase 8, on the grounds that the shipped Android client reads the stream catalog.

✅ ANSWERED 2026-08-29 by the org lead: ONE namespace. A trigger is a payload contract attached to an id that may also carry a subscription toggle; news.post names one event whichever question is being asked of it. They stay two REGISTRATIONS with two shapes — a stream entry is a subscription toggle and says nothing about payload — but an id has exactly one owner across both facets, and that is checked in both directions.

The risk the recommendation was hedging against does not materialise, and that is worth recording because it is the part that looked expensive: the push catalog is untouched. allStreams() still serves the stream facet only, so the shipped app sees exactly the seven-plus-five ids it saw before, and a trigger-only id simply has no push toggle. What one namespace actually costs is the ownership check; what it buys is notification_channel_prefs.stream_id staying single-keyed, where two namespaces would have forced a kind discriminator into its primary key and left news.post naming two things forever. See Phase 2's as-built for the two knock-on effects (a relaxed id grammar and a shared legacy allowlist) that only appeared once it was implemented.

7.3 Forward-compat: the note the brief asked for, corrected

Event-name collision handling is already implemented (§0.4), so the brief's §6 concern is closed. The real forward-compat note is different, and belongs in MODULE_API.md:

A trigger id is namespaced by its owner and collision-checked at registration, exactly as a notification stream is. What is not yet expressed is a rule or template referring to a trigger whose module has been uninstalled. engagement_rules.trigger_id is a plain VARCHAR, deliberately, so a module can be removed and reinstalled without the operator's rules being destroyed — the same decision announce_job_legs took for a leg whose module is gone ("Leave it alone: failing it would make the job roll up terminal on the strength of a leg that no longer exists, and reinstalling the module should resume it"). A rule whose trigger is unregistered must therefore show as dormant in the admin UI, never as an error and never auto-deleted.

7.4 Documentation obligations — the whole surface

§6.0b assigns each of these to the phase that causes it; this is the inventory it draws from. Nothing here is "documentation to do at the end" — a phase is not done until its rows have landed.

• docs/website/ENGAGEMENT.md — this document, as the design of record.
• docs/website/BACKEND_DESIGN.md — §7 (Email) rewritten, not amended: it currently documents Gmail OAuth2 as the mechanism, and every mention of "Connect Gmail", the borrowed google client and the mail.google.com scope goes with it (§1.2a). The table inventory gains eight tables; the route tables gain the engagement and channel-preference surfaces and lose the two /admin/email/connect/* routes.
• Operator-facing, for the Gmail removal — a release note naming the required action, and SMTP setup guidance wherever .env.example / website/README.md currently point an operator at the Connect Gmail flow. This is the one documentation obligation with a live deployment depending on it.
• docs/website/MODULE_API.md — §1.1 (1.7.0 + the stale-edge correction), §2.3 (ctx.events, ctx.inbox), §2.4 (registerEventTriggers), and §7.3's dormant-rule note.
• docs/website/TEAMS.md — §6.3/§6.4 rewritten once Phase 6 migrates the Team pipeline.
• docs/link/INTEGRATION.md + docs/link/PLAN.md — Phase 10's wire fields.
• docs/android/PLAN.md — §11 gains the in-app inbox and the per-channel preferences.
• docs/modules/uo/API.md + README.md — Phase 11's triggers.
• integration-kit/ — ci/core-ref.json moved to the new pin; chapter 2 gains a section on registering a trigger, since the kit currently teaches none of the registries. The kit teaches and never re-specifies, so it links to MODULE_API.md rather than restating the contract.
• runicgateway.com — the largest single obligation and the only one whose checks fetch their facts rather than being told them, so it fails on its own. Full detail in Phase 12; in summary: src/data/platform.json (protocol 4→5, moduleApi 1.6.0→1.7.0, the bundle triple) · administration/notifications-and-email.mdx (whose "There is no SMTP option" aside becomes false) · configuration.mdx, troubleshooting.mdx, architecture/system-architecture.mdx, architecture/protocol-versions.mdx · src/data/capabilities.mjs (the Notifications line claims a web channel that does not exist until Phase 7) · new admin pages for rules, templates and per-channel preferences · PLAY_DATA_SAFETY.md + /privacy, both generated from one inventory that an engagement mailer materially changes.
• .profile/README.md — only if this lands as a headline capability. It did: the org lead called it one, and the org landing page names the engagement system in the Phase 13 window.

---

Part 8 — What the system could be used for

Written as a catalogue, not a commitment — to check that the design in Parts 3–5 is general enough, and to show what an operator gets for the phases they pay for. §8.6 is no longer that. On 2026-08-31 the org lead scheduled every ✅ row of §8.6 into Phase 11, so for the module-uo section the burden of proof has inverted: a row that does not ship needs a reason recorded in the phase. The rest of Part 8 — §8.1–8.5 and §8.7 — remains unscheduled and stays a catalogue.

Read the availability column as: ✅ the data exists today and a rule could be written the day the engine lands · ⚠ the data exists but needs a mapper or a resolver · ❌ needs new plumbing (named in the row).

8.1 Core — account, access and security

Use	Trigger source	Data	Channels	Timing
Password reset	password_resets	✅ (a sender exists today)	email	instant
Account invite	user_invites	✅	email	instant
Email verification	Phase 9	❌ no verification flow yet	email	instant
New sign-in from an unrecognised device	trusted_devices	⚠ the table exists; nothing notifies	email, in-app	instant
A trusted device was added / all devices revoked	same	⚠	email, in-app	instant
2FA enabled / disabled, recovery codes regenerated	users.totp_enabled, recovery_codes	⚠	email, in-app	instant
Password or email changed	/auth/me account routes	⚠	email	instant
Your account was locked by the bot-score / IP-ban layer	middleware/botScore	⚠	email	instant, hard cooldown
SSO identity linked or unlinked	user_identities	⚠	email, in-app	instant
Your session was revoked everywhere	revoked_sessions	⚠	in-app	instant

The security family is the strongest argument for the in-app channel: every one of these is something a user should be able to review a history of, not merely be pinged about once.

8.2 Core — content and community

Use	Trigger source	Data	Channels	Timing
New news post / Five-on-Friday	posts + news.post stream	✅	email, push, in-app	instant or digest
Team forum reply / new thread	team_forum_posts	✅ (shipping today)	email, push, in-app	instant or digest
Team announcement from a leader	team.announcement stream	✅	email, push, in-app	instant
Joined / removed from a Team	team.member.* streams	✅	in-app, email	instant
Team leadership changed	team.leadership.changed	✅	in-app	instant
Someone replied to your thread	team_forum_posts.parent	⚠ author resolution exists; no per-author rule	email, in-app	instant
You were mentioned in a post	forum body	❌ no mention parsing	in-app, push	instant
A wiki page you edited changed	wiki_revisions	⚠ revisions exist; no watch list	email	digest
A wiki page you watch changed	—	❌ needs a watch table	email	digest
Weekly "what happened" digest	posts + forum + activity	⚠ digest machinery lands in Phase 6	email	weekly
Your uploaded image was removed by the sweep	team_forum_uploads	⚠	in-app	instant

8.3 Core — moderation, appeals and reports

Use	Trigger source	Data	Channels	Timing
You received a warning	warnings	⚠	email, in-app	instant
You were muted / banned, and why	mod_actions	⚠	email, in-app	instant
Your appeal was received / decided	appeals	⚠	email, in-app	instant
Your content was reported (to staff, not the author)	content_reports	⚠	in-app, email	instant, staff audience
A moderation request needs a second pair of eyes	team_moderation_requests	⚠	in-app, email	instant, staff
Report queue is over N items	content_reports count	❌ needs a threshold evaluator	email, in-app	daily digest

Note the audience direction: several of these go to staff, not to the subject. engagement_rules.audience has to support a role-derived audience ('staff', 'admins') as well as 'owner' and 'subscribers' — worth confirming in Phase 4 rather than discovering in Phase 11.

8.4 Core — operator and staff operations

Use	Trigger source	Data	Channels	Timing
Email delivery is failing	email_config.status	⚠ — and note the bootstrap problem: this one cannot be emailed	in-app, Discord	instant
A module failed to load / is in startup_failed	modules/loader.js	⚠	in-app, email	instant
Sidecar unreachable / protocol mismatch	uoLinkClient ok:false, 409	⚠	in-app, email, Discord	instant, cooldown
Announce leg exhausted its retries	announce_job_legs.status='failed'	✅	in-app, email	instant
A new admin was created, or a role was elevated	activity_log	⚠	email to admins	instant
Weekly operator report — signups, active users, moderation volume, send volume	activity_log, engagement_sends	⚠	email	weekly

engagement_sends making the send volume reportable is a small thing that closes a real gap: today "how much mail did we send" is unanswerable (G15).

8.5 Lifecycle and re-engagement — the "engagement drivers" the brief names

Use	Trigger source	Data	Channels	Timing
Welcome / first steps after registration	users.created_at	⚠ needs a time-based evaluator	email	delayed (e.g. +1 h)
Finish setting up — no linked game account after N days	shard_links absence	⚠ module-supplied predicate	email, in-app	delayed
We miss you — no login in N days	users.last_login_at	⚠ needs a scheduled sweep	email	monthly, hard cap
Come back for X — a scheduled event is starting	event.run.started, emitted by the event runner	✅ built — EVENTS_PLAN.md Phase 10. It is a trigger AND a stream, which is what gives it push: the push channel is stream-keyed, so the six other event. triggers are email and in-app only	email, push, in-app	on the run
Your invite is about to expire	user_invites.expires_at	⚠	email	delayed
Account dormant, scheduled for cleanup	policy	❌ no dormancy policy exists	email	scheduled, staged

These need a trigger kind the design does not yet have: a time-based trigger, not an event-based one. Everything in Parts 3–5 is "a thing happened → maybe send". "Nothing happened for 30 days → send" is a periodic evaluator over a query. That is a real addition — a registerScheduledTrigger({ id, cron, evaluate }) whose evaluate returns candidate (user, subject) pairs, with the cooldown table doing exactly the job it already does. It should be designed in Phase 2 even if it is built later, because retrofitting a second trigger kind into the rule model afterwards is the expensive version.

The same mechanism gives the operator a manual send: "announce this to everyone who opted into news", which is the one legitimately campaign-shaped use and the one most likely to be asked for first.

8.6 Module events — module-uo, grounded in what the shard actually emits

Every kind below is real (docs/link/INTEGRATION.md). The trigger id is what module-uo registers; core stays ignorant of every word in it. Every ✅ row here is Phase 11 scope except the four struck through or marked carved out, each of which carries its reason.

Three rows were corrected on 2026-08-31, when the set was scheduled and each claim was checked against the emitters rather than against this table. Two of the corrections are what widened Phase 10 from one wire enrichment to three; the third is a caveat that has to reach the operator, not a defect. Three more were carved out or narrowed on the same day, at the start of Phase 11, when the same check was run against the website rather than against the wire — see "Three carve-outs" below.

Trigger	Wire source	Data	Why anyone cares
uo.house.idoc_warning	house.decay → Greatly	⚠ mapping only (the enrichment is Phase 10)	The flagship. Your house is decaying; log in or lose it and its contents
uo.house.collapsed	house.decay → Collapsed, house.remove	✅	The bad news, so it is not a surprise
uo.vendor.sale	vendor.sale	✅ (ownerAcct → linked user) — but patch-tier only, see below	Your player vendor sold something, for how much
uo.vendor.expiring	vendor.listing + v5 fee fields	⚠ → ✅ after Phase 10; vendor.listing carries no ownerAcct and no fee state today	Your vendor is about to be dismissed for unpaid fees
uo.account.login_failed	v5 account.login.result	⚠ → ✅ after Phase 10; the existing account.login.attempt is pre-decision, see below	Someone tried to log into your game account, and failed, and from where
uo.character.death / murdered	player.death, player.murdered	✅	Opt-in; a killfeed some players want and most do not
uo.skill.capped	skill.gain where base == cap	✅	You hit the cap in a skill — a genuine milestone
uo.quest.complete	quest.complete	✅	Milestone / achievement mail
uo.guild.joined	guild.join	carved out — Phase 11	Core's team.member.joined already fires for this; see below
uo.guild.left	guild.leave, guild.roster	✅	A member left. Core has no team.member.left, so this one has no overlap
uo.guild.disbanded	guild.remove	✅	Consequential and easy to miss
uo.champ.started	champ.update → active	✅ (transition tracker exists)	A champion spawn is up — the classic "come online now" driver
uo.champ.boss_up	champ.update bossUp	✅	Higher-value version of the same
uo.governor.elected	city.update	✅ (transition tracker exists)	Civic events; naturally digestible
uo.election.opened	city.update electionPhase	✅	"Voting is open in Britain" — with autoPickAt as a real deadline
uo.server.up / down	server.hello, server.shutdown, server.crashed	✅	Downtime notice; needs a hard cooldown, a flapping shard is a mail loop
uo.page.new	page.new	✅	A player opened a help page → staff audience
uo.cheat.detected	cheat.fastwalk	✅	Staff audience only — this kind is not on the public allowlist
uo.audit.staff_action	audit.set, audit.command, admin.audit	✅	Admin-audience digest of staff activity
uo.link.requested	link.request	carved out — Phase 11	No addressable recipient, and a TTL no channel can beat; see below
uo.account.unlinked	account.unlinked	✅	Someone severed the tie from in-game
uo.market.item_listed	vendor.listing	✅ (protocol v3)	Saved-search hit: "a Vanquishing kryss appeared under 50k"
uo.points.rank_changed	points.board	⚠ subscribers only (protocol v3)	The board's top N changed. The personal "you were pushed out" half is carved out — see below
uo.economy.milestone	economy.supply	✅	Operator-facing; economy health thresholds
uo.world.saved	world.save.after	✅	Operator-facing only; world-size trend

Three rows as originally written were wrong, and finding out cost one sweep of the emitters:

• uo.vendor.sale is real and does carry ownerAcct — but it lives in servuo-plugins/patches/, the opt-in patch tier, verified only against ServUO 57.4. It is a PlayerVendorSale EventSink the patches add to core plus a subscriber that reads it, which is why it is absent from overlay/. A shard that declined the tier, or runs another ServUO version, emits this kind never — so the rule is silently dormant there rather than broken. Phase 10 deliberately does not try to move it into the overlay; the obligation is that the seeded rule and the operator docs say which tier it needs.
• uo.vendor.expiring had no data at all, not merely no mapper. vendor.listing carries ownerSerial and ownerName — no ownerAcct, so it cannot even be addressed to a website user — and nothing anywhere on the wire carries a vendor's held gold or daily charge. Phase 10 adds all four.
• uo.account.login_attempt could not have been built as described. EventSink.AccountLogin is a pre-decision veto hook; the emitter's own comment says "Fires before the auth decision, so this is an attempt, not a result". A rule on it would have mailed "someone tried to log into your account" every time the player logged in successfully — the exact inversion that makes people distrust security mail. Phase 10 adds a post-decision account.login.result, and the trigger is renamed uo.account.login_failed so its id cannot be misread again.

Three others are worth calling out as design pressure on Parts 3–5:

• uo.market.item_listed is a saved search, not a plain trigger. The audience is "users whose stored query matches this listing", which audience: 'computed' covers but a per-user query store does not exist. Scoping note only — it is the most-requested feature of every UO shard site and would land as its own workstream on top of this one.
• uo.server.up/down is the cooldown table's real stress test. A flapping shard emits both kinds repeatedly; without engagement_cooldowns keyed per rule this is a mail loop, which is exactly why the brief is right that cooldowns must exist before the first trigger ships.
• uo.cheat.detected and uo.audit.* must never be publicly subscribable. shardStreams.js already enforces this for push with a public-allowlist filter (PUBLIC_KINDS) and the comment calls it defence in depth. The engagement engine needs the equivalent: a trigger declares an audience it is permitted to have, and a rule cannot widen it. Without that, the module system's security boundary has a second door. This belongs in Phase 2's trigger declaration, not Phase 4.

Three carve-outs and one narrowing, settled by the org lead 2026-08-31 at the start of Phase 11. Phase 11 inverted the burden of proof — a ✅ row that does not ship needs a reason recorded — so here they are. All three were found by checking each row against what the website can address, which is a different question from whether the wire carries the event. In every case the event keeps being ingested and nothing else changes.

• uo.guild.joined — duplicates core's team.member.joined. A UO guild is a Team and module-uo is this deployment's Team provider, so teamSync.notifyRoster already emits team.member.joined and team.leadership.changed on every roster reconcile, and core already seeds (disabled) rules for both. Shipping a UO trigger for the same fact means an operator who enables the obvious two rules gets two mails for one join and has to work out why. uo.guild.left and uo.guild.disbanded still ship — core has no team.member.left and no disband event at all, so they are the half of the family with no overlap. The trade given up is latency: guild.join is real-time and the Team sweep is ~15 minutes. That is the right thing to give up, because a duplicate mail is a defect an operator discovers in production and fifteen minutes is not.
• uo.link.requested — nobody to address, and a deadline no channel can meet. By construction the game account is not yet linked, which is the entire point of the event, so an owner audience resolves to nobody: shard_account_links has no row for it, and there is no other tie between that account and a website user. Even if there were, link.request carries ttlSec — a default of five minutes — and every channel this system has is slower than that in the worst case and allowed to be. The player is already looking at the code on their screen when the event fires.
• uo.points.rank_changed — ships subscribers only; the personal half is carved out. points.board's top[] entries are {rank, serial, name, points} — a mobile serial, and shard_account_links is keyed by game account. No general serial→account map exists on the website: shard_online has one only for characters logged in right now, and shard_guild_members only for guilded ones. So "you were pushed out of the top ten" would be addressable for some players and silently not for others, which is worse than not offering it — a leaderboard mail that reaches half the board reads as favouritism. The board-changed feed at subscribers needs no owner and ships. Making the personal half real means a serial→account map, which nothing else in the tree needs, so it waits for something that does.

8.7 Module events — the game-agnostic shape

What a different game's module would register, to prove nothing above is UO-specific:

Pattern	UO instance	A survival/Rust-like instance	An MMO instance
Owned asset is at risk	house decaying	base decaying, upkeep expiring	plot/housing lease lapsing
Owned asset changed hands	house demolished	base raided/destroyed	item traded
Passive income event	player vendor sold	shop/market sale	auction house sold
Identity/security event	game-account login attempt	server-account login	account login
Time-boxed world event opening	champion spawn up	raid window / airdrop	world boss / dungeon rotation
Civic / social structure change	governor elected	clan leadership change	guild leadership change
Personal milestone	skill capped, quest done	level/blueprint unlocked	achievement earned
Server availability	shard up/down	server wipe/restart	realm maintenance
Staff-facing signal	help page opened, cheat flagged	report filed, anticheat flag	GM ticket

The engine sees none of the left-hand words. It sees a trigger id, a declared variable set, an audience kind and a subject key — which is the test the design has to pass, and the reason §4.3's variable contract is not optional.

8.8 What it is deliberately not for

Worth writing down, because the failure mode of an engagement system is scope creep into a marketing platform — which the brief explicitly rules out and which would change the security posture.

• No list building, no imported contacts, no audiences of non-users. Every recipient is a user row with a preference. The system has no concept of an address that is not attached to an account.
• No open/click tracking, no tracking pixels, no link rewriting. Beyond the privacy position, it would put a per-recipient beacon URL in every mail — a phone-home by construction (§3.2).
• No A/B testing, no drip sequences, no lead scoring, no funnels.
• No sending on behalf of a third party. The transport is the operator's own; there is no multi-tenant sender.
• No raw HTML authoring and no HTML-typed variables (§4.6.2). A module supplies data, never markup.
• Push stays content-free. Whatever else this system does, the tickle invariant survives it: a channel declares carriesContent, and push's is false structurally rather than by convention.