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

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

@@ -0,0 +1,266 @@
+// Work a service holds by its own limits, said to its caller and its operator (FAA-298): a held job's statusMessage in
+// the contract's pause grammar (`quota-exhausted[ until <until>]: waiting <reason> since <since>[: <message>]`; the
+// pinned interop-job schema is closed, so `waiting {reason, since, until, message}` rides statusMessage, never a field
+// of the job), one push per hold, and the operator's scoped lift. The twin of fabric_holds.py, held to the same
+// vectors (test/fixtures/holds/waiting-vectors.json). Part of the Node service kit (layer L3, after fabric-interop).
+// Node 20+, no dependency.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { ServiceError, nowIso } from './fabric-base.mjs';
+import { atomicWrite } from './fabric-paths.mjs';
+import { decisionShape } from './fabric-actions.mjs';
+import { QUOTA_EXHAUSTED, codePoints, pauseMessage, readJobPause, utcTime } from './fabric-interop-rules.mjs';
+import { secretValue } from './fabric-secrets.mjs';
+
+/** The limits a hold names: a daily quota, a per-caller share, a concurrency cap, a money cap. */
+export const HOLD_REASONS = Object.freeze(['daily-quota', 'caller-share', 'concurrency', 'money']);
+/** How the push names each reason to a person. */
+export const REASON_WORDS = Object.freeze({
+  'daily-quota': 'the daily quota', 'caller-share': 'its per-caller share',
+  concurrency: 'the concurrency cap', money: 'the money cap',
+});
+/** The push's kind: a decision for the operator (level notice, notify true). */
+export const HOLD_EVENT_KIND = 'limit.held';
+/** The record of a lift applied (level info, no notify). */
+export const LIFT_EVENT_KIND = 'limit.lifted';
+/** The decision action a lift carries (DEC-0121 AP-2 shape). */
+export const LIFT_ACTION = 'limit.lift';
+const MAX_STATUS_MESSAGE = 500;
+const WAITING = /^waiting (daily-quota|caller-share|concurrency|money) since ([0-9][0-9TZ:.-]*?)(?:: ([\s\S]+))?$/;
+const SIZES = ['jobs', 'usd', 'limit'];
+
+const instant = (value, name) => {
+  if (!Number.isFinite(utcTime(value))) throw new ServiceError(`${name} is a UTC instant (Z, at most 3 fraction digits).`);
+  return value;
+};
+const reasonOk = (reason, what) => {
+  if (!HOLD_REASONS.includes(reason)) throw new ServiceError(`A ${what}'s reason is one of ${HOLD_REASONS.join(', ')}.`);
+};
+const squash = (text) => String(text).split(/\s+/).filter(Boolean).join(' ');
+
+/** A held job's statusMessage; the message is shortened, never refused, to fit 500 characters. */
+export function waitingMessage(reason, since, until = null, message = null) {
+  reasonOk(reason, 'hold');
+  instant(since, 'since');
+  if (until !== null && until !== undefined) instant(until, 'until');
+  else until = null;
+  let text = `waiting ${reason} since ${since}`;
+  const head = QUOTA_EXHAUSTED.length + (until === null ? 0 : ' until '.length + until.length) + ': '.length;
+  if (message !== null && message !== undefined) {
+    const squashed = squash(message);
+    const room = MAX_STATUS_MESSAGE - head - codePoints(text) - ': '.length;
+    if (squashed && room > 0) {
+      text += ': ' + (codePoints(squashed) <= room ? squashed : [...squashed].slice(0, room - 3).join('').trimEnd() + '...');
+    }
+  }
+  return pauseMessage(until === null ? { text } : { resetsAt: until, text });
+}
+
+/** `{reason, since, until?, message?}` of a fabric.job.get answer whose job a limit holds, else null. */
+export function readWaiting(answer) {
+  const pause = readJobPause(answer);
+  if (!pause.paused) return null;
+  let rest = answer.job.statusMessage.slice(QUOTA_EXHAUSTED.length);
+  if ('resetsAt' in pause) rest = rest.slice(' until '.length + pause.resetsAt.length);
+  if (!rest.startsWith(': ')) return null;
+  const match = WAITING.exec(rest.slice(2));
+  if (!match || !Number.isFinite(utcTime(match[2]))) return null;
+  const waiting = { reason: match[1], since: match[2] };
+  if ('resetsAt' in pause) waiting.until = pause.resetsAt;
+  if (match[3] !== undefined) waiting.message = match[3];
+  return waiting;
+}
+
+/** Put one job of a fabric-interop JobStore on hold (JobStore.pause with the waiting text). */
+export function holdJob(jobs, jobId, reason, since, until = null, message = null) {
+  let text = waitingMessage(reason, since, until, message).slice(QUOTA_EXHAUSTED.length);
+  if (until !== null && until !== undefined) text = text.slice(' until '.length + until.length);
+  return jobs.pause(jobId, until === null || until === undefined ? { text: text.slice(2) } : { resetsAt: until, text: text.slice(2) });
+}
+
+/** The push's one sentence: who, what, why, when it frees by itself, and the question. */
+export function holdSentence(caller, work, reason, until) {
+  const frees = until !== null && until !== undefined ? `it frees by itself at ${until}`
+    : (['concurrency', 'caller-share'].includes(reason) ? 'it frees by itself when a running job ends' : 'it does not free by itself');
+  return `${work} for ${caller} is held by ${REASON_WORDS[reason]}; ${frees}. Raise the limit for it?`;
+}
+
+function text(value, name, high = 200) {
+  if (typeof value !== 'string' || !value.trim() || value.length > high) throw new ServiceError(`${name} is a text of 1 to ${high} characters.`);
+  if (secretValue(value)) throw new ServiceError(`${name} looks like a credential; a hold names callers and work, never a secret.`);
+  return squash(value);
+}
+
+const newId = () => crypto.randomUUID().replaceAll('-', '');
+
+/**
+ * The holds a service's limits put on work and the operator's lifts, in one file (0600, written atomically).
+ * `events`, when given, is a function `({kind, level, text, subject, notify}) => event` that writes the push and the
+ * lift record to the service's event log; without it they are returned for the service to write.
+ */
+export class HoldBook {
+  constructor(file, { events = null, clock = nowIso } = {}) {
+    this.file = file;
+    this.events = events;
+    this.clock = clock;
+  }
+
+  load() {
+    if (!fs.existsSync(this.file)) return { holds: [], lifts: [] };
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+    } catch {
+      throw new ServiceError('The hold book is not JSON; it is kept as it is.');
+    }
+    if (data === null || typeof data !== 'object' || !Array.isArray(data.holds) || !Array.isArray(data.lifts)) {
+      throw new ServiceError('The hold book is not {holds, lifts}; it is kept as it is.');
+    }
+    return data;
+  }
+
+  save(data) { atomicWrite(this.file, JSON.stringify(data, null, 1) + '\n', 0o600); }
+
+  now(now) { return instant(now ?? this.clock(), 'now'); }
+
+  emit(kind, level, sentence, subject, notify) {
+    const event = { kind, level, text: sentence, subject };
+    if (notify) event.notify = true;
+    return this.events ? this.events(event) : event;
+  }
+
+  static expire(data, at) {
+    for (const hold of data.holds) {
+      if (hold.closed === null && hold.until !== null && utcTime(hold.until) <= at) {
+        hold.closed = 'expired';
+        hold.closedAt = hold.until;
+      }
+    }
+  }
+
+  static live(lift, at) {
+    if (lift.from !== null && lift.from !== undefined && utcTime(lift.from) > at) return false;
+    if (lift.until !== null && lift.until !== undefined && utcTime(lift.until) <= at) return false;
+    return (lift.left ?? 1) > 0;
+  }
+
+  /** Hold `work` for `caller` by `reason`: {hold, statusMessage, push}; push only when this call opened the hold. */
+  hold({ caller, work, reason, until = null, message = null, jobId = null, now = null }) {
+    caller = text(caller, 'caller');
+    work = text(work, 'work');
+    reasonOk(reason, 'hold');
+    const at = this.now(now);
+    if (until !== null && utcTime(instant(until, 'until')) <= utcTime(at)) {
+      throw new ServiceError(`until ${until} has passed: the limit no longer holds the work.`);
+    }
+    const data = this.load();
+    HoldBook.expire(data, utcTime(at));
+    let hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    const opened = hold === undefined;
+    if (opened) {
+      hold = { id: newId(), reason, caller, work, since: at, until, jobs: [], closed: null };
+      data.holds.push(hold);
+    }
+    if (jobId !== null && !hold.jobs.includes(String(jobId))) hold.jobs.push(String(jobId));
+    this.save(data);
+    const statusMessage = waitingMessage(reason, hold.since, hold.until, message);
+    const push = opened ? this.emit(HOLD_EVENT_KIND, 'notice', holdSentence(caller, work, reason, until),
+      { type: 'limit', id: `${reason}:${caller}`.slice(0, 200), label: REASON_WORDS[reason] }, true) : null;
+    return { hold: { ...hold }, statusMessage, push };
+  }
+
+  /** Close the open hold of (reason, caller): the limit freed the work. The next hold pushes again. */
+  release({ reason, caller, now = null }) {
+    const at = this.now(now);
+    const data = this.load();
+    const hold = data.holds.find((h) => h.closed === null && h.reason === reason && h.caller === caller);
+    if (!hold) return null;
+    hold.closed = 'released';
+    hold.closedAt = at;
+    this.save(data);
+    return { ...hold };
+  }
+
+  openHolds(now = null) {
+    const data = this.load();
+    HoldBook.expire(data, utcTime(this.now(now)));
+    return data.holds.filter((h) => h.closed === null).map((h) => ({ ...h }));
+  }
+
+  /** Record the operator's answer as a scoped lift: exactly one of jobs, usd or limit (limit needs until). */
+  lift({ reason, decision, caller = null, jobId = null, jobs = null, usd = null, limit = null, until = null, now = null }) {
+    reasonOk(reason, 'lift');
+    if (!decisionShape(decision) || decision.action !== LIFT_ACTION) {
+      throw new ServiceError("A lift carries the operator's decision (decision.schema.json, action limit.lift, their "
+        + "words verbatim): operatorDecision({ action: 'limit.lift', instruction: words }).");
+    }
+    const sizes = { jobs, usd, limit };
+    const given = SIZES.filter((name) => sizes[name] !== null && sizes[name] !== undefined);
+    if (given.length !== 1) throw new ServiceError('A lift is one of jobs, usd or limit.');
+    const kind = given[0];
+    const size = sizes[kind];
+    if (typeof size !== 'number' || !Number.isFinite(size) || size <= 0 || (kind !== 'usd' && !Number.isInteger(size))) {
+      throw new ServiceError(`A lift's ${kind} is a positive ${kind === 'usd' ? 'number' : 'integer'}.`);
+    }
+    const at = this.now(now);
+    if (until !== null && utcTime(instant(until, 'until')) <= utcTime(at)) throw new ServiceError("A lift's window ends after now.");
+    if (kind === 'limit' && until === null) {
+      throw new ServiceError('A raised limit needs its window\'s end (until): it falls back when the window ends.');
+    }
+    const record = { id: newId(), reason, caller: caller === null ? null : text(caller, 'caller'),
+      job: jobId === null ? null : String(jobId), from: at, until, [kind]: size, decision: { ...decision }, at };
+    if (kind !== 'limit') record.left = size;
+    const data = this.load();
+    HoldBook.expire(data, utcTime(at));
+    for (const hold of data.holds) {
+      if (hold.closed === null && hold.reason === reason && (record.caller === null || record.caller === hold.caller)
+        && (jobId === null || hold.jobs.includes(String(jobId)))) {
+        hold.closed = 'lifted';
+        hold.closedAt = at;
+        hold.lift = record.id;
+      }
+    }
+    data.lifts.push(record);
+    this.save(data);
+    const scope = record.caller ? `for ${record.caller}` : 'for every caller';
+    const amount = { jobs: `${size} more job(s)`, usd: `USD ${size} more`, limit: `the limit at ${size}` }[kind];
+    this.emit(LIFT_EVENT_KIND, 'info', `The operator lifted ${REASON_WORDS[reason]} ${scope}: ${amount}${until ? ` until ${until}` : ''}.`,
+      { type: 'limit', id: `${reason}:${record.caller ?? '*'}`, label: REASON_WORDS[reason] }, false);
+    return { ...record };
+  }
+
+  static matching(data, reason, caller, jobId, at, kind) {
+    return data.lifts.filter((l) => l.reason === reason && kind in l && HoldBook.live(l, at)
+      && (l.caller === null || l.caller === caller) && (l.job === null || l.job === jobId));
+  }
+
+  /** Whether a lift lets work past the limit: {admitted: true, lift, left} spends one job or `costUsd`, else {admitted: false}. */
+  admit({ reason, caller, jobId = null, costUsd = null, now = null }) {
+    const at = utcTime(this.now(now));
+    const data = this.load();
+    const kind = costUsd !== null ? 'usd' : 'jobs';
+    const found = HoldBook.matching(data, reason, caller, jobId === null ? null : String(jobId), at, kind)
+      .sort((a, b) => ((a.job === null) - (b.job === null)) || ((a.caller === null) - (b.caller === null)));
+    for (const lift of found) {
+      const need = kind === 'usd' ? costUsd : 1;
+      if (lift.left >= need) {
+        lift.left = kind === 'usd' ? Math.round((lift.left - need) * 1e6) / 1e6 : lift.left - 1;
+        this.save(data);
+        return { admitted: true, lift: lift.id, left: lift.left };
+      }
+    }
+    return { admitted: false };
+  }
+
+  /** The limit in force: `base`, or the highest live raised limit for (reason, caller). */
+  limit({ reason, base, caller = null, now = null }) {
+    const at = utcTime(this.now(now));
+    return Math.max(base, ...HoldBook.matching(this.load(), reason, caller, null, at, 'limit').map((l) => l.limit));
+  }
+
+  /** Every lift with `live`: whether it still applies now. */
+  lifts(now = null) {
+    const at = utcTime(this.now(now));
+    return this.load().lifts.map((l) => ({ ...l, live: HoldBook.live(l, at) }));
+  }
+}

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

