@nomosprotocol/sdk 2.3.0 → 2.3.2

package/README.md

@@ -161,6 +161,17 @@ const verdict = await nomos.can({
 });
 ```
 
+Name your agent so the transcript records who asked, and mark test traffic so it stays out of the authority's public history and counts:
+
+```ts
+const verdict = await nomos.can(
+  { authority: "eu-ai-act", ai_categorises_biometric_data_for_sensitive_attributes: true },
+  { caller: { agent_id: "acme-hiring-agent", purpose: process.env.CI ? "test" : "production" } },
+);
+```
+
+The name is declared, not verified, and is shown as such. Don't know which authority applies? `GET /api/exchange/find?q=<what you're about to do>`, or the MCP tool `find_authority`.
+
 If a paid authority has not been purchased, NOMOS throws `NomosPaymentRequiredError` with the price and purchase URL attached.
 
 NOMOS never auto-charges on your behalf.
@@ -172,7 +183,7 @@ Use an authenticated client for artifacts belonging to your organization:
 ```ts
 import { Nomos } from "@nomosprotocol/sdk";
 
-const client = new Nomos("nms_live_...");
+const client = new Nomos("nmk_...");
 
 const verdict = await client.can({
   artifact_id: "loan_approval_v1",
@@ -263,7 +274,7 @@ itself needs.
 
 A `.nomos` file is a sealed, machine-executable representation of institutional authority.
 
-It can contain the rules, constraints, permissions, obligations, provenance, issuer information, version, and other governance metadata required to evaluate an action.
+It can contain the rules, constraints, permissions, obligations, provenance, issuer information, version, and other authority metadata required to evaluate an action.
 
 The artifact is cryptographically sealed.
 
@@ -470,7 +481,7 @@ The authenticated `Nomos` client exposes the broader platform:
 ```ts
 import { Nomos } from "@nomosprotocol/sdk";
 
