feat(atlas): serve the spawn atlas and give operators a panel for it

Protocol 3.0 order 3 (Part C), second of two website PRs. #112 built the data
pipeline; this makes it reachable — six public routes, five admin ones, two
public pages and an admin panel. Still website-only: no plugin, no sidecar, no
new event kinds, no wire change.

The API sits at /api/v1/public/atlas, not under /public/shard. Nothing here
touches the sidecar, so the pages stay complete while the shard is down, and a
/shard prefix would imply a dependency the atlas does not have. Unlike /shard/*
it IS site-mode gated, like /posts and /wiki: a bestiary is site content.

Every route carries requireFeature('atlas') and projects its response. The atlas
feature declares no sensitive fields, so the projection is a no-op today — the
call is there because v3.md 3.6.1's rule is that the FIRST field needing a gate
should be covered by construction rather than by a retrofit.

Two bugs the UI surfaced, both fixed here:

Respawn delays were stored in the wrong unit, sometimes. XmlSpawner writes
MinDelay/MaxDelay in minutes and switches to seconds only when a delay does not
divide into whole minutes, flagging it per record with DelayInSec. A `5` means
five minutes on one spawner and five seconds on the next, both plausible, and
the pipeline stored the raw number. 170 of 6,455 stock spawners are second
flagged. The parser normalises to seconds; the API and UI carry seconds.

That exposed the hash gate as a trap. "Has the tree changed?" is the wrong
question on its own: an install whose maps never change would have kept serving
the old readings forever, because the only thing compared was the tree.
PARSER_VERSION is now stored beside the source hashes and a mismatch counts as
drift, so any future parse correction lands on the next boot.

Also renamed the detail route's spawn-point array to `spawners` — it was
`points`, which is the COUNT on the search route, so one key meant a number in
one place and an array in the other.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP

server/src/model/shardAtlas/shardAtlas.db.js

@@ -192,6 +192,185 @@ 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,
@@ -199,4 +378,13 @@ module.exports = {
   getPending,
   setPending,
   clearPending,
+  countCreatures,
+  listCreatures,
+  getCreature,
+  listCreaturePlaces,
+  listCreaturePoints,
+  listCreatureCompanions,
+  listRegions,
+  listLandmarks,
+  listChampions,
 }

server/src/model/shardAtlas/shardAtlas.model.js

@@ -6,6 +6,7 @@ const settings = require('../settings/settings.model')
 const { slugify } = require('../../utils/spawnAtlasParse')
 const {
   AtlasSourceError,
+  PARSER_VERSION,
   buildAtlas,
   hashSources,
   sameSources,
@@ -120,6 +121,14 @@ async function applyAtlas(atlas) {
  * `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
@@ -142,7 +151,11 @@ async function refresh({ force = false, approve = false, path: pathOverride = ''
     ? Object.fromEntries(Object.entries(meta.source).map(([label, v]) => [label, v.sha256]))
     : null
 
-  if (!force && sameSources(hashes, loaded)) {
+  // 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 }
   }
 
@@ -227,7 +240,9 @@ async function status({ path: pathOverride = '' } = {}) {
       const loaded = meta?.source
         ? Object.fromEntries(Object.entries(meta.source).map(([l, v]) => [l, v.sha256]))
         : null
-      drift = !sameSources(hashes, loaded)
+      // 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
     }
@@ -282,6 +297,173 @@ async function refreshOnBoot() {
   }
 }
 
+// ── 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,
@@ -293,4 +475,11 @@ module.exports = {
   pointTypeRows,
   loadArtMap,
   SETTING_KEY,
+  searchCreatures,
+  getCreature,
+  listRegions,
+  listLandmarks,
+  listChampions,
+  listFacets,
+  publicMeta,
 }