feat(shard): ingest guild rosters and departures (protocol 4)

Protocol 2 gave the guild board a member *count* and nothing else, so the Guilds
page could say a guild had 155 members but never who they were, and
findGuildForActor deliberately answered only for leaders because membership for
rank-and-file was not in the feed at all. Protocol 4 puts it there.

`shard_guild_members` holds one row per member per guild, keyed on
(guild_id, serial). `guild.roster` replaces a guild's rows; `guild.leave` removes
one. A guild.remove now clears the membership too, so a disbanded guild does not
leave orphaned rows behind.

The chunking needs explaining. A roster over the shard's per-frame cap arrives as
several frames carrying seq/more/total. The sidecar reassembles them for its own
GET /guilds board, but the live WebSocket feed and the /history backfill both
carry the individual frames — so this ingest sees them unreassembled.

It copes without buffering, because a table expresses what the sidecar's single
JSON column could not: the frame carrying seq 0 clears the guild first, and every
frame then upserts its own rows. Upsert rather than insert because the /history
backfill replays stored frames on every reconnect, and a redelivery has to be a
no-op rather than a duplicate-key error. The cost is a sub-second window during a
multi-frame update where the table holds part of a roster; buffering to close it
would duplicate the sidecar's reassembly for a projection that is already only as
fresh as a 60s sweep.

On visibility: both kinds are mapped to the existing `guilds` feature. Without
that mapping rule 2 fails an unmapped kind closed to admin-only, which would have
quietly kept rosters off the public page forever. Mapping them is safe because a
roster is the first frame carrying locked fields inside an ARRAY of actors rather
than one nested actor, and the projection walker already recurses into arrays and
matches acct/webId by suffix — so a member's account name is stripped below admin
by exactly the rule that already strips guild.leader.acct. There is a test for
that specifically, because the difference is a public page listing character names
versus one publishing 150 account names.

`acct`/`web_id` are still stored, since that is what lets a linked member be
matched to a site user; they are just never projected below admin.

guild.leave is appended to the event log, as the departure counterpart to
guild.join and for the same reason — it is what a "so-and-so left" feed reads.
guild.roster stays out: it is board state like guild.update, and it is the one fat
frame on the wire, so logging it would put a full membership snapshot into
shard_events on every membership change.

The PUBLIC_KINDS guard test caught the addition, which is what it is for; its
expected set now carries a v4 group alongside the v3 one.

Refs: docs/website/TEAMS.md Part 12 Phase 1

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

server/model/shardState/shardState.db.js

@@ -171,6 +171,37 @@ const removeGuild = (id) => query('DELETE FROM shard_guilds WHERE id = ?', [id])
 const clearGuilds = () => query('DELETE FROM shard_guilds')
 const listGuilds = () => query(`SELECT ${GUILD_COLS} FROM shard_guilds ORDER BY name ASC`)
 
+// ── Guild membership (Protocol 4) ──────────────────────────────────────────
+const MEMBER_COLS = 'guild_id, serial, name, acct, web_id, is_player, t'
+
+// Upsert rather than plain insert: a roster frame can be redelivered (the /history
+// backfill replays stored frames on every reconnect), and a redelivery must be a
+// no-op rather than a duplicate-key error.
+const upsertGuildMembers = (rows) => {
+  if (!rows.length) return Promise.resolve()
+  const values = rows.map(() => '(?, ?, ?, ?, ?, ?, ?)').join(', ')
+  const params = rows.flatMap((r) => [r.guild_id, r.serial, r.name, r.acct, r.web_id, r.is_player, r.t])
+  return query(
+    `INSERT INTO shard_guild_members (${MEMBER_COLS}) VALUES ${values}
+     ON DUPLICATE KEY UPDATE name = VALUES(name), acct = VALUES(acct),
+       web_id = VALUES(web_id), is_player = VALUES(is_player), t = VALUES(t)`,
+    params,
+  )
+}
+
+const clearGuildMembers = (guildId) =>
+  query('DELETE FROM shard_guild_members WHERE guild_id = ?', [guildId])
+
+const removeGuildMember = (guildId, serial) =>
+  query('DELETE FROM shard_guild_members WHERE guild_id = ? AND serial = ?', [guildId, serial])
+
+const clearAllGuildMembers = () => query('DELETE FROM shard_guild_members')
+
+const listGuildMembers = (guildId) =>
+  query(`SELECT ${MEMBER_COLS} FROM shard_guild_members WHERE guild_id = ? ORDER BY name ASC`, [
+    guildId,
+  ])
+
 // The guild an actor LEADS — matched on the current board (leader_serial or the
 // linked leader_acct), so it reflects live state. Guild MEMBERSHIP for non-leaders
 // is not modelled (the board carries only counts + leader), so we don't guess it.
