feat(modules): the three de-entanglement registries, with core as the registrant

Phase 2 PR 4 of docs/website/MODULE_SYSTEM.md §2.7. Adds server/src/modules/registries.js
and moves core's own notification streams, announce leg and users-detail routes
behind it, so the three seams §1.8 and §1.9 named are exercised on every boot
before any module depends on them.

Registering is validate-then-commit per registrant: the loader stages what a
module claims and the second pass commits it, so a module that throws halfway
through register() — or fails checkDeclared after it — leaves nothing behind.
That is the registry-side twin of PR 2's second-pass mount rule.

Four decisions, all the recommended option:

- announce legs became a child table. `announce_job_legs` replaces the
  towncrier_*/discord_* column groups, so the leg set is data: core registers
  `discord`, module-uo will register `towncrier`, and a module cannot ALTER a
  core table to add its own. Backfill is guarded on information_schema (a
  SELECT of a dropped column is a parse error, not a runtime one) and the
  columns go with DROP COLUMN IF EXISTS. Verified against the live dev DB:
  three legacy jobs migrated faithfully, three replays, no duplicates.
- `mapEvent` dropped from registerNotificationStreams. §1.8 already inverts the
  push path so a module owns fromShardEvent and calls core's publish() with a
  stream id it resolved; a second mapping mechanism was a leftover. The public
  safety filter, the kinds it reads and the streams it protects now live in one
  file and move together.
- core registers through the same staging area a module uses, via an explicit
  registries.registerCore() in app.js before modules.load().
- core's six /admin/users/:id/shard/* paths now go through the
  `admin.users.detail` slot, and getUser moved back to admin.controller.js.

Found on the way, and the reason two build tools changed:

- scripts/routeManifest.js could not decode a parameterised mount. Its
  unwinder expected `(?:([^\/]+?))`; express 4.22 emits `(?:\/([^/]+?))` with
  the separator inside the group. The branch had never run. It threw rather
  than guessing, which is what it is for.
- swagger-autogen cannot follow a route into an extension slot — the slot's
  router is created by declareSlot() and filled later, so there is no literal
  mount for a static parse. Regenerating deleted 407 lines and printed
  `Swagger-autogen: Success`, the spike's exact failure (MODULE_API.md §7.4).
  swagger/slotSpecs.js generates a fragment per filled slot and re-roots it at
  the prefix the router actually hangs at in the live app — read from the
  express stack via routeManifest's own mountPath, so the manifest and the spec
  cannot disagree. swagger/mergeSpec.js is the merge helper core owes for
  module fragments anyway (§6.1a), proved here against core's own slot first.

884 tests pass (856 before). routes.manifest.json is unchanged at 229 routes.
The OpenAPI spec diff is two lines of intent: the retry endpoint's summary, and
its `leg` no longer being a fixed enum.

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

server/src/utils/announceWorker.js

@@ -2,59 +2,35 @@
 //
 // A lightweight, in-process table poller (no Redis/BullMQ in the stack). Every
 // ANNOUNCE_POLL_MS it sweeps announce_jobs for legs that are due — freshly
-// enqueued or past their backoff — and dispatches each one:
-//   • town crier  → uoLinkClient.postTownCrier (sidecar → in-game)
-//   • discord     → botInternalClient.announce (bot → #news channel)
-// Both clients never throw (they return { ok, status, error }); the model turns
-// each result into done / retry / terminal and owns the backoff + rollup. One
-// leg failing never touches the other. Same setInterval + unref + stop() shape
-// as middleware/botScore's sweeper, wired into server.js start/shutdown.
+// enqueued or past their backoff — and dispatches each one through the leg that
+// registered itself for that id (modules/registries.js). Core registers
+// `discord`; module-uo registers `towncrier`; another game's module registers its
+// own, and nothing in this file changes.
+//
+// A leg's client never throws (they return { ok, status, error }) and its
+// classify() turns that into done / retry / terminal, which the model converts to
+// backoff + rollup. One leg failing never touches another. Same setInterval +
+// unref + stop() shape as middleware/botScore's sweeper, wired into server.js
+// start/shutdown.
 
 const announceJobs = require('../model/announceJobs/announceJobs.model')
 const announceJobsDb = require('../model/announceJobs/announceJobs.db')
