@passioncode-ai/fabric-agent-adapter 0.60.0 → 0.62.0

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

@@ -5,10 +5,10 @@ import crypto from 'node:crypto';
 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';
+import { BoardRequest, BoardSession, Checkpoint, PERSONAL_BOARD, covers, mandateOptions, readMandate } 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 }; // re-exported: callers import them from here since 0.40.0
+export { BoardRequest, BoardSession, Checkpoint, PERSONAL_BOARD }; // re-exported: callers import them from here since 0.40.0
 export { HOLD_RETRY_MAX_SECONDS, LEASE_MARGIN_SECONDS, SESSION_CODES }; // since 0.56.0 defined in fabric-board-slots.mjs
 
 export const RENEW_SECONDS = 20;
@@ -34,10 +34,23 @@ const NOT_OURS = new Set(['queued', 'claimed', 'answered']);
 export class WorkContext {
   #responder;
   #entry;
-  constructor(responder, entry) {
+  #caller;
+  constructor(responder, entry, mandate = null, caller = null) {
     this.#responder = responder;
     this.#entry = entry;
+    this.#caller = caller;
     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);
+  }
+  toJSON() {
+    return { stopped: this.stopped }; // never the mandate: it holds the operator's words
+  }
+  [Symbol.for('nodejs.util.inspect.custom')]() {
+    return this.toJSON(); // console.log(ctx) prints no mandate either
   }
   async progress(note) {
     if (this.stopped) throw new Stopped();
@@ -69,13 +82,15 @@ 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 } = {}) {
+    now = () => performance.now() / 1000, rand = Math.random, sessionFactory, agentId = null, mandateFrom = null, wall = Date.now } = {}) {
     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.');
     const caps = [...(capabilities ?? [])];
     if (!caps.length || caps.some((c) => typeof c !== 'string' || !CAPABILITY.test(c)) || new Set(caps).size !== caps.length) throw new BoardError('invalid_arguments', 'Name each capability once, [a-z][a-z0-9._-]{1,127}.');
     Object.assign(this, { hub, capabilities: caps, credentialFile, handler, admit, observe, emitTo: emit, now, rand });
     this.project = normalProject(projectId);
+    // 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 });
     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));
@@ -679,7 +694,11 @@ export class Responder extends SlotKeeper {
   }
 
   async runWork(entry, request) {
-    const ctx = new WorkContext(this, entry);
+    const { mandate, unread } = readMandate(request, this.mandateFrom, this.agentId);
+    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 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; });

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

