feat(events): schema, CRUD and the core action registry (Phase 1)

EVENTS_PLAN.md Phase 1. Six of the nine core tables — the ones that do not
depend on the module contract — plus definitions CRUD, publish, archive, and
the action registry with core as its first registrant.

**Nothing dispatches.** There is no runner until Phase 2, so a run row is
created and stays `scheduled`. That is this phase's correct answer and the
surface renders it verbatim rather than hiding it.

Schema (`db/schema.sql`, append-only):
  event_series, event_definitions, event_versions, event_runs,
  event_run_steps, event_run_log. The four that need a writer —
  event_action_settings, event_run_budget, event_run_resources,
  event_run_participants — arrive with the phases that give them one.

Registry (`modules/registries.js` + `config/coreEventActions.js`):
  registerEventActions staging and commit, with its own id namespace, the
  closed risk and reversibility sets, revert() required iff and only iff
  reversible: 'ledger', a bounded budgetMs and a param shape whose every
  entry needs a type and an example. perform/revert/cost are stripped from
  everything the catalog serves. Core declares core.announce, core.wait and
  core.cue through the same staging area a module will use.

  It is reachable ONLY by registerCore(): loader.js builds its own api facade
  and has no method that delegates here, so no module can call it and
  MODULE_API_VERSION is untouched. Phase 7 adds the facade and the bump.

Surface (13 routes under /api/v1/admin/events):
  Reads staff-wide; publish, archive and run creation admin-only from this
  phase per EVENTS.md §N2, even though the switchboard they will consult does
  not exist yet — a button that is admin-only later and open now is a gate
  nobody notices was missing. The live run controls and `verify` are absent
  rather than stubbed, because nothing is in flight yet.

Four things the build settled, all recorded in docs:
  - event_definitions gained a `spec` column. A draft's working copy cannot
    be an event_versions row: that table is immutable and a run pins one.
  - The spec validator must accept its own output. It added `actionVersion`
    and `dormant` and then refused them as unknown keys, which would have made
    the second save of any definition — and publish's re-validation —
    impossible. A test caught it; both are now accepted and recomputed.
  - A param's `example` is required, optional params included, matching
    registerEventTriggers. It is the authoring form's placeholder.
  - Two routes the §API-surface table did not name: GET /admin/events/:id and
    GET /admin/events/series.

Core's three perform() bodies answer { ok: false, retry: false } rather than
{ ok: true }: `ok: true` on an action that did nothing is a recorded world
change that did not occur, which is the exact mistake §F's failure default
exists to prevent.

`conditions.checkLiteral` is exported and reused for step-param type checking
— one switch over the six types, so "is this a datetime" has one answer.

Verified: 44 new tests, whole server suite, `npm run check:modules`, routes
manifest and swagger regenerated (the manifest diff is +13 routes, zero moved).

Docs: RunicGateway/docs#209

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

server/test/eventSpec.test.js

