feat(events): the resource ledger, leases and cleanup (Phase 8)

Event System Phase 8 (EVENTS_PLAN.md). Docs half: RunicGateway/docs#NNN.

One table, one core action, one route, one body field, and two members added to
MODULE_API 1.10.0 in place. The safety property the whole world-write half
depends on: core now remembers what a run changed in the world, and gives it
back on every terminal path.

Four decisions settled by the org lead on 2026-09-03, all as recommended:

- A lease is acquired by a new CORE action, `core.lease`. Section F puts the
  duration bound and the two-events-one-target conflict check on core's side of
  the seam, and a lease verb per module would be both re-implemented once per
  module, advisory everywhere.
- Record-before-confirm is a PLACEHOLDER keyed by the step's idempotency key. A
  spawn's ref does not exist until the module answers, so what core writes
  before the dispatch is `kind: '@step'`, `ref` = that key. If the answer never
  comes it stands, and cleanup calls revert() with the key and no resources --
  which is why section F's revert takes the key at all.
- Cleanup is one sweep over the ledger, not synthetic step rows. The
  step-shaped version costs a second retry counter beside `revert_attempts`.
- `reconcile` is declared here and TRIGGERED BY THE MODULE, through
  `ctx.events.reconcile()`. Core has no concept of the game being up, so it
  cannot decide when to ask; it asks once at its own boot.

MODULE_API stays 1.10.0. A protocol owes a bump once it has landed on `main`;
while it is on `edge` it is amended in place, so the whole module contract
reaches an author as one version they read once.

Verify

- `npm test` -- 2025 tests, 1935 pass, 89 skipped, 1 fail. That one is the
  pre-existing engagementManifest CRLF failure, in a file this branch does not
  touch (`edge` before: 1950/1876/73/1). +75 tests.
- The unique key was proved against a REAL MariaDB, because nothing else can
  prove it: whether multiple NULLs collide in a unique index, whether a STORED
  generated column is recomputed on UPDATE, and whether the SET NULL foreign key
  survives beside it are properties of the server. eventRunnerSql.test.js gained
  16 tests; 65 pass against the container. The real schema.sql was applied to a
  fresh database and to an existing one.
- Client: 362 pass, and it builds. routes:manifest and swagger -- one route
  added, none moved.

The live walk found three defects, and two of them are the phase's real finding

Driven by a throwaway `rig` module in website/modules/, deleted before commit.

1. A lease was never given back at all. `core.lease` reserves its own ledger
   row, so it never went through the ledger's dirty-marking, so a run holding
   only a lease kept `cleanup_status = 'not_required'` and the cleanup leg --
   which selected on `pending` -- never looked at it.
2. EVENT_REVERT_MAX_ATTEMPTS meant one attempt, not three. The first failing
   sweep moved the run to `incomplete`, which took it out of the leg's own scan
   for ever. The test covering the bound asserted `<= 3` and was satisfied by 1:
   a bound has two halves, and a test that only asserts the ceiling passes
   against a floor.
3. The first fix for (2) made the console lie. Spending every row's
   `revert_attempts` was a tidy way to take a `cleanup: false` run out of a
   counter-bounded scan, and the run page then rendered "3 attempts" beside
   resources nothing had ever tried. Found by opening the page.

Both (1) and (2) are the same mistake: deriving "is there anything to do" from a
summary column instead of from the rows. Neither was visible to a unit test,
because a test that calls the sweep directly never asks what would have selected
the run.

The two properties that need the process to die were walked as the plan asks.
With the module's perform() hanging, the placeholder existed while the dispatch
was in flight and nothing was named; after taskkill and a restart the reclaim
re-dispatched the same idempotency key, the retry re-used its own placeholder,
and everything was given back. Then, with the module reporting one of two
resources as no longer in force, the boot-time reconcile marked the other
`orphaned` -- never `reverted`.

This branch does NOT bump MODULE_API_VERSION, so the integration kit stays as
Phase 7 left it: red until the Phase 16 cutover re-pins ci/core-ref.json.

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

server/src/events/ledger.js

