@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.40.0

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-board-session.mjs

@@ -0,0 +1,840 @@
+// The board responder (DEC-0078, FAA-12b): a board session over the hub, the fsynced checkpoint, the request a handler sees and the responder loop.
+// Part of the Node board connector (FAA-65, layer L4); the twin of fabric_board_session.py. Node 20+, no dependency.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Backoff, HubError, MCP_PROTOCOL_VERSION, normalProject, postMcp, toolAnswer } from './fabric-hub.mjs';
+import { acceptedRevisions, atomicWrite, ensurePrivateDir, feedDataProblems, negotiateRevision } from './fabric-service.mjs';
+import { BoardError, CAPABILITY, REQUEST_STATES, RESPOND_TOOLS, SUMMARY_MAX, Stopped, isInt, isObj, outcomeProblems, receiptProblems, refusalProblems } from './fabric-board-shapes.mjs';
+
+export const RENEW_SECONDS = 20;
+
+export const POLL_SECONDS = 15;
+
+export const POLL_JITTER_SECONDS = 5;
+
+export const DRAIN_SECONDS = 10;
+
+export const EVENT_SCHEMA = 'urn:fabric:schema:board-responder-event:1';
+
+export const STOP_CODES = Object.freeze(new Set(['fenced', 'lease_expired', 'authority_changed']));
+
+const TERMINAL = new Set(['completed', 'failed_known', 'cancelled', 'expired']);
+
+/** How long a held slot waits before it asks again: doubling from the poll interval, never past this. */
+export const HOLD_RETRY_MAX_SECONDS = 900;
+
+/** MCP over HTTP with a board session's one-session bearer; calls are serialised; close() sends the session's DELETE. */
+export class BoardSession {
+  constructor(grant, { timeout = 15000, post = postMcp } = {}) {
+    Object.assign(this, { grant, timeout, post });
+    this.mcpSession = null;
+    this.protocolVersion = MCP_PROTOCOL_VERSION;
+    this.rpc = 0;
+    this.queue = Promise.resolve();
+  }
+
+  #serial(fn) {
+    const run = this.queue.then(fn, fn);
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  async #send(body, method = 'POST') {
+    try {
+      return await this.post(this.grant.origin, body, this.grant.bearer(), { session: this.mcpSession, timeout: this.timeout, method, protocolVersion: this.mcpSession ? this.protocolVersion : undefined });
+    } catch (e) {
+      if (e instanceof HubError) throw new BoardError('unreachable', 'Fabric\'s hub did not answer; a write may have been stored, so send it again with the same idempotency key.', true);
+      throw e;
+    }
+  }
+
+  open() {
+    return this.#serial(async () => {
+      this.rpc += 1;
+      const answer = await this.#send({ jsonrpc: '2.0', id: this.rpc, method: 'initialize', params: { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo: { name: 'fabric-agent-adapter-board', version: '1' } } });
+      if (answer.status === 401) throw new BoardError('session-ended', 'Fabric refused the board session\'s bearer; join again.', true);
+      const sid = answer.headers['mcp-session-id'];
+      if (answer.status !== 200 || !isObj(answer.body) || !isObj(answer.body.result) || !sid) throw new BoardError('unreachable', `Fabric did not open the board session (HTTP ${answer.status}).`, true);
+      this.mcpSession = String(sid);
+      if (typeof answer.body.result.protocolVersion === 'string') this.protocolVersion = answer.body.result.protocolVersion;
+      await this.#send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+    });
+  }
+
+  call(tool, args) {
+    if (!RESPOND_TOOLS.has(tool)) return Promise.reject(new BoardError('not-in-scope', `${tool} is not served to a board session; use a Project session for it.`, false, tool));
+    return this.#serial(async () => {
+      if (!this.mcpSession) throw new BoardError('session-ended', 'The board session is not open.', true, tool);
+      this.rpc += 1;
+      const answer = await this.#send({ jsonrpc: '2.0', id: this.rpc, method: 'tools/call', params: { name: tool, arguments: args } });
+      if (answer.status === 401) throw new BoardError('session-ended', 'Fabric ended the board session (it left, was revoked or expired); join again.', true, tool);
+      let value;
+      try {
+        value = toolAnswer(answer, tool);
+      } catch (e) {
+        throw new BoardError(e.retryable ? 'unreachable' : 'receipt-shape', e.message, e.retryable, tool);
+      }
+      if ('error' in value) {
+        if (refusalProblems(value).length) throw new BoardError('receipt-shape', `Fabric refused ${tool} in a form the contract does not name.`, false, tool);
+        throw new BoardError(value.error.code, value.error.message, value.error.retryable, tool);
+      }
+      return value;
+    });
+  }
+
+  close() {
+    return this.#serial(async () => {
+      if (!this.mcpSession) return;
+      try {
+        await this.#send({}, 'DELETE');
+      } catch {
+        // best effort: the lease lapses in 60 s anyway
+      }
+      this.mcpSession = null;
+    });
+  }
+}
+
+/** The responder's journal (0600 JSON, the same file fabric_board.py writes), fsynced before the step it announces. */
+export class Checkpoint {
+  constructor(file) {
+    this.file = file;
+    this.entries = this.#load();
+  }
+  #load() {
+    let text;
+    try {
+      text = fs.readFileSync(this.file, 'utf8');
+    } catch (e) {
+      if (e.code === 'ENOENT') return {};
+      throw new BoardError('checkpoint', `The board checkpoint ${this.file} cannot be read (${e.code}); fix or move it before answering requests.`);
+    }
+    let doc;
+    try {
+      doc = JSON.parse(text);
+    } catch {
+      doc = null;
+    }
+    if (!isObj(doc) || doc.version !== 1 || !isObj(doc.requests)) throw new BoardError('checkpoint', `The board checkpoint ${this.file} is not one this kit writes.`);
+    return doc.requests;
+  }
+  #write(entries) {
+    try {
+      ensurePrivateDir(path.dirname(this.file));
+      const sorted = Object.fromEntries(Object.keys(entries).sort().map((k) => [k, entries[k]]));
+      atomicWrite(this.file, `${JSON.stringify({ requests: sorted, version: 1 }, null, 1)}\n`, 0o600);
+    } catch (e) {
+      throw new BoardError('checkpoint', `The board checkpoint could not be written (${e.code ?? e.message}); nothing was sent.`);
+    }
+  }
+  put(entry) {
+    const entries = { ...this.entries, [entry.request]: JSON.parse(JSON.stringify(entry)) };
+    this.#write(entries);
+    this.entries = entries;
+  }
+  drop(requestId) {
+    if (!(requestId in this.entries)) return;
+    const { [requestId]: _gone, ...entries } = this.entries;
+    this.#write(entries);
+    this.entries = entries;
+  }
+}
+
+/** A claimed request as data: never an instruction. */
+export class BoardRequest {
+  constructor(message, capability) {
+    const req = isObj(message.request) ? message.request : {};
+    const body = isObj(message.body) ? message.body : {};
+    this.requestId = req.id;
+    this.messageId = message.id;
+    this.capability = capability;
+    this.body = typeof body.text === 'string' ? body.text : null;
+    this.bodyFormat = body.format ?? 'text/plain';
+    this.artifacts = Array.isArray(message.artifacts) ? [...message.artifacts] : [];
+    this.sender = isObj(message.sender) ? message.sender : {};
+    this.deadline = req.deadline;
+    this.thread = message.thread;
+  }
+  toJSON() {
+    return { requestId: this.requestId, capability: this.capability }; // never the body
+  }
+}
+
+/** What a handler may do while it works: progress(note), beginEffect(summary) before it spends or acts, and `stopped`. */
+export class WorkContext {
+  #responder;
+  #entry;
+  constructor(responder, entry) {
+    this.#responder = responder;
+    this.#entry = entry;
+    this.stopped = false;
+  }
+  async progress(note) {
+    if (this.stopped) throw new Stopped();
+    await this.#responder.progress(this.#entry, note, this);
+  }
+  async beginEffect(summary) {
+    if (this.stopped) throw new Stopped();
+    await this.#responder.effectBegin(this.#entry, summary, this);
+  }
+}
+
+const clean = (text, max = SUMMARY_MAX) => String(text).split(/\s+/).filter(Boolean).join(' ').slice(0, max);
+
+/**
+ * One service's responder for one Project and its capabilities, one request at a time. handler(request, ctx) answers
+ * the outcome (may be async); admit(request) is the input gate; observe(entry) reads the world after a restart;
+ * emit(kind, level, text, extra) receives events. run({signal}) ticks until aborted; step() is one tick.
+ */
+export class Responder {
+  constructor({ hub, projectId, capabilities, credentialFile, checkpointFile, handler, admit, observe, emit, service = 'service',
+    now = () => performance.now() / 1000, rand = Math.random, sessionFactory } = {}) {
+    if (typeof admit !== 'function' || typeof handler !== 'function') throw new BoardError('invalid_arguments', 'A responder needs the service\'s own input gate (admit) and a handler.');
+    const caps = [...(capabilities ?? [])];
+    if (!caps.length || caps.some((c) => typeof c !== 'string' || !CAPABILITY.test(c)) || new Set(caps).size !== caps.length) throw new BoardError('invalid_arguments', 'Name each capability once, [a-z][a-z0-9._-]{1,127}.');
+    Object.assign(this, { hub, capabilities: caps, credentialFile, handler, admit, observe, emitTo: emit, now, rand });
+    this.project = normalProject(projectId);
+    this.service = String(service).replace(/[^A-Za-z0-9._-]/g, '-').slice(0, 40) || 'service';
+    this.checkpoint = new Checkpoint(checkpointFile);
+    this.sessionFactory = sessionFactory ?? ((grant) => new BoardSession(grant));
+    this.backoff = new Backoff({ rand });
+    this.session = null;
+    this.epoch = null;
+    this.slots = {};
+    this.current = null;
+    this.state = 'idle';
+    this.waitUntil = 0;
+    this.stopping = false;
+    this.claimKeys = {};
+    this.said = {};
+    this.rr = 0;
+    this.reconcileAt = 0;
+    /** The first pause under an operator's hold (DEC-0079); it doubles to HOLD_RETRY_MAX_SECONDS. */
+    this.holdDelay = POLL_SECONDS;
+    this.onHold = new Set();
+  }
+
+  // -- events --
+  emit(kind, level, text, { notify = false, episode, ...value } = {}) {
+    if (episode !== undefined) {
+      if (this.said[kind] === episode) return;
+      this.said[kind] = episode;
+    }
+    let data = { schema: EVENT_SCHEMA, value: Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined && v !== null)) };
+    if (feedDataProblems(data).length) data = undefined; // FAC-SEM-101: drop the data, keep the sentence
+    if (!this.emitTo) return;
+    try {
+      this.emitTo(kind, level, text, { notify, ...(data ? { data } : {}) });
+    } catch {
+      // an event that cannot be written never stops the responder
+    }
+  }
+
+  // -- keys and fences --
+  key(op) {
+    return `${this.service}.${op}.${crypto.randomBytes(8).toString('hex')}`;
+  }
+  idem(key) {
+    if (this.epoch === null) throw new BoardError('no-epoch', 'Fabric told this board session no idempotency epoch.', false, 'com.status');
+    return { epoch: this.epoch, key };
+  }
+  fence(entry, key) {
+    return { request: entry.request, generation: entry.generation, attempt: entry.attempt, digest: entry.digest, expectedRevision: entry.revision, idempotency: this.idem(key) };
+  }
+  receipt(op, answer) {
+    const problems = receiptProblems(answer, op);
+    if (problems.length) throw new BoardError('receipt-shape', `Fabric answered ${op} with a receipt the contract does not name (${problems[0]}).`, false, op);
+    return answer;
+  }
+  call(op, args) {
+    if (!this.session) return Promise.reject(new BoardError('session-ended', 'No board session.', true, op));
+    return this.session.call(op, args);
+  }
+
+  // -- connecting --
+  async status() {
+    const status = await this.call('com.status', {});
+    const verdict = negotiateRevision(status.protocol, acceptedRevisions('fabric-project-comms'));
+    if (verdict.error) throw new BoardError('schema-unsupported', `Fabric's board speaks ${status.protocol}, which this kit does not read.`, false, 'com.status', verdict.error.data);
+    if (status.board?.state === 'unavailable') throw new BoardError('not_available', 'Fabric\'s board cannot be read right now.', true, 'com.status');
+    const epoch = status.idempotency?.epoch;
+    // Fail closed: a guessed epoch would store keys under a namespace the board never named.
+    if (!isInt(epoch, 1)) throw new BoardError('no-epoch', 'Fabric told this board session no idempotency epoch (Fabric before its board-session fix); the responder waits rather than guess one.', false, 'com.status');
+    this.epoch = epoch;
+    return status;
+  }
+
+  async connect() {
+    this.state = 'connecting';
+    const grant = await this.hub.joinBoard(this.project, this.credentialFile);
+    const missing = this.capabilities.filter((c) => !grant.capabilities.includes(c));
+    const session = this.sessionFactory(grant);
+    await session.open();
+    this.session = session;
+    const status = await this.status();
+    if (missing.length) {
+      this.emit('board.access.needed', 'warn', `The operator has not let this service answer ${missing.join(', ')} on this Project; ask in Fabric (Agents & access).`, { notify: true, episode: missing.join(','), capabilities: missing });
+    }
+    this.slots = {};
+    await this.recover(status, this.capabilities.filter((c) => grant.capabilities.includes(c)));
+    this.state = 'ready';
+    for (const kind of ['board.down', 'board.blocked', ...(missing.length ? [] : ['board.access.needed'])]) delete this.said[kind];
+  }
+
+  async enroll(capability) {
+    const args = { idempotency: this.idem(this.key('enroll')), capability };
+    let receipt;
+    try {
+      receipt = this.receipt('com.enroll', await this.call('com.enroll', args));
+    } catch (e) {
+      if (e.code === 'held') {
+        this.pause(capability);
+        return;
+      }
+      if (e.code === 'fenced') {
+        this.slots[capability] = { state: 'contested', renewedAt: this.now() };
+        this.emit('board.slot.contested', 'warn', `Another responder holds the ${capability} slot on this Project; this service waits for it to lapse and never takes it over by itself.`, { notify: true, episode: capability, capability });
+        return;
+      }
+      throw e;
+    }
+    this.slots[capability] = { state: 'held', generation: receipt.slot.generation, renewedAt: this.now() };
+    delete this.said['board.slot.contested'];
+    this.lifted(capability);
+  }
+
+  /**
+   * The operator holds this slot or its Project (DEC-0079): ask again later, the pause doubling each time, and never act
+   * around the hold. Accepted work in progress continues; only new work waits.
+   */
+  pause(capability) {
+    const slot = this.slots[capability] ?? {};
+    const pauses = slot.state === 'paused' ? (slot.pauses ?? 0) + 1 : 1;
+    const wait = Math.min(HOLD_RETRY_MAX_SECONDS, this.holdDelay * 2 ** (pauses - 1));
+    this.slots[capability] = { state: 'paused', pauses, retryAt: this.now() + wait, renewedAt: this.now() };
+    if (!this.onHold.has(capability)) { // once per hold, per capability
+      this.onHold.add(capability);
+      this.emit('board.slot.held', 'info', `The operator holds new work for ${capability} on this Project; the service waits and asks again later. Work already accepted continues.`, { capability });
+    }
+  }
+
+  lifted(capability) {
+    if (!this.onHold.delete(capability)) return;
+    this.emit('board.slot.released', 'info', `The operator's hold on ${capability} was lifted; the service takes new work again.`, { capability });
+  }
+
+  // -- restart: reconcile and transfer --
+  async readState(entry) {
+    const message = await this.call('com.get', { message: entry.message });
+    const req = isObj(message) ? message.request : null;
+    if (!isObj(req) || req.id !== entry.request || !REQUEST_STATES.includes(req.state)) return null;
+    entry.revision = req.revision ?? entry.revision;
+    return req.state;
+  }
+
+  async recover(status, capabilities) {
+    const transfer = {};
+    const reconcile = [];
+    for (const entry of Object.values(this.checkpoint.entries)) {
+      if (!capabilities.includes(entry.capability)) continue;
+      let state;
+      try {
+        state = await this.readState(entry);
+      } catch (e) {
+        if (e.code === 'not_authorized') {
+          this.checkpoint.drop(entry.request);
+          continue;
+        }
+        throw e;
+      }
+      if (state === null || TERMINAL.has(state) || state === 'queued' || state === 'claimed') this.checkpoint.drop(entry.request);
+      else if (state === 'accepted') (transfer[entry.capability] ??= []).push(entry);
+      else reconcile.push(entry);
+    }
+    const responders = (status.responders ?? []).filter(isObj);
+    const generations = Object.fromEntries(responders.map((r) => [r.capability, r.generation ?? 0]));
+    const onHold = new Set(responders.filter((r) => r.held === true).map((r) => r.capability)); // DEC-0079
+    for (const capability of capabilities) {
+      if (onHold.has(capability)) {
+        for (const entry of transfer[capability] ?? []) {
+          entry.step = 'lapsed'; // taken back by a transfer once the hold is lifted
+          this.checkpoint.put(entry);
+        }
+        this.pause(capability);
+      } else if (transfer[capability]?.length) await this.replace(capability, transfer[capability], generations[capability] ?? 0);
+      else await this.enroll(capability);
+    }
+    for (const entry of reconcile) if (this.slots[entry.capability]?.state === 'held') await this.reconcile(entry);
+  }
+
+  async replace(capability, entries, generation) {
+    const args = { idempotency: this.idem(this.key('replace')), capability, expectedGeneration: isInt(generation, 0) ? generation : 0,
+      transfer: { requests: entries.map((e) => e.request).slice(0, 64), checkpoint: { summary: 'Resumed by the same service after a restart; no effect had begun.' } } };
+    let receipt;
+    try {
+      receipt = this.receipt('com.responder_replace', await this.call('com.responder_replace', args));
+    } catch (e) {
+      if (e.code !== 'held') throw e;
+      for (const entry of entries) {
+        entry.step = 'lapsed'; // nothing moved: taken back by a transfer once the hold is lifted
+        this.checkpoint.put(entry);
+      }
+      this.pause(capability);
+      return;
+    }
+    this.slots[capability] = { state: 'held', generation: receipt.slot.generation, renewedAt: this.now() };
+    this.lifted(capability);
+    const moved = new Map((receipt.transferred ?? []).map((item) => [item.request, item]));
+    for (const entry of entries) {
+      const item = moved.get(entry.request);
+      if (!item) {
+        // A board pinned before DEC-0078 hands back no attempt. Never claim it back: it stays held.
+        entry.step = 'held';
+        this.checkpoint.put(entry);
+        this.emit('board.request.held', 'warn', 'An accepted request could not be resumed: this Fabric does not hand back a transferred attempt (DEC-0078). It stays held; nothing was done.', { notify: true, episode: entry.request, request: entry.request, capability });
+        continue;
+      }
+      Object.assign(entry, { generation: item.attempt.generation, attempt: item.attempt.id, digest: item.attempt.digest, revision: item.revision,
+        step: ['accepting', 'held', 'lapsed'].includes(entry.step) ? 'accepted' : entry.step });
+      this.checkpoint.put(entry);
+      if (!this.current) await this.resume(entry);
+    }
+  }
+
+  async reconcile(entry) {
+    const state = await this.readState(entry);
+    if (state !== 'outcome_unknown') {
+      if (state !== null && (TERMINAL.has(state) || state === 'queued' || state === 'claimed')) this.checkpoint.drop(entry.request);
+      return;
+    }
+    let outcome = isObj(entry.outcome) && entry.outcome.observed === true ? entry.outcome : null;
+    if (!outcome && this.observe) {
+      try {
+        outcome = await this.observe({ ...entry });
+      } catch {
+        outcome = null;
+      }
+    }
+    if (!isObj(outcome) || outcome.observed !== true || outcomeProblems({ ...outcome, observed: true }, true).length) {
+      entry.step = 'unknown';
+      this.checkpoint.put(entry);
+      this.emit('board.reconcile.needed', 'warn', 'A request\'s outcome is unknown: the work may have happened. It stays unknown until this service observes what happened.', { notify: true, episode: entry.request, request: entry.request, capability: entry.capability });
+      return;
+    }
+    const sent = Object.fromEntries(['state', 'summary', 'evidence'].filter((k) => k in outcome).map((k) => [k, outcome[k]]));
+    sent.observed = true;
+    entry.keys ??= {};
+    entry.keys.reconcile ??= this.key('reconcile');
+    entry.step = 'reconciling';
+    this.checkpoint.put(entry);
+    this.receipt('com.reconcile', await this.call('com.reconcile', { idempotency: this.idem(entry.keys.reconcile), request: entry.request, digest: entry.digest, outcome: sent }));
+    this.checkpoint.drop(entry.request);
+    this.emit('board.request.reconciled', 'info', 'A request whose outcome was unknown was settled from what this service observed.', { request: entry.request, capability: entry.capability, state: sent.state });
+  }
+
+  // -- one tick --
+  interval() {
+    return Math.max(1, POLL_SECONDS + POLL_JITTER_SECONDS * (2 * this.rand() - 1));
+  }
+
+  /** One tick; answers the seconds to wait before the next. */
+  async step() {
+    if (this.stopping) return DRAIN_SECONDS;
+    const now = this.now();
+    if (now < this.waitUntil) return this.waitUntil - now;
+    try {
+      if (!this.session) await this.connect();
+      await this.tick();
+      this.backoff.reset();
+      return this.interval();
+    } catch (e) {
+      if (!(e instanceof BoardError) && !(e instanceof HubError)) throw e;
+      return this.fault(e);
+    }
+  }
+
+  async fault(e) {
+    const code = e.code ?? 'unreachable';
+    const wait = this.backoff.next();
+    this.waitUntil = this.now() + wait;
+    if (['not_authorized', 'authority_changed', 'credential'].includes(code)) {
+      this.state = 'not-authorized';
+      await this.dropSession();
+      this.emit('board.access.needed', 'warn', 'This service may not answer requests for this Project: the operator has to allow it in Fabric (Agents & access). Nothing is claimed until then.', { notify: true, episode: 'access', reason: code });
+    } else if (code === 'held') {
+      this.state = 'paused';
+      this.emit('board.held', 'info', 'The operator holds new work on this Project; the responder waits and asks again with a growing pause.', { episode: 'held', reason: code });
+    } else if (['no-epoch', 'schema-unsupported', 'checkpoint', 'receipt-shape'].includes(code)) {
+      this.state = 'down';
+      await this.dropSession();
+      this.emit('board.blocked', 'error', `The responder stopped answering requests: ${e.message}`, { notify: true, episode: code, reason: code });
+    } else {
+      this.state = 'down';
+      if (['session-ended', 'unreachable', 'not-running', 'not-a-hub', 'hub-unavailable', 'protocol'].includes(code)) await this.dropSession();
+      this.emit('board.down', 'warn', 'Fabric\'s board cannot be reached; the responder tries again with a growing pause.', { episode: 'down', reason: code });
+    }
+    return wait;
+  }
+
+  async dropSession() {
+    const work = this.current;
+    this.current = null;
+    if (work) {
+      const { entry } = work;
+      if (work.done && !work.failure && !outcomeProblems(work.outcome, !!entry.effect).length) {
+        entry.outcome = { ...work.outcome, observed: work.outcome.observed ?? !entry.effect };
+        try {
+          this.checkpoint.put(entry);
+        } catch {
+          // the next start reruns it
+        }
+      } else work.ctx.stopped = true;
+    }
+    const session = this.session;
+    this.session = null;
+    if (session) await session.close();
+  }
+
+  async tick() {
+    const work = this.current;
+    if (work) {
+      if (work.done) await this.finish(work);
+      else await this.renew(work);
+    }
+    const heldByWork = work && this.current ? work.entry.capability : null;
+    for (const [capability, slot] of Object.entries(this.slots)) {
+      if (slot.state === 'paused') {
+        // still held: a longer pause; lifted: the slot is ours again
+        if (capability !== heldByWork && this.now() >= (slot.retryAt ?? 0)) await this.enroll(capability);
+        continue;
+      }
+      if (capability !== heldByWork && this.now() - (slot.renewedAt ?? 0) >= RENEW_SECONDS - 0.5) await this.enroll(capability);
+    }
+    if (!this.current && !this.stopping) await this.continueLapsed();
+    if (!this.current && !this.stopping) {
+      await this.reconcilePending();
+      await this.claimNext();
+    }
+  }
+
+  async continueLapsed() {
+    const lapsed = {};
+    for (const entry of Object.values(this.checkpoint.entries)) {
+      if (entry.step === 'lapsed' && this.slots[entry.capability]?.state === 'held') (lapsed[entry.capability] ??= []).push(JSON.parse(JSON.stringify(entry)));
+    }
+    for (const [capability, entries] of Object.entries(lapsed)) {
+      const live = [];
+      for (const e of entries) {
+        if (await this.readState(e) === 'accepted') live.push(e);
+        else this.checkpoint.drop(e.request);
+      }
+      if (live.length) await this.replace(capability, live, this.slots[capability].generation ?? 0);
+    }
+  }
+
+  async reconcilePending() {
+    if (this.now() < this.reconcileAt) return;
+    this.reconcileAt = this.now() + 300;
+    for (const entry of Object.values(this.checkpoint.entries)) {
+      if (entry.step === 'unknown' && this.slots[entry.capability]?.state === 'held') await this.reconcile(entry);
+    }
+  }
+
+  async claimNext() {
+    const held = this.capabilities.filter((c) => this.slots[c]?.state === 'held');
+    for (let i = 0; i < held.length; i += 1) {
+      const capability = held[(this.rr + i) % held.length];
+      this.claimKeys[capability] ??= this.key('claim');
+      let answer;
+      try {
+        answer = this.receipt('com.claim', await this.call('com.claim', { idempotency: this.idem(this.claimKeys[capability]), capability }));
+      } catch (e) {
+        if (e.code === 'lease_expired') {
+          await this.enroll(capability);
+          continue;
+        }
+        if (e.code === 'idempotency_window_expired' || e.code === 'capacity_exceeded') {
+          delete this.claimKeys[capability];
+          await this.status();
+          continue;
+        }
+        if (e.code === 'fenced') {
+          this.slots[capability] = { state: 'contested', renewedAt: this.now() };
+          continue;
+        }
+        if (e.code === 'held') {
+          this.pause(capability);
+          continue;
+        }
+        throw e;
+      }
+      if (!('request' in answer)) continue; // nothing claimable; the same key polls again
+      delete this.claimKeys[capability];
+      this.rr += 1;
+      await this.start(capability, answer);
+      return;
+    }
+  }
+
+  // -- a claimed request --
+  async start(capability, receipt) {
+    if (!receipt.attempt || !receipt.message) throw new BoardError('receipt-shape', 'com.claim answered a request without its attempt or message.', false, 'com.claim');
+    const { attempt } = receipt;
+    const entry = { request: receipt.request.id, message: receipt.message, capability, generation: attempt.generation, attempt: attempt.id, digest: attempt.digest,
+      revision: receipt.request.revision, step: 'claimed', keys: {}, effect: false };
+    this.checkpoint.put(entry);
+    const message = await this.call('com.get', { message: entry.message });
+    const req = isObj(message) ? message.request : null;
+    if (message.digest !== entry.digest) {
+      this.checkpoint.drop(entry.request);
+      this.emit('board.request.skipped', 'warn', 'A claimed request was not accepted: the message read back carries another digest than the claim. Nothing was done; the claim lapses.', { request: entry.request, capability, reason: 'digest-mismatch' });
+      return;
+    }
+    if (!isObj(req) || req.id !== entry.request || req.capability !== capability || req.target !== this.project) {
+      this.checkpoint.drop(entry.request);
+      this.emit('board.request.skipped', 'warn', 'A claimed request was not accepted: it is not addressed to this Project and capability. Nothing was done; the claim lapses.', { request: entry.request, capability, reason: 'not-addressed' });
+      return;
+    }
+    const request = new BoardRequest(message, capability);
+    let reason;
+    if (message.redacted === true || typeof request.body !== 'string') reason = 'The request\'s body was redacted, so there is nothing to act on.';
+    else {
+      try {
+        reason = (await this.admit(request)) ?? null;
+      } catch {
+        reason = 'The service\'s input gate could not read this request.';
+      }
+    }
+    if (!(await this.accept(entry))) return;
+    if (reason !== null && reason !== undefined) {
+      entry.outcome = { state: 'failed_known', observed: true, summary: clean(`Refused by this service's input gate: ${reason}`) };
+      await this.complete(entry);
+      this.emit('board.request.refused', 'info', 'A request was refused by the service\'s input gate and completed as failed.', { request: entry.request, capability });
+      return;
+    }
+    await this.runWork(entry, request);
+  }
+
+  async accept(entry) {
+    entry.keys.accept ??= this.key('accept');
+    entry.step = 'accepting';
+    this.checkpoint.put(entry);
+    let receipt;
+    try {
+      receipt = await this.fenced('com.accept', entry, { fence: this.fence(entry, entry.keys.accept) });
+    } catch (e) {
+      if (e.code !== 'held') throw e;
+      // A hold came between the claim and the accept (DEC-0079): nothing was done, the claim lapses and the request waits.
+      this.checkpoint.drop(entry.request);
+      this.emit('board.request.waiting', 'info', 'A claimed request was not accepted: the operator holds it. Nothing was done; it waits on the board.', { request: entry.request, capability: entry.capability });
+      this.pause(entry.capability);
+      return false;
+    }
+    if (!receipt) return false; // the claim was lost before it was accepted; nothing was done
+    entry.revision = receipt.request.revision;
+    entry.step = 'accepted';
+    this.checkpoint.put(entry);
+    return true;
+  }
+
+  async runWork(entry, request) {
+    const ctx = new WorkContext(this, entry);
+    const work = { entry, request, ctx, done: false, outcome: null, failure: null, renewedAt: this.now() };
+    this.current = work;
+    work.promise = Promise.resolve().then(() => this.handler(request, ctx)).then((outcome) => { work.outcome = outcome; }, (e) => { work.failure = e; }).finally(() => { work.done = true; });
+    // A handler that answers at once is finished in this tick; a longer one is renewed by the next ticks.
+    await Promise.race([work.promise, new Promise((resolve) => setImmediate(resolve))]);
+    if (work.done && this.current === work) await this.finish(work);
+  }
+
+  async resume(entry) {
+    if (isObj(entry.outcome)) {
+      await this.complete(entry);
+      return;
+    }
+    const message = await this.call('com.get', { message: entry.message });
+    await this.runWork(entry, new BoardRequest(message, entry.capability));
+  }
+
+  async fenced(op, entry, args) {
+    try {
+      return this.receipt(op, await this.call(op, args));
+    } catch (e) {
+      if (STOP_CODES.has(e.code) || ['revision_conflict', 'invalid_transition', 'digest_conflict'].includes(e.code)) {
+        this.lose(entry, e.code);
+        if (e.code === 'authority_changed') throw e;
+        return null;
+      }
+      throw e;
+    }
+  }
+
+  lose(entry, code) {
+    if (this.current && this.current.entry === entry) this.current.ctx.stopped = true;
+    if (entry.effect) {
+      entry.step = 'unknown';
+      this.checkpoint.put(entry);
+      this.emit('board.reconcile.needed', 'warn', 'The attempt was lost after its effect began; the outcome stays unknown until this service observes what happened.', { notify: true, episode: entry.request, request: entry.request, capability: entry.capability, reason: code });
+    } else if (code === 'lease_expired' && !['claimed', 'accepting'].includes(entry.step)) {
+      entry.step = 'lapsed';
+      this.checkpoint.put(entry);
+      this.emit('board.attempt.lost', 'warn', 'This service\'s lease on an accepted request lapsed; it stopped working on it and takes it back by a transfer.', { request: entry.request, capability: entry.capability, reason: code });
+    } else {
+      this.checkpoint.drop(entry.request);
+      this.emit('board.attempt.lost', 'warn', `The board took a request back from this service (${code}); it stopped working on it, and nothing had been done outside the service.`, { request: entry.request, capability: entry.capability, reason: code });
+    }
+  }
+
+  async renew(work) {
+    if (this.now() - (work.renewedAt ?? 0) < RENEW_SECONDS - 0.5) return;
+    const receipt = await this.fenced('com.renew', work.entry, { fence: this.fence(work.entry, this.key('renew')) });
+    if (!receipt) {
+      this.current = null;
+      return;
+    }
+    work.renewedAt = this.now();
+    (this.slots[work.entry.capability] ??= {}).renewedAt = this.now();
+  }
+
+  async progress(entry, note) {
+    const args = { fence: this.fence(entry, this.key('progress')) };
+    if (note !== undefined && note !== null) args.note = { text: clean(note) || 'Working.' };
+    if (!(await this.fenced('com.progress', entry, args))) throw new Stopped();
+  }
+
+  async effectBegin(entry, summary, ctx) {
+    entry.keys.effect_begin ??= this.key('effect');
+    entry.step = 'effect-beginning';
+    entry.effect = true; // from here a lost attempt is an unknown outcome, never "nothing happened"
+    this.checkpoint.put(entry);
+    const args = { fence: this.fence(entry, entry.keys.effect_begin), ...(summary ? { summary: clean(summary) } : {}) };
+    let receipt = null;
+    let lost = 0;
+    let delay = this.holdDelay;
+    for (;;) { // a lost answer: the same key again tells whether it was stored
+      try {
+        receipt = await this.fenced('com.effect_begin', entry, args);
+        break;
+      } catch (e) {
+        if (e.code === 'held') {
+          // The operator holds this work (DEC-0079): the effect has not begun. Wait, keep the lease (the tick renews it;
+          // com.renew is never held), and ask again with the same key.
+          entry.effect = false;
+          entry.step = 'effect-held';
+          this.checkpoint.put(entry);
+          this.emit('board.request.waiting', 'info', 'The operator holds this request before its effect: the service waits and does nothing outside it until the hold is lifted.', { episode: entry.request, request: entry.request, capability: entry.capability });
+          const until = Date.now() + delay * 1000;
+          while (Date.now() < until) {
+            if (ctx?.stopped) throw new Stopped();
+            await new Promise((resolve) => setTimeout(resolve, Math.min(250, Math.max(1, until - Date.now()))));
+          }
+          if (ctx?.stopped) throw new Stopped();
+          delay = Math.min(HOLD_RETRY_MAX_SECONDS, delay * 2);
+          entry.effect = true;
+          entry.step = 'effect-beginning';
+          this.checkpoint.put(entry);
+          continue;
+        }
+        if (e.code !== 'unreachable' || lost === 2) throw new Stopped();
+        lost += 1;
+        await new Promise((resolve) => setTimeout(resolve, lost * 1000));
+      }
+    }
+    if (!receipt) throw new Stopped();
+    entry.revision = receipt.request.revision;
+    entry.step = 'in-progress';
+    this.checkpoint.put(entry);
+  }
+
+  async finish(work) {
+    const { entry } = work;
+    if (work.ctx.stopped && !(entry.request in this.checkpoint.entries)) {
+      this.current = null;
+      return;
+    }
+    let { outcome } = work;
+    if (work.failure) {
+      if (entry.effect || work.failure instanceof Stopped) {
+        this.current = null;
+        if (entry.effect) this.lose(entry, 'handler-failed');
+        return;
+      }
+      outcome = { state: 'failed_known', observed: true, summary: `The service could not do this (${work.failure?.name ?? 'Error'}).` };
+    }
+    const problems = outcomeProblems(outcome, !!entry.effect);
+    if (problems.length) {
+      this.current = null;
+      if (entry.effect) this.lose(entry, problems.some((p) => p.includes('observation_required')) ? 'observation_required' : 'outcome');
+      else {
+        entry.outcome = { state: 'failed_known', observed: true, summary: 'The service answered in a form it cannot send.' };
+        await this.complete(entry);
+      }
+      this.emit('board.outcome.invalid', 'warn', `The handler's outcome was not sent: ${problems[0]}.`, { request: entry.request, capability: entry.capability });
+      return;
+    }
+    entry.outcome = { ...outcome, observed: outcome.observed ?? !entry.effect };
+    await this.complete(entry);
+  }
+
+  async complete(entry) {
+    const { outcome } = entry;
+    const { reply } = outcome;
+    if (reply && !entry.replied) {
+      entry.keys.reply ??= this.key('reply');
+      entry.step = 'replying';
+      this.checkpoint.put(entry);
+      const args = { fence: this.fence(entry, entry.keys.reply), body: { text: reply.text, ...(reply.format ? { format: reply.format } : {}) }, ...(reply.artifacts?.length ? { artifacts: reply.artifacts } : {}) };
+      if (!(await this.fenced('com.reply', entry, args))) {
+        this.current = null;
+        return;
+      }
+      entry.replied = true;
+      this.checkpoint.put(entry);
+    }
+    entry.keys.complete ??= this.key('complete');
+    entry.step = 'completing';
+    this.checkpoint.put(entry);
+    const sent = Object.fromEntries(['state', 'observed', 'summary', 'evidence'].filter((k) => k in outcome).map((k) => [k, outcome[k]]));
+    const receipt = await this.fenced('com.complete', entry, { fence: this.fence(entry, entry.keys.complete), outcome: sent });
+    this.current = null;
+    if (!receipt) return;
+    this.checkpoint.drop(entry.request);
+    this.emit('board.request.completed', 'info', `A request was answered: ${sent.state === 'completed' ? 'completed' : 'failed, as known'}.`, { request: entry.request, capability: entry.capability, state: sent.state });
+  }
+
+  // -- running --
+  /** Tick until `signal` aborts, then shutdown(). */
+  async run({ signal, drain = DRAIN_SECONDS } = {}) {
+    while (!signal?.aborted) {
+      const wait = await this.step();
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, wait * 1000);
+        signal?.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+      });
+    }
+    await this.shutdown(drain);
+  }
+
+  /** Stop claiming, give running work up to `drain` seconds, then leave the session (its DELETE releases the slots). */
+  async shutdown(drain = DRAIN_SECONDS) {
+    this.stopping = true;
+    const work = this.current;
+    if (work && !work.done) {
+      await Promise.race([work.promise, new Promise((resolve) => setTimeout(resolve, drain * 1000).unref?.())]);
+      if (!work.done) work.ctx.stopped = true;
+    }
+    if (work && work.done && this.session) {
+      try {
+        await this.finish(work);
+      } catch {
+        // the checkpoint keeps it
+      }
+    }
+    if (this.session) {
+      await this.session.close();
+      this.session = null;
+    }
+    this.state = 'stopped';
+  }
+}