@@ -0,0 +1,231 @@
+// ── The event spec validator (EVENTS.md §C/§D, Phase 1) ────────────────────
+//
+// The boundary that decides whether a version may exist. Its interesting cases
+// are all about time rather than shape:
+//
+//   • a step's params are checked against the action's DECLARED params, and the
+//     action version it was authored against is captured at save
+//   • `on_failure` is defaulted from the risk class, because a `change` action
+//     that fell back to `skip` would advance a run over a half-changed world
+//   • an unregistered action is refused on a NEW step and KEPT on an existing
+//     one — the rule `engagementRules.model` established for a dormant trigger,
+//     for the same reason: an uninstall must not be destructive after the fact
+//   • a dormant step blocks a PUBLISH and never a SAVE
+//   • two phases may not share a key, because `UNIQUE (run_id, phase, seq)`
+//     would silently collapse them into one at materialisation
+//   • a key a later phase owns (`advance`, `announcements`) is REFUSED rather
+//     than preserved, so no corpus of unvalidated specs accumulates
+process.env.DB_HOST = '127.0.0.1'
+process.env.DB_PORT = '59999'
+
+const { test, beforeEach, afterEach, after } = require('node:test')
+const assert = require('node:assert/strict')
+
+const registries = require('../src/modules/registries')
+const spec = require('../src/events/spec')
+const db = require('../src/utils/db')
+
+after(() => db.close())
+
+beforeEach(() => {
+  registries._reset()
+  registries.registerCore()
+  const api = registries.stage('demo')
+  api.registerEventActions([
+    {
+      id: 'demo.world.change',
+      label: 'Change the world',
+      risk: 'change',
+      reversible: 'none',
+      version: 4,
+      params: [
+        { name: 'region', type: 'string', required: true, example: 'Yew' },
+        { name: 'count', type: 'int', required: true, example: 12 },
+        { name: 'hue', type: 'int', required: false, example: 1157 },
+      ],
+      perform: async () => ({ ok: true }),
+    },
+    {
+      id: 'demo.world.wreck',
+      label: 'Wreck the world',
+      risk: 'irreversible',
+      reversible: 'none',
+      perform: async () => ({ ok: true }),
+    },
+  ])
+  registries.apply(api.staged)
+})
+afterEach(() => registries._reset())
+
+const oneStep = (step) => ({
+  schedule: { kind: 'manual' },
+  phases: [{ key: 'main', label: 'Main', steps: [step] }],
+})
+
+test('the empty spec is valid, and is what a new draft carries', () => {
+  const result = spec.validate(spec.emptySpec())
+  assert.equal(result.ok, true)
+  assert.equal(result.spec.phases.length, 1)
+  assert.deepEqual(result.spec.schedule, { kind: 'manual' })
+})
+
+test('params are checked against the declaration and coerced', () => {
+  const result = spec.validate(
+    oneStep({ actionId: 'demo.world.change', params: { region: 'Yew', count: 12 } }),
+  )
+  assert.equal(result.ok, true)
+  const [step] = result.spec.phases[0].steps
+  assert.deepEqual(step.params, { region: 'Yew', count: 12 })
+  // Captured from the declaration, not from the request: it is what lets a later
+  // bump warn in the editor instead of dispatching a mistyped parameter.
+  assert.equal(step.actionVersion, 4)
+  assert.equal(step.dormant, false)
+})
+
+test('a missing required param, a wrong type and an unknown param are all refused', () => {
+  const missing = spec.validate(oneStep({ actionId: 'demo.world.change', params: { region: 'Yew' } }))
+  assert.equal(missing.ok, false)
+  assert.match(missing.errors.join('\n'), /"count" is required/)
+
+  const wrong = spec.validate(
+    oneStep({ actionId: 'demo.world.change', params: { region: 'Yew', count: 'twelve' } }),
+  )
+  assert.equal(wrong.ok, false)
+  assert.match(wrong.errors.join('\n'), /"count" expected an integer/)
+
+  // An unknown param is an ERROR, not a silent drop: an author who typed
+  // `regions` has written a step that would dispatch with the region missing,
+  // and dropping the key makes that look like it saved cleanly.
+  const typo = spec.validate(
+    oneStep({ actionId: 'demo.world.change', params: { regions: 'Yew', count: 1 } }),
+  )
+  assert.equal(typo.ok, false)
+  assert.match(typo.errors.join('\n'), /"regions" is not a param of demo\.world\.change/)
+})
+
+test('on_failure is defaulted from the risk class', () => {
+  const notify = spec.validate(
+    oneStep({ actionId: 'core.announce', params: { leg: 'discord', body: 'hi' } }),
+  )
+  assert.equal(notify.spec.phases[0].steps[0].onFailure, 'skip')
+
+  const change = spec.validate(
+    oneStep({ actionId: 'demo.world.change', params: { region: 'Yew', count: 1 } }),
+  )
+  assert.equal(change.spec.phases[0].steps[0].onFailure, 'pause')
+
+  const irreversible = spec.validate(oneStep({ actionId: 'demo.world.wreck' }))
+  assert.equal(irreversible.spec.phases[0].steps[0].onFailure, 'abort_run')
+
+  // An author may still choose, within the closed set.
+  const chosen = spec.validate(oneStep({ actionId: 'demo.world.wreck', onFailure: 'skip' }))
+  assert.equal(chosen.spec.phases[0].steps[0].onFailure, 'skip')
+  const invented = spec.validate(oneStep({ actionId: 'demo.world.wreck', onFailure: 'shrug' }))
+  assert.equal(invented.ok, false)
+  assert.match(invented.errors.join('\n'), /onFailure: must be one of/)
+})
+
+test('a NEW step may not name an unregistered action', () => {
+  const result = spec.validate(oneStep({ actionId: 'gone.module.verb' }))
+  assert.equal(result.ok, false)
+  assert.match(result.errors.join('\n'), /no module registers "gone\.module\.verb"/)
+})
+
+test('an EXISTING step keeps its action when the module goes away, and is marked dormant', () => {
+  const saved = spec.validate(
+    oneStep({ actionId: 'demo.world.change', params: { region: 'Yew', count: 3 } }),
+  ).spec
+
+  // The module is uninstalled between one save and the next.
+  registries._reset()
+  registries.registerCore()
+
+  const again = spec.validate(saved, { knownActionIds: spec.actionIdsIn(saved) })
+  assert.equal(again.ok, true, again.errors && again.errors.join('\n'))
+  const [step] = again.spec.phases[0].steps
+  assert.equal(step.dormant, true)
+  // Params pass through untouched: the only thing that could validate them left
+  // with the module.
+  assert.deepEqual(step.params, { region: 'Yew', count: 3 })
+
+  // …and that is exactly what publish refuses.
+  const publishable = spec.publishable(again.spec)
+  assert.equal(publishable.ok, false)
+  assert.deepEqual(publishable.dormant, ['demo.world.change'])
+})
+
+test('validate accepts its own output — a saved spec is re-validated on every save', () => {
+  // The property the dormancy test above found the hard way: `validate` adds
+  // `actionVersion` and `dormant`, and a validator that then refused its own
+  // fields would make the SECOND save of any definition impossible, and publish
+  // — which re-validates before snapshotting — impossible full stop.
+  const once = spec.validate(
+    oneStep({ actionId: 'demo.world.change', params: { region: 'Yew', count: 3 } }),
+  )
+  const twice = spec.validate(once.spec)
+  assert.equal(twice.ok, true, twice.errors && twice.errors.join('\n'))
+  assert.deepEqual(twice.spec, once.spec)
+})
+
+test('two phases may not share a key', () => {
+  const result = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [
+      { key: 'main', label: 'One', steps: [] },
+      { key: 'main', label: 'Two', steps: [] },
+    ],
+  })
+  assert.equal(result.ok, false)
+  assert.match(result.errors.join('\n'), /used by more than one phase/)
+})
+
+test('a key a later phase owns is refused, not silently preserved', () => {
+  const top = spec.validate({ schedule: { kind: 'manual' }, phases: [], announcements: [] })
+  assert.equal(top.ok, false)
+  assert.match(top.errors.join('\n'), /unknown key "announcements"/)
+
+  const phase = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [{ key: 'main', label: 'Main', steps: [], advance: { after: '30m' } }],
+  })
+  assert.equal(phase.ok, false)
+  assert.match(phase.errors.join('\n'), /unknown key\(s\) advance .*Phase 5/)
+})
+
+test('only the manual schedule exists in this phase', () => {
+  const weekly = spec.validate({
+    schedule: { kind: 'weekly', days: ['fri'], time: '20:00' },
+    phases: [{ key: 'main', label: 'Main', steps: [] }],
+  })
+  assert.equal(weekly.ok, false)
+  assert.match(weekly.errors.join('\n'), /recurrence arrives in Phase 4/)
+})
+
+test('every problem is reported, not just the first', () => {
+  const result = spec.validate({
+    schedule: { kind: 'manual' },
+    phases: [
+      { key: 'BAD KEY', label: '', steps: [{ actionId: 'demo.world.change', params: {} }] },
+    ],
+  })
+  assert.equal(result.ok, false)
+  const joined = result.errors.join('\n')
+  assert.match(joined, /bad phase key/)
+  assert.match(joined, /a phase needs a label/)
+  assert.match(joined, /"region" is required/)
+  assert.match(joined, /"count" is required/)
+})
+
+test('the size bounds hold', () => {
+  const many = {
+    schedule: { kind: 'manual' },
+    phases: Array.from({ length: spec.MAX_PHASES + 1 }, (_, i) => ({
+      key: `p${i}`,
+      label: `P${i}`,
+      steps: [],
+    })),
+  }
+  const result = spec.validate(many)
+  assert.equal(result.ok, false)
+  assert.match(result.errors.join('\n'), new RegExp(`at most ${spec.MAX_PHASES} phases`))
+})