@@ -0,0 +1,221 @@
+// ── Recording what a run changed in the world ──────────────────────────────
+//
+// EVENTS.md §D and §L, and Phase 8 of EVENTS_PLAN.md. The write half of the
+// resource ledger; `events/cleanup.js` is the read-and-undo half.
+//
+// **Rule 1 is the whole reason this file is not two lines inside `drainStep`.**
+// A resource is recorded BEFORE it is confirmed. The obstacle is that a spawn's
+// serial does not exist until the module answers, so there is nothing to write a
+// row about yet — which is why what goes in before the dispatch is a PLACEHOLDER
+// keyed by the step's idempotency key rather than by the object:
+//
+//     pre-dispatch   INSERT pending { kind: '@step', ref: <idempotency key> }
+//     answer         INSERT confirmed { kind: 'creature', ref: '0x40001234' } × n
+//                    resolve the placeholder
+//     ack lost       the placeholder is still `pending`
+//     cleanup        revert({ idempotencyKey, resources: [] })
+//
+// That last line is why §F's `revert({ runId, resources, idempotencyKey })` takes
+// the key at all. A module that half-ran and never answered is reachable by its
+// key and by nothing else, and Phase 11's plugin-side key ledger is what makes
+// answering it exact. Until then the contract is still honest, because §L
+// requires reverting something that does not exist to be a SUCCESS.
+//
+// **Recording is idempotent, and the database is what makes it so.** A retry
+// re-dispatches the same idempotency key, and a module that answers with the same
+// resources twice must not produce two rows. `uq_evres_target` refuses the second
+// insert, and this file reads that refusal as "already recorded" rather than as an
+// error — the same posture `materialisePhase`'s INSERT IGNORE takes.
+//
+// **A lease does not use the placeholder.** Its target is knowable before the
+// dispatch — it is the lease id the step names — so `core.lease` reserves the
+// real row first, which is both a stronger form of rule 1 and the only place the
+// two-events-one-target refusal can happen before the world has been written to.
+
+const resourcesDb = require('../model/events/eventRunResources.db')
+const runsDb = require('../model/events/eventRuns.db')
+const registries = require('../modules/registries')
+const log = require('../utils/logger')('events')
+
+// Which reversible classes get a pre-dispatch placeholder. `none` is gone once
+// done and `self` undoes itself, so neither has anything core could come back
+// for; `override` reserves its own target instead (see the header). That leaves
+// `ledger` — the class that declares `revert()`, which is exactly the class whose
+// refs core cannot know until the module speaks.
+const PLACEHOLDER_CLASSES = ['ledger']
+
+// A resource `kind` may be anything a module likes except core's own reserved
+// one. Bounded to the column, and refused rather than truncated: a truncated ref
+// is a cleanup call naming the wrong object.
+const MAX_KIND = 64
+const MAX_REF = 190
+const MAX_MEMBER_KEY = 190
+
+/** Does this action produce anything core will have to come back for? */
+const ledgers = (action) => action && (action.reversible === 'ledger' || action.reversible === 'override')
+
+/**
+ * Turn one entry of a module's `resources` array into a row, or say why not.
+ *
+ * Every failure here is the module's mistake rather than the world's, so none of
+ * them is a retry: a badly shaped resource will be just as badly shaped on the
+ * second attempt. They are logged and dropped, and the step still counts as done
+ * — because it IS done; something happened in the world, and refusing to record
+ * it would be the one outcome worse than recording it imperfectly.
+ */
+function normalise(entry, actionId) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return { ok: false, reason: `${actionId} reported a resource that is not an object` }
+  }
+  const kind = String(entry.kind || '')
+  const ref = String(entry.ref === undefined || entry.ref === null ? '' : entry.ref)
+  if (!kind || kind.length > MAX_KIND) {
+    return { ok: false, reason: `${actionId} reported a resource with a bad kind "${entry.kind}"` }
+  }
+  if (kind === resourcesDb.STEP_KIND) {
+    // Core's own. A module that could write one would be a module that could make
+    // its own step's placeholder look resolved.
+    return { ok: false, reason: `${actionId} reported a resource of the reserved kind "${kind}"` }
+  }
+  if (!ref || ref.length > MAX_REF) {
+    return { ok: false, reason: `${actionId} reported a resource with a bad ref "${entry.ref}"` }
+  }
+  const memberKey = entry.memberKey === undefined || entry.memberKey === null ? null : String(entry.memberKey)
+  if (memberKey !== null && memberKey.length > MAX_MEMBER_KEY) {
+    return { ok: false, reason: `${actionId} reported a resource with an over-long memberKey` }
+  }
+
+  let leaseUntil = null
+  if (entry.until !== undefined && entry.until !== null) {
+    const at = new Date(entry.until)
+    if (Number.isNaN(at.getTime())) {
+      return { ok: false, reason: `${actionId} reported a resource with a bad until "${entry.until}"` }
+    }
+    leaseUntil = at
+  }
+
+  // A borrowed value must name a lease core knows how to give back. Core restores
+  // an `override` through the lease registry — that is the split §F draws — so a
+  // ref naming nothing registered is a resource core would be recording with no
+  // way to undo it, which is the promise rule 2 exists to stop core making.
+  if (kind === 'override' && !registries.eventLease(ref)) {
+    return { ok: false, reason: `${actionId} reported a lease "${ref}" no module registers` }
+  }
+
+  return {
+    ok: true,
+    row: {
+      kind,
+      ref,
+      payload: entry.payload === undefined ? null : entry.payload,
+      leaseUntil,
+      memberKey,
+    },
+  }
+}
+
+/**
+ * Write the pre-dispatch placeholder for a step that is about to change the
+ * world. Answers the row id, or null when this action ledgers nothing.
+ *
+ * **A duplicate is not a failure.** A retry re-uses its step's idempotency key, so
+ * the second attempt's placeholder collides with the first's — and finding it
+ * already there is the correct answer, not an error. The existing row is reused.
+ */
+async function reserveStep(run, step, action) {
+  if (!ledgers(action) || !PLACEHOLDER_CLASSES.includes(action.reversible)) return null
+
+  const owner = action.owner || 'core'
+  const reserved = await resourcesDb.reserve({
+    runId: run.id,
+    stepId: step.id,
+    owner,
+    kind: resourcesDb.STEP_KIND,
+    ref: step.idempotency_key,
+    payload: { action: action.id, phase: step.phase, seq: step.seq },
+  })
+  if (reserved.ok) {
+    await markRunDirty(run.id)
+    return reserved.id
+  }
+  // The only way a '@step' row collides is with this step's own earlier attempt,
+  // because an idempotency key is minted once per step and never varies by
+  // attempt (§E). Reuse it.
+  const existing = await resourcesDb.findByTarget(owner, resourcesDb.STEP_KIND, step.idempotency_key)
+  return existing ? existing.id : null
+}
+
+/**
+ * Record what a module said it made, and close out the placeholder.
+ *
+ * Answers `{ recorded, rejected }` — how many rows went in, and the reasons any
+ * entry was dropped. Never throws: a step that changed the world has changed it,
+ * and a ledger that threw would turn a bookkeeping problem into a failed step and
+ * then into a retry of a world write that already happened.
+ */
+async function recordAnswer({ run, step, action, placeholderId, resources }) {
+  const out = { recorded: 0, rejected: [] }
+  if (!ledgers(action)) return out
+
+  const owner = action.owner || 'core'
+  const list = Array.isArray(resources) ? resources : []
+
+  for (const entry of list) {
+    const parsed = normalise(entry, action.id)
+    if (!parsed.ok) {
+      out.rejected.push(parsed.reason)
+      log.warn('event resource rejected', { run: run.id, step: step.id, reason: parsed.reason })
+      continue
+    }
+    try {
+      const reserved = await resourcesDb.reserve({
+        runId: run.id,
+        stepId: step.id,
+        owner,
+        kind: parsed.row.kind,
+        ref: parsed.row.ref,
+        payload: parsed.row.payload,
+        leaseUntil: parsed.row.leaseUntil,
+        memberKey: parsed.row.memberKey,
+      })
+      if (!reserved.ok) {
+        // Already ledgered — by this step's own earlier attempt, or (a module bug
+        // rather than a race) by another run that still holds the same target.
+        // Either way there is a live row for it and a second would be the double
+        // cleanup the unique key exists to prevent.
+        if (reserved.holder && reserved.holder.run_id !== run.id) {
+          out.rejected.push(`${parsed.row.kind} "${parsed.row.ref}" is already held by run ${reserved.holder.run_id}`)
+        }
+        continue
+      }
+      await resourcesDb.confirm(reserved.id)
+      out.recorded += 1
+    } catch (err) {
+      // Bookkeeping must not become the step's control flow.
+      out.rejected.push(err.message)
+      log.error('event resource insert failed', { run: run.id, step: step.id, message: err.message })
+    }
+  }
+
+  if (out.recorded > 0) await markRunDirty(run.id)
+
+  // The placeholder's job is over the moment the real rows exist. It is resolved
+  // even when the module reported nothing at all — an action that ledgers and
+  // then answers `ok` with an empty list is saying "I made nothing", and holding
+  // its placeholder open would make cleanup call `revert()` for a step that has
+  // nothing to give back on every terminal path for ever.
+  if (placeholderId) await resourcesDb.resolvePlaceholder(placeholderId)
+
+  return out
+}
+
+/**
+ * There is now something to clean up. Idempotent and guarded, so it can never
+ * walk a run back from `complete` or `incomplete` to `pending` — only a human's
+ * cleanup does that, and it does it deliberately.
+ */
+async function markRunDirty(runId) {
+  await runsDb.setCleanupStatus(runId, 'pending', ['not_required'])
+}
+
+module.exports = { ledgers, normalise, reserveStep, recordAnswer, markRunDirty, PLACEHOLDER_CLASSES }