feat(shard): ingest world.ruleset and publish it at /site/rules

Protocol 3.0 §5 (docs/link/v3.md). The shard publishes its own ruleset —
expansion, which optional systems are on, skill/stat caps, account and house
limits, champion scroll rules, the save/restart schedule — and the site renders
it, so the rules page cannot drift from how the shard actually plays.

Server
  - shard_ruleset: a singleton table (id = 1) holding the whole frame in
    `payload`, with `rev` and `expansion` hoisted. Nothing is normalized out:
    the frame is a flat description of config read as one page, and splitting it
    into columns would mean a schema change every time the shard grows a block.
  - shardIngest routes world.ruleset to setRuleset and deliberately does NOT
    log it — the shard re-emits the whole ruleset on every sidecar connect, so
    logging would append a duplicate row per reconnect, and server.hello already
    marks each of those.
  - uoLinkSocket backfills GET /ruleset explicitly rather than via snapshot(),
    which asserts an array; this covers the order where the sidecar was already
    up and holding the ruleset when we reconnected.
  - GET /public/shard/ruleset behind requireFeature('ruleset') and projected,
    per §3.6.1's rule that a shard read which doesn't project is a bug. `null`
    means the shard has never published one — a real answer, distinct from a
    published ruleset, and the page says so.

Client
  - routes/public/Rules.jsx at /site/rules, live via world.ruleset (a frame is a
    complete ruleset, not a delta, so the newest one wins outright). Caps are
    rendered from tenths — 7000 is 700.0, and showing the raw number would
    mislead. A systems key this build doesn't know still renders, humanised, so
    a newer plugin can't go invisible against an older client.
  - Nav entry gated on the `ruleset` feature, so it hides rather than 403s.

Verified end to end against the local MariaDB and a sidecar fed by a fake shard:
backfill snapshot, live SSE delivery of a changed ruleset, REST reflecting the
overwrite, an empty /feed (not logged), and the gate — 200 by default, 403 at
audience=staff (and dropped from /features so nav hides it), 404 when disabled.
Page rendered clean at all breakpoints checked, no console errors.

497 server tests pass; routes.manifest.json, routes.guards.json and the OpenAPI
spec regenerated.

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

server/src/model/shardState/shardState.db.js

@@ -259,6 +259,25 @@ async function latestPresence() {
   return rows[0] || null
 }
 
