Module-uo/server/config/uoEventActions.js

// ── module-uo's event verbs, wave 1 ────────────────────────────────────────
//
// EVENTS.md §F, EVENTS_PLAN.md Phase 9. The first three actions an event author
// can put in a step that reach the game, plus the budget dimension that bounds
// one of them and the three option sources the atlas answers.
//
// **Nothing here is new plumbing.** `uoLinkClient` has carried `adminBroadcast`,
// `postTownCrier`/`deleteTownCrier` and `postNews`/`deleteNews` since protocol
// 2.1; the admin screens have driven all three by hand for months. What this file
// adds is the declaration that lets the event engine drive them unattended —
// which is a different question, and the reason most of this file is about what
// happens when a call does NOT come back.
//
// ── The three rules that shape every declaration below ─────────────────────
//
// **1. `budgetMs` must exceed the client's own timeout, or the module never gets
// to classify its own failure.** `dispatch.classify()` answers `retry` for a
// budget timeout unconditionally and a module cannot override that — the module
// is not asked, because it is still awaiting a socket. `uoLinkClient.TIMEOUT_MS`
// is 12s and core's `DEFAULT_BUDGET_MS` is 10s, so on default settings core's
// deadline fires FIRST on every slow shard and the step is retried. Every action
// here therefore declares `budgetMs: 15000`: the client always answers first, and
// what the runner acts on is this file's judgement rather than a race.
//
// That is not a tuning detail. It is the whole of what makes rule 2 true.
//
// **2. A broadcast is attempted exactly once.** `on_failure` is what happens
// AFTER `EVENT_STEP_MAX_ATTEMPTS` retries, and `skip` — the default for `notify`
// — is a disposition, not a retry policy; there is no per-action lever that says
// "do not retry me". The lever a module HAS is the failure envelope, so
// `uo.broadcast` answers `retry: false` to everything. A retried broadcast is a
// second announcement to everyone online, and there is no idempotency key on the
// wire until Phase 11 to make the shard refuse the repeat. A lost announcement is
// cheaper than a doubled one.
//
// **3. What a shard restart wipes, `reconcile()` reports gone — and it knows
// which restart it was without asking.** There is no "list the town-crier lines"
// or "list the news articles" on the wire, and adding one would be protocol work
// for a question the module can already answer: a town-crier line and an
// event-owned news article both live in shard memory, so a restart is
// definitionally the loss of both. `perform()` stamps the shard's `bootId` into
// the resource payload and `reconcile()` reports in force exactly the rows whose
// stamp still matches. That is correct for BOTH callers — the module's own
// `ctx.events.reconcile()` on a changed `bootId`, and core's boot-time sweep,
// where the shard may not have restarted at all and answering "all gone" would
// abandon live rows.

const core = require('../core')
const uoLinkClient = require('../utils/uoLinkClient')
const uoLinkConfig = require('../model/uoLinkConfig/uoLinkConfig.model')
const shardAtlas = require('../model/shardAtlas/shardAtlas.model')
const { classify: classifySidecarWrite } = require('../utils/shardAnnounce')

const log = core.logger('uo-events')

// See rule 1 in the header. Above `uoLinkClient.TIMEOUT_MS` (12s), below core's
// `MAX_BUDGET_MS` (1h) by a mile.
const BUDGET_MS = 15000

// The sidecar's own caps, mirrored from the admin routes that already validate
// against them (`admin/uoLink.router.js` for the crier, `admin/shard.router.js`
// for the broadcast). Pre-checked here so an over-long line is a refusal a DRY
// RUN can show the author, rather than a 400 mid-run.
const MAX_BROADCAST_LEN = 300
const MAX_CRIER_LINES = 8
const MAX_CRIER_LINE_LEN = 200
const MAX_CRIER_DURATION_SEC = 86400
const MAX_NEWS_TITLE = 120
const MAX_NEWS_BODY = 900

// How many options one source will answer with. Real UO facets carry a few
// hundred regions and landmarks and ~800 constructible creature types, so this is
// comfortably above the data rather than a guess at it — and a deployment that
// exceeds it gets a log line naming the source and the counts, because a dropdown
// that silently omits the landmark an author is looking for is the defect this
// bound would otherwise introduce.
const MAX_OPTIONS = 2000

