@fidacy/mcp 0.2.2 → 0.2.3

package/dist/core.js

@@ -251,6 +251,10 @@ var DevFidacyCore = class {
       return null;
     return { record: record2, chainIntact: this.store.intact(), verifiedAgainstPublicKey: this.pubPem };
   }
+  async history(limit = 50) {
+    const all = this.store.records();
+    return limit > 0 && all.length > limit ? all.slice(-limit) : all;
+  }
   publicKey() {
     return this.pubPem;
   }
@@ -285,6 +289,10 @@ var HttpFidacyCore = class {
   async getProof(decisionId) {
     return this.call("/v1/audit/proof", { decisionId });
   }
+  async history(limit = 50) {
+    const res = await this.call("/v1/audit/list", { limit });
+    return res.records ?? [];
+  }
   publicKey() {
     return this.subjectPub;
   }
@@ -350,6 +358,9 @@ var FileAuditStore = class {
     if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
       record2.purpose = decision.request.purpose.slice(0, 500);
     }
+    if (typeof decision.request?.payee === "string" && decision.request.payee.trim()) {
+      record2.payee = decision.request.payee.slice(0, 200);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -359,6 +370,14 @@ var FileAuditStore = class {
       const invoice = canonInvoice(req?.invoiceRef);
       if (invoice)
         record2.invoiceRef = invoice;
+    } else {
+      if (decision.violatedRule)
+        record2.violatedRule = decision.violatedRule;
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
     }
     fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
     this.chain.push(record2);
@@ -442,7 +461,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.2.2" : "dev";
+var CLIENT_VERSION = true ? "0.2.3" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -596,6 +615,7 @@ function makeCore() {
       return dev.decide(req, subject);
     },
     getProof: (decisionId) => dev.getProof(decisionId),
+    history: (limit) => dev.history(limit),
     publicKey: () => dev.publicKey()
   };
 }

package/dist/index.js

@@ -258,6 +258,10 @@ var DevFidacyCore = class {
       return null;
     return { record: record2, chainIntact: this.store.intact(), verifiedAgainstPublicKey: this.pubPem };
   }
+  async history(limit = 50) {
+    const all = this.store.records();
+    return limit > 0 && all.length > limit ? all.slice(-limit) : all;
+  }
   publicKey() {
     return this.pubPem;
   }
@@ -292,6 +296,10 @@ var HttpFidacyCore = class {
   async getProof(decisionId) {
     return this.call("/v1/audit/proof", { decisionId });
   }
+  async history(limit = 50) {
+    const res = await this.call("/v1/audit/list", { limit });
+    return res.records ?? [];
+  }
   publicKey() {
     return this.subjectPub;
   }
@@ -357,6 +365,9 @@ var FileAuditStore = class {
     if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
       record2.purpose = decision.request.purpose.slice(0, 500);
     }
+    if (typeof decision.request?.payee === "string" && decision.request.payee.trim()) {
+      record2.payee = decision.request.payee.slice(0, 200);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -366,6 +377,14 @@ var FileAuditStore = class {
       const invoice = canonInvoice(req?.invoiceRef);
       if (invoice)
         record2.invoiceRef = invoice;
+    } else {
+      if (decision.violatedRule)
+        record2.violatedRule = decision.violatedRule;
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
     }
     fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
     this.chain.push(record2);
@@ -471,7 +490,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.2.2" : "dev";
+var CLIENT_VERSION = true ? "0.2.3" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -628,6 +647,7 @@ function makeCore() {
       return dev.decide(req, subject2);
     },
     getProof: (decisionId) => dev.getProof(decisionId),
+    history: (limit) => dev.history(limit),
     publicKey: () => dev.publicKey()
   };
 }
@@ -814,7 +834,7 @@ async function findArtifacts(sha2562, cfg) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.2.2" : "dev";
+var CLIENT_VERSION2 = true ? "0.2.3" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -985,11 +1005,124 @@ function activationBootLine() {
   return ` Anonymous trial: ${used}/${FREE_DECISIONS} free decisions used; after that the firewall requires a free API key.`;
 }
 
