feat(shard): ingest Protocol 2.0 boards — guilds, governors, presence, houses

Phase 1 of the Protocol 2.0/2.1 integration: the read/ingest backend for the four
new uo-link boards, following the established champs/pages pattern (ingest → our
MariaDB + snapshot-on-reconnect + public SSE + token-free public endpoint).

- Schema: shard_guilds, shard_governors, shard_governor_terms, shard_presence;
  extend shard_houses with the house.update registry columns (owner_name,
  co_owners, friends, price, decay, in_registry) so the decay-transition and
  registry feeds share one house row without clobbering each other.
- Ingest: route guild.update/remove, city.update, presence.online,
  house.update/remove; log guild.join (real-time joins feed); region.enter is
  broadcast-only. All new public kinds added to the SSE allowlist.
- Governor term history captured from day one: on every observed governor CHANGE
  the open term is closed and a new one opened, idempotent so backfill/duplicate
  city.update never spawn spurious terms. votes stays NULL (the feed carries only
  candidate count, not tallies) — we never fabricate vote numbers.
- Client + backfill: getGuilds/getGovernors/getHouses/getPresence; snapshot each
  board on every WS (re)connect, independently guarded so an empty/failed board
  (e.g. no City Loyalty) never wipes another.
- Public endpoints: /shard/{guilds,governors,governors/:city/history,presence,houses}.
- Tests: ingest routing for all new kinds + governor term-capture idempotency
  (15 new; full suite 179/179). Swagger regenerated.

Refs .plans/protocol2-integration.md (Phase 1).

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

server/test/shardIngest.protocol2.test.js

@@ -0,0 +1,93 @@
+const { test, beforeEach } = require('node:test')
+const assert = require('node:assert/strict')
+
+const shardIngest = require('../src/utils/shardIngest')
+
+// Stub deps recording the Protocol 2.0 board calls the dispatcher makes. Only the
+// methods the tested kinds touch need to be real; the rest are no-op async so
+// ingest() never throws on an unrelated kind.
+function makeDeps() {
+  const calls = {
+    guildUpsert: [], guildRemove: [],
+    governorUpsert: [],
+    presenceSet: [],
+    houseRegistry: [], houseRemove: [],
+    appended: [], broadcast: [],
+  }
+  const noop = async () => {}
+  return {
+    calls,
+    shardEvents: { append: async (row) => { calls.appended.push(row); return true } },
+    shardState: {
+      upsertGuild: async (ev) => { calls.guildUpsert.push(ev) },
+      removeGuild: async (id) => { calls.guildRemove.push(id) },
+      upsertGovernor: async (ev) => { calls.governorUpsert.push(ev) },
+      setPresence: async (ev) => { calls.presenceSet.push(ev) },
+      upsertHouseRegistry: async (ev) => { calls.houseRegistry.push(ev) },
+      removeHouse: async (serial) => { calls.houseRemove.push(serial) },
+      // Present so any stray routing is a harmless no-op.
+      clearOnline: noop, upsertOnline: noop, setOffline: noop, upsertHouse: noop,
+      addEconomySample: noop,
+    },
+    uoLinkConfig: { recordStatus: noop },
+    broadcast: (ev) => { calls.broadcast.push(ev) },
+    log: { warn() {}, info() {}, error() {} },
+  }
+}
+
+beforeEach(() => shardIngest.reset())
+
+test('guild.update routes to upsertGuild and is not logged; guild.remove routes to removeGuild', async () => {
+  const deps = makeDeps()
+  const r = await shardIngest.ingest({ kind: 'guild.update', id: 1042, name: 'TSH', t: 1 }, deps)
+  assert.equal(deps.calls.guildUpsert.length, 1)
+  assert.equal(deps.calls.guildUpsert[0].id, 1042)
+  assert.equal(r.logged, false) // board state, not appended to shard_events
+  await shardIngest.ingest({ kind: 'guild.remove', id: 1042, t: 2 }, deps)
+  assert.deepEqual(deps.calls.guildRemove, [1042])
+})
+
+test('guild.join is appended to the event log (real-time joins feed) and broadcast', async () => {
+  const deps = makeDeps()
+  const r = await shardIngest.ingest(
+    { kind: 'guild.join', id: 1042, who: { name: 'Bran' }, t: 3 }, deps)
+  assert.equal(r.logged, true)
+  assert.equal(deps.calls.appended.length, 1)
+  assert.equal(deps.calls.appended[0].kind, 'guild.join')
+  assert.equal(deps.calls.broadcast.length, 1)
+})
+
+test('city.update routes to upsertGovernor (which also captures term history)', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest(
+    { kind: 'city.update', city: 'Britain', governor: { serial: '0x1', name: 'Darrow' }, t: 4 }, deps)
+  assert.equal(deps.calls.governorUpsert.length, 1)
+  assert.equal(deps.calls.governorUpsert[0].city, 'Britain')
+})
+
+test('presence.online routes to setPresence and is not logged', async () => {
+  const deps = makeDeps()
+  const r = await shardIngest.ingest(
+    { kind: 'presence.online', count: 42, byRegion: { Britain: 18 }, t: 5 }, deps)
+  assert.equal(deps.calls.presenceSet.length, 1)
+  assert.equal(deps.calls.presenceSet[0].count, 42)
+  assert.equal(r.logged, false)
+})
+
+test('house.update routes to upsertHouseRegistry; house.remove routes to removeHouse', async () => {
+  const deps = makeDeps()
+  await shardIngest.ingest({ kind: 'house.update', serial: '0x40001234', name: 'Anvil', t: 6 }, deps)
+  assert.equal(deps.calls.houseRegistry.length, 1)
+  assert.equal(deps.calls.houseRegistry[0].serial, '0x40001234')
+  await shardIngest.ingest({ kind: 'house.remove', serial: '0x40001234', t: 7 }, deps)
+  assert.deepEqual(deps.calls.houseRemove, ['0x40001234'])
+})
+
+test('region.enter is broadcast-only — not logged, no state side effect', async () => {
+  const deps = makeDeps()
+  const r = await shardIngest.ingest(
+    { kind: 'region.enter', from: 'Britain', to: 'Despise', who: { name: 'Darrow' }, t: 8 }, deps)
+  assert.equal(r.logged, false)
+  assert.equal(deps.calls.appended.length, 0)
+  assert.equal(deps.calls.broadcast.length, 1) // still surfaced live
+})

