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

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-package.mjs

@@ -509,9 +509,71 @@ const FOLDER_MESSAGES = {
   'provider-manifest': 'provider-manifest: the provider manifest must be a JSON object, and when it carries costPresets fabric.package.json must carry the same costPresets (copy them; pack does not)',
 };
 
+/**
+ * The agent's source manifest (contract DEC-0149, `fabric-source/1`): when the folder carries one, `pack` writes
+ * `secrets[]` from its secret slots and `state[]` from its store slots' paths, and FAC-SEM-160 holds them equal.
+ */
+export const SOURCE_FILE = 'fabric.source.json';
+
+function sourceManifest(files) {
+  if (!files.has(SOURCE_FILE)) return undefined;
+  const source = parseStrict(files.get(SOURCE_FILE), SOURCE_FILE);
+  if (source.format !== 'fabric-source/1') throw new PackageError(`${SOURCE_FILE} is not a fabric-source/1 manifest (its format member).`);
+  return source;
+}
+
+/** `secrets[]` from the secret slots (name, purpose, optional) and `state[]` from the store slots (path, purpose). */
+export function sourceMembers(source) {
+  const secrets = [];
+  const state = [];
+  for (const slot of objects(source.slots)) {
+    if (slot.kind === 'secret' && isString(slot.name)) secrets.push({ name: slot.name, purpose: slot.purpose, ...(slot.optional === true ? { optional: true } : {}) });
+    else if (slot.kind === 'store' && isString(slot.path)) state.push({ path: slot.path, purpose: slot.purpose });
+  }
+  return { secrets, state };
+}
+
+/**
+ * FAC-SEM-160 (contract `sourcePackageFindings`): the package's secrets[] are the source's secret slots, by name and
+ * optional; its state[] paths are the store slots' paths when state[] holds any entry.
+ */
+export function sourcePackageFindings(source, pkg) {
+  if (!isObject(source) || !isObject(pkg)) return [];
+  const out = [];
+  const flag = (instancePath, message) => out.push({ code: 'FAC-SEM-160', instancePath, message });
+  const slots = objects(source.slots);
+  const secrets = new Map(slots.filter((s) => s.kind === 'secret' && isString(s.name)).map((s) => [s.name, s.optional === true]));
+  const stores = new Set(slots.filter((s) => s.kind === 'store' && isString(s.path)).map((s) => s.path));
+  const packaged = (Array.isArray(pkg.secrets) ? pkg.secrets : []).flatMap((e, i) => (isObject(e) ? [[e, i]] : []));
+  const names = new Set(packaged.map(([e]) => e.name));
+  for (const name of secrets.keys()) if (!names.has(name)) flag('/package/secrets', `the source's secret slot ${name} is not in the package's secrets[]`);
+  for (const [entry, index] of packaged) {
+    if (!isString(entry.name) || !secrets.has(entry.name)) flag(`/package/secrets/${index}/name`, `secrets[${index}] is no secret slot of the source`);
+    else if (secrets.get(entry.name) !== (entry.optional === true)) flag(`/package/secrets/${index}/optional`, `secrets[${index}] is ${secrets.get(entry.name) ? '' : 'not '}optional in the source`);
+  }
+  if (!Array.isArray(pkg.state) || pkg.state.length === 0) return out;
+  const paths = new Set(objects(pkg.state).map((e) => e.path));
+  for (const p of stores) if (!paths.has(p)) flag('/package/state', "a store slot's path of the source is not in the package's state[]");
+  pkg.state.forEach((entry, index) => {
+    if (isObject(entry) && (!isString(entry.path) || !stores.has(entry.path))) flag(`/package/state/${index}/path`, `state[${index}] is no store slot of the source`);
+  });
+  return out;
+}
+
+function sourceProblems(pkg, files) {
+  if (!files.has(SOURCE_FILE)) return [];
+  try {
+    return sourcePackageFindings(sourceManifest(files), pkg).map((p) => ({ ...p, rule: p.code }));
+  } catch (error) {
+    if (!(error instanceof PackageError)) throw error;
+    return [{ rule: 'source', instancePath: '/files', message: error.message }];
+  }
+}
+
 function allProblems(pkg, files) {
   return [
     ...schemaProblems(pkg).map((p) => ({ ...p, rule: 'schema' })),
+    ...sourceProblems(pkg, files),
     ...pathProblems(pkg).map((p) => ({ ...p, rule: 'path' })),
     ...packageFindings(pkg).map((p) => ({ ...p, rule: p.code })),
     ...checkPackageFolder(pkg, files).map((p) => ({ rule: 'folder', problem: p.problem, instancePath: p.path, message: FOLDER_MESSAGES[p.problem] ?? p.problem })),
@@ -525,6 +587,21 @@ function writeAtomic(file, text) {
   fs.renameSync(temp, file);
 }
 
+/** The names a hand-written secrets[] declares that the source manifest has no secret slot for, in their order. */
+function secretsLacking(draft, secrets) {
+  const have = new Set(secrets.map((s) => s.name));
+  const lacking = [];
+  for (const entry of Array.isArray(draft.secrets) ? draft.secrets : []) {
+    const name = isObject(entry) ? entry.name : undefined;
+    if (isString(name) && !have.has(name) && !lacking.includes(name)) lacking.push(name);
+  }
+  return lacking;
+}
+
+function lackingMessage(lacking) {
+  return `${SOURCE_FILE} declares no secret slot for ${lacking.join(', ')}, which ${PACKAGE_FILE}'s secrets[] names: pack writes secrets[] from the manifest's slots and never drops a declared secret. Add each as a slot of kind secret to ${SOURCE_FILE} (or take it out of secrets[]), then pack again`;
+}
+
 /** Pack `folder`; with `apply` and no problem, fabric.package.json is rewritten. */
 export function pack(folder, { apply = false } = {}) {
   const files = readFolder(folder);
@@ -532,8 +609,28 @@ export function pack(folder, { apply = false } = {}) {
     throw new PackageError(`Write ${PACKAGE_FILE} in the folder first: schema, kind, id, version, publisher, licence and, for an agent, resultSignal and evals with its receipt. pack fills in agentRef, files[] and digest.`);
   }
   const draft = parseStrict(files.get(PACKAGE_FILE), PACKAGE_FILE);
+  const source = sourceManifest(files);
+  const written = [];
+  const refused = [];
+  if (source !== undefined) {
+    // DEC-0149: secrets[] and state[] come from the source manifest's slots; an empty state[] is a copy without state.
+    const members = sourceMembers(source);
+    const lacking = secretsLacking(draft, members.secrets);
+    if (lacking.length > 0) {
+      // a declared secret is never dropped: the manifest gains its slot first
+      refused.push({ rule: 'source', instancePath: '/secrets', message: lackingMessage(lacking) });
+    } else if (members.secrets.length > 0 || Object.hasOwn(draft, 'secrets')) {
+      Object.defineProperty(draft, 'secrets', { value: members.secrets, enumerable: true, writable: true, configurable: true });
+      written.push('secrets[]');
+    }
+    if (members.state.length > 0 && !(Array.isArray(draft.state) && draft.state.length === 0)) {
+      Object.defineProperty(draft, 'state', { value: members.state, enumerable: true, writable: true, configurable: true });
+      written.push('state[]');
+    }
+  }
   const { pkg, notes } = compose(draft, files);
-  const problems = allProblems(pkg, files);
+  if (written.length > 0) notes.push(`${written.join(' and ')} written from ${SOURCE_FILE}`);
+  const problems = [...refused, ...allProblems(pkg, files)];
   const suite = isObject(pkg.evals) ? pkg.evals.suite : undefined;
   if (isString(suite) && files.has(suite) && problems.some((p) => p.instancePath === '/evals/receipt/suite')) notes.push(`the suite packed is ${sha256Of(files.get(suite))}: run it again and write that receipt`);
   const answer = { ok: problems.length === 0, applied: false, digest: pkg.digest, files: pkg.files.length, problems, notes };

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.2.0+kit.5'; // the Python twin's, Observatory's 1.2.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);
@@ -416,7 +420,7 @@ async function ownerOf(local, remote, opts = {}, server = false) {
     // Linux: a connection not yet accept()ed is printed with uid 0 and inode 0; it belongs to the listener on its local
     // address and dies with it, so that listener answers. An accepted connection's own row carries the uid of the
     // process that accepted it: it answers itself, so a listener swapped after another account accepted the client
-    // cannot pass (Project Observatory's 1.2.0 reading, board thread ced00f6e; the contract's pending CT-254, FAA-258).
+    // cannot pass (Project Observatory's 1.2.0 reading, board thread ced00f6e; the contract's CT-254, released).
     // A server row its owner already closed (an orphan) also has inode 0 and reads so: no process holds it, so nothing
     // sent to it reaches anyone (0.74.0 unit reading 6).
     return oneOwner(listenersOf(table.rows, found[0].local), table.how, opts, 'not-accepted');
@@ -460,7 +464,7 @@ export function peer(socket, opts) {
 // For a client's connected socket: who accepted it. The row whose local address is the server's and whose remote
 // address is this socket's own, the server process's accepted socket, so a listener swapped after listen cannot pass
 // for the one that answers. On Linux a connection not yet accept()ed has no owner of its own (inode 0): its listener
-// answers (the contract's pending CT-254, FAA-258).
+// answers (the contract's CT-254, HA-2's Linux source).
 export function serverEnd(socket, opts) {
   if (!socket.remoteAddress || !socket.localAddress) return Promise.resolve(owner(UNKNOWN, { reason: 'socket: not connected' }));
   return ownerOf(address(socket.remoteAddress, socket.remotePort), address(socket.localAddress, socket.localPort), opts, true);

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

@@ -12,7 +12,7 @@ export const PROTOCOL_REVISIONS = new Map(Object.entries({
   'fabric-interop': ['0.1', '0.2'], 'fabric-local-channel': ['0.1'], 'fabric-local-runner': ['0.1'], 'fabric-machine-report': ['1'], 'fabric-ops-digest': ['0.1'], 'fabric-operator-channel': ['0.1'],
   'fabric-package': ['1'],
   'fabric-peer-share': ['1'], 'fabric-peer-share-envelope': ['1'], 'fabric-peer-share-report': ['1'], 'fabric-project-comms': ['0.1'], 'fabric-proposal': ['1'], 'fabric-provider': ['0.1'], 'fabric-relay': ['0.1'],
-  'fabric-secret-envelope': ['1'], 'fabric-service': ['0.1'], 'fabric-settings-backup': ['1'], heartbeat: ['1'], 'learning-note': ['1'], 'machine-report': ['1'], mandate: ['1'],
+  'fabric-secret-envelope': ['1'], 'fabric-service': ['0.1'], 'fabric-settings-backup': ['1'], 'fabric-source': ['1'], heartbeat: ['1'], 'learning-note': ['1'], 'machine-report': ['1'], mandate: ['1'],
   memory: ['0.1'], 'node-summary': ['1'], 'operator-source': ['1'], 'org-adaptation': ['1'], 'org-adaptation-receipt': ['1'], 'org-authority': ['1'], 'org-authority-draft': ['1'],
   'org-key-set': ['1'], 'org-key-set-draft': ['1'], 'org-membership': ['1'], 'org-root-registration': ['1'], 'pairing-message': ['1'],
   'peer-share-deletion': ['1'], 'peer-share-frame': ['1'], 'peer-share-revocation': ['1'], pipeline: ['0.1'], 'repair-request': ['1'], 'repair-result': ['1'],

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

@@ -38,8 +38,12 @@ export function credentialName(name) {
 
 /** A JWT or JWS anywhere in a value. */
 export const JWT_SHAPE = /eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*/;
-/** A value that says it is a credential, or a provider key's shape. */
-export const SECRET_VALUE = /(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})/i;
+/** A value that says it is a credential (`Bearer ` at its start, in any case), or a provider key's shape with its prefix
+ * in its canonical case only, at the start of a value, after a character that is no ASCII letter or digit, or after an
+ * escape; an `sk-` key holds a digit and an upper-case letter with 16 or more characters, or a digit with 32 or more,
+ * within 256 characters (the contract's SECRET_VALUE at the pin, DEC-0151). A match includes its boundary character:
+ * callers test, never read the matched text or its index. */
+export const SECRET_VALUE = /(^[Bb][Ee][Aa][Rr][Ee][Rr]\s.+|(?:^|[^A-Za-z0-9]|%[0-9A-Fa-f]{2}|\\[nrt"']|\\u[0-9A-Fa-f]{4}|\\x[0-9A-Fa-f]{2}|\\[bfv0ae]|\\[0-7]{1,3}|%25[0-9A-Fa-f]{2}|\x1b\[[0-9;:]*m|(?:\\u001[bB]|\\x1[bB]|\\e|\\033|\\33)\[[0-9;:]*m)(?:sk-(?=[A-Za-z0-9_-]{0,255}?\d)(?:(?=[A-Za-z0-9_-]{0,255}?[A-Z])[A-Za-z0-9_-]{16,}|[A-Za-z0-9_-]{32,})|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}))/;
 const LONG_RUN = /[A-Za-z0-9+/=_-]{40,}/g;
 export const longSecret = (value) => (value.match(LONG_RUN) ?? []).some((run) => /[a-z]/.test(run) && /[A-Z]/.test(run) && /[0-9]/.test(run));
 
@@ -91,7 +95,10 @@ export function secretUrl(value) {
 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');
+// A repository name's own key shapes, boundary-free and case-sensitive (DEC-0151): SECRET_VALUE takes a consuming
+// boundary, so composed after a separator look-behind it would miss a key after `-`, `.` or `_`.
+const REPOSITORY_KEYS = 'sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,}';
+const KEY_AT_A_WORD = new RegExp(`(?:^|(?<=[._-]))(?:${REPOSITORY_KEYS})`);
 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
 

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,
@@ -103,6 +107,10 @@ export {
   STATUSES,
   PLACEMENTS,
   MANAGERS,
+  PEER_CHECKS,
+  connectionRefusal,
+  connectionOwner,
+  loopbackServer,
   descriptorPath,
   readDescriptors,
   validateDescriptor,
@@ -118,7 +126,9 @@ export {
   fabricButtonPresence,
   placementOf,
   remoteOriginProblems,
+  portListenerRefusal,
   portOf,
+  portOwner,
   NO_SOURCE_REPOSITORY,
   namesRepository,
   sourceRefusal,
@@ -179,6 +189,7 @@ export {
   taskUninstall,
   launchdPlist,
   SYSTEM_DAEMONS,
+  USER_NAME_RULE,
   launchdDomain,
   wellKnownOf,
   jobWellKnownOf,