@kyaki/agents 0.1.0

package/src/auditor.ts

@@ -0,0 +1,342 @@
+/**
+ * auditor.ts — The Auditor: the third agent on the Mandate OS, and the only
+ * one that never spends.
+ *
+ * Where the Procurer pushes money outward and the Treasurer moves the balance
+ * sheet, the Auditor *proves the whole fleet stayed inside its authority*. It
+ * is the agent that operationalizes the project's central claim — "the books
+ * are self-auditing" — by turning it into a concrete, signed artifact.
+ *
+ * It composes existing rings; it invents no new kernel primitive:
+ *   L0  AuditLog.verifyChain      — is the record itself tamper-free?
+ *   L0  verifyTransaction         — does each committed spend STILL verify,
+ *                                   re-run against state as of its own commit?
+ *   L1  OrgSpendLedger semantics  — did aggregate exposure breach the org cap?
+ *   L1  AutonomyLadder.demote     — punish the agent the instant a provable
+ *                                   cryptographic anomaly is found.
+ *
+ * The audit produces a `KyaAuditAttestation`: an Ed25519 signature by the
+ * auditor's own key over the canonical set of findings + the chain head. Like
+ * a mandate, an intent, or a CFO approval, the audit-of-record is a verifiable
+ * object — not a database row asserting "trust me."
+ *
+ * Reconciliation principle (inherited from the Procurer's savings report): if
+ * the hash chain does not verify, the committed record cannot be trusted, so
+ * the report says so loudly rather than quietly reporting clean.
+ */
+import {
+  canonicalBytes, fromBase58, publicKeyFromDid, sign, toBase58, verifySignature,
+  verifyTransaction, MemorySpendStore,
+  type AgentKeys, type AuditEvent, type AuditLog, type SpendMandate,
+  type TransactionIntent, type VerificationContext,
+} from '@kyaki/core';
+import { AutonomyLadder, type SpendPolicy } from '@kyaki/policy';
+
+const DAY_MS = 24 * 3600 * 1000;
+
+/** Kernel deny-reasons that prove cryptographic misbehavior by a named agent
+ *  key — these, and only these, cost the agent a rung on the autonomy ladder. */
+const SECURITY_REASONS = new Set([
+  'MANDATE_SIGNATURE_INVALID',
+  'INTENT_SIGNATURE_INVALID',
+  'AGENT_MISMATCH',
+  'MANDATE_ID_MISMATCH',
+]);
+
+export type Severity = 'info' | 'warning' | 'violation' | 'critical';
+
+export interface Finding {
+  code: string;
+  severity: Severity;
+  detail: string;
+  agentDid?: string;
+  mandateId?: string;
+  intentId?: string;
+}
+
+/** A committed spend, presented to the Auditor as the verifiable pair the
+ *  kernel originally checked: the agent's signed intent + the principal's
+ *  signed mandate it named. */
+export interface CommittedSpend {
+  intent: TransactionIntent;
+  mandate: SpendMandate;
+}
+
+/** A revocation event with a timestamp. The live RevocationStore is timeless
+ *  (boolean); for forensic "did the spend happen AFTER revocation?" the
+ *  Auditor needs the revocation's `at`. */
+export interface RevocationRecord {
+  mandateId: string;
+  at: string;
+}
+
+export interface AuditAttestation {
+  type: 'KyaAuditAttestation';
+  auditor: string;
+  chainHead: string;
+  at: string;
+  findings: Finding[];
+  signature: string;
+}
+
+export interface AuditReport {
+  at: string;
+  chainValid: boolean;
+  clean: boolean;
+  findings: Finding[];
+  summary: Record<Severity, number>;
+  reconciledMandates: number;
+  reconciledSpends: number;
+  demoted: string[];
+  attestation: AuditAttestation;
+}
+
+export interface AuditInput {
+  committed: CommittedSpend[];
+  revocations?: RevocationRecord[];
+}
+
+export interface AuditorConfig {
+  auditorKeys: AgentKeys;
+  /** The hash chain under examination (the fleet's audit-of-record). */
+  audit: AuditLog;
+  /** Org policy — only `orgLimits.dailyCap` is consulted, for aggregate exposure. */
+  policy?: SpendPolicy;
+  /** When present, agents caught in a security anomaly are demoted. */
+  ladder?: AutonomyLadder;
+  /** Where the Auditor anchors its OWN result, so the audit is itself audited. */
+  oversight?: AuditLog;
+  /** Chain event types that denote a committed spend, for chain↔object
+   *  reconciliation. Defaults to the Procurer's commit events; pass the
+   *  Treasurer's (or any agent's) commit event types to widen coverage. */
+  committedEventTypes?: string[];
+  now?: Date;
+}
+
+const GENESIS = '0'.repeat(64);
+const DEFAULT_COMMIT_TYPES = ['procurement.purchased', 'approval.executed'];
+
+const EMPTY_SUMMARY = (): Record<Severity, number> => ({ info: 0, warning: 0, violation: 0, critical: 0 });
+
+/** Recompute and check an attestation's signature. Tampering with any finding,
+ *  the chain head, or the timestamp invalidates it — exactly like a mandate. */
+export function verifyAuditAttestation(att: AuditAttestation): boolean {
+  try {
+    const { signature, ...doc } = att;
+    const publicKey = publicKeyFromDid(att.auditor);
+    return verifySignature(fromBase58(signature), canonicalBytes(doc), publicKey);
+  } catch {
+    return false;
+  }
+}
+
+export class AuditorAgent {
+  constructor(private readonly cfg: AuditorConfig) {}
+
+  private now(): Date { return this.cfg.now ?? new Date(); }
+
+  /** The intent id a commit-class chain event points at (txnId or intentId). */
+  private intentIdOf(event: AuditEvent): string | undefined {
+    return (event as { txnId?: string; intentId?: string }).txnId
+      ?? (event as { intentId?: string }).intentId;
+  }
+
+  private commitTypes(): Set<string> {
+    return new Set(this.cfg.committedEventTypes ?? DEFAULT_COMMIT_TYPES);
+  }
+
+  async audit(input: AuditInput): Promise<AuditReport> {
+    const at = this.now().toISOString();
+    const findings: Finding[] = [];
+    const revokedAt = new Map<string, number>();
+    for (const r of input.revocations ?? []) revokedAt.set(r.mandateId, Date.parse(r.at));
+
+    // 1. Chain integrity. If the record is forged, nothing built on it is trustworthy.
+    const chainValid = this.cfg.audit.verifyChain();
+    if (!chainValid) {
+      findings.push({
+        code: 'CHAIN_BROKEN', severity: 'critical',
+        detail: 'Audit hash chain failed verification — the committed record has been tampered with; downstream reconciliation is not trustworthy.',
+      });
+    }
+
+    // Order committed spends by their own timestamp so per-mandate cumulative
+    // and velocity re-checks see only what preceded each spend.
+    const ordered = input.committed
+      .map((c, i) => ({ c, i, t: Date.parse(c.intent.timestamp) }))
+      .sort((a, b) => (a.t - b.t) || (a.i - b.i));
+
+    const mandates = new Set<string>();
+    const nonceSeen = new Map<string, string>();   // nonce -> first intentId
+    const intentIdSeen = new Map<string, number>();
+
+    // 2. Per-spend re-verification, AS OF the spend's own commit time.
+    for (let pos = 0; pos < ordered.length; pos++) {
+      const { c } = ordered[pos]!;
+      const { intent, mandate } = c;
+      mandates.add(mandate.id);
+
+      // Reconstruct mandate state as it stood just before this spend: every
+      // strictly-earlier committed spend on the SAME mandate (ordered is a
+      // stable timestamp sort, so positions < pos are exactly those).
+      const spendTime = new Date(Date.parse(intent.timestamp));
+      const spend = new MemorySpendStore();
+      for (let k = 0; k < pos; k++) {
+        const prior = ordered[k]!.c.intent;
+        if (prior.mandateId !== intent.mandateId) continue;
+        await spend.record(prior.mandateId, prior.amount, prior.id, new Date(ordered[k]!.t));
+      }
+      const ctx: VerificationContext = { spend, now: spendTime };
+      const res = await verifyTransaction(mandate, intent, ctx);
+      if (res.decision === 'deny') {
+        for (const reason of res.reasons) {
+          findings.push({
+            code: reason,
+            severity: SECURITY_REASONS.has(reason) ? 'critical' : 'violation',
+            detail: `Committed spend fails re-verification as of its own timestamp: ${reason}. The kernel should never have allowed it.`,
+            agentDid: intent.agent, mandateId: mandate.id, intentId: intent.id,
+          });
+        }
+      }
+
+      // 2b. Authority that has since lapsed (the spend was fine; the mandate is now dead).
+      if (Date.parse(mandate.validUntil) < this.now().getTime()) {
+        findings.push({
+          code: 'AUTHORITY_LAPSED', severity: 'warning',
+          detail: 'The mandate behind a committed spend has since expired. The spend was authorized when made; the authority is no longer live.',
+          agentDid: intent.agent, mandateId: mandate.id, intentId: intent.id,
+        });
+      }
+
+      // 2c. Spend AFTER revocation — a real breach.
+      const rev = revokedAt.get(mandate.id);
+      if (rev !== undefined && Date.parse(intent.timestamp) >= rev) {
+        findings.push({
+          code: 'SPEND_AFTER_REVOCATION', severity: 'critical',
+          detail: 'A spend committed at or after the mandate was revoked.',
+          agentDid: intent.agent, mandateId: mandate.id, intentId: intent.id,
+        });
+      }
+
+      // 3. Ledger-level duplicate detection: replay / double-spend that slipped in.
+      const priorNonce = nonceSeen.get(intent.nonce);
+      if (priorNonce && priorNonce !== intent.id) {
+        findings.push({
+          code: 'REPLAY_IN_LEDGER', severity: 'critical',
+          detail: `Duplicate nonce across committed intents (${priorNonce} and ${intent.id}) — a replay reached the ledger.`,
+          agentDid: intent.agent, mandateId: mandate.id, intentId: intent.id,
+        });
+      } else if (!priorNonce) {
+        nonceSeen.set(intent.nonce, intent.id);
+      }
+      intentIdSeen.set(intent.id, (intentIdSeen.get(intent.id) ?? 0) + 1);
+    }
+
+    for (const [intentId, count] of intentIdSeen) {
+      if (count > 1) {
+        findings.push({
+          code: 'DUPLICATE_INTENT_ID', severity: 'critical',
+          detail: `Intent id ${intentId} appears ${count}× in the committed ledger.`,
+          intentId,
+        });
+      }
+    }
+
+    // 4. Aggregate org exposure (cross-mandate) within the rolling day.
+    const dailyCap = this.cfg.policy?.orgLimits?.dailyCap;
+    if (dailyCap !== undefined) {
+      const tNow = this.now().getTime();
+      const spentToday = input.committed
+        .filter((c) => tNow - Date.parse(c.intent.timestamp) < DAY_MS)
+        .reduce((s, c) => s + c.intent.amount, 0);
+      if (spentToday > dailyCap) {
+        findings.push({
+          code: 'ORG_EXPOSURE_BREACH', severity: 'violation',
+          detail: `Aggregate spend in the last 24h (${spentToday}) exceeds the org daily cap (${dailyCap}).`,
+        });
+      }
+    }
+
+    // 5. Coverage: the chain and the signed objects must reconcile, both ways.
+    //    (Only meaningful if the chain verifies in the first place.)
+    if (chainValid) {
+      const commitTypes = this.commitTypes();
+      const chainIntentIds = new Set<string>();
+      for (const e of this.cfg.audit.entries()) {
+        if (!commitTypes.has(e.event.type)) continue;
+        const id = this.intentIdOf(e.event);
+        if (id) chainIntentIds.add(id);
+      }
+      const committedIds = new Set(input.committed.map((c) => c.intent.id));
+
+      for (const c of input.committed) {
+        if (!chainIntentIds.has(c.intent.id)) {
+          findings.push({
+            code: 'UNRECORDED_SPEND', severity: 'critical',
+            detail: 'A signed, committed intent has no matching entry in the audit chain — money moved with no record.',
+            agentDid: c.intent.agent, mandateId: c.intent.mandateId, intentId: c.intent.id,
+          });
+        }
+      }
+      for (const id of chainIntentIds) {
+        if (!committedIds.has(id)) {
+          findings.push({
+            code: 'PHANTOM_ENTRY', severity: 'critical',
+            detail: 'A commit entry in the audit chain references an intent with no backing signed object — a record with no provable spend.',
+            intentId: id,
+          });
+        }
+      }
+    }
+
+    // 6. Enforcement: demote every agent provably caught in a security anomaly,
+    //    once per audit (asymmetric, instant — the ladder's whole purpose).
+    const offenders = new Set<string>();
+    for (const f of findings) {
+      const isSecurity = SECURITY_REASONS.has(f.code) || f.code === 'SPEND_AFTER_REVOCATION' || f.code === 'REPLAY_IN_LEDGER';
+      if (isSecurity && f.agentDid) offenders.add(f.agentDid);
+    }
+    const demoted: string[] = [];
+    if (this.cfg.ladder) {
+      for (const agentDid of offenders) {
+        this.cfg.ladder.record(agentDid, 'security_anomaly');
+        demoted.push(agentDid);
+      }
+    }
+
+    // 7. Tally, sign the attestation, and anchor the audit-of-the-audit.
+    const summary = EMPTY_SUMMARY();
+    for (const f of findings) summary[f.severity] += 1;
+    const clean = summary.violation === 0 && summary.critical === 0;
+
+    const entries = this.cfg.audit.entries();
+    const chainHead = entries.length > 0 ? entries[entries.length - 1]!.hash : GENESIS;
+    const attestation = this.signAttestation(chainHead, at, findings);
+
+    this.cfg.oversight?.append({
+      type: 'audit.completed',
+      auditor: this.cfg.auditorKeys.did,
+      chainHead, chainValid, clean,
+      findingCount: findings.length,
+      summary,
+      demoted,
+    } as AuditEvent, this.now());
+
+    return {
+      at, chainValid, clean, findings, summary,
+      reconciledMandates: mandates.size,
+      reconciledSpends: input.committed.length,
+      demoted, attestation,
+    };
+  }
+
+  private signAttestation(chainHead: string, at: string, findings: Finding[]): AuditAttestation {
+    const doc = {
+      type: 'KyaAuditAttestation' as const,
+      auditor: this.cfg.auditorKeys.did,
+      chainHead, at, findings,
+    };
+    const signature = toBase58(sign(canonicalBytes(doc), this.cfg.auditorKeys.privateKey));
+    return { ...doc, signature };
+  }
+}

