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

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

@@ -1,11 +1,13 @@
-// 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.
+// The board responder (DEC-0078, FAA-12b): the work context a handler sees and the responder loop. The session, the
+// checkpoint and the request live in fabric-board-link.mjs and are re-exported here.
 // 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';
+import { Backoff, HubError, normalProject } from './fabric-hub.mjs';
+import { acceptedRevisions, feedDataProblems, negotiateRevision } from './fabric-service.mjs';
+import { BoardError, CAPABILITY, LEASE_SECONDS, REQUEST_STATES, SUMMARY_MAX, Stopped, isInt, isObj, outcomeProblems, receiptProblems } from './fabric-board-shapes.mjs';
+import { BoardRequest, BoardSession, Checkpoint } from './fabric-board-link.mjs';
+
+export { BoardRequest, BoardSession, Checkpoint }; // re-exported: callers import them from here since 0.40.0
 
 export const RENEW_SECONDS = 20;
 
@@ -21,146 +23,12 @@ export const STOP_CODES = Object.freeze(new Set(['fenced', 'lease_expired', 'aut
 
 const TERMINAL = new Set(['completed', 'failed_known', 'cancelled', 'expired']);
 
+/** A lost call is sent again this long before the lease it keeps would lapse (FAA-77, finding 38). */
+export const LEASE_MARGIN_SECONDS = 10;
+
 /** 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;
@@ -213,6 +81,16 @@ export class Responder {
     /** 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();
+    /** One fenced call at a time, and the entry edits beside them (FAA-77, finding 36). */
+    this.fenceQueue = Promise.resolve();
+    this.toResume = []; // transferred requests waiting until nothing runs (finding 39)
+  }
+
+  /** Runs fn after every fenced call queued before it (finding 36): an await inside a call never lets another in. */
+  locked(fn) {
+    const run = this.fenceQueue.then(fn, fn);
+    this.fenceQueue = run.catch(() => {});
+    return run;
   }
 
   // -- events --
@@ -365,12 +243,18 @@ export class Responder {
       } 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);
+    for (const entry of reconcile) {
+      if (this.slots[entry.capability]?.state === 'held') await this.reconcile(entry);
+      else if (entry.step !== 'unknown') {
+        entry.step = 'unknown'; // the slot is not this session's yet: a later tick reconciles it (finding 38)
+        this.checkpoint.put(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.' } } };
+    const args = { idempotency: this.idem(this.key('replace')), capability, expectedGeneration: isInt(generation, 0) ? generation : 0 };
+    if (entries.length) args.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));
@@ -395,28 +279,84 @@ export class Responder {
         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;
       }
+      if (entry.step === 'replying' && !entry.replied && entry.keys?.reply && !entry.probe) {
+        // Finding 35: whether the old reply was stored is asked under the old fence, but only from the resume queue, after
+        // the new attempt is recorded: a second lost answer then leaves the request queued, never stranded.
+        entry.probe = { generation: entry.generation, attempt: entry.attempt, digest: entry.digest, revision: entry.revision, key: entry.keys.reply };
+      }
       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 });
+      // Finding 35: a fenced key's digest named the old attempt; under the new one it is idempotency_conflict.
+      entry.keys = entry.keys?.reconcile ? { reconcile: entry.keys.reconcile } : {};
       this.checkpoint.put(entry);
-      if (!this.current) await this.resume(entry);
+      if (!this.toResume.includes(entry.request)) this.toResume.push(entry.request);
     }
+    await this.resumeNext();
   }
 
