@passioncode-ai/fabric-agent-adapter 0.26.0 → 0.28.0

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

@@ -0,0 +1,337 @@
+// The Fabric hub's door, as a service agent reaches it (fabric-hub/0.1; Fabric ADR-0115 §1, ADR-0149 §4; FAA-12b).
+// The twin of fabric_hub.py, same rules and the same answers; Node built-ins only.
+//
+// 1. Find the hub, every time: locateHub() re-reads hub.json beside Fabric's registry (macOS
+//    ~/Library/Application Support/ai.passioncode.fabric, Windows %LOCALAPPDATA%\passioncode-fabric, Linux
+//    $XDG_DATA_HOME/passioncode-fabric) the way Fabric's own locateHub does: a small regular file, never a link or a
+//    FIFO; protocol fabric-hub/0.1; origin exactly http://127.0.0.1:<port>; MCP at /mcp; a door token file inside the
+//    registry root; a pid that is alive. The port does not prove who holds it, so a binding credential is sent only
+//    after this check passes, done again before each send.
+// 2. Ask once, keep the credential in a file: requestBoardAccess() asks for the board.respond grant through the door;
+//    pollAccess() writes the credential, shown once, to a 0600 file and answers without it. Tokens live in files and
+//    headers only — never argv, a URL, a log line or an error text.
+// 3. Join the board: joinBoard() calls fabric.board.join {projectId} and answers a BoardGrant (a one-session bearer
+//    that fabric-board.mjs's BoardSession spends with one MCP initialize). Without a grant: HubError not_authorized
+//    whose data.ask holds the fabric.access.request arguments.
+//
+// Fabric down: every call throws HubError with retryable true; Backoff gives the bounded, jittered wait (2 s doubling to
+// 5 minutes), so nothing spins. fabric-hub/0.1 publishes no hub key; a later hub.json naming hubKey {kid, x} is
+// checked with fabric-estate.mjs's hubKeyCertified when the caller passes an estate record, refused with DEC-0060's
+// own detail.
+
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { atomicWrite, ensurePrivateDir, readToken } from './fabric-service.mjs';
+import { hubKeyCertified } from './fabric-estate.mjs';
+
+export const HUB_PROTOCOL = 'fabric-hub/0.1';
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+export const READ_CAP = 64 * 1024;
+const LOOPBACK_ORIGIN = /^http:\/\/127\.0\.0\.1:(\d{4,5})$/;
+const TOKEN = /^[A-Za-z0-9_-]{43}$/;
+const UUID = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const CAPABILITY = /^[a-z][a-z0-9._-]{1,127}$/;
+
+/** A typed refusal or fault: code, one-sentence message, retryable, data (never a secret). */
+export class HubError extends Error {
+  constructor(code, message, retryable = false, data = {}) {
+    super(message);
+    this.name = 'HubError';
+    this.code = code;
+    this.retryable = retryable;
+    this.data = data ?? {};
+  }
+}
+
+/** Fabric's registry root, where hub.json lives (Fabric agentRegistry.ts#registryDirs). */
+export function fabricRoot(platform = process.platform, env = process.env) {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  if (platform === 'darwin') return path.join(home, 'Library/Application Support/ai.passioncode.fabric');
+  if (platform === 'win32') return path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'passioncode-fabric');
+  return path.join(env.XDG_DATA_HOME || path.join(home, '.local/share'), 'passioncode-fabric');
+}
+
+/** Whether a process with this id runs as this user (Fabric hub.ts#pidAlive): EPERM is another user's process. */
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readSmall(file) {
+  const info = fs.lstatSync(file);
+  if (!info.isFile() || info.size > READ_CAP) return null;
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+  try {
+    if (!fs.fstatSync(fd).isFile()) return null;
+    const buf = Buffer.alloc(READ_CAP + 1);
+    let got = 0;
+    for (;;) {
+      const n = fs.readSync(fd, buf, got, buf.length - got, null);
+      if (n === 0) break;
+      got += n;
+      if (got > READ_CAP) return null;
+    }
+    return buf.subarray(0, got).toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * hub.json read the way an agent must, every call. Answers {origin, mcpUrl, doorTokenFile, pid, startedAt, features} or
+ * throws HubError (not-running, retryable; not-a-hub). Reads no token. `estate` is {record, applied}: with it, a hubKey
+ * the document names is checked by hubKeyCertified (DEC-0060); fabric-hub/0.1 names none.
+ */
+export function locateHub(root = fabricRoot(), { alive = pidAlive, estate, now } = {}) {
+  const hubFile = path.join(root, 'hub.json');
+  const notHub = (reason) => new HubError('not-a-hub', `Fabric's hub.json ${reason}.`);
+  let text;
+  try {
+    text = readSmall(hubFile);
+  } catch (e) {
+    if (e.code === 'ENOENT') throw new HubError('not-running', 'Fabric is not running: there is no hub.json.', true);
+    throw new HubError('not-a-hub', `Fabric's hub.json could not be read (${e.code ?? 'error'}).`, true);
+  }
+  if (text === null) throw notHub('is not a small regular file');
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    throw notHub('is not JSON');
+  }
+  if (!doc || typeof doc !== 'object' || doc.protocol !== HUB_PROTOCOL) throw notHub(`does not speak ${HUB_PROTOCOL}`);
+  const origin = typeof doc.origin === 'string' ? doc.origin : '';
+  const m = LOOPBACK_ORIGIN.exec(origin);
+  if (!m || Number(m[1]) < 1024 || Number(m[1]) > 65535) throw notHub('names an origin that is not the loopback literal');
+  if (doc.mcp !== '/mcp') throw notHub('names another MCP path');
+  if (!Number.isInteger(doc.pid) || doc.pid <= 0) throw notHub('names no process');
+  const tokenFile = typeof doc.doorTokenFile === 'string' ? doc.doorTokenFile : '';
+  let sameRoot = false;
+  try {
+    sameRoot = path.isAbsolute(tokenFile) && fs.realpathSync(path.dirname(tokenFile)) === fs.realpathSync(root);
+  } catch {
+    sameRoot = false;
+  }
+  if (!sameRoot) throw notHub('names a door token outside the registry root');
+  if (!alive(doc.pid)) throw new HubError('not-running', `Fabric is not running: hub.json names process ${doc.pid}, which is not running.`, true);
+  const features = Array.isArray(doc.features) ? doc.features.filter((f) => typeof f === 'string') : [];
+  if (estate && doc.hubKey && typeof doc.hubKey === 'object') {
+    const verdict = hubKeyCertified(estate.record, doc.hubKey.kid, doc.hubKey.x, now ?? Date.now() / 1000, estate.applied ?? undefined);
+    if (!verdict.certified) throw new HubError('hub-key-refused', `The estate record does not certify the hub's key (${verdict.detail}).`, false, { fault: verdict.fault, detail: verdict.detail });
+  }
+  return { origin, mcpUrl: `${origin}/mcp`, doorTokenFile: tokenFile, pid: doc.pid, startedAt: doc.startedAt, features };
+}
+
+/** The door token hub.json names: a 0600 file of this user, never a link, 43 base64url characters. */
+export function readDoorToken(location) {
+  let token;
+  try {
+    token = readToken(location.doorTokenFile);
+  } catch (e) {
+    if (e.code === 'ENOENT') throw new HubError('not-running', 'Fabric is starting or stopping: its door token is not there.', true);
+    throw new HubError('not-a-hub', `The door token file is not one Fabric writes (${e.message}).`);
+  }
+  if (!TOKEN.test(token)) throw new HubError('not-a-hub', 'The door token is not one Fabric writes.');
+  return token;
+}
+
+/** A binding credential from its 0600 file: 43 base64url characters. */
+export function readCredential(file) {
+  let token;
+  try {
+    token = readToken(file);
+  } catch (e) {
+    if (e.code === 'ENOENT') throw new HubError('credential', `No binding credential at ${file}: ask for the grant first (requestBoardAccess).`);
+    throw new HubError('credential', e.message);
+  }
+  if (!TOKEN.test(token)) throw new HubError('credential', `The file ${file} does not hold a Fabric binding credential.`);
+  return token;
+}
+
+/**
+ * One MCP request to <origin>/mcp with a bearer in the header; only http://127.0.0.1:<port>, no proxy. Answers
+ * {status, headers, body} (body parsed JSON or null; an SSE answer read to its first data: line). A refused connection
+ * is HubError hub-unavailable (retryable).
+ */
+export function postMcp(origin, body, bearer, { session, timeout = 15000, method = 'POST', protocolVersion } = {}) {
+  const m = LOOPBACK_ORIGIN.exec(origin);
+  if (!m) return Promise.reject(new HubError('not-a-hub', 'Only the hub\'s loopback origin is used.'));
+  const payload = method === 'DELETE' ? null : Buffer.from(JSON.stringify(body));
+  const headers = { authorization: `Bearer ${bearer}`, 'content-type': 'application/json', accept: 'application/json, text/event-stream', host: `127.0.0.1:${m[1]}` };
+  if (session) headers['mcp-session-id'] = session;
+  if (protocolVersion) headers['mcp-protocol-version'] = protocolVersion;
+  if (payload) headers['content-length'] = String(payload.length);
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port: Number(m[1]), path: '/mcp', method, headers, timeout, agent: false }, (res) => {
+      const chunks = [];
+      let size = 0;
+      res.on('data', (c) => {
+        size += c.length;
+        if (size <= 4 * 1024 * 1024) chunks.push(c);
+      });
+      res.on('end', () => {
+        let text = Buffer.concat(chunks).toString('utf8');
+        if (String(res.headers['content-type'] ?? '').includes('text/event-stream')) {
+          text = (text.split(/\r?\n/).find((l) => l.startsWith('data:')) ?? '').slice(5).trim();
+        }
+        let parsed = null;
+        try {
+          parsed = text.trim() ? JSON.parse(text) : null;
+        } catch {
+          parsed = null;
+        }
+        resolve({ status: res.statusCode, headers: res.headers, body: parsed });
+      });
+      res.on('error', () => reject(new HubError('hub-unavailable', 'Fabric\'s hub did not answer (the answer broke off).', true)));
+    });
+    req.on('timeout', () => req.destroy(new Error('timeout')));
+    req.on('error', (e) => reject(new HubError('hub-unavailable', `Fabric's hub did not answer (${e.code ?? e.message}).`, true)));
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+/** A tools/call answer as an object: structuredContent, else the first text content parsed. */
+export function toolAnswer({ status, body }, tool) {
+  if (status === 401) throw new HubError('credential', `The hub refused the credential for ${tool}.`);
+  if (status === 429 || status >= 500) throw new HubError('hub-unavailable', `Fabric's hub could not take ${tool} just now (HTTP ${status}).`, true);
+  if (status !== 200 || !body || typeof body !== 'object') throw new HubError('protocol', `Fabric's hub answered ${tool} with HTTP ${status} and no MCP answer.`, true);
+  if (body.error) throw new HubError('protocol', `Fabric refused ${tool}: ${String(body.error?.message ?? 'an MCP error').slice(0, 200)}`);
+  const result = body.result;
+  if (!result || typeof result !== 'object') throw new HubError('protocol', `Fabric's answer to ${tool} has no result.`);
+  let value = result.structuredContent;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    const text = Array.isArray(result.content) && result.content[0] && typeof result.content[0].text === 'string' ? result.content[0].text : null;
+    try {
+      value = text === null ? null : JSON.parse(text);
+    } catch {
+      value = null;
+    }
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new HubError('protocol', `Fabric's answer to ${tool} is not a JSON object.`);
+  return value;
+}
+
+/** What fabric.board.join handed out. The bearer is a private field, kept off JSON and inspection. */
+export class BoardGrant {
+  #bearer;
+  constructor(bearer, sessionId, projectId, capabilities, origin, pid) {
+    this.#bearer = bearer;
+    this.sessionId = sessionId;
+    this.projectId = projectId;
+    this.capabilities = [...capabilities];
+    this.origin = origin;
+    this.pid = pid;
+  }
+  bearer() {
+    return this.#bearer;
+  }
+}
+
+/** The grant's resource, board:<project>/<capability> (ADR-0149 §2). */
+export const boardResource = (projectId, capability) => `board:${projectId}/${capability}`;
+
+/** A Project id as Fabric's board compares it: a uuid lower-cased; other ids are opaque, compared as written (DEC-0077). */
+export function normalProject(projectId) {
+  if (typeof projectId !== 'string' || !UUID.test(projectId)) throw new HubError('protocol', 'fabric.board.join takes a Project id that is a uuid.');
+  return projectId.toLowerCase();
+}
+
+/** The door client. Every call re-reads hub.json first. `alive` and `post` are seams for tests. */
+export class HubClient {
+  constructor(root = fabricRoot(), { alive = pidAlive, timeout = 15000, estate, post = postMcp } = {}) {
+    Object.assign(this, { root, alive, timeout, estate, post });
+    this.rpc = 0;
+  }
+
+  locate() {
+    return locateHub(this.root, { alive: this.alive, estate: this.estate });
+  }
+
+  async #call(bearerOf, tool, args) {
+    const location = this.locate(); // the pid check, right before the credential leaves this process
+    const bearer = bearerOf(location);
+    this.rpc += 1;
+    const answer = await this.post(location.origin, { jsonrpc: '2.0', id: this.rpc, method: 'tools/call', params: { name: tool, arguments: args } }, bearer, { timeout: this.timeout });
+    const value = toolAnswer(answer, tool);
+    if (value.error && typeof value.error === 'object' && typeof value.error.code === 'string') {
+      const data = value.error.data && typeof value.error.data === 'object' ? value.error.data : {};
+      throw new HubError(value.error.code, String(value.error.message ?? 'refused').slice(0, 300), value.error.code === 'hub-unavailable', data);
+    }
+    return value;
+  }
+
+  callDoor(tool, args) {
+    return this.#call(readDoorToken, tool, args);
+  }
+
+  callBinding(tool, args, credentialFile) {
+    return this.#call(() => readCredential(credentialFile), tool, args);
+  }
+
+  /** Ask the operator, once, to let agentId answer capabilities for projectId (fabric.access.request, board.respond). */
+  async requestBoardAccess(agentId, projectId, capabilities, reason) {
+    const project = normalProject(projectId);
+    const caps = [...(capabilities ?? [])];
+    if (!caps.length || caps.some((c) => typeof c !== 'string' || !CAPABILITY.test(c))) throw new HubError('protocol', 'Name at least one capability, each [a-z][a-z0-9._-]{1,127}.');
+    return this.callDoor('fabric.access.request', { agentId, callee: 'fabric', capabilities: ['board.respond'], resources: caps.map((c) => boardResource(project, c)), reason });
+  }
+
+  /** Read the request through the door; on Allow the credential is written to credentialFile (0600) and left out. */
+  async pollAccess(requestId, pollSecret, credentialFile) {
+    const answer = await this.callDoor('fabric.access.status', { requestId, pollSecret });
+    const { credential, ...rest } = answer;
+    if (typeof credential === 'string') {
+      if (!TOKEN.test(credential)) throw new HubError('protocol', 'Fabric handed out a credential this kit does not recognise; nothing was saved.');
+      ensurePrivateDir(path.dirname(credentialFile));
+      atomicWrite(credentialFile, credential, 0o600);
+      rest.credentialSaved = true;
+    }
+    return rest;
+  }
+
+  /** fabric.board.join {projectId}: a board session for one Project. */
+  async joinBoard(projectId, credentialFile) {
+    const project = normalProject(projectId);
+    let answer;
+    try {
+      answer = await this.callBinding('fabric.board.join', { projectId: project }, credentialFile);
+    } catch (e) {
+      if (e instanceof HubError && (e.code === 'not_authorized' || e.code === 'not-authorized')) {
+        throw new HubError('not_authorized', 'The operator has not let this agent answer requests for that Project: ask with fabric.access.request (callee fabric, capability board.respond, resource board:<project>/<capability>).',
+          false, { ask: { callee: 'fabric', capabilities: ['board.respond'], resources: [boardResource(project, '<capability>')] } });
+      }
+      throw e;
+    }
+    const s = answer.session;
+    if (!s || typeof s !== 'object' || typeof s.bearer !== 'string' || typeof s.sessionId !== 'string') throw new HubError('protocol', 'fabric.board.join answered no board session.');
+    if (s.projectId !== project) throw new HubError('protocol', 'fabric.board.join answered a session for another Project.');
+    const caps = Array.isArray(s.capabilities) ? s.capabilities.filter((c) => typeof c === 'string') : [];
+    const location = this.locate();
+    return new BoardGrant(s.bearer, s.sessionId, project, caps, location.origin, location.pid);
+  }
+}
+
+/** Bounded exponential backoff with jitter: first seconds doubling to cap, ±jitter, never under floor. */
+export class Backoff {
+  constructor({ first = 2, cap = 300, jitter = 0.2, floor = 1, rand = Math.random } = {}) {
+    Object.assign(this, { first, cap, jitter, floor, rand });
+    this.attempt = 0;
+  }
+  next() {
+    const base = Math.min(this.cap, this.first * 2 ** Math.min(this.attempt, 32));
+    this.attempt += 1;
+    const wait = base * (1 + this.jitter * (2 * this.rand() - 1));
+    return Math.max(this.floor, Math.min(this.cap, wait));
+  }
+  reset() {
+    this.attempt = 0;
+  }
+}

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

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
+import { normalIdentifier } from './fabric-identifiers.mjs';
 import { credentialName, secretArgument, secretUrl, secretValue } from './fabric-secrets.mjs';
 
 export const PROTOCOL = 'fabric-service/0.1';