-const logic = require('../model/announceJobs/announceJobs.logic')
 const posts = require('../model/posts/posts.model')
-const uoLinkClient = require('./uoLinkClient')
-const botInternalClient = require('./botInternalClient')
+const registries = require('../modules/registries')
 const log = require('./logger')('announce-worker')
 
 const POLL_MS = Number(process.env.ANNOUNCE_POLL_MS) || 15_000
-const TOWNCRIER_DURATION_SEC = Number(process.env.TOWNCRIER_DURATION_SEC) || 3600
-
-function baseUrl() {
-  return (process.env.APP_BASE_URL || 'http://localhost:5173').replace(/\/+$/, '')
-}
-
-// ── Leg dispatchers ─────────────────────────────────────────────────────────
-// Return the raw client result ({ ok, status, data, error }); classification is
-// the model/logic's job.
-
-async function dispatchTownCrier(post) {
-  const lines = logic.buildTownCrierText(post, { baseUrl: baseUrl() })
-  // Stable id: re-posting `post-<id>` REPLACES the prior town-crier entry rather
-  // than stacking a duplicate, so a retry after a partial failure is safe.
-  return uoLinkClient.postTownCrier({
-    id: `post-${post.id}`,
-    lines,
-    durationSec: TOWNCRIER_DURATION_SEC,
-  })
-}
-
-async function dispatchDiscord(post) {
-  const base = baseUrl()
-  // Stored image paths are relative ("/uploads/x.png"); Discord embeds need an
-  // absolute URL.
-  const imageUrl = post.image_url ? new URL(post.image_url, base).toString() : null
-  return botInternalClient.announce({
-    title: post.title,
-    excerpt: post.excerpt,
-    url: `${base}/site/news`,
-    imageUrl,
-  })
-}
 
 // Process a single due leg of a job: fetch the post, dispatch, classify, record.
 async function processLeg(job, leg) {
+  const registered = registries.announceLeg(leg)
+  if (!registered) {
+    // A row for a leg nobody registers any more (its module was removed). 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.
+    return
+  }
+
   const post = await posts.getById(job.post_id)
   if (!post) {
     // Post was deleted between enqueue and dispatch (the CASCADE usually reaps
@@ -63,16 +39,9 @@ async function processLeg(job, leg) {
     return
   }
 
-  let result
   let classification
   try {
-    if (leg === 'towncrier') {
-      result = await dispatchTownCrier(post)
-      classification = logic.classifyTownCrier(result)
-    } else {
-      result = await dispatchDiscord(post)
-      classification = logic.classifyDiscord(result)
-    }
+    classification = registered.classify(await registered.dispatch(post))
   } catch (err) {
     // Clients shouldn't throw, but if one does, treat it as a transient failure
     // rather than crashing the tick.
@@ -83,11 +52,10 @@ async function processLeg(job, leg) {
   await announceJobs.recordOutcome(job, leg, classification)
 }
 
-// One sweep: find due jobs and process each due leg. A job may have both legs due
-// (a fresh enqueue) — process the ones that are actually pending. `job` is a
-// snapshot from the SELECT; recordOutcome re-reads for the rollup, so processing
-// the two legs sequentially off the same snapshot is fine (each leg only writes
-// its own columns).
+// One sweep: find due jobs and process each due leg. A job may have several legs
+// due at once (a fresh enqueue). `job` is a snapshot from the SELECT;
+// recordOutcome re-reads for the rollup, so processing the legs sequentially off
+// the same snapshot is fine (each leg only writes its own row).
 async function tick(now = new Date()) {
   let jobs
   try {
@@ -99,15 +67,15 @@ async function tick(now = new Date()) {
   if (!jobs || jobs.length === 0) return
 
   for (const job of jobs) {
-    if (isLegDue(job, 'towncrier', now)) await processLeg(job, 'towncrier')
-    if (isLegDue(job, 'discord', now)) await processLeg(job, 'discord')
+    for (const row of job.legs || []) {
+      if (isLegDue(row, now)) await processLeg(job, row.leg)
+    }
   }
 }
 
-function isLegDue(job, leg, now) {
-  if (job[`${leg}_status`] !== 'pending') return false
-  const next = job[`${leg}_next_attempt_at`]
-  return next == null || new Date(next) <= now
+function isLegDue(row, now) {
+  if (!row || row.status !== 'pending') return false
+  return row.next_attempt_at == null || new Date(row.next_attempt_at) <= now
 }
 
 let timer = null
@@ -118,7 +86,7 @@ function start() {
     tick().catch((err) => log.error('announce tick failed', { message: err.message }))
   }, POLL_MS)
   if (timer.unref) timer.unref() // don't keep the event loop alive (tests, shutdown)
-  log.info('announcement dispatcher started', { pollMs: POLL_MS })
+  log.info('announcement dispatcher started', { pollMs: POLL_MS, legs: registries.announceLegIds() })
   return timer
 }
 
@@ -129,4 +97,4 @@ function stop() {
   }
 }
 
-module.exports = { start, stop, tick, processLeg, dispatchTownCrier, dispatchDiscord }
+module.exports = { start, stop, tick, processLeg, isLegDue }

server/src/utils/discordAnnounce.js

@@ -0,0 +1,45 @@
+// ── The Discord announce leg ───────────────────────────────────────────────
+//
+// CORE content — the Discord bot has no game logic (MODULE_SYSTEM.md §1.10), so
+// this leg stays in core when module-uo leaves with the town crier. It is written
+// in the same shape as a module's leg and registered through the same function
+// (modules/registries.js registerAnnounceLeg), because a registry only core's
+// hardcoded base bypasses is not exercised until a module arrives.
+
+const botInternalClient = require('./botInternalClient')
+const { articleUrl, baseUrl, legError } = require('../model/announceJobs/announceJobs.logic')
+
+// Deliver. Returns the raw client result ({ ok, status, data, error }) — the
+// client never throws, and classification is `classify`'s job.
+async function dispatch(post) {
+  const base = baseUrl()
+  // Stored image paths are relative ("/uploads/x.png"); Discord embeds need an
+  // absolute URL.
+  const imageUrl = post.image_url ? new URL(post.image_url, base).toString() : null
+  return botInternalClient.announce({
+    title: post.title,
+    excerpt: post.excerpt,
+    url: articleUrl(base),
+    imageUrl,
+  })
+}
+
+// The bot's /internal/announce collapses failures (503 = not connected,
+// 400 = no news channel configured) without surfacing Discord's own retry_after,
+// so there is no reliable terminal signal to key on here. Retry every failure on
+// the shared backoff; a genuine config problem simply exhausts its attempts and
+// lands as `failed` in the admin panel, where the per-leg retry button re-runs it
+// after the channel is set.
+function classify(result) {
+  if (result && result.ok) return { outcome: 'done' }
+  return { outcome: 'retry', error: legError(result) }
+}
+
+const leg = {
+  leg: 'discord',
+  label: 'Discord #news',
+  dispatch,
+  classify,
+}
+
+module.exports = { leg, dispatch, classify }

server/src/utils/pushDispatch.js

@@ -1,10 +1,14 @@
 // ── Push-notification fan-out (content-free tickles) ───────────────────────
 //
-// The transport-agnostic publisher that turns an event into opt-in push
-// notifications. Two producers call in:
-//   • utils/shardIngest.js  → fromShardEvent(event) for shard-derived streams
-//     (beside the existing SSE broadcast — same event source, same allowlist).
-//   • the admin create/publish-post path → publish('news.post', …).
+// The transport-agnostic publisher that turns a stream id into opt-in push
+// notifications. It knows nothing about where the stream came from: the admin
+// create/publish-post path calls publish('news.post', …), and utils/shardPush.js
+// resolves a shard event to a stream and an owner and calls the same function.
+//
+// That split is MODULE_SYSTEM.md §1.8's second entanglement, inverted. This file
+// used to own `fromShardEvent()`, which required the shardLinks model and the
+// shard event mapper — core infrastructure reaching into game content. Now the
+// content side calls in, and a module reaches this through `ctx.push.publish`.
 //
 // What actually leaves the server is a CONTENT-FREE tickle — `{ stream, ref }`,
 // no sensitive data — POSTed to each subscribed device's UnifiedPush/ntfy
@@ -18,9 +22,7 @@
 // registration AND every publish: HTTPS only, never a private/loopback host, and
 // (when configured) the origin must be in the shard's ntfy allow-set.
 
-const shardLinks = require('../model/shardLinks/shardLinks.model')
 const pushDevicesModel = require('../model/pushDevices/pushDevices.model')
-const { mapShardEvent } = require('../config/notificationStreams')
 const log = require('./logger')('push-dispatch')
 
 const TIMEOUT_MS = 5000
@@ -106,30 +108,4 @@ async function publish(streamId, { ref, ownerUserId } = {}, deps = {}) {
   await Promise.all(rows.map((r) => postTickle(r.endpoint, bodyStr, deps)))
 }
 
-// Fan a shard event out to push. Resolves personal (owner-keyed) targets to the
-// owning website user via shardLinks (an unlinked account → nobody to notify).
-// Never throws — a dead relay must never affect ingest.
-async function fromShardEvent(event, deps = {}) {
-  const links = deps.shardLinks || shardLinks
-  const targets = mapShardEvent(event, deps.tracker)
-  for (const t of targets) {
-    try {
-      if (t.ownerAccount) {
-        let owner = null
-        try {
-          owner = await links.getByAccount(t.ownerAccount)
-        } catch {
-          owner = null
-        }
-        if (!owner || owner.userId == null) continue
-        await publish(t.streamId, { ref: t.ref, ownerUserId: owner.userId }, deps)
-      } else {
-        await publish(t.streamId, { ref: t.ref }, deps)
-      }
-    } catch (err) {
-      log.warn('push dispatch target failed', { streamId: t.streamId, message: err.message })
-    }
-  }
-}
-
-module.exports = { publish, fromShardEvent, isAllowedEndpoint }
+module.exports = { publish, isAllowedEndpoint }

server/src/utils/shardAnnounce.js

@@ -0,0 +1,77 @@
+// ── The in-game town-crier announce leg ────────────────────────────────────
+//
+// MODULE-UO CONTENT, still living in core. MODULE_SYSTEM.md §1.8's third
+// entangled file: utils/announceWorker.js is core's news dispatcher, but one of
+// its two delivery legs goes to the shard through uoLinkClient.postTownCrier.
+// PR 4 turned the legs into registrations, and this file is what module-uo will
+// register in Phase 3 — it moves whole, with `'core'` becoming `'uo'` and the
+// leg id staying `towncrier` (grandfathered in registries.js: the id is a stored
+// value in announce_job_legs.leg).
+
+const uoLinkClient = require('./uoLinkClient')
+const { deriveExcerpt } = require('./sanitizeHtml')
+const { articleUrl, baseUrl, legError } = require('../model/announceJobs/announceJobs.logic')
+
+const TOWNCRIER_DURATION_SEC = Number(process.env.TOWNCRIER_DURATION_SEC) || 3600
+
+// Sidecar town-crier caps, mirrored from the admin route validation
+// (admin/uoLink.router.js: lines isArray({ max: 8 }), lines.* isLength({ max: 200 })).
+// We pre-truncate to these so a published post never bounces with an error.
+const MAX_LINES = 8
+const MAX_LINE_LEN = 200
+
+// Trim to a hard length, appending an ellipsis only when something was cut.
+function clamp(value, max) {
+  const s = String(value == null ? '' : value)
+    .replace(/\s+/g, ' ')
+    .trim()
+  if (s.length <= max) return s
+  return `${s.slice(0, max - 1).trimEnd()}…`
+}
+
+// Build the town-crier lines: title, a one-line excerpt, then the URL. Each line
+// is clamped to the sidecar's per-line cap and the whole thing to the line-count
+// cap. Falls back to a stripped body excerpt when the post has no excerpt.
+function buildTownCrierText(post, { baseUrl: base } = {}) {
+  const title = clamp(post.title, MAX_LINE_LEN)
+  const excerptSource = post.excerpt || deriveExcerpt(post.body, MAX_LINE_LEN) || ''
+  const lines = [title]
+  const excerpt = clamp(excerptSource, MAX_LINE_LEN)
+  if (excerpt) lines.push(excerpt)
+  const url = clamp(articleUrl(base), MAX_LINE_LEN)
+  if (url) lines.push(url)
+  return lines.filter(Boolean).slice(0, MAX_LINES)
+}
+
+async function dispatch(post) {
+  const lines = buildTownCrierText(post, { baseUrl: baseUrl() })
+  // Stable id: re-posting `post-<id>` REPLACES the prior town-crier entry rather
+  // than stacking a duplicate, so a retry after a partial failure is safe.
+  return uoLinkClient.postTownCrier({
+    id: `post-${post.id}`,
+    lines,
+    durationSec: TOWNCRIER_DURATION_SEC,
+  })
+}
+
+function classify(result) {
+  if (result && result.ok) return { outcome: 'done' }
+  const status = result ? result.status : 0
+  // 400 = over the line/duration caps (a data problem — do NOT retry).
+  // 401 = token mismatch, 409 = protocol mismatch (both config problems).
+  if (status === 400 || status === 401 || status === 409) {
+    return { outcome: 'terminal', error: legError(result) }
+  }
+  // 503 (shard not connected), 504 (shard timeout), 0 (network/timeout / not
+  // configured yet), and any other 5xx are transient — retry.
+  return { outcome: 'retry', error: legError(result) }
+}
+
+const leg = {
+  leg: 'towncrier',
+  label: 'In-game town crier',
+  dispatch,
+  classify,
+}
+
+module.exports = { leg, dispatch, classify, buildTownCrierText, MAX_LINES, MAX_LINE_LEN }

server/src/utils/shardIngest.js

@@ -19,7 +19,7 @@ const shardMarketModel = require('../model/shardMarket/shardMarket.model')
 const uoLinkConfigModel = require('../model/uoLinkConfig/uoLinkConfig.model')
 const settingsModel = require('../model/settings/settings.model')
 const broadcaster = require('./shardBroadcast')
-const pushDispatch = require('./pushDispatch')
+const shardPush = require('./shardPush')
 const defaultLog = require('./logger')('shard-ingest')
 
 // Notable kinds appended to the shard_events log. High-frequency/session kinds
@@ -262,7 +262,7 @@ function resolveDeps(deps) {
     uoLinkConfig: deps.uoLinkConfig || uoLinkConfigModel,
     settings: deps.settings || settingsModel,
     broadcast: deps.broadcast || broadcaster.broadcast,
-    pushDispatch: deps.pushDispatch || pushDispatch.fromShardEvent,
+    pushDispatch: deps.pushDispatch || shardPush.fromShardEvent,
     log: deps.log || defaultLog,
   }
 }

server/src/utils/shardPush.js

@@ -0,0 +1,47 @@
+// ── Shard event → push fan-out ─────────────────────────────────────────────
+//
+// MODULE-UO CONTENT, still living in core — the inverted half of
+// MODULE_SYSTEM.md §1.8's second entangled file. `utils/pushDispatch.js` is core
+// infrastructure, but its `fromShardEvent()` required the shardLinks model and
+// the shard event mapper, which is a core file importing content. PR 4 inverted
+// it: `publish()` stays core, and this — the thing that knows what a shard event
+// is — moved out to call it. Phase 3 moves this file to module-uo whole, where it
+// will reach `publish` through `ctx.push.publish` instead of a require.
+//
+// Owner resolution is the reason this cannot just be a mapper: a personal
+// (owner-keyed) target names a GAME account, and turning that into a website user
+// needs the shardLinks model. An unlinked account is simply nobody to notify.
+
+const shardLinks = require('../model/shardLinks/shardLinks.model')
+const { mapShardEvent } = require('../config/shardStreams')
+const { publish } = require('./pushDispatch')
+const log = require('./logger')('shard-push')
+
+// Fan a shard event out to push. Resolves personal (owner-keyed) targets to the
+// owning website user via shardLinks (an unlinked account → nobody to notify).
+// Never throws — a dead relay must never affect ingest.
+async function fromShardEvent(event, deps = {}) {
+  const links = deps.shardLinks || shardLinks
+  const doPublish = deps.publish || publish
+  const targets = mapShardEvent(event, deps.tracker)
+  for (const t of targets) {
+    try {
+      if (t.ownerAccount) {
+        let owner = null
+        try {
+          owner = await links.getByAccount(t.ownerAccount)
+        } catch {
+          owner = null
+        }
+        if (!owner || owner.userId == null) continue
+        await doPublish(t.streamId, { ref: t.ref, ownerUserId: owner.userId }, deps)
+      } else {
+        await doPublish(t.streamId, { ref: t.ref }, deps)
+      }
+    } catch (err) {
+      log.warn('push dispatch target failed', { streamId: t.streamId, message: err.message })
+    }
+  }
+}
+
+module.exports = { fromShardEvent }