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

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

@@ -12,9 +12,11 @@
 
 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 { effectClosure } from './fabric-mandate.mjs'; // defined once beside the mandate that reads it too (DEC-0125)
 
 export const REFUSAL_CODES = Object.freeze([
@@ -411,8 +413,34 @@ export const actionDigest = (action) => `sha256:${crypto.createHash('sha256').up
 
 const loopback = (host) => host === 'localhost' || (net.isIP(host.replace(/^\[|\]$/g, '')) !== 0 && (/^127\./.test(host) || host.replace(/^\[|\]$/g, '') === '::1'));
 
+const KEY_SET_MAX = 65536;
+const KEY_SET_AGENT = new CheckedAgent({ keepAlive: false });
+
+// Plain http, which a key set source allows on loopback only: through a CheckedAgent, so the listener's owner is told
+// before a byte is written and keys another OS account's process serves are never read (DEC-0154 HA-2, FAA-255).
+function loopbackKeySet(source, agent) {
+  return new Promise((resolve, reject) => {
+    const request = http.get(source.split('#')[0], { agent, headers: { Accept: 'application/json' }, timeout: 5000 }, (response) => {
+      if (response.statusCode < 200 || response.statusCode > 299) { response.resume(); reject(new Error(`HTTP ${response.statusCode}`)); return; }
+      let text = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => { text += chunk; if (text.length > KEY_SET_MAX) { request.destroy(); reject(new Error('the key set is too large')); } });
+      response.on('end', () => { try { resolve(JSON.parse(text)); } catch (e) { reject(e); } });
+      response.on('error', reject);
+    });
+    request.on('timeout', () => request.destroy(new Error('the key set did not arrive within 5 s')));
+    request.on('error', (e) => reject(e instanceof ListenerRefused ? new Error(`foreign-user: ${e.message}`) : e));
+  });
+}
+
+/** Read a key set source: an https URL (fetch, no redirect), a loopback http URL (checked listener) or a file. */
+export async function fetchKeySet(source, { agent = KEY_SET_AGENT } = {}) {
+  if (/^http:\/\//.test(source)) return loopbackKeySet(source, agent);
+  return defaultFetch(source);
+}
+
 async function defaultFetch(source) {
-  if (/^https?:\/\//.test(source)) {
+  if (/^https:\/\//.test(source)) {
     const response = await fetch(source, { headers: { Accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(5000) });
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
     if (Number(response.headers.get('content-length') ?? 0) > 65536) throw new Error('the key set is too large');
@@ -428,7 +456,7 @@ async function defaultFetch(source) {
  * `await get(kid)` answers null when no set younger than 10 minutes can be had (issuer-unavailable).
  */
 export class JwksCache {
-  constructor(source, { fetch: fetcher = defaultFetch, clock = () => Date.now() / 1000 } = {}) {
+  constructor(source, { fetch: fetcher = fetchKeySet, clock = () => Date.now() / 1000 } = {}) {
     if (typeof source !== 'string' || !source) throw new Error('the key set needs a source');
     if (/^https?:\/\//.test(source)) {
       const url = new URL(source);

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

@@ -1,10 +1,12 @@
 // 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';
 import fs from 'node:fs';
 import path from 'node:path';
 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 { ID, INSTANCE, LOCAL_PATH, PRIMARY_CAPABILITY, PROTOCOL, ServiceError, TASK, UNIT, expand } from './fabric-base.mjs';
 import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
+import { ANOTHER_ACCOUNT } from './fabric-peer-owner.mjs'; // L0: who listens on a port (DEC-0154 HA-2, FAA-225)
 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';
@@ -15,7 +17,7 @@ import { ROUTES } from './fabric-usage.mjs';
 // document's `extensions`. The kit is assets/dashboard-kit; its version is the one in kit.json.
 export const DASHBOARD_EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1';
 
-export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.5';
+export const DASHBOARD_KIT = 'fabric-dashboard-kit@1.1.6';
 
 export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 
@@ -313,9 +315,43 @@ export function sourceRefusal(d, dir = servicesDir()) {
   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()) {
+// The child that answers portOwner: a plain listen on 127.0.0.1:<port> that succeeds means nothing holds it (the table
+// is not read); one that fails asks fabric-peer-owner's listener. A child, because writeDescriptor is synchronous.
+const PORT_OWNER_CHILD = `
+import net from 'node:net';
+const [port, url] = process.argv.slice(1);
+const say = (value) => process.stdout.write(JSON.stringify(value));
+const server = net.createServer();
+server.once('error', async () => {
+  try { const { listener } = await import(url); const who = await listener(Number(port)); say([who.kind, Number.isInteger(who.uid) ? who.uid : null]); }
+  catch { say(['unknown', null]); }
+});
+server.listen({ port: Number(port), host: '127.0.0.1', exclusive: true }, () => server.close(() => say(null)));
+`;
+
+/** Who listens on 127.0.0.1:<port> now, as [kind, uid] from the kit's fabric-peer-owner, or null when nothing holds it
+ * (FAA-225, DEC-0154 HA-2). */
+export function portOwner(port) {
+  const done = spawnSync(process.execPath, ['--input-type=module', '-e', PORT_OWNER_CHILD, String(port),
+    new URL('./fabric-peer-owner.mjs', import.meta.url).href], { encoding: 'utf8', timeout: 10000 });
+  try { return JSON.parse(done.stdout); } catch { return ['unknown', null]; }
+}
+
+/** Why an install may not take `port`: another OS account listens on it (FAA-225). This account, the system (launchd
+ * holds a socket-activated job's socket), nobody and an unreadable table pass. The recorded port per account and its
+ * claim file wait on contract DEC-0160. */
+export function portListenerRefusal(port, reader = portOwner) {
+  const found = reader(port);
+  if (!Array.isArray(found) || found[0] !== ANOTHER_ACCOUNT) return null;
+  const uid = Number.isInteger(found[1]) ? ` (uid ${found[1]})` : '';
+  return `Port ${port} is listened on by another OS account${uid}: choose a port no other account holds (DEC-0154, FAA-225).`;
+}
+
+/** Installer-only. Refuses a port or id.instance another descriptor claims (a port is a claim), and a port another OS
+ * 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 } = {}) {
   const problems = validateDescriptor(d);
   if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
   const me = `${d.id}.${d.instance}`;
@@ -334,6 +370,8 @@ export function writeDescriptor(d, dir = servicesDir()) {
     try { otherPort = portOf(String(other.origin ?? '')); } catch { continue; }
     if (otherPort === port) throw new ServiceError(`Port ${port} is already claimed by ${key} (${file}).`);
   }
+  const held = port === null ? null : portListenerRefusal(port, reader);
+  if (held) throw new ServiceError(held);
   ensurePrivateDir(dir);
   const target = descriptorPath(d.id, d.instance, dir);
   atomicWrite(target, `${JSON.stringify(d, null, 2)}\n`, 0o600);
@@ -418,6 +456,9 @@ export function configurationProblems(doc) {
 // `a2a` (DEC-0122) is surfaces.a2a, where the service serves its public Agent Card (a2aSurface builds one); passed here
 // or in `surfaces`, never both, and refused when it is not the schema's. A reader pinned before DEC-0122 refuses the
 // member, so a service carries it only once its readers are pinned at or after it.
+// FAA-244: DEC-0140 PR-1 reserves the primary responder's capability; a service never publishes it.
+const reserved = (where) => `${where}: ${PRIMARY_CAPABILITY} is reserved for a Project's primary responder, a session (DEC-0140 PR-1); a service never serves it as a tool or declares it.`;
+
 export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration, protocols, actions, a2a }) {
   if (!STATUSES.includes(status)) throw new ServiceError(`status must be one of ${STATUSES.join(', ')}.`);
   if (!surfaces?.events) throw new ServiceError('surfaces.events is required.');
@@ -430,6 +471,7 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
     const problems = a2aSurfaceProblems(surfaces.a2a);
     if (problems.length) throw new ServiceError(`surfaces.a2a: ${problems.join('; ')}.`);
   }
