@passioncode-ai/fabric-agent-adapter 0.79.1 → 0.80.2

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

@@ -0,0 +1,344 @@
+// The call queue and the load report of DEC-0104 (contract src/agent-network.ts, FAC-SEM-131 to FAC-SEM-133), as the
+// contract's reference answers them: a node that hosts a job-backed agent queues its jobs per (agentRef, context) with
+// these and reports its load as service-load/1 under extensions/load/0.1. Part of the Node service kit (FAA-289, layer
+// L3); the twin of fabric_load.py. Node 20+, no dependency. Nothing here throws on what it reads, except
+// loadExtension, which refuses a declaration a reader would treat as not declared.
+//
+// - jobCallerKey(accepted, credential): the opaque key of a job's caller (an accepted delegation's principal, its
+//   outermost actor and a partner organization ending the chain; else the credential the node knows the caller by).
+// - nextQueuedJob(queue, running, limits): the job the node starts next, or undefined (fairness between callers).
+// - admitJob(queue, running, job, limits, retryAfterSeconds): {admit: true}, or the queue-full refusal with its data.
+// - queueStatusMessage(position, length), readQueuePosition(statusMessage): `queued <position> of <length>`.
+// - jobQueueRules(value): FAC-SEM-131 over {queue, running, limits, started}.
+// - loadReportRules(report): FAC-SEM-132 on a service-load/1 report; loadReportProblems(report): its schema.
+// - loadView(wellKnown), loadExtensionRules(wellKnown): the declaration as a reader reads it, and FAC-SEM-133.
+// - loadExtension({ path, windowSeconds, limits }): the `extensions` entry a service declares.
+//
+// The kit has no JSON Schema validator: the two shapes are written here from the schemas as the contract's validator
+// reads them (lengths in code points, date-time as ajv-formats' full mode). Times in the queue are UTC instants
+// (interop-common#/$defs/utcInstant); times in the report are RFC 3339 read strictly (the contract's strictTime). The
+// wording of a schema problem is the kit's, not ajv's.
+import { ServiceError } from './fabric-base.mjs';
+import { dateTime } from './fabric-connections.mjs'; // ajv-formats' date-time, as the contract's validator reads it
+import { isObject, isString, objects, show } from './fabric-jsvalue.mjs';
+import { parseRfc3339Ms } from './fabric-time.mjs'; // the contract's strictTime
+
+/**
+ * @typedef {{ id: string, caller: string, at: string }} QueuedJob A job waiting at the hosting node: its id, its
+ *   caller's key (jobCallerKey) and when it arrived (a UTC instant).
+ * @typedef {{ id: string, caller?: string }} RunningJob A job running: its id and caller.
+ * @typedef {{ concurrency: number, perCaller: number, queueMax: number }} QueueLimits The queue's limits per
+ *   (agentRef, context), as the load extension declares them.
+ * @typedef {{ admit: true } | { admit: false, error: { code: 'queue-full', message: string,
+ *   data: { retryable: true, retryAfterSeconds: number } } }} Admission
+ * @typedef {{ code: string, instancePath: string, message: string }} Finding
+ * @typedef {{ declared: boolean, valid: boolean, load: { path: string, windowSeconds: number, limits: QueueLimits } | null,
+ *   errors: string[] }} LoadView
+ */
+
+export const LOAD_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/load/0.1';
+export const LOAD_REPORT_TYPE = 'service-load/1';
+// The refusal code, the same as fabric-interop-rules.mjs's QUEUE_FULL (a test holds them equal); not imported because
+// the facade fabric-service.mjs, which re-exports this module, comes before the interop rules in the kit's order.
+const QUEUE_FULL = 'queue-full';
+export const QUEUE_FULL_MESSAGE = "the agent's queue for this context is full: start again later";
+/** The longest queue a status message names (`queued <position> of <length>`, six digits). */
+export const QUEUE_LENGTH_MAX = 999999;
+export const DEFAULT_RETRY_AFTER_SECONDS = 60;
+
+const UTC_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:[0-5]\d(?:\.\d{1,3})?Z$/;
+const QUEUED = /^queued ([1-9]\d{0,5}) of ([1-9]\d{0,5})$/;
+const ORIGIN_PATH = /^\/(?!\/)[^\s]*$/u;
+const CONTEXT = /^(?:personal|org:[A-Za-z0-9][A-Za-z0-9_-]{0,127})$/;
+const KEY_PATH = `/extensions/${LOAD_EXTENSION_KEY.replace(/~/g, '~0').replace(/\//g, '~1')}`;
+const LIMITS = [['concurrency', 1, 1024], ['perCaller', 1, 1024], ['queueMax', 0, 100000]];
+const ROW_COUNTS = ['queued', 'running', 'completed', 'failed'];
+
+/** An own member, or undefined. */
+const member = (value, key) => (isObject(value) && Object.hasOwn(value, key) ? value[key] : undefined);
+/** A UTC instant (`T`, `Z`, at most three fraction digits, a day that exists) in milliseconds, else NaN. */
+const utcMs = (value) => (isString(value) && UTC_INSTANT.test(value) ? parseRfc3339Ms(value) : Number.NaN);
+const strictMs = (value) => (isString(value) ? parseRfc3339Ms(value) : Number.NaN);
+const codePoints = (value) => [...value].length;
+
+// --- The call queue (fabric-interop, DEC-0104) ---
+
+/**
+ * The key of a job's caller at a node that queues (DEC-0104), as the contract's jobCallerKey: for a call whose
+ * delegation the node accepted (verifyDelegation's answer), its `principal` and `caller` and the partner organization
+ * when the chain ends in one (DEC-0090); for a call with no token, the credential the node knows the caller by (a
+ * gate's pass with `principal: null` is that case too). A refused verdict has no key, and neither has an unreadable
+ * call: undefined. The key is opaque; only equality matters.
+ * @param {unknown} accepted
+ * @param {unknown} credential
+ * @returns {string | undefined}
+ */
+export function jobCallerKey(accepted, credential) {
+  if (isObject(accepted) && !(member(accepted, 'ok') === true && member(accepted, 'principal') === null)) {
+    const principal = member(accepted, 'principal');
+    const caller = member(accepted, 'caller');
+    if (member(accepted, 'ok') !== true || !isString(principal) || principal === '' || !isString(caller) || caller === '') return undefined;
+    const given = member(accepted, 'chain');
+    const chain = Array.isArray(given) ? given : [];
+    const last = chain[chain.length - 1];
+    const partner = chain.length > 1 && isString(last) && last.startsWith('org:') ? [last] : [];
+    return JSON.stringify(['delegated', principal, caller, ...partner]);
+  }
+  return isString(credential) && credential !== '' ? JSON.stringify(['credential', credential]) : undefined;
+}
+
+const limitsOk = (limits) => isObject(limits)
+  && [member(limits, 'concurrency'), member(limits, 'perCaller')].every((n) => Number.isSafeInteger(n) && n >= 1)
+  && Number.isSafeInteger(member(limits, 'queueMax')) && limits.queueMax >= 0;
+const waitingJob = (job) => isObject(job) && isString(member(job, 'id')) && isString(member(job, 'caller')) && Number.isFinite(utcMs(member(job, 'at')));
+
+/**
+ * The job the hosting node starts next for one (agentRef, context), or undefined (DEC-0104). Nothing starts while
+ * `concurrency` jobs run (every running job holds a slot, its caller readable or not). Of the waiting jobs whose caller
+ * runs fewer than `perCaller`, the one whose caller runs the fewest wins; between those callers, the one whose oldest
+ * waiting job arrived first; within a caller, its oldest. Arrival ties break by id (UTF-16 order).
+ * @param {unknown} queue
+ * @param {unknown} running
+ * @param {unknown} limits
+ * @returns {string | undefined}
+ */
+export function nextQueuedJob(queue, running, limits) {
+  if (!limitsOk(limits)) return undefined;
+  if ((Array.isArray(running) ? running.length : 0) >= limits.concurrency) return undefined;
+  const runningOf = new Map();
+  for (const job of objects(running)) if (isString(member(job, 'caller'))) runningOf.set(job.caller, (runningOf.get(job.caller) ?? 0) + 1);
+  const waiting = objects(queue)
+    .filter((job) => waitingJob(job) && (runningOf.get(job.caller) ?? 0) < limits.perCaller)
+    .sort((a, b) => utcMs(a.at) - utcMs(b.at) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  let best;
+  for (const job of waiting) if (best === undefined || (runningOf.get(job.caller) ?? 0) < (runningOf.get(best.caller) ?? 0)) best = job;
+  return best?.id;
+}
+
+/**
+ * Whether a start is admitted (DEC-0104): it is when the job would start at once (nextQueuedJob over the queue with it
+ * added answers its id), or when fewer than `queueMax` jobs wait; otherwise {admit: false, error} with the queue-full
+ * refusal and its `retryAfterSeconds` (1 to 3600, else 60). Unreadable limits or job refuse.
+ * @param {unknown} queue
+ * @param {unknown} running
+ * @param {unknown} job
+ * @param {unknown} limits
+ * @param {unknown} retryAfterSeconds
+ * @returns {Admission}
+ */
+export function admitJob(queue, running, job, limits, retryAfterSeconds) {
+  const waiting = objects(queue);
+  if (limitsOk(limits) && waitingJob(job) && (nextQueuedJob([...waiting, job], running, limits) === job.id || waiting.length < limits.queueMax)) return { admit: true };
+  const after = Number.isSafeInteger(retryAfterSeconds) && retryAfterSeconds >= 1 && retryAfterSeconds <= 3600 ? retryAfterSeconds : DEFAULT_RETRY_AFTER_SECONDS;
+  return { admit: false, error: { code: QUEUE_FULL, message: QUEUE_FULL_MESSAGE, data: { retryable: true, retryAfterSeconds: after } } };
+}
+
+/**
+ * The `statusMessage` of a waiting job (DEC-0104): `queued <position> of <length>`, 1 is next, 1 <= position <= length
+ * <= 999999; undefined for anything else.
+ * @param {unknown} position
+ * @param {unknown} length
+ * @returns {string | undefined}
+ */
+export const queueStatusMessage = (position, length) => (Number.isSafeInteger(position) && Number.isSafeInteger(length)
+  && position >= 1 && position <= length && length <= QUEUE_LENGTH_MAX ? `queued ${position} of ${length}` : undefined);
+
+/**
+ * A waiting job's place, read from its `statusMessage`, or undefined when it is not the queue's grammar.
+ * @param {unknown} statusMessage
+ * @returns {{ position: number, length: number } | undefined}
+ */
+export function readQueuePosition(statusMessage) {
+  const match = isString(statusMessage) ? QUEUED.exec(statusMessage) : null;
+  if (!match) return undefined;
+  const position = Number(match[1]);
+  const length = Number(match[2]);
+  return position >= 1 && position <= length ? { position, length } : undefined;
+}
+
+const finding = (code, instancePath, message) => ({ code, instancePath, message });
+
+/**
+ * FAC-SEM-131 on {queue, running, limits, started} (`started`: the id the node started, or null): it is nextQueuedJob's.
+ * @param {unknown} value
+ * @returns {Finding[]}
+ */
+export function jobQueueRules(value) {
+  const want = nextQueuedJob(member(value, 'queue'), member(value, 'running'), member(value, 'limits')) ?? null;
+  if ((member(value, 'started') ?? null) === want) return [];
+  return [finding('FAC-SEM-131', '/started', want === null ? 'nothing may start now' : `the job to start is ${show(want)}`)];
+}
+
+// --- The load report (DEC-0104) ---
+
+/**
+ * FAC-SEM-132 on a service-load/1 report: windows in order one `windowSeconds` apart, none after `generatedAt`, one
+ * row per context, p50 at most p95, a run time only where a job ended.
+ * @param {unknown} report
+ * @returns {Finding[]}
+ */
+export function loadReportRules(report) {
+  const findings = [];
+  const flag = (instancePath, message) => findings.push(finding('FAC-SEM-132', instancePath, message));
+  const seconds = member(report, 'windowSeconds');
+  const step = Number.isSafeInteger(seconds) ? seconds * 1000 : Number.NaN;
+  const generated = strictMs(member(report, 'generatedAt'));
+  let previous;
+  objects(member(report, 'windows')).forEach((window, index) => {
+    const start = strictMs(member(window, 'start'));
+    if (start > generated) flag(`/windows/${index}/start`, 'a window starts after the report was generated');
+    if (previous !== undefined && start - previous !== step) flag(`/windows/${index}/start`, 'windows are not in order one windowSeconds apart');
+    previous = start;
+    const seen = new Set();
+    objects(member(window, 'byContext')).forEach((row, at) => {
+      const path = `/windows/${index}/byContext/${at}`;
+      const context = member(row, 'context');
+      if (isString(context) && seen.has(context)) flag(`${path}/context`, `context ${show(context)} appears twice in one window`);
+      if (isString(context)) seen.add(context);
+      for (const name of ['waitMs', 'runMs']) {
+        const pct = member(row, name);
+        if (isObject(pct) && typeof member(pct, 'p50') === 'number' && typeof member(pct, 'p95') === 'number' && pct.p50 > pct.p95) flag(`${path}/${name}`, 'p50 is above p95');
+      }
+      if (isObject(member(row, 'runMs')) && member(row, 'completed') === 0 && member(row, 'failed') === 0) flag(`${path}/runMs`, 'a run time with no job ended in the window');
+    });
+  });
+  return findings;
+}
+
+/** JSON Schema's integer with its bounds, as ajv reads it: a number with no fraction, never a boolean. */
+function integer(value, low, high, at, errors) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value % 1 !== 0) errors.push(`${at} type`);
+  else if (value < low) errors.push(`${at} minimum`);
+  else if (high !== undefined && value > high) errors.push(`${at} maximum`);
+}
+
+function members(value, allowed, required, at, errors) {
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) errors.push(`${at}/${key} additionalProperties`);
+  for (const key of required) if (!Object.hasOwn(value, key)) errors.push(`${at || '/'} required ${key}`);
+}
+
+function timestamp(value, at, errors) {
+  if (!isString(value)) errors.push(`${at} type`);
+  else if (!dateTime(value)) errors.push(`${at} format`);
+}
+
+function percentiles(value, at, errors) {
+  if (!isObject(value)) {
+    errors.push(`${at} type`);
+    return;
+  }
+  members(value, ['p50', 'p95'], ['p50', 'p95'], at, errors);
+  for (const name of ['p50', 'p95']) if (Object.hasOwn(value, name)) integer(value[name], 0, undefined, `${at}/${name}`, errors);
+}
+
+function rowProblems(row, at, errors) {
+  if (!isObject(row)) {
+    errors.push(`${at} type`);
+    return;
+  }
+  members(row, ['context', ...ROW_COUNTS, 'waitMs', 'runMs'], ['context', ...ROW_COUNTS], at, errors);
+  if (Object.hasOwn(row, 'context') && !(isString(row.context) && CONTEXT.test(row.context))) errors.push(`${at}/context ${isString(row.context) ? 'pattern' : 'type'}`);
+  for (const name of ROW_COUNTS) if (Object.hasOwn(row, name)) integer(row[name], 0, undefined, `${at}/${name}`, errors);
+  for (const name of ['waitMs', 'runMs']) if (Object.hasOwn(row, name)) percentiles(row[name], `${at}/${name}`, errors);
+}
+
+/**
+ * service-load.schema.json: what makes `report` not a service-load/1 report, each as `<path> <keyword>`; empty for a
+ * valid one. Counts and durations only: a member the schema does not name (a caller, a job id) is refused.
+ * @param {unknown} report
+ * @returns {string[]}
+ */
+export function loadReportProblems(report) {
+  if (!isObject(report)) return ['/ type'];
+  const errors = [];
+  const names = ['type', 'generatedAt', 'windowSeconds', 'windows'];
+  members(report, names, names, '', errors);
+  if (Object.hasOwn(report, 'type') && report.type !== LOAD_REPORT_TYPE) errors.push('/type const');
+  if (Object.hasOwn(report, 'generatedAt')) timestamp(report.generatedAt, '/generatedAt', errors);
+  if (Object.hasOwn(report, 'windowSeconds')) integer(report.windowSeconds, 60, 86400, '/windowSeconds', errors);
+  if (Object.hasOwn(report, 'windows') && !Array.isArray(report.windows)) errors.push('/windows type');
+  else if (Object.hasOwn(report, 'windows')) {
+    if (report.windows.length > 168) errors.push('/windows maxItems');
+    report.windows.forEach((window, index) => {
+      const at = `/windows/${index}`;
+      if (!isObject(window)) {
+        errors.push(`${at} type`);
+        return;
+      }
+      members(window, ['start', 'byContext'], ['start', 'byContext'], at, errors);
+      if (Object.hasOwn(window, 'start')) timestamp(window.start, `${at}/start`, errors);
+      if (Object.hasOwn(window, 'byContext') && !Array.isArray(window.byContext)) errors.push(`${at}/byContext type`);
+      else if (Object.hasOwn(window, 'byContext')) {
+        if (window.byContext.length > 64) errors.push(`${at}/byContext maxItems`);
+        window.byContext.forEach((row, rowIndex) => rowProblems(row, `${at}/byContext/${rowIndex}`, errors));
+      }
+    });
+  }
+  return errors;
+}
+
+/** service-load-extension.schema.json, each problem as `<path> <keyword>`; empty for a valid declaration. */
+function declarationProblems(value) {
+  if (!isObject(value)) return ['/ type'];
+  const errors = [];
+  members(value, ['path', 'windowSeconds', 'limits'], ['path', 'windowSeconds', 'limits'], '', errors);
+  if (Object.hasOwn(value, 'path')) {
+    if (!isString(value.path)) errors.push('/path type');
+    else {
+      if (codePoints(value.path) > 256) errors.push('/path maxLength'); // the originPath's own 2048 is wider
+      if (!ORIGIN_PATH.test(value.path)) errors.push('/path pattern');
+    }
+  }
+  if (Object.hasOwn(value, 'windowSeconds')) integer(value.windowSeconds, 60, 86400, '/windowSeconds', errors);
+  if (Object.hasOwn(value, 'limits')) {
+    const { limits } = value;
+    if (!isObject(limits)) errors.push('/limits type');
+    else {
+      const names = LIMITS.map(([name]) => name);
+      members(limits, names, names, '/limits', errors);
+      for (const [name, low, high] of LIMITS) if (Object.hasOwn(limits, name)) integer(limits[name], low, high, `/limits/${name}`, errors);
+    }
+  }
+  return errors;
+}
+
+/**
+ * The load declaration as a reader reads it (DEC-0104): `declared` when the extension key is present, `valid` when its
+ * value is the schema's, `load` the declaration when valid (else null) and `errors` its problems. A reader treats an
+ * invalid value as not declared and reports it (FAC-SEM-133).
+ * @param {unknown} wellKnown
+ * @returns {LoadView}
+ */
+export function loadView(wellKnown) {
+  const extensions = member(wellKnown, 'extensions');
+  if (!isObject(extensions) || !Object.hasOwn(extensions, LOAD_EXTENSION_KEY)) return { declared: false, valid: false, load: null, errors: [] };
+  const value = extensions[LOAD_EXTENSION_KEY];
+  const errors = declarationProblems(value);
+  return { declared: true, valid: errors.length === 0, load: errors.length === 0 ? value : null, errors };
+}
+
+/**
+ * FAC-SEM-133 on a well-known document: a value under the load extension key is valid against
+ * service-load-extension.schema.json; one finding at the key otherwise.
+ * @param {unknown} wellKnown
+ * @returns {Finding[]}
+ */
+export function loadExtensionRules(wellKnown) {
+  const view = loadView(wellKnown);
+  if (!view.declared || view.valid) return [];
+  return [finding('FAC-SEM-133', KEY_PATH, `the load declaration is invalid (${view.errors.join('; ')}); a reader treats it as not declared and reports it (DEC-0104)`)];
+}
+
+/**
+ * The `extensions` entry a service declares (DEC-0104): where it serves its service-load/1 report (an origin path,
+ * served under the descriptor token like the usage report), the report's window and the queue's limits per
+ * (agentRef, context). Throws ServiceError on a declaration a reader would treat as not declared.
+ * @param {{ path: string, windowSeconds: number, limits: QueueLimits }} declaration
+ * @returns {Record<string, { path: string, windowSeconds: number, limits: QueueLimits }>}
+ */
+export function loadExtension({ path, windowSeconds, limits } = {}) {
+  const value = { path, windowSeconds, limits: isObject(limits) ? { ...limits } : limits };
+  const problems = declarationProblems(value);
+  if (problems.length) throw new ServiceError(`Load declaration: ${problems.join('; ')}.`);
+  return { [LOAD_EXTENSION_KEY]: value };
+}

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

