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 retried, and protocol 6 is what changed that.** Wave 1
// shipped `uo.broadcast` answering `retry: false` to everything, because a
// retried broadcast was a second announcement to everyone online and nothing on
// the wire could make the shard refuse the repeat. A lost announcement was
// cheaper than a doubled one, and that was the whole argument.
//
// Protocol 6 removes its premise. Every write below now carries the step's
// `idempotencyKey`; the shard executes a key at most once and answers a repeat
// with the ORIGINAL reply rather than re-running it. So a retry of a broadcast
// whose acknowledgement was lost cannot announce twice — it collects the answer
// the first attempt never delivered. A shard restarting mid-run is now recovered
// from rather than written off, which is the case rule 2 used to throw away
// knowingly.
//
// Rule 1 is what keeps this true rather than merely intended: if core's deadline
// fired first the module would never be asked, and the retry would be core's
// unconditional one — carrying the same key, so still safe, but classified
// without the module's judgement.

// **2a. The one status that is new here.** A repeat arriving while the original
// is still in flight on the shard is answered `bridge.busy`, which the sidecar
// maps to **425**. It is transient by construction: the work is happening. It is
// not in `PERMANENT_STATUSES` and `classify()` falls through to retry, so it
// needs no arm of its own — but it is named so that a future tightening of that
// list has to decide about it deliberately.
//
// **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.',
  },
]

// ── Participation (protocol 6 part b, EVENTS_PLAN.md Phase 11b) ────────────
//
// EVENTS.md §G rates participation attribution as the largest remaining piece of
// new UO work and says why nothing composed out of the existing streams stands in
// for it: `region.enter` plus `mob.killed` is loosely composable and NOT
// trustworthy enough to publish results on. Nothing scopes a kill or an arrival to
// a run, nothing separates a passer-by from an attendee, and nothing survives a
// relog.
//
// So the shard counts, and reports one opaque number per member. Core stores the
// number and never interprets it, which is what keeps the engine game-agnostic:
// "a minute present plus five a kill" is a sentence about Ultima Online.
//
// **Members are keyed by character serial**, matching this module's Teams
// `memberKey` (`teamProvider.model.js`), so one module speaks one member
// vocabulary and a participant joins to a roster without a translation table.

/** The widest area an event may declare, mirroring the shard's own bound. */
const MAX_AREA_RADIUS = 300

/**
 * A shard-reported `webId` as a website user id, or undefined.
 *
 * The shard writes this only for an account that is actually linked, so most
 * characters carry none and `undefined` is the ordinary answer rather than a
 * failure. Checked rather than coerced, because core refuses a `userId` that is
 * not a positive integer and it is right to: the column is a foreign key into
 * `users`, and a non-number that happened to survive a coercion would attribute
 * somebody's attendance to a stranger.
 */
function webUserId(webId) {
  if (webId === undefined || webId === null || webId === '') return undefined
  const n = Number(webId)
  return Number.isInteger(n) && n > 0 ? n : undefined
}

/** Resolve a `facet/name` landmark to the point the shard counts around. */
async function landmarkPoint(value) {
  const raw = String(value == null ? '' : value)
  const cut = raw.indexOf('/')
  if (cut < 1) {
    return { ok: false, error: `"${raw}" is not a facet/name place` }
  }

  const facet = raw.slice(0, cut)
  const name = raw.slice(cut + 1)
  const rows = await shardAtlas.listLandmarks({ facet })
  const hit = rows.find((r) => r.facet === facet && r.name === name)

  if (!hit) {
    return { ok: false, error: `this shard's atlas has no landmark called "${name}" on ${facet}` }
  }
  return { ok: true, map: hit.facet, x: hit.x, y: hit.y }
}