-  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;
+  /**
+   * A reply whose answer was lost under the old attempt (finding 35): a stored key answers before the fence is checked
+   * (project-comms.md, Idempotency), so the old call again, under the old fence kept in `probe`, says whether it was
+   * stored; a refusal says it was not. A lost answer, or a board that cannot be read now, throws and leaves `probe` for
+   * the next try: neither says whether the reply was stored.
+   */
+  async repliedBefore(entry) {
+    const { key, generation, attempt, digest, revision } = entry.probe;
+    let replied = true;
+    try {
+      this.receipt('com.reply', await this.call('com.reply', { ...this.replyExtra(entry), fence: this.fence({ ...entry, generation, attempt, digest, revision }, key) }));
+    } catch (e) {
+      if (['unreachable', 'session-ended', 'authority_changed', 'not_authorized', 'not_available', 'capacity_exceeded'].includes(e.code) || !(e instanceof BoardError)) throw e;
+      replied = false;
     }
+    if (replied) entry.replied = true;
+    delete entry.probe;
+    this.checkpoint.put(entry);
+  }
+
+  /**
+   * Resume a transferred request while nothing runs; each idle tick takes the next (finding 39). A request leaves the
+   * queue only once its probe has answered: a lost answer keeps it first in line for the next tick (finding 35).
+   */
+  async resumeNext() {
+    while (!this.current && this.toResume.length && !this.stopping) {
+      const stored = this.checkpoint.entries[this.toResume[0]];
+      if (!stored || this.slots[stored.capability]?.state !== 'held') {
+        this.toResume.shift();
+        continue;
+      }
+      const entry = JSON.parse(JSON.stringify(stored));
+      if (entry.probe) await this.repliedBefore(entry);
+      this.toResume.shift();
+      await this.resume(entry);
+    }
+  }
+
+  /** An observed outcome: the one already known, else what observe(entry) reads; null when nothing was observed. */
+  async observed(entry) {
     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;
+        outcome = null; // an observation that failed is no observation
       }
     }
-    if (!isObj(outcome) || outcome.observed !== true || outcomeProblems({ ...outcome, observed: true }, true).length) {
+    return isObj(outcome) && outcome.observed === true && !outcomeProblems({ ...outcome, observed: true }, true).length ? outcome : null;
+  }
+
+  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);
+      else if (state === 'in_progress' && entry.step !== 'unknown') {
+        entry.step = 'unknown'; // no next holder took the slot yet: a later tick tries again (finding 38)
+        this.checkpoint.put(entry);
+      }
+      return;
+    }
+    const outcome = await this.observed(entry);
+    if (!outcome) {
       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 });
@@ -447,6 +387,10 @@ export class Responder {
       if (!this.session) await this.connect();
       await this.tick();
       this.backoff.reset();
+      if (this.state === 'down') { // a lost call was sent again and answered: the session held throughout
+        this.state = 'ready';
+        delete this.said['board.down'];
+      }
       return this.interval();
     } catch (e) {
       if (!(e instanceof BoardError) && !(e instanceof HubError)) throw e;
@@ -454,9 +398,18 @@ export class Responder {
     }
   }
 
