@passioncode-ai/fabric-agent-adapter 0.82.0 → 0.83.1

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

@@ -5,7 +5,7 @@ import crypto from 'node:crypto';
 import { Backoff, HubError, normalProject } from './fabric-hub.mjs';
 import { PRIMARY_CAPABILITY, 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, PERSONAL_BOARD, covers, mandateOptions, readMandate } from './fabric-board-link.mjs';
+import { BoardRequest, BoardSession, Checkpoint, PERSONAL_BOARD, covers, mandateOptions, noticeLinks, readBackProblem, readMandate, senderAgent } from './fabric-board-link.mjs';
 import { HOLD_RETRY_MAX_SECONDS, LEASE_MARGIN_SECONDS, SESSION_CODES, SlotKeeper } from './fabric-board-slots.mjs';
 
 export { BoardRequest, BoardSession, Checkpoint, PERSONAL_BOARD }; // re-exported: callers import them from here since 0.40.0
@@ -20,6 +20,8 @@ export const POLL_JITTER_SECONDS = 5;
 export const DRAIN_SECONDS = 10;
 /** An idle responder's leave waits this long for the DELETE, so an idle stop ends within LC-01's 5 s (FAA-173). */
 export const IDLE_LEAVE_SECONDS = 3;
+/** `board.down` is said once per outage window: said again only after the board stayed up this long (FAA-187 (22)). */
+export const DOWN_QUIET_SECONDS = 300;
 
 export const EVENT_SCHEMA = 'urn:fabric:schema:board-responder-event:1';
 
