feat(server): port the UO models, utils and schema fragment

The data half of the extraction: 8 model directories, 13 utils, the shard
stream catalog and the 27-table schema fragment with its purge.

server/core.js is what makes the port a one-line import change per file rather
than a signature change per function. Ported code requires its dependencies at
file scope -- `const { query } = require('../../core')` -- which runs before
register() has been called and before any ctx exists. So every member is a
stable function that resolves ctx when CALLED, and nothing may be destructured
off ctx at init either, because core is free to hand over a getter.

Two helpers are vendored rather than taken from ctx, and the line between them
is the point. utils/excerpt.js is core's deriveExcerpt -- nine lines of pure
text handling. Core's sanitiser next to it was NOT copied: a second copy of a
security control diverges silently the moment either is fixed. announceLinks.js
vendors legError and articleUrl the same way, but baseUrl could not be: core's
reads APP_BASE_URL, and §2.7 forbids a module reading core's environment, so it
comes off ctx.site.baseUrl.

The schema fragment is core's 27 shard_*/uo_link_* statements, verbs CREATE,
ALTER and UPDATE only, every CREATE TABLE guarded. Two of its tables carry a
foreign key INTO users, which is allowed and is why the replay order matters --
core's schema is in place before this runs. The reverse never occurs and must
not: it would make core unable to boot without a module installed.

One real port bug caught by the integration run, not by tests: the atlas art
map resolved `../../../db/data`, which pointed at core's tree when this file
lived there and points outside server/ now. A path that happens to resolve is
exactly what survives a green suite, because the absent-file branch returns {}
and looks like the normal case.

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

server/model/shardAtlas/shardAtlas.db.js

