@kyaki/agents 0.1.0

package/src/steward.ts

@@ -0,0 +1,168 @@
+/**
+ * steward.ts — The Steward: KYA's fourth agent, and the only one that acts on
+ * the PRINCIPAL's key.
+ *
+ * Where the Procurer pushes money outward and the Treasurer moves the balance
+ * sheet (both under DELEGATED authority), and the Auditor merely observes, the
+ * Steward GRANTS and REVOKES authority itself. It operationalizes KYA's third
+ * pillar — "authorization, *revocation*, and audit" — the one with no agent
+ * until now. It spends nothing.
+ *
+ * Two motions:
+ *   - issueFor(target) — compile a scoped mandate from org policy (L1
+ *     `compileScope`) and sign it with the principal's key (L0 `issueMandate`),
+ *     so delegations are born from policy-as-code, not by hand.
+ *   - govern(report)   — read the Auditor's verdict (`report.demoted`, the
+ *     provably-misbehaving agents) and REVOKE their mandates in the kernel's
+ *     live revocation registry. The next spend on a revoked mandate is denied
+ *     by the kernel (`MANDATE_REVOKED`). The Auditor adjusts the autonomy TIER;
+ *     the Steward terminates the AUTHORITY. Detect → respond, closed.
+ *
+ * Every issuance and revocation appends to the Steward's own hash-chained
+ * governance log, and `attest()` signs its head — so authority changes are
+ * themselves tamper-evident, exactly like a mandate, an intent, or an audit.
+ */
+import {
+  canonicalBytes, fromBase58, issueMandate, publicKeyFromDid, sign, toBase58, verifySignature,
+  type AuditLog, type Identity, type RevocationStore, type SpendMandate,
+} from '@kyaki/core';
+import { compileScope, type SpendPolicy } from '@kyaki/policy';
+import type { AuditReport } from './auditor.js';
+
+const GENESIS = '0'.repeat(64);
+
+export type AuthorityActionKind = 'issued' | 'revoked' | 'noop';
+
+export interface AuthorityAction {
+  kind: AuthorityActionKind;
+  agentDid: string;
+  mandateId?: string;
+  reasons: string[];
+  /** Present on `issued` — the freshly signed delegation. */
+  mandate?: SpendMandate;
+}
+
+export interface GovernanceAttestation {
+  type: 'KyaGovernanceAttestation';
+  steward: string;
+  chainHead: string;
+  at: string;
+  signature: string;
+}
+
+/** Re-check a governance attestation offline — tampering with the chain head or
+ *  the timestamp invalidates it, exactly like a mandate or an audit. */
+export function verifyGovernanceAttestation(att: GovernanceAttestation): boolean {
+  try {
+    const { signature, ...doc } = att;
+    return verifySignature(fromBase58(signature), canonicalBytes(doc), publicKeyFromDid(att.steward));
+  } catch {
+    return false;
+  }
+}
+
+export interface StewardConfig {
+  /** The principal's key — issues and revokes delegated authority. */
+  principal: Identity;
+  /** The Steward's own key — signs governance attestations. */
+  stewardKeys: Identity;
+  policy: SpendPolicy;
+  /** The kernel's LIVE revocation registry — must be the same instance the
+   *  agents' VerificationContext consults, or revocation won't bite. */
+  revocations: RevocationStore;
+  /** The Steward's own lifecycle chain; every issue/revoke is anchored here. */
+  governance?: AuditLog;
+  now?: Date;
+}
+
+export class Steward {
+  private readonly byAgent = new Map<string, Set<string>>();   // agentDid -> mandateIds
+  private readonly owner = new Map<string, string>();          // mandateId -> agentDid
+
+  constructor(private readonly cfg: StewardConfig) {}
+
+  private now(): Date { return this.cfg.now ?? new Date(); }
+
+  /** Issue a policy-derived, principal-signed mandate for an agent/role. */
+  issueFor(target: { agentDid: string; role?: string }, opts: { validForSeconds?: number } = {}): AuthorityAction {
+    const compiled = compileScope(this.cfg.policy, {
+      agentDid: target.agentDid, ...(target.role ? { role: target.role } : {}),
+    });
+    const validForSeconds = opts.validForSeconds ?? compiled.validForSeconds;
+    const mandate = issueMandate({
+      principal: this.cfg.principal, agentDid: target.agentDid, scope: compiled.scope,
+      ...(this.cfg.now ? { validFrom: this.cfg.now } : {}),
+      ...(validForSeconds !== undefined ? { validForSeconds } : {}),
+    });
+    this.track(mandate);
+    this.cfg.governance?.append(
+      { type: 'authority.issued', mandateId: mandate.id, agentDid: target.agentDid, ruleId: compiled.ruleId },
+      this.now(),
+    );
+    return { kind: 'issued', agentDid: target.agentDid, mandateId: mandate.id, reasons: [compiled.ruleId], mandate };
+  }
+
+  /** Register an externally-issued mandate so the Steward can later revoke it. */
+  track(mandate: SpendMandate): void {
+    const agentDid = mandate.credentialSubject.id;
+    this.owner.set(mandate.id, agentDid);
+    const set = this.byAgent.get(agentDid) ?? new Set<string>();
+    set.add(mandate.id);
+    this.byAgent.set(agentDid, set);
+  }
+
+  mandatesOf(agentDid: string): string[] {
+    return [...(this.byAgent.get(agentDid) ?? [])];
+  }
+
+  isRevoked(mandateId: string): Promise<boolean> {
+    return this.cfg.revocations.isRevoked(mandateId);
+  }
+
+  /** Revoke a single mandate in the kernel's live registry, audited. */
+  async revoke(mandateId: string, reasons: string[]): Promise<AuthorityAction> {
+    const agentDid = this.owner.get(mandateId) ?? '—';
+    await this.cfg.revocations.revoke(mandateId);
+    this.cfg.governance?.append({ type: 'authority.revoked', mandateId, agentDid, reasons }, this.now());
+    return { kind: 'revoked', agentDid, mandateId, reasons };
+  }
+
+  /**
+   * Respond to an audit: revoke the mandates of every agent the Auditor
+   * provably caught (`report.demoted`). The Steward enacts the consequence the
+   * Auditor's demotion only signals. Idempotent — an already-revoked mandate is
+   * a noop, so re-running the same report never double-revokes.
+   */
+  async govern(report: Pick<AuditReport, 'demoted' | 'findings'>): Promise<AuthorityAction[]> {
+    const actions: AuthorityAction[] = [];
+    for (const agentDid of report.demoted) {
+      const reasons = report.findings.filter((f) => f.agentDid === agentDid).map((f) => f.code);
+      const mandateIds = this.mandatesOf(agentDid);
+      if (mandateIds.length === 0) {
+        actions.push({ kind: 'noop', agentDid, reasons: ['NO_TRACKED_MANDATE'] });
+        continue;
+      }
+      for (const mandateId of mandateIds) {
+        if (await this.cfg.revocations.isRevoked(mandateId)) {
+          actions.push({ kind: 'noop', agentDid, mandateId, reasons: ['ALREADY_REVOKED'] });
+          continue;
+        }
+        actions.push(await this.revoke(mandateId, reasons.length > 0 ? reasons : ['AGENT_DEMOTED']));
+      }
+    }
+    return actions;
+  }
+
+  /** Sign the governance chain head — the authority-change history, verifiable. */
+  attest(): GovernanceAttestation {
+    const entries = this.cfg.governance?.entries() ?? [];
+    const chainHead = entries.length > 0 ? entries[entries.length - 1]!.hash : GENESIS;
+    const doc = {
+      type: 'KyaGovernanceAttestation' as const,
+      steward: this.cfg.stewardKeys.did,
+      chainHead,
+      at: this.now().toISOString(),
+    };
+    return { ...doc, signature: toBase58(sign(canonicalBytes(doc), this.cfg.stewardKeys.privateKey)) };
+  }
+}