package/src/continuous-auditor.ts

@@ -0,0 +1,68 @@
+/**
+ * continuous-auditor.ts — the operator surface around the Auditor.
+ *
+ * The Auditor answers one question per call. An operator (or the CFO inbox)
+ * wants the *running* answer: has the fleet ever drifted, how long has it been
+ * clean, and what is the tamper-evident history of every attestation it signed?
+ *
+ * This wraps AuditorAgent into a run-on-demand loop — drive it from a cron, a
+ * queue, or a `while` loop — and folds each pass into a running record. The
+ * `oversight` AuditLog shared via config anchors every run into a hash chain,
+ * so the audit history is itself audited. Each signed attestation is a portable
+ * object the human-governance ring can ingest and verify offline.
+ */
+import { AuditorAgent, type AuditAttestation, type AuditInput, type AuditReport, type AuditorConfig } from './auditor.js';
+
+export interface AuditHealth {
+  runs: number;
+  /** Has ANY pass come back non-clean? Monitors latch on this. */
+  everDirty: boolean;
+  /** Consecutive clean passes ending at the latest run. */
+  cleanStreak: number;
+  /** Findings in the most recent pass. */
+  openFindings: number;
+  lastAuditAt?: string;
+  lastAttestation?: AuditAttestation;
+}
+
+export class ContinuousAuditor {
+  private readonly auditor: AuditorAgent;
+  private readonly reports: AuditReport[] = [];
+
+  constructor(cfg: AuditorConfig) {
+    this.auditor = new AuditorAgent(cfg);
+  }
+
+  /** Run one audit pass and fold it into the running record. */
+  async run(input: AuditInput): Promise<AuditReport> {
+    const report = await this.auditor.audit(input);
+    this.reports.push(report);
+    return report;
+  }
+
+  /** Every signed attestation, in run order — the audit-of-record stream. */
+  attestations(): AuditAttestation[] {
+    return this.reports.map((r) => r.attestation);
+  }
+
+  history(): readonly AuditReport[] {
+    return this.reports;
+  }
+
+  /** A one-glance operational summary for a dashboard or the CFO inbox. */
+  health(): AuditHealth {
+    let cleanStreak = 0;
+    for (let i = this.reports.length - 1; i >= 0; i--) {
+      if (!this.reports[i]!.clean) break;
+      cleanStreak += 1;
+    }
+    const last = this.reports[this.reports.length - 1];
+    return {
+      runs: this.reports.length,
+      everDirty: this.reports.some((r) => !r.clean),
+      cleanStreak,
+      openFindings: last ? last.findings.length : 0,
+      ...(last ? { lastAuditAt: last.at, lastAttestation: last.attestation } : {}),
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @kyaki/agents — L2 Agent Runtime.
+ *
+ * Two spenders, a watcher, and a steward:
+ *   ProcurerAgent — sources compliant vendors, spends outward, proves savings.
+ *   Treasurer     — manages the balance sheet: obligations, FX sourcing, sweeps.
+ *   AuditorAgent  — spends nothing; proves the fleet stayed inside authority
+ *                   and signs a verifiable audit-of-record.
+ *   Steward       — acts on the PRINCIPAL's key: issues mandates from policy and
+ *                   revokes them when the Auditor proves an agent misbehaved.
+ */
+export type { ApprovalRequest, Market, OutcomeStatus, ProcurementNeed, ProcurementOutcome, SkippedOffer, VendorOffer } from './types.js';
+export { MockMarket } from './market.js';
+export { ApprovalInbox, signApproval, verifyApproval, type SignedApproval } from './approvals.js';
+export { ProcurerAgent, type ProcurerConfig } from './procurer.js';
+export {
+  Treasurer, StaticFX, TreasuryApprovalInbox,
+  type Account, type AccountType, type ActionKind, type ActionStatus,
+  type CashPosition, type FXProvider, type Obligation, type PendingMovement,
+  type MovementStatus, type TreasurerConfig, type TreasuryAction,
+} from './treasury.js';
+export {
+  AuditorAgent, verifyAuditAttestation,
+  type AuditAttestation, type AuditInput, type AuditReport, type AuditorConfig,
+  type CommittedSpend, type Finding, type RevocationRecord, type Severity,
+} from './auditor.js';
+export { ContinuousAuditor, type AuditHealth } from './continuous-auditor.js';
+export {
+  Steward, verifyGovernanceAttestation,
+  type AuthorityAction, type AuthorityActionKind, type GovernanceAttestation, type StewardConfig,
+} from './steward.js';

package/src/market.ts

@@ -0,0 +1,11 @@
+/**
+ * market.ts — Mock RFQ market for demos and tests.
+ */
+import type { Market, VendorOffer } from './types.js';
+
+export class MockMarket implements Market {
+  constructor(private readonly book: Record<string, VendorOffer[]>) {}
+  offersFor(needId: string): VendorOffer[] {
+    return [...(this.book[needId] ?? [])];
+  }
+}

package/src/procurer.ts

@@ -0,0 +1,183 @@
+/**
+ * procurer.ts — The Procurer: first autonomous agent on the Mandate OS.
+ * RFQ across vendors, COMPLIANCE-FILTERED sourcing (a cheaper off-policy
+ * vendor is refused, not bought), tri-state execution through the policy
+ * engine, signed-approval workflow, and a savings report where every claimed
+ * saving resolves to a signed transaction id in the hash-chained audit log.
+ */
+import {
+  createTransactionIntent, type AgentKeys, type AuditLog, type SpendMandate,
+  type TransactionIntent, type VerificationContext,
+} from '@kyaki/core';
+import {
+  evaluateWithPolicy, type AutonomyLadder, type OrgSpendLedger, type SpendPolicy,
+} from '@kyaki/policy';
+import { verifyApproval, type ApprovalInbox, type SignedApproval } from './approvals.js';
+import type { CommittedSpend } from './auditor.js';
+import type { Market, ProcurementNeed, ProcurementOutcome, SkippedOffer, VendorOffer } from './types.js';
+
+export interface ProcurerConfig {
+  agentKeys: AgentKeys;
+  mandate: SpendMandate;
+  approvalAbove?: number;
+  policy: SpendPolicy;
+  ladder?: AutonomyLadder;
+  orgLedger?: OrgSpendLedger;
+  kernelCtx: VerificationContext;
+  market: Market;
+  approvals: ApprovalInbox;
+  audit?: AuditLog;
+}
+
+interface PurchaseLine {
+  needId: string;
+  vendor: string;
+  paid: number;
+  baseline: number;
+  txnId: string;
+}
+
+export class ProcurerAgent {
+  private purchases: PurchaseLine[] = [];
+  private committed: CommittedSpend[] = [];
+
+  constructor(private readonly cfg: ProcurerConfig) {}
+
+  private scope() { return this.cfg.mandate.credentialSubject.scope; }
+
+  private complianceFailure(offer: VendorOffer, need: ProcurementNeed): string | null {
+    const scope = this.scope();
+    if (offer.currency !== scope.currency) return 'CURRENCY_MISMATCH';
+    if (scope.merchantAllowlist && scope.merchantAllowlist.length > 0 && !scope.merchantAllowlist.includes(offer.vendor)) {
+      return 'MERCHANT_NOT_ALLOWED';
+    }
+    if (offer.price > scope.maxPerTransaction) return 'AMOUNT_EXCEEDS_PER_TXN_CAP';
+    if (need.maxBudget !== undefined && offer.price > need.maxBudget) return 'OVER_NEED_BUDGET';
+    return null;
+  }
+
+  private intentFor(offer: VendorOffer, need: ProcurementNeed): TransactionIntent {
+    return createTransactionIntent({
+      agent: this.cfg.agentKeys,
+      mandateId: this.cfg.mandate.id,
+      merchant: offer.vendor,
+      amount: offer.price,
+      currency: offer.currency,
+      ...(need.category ? { category: need.category } : {}),
+      description: need.description,
+      ...(this.cfg.kernelCtx.now ? { now: this.cfg.kernelCtx.now } : {}),
+    });
+  }
+
+  async run(needs: ProcurementNeed[]): Promise<ProcurementOutcome[]> {
+    const outcomes: ProcurementOutcome[] = [];
+    for (const need of needs) outcomes.push(await this.source(need));
+    return outcomes;
+  }
+
+  async source(need: ProcurementNeed): Promise<ProcurementOutcome> {
+    const audit = this.cfg.audit;
+    const offers = [...(await this.cfg.market.offersFor(need.id))].sort((a, b) => a.price - b.price);
+
+    const compliant: VendorOffer[] = [];
+    const skipped: SkippedOffer[] = [];
+    for (const offer of offers) {
+      const failure = this.complianceFailure(offer, need);
+      if (failure === null) compliant.push(offer);
+      else skipped.push({ vendor: offer.vendor, price: offer.price, reason: failure });
+    }
+
+    if (compliant.length === 0) {
+      audit?.append({ type: 'procurement.refused', needId: need.id, description: need.description, skipped });
+      return { need, status: 'no_compliant_vendor', skippedNonCompliant: skipped };
+    }
+
+    const best = compliant[0]!;
+    const baseline = compliant[compliant.length - 1]!.price;
+    const temptations = skipped.filter((s) => s.price < best.price);
+
+    const intent = this.intentFor(best, need);
+    const result = await evaluateWithPolicy({
+      policy: this.cfg.policy, mandate: this.cfg.mandate, intent,
+      ...(this.cfg.approvalAbove !== undefined ? { approvalAbove: this.cfg.approvalAbove } : {}),
+      ...(this.cfg.ladder ? { ladder: this.cfg.ladder } : {}),
+      ...(this.cfg.orgLedger ? { orgLedger: this.cfg.orgLedger } : {}),
+      kernelCtx: this.cfg.kernelCtx,
+    });
+
+    if (result.decision === 'allow') {
+      this.purchases.push({ needId: need.id, vendor: best.vendor, paid: best.price, baseline, txnId: intent.id });
+      this.committed.push({ intent, mandate: this.cfg.mandate });
+      audit?.append({ type: 'procurement.purchased', needId: need.id, vendor: best.vendor, amount: best.price, currency: best.currency, txnId: intent.id });
+      return { need, status: 'purchased', offer: best, txnId: intent.id, ...(temptations.length > 0 ? { skippedNonCompliant: temptations } : {}) };
+    }
+
+    if (result.decision === 'escalate') {
+      const request = this.cfg.approvals.submit({ intent, mandate: this.cfg.mandate, need, offer: best, reason: result.policy.reasons.join(',') });
+      audit?.append({ type: 'procurement.escalated', needId: need.id, vendor: best.vendor, amount: best.price, approvalId: request.id, intentId: intent.id });
+      return { need, status: 'pending_approval', offer: best, approvalId: request.id, ...(temptations.length > 0 ? { skippedNonCompliant: temptations } : {}) };
+    }
+
+    audit?.append({ type: 'procurement.deferred', needId: need.id, vendor: best.vendor, amount: best.price, reasons: [...result.kernel.reasons, ...result.policy.reasons] });
+    return { need, status: 'deferred', offer: best, reasons: [...result.kernel.reasons, ...result.policy.reasons] };
+  }
+
+  async executeApproved(approvalId: string, approval: SignedApproval): Promise<ProcurementOutcome> {
+    const request = this.cfg.approvals.get(approvalId);
+    if (!request) throw new Error(`No approval request ${approvalId}`);
+
+    if (!verifyApproval(approval) || approval.intentId !== request.intent.id) {
+      return { need: request.need, status: 'deferred', reasons: ['APPROVAL_SIGNATURE_INVALID'] };
+    }
+    if (!this.cfg.approvals.markExecuted(approvalId)) {
+      return { need: request.need, status: 'deferred', reasons: ['ALREADY_EXECUTED'] };
+    }
+
+    const result = await evaluateWithPolicy({
+      policy: this.cfg.policy, mandate: this.cfg.mandate, intent: request.intent,
+      ...(this.cfg.approvalAbove !== undefined ? { approvalAbove: this.cfg.approvalAbove } : {}),
+      humanApproval: approval,
+      ...(this.cfg.ladder ? { ladder: this.cfg.ladder } : {}),
+      ...(this.cfg.orgLedger ? { orgLedger: this.cfg.orgLedger } : {}),
+      kernelCtx: this.cfg.kernelCtx,
+    });
+
+    if (result.decision !== 'allow') {
+      this.cfg.audit?.append({ type: 'approval.execution_denied', approvalId, intentId: request.intent.id, reasons: [...result.kernel.reasons, ...result.policy.reasons] });
+      return { need: request.need, status: 'deferred', offer: request.offer, reasons: [...result.kernel.reasons, ...result.policy.reasons] };
+    }
+
+    const offers = [...(await this.cfg.market.offersFor(request.need.id))]
+      .filter((o) => this.complianceFailure(o, request.need) === null)
+      .sort((a, b) => a.price - b.price);
+    const baseline = offers.length > 0 ? offers[offers.length - 1]!.price : request.offer.price;
+
+    this.purchases.push({ needId: request.need.id, vendor: request.offer.vendor, paid: request.offer.price, baseline, txnId: request.intent.id });
+    this.committed.push({ intent: request.intent, mandate: this.cfg.mandate });
+    this.cfg.audit?.append({ type: 'approval.executed', approvalId, intentId: request.intent.id, approvedBy: approval.approvedBy, approvalSignature: approval.signature, amount: request.offer.price, vendor: request.offer.vendor });
+    return { need: request.need, status: 'purchased', offer: request.offer, txnId: request.intent.id };
+  }
+
+  /** The signed {intent, mandate} pairs this agent actually committed — the
+   *  Auditor's input. Surfacing them lets L3 oversight reconcile real output. */
+  committedSpends(): CommittedSpend[] {
+    return [...this.committed];
+  }
+
+  savingsReport(): { lines: PurchaseLine[]; totalSaved: number; totalPaid: number; chainValid: boolean } {
+    const audit = this.cfg.audit;
+    const chainValid = audit ? audit.verifyChain() : false;
+    const provenTxnIds = new Set(
+      (audit?.entries() ?? [])
+        .filter((e) => e.event.type === 'procurement.purchased' || e.event.type === 'approval.executed')
+        .map((e) => (e.event as { txnId?: string; intentId?: string }).txnId ?? (e.event as { intentId?: string }).intentId)
+    );
+    const lines = this.purchases.filter((p) => chainValid && provenTxnIds.has(p.txnId));
+    return {
+      lines,
+      totalSaved: lines.reduce((s, l) => s + (l.baseline - l.paid), 0),
+      totalPaid: lines.reduce((s, l) => s + l.paid, 0),
+      chainValid,
+    };
+  }
+}