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

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

@@ -11,7 +11,7 @@
 // Node's own crypto: ES256 through createPublicKey (JWK) and verify (DER), EdDSA through Ed25519.
 
 import crypto from 'node:crypto';
-import { jcs } from './fabric-delegation.mjs';
+import { jcs } from './fabric-jsvalue.mjs';
 import { normalIdentifier } from './fabric-identifiers.mjs';
 import { secretValue } from './fabric-secrets.mjs';
 
@@ -23,28 +23,7 @@ export const CLOCK_SKEW_SECONDS = 60;
 export const ASSERTION_ALGORITHMS = Object.freeze(['ES256', 'EdDSA']);
 export const FLAGS = Object.freeze({ UP: 0x01, UV: 0x04, BE: 0x08, BS: 0x10, AT: 0x40, ED: 0x80 });
 
-const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const isString = (value) => typeof value === 'string';
-const list = (value) => (Array.isArray(value) ? value.filter(isObject) : []);
-/** The object items of an array with their index as written, so an instancePath names the item even after a non-object. */
-const indexed = (value) => (Array.isArray(value) ? value.flatMap((item, index) => (isObject(item) ? [[item, index]] : [])) : []);
-/** The contract's `show`: String(value), or its JSON where String() throws (an object whose own `toString` is data). */
-const show = (value) => {
-  if (typeof value === 'string') return value;
-  try {
-    return String(value);
-  } catch {
-    return JSON.stringify(value) ?? typeof value;
-  }
-};
-/** The contract's `toNumber`: Number(value), or NaN where Number() throws. */
-const toNumber = (value) => {
-  try {
-    return Number(value);
-  } catch {
-    return Number.NaN;
-  }
-};
+import { isObject, isString, objects as list, indexed, show, toNumber, keyOf } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
 /** DEC-0082: the personal context, and an organization's context `org:<orgId>` (the contract's `context-route.ts`). */
 export const PERSONAL_CONTEXT = 'personal';
 export const ORG_CONTEXT_PREFIX = 'org:';
@@ -59,43 +38,15 @@ export function parseContext(value) {
 }
 /** A placement's or a secret placement's context: its `context`, `personal` when absent (DEC-0082). */
 const contextOf = (entry) => (entry.context === undefined ? PERSONAL_CONTEXT : entry.context);
-/** A collision-free key over JSON values. */
-const keyOf = (...parts) => JSON.stringify(parts);
-const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest();
+import { sha256, isSmallOrderOrMalformed as smallOrder, isValidP256Key } from './fabric-crypto.mjs'; // the core's (FAA-65)
+export { isValidP256Key };
 const B64URL = /^[A-Za-z0-9_-]+$/;
 const bytes = (text) => Buffer.from(text, 'base64url');
 const canonical = (text) => Buffer.from(text, 'base64url').toString('base64url') === text;
 
-const SMALL_ORDER = new Set([
-  '0000000000000000000000000000000000000000000000000000000000000000', '0100000000000000000000000000000000000000000000000000000000000000',
-  '26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05', 'c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a',
-  'ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f', 'edffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
-  'eeffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f',
-]);
-/** The contract's isSmallOrderKey: a key that is not 32 bytes counts as one too. */
-function smallOrder(raw) {
-  if (raw.length !== 32) return true;
-  const cleared = Buffer.from(raw);
-  cleared[31] &= 0x7f;
-  return SMALL_ORDER.has(cleared.toString('hex'));
-}
 
-// ---- P-256 (DEC-0053; SEC 1 v2 §3.2.2) ----
-
-const P = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn;
-const 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 >= P || y >= P) return false;
-  const left = (y * y) % P;
-  const right = (((x * x) % P) * x - 3n * x + B) % P;
-  return left === ((right % P) + P) % P;
-}
+
+
 
 // ---- WebAuthn Level 3 §7.2, offline ----
 