-const client = new Nomos("nms_live_...");
+const client = new Nomos("nmk_...");
 
 // Authorization
 await client.can({

package/dist/index.cjs

@@ -41,12 +41,14 @@ __export(index_exports, {
   WELL_KNOWN: () => WELL_KNOWN,
   accept: () => accept,
   act: () => act,
+  applyToolBindings: () => applyToolBindings,
   approver: () => approver,
   bindingDigest: () => bindingDigest,
   buildAct: () => buildAct,
   can: () => can,
   certificateRegistry: () => certificateRegistry,
   certify: () => certify,
+  describeSuggestion: () => describeSuggestion,
   fetchDocument: () => fetchDocument,
   generateSigner: () => generateSigner,
   issuer: () => issuer,
@@ -57,6 +59,7 @@ __export(index_exports, {
   memoryStore: () => memoryStore,
   nomos: () => nomos,
   originOf: () => originOf,
+  parseToolBindings: () => parseToolBindings,
   passkeyApprover: () => passkeyApprover,
   postgresPasskeyStore: () => postgresPasskeyStore,
   postgresRegistryStore: () => postgresRegistryStore,
@@ -75,6 +78,7 @@ __export(index_exports, {
   signRevocationList: () => signRevocationList,
   signTestimony: () => signTestimony,
   statusFor: () => statusFor,
+  suggestToolBindings: () => suggestToolBindings,
   verifyAct: () => verifyAct,
   verifyArtifact: () => verifyArtifact,
   verifyChain: () => verifyChain,
@@ -187,7 +191,7 @@ function isRetryable(status) {
 }
 
 // src/http-client.ts
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "2.3.2";
 var HttpClient = class {
   constructor(opts) {
     this.opts = opts;
@@ -211,6 +215,7 @@ var HttpClient = class {
       "User-Agent": `nomos-node/${SDK_VERSION}`,
       "NOMOS-SDK-Version": SDK_VERSION
     };
+    if (reqOpts?.headers) Object.assign(headers, reqOpts.headers);
     if (reqOpts?.idempotencyKey) {
       headers["Idempotency-Key"] = reqOpts.idempotencyKey;
     }
@@ -719,6 +724,13 @@ function normalizeAuthorityQueryResult(data, authority) {
     ...data.revoked === true ? { revoked: true, revocation_reason: data.revocation_reason } : {}
   };
 }
+function callerHeaders(c) {
+  const h = {};
+  if (c?.agent_id) h["X-Nomos-Agent"] = c.agent_id;
+  if (c?.acts_for) h["X-Nomos-Acts-For"] = c.acts_for;
+  if (c?.purpose) h["X-Nomos-Purpose"] = c.purpose;
+  return h;
+}
 async function canViaExchange(authority, facts, action, opts) {
   const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
   const url = `${base}/api/v1/can`;
@@ -726,7 +738,7 @@ async function canViaExchange(authority, facts, action, opts) {
   try {
     res = await fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": `nomos-node/${SDK_VERSION}`, ...callerHeaders(opts?.caller) },
       body: JSON.stringify({ artifact: authority, action, ...facts }),
       signal: opts?.signal
     });
@@ -739,8 +751,8 @@ async function canViaExchange(authority, facts, action, opts) {
   if (!res.ok) mapHttpError(res.status, data, requestId);
   return normalizeAuthorityQueryResult(data, authority);
 }
-async function canViaExchangeAuthenticated(http, authority, facts, action) {
-  const { data } = await http.post("/api/v1/can", { artifact: authority, action, ...facts });
+async function canViaExchangeAuthenticated(http, authority, facts, action, caller) {
+  const { data } = await http.post("/api/v1/can", { artifact: authority, action, ...facts }, { headers: callerHeaders(caller) });
   return normalizeAuthorityQueryResult(data, authority);
 }
 async function canViaArtifact(http, artifactId, facts, action) {
@@ -837,7 +849,6 @@ async function can(params, opts) {
   return canViaExchange(params.authority, facts, action, opts);
 }
 async function canAuthenticated(http, params, opts) {
-  void opts;
   const { facts, action } = splitFacts(params);
   if (params.artifact !== void 0) {
     if (!params.key_certs || !params.root_public_key_pem) {
@@ -846,13 +857,13 @@ async function canAuthenticated(http, params, opts) {
     return canViaChain(params.artifact, params.key_certs, params.root_public_key_pem, facts, action, opts);
   }
   if (params.artifact_id) return canViaArtifact(http, params.artifact_id, facts, action);
-  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action);
+  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action, opts?.caller);
   throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), or `artifact` (chain-of-trust) is required.");
 }
 var nomos = { can };
 
 // src/nomos.ts
-var DEFAULT_BASE_URL = "https://nomos.ai";
+var DEFAULT_BASE_URL = "https://www.nomosprotocol.com";
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_TIMEOUT = 3e4;
 var Nomos = class {
@@ -862,7 +873,7 @@ var Nomos = class {
   constructor(apiKey, config = {}) {
     if (!apiKey || typeof apiKey !== "string") {
       throw new NomosAuthenticationError(
-        'A valid API key is required. Pass it as the first argument: new Nomos("nms_live_...")'
+        'A valid API key is required. Pass it as the first argument: new Nomos("nmk_...")'
       );
     }
     this.mode = apiKey.startsWith("nms_test_") ? "test" : "live";
@@ -884,7 +895,7 @@ var Nomos = class {
    * return shape either way, so calling code never needs to know which rail answered.
    *
    * @example
-   * const client = new Nomos('nms_live_...');
+   * const client = new Nomos('nmk_...');
    * const verdict = await client.can({ artifact_id: 'loan_approval_v1', credit_score: 720 });
    */
   async can(params, opts) {
@@ -5047,9 +5058,14 @@ var TIE_ORDERS = {
 function evaluate(artifact, facts) {
   const logic = artifact.logic;
   const res = logic.resolution ?? {};
-  const decisions = logic.decisions;
-  if (!Array.isArray(decisions))
+  if (!Array.isArray(logic.decisions))
     throw new Error("logic.decisions missing");
+  const declared = new Set(Object.keys(artifact.execution?.actions ?? {}));
+  const isObligation = (d) => {
+    const t = d?.then?.[0];
+    return t?.type === "emit" || t?.type === "action" && declared.has(t?.action_name);
+  };
+  const decisions = logic.decisions.filter((d) => !isObligation(d));
   const order = TIE_ORDERS[res.tie_breaker ?? "deny_wins"];
   if (!order)
     throw new Error("unknown tie_breaker");
@@ -5473,6 +5489,136 @@ async function verifyChainRemote(params, opts) {
   throw new NomosAPIError(message, res.status, requestId);
 }
 
+// src/bindings.ts
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+var isScalar = (v) => typeof v === "string" || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v);
+function parseToolBindings(raw) {
+  const no = (why) => {
+    throw new Error(why);
+  };
+  const obj = raw;
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) no("it is not a JSON object");
+  if (obj.version !== 1) no('"version" must be 1');
+  if (typeof obj.artifact !== "string" || !obj.artifact) no('"artifact" must name the sealed policy');
+  if (typeof obj.reviewed !== "boolean") no('"reviewed" must be true or false');
+  if (!obj.tools || typeof obj.tools !== "object" || Array.isArray(obj.tools)) no('"tools" must be an object');
+  for (const k of Object.keys(obj)) if (!["version", "artifact", "reviewed", "tools", "_review"].includes(k)) no(`unknown setting "${k}"`);
+  const tools = {};
+  for (const tool of Object.keys(obj.tools)) {
+    if (FORBIDDEN_KEYS.has(tool)) no(`"${tool}" isn't a usable tool name`);
+    const entry = obj.tools[tool];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) no(`tool "${tool}" must be an object with "facts"`);
+    for (const k of Object.keys(entry)) if (!["facts", "_why"].includes(k)) no(`tool "${tool}": unknown setting "${k}"`);
+    const facts = entry.facts;
+    if (!facts || typeof facts !== "object" || Array.isArray(facts)) no(`tool "${tool}" needs "facts"`);
+    tools[tool] = { facts: {} };
+    for (const fact of Object.keys(facts)) {
+      const where = `${tool}.${fact}`;
+      if (fact === "tool") no(`${where}: "tool" is set by the guard to the tool's name`);
+      if (FORBIDDEN_KEYS.has(fact)) no(`${where} isn't a usable fact name`);
+      const b = facts[fact];
+      if (!b || typeof b !== "object" || Array.isArray(b)) no(`${where} must be an object with "arg"`);
+      for (const k of Object.keys(b)) if (!["arg", "scale", "map", "_why"].includes(k)) no(`${where}: "${k}" isn't allowed. A fact can only come from an argument of the call`);
+      if (typeof b.arg !== "string" || !b.arg) no(`${where} needs "arg", the argument it comes from`);
+      if (b.arg.split(".").some((s) => !s || FORBIDDEN_KEYS.has(s))) no(`${where}: "${b.arg}" isn't a usable argument path`);
+      if (b.scale !== void 0 && b.map !== void 0) no(`${where}: use "scale" or "map", not both`);
+      if (b.scale !== void 0 && (typeof b.scale !== "number" || !Number.isFinite(b.scale) || b.scale === 0)) no(`${where}: "scale" must be a non-zero number`);
+      if (b.map !== void 0) {
+        if (!b.map || typeof b.map !== "object" || Array.isArray(b.map)) no(`${where}: "map" must be an object`);
+        for (const k of Object.keys(b.map)) if (FORBIDDEN_KEYS.has(k) || !isScalar(b.map[k])) no(`${where}: "map" can only hold plain values`);
+      }
+      tools[tool].facts[fact] = { arg: b.arg, ...b.scale !== void 0 ? { scale: b.scale } : {}, ...b.map !== void 0 ? { map: b.map } : {} };
+    }
+  }
+  return { version: 1, artifact: obj.artifact, reviewed: obj.reviewed, tools };
+}
+function applyToolBindings(bindings, tool, args) {
+  const inputs = { tool };
+  const unresolved = [];
+  const facts = hasOwn(bindings.tools, tool) ? bindings.tools[tool].facts : {};
+  for (const [fact, b] of Object.entries(facts)) {
+    let v = args;
+    for (const seg of b.arg.split(".")) v = v && typeof v === "object" && !Array.isArray(v) && hasOwn(v, seg) ? v[seg] : void 0;
+    if (v === void 0 || v === null) {
+      unresolved.push({ fact, arg: b.arg, why: "missing" });
+      continue;
+    }
+    if (b.scale !== void 0) {
+      if (typeof v !== "number" || !Number.isFinite(v)) {
+        unresolved.push({ fact, arg: b.arg, why: "not_a_number" });
+        continue;
+      }
+      inputs[fact] = Number((v * b.scale).toFixed(9));
+      continue;
+    }
+    if (!isScalar(v)) {
+      unresolved.push({ fact, arg: b.arg, why: "not_a_value" });
+      continue;
+    }
+    if (b.map) {
+      if (!hasOwn(b.map, String(v))) {
+        unresolved.push({ fact, arg: b.arg, why: "not_in_map" });
+        continue;
+      }
+      inputs[fact] = b.map[String(v)];
+      continue;
+    }
+    inputs[fact] = v;
+  }
+  return { inputs, unresolved };
+}
+var WEAK = /* @__PURE__ */ new Set(["is", "has", "the", "a", "an", "of", "to", "in", "id", "name", "type", "value", "status", "code", "data", "info", "flag", "number", "num", "total", "ai", "system"]);
+var UNITS = { cents: 0.01, pence: 0.01, fils: 0.01, usd: null, dollars: null, aed: null, eur: null };
+var words = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).map((w) => w.toLowerCase()).filter(Boolean);
+var flatProperties = (props, prefix = "") => Object.entries(props ?? {}).flatMap(([k, s]) => FORBIDDEN_KEYS.has(k) ? [] : s?.type === "object" && s.properties ? flatProperties(s.properties, `${prefix}${k}.`) : [{ path: `${prefix}${k}`, schema: s }]);
+function suggestToolBindings(artifact, tools, fields) {
+  const bindings = { version: 1, artifact, reviewed: false, tools: {} };
+  const proposals = [];
+  const unbound = [];
+  for (const tool of tools) {
+    bindings.tools[tool.name] = { facts: {} };
+    const args = flatProperties(tool.inputSchema?.properties);
+    for (const field of fields) {
+      if (field.name === "tool") continue;
+      const want = words(field.name).filter((w) => !WEAK.has(w) && !(w in UNITS));
+      const scored = args.map((a) => {
+        const raw = words(a.path);
+        const have = raw.filter((w) => !WEAK.has(w) && !(w in UNITS));
+        const shared = want.filter((w) => have.includes(w));
+        const unit = raw.find((w) => w in UNITS);
+        const same = words(field.name).join("_") === raw.join("_");
+        const sameCore = want.length > 0 && want.length === have.length && shared.length === want.length;
+        return { a, shared, unit, same, sameCore, score: same ? 3 : sameCore ? 2 : shared.length ? shared.length / Math.max(want.length, have.length) : 0 };
+      }).filter((s) => s.score > 0).sort((x, y) => y.score - x.score);
+      if (!scored.length) {
+        unbound.push({ tool: tool.name, fact: field.name, candidates: [] });
+        continue;
+      }
+      const best = scored[0];
+      if (scored[1] && scored[1].score === best.score) {
+        unbound.push({ tool: tool.name, fact: field.name, candidates: scored.filter((s) => s.score === best.score).map((s) => s.a.path) });
+        continue;
+      }
+      const scale = best.unit ? UNITS[best.unit] ?? void 0 : void 0;
+      const why = best.same ? "the same name" : best.sameCore ? "the same words" : `shares "${best.shared.join(", ")}"`;
+      proposals.push({ tool: tool.name, fact: field.name, arg: best.a.path, confidence: best.same || best.sameCore ? "exact" : "likely", why: scale ? `${why}; ${best.unit} scaled by ${scale}` : why, ...scale ? { scale } : {} });
+      bindings.tools[tool.name].facts[field.name] = { arg: best.a.path, ...scale ? { scale } : {} };
+    }
+  }
+  return { bindings, proposals, unbound };
+}
+function describeSuggestion(s) {
+  const lines = [];
+  for (const tool of Object.keys(s.bindings.tools)) {
+    lines.push(`
+${tool}`);
+    for (const p of s.proposals.filter((x) => x.tool === tool)) lines.push(`  ${p.confidence === "exact" ? "matched " : "CHECK   "} ${p.fact} <- ${p.arg}${p.scale ? ` x ${p.scale}` : ""} (${p.why})`);
+    for (const u of s.unbound.filter((x) => x.tool === tool)) lines.push(`  NO MATCH ${u.fact}${u.candidates.length ? ` (could be: ${u.candidates.join(", ")})` : ""}`);
+  }
+  return lines.join("\n");
+}
+
 // src/act/bytes.ts
 var utf82 = (s) => new TextEncoder().encode(s);
 var fromUtf82 = (b) => new TextDecoder().decode(b);
@@ -7034,12 +7180,14 @@ ${buttons}</body>`;
   WELL_KNOWN,
   accept,
   act,
+  applyToolBindings,
   approver,
   bindingDigest,
   buildAct,
   can,
   certificateRegistry,
   certify,
+  describeSuggestion,
   fetchDocument,
   generateSigner,
   issuer,
@@ -7050,6 +7198,7 @@ ${buttons}</body>`;
   memoryStore,
   nomos,
   originOf,
+  parseToolBindings,
   passkeyApprover,
   postgresPasskeyStore,
   postgresRegistryStore,
@@ -7068,6 +7217,7 @@ ${buttons}</body>`;
   signRevocationList,
   signTestimony,
   statusFor,
+  suggestToolBindings,
   verifyAct,
   verifyArtifact,
   verifyChain,

package/dist/index.d.cts

@@ -88,6 +88,17 @@ interface CanOptions {
     baseUrl?: string;
     /** AbortSignal to cancel the request. */
     signal?: AbortSignal;
+    /** Who is asking, recorded on the transcript (sent as X-Nomos-Agent / -Acts-For / -Purpose).
+     *  `purpose: 'test'` queries are answered and sealed but kept out of the authority's public
+     *  history and counts — set it from tests and CI. Exchange authorities only. */
+    caller?: CanCaller;
+}
+interface CanCaller {
+    /** A stable name for your agent, e.g. "acme-credit-agent". */
+    agent_id?: string;
+    /** The organisation it acts for. Ignored when the request carries an API key (the key's account is used). */
+    acts_for?: string;
+    purpose?: 'production' | 'test';
 }
 interface CanResult {
     /** True only for an AUTHORIZED verdict. DENIED and ESCALATED are both `false`. */
@@ -395,7 +406,7 @@ interface GenerateGovernanceResult {
     download_url?: string;
 }
 interface NomosConfig {
-    /** Base URL override — defaults to https://nomos.ai */
+    /** Base URL override — defaults to https://www.nomosprotocol.com */
     baseUrl?: string;
     /** Max retries on 429 / 5xx (default: 3) */
     maxRetries?: number;
@@ -411,6 +422,8 @@ interface RequestOptions {
     idempotencyKey?: string;
     /** Per-request API key — useful for multi-tenant platforms */
     apiKey?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
 }
 interface NomosRawResponse {
     /** x-request-id header value — include in support tickets */
@@ -776,7 +789,7 @@ declare class Nomos {
      * return shape either way, so calling code never needs to know which rail answered.
      *
      * @example
-     * const client = new Nomos('nms_live_...');
+     * const client = new Nomos('nmk_...');
      * const verdict = await client.can({ artifact_id: 'loan_approval_v1', credit_score: 720 });
      */
     can(params: CanParams, opts?: CanOptions): Promise<CanResult>;
@@ -807,6 +820,86 @@ declare const nomos: {
  */
 declare function verifyChain(params: VerifyChainParams, opts?: VerifyChainOptions): Promise<VerifyChainResult>;
 
+/**
+ * Tool bindings: which of a tool's arguments is which fact a sealed policy reads. A policy reads
+ * `loan_amount`; a tool sends `amount_cents`. Without a binding the policy has nothing to decide on,
+ * and a fail-closed check holds every call.
+ *
+ * A binding decides what a policy sees, so it is built to be safe:
+ *  - It is an explicit, reviewed file. Suggestions are proposals, marked unreviewed.
+ *  - A fact only ever comes from an argument of the call. There are no constants, so nobody can
+ *    hard-code a fact to quiet a policy.
+ *  - With a binding, only bound facts reach the policy, so an agent can't state a fact the tool
+ *    wouldn't act on by adding an argument of that name.
+ *  - A missing argument or an unmapped value leaves the fact undecided. It is never guessed.
+ *
+ * Pure: no I/O, no model. Specified in NOMOS-SPEC-011 (Draft), nomos-spec/spec; see also
+ * docs/design-notes/tool-fact-binding.md.
+ */
+interface FactBinding {
+    /** The argument this fact comes from. Dots reach into objects: `customer.kyc`. */
+    arg: string;
+    /** Multiply a number: `amount_cents` into dollars is 0.01. */
+    scale?: number;
+    /** Translate a value: { "ok": "verified" }. A value not listed leaves the fact undecided. */
+    map?: Record<string, string | number | boolean>;
+}
+interface ToolBindings {
+    version: 1;
+    /** The sealed policy these facts belong to. */
+    artifact: string;
+    /** False until a person has checked it. The guard won't enforce an unreviewed file. */
+    reviewed: boolean;
+    tools: Record<string, {
+        facts: Record<string, FactBinding>;
+    }>;
+}
+/** Reads a bindings file, refusing anything it doesn't fully understand. Throws with a plain reason. */
+declare function parseToolBindings(raw: unknown): ToolBindings;
+interface UnresolvedFact {
+    fact: string;
+    arg: string;
+    why: 'missing' | 'not_a_number' | 'not_a_value' | 'not_in_map';
+}
+/** The facts a policy gets for this call, and which it couldn't get. */
+declare function applyToolBindings(bindings: ToolBindings, tool: string, args: Record<string, unknown>): {
+    inputs: Record<string, string | number | boolean>;
+    unresolved: UnresolvedFact[];
+};
+interface ToolDescription {
+    name: string;
+    inputSchema?: {
+        properties?: Record<string, any>;
+    } | null;
+}
+interface PolicyField {
+    name: string;
+    type?: string;
+    description?: string | null;
+    values?: string[];
+}
+interface BindingProposal {
+    tool: string;
+    fact: string;
+    arg: string;
+    confidence: 'exact' | 'likely';
+    why: string;
+    scale?: number;
+}
+interface BindingSuggestion {
+    bindings: ToolBindings;
+    proposals: BindingProposal[];
+    unbound: Array<{
+        tool: string;
+        fact: string;
+        candidates: string[];
+    }>;
+}
+/** Proposes bindings from names alone, for a person to check. Never guesses a value translation. */
+declare function suggestToolBindings(artifact: string, tools: ToolDescription[], fields: PolicyField[]): BindingSuggestion;
+/** A plain report of a suggestion, for the person who has to check it. */
+declare function describeSuggestion(s: BindingSuggestion): string;
+
 type SignatureSuite = 'Ed25519' | 'ES256';
 interface Signer {
     /** NOMOS-SPEC-001 §8.4 key id of the public key. */
@@ -1542,4 +1635,4 @@ declare function approver(o: ApproverOptions): {
     pending: Map<string, Pending>;
 };
 
-export { ACT_MEDIA_TYPE, type AcceptOptions, type AcceptStore, type AcceptTransaction, type AcceptedAuthority, type KeyCertificate as ActKeyCertificate, type ActOptions, type ActResult, type ActStatus, type Action, type Answer, type ApproverOptions, type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type BuildActOptions, type CanOptions, type CanParams, type CanResult, type CanVerdict, type CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, approver, buildAct, can, certificateRegistry, certify, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, verifyChain, verifyEnrolmentToken, witness };
+export { ACT_MEDIA_TYPE, type AcceptOptions, type AcceptStore, type AcceptTransaction, type AcceptedAuthority, type KeyCertificate as ActKeyCertificate, type ActOptions, type ActResult, type ActStatus, type Action, type Answer, type ApproverOptions, type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type BindingProposal, type BindingSuggestion, type BuildActOptions, type CanCaller, type CanOptions, type CanParams, type CanResult, type CanVerdict, type CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type FactBinding, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PolicyField, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type ToolBindings, type ToolDescription, type UnresolvedFact, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, applyToolBindings, approver, buildAct, can, certificateRegistry, certify, describeSuggestion, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, parseToolBindings, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, suggestToolBindings, verifyChain, verifyEnrolmentToken, witness };

package/dist/index.d.ts

@@ -88,6 +88,17 @@ interface CanOptions {
     baseUrl?: string;
     /** AbortSignal to cancel the request. */
     signal?: AbortSignal;
+    /** Who is asking, recorded on the transcript (sent as X-Nomos-Agent / -Acts-For / -Purpose).
+     *  `purpose: 'test'` queries are answered and sealed but kept out of the authority's public
+     *  history and counts — set it from tests and CI. Exchange authorities only. */
+    caller?: CanCaller;
+}
+interface CanCaller {
+    /** A stable name for your agent, e.g. "acme-credit-agent". */
+    agent_id?: string;
+    /** The organisation it acts for. Ignored when the request carries an API key (the key's account is used). */
+    acts_for?: string;
+    purpose?: 'production' | 'test';
 }
 interface CanResult {
     /** True only for an AUTHORIZED verdict. DENIED and ESCALATED are both `false`. */
@@ -395,7 +406,7 @@ interface GenerateGovernanceResult {
     download_url?: string;
 }
 interface NomosConfig {
-    /** Base URL override — defaults to https://nomos.ai */
+    /** Base URL override — defaults to https://www.nomosprotocol.com */
     baseUrl?: string;
     /** Max retries on 429 / 5xx (default: 3) */
     maxRetries?: number;
@@ -411,6 +422,8 @@ interface RequestOptions {
     idempotencyKey?: string;
     /** Per-request API key — useful for multi-tenant platforms */
     apiKey?: string;
+    /** Extra request headers. */
+    headers?: Record<string, string>;
 }
 interface NomosRawResponse {
     /** x-request-id header value — include in support tickets */
@@ -776,7 +789,7 @@ declare class Nomos {
      * return shape either way, so calling code never needs to know which rail answered.
      *
      * @example
-     * const client = new Nomos('nms_live_...');
+     * const client = new Nomos('nmk_...');
      * const verdict = await client.can({ artifact_id: 'loan_approval_v1', credit_score: 720 });
      */
     can(params: CanParams, opts?: CanOptions): Promise<CanResult>;
@@ -807,6 +820,86 @@ declare const nomos: {
  */
 declare function verifyChain(params: VerifyChainParams, opts?: VerifyChainOptions): Promise<VerifyChainResult>;
 
+/**
+ * Tool bindings: which of a tool's arguments is which fact a sealed policy reads. A policy reads
+ * `loan_amount`; a tool sends `amount_cents`. Without a binding the policy has nothing to decide on,
+ * and a fail-closed check holds every call.
+ *
+ * A binding decides what a policy sees, so it is built to be safe:
+ *  - It is an explicit, reviewed file. Suggestions are proposals, marked unreviewed.
+ *  - A fact only ever comes from an argument of the call. There are no constants, so nobody can
+ *    hard-code a fact to quiet a policy.
+ *  - With a binding, only bound facts reach the policy, so an agent can't state a fact the tool
+ *    wouldn't act on by adding an argument of that name.
+ *  - A missing argument or an unmapped value leaves the fact undecided. It is never guessed.
+ *
+ * Pure: no I/O, no model. Specified in NOMOS-SPEC-011 (Draft), nomos-spec/spec; see also
+ * docs/design-notes/tool-fact-binding.md.
+ */
+interface FactBinding {
+    /** The argument this fact comes from. Dots reach into objects: `customer.kyc`. */
+    arg: string;
+    /** Multiply a number: `amount_cents` into dollars is 0.01. */
+    scale?: number;
+    /** Translate a value: { "ok": "verified" }. A value not listed leaves the fact undecided. */
+    map?: Record<string, string | number | boolean>;
+}
+interface ToolBindings {
+    version: 1;
+    /** The sealed policy these facts belong to. */
+    artifact: string;
+    /** False until a person has checked it. The guard won't enforce an unreviewed file. */
+    reviewed: boolean;
+    tools: Record<string, {
+        facts: Record<string, FactBinding>;
+    }>;
+}
+/** Reads a bindings file, refusing anything it doesn't fully understand. Throws with a plain reason. */
+declare function parseToolBindings(raw: unknown): ToolBindings;
+interface UnresolvedFact {
+    fact: string;
+    arg: string;
+    why: 'missing' | 'not_a_number' | 'not_a_value' | 'not_in_map';
+}
+/** The facts a policy gets for this call, and which it couldn't get. */
+declare function applyToolBindings(bindings: ToolBindings, tool: string, args: Record<string, unknown>): {
+    inputs: Record<string, string | number | boolean>;
+    unresolved: UnresolvedFact[];
+};
+interface ToolDescription {
+    name: string;
+    inputSchema?: {
+        properties?: Record<string, any>;
+    } | null;
+}
+interface PolicyField {
+    name: string;
+    type?: string;
+    description?: string | null;
+    values?: string[];
+}
+interface BindingProposal {
+    tool: string;
+    fact: string;
+    arg: string;
+    confidence: 'exact' | 'likely';
+    why: string;
+    scale?: number;
+}
+interface BindingSuggestion {
+    bindings: ToolBindings;
+    proposals: BindingProposal[];
+    unbound: Array<{
+        tool: string;
+        fact: string;
+        candidates: string[];
+    }>;
+}
+/** Proposes bindings from names alone, for a person to check. Never guesses a value translation. */
+declare function suggestToolBindings(artifact: string, tools: ToolDescription[], fields: PolicyField[]): BindingSuggestion;
+/** A plain report of a suggestion, for the person who has to check it. */
+declare function describeSuggestion(s: BindingSuggestion): string;
+
 type SignatureSuite = 'Ed25519' | 'ES256';
 interface Signer {
     /** NOMOS-SPEC-001 §8.4 key id of the public key. */
@@ -1542,4 +1635,4 @@ declare function approver(o: ApproverOptions): {
     pending: Map<string, Pending>;
 };
 
-export { ACT_MEDIA_TYPE, type AcceptOptions, type AcceptStore, type AcceptTransaction, type AcceptedAuthority, type KeyCertificate as ActKeyCertificate, type ActOptions, type ActResult, type ActStatus, type Action, type Answer, type ApproverOptions, type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type BuildActOptions, type CanOptions, type CanParams, type CanResult, type CanVerdict, type CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, approver, buildAct, can, certificateRegistry, certify, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, verifyChain, verifyEnrolmentToken, witness };
+export { ACT_MEDIA_TYPE, type AcceptOptions, type AcceptStore, type AcceptTransaction, type AcceptedAuthority, type KeyCertificate as ActKeyCertificate, type ActOptions, type ActResult, type ActStatus, type Action, type Answer, type ApproverOptions, type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type BindingProposal, type BindingSuggestion, type BuildActOptions, type CanCaller, type CanOptions, type CanParams, type CanResult, type CanVerdict, type CertificateRegistry, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type EnrolmentClaims, type FactBinding, type GenerateGovernanceParams, type GenerateGovernanceResult, type IssueOptions, type IssuerDocument, type IssuerOptions, type KeyCertificate$1 as KeyCertificate, type ListArtifactsParams, MAX_PRESENTED, Nomos, NomosAPIError, NomosActError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosDiscoveryError, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type PasskeyApproverOptions, type PasskeyCredential, type PasskeyStore, type PendingApproval, type PgClient, type PgPool, type PolicyField, type PostgresStoreOptions, type Receipt, RegistryError, type RegistryStore, type RelyingPartyDocument, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type RevocationSourceOptions, RevocationUnavailable, type SignatureSuite, type Signer, type ToolBindings, type ToolDescription, type UnresolvedFact, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, WELL_KNOWN, type WithLastResponse, type WitnessDocument, type WitnessOptions, accept, act, applyToolBindings, approver, buildAct, can, certificateRegistry, certify, describeSuggestion, fetchDocument, generateSigner, issuer, kidOf, localSigner, memoryPasskeyStore, memoryRegistryStore, memoryStore, nomos, originOf, parseToolBindings, passkeyApprover, postgresPasskeyStore, postgresRegistryStore, postgresStore, presentedCertificates, readAttestation, reliedKids, revocationListCertificates, revocationSource, seal, seededSigner, signConsent, signEnrolmentToken, signInForce, signRevocation, signRevocationList, signTestimony, statusFor, suggestToolBindings, verifyChain, verifyEnrolmentToken, witness };

package/dist/index.js

@@ -107,7 +107,7 @@ function isRetryable(status) {
 }
 
 // src/http-client.ts
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "2.3.2";
 var HttpClient = class {
   constructor(opts) {
     this.opts = opts;
@@ -131,6 +131,7 @@ var HttpClient = class {
       "User-Agent": `nomos-node/${SDK_VERSION}`,
       "NOMOS-SDK-Version": SDK_VERSION
     };
+    if (reqOpts?.headers) Object.assign(headers, reqOpts.headers);
     if (reqOpts?.idempotencyKey) {
       headers["Idempotency-Key"] = reqOpts.idempotencyKey;
     }
@@ -639,6 +640,13 @@ function normalizeAuthorityQueryResult(data, authority) {
     ...data.revoked === true ? { revoked: true, revocation_reason: data.revocation_reason } : {}
   };
 }
+function callerHeaders(c) {
+  const h = {};
+  if (c?.agent_id) h["X-Nomos-Agent"] = c.agent_id;
+  if (c?.acts_for) h["X-Nomos-Acts-For"] = c.acts_for;
+  if (c?.purpose) h["X-Nomos-Purpose"] = c.purpose;
+  return h;
+}
 async function canViaExchange(authority, facts, action, opts) {
   const base = (opts?.baseUrl ?? DEFAULT_EXCHANGE_BASE).replace(/\/$/, "");
   const url = `${base}/api/v1/can`;
@@ -646,7 +654,7 @@ async function canViaExchange(authority, facts, action, opts) {
   try {
     res = await fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", "User-Agent": `nomos-node/${SDK_VERSION}`, ...callerHeaders(opts?.caller) },
       body: JSON.stringify({ artifact: authority, action, ...facts }),
       signal: opts?.signal
     });
@@ -659,8 +667,8 @@ async function canViaExchange(authority, facts, action, opts) {
   if (!res.ok) mapHttpError(res.status, data, requestId);
   return normalizeAuthorityQueryResult(data, authority);
 }
-async function canViaExchangeAuthenticated(http, authority, facts, action) {
-  const { data } = await http.post("/api/v1/can", { artifact: authority, action, ...facts });
+async function canViaExchangeAuthenticated(http, authority, facts, action, caller) {
+  const { data } = await http.post("/api/v1/can", { artifact: authority, action, ...facts }, { headers: callerHeaders(caller) });
   return normalizeAuthorityQueryResult(data, authority);
 }
 async function canViaArtifact(http, artifactId, facts, action) {
@@ -757,7 +765,6 @@ async function can(params, opts) {
   return canViaExchange(params.authority, facts, action, opts);
 }
 async function canAuthenticated(http, params, opts) {
-  void opts;
   const { facts, action } = splitFacts(params);
   if (params.artifact !== void 0) {
     if (!params.key_certs || !params.root_public_key_pem) {
@@ -766,13 +773,13 @@ async function canAuthenticated(http, params, opts) {
     return canViaChain(params.artifact, params.key_certs, params.root_public_key_pem, facts, action, opts);
   }
   if (params.artifact_id) return canViaArtifact(http, params.artifact_id, facts, action);
-  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action);
+  if (params.authority) return canViaExchangeAuthenticated(http, params.authority, facts, action, opts?.caller);
   throw new Error("can(): `authority` (a public Exchange artifact), `artifact_id` (your own artifact), or `artifact` (chain-of-trust) is required.");
 }
 var nomos = { can };
 
 // src/nomos.ts
-var DEFAULT_BASE_URL = "https://nomos.ai";
+var DEFAULT_BASE_URL = "https://www.nomosprotocol.com";
 var DEFAULT_MAX_RETRIES = 3;
 var DEFAULT_TIMEOUT = 3e4;
 var Nomos = class {
@@ -782,7 +789,7 @@ var Nomos = class {
   constructor(apiKey, config = {}) {
     if (!apiKey || typeof apiKey !== "string") {
       throw new NomosAuthenticationError(
-        'A valid API key is required. Pass it as the first argument: new Nomos("nms_live_...")'
+        'A valid API key is required. Pass it as the first argument: new Nomos("nmk_...")'
       );
     }
     this.mode = apiKey.startsWith("nms_test_") ? "test" : "live";
@@ -804,7 +811,7 @@ var Nomos = class {
    * return shape either way, so calling code never needs to know which rail answered.
    *
    * @example
-   * const client = new Nomos('nms_live_...');
+   * const client = new Nomos('nmk_...');
    * const verdict = await client.can({ artifact_id: 'loan_approval_v1', credit_score: 720 });
    */
   async can(params, opts) {
@@ -4967,9 +4974,14 @@ var TIE_ORDERS = {
 function evaluate(artifact, facts) {
   const logic = artifact.logic;
   const res = logic.resolution ?? {};
-  const decisions = logic.decisions;
-  if (!Array.isArray(decisions))
+  if (!Array.isArray(logic.decisions))
     throw new Error("logic.decisions missing");
+  const declared = new Set(Object.keys(artifact.execution?.actions ?? {}));
+  const isObligation = (d) => {
+    const t = d?.then?.[0];
+    return t?.type === "emit" || t?.type === "action" && declared.has(t?.action_name);
+  };
+  const decisions = logic.decisions.filter((d) => !isObligation(d));
   const order = TIE_ORDERS[res.tie_breaker ?? "deny_wins"];
   if (!order)
     throw new Error("unknown tie_breaker");
@@ -5393,6 +5405,136 @@ async function verifyChainRemote(params, opts) {
   throw new NomosAPIError(message, res.status, requestId);
 }
 
+// src/bindings.ts
+var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var hasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+var isScalar = (v) => typeof v === "string" || typeof v === "boolean" || typeof v === "number" && Number.isFinite(v);
+function parseToolBindings(raw) {
+  const no = (why) => {
+    throw new Error(why);
+  };
+  const obj = raw;
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) no("it is not a JSON object");
+  if (obj.version !== 1) no('"version" must be 1');
+  if (typeof obj.artifact !== "string" || !obj.artifact) no('"artifact" must name the sealed policy');
+  if (typeof obj.reviewed !== "boolean") no('"reviewed" must be true or false');
+  if (!obj.tools || typeof obj.tools !== "object" || Array.isArray(obj.tools)) no('"tools" must be an object');
+  for (const k of Object.keys(obj)) if (!["version", "artifact", "reviewed", "tools", "_review"].includes(k)) no(`unknown setting "${k}"`);
+  const tools = {};
+  for (const tool of Object.keys(obj.tools)) {
+    if (FORBIDDEN_KEYS.has(tool)) no(`"${tool}" isn't a usable tool name`);
+    const entry = obj.tools[tool];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) no(`tool "${tool}" must be an object with "facts"`);
+    for (const k of Object.keys(entry)) if (!["facts", "_why"].includes(k)) no(`tool "${tool}": unknown setting "${k}"`);
+    const facts = entry.facts;
+    if (!facts || typeof facts !== "object" || Array.isArray(facts)) no(`tool "${tool}" needs "facts"`);
+    tools[tool] = { facts: {} };
+    for (const fact of Object.keys(facts)) {
+      const where = `${tool}.${fact}`;
+      if (fact === "tool") no(`${where}: "tool" is set by the guard to the tool's name`);
+      if (FORBIDDEN_KEYS.has(fact)) no(`${where} isn't a usable fact name`);
+      const b = facts[fact];
+      if (!b || typeof b !== "object" || Array.isArray(b)) no(`${where} must be an object with "arg"`);
+      for (const k of Object.keys(b)) if (!["arg", "scale", "map", "_why"].includes(k)) no(`${where}: "${k}" isn't allowed. A fact can only come from an argument of the call`);
+      if (typeof b.arg !== "string" || !b.arg) no(`${where} needs "arg", the argument it comes from`);
+      if (b.arg.split(".").some((s) => !s || FORBIDDEN_KEYS.has(s))) no(`${where}: "${b.arg}" isn't a usable argument path`);
+      if (b.scale !== void 0 && b.map !== void 0) no(`${where}: use "scale" or "map", not both`);
+      if (b.scale !== void 0 && (typeof b.scale !== "number" || !Number.isFinite(b.scale) || b.scale === 0)) no(`${where}: "scale" must be a non-zero number`);
+      if (b.map !== void 0) {
+        if (!b.map || typeof b.map !== "object" || Array.isArray(b.map)) no(`${where}: "map" must be an object`);
+        for (const k of Object.keys(b.map)) if (FORBIDDEN_KEYS.has(k) || !isScalar(b.map[k])) no(`${where}: "map" can only hold plain values`);
+      }
+      tools[tool].facts[fact] = { arg: b.arg, ...b.scale !== void 0 ? { scale: b.scale } : {}, ...b.map !== void 0 ? { map: b.map } : {} };
+    }
+  }
+  return { version: 1, artifact: obj.artifact, reviewed: obj.reviewed, tools };
+}
+function applyToolBindings(bindings, tool, args) {
+  const inputs = { tool };
+  const unresolved = [];
+  const facts = hasOwn(bindings.tools, tool) ? bindings.tools[tool].facts : {};
+  for (const [fact, b] of Object.entries(facts)) {
+    let v = args;
+    for (const seg of b.arg.split(".")) v = v && typeof v === "object" && !Array.isArray(v) && hasOwn(v, seg) ? v[seg] : void 0;
+    if (v === void 0 || v === null) {
+      unresolved.push({ fact, arg: b.arg, why: "missing" });
+      continue;
+    }
+    if (b.scale !== void 0) {
+      if (typeof v !== "number" || !Number.isFinite(v)) {
+        unresolved.push({ fact, arg: b.arg, why: "not_a_number" });
+        continue;
+      }
+      inputs[fact] = Number((v * b.scale).toFixed(9));
+      continue;
+    }
+    if (!isScalar(v)) {
+      unresolved.push({ fact, arg: b.arg, why: "not_a_value" });
+      continue;
+    }
+    if (b.map) {
+      if (!hasOwn(b.map, String(v))) {
+        unresolved.push({ fact, arg: b.arg, why: "not_in_map" });
+        continue;
+      }
+      inputs[fact] = b.map[String(v)];
+      continue;
+    }
+    inputs[fact] = v;
+  }
+  return { inputs, unresolved };
+}
+var WEAK = /* @__PURE__ */ new Set(["is", "has", "the", "a", "an", "of", "to", "in", "id", "name", "type", "value", "status", "code", "data", "info", "flag", "number", "num", "total", "ai", "system"]);
+var UNITS = { cents: 0.01, pence: 0.01, fils: 0.01, usd: null, dollars: null, aed: null, eur: null };
+var words = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).map((w) => w.toLowerCase()).filter(Boolean);
+var flatProperties = (props, prefix = "") => Object.entries(props ?? {}).flatMap(([k, s]) => FORBIDDEN_KEYS.has(k) ? [] : s?.type === "object" && s.properties ? flatProperties(s.properties, `${prefix}${k}.`) : [{ path: `${prefix}${k}`, schema: s }]);
+function suggestToolBindings(artifact, tools, fields) {
+  const bindings = { version: 1, artifact, reviewed: false, tools: {} };
+  const proposals = [];
+  const unbound = [];
+  for (const tool of tools) {
+    bindings.tools[tool.name] = { facts: {} };
+    const args = flatProperties(tool.inputSchema?.properties);
+    for (const field of fields) {
+      if (field.name === "tool") continue;
+      const want = words(field.name).filter((w) => !WEAK.has(w) && !(w in UNITS));
+      const scored = args.map((a) => {
+        const raw = words(a.path);
+        const have = raw.filter((w) => !WEAK.has(w) && !(w in UNITS));
+        const shared = want.filter((w) => have.includes(w));
+        const unit = raw.find((w) => w in UNITS);
+        const same = words(field.name).join("_") === raw.join("_");
+        const sameCore = want.length > 0 && want.length === have.length && shared.length === want.length;
+        return { a, shared, unit, same, sameCore, score: same ? 3 : sameCore ? 2 : shared.length ? shared.length / Math.max(want.length, have.length) : 0 };
+      }).filter((s) => s.score > 0).sort((x, y) => y.score - x.score);
+      if (!scored.length) {
+        unbound.push({ tool: tool.name, fact: field.name, candidates: [] });
+        continue;
+      }
+      const best = scored[0];
+      if (scored[1] && scored[1].score === best.score) {
+        unbound.push({ tool: tool.name, fact: field.name, candidates: scored.filter((s) => s.score === best.score).map((s) => s.a.path) });
+        continue;
+      }
+      const scale = best.unit ? UNITS[best.unit] ?? void 0 : void 0;
+      const why = best.same ? "the same name" : best.sameCore ? "the same words" : `shares "${best.shared.join(", ")}"`;
+      proposals.push({ tool: tool.name, fact: field.name, arg: best.a.path, confidence: best.same || best.sameCore ? "exact" : "likely", why: scale ? `${why}; ${best.unit} scaled by ${scale}` : why, ...scale ? { scale } : {} });
+      bindings.tools[tool.name].facts[field.name] = { arg: best.a.path, ...scale ? { scale } : {} };
+    }
+  }
+  return { bindings, proposals, unbound };
+}
+function describeSuggestion(s) {
+  const lines = [];
+  for (const tool of Object.keys(s.bindings.tools)) {
+    lines.push(`
+${tool}`);
+    for (const p of s.proposals.filter((x) => x.tool === tool)) lines.push(`  ${p.confidence === "exact" ? "matched " : "CHECK   "} ${p.fact} <- ${p.arg}${p.scale ? ` x ${p.scale}` : ""} (${p.why})`);
+    for (const u of s.unbound.filter((x) => x.tool === tool)) lines.push(`  NO MATCH ${u.fact}${u.candidates.length ? ` (could be: ${u.candidates.join(", ")})` : ""}`);
+  }
+  return lines.join("\n");
+}
+
 // src/act/bytes.ts
 var utf82 = (s) => new TextEncoder().encode(s);
 var fromUtf82 = (b) => new TextDecoder().decode(b);
@@ -6953,12 +7095,14 @@ export {
   WELL_KNOWN,
   accept,
   act,
+  applyToolBindings,
   approver,
   bindingDigest,
   buildAct,
   can,
   certificateRegistry,
   certify,
+  describeSuggestion,
   fetchDocument,
   generateSigner,
   issuer,
@@ -6969,6 +7113,7 @@ export {
   memoryStore,
   nomos,
   originOf,
+  parseToolBindings,
   passkeyApprover,
   postgresPasskeyStore,
   postgresRegistryStore,
@@ -6987,6 +7132,7 @@ export {
   signRevocationList,
   signTestimony,
   statusFor,
+  suggestToolBindings,
   verifyAct,
   verifyArtifact,
   verifyChain,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomosprotocol/sdk",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "NOMOS for TypeScript: accept() for the system that makes a change, act() for the agent that asks, the issuer, witness and approver roles, and the Exchange client. Verification is local (@nomosprotocol/verify).",
   "publishConfig": {
     "access": "public"
@@ -64,6 +64,13 @@
   ],
   "author": "NOMOS",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nomos-spec/spec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nomos-spec/spec/issues"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -74,6 +81,6 @@
   "dependencies": {
     "@noble/curves": "^2.4.0",
     "@noble/hashes": "^2.4.0",
-    "@nomosprotocol/verify": "^1.2.0"
+    "@nomosprotocol/verify": "^1.3.0"
   }
 }