@@ -20,7 +20,8 @@
 // Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 import http from 'node:http';
-import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED } from './fabric-peer-owner.mjs';
+import net from 'node:net';
+import { CheckedAgent, ListenerRefused, TABLE_RESTRICTED, UNKNOWN, method as tableMethod, owner as ownerOf, refusal, serverEnd } 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']);
@@ -158,6 +159,61 @@ function checkHeaders(headers) {
 
 const LOOPBACK_AGENT = new CheckedAgent();
 
+// Whether a connected socket reached this computer's loopback, by the address it connected to, not by the URL's
+// spelling: a name the hosts file maps to 127.0.0.1, `0.0.0.0` and `[::ffff:127.0.0.1]` arrive here (FAA-260).
+export function peerIsLoopback(address) {
+  const a = String(address ?? '').split('%', 1)[0].toLowerCase();
+  if (a === '::1' || a === '0.0.0.0' || a === '::') return true;
+  const v4 = /^(?:::ffff:)?(\d{1,3})\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.exec(a);
+  if (v4) return v4[1] === '127';
+  const hex = /^::ffff:([0-9a-f]{1,4}):[0-9a-f]{1,4}$/.exec(a);
+  return hex !== null && (parseInt(hex[1], 16) >> 8) === 127;
+}
+
+// An http.Agent for plain http to a host not spelled as loopback (`insecure`): when the connected socket's peer is a
+// loopback address, its server end is told as CheckedAgent tells it and refused before a byte is written unless it is
+// this OS account's process (DEC-0154 HA-2; 0.74.0 unit readings 7 and 8, FAA-260). Another peer is used as it is.
+export class PeerCheckedAgent extends http.Agent {
+  constructor({ ask = {}, ...options } = {}) {
+    super(options);
+    this.ask = ask;
+  }
+
+  createConnection(options, callback) {
+    let done = false;
+    const finish = (err, socket) => { if (!done) { done = true; callback(err, socket); } };
+    const port = Number(options.port);
+    const socket = net.connect({ host: options.host, port, noDelay: true, autoSelectFamily: true,
+      ...(options.lookup ? { lookup: options.lookup } : {}) });
+    socket.once('error', (err) => finish(err));
+    socket.once('connect', async () => {
+      if (!peerIsLoopback(socket.remoteAddress)) {
+        socket.removeAllListeners('error');
+        finish(null, socket);
+        return;
+      }
+      socket.pause();
+      let who;
+      try {
+        who = await serverEnd(socket, this.ask);
+      } catch (err) {
+        who = ownerOf(UNKNOWN, { method: tableMethod(), reason: `check: ${err?.name ?? 'Error'}` });
+      }
+      const refused = refusal(who, port, null);
+      if (refused) {
+        socket.destroy();
+        finish(new ListenerRefused(refused[0], `${refused[1]}; nothing was sent`, who));
+        return;
+      }
+      socket.removeAllListeners('error');
+      socket.resume();
+      finish(null, socket);
+    });
+  }
+}
+
+const PLAIN_AGENT = new PeerCheckedAgent();
+
 // Plain http to a loopback host (DEC-0154 HA-2): node:http over a connection checked before a byte is written, no
 // redirect followed, the body read to one byte past maxBytes. fetch cannot hand its socket to the check.
 export function checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes, agent = LOOPBACK_AGENT }) {
@@ -198,12 +254,15 @@ export function checkedLoopbackTransport({ method, url, headers, body, timeoutS,
   });
 }
 
-// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes; plain http to a
-// loopback host goes through checkedLoopbackTransport.
+// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes; plain http goes
+// through checkedLoopbackTransport, its connection checked when it reaches loopback (FAA-260).
 export async function fetchTransport({ method, url, headers, body, timeoutS, maxBytes }) {
   const target = new URL(url);
-  if (target.protocol === 'http:' && isLoopback(target.hostname)) {
-    return checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes });
+  if (target.protocol === 'http:') {
+    // plain http never goes through fetch: a URL spelled as loopback is checked on every connection, any other is
+    // checked when its connected peer is a loopback address (FAA-260)
+    return checkedLoopbackTransport({ method, url, headers, body, timeoutS, maxBytes,
+      ...(isLoopback(target.hostname) ? {} : { agent: PLAIN_AGENT }) });
   }
   const res = await fetch(url, { method, headers, body: body ?? undefined, redirect: 'manual',
     signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutS * 1000))) });

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.4'; // 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';
@@ -420,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');
@@ -464,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

@@ -107,6 +107,10 @@ export {
   STATUSES,
   PLACEMENTS,
   MANAGERS,
+  PEER_CHECKS,
+  connectionRefusal,
+  connectionOwner,
+  loopbackServer,
   descriptorPath,
   readDescriptors,
   validateDescriptor,
@@ -185,6 +189,7 @@ export {
   taskUninstall,
   launchdPlist,
   SYSTEM_DAEMONS,
+  USER_NAME_RULE,
   launchdDomain,
   wellKnownOf,
   jobWellKnownOf,