@@ -37,6 +37,7 @@ export {
   BoardRequest,
   WorkContext,
   Responder,
+  PERSONAL_BOARD,
 } from './fabric-board-session.mjs';
 export {
   selfCheck,

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

@@ -432,7 +432,9 @@ export class JwksCache {
     if (typeof source !== 'string' || !source) throw new Error('the key set needs a source');
     if (/^https?:\/\//.test(source)) {
       const url = new URL(source);
-      if (url.username || url.password) throw new Error('a key set URL carries no credentials');
+      const text = source.replace(/^[\x00-\x20]+|[\x00-\x20]+$/g, '').replace(/[\t\n\r]/g, '');
+      // the authority as written too, as Python's netloc reads it (`https://h\\u:p@x/j`, `https://@x/j`: seam reading 13)
+      if (url.username || url.password || /^[a-z][a-z0-9+.-]*:[/\\]*[^/?#]*@/i.test(text)) throw new Error('a key set URL carries no credentials');
       if (url.protocol === 'http:' && !loopback(url.hostname)) throw new Error('a key set is read over https, or over http on loopback only');
     } else if (source.includes('://')) {
       throw new Error('a key set is an https URL, a loopback http URL or a file path');

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

@@ -2,7 +2,7 @@
 // Part of the Node service kit (FAA-65, layer L3); the twin of fabric_descriptor.py. Node 20+, no dependency.
 import fs from 'node:fs';
 import path from 'node:path';
-import { credentialName, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
+import { credentialName, repositoryCredential, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
 import { ID, INSTANCE, LOCAL_PATH, PROTOCOL, ServiceError, TASK, UNIT, expand } from './fabric-base.mjs';
 import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
 import { protocolsFindings } from './fabric-protocols.mjs';
@@ -182,7 +182,7 @@ export function descriptorMemberProblems(d) {
     for (const k of Object.keys(runner)) if (!['kind', 'credentialKind'].includes(k)) problems.push(`runner has no member ${k}`);
     if (!CREDENTIAL_KINDS.includes(runner.credentialKind)) problems.push('runner.credentialKind is subscription, key, platform-metered or none');
     if ('kind' in runner && !(typeof runner.kind === 'string' && RUNNER_KIND_NAME.test(runner.kind))) problems.push("runner.kind is a runner kind's name");
-    if (runner.credentialKind === 'subscription' && !Object.hasOwn(SUBSCRIPTION_RUNNERS, runner.kind)) problems.push("a subscription runs only in its vendor's runner: runner.kind claude-code, kimi-code or codex");
+    if (runner.credentialKind === 'subscription' && !(typeof runner.kind === 'string' && Object.hasOwn(SUBSCRIPTION_RUNNERS, runner.kind))) problems.push("a subscription runs only in its vendor's runner: runner.kind claude-code, kimi-code or codex");
     for (const [k, v] of Object.entries(runner)) places.push([`/runner/${pointer(k)}`, v]);
   }
   if ('source' in d) {
@@ -194,7 +194,8 @@ export function descriptorMemberProblems(d) {
       if (!(typeof repository === 'string' && SOURCE_URI.test(repository.replace(IP_LITERAL, '$1h')))) problems.push('source.repository is a URI (RFC 3986), such as https://github.com/owner/name');
       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');
-      places.push(['/source/repository', repository]);
+      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)
     }
   }
   if ('peer' in d) {
@@ -290,10 +291,39 @@ export function portOf(origin) {
   return Number(m[1]);
 }
 
+export const NO_SOURCE_REPOSITORY = 'names no source.repository, the repository its code is built from '
+  + '(https://github.com/owner/name): it links the agent to its project (FAA-198)';
+const PASS_SOURCE = 'Name it in this call: source: { repository } in the descriptor writeDescriptor writes, or in '
+  + 'registerRemote\'s options; one written after the call returns is too late for a new install.';
+
+const HIERARCHICAL = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+
+// FAA-198: why a new install of this (valid) descriptor is refused, or null: it names no source.repository and no
+// descriptor of its id.instance is installed yet. An installer checks it before it writes anything else.
+export const namesRepository = (d) => d?.source !== null && typeof d?.source === 'object' && !Array.isArray(d.source)
+  && typeof d.source.repository === 'string' && d.source.repository !== '';
+
+// An installed descriptor is a regular file, whatever it holds; a folder, a broken link or a path that cannot be
+// examined is none.
+export function sourceRefusal(d, dir = servicesDir()) {
+  if (namesRepository(d)) return null;
+  const instance = d?.instance ?? 'default';
+  // An id or instance that is no string names no installed file, in both kits (seam reading 3).
+  try { if (typeof d?.id === 'string' && typeof instance === 'string' && fs.statSync(descriptorPath(d.id, instance, dir)).isFile()) return null; } catch { /* not installed */ }
+  return `Descriptor ${d?.id}.${instance} ${NO_SOURCE_REPOSITORY}. ${PASS_SOURCE}`;
+}
+
+// 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()) {
   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' });
+  }
   // 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-http.mjs

@@ -52,8 +52,17 @@ export class Response {
 
 // The URL as it may appear in an error or a log line: scheme, host, port and path; no userinfo, query or fragment.
 export function redactUrl(url) {
+  let text = String(url).replace(/^[\x00-\x20]+|[\x00-\x20]+$/g, '').replace(/[\t\n\r]/g, '');
+  // The user information as written goes first, as the Python twin drops it: `https://h\\u:pw@x/r` would print `pw` in
+  // its path, a backslash being a slash to WHATWG (0.62.0 seam reading 11).
+  const written = /^([A-Za-z][A-Za-z0-9+.-]*:[/\\]*)([^/?#]*)/.exec(text); // after any run of slashes (seam reading 13)
+  if (written && written[2].includes('@')) text = written[1] + written[2].slice(written[2].lastIndexOf('@') + 1) + text.slice(written[0].length);
   let parts;
-  try { parts = new URL(String(url)); } catch { return '<unparseable url>'; }
+  try { parts = new URL(text); } catch {
+    // a scheme other than a special one keeps its name, as the Python twin prints it whatever follows (unit reading 14)
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(text)?.[1].toLowerCase();
+    return scheme && !['http', 'https', 'ws', 'wss', 'ftp'].includes(scheme) ? `${scheme}:<redacted>` : '<unparseable url>';
+  }
   // Only http and https are sent; any other scheme keeps no more than its name (0.56.0 product r10).
   if (parts.protocol !== 'http:' && parts.protocol !== 'https:') return `${parts.protocol}<redacted>`;
   return `${parts.protocol}//${parts.host}${parts.pathname}`;
@@ -74,7 +83,10 @@ export function checkUrl(url, { insecure = false } = {}) {
   if (!['http:', 'https:'].includes(parts.protocol) || !parts.hostname) {
     throw new HttpError('only http and https URLs with a host are sent', { url: redactUrl(url), kind: 'refused' });
   }
-  if (parts.username || parts.password || /^[a-z]+:\/*[^/?#]*@/i.test(String(url).trim())) {
+  // the user information as written, read on the text `new URL` reads (C0 and space off its ends, tab, CR and LF out),
+  // so `ht\ttps://h\\u:pw@x/r` is refused as the Python twin refuses it (0.62.0 unit reading 12)
+  const text = String(url).replace(/^[\x00-\x20]+|[\x00-\x20]+$/g, '').replace(/[\t\n\r]/g, '');
+  if (parts.username || parts.password || /^[a-z][a-z0-9+.-]*:[/\\]*[^/?#]*@/i.test(text)) {
     throw new HttpError('credentials in a URL are refused: send them in a header', { url: redactUrl(url), kind: 'refused' });
   }
   if (parts.protocol === 'http:' && !insecure && !isLoopback(parts.hostname)) {

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

@@ -282,6 +282,16 @@ export function mandateSpend(value) {
   return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
 
+/** A job's approval step {effect, spendUsd?, project?} as a job file keeps it: read as the gate reads it, so a job's
+ * start and its answer agree (0.61.0 seam reading 32, readings 33 and 34): a spend through mandateSpend (dropped when none), a project
+ * as a primitive string, else UNREADABLE_PROJECT (dropped when null or undefined). */
+export function keptStep(step) {
+  const { effect, spendUsd, project } = step; // each member read once (seam reading 34)
+  const spend = mandateSpend(spendUsd);
+  return { effect, ...(spend !== undefined ? { spendUsd: spend } : {}),
+    ...(project !== undefined && project !== null ? { project: typeof project === 'string' ? project : UNREADABLE_PROJECT } : {}) };
+}
+
 export function actionGate({ action, tier, caller, meta, target, elicited = false, approval, actionDigest, humanStepUrl, now, self, effect, callerAgent, spendUsd, project, mandateCapability } = {}) {
   const inputs = { action, tier, caller, elicited: elicited === true, now };
   if (isObject(meta) && Object.hasOwn(meta, 'decision')) inputs.decision = meta.decision;

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

@@ -41,6 +41,7 @@ export {
   jobStep,
   actionGate,
   mandateSpend,
+  keptStep,
   UNREADABLE_PROJECT,
   actionRefusalToolResult,
   usageFindings,
@@ -49,7 +50,7 @@ export {
   pauseMessage,
   repeatedKeyDecision,
 } from './fabric-interop-rules.mjs';
-import { PROTOCOL, EXTENSION_KEY, MCP_REVISION, TERMINAL, CONTRACT_VERSION, JOB_HANDLE_SCHEMA, InteropError, UnknownJob, parseTraceparent, childTraceparent, traceIds, QUOTA_EXHAUSTED, QUEUE_FULL, OUTCOME_UNKNOWN, LIMIT_REACHED, INTEROP_NULL_USAGE, PROTOCOLS_READ, utcTime, quotaDataOk, readJobPause, jobCallerAction, intentIdempotencyKey, readsNullUsage, requestMeta, usageFindings, usageToward, jobLimitRules, pauseMessage, repeatedKeyDecision, OUTCOMES, ENVELOPE_REQUIRED, JOB_ID, KEY, SECRET_WORDS } from './fabric-interop-rules.mjs'; // the rule layer (FAA-92)
+import { PROTOCOL, EXTENSION_KEY, MCP_REVISION, TERMINAL, CONTRACT_VERSION, JOB_HANDLE_SCHEMA, InteropError, UnknownJob, parseTraceparent, childTraceparent, traceIds, QUOTA_EXHAUSTED, QUEUE_FULL, OUTCOME_UNKNOWN, LIMIT_REACHED, INTEROP_NULL_USAGE, PROTOCOLS_READ, utcTime, quotaDataOk, readJobPause, jobCallerAction, intentIdempotencyKey, readsNullUsage, requestMeta, usageFindings, usageToward, jobLimitRules, pauseMessage, repeatedKeyDecision, keptStep, OUTCOMES, ENVELOPE_REQUIRED, JOB_ID, KEY, SECRET_WORDS } from './fabric-interop-rules.mjs'; // the rule layer (FAA-92)
 
 // --- C3.1 capabilities as tools ----------------------------------------------------------
 export function expectedAnnotations(effect, idempotency) {
@@ -266,23 +267,28 @@ export class JobStore {
 
   // `steps` (DEC-0125) maps a request key to the approval step it asks for, {effect, spendUsd?, project?}, kept in the
   // job's private part (the format fabric_interop.py writes) so a service reads an answer's _meta.mandate for that step.
+  // A step is kept as the gate reads it (keptStep), so a job's start and its answer agree.
   requestInput(jobId, inputRequests, statusMessage, { steps } = {}) {
+    const entries = Object.entries(inputRequests ?? {});
+    if (!entries.length || Array.isArray(inputRequests) || typeof inputRequests !== 'object') throw new InteropError('input_required needs a JSON object of at least one input request.'); // a JSON object of requests, first (unit 38, 40)
+    const kept = Object.create(null); // the value checked is the value kept (seam 34); a key __proto__ stays a key (35)
     for (const [key, step] of Object.entries(steps ?? {})) {
-      if (!Object.hasOwn(inputRequests ?? {}, key) || !EFFECT_CLASSES.includes(step?.effect)) throw new InteropError(`Step ${key}: an input request's key with its effect class (DEC-0125).`);
+      kept[key] = Object.hasOwn(inputRequests, key) && step !== null && step !== undefined ? keptStep(step) : {};
+      if (!EFFECT_CLASSES.includes(kept[key].effect)) throw new InteropError(`Step ${key}: an input request's key with its effect class (DEC-0125).`);
     }
-    const entries = Object.entries(inputRequests ?? {});
-    if (!entries.length) throw new InteropError('input_required needs at least one input request.');
-    for (const [key, request] of entries) if (!KEY.test(key) || request?.method !== 'elicitation/create') throw new InteropError(`Input request ${key} must be a keyed elicitation/create request.`);
+    for (const [key, request] of entries) if (!KEY.test(key) || request === null || typeof request !== 'object' || Array.isArray(request) || request.method !== 'elicitation/create') throw new InteropError(`Input request ${key} must be a keyed elicitation/create request.`);
     const [finding] = inputRequestLinkFindings({ inputRequests }); // FAC-SEM-143 (D12)
     if (finding) throw new InteropError(`${finding.instancePath}: ${finding.message}`);
-    return this.transition(jobId, 'input_required', { inputRequests, statusMessage }, { steps: { ...(steps ?? {}) } });
+    return this.transition(jobId, 'input_required', { inputRequests, statusMessage }, { steps: kept });
   }
 
   answer(jobId, inputResponses) {
     const job = this.get(jobId);
     if (job.status !== 'input_required') return {};
-    const matched = Object.fromEntries(Object.entries(inputResponses ?? {}).filter(([key, value]) =>
-      key in (job.inputRequests ?? {}) && ['accept', 'decline', 'cancel'].includes(value?.action)));
+    const plain = (value) => value !== null && typeof value === 'object' && !Array.isArray(value); // as Python's dict (seam r37)
+    const asked = plain(job.inputRequests) ? job.inputRequests : {};
+    const matched = Object.fromEntries(Object.entries(plain(inputResponses) ? inputResponses : {}).filter(([key, value]) =>
+      Object.hasOwn(asked, key) && ['accept', 'decline', 'cancel'].includes(value?.action))); // an asked key, never an inherited name (seam 36)
     // The answered question's kept steps go in the same write: none outlives its answer.
     if (Object.keys(matched).length) this.transition(jobId, 'working', {}, { steps: {} });
     return matched;

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

@@ -43,9 +43,19 @@ export class InstanceLock {
         if (error.code === 'EAGAIN' || error.code === 'EWOULDBLOCK') throw new AlreadyRunning(readPid(this.path), this.path);
         throw error;
       }
-      fs.ftruncateSync(this.fd, 0);
-      fs.writeSync(this.fd, String(process.pid));
-      fs.fsyncSync(this.fd);
+      try {
+        fs.ftruncateSync(this.fd, 0);
+        fs.writeSync(this.fd, String(process.pid));
+        fs.fsyncSync(this.fd);
+      } catch (error) { // a full disk or an I/O error: let the lock go, or nobody can (the caller drops this object)
+        const fd = this.fd;
+        this.fd = null;
+        try {
+          fs.closeSync(fd);
+        } catch { // a deferred write error (NFS) at the close: the lock still goes, the first error stands
+        }
+        throw error;
+      }
       return this;
     }
     // Linux: an abstract unix socket; Windows: a named pipe. Each is exclusive, has no file, and dies
@@ -66,7 +76,17 @@ export class InstanceLock {
       this.server.listen(name, resolve);
     });
     this.server.unref();
-    atomicWrite(this.path, String(process.pid));
+    try {
+      atomicWrite(this.path, String(process.pid));
+    } catch (error) { // as on macOS: the name is let go with the failed write, the first error standing
+      const server = this.server;
+      this.server = null;
+      try {
+        server.close();
+      } catch { // nothing to add to the first error
+      }
+      throw error;
+    }
     return this;
   }
 

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

@@ -45,6 +45,9 @@ export const OPERATOR_SOURCE_PROTOCOL = 'operator-source/1';
 const SCOPE_MEMBERS = new Set(['capabilities', 'actions', 'effects', 'perCallMaxUsd', 'projects']);
 const STEP_MEMBERS = new Set(['agent', 'at', 'scope']);
 const AGENT_ID = /^[a-z][a-z0-9-]{1,62}(\.[a-z][a-z0-9-]{0,31})?$/; // common.schema.json agentId
+
+/** A registry agent id (common.schema.json agentId): a provider or service id, optionally `.instance`. */
+export const isAgentId = (value) => typeof value === 'string' && AGENT_ID.test(value);
 const CAPABILITY = /^[a-z][a-z0-9._-]{1,127}$/; // common.schema.json capabilityName
 const REQUEST_KEY = /^[A-Za-z0-9_.-]{1,64}$/; // interop-common.schema.json requestKey
 const PROJECT = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;

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

@@ -84,3 +84,60 @@ export function secretUrl(value) {
   }
   return false;
 }
+
+const REPOSITORY_URI = /^([A-Za-z][A-Za-z0-9+.-]*:(?:\/\/[^/?#]*)?)([^?#]*)([\s\S]*)$/;
+const REPOSITORY_NAME = /^(?:[a-z0-9._-]+|[A-Za-z._-]+)$/; // lower case, or letters with no digit (readings 8)
+const REPOSITORY_AUTHORITY = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+const KEY_AT_A_WORD = new RegExp(`(?:^|(?<=[._-]))(?:${SECRET_VALUE.source})`, 'i');
+const JWT_AT_A_WORD = new RegExp(`(?:^|(?<=[._-]))${JWT_SHAPE.source}`);
+const SPECIAL_QUERY = /^(?:https?|wss?|ftp|file):/i; // whose query also encodes `'`, as the URL standard does
+
+/** Whether a path segment reads as a repository's name: lower case, or letters with no digit, with no provider key's
+ * or JWT's shape at its start or after a `.`, `_` or `-` (0.62.0 readings 9 and 10), so a letters-only key is a key. */
+export const repositoryName = (piece) => REPOSITORY_NAME.test(piece) && !KEY_AT_A_WORD.test(piece) && !JWT_AT_A_WORD.test(piece);
+
+/** Every `%XX` escape of an ASCII character decoded, the rest as written (fabric_secrets.ascii_decoded, readings 11). */
+export const asciiDecoded = (text) => text.replace(/%([0-7][0-9A-Fa-f])/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+
+/** Whether a repository URI's user information holds a password: every slash and backslash after the colon skipped,
+ * then up to the next `/`, `?` or `#` (fabric_secrets.repository_password, 0.62.0 readings 10 to 14). */
+export function repositoryPassword(value) {
+  const text = value.replace(/^[\x00-\x20]+|[\x00-\x20]+$/g, '').replace(/[\t\n\r]/g, '');
+  const colon = text.indexOf(':');
+  const rest = colon < 0 ? '' : text.slice(colon + 1); // as Python's partition leaves it (unit reading 12)
+  const authorities = colon < 0 ? [] : [/^[^/?#]*/.exec(rest.replace(/^[/\\]+/, ''))[0]];
+  const users = authorities.map((authority) => authority.slice(0, Math.max(authority.lastIndexOf('@'), 0)));
+  return [...users, ...users.map(asciiDecoded)].some((user) => user.includes(':') && user.slice(user.indexOf(':') + 1) !== '');
+}
+
+// A repository's parameters, read as fabric_secrets.secret_url reads them, by hand: `new URL`
+// refuses a host it cannot parse and a special scheme written without `//` (`https:host/r?access_token=...`), where
+// the Python twin still reads them (0.62.0 readings 8 and 9, FAA-200 (17)).
+function repositoryParts(head, tail) {
+  const text = tail.replace(/[\x00-\x20]+$/, '').replace(/[\t\n\r]/g, '');
+  const hash = text.indexOf('#');
+  const before = hash < 0 ? text : text.slice(0, hash);
+  const query = before.startsWith('?') ? before.slice(1) : '';
+  const fragment = hash < 0 ? '' : text.slice(hash + 1);
+  try { // percent-encode them as `new URL` does, on a host it always reads
+    const url = new URL(`${SPECIAL_QUERY.test(head) ? 'https://h.invalid/' : 'x-repository://h/'}?${query}#${fragment}`);
+    return [url.search.slice(1), url.hash.slice(1)];
+  } catch { return [query, fragment]; }
+}
+
+// FAA-198 (0.62.0 readings 6 and 7): whether a repository URI carries a credential: in its scheme and authority (a
+// user), in its query or fragment as secretUrl reads them, or as a path segment shaped like a key. A path segment in
+// lower case, or of letters with no digit (task-pipeline-dashboard, Task-Pipeline-Dashboard), is the repository's
+// name, never a key, though it reads as an `sk-` shape, unless a key's shape starts it or follows a `.`, `_` or `-` in
+// it (repositoryName); a segment is read as written and asciiDecoded. A
+// user outside a URL's authority (an scp form, `https:user@host/path`) counts as one: a user is an authority's.
+export function repositoryCredential(value) {
+  if (value.includes('@') && !REPOSITORY_AUTHORITY.test(value)) return true;
+  const match = REPOSITORY_URI.exec(value);
+  if (!match) return secretArgument(value);
+  const [, head, path, tail] = match;
+  const odd = [path, asciiDecoded(path)].flatMap((written) => written.split(/[/\\:]/)).filter((piece) => piece && !repositoryName(piece));
+  if (repositoryPassword(value) || secretArgument(head + tail) || secretArgument(asciiDecoded(head)) || odd.some((piece) => secretArgument(piece))) return true; // the authority decoded too (unit reading 12)
+  return repositoryParts(head, tail).some((part) => [...rawValues(part)].some(([name, values]) =>
+    values.some((raw) => (raw !== '' && credentialName(name)) || secretValue(raw))));
+}

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

@@ -118,6 +118,9 @@ export {
   placementOf,
   remoteOriginProblems,
   portOf,
+  NO_SOURCE_REPOSITORY,
+  namesRepository,
+  sourceRefusal,
   writeDescriptor,
   removeDescriptor,
   dashboardExtensionProblems,

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_auth.py

@@ -36,6 +36,9 @@ from fabric_paths import (
     services_dir,
 )
 from fabric_descriptor import (
+    descriptor_path,
+    names_repository,
+    source_refusal,
     validate_descriptor,
     write_descriptor,
 )
@@ -393,6 +396,15 @@ def register_remote(*, service_id: str, name: str, origin: str, token: str, inst
         descriptor["runner"] = dict(runner)
     if peer is not None:
         descriptor["peer"] = dict(peer)
+    if source is None:  # a rotation that names no source keeps the installed one (0.62.0 seam reading 1)
+        try:
+            installed = json.loads(descriptor_path(service_id, instance, root).read_text(encoding="utf-8")).get("source")
+        except (OSError, ValueError, AttributeError):
+            installed = None
+        # Only one the kit accepts: a hand-edited source never blocks a rotation; it is dropped with the warning.
+        base = set(validate_descriptor(descriptor))
+        source = installed if names_repository({"source": installed}) and set(
+            validate_descriptor(dict(descriptor, source=installed))) <= base else None
     if source is not None:
         descriptor["source"] = dict(source) if isinstance(source, dict) else source
     if doctor:
@@ -400,9 +412,12 @@ def register_remote(*, service_id: str, name: str, origin: str, token: str, inst
     problems = validate_descriptor(descriptor)
     if problems:
         raise ServiceError("Descriptor is invalid: %s." % "; ".join(problems))
+    refusal = source_refusal(descriptor, root)  # before the token is written: a refused install leaves nothing (FAA-198)
+    if refusal:
+        raise ServiceError(refusal)
     ensure_private_dir(token_file.parent)
     atomic_write(token_file, token.strip().encode(), 0o600)
-    return write_descriptor(descriptor, root)
+    return write_descriptor(descriptor, root, _stacklevel=3)  # the warning names the installer's call
 
 
 def cookie_value(cookie_header: Optional[str], name: str = SESSION_COOKIE) -> Optional[str]:

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_board.py

@@ -62,6 +62,7 @@ from fabric_board_session import (  # noqa: F401
     _Work,
     Handler,
     Responder,
+    PERSONAL_BOARD,
 )
 from fabric_board_fixture import (  # noqa: F401
     _FIXTURE_PROJECT,

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric_board_link.py

@@ -4,18 +4,26 @@ names. Standard library only, Python 3.9+."""
 from __future__ import annotations
 
 import json
+import math
+import re
+from collections.abc import Mapping
 import threading
 from pathlib import Path
 from typing import Any
 from typing import Callable
 from typing import Dict
+from typing import List
 from typing import Optional
+from typing import Tuple
 
 import sys as _sys  # noqa: E402
 from pathlib import Path as _Path  # noqa: E402
 if str(_Path(__file__).resolve().parent) not in _sys.path:  # the kit loads from any working directory (FAA-65)
     _sys.path.insert(0, str(_Path(__file__).resolve().parent))
 import fabric_hub as _hub
+import fabric_interop_rules as _rules
+import fabric_mandate as _mandate
+from fabric_time import format_rfc3339 as _format_rfc3339  # noqa: E402 - the core's (FAA-65)
 import fabric_service as _fs
 from fabric_board_shapes import (  # noqa: E402 - the kit (FAA-65)
     BoardError,
@@ -210,3 +218,141 @@ class BoardRequest:
 
     def __repr__(self) -> str:  # never the body
         return "BoardRequest(%r, %r)" % (self.request_id, self.capability)
+
+
+# -- the operator's mandate in a board request (FAA-135; contract project-comms.md, DEC-0125 MD-3) ---------------------
+
+#: `mandate_from` naming every trusted sender of the board the service is installed on: the operator's personal board.
+PERSONAL_BOARD = "personal-board"
+_OPENER = re.compile(r"```json[ \t]*")
+_CLOSER = re.compile(r"```[ \t]*")
+
+
+def _json_blocks(body: str) -> List[str]:
+    """The bodies of the ```json blocks, each fence on its own line: one pass over the lines, so linear in the body
+    (an anchored regex rescanned to the end from every unclosed opener). Lines end at "\\n" alone, one "\\r" before it
+    dropped, as in the Node twin; an unclosed opener ends the scan."""
+    lines = [line[:-1] if line.endswith("\r") else line for line in body.split("\n")]
+    blocks: List[str] = []
+    i = 0
+    while i < len(lines):
+        if _OPENER.fullmatch(lines[i]):
+            j = i + 1
+            while j < len(lines) and not _CLOSER.fullmatch(lines[j]):
+                j += 1
+            if j == len(lines):
+                break
+            blocks.append("\n".join(lines[i + 1:j]))
+            i = j
+        i += 1
+    return blocks
+
+
+def _no_constant(name: str) -> Any:
+    raise ValueError(name)  # NaN and Infinity are not JSON
+
+
+def _bounded_int(literal: str) -> int:
+    """An integer of at most 4300 digits on every Python: 3.9 without int_max_str_digits converts a longer one in
+    quadratic time, and later ones refuse it, so all of them now refuse it alike."""
+    if len(literal) - literal.startswith("-") > 4300:
+        raise ValueError("an integer longer than 4300 digits")
+    return int(literal)
+
+
+def read_mandate(request: "BoardRequest", mandate_from: Any, agent_id: Optional[str]) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+    """The mandate a request carries, read only when the service opted in (`agent_id` and `mandate_from` set), the board
+    verified the sender (`provenance: trusted`) and its Project is one `mandate_from` names (or `PERSONAL_BOARD`): a T1
+    caller by project-comms. Answers `(mandate, None)`, `(None, None)` when none is read, or `(None, code)` for a body
+    that carries one the kit will not read: `mandate-blocks` (more than one) or `mandate-unreadable` (a block naming
+    `mandate/1` that is not JSON). A `source` in the block is dropped: a board block carries none (OA-7). Whether it
+    covers a call is `covers`' answer, never this one's."""
+    if agent_id is None or mandate_from is None or not isinstance(request.body, str):
+        return None, None
+    sender = request.sender if isinstance(request.sender, dict) else {}
+    principal = sender.get("principal") if isinstance(sender.get("principal"), dict) else {}
+    if principal.get("provenance") != "trusted":
+        return None, None
+    if not isinstance(sender.get("project"), str) or not sender["project"]:  # comms-message requires it; the caller
+        return None, None
+    if mandate_from != PERSONAL_BOARD and _fold(sender["project"]) not in mandate_from:
+        return None, None
+    found = []
+    for block in _json_blocks(request.body):
+        try:
+            value = json.loads(block, parse_constant=_no_constant, parse_int=_bounded_int)
+        except (ValueError, RecursionError):
+            if "mandate/1" in block:
+                return None, "mandate-unreadable"
+            continue
+        if isinstance(value, dict) and value.get("kind") == "mandate/1":
+            value.pop("source", None)  # a Project declares no protocols: a board block carries no source (OA-7)
+            found.append(value)
+    if len(found) > 1:
+        return None, "mandate-blocks"
+    return (found[0], None) if found else (None, None)
+
+
+CALL_MEMBERS = ("capability", "action", "effect", "spendUsd", "project")  # what mandate_covers reads of a call
+
+
+def covers(mandate: Optional[Dict[str, Any]], call: Any, agent_id: Optional[str], wall: Callable[[], float],
+           caller: Any = None) -> Optional[Dict[str, Any]]:
+    """`mandate_covers` for a call under a board request's mandate, its sender placed as T1 and no caller agent id (the
+    board names a Project's principal, not an agent the chain can bind; the chain's end alone binds it, MD-3). A covered
+    answer's `recordAs` names `caller`, the sender Project the board verified (MD-3 records the caller, as the action
+    path does). None when no mandate travelled: the handler asks the operator as it would without one. The call's
+    `spendUsd` and `project` are read failing closed, as the kit's other mandate readers read them (FAA-139): a spend
+    that is not a finite number is none, which a ceiling refuses; a `project` that is not a string, None included (the
+    contract's mandateCovers refuses a null project), is unreadable, which a mandate limited to projects refuses; a call
+    that names none leaves `project` out. Only the five members `mandate_covers` reads are read, each once, the way the
+    handler's own `call[name]` reads it (a `__getitem__` or a default answers, never the mapping's storage), and the
+    rest of the call is never touched."""
+    if mandate is None or agent_id is None:
+        return None
+    if isinstance(call, Mapping):
+        read: Dict[str, Any] = {}
+        for name in CALL_MEMBERS:
+            try:
+                value = call[name]
+            except KeyError:  # not named; any other error the mapping raises passes to the handler
+                continue
+            if name == "spendUsd":
+                value = _rules.mandate_spend(value)
+                if value is None:
+                    continue
+            elif name == "project":
+                value = value if type(value) is str else _rules.UNREADABLE_PROJECT
+            read[name] = value
+        call = read
+    clock, now = wall(), ""
+    if isinstance(clock, (int, float)) and not isinstance(clock, bool):
+        try:
+            now = _format_rfc3339(clock * 1000) if math.isfinite(clock) else ""
+        except (OverflowError, ValueError):  # finite but outside the dates a clock can name
+            now = ""
+    answer = _mandate.mandate_covers({"mandate": mandate, "tier": "T1", "now": now, "self": agent_id, "call": call})
+    if "recordAs" in answer:
+        answer = {"ok": True, "recordAs": dict(answer["recordAs"], caller=caller)}
+    return answer
+
+
+def mandate_options(agent_id: Any, mandate_from: Any) -> Any:
+    """The responder's opt-in, checked: an agent id the registry accepts, and `mandate_from` either `PERSONAL_BOARD` or
+    a collection of Project ids (strings). Answers `mandate_from` as the responder keeps it (a frozenset or the string)."""
+    if agent_id is not None and not _mandate.is_agent_id(agent_id):
+        raise BoardError("invalid_arguments", "agent_id must be the service's registry agent id.")
+    if mandate_from is None or mandate_from == PERSONAL_BOARD:
+        return mandate_from
+    try:
+        projects = None if isinstance(mandate_from, (str, bytes, Mapping)) else list(mandate_from)
+    except TypeError:
+        projects = None
+    if projects is None or not all(isinstance(p, str) and p for p in projects):
+        raise BoardError("invalid_arguments", "mandate_from is %r or a collection of Project ids." % PERSONAL_BOARD)
+    return frozenset(_fold(p) for p in projects)
+
+
+def _fold(project: str) -> str:
+    """A Project id as Fabric's board compares it: a uuid lower-cased, any other id as written (_hub._project)."""
+    return project.lower() if _hub.UUID.fullmatch(project) else project