@@ -35,16 +37,18 @@ export class WorkContext {
   #responder;
   #entry;
   #caller;
-  constructor(responder, entry, mandate = null, caller = null) {
+  #agent;
+  constructor(responder, entry, mandate = null, caller = null, callerAgent = null) {
     this.#responder = responder;
     this.#entry = entry;
     this.#caller = caller;
+    this.#agent = callerAgent; // FAA-135: the sender's agent id identifyAgent named, binding the mandate's chain
     this.stopped = false;
     this.mandate = mandate; // the operator's mandate the request carried, when the responder reads one (FAA-135)
   }
   /** Whether the request's mandate covers `call` (`mandateCovers`' answer); null when none travelled. */
   mandateCovers(call) {
-    return covers(this.mandate, call, this.#responder.agentId, this.#responder.wall, this.#caller);
+    return covers(this.mandate, call, this.#responder.agentId, this.#responder.wall, this.#caller, this.#agent);
   }
   toJSON() {
     return { stopped: this.stopped }; // never the mandate: it holds the operator's words
@@ -82,33 +86,39 @@ function noticeSubject(value, project, episode) {
  */
 export class Responder extends SlotKeeper {
   constructor({ hub, projectId, capabilities, credentialFile, checkpointFile, handler, admit, observe, emit, service = 'service',
-    now = () => performance.now() / 1000, rand = Math.random, sessionFactory, agentId = null, mandateFrom = null, wall = Date.now } = {}) {
+    now = () => performance.now() / 1000, rand = Math.random, sessionFactory, agentId = null, mandateFrom = null, wall = Date.now, identifyAgent = null, links = null } = {}) {
     super();
-    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.');
+    if (typeof admit !== 'function' || typeof handler !== 'function' || !(identifyAgent == null || typeof identifyAgent === 'function')) {
+      throw new BoardError('invalid_arguments', 'A responder needs the service\'s own input gate (admit) and a handler; identifyAgent, when given, is a function of the sender (FAA-135).');
+    }
     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}.');
     // FAA-244: DEC-0140 PR-1, a session's slot, never a service's
     if (caps.includes(PRIMARY_CAPABILITY)) throw new BoardError('invalid_arguments', `${PRIMARY_CAPABILITY} is a Project's primary responder's, a session's: a service answers the capabilities it declares (DEC-0140 PR-1).`);
     Object.assign(this, { hub, capabilities: caps, credentialFile, handler, admit, observe, emitTo: emit, now, rand });
     this.project = normalProject(projectId);
-    // FAA-135: read the operator's mandate from a trusted request of his own Project (opt-in; null reads none)
-    Object.assign(this, { mandateFrom: mandateOptions(agentId, mandateFrom), agentId: agentId ?? null, wall });
+    // FAA-135: read the operator's mandate from a trusted request of his own Project (opt-in; null reads none), and bind
+    // its chain with the agent id identifyAgent names for the sender (asked only when a mandate travelled)
+    Object.assign(this, { mandateFrom: mandateOptions(agentId, mandateFrom), agentId: agentId ?? null, wall, identifyAgent: identifyAgent ?? null });
+    this.links = noticeLinks(links); // FAA-187 (21): the page that resolves each notify kind
     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 = {};
+    // FAA-196 (24): maps keyed by a capability's name have no prototype, so `constructor` is a name like any other
+    this.slots = Object.create(null);
     this.current = null;
     this.state = 'idle';
     this.waitUntil = 0;
     this.stopping = false;
     /** Whether shutdown found work to drain, published before it waits; null before shutdown starts (FAA-186). */
     this.draining = null;
-    this.claimKeys = {};
+    this.claimKeys = Object.create(null);
     this.probing = new Set(); // moved slots whose move-back claim lost its answer: asked again under the same key
-    this.said = {};
+    this.said = Object.create(null);
+    this.upSince = null; // when the board was last seen up after a fault (FAA-187 (22))
     this.rr = 0;
     this.reconcileAt = 0;
     /** The first pause under an operator's hold (DEC-0079); it doubles to HOLD_RETRY_MAX_SECONDS. */
@@ -118,7 +128,7 @@ export class Responder extends SlotKeeper {
     this.fenceQueue = Promise.resolve();
     this.toResume = []; // transferred requests waiting until nothing runs (finding 39)
     this.suspect = new Set(); // capabilities a fenced call was refused on: com.status says whether they moved (FAA-155)
-    this.confirmed = {}; // this session's: the generation it held, or com.status showed unmoved
+    this.confirmed = Object.create(null); // this session's: the generation it held, or com.status showed unmoved
   }
 
   /** Runs fn after every fenced call queued before it (finding 36): an await inside a call never lets another in. */
@@ -148,7 +158,8 @@ export class Responder extends SlotKeeper {
     // (events-and-notifications.md, "Say who wants what"; 0.56.0 seam r30).
     const subject = noticeSubject(value, this.project, episode);
     try {
-      this.emitTo(kind, level, text, { notify, subject, ...(data ? { data } : {}) });
+      const link = notify && this.links && Object.hasOwn(this.links, kind) ? { link: this.links[kind] } : {}; // the page that resolves it (FAA-187 (21))
+      this.emitTo(kind, level, text, { notify, subject, ...link, ...(data ? { data } : {}) });
     } catch {
       // an event that cannot be written never stops the responder
     }
@@ -190,8 +201,8 @@ export class Responder extends SlotKeeper {
 
   async connect() {
     this.state = 'connecting';
-    this.slots = {}; // the previous session's slots are not this one's: a refusal now reconnects (FAA-163)
-    this.confirmed = {}; // nor its confirmations: a slot may have moved between the two sessions
+    this.slots = Object.create(null); // the previous session's slots are not this one's: a refusal now reconnects (FAA-163)
+    this.confirmed = Object.create(null); // nor its confirmations: a slot may have moved between the two sessions
     this.probing = new Set(); // nor its lost move-back claims
     const grant = await this.hub.joinBoard(this.project, this.credentialFile);
     const missing = this.capabilities.filter((c) => !grant.capabilities.includes(c));
@@ -202,10 +213,10 @@ export class Responder extends SlotKeeper {
     if (missing.length) {
       this.emit('board.access.needed', 'warning', `The operator has not let this service answer ${missing.join(', ')} on this Project; ask in Fabric (Settings → Agent access).`, { notify: true, episode: missing.join(','), capabilities: missing });
     }
-    this.slots = {};
+    this.slots = Object.create(null);
     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];
+    for (const kind of ['board.blocked', ...(missing.length ? [] : ['board.access.needed'])]) delete this.said[kind]; // board.down waits for its quiet window (step)
   }
 
   async enroll(capability) {
@@ -262,7 +273,7 @@ export class Responder extends SlotKeeper {
   }
 
   async recover(status, capabilities) {
-    const transfer = {};
+    const transfer = Object.create(null);
     const reconcile = [];
     for (const entry of Object.values(this.checkpoint.entries)) {
       if (!capabilities.includes(entry.capability)) continue;
@@ -281,7 +292,7 @@ export class Responder extends SlotKeeper {
       else reconcile.push(entry);
     }
     const responders = (status.responders ?? []).filter(isObj);
-    const generations = Object.fromEntries(responders.map((r) => [r.capability, r.generation ?? 0]));
+    const generations = Object.assign(Object.create(null), 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
     let failure = null;
     for (const capability of capabilities) {
@@ -470,10 +481,9 @@ export class Responder extends SlotKeeper {
       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'];
-      }
+      if (this.state === 'down') this.state = 'ready'; // a lost call was sent again and answered: the session held throughout
+      this.upSince ??= now;
+      if (now - this.upSince >= DOWN_QUIET_SECONDS) delete this.said['board.down']; // up a whole window: a later outage is said again
       return this.interval();
     } catch (e) {
       if (!(e instanceof BoardError) && !(e instanceof HubError)) throw e;
@@ -492,6 +502,7 @@ export class Responder extends SlotKeeper {
 
   async fault(e) {
     const code = e.code ?? 'unreachable';
+    this.upSince = null;
     const connecting = this.state === 'connecting' && !Object.values(this.slots).some((s) => s?.state === 'held');
     let wait = this.backoff.next();
     const left = this.leaseLeft() - LEASE_MARGIN_SECONDS;
@@ -554,9 +565,10 @@ export class Responder extends SlotKeeper {
       await this.gone(capability);
       this.suspect.delete(capability);
     }
+    const shared = {}; // one com.status read a tick for every moved slot (FAA-194 (5))
     for (const [capability, slot] of Object.entries(this.slots)) {
       if (slot.state === 'moved') { // never enrolled again on its own, even when the new holder lapses (FAA-155)
-        if (this.now() - (slot.renewedAt ?? 0) >= RENEW_SECONDS - 0.5) await this.movedBack(capability); // unless com.status shows a later generation it may hold (FAA-165)
+        if (this.now() - (slot.renewedAt ?? 0) >= RENEW_SECONDS - 0.5) await this.movedBack(capability, shared); // unless com.status shows a later generation it may hold (FAA-165)
         continue;
       }
       if (slot.state === 'paused') {
@@ -581,7 +593,7 @@ export class Responder extends SlotKeeper {
   }
 
   async continueLapsed() {
-    const lapsed = {};
+    const lapsed = Object.create(null);
     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)));
     }
@@ -648,13 +660,13 @@ export class Responder extends SlotKeeper {
       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) {
+    const problem = readBackProblem(message, entry, this.project);
+    if (problem === 'digest-mismatch') {
       this.checkpoint.drop(entry.request);
       this.emit('board.request.skipped', 'warning', '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) {
+    if (problem) {
       this.checkpoint.drop(entry.request);
       this.emit('board.request.skipped', 'warning', '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;
@@ -701,12 +713,14 @@ export class Responder extends SlotKeeper {
     return true;
   }
 
-  async runWork(entry, request) {
-    const { mandate, unread } = readMandate(request, this.mandateFrom, this.agentId);
+  async runWork(entry, request, problem = null) {
+    let { mandate, unread } = readMandate(request, this.mandateFrom, this.agentId);
+    if (problem && (mandate !== null || unread)) [mandate, unread] = [null, problem]; // FAA-196 (1): another message than accepted
     if (unread) { // by its code alone: the block holds the operator's words
       this.emit('board.request.mandate_unread', 'warning', `Request ${entry.request} carries a mandate the kit does not read (${unread}); it is worked without one.`, { request: entry.request, reason: unread });
     }
-    const ctx = new WorkContext(this, entry, mandate, isObj(request.sender) ? request.sender.project ?? null : null);
+    const sender = isObj(request.sender) ? request.sender : {};
+    const ctx = new WorkContext(this, entry, mandate, sender.project ?? null, senderAgent(this.identifyAgent, sender, mandate));
     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; });
@@ -721,7 +735,7 @@ export class Responder extends SlotKeeper {
       return;
     }
     const message = await this.call('com.get', { message: entry.message });
-    await this.runWork(entry, new BoardRequest(message, entry.capability));
+    await this.runWork(entry, new BoardRequest(message, entry.capability), readBackProblem(message, entry, this.project));
   }
 
   /**

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

@@ -131,7 +131,7 @@ export class SlotKeeper {
     delete this.confirmed[capability];
     delete this.claimKeys[capability]; // the move returned that claim to the queue: its receipt is dead
     if (!('moved' in held)) { // once, even across restarts
-      this.emit('board.slot.moved', 'warning', `The ${capability} slot on this Project moved to another session. This service stopped answering it; accepted work stays \`accepted\` (work begun is the new holder's). The operator brings it back by take-back (once the other session lets it go, or at a restart with accepted work waiting; a restart alone does not) or, where Fabric offers it, a move back here. Else ask its maintainer.`, { notify: true, episode: capability, capability, generation: now, held: held.generation });
+      this.emit('board.slot.moved', 'warning', `The ${capability} slot on this Project moved to another session. This service stopped answering it; accepted work stays accepted (work begun is the new holder's). The operator brings it back by take-back (once the other session lets it go, or at a restart or reconnect with accepted work waiting; neither alone does) or, where Fabric can, a move back here. Else ask its maintainer.`, { notify: true, episode: capability, capability, generation: now, held: held.generation });
       this.note(capability, { ...held, moved: now }); // said again at the next start if it cannot be written
     }
     return true;
@@ -143,14 +143,21 @@ export class SlotKeeper {
    * com.claim asks whether the slot is its own. A claim that lands makes it held again and starts what it handed out; a
    * lease_expired one (the move reached this session but its lease lapsed) enrolls again; a fenced one is another
    * session's, recorded so the same generation is not asked about twice. Never an enroll or a replace on a slot another
-   * session holds: a slot moved off stays off unless it is handed back.
+   * session holds: a slot moved off stays off unless it is handed back. `shared` holds the tick's one com.status read,
+   * shared by every moved slot (FAA-194 (5)).
    */
-  async movedBack(capability) {
+  async movedBack(capability, shared = null) {
     if (this.current || this.stopping) return; // a claim now could hand out a second request, or start work while the responder stops
     const held = this.checkpoint.slots[capability] ?? {};
     if (held.project !== this.project || !isInt(held.moved, 1)) return;
     if (this.slots[capability]) this.slots[capability].renewedAt = this.now();
-    const now = ((await this.status()).responders ?? []).find((r) => isObj(r) && r.capability === capability)?.generation;
+    let status;
+    if (shared && 'status' in shared) status = shared.status;
+    else {
+      status = await this.status();
+      if (shared) shared.status = status;
+    }
+    const now = (status.responders ?? []).find((r) => isObj(r) && r.capability === capability)?.generation;
     if (!isInt(now, 1) || now <= held.moved) return;
     if (!this.probing.has(capability) || !this.claimKeys[capability]) { // a fresh key: one from before the move may hold a dead receipt
       this.claimKeys[capability] = this.key('claim');
@@ -201,14 +208,17 @@ export class SlotKeeper {
   }
 
   /** The slot is this session's again at `generation`: held, its record rewritten without the move (FAA-165). */
-  back(capability, held, generation) {
-    return this.locked(() => {
+  async back(capability, held, generation) {
+    const back = await this.locked(() => {
       if (!sameRecord(this.checkpoint.slots[capability], held)) return false; // a takeBack forgot it; its own next tick enrolls
       this.slots[capability] = { state: 'held', generation, renewedAt: -Infinity }; // no lease yet
       this.heldAt(capability, generation);
       delete this.said['board.slot.moved']; // a later move is said again
       return true;
     });
+    // FAA-194 (8): the feed no longer ends on the move's warning
+    if (back) this.emit('board.slot.returned', 'info', `The ${capability} slot on this Project is this service's again: the operator moved it back here, and it answers it from now on.`, { capability, generation });
+    return back;
   }
 
   /**

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

@@ -88,7 +88,28 @@ function shapeProblems(value) {
 // The contract's KEY_SHAPE (src/connections.ts): a provider key where it starts a word, case-sensitive prefixes, the
 // `sk-` rules and a Telegram bot token.
 const KEY_SHAPE = /(?:^|[^A-Za-z0-9])(?:sk-(?=[A-Za-z0-9_-]*\d)(?:(?=[A-Za-z0-9_-]*[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}|(?:bot)?\d{6,12}:(?=[A-Za-z0-9_-]*[A-Z])(?=[A-Za-z0-9_-]*[a-z])[A-Za-z0-9_-]{34,35}(?![A-Za-z0-9_-]))/;
-const SCHEME = /[a-z][a-z0-9+.-]*:\/\//gi;
+const SCHEME_CHAR = /[a-z0-9+.-]/i;
+const SCHEME_LETTER = /[a-z]/i;
+/**
+ * The [start, end] of each URL scheme and its `://` in a piece, where `/[a-z][a-z0-9+.-]*:\/\//gi` finds them left to
+ * right, read in linear time (FAA-322: the pattern tried every letter of a long run with no `://`). From each `://` the
+ * run of scheme characters before it is read back, and the match starts at its first letter at or after where the last
+ * match ended. The twin of fabric_connections._scheme_spans.
+ */
+export function schemeSpans(piece) {
+  const spans = [];
+  let after = 0;
+  for (let at = piece.indexOf('://'); at >= 0; at = piece.indexOf('://', at + 1)) {
+    let start = at;
+    while (start > after && SCHEME_CHAR.test(piece[start - 1])) start -= 1;
+    while (start < at && !SCHEME_LETTER.test(piece[start])) start += 1;
+    if (start < at) {
+      spans.push([start, at + 3]);
+      after = at + 3;
+    }
+  }
+  return spans;
+}
 const CLOSING = /[)\]}>"'.,;:!?]/;
 const TRIED_BACK = 1;
 /** The URLs a member may hold, from every scheme in each whitespace-delimited piece, without the closing brackets,
@@ -96,8 +117,8 @@ const TRIED_BACK = 1;
 function urlsIn(value) {
   const urls = [];
   for (const piece of value.split(/\s+/)) {
-    for (const match of piece.matchAll(SCHEME)) {
-      const url = piece.slice(match.index);
+    for (const [start] of schemeSpans(piece)) {
+      const url = piece.slice(start);
       let end = url.length;
       while (end > 0 && CLOSING.test(url[end - 1])) end -= 1;
       for (let back = 0; back <= TRIED_BACK && end + back <= url.length; back += 1) urls.push(url.slice(0, end + back));
@@ -108,8 +129,8 @@ function urlsIn(value) {
 /** A long secret-shaped run in a piece read whole; in a piece that holds a URL, the text before its first scheme's `://`. */
 const longRun = (value) =>
   value.split(/\s+/).some((piece) => {
-    const at = piece.search(SCHEME);
-    const cut = at < 0 ? -1 : piece.indexOf('://', at);
+    const found = schemeSpans(piece);
+    const cut = found.length ? found[0][1] - 3 : -1;
     return longSecret(cut < 0 ? piece : piece.slice(0, cut));
   });
 // hasJwt reads a JWT in one pass, where JWT_SHAPE backtracks from every `eyJ` of a long run (FAA-313).

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

@@ -15,10 +15,10 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import http from 'node:http';
-import net from 'node:net';
 import { hubKeyCertified } from './fabric-estate.mjs';
 import { atomicWrite } from './fabric-paths.mjs'; // the kit's private writer (FAA-85)
 import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs'; // a loopback key set from this account's listener only (FAA-255)
+import { loopbackHost } from './fabric-socket-proof.mjs';
 import { effectClosure } from './fabric-mandate.mjs'; // defined once beside the mandate that reads it too (DEC-0125)
 
 export const REFUSAL_CODES = Object.freeze([
@@ -413,7 +413,8 @@ export function readDelegationToken(headers) {
 /** The digest an approval binds: sha256: and the hex SHA-256 of the action's RFC 8785 form. */
 export const actionDigest = (action) => `sha256:${crypto.createHash('sha256').update(jcs(action), 'utf8').digest('hex')}`;
 
-const loopback = (host) => host === 'localhost' || (net.isIP(host.replace(/^\[|\]$/g, '')) !== 0 && (/^127\./.test(host) || host.replace(/^\[|\]$/g, '') === '::1'));
+// A key set source's loopback host: the kit's one rule, shared with fabric-http's checkUrl (FAA-187 (15)).
+const loopback = loopbackHost;
 
 const KEY_SET_MAX = 65536;
 const KEY_SET_AGENT = new CheckedAgent({ keepAlive: false });

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

@@ -12,13 +12,13 @@ import { protocolsFindings } from './fabric-protocols.mjs';
 import { CONNECTIONS_EXTENSION_KEY, connectionsView } from './fabric-connections.mjs';
 import { ACTIONS_EXTENSION_KEY, actionsExtension, actionsExtensionRules } from './fabric-actions.mjs';
 import { a2aSurfaceProblems } from './fabric-a2a.mjs';
-import { ROUTES } from './fabric-usage.mjs';
+import { ROUTES, isPlainObject } from './fabric-usage.mjs';
 
 // The embedded dashboard declaration (fabric-dashboard/0.1, DEC-0036 ED-9), under the well-known
 // 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.7';
+export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.8';
 
 export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 
@@ -47,7 +47,8 @@ export function readDescriptors(dir = servicesDir()) {
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir).filter((n) => n.endsWith('.json')).sort().flatMap((n) => {
     try {
-      return [[path.join(dir, n), JSON.parse(fs.readFileSync(path.join(dir, n), 'utf8'))]];
+      const value = JSON.parse(fs.readFileSync(path.join(dir, n), 'utf8'));
+      return isPlainObject(value) ? [[path.join(dir, n), value]] : []; // no object, no descriptor (FAA-200 (50))
     } catch {
       return [];
     }
@@ -66,14 +67,16 @@ export function validateDescriptor(d) {
   }
   if (problems.length) return problems;
   if (d.protocol !== PROTOCOL) problems.push(`protocol must be ${PROTOCOL}`);
-  if (!ID.test(d.id)) problems.push(`id must match ${ID}`);
-  if (!INSTANCE.test(d.instance)) problems.push(`instance must match ${INSTANCE}`);
+  for (const [key, pattern] of [['id', ID], ['instance', INSTANCE]]) { // a string before its pattern (FAA-200 (9), (36))
+    if (typeof d[key] !== 'string') problems.push(`${key} must be a string`);
+    else if (!pattern.test(d[key])) problems.push(`${key} must match ${pattern}`);
+  }
   if (remote) problems.push(...remoteOriginProblems(d.origin));
   else if (d.origin !== undefined && !ORIGIN.test(d.origin)) problems.push('origin must be http://127.0.0.1:<port>');
   if (!d.auth?.tokenFile) problems.push('auth.tokenFile is required');
-  else if (!LOCAL_PATH.test(String(d.auth.tokenFile))) problems.push('auth.tokenFile must be a local path, never a network share');
+  else if (!LOCAL_PATH.test(String(d.auth.tokenFile))) problems.push('auth.tokenFile must be an absolute local path (/, ~/ or a drive letter), never a relative path, never a network share');
   for (const value of [...(d.paths?.data !== undefined ? [d.paths.data] : []), ...(d.paths?.logs ?? [])]) {
-    if (!LOCAL_PATH.test(String(value))) problems.push(`paths must be local paths, never a network share: ${JSON.stringify(value)}`);
+    if (!LOCAL_PATH.test(String(value))) problems.push(`paths must be absolute local paths (/, ~/ or a drive letter), never a relative path, never a network share: ${JSON.stringify(value)}`);
   }
   if (!(typeof (d.auth?.header ?? 'Authorization') === 'string' && AUTH_HEADER.test(d.auth?.header ?? 'Authorization'))) problems.push(`auth.header must match ${AUTH_HEADER.source}`);
   if (!['Bearer', 'none'].includes(d.auth?.scheme ?? 'Bearer')) problems.push('auth.scheme is Bearer or none');
@@ -198,7 +201,7 @@ export function descriptorMemberProblems(d) {
       else if (URI_PASSWORD.test(repository)) problems.push('source.repository carries no password: it names the repository, never a credential'); // before the host
       else if (!authorityOk(repository)) problems.push('source.repository names a host, and a port of digits up to 65535 when it has one');
       else if (repository.includes('@') && !HIERARCHICAL.test(repository)) problems.push('source.repository with a user is a URL with an authority (https://user@host/path), never an scp form'); // readings 7
-      else if (repositoryCredential(repository)) problems.push('FAC-SEM-086: /source/repository holds a value shaped like a credential; it names a repository'); // its name is no key (seam 6)
+      else if (repositoryCredential(repository)) problems.push("FAC-SEM-086: /source/repository holds a value shaped like a credential; it names a repository: write the repository's name in lower case if it is one"); // its name is no key (seam 6)
     }
   }
   if ('peer' in d) {
@@ -428,15 +431,18 @@ export function portListenerRefusal(port, reader = portOwner) {
  * account listens on (FAA-225; `portOwner(port) -> [kind, uid] | null` reads it, the kit's own by default).
  * FAA-198: a new descriptor names its source.repository; rewriting one already installed without it only warns
  * (process.emitWarning, code FABRIC_NO_SOURCE_REPOSITORY), so an installed agent's update keeps working. */
-export function writeDescriptor(d, dir = servicesDir(), { portOwner: reader = portOwner } = {}) {
+/** The rewrite warning of a descriptor that names no source.repository (FAA-198). */
+export function warnNoSource(d) {
+  process.emitWarning(`Descriptor ${d.id}.${d.instance} ${NO_SOURCE_REPOSITORY}; a new install is refused without it.`, { code: 'FABRIC_NO_SOURCE_REPOSITORY' });
+}
+
+export function writeDescriptor(d, dir = servicesDir(), { portOwner: reader = portOwner, warned = false } = {}) {
   const problems = validateDescriptor(d);
   if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
   const me = `${d.id}.${d.instance}`;
   const refusal = sourceRefusal(d, dir);
   if (refusal) throw new ServiceError(refusal);
-  if (!namesRepository(d)) {
-    process.emitWarning(`Descriptor ${me} ${NO_SOURCE_REPOSITORY}; a new install is refused without it.`, { code: 'FABRIC_NO_SOURCE_REPOSITORY' });
-  }
+  if (!namesRepository(d) && !warned) warnNoSource(d); // registerRemote warns itself, before its token (FAA-200 (1))
   // DEC-0019: only a local placement claims a port on this computer; DEC-0069: an app's descriptor names none.
   const port = placementOf(d) === 'remote' || d.origin === undefined ? null : portOf(d.origin);
   for (const [file, other] of readDescriptors(dir)) {

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

@@ -18,7 +18,12 @@ const TRACE_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
 
 const SPAN_ID = /^(?!0{16}$)[0-9a-f]{16}$/;
 
-/** One activity event. `level` is one of LEVELS; `warn`, the dashboard chip's name, is stored as `warning`. `data` (DEC-0070) adds machine-readable fields, `{schema, value}`, never a secret: refused here, so no feed carries one. */
+/**
+ * One activity event. `level` is one of LEVELS; `warn`, the dashboard kit's chip for "a person is needed"
+ * (`.fd-s-warn`), is stored as `warning`, the feed's name for the same level, so a reader that draws chips shows a
+ * stored `warning` as the `warn` chip (FAA-276, FAA-277 (6)). `data` (DEC-0070) adds machine-readable fields,
+ * `{schema, value}`, never a secret: refused here, so no feed carries one.
+ */
 export function makeEvent(id, at, kind, given, text, { subject, link, notify, traceId, spanId, data } = {}) {
   const level = typeof given === 'string' && Object.hasOwn(LEVEL_ALIASES, given) ? LEVEL_ALIASES[given] : given;
   if (!LEVELS.includes(level)) throw new ServiceError(`level must be one of ${LEVELS.join(', ')} (or \`warn\` for \`warning\`).`);

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

@@ -2,7 +2,9 @@
 // the contract's pause grammar (`quota-exhausted[ until <until>]: waiting <reason> since <since>[: <message>]`; the
 // pinned interop-job schema is closed, so `waiting {reason, since, until, message}` rides statusMessage, never a field
 // of the job), one push per hold, and the operator's scoped lift. The twin of fabric_holds.py, held to the same
-// vectors (test/fixtures/holds/waiting-vectors.json). Part of the Node service kit (layer L3, after fabric-interop).
+// vectors (test/fixtures/holds/waiting-vectors.json). A record written since 0.83.0 carries `squash: 'ecmascript'`; one
+// without it is matched under both squashes, as 0.81.0's Python twin squashed names with str.split() (FAA-320,
+// test/fixtures/holds/legacy-squash-vectors.json). Part of the Node service kit (layer L3, after fabric-interop).
 // Node 20+, no dependency.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
@@ -40,6 +42,17 @@ const reasonOk = (reason, what) => {
 // (FAA-316): Python's str.split() also takes U+001C to U+001F and U+0085 and not U+FEFF.
 const SPACES = /[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+/g;
 const squash = (text) => String(text).replace(SPACES, ' ').replace(/^ | $/g, '');
+/** What a record written since 0.83.0 carries: its names were squashed with ECMAScript's whitespace (FAA-320). */
+export const SQUASH = 'ecmascript';
+// Python's str.isspace() class, the one 0.81.0's Python twin squashed a name with (`" ".join(text.split())`).
+const PY_SPACES = /[\t\n\v\f\r\u001c-\u001f \u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]+/g;
+const legacySquash = (text) => String(text).replace(PY_SPACES, ' ').replace(/^ | $/g, '');
+// The stored forms `caller` matches in `record`: the ECMAScript squash, and for a record with no `squash` mark (written
+// before 0.83.0) also the squash 0.81.0's Python twin wrote (FAA-320). null matches only null.
+const names = (caller, record) => {
+  if (typeof caller !== 'string') return [caller];
+  return record.squash === SQUASH ? [squash(caller)] : [squash(caller), legacySquash(caller)];
+};
 
 /** A held job's statusMessage; the message is shortened, never refused, to fit 500 characters. */
 export function waitingMessage(reason, since, until = null, message = null) {
@@ -149,6 +162,7 @@ export class HoldBook {
 
   /** Hold `work` for `caller` by `reason`: {hold, statusMessage, push}; push only when this call opened the hold. */
   hold({ caller, work, reason, until = null, message = null, jobId = null, now = null }) {
+    const rawCaller = caller;
     caller = text(caller, 'caller');
     work = text(work, 'work');
     reasonOk(reason, 'hold');
@@ -158,10 +172,10 @@ export class HoldBook {
     }
     const data = this.load();
     HoldBook.expire(data, utcTime(at));
-    let hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    let hold = data.holds.find((h) => h.closed === null && h.reason === reason && names(rawCaller, h).includes(h.caller));
     const opened = hold === undefined;
     if (opened) {
-      hold = { id: newId(), reason, caller, work, since: at, until, jobs: [], closed: null };
+      hold = { id: newId(), reason, caller, work, since: at, until, jobs: [], closed: null, squash: SQUASH };
       data.holds.push(hold);
     }
     if (jobId !== null && !hold.jobs.includes(String(jobId))) hold.jobs.push(String(jobId));
@@ -176,7 +190,7 @@ export class HoldBook {
   release({ reason, caller, now = null }) {
     const at = this.now(now);
     const data = this.load();
-    const hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    const hold = data.holds.find((h) => h.closed === null && h.reason === reason && names(caller, h).includes(h.caller));
     if (!hold) return null;
     hold.closed = 'released';
     hold.closedAt = at;
@@ -211,12 +225,12 @@ export class HoldBook {
       throw new ServiceError('A raised limit needs its window\'s end (until): it falls back when the window ends.');
     }
     const record = { id: newId(), reason, caller: caller === null ? null : text(caller, 'caller'),
-      job: jobId === null ? null : String(jobId), from: at, until, [kind]: size, decision: { ...decision }, at };
+      job: jobId === null ? null : String(jobId), from: at, until, [kind]: size, decision: { ...decision }, at, squash: SQUASH };
     if (kind !== 'limit') record.left = size;
     const data = this.load();
     HoldBook.expire(data, utcTime(at));
     for (const hold of data.holds) {
-      if (hold.closed === null && hold.reason === reason && (record.caller === null || record.caller === hold.caller)
+      if (hold.closed === null && hold.reason === reason && (caller === null || names(caller, hold).includes(hold.caller))
         && (jobId === null || hold.jobs.includes(String(jobId)))) {
         hold.closed = 'lifted';
         hold.closedAt = at;
@@ -234,7 +248,7 @@ export class HoldBook {
 
   static matching(data, reason, caller, jobId, at, kind) {
     return data.lifts.filter((l) => l.reason === reason && kind in l && HoldBook.live(l, at)
-      && (l.caller === null || l.caller === caller) && (l.job === null || l.job === jobId));
+      && (l.caller === null || names(caller, l).includes(l.caller)) && (l.job === null || l.job === jobId));
   }
 
   /** Whether a lift lets work past the limit: {admitted: true, lift, left} spends one job or `costUsd`, else {admitted: false}. */

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

@@ -22,6 +22,7 @@
 import http from 'node:http';
 import net from 'node:net';
 import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED, UNKNOWN, method as tableMethod, owner as ownerOf, refusal, serverEnd } from './fabric-peer-owner.mjs';
+import { loopbackHost } from './fabric-socket-proof.mjs';
 
 export const RETRY_STATUSES = Object.freeze([408, 425, 429, 500, 502, 503, 504]);
 export const IDEMPOTENT_METHODS = Object.freeze(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
@@ -78,11 +79,8 @@ export function redactUrl(url) {
   return `${parts.protocol}//${parts.host}${parts.pathname}`;
 }
 
-function isLoopback(host) {
-  const h = host.replace(/^\[|\]$/g, '');
-  if (h === 'localhost' || h.endsWith('.localhost') || h === '::1') return true;
-  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
-}
+// Loopback as new URL leaves the host: the kit's one rule, shared with fabric-delegation (FAA-187 (15)).
+const isLoopback = loopbackHost;
 
 // Refuse what this client never sends: another scheme, no host, credentials in the URL, plain http off loopback.
 export function checkUrl(url, { insecure = false } = {}) {

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

@@ -79,7 +79,8 @@ export function fabricRoot(platform = process.platform, env = process.env) {
 /**
  * true: a process of this OS account runs under pid; false: none does. null (falsy): a process of another account does
  * (EPERM), as when the id hub.json names was reused: not verified, never called running (FAA-304, the session hooks'
- * answer since FAA-254). Never signals it.
+ * answer since FAA-254). Never signals it. On Windows libuv opens the process for terminate, query and synchronize, so
+ * an elevated process of the same user answers EPERM too; the Python twin asks OpenProcess for the same access (FAA-323).
  */
 export function pidAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
@@ -192,7 +193,7 @@ export function readCredential(file) {
  * is HubError hub-unavailable (retryable); a listener that is not this OS account's process is HubError foreign-user
  * (retryable) before the bearer is sent (DEC-0154 HA-2): the connection is checked from the socket table first.
  */
-export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion, agent = HUB_AGENT } = {}) {
+export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion, agent = HUB_AGENT, deadline = 0 } = {}) {
   const m = LOOPBACK_ORIGIN.exec(origin);
   if (!m) return Promise.reject(new HubError('not-a-hub', 'Only the hub\'s loopback origin is used.'));
   const payload = method === 'DELETE' ? null : Buffer.from(JSON.stringify(body));
@@ -224,6 +225,9 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
       res.on('error', () => reject(new HubError('hub-unavailable', 'Fabric\'s hub did not answer (the answer broke off).', true)));
     });
     req.on('timeout', () => req.destroy(new Error('timeout')));
+    // `deadline` (ms) bounds the whole request, where `timeout` bounds each socket read (FAA-187 (12))
+    const timer = deadline > 0 ? setTimeout(() => req.destroy(new Error('deadline')), deadline) : null;
+    if (timer) req.on('close', () => clearTimeout(timer));
     req.on('error', (e) => reject(e instanceof ListenerRefused
       ? listenerRefusal(e)
       : new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));