/**
 * The id both keyed verbs post under.
 *
 * The step's idempotency key is `sha256(runId|stepId)` truncated to 40 hex — a
 * function of identity and never of attempt — so a retry re-posts the SAME id and
 * the sidecar replaces rather than stacks. That is the property that makes the
 * crier and the news gump safe to retry and the broadcast not.
 *
 * **The `evt-` prefix is load-bearing for news.** `newsGump.js` posts articles
 * under the bare website post id (`String(post.id)`) and `reassertAll()` re-pushes
 * that whole set on every sidecar reconnect. An event article numbered into the
 * same space would be a collision with a post — silently, and in whichever
 * direction wrote last. 4 + 40 characters, inside the sidecar's 64-char cap.
 */
const resourceId = (idempotencyKey) => `evt-${idempotencyKey}`

/** The shard boot this write belongs to, or null when nothing has connected yet. */
async function currentBootId() {
  try {
    const config = await uoLinkConfig.getSafe()
    return config.bootId || null
  } catch (err) {
    // Never fatal to a world write. A missing stamp means `reconcile()` cannot
    // vouch for the row, which leaves core believing its own ledger — the
    // pre-Phase-8 behaviour, and the right way to be wrong.
    log.warn('could not read the shard boot id for an event resource', { error: err.message })
    return null
  }
}

// Statuses that will never succeed however many times they are tried: a data
// refusal, a bad token, a switched-off write plane, a protocol mismatch. Named
// here rather than folded into `shardAnnounce.classify` because 403 is reachable
// only from the `/admin/*` verbs — the announce leg posts to the town crier,
// which the admin write plane does not gate — and widening a shared classifier
// for a case its own caller cannot produce is how a shared rule stops being one.
const PERMANENT_STATUSES = new Set([400, 401, 403, 404, 409])

/**
 * What the shard actually said, in its own words.
 *
 * **The sidecar explains its refusals and `legError` drops the explanation**, and
 * this was worth its own helper the moment an event started making these calls
 * unattended. A `403` body reads `{"reason":"admin write plane disabled"}`;
 * `legError` looks for `data.message`, finds nothing, and falls back to "sidecar
 * responded 403". For a staff member clicking a button that is survivable — they
 * know what they just switched off. For an event that ran at four in the morning,
 * the run log is the only place anyone will ever learn why, and "403" is not an
 * answer an operator can act on.
 */
function sidecarReason(result, what) {
  const data = (result && result.data) || {}
  return data.reason || data.message || (result && result.error) || `the shard refused the ${what}`
}

/**
 * The sidecar's answer, as an event outcome.
 *
 * **The announce leg's classification, not a second opinion.** `shardAnnounce`
 * already decides what each status from this transport means — 400 a data
 * problem, 401/409 a config problem, everything else transient — and it decides
 * it about the same sidecar over the same client. Two copies of that judgement is
 * how the two drift, which is the argument `core.announce` makes for deferring to
 * a leg's own `classify()`.
 */
function sidecarFailure(result, what) {
  const { outcome } = classifySidecarWrite(result)
  const permanent = PERMANENT_STATUSES.has(result && result.status)
  return {
    ok: false,
    retry: outcome === 'retry' && !permanent,
    error: sidecarReason(result, what),
  }
}

/** Split an authored text block into crier lines, and say why it is not one. */
function crierLines(raw) {
  const lines = String(raw == null ? '' : raw)
    .split(/\r?\n/)
    .map((l) => l.trim())
    .filter(Boolean)
  if (!lines.length) return { ok: false, error: 'the message is empty' }
  if (lines.length > MAX_CRIER_LINES) {
    return { ok: false, error: `the criers carry ${MAX_CRIER_LINES} lines and this is ${lines.length}` }
  }
  const over = lines.find((l) => l.length > MAX_CRIER_LINE_LEN)
  if (over) {
    return {
      ok: false,
      error: `a crier line is capped at ${MAX_CRIER_LINE_LEN} characters and "${over.slice(0, 40)}…" is ${over.length}`,
    }
  }
  return { ok: true, lines }
}

// ── Budgets ────────────────────────────────────────────────────────────────
//
// One dimension, and only `uo.broadcast` spends it (org lead, 2026-09-04). A run
// that broadcasts forty times is the spam failure mode, and a per-run cap is the
// only thing standing between an authoring mistake and every player online. The
// two keyed verbs get none: they are posted under a run-scoped id and a repeat
// REPLACES, so the thing a cap would guard against does not exist for them.

const BUDGETS = [
  {
    id: 'uo.broadcasts',
    label: 'Global broadcasts',
    unit: 'broadcasts',
    description: 'System messages this run may put in front of everyone online.',
  },
]

// ── Actions ────────────────────────────────────────────────────────────────

