@passioncode-ai/fabric-agent-adapter 0.39.1 → 0.41.0

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

@@ -21,14 +21,9 @@ const ESTATE_SCOPE = /^estate:[A-Za-z0-9][A-Za-z0-9._:~-]{0,127}$/;
 const NONCE32 = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
 const ASSERTION_MEMBERS = 'alg,authenticatorData,clientDataJSON,credentialId,format,sig';
 
-const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const isString = (value) => typeof value === 'string';
+import { isObject, isString, objects as list, show, jsonEqual } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
+import { clockMs as clockOf } from './fabric-time.mjs'; // the core's (FAA-65)
 const matches = (pattern, value) => isString(value) && pattern.test(value);
-const list = (value) => (Array.isArray(value) ? value.filter(isObject) : []);
-const show = (value) => {
-  if (typeof value === 'string') return value;
-  try { return String(value); } catch { return JSON.stringify(value) ?? typeof value; }
-};
 const REGISTER = new Map([
   [ENROLL_TOKEN_TYPE, { fields: ENROLL_TOKEN_FIELDS, check: (f) => matches(ESTATE_SCOPE, f.scope) && matches(SHA256, f.genesis) && f.purpose === ENROLL_PURPOSE
     && (f.ceiling === null || matches(SHA256, f.ceiling)) && Number.isFinite(estateTime(f.notBefore)) && Number.isFinite(estateTime(f.expiresAt)) && matches(NONCE32, f.nonce) && f.uses === 1 }],
@@ -52,9 +47,12 @@ function statementFields(token) {
   return signingStatement(ENROLL_TOKEN_TYPE, fields) ? fields : undefined;
 }
 
-/** The reference verifier of an enroll-token/1 under trust {record, genesis, at: Date}; the first failure answers. */
+/**
+ * The reference verifier of an enroll-token/1 under trust {record, genesis, at}; `at` is a Date or epoch seconds, as
+ * verifyEstateRecord and the Python twin take it. The first failure answers.
+ */
 export function verifyEnrollToken(token, trust) {
-  const at = isObject(trust) && trust.at instanceof Date ? trust.at.getTime() : Number.NaN;
+  const at = isObject(trust) ? clockOf(trust.at) : Number.NaN;
   if (!Number.isFinite(at)) return { ok: false, problem: 'no-clock' };
   const fields = statementFields(token);
   const record = trust.record;
@@ -180,15 +178,6 @@ const sha = (text) => crypto.createHash('sha256').update(Buffer.from(text, 'utf8
 const uint40 = (digest, offset) => digest.readUIntBE(offset, 5);
 const own = (value, key) => (isObject(value) && Object.hasOwn(value, key) ? value[key] : undefined);
 const isRole = (value) => value === 'new' || value === 'trusted';
-function jsonEqual(a, b) {
-  if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, i) => jsonEqual(item, b[i]));
-  if (isObject(a) || isObject(b)) {
-    if (!isObject(a) || !isObject(b)) return false;
-    const keys = Object.keys(a);
-    return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && jsonEqual(a[key], b[key]));
-  }
-  return a === b;
-}
 
 /** The machine a key list belongs to, or undefined (one sig key, at most one kem key, one machine id, valid keys). */
 export function machineOfKeys(keys) {

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

@@ -0,0 +1,41 @@
+// The Node kit's cryptography helpers, once (FAA-65, layer L1); the twin of fabric_crypto.py. Signature verification
+// itself is Node's (`crypto.verify`); what lives here is what the runtime does not refuse on its own: keys of small
+// order (DEC-0045) and P-256 points off the curve, plus sha256. Node 20+, no dependency.
+import crypto from 'node:crypto';
+
+export const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest();
+
+// The small-order points of edwards25519 and their non-canonical encodings, compared with the sign bit cleared
+// (libsodium's has_small_order list). Under such a key, R = [S]B verifies for a quarter or more of all messages, and
+// Node before 26 lets OpenSSL accept it: the kit refuses these keys itself rather than trust the runtime.
+export const SMALL_ORDER_ENCODINGS = Object.freeze([
+  '0000000000000000000000000000000000000000000000000000000000000000', '0100000000000000000000000000000000000000000000000000000000000000',
+  '26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05', 'c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a',
+  'ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f', 'edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
+  'eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
+]);
+const cleared = (raw) => { const copy = Buffer.from(raw); copy[31] &= 0x7f; return copy.toString('hex'); };
+
+/** Whether a 32-byte Ed25519 public key is a point of small order (in any encoding); a key of another length is not one. */
+export function isSmallOrderKey(key) {
+  if (!Buffer.isBuffer(key) || key.length !== 32) return false;
+  return SMALL_ORDER_ENCODINGS.includes(cleared(key));
+}
+
+/** The contract's isSmallOrderKey as the estate record reads a hub key: a key that is not 32 bytes counts as one too. */
+export const isSmallOrderOrMalformed = (raw) => raw.length !== 32 || SMALL_ORDER_ENCODINGS.includes(cleared(raw));
+
+const P256_P = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn;
+const P256_B = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn;
+const toBig = (part) => BigInt(`0x${Buffer.from(part).toString('hex')}`);
+
+/** Whether `raw` is a valid uncompressed P-256 public key: 0x04 ‖ X ‖ Y, both below p, on the curve. */
+export function isValidP256Key(raw) {
+  if (raw.length !== 65 || raw[0] !== 0x04) return false;
+  const x = toBig(raw.subarray(1, 33));
+  const y = toBig(raw.subarray(33, 65));
+  if (x >= P256_P || y >= P256_P) return false;
+  const left = (y * y) % P256_P;
+  const right = (((x * x) % P256_P) * x - 3n * x + P256_B) % P256_P;
+  return left === ((right % P256_P) + P256_P) % P256_P;
+}

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

@@ -67,8 +67,10 @@ const SCOPE = /^[a-z][a-z0-9._-]{1,127}( [a-z][a-z0-9._-]{1,127})*$/;
 const SPEND_WINDOWS = ['total', 'task', 'project', 'day', 'week', 'month'];
 const isUri = (value) => typeof value === 'string' && URI.test(value);
 const isAmount = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
-const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const isString = (value) => typeof value === 'string' && value.length > 0;
+import { jcs, isObject } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
+export { jcs };
+/** A string with at least one character (the token's claims refuse an empty one). */
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
 const isTime = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0;
 
 /** Whether a JSON text repeats a member name in one object: refused, never resolved (RFC 7515 §5.2, RFC 8725 §3.2). */
@@ -122,7 +124,7 @@ function parseCompact(token) {
 function headerProblem(header, typ) {
   if (header.alg !== 'EdDSA') return 'alg-not-eddsa';
   if (header.typ !== typ) return 'wrong-typ';
-  if (!isString(header.kid)) return 'no-kid';
+  if (!isNonEmptyString(header.kid)) return 'no-kid';
   for (const member of ['crit', 'jku', 'jwk', 'x5u', 'x5c']) if (header[member] !== undefined) return `header-${member}`;
   return undefined;
 }
@@ -134,9 +136,10 @@ function keyFor(jwks, kid) {
   if (!jwk) return { problem: 'unknown-key' };
   // A key published for another use or algorithm is never a candidate (RFC 7517 §4.2, §4.4).
   if ((jwk.use !== undefined && jwk.use !== 'sig') || (jwk.alg !== undefined && jwk.alg !== 'EdDSA')) return { problem: 'key-not-for-signing' };
-  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || !isString(jwk.x) || jwk.d !== undefined) return { problem: 'unusable-key' };
+  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || !isNonEmptyString(jwk.x) || jwk.d !== undefined) return { problem: 'unusable-key' };
   const raw = Buffer.from(jwk.x, 'base64url');
-  if (raw.length !== 32) return { problem: 'unusable-key' };
+  // D4: exactly the 43 characters that write 32 bytes (Buffer reads padding, `+` and stray characters leniently).
+  if (raw.length !== 32 || raw.toString('base64url') !== jwk.x) return { problem: 'unusable-key' };
   if (isSmallOrderKey(raw)) return { problem: 'small-order-key' }; // before any verification (DEC-0045, CT-29)
   try {
     return { key: crypto.createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, format: 'jwk' }), raw, x: jwk.x };
@@ -145,22 +148,8 @@ function keyFor(jwks, kid) {
   }
 }
 
-// The small-order points of edwards25519 and their non-canonical encodings, compared with the sign bit cleared
-// (libsodium's has_small_order list). Under such a key, R = [S]B verifies for a quarter or more of all messages, and
-// Node before 26 lets OpenSSL accept it: the kit refuses these keys itself rather than trust the runtime.
-const SMALL_ORDER = [
-  '0000000000000000000000000000000000000000000000000000000000000000', '0100000000000000000000000000000000000000000000000000000000000000',
-  '26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05', 'c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a',
-  'ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f', 'edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
-  'eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
-];
-/** Whether a 32-byte Ed25519 public key is a point of small order (in any encoding). */
-export function isSmallOrderKey(key) {
-  if (!Buffer.isBuffer(key) || key.length !== 32) return false;
-  const cleared = Buffer.from(key);
-  cleared[31] &= 0x7f;
-  return SMALL_ORDER.includes(cleared.toString('hex'));
-}
+import { isSmallOrderKey } from './fabric-crypto.mjs'; // the core's (FAA-65)
+export { isSmallOrderKey };
 
 const hasKeys = (jwks) => isObject(jwks) && Array.isArray(jwks.keys) && jwks.keys.length > 0;
 
@@ -189,7 +178,7 @@ export function chainDepth(act) {
   let node = act;
   while (node !== undefined) {
     if (depth > 0 && isPartnerActor(node)) return depth + 1; // a partner actor ends the chain, never begins it
-    if (!isObject(node) || !isString(node.sub)) return Number.POSITIVE_INFINITY;
+    if (!isObject(node) || !isNonEmptyString(node.sub)) return Number.POSITIVE_INFINITY;
     depth += 1;
     if (depth > 64) return depth;
     node = node.act;
@@ -251,7 +240,7 @@ function delegationShape(payload) {
 
 function approvalShape(payload) {
   const { iss, actionDigest: digest, aud, approver, method, iat, exp, jti } = payload;
-  if (!isString(iss) || !isString(digest) || !isString(aud) || !isString(approver) || !isString(jti) || !isTime(iat) || !isTime(exp)) return undefined;
+  if (!isNonEmptyString(iss) || !isNonEmptyString(digest) || !isNonEmptyString(aud) || !isNonEmptyString(approver) || !isNonEmptyString(jti) || !isTime(iat) || !isTime(exp)) return undefined;
   if (method !== 'prompt' && method !== 'operator-channel') return undefined; // DEC-0045: `device` is removed
   return payload;
 }
@@ -292,7 +281,7 @@ function estateProblem({ estate, estateApplied, estateRevocations }, kid, x, now
 export function verifyDelegation(token, { audience, jwks, now, capability, effect, issuer, readOnly, estate, estateApplied, estateRevocations } = {}) {
   // Before row 1: every time row compares against the clock, and a comparison with NaN is always false.
   if (!readableClock(now)) return refuse('unknown-state', 'no-clock');
-  if (!isString(issuer)) return refuse('issuer-unavailable', 'no-trusted-issuer');
+  if (!isNonEmptyString(issuer)) return refuse('issuer-unavailable', 'no-trusted-issuer');
   if (!hasKeys(jwks)) return refuse('issuer-unavailable', 'no-published-keys');
   const checked = authentic(token, jwks, DELEGATION_TYP);
   if ('problem' in checked) return refuse(checked.issuer ? 'issuer-unavailable' : 'unauthenticated', checked.problem);
@@ -320,7 +309,7 @@ export function verifyApproval(approval, { audience, jwks, now, actionDigest: ex
   if (approval === undefined || approval === null || approval === '') return refuse('approval-required', 'no-approval', { actionDigest: expected });
   if (!isObject(jtiStore) || typeof jtiStore.consume !== 'function') return refuse('unknown-state', 'no-jti-store');
   if (!readableClock(now)) return refuse('unknown-state', 'no-clock');
-  if (!isString(issuer)) return refuse('issuer-unavailable', 'no-trusted-issuer');
+  if (!isNonEmptyString(issuer)) return refuse('issuer-unavailable', 'no-trusted-issuer');
   if (!hasKeys(jwks)) return refuse('issuer-unavailable', 'no-published-keys');
   const checked = authentic(approval, jwks, APPROVAL_TYP);
   if ('problem' in checked) return refuse(checked.issuer ? 'issuer-unavailable' : 'approval-invalid', checked.problem);
@@ -404,26 +393,6 @@ export function readDelegationToken(headers) {
   return undefined;
 }
 
-/** RFC 8785: members sorted by UTF-16 code units, numbers in ECMAScript form; refuses what has no canonical form. */
-export function jcs(value) {
-  if (value === null || typeof value === 'boolean') return JSON.stringify(value);
-  if (typeof value === 'number') {
-    if (!Number.isFinite(value)) throw new TypeError('a non-finite number has no canonical form');
-    return JSON.stringify(value);
-  }
-  if (typeof value === 'string') {
-    if (/\p{Surrogate}/u.test(value)) throw new TypeError('a lone surrogate has no canonical form');
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) return `[${Array.from(value, (item) => jcs(item)).join(',')}]`;
-  if (isObject(value)) {
-    const prototype = Object.getPrototypeOf(value);
-    if (prototype !== Object.prototype && prototype !== null) throw new TypeError('only plain JSON objects have a canonical form');
-    const keys = Object.keys(value).sort();
-    return `{${keys.map((key) => `${jcs(key)}:${jcs(value[key])}`).join(',')}}`;
-  }
-  throw new TypeError(`${typeof value} has no canonical form`);
-}
 
 /** The digest an approval binds: sha256: and the hex SHA-256 of the action's RFC 8785 form. */
 export const actionDigest = (action) => `sha256:${crypto.createHash('sha256').update(jcs(action), 'utf8').digest('hex')}`;
@@ -492,7 +461,7 @@ export const TIERS = Object.freeze(['T0', 'T1', 'T2']);
  * with no delegation. A present token is verified at every tier. `issuer` (auth.delegation.issuer) is required.
  */
 export function delegationGate({ audience, jwks, effects, issuer, readOnly = false, clock = () => Date.now() / 1000, estate, estateApplied, estateRevocations }) {
-  if (!isString(issuer)) throw new Error('the gate needs the issuer it trusts (auth.delegation.issuer)');
+  if (!isNonEmptyString(issuer)) throw new Error('the gate needs the issuer it trusts (auth.delegation.issuer)');
   return async (tool, headers, tier = 'T2') => {
     const effect = effects?.[tool];
     if (!EFFECT_CLASSES.includes(effect)) return refuse('unknown-state', 'no-declared-effect');

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

@@ -0,0 +1,387 @@
+// 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 fs from 'node:fs';
+import path from 'node:path';
+import { credentialName, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
+import { ID, INSTANCE, LOCAL_PATH, PROTOCOL, ServiceError, TASK, UNIT, expand } from './fabric-base.mjs';
+import { atomicWrite, ensurePrivateDir, servicesDir } from './fabric-paths.mjs';
+import { protocolsFindings } from './fabric-protocols.mjs';
+import { ROUTES } from './fabric-usage.mjs';
+
+// The embedded dashboard declaration (fabric-dashboard/0.1, DEC-0036 ED-9), under the well-known
+// 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.2';
+
+export const REFERENCE_THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
+
+export const STATUSES = ['starting', 'ready', 'degraded', 'stopping'];
+
+export const PLACEMENTS = ['local', 'remote'];
+
+const ORIGIN = /^http:\/\/127\.0\.0\.1:([0-9]{3,5})$/;
+
+const REMOTE_ORIGIN = /^https:\/\/((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63})(?::([0-9]{1,5}))?$/;
+
+const RESERVED_HOST = /(^|\.)(localhost|local|internal|home\.arpa|lan|localdomain)$/;
+
+// DEC-0061: `node` (Project Observatory's node supervises its children, no supervisor file); DEC-0069: `person` (an app a
+// person installs and starts; its descriptor says it is installed, never that it runs).
+export const MANAGERS = Object.freeze(['launchd', 'systemd', 'task-scheduler', 'node', 'person', 'none']);
+
+/** Managers that write no launchd label or plist (DEC-0057, DEC-0061, DEC-0069). */
+const NOT_LAUNCHD = Object.freeze(['systemd', 'task-scheduler', 'node', 'person']);
+
+const AUTH_HEADER = /^[A-Za-z][A-Za-z0-9-]{0,63}$/;
+
+export const descriptorPath = (id, instance = 'default', dir = servicesDir()) => path.join(dir, `${id}.${instance}.json`);
+
+export function readDescriptors(dir = servicesDir()) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((n) => n.endsWith('.json')).sort().flatMap((n) => {
+    try {
+      return [[path.join(dir, n), JSON.parse(fs.readFileSync(path.join(dir, n), 'utf8'))]];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export function validateDescriptor(d) {
+  const problems = [];
+  const remote = placementOf(d) === 'remote';
+  if (d.placement !== undefined && !PLACEMENTS.includes(d.placement)) problems.push('placement must be local or remote');
+  // DEC-0069: an app's descriptor says it is installed, never that it runs; its live origin is in its own liveness file.
+  const app = d.lifecycle?.manager === 'person';
+  const required = ['protocol', 'id', 'instance', 'name', ...(app ? [] : ['origin']), 'auth', 'lifecycle', 'installedAt', 'installedBy'];
+  for (const key of remote ? required : [...required, 'paths']) {
+    if (!(key in d)) problems.push(`missing ${key}`);
+  }
+  if (problems.length) return problems;
+  if (d.protocol !== PROTOCOL) problems.push(`protocol must be ${PROTOCOL}`);
+  if (!ID.test(d.id)) problems.push(`id must match ${ID}`);
+  if (!INSTANCE.test(d.instance)) problems.push(`instance must match ${INSTANCE}`);
+  if (remote) problems.push(...remoteOriginProblems(d.origin));
+  else if (d.origin !== undefined && !ORIGIN.test(d.origin)) problems.push('origin must be http://127.0.0.1:<port>');
+  if (!d.auth?.tokenFile) problems.push('auth.tokenFile is required');
+  else if (!LOCAL_PATH.test(String(d.auth.tokenFile))) problems.push('auth.tokenFile must be a local path, never a network share');
+  for (const value of [...(d.paths?.data !== undefined ? [d.paths.data] : []), ...(d.paths?.logs ?? [])]) {
+    if (!LOCAL_PATH.test(String(value))) problems.push(`paths must be local paths, never a network share: ${JSON.stringify(value)}`);
+  }
+  if (!(typeof (d.auth?.header ?? 'Authorization') === 'string' && AUTH_HEADER.test(d.auth?.header ?? 'Authorization'))) problems.push(`auth.header must match ${AUTH_HEADER.source}`);
+  if (!['Bearer', 'none'].includes(d.auth?.scheme ?? 'Bearer')) problems.push('auth.scheme is Bearer or none');
+  if ((d.auth?.header ?? 'Authorization') !== 'Authorization' && (d.auth?.scheme ?? 'Bearer') !== 'none') {
+    problems.push('a custom auth header carries the raw token: scheme must be none');
+  }
+  const life = d.lifecycle ?? {};
+  const manager = life.manager;
+  if (!MANAGERS.includes(manager)) problems.push('lifecycle.manager must be launchd, systemd, task-scheduler, node, person or none');
+  // DEC-0069: `app` is the installed app of a person's descriptor, and nothing else's.
+  if (manager === 'person' && life.app === undefined) problems.push("a person's app declares lifecycle.app, the installed app");
+  if (life.app !== undefined && manager !== 'person') problems.push('lifecycle.app belongs to manager person only');
+  if (life.app !== undefined && !LOCAL_PATH.test(String(life.app))) problems.push('lifecycle.app must be a local path');
+  if (manager === 'launchd' && !(life.label && String(life.plist ?? '').endsWith('.plist'))) {
+    problems.push('a launchd service declares label and plist');
+  }
+  if (life.plist !== undefined && !LOCAL_PATH.test(String(life.plist))) problems.push('lifecycle.plist must be a local path');
+  // DEC-0057, DEC-0061, DEC-0069: a descriptor names one supervisor; launchd's label and plist never sit beside another.
+  for (const field of ['label', 'plist']) {
+    if (life[field] !== undefined && NOT_LAUNCHD.includes(manager)) problems.push(`lifecycle.${field} belongs to launchd, not to ${manager}`);
+  }
+  // DEC-0032: `unit` goes with systemd and `task` with Task Scheduler, and with nothing else.
+  for (const [field, owner, pattern] of [['unit', 'systemd', UNIT], ['task', 'task-scheduler', TASK]]) {
+    if (manager === owner && life[field] === undefined) problems.push(`a ${owner} service declares ${field}`);
+    if (life[field] !== undefined && manager !== owner) problems.push(`lifecycle.${field} belongs to manager ${owner} only`);
+    if (life[field] !== undefined && !pattern.test(String(life[field]))) problems.push(`lifecycle.${field} must match ${pattern.source}`);
+  }
+  if (remote) {
+    if (manager !== 'none') problems.push('a remote service is supervised by its platform: lifecycle.manager must be none');
+    for (const [field, of] of [['label', 'launchd'], ['plist', 'launchd'], ['unit', 'systemd'], ['task', 'Task Scheduler']]) {
+      if (life[field] !== undefined) problems.push(`a remote service has no ${of} ${field}`);
+    }
+    if (d.commands?.update !== undefined) problems.push('a remote service declares no update command');
+  }
+  problems.push(...descriptorMemberProblems(d));
+  for (const [name, argv] of Object.entries(d.commands ?? {})) {
+    if (!['doctor', 'update'].includes(name)) problems.push(`unknown command ${name}`);
+    else if (!Array.isArray(argv) || !argv.length || !argv.every((a) => typeof a === 'string')) problems.push(`command ${name} must be an argument array`);
+    else if (!LOCAL_PATH.test(argv[0])) problems.push(`command ${name} must start with an absolute or ~/ executable`);
+  }
+  return problems;
+}
+
+/** DEC-0019: `local` unless the descriptor says `remote`. */
+
+/** The organization edition's data classes, least sensitive first (DEC-0061, DEC-0053). */
+export const PEER_DATA_CLASSES = Object.freeze(['public', 'internal', 'confidential', 'restricted']);
+
+/** The kind of a runner's sign-in, never a credential's value (DEC-0061). */
+export const CREDENTIAL_KINDS = Object.freeze(['subscription', 'key', 'platform-metered', 'none']);
+
+/** A subscription runs only in its vendor's runner (DEC-0046): runner kind → login. */
+export const SUBSCRIPTION_RUNNERS = Object.freeze({ 'claude-code': 'claude', 'kimi-code': 'kimi', codex: 'chatgpt' });
+
+const PEER_ENDPOINT = /^https:\/\/((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63})(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?(\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*)?$/;
+
+const RESIDENCY = /^(A[B-Z]|[B-PR-WY][A-Z]|Q[A-L]|Z[A-Y])$/;
+
+const RUNNER_KIND_NAME = /^[a-z][a-z0-9-]{1,62}$/;
+
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+const textOfLength = (v, low = 1, high = 200) => typeof v === 'string' && v.length >= low && v.length <= high;
+
+/** A JSON Pointer token (RFC 6901 §4). */
+const pointer = (name) => String(name).replace(/~/g, '~0').replace(/\//g, '~1');
+
+/**
+ * DEC-0061 and DEC-0069 on a descriptor's `installedBy`, `runner` and `peer`, as the schema shapes them, with FAC-SEM-085
+ * (a peer on a reserved name) and FAC-SEM-086 (a credential-shaped value in `runner` or `installedBy`, named by its
+ * place, never its value).
+ */
+export function descriptorMemberProblems(d) {
+  const problems = [];
+  const life = isObj(d.lifecycle) ? d.lifecycle : {};
+  const by = d.installedBy;
+  const places = [];
+  if (typeof by === 'string') {
+    if (!textOfLength(by)) problems.push('installedBy is the installer and its version, 1 to 200 characters');
+    places.push(['/installedBy', by]);
+  } else if (isObj(by)) {
+    for (const k of Object.keys(by)) if (!['by', 'role', 'tool'].includes(k)) problems.push(`installedBy has no member ${k}`);
+    if (!['person', 'node', 'organization'].includes(by.by)) problems.push('installedBy.by is person, node or organization');
+    if (by.by === 'person' && !['operator', 'administrator'].includes(by.role)) problems.push('installedBy.role is operator or administrator for a person');
+    if (by.by !== 'person' && 'role' in by) problems.push('installedBy.role belongs to a person only');
+    if (!textOfLength(by.tool)) problems.push('installedBy.tool is the installer and its version, 1 to 200 characters');
+    for (const [k, v] of Object.entries(by)) places.push([`/installedBy/${pointer(k)}`, v]);
+  } else problems.push("installedBy is the installer's name or {by, role?, tool}");
+  if (life.manager === 'person' && !(isObj(by) && by.by === 'person')) problems.push("an app's descriptor names who installed it as a person: installedBy {by: person, role, tool} (DEC-0069)");
+  let runner = d.runner;
+  if ('runner' in d) {
+    if (!isObj(runner)) { problems.push('runner is {kind?, credentialKind}'); runner = {}; }
+    for (const k of Object.keys(runner)) if (!['kind', 'credentialKind'].includes(k)) problems.push(`runner has no member ${k}`);
+    if (!CREDENTIAL_KINDS.includes(runner.credentialKind)) problems.push('runner.credentialKind is subscription, key, platform-metered or none');
+    if ('kind' in runner && !(typeof runner.kind === 'string' && RUNNER_KIND_NAME.test(runner.kind))) problems.push("runner.kind is a runner kind's name");
+    if (runner.credentialKind === 'subscription' && !Object.hasOwn(SUBSCRIPTION_RUNNERS, runner.kind)) problems.push("a subscription runs only in its vendor's runner: runner.kind claude-code, kimi-code or codex");
+    for (const [k, v] of Object.entries(runner)) places.push([`/runner/${pointer(k)}`, v]);
+  }
+  if ('peer' in d) {
+    let peer = d.peer;
+    if (!isObj(peer)) { problems.push('peer is {endpoint, custody, residency, maxDataClass}'); peer = {}; }
+    for (const k of Object.keys(peer)) if (!['endpoint', 'custody', 'residency', 'maxDataClass'].includes(k)) problems.push(`peer has no member ${k}`);
+    const m = typeof peer.endpoint === 'string' && peer.endpoint.length <= 2048 ? PEER_ENDPOINT.exec(peer.endpoint) : null;
+    if (!m) problems.push('peer.endpoint is https://<dns-name>[:<port>][/<path>], no query, fragment, userinfo or IP literal');
+    else if (RESERVED_HOST.test(m[1])) problems.push(`FAC-SEM-085: a service offered to others cannot be reached at the reserved name ${m[1]}`);
+    if (!['organization-managed', 'personal'].includes(peer.custody)) problems.push('peer.custody is organization-managed or personal');
+    const r = peer.residency;
+    if (!Array.isArray(r) || r.length < 1 || r.length > 32 || new Set(r.map((x) => JSON.stringify(x))).size !== r.length || !r.every((x) => typeof x === 'string' && RESIDENCY.test(x))) {
+      problems.push('peer.residency is 1 to 32 distinct ISO 3166-1 alpha-2 codes in upper case, EU admitted, no user-assigned code');
+    }
+    if (!PEER_DATA_CLASSES.includes(peer.maxDataClass)) problems.push('peer.maxDataClass is public, internal, confidential or restricted');
+    if (!('runner' in d)) problems.push('a service offered to others declares runner (DEC-0061)');
+    else if (isObj(runner) && runner.credentialKind === 'subscription') problems.push('a service offered to others never runs on a subscription (DEC-0061)');
+  }
+  for (const [place, value] of places) {
+    if (typeof value === 'string' && secretArgument(value)) problems.push(`FAC-SEM-086: ${place} holds a value shaped like a credential; it names a kind, a role or an installer`);
+  }
+  return problems;
+}
+
+/**
+ * The host's check before it routes a request from anyone but the service's operator (DEC-0061, FAC-SEM-088):
+ * `not-offered`, `peer-invalid`, `data-class-unknown` or `above-max-data-class`; null when it may. The contract's `peerRefusal`.
+ */
+export function peerRefusal(descriptor, dataClass) {
+  if (!isObj(descriptor) || !isObj(descriptor.peer)) return 'not-offered';
+  const max = typeof descriptor.peer.maxDataClass === 'string' ? PEER_DATA_CLASSES.indexOf(descriptor.peer.maxDataClass) : -1;
+  if (max < 0) return 'peer-invalid';
+  const asked = typeof dataClass === 'string' ? PEER_DATA_CLASSES.indexOf(dataClass) : -1;
+  if (asked < 0) return 'data-class-unknown';
+  return asked > max ? 'above-max-data-class' : null;
+}
+
+/**
+ * What an app that writes its own descriptor does with it on a start (DEC-0069): `keep` from a translocated copy (macOS
+ * App Translocation); otherwise `write` when there is none, when it is not an app's descriptor, or when its version
+ * (`installedBy.tool`) or its path (`lifecycle.app`) differs; `keep` otherwise. The contract's `appDescriptorAction`.
+ */
+export function appDescriptorAction(existing, tool, appPath) {
+  if (appPath.includes('/AppTranslocation/')) return 'keep';
+  if (!isObj(existing) || !isObj(existing.installedBy)) return 'write';
+  const recorded = isObj(existing.lifecycle) ? existing.lifecycle.app : undefined;
+  return existing.installedBy.tool === tool && recorded === appPath ? 'keep' : 'write';
+}
+
+/** Whether a reader treats a descriptor as stale (DEC-0069): an app's descriptor whose installed app it did not find. */
+export function appDescriptorStale(descriptor, appPresent) {
+  if (!isObj(descriptor) || !isObj(descriptor.lifecycle) || descriptor.lifecycle.manager !== 'person') return false;
+  return !appPresent;
+}
+
+/** Whether `lifecycle.app` of an app's descriptor exists on this machine (a bundle is a folder, an executable a file). */
+export function appPresent(descriptor) {
+  const app = isObj(descriptor?.lifecycle) ? descriptor.lifecycle.app : undefined;
+  try { return typeof app === 'string' && fs.existsSync(expand(app)); } catch { return false; }
+}
+
+/** Fabric's own descriptor (Fabric ADR-0139): `services/fabric.default.json`. */
+export const FABRIC_SERVICE = Object.freeze(['fabric', 'default']);
+
+/**
+ * `present` or `absent` for Fabric's button (DEC-0040 FB-5, DEC-0069, Fabric SCN-142): present when Fabric's own
+ * descriptor is registered and, for an app's descriptor, its app is still installed; a server sets `data-fabric="absent"`
+ * on the button's script otherwise. The button only follows a link, so the liveness file is not read here.
+ */
+export function fabricButtonPresence(dir = servicesDir()) {
+  let found;
+  try { found = JSON.parse(fs.readFileSync(descriptorPath(...FABRIC_SERVICE, dir), 'utf8')); } catch { return 'absent'; }
+  if (!isObj(found) || validateDescriptor(found).length) return 'absent';
+  return appDescriptorStale(found, appPresent(found)) ? 'absent' : 'present';
+}
+
+export function placementOf(d) {
+  return d?.placement === 'remote' ? 'remote' : 'local';
+}
+
+/** Problems with a remote origin: https, a public DNS name, an optional port, nothing else. */
+export function remoteOriginProblems(origin) {
+  const m = REMOTE_ORIGIN.exec(String(origin ?? ''));
+  if (!m) return ['a remote origin must be https://<dns-name>[:<port>] with no path, query or IP literal'];
+  if (RESERVED_HOST.test(m[1])) return [`a remote service cannot live on the reserved name ${m[1]}`];
+  if (m[2] !== undefined && (Number(m[2]) < 1 || Number(m[2]) > 65535)) return ['the origin port is out of range'];
+  return [];
+}
+
+export function portOf(origin) {
+  const m = ORIGIN.exec(origin);
+  if (!m) throw new ServiceError(`Origin ${origin} is not http://127.0.0.1:<port>.`);
+  return Number(m[1]);
+}
+
+export function writeDescriptor(d, dir = servicesDir()) {
+  const problems = validateDescriptor(d);
+  if (problems.length) throw new ServiceError(`Descriptor is invalid: ${problems.join('; ')}.`);
+  const me = `${d.id}.${d.instance}`;
+  // DEC-0019: only a local placement claims a port on this computer; DEC-0069: an app's descriptor names none.
+  const port = placementOf(d) === 'remote' || d.origin === undefined ? null : portOf(d.origin);
+  for (const [file, other] of readDescriptors(dir)) {
+    const key = `${other.id}.${other.instance ?? 'default'}`;
+    if (key === me) continue;
+    if (port === null) continue; // a remote origin's port is another computer's
+    let otherPort = null;
+    try { otherPort = portOf(String(other.origin ?? '')); } catch { continue; }
+    if (otherPort === port) throw new ServiceError(`Port ${port} is already claimed by ${key} (${file}).`);
+  }
+  ensurePrivateDir(dir);
+  const target = descriptorPath(d.id, d.instance, dir);
+  atomicWrite(target, `${JSON.stringify(d, null, 2)}\n`, 0o600);
+  return target;
+}
+
+export function removeDescriptor(id, instance = 'default', dir = servicesDir()) {
+  try { fs.unlinkSync(descriptorPath(id, instance, dir)); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; }
+}
+
+const THEME_ID = /^[a-z][a-z0-9-]{0,31}$/;
+
+const KIT_REF = /^[a-z][a-z0-9-]{0,63}@(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;
+
+// What makes value not a valid ED-9 declaration (service-dashboard-extension.schema.json).
+export function dashboardExtensionProblems(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return ['the declaration is not an object'];
+  const out = [];
+  const extra = Object.keys(value).filter((k) => !['minWidth', 'appearance', 'themes', 'kit'].includes(k)).sort();
+  if (extra.length) out.push(`unknown field(s): ${extra.join(', ')}`);
+  const w = value.minWidth;
+  if (!Number.isInteger(w)) out.push('minWidth is required and must be a whole number of CSS pixels');
+  else if (w < 360 || w > 1280) out.push(`minWidth ${w} is outside 360…1280`);
+  if ('appearance' in value) {
+    const a = value.appearance;
+    if (!Array.isArray(a) || a.length > 2 || new Set(a).size !== a.length || a.some((x) => x !== 'scheme' && x !== 'theme')) out.push('appearance is a list of distinct fields from scheme, theme');
+  }
+  if ('themes' in value) {
+    const t = value.themes;
+    if (!Array.isArray(t) || t.length < 1 || t.length > 32 || new Set(t).size !== t.length || t.some((x) => typeof x !== 'string' || !THEME_ID.test(x))) out.push('themes is 1…32 distinct theme ids matching ^[a-z][a-z0-9-]{0,31}$');
+  }
+  if ('kit' in value && !(typeof value.kit === 'string' && KIT_REF.test(value.kit))) out.push(`kit is name@semver, for example ${DASHBOARD_KIT}`);
+  return out;
+}
+
+// The `extensions` entry a dashboard built from the kit declares (DEC-0036 ED-9). Declare it only
+// when the page meets ED-1…ED-6 — check_dashboard_layout.mjs measures that.
+export function dashboardExtension({ minWidth = 360, appearance = ['scheme', 'theme'], themes = REFERENCE_THEMES, kit = DASHBOARD_KIT } = {}) {
+  const value = { minWidth };
+  if (appearance?.length) value.appearance = [...appearance];
+  if (themes?.length) value.themes = [...themes];
+  if (kit) value.kit = kit;
+  const problems = dashboardExtensionProblems(value);
+  if (problems.length) throw new ServiceError(`Dashboard declaration: ${problems.join('; ')}.`);
+  return { [DASHBOARD_EXTENSION_KEY]: value };
+}
+
+// `extensions` is kept as given (a reader ignores keys it does not know); a dashboard declaration in
+// it must be valid (dashboardExtension builds one).
+const PROFILE_ID = /^[a-z][a-z0-9-]{0,62}$/;
+
+const RUNNER_KIND = /^[a-z][a-z0-9-]{1,62}$/;
+
+const MODEL_ID = /^[a-z0-9][a-z0-9._-]{0,63}\/[a-z0-9][a-z0-9._:-]{0,127}$/;
+
+/** DEC-0046: the well-known `configuration` — {slots, resolved} as service-well-known.schema.json types it. */
+export function configurationProblems(doc) {
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return ['configuration is an object'];
+  const problems = Object.keys(doc).filter((k) => k !== 'slots' && k !== 'resolved').map((k) => `configuration has no member ${k}`);
+  const { slots, resolved } = doc;
+  if (!Array.isArray(slots) || slots.length > 2 || new Set(slots).size !== slots.length || !slots.every((s) => s === 'runner' || s === 'model')) problems.push('slots is a list of runner and model, each once');
+  if (resolved === null || typeof resolved !== 'object' || Array.isArray(resolved)) return [...problems, 'resolved is an object'];
+  const checks = {
+    from: (x) => ['request', 'agent', 'binding', 'estate'].includes(x),
+    runnerProfile: (x) => typeof x === 'string' && PROFILE_ID.test(x),
+    modelProfile: (x) => typeof x === 'string' && PROFILE_ID.test(x),
+    runnerKind: (x) => typeof x === 'string' && RUNNER_KIND.test(x),
+    route: (x) => ROUTES.includes(x),
+    models: (x) => Array.isArray(x) && x.length <= 16 && x.every((m) => typeof m === 'string' && MODEL_ID.test(m)),
+  };
+  for (const [k, v] of Object.entries(resolved)) {
+    if (!Object.hasOwn(checks, k)) problems.push(`resolved has no member ${k}`);
+    else if (!checks[k](v)) problems.push(`resolved.${k} is not valid`);
+  }
+  return problems;
+}
+
+export function buildWellKnown({ id, instance, name, version, build, startedAt, status, degraded = [], surfaces, summary, updateAvailable = null, pid = process.pid, extensions, configuration, protocols }) {
+  if (!STATUSES.includes(status)) throw new ServiceError(`status must be one of ${STATUSES.join(', ')}.`);
+  if (!surfaces?.events) throw new ServiceError('surfaces.events is required.');
+  if (!(build?.commit || build?.digest)) throw new ServiceError('build needs a commit or a digest.');
+  const doc = {
+    protocol: PROTOCOL,
+    service: { id, instance, name, version, build },
+    process: { pid, startedAt },
+    status: status === 'ready' && degraded.length ? 'degraded' : status,
+    degraded: [...degraded],
+    surfaces,
+    update: { available: updateAvailable },
+  };
+  if (summary?.length) doc.summary = summary.slice(0, 6);
+  if (extensions && Object.keys(extensions).length) {
+    if (DASHBOARD_EXTENSION_KEY in extensions) {
+      const problems = dashboardExtensionProblems(extensions[DASHBOARD_EXTENSION_KEY]);
+      if (problems.length) throw new ServiceError(`Dashboard declaration: ${problems.join('; ')}.`);
+    }
+    doc.extensions = { ...extensions };
+  }
+  if (configuration !== undefined) {
+    const problems = configurationProblems(configuration);
+    if (problems.length) throw new ServiceError(`configuration: ${problems.join('; ')}.`);
+    doc.configuration = configuration;
+  }
+  if (protocols !== undefined) {
+    // DEC-0067: the revisions this service accepts. The document is closed for a reader pinned before DEC-0067, so a
+    // service lists them only once its hosts are pinned at or after it.
+    const problems = protocolsFindings(protocols);
+    if (problems.length) throw new ServiceError(`protocols: ${problems.map((f) => f.message).join('; ')}.`);
+    doc.protocols = [...protocols];
+  }
+  return doc;
+}