refactor(atlas): derive the atlas from the shard's tree on every boot

Replaces the committed-artifact design from the first commit. Two problems with it, both raised in review: **Facets are not a fixed list.** The first pass carried a hardcoded table of the six stock UO facets to reconcile the spelling drift between sources. That is wrong: a shard may add facets, replace them outright, or rename them when its maps are updated, and a built-in list quietly mishandles all three. Nothing in the atlas names a facet any more. The facet set is discovered from the tree — spawn records and region definitions are the authority — and the loose spellings in Data/Locations are matched against it by key and prefix. Custom facets get identical treatment; the tests use `Sosaria` and `Underdark` precisely so a stock-facet assumption cannot creep back in. **A snapshot goes stale.** Maps change over a server's life, so a build-once artifact silently drifts from the world players actually see. The tree is now the single source of truth and the atlas is re-derived on every boot. ## What that changed - **The committed artifact is gone** — 1.41 MB of generated JSON removed, along with `scripts/buildSpawnAtlas.js` and the whole encode/decode seam it needed (`encodePoint`/`readPoint`, the tuple encoding, the omitted-defaults scheme and their round-trip tests). Nothing to keep in sync, nothing to go stale. - **NEW `src/utils/spawnAtlasSource.js`** — the only thing that touches a ServUO tree; shared by the boot path and the CLI. Parsers stay pure and fs-free. - **NEW `src/model/shardAtlas/`** — `.db.js` (the one-transaction replace) and `.model.js` (the refresh decision). - **`scripts/importSpawnAtlas.js`** is now a thin CLI over the model: `--servuo`, `--force`, `--approve`, `--reject`, `--status`. `atlas:build` is gone; `atlas:import` remains. - Path comes from the `spawn_atlas_servuo_path` admin setting, falling back to `SERVUO_PATH`. The setting wins, matching how the rest of the shard integration is admin-managed rather than env-configured. ## Two contracts on the boot path **It never blocks startup.** No path, an unreadable mount, a malformed file, a database error — every one is caught and logged, and the site comes up serving whatever atlas it already had. Verified by booting the real server with no path, a broken path, and a good path. **A facet disappearing is never 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 boot cannot tell them apart. The refresh is staged in `shard_atlas_pending` for an admin to approve or reject, and startup continues regardless. Additions and every other change apply immediately, since none of them can destroy something an operator would miss. Only the decision is stored, not the parsed world: a few KB of source hashes and the facet diff. Approving re-parses, so what gets applied matches the tree at approval time rather than at boot. A rejection is remembered against those exact hashes, so a declined refresh does not re-prompt on every restart — changing the tree changes the hashes and asks again. Hash-gated, so the common case (restart, maps unchanged) reads and hashes the tree (~120 ms) and writes nothing. A real change costs a ~400 ms parse. The admin approve/reject UI is part of the second PR, with the rest of the routes and pages. Until then the CLI covers it. ## Verification - **564 server tests pass**, 28 new in `spawnAtlas.source.test.js` covering the custom-facet build, the spelling reconciliation, hash gating, and every branch of the refresh decision — including that `refreshOnBoot` survives a database that throws on every call. - End-to-end against the local MariaDB and the real ServUO tree: 6,455 points, 800 creatures, 23,927 point/type rows, 387 regions, 558 landmarks, 25 altars, 83.2% of points resolved to a place name. - The facet gate exercised against a real tree copy with `malas.xml` removed: staged rather than applied, atlas untouched with all 293 Malas points intact, reject then stays quiet on re-run, approve applies and drops the facet. - Booted the real server under all three source conditions; none blocked. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP
2026-07-28 16:41:33 -05:00
parent 353cce9f26
commit 2801ec8f4d
22 changed files with 1528 additions and 1018 deletions
--- a/server/src/model/shardAtlas/shardAtlas.db.js
+++ b/server/src/model/shardAtlas/shardAtlas.db.js
@@ -0,0 +1,202 @@
+const { pool, query } = require('../../utils/db')
+
+// 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 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')
+}
+
+module.exports = {
+  replaceAtlas,
+  getMeta,
+  getFacets,
+  getPending,
+  setPending,
+  clearPending,
+}