@@ -0,0 +1,392 @@
+const core = require('../../core')
+
+const { query } = core
+
+// Raw SQL for the spawn atlas. Every table here is IMPORT-OWNED: `replaceAtlas`
+// empties and refills all six inside one transaction, and nothing else in the
+// codebase writes to them. There are no foreign keys, consistent with every
+// other shard_* table.
+
+const BATCH = 500
+
+const ATLAS_TABLES = [
+  'shard_spawn_point_types',
+  'shard_spawn_points',
+  'shard_spawn_creatures',
+  'shard_regions',
+  'shard_landmarks',
+  'shard_champion_spawns',
+]
+
+async function insertBatched(conn, sql, rows) {
+  for (let i = 0; i < rows.length; i += BATCH) {
+    await conn.batch(sql, rows.slice(i, i + BATCH))
+  }
+  return rows.length
+}
+
+/**
+ * Replace the entire atlas in one transaction.
+ *
+ * All-or-nothing on purpose: a failed reload must leave the previous atlas
+ * intact rather than a half-loaded world, since a partially-imported atlas is
+ * indistinguishable from a real one to anyone reading it.
+ *
+ * `DELETE`, not `TRUNCATE` — `TRUNCATE` is DDL in MariaDB and implicitly
+ * commits, which would defeat exactly that guarantee. At ~7k rows the cost of
+ * `DELETE` is irrelevant.
+ */
+async function replaceAtlas(atlas, art = {}) {
+  const conn = await core.pool.getConnection()
+  const counts = {}
+  try {
+    await conn.beginTransaction()
+
+    for (const table of ATLAS_TABLES) await conn.query(`DELETE FROM ${table}`)
+
+    counts.creatures = await insertBatched(
+      conn,
+      'INSERT INTO shard_spawn_creatures (slug, name, total, points, facets, art) VALUES (?,?,?,?,?,?)',
+      atlas.creatures.map((c) => [
+        c.slug,
+        c.name,
+        c.total ?? 0,
+        c.points ?? 0,
+        JSON.stringify(c.facets ?? {}),
+        art[c.slug] ?? null,
+      ]),
+    )
+
+    counts.regions = await insertBatched(
+      conn,
+      'INSERT INTO shard_regions (facet, name, type, priority, parent, rects) VALUES (?,?,?,?,?,?)',
+      atlas.regions.map((r) => [
+        r.facet,
+        r.name,
+        r.type || null,
+        r.priority ?? 0,
+        r.parent || null,
+        JSON.stringify(r.rects ?? []),
+      ]),
+    )
+
+    counts.landmarks = await insertBatched(
+      conn,
+      'INSERT INTO shard_landmarks (facet, name, grp, x, y, z) VALUES (?,?,?,?,?,?)',
+      atlas.landmarks.map((l) => [
+        l.facet,
+        l.name,
+        l.group || null,
+        l.x ?? 0,
+        l.y ?? 0,
+        l.z ?? 0,
+      ]),
+    )
+
+    counts.champions = await insertBatched(
+      conn,
+      'INSERT INTO shard_champion_spawns ' +
+        '(slug, name, grp, type, random_type, facet, x, y, z, radius, label) ' +
+        'VALUES (?,?,?,?,?,?,?,?,?,?,?)',
+      atlas.champions.map((c) => [
+        c.slug,
+        c.name,
+        c.group || null,
+        c.type || null,
+        c.randomType ? 1 : 0,
+        c.facet,
+        c.x ?? 0,
+        c.y ?? 0,
+        c.z ?? 0,
+        c.radius ?? 0,
+        c.label || null,
+      ]),
+    )
+
+    // Point ids are assigned explicitly rather than left to AUTO_INCREMENT: the
+    // join rows need to know them and `conn.batch()` reports no usable insertId
+    // for a multi-row insert. Safe because this transaction just emptied the
+    // table and nothing else writes to it.
+    counts.points = await insertBatched(
+      conn,
+      'INSERT INTO shard_spawn_points ' +
+        '(id, facet, name, x, y, width, height, spawn_range, max_count, min_delay, max_delay, ' +
+        'tod_start, tod_end, tod_mode, region, landmark, label) ' +
+        'VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)',
+      atlas.points.map((p, i) => [
+        i + 1,
+        p.facet,
+        p.name,
+        p.x,
+        p.y,
+        p.width ?? 0,
+        p.height ?? 0,
+        p.range ?? 0,
+        p.maxCount ?? 0,
+        p.minDelay ?? 0,
+        p.maxDelay ?? 0,
+        p.todStart ?? 0,
+        p.todEnd ?? 0,
+        p.todMode ?? 0,
+        p.region,
+        p.landmark,
+        p.label || 'Wilderness',
+      ]),
+    )
+
+    counts.pointTypes = await insertBatched(
+      conn,
+      'INSERT INTO shard_spawn_point_types (point_id, slug, max_count) VALUES (?,?,?)',
+      atlas.pointTypes,
+    )
+
+    await conn.query(
+      'INSERT INTO shard_atlas_meta (id, payload) VALUES (1, ?) ' +
+        'ON DUPLICATE KEY UPDATE payload = VALUES(payload), imported_at = CURRENT_TIMESTAMP',
+      [JSON.stringify({ ...atlas.meta, importedCounts: counts })],
+    )
+
+    // A completed import answers whatever was pending.
+    await conn.query('DELETE FROM shard_atlas_pending')
+
+    await conn.commit()
+    return counts
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+async function getMeta() {
+  const rows = await query('SELECT payload, imported_at FROM shard_atlas_meta WHERE id = 1')
+  if (rows.length === 0) return null
+  const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload
+  return { ...payload, importedAt: rows[0].imported_at }
+}
+
+/** Facet names currently loaded, used to detect a facet disappearing. */
+async function getFacets() {
+  const rows = await query('SELECT DISTINCT facet FROM shard_spawn_points ORDER BY facet')
+  return rows.map((row) => row.facet)
+}
+
+// ── Pending review ─────────────────────────────────────────────────────────
+
+async function getPending() {
+  const rows = await query('SELECT payload, status, detected_at FROM shard_atlas_pending WHERE id = 1')
+  if (rows.length === 0) return null
+  const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload
+  return { ...payload, status: rows[0].status, detectedAt: rows[0].detected_at }
+}
+
+async function setPending(payload, status = 'pending') {
+  return query(
+    'INSERT INTO shard_atlas_pending (id, status, payload) VALUES (1, ?, ?) ' +
+      'ON DUPLICATE KEY UPDATE status = VALUES(status), payload = VALUES(payload), ' +
+      'detected_at = CURRENT_TIMESTAMP',
+    [status, JSON.stringify(payload)],
+  )
+}
+
+async function clearPending() {
+  return query('DELETE FROM shard_atlas_pending')
+}
+
+// ── Reads (the public /atlas surface) ──────────────────────────────────────
+//
+// Every read here is a plain indexed query over ~7k rows and is served entirely
+// from MariaDB: the atlas is static shard content, so nothing on this path
+// touches the sidecar and nothing degrades when the shard is down.
+//
+// A facet filter is expressed as EXISTS over the points, never as a JSON path
+// built from caller input. `shard_spawn_creatures.facets` is a JSON object keyed
+// by facet name, and matching a key means either concatenating the name into a
+// path or handing it to JSON_SEARCH — whose search string treats `%` and `_` as
+// wildcards, so `?facet=%` would quietly match everything. The join is exact and
+// uses the indexes that already exist.
+const CREATURE_FACET_EXISTS = `EXISTS (
+  SELECT 1 FROM shard_spawn_point_types t
+    JOIN shard_spawn_points p ON p.id = t.point_id
+   WHERE t.slug = c.slug AND p.facet = ?
+)`
+
+// Build the WHERE for a creature search. `q` is a substring match on the display
+// name — a LIKE scan, which is free at ~800 rows and, unlike FULLTEXT, has no
+// minimum token length to break a search for "orc".
+function creatureWhere({ q, facet }) {
+  const where = []
+  const params = []
+  if (q) {
+    where.push('c.name LIKE ?')
+    params.push(`%${q}%`)
+  }
+  if (facet) {
+    where.push(CREATURE_FACET_EXISTS)
+    params.push(facet)
+  }
+  return { sql: where.length ? `WHERE ${where.join(' AND ')}` : '', params }
+}
+
+async function countCreatures({ q = '', facet = '' } = {}) {
+  const { sql, params } = creatureWhere({ q, facet })
+  const rows = await query(`SELECT COUNT(*) AS n FROM shard_spawn_creatures c ${sql}`, params)
+  return rows[0] ? Number(rows[0].n) : 0
+}
+
+function listCreatures({ q = '', facet = '', limit = 50, offset = 0 } = {}) {
+  const { sql, params } = creatureWhere({ q, facet })
+  return query(
+    `SELECT c.slug, c.name, c.total, c.points, c.facets, c.art
+       FROM shard_spawn_creatures c
+       ${sql}
+      ORDER BY c.total DESC, c.name ASC
+      LIMIT ? OFFSET ?`,
+    [...params, limit, offset],
+  )
+}
+
+async function getCreature(slug) {
+  const rows = await query(
+    'SELECT slug, name, total, points, facets, art FROM shard_spawn_creatures WHERE slug = ?',
+    [slug],
+  )
+  return rows[0] || null
+}
+
+/**
+ * Where a creature spawns, grouped by resolved place.
+ *
+ * This is the answer the atlas exists to give — "lizardman → Shrines,
+ * Isamu-Jima, Yew" — so it is aggregated in SQL rather than by summing 6,455
+ * point rows in Node.
+ */
+function listCreaturePlaces(slug, { facet = '' } = {}) {
+  const params = [slug]
+  let facetSql = ''
+  if (facet) {
+    facetSql = 'AND p.facet = ?'
+    params.push(facet)
+  }
+  return query(
+    `SELECT p.facet, p.label, COUNT(*) AS spawners, SUM(t.max_count) AS max_alive
+       FROM shard_spawn_point_types t
+       JOIN shard_spawn_points p ON p.id = t.point_id
+      WHERE t.slug = ? ${facetSql}
+      GROUP BY p.facet, p.label
+      ORDER BY spawners DESC, p.facet ASC, p.label ASC`,
+    params,
+  )
+}
+
+/** The individual spawners for a creature, newest-largest first. Bounded. */
+function listCreaturePoints(slug, { facet = '', limit = 200 } = {}) {
+  const params = [slug]
+  let facetSql = ''
+  if (facet) {
+    facetSql = 'AND p.facet = ?'
+    params.push(facet)
+  }
+  params.push(limit)
+  return query(
+    `SELECT p.id, p.facet, p.name, p.x, p.y, p.width, p.height, p.spawn_range,
+            p.min_delay, p.max_delay, p.tod_start, p.tod_end, p.tod_mode,
+            p.region, p.landmark, p.label, t.max_count
+       FROM shard_spawn_point_types t
+       JOIN shard_spawn_points p ON p.id = t.point_id
+      WHERE t.slug = ? ${facetSql}
+      ORDER BY t.max_count DESC, p.facet ASC, p.label ASC, p.id ASC
+      LIMIT ?`,
+    params,
+  )
+}
+
+/** Every other creature sharing a spawner with this one. */
+function listCreatureCompanions(slug, { limit = 24 } = {}) {
+  return query(
+    `SELECT o.slug, c.name, COUNT(*) AS shared
+       FROM shard_spawn_point_types t
+       JOIN shard_spawn_point_types o ON o.point_id = t.point_id AND o.slug <> t.slug
+       JOIN shard_spawn_creatures c ON c.slug = o.slug
+      WHERE t.slug = ?
+      GROUP BY o.slug, c.name
+      ORDER BY shared DESC, c.name ASC
+      LIMIT ?`,
+    [slug, limit],
+  )
+}
+
+function listRegions({ facet = '', q = '' } = {}) {
+  const where = []
+  const params = []
+  if (facet) {
+    where.push('facet = ?')
+    params.push(facet)
+  }
+  if (q) {
+    where.push('name LIKE ?')
+    params.push(`%${q}%`)
+  }
+  return query(
+    `SELECT facet, name, type, priority, parent, rects
+       FROM shard_regions
+       ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+      ORDER BY facet ASC, name ASC`,
+    params,
+  )
+}
+
+function listLandmarks({ facet = '', q = '' } = {}) {
+  const where = []
+  const params = []
+  if (facet) {
+    where.push('facet = ?')
+    params.push(facet)
+  }
+  if (q) {
+    where.push('(name LIKE ? OR grp LIKE ?)')
+    params.push(`%${q}%`, `%${q}%`)
+  }
+  return query(
+    `SELECT facet, name, grp, x, y, z
+       FROM shard_landmarks
+       ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+      ORDER BY facet ASC, grp ASC, name ASC`,
+    params,
+  )
+}
+
+function listChampions({ facet = '' } = {}) {
+  const params = []
+  let where = ''
+  if (facet) {
+    where = 'WHERE facet = ?'
+    params.push(facet)
+  }
+  return query(
+    `SELECT slug, name, grp, type, random_type, facet, x, y, z, radius, label
+       FROM shard_champion_spawns
+       ${where}
+      ORDER BY facet ASC, name ASC`,
+    params,
+  )
+}
+
+module.exports = {
+  replaceAtlas,
+  getMeta,
+  getFacets,
+  getPending,
+  setPending,
+  clearPending,
+  countCreatures,
+  listCreatures,
+  getCreature,
+  listCreaturePlaces,
+  listCreaturePoints,
+  listCreatureCompanions,
+  listRegions,
+  listLandmarks,
+  listChampions,
+}

server/model/shardAtlas/shardAtlas.model.js

@@ -0,0 +1,491 @@
+const fs = require('fs')
+const path = require('path')
+
+const db = require('./shardAtlas.db')
+const core = require('../../core')
+const { settings } = core
+const { slugify } = require('../../utils/spawnAtlasParse')
+const {
+  AtlasSourceError,
+  PARSER_VERSION,
+  buildAtlas,
+  hashSources,
+  sameSources,
+} = require('../../utils/spawnAtlasSource')
+const log = require('../../core').logger('shardAtlas')
+
+// The spawn atlas, refreshed from the shard's own ServUO tree.
+//
+// The tree is the single source of truth. Nothing is precomputed and committed,
+// because a shard's maps change over its lifetime — facets get added, replaced
+// or renamed — and a snapshot in the repo would go stale against the world
+// players actually see. So the atlas is re-derived on every boot.
+//
+// Two rules govern the boot path:
+//
+//   1. **It never blocks startup.** No configured path, an unreadable path, a
+//      malformed file, a database error — all of it is caught and logged. The
+//      site comes up either way, serving whatever atlas it already had.
+//   2. **A facet disappearing is not applied automatically.** Losing a facet is
+//      the signature of a half-copied or mid-update tree as much as of a real
+//      map change, and the two are indistinguishable from here. The refresh is
+//      staged for a human instead, and an admin approves or rejects it.
+//
+// Everything else — new facets, renamed regions, changed spawns — applies
+// straight away, because none of it can silently destroy data an operator would
+// miss.
+
+const SETTING_KEY = 'spawn_atlas_servuo_path'
+
+/**
+ * Where the ServUO tree lives.
+ *
+ * The admin setting wins over the environment so an operator can point the
+ * atlas at a different tree without a redeploy, matching how the rest of the
+ * shard integration is admin-managed rather than env-configured. `SERVUO_PATH`
+ * remains as the deploy-time default, since the path usually describes a mount
+ * that the deployment sets up.
+ */
+async function getServuoPath() {
+  try {
+    const configured = await settings.get(SETTING_KEY)
+    if (configured && String(configured).trim() !== '') return String(configured).trim()
+  } catch {
+    // Settings unavailable is not fatal — fall through to the env default.
+  }
+  const fromEnv = process.env.SERVUO_PATH
+  return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : ''
+}
+
+async function setServuoPath(value, updatedBy = null) {
+  return settings.set(SETTING_KEY, String(value ?? '').trim(), updatedBy)
+}
+
+/**
+ * Optional operator-supplied art map, `{ "<slug>": "<file under uploads/atlas/>" }`.
+ *
+ * Never committed and never shipped — creature sprites come out of the
+ * operator's own client `.mul`/`.uop` files, which are theirs, not ours to
+ * redistribute. Absent (the normal case) every `art` stays NULL and the UI
+ * renders text-only.
+ */
+// Resolved from ctx.paths.moduleRoot rather than by walking up from __dirname.
+// The ported default was `../../../db/data`, which pointed at core's tree when
+// this file lived there and points OUTSIDE server/ now — a path that happens to
+// resolve is exactly the kind of port bug that survives a green test suite,
+// because the absent-file branch returns {} and looks like the normal case.
+function loadArtMap(dir = path.join(core.moduleRoot, 'server', 'data')) {
+  try {
+    const file = path.join(dir, 'spawnAtlas.art.json')
+    if (!fs.existsSync(file)) return {}
+    const map = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return map && typeof map === 'object' ? map : {}
+  } catch (err) {
+    log.warn('spawn atlas art map could not be read', { error: err.message })
+    return {}
+  }
+}
+
+/**
+ * Flatten each point's types into `shard_spawn_point_types` rows.
+ *
+ * A spawner may legitimately list the same type twice, and the primary key is
+ * (point_id, slug), so duplicates collapse to the larger max rather than
+ * failing the insert.
+ */
+function pointTypeRows(points) {
+  const rows = []
+  points.forEach((point, i) => {
+    const bySlug = new Map()
+    for (const entry of point.types ?? []) {
+      const slug = slugify(entry.type)
+      if (slug === '') continue
+      bySlug.set(slug, Math.max(bySlug.get(slug) ?? 0, entry.max ?? 1))
+    }
+    for (const [slug, max] of bySlug) rows.push([i + 1, slug, max])
+  })
+  return rows
+}
+
+async function applyAtlas(atlas) {
+  return db.replaceAtlas({ ...atlas, pointTypes: pointTypeRows(atlas.points) }, loadArtMap())
+}
+
+/**
+ * Refresh the atlas from the configured ServUO tree.
+ *
+ * Returns a result describing what happened rather than throwing, so the caller
+ * — including the boot path — can log it and move on:
+ *
+ *   `skipped`     no path configured
+ *   `unavailable` path configured but unreadable / missing required files
+ *   `unchanged`   source hashes match the loaded atlas; nothing parsed
+ *   `imported`    parsed and applied
+ *   `needsReview` parsed, but a facet would be lost; staged for an admin
+ *   `failed`      parsed or applied and something went wrong
+ *
+ * `force` skips the hash check (an admin asking for a reimport) and `approve`
+ * additionally accepts facet loss (an admin approving a staged refresh).
+ */
+/**
+ * Was the loaded atlas built by THIS parser?
+ *
+ * An atlas imported before `parserVersion` existed reports undefined, which is
+ * correctly "no" — those are exactly the ones carrying the old readings.
+ */
+const currentParser = (meta) => meta?.parserVersion === PARSER_VERSION
+
+async function refresh({ force = false, approve = false, path: pathOverride = '' } = {}) {
+  // An explicit override wins outright — it is a one-off "use this tree", and it
+  // must not be silently overruled by the configured path the way an env default
+  // would be.
+  const root = pathOverride.trim() !== '' ? pathOverride.trim() : await getServuoPath()
+  if (root === '') return { status: 'skipped', reason: 'no ServUO path configured' }
+
+  let hashes
+  try {
+    hashes = hashSources(root)
+  } catch (err) {
+    if (err instanceof AtlasSourceError) {
+      return { status: 'unavailable', reason: err.message, code: err.code, path: root }
+    }
+    return { status: 'failed', reason: err.message, path: root }
+  }
+
+  const meta = await db.getMeta().catch(() => null)
+  const loaded = meta?.source
+    ? Object.fromEntries(Object.entries(meta.source).map(([label, v]) => [label, v.sha256]))
+    : null
+
+  // Two things make a loaded atlas stale: the tree changed, or the PARSER did.
+  // Only checking the tree would strand an install whose maps never change on
+  // whatever an older build derived — a corrected parse would ship and never
+  // reach the data.
+  if (!force && sameSources(hashes, loaded) && currentParser(meta)) {
+    return { status: 'unchanged', path: root }
+  }
+
+  // A rejected refresh must not re-prompt on every boot. It stays rejected until
+  // the tree changes again, at which point the hashes differ and it is a new
+  // decision.
+  const pending = await db.getPending().catch(() => null)
+  if (!approve && !force && pending?.status === 'rejected' && sameSources(hashes, pending.hashes)) {
+    return { status: 'unchanged', path: root, reason: 'refresh previously rejected' }
+  }
+
+  let atlas
+  try {
+    atlas = buildAtlas(root)
+  } catch (err) {
+    return { status: 'failed', reason: err.message, path: root }
+  }
+
+  const currentFacets = await db.getFacets().catch(() => [])
+  const incomingFacets = atlas.facets
+  const removedFacets = currentFacets.filter((facet) => !incomingFacets.includes(facet))
+  const addedFacets = incomingFacets.filter((facet) => !currentFacets.includes(facet))
+
+  // Losing a facet is indistinguishable here from a half-copied tree, so it is
+  // staged rather than applied — but startup is never blocked by it.
+  if (removedFacets.length > 0 && !approve) {
+    const summary = {
+      hashes,
+      path: root,
+      currentFacets,
+      incomingFacets,
+      removedFacets,
+      addedFacets,
+      counts: atlas.meta.counts,
+    }
+    await db.setPending(summary, 'pending').catch((err) => {
+      log.warn('could not stage spawn atlas refresh', { error: err.message })
+    })
+    return { status: 'needsReview', ...summary }
+  }
+
+  try {
+    const counts = await applyAtlas(atlas)
+    return { status: 'imported', path: root, counts, addedFacets, removedFacets }
+  } catch (err) {
+    return { status: 'failed', reason: err.message, path: root }
+  }
+}
+
+/** Admin approved a staged refresh: apply it, facet loss and all. */
+async function approvePending(options = {}) {
+  return refresh({ ...options, approve: true, force: true })
+}
+
+/**
+ * Admin rejected a staged refresh: keep the current atlas and remember the
+ * decision against those exact source hashes, so it does not re-prompt every
+ * boot. A further change to the tree produces different hashes and asks again.
+ */
+async function rejectPending() {
+  const pending = await db.getPending()
+  if (!pending) return { status: 'none' }
+  await db.setPending({ ...pending, rejectedAt: new Date().toISOString() }, 'rejected')
+  return { status: 'rejected' }
+}
+
+/** Everything the admin panel needs to describe atlas state. */
+async function status({ path: pathOverride = '' } = {}) {
+  const root = pathOverride.trim() !== '' ? pathOverride.trim() : await getServuoPath()
+  const [meta, pending, facets] = await Promise.all([
+    db.getMeta().catch(() => null),
+    db.getPending().catch(() => null),
+    db.getFacets().catch(() => []),
+  ])
+
+  let treeReadable = false
+  let drift = null
+  if (root !== '') {
+    try {
+      const hashes = hashSources(root)
+      treeReadable = true
+      const loaded = meta?.source
+        ? Object.fromEntries(Object.entries(meta.source).map(([l, v]) => [l, v.sha256]))
+        : null
+      // Same question `refresh` asks: an import picks something up when either
+      // the tree or the parser has moved on.
+      drift = !sameSources(hashes, loaded) || !currentParser(meta)
+    } catch {
+      treeReadable = false
+    }
+  }
+
+  return {
+    configured: root !== '',
+    path: root,
+    treeReadable,
+    drift,
+    facets,
+    importedAt: meta?.importedAt ?? null,
+    counts: meta?.counts ?? null,
+    pending,
+  }
+}
+
+/**
+ * Boot hook. Best-effort by contract: it logs and returns, never throws, so a
+ * missing tree or a bad file can never stop the site coming up.
+ */
+async function refreshOnBoot() {
+  try {
+    const result = await refresh()
+    switch (result.status) {
+      case 'imported':
+        log.info('spawn atlas refreshed from ServUO tree', {
+          ...result.counts,
+          added: result.addedFacets,
+        })
+        break
+      case 'needsReview':
+        log.warn(
+          'spawn atlas refresh staged for admin review — a facet would be removed; ' +
+            'the existing atlas is unchanged',
+          { removed: result.removedFacets, added: result.addedFacets },
+        )
+        break
+      case 'unavailable':
+        log.warn('spawn atlas source unavailable', { reason: result.reason, path: result.path })
+        break
+      case 'failed':
+        log.warn('spawn atlas refresh failed', { reason: result.reason })
+        break
+      default:
+        break
+    }
+    return result
+  } catch (err) {
+    log.warn('spawn atlas refresh errored', { error: err.message })
+    return { status: 'failed', reason: err.message }
+  }
+}
+
+// ── Reads ──────────────────────────────────────────────────────────────────
+//
+// The shapes the /public/atlas endpoints serve. Rows are camelCased here rather
+// than in the controller, for the same reason shardState does it: the column
+// names are an implementation detail of the import, and the browser contract
+// should not move when a column is renamed.
+
+const jsonOr = (value, fallback) => {
+  if (value == null) return fallback
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return fallback
+  }
+}
+
+const shapeCreature = (row) => ({
+  slug: row.slug,
+  name: row.name,
+  // `total` is the summed MaxCount across every spawner (how many can be alive
+  // at once); `points` is how many spawners mention it. They answer different
+  // questions and the UI shows both.
+  total: row.total,
+  points: row.points,
+  facets: jsonOr(row.facets, {}),
+  art: row.art || null,
+})
+
+const shapePlace = (row) => ({
+  facet: row.facet,
+  label: row.label,
+  spawners: Number(row.spawners) || 0,
+  maxAlive: Number(row.max_alive) || 0,
+})
+
+const shapePoint = (row) => ({
+  id: row.id,
+  facet: row.facet,
+  name: row.name || null,
+  x: row.x,
+  y: row.y,
+  width: row.width,
+  height: row.height,
+  range: row.spawn_range,
+  maxCount: row.max_count,
+  minDelay: row.min_delay,
+  maxDelay: row.max_delay,
+  todStart: row.tod_start,
+  todEnd: row.tod_end,
+  todMode: row.tod_mode,
+  region: row.region || null,
+  landmark: row.landmark || null,
+  label: row.label,
+})
+
+/**
+ * Paginated creature search. Returns the page plus the unpaginated total, so
+ * the UI can say "showing 50 of 800" without a second round trip.
+ */
+async function searchCreatures({ q = '', facet = '', limit = 50, offset = 0 } = {}) {
+  const [rows, total] = await Promise.all([
+    db.listCreatures({ q, facet, limit, offset }),
+    db.countCreatures({ q, facet }),
+  ])
+  return { total, limit, offset, creatures: rows.map(shapeCreature) }
+}
+
+/**
+ * One creature: its totals, the places it spawns (the aggregate the atlas
+ * exists for), the individual spawners, and what else shares those spawners.
+ *
+ * `null` when the slug is unknown — the controller turns that into a 404.
+ */
+async function getCreature(slug, { facet = '', points = 200 } = {}) {
+  const row = await db.getCreature(slug)
+  if (!row) return null
+  const [places, pointRows, alsoHere] = await Promise.all([
+    db.listCreaturePlaces(slug, { facet }),
+    db.listCreaturePoints(slug, { facet, limit: points }),
+    db.listCreatureCompanions(slug),
+  ])
+  return {
+    ...shapeCreature(row),
+    places: places.map(shapePlace),
+    // `spawners`, not `points`: shapeCreature already uses `points` for the
+    // COUNT of spawners, and reusing the key for the list of them would make the
+    // same field a number on the search route and an array here.
+    spawners: pointRows.map(shapePoint),
+    // Bounded by the query, so a creature on hundreds of spawners returns a page
+    // rather than the world.
+    spawnersTruncated: pointRows.length >= points,
+    alsoHere: alsoHere.map((r) => ({
+      slug: r.slug,
+      name: r.name,
+      shared: Number(r.shared) || 0,
+    })),
+  }
+}
+
+async function listRegions(opts = {}) {
+  const rows = await db.listRegions(opts)
+  return rows.map((r) => ({
+    facet: r.facet,
+    name: r.name,
+    type: r.type || null,
+    priority: r.priority,
+    parent: r.parent || null,
+    rects: jsonOr(r.rects, []),
+  }))
+}
+
+async function listLandmarks(opts = {}) {
+  const rows = await db.listLandmarks(opts)
+  return rows.map((r) => ({
+    facet: r.facet,
+    name: r.name,
+    group: r.grp || null,
+    x: r.x,
+    y: r.y,
+    z: r.z,
+  }))
+}
+
+async function listChampions(opts = {}) {
+  const rows = await db.listChampions(opts)
+  return rows.map((r) => ({
+    slug: r.slug,
+    name: r.name,
+    group: r.grp || null,
+    // '' on the wire means "randomised at activation"; `randomType` says so
+    // explicitly rather than making the client infer it from an empty string.
+    type: r.type || null,
+    randomType: !!r.random_type,
+    facet: r.facet,
+    x: r.x,
+    y: r.y,
+    z: r.z,
+    radius: r.radius,
+    label: r.label || null,
+  }))
+}
+
+/**
+ * What is loaded: the facet list, the counts, and when it was imported.
+ *
+ * Deliberately does NOT report the source path, the per-file hashes or whether
+ * a refresh is pending. Those describe the operator's filesystem, and this is a
+ * public endpoint; the admin status route carries them instead.
+ */
+async function publicMeta() {
+  const [meta, facets] = await Promise.all([
+    db.getMeta().catch(() => null),
+    db.getFacets().catch(() => []),
+  ])
+  return {
+    importedAt: meta?.importedAt ?? null,
+    generatedAt: meta?.generatedAt ?? null,
+    // The parse counts, not the row counts: `unresolvedPoints` is what lets the
+    // page state its own placement accuracy instead of implying it is complete.
+    counts: meta?.counts ?? null,
+    facets,
+  }
+}
+
+const listFacets = () => db.getFacets()
+
+module.exports = {
+  refresh,
+  refreshOnBoot,
+  approvePending,
+  rejectPending,
+  status,
+  getServuoPath,
+  setServuoPath,
+  pointTypeRows,
+  loadArtMap,
+  SETTING_KEY,
+  searchCreatures,
+  getCreature,
+  listRegions,
+  listLandmarks,
+  listChampions,
+  listFacets,
+  publicMeta,
+}

server/model/shardClilocs/shardClilocs.db.js

@@ -0,0 +1,110 @@
+const core = require('../../core')
+
+const { query } = core
+
+// Raw SQL for the cliloc table. `shard_clilocs` is IMPORT-OWNED: `replaceAll`
+// empties and refills it inside one transaction, and nothing else in the
+// codebase writes to it. No foreign keys, consistent with every other shard_*
+// table.
+
+const BATCH = 1000
+
+/**
+ * Replace the entire cliloc table in one transaction.
+ *
+ * All-or-nothing on purpose: a failed reload must leave the previous table
+ * intact rather than a half-loaded one, because a partially-imported cliloc
+ * table is indistinguishable from a complete one to anyone reading it — you
+ * would just see some items named and some not, which is also what "no table at
+ * all" looks like.
+ *
+ * `DELETE`, not `TRUNCATE` — `TRUNCATE` is DDL in MariaDB and implicitly
+ * commits, which would defeat exactly that guarantee. (The same trap the spawn
+ * atlas import documents; at ~123k rows `DELETE` is still well under a second.)
+ */
+async function replaceAll(entries, meta) {
+  const conn = await core.pool.getConnection()
+  try {
+    await conn.beginTransaction()
+    await conn.query('DELETE FROM shard_clilocs')
+
+    // Blank entries are dropped rather than stored. Roughly HALF of a real
+    // cliloc table is empty strings — ids the client reserves and never uses —
+    // and a row that resolves to no name is indistinguishable from no row at
+    // all to every caller. Dropping them halves the table (123,490 → ~67,500)
+    // and, more importantly, makes the binary and text imports converge on
+    // identical content: the binary format carries the blanks explicitly and a
+    // text export may or may not, depending on the tool.
+    //
+    // Later duplicates win. Merging across sources already happened upstream in
+    // `readCliloc`, so in practice this collapses nothing — it is kept because
+    // the plain format permits a repeated id WITHIN one file and the client's
+    // own loader resolves it the same way (its dictionary assignment
+    // overwrites). Without it, a file the game itself would load happily would
+    // fail the batch insert on a primary-key collision.
+    const byNumber = new Map()
+    let blank = 0
+    for (const entry of entries) {
+      if (!Number.isInteger(entry.number)) continue
+      if (String(entry.text ?? '').trim() === '') {
+        blank++
+        continue
+      }
+      byNumber.set(entry.number, entry)
+    }
+
+    const rows = [...byNumber.values()].map((e) => [e.number, e.flag ?? 0, e.text])
+    for (let i = 0; i < rows.length; i += BATCH) {
+      await conn.batch('INSERT INTO shard_clilocs (number, flag, text) VALUES (?,?,?)', rows.slice(i, i + BATCH))
+    }
+
+    await conn.query(
+      'INSERT INTO shard_cliloc_meta (id, payload) VALUES (1, ?) ' +
+        'ON DUPLICATE KEY UPDATE payload = VALUES(payload), imported_at = CURRENT_TIMESTAMP',
+      [JSON.stringify({ ...meta, count: rows.length })],
+    )
+
+    await conn.commit()
+    return { count: rows.length, blank, duplicates: entries.length - blank - rows.length }
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+async function getMeta() {
+  const rows = await query('SELECT payload, imported_at FROM shard_cliloc_meta WHERE id = 1')
+  if (rows.length === 0) return null
+  const payload = typeof rows[0].payload === 'string' ? JSON.parse(rows[0].payload) : rows[0].payload
+  return { ...payload, importedAt: rows[0].imported_at }
+}
+
+/**
+ * Look up a batch of ids.
+ *
+ * Batched rather than one-at-a-time because every caller has a LIST: a character
+ * sheet resolves a dozen equipment ids at once, and a page of marketplace
+ * listings resolves fifty. `IN (...)` with generated placeholders keeps it one
+ * round trip and one parameterized statement.
+ */
+async function lookup(numbers) {
+  if (!Array.isArray(numbers) || numbers.length === 0) return []
+  const ids = [...new Set(numbers.filter((n) => Number.isInteger(n)))]
+  if (ids.length === 0) return []
+  const placeholders = ids.map(() => '?').join(',')
+  return query(`SELECT number, text FROM shard_clilocs WHERE number IN (${placeholders})`, ids)
+}
+
+async function count() {
+  const rows = await query('SELECT COUNT(*) AS n FROM shard_clilocs')
+  return Number(rows[0]?.n) || 0
+}
+
+module.exports = {
+  replaceAll,
+  getMeta,
+  lookup,
+  count,
+}

server/model/shardClilocs/shardClilocs.model.js

@@ -0,0 +1,368 @@
+const db = require('./shardClilocs.db')
+const { settings } = require('../../core')
+const { displayText } = require('../../utils/clilocParse')
+const {
+  ClilocFormatError,
+  ClilocSourceError,
+  PARSER_VERSION,
+  hashSources,
+  sameSources,
+  missingSources,
+  readCliloc,
+} = require('../../utils/clilocSource')
+const log = require('../../core').logger('shardClilocs')
+
+// The cliloc table — UO's id → display-string map, refreshed from a file the
+// operator converts once from their own client.
+//
+// Why the site holds this at all: items on the wire carry a `LabelNumber`, not a
+// name. `char.profile.equipment` has always sent `cliloc`, and every marketplace
+// listing sends one too. Without the table the UI can only print `id 1023721`
+// where the game prints "quarter staff".
+//
+// Two rules govern the boot path, both inherited from the spawn atlas:
+//
+//   1. **It never blocks startup.** No configured path, an unreadable file, a
+//      wrong-format file, a database error — all caught and logged. The site
+//      comes up either way, serving whatever table it already had (or none, in
+//      which case the UI falls back to item ids exactly as it did before).
+//   2. **Nothing client-derived is committed.** The table is built from the
+//      operator's own file at a configured path. The repo ships no strings.
+//
+// The table is built from a SET of sources — the converted client table plus
+// every operator-maintained overlay beside it — because shards edit items and
+// add new ones, and those carry cliloc ids no stock client table has. All of
+// them are re-read on every boot and hash-gated together, so adding one custom
+// item never means re-exporting a 5 MB client file. Later sources win.
+//
+// That set is also why this has the atlas's escalation, in a lighter form. A
+// single corrupt file fails the parse loudly, but a source that has simply
+// VANISHED parses perfectly and imports a table quietly missing everything it
+// contributed — the same ambiguity (real change vs half-copied mount) the atlas
+// stages a facet removal for. So a disappearing source is refused and reported
+// rather than applied.
+//
+// It is lighter than the atlas's because it needs to be: the atlas stores a
+// pending decision in its own table and adds approve/reject endpoints, whereas
+// here the decision is a single boolean an admin passes to the import they were
+// already going to run. Re-parsing at approval time — the property that makes
+// the atlas store only the decision — is automatic when there is nothing stored.
+
+const SETTING_KEY = 'cliloc_client_path'
+
+/**
+ * Where the converted cliloc file lives.
+ *
+ * The admin setting wins over the environment so an operator can repoint it
+ * without a redeploy, matching how the rest of the shard integration is
+ * admin-managed rather than env-configured. `UO_CLIENT_PATH` remains as the
+ * deploy-time default, since the path usually describes a mount the deployment
+ * sets up.
+ */
+async function getClientPath() {
+  try {
+    const configured = await settings.get(SETTING_KEY)
+    if (configured && String(configured).trim() !== '') return String(configured).trim()
+  } catch {
+    // Settings unavailable is not fatal — fall through to the env default.
+  }
+  const fromEnv = process.env.UO_CLIENT_PATH
+  return fromEnv && fromEnv.trim() !== '' ? fromEnv.trim() : ''
+}
+
+async function setClientPath(value, updatedBy = null) {
+  const result = await settings.set(SETTING_KEY, String(value ?? '').trim(), updatedBy)
+  invalidate()
+  return result
+}
+
+// ── Refresh ────────────────────────────────────────────────────────────────
+
+/** Was the loaded table built by THIS parser? */
+const currentParser = (meta) => meta?.parserVersion === PARSER_VERSION
+
+/**
+ * Refresh the cliloc table from the configured file.
+ *
+ * Returns a result describing what happened rather than throwing, so the caller
+ * — including the boot path — can log it and move on:
+ *
+ *   `skipped`     no path configured
+ *   `unavailable` path configured but missing / unreadable / not a cliloc file
+ *   `unchanged`   source hashes match the loaded table; nothing parsed
+ *   `imported`    parsed and applied
+ *   `needsReview` a previously-present source has vanished; NOT applied
+ *   `failed`      parsed or applied and something went wrong
+ *
+ * `force` skips the hash check (an admin asking for a reimport). `approve`
+ * additionally accepts a vanished source.
+ */
+async function refresh({ force = false, approve = false, path: pathOverride = '' } = {}) {
+  // An explicit override wins outright — a one-off "use this file", which must
+  // not be silently overruled by the configured path the way an env default is.
+  const configured = pathOverride.trim() !== '' ? pathOverride.trim() : await getClientPath()
+  if (configured === '') return { status: 'skipped', reason: 'no cliloc path configured' }
+
+  let fingerprint
+  try {
+    fingerprint = hashSources(configured)
+  } catch (err) {
+    if (err instanceof ClilocSourceError) {
+      return { status: 'unavailable', reason: err.message, code: err.code, path: configured }
+    }
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+
+  const meta = await db.getMeta().catch(() => null)
+
+  // Two things make a loaded table stale: any source changed, or the PARSER did.
+  // Only checking the sources would strand an install whose client never patches
+  // on whatever an older build derived.
+  if (!force && sameSources(fingerprint.hashes, meta?.hashes) && currentParser(meta)) {
+    return {
+      status: 'unchanged',
+      path: configured,
+      file: fingerprint.file,
+      count: meta.count ?? null,
+      customCount: fingerprint.customCount,
+    }
+  }
+
+  // A source that was there last import and is not there now is refused, not
+  // applied — an unmounted volume and a deliberate deletion look identical from
+  // here, and the wrong guess silently drops every name that file contributed.
+  const gone = missingSources(fingerprint.hashes, meta?.hashes)
+  if (gone.length > 0 && !approve) {
+    return {
+      status: 'needsReview',
+      reason: `${gone.length} previously-loaded cliloc source(s) are missing; the existing table is unchanged`,
+      missingSources: gone,
+      path: configured,
+      file: fingerprint.file,
+    }
+  }
+
+  let parsed
+  try {
+    parsed = readCliloc(configured)
+  } catch (err) {
+    if (err instanceof ClilocFormatError || err instanceof ClilocSourceError) {
+      return { status: 'unavailable', reason: err.message, code: err.code, path: configured }
+    }
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+
+  try {
+    const applied = await db.replaceAll(parsed.entries, parsed.source)
+    invalidate()
+    return {
+      status: 'imported',
+      path: configured,
+      file: parsed.source.file,
+      count: applied.count,
+      parsed: parsed.entries.length,
+      blank: applied.blank,
+      // Per-source breakdown: how many entries each file contributed and how
+      // many of them overrode something already merged. An operator who adds an
+      // overlay wants to see it took effect, and "overrode: 0" on a file meant
+      // to re-label stock items says it did not.
+      sources: parsed.source.sources,
+      acceptedMissing: gone.length > 0 ? gone : undefined,
+    }
+  } catch (err) {
+    return { status: 'failed', reason: err.message, path: configured }
+  }
+}
+
+/**
+ * Boot hook. Best-effort by contract: it logs and returns, never throws, so a
+ * missing or malformed cliloc file can never stop the site coming up.
+ */
+async function refreshOnBoot() {
+  try {
+    const result = await refresh()
+    switch (result.status) {
+      case 'imported':
+        log.info('cliloc table refreshed', {
+          file: result.file,
+          count: result.count,
+          overlays: (result.sources || []).filter((s) => s.kind === 'custom').length,
+        })
+        break
+      case 'needsReview':
+        log.warn(
+          'cliloc refresh staged for admin review — a previously-loaded source is missing; ' +
+            'the existing table is unchanged',
+          { missing: result.missingSources },
+        )
+        break
+      case 'unavailable':
+        // Deliberately a warning, not an error: an operator who has not supplied
+        // a cliloc file is in a supported state (the UI shows item ids), and the
+        // most common cause — pointing at the client's own compressed file —
+        // needs the reason spelled out rather than a stack trace.
+        log.warn('cliloc source unavailable (item names will show as ids)', {
+          reason: result.reason,
+          code: result.code,
+          path: result.path,
+        })
+        break
+      case 'failed':
+        log.warn('cliloc refresh failed', { reason: result.reason })
+        break
+      default:
+        break
+    }
+    return result
+  } catch (err) {
+    log.warn('cliloc refresh errored', { error: err.message })
+    return { status: 'failed', reason: err.message }
+  }
+}
+
+/** Everything the admin panel needs to describe cliloc state. */
+async function status({ path: pathOverride = '' } = {}) {
+  const configured = pathOverride.trim() !== '' ? pathOverride.trim() : await getClientPath()
+  const meta = await db.getMeta().catch(() => null)
+  const loaded = await db.count().catch(() => 0)
+
+  let fileReadable = false
+  let file = null
+  let drift = null
+  let problem = null
+  let code = null
+  let sources = []
+  let missing = []
+  if (configured !== '') {
+    try {
+      const fingerprint = hashSources(configured)
+      fileReadable = true
+      file = fingerprint.file
+      sources = Object.keys(fingerprint.hashes)
+      missing = missingSources(fingerprint.hashes, meta?.hashes)
+      // A compressed file is readable but not importable, and the panel has to
+      // say so HERE — otherwise pointing at an unconverted client directory
+      // reports a healthy file with pending drift ("ready to import") and the
+      // operator only finds out when the import fails. `drift` stays null
+      // because comparing hashes with an unusable file answers nothing.
+      if (fingerprint.compressed) {
+        problem =
+          'This is a compressed (Mythic-format) cliloc file, which the site cannot read. ' +
+          'Convert it to the plain format first — see docs/website/CLILOCS.md.'
+        code = 'COMPRESSED'
+      } else {
+        drift = !sameSources(fingerprint.hashes, meta?.hashes) || !currentParser(meta)
+      }
+    } catch (err) {
+      fileReadable = false
+      problem = err.message
+      code = err.code ?? null
+    }
+  }
+
+  return {
+    configured: configured !== '',
+    path: configured,
+    file,
+    fileReadable,
+    problem,
+    code,
+    drift,
+    count: loaded,
+    // Every source found now (base first, then overlays), what each contributed
+    // at the last import, and any that have since vanished — which is the state
+    // an import will refuse without `approve`.
+    sources,
+    loadedSources: meta?.sources ?? null,
+    missingSources: missing,
+    importedAt: meta?.importedAt ?? null,
+    sourceBytes: meta?.bytes ?? null,
+  }
+}
+
+// ── Lookup ─────────────────────────────────────────────────────────────────
+//
+// Resolution happens SERVER-SIDE, not in the browser. Two reasons: the table is
+// ~123k rows and shipping it to a client would dwarf every page that uses it,
+// and the Android app consumes the same JSON and would otherwise need its own
+// copy. Callers get names, not ids-plus-a-table.
+
+// A small write-through cache in front of the table. Item ids repeat heavily —
+// one page of listings is mostly the same few hundred clilocs, and a character
+// sheet re-resolves the same gear on every view — so this turns the steady state
+// into zero queries. Capped so a pathological caller cannot grow it without
+// bound; on overflow it is dropped wholesale rather than evicted entry-by-entry,
+// which is cheap and correct for a table that only changes on reimport.
+const CACHE_MAX = 20000
+let cache = new Map()
+
+function invalidate() {
+  cache = new Map()
+}
+
+/**
+ * Resolve a batch of cliloc ids to display strings.
+ *
+ * Returns a `Map<number, string>` holding only the ids that resolved to
+ * something displayable — an id with no row, or one whose text is nothing but
+ * interpolated arguments we do not have, is simply absent. Callers fall back to
+ * whatever they had (the item id), so "missing" and "unnamed" collapse into one
+ * branch at the call site.
+ *
+ * Never throws: a cliloc lookup is decoration on someone's character sheet, and
+ * a database blip must not fail the sheet.
+ */
+async function resolveMany(numbers) {
+  const out = new Map()
+  if (!Array.isArray(numbers)) return out
+
+  const wanted = [...new Set(numbers.filter((n) => Number.isInteger(n) && n > 0))]
+  if (wanted.length === 0) return out
+
+  const missing = []
+  for (const number of wanted) {
+    if (cache.has(number)) {
+      const hit = cache.get(number)
+      if (hit !== '') out.set(number, hit)
+    } else {
+      missing.push(number)
+    }
+  }
+
+  if (missing.length > 0) {
+    try {
+      const rows = await db.lookup(missing)
+      const found = new Map(rows.map((r) => [Number(r.number), displayText(r.text)]))
+      if (cache.size + missing.length > CACHE_MAX) invalidate()
+      for (const number of missing) {
+        // Cache the miss too ('' meaning "no usable name"), so an id absent from
+        // the table does not re-query on every page view.
+        const text = found.get(number) ?? ''
+        cache.set(number, text)
+        if (text !== '') out.set(number, text)
+      }
+    } catch (err) {
+      log.warn('cliloc lookup failed', { message: err.message })
+    }
+  }
+
+  return out
+}
+
+/** Single-id convenience. Returns `null` when there is no usable name. */
+async function resolve(number) {
+  const found = await resolveMany([number])
+  return found.get(number) ?? null
+}
+
+module.exports = {
+  SETTING_KEY,
+  getClientPath,
+  setClientPath,
+  refresh,
+  refreshOnBoot,
+  status,
+  resolveMany,
+  resolve,
+  invalidate,
+}

server/model/shardEvents/shardEvents.db.js

@@ -0,0 +1,46 @@
+const { query } = require('../../core')
+
+// INSERT IGNORE on the UNIQUE dedupe_key — a re-ingested event (WS-reconnect
+// backfill overlap) is silently skipped rather than duplicated. Returns true if
+// a new row was actually inserted.
+async function insertIgnore({ kind, t, bootId, payload, dedupeKey }) {
+  const res = await query(
+    `INSERT IGNORE INTO shard_events (kind, t, boot_id, payload, dedupe_key)
+     VALUES (?, ?, ?, ?, ?)`,
+    [kind, t, bootId || null, JSON.stringify(payload), dedupeKey],
+  )
+  return res.affectedRows > 0
+}
+
+// Recent events, newest first. Filter by a single `kind`, or an allowlist of
+// `kinds` (IN clause) — the public feed uses the allowlist so it can never leak
+// staff/sensitive kinds. limit is clamped by the model.
+async function list({ kind, kinds, limit }) {
+  // An allowlist that resolved to NOTHING means "serve nothing" — never "serve
+  // everything". Falling through to the unfiltered query below would have turned
+  // a fully-gated visibility config into a full dump of the event log, staff
+  // audit and cheat detections included.
+  if (kinds && kinds.length === 0) return []
+  if (kinds && kinds.length) {
+    const placeholders = kinds.map(() => '?').join(', ')
+    return query(
+      `SELECT id, kind, t, boot_id, payload, created_at
+         FROM shard_events WHERE kind IN (${placeholders}) ORDER BY t DESC LIMIT ?`,
+      [...kinds, limit],
+    )
+  }
+  if (kind) {
+    return query(
+      `SELECT id, kind, t, boot_id, payload, created_at
+         FROM shard_events WHERE kind = ? ORDER BY t DESC LIMIT ?`,
+      [kind, limit],
+    )
+  }
+  return query(
+    `SELECT id, kind, t, boot_id, payload, created_at
+       FROM shard_events ORDER BY t DESC LIMIT ?`,
+    [limit],
+  )
+}
+
+module.exports = { insertIgnore, list }

server/model/shardEvents/shardEvents.model.js

@@ -0,0 +1,61 @@
+// Append-only shard event log. The WS ingest dispatcher calls append() for the
+// notable kinds; the public/admin read endpoints call list(). The DB layer only
+// sees an already-computed dedupe_key so INSERT IGNORE is idempotent across
+// WS-reconnect backfill.
+
+const crypto = require('crypto')
+const db = require('./shardEvents.db')
+
+const MAX_LIMIT = 1000
+const DEFAULT_LIMIT = 100
+
+// Stable stringify — keys sorted — so the dedupe hash is independent of the
+// property order the sidecar happened to serialize with.
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  const keys = Object.keys(value).sort()
+  const entries = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+  return `{${entries.join(',')}}`
+}
+
+// dedupe_key = sha256(kind + t + stable-json(payload)), truncated to 40 hex chars.
+// This is a content fingerprint for idempotent INSERT IGNORE, not a security value,
+// but we use SHA-256 rather than SHA-1 anyway; the truncation keeps it inside the
+// CHAR(40) column (160 bits is ample collision resistance for dedupe). Two identical
+// events (same kind, same timestamp, same body) collapse to one row.
+function dedupeKey(kind, t, payload) {
+  return crypto
+    .createHash('sha256')
+    .update(`${kind}|${t}|${stableStringify(payload)}`)
+    .digest('hex')
+    .slice(0, 40)
+}
+
+// Append one event. Returns true if a new row was inserted (false = deduped).
+async function append({ kind, t, bootId, payload }) {
+  return db.insertIgnore({ kind, t, bootId, payload, dedupeKey: dedupeKey(kind, t, payload) })
+}
+
+function normalizeLimit(limit) {
+  const n = Number(limit)
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT
+  return Math.min(Math.floor(n), MAX_LIMIT)
+}
+
+// Recent events, newest first. Each row's JSON payload is parsed back to an
+// object. `kinds` (array) restricts to an allowlist; `kind` filters a single kind.
+async function list({ kind, kinds, limit } = {}) {
+  const rows = await db.list({ kind, kinds, limit: normalizeLimit(limit) })
+  return rows.map((row) => ({
+    id: row.id,
+    kind: row.kind,
+    t: row.t,
+    bootId: row.boot_id || null,
+    // mariadb returns JSON columns as strings on some versions; parse defensively.
+    payload: typeof row.payload === 'string' ? JSON.parse(row.payload) : row.payload,
+    createdAt: row.created_at,
+  }))
+}
+
+module.exports = { append, list, dedupeKey }

server/model/shardLinks/shardLinks.db.js

@@ -0,0 +1,42 @@
+const { query } = require('../../core')
+
+const COLS = 'account, user_id, char_name, linked_at'
+
+// Upsert a link. account is the PK, so a re-link moves the account to the new
+// user (the sidecar already treats /link/confirm as authoritative).
+async function upsert({ account, userId, charName }) {
+  await query(
+    `INSERT INTO shard_account_links (account, user_id, char_name)
+     VALUES (?, ?, ?)
+     ON DUPLICATE KEY UPDATE user_id = VALUES(user_id), char_name = VALUES(char_name)`,
+    [account, userId, charName || null],
+  )
+  return getByAccount(account)
+}
+
+async function getByAccount(account) {
+  const rows = await query(`SELECT ${COLS} FROM shard_account_links WHERE account = ? LIMIT 1`, [account])
+  return rows[0] || null
+}
+
+const listByUser = (userId) =>
+  query(`SELECT ${COLS} FROM shard_account_links WHERE user_id = ? ORDER BY linked_at DESC`, [userId])
+
+async function isOwnedBy(account, userId) {
+  const rows = await query(
+    'SELECT 1 FROM shard_account_links WHERE account = ? AND user_id = ? LIMIT 1',
+    [account, userId],
+  )
+  return rows.length > 0
+}
+
+const remove = (account, userId) =>
+  query('DELETE FROM shard_account_links WHERE account = ? AND user_id = ?', [account, userId])
+
+// Drop the mirror for an account regardless of which user held it — used to
+// reconcile when the tie is severed at the source (an in-game [unlink →
+// account.unlinked event, or a site-side DELETE /link/{account}).
+const removeByAccount = (account) =>
+  query('DELETE FROM shard_account_links WHERE account = ?', [account])
+
+module.exports = { upsert, getByAccount, listByUser, isOwnedBy, remove, removeByAccount }

server/model/shardLinks/shardLinks.model.js

@@ -0,0 +1,37 @@
+// Site-side mirror of in-game-account → website-user links. The sidecar owns the
+// authoritative link (it tags the game account on /link/confirm); this model
+// records it locally so the player portal can list links and enforce ownership.
+
+const db = require('./shardLinks.db')
+
+function toSafe(row) {
+  if (!row) return null
+  return {
+    account: row.account,
+    userId: row.user_id,
+    charName: row.char_name || null,
+    linkedAt: row.linked_at,
+  }
+}
+
+async function link({ account, userId, charName }) {
+  return toSafe(await db.upsert({ account, userId, charName }))
+}
+
+async function listForUser(userId) {
+  const rows = await db.listByUser(userId)
+  return rows.map(toSafe)
+}
+
+const ownsAccount = (account, userId) => db.isOwnedBy(account, userId)
+
+async function getByAccount(account) {
+  return toSafe(await db.getByAccount(account))
+}
+
+const unlink = (account, userId) => db.remove(account, userId)
+
+// Drop the local mirror for an account (source-of-truth severed elsewhere).
+const removeByAccount = (account) => db.removeByAccount(account)
+
+module.exports = { link, listForUser, ownsAccount, getByAccount, unlink, removeByAccount }

server/model/shardMarket/shardMarket.db.js

@@ -0,0 +1,301 @@
+const core = require('../../core')
+
+const { query } = core
+
+// Raw SQL for the player-vendor market index (Protocol 3.0 vendor.listing).
+//
+// Two tables, both INGEST-OWNED: `shard_vendors` (one row per shop) and
+// `shard_vendor_items` (one row per priced listing). Nothing else in the codebase
+// writes to either. No foreign keys, consistent with every other shard_* table.
+
+// Insert batch size for one vendor's listings. A shop is capped at
+// MarketMaxListings (250 by default) on the shard side, so in practice this is
+// one batch — it exists for the operator who raised that cap.
+const BATCH = 500
+
+// LIKE wildcards in user input. `%` and `_` are not special to the parameterized
+// query — they are special to LIKE itself — so a search for "50% off" would
+// otherwise match everything containing "50" and a search for "_" would match
+// every single-character name. Escaped with a backslash, which is MariaDB's
+// default LIKE escape (no ESCAPE clause needed).
+const likeTerm = (q) => `%${String(q).replace(/[\\%_]/g, (c) => `\\${c}`)}%`
+
+/**
+ * Replace one vendor's whole row and listing set, in one transaction.
+ *
+ * Delete-then-insert rather than a diff, because the frame is AUTHORITATIVE for
+ * that vendor: the shard's sweep only emits a shop whose contents, prices or
+ * location moved, and when it does it sends the whole shop. Reconciling it item
+ * by item would be more code for the same result and would leave sold items
+ * behind on any path the reconciliation missed.
+ *
+ * All-or-nothing matters here for a specific reason: the two writes are "the
+ * shop" and "what is in it", and a failure between them leaves a shop advertising
+ * an inventory it no longer has (or none at all) — visibly wrong on the page, and
+ * indistinguishable from a genuinely empty shop.
+ */
+async function replaceVendor(vendor, items) {
+  const conn = await core.pool.getConnection()
+  try {
+    await conn.beginTransaction()
+
+    await conn.query(
+      `INSERT INTO shard_vendors
+         (serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house,
+          item_count, item_total, truncated, t)
+       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+       ON DUPLICATE KEY UPDATE shop_name = VALUES(shop_name), owner_serial = VALUES(owner_serial),
+         owner_name = VALUES(owner_name), map = VALUES(map), x = VALUES(x), y = VALUES(y),
+         z = VALUES(z), region = VALUES(region), house = VALUES(house),
+         item_count = VALUES(item_count), item_total = VALUES(item_total),
+         truncated = VALUES(truncated), t = VALUES(t),
+         -- Touched explicitly rather than left to ON UPDATE CURRENT_TIMESTAMP:
+         -- MariaDB does not fire that when every column is written back
+         -- unchanged, and a shop that is re-published identically is still
+         -- FRESHLY CONFIRMED. Without this the staleness banner would age a
+         -- perfectly current shop forever.
+         updated_at = CURRENT_TIMESTAMP`,
+      [
+        vendor.serial,
+        vendor.shopName ?? null,
+        vendor.ownerSerial ?? null,
+        vendor.ownerName ?? null,
+        vendor.map ?? null,
+        Number.isFinite(vendor.x) ? vendor.x : null,
+        Number.isFinite(vendor.y) ? vendor.y : null,
+        Number.isFinite(vendor.z) ? vendor.z : null,
+        vendor.region ?? null,
+        vendor.house ?? null,
+        items.length,
+        Number.isFinite(vendor.itemTotal) ? vendor.itemTotal : items.length,
+        vendor.truncated ? 1 : 0,
+        Number.isFinite(vendor.t) ? vendor.t : null,
+      ],
+    )
+
+    await conn.query('DELETE FROM shard_vendor_items WHERE vendor_serial = ?', [vendor.serial])
+
+    const rows = items.map((i) => [
+      vendor.serial,
+      i.serial,
+      i.itemId,
+      i.hue,
+      i.amount,
+      i.price,
+      i.name,
+      i.cliloc,
+      i.displayName,
+      i.child ? 1 : 0,
+    ])
+
+    for (let i = 0; i < rows.length; i += BATCH) {
+      await conn.batch(
+        `INSERT INTO shard_vendor_items
+           (vendor_serial, serial, item_id, hue, amount, price, name, cliloc, display_name, child)
+         VALUES (?,?,?,?,?,?,?,?,?,?)`,
+        rows.slice(i, i + BATCH),
+      )
+    }
+
+    await conn.commit()
+    return { items: rows.length }
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+/** Drop one vendor and its listings (vendor.listing.remove). */
+async function removeVendor(serial) {
+  const conn = await core.pool.getConnection()
+  try {
+    await conn.beginTransaction()
+    await conn.query('DELETE FROM shard_vendor_items WHERE vendor_serial = ?', [serial])
+    await conn.query('DELETE FROM shard_vendors WHERE serial = ?', [serial])
+    await conn.commit()
+  } catch (err) {
+    await conn.rollback().catch(() => {})
+    throw err
+  } finally {
+    conn.release()
+  }
+}
+
+// ── Search ─────────────────────────────────────────────────────────────────
+//
+// The unit of a search RESULT is a listing, not a vendor: "who sells a vanquishing
+// kryss and for how much" is the question, and answering it per vendor would make
+// the caller flatten the shops back out. The vendor's columns ride along on the
+// join so a result row is self-contained.
+
+function searchWhere({ q, minPrice, maxPrice, itemId, map, region }) {
+  const where = ['i.price > 0']
+  const params = []
+
+  if (q) {
+    // Both the resolved display name and the item's own literal, because an item
+    // with a player-set name (most of what is actually worth searching for on a
+    // player-run shard) may have a generic cliloc.
+    where.push('(i.display_name LIKE ? OR i.name LIKE ?)')
+    params.push(likeTerm(q), likeTerm(q))
+  }
+  if (Number.isFinite(minPrice)) {
+    where.push('i.price >= ?')
+    params.push(minPrice)
+  }
+  if (Number.isFinite(maxPrice)) {
+    where.push('i.price <= ?')
+    params.push(maxPrice)
+  }
+  if (Number.isFinite(itemId)) {
+    where.push('i.item_id = ?')
+    params.push(itemId)
+  }
+  if (map) {
+    where.push('v.map = ?')
+    params.push(map)
+  }
+  if (region) {
+    where.push('v.region = ?')
+    params.push(region)
+  }
+
+  return { sql: `WHERE ${where.join(' AND ')}`, params }
+}
+
+// Whitelisted, because this interpolates into the statement. `recent` sorts by
+// the vendor's freshness, which is the only way to see what has just been listed
+// on a shard whose sweep is minutes wide.
+const SORTS = {
+  price_asc: 'i.price ASC, i.id ASC',
+  price_desc: 'i.price DESC, i.id ASC',
+  recent: 'v.updated_at DESC, i.id ASC',
+}
+
+async function searchListings({ q, minPrice, maxPrice, itemId, map, region, sort, limit, offset }) {
+  const { sql, params } = searchWhere({ q, minPrice, maxPrice, itemId, map, region })
+  const order = SORTS[sort] || SORTS.price_asc
+
+  const rows = await query(
+    `SELECT i.serial, i.item_id, i.hue, i.amount, i.price, i.name, i.cliloc, i.display_name, i.child,
+            v.serial AS vendor_serial, v.shop_name, v.owner_serial, v.owner_name,
+            v.map, v.x, v.y, v.z, v.region, v.house, v.updated_at
+       FROM shard_vendor_items i
+       JOIN shard_vendors v ON v.serial = i.vendor_serial
+       ${sql}
+      ORDER BY ${order}
+      LIMIT ? OFFSET ?`,
+    [...params, limit, offset],
+  )
+
+  const counted = await query(
+    `SELECT COUNT(*) AS n
+       FROM shard_vendor_items i
+       JOIN shard_vendors v ON v.serial = i.vendor_serial
+       ${sql}`,
+    params,
+  )
+
+  return { rows, total: Number(counted[0]?.n) || 0 }
+}
+
+async function getVendor(serial) {
+  const rows = await query(
+    `SELECT serial, shop_name, owner_serial, owner_name, map, x, y, z, region, house,
+            item_count, item_total, truncated, t, updated_at
+       FROM shard_vendors WHERE serial = ?`,
+    [serial],
+  )
+  return rows[0] || null
+}
+
+async function listVendorItems(serial, { limit, offset }) {
+  return query(
+    `SELECT serial, item_id, hue, amount, price, name, cliloc, display_name, child
+       FROM shard_vendor_items
+      WHERE vendor_serial = ?
+      ORDER BY price ASC, id ASC
+      LIMIT ? OFFSET ?`,
+    [serial, limit, offset],
+  )
+}
+
+/**
+ * What the market page's header needs: how big the index is, and how stale it may
+ * be. `staleAt` is the OLDEST vendor row — the round-robin sweep means a shop can
+ * be a full cycle behind, and the page says so rather than implying live prices.
+ */
+async function meta() {
+  const rows = await query(
+    `SELECT COUNT(*) AS vendors, MIN(updated_at) AS stale_at, MAX(updated_at) AS fresh_at
+       FROM shard_vendors`,
+  )
+  const items = await query('SELECT COUNT(*) AS n FROM shard_vendor_items')
+  return {
+    vendors: Number(rows[0]?.vendors) || 0,
+    items: Number(items[0]?.n) || 0,
+    staleAt: rows[0]?.stale_at || null,
+    freshAt: rows[0]?.fresh_at || null,
+  }
+}
+
+/** The distinct facets and regions holding vendors — drives the page's filters. */
+async function listPlaces() {
+  const maps = await query(
+    'SELECT DISTINCT map FROM shard_vendors WHERE map IS NOT NULL ORDER BY map',
+  )
+  const regions = await query(
+    'SELECT DISTINCT region FROM shard_vendors WHERE region IS NOT NULL ORDER BY region',
+  )
+  return { maps: maps.map((r) => r.map), regions: regions.map((r) => r.region) }
+}
+
+// ── Cliloc re-resolution ───────────────────────────────────────────────────
+
+/**
+ * One page of listings whose name still needs resolving, for the bulk pass that
+ * runs after a cliloc import.
+ *
+ * Keyed on `id > after` rather than OFFSET: the pass updates the very rows it is
+ * scanning, and an OFFSET walk over a table being rewritten skips rows. Every
+ * row with a cliloc is re-read, not just the unresolved ones, because an import
+ * can also CHANGE a name — a shard overlay relabelling a stock item is the whole
+ * reason overlays exist.
+ */
+async function listResolvableItems(after, limit) {
+  return query(
+    `SELECT id, cliloc, name, display_name
+       FROM shard_vendor_items
+      WHERE cliloc IS NOT NULL AND cliloc > 0 AND id > ?
+      ORDER BY id
+      LIMIT ?`,
+    [after, limit],
+  )
+}
+
+/** Write back a batch of re-resolved display names. */
+async function updateDisplayNames(pairs) {
+  if (pairs.length === 0) return 0
+  const conn = await core.pool.getConnection()
+  try {
+    await conn.batch('UPDATE shard_vendor_items SET display_name = ? WHERE id = ?', pairs)
+    return pairs.length
+  } finally {
+    conn.release()
+  }
+}
+
+module.exports = {
+  replaceVendor,
+  removeVendor,
+  searchListings,
+  getVendor,
+  listVendorItems,
+  meta,
+  listPlaces,
+  listResolvableItems,
+  updateDisplayNames,
+  likeTerm,
+}

server/model/shardMarket/shardMarket.model.js

@@ -0,0 +1,329 @@
+// ── Player-vendor market index (Protocol 3.0 vendor.listing) ───────────────
+//
+// The shard-wide shop index: what every player vendor is selling, for how much,
+// and where it is standing. This is the website's half of the search the in-game
+// Vendor Search gump offers — the same data, the same opt-out, reachable without
+// logging in to the game.
+//
+// Ingest is per-vendor and authoritative: the shard's round-robin sweep emits one
+// `vendor.listing` frame per shop whose contents, prices or location moved, and
+// the frame is the whole shop (see docs/link/v3.md §8 and BridgeMarket.cs). This
+// module normalizes it into shard_vendors + shard_vendor_items and, crucially,
+// resolves each listing's cliloc to a DISPLAY NAME on the way in — a search for
+// "kryss" is a search over names, and the shard only ever sends numbers.
+
+const db = require('./shardMarket.db')
+const clilocs = require('../shardClilocs/shardClilocs.model')
+const log = require('../../core').logger('shard-market')
+
+// Defense in depth on top of the shard's own MarketMaxListings cap. The shard is
+// trusted, but it is a separately-versioned component: a frame from a plugin
+// whose cap was raised (or a shard running modified scripts) must not be able to
+// turn one ingest into an unbounded transaction.
+const MAX_ITEMS_PER_VENDOR = 5000
+
+// Column widths in schema.sql. Truncating here rather than letting MariaDB do it
+// keeps the behavior the same in strict mode, where an over-length value is an
+// ERROR and would fail the whole vendor rather than shortening one name.
+const MAX_NAME = 160
+const MAX_SHOP = 160
+const MAX_OWNER = 64
+const MAX_MAP = 40
+const MAX_REGION = 80
+const MAX_SERIAL = 20
+
+const clip = (value, max) => {
+  if (value == null) return null
+  const s = String(value)
+  return s.length > max ? s.slice(0, max) : s
+}
+
+const int = (value, fallback = 0) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? Math.trunc(n) : fallback
+}
+
+// ── Ingest ─────────────────────────────────────────────────────────────────
+
+/**
+ * Flatten one `vendor.listing` frame into the row shapes the DB layer wants.
+ *
+ * `location` arrives as a nested object rather than flat map/x/y/region, and that
+ * shape is load-bearing rather than cosmetic: the visibility projection matches
+ * literal JSON keys, so ONE `market.location` rule can hide a vendor's
+ * whereabouts only if `location` is a single key on both the live frame and the
+ * stored read model. Flattening it here for storage and re-nesting it on read is
+ * what keeps that true on both paths.
+ *
+ * Exported for tests — it is the part with rules in it, and it is pure.
+ */
+function flattenFrame(ev) {
+  const loc = (ev && ev.location) || {}
+  return {
+    serial: clip(ev.serial, MAX_SERIAL),
+    shopName: clip(ev.shopName, MAX_SHOP),
+    ownerSerial: clip(ev.ownerSerial, MAX_SERIAL),
+    ownerName: clip(ev.ownerName, MAX_OWNER),
+    map: clip(loc.map, MAX_MAP),
+    x: Number.isFinite(loc.x) ? Math.trunc(loc.x) : null,
+    y: Number.isFinite(loc.y) ? Math.trunc(loc.y) : null,
+    z: Number.isFinite(loc.z) ? Math.trunc(loc.z) : null,
+    region: clip(loc.region, MAX_REGION),
+    house: clip(loc.house, MAX_SHOP),
+    // What the SHOP holds, which is not what the frame carries when it was
+    // truncated. Kept apart so the page can say "showing 250 of 3,104" rather
+    // than presenting a partial shop as a complete one.
+    itemTotal: int(ev.total, int(ev.count, 0)),
+    truncated: ev.truncated === true,
+    t: Number.isFinite(ev.t) ? ev.t : null,
+  }
+}
+
+/**
+ * Resolve each listing's display name.
+ *
+ * Order of preference is the item's own literal `name` first, then the cliloc.
+ * That is the opposite of what "resolve the id" suggests and it is right: a
+ * literal name only exists because a player set one ("Bob's vanquishing kryss"),
+ * and it is strictly more specific than the generic cliloc the item still
+ * carries.
+ *
+ * One batched lookup per frame rather than per item; `resolveMany` is cached and
+ * never throws, so a cliloc table that is missing entirely just leaves
+ * `displayName` null and the page renders item ids, exactly as it did before the
+ * table existed.
+ */
+async function shapeItems(ev) {
+  const raw = Array.isArray(ev.items) ? ev.items.slice(0, MAX_ITEMS_PER_VENDOR) : []
+
+  const wanted = raw
+    .map((i) => int(i && i.cliloc, 0))
+    .filter((n) => n > 0)
+
+  const names = await clilocs.resolveMany(wanted)
+
+  return raw
+    .filter((i) => i && i.serial)
+    .map((i) => {
+      const literal = clip(i.name, MAX_NAME)
+      const cliloc = int(i.cliloc, 0) || null
+      return {
+        serial: clip(i.serial, MAX_SERIAL),
+        itemId: int(i.itemId, 0),
+        hue: int(i.hue, 0),
+        amount: int(i.amount, 1),
+        price: int(i.price, 0),
+        name: literal,
+        cliloc,
+        displayName: literal || (cliloc ? clip(names.get(cliloc) ?? null, MAX_NAME) : null),
+        child: i.child === true,
+      }
+    })
+    // Unpriced rows are inventory, not listings. The shard already drops them;
+    // this is the same rule enforced where the table is written, so a plugin that
+    // stops enforcing it cannot put un-buyable rows on the market page.
+    .filter((i) => i.price > 0)
+}
+
+/** Ingest one `vendor.listing` frame. */
+async function upsertVendor(ev) {
+  if (!ev || !ev.serial) return
+  const vendor = flattenFrame(ev)
+  const items = await shapeItems(ev)
+  await db.replaceVendor(vendor, items)
+}
+
+/** Ingest one `vendor.listing.remove` frame. */
+async function removeVendor(serial) {
+  if (!serial) return
+  await db.removeVendor(String(serial).slice(0, MAX_SERIAL))
+}
+
+// ── Read models ────────────────────────────────────────────────────────────
+//
+// `location` is re-nested (see flattenFrame) so the stored read model and the
+// live wire frame present the same keys to the visibility projection.
+
+const place = (r) => ({
+  map: r.map,
+  x: r.x,
+  y: r.y,
+  z: r.z,
+  region: r.region,
+  house: r.house,
+})
+
+// A listing as the search returns it: the item, plus enough of its shop to be
+// actionable without a second request. `displayName` falls back to nothing rather
+// than to a fabricated "Item 3922" — the client decides how to render an
+// unresolved id, and inventing a name here would make it indistinguishable from
+// a real one.
+const shapeListing = (r) => ({
+  serial: r.serial,
+  itemId: r.item_id,
+  hue: r.hue,
+  amount: r.amount,
+  price: Number(r.price),
+  name: r.name,
+  cliloc: r.cliloc,
+  displayName: r.display_name,
+  child: !!r.child,
+  vendor: {
+    serial: r.vendor_serial,
+    shopName: r.shop_name,
+    ownerSerial: r.owner_serial,
+    ownerName: r.owner_name,
+    location: place(r),
+    updatedAt: r.updated_at,
+  },
+})
+
+const shapeVendor = (r) => ({
+  serial: r.serial,
+  shopName: r.shop_name,
+  ownerSerial: r.owner_serial,
+  ownerName: r.owner_name,
+  location: place(r),
+  count: r.item_count,
+  total: r.item_total,
+  truncated: !!r.truncated,
+  updatedAt: r.updated_at,
+})
+
+const shapeItem = (r) => ({
+  serial: r.serial,
+  itemId: r.item_id,
+  hue: r.hue,
+  amount: r.amount,
+  price: Number(r.price),
+  name: r.name,
+  cliloc: r.cliloc,
+  displayName: r.display_name,
+  child: !!r.child,
+})
+
+/**
+ * Search the index. Returns a page of LISTINGS (not vendors) plus the
+ * unpaginated total and the staleness stamp the page's banner needs.
+ */
+async function search({
+  q = '',
+  minPrice,
+  maxPrice,
+  itemId,
+  map = '',
+  region = '',
+  sort = 'price_asc',
+  limit = 50,
+  offset = 0,
+} = {}) {
+  const { rows, total } = await db.searchListings({
+    q: q.trim(),
+    minPrice: Number.isFinite(minPrice) ? minPrice : undefined,
+    maxPrice: Number.isFinite(maxPrice) ? maxPrice : undefined,
+    itemId: Number.isFinite(itemId) ? itemId : undefined,
+    map: map.trim(),
+    region: region.trim(),
+    sort,
+    limit,
+    offset,
+  })
+
+  const info = await db.meta()
+
+  return {
+    listings: rows.map(shapeListing),
+    total,
+    limit,
+    offset,
+    // Repeated on every search response rather than left to a separate /meta
+    // call: the banner that says how old these prices are must age with the
+    // results it labels, and a client that fetched it once would keep showing a
+    // stamp from before the page it is looking at.
+    staleAt: info.staleAt,
+    vendors: info.vendors,
+  }
+}
+
+/** One shop and its listings. `null` when the index has never seen that serial. */
+async function getVendor(serial, { limit = 250, offset = 0 } = {}) {
+  const row = await db.getVendor(serial)
+  if (!row) return null
+  const items = await db.listVendorItems(serial, { limit, offset })
+  return { ...shapeVendor(row), items: items.map(shapeItem) }
+}
+
+/** Index size, staleness, and the facet/region filter options. */
+async function meta() {
+  const [info, places] = await Promise.all([db.meta(), db.listPlaces()])
+  return { ...info, ...places }
+}
+
+// ── Cliloc re-resolution ───────────────────────────────────────────────────
+
+// Batch size for the post-import pass. Big enough that a 40k-row table is ~40
+// round trips, small enough that a single batch is not a long-held connection.
+const RESOLVE_BATCH = 1000
+
+/**
+ * Re-resolve every listing's display name against the current cliloc table.
+ *
+ * Called after a cliloc import, and it has to be: the market's diff sweep will
+ * NOT re-send an unchanged shop just because the site learned what its items are
+ * called, so without this an operator who configures clilocs after the first
+ * market sweep sees item ids until every shop happens to change. That is the same
+ * class of staleness the spawn atlas avoids by re-parsing on boot — here the
+ * source of truth for names moved, not the data.
+ *
+ * Never throws. It is a cosmetic backfill on a table that is already serving; a
+ * failure means names stay as they were, which is exactly the pre-import state.
+ */
+async function refreshDisplayNames() {
+  let after = 0
+  let scanned = 0
+  let changed = 0
+
+  try {
+    for (;;) {
+      const rows = await db.listResolvableItems(after, RESOLVE_BATCH)
+      if (rows.length === 0) break
+
+      after = rows[rows.length - 1].id
+      scanned += rows.length
+
+      const names = await clilocs.resolveMany(rows.map((r) => Number(r.cliloc)))
+
+      const pairs = []
+      for (const row of rows) {
+        // The literal name still wins, so a re-resolution never overwrites a
+        // player-set name with the generic cliloc behind it.
+        const next = row.name
+          ? clip(row.name, MAX_NAME)
+          : clip(names.get(Number(row.cliloc)) ?? null, MAX_NAME)
+        if (next !== row.display_name) pairs.push([next, row.id])
+      }
+
+      changed += await db.updateDisplayNames(pairs)
+    }
+
+    if (changed > 0) log.info('market display names refreshed', { scanned, changed })
+    return { scanned, changed }
+  } catch (err) {
+    log.warn('market display-name refresh failed', { message: err.message, scanned, changed })
+    return { scanned, changed, error: err.message }
+  }
+}
+
+module.exports = {
+  upsertVendor,
+  removeVendor,
+  search,
+  getVendor,
+  meta,
+  refreshDisplayNames,
+  flattenFrame,
+  shapeItems,
+  shapeListing,
+  shapeVendor,
+  MAX_ITEMS_PER_VENDOR,
+}

server/model/shardState/shardState.db.js

@@ -0,0 +1,369 @@
+const { query } = require('../../core')
+
+// Shared upsert builder for the shard-state tables. Each is keyed on a single
+// primary column (`pkCol` = pk); `fields` carries only the columns the model
+// wants to write, so a partial refresh touches nothing else. `coalesce` keeps
+// the prior column value when the incoming one is NULL (used by shard_online so a
+// vitals frame that omits acct/name doesn't blank what mob.login set); otherwise
+// the incoming value wins (VALUES()).
+function upsertRow(table, pkCol, pk, fields, { coalesce = false } = {}) {
+  const cols = Object.keys(fields)
+  const allCols = [pkCol, ...cols]
+  const insertCols = allCols.map((c) => `\`${c}\``).join(', ')
+  const placeholders = allCols.map(() => '?').join(', ')
+  const rhs = coalesce
+    ? (c) => `\`${c}\` = COALESCE(VALUES(\`${c}\`), \`${c}\`)`
+    : (c) => `\`${c}\` = VALUES(\`${c}\`)`
+  const updates = cols.map(rhs).join(', ')
+  return query(
+    `INSERT INTO ${table} (${insertCols}) VALUES (${placeholders})
+     ON DUPLICATE KEY UPDATE ${updates}`,
+    [pk, ...cols.map((c) => fields[c])],
+  )
+}
+
+// ── Online players ─────────────────────────────────────────────────────────
+const ONLINE_COLS =
+  'serial, name, acct, web_id, map, x, y, z, hits, hits_max, mana, mana_max, stam, stam_max, str, dex, `int`, updated_at'
+
+// Upsert one online player. `fields` already prepared by the model (only the
+// columns it wants to write); serial is required and is the primary key.
+// COALESCE variant: a char.vitals frame that omits acct/name must not blank what
+// mob.login set, so an incoming NULL keeps the prior column value.
+const upsertOnline = (serial, fields) =>
+  upsertRow('shard_online', 'serial', serial, fields, { coalesce: true })
+
+const removeOnline = (serial) => query('DELETE FROM shard_online WHERE serial = ?', [serial])
+const clearOnline = () => query('DELETE FROM shard_online')
+
+async function countOnline() {
+  const rows = await query('SELECT COUNT(*) AS n FROM shard_online')
+  return rows[0] ? Number(rows[0].n) : 0
+}
+
+const listOnline = () =>
+  query(`SELECT ${ONLINE_COLS} FROM shard_online ORDER BY name ASC`)
+
+// Online players on any of the given game accounts (admin: a user's linked
+// accounts). Empty list short-circuits so we never emit `IN ()`.
+const listOnlineByAccounts = (accounts) =>
+  accounts.length === 0
+    ? Promise.resolve([])
+    : query(
+        `SELECT ${ONLINE_COLS} FROM shard_online
+          WHERE acct IN (${accounts.map(() => '?').join(', ')})
+          ORDER BY name ASC`,
+        accounts,
+      )
+
+// Staff roles whose online presence is shown on the public Shard page. Players
+// who link an account are NOT surfaced publicly — only staff opt into visibility
+// by virtue of being staff.
+const PUBLIC_ONLINE_ROLES = ['admin', 'editor', 'moderator']
+
+// Online players whose game account is linked to a STAFF website user. Joined
+// against shard_account_links (not the sidecar-supplied web_id) so a link takes
+// effect immediately, regardless of whether the player has re-logged since
+// linking, then through to users so only staff roles are surfaced publicly.
+const listOnlineLinked = () => {
+  const cols = ONLINE_COLS.split(', ')
+    .map((c) => `o.${c}`)
+    .join(', ')
+  return query(
+    `SELECT ${cols}
+       FROM shard_online o
+       JOIN shard_account_links l ON l.account = o.acct
+       JOIN users u ON u.id = l.user_id
+      WHERE u.role IN (${PUBLIC_ONLINE_ROLES.map(() => '?').join(', ')})
+      ORDER BY o.name ASC`,
+    PUBLIC_ONLINE_ROLES,
+  )
+}
+
+// ── Economy supply series ────────────────────────────────────────────────
+const insertEconomy = ({ accounts, gold, t }) =>
+  query('INSERT INTO shard_economy (accounts, gold, t) VALUES (?, ?, ?)', [
+    accounts ?? null,
+    gold ?? null,
+    t,
+  ])
+
+const listEconomy = (limit) =>
+  query('SELECT accounts, gold, t FROM shard_economy ORDER BY t DESC LIMIT ?', [limit])
+
+async function latestEconomy() {
+  const rows = await query('SELECT accounts, gold, t FROM shard_economy ORDER BY t DESC LIMIT 1')
+  return rows[0] || null
+}
+
+// ── Houses / IDOC ────────────────────────────────────────────────────────
+const HOUSE_COLS =
+  'serial, stage, map, x, y, z, region, name, owner_serial, owner_acct, built_on, last_refreshed, is_idoc, updated_at'
+
+const upsertHouse = (serial, fields) => upsertRow('shard_houses', 'serial', serial, fields)
+
+const listIdocHouses = () =>
+  query(`SELECT ${HOUSE_COLS} FROM shard_houses WHERE is_idoc = 1 ORDER BY updated_at DESC`)
+
+// Houses owned by any of the given game accounts (admin: a user's linked
+// accounts). IDOC houses first, then newest-refreshed. Empty list short-circuits.
+const listHousesByAccounts = (accounts) =>
+  accounts.length === 0
+    ? Promise.resolve([])
+    : query(
+        `SELECT ${HOUSE_REG_COLS} FROM shard_houses
+          WHERE owner_acct IN (${accounts.map(() => '?').join(', ')})
+          ORDER BY is_idoc DESC, updated_at DESC`,
+        accounts,
+      )
+
+// ── House registry (Protocol 2.0 house.update / house.remove) ──────────────
+// The registry columns extend HOUSE_COLS; a registry row is one we've seen via
+// house.update (in_registry = 1), as opposed to a decay-only transition row.
+const HOUSE_REG_COLS = `${HOUSE_COLS}, owner_name, co_owners, friends, price, decay, in_registry`
+
+const removeHouse = (serial) => query('DELETE FROM shard_houses WHERE serial = ?', [serial])
+
+// The full registered-house browser: every row we've seen via house.update.
+const listRegistryHouses = () =>
+  query(`SELECT ${HOUSE_REG_COLS} FROM shard_houses WHERE in_registry = 1 ORDER BY name ASC`)
+
+// ── Champion spawns ────────────────────────────────────────────────────────
+const CHAMP_COLS =
+  'serial, category, type, name, status, active, map, x, y, z, boss_up, payload, t, updated_at'
+
+const upsertChamp = (serial, fields) => upsertRow('shard_champs', 'serial', serial, fields)
+
+const removeChamp = (serial) => query('DELETE FROM shard_champs WHERE serial = ?', [serial])
+const clearChamps = () => query('DELETE FROM shard_champs')
+// Ordered by name (matches the sidecar's /champs ordering).
+const listChamps = () => query(`SELECT ${CHAMP_COLS} FROM shard_champs ORDER BY name ASC`)
+
+// ── Help-page (support) queue ──────────────────────────────────────────────
+const PAGE_COLS =
+  'page_id, type, sender_name, sender_acct, web_id, message, map, x, y, z, sent_ms, handled, handler, payload, updated_at'
+
+async function upsertPage(pageId, fields) {
+  const cols = Object.keys(fields)
+  const allCols = ['page_id', ...cols]
+  const insertCols = allCols.map((c) => `\`${c}\``).join(', ')
+  const placeholders = allCols.map(() => '?').join(', ')
+  const updates = cols.map((c) => `\`${c}\` = VALUES(\`${c}\`)`).join(', ')
+  await query(
+    `INSERT INTO shard_pages (${insertCols}) VALUES (${placeholders})
+     ON DUPLICATE KEY UPDATE ${updates}`,
+    [pageId, ...cols.map((c) => fields[c])],
+  )
+}
+
+const removePage = (pageId) => query('DELETE FROM shard_pages WHERE page_id = ?', [pageId])
+const clearPages = () => query('DELETE FROM shard_pages')
+// Oldest-open first so the queue reads like a work list.
+const listPages = () => query(`SELECT ${PAGE_COLS} FROM shard_pages ORDER BY sent_ms ASC`)
+
+// ── Guild board (Protocol 2.0) ─────────────────────────────────────────────
+const GUILD_COLS =
+  'id, name, abbr, members, online, alliance, leader_serial, leader_name, leader_acct, leader_web_id, payload, t, updated_at'
+
+const upsertGuild = (id, fields) => upsertRow('shard_guilds', 'id', id, fields)
+
+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`)
+
+// 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.
+const findGuildLedByActor = (serial, acct) =>
+  query(
+    `SELECT id, name, abbr, alliance, leader_name FROM shard_guilds
+      WHERE leader_serial = ? OR (leader_acct IS NOT NULL AND leader_acct = ?)
+      LIMIT 1`,
+    [serial ?? null, acct ?? null],
+  )
+
+// Guilds led by any of the given game accounts (admin: a user's linked accounts).
+const listGuildsLedByAccounts = (accounts) =>
+  accounts.length === 0
+    ? Promise.resolve([])
+    : query(
+        `SELECT id, name, abbr, alliance, leader_name FROM shard_guilds
+          WHERE leader_acct IN (${accounts.map(() => '?').join(', ')})
+          ORDER BY name ASC`,
+        accounts,
+      )
+
+// ── Governor board + term history (Protocol 2.0) ───────────────────────────
+const GOV_COLS =
+  'city, governor_serial, governor_name, governor_acct, governor_web_id, elect_serial, elect_name, elect_acct, election_phase, candidates, auto_pick_at, payload, t, updated_at'
+
+const upsertGovernor = (city, fields) => upsertRow('shard_governors', 'city', city, fields)
+
+const listGovernors = () => query(`SELECT ${GOV_COLS} FROM shard_governors ORDER BY city ASC`)
+
+// Cities whose current governor is one of the given game accounts (cross-link:
+// does this user hold a governorship?). Empty list short-circuits.
+const listGovernorshipsByAccounts = (accounts) =>
+  accounts.length === 0
+    ? Promise.resolve([])
+    : query(
+        `SELECT ${GOV_COLS} FROM shard_governors
+          WHERE governor_acct IN (${accounts.map(() => '?').join(', ')})
+          ORDER BY city ASC`,
+        accounts,
+      )
+
+// The single open term (ended_at IS NULL) for a city, if any.
+async function currentGovernorTerm(city) {
+  const rows = await query(
+    'SELECT id, city, governor_serial, governor_name, governor_acct, governor_web_id, started_at, ended_at, votes FROM shard_governor_terms WHERE city = ? AND ended_at IS NULL ORDER BY started_at DESC LIMIT 1',
+    [city],
+  )
+  return rows[0] || null
+}
+
+const closeGovernorTerm = (id, endedAt) =>
+  query('UPDATE shard_governor_terms SET ended_at = ? WHERE id = ?', [endedAt, id])
+
+const openGovernorTerm = ({ city, serial, name, acct, webId, startedAt }) =>
+  query(
+    `INSERT INTO shard_governor_terms
+       (city, governor_serial, governor_name, governor_acct, governor_web_id, started_at)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    [city, serial ?? null, name ?? null, acct ?? null, webId ?? null, startedAt],
+  )
+
+const listGovernorTerms = (city, limit) =>
+  query(
+    'SELECT id, city, governor_serial, governor_name, governor_acct, governor_web_id, started_at, ended_at, votes FROM shard_governor_terms WHERE city = ? ORDER BY started_at DESC LIMIT ?',
+    [city, limit],
+  )
+
+// ── Online-population snapshot (Protocol 2.0 presence.online) ───────────────
+async function setPresence({ count, byFacet, byRegion, t }) {
+  await query(
+    `INSERT INTO shard_presence (id, count, by_facet, by_region, t) VALUES (1, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE count = VALUES(count), by_facet = VALUES(by_facet),
+       by_region = VALUES(by_region), t = VALUES(t)`,
+    [
+      Number.isFinite(count) ? count : 0,
+      byFacet ? JSON.stringify(byFacet) : null,
+      byRegion ? JSON.stringify(byRegion) : null,
+      Number.isFinite(t) ? t : null,
+    ],
+  )
+}
+
+async function latestPresence() {
+  const rows = await query('SELECT count, by_facet, by_region, t FROM shard_presence WHERE id = 1')
+  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
+}
+
+// ── Points/loyalty boards (Protocol 3.0 points.board) ──────────────────────
+// One row per point system. The shard only emits a system whose top N actually
+// moved, so this is a sparse stream of overwrites; there is no delete, because
+// the shard's set of systems is fixed at startup.
+async function upsertPointsBoard({ system, name, nameCliloc, maxPoints, players, showOnGump, payload, t }) {
+  await query(
+    `INSERT INTO shard_points_boards
+       (system, name, name_cliloc, max_points, players, show_on_gump, payload, t)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE name = VALUES(name), name_cliloc = VALUES(name_cliloc),
+       max_points = VALUES(max_points), players = VALUES(players),
+       show_on_gump = VALUES(show_on_gump), payload = VALUES(payload), t = VALUES(t)`,
+    [
+      system,
+      name ?? null,
+      Number.isFinite(nameCliloc) ? nameCliloc : null,
+      Number.isFinite(maxPoints) ? maxPoints : null,
+      Number.isFinite(players) ? players : null,
+      showOnGump ? 1 : 0,
+      payload,
+      Number.isFinite(t) ? t : null,
+    ],
+  )
+}
+
+// Ordered by display name, falling back to the system key for a board whose name
+// arrived as a bare cliloc — otherwise every unresolved board would sort together
+// under NULL.
+async function listPointsBoards() {
+  return query(
+    `SELECT system, name, name_cliloc, max_points, players, show_on_gump, payload, t, updated_at
+       FROM shard_points_boards ORDER BY COALESCE(name, system), system`,
+  )
+}
+
+async function getPointsBoard(system) {
+  const rows = await query(
+    `SELECT system, name, name_cliloc, max_points, players, show_on_gump, payload, t, updated_at
+       FROM shard_points_boards WHERE system = ?`,
+    [system],
+  )
+  return rows[0] || null
+}
+
+module.exports = {
+  upsertOnline,
+  removeOnline,
+  clearOnline,
+  countOnline,
+  listOnline,
+  listOnlineLinked,
+  listOnlineByAccounts,
+  insertEconomy,
+  listEconomy,
+  latestEconomy,
+  upsertHouse,
+  listIdocHouses,
+  listHousesByAccounts,
+  removeHouse,
+  listRegistryHouses,
+  upsertGuild,
+  removeGuild,
+  clearGuilds,
+  listGuilds,
+  findGuildLedByActor,
+  listGuildsLedByAccounts,
+  upsertGovernor,
+  listGovernors,
+  listGovernorshipsByAccounts,
+  currentGovernorTerm,
+  closeGovernorTerm,
+  openGovernorTerm,
+  listGovernorTerms,
+  setPresence,
+  latestPresence,
+  setRuleset,
+  getRuleset,
+  upsertPointsBoard,
+  listPointsBoards,
+  getPointsBoard,
+  upsertChamp,
+  removeChamp,
+  clearChamps,
+  listChamps,
+  upsertPage,
+  removePage,
+  clearPages,
+  listPages,
+}

server/model/shardState/shardState.model.js

@@ -0,0 +1,638 @@
+// Live shard state derived from the WS feed: who is online, the gold-supply
+// series, and per-house decay stage. The ingest dispatcher calls the write
+// methods; the public read endpoints call the list/count methods. Writes take
+// camelCase semantic objects and map to the snake_case columns; only the keys
+// present are written (so a char.vitals refresh doesn't clobber login fields).
+
+const db = require('./shardState.db')
+
+const MAX_ECONOMY = 1000
+
+// Small coercion helpers, kept out of the upsert builders below so those stay
+// flat (each inline `?? null` / ternary otherwise adds to cognitive complexity).
+const orNull = (v) => v ?? null
+const toDate = (v) => (v ? new Date(v) : null)
+// Owner is an actor object (or null for an abandoned house); flatten to columns.
+const ownerFields = (owner) => ({
+  owner_serial: orNull(owner?.serial),
+  owner_acct: orNull(owner?.acct),
+  owner_name: orNull(owner?.name),
+})
+
+// Map a camelCase online descriptor to DB columns, dropping undefined keys so a
+// partial refresh only touches the fields it carries.
+function onlineFields(data) {
+  const map = {
+    name: data.name,
+    acct: data.acct,
+    web_id: data.webId,
+    map: data.map,
+    x: data.x,
+    y: data.y,
+    z: data.z,
+    hits: data.hits,
+    hits_max: data.hitsMax,
+    mana: data.mana,
+    mana_max: data.manaMax,
+    stam: data.stam,
+    stam_max: data.stamMax,
+    str: data.str,
+    dex: data.dex,
+    int: data.int,
+  }
+  const fields = {}
+  for (const [k, v] of Object.entries(map)) if (v !== undefined) fields[k] = v
+  return fields
+}
+
+// Upsert an online player (mob.login) or refresh their vitals (char.vitals).
+async function upsertOnline(data) {
+  if (!data || !data.serial) return
+  await db.upsertOnline(data.serial, onlineFields(data))
+}
+
+const setOffline = (serial) => db.removeOnline(serial)
+const clearOnline = () => db.clearOnline()
+const onlineCount = () => db.countOnline()
+
+function shapeOnline(r) {
+  return {
+    serial: r.serial,
+    name: r.name,
+    acct: r.acct,
+    webId: r.web_id,
+    map: r.map,
+    x: r.x,
+    y: r.y,
+    z: r.z,
+    hits: r.hits,
+    hitsMax: r.hits_max,
+    mana: r.mana,
+    manaMax: r.mana_max,
+    stam: r.stam,
+    stamMax: r.stam_max,
+    str: r.str,
+    dex: r.dex,
+    int: r.int,
+    updatedAt: r.updated_at,
+  }
+}
+
+// Only players whose account is linked to a website user (opt-in visibility).
+async function listOnlineLinked() {
+  const rows = await db.listOnlineLinked()
+  return rows.map(shapeOnline)
+}
+
+async function listOnline() {
+  const rows = await db.listOnline()
+  return rows.map(shapeOnline)
+}
+
+// Append a gold-supply sample (economy.supply).
+async function addEconomySample({ accounts, gold, t }) {
+  await db.insertEconomy({ accounts, gold, t })
+}
+
+async function listEconomy(limit = 100) {
+  const n = Math.min(Math.max(Number(limit) || 100, 1), MAX_ECONOMY)
+  const rows = await db.listEconomy(n)
+  // Return oldest → newest for charting.
+  return rows
+    .map((r) => ({ accounts: r.accounts, gold: r.gold == null ? null : Number(r.gold), t: r.t }))
+    .reverse()
+}
+
+async function latestEconomy() {
+  const r = await db.latestEconomy()
+  return r ? { accounts: r.accounts, gold: r.gold == null ? null : Number(r.gold), t: r.t } : null
+}
+
+// Upsert a house's decay stage (house.decay). is_idoc is derived from the stage.
+async function upsertHouse(data) {
+  if (!data || !data.serial) return
+  const fields = {
+    stage: data.stage ?? null,
+    map: data.map ?? null,
+    x: data.x ?? null,
+    y: data.y ?? null,
+    z: data.z ?? null,
+    region: data.region ?? null,
+    name: data.name ?? null,
+    owner_serial: data.ownerSerial ?? null,
+    owner_acct: data.ownerAcct ?? null,
+    built_on: data.builtOn ? new Date(data.builtOn) : null,
+    last_refreshed: data.lastRefreshed ? new Date(data.lastRefreshed) : null,
+    is_idoc: String(data.stage).toUpperCase() === 'IDOC' ? 1 : 0,
+  }
+  await db.upsertHouse(data.serial, fields)
+}
+
+function shapeHouse(r) {
+  return {
+    serial: r.serial,
+    stage: r.stage,
+    map: r.map,
+    x: r.x,
+    y: r.y,
+    z: r.z,
+    region: r.region,
+    name: r.name,
+    ownerSerial: r.owner_serial,
+    ownerAcct: r.owner_acct,
+    // Registry fields (Protocol 2.0 house.update); undefined on decay-only rows.
+    ownerName: r.owner_name,
+    coOwners: r.co_owners,
+    friends: r.friends,
+    price: r.price == null ? null : Number(r.price),
+    decay: r.decay,
+    inRegistry: r.in_registry == null ? undefined : Boolean(r.in_registry),
+    builtOn: r.built_on,
+    lastRefreshed: r.last_refreshed,
+    isIdoc: Boolean(r.is_idoc),
+    updatedAt: r.updated_at,
+  }
+}
+
+async function listIdoc() {
+  const rows = await db.listIdocHouses()
+  return rows.map(shapeHouse)
+}
+
+// Houses owned by the given game accounts (admin: a user's linked accounts).
+async function listHousesForAccounts(accounts) {
+  const rows = await db.listHousesByAccounts(accounts)
+  return rows.map(shapeHouse)
+}
+
+// ── House registry (Protocol 2.0 house.update / house.remove) ──────────────
+// Richer per-house snapshot than the decay-transition feed. Writes only the
+// registry columns (+ shared location/owner fields); is_idoc/stage stay owned by
+// the house.decay path, so the two feeds never clobber each other. owner is an
+// actor object (or null for an abandoned house).
+async function upsertHouseRegistry(data) {
+  if (!data || !data.serial) return
+  const fields = {
+    name: orNull(data.name),
+    ...ownerFields(data.owner || null),
+    co_owners: orNull(data.coOwners),
+    friends: orNull(data.friends),
+    price: orNull(data.price),
+    decay: orNull(data.decay),
+    region: orNull(data.region),
+    map: orNull(data.map),
+    x: orNull(data.x),
+    y: orNull(data.y),
+    z: orNull(data.z),
+    built_on: toDate(data.builtOn),
+    last_refreshed: toDate(data.lastRefreshed),
+    in_registry: 1,
+  }
+  await db.upsertHouse(data.serial, fields)
+}
+
+const removeHouse = (serial) => (serial ? db.removeHouse(serial) : Promise.resolve())
+
+async function listHouses() {
+  const rows = await db.listRegistryHouses()
+  return rows.map(shapeHouse)
+}
+
+// Online players on the given game accounts (admin: a user's linked accounts).
+async function listOnlineForAccounts(accounts) {
+  const rows = await db.listOnlineByAccounts(accounts)
+  return rows.map(shapeOnline)
+}
+
+// ── Champion spawns ────────────────────────────────────────────────────────
+// Upsert a champ spawn's state (champ.update). The full event is stored in
+// `payload` for the category-specific fields; a few columns are hoisted out for
+// querying/ordering. is-boss-up is derived from bossUp (sea bosses are always up).
+async function upsertChamp(ev) {
+  if (!ev || !ev.serial) return
+  await db.upsertChamp(ev.serial, {
+    category: orNull(ev.category),
+    type: orNull(ev.type),
+    name: orNull(ev.name),
+    status: orNull(ev.status),
+    active: ev.active ? 1 : 0,
+    map: orNull(ev.map),
+    x: orNull(ev.x),
+    y: orNull(ev.y),
+    z: orNull(ev.z),
+    boss_up: ev.bossUp ? 1 : 0,
+    payload: JSON.stringify(ev),
+    t: Number.isFinite(ev.t) ? ev.t : null,
+  })
+}
+
+const removeChamp = (serial) => (serial ? db.removeChamp(serial) : Promise.resolve())
+const clearChamps = () => db.clearChamps()
+
+// Return the stored champ.update payload (the shape the sidecar/UI expect),
+// falling back to the hoisted columns if an older row lacks a payload.
+function shapeChamp(r) {
+  const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload
+  return payload || {
+    kind: 'champ.update',
+    serial: r.serial,
+    category: r.category,
+    type: r.type,
+    name: r.name,
+    status: r.status,
+    active: Boolean(r.active),
+    map: r.map,
+    x: r.x,
+    y: r.y,
+    z: r.z,
+    bossUp: Boolean(r.boss_up),
+    t: r.t,
+  }
+}
+
+async function listChamps() {
+  const rows = await db.listChamps()
+  return rows.map(shapeChamp)
+}
+
+// Replace the whole board with a fresh snapshot (sidecar GET /champs on connect).
+async function replaceChamps(spawns) {
+  await db.clearChamps()
+  for (const ev of spawns || []) await upsertChamp(ev)
+}
+
+// ── Help-page (support) queue ──────────────────────────────────────────────
+// Upsert a page (page.new / page.updated). The `sender` actor object carries the
+// name/acct/webId; the rest are top-level fields.
+async function upsertPage(ev) {
+  const pageId = ev && (ev.pageId || (ev.sender && ev.sender.serial))
+  if (!pageId) return
+  const sender = ev.sender || {}
+  await db.upsertPage(pageId, {
+    type: orNull(ev.type),
+    sender_name: orNull(sender.name),
+    sender_acct: orNull(sender.acct),
+    web_id: orNull(sender.webId),
+    message: orNull(ev.message),
+    map: orNull(ev.map),
+    x: orNull(ev.x),
+    y: orNull(ev.y),
+    z: orNull(ev.z),
+    sent_ms: Number.isFinite(ev.sentMs) ? ev.sentMs : null,
+    handled: ev.handled ? 1 : 0,
+    handler: orNull(ev.handler),
+    payload: JSON.stringify(ev),
+  })
+}
+
+const removePage = (pageId) => (pageId ? db.removePage(pageId) : Promise.resolve())
+const clearPages = () => db.clearPages()
+
+function shapePage(r) {
+  const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload
+  return {
+    pageId: r.page_id,
+    type: r.type,
+    sender: { serial: r.page_id, name: r.sender_name, acct: r.sender_acct, webId: r.web_id },
+    message: r.message,
+    map: r.map,
+    x: r.x,
+    y: r.y,
+    z: r.z,
+    sentMs: r.sent_ms == null ? null : Number(r.sent_ms),
+    handled: Boolean(r.handled),
+    handler: r.handler,
+    updatedAt: r.updated_at,
+    // Keep the raw payload available for any field not hoisted above.
+    payload: payload || undefined,
+  }
+}
+
+async function listPages() {
+  const rows = await db.listPages()
+  return rows.map(shapePage)
+}
+
+// Replace the whole queue with a fresh snapshot (sidecar GET /pages on connect).
+async function replacePages(pages) {
+  await db.clearPages()
+  for (const ev of pages || []) await upsertPage(ev)
+}
+
+// ── Guild board (Protocol 2.0) ─────────────────────────────────────────────
+// Upsert a guild's roster snapshot (guild.update). The leader is an actor object
+// flattened into leader_* columns; the full event lives in `payload`.
+async function upsertGuild(ev) {
+  if (!ev || ev.id == null) return
+  const leader = ev.leader || {}
+  await db.upsertGuild(ev.id, {
+    name: ev.name ?? null,
+    abbr: ev.abbr ?? null,
+    members: ev.members ?? null,
+    online: ev.online ?? null,
+    alliance: ev.alliance ?? null,
+    leader_serial: leader.serial ?? null,
+    leader_name: leader.name ?? null,
+    leader_acct: leader.acct ?? null,
+    leader_web_id: leader.webId ?? null,
+    payload: JSON.stringify(ev),
+    t: Number.isFinite(ev.t) ? ev.t : null,
+  })
+}
+
+const removeGuild = (id) => (id == null ? Promise.resolve() : db.removeGuild(id))
+const clearGuilds = () => db.clearGuilds()
+
+function shapeGuild(r) {
+  const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload
+  return payload || {
+    kind: 'guild.update',
+    id: r.id,
+    name: r.name,
+    abbr: r.abbr,
+    members: r.members,
+    online: r.online,
+    alliance: r.alliance,
+    leader: r.leader_serial
+      ? { serial: r.leader_serial, name: r.leader_name, acct: r.leader_acct, webId: r.leader_web_id }
+      : null,
+    t: r.t,
+  }
+}
+
+async function listGuilds() {
+  const rows = await db.listGuilds()
+  return rows.map(shapeGuild)
+}
+
+// Replace the board with a fresh snapshot (sidecar GET /guilds on connect).
+async function replaceGuilds(guilds) {
+  await db.clearGuilds()
+  for (const ev of guilds || []) await upsertGuild(ev)
+}
+
+// The guild an actor leads (cross-link on the character sheet). Leadership only —
+// see the db note; membership for rank-and-file isn't in the feed, so we return
+// null rather than show a possibly-stale guess.
+async function findGuildForActor({ serial, acct }) {
+  const rows = await db.findGuildLedByActor(serial ?? null, acct ?? null)
+  const g = rows[0]
+  if (!g) return null
+  return { id: g.id, name: g.name, abbr: g.abbr, alliance: g.alliance, role: 'leader' }
+}
+
+// Guilds led by any of a user's linked accounts (admin user-detail cross-link).
+async function listGuildsLedForAccounts(accounts) {
+  const rows = await db.listGuildsLedByAccounts(accounts)
+  return rows.map((g) => ({ id: g.id, name: g.name, abbr: g.abbr, alliance: g.alliance, leaderName: g.leader_name }))
+}
+
+// ── Town governors (Protocol 2.0) ──────────────────────────────────────────
+// Upsert a city's governance snapshot (city.update) AND capture term history.
+// Term capture runs first (it reads the CURRENT open term to decide whether the
+// governor changed) and is idempotent: a repeat/backfill of the same governor is a
+// no-op, so it's safe to call on the live feed and on reconnect snapshots alike.
+async function upsertGovernor(ev) {
+  if (!ev || !ev.city) return
+  await recordGovernorTransition(ev)
+  const gov = ev.governor
+  const elect = ev.governorElect
+  await db.upsertGovernor(ev.city, {
+    governor_serial: orNull(gov?.serial),
+    governor_name: orNull(gov?.name),
+    governor_acct: orNull(gov?.acct),
+    governor_web_id: orNull(gov?.webId),
+    elect_serial: orNull(elect?.serial),
+    elect_name: orNull(elect?.name),
+    elect_acct: orNull(elect?.acct),
+    election_phase: orNull(ev.electionPhase),
+    candidates: orNull(ev.candidates),
+    auto_pick_at: toDate(ev.autoPickAt),
+    payload: JSON.stringify(ev),
+    t: Number.isFinite(ev.t) ? ev.t : null,
+  })
+}
+
+// Close the open term and open a new one when the governor CHANGES. Idempotent:
+// same governor as the open term ⇒ nothing happens (so backfill/duplicate
+// city.update events never spawn spurious terms).
+async function recordGovernorTransition(ev) {
+  const gov = ev.governor || null
+  const newSerial = gov ? gov.serial ?? null : null
+  const t = Number.isFinite(ev.t) ? ev.t : Date.now()
+  const open = await db.currentGovernorTerm(ev.city)
+  const openSerial = open ? open.governor_serial : null
+  if (open && openSerial === newSerial) return // unchanged — nothing to record
+  if (open) await db.closeGovernorTerm(open.id, t) // governor changed or seat vacated
+  if (newSerial) {
+    await db.openGovernorTerm({
+      city: ev.city,
+      serial: newSerial,
+      name: gov.name ?? null,
+      acct: gov.acct ?? null,
+      webId: gov.webId ?? null,
+      startedAt: t,
+    })
+  }
+}
+
+function shapeGovernor(r) {
+  const payload = typeof r.payload === 'string' ? safeJson(r.payload) : r.payload
+  return payload || {
+    kind: 'city.update',
+    city: r.city,
+    governor: r.governor_serial
+      ? { serial: r.governor_serial, name: r.governor_name, acct: r.governor_acct, webId: r.governor_web_id }
+      : null,
+    governorElect: r.elect_serial
+      ? { serial: r.elect_serial, name: r.elect_name, acct: r.elect_acct }
+      : null,
+    electionPhase: r.election_phase,
+    candidates: r.candidates,
+    t: r.t,
+  }
+}
+
+async function listGovernors() {
+  const rows = await db.listGovernors()
+  return rows.map(shapeGovernor)
+}
+
+// Cities the given game accounts currently govern (cross-link badge).
+async function listGovernorshipsForAccounts(accounts) {
+  const rows = await db.listGovernorshipsByAccounts(accounts)
+  return rows.map(shapeGovernor)
+}
+
+// Term history for a city (look-back), newest first.
+async function listGovernorHistory(city, limit = 100) {
+  const n = Math.min(Math.max(Number(limit) || 100, 1), 500)
+  const rows = await db.listGovernorTerms(city, n)
+  return rows.map((r) => ({
+    city: r.city,
+    governor: r.governor_serial
+      ? { serial: r.governor_serial, name: r.governor_name, acct: r.governor_acct, webId: r.governor_web_id }
+      : null,
+    startedAt: r.started_at == null ? null : Number(r.started_at),
+    endedAt: r.ended_at == null ? null : Number(r.ended_at),
+    votes: r.votes,
+  }))
+}
+
+// Upsert governors without clearing (cities are fixed, no remove event); term
+// capture inside upsertGovernor stays idempotent across reconnect snapshots.
+async function replaceGovernors(cities) {
+  for (const ev of cities || []) await upsertGovernor(ev)
+}
+
+// ── Online-population snapshot (Protocol 2.0 presence.online) ───────────────
+async function setPresence(ev) {
+  if (!ev) return
+  await db.setPresence({
+    count: ev.count,
+    byFacet: ev.byFacet || null,
+    byRegion: ev.byRegion || null,
+    t: ev.t,
+  })
+}
+
+async function latestPresence() {
+  const r = await db.latestPresence()
+  if (!r) return { count: 0, byFacet: {}, byRegion: {}, t: null }
+  const parse = (v) => (typeof v === 'string' ? safeJson(v) || {} : v || {})
+  return {
+    count: Number(r.count) || 0,
+    byFacet: parse(r.by_facet),
+    byRegion: parse(r.by_region),
+    t: r.t == null ? null : Number(r.t),
+  }
+}
+
+// ── 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 }
+}
+
+// ── Points/loyalty boards (Protocol 3.0 points.board) ──────────────────────
+//
+// The whole frame is stored in `payload`; the columns beside it are hoisted for
+// listing and ordering only. The top-N list deliberately stays inside the payload
+// (see schema.sql) — it is a fixed-size list read whole, like the governor board's
+// candidates.
+async function upsertPointsBoard(ev) {
+  if (!ev || !ev.system) return
+  await db.upsertPointsBoard({
+    system: String(ev.system).slice(0, 48),
+    name: ev.nameString ?? null,
+    nameCliloc: ev.nameNumber,
+    maxPoints: ev.maxPoints,
+    players: ev.players,
+    showOnGump: ev.showOnGump !== false,
+    payload: JSON.stringify(ev),
+    t: ev.t,
+  })
+}
+
+// A stored frame plus the freshness stamp. `top` is normalized to an array so a
+// caller never has to guard it — a board with nobody on it is a real state (a
+// system nobody has scored in yet), distinct from a system that was never
+// published at all, which is absent from the table entirely.
+function shapePointsBoard(r) {
+  const payload = (typeof r.payload === 'string' ? safeJson(r.payload) : r.payload) || {}
+  return {
+    ...payload,
+    system: r.system,
+    top: Array.isArray(payload.top) ? payload.top : [],
+    updatedAt: r.updated_at,
+  }
+}
+
+async function listPointsBoards() {
+  const rows = await db.listPointsBoards()
+  return rows.map(shapePointsBoard)
+}
+
+async function getPointsBoard(system) {
+  const r = await db.getPointsBoard(system)
+  return r ? shapePointsBoard(r) : null
+}
+
+function safeJson(s) {
+  try {
+    return JSON.parse(s)
+  } catch {
+    return null
+  }
+}
+
+module.exports = {
+  upsertOnline,
+  setOffline,
+  clearOnline,
+  onlineCount,
+  listOnline,
+  listOnlineLinked,
+  listOnlineForAccounts,
+  addEconomySample,
+  listEconomy,
+  latestEconomy,
+  upsertHouse,
+  listIdoc,
+  listHousesForAccounts,
+  upsertHouseRegistry,
+  removeHouse,
+  listHouses,
+  upsertChamp,
+  removeChamp,
+  clearChamps,
+  listChamps,
+  replaceChamps,
+  upsertPage,
+  removePage,
+  clearPages,
+  listPages,
+  replacePages,
+  upsertGuild,
+  removeGuild,
+  clearGuilds,
+  listGuilds,
+  replaceGuilds,
+  findGuildForActor,
+  listGuildsLedForAccounts,
+  upsertGovernor,
+  listGovernors,
+  listGovernorshipsForAccounts,
+  listGovernorHistory,
+  replaceGovernors,
+  setPresence,
+  latestPresence,
+  setRuleset,
+  getRuleset,
+  upsertPointsBoard,
+  listPointsBoards,
+  getPointsBoard,
+}

server/model/shardVisibility/shardVisibility.db.js

@@ -0,0 +1,37 @@
+const { query } = require('../../core')
+
+// One row per shard feature. Absent rows are fine — utils/shardVisibility.js
+// compiles a default for every known feature and merges stored rows over it, so
+// a fresh install with an empty table behaves exactly as the site did pre-v3.
+
+const COLS = 'feature, enabled, audience, stream, field_rules, updated_by, updated_at'
+
+const listAll = () => query(`SELECT ${COLS} FROM shard_feature_visibility`)
+
+const getOne = (feature) =>
+  query(`SELECT ${COLS} FROM shard_feature_visibility WHERE feature = ?`, [feature])
+
+// Upsert one feature's settings. `fieldRules` is stored as a JSON object of
+// {field: rung}; the caller has already stripped locked fields and validated
+// every rung against the ladder.
+const upsert = ({ feature, enabled, audience, stream, fieldRules, updatedBy }) =>
+  query(
+    `INSERT INTO shard_feature_visibility (feature, enabled, audience, stream, field_rules, updated_by)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE
+       enabled     = VALUES(enabled),
+       audience    = VALUES(audience),
+       stream      = VALUES(stream),
+       field_rules = VALUES(field_rules),
+       updated_by  = VALUES(updated_by)`,
+    [
+      feature,
+      enabled ? 1 : 0,
+      audience,
+      stream ? 1 : 0,
+      fieldRules == null ? null : JSON.stringify(fieldRules),
+      updatedBy ?? null,
+    ],
+  )
+
+module.exports = { listAll, getOne, upsert }

server/model/shardVisibility/shardVisibility.model.js

@@ -0,0 +1,44 @@
+// ── Shard feature visibility (model) ───────────────────────────────────────
+//
+// Thin row-shaping layer over shardVisibility.db. The policy — the ladder, the
+// feature catalog, the locked fields, the kind→feature map — lives in
+// utils/shardVisibility.js; this file only reads and writes rows.
+
+const db = require('./shardVisibility.db')
+
+// The `field_rules` JSON column comes back as a string on the mariadb driver.
+function parseRules(raw) {
+  if (raw == null) return {}
+  if (typeof raw === 'object') return raw
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+const toSafe = (row) =>
+  row && {
+    feature: row.feature,
+    enabled: !!row.enabled,
+    audience: row.audience,
+    stream: row.stream == null ? null : !!row.stream,
+    fieldRules: parseRules(row.field_rules),
+    updatedBy: row.updated_by,
+    updatedAt: row.updated_at,
+  }
+
+async function listAll() {
+  const rows = await db.listAll()
+  return rows.map(toSafe)
+}
+
+async function getOne(feature) {
+  const rows = await db.getOne(feature)
+  return toSafe(rows[0])
+}
+
+const upsert = (entry) => db.upsert(entry)
+
+module.exports = { listAll, getOne, upsert }

server/model/singletonConfigDb.js

@@ -0,0 +1,35 @@
+const { query } = require('../core')
+
+// Factory for the singleton config tables (bot_config, email_config,
+// uo_link_config). Each is a one-row table keyed on id = 1: `get()` returns the
+// row (or null before the admin first saves it), and `upsert()` writes only the
+// columns the model prepared, leaving the rest untouched. The three tables share
+// this shape exactly, so the DB layer is generated rather than copy-pasted —
+// only the table name and column list differ.
+//
+// `fields` are already prepared by the model (secrets pre-encrypted); ordering
+// and encryption stay a model-layer concern.
+function singletonConfigDb(table, cols) {
+  async function get() {
+    const rows = await query(`SELECT ${cols} FROM ${table} WHERE id = 1 LIMIT 1`)
+    return rows[0] || null
+  }
+
+  async function upsert(fields) {
+    const columns = Object.keys(fields)
+    const vals = columns.map((c) => fields[c])
+    const insertCols = ['id', ...columns].map((c) => `\`${c}\``).join(', ')
+    const placeholders = ['1', ...columns.map(() => '?')].join(', ')
+    const updates = columns.map((c) => `\`${c}\` = VALUES(\`${c}\`)`).join(', ')
+    await query(
+      `INSERT INTO ${table} (${insertCols}) VALUES (${placeholders})
+       ON DUPLICATE KEY UPDATE ${updates}`,
+      vals,
+    )
+    return get()
+  }
+
+  return { get, upsert }
+}
+
+module.exports = singletonConfigDb

server/model/uoLinkConfig/uoLinkConfig.db.js

@@ -0,0 +1,7 @@
+const singletonConfigDb = require('../singletonConfigDb')
+
+const COLS =
+  'id, base_url, ws_url, auth_token_enc, protocol, enabled, status, status_detail, plugin_connected, last_event_at, boot_id, updated_by, created_at, updated_at'
+
+// Singleton row (id = 1). See ../singletonConfigDb for the get/upsert contract.
+module.exports = singletonConfigDb('uo_link_config', COLS)

server/model/uoLinkConfig/uoLinkConfig.model.js

@@ -0,0 +1,88 @@
+// uo-link sidecar connection config store. Mirrors botConfig/emailConfig: the DB
+// layer only ever sees ciphertext, and only getWithToken() (used server-side to
+// call the sidecar over REST/WS) decrypts it. The admin-facing getSafe() never
+// includes the token — it exposes only `hasToken`. A blank `token` on save means
+// "leave the existing token unchanged" (same convention as the other configs).
+
+const db = require('./uoLinkConfig.db')
+const { secretBox } = require('../../core')
+
+// The wire protocol this build speaks (link/sidecar/src/main.rs PROTOCOL_VERSION).
+// Only used before an admin has saved anything — the stored row wins once it exists,
+// and UOLINK_PROTOCOL still overrides for an operator running an older sidecar.
+const DEFAULT_PROTOCOL = Number(process.env.UOLINK_PROTOCOL) || 3
+
+function toSafe(row) {
+  if (!row) {
+    return {
+      baseUrl: process.env.UOLINK_BASE_URL || null,
+      wsUrl: process.env.UOLINK_WS_URL || null,
+      protocol: DEFAULT_PROTOCOL,
+      enabled: false,
+      hasToken: false,
+      status: 'disconnected',
+      statusDetail: null,
+      pluginConnected: false,
+      lastEventAt: null,
+      bootId: null,
+    }
+  }
+  return {
+    baseUrl: row.base_url || null,
+    wsUrl: row.ws_url || null,
+    protocol: row.protocol || DEFAULT_PROTOCOL,
+    enabled: Boolean(row.enabled),
+    hasToken: Boolean(row.auth_token_enc),
+    status: row.status || 'disconnected',
+    statusDetail: row.status_detail || null,
+    pluginConnected: Boolean(row.plugin_connected),
+    lastEventAt: row.last_event_at || null,
+    bootId: row.boot_id || null,
+  }
+}
+
+async function getSafe() {
+  return toSafe(await db.get())
+}
+
+// Decrypted token included — server-side only (calling the sidecar's REST/WS
+// API). Returns null when nothing has been saved yet.
+async function getWithToken() {
+  const row = await db.get()
+  if (!row) return null
+  return { ...toSafe(row), token: row.auth_token_enc ? secretBox.decrypt(row.auth_token_enc) : null }
+}
+
+// Save admin-supplied config. `token` undefined or '' means "leave the existing
+// token unchanged" (same convention as botConfig.save).
+async function save({ baseUrl, wsUrl, token, protocol, enabled, updatedBy }) {
+  const fields = {}
+  if (baseUrl !== undefined) fields.base_url = baseUrl
+  if (wsUrl !== undefined) fields.ws_url = wsUrl
+  if (token) fields.auth_token_enc = secretBox.encrypt(token)
+  if (protocol !== undefined) fields.protocol = protocol
+  if (enabled !== undefined) fields.enabled = enabled ? 1 : 0
+  if (updatedBy !== undefined) fields.updated_by = updatedBy
+  const row = await db.upsert(fields)
+  return toSafe(row)
+}
+
+// Mirror the sidecar's last-reported connection state into the DB so the admin
+// panel has something to show between polls and the public status endpoint can
+// read it without a live round-trip.
+async function recordStatus({ status, statusDetail, pluginConnected, lastEventAt, bootId }) {
+  const fields = {}
+  if (status !== undefined) fields.status = status
+  if (statusDetail !== undefined) fields.status_detail = statusDetail
+  if (pluginConnected !== undefined) fields.plugin_connected = pluginConnected ? 1 : 0
+  // lastEventAt may arrive as an ISO string (e.g. "2026-07-10T22:08:27Z"); the
+  // mariadb DATETIME parser rejects the "T"/"Z", so hand it a real Date (same
+  // fix as botConfig.recordStatus's last_connected_at).
+  if (lastEventAt !== undefined) fields.last_event_at = lastEventAt ? new Date(lastEventAt) : null
+  if (bootId !== undefined) fields.boot_id = bootId
+  if (Object.keys(fields).length === 0) return getSafe()
+  const row = await db.upsert(fields)
+  return toSafe(row)
+}
+
+module.exports = { getSafe, getWithToken, save, recordStatus }