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

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // 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.
@@ -5,7 +6,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 +21,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 +38,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,43 +87,50 @@ 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. */
     this.holdDelay = POLL_SECONDS;
     this.onHold = new Set();
+    this.takenBack = new Set(); // capabilities the operator took back, not yet held again (FAA-325)
     /** 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)
     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 +160,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 +203,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 +215,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 +275,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 +294,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 +483,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 +504,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 +567,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 +595,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 +662,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 +715,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 +737,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-shapes.mjs

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The project board's wire (fabric-project-comms/0.1, DEC-0022, DEC-0073, DEC-0077): constants, refusal codes, the request digest, the closed shapes the kit reads back, evidence.
 // Part of the Node board connector (FAA-65, layer L4); the twin of fabric_board_shapes.py. Node 20+, no dependency.
 import crypto from 'node:crypto';

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The board responder's slot records (FAA-155, FAA-163): the generation it holds each slot at, a move to another
 // session and its take-back, and a capability whose enroll was refused, retried on its own. Part of the board
 // connector (FAA-65, layer L4); Responder (fabric-board-session.mjs) extends SlotKeeper.
@@ -27,6 +28,9 @@ export class SlotKeeper {
     this.confirmed[capability] = generation;
     delete this.said[`board.slot.refused:${capability}`]; // held again: a later refusal is said again
     delete this.said[`board.slot.contested:${capability}`]; // and a later contest, by enroll or replace
+    if (this.takenBack.delete(capability)) { // FAA-325: held again after the operator's take-back, said once
+      this.emit('board.slot.returned', 'info', `The ${capability} slot on this Project is this service's again: the operator took it back, and it answers it from now on.`, { capability, generation });
+    }
   }
 
   /** The slot record, best effort: one that cannot be written now is written at the next receipt. */
@@ -131,7 +135,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 +147,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 +212,18 @@ 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.takenBack.delete(capability); // said below as a move back, once
       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;
   }
 
   /**
@@ -220,8 +235,11 @@ export class SlotKeeper {
     this.checkpoint.slot(capability, null);
     delete this.claimKeys[capability]; // a receipt from before the take-back may be dead
     this.probing.delete(capability);
-    if (this.slots[capability]?.state === 'moved') this.slots[capability] = { state: 'contested', renewedAt: 0 };
+    const state = this.slots[capability]?.state;
+    if (state === 'moved') this.slots[capability] = { state: 'contested', renewedAt: 0 };
     delete this.said['board.slot.moved'];
+    // board.slot.returned is said once the slot is held again (FAA-325); a slot still held has nothing to say
+    if (state !== 'held') this.takenBack.add(capability);
   }
 
   // -- one capability's refusal (FAA-163) --

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // 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 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.

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The estate ceremonies' headless join (contract DEC-0084), the Node kit; the twin of fabric_ceremonies.py, answer for
 // answer (test/fixtures/contract/ceremony-vectors.json). Node built-ins only.
 // verifyEnrollToken (the hub's and the node's verifier of an enroll-token/1), enrollJoinInput (what the joining machine

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // What an agent uses: fabric-connections/0.1, the extension keyed extensions/connections/0.1 (DEC-0096, FAC-SEM-127).
 // connectionsView reads a well-known document as the contract's connectionsView does (it never throws);
 // connectionsExtension builds the `extensions` entry a service declares, `state` from its own checks and its degraded[].
@@ -88,7 +89,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 +118,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 +130,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-context.mjs

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // One instance per context (FAA-125, organization row N-11; contract DEC-0082, "One instance per context on a machine"):
 // from a context, `personal` or `org:<orgId>`, the service instance, its folders, descriptor and instance lock.
 // Part of the Node service kit (layer L3, after fabric-descriptor); the twin of fabric_context.py, answer for answer

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The Node kit's cryptography helpers, once (FAA-65, layer L1); the twin of fabric_crypto.py. Signature verification
 // itself is Node's (`crypto.verify`); what lives here is what the runtime does not refuse on its own: keys of small
 // order (DEC-0045) and P-256 points off the curve, plus sha256. Node 20+, no dependency.

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // The callee's side of fabric-delegation/0.1 (Fabric Agent Contract DEC-0039, Fabric ADR-0144): check a
 // delegation token or an approval offline against the estate's published keys, and answer `ok` or one refusal
 // code. A port of the contract's `src/delegation.ts` at the pinned revision; the shared vectors in
@@ -15,10 +16,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 +414,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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // How a service is found (fabric-service/0.1): its descriptor, peers and app descriptors (DEC-0061, DEC-0069), build identity and the well-known document.
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_descriptor.py. Node 20+, no dependency.
 import { spawnSync } from 'node:child_process';
@@ -12,13 +13,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.9';
 
 export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 
@@ -47,7 +48,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 +68,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 +202,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 +432,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-estate-rules.mjs

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // `estate-record/1` (Fabric Agent Contract DEC-0055): the record's own rules, without a verifier; the twin of
 // fabric_estate_rules.py. The contract's src/estate-record-rules.ts at the pin, held to the contract's own vectors
 // (test/fixtures/contract/estate-vectors.json). Split from fabric-estate.mjs (0.52.0, decision D8) so each module stays

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // `estate-record/1` (Fabric Agent Contract DEC-0055): verify an estate revision and check its rules, the twin of
 // fabric_estate.py. The contract's src/estate-record-rules.ts, src/webauthn.ts and src/p256.ts at the pin, held to the
 // contract's own vectors (test/fixtures/contract/estate-vectors.json):

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

@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 // A service's events (DEC-0029): making them, paging them and the JSONL event log.
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_events.py. Node 20+, no dependency.
 import { ServiceError } from './fabric-base.mjs';
@@ -18,7 +19,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\`).`);