+// src/reporting.ts
+function withinDays(records, days, now = Date.now()) {
+  if (!Number.isFinite(days) || days <= 0) return [...records];
+  const cutoff = now - days * 864e5;
+  return records.filter((r) => {
+    const t = Date.parse(r.ts);
+    return Number.isFinite(t) && t >= cutoff;
+  });
+}
+var addTo = (bucket, key, value) => {
+  bucket[key] = (bucket[key] ?? 0) + value;
+};
+function summarize(records, days, now = Date.now()) {
+  const rows = withinDays(records, days, now);
+  const out = {
+    window_days: days,
+    decisions: rows.length,
+    allowed: 0,
+    denied: 0,
+    allowed_totals: {},
+    blocked_totals: {},
+    denied_by_rule: {},
+    payees_paid: [],
+    amount_unknown: 0,
+    first_ts: rows.length ? rows[0].ts : null,
+    last_ts: rows.length ? rows[rows.length - 1].ts : null
+  };
+  const paid = /* @__PURE__ */ new Set();
+  for (const r of rows) {
+    const known = typeof r.amount === "number" && Number.isFinite(r.amount);
+    if (!known) out.amount_unknown += 1;
+    const ccy = r.currency ?? "unknown";
+    if (r.status === "ALLOW") {
+      out.allowed += 1;
+      if (known) addTo(out.allowed_totals, ccy, r.amount);
+      if (r.payee) paid.add(r.payee);
+    } else {
+      out.denied += 1;
+      if (known) addTo(out.blocked_totals, ccy, r.amount);
+      addTo(out.denied_by_rule, r.violatedRule ?? "not_recorded", 1);
+    }
+  }
+  out.payees_paid = [...paid].sort();
+  return out;
+}
+var money = (totals) => {
+  const parts = Object.entries(totals).map(([ccy, v]) => `${v.toLocaleString("en-US")} ${ccy}`);
+  return parts.length ? parts.join(", ") : "0";
+};
+function renderSummary(s) {
+  if (s.decisions === 0) {
+    return `No agent payment decisions in the last ${s.window_days} day(s). The firewall is active and has nothing to report, which is the expected state until an agent attempts a payment.`;
+  }
+  const lines = [
+    `Last ${s.window_days} day(s): ${s.decisions} payment decision(s), ${s.allowed} allowed and ${s.denied} blocked before execution.`,
+    `Paid: ${money(s.allowed_totals)}${s.payees_paid.length ? ` across ${s.payees_paid.length} payee(s): ${s.payees_paid.slice(0, 8).join(", ")}${s.payees_paid.length > 8 ? ", \u2026" : ""}` : ""}.`
+  ];
+  if (s.denied > 0) {
+    const ranked = Object.entries(s.denied_by_rule).sort((a, b) => b[1] - a[1]);
+    lines.push(`Blocked: ${money(s.blocked_totals)} in attempted value. By rule: ${ranked.map(([rule, n]) => `${rule} (${n})`).join(", ")}.`);
+  }
+  if (s.amount_unknown > 0) {
+    lines.push(`${s.amount_unknown} record(s) in this window predate amount logging, so the totals above are a floor, not the exact figure.`);
+  }
+  return lines.join("\n");
+}
+function toRows(records, status, limit) {
+  const filtered = status === "all" ? [...records] : records.filter((r) => r.status === status);
+  return filtered.slice(-Math.max(1, limit)).reverse().map((r) => ({
+    seq: r.seq,
+    decisionId: r.decisionId,
+    status: r.status,
+    ts: r.ts,
+    payee: r.payee,
+    amount: r.amount,
+    currency: r.currency,
+    purpose: r.purpose,
+    violatedRule: r.violatedRule,
+    invoiceRef: r.invoiceRef
+  }));
+}
+function renderRows(rows) {
+  if (!rows.length) return "No decisions match that filter yet.";
+  return rows.map((r) => {
+    const amount = typeof r.amount === "number" ? `${r.amount.toLocaleString("en-US")} ${r.currency ?? ""}`.trim() : "amount not recorded";
+    const who = r.payee ?? "payee not recorded";
+    const why = r.status === "DENY" ? ` blocked by ${r.violatedRule ?? "a rule not recorded on this older entry"}.` : "";
+    const said = r.purpose ? ` Agent's stated reason: "${r.purpose}".` : "";
+    return `#${r.seq} ${r.ts} ${r.status} ${amount} to ${who}.${why}${said} (decision ${r.decisionId})`;
+  }).join("\n");
+}
+function explainRule(rule, payee) {
+  if (!rule) return "This entry predates readable rule logging, so the specific rule is not on the record. The decision payload is still covered by the chain digest.";
+  if (rule.startsWith("payee_not_in_allowlist"))
+    return `The payee${payee ? ` "${payee}"` : ""} is not on the mandate's allowlist. This is the deny-by-default rule doing its job: an agent can only pay counterparties a human put on the list, which is what stops a swapped or lookalike vendor.`;
+  if (rule.startsWith("category_not_allowed"))
+    return "The stated purpose category is not one the mandate permits for this agent.";
+  if (rule.startsWith("currency_not_allowed"))
+    return "The payment currency is not the mandate's currency.";
+  if (rule.startsWith("per_tx") || rule.includes("perTxMax"))
+    return "The amount exceeds the per-transaction ceiling in the mandate.";
+  if (rule.includes("maxTotal") || rule.startsWith("budget"))
+    return "The payment would push cumulative spend past the mandate's total budget for the window.";
+  if (rule.startsWith("invoice") || rule.includes("duplicate"))
+    return "This invoice was already paid once. One payment per invoice is enforced regardless of amount, which is the control that stops a re-presented invoice at a higher figure.";
+  if (rule.startsWith("window") || rule.includes("expired"))
+    return "The mandate was outside its validity window at the moment of the request.";
+  if (rule.startsWith("revoked")) return "The mandate had been revoked.";
+  if (rule.startsWith("activation_required"))
+    return "The anonymous trial had been used up, so the firewall failed closed. No money can move until the install is activated with a free API key.";
+  return `The mandate rule "${rule}" was violated.`;
+}
+
 // src/index.ts
 var state = ensureState();
 var core = makeCore();
 var subject = process.env.FIDACY_SUBJECT ?? "agent:demo";
