Files
website/server/src/router/v1/admin/events.controller.js
wtclaude cee4ab8aea
All checks were successful
PR Checks / bot-tests (pull_request) Successful in 46s
PR Checks / server-tests (pull_request) Successful in 7m0s
PR Checks / client-build (pull_request) Successful in 7m29s
feat(demo): refuse an event step at save with demoRefuses (MODULE_API 1.19.0)
DEMO_MODE.md §3.4 refuses a denied console command when the event is
saved and when it runs. Saving is core's route, and core never asked a
module about a step's params, so the save-time half had no seam (DM18).

An event action may now declare demoRefuses(params), returning a
sentence or null. With DEMO_MODE on, create, save and publish ask it
for every step; the first sentence refuses the write 403 DEMO_LOCKED
with that sentence as the message (and in errors). A hook that throws
refuses too. Off the demo it is validated and never called, and the
catalog strips it with the other callables.

The events controller passes code and message through on create,
update and publish, so the client's one DEMO_LOCKED toast fires.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
2026-10-26 03:39:42 -05:00

881 lines
36 KiB
JavaScript

// ── Admin: events ──────────────────────────────────────────────────────────
//
// EVENTS.md § API surface, Phase 1. Definitions CRUD, publish, archive, the
// action catalog and the run reads.
//
// This file reads ids out of URLs and shapes responses; it validates nothing.
// Every decision lives in `model/events/*.model.js` and in `events/spec.js`, so
// a definition arriving from a future import or a restore gets the same answer
// this screen does.
//
// **Phase 3 added the live run controls** at the bottom of this file: pause,
// resume, cancel, and a step's confirm, skip and retry. `advance` joined them in
// Phase 5, the action switchboard in Phase 6, and **`cleanup` in Phase 8** —
// each when the phase that gave it something to act on landed, and each absent
// rather than stubbed until then, for the reason the whole set was in Phase 1: a
// control that returns 200 and does nothing is worse than one that is not there.
// Nothing in the § API surface table is absent any more.
const registries = require('../../../modules/registries')
const spec = require('../../../events/spec')
const conditionGrammar = require('../../../engagement/conditions')
const definitionsDb = require('../../../model/events/eventDefinitions.db')
const definitions = require('../../../model/events/eventDefinitions.model')
const versionsDb = require('../../../model/events/eventVersions.db')
const seriesDb = require('../../../model/events/eventSeries.db')
const series = require('../../../model/events/eventSeries.model')
const calendarModel = require('../../../model/events/eventCalendar.model')
const eventRunner = require('../../../utils/eventRunner')
const runsDb = require('../../../model/events/eventRuns.db')
const runs = require('../../../model/events/eventRuns.model')
const controls = require('../../../model/events/eventRunControls.model')
const logDb = require('../../../model/events/eventRunLog.db')
const activity = require('../../../model/activity/activity.model')
const settingsDb = require('../../../model/events/eventActionSettings.db')
const authorize = require('../../../events/authorize')
const price = require('../../../events/price')
const starts = require('../../../events/starts')
const triggerStartsDb = require('../../../model/events/eventTriggerStarts.db')
const asId = (raw) => {
const n = Number(raw)
return Number.isInteger(n) && n > 0 ? n : null
}
/**
* A refused save's body: the errors, plus `code` and `message` when the model
* set them. The demo's step refusal does (DM18), so the client's one
* `DEMO_LOCKED` toast fires as it does for a route lock.
*/
const refusal = (result) => ({
errors: result.errors,
...(result.code ? { code: result.code, message: result.message } : {}),
})
/**
* The shape a definition takes on the wire.
*
* Explicit rather than the row, like every other admin surface here: the row
* carries `created_by`, `updated_by` and the joined series columns, and a
* response that spreads it is a response that gains a column the day somebody
* adds one.
*/
const shapeDefinition = (d) => ({
id: d.id,
title: d.title,
slug: d.slug,
summary: d.summary,
body: d.body,
imageUrl: d.image_url,
ownerModule: d.owner_module,
state: d.state,
currentVersionId: d.current_version_id,
currentVersion: d.current_version,
// §K's gate, rendered where it can still be acted on. `null` on a draft --
// there is no version to have verified -- and a date once a dry run has passed
// against the published one.
currentVersionVerifiedAt: d.current_version_verified_at || null,
seriesId: d.series_id,
seriesName: d.series_name,
seriesOrder: d.series_order,
concurrencyKey: d.concurrency_key,
graceSeconds: d.grace_seconds,
timezone: d.timezone,
// Whether the public calendar announces it (Phase 14a). Not whether it may
// run — an unlisted event schedules and runs exactly as a listed one does,
// and is on THIS screen either way.
listed: Boolean(d.listed),
spec: d.spec,
createdAt: d.created_at,
updatedAt: d.updated_at,
})
/**
* The definition as the EDITOR reads it: the shape above, and whether the working
* copy has moved on from the published version (Rust PLAN_REDESIGNS §2.3). One
* extra read, so only the three routes the editor loads from carry it.
*/
const shapeEditable = async (row) => ({
...shapeDefinition(row),
draftAhead: await definitions.draftAhead(row),
// What its trigger starts have done lately (D370): the last run one started
// and the firings ignored since, by why. Null until a trigger first tries.
triggerStarts: starts.describeState(await triggerStartsDb.forDefinition(row.id)),
})
const shapeRun = (r) => ({
id: r.id,
definitionId: r.definition_id,
definitionTitle: r.definition_title,
definitionSlug: r.definition_slug,
versionId: r.version_id,
version: r.version_number,
scope: r.scope,
status: r.status,
health: r.health,
cleanupStatus: r.cleanup_status,
currentPhase: r.current_phase,
scheduledFor: r.scheduled_for,
timezone: r.timezone,
concurrencyKey: r.concurrency_key,
params: r.params,
rehearsal: r.rehearsal,
// What started it, when a game firing did (D370): the trigger, when, its
// subject, the condition it matched and its declared variables. Null for a
// run started by hand or by the schedule.
origin: r.origin || null,
startedAt: r.started_at,
endedAt: r.ended_at,
// When the results table was ranked and published (Phase 10). On the LIST as
// well as the console, because "which of last month's events still have no
// published results" is a question about a list.
resultsPublishedAt: r.results_published_at,
lastError: r.last_error,
createdAt: r.created_at,
// How many steps are parked on a human. Derived, not a column, and surfaced on
// the LIST as well as the console because a cue nobody notices is a run that
// never advances while looking perfectly healthy from the outside.
waitingSteps: Number(r.waiting_steps || 0),
})
const shapeStep = (s) => ({
id: s.id,
runId: s.run_id,
phase: s.phase,
seq: s.seq,
actionId: s.action_id,
params: s.params,
actionVersion: s.action_version,
status: s.status,
// `running` with no lease is a parked step (§E) — waiting on a human, with
// nothing holding it. The console has to tell that apart from a step some
// process is mid-dispatch on, and it must not do so by being shown the lease:
// one derived boolean rather than `claimed_by` and `claim_expires_at`, which
// are the runner's business and would invite a UI that reasoned about leases.
parked: s.status === 'running' && !s.claim_expires_at,
dueAt: s.due_at,
attempts: s.attempts,
onFailure: s.on_failure,
idempotencyKey: s.idempotency_key,
lastError: s.last_error,
startedAt: s.started_at,
finishedAt: s.finished_at,
})
/** GET /api/v1/admin/events */
exports.list = async (req, res) => {
const state = ['draft', 'ready', 'archived'].includes(req.query.state) ? req.query.state : null
const rows = await definitionsDb.list({ state })
res.json({ events: rows.map(shapeDefinition) })
}
/**
* GET /api/v1/admin/events/catalog
*
* The registered actions, their param schemas, their risk classes and the
* vocabularies over both — served from the registries, so there is no table
* behind it and a module that was uninstalled simply stops appearing. Same
* argument the engagement trigger catalog makes: the editor offers exactly the
* set the save path checks against, so the two cannot drift.
*
* Budget dimensions are absent, and that is Phase 1 being honest rather than an
* omission: `registerEventBudgets` is Phase 7's and nothing declares one yet.
*/
exports.catalog = (_req, res) => {
res.json({
actions: registries.allEventActions(),
risks: registries.ACTION_RISKS,
reversible: registries.ACTION_REVERSIBLE,
paramTypes: registries.ACTION_PARAM_TYPES,
onFailure: spec.ON_FAILURE,
onFailureByRisk: spec.ON_FAILURE_BY_RISK,
scheduleKinds: spec.SCHEDULE_KINDS,
// **The trigger catalog is served here too, and not borrowed from
// `/admin/engagement/triggers`** (Phase 5). §C's claim is that the trigger
// catalog a module already ships IS the catalog of things that can advance a
// phase — so it is the same registry, read twice. What differs is who may
// read it: the engagement route is `adminOnly`, and event definitions are
// authored by `admin` AND `editor`. Pointing this editor at that route would
// have left an editor writing a trigger id from memory into a field the save
// path then refused.
//
// Each declaration is reduced to what the gate form needs — id, label and
// the variables a `where` may name. Everything else on a trigger (its
// audience, its ceiling, its subject key) is about who gets MAILED, which is
// a different question and not this screen's.
triggers: registries.allTriggers().map((t) => ({
id: t.id,
label: t.label,
description: t.description,
owner: t.owner,
variables: (t.variables || []).map((v) => ({
name: v.name,
type: v.type,
required: v.required,
description: v.description,
})),
})),
operators: conditionGrammar.vocabulary(),
advanceKinds: spec.ADVANCE_KINDS,
// **The other three registrations of the module contract** (Phase 7). Served
// beside the actions rather than on three routes of their own, because the
// step editor needs all four to render one step: the action says what params
// it takes, a param's `source` names an option source, and a cap the editor
// shows is a budget's label and unit. Four requests to draw one form would
// be four chances for the screen to render half of it.
//
// Each is already stripped of its callables by the registry (`resolve`,
// `read`, `apply`, `restore`) — the same rule that keeps `perform` off an
// action here. A source's VALUES are not in this payload either: they are a
// request of their own (`/options/:sourceId`), because a source can be slow,
// can fail, and would otherwise take the whole catalog down with it.
budgets: registries.allEventBudgets(),
leases: registries.allEventLeases(),
optionSources: registries.allEventOptionSources(),
// MODULE_API 1.13.0 (Rust PLAN_REDESIGNS §2.5). Without `build`, like every
// callable above; filling one in is its own request.
templates: registries.allEventTemplates(),
limits: {
maxPhases: spec.MAX_PHASES,
maxStepsPerPhase: spec.MAX_STEPS_PER_PHASE,
maxSteps: spec.MAX_STEPS,
defaultBudgetMs: registries.DEFAULT_BUDGET_MS,
maxAdvanceCount: spec.MAX_ADVANCE_COUNT,
maxAfterSeconds: spec.MAX_AFTER_SECONDS,
// A definition's `starts` (D370): how many, and the cooldown's ceiling.
maxStarts: spec.MAX_STARTS,
maxCooldownSeconds: spec.MAX_COOLDOWN_SECONDS,
},
})
}
const shapeSeries = (s) => ({
id: s.id,
name: s.name,
slug: s.slug,
description: s.description,
ordering: s.ordering,
definitionCount: Number(s.definition_count || 0),
})
/** GET /api/v1/admin/events/series */
exports.listSeries = async (_req, res) => {
const rows = await seriesDb.list()
res.json({ series: rows.map(shapeSeries) })
}
/** POST /api/v1/admin/events/series */
exports.createSeries = async (req, res) => {
const result = await series.create(req.body, req.user?.id)
if (!result.ok) return res.status(result.status).json({ errors: result.errors })
await activity.log({
req,
action: 'event.series.created',
detail: { id: result.series.id, name: result.series.name },
})
res.status(201).json({ series: shapeSeries(result.series) })
}
/** PUT /api/v1/admin/events/series/:seriesId */
exports.updateSeries = async (req, res) => {
const id = asId(req.params.seriesId)
if (!id) return res.status(404).json({ error: 'no such series' })
const result = await series.update(id, req.body, req.user?.id)
if (!result.ok) return res.status(result.status).json({ errors: result.errors })
await activity.log({ req, action: 'event.series.updated', detail: { id, name: result.series.name } })
res.json({ series: shapeSeries(result.series) })
}
/**
* DELETE /api/v1/admin/events/series/:seriesId
*
* `detached` is in the response because the delete is not confined to the row:
* `series_id` is `ON DELETE SET NULL`, so definitions that belonged to the arc
* survive it without one. Saying how many is the difference between an operator
* knowing and an operator finding out.
*/
exports.deleteSeries = async (req, res) => {
const id = asId(req.params.seriesId)
if (!id) return res.status(404).json({ error: 'no such series' })
const result = await series.remove(id)
if (!result.ok) return res.status(result.status).json({ errors: result.errors })
await activity.log({ req, action: 'event.series.deleted', detail: { id, detached: result.detached } })
res.json({ ok: true, detached: result.detached })
}
/**
* GET /api/v1/admin/events/calendar
*
* `from` and `to` are UTC instants and the caller supplies both: a month grid
* knows its own boundaries in the viewer's zone, and having the server guess
* them would be the server guessing the viewer's zone.
*/
exports.calendar = async (req, res) => {
const result = await calendarModel.calendar({
from: req.query.from,
to: req.query.to,
status: req.query.status || null,
scope: req.query.scope || null,
seriesId: asId(req.query.seriesId),
horizonDays: eventRunner.HORIZON_DAYS,
})
if (!result.ok) return res.status(result.status).json({ errors: result.errors })
res.json({
window: result.window,
horizon: result.horizon,
horizonDays: eventRunner.HORIZON_DAYS,
entries: result.entries,
truncated: result.truncated,
})
}
/** GET /api/v1/admin/events/runs */
exports.listRuns = async (req, res) => {
const rows = await runsDb.list({
definitionId: asId(req.query.definitionId),
status: req.query.status || null,
limit: req.query.limit,
})
res.json({ runs: rows.map(shapeRun) })
}
/** GET /api/v1/admin/events/runs/:runId */
exports.getRun = async (req, res) => {
const runId = asId(req.params.runId)
if (!runId) return res.status(400).json({ error: 'bad run id' })
const found = await runs.detail(runId)
if (!found) return res.status(404).json({ error: 'no such run' })
return res.json({
run: shapeRun(found.run),
steps: found.steps.map(shapeStep),
counts: found.counts,
// Already rendered in the condition builder's own words (Phase 5). See
// `eventRuns.model.detail` for why the sentence is built here and not in
// the browser.
gates: found.gates,
// The caps this run was given and what it has spent (Phase 6). Copied into
// the run when it was created, so it answers "what was THIS run allowed"
// rather than "what is allowed now" — which is the question that survives
// an admin moving a switch tomorrow.
budget: found.budget,
// The resource ledger (Phase 8): everything this run created or borrowed, and
// what became of each. The WHOLE ledger, reverted rows included — "how much
// did last night's invasion spawn, and did all of it come back" is one
// question with two halves, and a list of only the failures answers neither.
resources: found.resources,
unresolvedResources: found.unresolvedResources,
// Who took part, best first (Phase 10). `rank` is null on every row until
// `core.results.publish` has ranked them, which is what lets the console
// show a collected-but-unpublished run as exactly that rather than
// inventing an ordering nobody settled.
participants: found.participants,
})
}
/** GET /api/v1/admin/events/runs/:runId/log */
exports.getRunLog = async (req, res) => {
const runId = asId(req.params.runId)
if (!runId) return res.status(400).json({ error: 'bad run id' })
const run = await runsDb.getById(runId)
if (!run) return res.status(404).json({ error: 'no such run' })
const lines = await logDb.listForRun(runId, { limit: req.query.limit })
return res.json({
log: lines.map((l) => ({
id: l.id,
stepId: l.step_id,
kind: l.kind,
phase: l.phase,
detail: l.detail,
at: l.at,
})),
kinds: logDb.KINDS,
})
}
/** GET /api/v1/admin/events/:id */
exports.get = async (req, res) => {
const id = asId(req.params.id)
if (!id) return res.status(400).json({ error: 'bad event id' })
const row = await definitionsDb.getById(id)
if (!row) return res.status(404).json({ error: 'no such event definition' })
return res.json({ event: await shapeEditable(row) })
}
/** GET /api/v1/admin/events/:id/versions */
exports.listVersions = async (req, res) => {
const id = asId(req.params.id)
if (!id) return res.status(400).json({ error: 'bad event id' })
const row = await definitionsDb.getById(id)
if (!row) return res.status(404).json({ error: 'no such event definition' })
const rows = await versionsDb.listForDefinition(id)
return res.json({
versions: rows.map((v) => ({
id: v.id,
version: v.version,
publishedAt: v.published_at,
publishedBy: v.published_by,
publishedByUsername: v.published_by_username,
current: v.id === row.current_version_id,
})),
})
}
/** POST /api/v1/admin/events */
exports.create = async (req, res) => {
const result = await definitions.create(req.body, req.user.id, { role: req.user.role })
if (!result.ok) return res.status(result.status || 400).json(refusal(result))
await activity.log({
req,
action: 'event.definition.created',
detail: { id: result.id, title: result.definition.title },
})
return res.status(201).json({ event: shapeDefinition(result.definition) })
}
/** PUT /api/v1/admin/events/:id */
exports.update = async (req, res) => {
const id = asId(req.params.id)
if (!id) return res.status(400).json({ error: 'bad event id' })
const result = await definitions.save(id, req.body, req.user.id, { role: req.user.role })
if (!result.ok) return res.status(result.status || 400).json(refusal(result))
await activity.log({
req,
action: 'event.definition.updated',
detail: { id, title: result.definition.title },
})
return res.json({ event: await shapeEditable(result.definition) })
}
/** POST /api/v1/admin/events/:id/publish */
exports.publish = async (req, res) => {
const id = asId(req.params.id)
if (!id) return res.status(400).json({ error: 'bad event id' })
const result = await definitions.publish(id, req.user.id)
if (!result.ok) return res.status(result.status || 400).json(refusal(result))
await activity.log({
req,
action: 'event.definition.published',
detail: {
id,
version: result.version,
versionId: result.versionId,
repinned: result.repinned,
verified: result.verified,
},
})
return res.json({
event: await shapeEditable(result.definition),
version: result.version,
versionId: result.versionId,
// How many already-materialised occurrences moved to this version. The
// screen says so, because "my fix did not reach next Friday" is otherwise
// found out on Friday.
repinned: result.repinned,
// Whether a dry run that passed on this exact draft made the version
// verified at birth (W5), so the screen can say it needs no second one.
verified: result.verified,
})
}
/**
* POST /api/v1/admin/events/:id/verify — the dry run.
*
* `admin, editor` rather than `admin` (§ API surface): a dry run dispatches
* nothing and changes nothing, and the author who wrote the definition is
* exactly who should be able to price it against the caps before asking an
* admin to publish it.
*
* **A report with findings is a 200, not a 400.** The request succeeded; the
* plan has problems. Answering 4xx would make "this event asks for 45 creatures
* and you allow 30" indistinguishable to the client from "you sent a bad event
* id", and the whole value of the screen is rendering the findings.
*/
exports.verify = async (req, res) => {
const id = asId(req.params.id)
if (!id) return res.status(400).json({ error: 'bad event id' })
const result = await definitions.verify(id, req.user)
if (!result.ok) return res.status(result.status || 400).json({ errors: result.errors })
await activity.log({
req,
action: 'event.definition.verified',
detail: {
id,
target: result.target,
versionId: result.versionId,
passed: result.report.ok,
findings: result.report.findings.length,
},
})
return res.json({
target: result.target,
versionId: result.versionId,
version: result.version,
recorded: result.recorded,
draftRecorded: result.draftRecorded,
report: result.report,
})
}
/**
* POST /api/v1/admin/events/price — the live cap meter (Phase 13).
*
* `admin, editor`, exactly as the dry run is and for the same reason: an author
* should be able to find out what their plan would cost before asking an admin
* to commit the deployment to it.
*
* **The spec is in the BODY, not looked up by id**, and that is the whole point
* of the route. The meter answers a question about the plan in the author's
* hands — half-typed, unsaved, and quite possibly not publishable yet — so a
* route that read the stored draft would be answering about a spec the author is
* no longer looking at.
*
* It dispatches nothing, unlike `verify`, and it records nothing, unlike a dry
* run that passes against a version — which is the stamp §K's unattended-start
* gate reads. Those two absences are exactly what make it safe to call while
* somebody is still typing.
*
* A body core cannot make sense of is a `400`; a plan that is over the caps is a
* **200**, for the dry run's reason — *"this asks for 45 and you allow 30"* is
* an answer, not a failed request.
*
* Not logged to the activity trail. It is a read that changes nothing and it
* fires on a debounce while a form is edited; an audit line per keystroke would
* bury the acts that matter under the act of looking.
*/
exports.price = async (req, res) => {
const result = await price.priceSpec(req.body || {})
if (!result.ok) return res.status(400).json({ error: result.error })
return res.json({
steps: result.steps,
priced: result.priced,
cost: result.cost,
phases: result.phases,
unpriced: result.unpriced,
})
}
/**
* GET /api/v1/admin/events/actions — the deployment's switchboard.
*
* Every registered action, each with the deployment's stored opinion of it or,
* where there is none, **the default its risk class implies**. The default is
* computed by `authorize.isEnabled` rather than here, because a screen that
* worked out the posture for itself would be a second copy of the posture, and
* the copy that drifts is always the one on the screen.
*
* `configured` says whether a row exists, which the client needs to tell "an
* admin turned this on" from "this has always been on" — the same fact, arrived
* at two ways, and only one of them is a decision somebody made.
*/
exports.actions = async (_req, res) => {
const all = registries.allEventActions()
const stored = await settingsDb.byIds(all.map((a) => a.id))
return res.json({
actions: all.map((a) => {
const row = stored.get(a.id) || null
const full = registries.eventAction(a.id)
return {
...a,
enabled: authorize.isEnabled(full, row),
configured: Boolean(row),
changesWorld: authorize.changesWorld(full),
// The dimensions this action can spend, so the screen can offer a cap
// box per dimension — each now carrying the label and unit its
// `registerEventBudgets` declaration gives it (Phase 7), because "30" on
// a box is ambiguous in exactly the case that matters: 30 of what?
//
// `registered: false` says a dimension nobody declares, and it is shown
// rather than filtered out: an action that prices an undeclared
// dimension is REFUSED at save and at dispatch, so the screen must be
// able to show the operator why their action will not run instead of
// quietly listing one fewer box than the action has dimensions.
dimensions: authorize.budgetsOf(full),
caps: row?.caps || {},
updatedAt: row?.updated_at || null,
updatedBy: row?.updated_by_username || null,
}
}),
// The rule the screen explains to the operator, served rather than written
// into the client twice.
worldChangingRisks: authorize.WORLD_CHANGING,
})
}
/**
* GET /api/v1/admin/events/catalog/options/:sourceId — the values behind a param's `source`.
*
* §F's *Param option sources* (Phase 7). Without it the step editor is a JSON
* editor with better fonts: a landmark, a creature and an item are all "a string
* the operator has to spell right", and an unattended world write scheduled with
* a typo in it is the failure this whole feature exists to make unlikely.
*
* **A refusal is a 200 with `ok: false`, not a 4xx or a 5xx.** §F: a source that
* cannot answer degrades its field to free text with a visible warning rather
* than blocking the form. A 502 would be true about the module and wrong about
* the screen — the operator very often knows the value they want to type, and an
* authoring form that a sidecar outage can make unusable is a worse failure than
* the typo the dropdown prevents. The client renders the `reason` beside the box.
*
* `admin, editor`, like the catalog and for the same argument: this is authoring
* data, and an editor who can write the step must be able to see the values it
* accepts. The registry answers it, so it names no game noun here.
*/
exports.options = async (req, res) => {
// `q` is passed straight through and bounded by the registry, not here: the
// registry is what every caller of a source goes through, and a bound written
// on the route would be a bound the next caller does not have.
const result = await registries.resolveOptionSource(String(req.params.sourceId || ''), {
q: String(req.query.q || ''),
})
return res.json(result)
}
/**
* POST /api/v1/admin/events/catalog/templates/:templateId — fill a template in.
*
* MODULE_API 1.13.0 (Rust PLAN_REDESIGNS §2.5). Answers a draft and writes
* nothing, so there is nothing to put in the activity log: the definition the
* draft becomes is logged when it is created, by the route that creates it.
*/
exports.buildTemplate = async (req, res) => {
const result = await definitions.buildFromTemplate(req.params.templateId, req.body?.inputs)
if (!result.ok) return res.status(result.status || 400).json({ errors: result.errors })
return res.json({ draft: result.draft })
}
/**
* PUT /api/v1/admin/events/actions — set one action's switch and caps.
*
* One action per request rather than the whole board: the board is rendered from
* the registry and a whole-board PUT would have to say what an action MISSING
* from the body means. On a screen listing what is registered right now, that is
* "a module booted between the GET and the PUT", and answering it by writing a
* default over an admin's stored choice is the kind of quiet data loss a sparse
* write does not have.
*/
exports.saveAction = async (req, res) => {
const actionId = String(req.body?.actionId || '')
const action = registries.eventAction(actionId)
if (!action) return res.status(404).json({ error: 'no module registers that action' })
if (typeof req.body?.enabled !== 'boolean') {
return res.status(400).json({ error: 'enabled must be true or false' })
}
// Caps are validated against the dimensions this action can actually spend.
// A cap on a dimension it never names is not a harmless extra row — it is a
// number an operator believes is protecting them, on a screen that would
// render it back to them forever, bounding nothing.
const known = new Set(authorize.dimensionsOf(action))
const caps = {}
for (const [dimension, raw] of Object.entries(req.body?.caps || {})) {
if (raw === null || raw === '') continue
if (!known.has(dimension)) {
return res.status(400).json({ error: `"${action.id}" does not spend "${dimension}"` })
}
const n = Number(raw)
if (!Number.isInteger(n) || n < 0) {
return res.status(400).json({ error: `the cap for "${dimension}" must be a whole number of 0 or more` })
}
caps[dimension] = n
}
const row = await settingsDb.put(actionId, { enabled: req.body.enabled, caps }, req.user.id)
await activity.log({
req,
action: 'event.action.configured',
detail: { actionId, enabled: Boolean(req.body.enabled), caps },
})
return res.json({
action: {
id: actionId,
enabled: Boolean(row.enabled),
configured: true,
caps: row.caps,
updatedAt: row.updated_at,
},
})
}
/** DELETE /api/v1/admin/events/:id — archive, never a hard delete */
exports.archive = async (req, res) => {
const id = asId(req.params.id)
if (!id) return res.status(400).json({ error: 'bad event id' })
const result = await definitions.archive(id, req.user.id)
if (!result.ok) return res.status(result.status || 400).json({ errors: result.errors })
await activity.log({ req, action: 'event.definition.archived', detail: { id } })
return res.json({ event: shapeDefinition(result.definition) })
}
/**
* POST /api/v1/admin/events/:id/runs
*
* Creates the occurrence. It stays `scheduled` until Phase 2's runner exists,
* and the response says so through `pending: true` rather than by pretending
* something started.
*/
exports.startRun = async (req, res) => {
const id = asId(req.params.id)
if (!id) return res.status(400).json({ error: 'bad event id' })
const result = await runs.create(
id,
{
scope: req.body?.scope,
scheduledFor: req.body?.scheduledFor,
rehearsal: Boolean(req.body?.rehearsal),
params: req.body?.params ?? null,
},
req.user.id,
)
if (!result.ok) return res.status(result.status || 400).json({ errors: result.errors })
if (result.created) {
await activity.log({
req,
action: 'event.run.created',
detail: {
definitionId: id,
runId: result.run.id,
rehearsal: Boolean(req.body?.rehearsal),
},
})
}
return res.status(result.created ? 201 : 200).json({
run: shapeRun(result.run),
created: result.created,
})
}
// ── Phase 3: the live run controls ─────────────────────────────────────────
//
// Six handlers, and each is the same four lines: read the ids out of the URL,
// hand off to `eventRunControls`, log the manual transition to `activity_log`,
// answer with the row. Every guard is in the model, where a control invoked from
// anywhere else gets the same answer — which is the same division this file has
// had since Phase 1.
//
// **The audit is written in two places on purpose, and they are not redundant.**
// `event_run_log` is the run's own diagnostic record: queryable by phase and by
// step, and it is what the console renders. `activity_log` is the deployment's
// record of what staff did, and it is where "who cancelled the invasion" is
// looked up months later by somebody who is not looking at that run. §J names
// both.
/** POST /api/v1/admin/events/runs/:runId/pause */
exports.pauseRun = async (req, res) => {
const runId = asId(req.params.runId)
if (!runId) return res.status(400).json({ error: 'bad run id' })
const result = await controls.pause(runId, { reason: req.body?.reason }, req.user.id)
if (!result.ok) return res.status(result.status || 409).json({ errors: result.errors })
await activity.log({ req, action: 'event.run.paused', detail: { runId, reason: req.body?.reason || null } })
return res.json({ run: shapeRun(result.run) })
}
/** POST /api/v1/admin/events/runs/:runId/resume */
exports.resumeRun = async (req, res) => {
const runId = asId(req.params.runId)
if (!runId) return res.status(400).json({ error: 'bad run id' })
const result = await controls.resume(runId, {}, req.user.id)
if (!result.ok) return res.status(result.status || 409).json({ errors: result.errors })
await activity.log({ req, action: 'event.run.resumed', detail: { runId } })
return res.json({ run: shapeRun(result.run) })
}
/** POST /api/v1/admin/events/runs/:runId/advance */
exports.advanceRunPhase = async (req, res) => {
const runId = asId(req.params.runId)
if (!runId) return res.status(400).json({ error: 'bad run id' })
const result = await controls.advancePhase(runId, { reason: req.body?.reason }, req.user.id)
if (!result.ok) return res.status(result.status || 409).json({ errors: result.errors })
await activity.log({
req,
action: 'event.run.advanced',
detail: { runId, phase: result.phase, reason: req.body?.reason || null },
})
return res.json({ run: shapeRun(result.run), phase: result.phase })
}
/** POST /api/v1/admin/events/runs/:runId/cancel */
exports.cancelRun = async (req, res) => {
const runId = asId(req.params.runId)
if (!runId) return res.status(400).json({ error: 'bad run id' })
// **`cleanup` defaults to true and has to be asked out of.** §L makes cancelling
// WITHOUT cleanup the separate, admin-only, logged action, so an absent flag
// must mean "give back what this run took" — the safe direction, and the one a
// moderator's cancel at two in the morning takes without having to know the
// flag exists.
const withCleanup = req.body?.cleanup !== false
const result = await controls.cancel(
runId,
{ reason: req.body?.reason, cleanup: withCleanup },
req.user.id,
{ isAdmin: req.user.role === 'admin' },
)
if (!result.ok) return res.status(result.status || 409).json({ errors: result.errors })
await activity.log({
req,
action: 'event.run.cancelled',
detail: {
runId,
reason: req.body?.reason || null,
cancelledSteps: result.cancelledSteps,
cleanup: result.cleanup,
},
})
return res.json({
run: shapeRun(result.run),
cancelledSteps: result.cancelledSteps,
cleanup: result.cleanup,
})
}
/** POST /api/v1/admin/events/runs/:runId/cleanup */
exports.cleanupRun = async (req, res) => {
const runId = asId(req.params.runId)
if (!runId) return res.status(400).json({ error: 'bad run id' })
const result = await controls.cleanupRun(runId, req.user.id)
if (!result.ok) return res.status(result.status || 409).json({ errors: result.errors })
await activity.log({ req, action: 'event.run.cleaned', detail: { runId, ...result.summary } })
// **A 200 whatever the sweep found.** The request succeeded; some resources may
// still be out there, and answering 4xx would make "the shard refused to delete
// three of these" indistinguishable from "you sent a bad run id" — the same
// argument the dry run's findings make.
return res.json({ run: shapeRun(result.run), summary: result.summary })
}
/** POST /api/v1/admin/events/runs/:runId/steps/:stepId/confirm */
exports.confirmStep = async (req, res) => {
const runId = asId(req.params.runId)
const stepId = asId(req.params.stepId)
if (!runId || !stepId) return res.status(400).json({ error: 'bad run or step id' })
const result = await controls.confirmStep(runId, stepId, { note: req.body?.note }, req.user.id)
if (!result.ok) return res.status(result.status || 409).json({ errors: result.errors })
await activity.log({ req, action: 'event.step.confirmed', detail: { runId, stepId, action: result.step.action_id } })
return res.json({ step: shapeStep(result.step) })
}
/** POST /api/v1/admin/events/runs/:runId/steps/:stepId/skip */
exports.skipStep = async (req, res) => {
const runId = asId(req.params.runId)
const stepId = asId(req.params.stepId)
if (!runId || !stepId) return res.status(400).json({ error: 'bad run or step id' })
const result = await controls.skipStep(runId, stepId, { reason: req.body?.reason }, req.user.id)
if (!result.ok) return res.status(result.status || 409).json({ errors: result.errors })
await activity.log({
req,
action: 'event.step.skipped',
detail: { runId, stepId, action: result.step.action_id, reason: req.body?.reason || null },
})
return res.json({ step: shapeStep(result.step) })
}
/** POST /api/v1/admin/events/runs/:runId/steps/:stepId/retry */
exports.retryStep = async (req, res) => {
const runId = asId(req.params.runId)
const stepId = asId(req.params.stepId)
if (!runId || !stepId) return res.status(400).json({ error: 'bad run or step id' })
const result = await controls.retryStep(runId, stepId, {}, req.user.id)
if (!result.ok) return res.status(result.status || 409).json({ errors: result.errors })
await activity.log({ req, action: 'event.step.retried', detail: { runId, stepId, action: result.step.action_id } })
return res.json({ step: shapeStep(result.step), run: shapeRun(result.run), resumed: result.resumed })
}