+// ── Shard ruleset (Protocol 3.0 world.ruleset) ─────────────────────────────
+// Singleton, same shape as shard_presence: the shard re-emits the whole frame on
+// every connect, so there is nothing to merge — the latest one wins outright.
+async function setRuleset({ rev, expansion, payload, t }) {
+  await query(
+    `INSERT INTO shard_ruleset (id, rev, expansion, payload, t) VALUES (1, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE rev = VALUES(rev), expansion = VALUES(expansion),
+       payload = VALUES(payload), t = VALUES(t)`,
+    [rev ?? null, expansion ?? null, payload, Number.isFinite(t) ? t : null],
+  )
+}
+
+async function getRuleset() {
+  const rows = await query(
+    'SELECT rev, expansion, payload, t, updated_at FROM shard_ruleset WHERE id = 1',
+  )
+  return rows[0] || null
+}
+
 module.exports = {
   upsertOnline,
   removeOnline,
@@ -290,6 +309,8 @@ module.exports = {
   listGovernorTerms,
   setPresence,
   latestPresence,
+  setRuleset,
+  getRuleset,
   upsertChamp,
   removeChamp,
   clearChamps,

server/src/model/shardState/shardState.model.js

@@ -508,6 +508,35 @@ async function latestPresence() {
   }
 }
 
+// ── Shard ruleset (Protocol 3.0 world.ruleset) ─────────────────────────────
+//
+// The whole frame is stored in `payload` and served back whole. Nothing is
+// normalized out of it: it is a flat description of config read as one page, and
+// splitting it into columns would mean a schema change every time the shard grows
+// a new block. `rev` and `expansion` are hoisted only because they are cheap to
+// index/display, following shard_champs' payload-plus-hoisted-columns pattern.
+async function setRuleset(ev) {
+  if (!ev) return
+  await db.setRuleset({
+    rev: ev.rev ?? null,
+    expansion: ev.expansion ?? null,
+    payload: JSON.stringify(ev),
+    t: ev.t,
+  })
+}
+
+// The stored ruleset, or null when the shard has never published one (an old
+// plugin, or Bridge.RulesetEnabled=false). Null is a real answer here — the page
+// says "not published yet" rather than rendering an empty ruleset as if the shard
+// had no rules — so it is deliberately not smoothed into {}.
+async function getRuleset() {
+  const r = await db.getRuleset()
+  if (!r) return null
+  const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload
+  if (!payload) return null
+  return { ...payload, updatedAt: r.updated_at }
+}
+
 function safeJson(s) {
   try {
     return JSON.parse(s)
@@ -557,4 +586,6 @@ module.exports = {
   replaceGovernors,
   setPresence,
   latestPresence,
+  setRuleset,
+  getRuleset,
 }

server/src/router/v1/public/shard.controller.js

@@ -237,6 +237,31 @@ async function getHouses(req, res) {
   }
 }
 
+// GET /public/shard/ruleset — the shard's published ruleset (Protocol 3.0):
+// expansion, which optional systems are on, skill/stat caps, account and house
+// limits, champion scroll rules, the save/restart schedule. Served from our own
+// store, so it renders while the shard is down; live via world.ruleset on the
+// public SSE stream.
+//
+// `null` means the shard has never published one (an old plugin, or
+// Bridge.RulesetEnabled=false) — a real answer, distinct from a published
+// ruleset, and the page says so rather than rendering an empty one.
+//
+// Projected like every other shard read (§3.6.1's rule: a read path that returns
+// shard data and does not call projectFeature is a bug). The `connect` string is
+// the one configurable field — an operator who published a connect address may
+// still want it behind a login.
+async function getRuleset(req, res) {
+  try {
+    const ruleset = await shardState.getRuleset()
+    if (!ruleset) return res.json(null)
+    return res.json(await visibility.project('ruleset', ruleset, req))
+  } catch (err) {
+    log.error('shard.getRuleset', err)
+    return res.status(500).json({ message: 'Internal Server Error' })
+  }
+}
+
 // GET /public/shard/features — the shard features THIS caller can actually see,
 // so the SPA (and the Android client) can hide nav entries instead of rendering
 // links that 403. Deliberately reports only what the viewer may reach: the list
@@ -270,6 +295,7 @@ module.exports = {
   getGovernorHistory,
   getPresence,
   getHouses,
+  getRuleset,
   getFeatures,
   stream,
 }

server/src/router/v1/public/shard.router.js

@@ -137,6 +137,15 @@ shardRouter.get(
   /* #swagger.responses[200] = { description: 'Houses, ordered by name', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
   shard.getHouses,
 )
+shardRouter.get(
+  '/ruleset',
+  requireFeature('ruleset'),
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'The shard\'s published ruleset (expansion, systems, caps, limits)'
+  // #swagger.description = 'How this shard is actually configured, published by the shard itself as one world.ruleset frame: expansion, which optional systems are on, skill/stat caps, account and house limits, champion scroll rules and the save/restart schedule. Served from our own store, so it renders while the shard is down; live via world.ruleset on /shard/stream. Returns `null` if the shard has never published one (an older plugin, or Bridge.RulesetEnabled=false) — distinct from a published ruleset, and the page renders it differently.'
+  /* #swagger.responses[200] = { description: 'The ruleset, or null if never published', content: { "application/json": { schema: { type: "object", nullable: true, additionalProperties: true } } } } */
+  shard.getRuleset,
+)
 shardRouter.get(
   '/features',
   // #swagger.tags = ['Public · Shard']

server/src/utils/shardIngest.js

@@ -173,6 +173,14 @@ async function applyStateChange(event, deps) {
     case 'house.remove':
       await shardState.removeHouse(event.serial)
       return
+    // ── Protocol 3.0 ─────────────────────────────────────────────────────
+    // The shard re-emits its whole ruleset on every sidecar connect, so this is
+    // an overwrite, not an append — and deliberately NOT in LOGGED_KINDS: it
+    // would put a duplicate row in the event log on every reconnect, and
+    // server.hello already marks each of those.
+    case 'world.ruleset':
+      await shardState.setRuleset(event)
+      return
     case 'account.unlinked':
       // A player ran [unlink in game (or a site-side unlink echoed back) — drop
       // our local link mirror so attribution stops immediately.

server/src/utils/uoLinkClient.js

@@ -128,6 +128,9 @@ const getGuilds = () => call('/guilds')
 const getGovernors = () => call('/governors')
 const getHouses = () => call('/houses')
 const getPresence = () => call('/online') // aggregate population (count + byFacet/byRegion)
+// Protocol 3.0: the shard's published ruleset. Object-shaped, not a board — the
+// sidecar answers `{ ruleset: null }` until the shard has published one.
+const getRuleset = () => call('/ruleset')
 
 // ── Commands ──────────────────────────────────────────────────────────────
 const confirmLink = (code, websiteUserId) =>
@@ -191,6 +194,7 @@ module.exports = {
   getGovernors,
   getHouses,
   getPresence,
+  getRuleset,
   confirmLink,
   linkLookup,
   createAccount,

server/src/utils/uoLinkSocket.js

@@ -88,6 +88,17 @@ async function backfill() {
     await snapshot(() => uoLinkClient.getGovernors(), 'cities', (c) => shardState.replaceGovernors(c), 'snapshotted governor board from /governors')
     await snapshot(() => uoLinkClient.getHouses(), 'houses', ingestEach, 'snapshotted house registry from /houses')
 
+    // ── Protocol 3.0 ─────────────────────────────────────────────────────
+    // The ruleset is object-shaped, not a board, so it can't go through
+    // snapshot() (which asserts an array under `key`). The shard also re-emits
+    // world.ruleset on its own connect — this covers the other order, where the
+    // sidecar was already up and holding the ruleset when WE reconnected.
+    const ruleset = await uoLinkClient.getRuleset()
+    if (ruleset.ok && ruleset.data && ruleset.data.ruleset) {
+      await shardState.setRuleset(ruleset.data.ruleset)
+      log.info('snapshotted shard ruleset from /ruleset', { rev: ruleset.data.ruleset.rev })
+    }
+
     const presence = await uoLinkClient.getPresence()
     if (presence.ok && presence.data && typeof presence.data.count === 'number') {
       await shardState.setPresence(presence.data)