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/src/model/events/eventDefinitions.model.js

@@ -0,0 +1,270 @@
+// ── Event definitions — the save path ──────────────────────────────────────
+//
+// EVENTS.md §D and "Versioning, and editing a live event". A definition is
+// operator-authored data, and this file is the boundary that decides whether a
+// version of it may exist. The authoring UI (Phase 3, then Phase 13) will
+// re-check some of this for the sake of a good inline error; that second copy is
+// expected to drift, so this one is the one that decides, and a definition
+// arriving by any other route gets the same answer.
+//
+// **The three rules with teeth, and each is a rule about time rather than about
+// shape:**
+//
+// 1. Publishing SNAPSHOTS. It copies the working spec into an immutable
+//    `event_versions` row and points `current_version_id` at it. Editing
+//    afterwards is free and does not touch the row a live run pinned.
+// 2. A dormant step blocks a PUBLISH and never a SAVE. An uninstalled module
+//    must not make an author's work uneditable, and it must not let a version be
+//    published that names a verb nobody can perform.
+// 3. Archiving is what "delete" means here. `event_runs.version_id` RESTRICTs, so
+//    a hard delete of a definition that has ever run is refused by the database
+//    anyway — and the row's history is the thing an audit reads.
+
+const db = require('./eventDefinitions.db')
+const versionsDb = require('./eventVersions.db')
+const runsDb = require('./eventRuns.db')
+const seriesDb = require('./eventSeries.db')
+const spec = require('../../events/spec')
+const { slugify, uniqueSlug } = require('../teams/teamSlug')
+const { cleanBody } = require('../../utils/sanitizeHtml')
+
+const MAX_TITLE = 200
+const MAX_SUMMARY = 500
+const MAX_URL = 500
+const MAX_CONCURRENCY_KEY = 190
+
+// A day either side of §D's default. Below a minute the grace window cannot
+// survive a single slow boot; above a day a "missed" occurrence would start
+// silently the following afternoon, which is the exact behaviour §E forbids.
+const MIN_GRACE_SECONDS = 60
+const MAX_GRACE_SECONDS = 86_400
+
+/**
+ * IANA zone names, checked against the platform's own database rather than a
+ * list. `Intl.DateTimeFormat` throws `RangeError` on an unknown zone, and Node
+ * ships the full tzdata — so this is the same check Phase 4's occurrence
+ * arithmetic will make, asked one screen earlier where an operator can fix it.
+ */
+function isTimezone(tz) {
+  try {
+    Intl.DateTimeFormat(undefined, { timeZone: tz })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+const trimOrNull = (v, max) => {
+  if (v === undefined || v === null) return null
+  const s = String(v).trim()
+  return s === '' ? null : s.slice(0, max)
+}
+
+/**
+ * Validate an incoming definition against the registries and the schema.
+ *
+ * `{ ok: true, definition }` with a normalised row ready for insert/update, or
+ * `{ ok: false, errors }` listing every problem rather than the first.
+ *
+ * `existing` is the row being edited, or null on a create. It is what lets a
+ * dormant step survive: the ids already in the saved spec widen what the spec
+ * validator will accept, so an uninstall is never destructive after the fact.
+ */
+async function validate(input, { existing = null } = {}) {
+  const errors = []
+  const body = isPlainObject(input) ? input : {}
+
+  const title = trimOrNull(body.title, MAX_TITLE)
+  if (!title) errors.push('title is required')
+
+  const summary = trimOrNull(body.summary, MAX_SUMMARY)
+  const imageUrl = trimOrNull(body.imageUrl, MAX_URL)
+  const concurrencyKey = trimOrNull(body.concurrencyKey, MAX_CONCURRENCY_KEY)
+
+  // The storyline. Sanitized on write, exactly as a wiki page and a forum post
+  // are: it is author-supplied HTML that ends up on a public page.
+  const storyline = body.body === undefined || body.body === null ? null : cleanBody(String(body.body))
+
+  const timezone = trimOrNull(body.timezone, 64) || existing?.timezone || 'UTC'
+  if (!isTimezone(timezone)) errors.push(`timezone: "${timezone}" is not an IANA zone name`)
+
+  const graceRaw = body.graceSeconds === undefined ? (existing?.grace_seconds ?? 900) : body.graceSeconds
+  const graceSeconds = Number(graceRaw)
+  if (
+    !Number.isInteger(graceSeconds) ||
+    graceSeconds < MIN_GRACE_SECONDS ||
+    graceSeconds > MAX_GRACE_SECONDS
+  ) {
+    errors.push(`graceSeconds must be an integer ${MIN_GRACE_SECONDS}..${MAX_GRACE_SECONDS}`)
+  }
+
+  let seriesId = null
+  if (body.seriesId !== undefined && body.seriesId !== null && body.seriesId !== '') {
+    seriesId = Number(body.seriesId)
+    if (!Number.isInteger(seriesId) || seriesId < 1) {
+      errors.push('seriesId must be an integer')
+      seriesId = null
+    } else if (!(await seriesDb.exists(seriesId))) {
+      // Checked here as well as by the foreign key, because a 1452 reaching a
+      // controller is a 500 and this is a 400 an author can act on.
+      errors.push(`seriesId ${seriesId} does not exist`)
+      seriesId = null
+    }
+  } else if (existing) {
+    seriesId = existing.series_id
+  }
+
+  const seriesOrderRaw = body.seriesOrder === undefined ? (existing?.series_order ?? 0) : body.seriesOrder
+  const seriesOrder = Number(seriesOrderRaw)
+  if (!Number.isInteger(seriesOrder)) errors.push('seriesOrder must be an integer')
+
+  // ── the spec ──
+  const rawSpec = body.spec === undefined ? existing?.spec ?? spec.emptySpec() : body.spec
+  const known = existing?.spec ? spec.actionIdsIn(existing.spec) : []
+  const checked = spec.validate(rawSpec, { knownActionIds: known })
+  if (!checked.ok) errors.push(...checked.errors)
+
+  // ── the slug ──
+  //
+  // Derived from the title on create and FROZEN afterwards, like a Team's: the
+  // public event page lives at it, and a retitle must not break a link somebody
+  // posted in Discord. An author who genuinely needs a different address makes a
+  // new definition.
+  let slug = existing?.slug || null
+  if (!slug) {
+    const stem = slugify(title || '') || 'event'
+    const taken = (await db.list()).map((d) => d.slug)
+    slug = uniqueSlug(stem, taken, { fallback: 'event' })
+  }
+
+  if (errors.length) return { ok: false, errors }
+
+  return {
+    ok: true,
+    definition: {
+      title,
+      slug,
+      summary,
+      body: storyline,
+      image_url: imageUrl,
+      owner_module: existing?.owner_module ?? null,
+      series_id: seriesId,
+      series_order: seriesOrder,
+      concurrency_key: concurrencyKey,
+      grace_seconds: graceSeconds,
+      timezone,
+      spec: checked.spec,
+    },
+  }
+}
+
+/** Create a draft. */
+async function create(input, userId) {
+  const result = await validate(input)
+  if (!result.ok) return result
+  const id = await db.insert({ ...result.definition, created_by: userId })
+  return { ok: true, id, definition: await db.getById(id) }
+}
+
+/**
+ * Edit a definition.
+ *
+ * An `archived` definition is not editable. That is the one state check here,
+ * and it is a real one rather than a formality: archiving is how a definition is
+ * retired, and a retired definition that can still be edited is a definition
+ * somebody will edit and then wonder why it never runs.
+ */
+async function save(id, input, userId) {
+  const existing = await db.getById(id)
+  if (!existing) return { ok: false, status: 404, errors: ['no such event definition'] }
+  if (existing.state === 'archived') {
+    return { ok: false, status: 409, errors: ['an archived definition cannot be edited'] }
+  }
+  const result = await validate(input, { existing })
+  if (!result.ok) return result
+  await db.update(id, { ...result.definition, updated_by: userId })
+  return { ok: true, id, definition: await db.getById(id) }
+}
+
+/**
+ * Publish: snapshot the working spec into an immutable version and go `ready`.
+ *
+ * The spec is re-validated here against the registries as they stand RIGHT NOW,
+ * not trusted from the save that wrote it. A module uninstalled between the two
+ * is the whole reason: the save was legitimate, and publishing a version whose
+ * steps name a verb nobody can perform would be a run that fails at dispatch
+ * with the world half-changed.
+ */
+async function publish(id, userId) {
+  const existing = await db.getById(id)
+  if (!existing) return { ok: false, status: 404, errors: ['no such event definition'] }
+  if (existing.state === 'archived') {
+    return { ok: false, status: 409, errors: ['an archived definition cannot be published'] }
+  }
+
+  const checked = spec.validate(existing.spec, {
+    knownActionIds: spec.actionIdsIn(existing.spec),
+  })
+  if (!checked.ok) return { ok: false, status: 400, errors: checked.errors }
+
+  const publishable = spec.publishable(checked.spec)
+  if (!publishable.ok) {
+    return {
+      ok: false,
+      status: 409,
+      errors: [
+        `cannot publish: no module registers ${publishable.dormant.join(', ')}`,
+      ],
+    }
+  }
+  if (!checked.spec.phases.some((p) => p.steps.length)) {
+    // An empty event publishes cleanly and then does nothing, which looks like a
+    // broken run rather than an empty one. Refusing costs an author one click and
+    // saves an operator a diagnosis.
+    return { ok: false, status: 400, errors: ['cannot publish: no phase has any steps'] }
+  }
+
+  const version = await versionsDb.nextVersion(id)
+  const versionId = await versionsDb.insert(id, version, checked.spec, userId)
+  await db.markReady(id, versionId, userId)
+  return { ok: true, versionId, version, definition: await db.getById(id) }
+}
+
+/**
+ * Archive.
+ *
+ * Refused while a run of this definition is still in flight — not because the
+ * database would object (it would not; archiving is an UPDATE), but because the
+ * screen the run is on reads its title and state from here, and retiring a
+ * definition mid-run makes the console describe something that is no longer
+ * supposed to exist. Cancel the run, then archive.
+ */
+async function archive(id, userId) {
+  const existing = await db.getById(id)
+  if (!existing) return { ok: false, status: 404, errors: ['no such event definition'] }
+  if (existing.state === 'archived') return { ok: true, definition: existing }
+
+  const active = await runsDb.countActiveForDefinition(id)
+  if (active > 0) {
+    return {
+      ok: false,
+      status: 409,
+      errors: [`cannot archive: ${active} run(s) of this definition are still in flight`],
+    }
+  }
+  await db.archive(id, userId)
+  return { ok: true, definition: await db.getById(id) }
+}
+
+module.exports = {
+  validate,
+  create,
+  save,
+  publish,
+  archive,
+  isTimezone,
+  MIN_GRACE_SECONDS,
+  MAX_GRACE_SECONDS,
+}