+  if (Array.isArray(surfaces.mcp?.capabilities) && surfaces.mcp.capabilities.includes(PRIMARY_CAPABILITY)) throw new ServiceError(reserved('surfaces.mcp.capabilities'));
   if (!(build?.commit || build?.digest)) throw new ServiceError('build needs a commit or a digest.');
   const doc = {
     protocol: PROTOCOL,
@@ -461,6 +503,7 @@ export function buildWellKnown({ id, instance, name, version, build, startedAt,
       // compared with the capabilities this document's MCP surface lists.
       const findings = actionsExtensionRules({ extensions: { [ACTIONS_EXTENSION_KEY]: extensions[ACTIONS_EXTENSION_KEY] }, surfaces });
       if (findings.length) throw new ServiceError(`Actions declaration: ${findings.map((f) => f.message).join('; ')}.`);
+      if ((extensions[ACTIONS_EXTENSION_KEY]?.actions ?? []).some((a) => a?.tool === PRIMARY_CAPABILITY)) throw new ServiceError(reserved("an action's tool"));
     }
     doc.extensions = { ...extensions };
   }

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

@@ -16,9 +16,11 @@
 // The transport is injected in tests: async ({ method, url, headers, body, timeoutS, maxBytes }) =>
 // { status, headers, body: Uint8Array }, throwing on a connection error (a `TimeoutError` name is a timeout) or an
 // HttpError. Node 20 or newer, no dependencies. Part of the service kit (FAA-65, layer L4).
+//
+// Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 import http from 'node:http';
-import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
 
 export const RETRY_STATUSES = Object.freeze([408, 425, 429, 500, 502, 503, 504]);
 export const IDEMPOTENT_METHODS = Object.freeze(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
@@ -27,7 +29,7 @@ const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 
 export class HttpError extends Error {
   constructor(message, { status = null, url = '', attempts = 0, retryAfterS = null, body = new Uint8Array(0),
-    kind = 'http' } = {}) {
+    kind = 'http', reason = null } = {}) {
     super(message);
     this.name = 'HttpError';
     this.status = status;
@@ -36,6 +38,8 @@ export class HttpError extends Error {
     this.retryAfterS = retryAfterS;
     this.body = body.slice(0, 2048);
     this.kind = kind; // http, connection, timeout, too-large, refused, foreign-user
+    // For foreign-user, why (FAA-272): table-restricted (never clears), the owner's kind, or the check's reason.
+    this.reason = reason;
   }
 }
 
@@ -184,7 +188,9 @@ export function checkedLoopbackTransport({ method, url, headers, body, timeoutS,
     req.on('error', (err) => {
       clearTimeout(timer);
       if (err instanceof ListenerRefused) {
-        reject(new HttpError(`${method} ${redactUrl(url)}: foreign-user: ${err.message}`, { url: redactUrl(url), kind: 'foreign-user' }));
+        const why = String(err.owner?.reason ?? err.owner?.kind ?? err.code ?? 'unknown');
+        const reason = why.startsWith(TABLE_RESTRICTED) ? TABLE_RESTRICTED : why.split(':', 1)[0];
+        reject(new HttpError(`${method} ${redactUrl(url)}: foreign-user: ${err.message}`, { url: redactUrl(url), kind: 'foreign-user', reason }));
       } else reject(err);
     });
     if (body) req.write(body);

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

@@ -27,7 +27,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { atomicWrite, ensurePrivateDir, readToken } from './fabric-service.mjs';
 import { hubKeyCertified } from './fabric-estate.mjs';
-import { CheckedAgent, ListenerRefused } from './fabric-peer-owner.mjs';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
 
 // DEC-0154 HA-2: every connection to the door is checked before a byte goes out; kept alive, so a busy session reads the
 // socket table once per connection, not once per call. A free socket is closed after 2 s idle, before a server's own
@@ -53,6 +53,20 @@ export class HubError extends Error {
   }
 }
 
+/**
+ * The HubError for a hub port the peer-owner check refused (DEC-0154 HA-2): code `foreign-user`, the pinned contract's
+ * state name, with the owner's reason in the sentence and in `data.reason` (FAA-272): `table-restricted` when this
+ * runtime's socket table hides other processes' sockets, which never clears, so it is not retryable; otherwise the
+ * owner's kind or the check's reason (`another-account`, `no-row`), retryable as before.
+ */
+export function listenerRefusal(e) {
+  const kind = e?.owner?.kind ?? null;
+  const why = String(e?.owner?.reason ?? kind ?? e?.code ?? 'unknown');
+  const reason = why.startsWith(TABLE_RESTRICTED) ? TABLE_RESTRICTED : why.split(':', 1)[0];
+  const shown = kind && e?.owner?.reason ? `${kind}: ${e.owner.reason}` : String(kind ?? why);
+  return new HubError('foreign-user', `The hub's port is not held by this OS account's process (${shown}); nothing was sent.`, reason !== TABLE_RESTRICTED, { reason });
+}
+
 /** Fabric's registry root, where hub.json lives (Fabric agentRegistry.ts#registryDirs). */
 export function fabricRoot(platform = process.platform, env = process.env) {
   const home = env.HOME || env.USERPROFILE || os.homedir();
@@ -202,7 +216,7 @@ export function postMcp(origin, body, bearer, { session, timeout = 15000, method
     });
     req.on('timeout', () => req.destroy(new Error('timeout')));
     req.on('error', (e) => reject(e instanceof ListenerRefused
-      ? new HubError('foreign-user', `The hub's port is not held by this OS account's process (${e.owner?.kind ?? e.code}); nothing was sent.`, true)
+      ? listenerRefusal(e)
       : new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));
     if (payload) req.write(payload);
     req.end();

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 };
+}