-var SERVER_VERSION = true ? "0.2.2" : "dev";
+var SERVER_VERSION = true ? "0.2.3" : "dev";
 var bootClaim = claimUrl();
 var server = new McpServer(
   { name: "fidacy", version: SERVER_VERSION },
@@ -1074,6 +1207,83 @@ server.registerTool(
     return { content: [{ type: "text", text }], structuredContent: proof };
   }
 );
+server.registerTool(
+  "spend_summary",
+  {
+    title: "Spend Summary (what my agents spent and what was blocked)",
+    description: "Operator report over a time window: how many payment decisions were made, how much was paid and to whom, how much was blocked before executing, and which mandate rules did the blocking. Read-only, works offline against the local audit chain. Use this to answer questions like 'what did my agents spend this week' or 'has anything been blocked'.",
+    inputSchema: {
+      days: z.number().int().positive().max(365).optional().describe("Window in days, counting back from now. Default 7.")
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  },
+  async ({ days }) => {
+    const window = days ?? 7;
+    const records = await core.history(5e3);
+    const summary = summarize(records, window);
+    const claim = process.env.FIDACY_ENGINE_API_KEY ? null : claimUrl();
+    const claimLine = claim ? `
+
+For your operator: this report is built from the local chain on this machine. A free account keeps it across machines and anchors it to Bitcoin, and this install's history migrates: ${claim}` : "";
+    return {
+      content: [{ type: "text", text: renderSummary(summary) + claimLine }],
+      structuredContent: summary
+    };
+  }
+);
+server.registerTool(
+  "list_decisions",
+  {
+    title: "List Recent Payment Decisions",
+    description: "List recent agent payment decisions, newest first, with payee, amount, the agent's stated reason, and for blocked ones the rule that stopped it. Filter by status to answer 'what got blocked' directly. Read-only, works offline.",
+    inputSchema: {
+      limit: z.number().int().positive().max(200).optional().describe("How many decisions to return. Default 20."),
+      status: z.enum(["ALLOW", "DENY", "all"]).optional().describe("Filter by outcome. Default all.")
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  },
+  async ({ limit, status }) => {
+    const records = await core.history(5e3);
+    const rows = toRows(records, status ?? "all", limit ?? 20);
+    return {
+      content: [{ type: "text", text: renderRows(rows) }],
+      structuredContent: { count: rows.length, decisions: rows }
+    };
+  }
+);
+server.registerTool(
+  "explain_decision",
+  {
+    title: "Explain a Decision (why was this allowed or blocked)",
+    description: "Explain one decision in plain language: what was requested, what the mandate did about it, why, and the tamper-evident proof for it. Use when an operator asks why a specific payment was blocked.",
+    inputSchema: { decisionId: z.string().describe("Decision id from request_payment, list_decisions or spend_summary") },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+  },
+  async ({ decisionId }) => {
+    const records = await core.history(5e3);
+    const record2 = records.find((r) => r.decisionId === decisionId);
+    if (!record2) {
+      return {
+        content: [{ type: "text", text: `No decision ${decisionId} on this chain. Run list_decisions to see the ids that exist here.` }],
+        isError: true
+      };
+    }
+    const proof = await core.getProof(decisionId);
+    const amount = typeof record2.amount === "number" ? `${record2.amount.toLocaleString("en-US")} ${record2.currency ?? ""}`.trim() : "an amount that was not recorded";
+    const head = record2.status === "ALLOW" ? `Decision ${decisionId} ALLOWED a payment of ${amount}${record2.payee ? ` to ${record2.payee}` : ""} at ${record2.ts}. It was inside every rule of the active mandate, and a signed grant was issued so a downstream executor could settle it.` : `Decision ${decisionId} BLOCKED a payment of ${amount}${record2.payee ? ` to ${record2.payee}` : ""} at ${record2.ts}. No money moved and no grant was issued.`;
+    const why = record2.status === "DENY" ? `
+
+Why: ${explainRule(record2.violatedRule, record2.payee)}` : "";
+    const said = record2.purpose ? `
+
+The agent's stated reason at the time: "${record2.purpose}".` : "";
+    const integrity = proof ? `
+
+Proof: entry #${record2.seq} in the hash-chained audit, chain currently ${proof.chainIntact ? "intact" : "BROKEN (records were altered or removed)"}. Call get_audit_proof for the full portable proof.` : "";
+    const payload = { record: record2, explanation: explainRule(record2.violatedRule, record2.payee), chainIntact: proof?.chainIntact ?? null };
+    return { content: [{ type: "text", text: head + why + said + integrity }], structuredContent: payload };
+  }
+);
 server.registerTool(
   "assess_action",
   {

package/dist/lib.js

@@ -289,6 +289,10 @@ var DevFidacyCore = class {
       return null;
     return { record: record2, chainIntact: this.store.intact(), verifiedAgainstPublicKey: this.pubPem };
   }
+  async history(limit = 50) {
+    const all = this.store.records();
+    return limit > 0 && all.length > limit ? all.slice(-limit) : all;
+  }
   publicKey() {
     return this.pubPem;
   }
@@ -323,6 +327,10 @@ var HttpFidacyCore = class {
   async getProof(decisionId) {
     return this.call("/v1/audit/proof", { decisionId });
   }
+  async history(limit = 50) {
+    const res = await this.call("/v1/audit/list", { limit });
+    return res.records ?? [];
+  }
   publicKey() {
     return this.subjectPub;
   }
@@ -388,6 +396,9 @@ var FileAuditStore = class {
     if (typeof decision.request?.purpose === "string" && decision.request.purpose.trim()) {
       record2.purpose = decision.request.purpose.slice(0, 500);
     }
+    if (typeof decision.request?.payee === "string" && decision.request.payee.trim()) {
+      record2.payee = decision.request.payee.slice(0, 200);
+    }
     if (decision.status === "ALLOW") {
       const req = decision.request;
       if (typeof req?.amount === "number" && Number.isFinite(req.amount))
@@ -397,6 +408,14 @@ var FileAuditStore = class {
       const invoice = canonInvoice(req?.invoiceRef);
       if (invoice)
         record2.invoiceRef = invoice;
+    } else {
+      if (decision.violatedRule)
+        record2.violatedRule = decision.violatedRule;
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
     }
     fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
     this.chain.push(record2);
@@ -594,7 +613,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.2.2" : "dev";
+var CLIENT_VERSION = true ? "0.2.3" : "dev";
 function bandOf(amount) {
   if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0) return void 0;
   if (amount < 10) return "lt10";
@@ -754,6 +773,7 @@ function makeCore() {
       return dev.decide(req, subject);
     },
     getProof: (decisionId) => dev.getProof(decisionId),
+    history: (limit) => dev.history(limit),
     publicKey: () => dev.publicKey()
   };
 }
@@ -771,7 +791,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.2.2" : "dev";
+var CLIENT_VERSION2 = true ? "0.2.3" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -920,6 +940,119 @@ function activationBootLine() {
   }
   return ` Anonymous trial: ${used}/${FREE_DECISIONS} free decisions used; after that the firewall requires a free API key.`;
 }
+
+// src/reporting.ts
+function withinDays(records, days, now = Date.now()) {
+  if (!Number.isFinite(days) || days <= 0) return [...records];
+  const cutoff = now - days * 864e5;
+  return records.filter((r) => {
+    const t = Date.parse(r.ts);
+    return Number.isFinite(t) && t >= cutoff;
+  });
+}
+var addTo = (bucket, key, value) => {
+  bucket[key] = (bucket[key] ?? 0) + value;
+};
+function summarize(records, days, now = Date.now()) {
+  const rows = withinDays(records, days, now);
+  const out = {
+    window_days: days,
+    decisions: rows.length,
+    allowed: 0,
+    denied: 0,
+    allowed_totals: {},
+    blocked_totals: {},
+    denied_by_rule: {},
+    payees_paid: [],
+    amount_unknown: 0,
+    first_ts: rows.length ? rows[0].ts : null,
+    last_ts: rows.length ? rows[rows.length - 1].ts : null
+  };
+  const paid = /* @__PURE__ */ new Set();
+  for (const r of rows) {
+    const known = typeof r.amount === "number" && Number.isFinite(r.amount);
+    if (!known) out.amount_unknown += 1;
+    const ccy = r.currency ?? "unknown";
+    if (r.status === "ALLOW") {
+      out.allowed += 1;
+      if (known) addTo(out.allowed_totals, ccy, r.amount);
+      if (r.payee) paid.add(r.payee);
+    } else {
+      out.denied += 1;
+      if (known) addTo(out.blocked_totals, ccy, r.amount);
+      addTo(out.denied_by_rule, r.violatedRule ?? "not_recorded", 1);
+    }
+  }
+  out.payees_paid = [...paid].sort();
+  return out;
+}
+var money = (totals) => {
+  const parts = Object.entries(totals).map(([ccy, v]) => `${v.toLocaleString("en-US")} ${ccy}`);
+  return parts.length ? parts.join(", ") : "0";
+};
+function renderSummary(s) {
+  if (s.decisions === 0) {
+    return `No agent payment decisions in the last ${s.window_days} day(s). The firewall is active and has nothing to report, which is the expected state until an agent attempts a payment.`;
+  }
+  const lines = [
+    `Last ${s.window_days} day(s): ${s.decisions} payment decision(s), ${s.allowed} allowed and ${s.denied} blocked before execution.`,
+    `Paid: ${money(s.allowed_totals)}${s.payees_paid.length ? ` across ${s.payees_paid.length} payee(s): ${s.payees_paid.slice(0, 8).join(", ")}${s.payees_paid.length > 8 ? ", \u2026" : ""}` : ""}.`
+  ];
+  if (s.denied > 0) {
+    const ranked = Object.entries(s.denied_by_rule).sort((a, b) => b[1] - a[1]);
+    lines.push(`Blocked: ${money(s.blocked_totals)} in attempted value. By rule: ${ranked.map(([rule, n]) => `${rule} (${n})`).join(", ")}.`);
+  }
+  if (s.amount_unknown > 0) {
+    lines.push(`${s.amount_unknown} record(s) in this window predate amount logging, so the totals above are a floor, not the exact figure.`);
+  }
+  return lines.join("\n");
+}
+function toRows(records, status, limit) {
+  const filtered = status === "all" ? [...records] : records.filter((r) => r.status === status);
+  return filtered.slice(-Math.max(1, limit)).reverse().map((r) => ({
+    seq: r.seq,
+    decisionId: r.decisionId,
+    status: r.status,
+    ts: r.ts,
+    payee: r.payee,
+    amount: r.amount,
+    currency: r.currency,
+    purpose: r.purpose,
+    violatedRule: r.violatedRule,
+    invoiceRef: r.invoiceRef
+  }));
+}
+function renderRows(rows) {
+  if (!rows.length) return "No decisions match that filter yet.";
+  return rows.map((r) => {
+    const amount = typeof r.amount === "number" ? `${r.amount.toLocaleString("en-US")} ${r.currency ?? ""}`.trim() : "amount not recorded";
+    const who = r.payee ?? "payee not recorded";
+    const why = r.status === "DENY" ? ` blocked by ${r.violatedRule ?? "a rule not recorded on this older entry"}.` : "";
+    const said = r.purpose ? ` Agent's stated reason: "${r.purpose}".` : "";
+    return `#${r.seq} ${r.ts} ${r.status} ${amount} to ${who}.${why}${said} (decision ${r.decisionId})`;
+  }).join("\n");
+}
+function explainRule(rule, payee) {
+  if (!rule) return "This entry predates readable rule logging, so the specific rule is not on the record. The decision payload is still covered by the chain digest.";
+  if (rule.startsWith("payee_not_in_allowlist"))
+    return `The payee${payee ? ` "${payee}"` : ""} is not on the mandate's allowlist. This is the deny-by-default rule doing its job: an agent can only pay counterparties a human put on the list, which is what stops a swapped or lookalike vendor.`;
+  if (rule.startsWith("category_not_allowed"))
+    return "The stated purpose category is not one the mandate permits for this agent.";
+  if (rule.startsWith("currency_not_allowed"))
+    return "The payment currency is not the mandate's currency.";
+  if (rule.startsWith("per_tx") || rule.includes("perTxMax"))
+    return "The amount exceeds the per-transaction ceiling in the mandate.";
+  if (rule.includes("maxTotal") || rule.startsWith("budget"))
+    return "The payment would push cumulative spend past the mandate's total budget for the window.";
+  if (rule.startsWith("invoice") || rule.includes("duplicate"))
+    return "This invoice was already paid once. One payment per invoice is enforced regardless of amount, which is the control that stops a re-presented invoice at a higher figure.";
+  if (rule.startsWith("window") || rule.includes("expired"))
+    return "The mandate was outside its validity window at the moment of the request.";
+  if (rule.startsWith("revoked")) return "The mandate had been revoked.";
+  if (rule.startsWith("activation_required"))
+    return "The anonymous trial had been used up, so the firewall failed closed. No money can move until the install is activated with a free API key.";
+  return `The mandate rule "${rule}" was violated.`;
+}
 export {
   DevFidacyCore,
   FREE_DECISIONS,
@@ -935,6 +1068,7 @@ export {
   decisionNudge,
   ensureState,
   evaluate,
+  explainRule,
   hasEngineKey,
   httpRedeem,
   installAgeDays,
@@ -948,16 +1082,21 @@ export {
   recordAgentActive,
   recordInstall,
   remainingFree,
+  renderRows,
+  renderSummary,
   requestUpgrade,
   requireHttpsBase,
   setTelemetryShell,
   sha256,
   sign,
   stableStringify,
+  summarize,
+  toRows,
   trialCountdownLine,
   upgradeUrl,
   validateRequest,
   verify,
   verifyGrant,
-  weekOneBootNudge
+  weekOneBootNudge,
+  withinDays
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Fidacy action firewall for AI agents. Mandate-gated payment authorization as an MCP server.",
   "license": "Apache-2.0",
   "homepage": "https://fidacy.com",