feat(events): the five world verbs an author sees (Phase 12a)

`uo.creature.spawn`, `uo.boss.spawn`, `uo.npc.place`, `uo.gate.open` and
`uo.decor.place`, over protocol 7's one command family. Five actions because
five is what an author has; one `perform`/`revert`/`reconcile` because on the
wire they are one thing.

Five new budget dimensions -- `uo.creatures`, `uo.bosses`, `uo.npcs`,
`uo.decor`, `uo.gate.minutes` -- all declared by THIS MODULE (org lead,
2026-09-07). Core meters whatever dimensions a module declares and holds no UO
knowledge, which is the whole of what MODULE_API means by game-agnostic. A gate
is priced in minutes rather than in gates: one standing all day and twelve
standing five minutes each are not the same imposition on a world.

`reconcile()` ASKS the shard, and is the one place in this file that must not
use `reconcileByBootId`. A crier line lives in shard memory, so a changed
`bootId` IS proof it is gone; a spawned creature is in the world SAVE and
survives the restart the stamp would report it lost by. Anything `world.owned`
does not list is gone -- safe only because the shard's registry and the objects
it describes are written by the same save.

Teardown reports `gone` as success and `refused` as failed. A creature a player
killed is the point of having spawned it, and a run that ended `incomplete`
because its event worked would be a report nobody could read. `refused` means
the shard denies this run ever owned the serial, so nothing will delete it
through this path and the row must land unresolved with a reason.

The atlas gains a decoration index, parsed from the shard's own
`Data/Decoration/**/*.cfg` -- 120 files, read RECURSIVELY because the real tree
nests two deep and a flat read would index a fraction of it while looking like
it worked. 313 distinct types. The decor verb resolves through it rather than
passing a type name through, which keeps the verb to this shard's own decoration
vocabulary AND fetches the item id: `Static` alone accounts for 5031 placements
under 1992 different graphics, so a bare type name places the wrong thing.
`PARSER_VERSION` -> 3, so an already-imported tree is re-read.

Two things the build found in code that had already shipped:

`uo.options.creatures` answered with the atlas SLUG -- unique, stable, and not
something the shard can build, because a creature is constructed from a ServUO
class name and `orc-brute` is not one. The atlas's `name` is the raw type token
from the spawn files, so the fix was to stop discarding the half that works.
Safe to change because Phase 12a is the source's first consumer; the file said
so when it shipped.

`uo.npc.place` could not be performed from its own required params. Both ends
refuse an oracle with neither a greeting nor a line, but both fields were
optional -- so a cross-field rule sat where no authoring form could render it.
The greeting is now `required`, which says the same thing in the contract
itself. Caught by the existing dry-run sweep, which is a better argument for
that test than anything written about it when it shipped.

605 tests pass. `swagger-fragment.json` is stale on `edge` already and this
phase adds no route, so it is left alone.

Refs: docs/link/v7.md, docs/website/EVENTS_PLAN.md Phase 12a

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

server/model/shardAtlas/shardAtlas.db.js

@@ -16,6 +16,7 @@ const ATLAS_TABLES = [
   'shard_regions',
   'shard_landmarks',
   'shard_champion_spawns',
+  'shard_decor_types',
 ]
 
 async function insertBatched(conn, sql, rows) {
@@ -103,6 +104,16 @@ async function replaceAtlas(atlas, art = {}) {
       ]),
     )
 
+    // Optional: a tree with no Data/Decoration leaves this empty rather than
+    // failing the import, and the decoration verb then simply has nothing to
+    // offer. `?? []` rather than a guard, so an atlas built by an older parser
+    // (no `decor` key at all) reloads cleanly instead of throwing here.
+    counts.decor = await insertBatched(
+      conn,
+      'INSERT INTO shard_decor_types (type, item_id, uses) VALUES (?,?,?)',
+      (atlas.decor ?? []).map((d) => [d.type, d.itemId ?? 0, d.uses ?? 0]),
+    )
+
     // 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
@@ -357,6 +368,38 @@ function listLandmarks({ facet = '', q = '' } = {}) {
   )
 }
 
+/**
+ * Every decoration type this shard uses, most-used first.
+ *
+ * Ordered by `uses` because a dropdown of 313 types needs the ones the shard
+ * actually reaches for at the top; the alphabetical tiebreak keeps the order
+ * stable across imports, which matters for a form an author scrolls.
+ */
+function listDecorTypes({ q = '' } = {}) {
+  const where = []
+  const params = []
+  if (q) {
+    where.push('type LIKE ?')
+    params.push(`%${q}%`)
+  }
+  return query(
+    `SELECT type, item_id, uses
+       FROM shard_decor_types
+       ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+      ORDER BY uses DESC, type ASC`,
+    params,
+  )
+}
+
+/** One decoration type, or nothing when this shard's files never name it. */
+async function getDecorType(type) {
+  const rows = await query(
+    'SELECT type, item_id, uses FROM shard_decor_types WHERE type = ?',
+    [type],
+  )
+  return rows[0] || null
+}
+
 function listChampions({ facet = '' } = {}) {
   const params = []
   let where = ''
@@ -388,5 +431,7 @@ module.exports = {
   listCreatureCompanions,
   listRegions,
   listLandmarks,
+  listDecorTypes,
+  getDecorType,
   listChampions,
 }

server/model/shardAtlas/shardAtlas.model.js

@@ -403,6 +403,38 @@ async function getCreature(slug, { facet = '', points = 200 } = {}) {
   }
 }
 
+/**
+ * Decoration types, shaped for a dropdown.
+ *
+ * `type` is both the value and the label: it is the ServUO class name and it is
+ * what the plugin constructs from, so showing the author anything else would
+ * put a name on the screen that does not appear in the refusal if the shard
+ * declines it.
+ */
+async function listDecorTypes(opts = {}) {
+  const rows = await db.listDecorTypes(opts)
+  return rows.map((r) => ({
+    type: r.type,
+    itemId: Number(r.item_id) || 0,
+    uses: Number(r.uses) || 0,
+  }))
+}
+
+/**
+ * One decoration type, or null.
+ *
+ * The events decoration verb resolves through this rather than passing a type
+ * name straight through, which does two things at once: it fetches the item id
+ * the graphic-holder classes need, and it keeps the verb to the vocabulary this
+ * shard's own decoration files use. A type the atlas has never seen is refused
+ * here rather than constructed there.
+ */
+async function getDecorType(type) {
+  const row = await db.getDecorType(String(type == null ? '' : type).trim())
+  if (!row) return null
+  return { type: row.type, itemId: Number(row.item_id) || 0, uses: Number(row.uses) || 0 }
+}
+
 async function listRegions(opts = {}) {
   const rows = await db.listRegions(opts)
   return rows.map((r) => ({
@@ -485,6 +517,8 @@ module.exports = {
   getCreature,
   listRegions,
   listLandmarks,
+  listDecorTypes,
+  getDecorType,
   listChampions,
   listFacets,
   publicMeta,