const ACTIONS = [
  {
    id: 'uo.broadcast',
    label: 'Broadcast to everyone online',
    description:
      'Puts one system message in front of every player currently logged in. Sent once and never retried — a repeat would be a second announcement, and until the shard can refuse a duplicate there is no way to take one back.',

    // Nothing in the world changes and nothing is created; a message goes out.
    // Same class as `core.announce`, and for the same reason — which also gives
    // it `skip` as its default disposition, so a run does not stop over an
    // announcement that did not go out.
    risk: 'notify',
    // There is no undo, and declaring `ledger` would put a row in the cleanup
    // ledger that teardown could never resolve.
    reversible: 'none',
    version: 1,
    budgetMs: BUDGET_MS,

    cost: () => ({ 'uo.broadcasts': 1 }),

    params: [
      {
        name: 'text',
        type: 'string',
        required: true,
        example: 'The gates of Britain open at dusk. Gather at the bank.',
        description: `The message, up to ${MAX_BROADCAST_LEN} characters.`,
      },
      {
        name: 'hue',
        type: 'int',
        required: false,
        example: 1153,
        description: 'UO colour id for the message. Left out, the shard uses its system colour.',
      },
    ],

    async perform({ runId, params, verify }) {
      const text = String(params.text == null ? '' : params.text).trim()
      // Checked here rather than left to the sidecar's 400, so the DRY RUN shows
      // the author the refusal — which is the whole point of having one.
      if (!text) return { ok: false, retry: false, error: 'the message is empty' }
      if (text.length > MAX_BROADCAST_LEN) {
        return {
          ok: false,
          retry: false,
          error: `a broadcast is capped at ${MAX_BROADCAST_LEN} characters and this is ${text.length}`,
        }
      }
      if (verify) return { ok: true }

      // `event:<runId>` (org lead, 2026-09-04). The shard records an actor on
      // every staff write and echoes it back as an `admin.audit` event, so this
      // is what an operator reads in the game's own audit trail afterwards. No
      // staff member pressed a button — attributing it to one would be a false
      // record — and the run id is the thing that makes the line actionable.
      const result = await uoLinkClient.adminBroadcast({
        actor: `event:${runId}`,
        text,
        hue: params.hue === undefined || params.hue === null ? undefined : Number(params.hue),
      })
      if (result.ok) return { ok: true }

      // **Every failure is terminal, deliberately** — see rule 2 in the header.
      // A 503 from a shard that is merely restarting IS transient and this throws
      // that retry away; that is the trade, taken knowingly, because the failure
      // this refuses to risk is announcing twice to everyone online. Phase 11
      // puts an idempotency key on the wire and this line is what changes.
      //
      // **The clause is only added where a retry was genuinely given up**, and
      // the rig is what made that distinction matter. A 403 — the shard's admin
      // write plane switched off — will not succeed on any attempt, so telling an
      // operator it was "not retried because a repeat would announce twice" points
      // them at a policy decision when what they need is the sentence the shard
      // already wrote: "admin write plane disabled". A reason that explains the
      // wrong thing is worse than a bare status code.
      const reason = sidecarReason(result, 'broadcast')
      if (PERMANENT_STATUSES.has(result.status)) return { ok: false, retry: false, error: reason }
      return {
        ok: false,
        retry: false,
        error: `${reason} (not retried: a repeat would announce twice)`,
      }
    },
  },

  {
    id: 'uo.towncrier.post',
    label: 'Post to the town criers',
    description:
      'Puts up to eight lines in the mouths of the town criers for a set time, and takes them down again when the event ends.',

    // `notify` is about what a FAILURE costs — nothing is half-changed and the
    // run should carry on — while `ledger` is about what SUCCESS leaves behind.
    // The two are independent questions and this is the combination where that
    // shows: an announcement that can be withdrawn.
    risk: 'notify',
    reversible: 'ledger',
    version: 1,
    budgetMs: BUDGET_MS,

    params: [
      {
        // **One text block, not a list, because the param vocabulary has no
        // array type** (`VARIABLE_TYPES` is string/int/float/boolean/datetime/url).
        // Splitting on newlines is the honest encoding of eight short lines in a
        // textarea, and the caps are checked before anything is sent.
        name: 'lines',
        type: 'string',
        required: true,
        example: 'Hear ye! The Britain gates open at dusk.\nSeek the herald by the bank.',
        description: `One line per newline. Up to ${MAX_CRIER_LINES} lines of ${MAX_CRIER_LINE_LEN} characters.`,
      },
      {
        name: 'durationMinutes',
        type: 'int',
        required: false,
        example: 60,
        description: 'How long the criers keep saying it. Left out, the shard keeps it for an hour.',
      },
    ],

    async perform({ runId, idempotencyKey, params, verify }) {
      const parsed = crierLines(params.lines)
      if (!parsed.ok) return { ok: false, retry: false, error: parsed.error }

      let durationSec
      if (params.durationMinutes !== undefined && params.durationMinutes !== null) {
        const minutes = Number(params.durationMinutes)
        if (!Number.isFinite(minutes) || minutes <= 0) {
          return { ok: false, retry: false, error: `"${params.durationMinutes}" is not a number of minutes` }
        }
        durationSec = Math.min(Math.round(minutes * 60), MAX_CRIER_DURATION_SEC)
      }

      if (verify) return { ok: true }

      const id = resourceId(idempotencyKey)
      const bootId = await currentBootId()
      const result = await uoLinkClient.postTownCrier({ id, lines: parsed.lines, durationSec })
      if (!result.ok) return sidecarFailure(result, 'town-crier post')

      // The stamp rule 3 rests on. `runId` rides along so a row read out of the
      // ledger says which run put it up without a join.
      return { ok: true, resources: [{ kind: 'towncrier', ref: id, payload: { bootId, runId } }] }
    },

    async revert({ resources }) {
      const failed = []
      for (const resource of resources) {
        const result = await uoLinkClient.deleteTownCrier(resource.ref)
        // §L: "gone, and that is fine" is a successful revert. A crier line whose
        // duration simply ran out is a 404, and it is the outcome we wanted.
        if (!result.ok && result.status !== 404) failed.push(resource.ref)
      }
      if (!failed.length) return { ok: true }
      return { ok: true, failed }
    },

    reconcile: reconcileByBootId,
  },

  {
    id: 'uo.news.post',
    label: 'Post an article to the news gump',
    description:
      "Puts an article in the in-game Town Cryer news window for the life of the event, and pulls it when the event ends. Separate from the site's own news posts, which sync there on their own.",

    risk: 'notify',
    reversible: 'ledger',
    version: 1,
    budgetMs: BUDGET_MS,

    params: [
      {
        name: 'title',
        type: 'string',
        required: true,
        example: 'The Britannian Midsummer Fair',
        description: `The article heading, up to ${MAX_NEWS_TITLE} characters.`,
      },
      {
        name: 'body',
        type: 'string',
        required: true,
        example: 'Merchants from every city gather in Britain for three days of trade and contest.',
        description: `The article, up to ${MAX_NEWS_BODY} characters. Plain text; the gump renders a small HTML subset and this is wrapped for it.`,
      },
      {
        name: 'url',
        type: 'url',
        required: false,
        example: 'https://example.com/site/events',
        description: "The article's \"more info\" link. Left out, the gump shows no link.",
      },
      {
        name: 'image',
        type: 'int',
        required: false,
        example: 5013,
        description: 'A shard art id to illustrate the article. Left out, the sidecar uses a neutral scroll.',
      },
      {
        name: 'announce',
        type: 'boolean',
        required: false,
        example: true,
        description: 'Whether the criers proclaim the title when it goes up. Left out, they do.',
      },
    ],

    async perform({ runId, idempotencyKey, params, verify }) {
      const title = String(params.title == null ? '' : params.title).replace(/\s+/g, ' ').trim()
      const body = String(params.body == null ? '' : params.body).trim()
      if (!title) return { ok: false, retry: false, error: 'the article has no title' }
      if (title.length > MAX_NEWS_TITLE) {
        return {
          ok: false,
          retry: false,
          error: `a news title is capped at ${MAX_NEWS_TITLE} characters and this is ${title.length}`,
        }
      }
      if (!body) return { ok: false, retry: false, error: 'the article has no body' }
      if (body.length > MAX_NEWS_BODY) {
        return {
          ok: false,
          retry: false,
          error: `a news body is capped at ${MAX_NEWS_BODY} characters and this is ${body.length}`,
        }
      }

      if (verify) return { ok: true }

      const id = resourceId(idempotencyKey)
      const bootId = await currentBootId()
      const result = await uoLinkClient.postNews({
        id,
        title,
        // The same gump-HTML shape `newsGump.buildArticle` uses, so an event
        // article and a site article read alike in the window they share.
        body: `<CENTER>${title}</CENTER><BR><BR>${body}`,
        image:
          params.image === undefined || params.image === null ? undefined : Number(params.image),
        url: params.url || undefined,
        announce: params.announce === undefined || params.announce === null ? true : Boolean(params.announce),
      })
      if (!result.ok) return sidecarFailure(result, 'news article')

      return { ok: true, resources: [{ kind: 'news', ref: id, payload: { bootId, runId } }] }
    },

    async revert({ resources }) {
      const failed = []
      for (const resource of resources) {
        const result = await uoLinkClient.deleteNews(resource.ref)
        if (!result.ok && result.status !== 404) failed.push(resource.ref)
      }
      if (!failed.length) return { ok: true }
      return { ok: true, failed }
    },

    reconcile: reconcileByBootId,
  },
]