server/test/shardState.governorTerms.test.js

@@ -0,0 +1,77 @@
+const { test, beforeEach } = require('node:test')
+const assert = require('node:assert/strict')
+
+// Term capture lives in the model (shardState.model.upsertGovernor →
+// recordGovernorTransition) and talks to the db module. We exercise the real
+// logic against an in-memory fake by monkeypatching the shared db module object
+// (same instance the model require()s) — no DB, no mocking library.
+const db = require('../src/model/shardState/shardState.db')
+const model = require('../src/model/shardState/shardState.model')
+
+let terms // in-memory shard_governor_terms
+let nextId
+const saved = {}
+
+beforeEach(() => {
+  terms = []
+  nextId = 1
+  for (const k of ['currentGovernorTerm', 'closeGovernorTerm', 'openGovernorTerm', 'upsertGovernor']) {
+    saved[k] = db[k]
+  }
+  db.currentGovernorTerm = async (city) =>
+    terms.find((t) => t.city === city && t.ended_at === null) || null
+  db.closeGovernorTerm = async (id, endedAt) => {
+    const row = terms.find((t) => t.id === id)
+    if (row) row.ended_at = endedAt
+  }
+  db.openGovernorTerm = async ({ city, serial, name, acct, webId, startedAt }) => {
+    terms.push({ id: nextId++, city, governor_serial: serial, governor_name: name,
+      governor_acct: acct, governor_web_id: webId, started_at: startedAt, ended_at: null })
+  }
+  db.upsertGovernor = async () => {} // snapshot write — irrelevant to term capture
+})
+
+function restore() {
+  for (const k of Object.keys(saved)) db[k] = saved[k]
+}
+
+test('a repeated city.update with the same governor does NOT open a second term', async () => {
+  await model.upsertGovernor({ city: 'Britain', governor: { serial: '0x1', name: 'Darrow' }, t: 100 })
+  await model.upsertGovernor({ city: 'Britain', governor: { serial: '0x1', name: 'Darrow' }, t: 200 })
+  const open = terms.filter((t) => t.ended_at === null)
+  assert.equal(terms.length, 1)
+  assert.equal(open.length, 1)
+  assert.equal(open[0].governor_serial, '0x1')
+  assert.equal(open[0].started_at, 100)
+  restore()
+})
+
+test('a governor change closes the old term and opens a new one', async () => {
+  await model.upsertGovernor({ city: 'Britain', governor: { serial: '0x1', name: 'Darrow' }, t: 100 })
+  await model.upsertGovernor({ city: 'Britain', governor: { serial: '0x2', name: 'Mira' }, t: 300 })
+  assert.equal(terms.length, 2)
+  const [first, second] = terms
+  assert.equal(first.governor_serial, '0x1')
+  assert.equal(first.ended_at, 300) // closed at the transition time
+  assert.equal(second.governor_serial, '0x2')
+  assert.equal(second.ended_at, null) // now current
+  assert.equal(second.started_at, 300)
+  restore()
+})
+
+test('a seat going vacant closes the term without opening a new one', async () => {
+  await model.upsertGovernor({ city: 'Britain', governor: { serial: '0x1', name: 'Darrow' }, t: 100 })
+  await model.upsertGovernor({ city: 'Britain', governor: null, t: 400 })
+  assert.equal(terms.length, 1)
+  assert.equal(terms[0].ended_at, 400)
+  restore()
+})
+
+test('terms are tracked independently per city', async () => {
+  await model.upsertGovernor({ city: 'Britain', governor: { serial: '0x1' }, t: 100 })
+  await model.upsertGovernor({ city: 'Minoc', governor: { serial: '0x9' }, t: 120 })
+  await model.upsertGovernor({ city: 'Britain', governor: { serial: '0x1' }, t: 200 }) // dup, no-op
+  assert.equal(terms.length, 2)
+  assert.equal(terms.filter((t) => t.ended_at === null).length, 2)
+  restore()
+})