@@ -180,17 +131,8 @@ export const estateChallengeInput = (digest) => Buffer.from(jcs({ type: ESTATE_C
 /** The WebAuthn challenge a signer passes to navigator.credentials.get(): SHA-256 of estateChallengeInput. */
 export const estateChallenge = (digest) => sha256(estateChallengeInput(digest));
 
-const RFC3339 = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
-/** An RFC 3339 date-time as milliseconds, or NaN: `T`, an offset and a day that exists; a space and `:60` refused (ER-10). */
-export function estateTime(value) {
-  const match = isString(value) ? RFC3339.exec(value) : null;
-  if (!match) return Number.NaN;
-  const [year, month, day, hour, minute, second] = match.slice(1, 7).map(Number);
-  const date = new Date(0);
-  date.setUTCFullYear(year, month - 1, day);
-  if (date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day || hour > 23 || minute > 59 || second > 59) return Number.NaN;
-  return Date.parse(value);
-}
+import { parseRfc3339Ms as estateTime, clockMs as clockOf } from './fabric-time.mjs'; // the core's (FAA-65)
+export { estateTime };
 const LABEL = '[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?';
 /** `sign.` and at least two more labels, lower case: a signing RP ID is never a bare `sign.<tld>` (DEC-0063). */
 const SIGNING_RP = new RegExp(`^sign(?:\\.${LABEL}){2,}$`);
@@ -220,7 +162,6 @@ function signingCredential(credential, path, flag) {
 }
 
 const revocationKey = (entry) => `${String(entry.kind)} ${String(entry.ref)}`;
-const clockOf = (at) => (at instanceof Date ? at.getTime() : (typeof at === 'number' && Number.isFinite(at) ? at * 1000 : Number.NaN));
 
 /**
  * The reference verifier, in the order of estate-record.md's ER table. `at` is the clock (a Date, or epoch seconds); pass
@@ -297,6 +238,7 @@ export function verifyEstateRecord(record, trust) {
  * undefined when the record places no such agent there in that context.
  */
 export function placementTrust(record, machineId, agentRef, context = PERSONAL_CONTEXT) {
+  if (!isObject(record)) return undefined; // a record that is no object places nothing, as in the Python twin
   const machine = list(record.machines).find((entry) => entry.id === machineId);
   const placement = list(machine?.packages).find((entry) => entry.agentRef === agentRef && contextOf(entry) === context);
   if (!placement) return undefined;
@@ -437,7 +379,8 @@ function keys(value, flag) {
     if (deviceKeys.filter((key) => key.use === 'sig').length !== 1) flag(`${at}/deviceKeys`, 'a machine has exactly one signing device key, <id>#sig');
     if (deviceKeys.filter((key) => key.use === 'kem').length > 1) flag(`${at}/deviceKeys`, 'a machine has at most one key-agreement device key, <id>#kem');
     const seen = new Set();
-    deviceKeys.forEach((key, k) => {
+    // The index is the key's position in the list as written, non-objects counted, as the contract and the Python twin name it.
+    indexed(machine.deviceKeys).forEach(([key, k]) => {
       if (key.kid !== `${show(machine.id)}#${show(key.use)}`) flag(`${at}/deviceKeys/${k}/kid`, 'a device key is listed as <machine id>#sig or <machine id>#kem, by its role');
       // A key with no canonical fingerprint could be read as two keys by two readers, and no key reference names it (DEC-0084).
       if (deviceKeyFingerprint(key) === undefined) flag(`${at}/deviceKeys/${k}/publicKey`, "a device key's octets are written in canonical padded base64, the one form a key reference can name (DEC-0084)");

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

@@ -0,0 +1,52 @@
+// A service's events (DEC-0029): making them, paging them and the JSONL event log.
+// Part of the Node service kit (FAA-65, layer L3); the twin of fabric_events.py. Node 20+, no dependency.
+import { ServiceError } from './fabric-base.mjs';
+import { feedDataProblems } from './fabric-protocols.mjs';
+
+export const LEVELS = ['info', 'notice', 'warning', 'error'];
+
+export const EVENTS_DEFAULT_LIMIT = 50;
+
+export const EVENTS_MAX_LIMIT = 200;
+
+const KIND = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){0,5}$/;
+
+const TRACE_ID = /^(?!0{32}$)[0-9a-f]{32}$/;
+
+const SPAN_ID = /^(?!0{16}$)[0-9a-f]{16}$/;
+
+/** One activity event. `data` (DEC-0070) adds machine-readable fields, `{schema, value}`, never a secret: refused here, so no feed carries one. */
+export function makeEvent(id, at, kind, level, text, { subject, link, notify, traceId, spanId, data } = {}) {
+  if (!LEVELS.includes(level)) throw new ServiceError(`level must be one of ${LEVELS.join(', ')}.`);
+  if (!KIND.test(kind)) throw new ServiceError(`kind ${kind} must be dotted lowercase.`);
+  const sentence = String(text).split(/\s+/).filter(Boolean).join(' ');
+  if (!sentence) throw new ServiceError('An event needs a sentence.');
+  if (link !== undefined && (!link.startsWith('/') || link.startsWith('//'))) throw new ServiceError('link must be a path on this service.');
+  if ((traceId === undefined) !== (spanId === undefined)) throw new ServiceError('An event carries traceId and spanId together, or neither.');
+  if (traceId !== undefined && !(TRACE_ID.test(traceId) && SPAN_ID.test(spanId))) throw new ServiceError('traceId is 32 and spanId 16 lowercase hex characters, not all zeros.');
+  const event = { id: String(id), at, kind, level, text: sentence.slice(0, 500) };
+  if (subject) event.subject = subject;
+  if (link) event.link = link;
+  if (notify) event.notify = true;
+  if (traceId !== undefined) Object.assign(event, { traceId, spanId });
+  if (data !== undefined) {
+    const problems = feedDataProblems(data);
+    if (problems.length) throw new ServiceError(`Event data: ${problems.join('; ')}.`);
+    event.data = { schema: data.schema, value: data.value };
+  }
+  return event;
+}
+
+export function parseLimit(raw) {
+  if (raw === undefined || raw === null || raw === '') return EVENTS_DEFAULT_LIMIT;
+  const n = Number(raw);
+  if (!Number.isInteger(n)) throw new ServiceError('limit must be an integer.');
+  return Math.max(1, Math.min(EVENTS_MAX_LIMIT, n));
+}
+
+// fetch(after, limit) returns events with ids greater than `after`, ascending
+// (or the newest `limit`, ascending, when after is null) — a view over the log you already keep.
+export async function eventsPage(fetch, after, limit) {
+  const events = (await fetch(after ?? null, limit)).slice(0, limit);
+  return { events, cursor: events.length ? events.at(-1).id : (after ?? null) };
+}

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

@@ -0,0 +1,231 @@
+// An outbound HTTP client for a service: one deadline across every attempt, bounded retries with jittered backoff,
+// `Retry-After` honoured up to a cap, a response size cap, and no secret in an error. The twin of fabric_http.py:
+// the same rules, the same cases (test/fixtures/kit-http-cases.json).
+//
+//   const response = await request('GET', 'https://api.example/v1/items', { headers: {...}, deadlineS: 20, retries: 2 });
+//   response.status, response.headers['content-type'], response.json()
+//
+// What is retried: a status in RETRY_STATUSES or a connection error, at most `retries` times, and only when repeating
+// is safe: an idempotent method or an `Idempotency-Key` header; any other request only on 429. The wait before retry n
+// (from 0) is min(maxBackoffS, backoffBaseS * 2**n) * (0.5 + rand()); a `Retry-After` replaces it up to
+// maxRetryAfterS. A wait past the deadline is not taken. Plain http is refused unless the host is loopback or
+// `insecure`. An error names the method and the redacted URL, never a header or a body.
+//
+// The transport is injected in tests: async ({ method, url, headers, body, timeoutS, maxBytes }) =>
+// { status, headers, body: Uint8Array }, throwing on a connection error (a `TimeoutError` name is a timeout) or an
+// HttpError. Node 20 or newer, no dependencies. Part of the service kit (FAA-65, layer L4).
+
+export const RETRY_STATUSES = Object.freeze([408, 425, 429, 500, 502, 503, 504]);
+export const IDEMPOTENT_METHODS = Object.freeze(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
+export const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+export class HttpError extends Error {
+  constructor(message, { status = null, url = '', attempts = 0, retryAfterS = null, body = new Uint8Array(0),
+    kind = 'http' } = {}) {
+    super(message);
+    this.name = 'HttpError';
+    this.status = status;
+    this.url = url;
+    this.attempts = attempts;
+    this.retryAfterS = retryAfterS;
+    this.body = body.slice(0, 2048);
+    this.kind = kind; // http, connection, timeout, too-large, refused
+  }
+}
+
+export class Response {
+  constructor(status, headers, body, { attempts = 1, url = '' } = {}) {
+    this.status = status;
+    this.headers = Object.fromEntries(Object.entries(headers).map(([k, v]) => [String(k).toLowerCase(), String(v)]));
+    this.body = body;
+    this.attempts = attempts;
+    this.url = url;
+  }
+
+  get ok() { return this.status >= 200 && this.status < 300; }
+
+  text() { return new TextDecoder().decode(this.body); }
+
+  json() { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(this.body)); }
+}
+
+// The URL as it may appear in an error or a log line: scheme, host, port and path; no userinfo, query or fragment.
+export function redactUrl(url) {
+  let parts;
+  try { parts = new URL(String(url)); } catch { return '<unparseable url>'; }
+  return `${parts.protocol}//${parts.host}${parts.pathname}`;
+}
+
+function isLoopback(host) {
+  const h = host.replace(/^\[|\]$/g, '');
+  if (h === 'localhost' || h.endsWith('.localhost') || h === '::1') return true;
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+
+// Refuse what this client never sends: another scheme, no host, credentials in the URL, plain http off loopback.
+export function checkUrl(url, { insecure = false } = {}) {
+  let parts;
+  try { parts = new URL(String(url)); } catch {
+    throw new HttpError('the URL does not parse', { url: redactUrl(url), kind: 'refused' });
+  }
+  if (!['http:', 'https:'].includes(parts.protocol) || !parts.hostname) {
+    throw new HttpError('only http and https URLs with a host are sent', { url: redactUrl(url), kind: 'refused' });
+  }
+  if (parts.username || parts.password || /^[a-z]+:\/*[^/?#]*@/i.test(String(url).trim())) {
+    throw new HttpError('credentials in a URL are refused: send them in a header', { url: redactUrl(url), kind: 'refused' });
+  }
+  if (parts.protocol === 'http:' && !insecure && !isLoopback(parts.hostname)) {
+    throw new HttpError('plain http to a host that is not loopback is refused (insecure to allow)',
+      { url: redactUrl(url), kind: 'refused' });
+  }
+}
+
+const IMF_FIXDATE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d\d) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d\d):(\d\d):(\d\d) GMT$/;
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+// Seconds a `Retry-After` asks for: a non-negative integer, or an IMF-fixdate read from `now` (epoch seconds),
+// never below 0; null otherwise.
+export function retryAfterS(value, { now } = {}) {
+  if (value === null || value === undefined) return null;
+  const text = String(value).trim();
+  if (/^[0-9]{1,10}$/.test(text)) return Number(text);
+  const m = IMF_FIXDATE.exec(text);
+  if (!m) return null;
+  const [day, month, year, hh, mm, ss] = [Number(m[2]), MONTHS.indexOf(m[3]), Number(m[4]), Number(m[5]),
+    Number(m[6]), Number(m[7])];
+  const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+  if (hh > 23 || mm > 59 || ss > 60 || day < 1 || day > lastDay || year < 1000) return null; // Date.UTC maps 0-99
+  const when = Date.UTC(year, month, day, hh, mm, Math.min(ss, 59)) / 1000;
+  return Math.max(0, when - (now ?? Date.now() / 1000));
+}
+
+// Compact JSON in UTF-8, NaN and Infinity refused (JSON.stringify would write null): the twin of json_bytes.
+export function jsonBytes(value) {
+  const text = JSON.stringify(value, (key, v) => {
+    if (typeof v === 'number' && !Number.isFinite(v)) {
+      throw new HttpError('the body holds a number JSON cannot write (NaN or Infinity)', { kind: 'refused' });
+    }
+    return v;
+  });
+  return new TextEncoder().encode(text);
+}
+
+export function backoffS(attempt, { baseS, maxS, rand }) {
+  return Math.min(maxS, baseS * 2 ** attempt) * (0.5 + rand);
+}
+
+export function mayRetry(method, headers, status) {
+  if (status !== null && !RETRY_STATUSES.includes(status)) return false;
+  const safe = IDEMPOTENT_METHODS.includes(String(method).toUpperCase())
+    || Object.keys(headers).some((k) => k.toLowerCase() === 'idempotency-key');
+  return safe || status === 429;
+}
+
+function checkHeaders(headers) {
+  const out = {};
+  for (const [name, value] of Object.entries(headers)) {
+    const v = String(value);
+    if (!TOKEN.test(String(name))) throw new HttpError('a header name is not an HTTP token', { kind: 'refused' });
+    if (/[\r\n\0]/.test(v)) throw new HttpError('a header value carries a line break or NUL', { kind: 'refused' });
+    out[String(name)] = v;
+  }
+  return out;
+}
+
+// The default transport: fetch, no redirects followed, the body read to one byte past maxBytes.
+export async function fetchTransport({ method, url, headers, body, timeoutS, maxBytes }) {
+  const res = await fetch(url, { method, headers, body: body ?? undefined, redirect: 'manual',
+    signal: AbortSignal.timeout(Math.max(1, Math.ceil(timeoutS * 1000))) });
+  const chunks = [];
+  let size = 0;
+  if (res.body) {
+    const reader = res.body.getReader();
+    try {
+      while (size <= maxBytes) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+        size += value.length;
+      }
+    } finally {
+      await reader.cancel().catch(() => {});
+    }
+  }
+  const all = new Uint8Array(size);
+  let at = 0;
+  for (const c of chunks) { all.set(c, at); at += c.length; }
+  return { status: res.status, headers: Object.fromEntries(res.headers.entries()), body: all.slice(0, maxBytes + 1) };
+}
+
+const sleepMs = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000));
+
+export async function request(method, url, {
+  headers = {}, body = null, deadlineS = 30, retries = 2, maxBytes = DEFAULT_MAX_BYTES, backoffBaseS = 0.5,
+  maxBackoffS = 8, maxRetryAfterS = 30, insecure = false, transport = fetchTransport, sleep = sleepMs,
+  clock = () => performance.now() / 1000, rand = Math.random,
+} = {}) {
+  method = String(method).toUpperCase();
+  if (!TOKEN.test(method)) throw new HttpError('the method is not an HTTP token', { kind: 'refused' });
+  if (!Number.isInteger(retries) || retries < 0 || retries > 10) {
+    throw new HttpError('retries is an integer from 0 to 10', { kind: 'refused' });
+  }
+  if (!(deadlineS > 0 && maxBytes > 0)) throw new HttpError('deadlineS and maxBytes are positive', { kind: 'refused' });
+  checkUrl(url, { insecure });
+  const sent = checkHeaders(headers ?? {});
+  let data = null;
+  if (body === null || body === undefined) data = null;
+  else if (body instanceof Uint8Array) data = body;
+  else if (body instanceof ArrayBuffer) data = new Uint8Array(body);
+  else if (typeof body === 'string') data = new TextEncoder().encode(body);
+  else if (typeof body === 'object') {
+    data = jsonBytes(body);
+    if (!Object.keys(sent).some((k) => k.toLowerCase() === 'content-type')) sent['Content-Type'] = 'application/json';
+  } else throw new HttpError('the body is bytes, a string, an object or an array', { kind: 'refused' });
+  const where = redactUrl(url);
+  const end = clock() + deadlineS;
+  let attempt = 0;
+  for (;;) {
+    const left = end - clock();
+    if (left <= 0) {
+      throw new HttpError(`${method} ${where}: the deadline passed before an answer`,
+        { url: where, attempts: attempt, kind: 'timeout' });
+    }
+    attempt += 1;
+    let got = null;
+    let failure = null;
+    try {
+      got = await transport({ method, url, headers: { ...sent }, body: data, timeoutS: left, maxBytes });
+    } catch (err) {
+      if (err instanceof HttpError) throw err;
+      failure = err?.name === 'TimeoutError' || err?.name === 'AbortError'
+        ? new HttpError(`${method} ${where}: timed out`, { url: where, attempts: attempt, kind: 'timeout' })
+        : new HttpError(`${method} ${where}: connection error (${err?.name ?? 'Error'})`,
+          { url: where, attempts: attempt, kind: 'connection' });
+    }
+    let answer = null;
+    let wait;
+    if (failure === null) {
+      if (got.body.length > maxBytes) {
+        throw new HttpError(`${method} ${where}: the answer is over ${maxBytes} bytes`,
+          { status: got.status, url: where, attempts: attempt, kind: 'too-large' });
+      }
+      answer = new Response(got.status, got.headers, got.body, { attempts: attempt, url: where });
+      if (!mayRetry(method, sent, answer.status) || attempt > retries) return answer;
+      wait = retryAfterS(answer.headers['retry-after'] ?? null);
+      if (wait !== null) {
+        if (wait > maxRetryAfterS) return answer;
+      } else {
+        wait = backoffS(attempt - 1, { baseS: backoffBaseS, maxS: maxBackoffS, rand: rand() });
+      }
+    } else {
+      if (!mayRetry(method, sent, null) || attempt > retries) throw failure;
+      wait = backoffS(attempt - 1, { baseS: backoffBaseS, maxS: maxBackoffS, rand: rand() });
+    }
+    if (clock() + wait >= end) {
+      if (answer !== null) return answer;
+      throw failure;
+    }
+    await sleep(wait);
+  }
+}

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

@@ -147,8 +147,8 @@ const ERROR_CODE = /^[a-z][a-z0-9-]{1,63}$/;
 const MAX_STATUS_MESSAGE = 500;
 const MAX_ERROR_MESSAGE = 2000;
 const codePoints = (value) => [...value].length;
-const isString = (value) => typeof value === 'string';
-const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+import { isString } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
+import { isObject } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
 const own = (value, key) => (isObject(value) && Object.hasOwn(value, key) ? value[key] : undefined);
 
 /** A UTC instant as milliseconds, or NaN: the pattern and a day that exists, as the contract's strictTime reads it. */
@@ -347,6 +347,15 @@ export function urlRequest(message, url) {
 }
 
 // --- C3.2 jobs: the same file format as fabric_interop.JobStore ------------------------------
+const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+
+/** What a key is kept beside (FAA-77): sha256 of the RFC 8785 form of [capability, input]; an input with none is refused. */
+export function intentDigest(capability, input) {
+  let form;
+  try { form = jcs([capability, input]); } catch { throw new InteropError("A job's input with an idempotency key needs a JSON form (RFC 8785)."); }
+  return `sha256:${crypto.createHash('sha256').update(form, 'utf8').digest('hex')}`;
+}
+
 export class JobStore {
   constructor(dir) { this.dir = dir; }
 
@@ -370,36 +379,63 @@ export class JobStore {
 
   // With idempotencyKey the key is kept per caller (the authenticated caller, DEC-0087): a key that already names a job
   // starts nothing and throws, unless repeat() answers 'run'; then the key names the new job.
+  // The key is kept beside the intent's digest (FAA-77): a key that names a job of another intent is idempotency-conflict.
+  // A key file a kit before 0.41.0 wrote carries no intent: it is answered with its job as 0.40.0 answered it (see repeat).
   create(capability, input, { traceparent, pollIntervalMs, caller = null, idempotencyKey, now, limitHolds, approvalGranted = false } = {}) {
+    let intent = null;
     if (idempotencyKey !== undefined) {
-      const decision = this.repeat(caller, idempotencyKey, now ?? nowIso(), { limitHolds, approvalGranted });
+      intent = intentDigest(capability, input);
+      const decision = this.repeat(caller, idempotencyKey, now ?? nowIso(), { limitHolds, approvalGranted, capability, input });
+      if (decision.decision === 'conflict') throw new InteropError(`idempotency-conflict: key ${idempotencyKey} names a job of another intent; send the same capability and input, or a new key.`);
       if (decision.decision === 'same') throw new InteropError(`Key ${idempotencyKey} already names job ${decision.job.id}; answer with that job (JobStore.repeat).`);
     }
     const id = `job_${crypto.randomBytes(12).toString('hex')}`;
     const job = { id, status: 'working' };
     if (pollIntervalMs) job.pollIntervalMs = Math.trunc(pollIntervalMs);
     this.save({ job, private: { capability, input, traceparent: parseTraceparent(traceparent) ? traceparent : null } });
-    if (idempotencyKey !== undefined) atomicWrite(this.keyFile(caller, idempotencyKey), `${JSON.stringify({ job: id })}\n`, 0o600);
+    if (idempotencyKey !== undefined) atomicWrite(this.keyFile(caller, idempotencyKey), `${JSON.stringify({ job: id, intent })}\n`, 0o600);
     return { job: { id, status: 'working' } };
   }
 
   keyFile(caller, key) {
     if (typeof key !== 'string' || key.length === 0) throw new InteropError('An idempotency key is a non-empty string.');
+    if (LONE_SURROGATE.test(key) || (typeof caller === 'string' && LONE_SURROGATE.test(caller))) throw new InteropError('An idempotency key and its caller are Unicode text; a lone surrogate is refused.');
     const dir = path.join(this.dir, 'keys');
     ensurePrivateDir(dir);
     return path.join(dir, `${crypto.createHash('sha256').update(JSON.stringify([caller ?? null, key]), 'utf8').digest('hex')}.json`);
   }
 
-  // The answer to a key this caller sent before: {decision: 'new'|'same'|'run', job}.
-  repeat(caller, key, now, options = {}) {
-    let id;
-    try { id = JSON.parse(fs.readFileSync(this.keyFile(caller, key), 'utf8')).job; } catch (e) {
-      if (e.code === 'ENOENT') return { decision: 'new', job: null };
-      throw new InteropError(`Key ${key} is unreadable on disk.`);
+  keyRecord(caller, key) {
+    let record;
+    try { record = JSON.parse(fs.readFileSync(this.keyFile(caller, key), 'utf8')); } catch (e) {
+      if (e.code === 'ENOENT') return null;
+      if (e instanceof InteropError) throw e;
     }
+    if (record === null || typeof record !== 'object' || Array.isArray(record)) throw new InteropError(`Key ${key} is unreadable on disk.`);
+    return record;
+  }
+
+  // The answer to a key this caller sent before: {decision: 'new'|'same'|'run'|'conflict', job}. 'same': answer with
+  // that job; 'run': the intent runs again, once; 'conflict': given options.capability (and options.input), the key was
+  // kept beside another intent (idempotency-conflict, FAA-77). A key file a kit before 0.41.0 wrote holds only
+  // {"job": id}, no intent: it never answers 'conflict', and 'run' only for the intent its job stored; otherwise 'same'.
+  repeat(caller, key, now, options = {}) {
+    const record = this.keyRecord(caller, key);
+    if (record === null) return { decision: 'new', job: null };
+    const id = record.job;
+    if (typeof id !== 'string') throw new InteropError(`Key ${key} is unreadable on disk.`);
     let job;
     try { job = this.get(id); } catch (e) { if (e instanceof UnknownJob) return { decision: 'new', job: null }; throw e; }
-    return { decision: repeatedKeyDecision(job, now, options), job };
+    let decision = repeatedKeyDecision(job, now, options);
+    if (options.capability === undefined || options.capability === null) return { decision, job };
+    const intent = intentDigest(options.capability, options.input ?? null);
+    if (Object.hasOwn(record, 'intent')) return { decision: record.intent !== intent ? 'conflict' : decision, job };
+    // A 0.40.0 key runs only the intent its job stored (an input with no JSON form is refused, as the Python kit refuses it).
+    if (decision === 'run') {
+      const stored = this.load(id).private ?? {};
+      if (intentDigest(stored.capability ?? null, stored.input ?? null) !== intent) decision = 'same';
+    }
+    return { decision, job };
   }
 
   get(jobId) { return { ...this.load(jobId).job }; }
@@ -448,11 +484,9 @@ export class JobStore {
   // A job a limit paused and its provider will resume: working, the pause grammar, pollIntervalMs reaching the reset.
   pause(jobId, { resetsAt, text } = {}) {
     const statusMessage = pauseMessage({ resetsAt, text });
-    if (resetsAt !== undefined) {
-      const wait = utcTime(resetsAt) - Date.now();
-      if (wait > 0) { const record = this.load(jobId); record.job.pollIntervalMs = Math.trunc(Math.min(wait, 3600000)); this.save(record); }
-    }
-    return this.transition(jobId, 'working', { statusMessage });
+    const wait = resetsAt === undefined ? 0 : utcTime(resetsAt) - Date.now();
+    // One write, after the terminal check: a terminal job does not change, pollIntervalMs included (finding 11).
+    return this.transition(jobId, 'working', { statusMessage, pollIntervalMs: wait > 0 ? Math.trunc(Math.min(wait, 3600000)) : undefined });
   }
 
   // A job a limit stopped and its provider will not resume: failed, quota-exhausted, data {retryable, resetsAt?}.

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

@@ -0,0 +1,67 @@
+// JavaScript's view of JSON values, once for the whole Node kit (FAA-65, layer L0); the twin of fabric_jsvalue.py.
+// The contract's answers are computed by TypeScript; every reader in the kit takes these helpers from here:
+// isObject, isString, objects (an array's object items), indexed (with their index as written), show (the
+// contract's `show`), toNumber (the contract's `toNumber`), keyOf, jsonEqual (the contract's `jsonEqual`) and jcs
+// (RFC 8785). Node 20+, no dependency; nothing here imports another kit module.
+
+/** A plain JSON object (not null, not an array). */
+export const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const isString = (value) => typeof value === 'string';
+/** The object items of an array; [] for anything else. */
+export const objects = (value) => (Array.isArray(value) ? value.filter(isObject) : []);
+/** The object items of an array with their index as written, so an instancePath names the item even after a non-object. */
+export const indexed = (value) => (Array.isArray(value) ? value.flatMap((item, index) => (isObject(item) ? [[item, index]] : [])) : []);
+
+/** The contract's `show`: String(value), or its JSON where String() throws (an object whose own `toString` is data). */
+export function show(value) {
+  if (typeof value === 'string') return value;
+  try {
+    return String(value);
+  } catch {
+    return JSON.stringify(value) ?? typeof value;
+  }
+}
+
+/** The contract's `toNumber`: Number(value), or NaN where Number() throws. */
+export function toNumber(value) {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+}
+
+/** A collision-free key over JSON values. */
+export const keyOf = (...parts) => JSON.stringify(parts);
+
+/** The contract's jsonEqual: arrays in order, objects by their members whatever the order, anything else by ===. */
+export 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;
+}
+
+/** 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`);
+}