package/src/treasury.ts

@@ -0,0 +1,458 @@
+/**
+ * treasury.ts — The Treasurer, KYA's second autonomous agent.
+ *
+ * Where the Procurer spends OUTWARD, the Treasurer manages the BALANCE SHEET
+ * and proves, movement by movement, that it stayed inside its mandate. A full
+ * cycle (runCycle) pays due obligations FIRST (due-date order), then sweeps
+ * idle cash above a configured buffer into reserve/yield.
+ *
+ * Reconstructed from the canonical Notion source and rebased onto the on-disk
+ * hardened seam: every movement runs through evaluateWithPolicy(), which
+ * atomically does kernel-verify -> escalation gate -> org-exposure check ->
+ * kernel COMMIT. Account balances mutate ONLY after a committed allow, so a
+ * denied or escalated movement can never leave a negative balance or a phantom
+ * debit.
+ *
+ *  - Escalated movements park in a TreasuryApprovalInbox that uses the same
+ *    crash-safe two-phase exactly-once protocol as the Procurer:
+ *    approved -> claimExecution() -> 'executing' -> confirm / revert / fail.
+ *    A signed CFO Approval is required to finalize; the agent cannot approve
+ *    its own movement.
+ *  - The FX-funding leg is denominated in a currency the org actually HOLDS,
+ *    so L0/L1 always evaluate a real in-mandate-currency amount rather than
+ *    tripping a single-currency mandate.
+ */
+import { randomUUID } from 'node:crypto';
+import {
+  createTransactionIntent,
+  type AgentKeys,
+  type AuditLog,
+  type Identity,
+  type SpendMandate,
+  type TransactionIntent,
+  type VerificationContext,
+} from '@kyaki/core';
+import {
+  evaluateWithPolicy,
+  isSecurityAnomaly,
+  type AutonomyLadder,
+  type OrgSpendLedger,
+  type SpendPolicy,
+} from '@kyaki/policy';
+import { signApproval, verifyApproval, type SignedApproval } from './approvals.js';
+
+// ── Domain model ──────────────────────────────────────────────────────────
+
+export type AccountType = 'operating' | 'reserve' | 'yield';
+
+export interface Account {
+  id: string;
+  currency: string;
+  balance: number;
+  type: AccountType;
+  /** Operating accounts keep at least this much; the excess is sweepable. */
+  minBuffer?: number;
+}
+
+export interface Obligation {
+  id: string;
+  payee: string;
+  category: string;
+  amount: number;
+  currency: string;
+  /** Epoch ms. Funded only once `dueAt <= now`. */
+  dueAt: number;
+}
+
+export interface FXProvider {
+  /** Units of `to` per one unit of `from`. */
+  rate(from: string, to: string): number;
+}
+
+/** A deterministic FX desk for demos and tests. */
+export class StaticFX implements FXProvider {
+  constructor(private readonly table: Record<string, number>) {}
+  rate(from: string, to: string): number {
+    if (from === to) return 1;
+    const direct = this.table[`${from}/${to}`];
+    if (direct !== undefined) return direct;
+    const inverse = this.table[`${to}/${from}`];
+    if (inverse !== undefined && inverse !== 0) return 1 / inverse;
+    throw new Error(`NO_FX_RATE: ${from}->${to}`);
+  }
+}
+
+/**
+ * Amounts are integer minor units; FX products carry IEEE-754 noise
+ * (100000 * 1.1 === 110000.00000000001). Snap to whole minor units before
+ * rounding so the kernel always evaluates a clean integer.
+ */
+function roundMinorUnits(x: number): number {
+  return Math.round(x);
+}
+function ceilMinorUnits(x: number): number {
+  // Strip float noise to 6 decimals, then round up to the next whole unit.
+  return Math.ceil(Math.round(x * 1e6) / 1e6);
+}
+
+export type ActionKind = 'obligation_payment' | 'fx_conversion' | 'liquidity_sweep';
+export type ActionStatus = 'committed' | 'pending_approval' | 'denied' | 'skipped';
+
+export interface TreasuryAction {
+  kind: ActionKind;
+  status: ActionStatus;
+  accountId: string;
+  payee: string;
+  category: string;
+  /** Amount actually moved, in the SOURCE account's (held) currency. */
+  amount: number;
+  currency: string;
+  obligationId?: string;
+  intentId?: string;
+  approvalId?: string;
+  reasons?: string[];
+}
+
+export interface CashPosition {
+  baseCurrency: string;
+  byCurrency: Record<string, number>;
+  totalInBase: number;
+  nearTermObligationsInBase: number;
+  netLiquidityInBase: number;
+}
+
+// ── Two-phase escalation inbox (mirrors the Procurer's exactly-once protocol) ─
+
+export type MovementStatus =
+  | 'pending' | 'approved' | 'executing' | 'executed' | 'rejected' | 'failed';
+
+export interface PendingMovement {
+  id: string;
+  intent: TransactionIntent;
+  mandate: SpendMandate;
+  kind: ActionKind;
+  accountId: string;
+  payee: string;
+  category: string;
+  amount: number;
+  currency: string;
+  obligationId?: string;
+  reason: string;
+  submittedAt: string;
+  status: MovementStatus;
+  decidedBy?: string;
+  decidedAt?: string;
+  failureReasons?: string[];
+}
+
+export class TreasuryApprovalInbox {
+  private movements = new Map<string, PendingMovement>();
+
+  submit(input: Omit<PendingMovement, 'id' | 'submittedAt' | 'status'>): PendingMovement {
+    const movement: PendingMovement = {
+      ...input,
+      id: `mov_${randomUUID().slice(0, 8)}`,
+      submittedAt: new Date().toISOString(),
+      status: 'pending',
+    };
+    this.movements.set(movement.id, movement);
+    return movement;
+  }
+
+  get(id: string): PendingMovement | undefined { return this.movements.get(id); }
+  pending(): PendingMovement[] { return [...this.movements.values()].filter((m) => m.status === 'pending'); }
+  all(): PendingMovement[] { return [...this.movements.values()]; }
+
+  /** The CFO countersigns a parked movement with their own key. */
+  approve(id: string, approver: Identity): SignedApproval {
+    const m = this.movements.get(id);
+    if (!m) throw new Error(`No movement ${id}`);
+    if (m.status !== 'pending') throw new Error(`Movement ${id} is ${m.status}, not pending`);
+    const approval = signApproval(m.intent.id, approver);
+    m.status = 'approved';
+    m.decidedBy = approval.approvedBy;
+    m.decidedAt = approval.at;
+    return approval;
+  }
+
+  reject(id: string, approver: Identity): PendingMovement {
+    const m = this.movements.get(id);
+    if (!m) throw new Error(`No movement ${id}`);
+    if (m.status !== 'pending') throw new Error(`Movement ${id} is ${m.status}, not pending`);
+    m.status = 'rejected';
+    m.decidedBy = approver.did;
+    m.decidedAt = new Date().toISOString();
+    return m;
+  }
+
+  /** Atomic exactly-once gate: 'approved' -> 'executing'. True iff WE won. */
+  claimExecution(id: string): boolean {
+    const m = this.movements.get(id);
+    if (!m || m.status !== 'approved') return false;
+    m.status = 'executing';
+    return true;
+  }
+  confirmExecuted(id: string): void {
+    const m = this.movements.get(id);
+    if (m && m.status === 'executing') m.status = 'executed';
+  }
+  /** Transient deny: stays retryable. */
+  revertToApproved(id: string, reasons: string[]): void {
+    const m = this.movements.get(id);
+    if (m && m.status === 'executing') { m.status = 'approved'; m.failureReasons = reasons; }
+  }
+  /** Security failure: terminal AND visible. */
+  markFailed(id: string, reasons: string[]): void {
+    const m = this.movements.get(id);
+    if (m && m.status === 'executing') { m.status = 'failed'; m.failureReasons = reasons; }
+  }
+}
+
+// ── The Treasurer ───────────────────────────────────────────────────────────
+
+export interface TreasurerConfig {
+  agentKeys: AgentKeys;
+  mandate: SpendMandate;
+  policy: SpendPolicy;
+  accounts: Account[];
+  fx: FXProvider;
+  baseCurrency: string;
+  approvalAbove?: number;
+  ladder?: AutonomyLadder;
+  orgLedger?: OrgSpendLedger;
+  kernelCtx: VerificationContext;
+  approvals: TreasuryApprovalInbox;
+  audit?: AuditLog;
+}
+
+export class Treasurer {
+  private readonly accounts: Map<string, Account>;
+
+  constructor(private readonly cfg: TreasurerConfig) {
+    this.accounts = new Map(cfg.accounts.map((a) => [a.id, { ...a }]));
+  }
+
+  account(id: string): Account | undefined {
+    const a = this.accounts.get(id);
+    return a ? { ...a } : undefined;
+  }
+
+  /** The signed {intent, mandate} pairs this agent committed — Auditor input. */
+  committedSpends(): { intent: TransactionIntent; mandate: SpendMandate }[] {
+    return [...this.committed];
+  }
+  private committed: { intent: TransactionIntent; mandate: SpendMandate }[] = [];
+
+  private operatingFor(currency: string): Account | undefined {
+    return [...this.accounts.values()].find((a) => a.type === 'operating' && a.currency === currency);
+  }
+
+  private intentFor(source: Account, payee: string, category: string, amount: number, currency: string, now?: Date): TransactionIntent {
+    return createTransactionIntent({
+      agent: this.cfg.agentKeys,
+      mandateId: this.cfg.mandate.id,
+      merchant: payee,
+      amount,
+      currency,
+      category,
+      description: `treasury:${source.id}`,
+      ...(now ? { now } : {}),
+    });
+  }
+
+  /**
+   * The shared movement pipeline. Balance is debited ONLY on a committed
+   * allow. On escalate the movement parks (nothing debited); on deny it
+   * aborts (nothing debited). evaluateWithPolicy handles the org-exposure
+   * reserve/release and the atomic kernel commit internally.
+   */
+  private async execute(
+    kind: ActionKind, source: Account, payee: string, category: string,
+    amount: number, currency: string, obligationId: string | undefined, now: Date | undefined,
+  ): Promise<TreasuryAction> {
+    const live = this.accounts.get(source.id)!;
+    // Balance check up front: never sign a movement we cannot fund.
+    if (live.balance < amount) {
+      return {
+        kind, status: 'skipped', accountId: source.id, payee, category, amount, currency,
+        ...(obligationId ? { obligationId } : {}), reasons: ['INSUFFICIENT_FUNDS'],
+      };
+    }
+
+    const intent = this.intentFor(live, payee, category, amount, currency, now);
+    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') {
+      live.balance -= amount;
+      this.committed.push({ intent, mandate: this.cfg.mandate });
+      this.cfg.audit?.append({
+        type: 'treasury.committed', kind, accountId: source.id, payee, category,
+        amount, currency, intentId: intent.id, ...(obligationId ? { obligationId } : {}),
+      });
+      return {
+        kind, status: 'committed', accountId: source.id, payee, category, amount, currency,
+        intentId: intent.id, ...(obligationId ? { obligationId } : {}),
+      };
+    }
+
+    if (result.decision === 'escalate') {
+      const movement = this.cfg.approvals.submit({
+        intent, mandate: this.cfg.mandate, kind, accountId: source.id, payee, category,
+        amount, currency, ...(obligationId ? { obligationId } : {}), reason: result.policy.reasons.join(','),
+      });
+      this.cfg.audit?.append({
+        type: 'treasury.escalated', kind, accountId: source.id, payee, category,
+        amount, currency, approvalId: movement.id, intentId: intent.id, ...(obligationId ? { obligationId } : {}),
+      });
+      return {
+        kind, status: 'pending_approval', accountId: source.id, payee, category, amount,
+        currency, approvalId: movement.id, intentId: intent.id, ...(obligationId ? { obligationId } : {}),
+      };
+    }
+
+    const reasons = [...result.kernel.reasons, ...result.policy.reasons];
+    this.cfg.audit?.append({
+      type: 'treasury.denied', kind, accountId: source.id, payee, category,
+      amount, currency, reasons, ...(obligationId ? { obligationId } : {}),
+    });
+    return {
+      kind, status: 'denied', accountId: source.id, payee, category, amount, currency,
+      reasons, ...(obligationId ? { obligationId } : {}),
+    };
+  }
+
+  /** Fund a single obligation, routing through FX if we don't hold its currency. */
+  private async fundObligation(ob: Obligation, now?: Date): Promise<TreasuryAction> {
+    // 1) We hold the obligation's currency directly. Pay if it can cover it;
+    //    if underfunded, SKIP — converting into a currency we already hold is
+    //    nonsense, so this is a genuine funding gap.
+    const native = this.operatingFor(ob.currency);
+    if (native) {
+      if (native.balance >= ob.amount) {
+        return this.execute('obligation_payment', native, ob.payee, ob.category, ob.amount, ob.currency, ob.id, now);
+      }
+      return {
+        kind: 'obligation_payment', status: 'skipped', accountId: native.id, payee: ob.payee,
+        category: ob.category, amount: ob.amount, currency: ob.currency, obligationId: ob.id,
+        reasons: ['INSUFFICIENT_FUNDS'],
+      };
+    }
+
+    // 2) We do NOT hold the obligation's currency: route ONE mandate-governed
+    //    movement in a currency we hold (prefer base), FX desk settles abroad.
+    const candidates = [...this.accounts.values()].filter((a) => a.type === 'operating' && a.currency !== ob.currency);
+    const source = candidates.find((a) => a.currency === this.cfg.baseCurrency) ?? candidates[0];
+    if (!source) {
+      return {
+        kind: 'obligation_payment', status: 'skipped', accountId: '—', payee: ob.payee,
+        category: ob.category, amount: ob.amount, currency: ob.currency, obligationId: ob.id,
+        reasons: ['NO_FUNDING_ACCOUNT'],
+      };
+    }
+    const sourceAmount = ceilMinorUnits(ob.amount * this.cfg.fx.rate(ob.currency, source.currency));
+    return this.execute('fx_conversion', source, ob.payee, ob.category, sourceAmount, source.currency, ob.id, now);
+  }
+
+  /** A full treasury cycle: pay due obligations FIRST, then sweep idle cash. */
+  async runCycle(obligations: Obligation[], now?: Date): Promise<TreasuryAction[]> {
+    const at = (now ?? new Date()).getTime();
+    const actions: TreasuryAction[] = [];
+
+    const due = obligations.filter((o) => o.dueAt <= at).sort((a, b) => a.dueAt - b.dueAt);
+    for (const ob of due) actions.push(await this.fundObligation(ob, now));
+
+    // Liquidity sweep AFTER obligations, so we never sweep money we owe.
+    for (const acct of this.accounts.values()) {
+      if (acct.type !== 'operating' || acct.minBuffer === undefined) continue;
+      const excess = acct.balance - acct.minBuffer;
+      if (excess <= 0) continue;
+      const reserve = [...this.accounts.values()].find((a) => (a.type === 'reserve' || a.type === 'yield') && a.currency === acct.currency);
+      if (!reserve) continue;
+      const action = await this.execute('liquidity_sweep', acct, reserve.id, 'treasury_sweep', excess, acct.currency, undefined, now);
+      if (action.status === 'committed') this.accounts.get(reserve.id)!.balance += excess;
+      actions.push(action);
+    }
+    return actions;
+  }
+
+  /** Finalize an escalated movement with a signed CFO approval (two-phase). */
+  async applyApproval(approvalId: string, approval: SignedApproval): Promise<TreasuryAction> {
+    const movement = this.cfg.approvals.get(approvalId);
+    if (!movement) throw new Error(`No movement ${approvalId}`);
+
+    const base = {
+      kind: movement.kind, accountId: movement.accountId, payee: movement.payee,
+      category: movement.category, amount: movement.amount, currency: movement.currency,
+      ...(movement.obligationId ? { obligationId: movement.obligationId } : {}),
+    };
+
+    if (!verifyApproval(approval) || approval.intentId !== movement.intent.id) {
+      return { ...base, status: 'denied', reasons: ['APPROVAL_SIGNATURE_INVALID'] };
+    }
+    // Separation of duties: the agent that initiated the movement can never be
+    // the human that countersigns it. Approval is authority from ANOTHER key.
+    if (approval.approvedBy === this.cfg.agentKeys.did) {
+      return { ...base, status: 'denied', reasons: ['SELF_APPROVAL_FORBIDDEN'] };
+    }
+    // Exactly-once gate: a double-submit dies here, never reaching the kernel.
+    if (!this.cfg.approvals.claimExecution(approvalId)) {
+      return { ...base, status: 'denied', reasons: ['ALREADY_EXECUTED'] };
+    }
+
+    const result = await evaluateWithPolicy({
+      policy: this.cfg.policy, mandate: this.cfg.mandate, intent: movement.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') {
+      const reasons = [...result.kernel.reasons, ...result.policy.reasons];
+      if (isSecurityAnomaly(reasons)) this.cfg.approvals.markFailed(approvalId, reasons);
+      else this.cfg.approvals.revertToApproved(approvalId, reasons);
+      this.cfg.audit?.append({ type: 'treasury.approval_denied', approvalId, intentId: movement.intent.id, reasons });
+      return { ...base, status: 'denied', reasons };
+    }
+
+    this.cfg.approvals.confirmExecuted(approvalId);
+    const src = this.accounts.get(movement.accountId);
+    if (src) src.balance -= movement.amount;
+    if (movement.kind === 'liquidity_sweep') {
+      const reserve = [...this.accounts.values()].find((a) => (a.type === 'reserve' || a.type === 'yield') && a.currency === movement.currency);
+      if (reserve) reserve.balance += movement.amount;
+    }
+    this.committed.push({ intent: movement.intent, mandate: movement.mandate });
+    this.cfg.audit?.append({
+      type: 'treasury.approval_executed', approvalId, intentId: movement.intent.id,
+      approvedBy: approval.approvedBy, approvalSignature: approval.signature,
+      amount: movement.amount, currency: movement.currency, payee: movement.payee,
+    });
+    return { ...base, status: 'committed', intentId: movement.intent.id, approvalId };
+  }
+
+  /** Multi-currency cash position, converted to base, net of near-term obligations. */
+  cashPosition(obligations: Obligation[], horizonMs = 30 * 24 * 3600 * 1000, now?: Date): CashPosition {
+    const at = (now ?? new Date()).getTime();
+    const byCurrency: Record<string, number> = {};
+    let totalInBase = 0;
+    for (const a of this.accounts.values()) {
+      byCurrency[a.currency] = (byCurrency[a.currency] ?? 0) + a.balance;
+      totalInBase += roundMinorUnits(a.balance * this.cfg.fx.rate(a.currency, this.cfg.baseCurrency));
+    }
+    const nearTermObligationsInBase = obligations
+      .filter((o) => o.dueAt <= at + horizonMs)
+      .reduce((s, o) => s + roundMinorUnits(o.amount * this.cfg.fx.rate(o.currency, this.cfg.baseCurrency)), 0);
+    return {
+      baseCurrency: this.cfg.baseCurrency, byCurrency, totalInBase,
+      nearTermObligationsInBase, netLiquidityInBase: totalInBase - nearTermObligationsInBase,
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+/**
+ * types.ts — L2 agent runtime data model (procurement domain).
+ */
+import type { SpendMandate, TransactionIntent } from '@kyaki/core';
+
+export interface ProcurementNeed {
+  id: string;
+  description: string;
+  category?: string;
+  maxBudget?: number;
+}
+
+export interface VendorOffer {
+  needId: string;
+  vendor: string;
+  price: number;
+  currency: string;
+}
+
+export interface Market {
+  offersFor(needId: string): Promise<VendorOffer[]> | VendorOffer[];
+}
+
+export type OutcomeStatus =
+  | 'purchased'
+  | 'pending_approval'
+  | 'no_compliant_vendor'
+  | 'deferred';
+
+export interface SkippedOffer {
+  vendor: string;
+  price: number;
+  reason: string;
+}
+
+export interface ProcurementOutcome {
+  need: ProcurementNeed;
+  status: OutcomeStatus;
+  offer?: VendorOffer;
+  txnId?: string;
+  approvalId?: string;
+  skippedNonCompliant?: SkippedOffer[];
+  reasons?: string[];
+}
+
+export interface ApprovalRequest {
+  id: string;
+  intent: TransactionIntent;
+  mandate: SpendMandate;
+  need: ProcurementNeed;
+  offer: VendorOffer;
+  reason: string;
+  submittedAt: string;
+  status: 'pending' | 'approved' | 'rejected' | 'executed';
+  decidedBy?: string;
+  decidedAt?: string;
+}