// ── 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, idempotencyKey, 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),
        // Protocol 6, and the line rule 2 said would change. The key is the
        // step's, so every attempt at this step carries the same one and the
        // shard refuses the repeat — which is what makes the retry below safe to
        // ask for at all.
        idempotencyKey,
      })
      if (result.ok) return { ok: true }

      // **A transient failure is now retried**, where wave 1 gave up on it. What
      // used to make a retry unsafe was that the shard could not tell a repeat
      // from a fresh command; it can now, so a 503 from a shard that is merely
      // restarting is recovered from instead of being written off.
      //
      // The classification itself is `sidecarFailure`'s — the announce leg's own
      // judgement about this transport, deferred to rather than second-guessed,
      // exactly as the two keyed verbs below already do. That this action now
      // uses the SAME helper as its siblings, instead of a hand-rolled variant
      // that forced every outcome terminal, is most of the change here.
      return sidecarFailure(result, 'broadcast')
    },
  },

  {
    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()
      // Protocol 6. This verb was already safe to retry — a repeat under the same
      // `id` REPLACES the crier entry rather than stacking a second one — so the
      // key buys no new safety here. It is sent because it costs nothing and
      // makes the retry a no-op on the shard rather than a redundant world write,
      // and because a write plane where only some commands are keyed is one
      // somebody will later have to reason about per verb.
      const result = await uoLinkClient.postTownCrier({
        id,
        lines: parsed.lines,
        durationSec,
        idempotencyKey,
      })
      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),
        // Protocol 6, for the same reason the crier carries one — except that
        // here it does buy something. `announce: true` makes the criers proclaim
        // the article's title when it is posted, so a re-post under the same id
        // replaces the article silently but proclaims it AGAIN. The key stops the
        // second proclamation, which was the one part of this verb that was never
        // as idempotent as its `id` made it look.
        idempotencyKey,
      })
      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,
  },

  {
    id: 'uo.participation.open',
    label: 'Start counting who takes part',
    description:
      'Declares where this event happens and starts crediting the players who are there. Presence plus kill credit inside the area, counted on the shard and kept in its world save, so a restart mid-event does not lose the tally.',

    // **`inspect`, not `change`.** Nothing in the world moves and no player can
    // see it: the shard starts keeping a tally about a place. §K puts the
    // default-off line between `inspect` and `change`, and a step that only
    // watches is not one an operator should have to switch on before an event can
    // record who came.
    risk: 'inspect',
    // Ledgered anyway, because the shard IS holding something on this run's
    // behalf — one of a bounded number of counting slots — and teardown has to
    // give it back. Reversibility is about what a run owes, not about how loud it
    // was in taking it.
    reversible: 'ledger',
    version: 1,
    budgetMs: BUDGET_MS,

    params: [
      {
        name: 'place',
        type: 'string',
        required: true,
        example: 'Felucca/Britain',
        source: 'uo.options.landmarks',
        description: 'Where the event happens. The tally counts a circle around this point.',
      },
      {
        name: 'radius',
        type: 'int',
        required: true,
        example: 40,
        description: `How many tiles around it count as being there, up to ${MAX_AREA_RADIUS}.`,
      },
      {
        name: 'durationMinutes',
        type: 'int',
        required: false,
        example: 240,
        description:
          'How long to keep counting if nothing closes it. Left out, the shard counts until teardown.',
      },
    ],

    async perform({ runId, idempotencyKey, params, verify }) {
      const radius = Number(params.radius)
      if (!Number.isInteger(radius) || radius < 1 || radius > MAX_AREA_RADIUS) {
        return {
          ok: false,
          retry: false,
          error: `an area is 1 to ${MAX_AREA_RADIUS} tiles, and "${params.radius}" is not`,
        }
      }

      const point = await landmarkPoint(params.place)
      if (!point.ok) return { ok: false, retry: false, error: point.error }

      let holdMs
      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` }
        }
        holdMs = Math.round(minutes * 60_000)
      }

      if (verify) return { ok: true }

      const result = await uoLinkClient.openParticipation({
        runId,
        map: point.map,
        x: point.x,
        y: point.y,
        radius,
        holdMs,
        idempotencyKey,
      })
      if (!result.ok) return sidecarFailure(result, 'participation open')

      // **No `bootId` stamp, and that is the point of the phase.** Every other
      // resource in this file is stamped with the shard boot that made it, because
      // a town-crier line and a news article live in shard memory and a restart is
      // definitionally the loss of both. A participation ledger is the first thing
      // this bridge PERSISTS: it is in the world save, so it survives the restart
      // that would have proved the others gone. Reconcile has to ask.
      return {
        ok: true,
        resources: [{ kind: 'participation', ref: String(runId), payload: { runId, place: params.place, radius } }],
      }
    },

    async revert({ resources }) {
      const failed = []
      for (const resource of resources) {
        const result = await uoLinkClient.closeParticipation({ runId: resource.ref })
        // §L: "gone, and that is fine" is a successful revert. A run the shard has
        // already forgotten answers `known: false` with a 200 for exactly this.
        if (!result.ok && result.status !== 404) failed.push(resource.ref)
      }
      if (!failed.length) return { ok: true }
      return { ok: true, failed }
    },

    /**
     * **Not `reconcileByBootId`, and this is the one resource for which that is
     * true.** The boot-stamp trick works because a crier line and a news article
     * live in shard memory, so a changed `bootId` IS the proof they are gone. A
     * participation ledger is written into the world save specifically so that it
     * survives a restart, and reporting it lost on a boot change would orphan the
     * one resource the phase went to the trouble of persisting.
     *
     * So it asks. A 404 is the shard saying it is not counting that run; anything
     * else unanswerable leaves the row alone.
     */
    async reconcile({ resources }) {
      const inForce = []
      for (const resource of resources) {
        const result = await uoLinkClient.snapshotParticipation({ runId: resource.ref })
        if (result.ok) {
          inForce.push(resource.ref)
          continue
        }
        // Only an explicit "I am not counting that" takes a row out. A shard that
        // is down, slow or refusing has not said the ledger is gone.
        if (result.status !== 404) inForce.push(resource.ref)
      }
      return { ok: true, inForce }
    },
  },

  {
    id: 'uo.participation.collect',
    label: 'Record who took part',
    description:
      "Reads the shard's tally for this run and files it as the run's participants, so results and player history have something true to render.",

    risk: 'inspect',
    // Nothing is created and nothing is owed. The rows it writes are core's
    // `event_run_participants`, whose `UNIQUE (run_id, member_key)` makes a
    // retried collect an upsert rather than a doubled leaderboard.
    reversible: 'none',
    version: 1,
    budgetMs: BUDGET_MS,

    params: [],

    async perform({ runId, idempotencyKey, verify }) {
      if (verify) return { ok: true }

      const result = await uoLinkClient.snapshotParticipation({ runId, idempotencyKey })
      if (!result.ok) {
        // 425 is `bridge.busy`: a snapshot of this run is already walking on the
        // shard. Transient by construction — the work is happening — and it is not
        // in `PERMANENT_STATUSES`, so `sidecarFailure` classifies it retry without
        // needing an arm of its own.
        return sidecarFailure(result, 'participation tally')
      }

      const rows = (result.data && result.data.participants) || []

      return {
        ok: true,
        participants: rows.map((row) => ({
          // The serial, which is this module's member vocabulary everywhere.
          memberKey: row.serial,
          // **Resolved here, and only when the shard could resolve it.** A
          // `userId` is a foreign key into `users`, and core refuses anything that
          // is not a positive integer rather than coercing — a character serial
          // passed here would either fail the insert or, worse, attribute
          // somebody's attendance to a stranger who happened to hold that id.
          userId: webUserId(row.webId),
          score: row.score,
          joinedAt: row.firstMs ? new Date(row.firstMs) : undefined,
          // Opaque to core, and carried so a results table can say WHY somebody
          // scored what they did. A number an operator can only believe or not is
          // a number they will not defend when a player argues with it.
          meta: {
            name: row.name || null,
            seconds: row.seconds,
            minutes: row.minutes,
            kills: row.kills,
          },
        })),
      }
    },
  },
]

/**
 * 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 }
}

// ── Leases (protocol 6 part b, EVENTS_PLAN.md Phase 11b) ───────────────────
//
// **One key, and the catalog is short because ServUO made it short.** EVENTS.md
// §D describes the 258 `Config.Get` call sites as splitting into two patterns —
// cached at type initialisation, where a lease applies cleanly and does nothing,
// and read live, where it takes effect at once. Measured on 57.4 the split is not
// near even: of the 158 non-Bridge sites in `Scripts/`, roughly eight are live
// reads. Phase 11b ships the one that is both live and observable, and Phase 12
// adds the rest behind the boot-time self-check that drops a key which does not
// take.
//
// The module never writes a lease and never bounds one. An author puts
// `core.lease` in a step; core reads the baseline, reserves the target against
// the two-events-one-target index, applies the value with its deadline and
// restores it at teardown through `restore()` below. What is here is the three
// callables, plus the fourth this phase added.

/** How long core will let this deployment hold a config lease. Twelve hours. */
const MAX_LEASE_MS = 12 * 60 * 60 * 1000

/** The shard's lease list, or null when it could not be read. */
async function leaseRow(key) {
  const result = await uoLinkClient.getLeases()
  if (!result.ok) return null
  const rows = (result.data && result.data.leases) || []
  return rows.find((r) => r && r.key === key) || null
}

const LEASES = [
  {
    id: 'uo.playercaps.skillcap',
    label: 'Starting skill cap',
    description:
      "The per-skill cap a newly created character starts with. Read live at character creation, so it applies to everyone made while the lease is held and to nobody made before it.",
    type: 'float',
    // The shard enforces the same bounds independently, and that duplication is
    // deliberate: this pair is what core checks at AUTHORING time so a bad value
    // is a refusal on a form, and the shard's pair is what is true when the
    // website is wrong.
    min: 1000,
    max: 1500,
    maxDurationMs: MAX_LEASE_MS,

    async read() {
      const row = await leaseRow('PlayerCaps.SkillCap')
      if (!row) return { ok: false, error: 'the shard did not report its lease catalog' }
      return { ok: true, value: row.current }
    },

    async apply(value, until) {
      // **A duration, not the deadline.** `until` is an absolute time computed
      // here and honoured there, which is a deadline measured against two clocks;
      // a shard running ten minutes fast would restore a ten-minute lease the
      // instant it took it. The absolute time still rides along, because a
      // console that can say when the hold ends is worth the extra field.
      const holdMs = new Date(until).getTime() - Date.now()
      if (!Number.isFinite(holdMs) || holdMs <= 0) {
        return { ok: false, error: 'the lease deadline has already passed' }
      }

      const result = await uoLinkClient.applyLease({
        key: 'PlayerCaps.SkillCap',
        value,
        holdMs: Math.round(holdMs),
        untilMs: new Date(until).getTime(),
      })
      if (!result.ok) return { ok: false, error: sidecarReason(result, 'lease') }
      return { ok: true }
    },

    async restore(baseline, { expected } = {}) {
      const result = await uoLinkClient.releaseLease({
        key: 'PlayerCaps.SkillCap',
        expected,
        baseline,
      })

      // **Drift is a 200 carrying `lease.drifted`, not an HTTP failure**, because
      // the shard did exactly what it was asked: it compared, and it declined to
      // overwrite somebody's deliberate change. Core records that as a distinct
      // successful outcome rather than an error, so the shape it wants back is
      // `{ ok: false, drifted: true, current }` and not a thrown call.
      if (result.ok && result.data && result.data.kind === 'lease.drifted') {
        return { ok: false, drifted: true, current: result.data.current }
      }

      if (!result.ok) return { ok: false, error: sidecarReason(result, 'lease release') }
      return { ok: true }
    },

    /**
     * Whether the shard still has a record of the hold (Phase 11b).
     *
     * **Not a comparison against `read()`**, and the difference is the whole
     * reason this callable exists. A value that differs from what the run applied
     * is DRIFT, which `restore()` above reports so the ledger row lands `drifted`
     * with the current value beside it; answering "not in force" here would orphan
     * the row first and tell the operator the lease vanished rather than that
     * somebody moved it.
     *
     * A config lease is memory-only on the shard, so a restart reverts it and the
     * catalog reports `held: false` — which is exactly the case core could not see
     * before this phase, and the reason a restarted shard used to leave a run
     * hunting a baseline nobody was holding.
     */
    async inForce() {
      const row = await leaseRow('PlayerCaps.SkillCap')
      if (!row) return { ok: false, error: 'the shard did not report its lease catalog' }
      return { ok: true, held: row.held === true }
    },
  },
]

// ── 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,
  LEASES,
  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,
  MAX_AREA_RADIUS,
  MAX_LEASE_MS,
  PERMANENT_STATUSES,
  webUserId,
  landmarkPoint,
  sidecarReason,
  resourceId,
  crierLines,
  reconcileByBootId,
}