@@ -342,6 +373,11 @@ module.exports = {
   removeGuild,
   clearGuilds,
   listGuilds,
+  upsertGuildMembers,
+  clearGuildMembers,
+  removeGuildMember,
+  clearAllGuildMembers,
+  listGuildMembers,
   findGuildLedByActor,
   listGuildsLedByAccounts,
   upsertGovernor,

server/model/shardState/shardState.model.js

@@ -340,8 +340,80 @@ async function upsertGuild(ev) {
   })
 }
 
-const removeGuild = (id) => (id == null ? Promise.resolve() : db.removeGuild(id))
-const clearGuilds = () => db.clearGuilds()
+const removeGuild = async (id) => {
+  if (id == null) return
+  await db.removeGuild(id)
+  await db.clearGuildMembers(id)
+}
+const clearGuilds = async () => {
+  await db.clearGuilds()
+  await db.clearAllGuildMembers()
+}
+
+// ── Guild membership (Protocol 4) ──────────────────────────────────────────
+// Apply one guild.roster frame.
+//
+// A roster larger than the shard's per-frame cap arrives as several frames
+// carrying seq/more/total. The sidecar reassembles them for its OWN board, but the
+// live WebSocket feed and the /history backfill both carry the individual frames,
+// so this ingest sees them unreassembled and has to cope.
+//
+// It copes without buffering, because a table can express what a single JSON column
+// could not: the frame carrying seq 0 clears the guild first and every frame then
+// upserts its own rows. Rows are keyed on (guild_id, serial), so a redelivered frame
+// — the /history backfill replays stored frames on every reconnect — is idempotent
+// rather than a duplicate-key error.
+//
+// The cost is a brief window during a multi-frame update where the table holds part
+// of a roster. That is acceptable for a projection that is already only as fresh as
+// a 60s sweep, and the frames arrive back-to-back in one burst; buffering to close
+// it would duplicate the sidecar's reassembly for a sub-second inconsistency.
+async function upsertGuildRoster(ev) {
+  if (!ev || ev.id == null) return
+
+  const seq = Number.isFinite(ev.seq) ? ev.seq : 0
+  const members = Array.isArray(ev.members) ? ev.members : []
+
+  // seq 0 begins a roster and supersedes whatever was held for this guild.
+  if (seq === 0) await db.clearGuildMembers(ev.id)
+
+  const rows = members
+    .filter((m) => m && m.serial)
+    .map((m) => ({
+      guild_id: ev.id,
+      serial: m.serial,
+      name: m.name ?? null,
+      acct: m.acct ?? null,
+      web_id: Number.isFinite(m.webId) ? m.webId : null,
+      is_player: m.player ? 1 : 0,
+      t: Number.isFinite(ev.t) ? ev.t : null,
+    }))
+
+  await db.upsertGuildMembers(rows)
+}
+
+// A single departure (guild.leave). Advisory: the shard re-emits the full roster
+// whenever the member set changes, so the table would converge on the next frame
+// even if this were dropped. Applying it makes the change visible immediately
+// instead of at the end of the sweep that produced it.
+async function removeGuildMember(ev) {
+  if (!ev || ev.id == null || !ev.who) return
+  await db.removeGuildMember(ev.id, ev.who)
+}
+
+// The membership roster for one guild, in the wire shape the projection expects
+// (an array of actor objects), so shardVisibility strips acct/webId by the same
+// rule it applies to guild.leader.
+async function listGuildMembers(guildId) {
+  const rows = await db.listGuildMembers(guildId)
+  return rows.map((r) => ({
+    serial: r.serial,
+    name: r.name,
+    ...(r.acct == null ? {} : { acct: r.acct }),
+    ...(r.web_id == null ? {} : { webId: r.web_id }),
+    player: !!r.is_player,
+  }))
+}
 
 function shapeGuild(r) {
   const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload
@@ -620,6 +692,9 @@ module.exports = {
   removeGuild,
   clearGuilds,
   listGuilds,
+  upsertGuildRoster,
+  removeGuildMember,
+  listGuildMembers,
   replaceGuilds,
   findGuildForActor,
   listGuildsLedForAccounts,