@@ -1016,7 +1017,11 @@ const COUNTS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTok
  * One model call, from the provider's own usage numbers. No prompt, output or caller.
  * `costUsd` null means it cannot be priced: the report counts it as unpriced, never as $0.
  */
-export function makeUsageReceipt(provider, model, { inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0, costUsd = null, costBasis, at, route } = {}) {
+/**
+ * One model call. `projectId` (a URI, kept in its normal form, DEC-0076) and `taskRunId` (the service's own run id) attribute
+ * it to the project the service ran it for (DEC-0065); they never name a caller, session or person.
+ */
+export function makeUsageReceipt(provider, model, { inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0, costUsd = null, costBasis, at, route, projectId, taskRunId } = {}) {
   if (!PROVIDER.test(provider ?? '')) throw new ServiceError('provider must be a lowercase name such as anthropic or openrouter.');
   model = String(model ?? '').trim();
   if (!model || model.length > 128) throw new ServiceError('model must be 1 to 128 characters.');
@@ -1026,7 +1031,34 @@ export function makeUsageReceipt(provider, model, { inputTokens, outputTokens, c
   const basis = costBasis ?? (costUsd === null ? 'unknown' : 'provider');
   if (!COST_BASES.includes(basis) || (costUsd === null) !== (basis === 'unknown')) throw new ServiceError('costBasis is provider or price-list with a cost, unknown without one.');
   if (route !== undefined && !USAGE_ROUTES.includes(route)) throw new ServiceError('route is subscription, key or platform-metered (DEC-0046, DEC-0061).');
-  return { at: at ?? nowIso(), provider, model, ...counts, costUsd, costBasis: basis, ...(route === undefined ? {} : { route }) };
+  if (taskRunId !== undefined && projectId === undefined) throw new ServiceError('a task run belongs to a project: give projectId with taskRunId.');
+  if (projectId !== undefined && !(typeof projectId === 'string' && /^[A-Za-z][A-Za-z0-9+.-]*:\S+$/.test(projectId))) throw new ServiceError('projectId is the URI of the project the service ran the call for.');
+  if (taskRunId !== undefined && !(typeof taskRunId === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(taskRunId))) throw new ServiceError("taskRunId is the service's own run id: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$.");
+  return { at: at ?? nowIso(), provider, model, ...counts, costUsd, costBasis: basis, ...(route === undefined ? {} : { route }),
+    ...(projectId === undefined ? {} : { projectId: normalIdentifier(projectId) }), ...(taskRunId === undefined ? {} : { taskRunId }) };
+}
+
+/** DEC-0065's `byProject`: the window's calls by project (normal form, DEC-0076), each task run once within it. */
+function byProject(receipts, first, last) {
+  const projects = new Map();
+  const add = (row, r) => { row.calls += 1; if (r.costUsd === null || r.costUsd === undefined) row.unpricedCalls += 1; else row.cost += r.costUsd; };
+  for (const r of receipts) {
+    const date = String(r.at ?? '').slice(0, 10);
+    if (date < first || date > last || !r.projectId) continue;
+    if (!projects.has(r.projectId)) projects.set(r.projectId, { projectId: r.projectId, calls: 0, unpricedCalls: 0, cost: 0, runs: new Map() });
+    const row = projects.get(r.projectId);
+    add(row, r);
+    if (r.taskRunId) {
+      if (!row.runs.has(r.taskRunId)) row.runs.set(r.taskRunId, { taskRunId: r.taskRunId, calls: 0, unpricedCalls: 0, cost: 0 });
+      add(row.runs.get(r.taskRunId), r);
+    }
+  }
+  const close = ({ cost, ...rest }) => ({ ...rest, costUsd: rest.calls && rest.unpricedCalls === rest.calls ? null : Math.round(cost * 1e6) / 1e6 });
+  return [...projects.keys()].sort().map((key) => {
+    const { runs, ...row } = projects.get(key);
+    const taskRuns = [...runs.keys()].sort().map((id) => close(runs.get(id)));
+    return { ...close(row), ...(taskRuns.length ? { taskRuns } : {}) };
+  });
 }
 
 const utcDate = (ms) => new Date(ms).toISOString().slice(0, 10);
@@ -1041,6 +1073,181 @@ function closeRow(row) {
  * model; days without calls are omitted. A row whose calls are all unpriced costs null; totals
  * are the sums of the model rows (FAC-SEM-025).
  */
+// --- FAC-SEM-025 whole (DEC-0021, DEC-0065, CT-40, DEC-0076): the contract's `usageRules` --------------------------------
+
+const usageCount = (v) => (Number.isSafeInteger(v) && v >= 0 ? v : 0);
+const usageCost = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0);
+const exceeds = (a, b) => a - b > 0.000001 + 1e-9 * Math.max(Math.abs(a), Math.abs(b));
+const usd = (v) => String(Math.round(v * 1e6) / 1e6);
+const usageList = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'object' && x !== null && !Array.isArray(x)) : []);
+const RFC3339_TIME = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+function strictTime(value) {
+  const m = typeof value === 'string' ? RFC3339_TIME.exec(value) : null;
+  if (!m) return NaN;
+  const [y, mo, d, h, mi, s] = m.slice(1, 7).map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(y, mo - 1, d);
+  if (date.getUTCMonth() !== mo - 1 || date.getUTCDate() !== d || h > 23 || mi > 59 || s > 59) return NaN;
+  return Date.parse(value);
+}
+function utcDateMs(value) {
+  const m = typeof value === 'string' ? /^(\d{4})-(\d{2})-(\d{2})$/.exec(value) : null;
+  if (!m) return NaN;
+  const [y, mo, d] = m.slice(1).map(Number);
+  const ms = Date.UTC(y, mo - 1, d);
+  const date = new Date(ms);
+  return date.getUTCFullYear() === y && date.getUTCMonth() === mo - 1 && date.getUTCDate() === d ? ms : NaN;
+}
+function pricedRow(row, at) {
+  const calls = usageCount(row.calls), unpriced = usageCount(row.unpricedCalls);
+  const flag = (p, message) => [{ code: 'FAC-SEM-025', instancePath: p, message }];
+  if (unpriced > calls) return flag(`${at}/unpricedCalls`, 'more unpriced calls than calls');
+  if (calls > 0 && unpriced === calls && row.costUsd !== null) return flag(`${at}/costUsd`, 'every call is unpriced, so the cost is unknown (null), not a number');
+  if (unpriced < calls && row.costUsd === null) return flag(`${at}/costUsd`, 'priced calls carry a cost; null is only for a row with no priced call');
+  return [];
+}
+
+/**
+ * FAC-SEM-025 over a usage report, in the contract's order (`src/usage-rules.ts`): the arithmetic, the window (every
+ * date exists, not after `generatedAt`'s UTC date, at most 30 days before it) and the project attribution (each project
+ * once by its normal form, each task run once; calls, priced calls and known costs bounded). Never throws.
+ */
+export function usageFindings(report) {
+  const value = typeof report === 'object' && report !== null && !Array.isArray(report) ? report : {};
+  const findings = [];
+  const flag = (instancePath, message) => findings.push({ code: 'FAC-SEM-025', instancePath, message });
+  const days = usageList(value.days);
+  let previous = '';
+  days.forEach((day, i) => {
+    const at = `/days/${i}`;
+    const date = String(day.date ?? '');
+    if (date <= previous) flag(`${at}/date`, `days must run forward without a repeat (${date} after ${previous})`);
+    previous = date;
+    findings.push(...pricedRow(day, at));
+    const models = usageList(day.byModel);
+    models.forEach((m, j) => findings.push(...pricedRow(m, `${at}/byModel/${j}`)));
+    if (!models.length) {
+      const spent = ['calls', 'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens'].some((f) => Number(day[f] ?? 0) > 0) || Number(day.costUsd ?? 0) > 0;
+      if (spent) flag(`${at}/byModel`, 'a day with calls, tokens or cost names the models they belong to');
+      return;
+    }
+    for (const field of ['calls', 'unpricedCalls', 'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens']) {
+      const sum = models.reduce((n, m) => n + Number(m[field] ?? 0), 0);
+      if (Number(day[field] ?? 0) !== sum) flag(`${at}/${field}`, `the day's ${field} is not the sum of its models (${String(day[field] ?? 0)} ≠ ${sum})`);
+    }
+    const known = models.map((m) => (typeof m.costUsd === 'number' ? m.costUsd : null)).filter((x) => x !== null).reduce((n, x) => n + x, 0);
+    if (typeof day.costUsd === 'number' && Math.abs(day.costUsd - known) > 0.000001 + 1e-9 * Math.max(Math.abs(day.costUsd), Math.abs(known))) flag(`${at}/costUsd`, "the day's cost is not the sum of its models' known costs");
+  });
+  if (days.length) {
+    const generated = strictTime(value.generatedAt);
+    if (Number.isNaN(generated)) flag('/generatedAt', 'generatedAt is an RFC 3339 date-time with an offset, so the window can be read');
+    else {
+      const today = Math.floor(generated / 86_400_000) * 86_400_000;
+      const oldest = today - 30 * 86_400_000;
+      days.forEach((day, i) => {
+        const date = utcDateMs(day.date);
+        if (Number.isNaN(date)) flag(`/days/${i}/date`, "a day's date exists in its month");
+        else if (date > today) flag(`/days/${i}/date`, 'a day is not after the UTC date of generatedAt');
+        else if (date < oldest) flag(`/days/${i}/date`, 'a day is within the last 31 UTC days of generatedAt');
+      });
+    }
+  }
+  if (Array.isArray(value.byProject)) {
+    const seen = new Map();
+    let projectCalls = 0, projectCost = 0;
+    value.byProject.forEach((project, p) => {
+      if (typeof project !== 'object' || project === null || Array.isArray(project)) return;
+      const at = `/byProject/${p}`;
+      const normal = normalIdentifier(project.projectId);
+      if (normal !== undefined) {
+        if (seen.has(normal)) flag(`${at}/projectId`, `each project is one row: ${String(project.projectId)} names the project ${seen.get(normal)} already names`);
+        else seen.set(normal, String(project.projectId));
+      }
+      projectCalls += usageCount(project.calls);
+      projectCost += usageCost(project.costUsd);
+      findings.push(...pricedRow(project, at));
+      const runs = new Set();
+      let runCalls = 0, runCost = 0, runPriced = 0;
+      usageList(project.taskRuns).forEach((run, r) => {
+        if (typeof run.taskRunId === 'string') {
+          if (runs.has(run.taskRunId)) flag(`${at}/taskRuns/${r}/taskRunId`, 'each task run is one row within its project');
+          runs.add(run.taskRunId);
+        }
+        runCalls += usageCount(run.calls);
+        runCost += usageCost(run.costUsd);
+        runPriced += Math.max(0, usageCount(run.calls) - usageCount(run.unpricedCalls));
+        findings.push(...pricedRow(run, `${at}/taskRuns/${r}`));
+      });
+      const projectPriced = Math.max(0, usageCount(project.calls) - usageCount(project.unpricedCalls));
+      if (runCalls > usageCount(project.calls)) flag(`${at}/taskRuns`, `a project's task runs hold more calls than the project (${runCalls} > ${usageCount(project.calls)})`);
+      else if (runPriced > projectPriced) flag(`${at}/taskRuns`, `a project's task runs hold more priced calls than the project (${runPriced} > ${projectPriced})`);
+      else if (usageCost(project.costUsd) === project.costUsd && exceeds(runCost, usageCost(project.costUsd))) flag(`${at}/taskRuns`, `a project's task runs cost more than the project (${usd(runCost)} > ${usd(usageCost(project.costUsd))})`);
+    });
+    const dayCalls = days.reduce((n, d) => n + usageCount(d.calls), 0);
+    if (projectCalls > dayCalls) flag('/byProject', `the projects hold more calls than the days (${projectCalls} > ${dayCalls})`);
+    const dayCost = days.reduce((n, d) => n + usageCost(d.costUsd), 0);
+    if (exceeds(projectCost, dayCost)) flag('/byProject', `the projects cost more than the days (${usd(projectCost)} > ${usd(dayCost)})`);
+  }
+  return findings;
+}
+
+// --- OpenRouter attribution (DEC-0065): the contract's `attributionHeaders`, off by default ------------------------------
+
+export const OPENROUTER_CATEGORIES = Object.freeze(['cli-agent', 'ide-extension', 'cloud-agent', 'programming-app', 'native-app-builder',
+  'creative-writing', 'video-gen', 'image-gen', 'audio-gen', 'writing-assistant', 'general-chat', 'personal-agent', 'legal', 'roleplay', 'game']);
+const ATTR_PRODUCT = /^[a-z][a-z0-9-]{0,62}$/;
+const ATTR_TITLE = /^[\x21-\x7e](?:[\x20-\x7e]{0,98}[\x21-\x7e])?$/;
+const ATTRIBUTION_HEADER_NAMES = new Set(['http-referer', 'referer', 'x-openrouter-title', 'x-title', 'x-openrouter-categories']);
+
+/** FAC-SEM-098: a product's setting names a product slug, a printable title and at most two recognized categories. */
+export function attributionSettingFindings(value) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return [{ code: 'FAC-SEM-098', instancePath: '', message: 'an attribution setting is an object' }];
+  const findings = [];
+  const flag = (instancePath, message) => findings.push({ code: 'FAC-SEM-098', instancePath, message });
+  if (typeof value.product !== 'string' || !ATTR_PRODUCT.test(value.product)) flag('/product', 'the product is a lower-case slug, the last segment of its product page');
+  if (typeof value.title !== 'string' || !ATTR_TITLE.test(value.title)) flag('/title', "the title is the product's full name: printable ASCII, 1 to 100 characters, no space at either end");
+  if (value.categories !== undefined) {
+    if (!Array.isArray(value.categories)) flag('/categories', 'categories are a list');
+    else {
+      if (value.categories.length > 2) flag('/categories', 'at most 2 categories per request');
+      const seen = new Set();
+      value.categories.forEach((c, i) => {
+        if (typeof c !== 'string' || !OPENROUTER_CATEGORIES.includes(c)) flag(`/categories/${i}`, 'a category is one OpenRouter recognizes; it drops others without an error');
+        else if (seen.has(c)) flag(`/categories/${i}`, 'each category once');
+        else seen.add(c);
+      });
+    }
+  }
+  return findings;
+}
+
+function isOpenRouter(url) {
+  try {
+    const u = new URL(url);
+    return u.protocol === 'https:' && u.hostname === 'openrouter.ai' && u.port === '' && u.username === '' && u.password === '';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The headers a product adds to one request (DEC-0065, the contract's `attributionHeaders`), or none with the reason:
+ * `no-setting` (off by default), `invalid-setting`, `not-openrouter`, `forwarded`, `user-set`. Only `HTTP-Referer`,
+ * `X-OpenRouter-Title` and `X-OpenRouter-Categories`; it never reads, moves or returns a key.
+ */
+export function attributionHeaders(setting, given) {
+  const request = typeof given === 'object' && given !== null ? given : {};
+  if (setting === undefined || setting === null) return { headers: {}, none: 'no-setting' };
+  if (attributionSettingFindings(setting).length) return { headers: {}, none: 'invalid-setting' };
+  if (typeof request.url !== 'string' || !isOpenRouter(request.url)) return { headers: {}, none: 'not-openrouter' };
+  if (request.originated !== true) return { headers: {}, none: 'forwarded' };
+  const present = typeof request.headers === 'object' && request.headers !== null ? Object.keys(request.headers).map((n) => n.toLowerCase()) : [];
+  if (present.some((n) => ATTRIBUTION_HEADER_NAMES.has(n))) return { headers: {}, none: 'user-set' };
+  const headers = { 'HTTP-Referer': `https://passioncode.ai/${setting.product}/`, 'X-OpenRouter-Title': setting.title };
+  if (setting.categories?.length) headers['X-OpenRouter-Categories'] = setting.categories.join(',');
+  return { headers };
+}
+
 /**
  * `budgets` (DEC-0027) lists every spending limit the service applies, enforced or not. A machine limit with a
  * calendar `period` and no `spentUsd` is counted here from the receipts, the way `budget` is, so the two never
@@ -1077,6 +1284,8 @@ export function usageReport(receipts, { id, instance = 'default', now = Date.now
     return { ...closeRow(day), byModel: models };
   });
   const report = { protocol: PROTOCOL, service: { id, instance }, generatedAt: new Date(now).toISOString().replace(/\.\d{3}Z$/, 'Z'), currency: 'USD', days: outDays };
+  const projects = byProject(receipts, first, last);
+  if (projects.length) report.byProject = projects;
   if (budget !== undefined) {
     if (!['day', 'month'].includes(budget?.period) || typeof budget.limitUsd !== 'number' || !(budget.limitUsd > 0)) throw new ServiceError('budget is {period: day|month, limitUsd > 0}.');
     report.budget = { period: budget.period, limitUsd: budget.limitUsd, spentUsd: spentIn(outDays, budget.period, last) };