/**
 * Which of these does the shard still have? — answered from the boot stamp.
 *
 * Shared by both keyed verbs because the answer has the same shape for both:
 * shard memory, lost on restart. See rule 3 in the header for why this needs no
 * round trip and why it must not simply answer "all gone".
 *
 * **A row with no stamp is reported IN FORCE.** It was written by a build before
 * the stamp existed, or by a `perform()` whose config read hiccuped, and "I do not
 * know" must never be read as "it is gone" — core orphans exactly what this omits,
 * and an orphaned row is one teardown will never try to take back.
 */
async function reconcileByBootId({ resources }) {
  const bootId = await currentBootId()
  // Nothing has connected since this process came up, so there is no current boot
  // to compare against. Declining to answer leaves core believing its ledger.
  if (!bootId) return { ok: false, error: 'the shard has not identified itself since boot' }
  const inForce = resources
    .filter((r) => {
      const stamped = r.payload && r.payload.bootId
      return !stamped || stamped === bootId
    })
    .map((r) => r.ref)
  return { ok: true, inForce }
}

// ── Option sources ─────────────────────────────────────────────────────────
//
// Answered from the spawn atlas, which is derived from the operator's own ServUO
// tree on every boot and stored — so these resolve with the shard down, which is
// the property that makes them safe to put behind an authoring form.
//
// **Wave 1's three verbs use none of them.** They ship here rather than with
// their consumers in Phase 12 (org lead, 2026-09-04) because they cost nothing
// new, and Phase 12 is a five-repo protocol bump that should not also be carrying
// its first atlas plumbing. `/admin/events/catalog/options/:sourceId` exercises
// them today.
//
// **A place is named `facet/name`, not `name`.** Two facets both have a Britain,
// and a value that can name two different places is a value a Phase 12 step
// cannot act on. The author reads the label and the group; the stored value is
// unambiguous.

