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

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

@@ -0,0 +1,335 @@
+// OpenRouter chat completions for a service: its own key, a spend ceiling checked before every attempt, a usage receipt
+// for every answered call, and a fallback model of another vendor. The twin of fabric_openrouter.py: the same rules, the
+// same cases (test/fixtures/kit-openrouter-cases.json); the rules are written out in that file's docstring.
+//
+//   const client = new Client({ ceilingUsd: 2, ledger: new JsonlUsageLedger(file), prices: pricesFromCatalog(catalog) });
+//   const answer = await client.chat([{ role: 'user', content: '...' }],
+//     { model: 'deepseek/deepseek-v4.1-flash', fallback: 'qwen/qwen3.8-flash', maxTokens: 800 });
+//   answer.content, answer.receipt.costUsd
+//
+// The key is read from the environment variable `keyEnv` names when a call is made, sent only in the Authorization
+// header, never in an error. Before every attempt the window's spend (ledger receipts of the UTC day or month, plus
+// calls in flight) plus this attempt's worst case (one token per two UTF-8 bytes of the messages as JSON, maxTokens of
+// output, at the model's price) must stay within the ceiling. A 200 records one receipt; stop or tool_calls with
+// content is an answer; error is retried on the model; length, content_filter and empty go to the fallback; 408, 429,
+// 5xx and connection errors are retried within one deadline; 401, 402 and 403 stop at once. Attribution is off unless a
+// setting is given (FAC-SEM-098). Node 20 or newer, no dependencies. Part of the service kit (FAA-65, layer L4).
+
+import * as http from './fabric-http.mjs';
+import { isObject } from './fabric-jsvalue.mjs';
+import * as time from './fabric-time.mjs';
+import { attributionHeaders, makeUsageReceipt } from './fabric-usage.mjs';
+
+export const BASE_URL = 'https://openrouter.ai/api/v1';
+export const ANSWERED = Object.freeze(['stop', 'tool_calls']);
+const STOP_AT_ONCE = { 401: 'auth', 402: 'payment', 403: 'auth' };
+const RESERVED_PARAMS = ['model', 'messages', 'max_tokens', 'max_completion_tokens', 'maxTokens', 'stream', 'usage'];
+// Params that change what a call is billed for (other models, plugins, web search): the ceiling could not bound them.
+const UNBOUNDED_PARAMS = ['models', 'route', 'plugins', 'web_search_options', 'n'];
+
+export class OpenRouterError extends Error {
+  constructor(message, { kind, attempts = [] } = {}) {
+    super(message);
+    this.name = 'OpenRouterError';
+    this.kind = kind; // config, unpriced, ceiling, auth, payment, failed
+    this.attempts = [...attempts];
+  }
+}
+
+export const vendor = (model) => (String(model).includes('/') ? String(model).split('/', 1)[0] : '');
+
+const DECIMAL = /^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][-+]?[0-9]+)?$/;
+
+// A catalog price (a plain decimal string such as "0.000001", or a number) or null: blank, hex, a list, negative or
+// not finite are null, exactly as fabric_openrouter.py reads them.
+function price(value) {
+  let n;
+  if (typeof value === 'string') n = DECIMAL.test(value) ? Number(value) : Number.NaN;
+  else if (typeof value === 'number') n = value;
+  else return null;
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+const count = (v) => (Number.isSafeInteger(v) && v >= 0 ? v : null); // as fabric_openrouter.py: 0 to 2**53 - 1
+
+// Every message's content is text: a string, null, or parts that are all {type: 'text'}. An image, audio or file part is
+// billed in ways a byte count cannot bound, so the client does not send it.
+function textOnly(messages) {
+  return messages.every((m) => isObject(m) && (m.content === null || m.content === undefined || typeof m.content === 'string'
+    || (Array.isArray(m.content) && m.content.every((p) => isObject(p) && p.type === 'text'))));
+}
+
+// {model: {prompt, completion, request}} in USD per token (per request) from GET /api/v1/models; a model without a
+// readable prompt or completion price is left out, so the client refuses it rather than guessing.
+export function pricesFromCatalog(catalog) {
+  const out = {};
+  const rows = isObject(catalog) && Array.isArray(catalog.data) ? catalog.data : [];
+  for (const row of rows) {
+    if (!isObject(row) || typeof row.id !== 'string') continue;
+    const pricing = isObject(row.pricing) ? row.pricing : {};
+    const prompt = price(pricing.prompt);
+    const completion = price(pricing.completion);
+    if (prompt === null || completion === null) continue;
+    out[row.id] = { prompt, completion, request: price(pricing.request) ?? 0 };
+  }
+  return out;
+}
+
+// One token per two UTF-8 bytes of what is sent as compact JSON: the messages and every param, all billed as input.
+export const promptTokensBound = (value) => Math.ceil(http.jsonBytes(value).length / 2);
+
+function checkAttribution(projectId, taskRunId) {
+  try {
+    makeUsageReceipt('openrouter', 'check', { inputTokens: 0, outputTokens: 0, projectId, taskRunId });
+  } catch (err) {
+    throw new OpenRouterError(err.message, { kind: 'config' });
+  }
+}
+
+export class Client {
+  constructor({ ceilingUsd, ledger, prices, keyEnv = 'OPENROUTER_API_KEY', window = 'day', baseUrl = BASE_URL,
+    attribution = null, projectId, unmeasuredCallUsd = null, deadlineS = 120, retries = 1, env = process.env,
+    transport, sleep, clock = () => performance.now() / 1000, now = () => Date.now() / 1000, rand = Math.random } = {}) {
+    if (typeof ceilingUsd !== 'number' || !Number.isFinite(ceilingUsd) || ceilingUsd < 0) {
+      throw new OpenRouterError('ceilingUsd is a finite number of dollars, 0 or more', { kind: 'config' });
+    }
+    if (!['day', 'month'].includes(window)) throw new OpenRouterError('window is day or month (UTC)', { kind: 'config' });
+    if (!ledger || typeof ledger.record !== 'function' || typeof ledger.receipts !== 'function') {
+      throw new OpenRouterError('ledger has record(receipt) and receipts(), as JsonlUsageLedger', { kind: 'config' });
+    }
+    if (!Number.isInteger(retries) || retries < 0 || retries > 5) {
+      throw new OpenRouterError('retries is an integer from 0 to 5', { kind: 'config' });
+    }
+    http.checkUrl(baseUrl);
+    checkAttribution(projectId, undefined);
+    Object.assign(this, { ceilingUsd, ledger, keyEnv, window, attribution, projectId, unmeasuredCallUsd, deadlineS, retries });
+    this.prices = Object.fromEntries(Object.entries(prices ?? {}).map(([k, v]) => [k, { ...v }]));
+    this.baseUrl = baseUrl.replace(/\/+$/, '');
+    this.env = env;
+    this.transport = transport;
+    this.sleep = sleep ?? ((s) => new Promise((resolve) => setTimeout(resolve, s * 1000)));
+    this.clock = clock;
+    this.now = now;
+    this.rand = rand;
+    this.inFlight = 0;
+    this.unmeasuredWorst = new Map(); // `${at} ${model}` of an unmeasured receipt -> that attempt's worst case
+  }
+
+  priced(model) {
+    const p = this.prices[model];
+    if (!isObject(p)) return null;
+    const prompt = price(p.prompt);
+    const completion = price(p.completion);
+    if (prompt === null || completion === null) return null;
+    return { prompt, completion, request: price(p.request) ?? 0 };
+  }
+
+  worstCaseUsd(model, messages, maxTokens, params = {}) {
+    const p = this.priced(model);
+    if (p === null) return null;
+    return promptTokensBound({ ...params, messages }) * p.prompt + maxTokens * p.completion + p.request;
+  }
+
+  inWindow(at, today) {
+    const ms = time.parseRfc3339Ms(at);
+    if (Number.isNaN(ms)) return false;
+    const day = time.utcDay(ms);
+    return this.window === 'day' ? day === today : day.slice(0, 7) === today.slice(0, 7);
+  }
+
+  spentUsd({ unmeasuredUsd = 0 } = {}) {
+    const today = time.utcDay(this.now() * 1000);
+    let total = 0;
+    for (const r of this.ledger.receipts()) {
+      if (!isObject(r) || !this.inWindow(r.at, today)) continue;
+      if (typeof r.costUsd === 'number' && price(r.costUsd) !== null) total += r.costUsd;
+      else total += this.unmeasuredWorst.get(`${r.at} ${r.model}`) ?? unmeasuredUsd; // known here, else unmeasuredUsd
+    }
+    return total;
+  }
+
+  reserve(model, messages, maxTokens, params) {
+    const worst = this.worstCaseUsd(model, messages, maxTokens, params);
+    if (worst === null) {
+      throw new OpenRouterError(`${model} has no price: its spend cannot be bounded, so it is not called`, { kind: 'unpriced' });
+    }
+    const unmeasured = this.unmeasuredCallUsd === null ? worst : Number(this.unmeasuredCallUsd);
+    const spent = this.spentUsd({ unmeasuredUsd: unmeasured }) + this.inFlight;
+    if (spent + worst > this.ceilingUsd) {
+      throw new OpenRouterError(`the ${this.window} ceiling of $${this.ceilingUsd.toFixed(4)} would be passed: spent `
+        + `$${spent.toFixed(4)}, this attempt up to $${worst.toFixed(4)}`, { kind: 'ceiling' });
+    }
+    this.inFlight += worst; // synchronous with the check: no other call can pass between them
+    return worst;
+  }
+
+  release(amount) { this.inFlight = Math.max(0, this.inFlight - amount); }
+
+  receipt(asked, body, taskRunId, worst) {
+    const served = typeof body.model === 'string' && body.model.trim() ? body.model : asked;
+    const usage = isObject(body.usage) ? body.usage : null;
+    const common = { at: time.formatRfc3339(Math.trunc(this.now() * 1000)), route: 'key', projectId: this.projectId, taskRunId };
+    const prompt = usage ? count(usage.prompt_tokens) : null;
+    const completion = usage ? count(usage.completion_tokens) : null;
+    if (prompt === null || completion === null) {
+      const unmeasured = makeUsageReceipt('openrouter', served.slice(0, 128), { inputTokens: 0, outputTokens: 0, tokensMeasured: false, ...common });
+      this.rememberUnmeasured(unmeasured, worst);
+      return unmeasured;
+    }
+    const details = isObject(usage.prompt_tokens_details) ? usage.prompt_tokens_details : {};
+    const cached = count(details.cached_tokens) ?? 0;
+    const written = count(details.cache_write_tokens) ?? 0;
+    let cost = typeof usage.cost === 'number' ? price(usage.cost) : null;
+    let basis = 'provider';
+    if (cost === null) {
+      const p = this.priced(served) ?? this.priced(asked);
+      if (p) { cost = prompt * p.prompt + completion * p.completion; basis = 'price-list'; }
+    }
+    return makeUsageReceipt('openrouter', served.slice(0, 128), {
+      inputTokens: Math.max(0, prompt - cached - written), outputTokens: completion, cacheReadTokens: cached,
+      cacheWriteTokens: written, costUsd: cost, costBasis: cost === null ? undefined : basis, ...common,
+    });
+  }
+
+  // A receipt for an attempt that may have been billed with no usage to read: no tokens, no cost.
+  unmeasured(asked, taskRunId, worst) {
+    const receipt = makeUsageReceipt('openrouter', asked.slice(0, 128), { inputTokens: 0, outputTokens: 0, tokensMeasured: false,
+      at: time.formatRfc3339(Math.trunc(this.now() * 1000)), route: 'key', projectId: this.projectId, taskRunId });
+    this.rememberUnmeasured(receipt, worst);
+    return receipt;
+  }
+
+  rememberUnmeasured(receipt, worst) {
+    const key = `${receipt.at} ${receipt.model}`;
+    this.unmeasuredWorst.set(key, (this.unmeasuredWorst.get(key) ?? 0) + worst);
+  }
+
+  key() {
+    const key = this.env[this.keyEnv] ?? '';
+    if (!key || /[\r\n\0 ]/.test(key)) throw new OpenRouterError(`no usable key in the environment variable ${this.keyEnv}`, { kind: 'config' });
+    return key;
+  }
+
+  headers(key) {
+    const headers = { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' };
+    if (this.attribution !== null) {
+      Object.assign(headers, attributionHeaders(this.attribution, { url: this.baseUrl, originated: true, headers: {} }).headers);
+    }
+    return headers;
+  }
+
+  async chat(messages, { model, fallback, maxTokens, taskRunId, ...params } = {}) {
+    if (!Array.isArray(messages) || messages.length === 0) throw new OpenRouterError('messages is a non-empty list', { kind: 'config' });
+    if (!textOnly(messages)) {
+      throw new OpenRouterError('only text content is sent: an image, audio or file part has a cost the ceiling cannot bound', { kind: 'config' });
+    }
+    if (!vendor(model) || !vendor(fallback) || vendor(model) === vendor(fallback)) {
+      throw new OpenRouterError(`the fallback is a model of another vendor than ${model}`, { kind: 'config' });
+    }
+    if (!Number.isInteger(maxTokens) || maxTokens < 1 || maxTokens > 200_000) {
+      throw new OpenRouterError('maxTokens is an integer from 1 to 200000', { kind: 'config' });
+    }
+    checkAttribution(this.projectId, taskRunId); // before anything is sent: a billed call keeps its receipt
+    const clash = Object.keys(params).filter((k) => RESERVED_PARAMS.includes(k));
+    if (clash.length) throw new OpenRouterError(`the client sets ${clash.sort().join(', ')} itself`, { kind: 'config' });
+    const unbounded = Object.keys(params).filter((k) => UNBOUNDED_PARAMS.includes(k));
+    if (unbounded.length) {
+      throw new OpenRouterError(`${unbounded.sort().join(', ')} change what a call is billed for; the ceiling cannot bound them`, { kind: 'config' });
+    }
+    try {
+      promptTokensBound({ ...params, messages });
+    } catch {
+      throw new OpenRouterError('the request holds a number JSON cannot write (NaN or Infinity)', { kind: 'config' });
+    }
+    const headers = this.headers(this.key());
+    const url = `${this.baseUrl}/chat/completions`;
+    const end = this.clock() + this.deadlineS;
+    const attempts = [];
+    for (const current of [model, fallback]) {
+      const body = { model: current, messages, max_tokens: maxTokens, usage: { include: true }, ...params };
+      for (let tried = 0; tried <= this.retries; tried += 1) {
+        const left = end - this.clock();
+        if (left <= 0) throw new OpenRouterError(`the deadline passed after ${attempts.length} attempts`, { kind: 'failed', attempts });
+        let held;
+        try {
+          held = this.reserve(current, messages, maxTokens, params);
+        } catch (err) {
+          err.attempts = [...attempts];
+          throw err;
+        }
+        let result;
+        try {
+          result = await this.attempt(url, headers, body, left, current, taskRunId, held);
+        } finally {
+          this.release(held);
+        }
+        attempts.push({ model: current, status: result.status, outcome: result.outcome });
+        if (result.answer) return { ...result.answer, attempts };
+        if (Object.values(STOP_AT_ONCE).includes(result.outcome)) {
+          throw new OpenRouterError(`OpenRouter refused the key or the request (${result.status})`, { kind: result.outcome, attempts });
+        }
+        if (!['retry', 'error'].includes(result.outcome) || tried === this.retries) break;
+        const wait = result.wait ?? http.backoffS(tried, { baseS: 0.5, maxS: 8, rand: this.rand() });
+        if (this.clock() + wait >= end) break;
+        await this.sleep(wait);
+      }
+    }
+    throw new OpenRouterError(`no answer from ${model} or ${fallback}`, { kind: 'failed', attempts });
+  }
+
+  async attempt(url, headers, body, left, asked, taskRunId, worst) {
+    let response;
+    try {
+      response = await http.request('POST', url, { headers, body, deadlineS: left, retries: 0, transport: this.transport, clock: this.clock });
+    } catch (err) {
+      if (!(err instanceof http.HttpError)) throw err;
+      if (['timeout', 'connection'].includes(err.kind) || (err.kind === 'too-large' && err.status === 200)) {
+        // may have been billed (a cut connection looks like a refused one from here): counted, never as $0
+        this.ledger.record(this.unmeasured(asked, taskRunId, worst));
+      }
+      return { outcome: ['connection', 'timeout'].includes(err.kind) ? 'retry' : 'refused', status: err.status };
+    }
+    const { status } = response;
+    if (STOP_AT_ONCE[status]) return { outcome: STOP_AT_ONCE[status], status };
+    if (status !== 200) {
+      if (http.RETRY_STATUSES.includes(status)) return { outcome: 'retry', status, wait: http.retryAfterS(response.headers['retry-after'] ?? null) };
+      return { outcome: 'refused', status };
+    }
+    let parsed = null;
+    try { parsed = response.json(); } catch { /* read as no answer below */ }
+    if (!isObject(parsed)) {
+      this.ledger.record(this.unmeasured(asked, taskRunId, worst));
+      return { outcome: 'bad-answer', status };
+    }
+    let receipt;
+    try {
+      receipt = this.receipt(asked, parsed, taskRunId, worst);
+    } catch {
+      this.ledger.record(this.unmeasured(asked, taskRunId, worst)); // a billed answer it cannot read still counts
+      return { outcome: 'bad-answer', status };
+    }
+    this.ledger.record(receipt);
+    const choice = Array.isArray(parsed.choices) && isObject(parsed.choices[0]) ? parsed.choices[0] : {};
+    const message = isObject(choice.message) ? choice.message : {};
+    const finish = choice.finish_reason;
+    const content = typeof message.content === 'string' ? message.content : '';
+    const tools = Array.isArray(message.tool_calls) ? message.tool_calls : [];
+    if (finish === 'error' || isObject(parsed.error)) return { outcome: 'error', status };
+    if (finish === 'length') return { outcome: 'length', status };
+    if (finish === 'content_filter') return { outcome: 'filtered', status };
+    if (!ANSWERED.includes(finish) || !(content.trim() || tools.length)) return { outcome: 'empty', status };
+    return { outcome: 'answered', status, answer: { content, message, model: receipt.model, finishReason: finish, receipt } };
+  }
+}
+
+// Calls, priced spend and unpriced calls over receipts; spentUsd is null when every call is unpriced.
+export function totals(receipts) {
+  let calls = 0;
+  let priced = 0;
+  let spent = 0;
+  for (const r of receipts) {
+    calls += 1;
+    if (typeof r.costUsd === 'number' && price(r.costUsd) !== null) { priced += 1; spent += r.costUsd; }
+  }
+  return { calls, spentUsd: priced ? spent : null, unpricedCalls: calls - priced };
+}

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

@@ -31,9 +31,15 @@ const SECRET_FILE = /^(\.env(\..+)?|.*\.(pem|key|p12|pfx|jks|keystore)|id_(rsa|d
 const SECRET_FILE_OK = /^\.env\.(example|sample|template)$/;
 const B64URL = /^[A-Za-z0-9_-]+$/;
 const PKCS8_ED25519 = Buffer.from('302e020100300506032b657004220420', 'hex');
-const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
-const isString = (v) => typeof v === 'string';
-const objects = (v) => (Array.isArray(v) ? v.filter(isObject) : []);
+/**
+ * How deep a document read from disk may nest. Python's recursion limit and Node's stack give out at different depths,
+ * so both readers refuse past this one, well below either (FAA-78, finding 43); no package document comes near it.
+ */
+export const MAX_NESTING = 256;
+/** Strict UTF-8: invalid bytes are a refusal, never replaced, so the bytes read are the bytes signed (finding 43). */
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+import { isObject, objects, jsonEqual } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
+import { isString } from './fabric-jsvalue.mjs'; // the core's (FAA-65)
 
 /** A refusal a person can act on; the message names what to change. */
 export class PackageError extends Error {}
@@ -49,7 +55,15 @@ export const sha256Of = (data) => `sha256:${crypto.createHash('sha256').update(d
 /** SHA-256 over the UTF-8 RFC 8785 form of the package without digest and signatures (DEC-0050). */
 export function packageDigest(pkg) {
   const { digest: _d, signatures: _s, ...covered } = pkg;
-  return sha256Of(Buffer.from(jcs(covered), 'utf8'));
+  let text;
+  try {
+    text = jcs(covered);
+  } catch (error) {
+    // Nested past the stack: no form this kit can write, as Python's RecursionError is none.
+    if (error instanceof RangeError) throw new TypeError('the package nests too deeply to have an RFC 8785 form');
+    throw error;
+  }
+  return sha256Of(Buffer.from(text, 'utf8'));
 }
 
 /** The bytes a package signature covers (DEC-0051); the role is inside, so no signature stands for another role. */
@@ -116,18 +130,11 @@ export function readSigningKey(file, kid) {
 let schemaCache;
 const schema = () => (schemaCache ??= JSON.parse(fs.readFileSync(SCHEMA_FILE, 'utf8')));
 
-function jsonEqual(a, b) {
-  if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x, i) => jsonEqual(x, b[i]));
-  if (isObject(a) || isObject(b)) {
-    if (!isObject(a) || !isObject(b)) return false;
-    const ka = Object.keys(a);
-    return ka.length === Object.keys(b).length && ka.every((k) => Object.hasOwn(b, k) && jsonEqual(a[k], b[k]));
-  }
-  return a === b;
-}
 
 const typeOf = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v === 'number' ? (Number.isInteger(v) ? 'integer' : 'number') : typeof v);
-const DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-](\d{2}):(\d{2}))$/;
+const DATE_TIME = /^([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]([0-9]{2}):([0-9]{2}):([0-9]{2})(\.[0-9]+)?([Zz]|[+-]([0-9]{2}):([0-9]{2}))$/;
+const MONTH_DAYS = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+const leap = (year) => year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
 
 function formatOk(format, value) {
   if (!isString(value)) return true;
@@ -135,8 +142,9 @@ function formatOk(format, value) {
     const m = DATE_TIME.exec(value);
     if (!m) return false;
     const [y, mo, d, h, mi, s] = m.slice(1, 7).map(Number);
-    const days = new Date(Date.UTC(y, mo, 0)).getUTCDate();
-    if (mo < 1 || mo > 12 || d < 1 || d > days || h > 23 || mi > 59 || s > 59) return false;
+    // The proleptic calendar the contract's ajv-formats checks: year 0000 exists and is a leap year (0000-02-29 holds).
+    // Counted here, not with Date.UTC, which reads years 0 to 99 as 1900 to 1999.
+    if (mo < 1 || mo > 12 || d < 1 || d > (mo === 2 && leap(y) ? 29 : MONTH_DAYS[mo]) || h > 23 || mi > 59 || s > 59) return false;
     return m[8] === 'Z' || m[8] === 'z' || (Number(m[9]) < 24 && Number(m[10]) < 60);
   }
   if (format === 'uri') return /^[A-Za-z][A-Za-z0-9+.-]*:\S*$/.test(value);
@@ -299,6 +307,50 @@ function mcpRoles(value) {
   return findings;
 }
 
+// --- the path rule (FAA-78, finding 40; decision D5) -------------------------------------------------------------------
+
+/** C0 and C1 controls, DEL, and the two Unicode line terminators JavaScript's `.` stops at. */
+const control = (code) => code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0x2028 || code === 0x2029;
+
+/**
+ * Why `p` is no packaged path, or null. The schema's pattern says the same in one expression, but JavaScript's `.`
+ * stops at U+2028 and U+2029, so here and in the contract's own ajv its look-aheads never see a `..`, a backslash or a
+ * `//` after one (`a\u2028/../../etc/passwd` passes there). This rule reads the path character by character in both
+ * kits, and refuses C1 controls, DEL and the line terminators besides. A non-string is the schema's to refuse.
+ */
+export function pathProblem(p) {
+  if (!isString(p)) return null;
+  const chars = [...p];
+  if (chars.length < 1 || chars.length > 256) return 'a path is 1 to 256 characters';
+  if (chars.some((ch) => control(ch.codePointAt(0)))) return 'a path carries no control character and no line or paragraph separator';
+  if (p[0] === '/' || p[0] === '~') return 'a path is relative to the package folder: it never starts with / or ~';
+  if (p.includes('\\') || p.includes(':')) return 'a path is written with forward slashes and no colon';
+  if (p.includes('//') || p.endsWith('/')) return 'a path names a file: no empty segment and no trailing slash';
+  if (p.split('/').some((segment) => segment === '.' || segment === '..')) return 'a path never steps through . or ..';
+  return null;
+}
+
+/** Every member the schema types as a path, by its JSON pointer. */
+function pathFields(pkg) {
+  const fields = [['/provider', pkg.provider]];
+  if (isObject(pkg.evals)) fields.push(['/evals/suite', pkg.evals.suite]);
+  for (const name of ['state', 'dependencies', 'files']) {
+    (Array.isArray(pkg[name]) ? pkg[name] : []).forEach((entry, index) => { if (isObject(entry)) fields.push([`/${name}/${index}/path`, entry.path]); });
+  }
+  return fields.filter(([, value]) => value !== undefined);
+}
+
+/** The path rule over every path the package names: `{instancePath, message}` per path refused. */
+export function pathProblems(pkg) {
+  if (!isObject(pkg)) return [];
+  const out = [];
+  for (const [instancePath, value] of pathFields(pkg)) {
+    const message = pathProblem(value);
+    if (message !== null) out.push({ instancePath, message });
+  }
+  return out;
+}
+
 /** FAC-SEM-064 (whole), 065 (no secret), 066 (agentRef derived) and 102 (one role, one server), in that order. */
 export const packageFindings = (pkg) => [...whole(pkg), ...noSecret(pkg), ...agentRefRule(pkg), ...mcpRoles(pkg)];
 
@@ -307,7 +359,7 @@ export const packageFindings = (pkg) => [...whole(pkg), ...noSecret(pkg), ...age
 const parsed = (bytes) => {
   if (bytes === undefined) return undefined;
   try {
-    const value = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    const value = JSON.parse(strictUtf8.decode(bytes)); // invalid UTF-8 is no manifest, in both kits
     return isObject(value) ? value : undefined;
   } catch {
     return undefined;
@@ -399,10 +451,37 @@ export function consumerPlacement(pkg, configured) {
 const litter = (name) => (JUNK.test(name) ? 'litter' : SECRET_FILE.test(name) && !SECRET_FILE_OK.test(name) ? 'a credential file' : null);
 const utf16Order = (a, b) => (a < b ? -1 : a > b ? 1 : 0); // JavaScript compares strings by UTF-16 code units
 
+/** Opening a packaged file: never through a link (where the platform can say so), never waiting on a pipe (finding 42). */
+const FILE_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+/** What open() answers for a link it was told not to follow: ELOOP on Linux and macOS, EMLINK on FreeBSD. */
+const LINK_CODES = new Set(['ELOOP', 'EMLINK']);
+
+const unreadable = (where, error) => new PackageError(`Cannot read ${where || '.'}: ${error.code ?? error.message}.`);
+
+/** The file's bytes, or the reason it is not read: a link, or not a regular file. Throws the system's error. */
+function readRegular(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, FILE_FLAGS);
+  } catch (error) {
+    if (fs.constants.O_NOFOLLOW !== undefined && LINK_CODES.has(error.code)) return { why: 'a symlink' };
+    throw error;
+  }
+  try {
+    if (!fs.fstatSync(fd).isFile()) return { why: 'not a regular file' };
+    return { bytes: fs.readFileSync(fd) };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
 /**
  * Every regular file under `folder` by its forward-slash path. Refuses a symlink, a special file, version-control or
- * cache litter, and a file that is a credential by its name — each named, so the person can remove it or pack a clean
- * copy.
+ * cache litter, and a file that is a credential by its name, each named, so the person can remove it or pack a clean
+ * copy. A file or folder it cannot read is a refusal naming it (`Cannot read <path>: EACCES.`), never a crash (FAA-78,
+ * finding 41); a file is opened without following a link and read only when it is a regular file (finding 42). Node
+ * has no openat, so a folder swapped for a link mid-walk is checked by lstat before and after it is listed; the Python
+ * twin holds each folder open instead.
  */
 export function readFolder(folder) {
   let stat;
@@ -411,12 +490,31 @@ export function readFolder(folder) {
   const files = new Map();
   const refused = [];
   const walk = (dir, rel) => {
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => utf16Order(a.name, b.name))) {
+    let entries;
+    let before;
+    try {
+      before = rel ? fs.lstatSync(dir) : null;
+      entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => utf16Order(a.name, b.name));
+    } catch (error) {
+      throw unreadable(rel, error);
+    }
+    if (before && !before.isDirectory()) { refused.push(`${rel} (a symlink)`); return; }
+    for (const entry of entries) {
       const where = rel ? `${rel}/${entry.name}` : entry.name;
-      const why = entry.isSymbolicLink() ? 'a symlink' : litter(entry.name) ?? (entry.isDirectory() || entry.isFile() ? null : 'not a regular file');
-      if (why) { refused.push(`${where} (${why})`); continue; }
-      if (entry.isDirectory()) walk(path.join(dir, entry.name), where);
-      else files.set(where, fs.readFileSync(path.join(dir, entry.name)));
+      let why = entry.isSymbolicLink() ? 'a symlink' : litter(entry.name) ?? (entry.isDirectory() || entry.isFile() ? null : 'not a regular file');
+      if (!why && entry.isDirectory()) { walk(path.join(dir, entry.name), where); continue; }
+      if (!why) {
+        let read;
+        try { read = readRegular(path.join(dir, entry.name)); } catch (error) { throw unreadable(where, error); }
+        if (read.why === undefined) { files.set(where, read.bytes); continue; }
+        why = read.why;
+      }
+      refused.push(`${where} (${why})`);
+    }
+    if (before) {
+      let after;
+      try { after = fs.lstatSync(dir); } catch (error) { throw unreadable(rel, error); }
+      if (!after.isDirectory() || after.ino !== before.ino || after.dev !== before.dev) refused.push(`${rel} (a symlink)`);
     }
   };
   walk(folder, '');
@@ -424,8 +522,15 @@ export function readFolder(folder) {
   return files;
 }
 
-/** JSON.parse that refuses a member named twice in one object, as the Python kit's reader does. */
-function parseStrict(text, what) {
+/**
+ * A JSON object from strict UTF-8 bytes (a string is taken as decoded already): no member named twice, nesting at most
+ * MAX_NESTING deep, as the Python kit's reader. Every refusal is a PackageError.
+ */
+function parseStrict(input, what) {
+  let text = input;
+  if (typeof input !== 'string') {
+    try { text = strictUtf8.decode(input); } catch (error) { throw new PackageError(`${what} is not JSON: ${error.message}`); }
+  }
   let value;
   try { value = JSON.parse(text); } catch (error) { throw new PackageError(`${what} is not JSON: ${error.message}`); }
   const stack = [];
@@ -433,6 +538,7 @@ function parseStrict(text, what) {
   const skipString = () => { i += 1; let s = ''; while (text[i] !== '"') { if (text[i] === '\\') { s += text.slice(i, i + 2); i += 2; } else { s += text[i]; i += 1; } } i += 1; return JSON.parse(`"${s}"`); };
   while (i < text.length) {
     const c = text[i];
+    if ((c === '{' || c === '[') && stack.length >= MAX_NESTING) throw new PackageError(`${what} nests deeper than ${MAX_NESTING} levels.`);
     if (c === '{') { stack.push({ keys: new Set(), expectKey: true }); i += 1; } else if (c === '[') { stack.push(null); i += 1; } else if (c === '}' || c === ']') { stack.pop(); i += 1; } else if (c === ',') { const top = stack.at(-1); if (top) top.expectKey = true; i += 1; } else if (c === '"') {
       const top = stack.at(-1);
       const s = skipString();
@@ -461,20 +567,28 @@ export function compose(draft, files) {
     throw new PackageError(`agentRef is derived, never chosen: it is ${agentRefOf(draft.publisher, draft.id)} for this publisher and id (FAC-SEM-066). Remove agentRef or fix publisher/id.`);
   }
   const pkg = {};
+  // A member is defined, never assigned: `pkg.__proto__ = v` would set the prototype and drop the member, where the
+  // Python twin keeps it for the schema to refuse (finding 43).
+  const put = (key, value) => Object.defineProperty(pkg, key, { value, enumerable: true, writable: true, configurable: true });
   for (const [key, value] of Object.entries(draft)) {
     if (key === 'files' || key === 'digest' || key === 'signatures' || (agent && key === 'agentRef')) continue;
-    pkg[key] = value;
-    if (agent && key === 'publisher') pkg.agentRef = agentRefOf(draft.publisher, draft.id);
+    put(key, value);
+    if (agent && key === 'publisher') put('agentRef', agentRefOf(draft.publisher, draft.id));
   }
   if (Array.isArray(draft.signatures) && draft.signatures.length) notes.push(`dropped ${draft.signatures.length} signature(s): a repacked package is signed again`);
   pkg.files = [...files.keys()].filter((p) => p !== PACKAGE_FILE).sort(utf16Order).map((p) => ({ path: p, sha256: sha256Of(files.get(p)) }));
-  pkg.digest = packageDigest(pkg);
+  try {
+    pkg.digest = packageDigest(pkg);
+  } catch (error) {
+    throw new PackageError(`fabric.package.json has no RFC 8785 form, so it has no digest: ${error.message}`);
+  }
   return { pkg, notes };
 }
 
 function allProblems(pkg, files) {
   return [
     ...schemaProblems(pkg).map((p) => ({ ...p, rule: 'schema' })),
+    ...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: p.problem })),
   ];
@@ -493,7 +607,7 @@ export function pack(folder, { apply = false } = {}) {
   if (!files.has(PACKAGE_FILE)) {
     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).toString('utf8'), PACKAGE_FILE);
+  const draft = parseStrict(files.get(PACKAGE_FILE), PACKAGE_FILE);
   const { pkg, notes } = compose(draft, files);
   const problems = allProblems(pkg, files);
   const suite = isObject(pkg.evals) ? pkg.evals.suite : undefined;
@@ -511,7 +625,7 @@ export function pack(folder, { apply = false } = {}) {
 function packed(folder) {
   const files = readFolder(folder);
   if (!files.has(PACKAGE_FILE)) throw new PackageError(`${folder} has no ${PACKAGE_FILE}: pack it first.`);
-  return { pkg: parseStrict(files.get(PACKAGE_FILE).toString('utf8'), PACKAGE_FILE), files };
+  return { pkg: parseStrict(files.get(PACKAGE_FILE), PACKAGE_FILE), files };
 }
 
 /**
@@ -575,7 +689,7 @@ export function main(argv, print = (line) => process.stdout.write(`${line}\n`))
       answer = sign(folder, flags.key, { role: flags.role ?? 'publisher', kid: flags.kid, apply: Boolean(flags.apply) });
     } else {
       let trustText;
-      try { trustText = fs.readFileSync(flags.trust, 'utf8'); } catch (error) { throw new PackageError(`Cannot read ${flags.trust}: ${error.code ?? error.message}.`); }
+      try { trustText = fs.readFileSync(flags.trust); } catch (error) { throw new PackageError(`Cannot read ${flags.trust}: ${error.code ?? error.message}.`); }
       answer = verify(folder, parseStrict(trustText, flags.trust), { countersigned: Boolean(flags.countersigned) });
     }
   } catch (error) {