@@ -45,7 +45,7 @@ import http from 'node:http';
 import net from 'node:net';
 import os from 'node:os';
 
-export const PEER_OWNER_VERSION = '1.1.0+kit.3'; // the Python twin's, Observatory's 1.1.0 with the kit's differences
+export const PEER_OWNER_VERSION = '1.1.0+kit.4'; // the Python twin's, Observatory's 1.1.0 with the kit's differences
 export const THIS_ACCOUNT = 'this-account';
 export const ANOTHER_ACCOUNT = 'another-account';
 export const SYSTEM = 'system';
@@ -154,6 +154,10 @@ export function parseNetstat(text) {
   const at = names.indexOf('process:pid');
   const leading = at - names.slice(0, at).filter((w) => w === 'Address').length;
   const trailing = names.length - at - 1;
+  // The caller's own connection is in any table it can see: a header and no tcp row is the restricted table (FAA-273).
+  if (!lines.slice(header + 1).some((line) => (line.split(/\s+/).filter(Boolean)[0] ?? '').startsWith('tcp'))) {
+    throw new TableUnreadable(`${TABLE_RESTRICTED}: netstat printed only its header to this process`);
+  }
   const rows = [];
   for (const line of lines.slice(header + 1)) {
     const tok = line.split(/\s+/).filter(Boolean);

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

@@ -43,6 +43,10 @@ export {
 } from './fabric-protocols.mjs';
 export { ACTIONS_EXTENSION_KEY, actionDecision, actionRules, actionsExtension, actionsExtensionRules, actionsView, decisionShape } from './fabric-actions.mjs';
 export { CONNECTIONS_EXTENSION_KEY, connectionsExtension, connectionsRules, connectionsView } from './fabric-connections.mjs';
+export { // the call queue and the load report (DEC-0104, FAA-289)
+  DEFAULT_RETRY_AFTER_SECONDS, LOAD_EXTENSION_KEY, LOAD_REPORT_TYPE, QUEUE_FULL_MESSAGE, QUEUE_LENGTH_MAX, admitJob, jobCallerKey, jobQueueRules,
+  loadExtension, loadExtensionRules, loadReportProblems, loadReportRules, loadView, nextQueuedJob, queueStatusMessage, readQueuePosition,
+} from './fabric-load.mjs';
 export {
   EXIT_ALREADY_RUNNING,
   LOCK_WAIT_SUPERVISED_SECONDS,
@@ -118,7 +122,9 @@ export {
   fabricButtonPresence,
   placementOf,
   remoteOriginProblems,
+  portListenerRefusal,
   portOf,
+  portOwner,
   NO_SOURCE_REPOSITORY,
   namesRepository,
   sourceRefusal,

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

@@ -115,12 +115,33 @@ export function systemdUnit(unit, programArguments, { workingDirectory, environm
 
 const systemdDir = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'systemd', 'user');
 
+// FAA-253: the well-known answer at `origin`, polled until this OS account's listener answers as serviceId.instance, as
+// launchdInstall does (the pinned contract's Install row: every supervisor polls). Another account's listener, or one
+// whose owner cannot be told, is never a successful install (DEC-0154 HA-2).
+async function pollInstalled(origin, { serviceId, instance = 'default', timeout = 40, fetchWellKnown = wellKnownOf, sleep = pause, clock = Date.now } = {}) {
+  if (!serviceId) throw new ServiceError(`polling the install at ${origin} needs the serviceId it must answer as`);
+  const deadline = clock() + Math.max(0, timeout) * 1000;
+  let foreign = null;
+  for (;;) {
+    const doc = await fetchWellKnown(origin);
+    foreign = doc instanceof ForeignUserAnswer ? doc.reason : null;
+    if (!foreign && doc?.service?.id === serviceId && doc?.service?.instance === instance) return doc;
+    if (clock() >= deadline) break;
+    await sleep(500);
+  }
+  if (foreign) throw new ServiceError(`${origin} is not this service's: ${foreign} (DEC-0154 HA-2); the port is another OS account's or its owner cannot be told.`);
+  throw new ServiceError(`${origin} did not answer as ${serviceId}.${instance} within ${timeout} s; read its log.`);
+}
+
 /**
  * Write the user unit, enable it so it comes back after a login, and (re)start it so the new unit is what runs.
  * The operator's intent wins (LC-14): a unit already installed and disabled stays off — the file is rewritten, so the
- * new version is what starts once they enable it — unless `forceEnable` (the operator asked for it on).
+ * new version is what starts once they enable it — unless `forceEnable` (the operator asked for it on). With `origin`
+ * (and `serviceId`) it then polls the well-known answer as launchdInstall does and resolves to the unit file once this
+ * account's listener answers (FAA-253); without `origin` it stays synchronous.
  */
-export function systemdInstall(unit, text, { unitDir = systemdDir(), run = defaultRun, platform = process.platform, forceEnable = false } = {}) {
+export function systemdInstall(unit, text, { unitDir = systemdDir(), run = defaultRun, platform = process.platform, forceEnable = false,
+  origin, serviceId, instance, timeout, fetchWellKnown, sleep, clock } = {}) {
   if (platform !== 'linux') throw new ServiceError('systemd is the supervisor on Linux only.');
   if (!UNIT.test(unit)) throw new ServiceError(`unit must match ${UNIT.source}`);
   fs.mkdirSync(unitDir, { recursive: true });
@@ -128,10 +149,14 @@ export function systemdInstall(unit, text, { unitDir = systemdDir(), run = defau
   const state = fs.existsSync(file) ? String(run(['systemctl', '--user', 'is-enabled', unit])?.stdout ?? '').trim() : '';
   atomicWrite(file, text, 0o644);
   checkRun(run(['systemctl', '--user', 'daemon-reload']), 'systemctl --user daemon-reload');
-  if (state === 'disabled' && !forceEnable) return file;
-  checkRun(run(['systemctl', '--user', 'enable', unit]), 'systemctl --user enable');
-  checkRun(run(['systemctl', '--user', 'restart', unit]), 'systemctl --user restart');
-  return file;
+  const started = !(state === 'disabled' && !forceEnable);
+  if (started) {
+    checkRun(run(['systemctl', '--user', 'enable', unit]), 'systemctl --user enable');
+    checkRun(run(['systemctl', '--user', 'restart', unit]), 'systemctl --user restart');
+  }
+  if (origin === undefined) return file;
+  // FAA-253: with an origin it resolves once this account's listener answers; a unit kept off is not polled.
+  return started ? pollInstalled(origin, { serviceId, instance, timeout, fetchWellKnown, sleep, clock }).then(() => file) : Promise.resolve(file);
 }
 
 /** Stop it and keep it off across logins (`disable --now`), then remove the unit. */
@@ -203,9 +228,12 @@ const TASK_DISABLED = /<Settings>(?:(?!<\/Settings>)[\s\S])*<Enabled>false<\/Ena
 
 /**
  * Create (or replace) the task from its XML without administrator rights, then (re)start it so the new definition
- * is what runs. A task already installed and disabled stays off (LC-14) unless `forceEnable`.
+ * is what runs. A task already installed and disabled stays off (LC-14) unless `forceEnable`. With `origin` (and
+ * `serviceId`) it then polls the well-known answer as launchdInstall does and resolves to it (FAA-253); a task kept off
+ * resolves to undefined, unpolled. Without `origin` it stays synchronous.
  */
-export function taskInstall(task, xmlText, { run = defaultRun, platform = process.platform, forceEnable = false } = {}) {
+export function taskInstall(task, xmlText, { run = defaultRun, platform = process.platform, forceEnable = false,
+  origin, serviceId, instance, timeout, fetchWellKnown, sleep, clock } = {}) {
   if (platform !== 'win32') throw new ServiceError('Task Scheduler is the supervisor on Windows only.');
   const query = run(['schtasks', '/Query', '/TN', task, '/XML']);
   const existed = query?.status === 0;
@@ -221,10 +249,11 @@ export function taskInstall(task, xmlText, { run = defaultRun, platform = proces
   }
   if (keepOff) {
     checkRun(run(['schtasks', '/Change', '/TN', task, '/DISABLE']), 'schtasks /Change /DISABLE');
-    return;
+    return origin === undefined ? undefined : Promise.resolve(undefined);
   }
   if (existed) run(['schtasks', '/End', '/TN', task]);
   checkRun(run(['schtasks', '/Run', '/TN', task]), 'schtasks /Run');
+  return origin === undefined ? undefined : pollInstalled(origin, { serviceId, instance, timeout, fetchWellKnown, sleep, clock });
 }
 
 /** End the running task, then delete it. */

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

@@ -70,7 +70,14 @@ function byProject(receipts, first, last) {
   const close = ({ cost, ...rest }) => ({ ...rest, costUsd: rest.calls && rest.unpricedCalls === rest.calls ? null : Math.round(cost * 1e6) / 1e6 });
   return [...projects.keys()].sort().map((key) => {
     const { runs, ...row } = projects.get(key);
-    const taskRuns = [...runs.keys()].sort().map((id) => close(runs.get(id)));
+    // A run's cost rounds as the project's does but never above its exact cost: each run and the project round apart,
+    // so many runs rounding up summed past the project and failed FAC-SEM-025 (board request f5753c5a).
+    const closeRun = (run) => {
+      const out = close(run);
+      if (out.costUsd !== null && out.costUsd > run.cost) out.costUsd = Math.round((out.costUsd - 0.000001) * 1e6) / 1e6;
+      return out;
+    };
+    const taskRuns = [...runs.keys()].sort().map((id) => closeRun(runs.get(id)));
     return { ...close(row), ...(taskRuns.length ? { taskRuns } : {}) };
   });
 }

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

@@ -168,6 +168,7 @@ class Responder(SlotKeeper):
         self.state = "idle"
         self.wait_until = 0.0
         self.stopping = False
+        self.shutting_down, self.draining = threading.Event(), None  # shutdown began; it found work to drain (FAA-186)
         self.claim_keys: Dict[str, str] = {}
         self._probing: set = set()  # moved slots whose move-back claim lost its answer: asked again under the same key
         self._said: Dict[str, str] = {}
@@ -982,8 +983,8 @@ class Responder(SlotKeeper):
     def shutdown(self, drain: float = DRAIN_SECONDS) -> None:
         """Stop claiming, give running work up to `drain` seconds to finish and be completed, then leave the session
         (its DELETE releases the slots). What is still open stays in the checkpoint for the next start."""
-        self.stopping = True
-        work = self.current
+        self.stopping, work = True, self.current
+        self.draining = work is not None; self.shutting_down.set()  # noqa: E702 - published before it waits (FAA-186)
         if work is not None and not work.done.wait(drain):
             work.ctx.stopped.set()
         if work is not None and work.done.is_set() and self.session is not None:

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

@@ -247,3 +247,5 @@ class SlotKeeper:
             self._retry_later(capability, entries or [], exc)
             if exc.code in SESSION_CODES:
                 raise
+            if exc.code == "idempotency_window_expired":
+                self._status()  # the epoch moved: read it before the retry, which no held slot would do (FAA-186)

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

@@ -4,8 +4,10 @@
 `degraded[]`. Part of the service kit (FAA-62, layer L3). Standard library only."""
 from __future__ import annotations
 
+import bisect
 import ipaddress
 import re
+import unicodedata
 import urllib.parse
 from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence
 
@@ -173,6 +175,92 @@ _FORBIDDEN_HOST = set("\x00\t\n\r #/:<>?@[\\]^|")
 _FORBIDDEN_DOMAIN = _FORBIDDEN_HOST | set(chr(c) for c in range(0x20)) | {"%", "\x7f"}
 
 
+# FAA-98: UTS46 narrowed, not ported. A non-ASCII host is refused only where every Node from 20 to 26 refuses it, so
+# the doubt stays on the closed side (its URL's credentials are read). The two tables are measured by
+# test/fixtures/idna/make_idna_tables.mjs (idna-tables.json, held equal by test_the_idna_tables_are_the_measured_ones):
+# code points refused in every context, and code points removed between letters. The contextual rules read Unicode 3.2
+# classes (`unicodedata.ucd_3_2_0`) and skip what that Unicode does not know, since Node's own UTS46 data lags its
+# Unicode: an Arabic letter of Unicode 14 is no right-to-left letter to it.
+_IDNA_DISALLOWED = (
+    (0x80, 0xa0), (0xa8, 0xa8), (0xaf, 0xaf), (0xb4, 0xb4), (0xb8, 0xb8), (0x2d8, 0x2dd), (0x37a, 0x37a),
+    (0x384, 0x385), (0x600, 0x605), (0x61c, 0x61c), (0x6dd, 0x6dd), (0x70f, 0x70f), (0x890, 0x891), (0x8e2, 0x8e2),
+    (0x1680, 0x1680), (0x1fbd, 0x1fbd), (0x1fbf, 0x1fc1), (0x1fcd, 0x1fcf), (0x1fdd, 0x1fdf), (0x1fed, 0x1fee),
+    (0x1ffd, 0x1ffe), (0x2000, 0x200a), (0x200e, 0x200f), (0x2017, 0x2017), (0x2024, 0x2026), (0x2028, 0x202f),
+    (0x203e, 0x203e), (0x2047, 0x2049), (0x205f, 0x205f), (0x2066, 0x2069), (0x2100, 0x2101), (0x2105, 0x2106),
+    (0x2488, 0x249b), (0x2a74, 0x2a74), (0x2ff0, 0x3000), (0x309b, 0x309c), (0x31ef, 0x31ef), (0x33c2, 0x33c2),
+    (0x33c7, 0x33c7), (0x33d8, 0x33d8), (0xe000, 0xf8ff), (0xfc5e, 0xfc63), (0xfdfa, 0xfdfb), (0xfe12, 0xfe13),
+    (0xfe16, 0xfe16), (0xfe19, 0xfe19), (0xfe30, 0xfe30), (0xfe47, 0xfe4c), (0xfe52, 0xfe52), (0xfe55, 0xfe56),
+    (0xfe5f, 0xfe5f), (0xfe64, 0xfe65), (0xfe68, 0xfe68), (0xfe6a, 0xfe6b), (0xfe70, 0xfe70), (0xfe72, 0xfe72),
+    (0xfe74, 0xfe74), (0xfe76, 0xfe76), (0xfe78, 0xfe78), (0xfe7a, 0xfe7a), (0xfe7c, 0xfe7c), (0xfe7e, 0xfe7e),
+    (0xff03, 0xff03), (0xff05, 0xff05), (0xff0f, 0xff0f), (0xff1a, 0xff1a), (0xff1c, 0xff1c), (0xff1e, 0xff20),
+    (0xff3b, 0xff3e), (0xff5c, 0xff5c), (0xffe3, 0xffe3), (0xfff9, 0xfffd), (0x110bd, 0x110bd), (0x110cd, 0x110cd),
+    (0x13430, 0x1343f), (0x1f100, 0x1f100), (0xe0001, 0xe0001), (0xe0020, 0xe007f), (0xf0000, 0xffffd),
+    (0x100000, 0x10fffd),
+)
+_IDNA_IGNORED = (
+    (0xad, 0xad), (0x34f, 0x34f), (0x180b, 0x180d), (0x180f, 0x180f), (0x200b, 0x200b), (0x2060, 0x2060),
+    (0x2064, 0x2064), (0xfe00, 0xfe0f), (0xfeff, 0xfeff), (0x1bca0, 0x1bca3), (0xe0100, 0xe01ef),
+)
+_IDNA_DOTS = re.compile("[.\u3002\uff0e\uff61]")
+_U32 = unicodedata.ucd_3_2_0
+_RTL_OK = {"R", "AL", "AN", "EN", "ES", "CS", "ET", "ON", "BN", "NSM"}
+_JOINERS = "\u200c\u200d"
+
+
+def _in_ranges(ranges: Sequence[tuple], cp: int) -> bool:
+    i = bisect.bisect_right(ranges, (cp, 0x10ffff)) - 1
+    return i >= 0 and ranges[i][0] <= cp <= ranges[i][1]
+
+
+def _known(c: str) -> bool:
+    return _U32.category(c) != "Cn" and unicodedata.category(c) != "Cn"
+
+
+def _joiner_refused(label: str, i: int) -> bool:
+    """CheckJoiners as Node 20 to 26 all read it: they find a joining context, or a virama, anywhere in the label
+    (`\u0628a\u200c\u0627` and `\u0628\u200c\u0627\u200d` parse), so only a joiner with nothing but ASCII beside it
+    in its label has none for certain."""
+    return all(c.isascii() for j, c in enumerate(label) if j != i)
+
+
+def _bidi_refused(label: str) -> bool:
+    """RFC 5893 as Node 20 to 26 all read it: only a label holding R, AL or AN is judged, and its first code point is
+    not (Node 26 alone refuses a label opening with a digit or a hyphen)."""
+    if not label or not all(_known(c) for c in label) or any(c in _JOINERS for c in label):
+        return False  # Node 20 to 26 pass a label holding a joiner over (`\u05d0a\u094d\u200d` parses)
+    k = [_U32.bidirectional(c) for c in label]
+    if not any(x in ("R", "AL", "AN") for x in k):
+        return False
+    body = list(k)
+    while body and body[-1] == "NSM":
+        body.pop()
+    if not body or body[-1] not in ("R", "AL", "EN", "AN"):
+        return True
+    return k[0] in ("R", "AL") and (any(x not in _RTL_OK for x in k) or ("EN" in k and "AN" in k))
+
+
+def _idna_host(host: str) -> Optional[str]:
+    """None where WHATWG's domain-to-ASCII refuses a non-ASCII host for certain; else the host as UTS46 maps it, read
+    as NFKC with case folding (exact enough for the ASCII rules that follow, which read digits and dots)."""
+    if any(_in_ranges(_IDNA_DISALLOWED, ord(c)) for c in host):
+        return None
+    kept = "".join(c for c in host if not _in_ranges(_IDNA_IGNORED, ord(c)))
+    if kept == "":
+        return None  # nothing left: an empty host
+    if not all(_known(c) for c in kept):
+        return host  # a code point this Python's Unicode does not know: the contextual rules are not read
+    mapped = unicodedata.normalize("NFC", unicodedata.normalize("NFKC", unicodedata.normalize("NFKC", kept).casefold()))
+    for label in _IDNA_DOTS.split(mapped):
+        first = label[:1]
+        if first and first not in "\u17b4\u17b5" and _U32.category(first)[0] == "M" and unicodedata.category(first)[0] == "M":
+            return None  # a label opening with a mark (U+17B4 and U+17B5 are ignored by the newer Nodes)
+        if any(c in _JOINERS and _joiner_refused(label, i) for i, c in enumerate(label)):
+            return None
+        if _bidi_refused(label):
+            return None
+    return _IDNA_DOTS.sub(".", mapped)
+
+
 def _ipv4_number(part: str) -> Optional[int]:
     if part == "":
         return None  # an empty part fails WHATWG's IPv4 parser (`1..2`); `0x` alone is 0
@@ -198,10 +286,16 @@ def _domain_ok(host: str) -> bool:
             return False
     if any(c in _FORBIDDEN_DOMAIN for c in host):
         return False
-    # A non-ASCII host goes through UTS46 in WHATWG; this module does not port it. When unsure, the host is taken as
-    # valid, so its URL's credentials are read: the doubt then hides a list rather than publish one (round-2 reading).
+    # A non-ASCII host goes through UTS46 in WHATWG; this module reads it narrowly (_idna_host, FAA-98). When unsure,
+    # the host is taken as valid, so its URL's credentials are read: the doubt then hides a list rather than publish one
+    # (round-2 reading). A host UTS46 maps to ASCII is read by the ASCII rules below (`１２７.０.０.１` is an address).
     if any(ord(c) > 0x7f for c in host):
-        return True
+        mapped = _idna_host(host)
+        if mapped is None:
+            return False
+        if not mapped.isascii() or any(c in _FORBIDDEN_DOMAIN for c in mapped):
+            return True
+        host = mapped
     labels = host.split(".")
     if labels and labels[-1] == "" and len(labels) > 1:
         labels = labels[:-1]