+  /** Seconds this session's leases still run, by its own clock: the running attempt's, else the oldest held slot's. */
+  leaseLeft() {
+    const renewed = this.current ? [this.current.renewedAt ?? 0] : Object.values(this.slots).filter((s) => s.state === 'held').map((s) => s.renewedAt ?? 0);
+    return renewed.length && this.session ? Math.min(...renewed) + LEASE_SECONDS - this.now() : 0;
+  }
+
   async fault(e) {
     const code = e.code ?? 'unreachable';
-    const wait = this.backoff.next();
+    let wait = this.backoff.next();
+    const left = this.leaseLeft() - LEASE_MARGIN_SECONDS;
+    const keep = code === 'unreachable' && left > 0; // finding 38: the lease holds, so the session and the work stay
+    if (keep) wait = Math.max(1, Math.min(wait, left)); // and the call goes again before the lease lapses
     this.waitUntil = this.now() + wait;
     if (['not_authorized', 'authority_changed', 'credential'].includes(code)) {
       this.state = 'not-authorized';
@@ -465,13 +418,14 @@ export class Responder {
     } 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)) {
+    } else if (['no-epoch', 'schema-unsupported', 'checkpoint', 'receipt-shape', 'idempotency_conflict'].includes(code)) {
+      // idempotency_conflict is a key sent with other content, a defect and not an outage (finding 35)
       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();
+      if (['session-ended', 'unreachable', 'not-running', 'not-a-hub', 'hub-unavailable', 'protocol'].includes(code) && !keep) 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;
@@ -480,6 +434,7 @@ export class Responder {
   async dropSession() {
     const work = this.current;
     this.current = null;
+    this.toResume = []; // the next session transfers them again
     if (work) {
       const { entry } = work;
       if (work.done && !work.failure && !outcomeProblems(work.outcome, !!entry.effect).length) {
@@ -511,7 +466,10 @@ export class Responder {
       }
       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.continueLapsed();
+      await this.resumeNext();
+    }
     if (!this.current && !this.stopping) {
       await this.reconcilePending();
       await this.claimNext();
@@ -622,7 +580,7 @@ export class Responder {
     this.checkpoint.put(entry);
     let receipt;
     try {
-      receipt = await this.fenced('com.accept', entry, { fence: this.fence(entry, entry.keys.accept) });
+      receipt = await this.fenced('com.accept', 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.
@@ -657,16 +615,33 @@ export class Responder {
     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;
+  /**
+   * A fenced call, one at a time (finding 36): fence built, sent and receipt applied under the lock. A revision_conflict
+   * on com.renew or com.progress (they store nothing) reads the revision and sends once more. On a stop code the attempt
+   * is lost: the work stops, and it answers null (authority_changed throws after, so the responder stops claiming).
+   */
+  async fenced(op, entry, key, extra = {}, apply = null) {
+    let again = op === 'com.renew' || op === 'com.progress';
+    for (;;) {
+      try {
+        return await this.locked(async () => {
+          const receipt = this.receipt(op, await this.call(op, { ...extra, fence: this.fence(entry, key) }));
+          apply?.(receipt);
+          return receipt;
+        });
+      } catch (e) {
+        if (e.code === 'revision_conflict' && again) {
+          again = false;
+          await this.locked(() => this.readState(entry));
+          continue;
+        }
+        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;
       }
-      throw e;
     }
   }
 
@@ -688,8 +663,7 @@ export class Responder {
 
   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) {
+    if (!(await this.fenced('com.renew', work.entry, this.key('renew')))) {
       this.current = null;
       return;
     }
@@ -698,9 +672,8 @@ export class Responder {
   }
 
   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();
+    const extra = note !== undefined && note !== null ? { note: { text: clean(note) || 'Working.' } } : {};
+    if (!(await this.fenced('com.progress', entry, this.key('progress'), extra))) throw new Stopped();
   }
 
   async effectBegin(entry, summary, ctx) {
@@ -708,13 +681,18 @@ export class Responder {
     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) } : {}) };
+    const extra = summary ? { summary: clean(summary) } : {};
+    const begun = (receipt) => {
+      entry.revision = receipt.request.revision;
+      entry.step = 'in-progress';
+      this.checkpoint.put(entry);
+    };
     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);
+        receipt = await this.fenced('com.effect_begin', entry, entry.keys.effect_begin, extra, begun);
         break;
       } catch (e) {
         if (e.code === 'held') {
@@ -742,9 +720,6 @@ export class Responder {
       }
     }
     if (!receipt) throw new Stopped();
-    entry.revision = receipt.request.revision;
-    entry.step = 'in-progress';
-    this.checkpoint.put(entry);
   }
 
   async finish(work) {
@@ -755,37 +730,70 @@ export class Responder {
     }
     let { outcome } = work;
     if (work.failure) {
-      if (entry.effect || work.failure instanceof Stopped) {
+      if (entry.effect) {
+        await this.settleLive(entry, 'handler-failed');
+        return;
+      }
+      if (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');
+      this.emit('board.outcome.invalid', 'warn', `The handler's outcome was not sent: ${problems[0]}.`, { request: entry.request, capability: entry.capability });
+      if (entry.effect) await this.settleLive(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);
   }
 
+  /**
+   * Finding 37: the handler threw after beginEffect, or answered unobserved, while the attempt is live. Only an observed
+   * result settles a started effect (project-comms.md, Request lifecycle), so observe(entry) is completed under the live
+   * fence. With nothing observed, com.responder_replace on this responder's own slot is the contract's lost-result
+   * operation ("an in_progress one becomes outcome_unknown ... when the next holder takes the slot", Slots end with the
+   * session); com.reconcile settles it once something is observed.
+   */
+  async settleLive(entry, code) {
+    const lost = !!this.current?.ctx.stopped; // the attempt is not live: nothing to settle
+    const state = lost ? null : await this.readState(entry);
+    if (state === 'accepted') { // effect_begin was never stored, so nothing began: a known failure
+      entry.effect = false;
+      entry.outcome = { state: 'failed_known', observed: true, summary: `The service could not do this (${code}).` };
+      await this.complete(entry);
+      return;
+    }
+    const outcome = state === 'in_progress' ? await this.observed(entry) : null;
+    if (outcome) {
+      entry.outcome = { ...Object.fromEntries(['state', 'summary', 'evidence'].filter((k) => k in outcome).map((k) => [k, outcome[k]])), observed: true };
+      await this.complete(entry);
+      return;
+    }
+    this.current = null;
+    this.lose(entry, code);
+    const slot = this.slots[entry.capability] ?? {};
+    if (state === 'in_progress' && slot.state === 'held') await this.replace(entry.capability, [], slot.generation ?? 0);
+  }
+
+  replyExtra(entry) {
+    const { reply } = entry.outcome;
+    return { body: { text: reply.text, ...(reply.format ? { format: reply.format } : {}) }, ...(reply.artifacts?.length ? { artifacts: reply.artifacts } : {}) };
+  }
+
   async complete(entry) {
     const { outcome } = entry;
-    const { reply } = outcome;
-    if (reply && !entry.replied) {
+    if (outcome.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))) {
+      if (!(await this.fenced('com.reply', entry, entry.keys.reply, this.replyExtra(entry)))) {
         this.current = null;
         return;
       }
@@ -796,7 +804,7 @@ export class Responder {
     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 });
+    const receipt = await this.fenced('com.complete', entry, entry.keys.complete, { outcome: sent });
     this.current = null;
     if (!receipt) return;
     this.checkpoint.drop(entry.request);

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

@@ -5,7 +5,7 @@ import fs from 'node:fs';
 import { sameIdentifier } from './fabric-identifiers.mjs';
 
 // A service agent answers a Project's requests on Fabric's project board (fabric-project-comms/0.1; contract DEC-0022,
-// DEC-0073, DEC-0077, DEC-0078; Fabric ADR-0149; FAA-12b, FAA-40). The twin of fabric_board.py — the same steps, the
+// DEC-0073, DEC-0077, DEC-0078; Fabric ADR-0149; FAA-12b, FAA-40). The twin of fabric_board.py: the same steps, the
 // same checkpoint file, the same answers; Node built-ins only. fabric-hub.mjs finds the hub.
 //
 //   enroll (capability) → claim → read the message → accept (the exact digest) → [effectBegin] → [progress] →
@@ -14,12 +14,12 @@ import { sameIdentifier } from './fabric-identifiers.mjs';
 // Responder runs that loop inside the service process: one tick every 15 s ± 5 s, claiming when idle and renewing the
 // 60 s lease (at about 20 s) while work runs. Before it advances a step it writes and fsyncs a checkpoint; a restart
 // reconciles work whose outcome is unknown (com.reconcile) and takes accepted work back by com.responder_replace with a
-// transfer (DEC-0078's receipt member transferred; a Fabric that does not answer it leaves the work held — never claimed
+// transfer (DEC-0078's receipt member transferred; a Fabric that does not answer it leaves the work held, never claimed
 // back). It stops acting on fenced, lease_expired and authority_changed.
 //
 // THE REQUEST BODY IS DATA. admit(request) is the service's own input gate, required: null admits, a sentence refuses
-// (the request is accepted and completed failed_known with it). Whatever the handler does with an admitted body — and
-// the checks it needs before a model, a tool or a spend sees it — is the service's own responsibility.
+// (the request is accepted and completed failed_known with it). Whatever the handler does with an admitted body (and
+// the checks it needs before a model, a tool or a spend sees it) is the service's own responsibility.
 //
 // A board session is served the respond scope only (RESPOND_TOOLS). com.submit, com.cancel, com.read_ack and
 // com.directory are never sent through one; findProject checks a directory page a Project session read (FAC-SEM-107).
@@ -63,7 +63,7 @@ const TIMESTAMP = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2
 
 const URI = /^[A-Za-z][A-Za-z0-9+.-]*:\S+$/;
 
-/** A board refusal (a contract refusal code) or a kit fault — see fabric_board.py's BoardError for the kit's codes. */
+/** A board refusal (a contract refusal code) or a kit fault; see fabric_board.py's BoardError for the kit's codes. */
 export class BoardError extends Error {
   constructor(code, message, retryable = false, op = undefined, data = {}) {
     super(message);

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

@@ -1,6 +1,6 @@
 // The project board connector, Node: the facade (fabric-project-comms/0.1; the twin of fabric_board.py).
-// Since 0.40.0 (FAA-65) it is three modules: fabric-board-shapes, fabric-board-session and fabric-board-fixture. This file
-// re-exports everything it exported at 0.39.1. Node 20+, no dependency.
+// Since 0.40.0 (FAA-65) it is layered modules: fabric-board-shapes, fabric-board-link (since 0.41.0), fabric-board-session and
+// fabric-board-fixture. This file re-exports everything it exported at 0.39.1. Node 20+, no dependency.
 export {
   COMMS_PROTOCOL,
   LEASE_SECONDS,

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

@@ -22,6 +22,7 @@ const NONCE32 = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
 const ASSERTION_MEMBERS = 'alg,authenticatorData,clientDataJSON,credentialId,format,sig';
 
 import { isObject, isString, objects as list, show, jsonEqual } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
+import { clockMs as clockOf } from './fabric-time.mjs'; // the core's (FAA-65)
 const matches = (pattern, value) => isString(value) && pattern.test(value);
 const REGISTER = new Map([
   [ENROLL_TOKEN_TYPE, { fields: ENROLL_TOKEN_FIELDS, check: (f) => matches(ESTATE_SCOPE, f.scope) && matches(SHA256, f.genesis) && f.purpose === ENROLL_PURPOSE
@@ -46,9 +47,12 @@ function statementFields(token) {
   return signingStatement(ENROLL_TOKEN_TYPE, fields) ? fields : undefined;
 }
 
-/** The reference verifier of an enroll-token/1 under trust {record, genesis, at: Date}; the first failure answers. */
+/**
+ * The reference verifier of an enroll-token/1 under trust {record, genesis, at}; `at` is a Date or epoch seconds, as
+ * verifyEstateRecord and the Python twin take it. The first failure answers.
+ */
 export function verifyEnrollToken(token, trust) {
-  const at = isObject(trust) && trust.at instanceof Date ? trust.at.getTime() : Number.NaN;
+  const at = isObject(trust) ? clockOf(trust.at) : Number.NaN;
   if (!Number.isFinite(at)) return { ok: false, problem: 'no-clock' };
   const fields = statementFields(token);
   const record = trust.record;

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

@@ -138,7 +138,8 @@ function keyFor(jwks, kid) {
   if ((jwk.use !== undefined && jwk.use !== 'sig') || (jwk.alg !== undefined && jwk.alg !== 'EdDSA')) return { problem: 'key-not-for-signing' };
   if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || !isNonEmptyString(jwk.x) || jwk.d !== undefined) return { problem: 'unusable-key' };
   const raw = Buffer.from(jwk.x, 'base64url');
-  if (raw.length !== 32) return { problem: 'unusable-key' };
+  // D4: exactly the 43 characters that write 32 bytes (Buffer reads padding, `+` and stray characters leniently).
+  if (raw.length !== 32 || raw.toString('base64url') !== jwk.x) return { problem: 'unusable-key' };
   if (isSmallOrderKey(raw)) return { problem: 'small-order-key' }; // before any verification (DEC-0045, CT-29)
   try {
     return { key: crypto.createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, format: 'jwk' }), raw, x: jwk.x };

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

@@ -12,7 +12,7 @@ import { ROUTES } from './fabric-usage.mjs';
 // document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
 export const DASHBOARD_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1';
 
-export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.1';
+export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.2';
 
 export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];