/** Bound one source's answer, and say so when the atlas is bigger than the bound. */
function bounded(rows, sourceId) {
  if (rows.length <= MAX_OPTIONS) return rows
  log.warn('option source truncated — the atlas is larger than the dropdown bound', {
    source: sourceId,
    available: rows.length,
    served: MAX_OPTIONS,
  })
  return rows.slice(0, MAX_OPTIONS)
}

const OPTION_SOURCES = [
  {
    id: 'uo.options.regions',
    label: 'Regions',
    description: "Named regions from the shard's own map definitions, by facet.",
    async resolve() {
      const rows = await shardAtlas.listRegions()
      return bounded(rows, 'uo.options.regions').map((r) => ({
        value: `${r.facet}/${r.name}`,
        label: r.name,
        group: r.facet,
      }))
    },
  },
  {
    id: 'uo.options.landmarks',
    label: 'Landmarks',
    description: 'Named points of interest — towns, dungeons, moongates — by facet.',
    async resolve() {
      const rows = await shardAtlas.listLandmarks()
      return bounded(rows, 'uo.options.landmarks').map((r) => ({
        value: `${r.facet}/${r.name}`,
        label: r.name,
        // The atlas's own grouping where it has one, the facet otherwise — so a
        // shard whose landmark file carries no groups still gets a usable
        // dropdown rather than one flat list of several hundred names.
        group: r.group || r.facet,
      }))
    },
  },
  {
    id: 'uo.options.creatures',
    label: 'Creatures',
    description: 'Creature types the shard actually spawns, from the spawn atlas.',
    async resolve() {
      // The slug is unique by construction, so unlike a place a creature needs no
      // qualifier: it is the same type wherever it spawns.
      const { creatures } = await shardAtlas.searchCreatures({ limit: MAX_OPTIONS })
      return creatures.map((c) => ({ value: c.slug, label: c.name }))
    },
  },
]

module.exports = {
  ACTIONS,
  BUDGETS,
  OPTION_SOURCES,
  // Exported for the tests, which assert the caps and the classification rules
  // against the same constants the declarations use rather than against literals
  // that could drift from them.
  BUDGET_MS,
  MAX_BROADCAST_LEN,
  MAX_CRIER_LINES,
  MAX_CRIER_LINE_LEN,
  MAX_NEWS_TITLE,
  MAX_NEWS_BODY,
  MAX_OPTIONS,
  PERMANENT_STATUSES,
  sidecarReason,
  resourceId,
  crierLines,
  reconcileByBootId,
}