@decentrys/agent 0.1.0

package/src/policy.test.ts

@@ -0,0 +1,762 @@
+import { describe, expect, it } from 'vitest';
+import { classify, type Assessment, type Evidence, type ThreatSignal } from '@decentrys/protect';
+
+import { DEFAULT_AGENT_RISK_POLICY, evaluatePolicy, narrowPolicy, sealPolicy } from './policy';
+import { SpendLedger } from './ledger';
+import type { AgentAction } from './model';
+
+/**
+ * What AgentGuard is for.
+ *
+ * Protect informs a person who then decides; these tests exist because there
+ * is no person here. Every case below is a way an autonomous actor gets a
+ * treasury emptied — talking its limits upward, looping faster than a cap can
+ * notice, signing to a known drainer because the amount looked small, or
+ * proceeding through an outage because nothing said stop. None of them are
+ * hypothetical failure modes for a human; all of them are routine for a
+ * process in a `while` loop.
+ */
+
+const NOW = new Date('2026-09-06T12:00:00Z');
+const AGENT = 'agent-treasury-1';
+
+function action(overrides: Partial<AgentAction> = {}): AgentAction {
+  return {
+    agentId: AGENT,
+    chain: 'ethereum',
+    type: 'transfer',
+    from: '0x1111111111111111111111111111111111111111',
+    to: '0x2222222222222222222222222222222222222222',
+    valueUsd: 100,
+    ...overrides,
+  };
+}
+
+function evidence(overrides: Partial<Evidence> = {}): Evidence {
+  return {
+    id: 'ev_1',
+    type: 'BYTECODE_MATCH',
+    source: 'Decentrys',
+    observedAt: NOW.toISOString(),
+    confidence: 0.99,
+    analystVerified: false,
+    ...overrides,
+  };
+}
+
+function signal(overrides: Partial<ThreatSignal> = {}): ThreatSignal {
+  return {
+    type: 'KNOWN_DRAINER_BYTECODE',
+    severity: 'CRITICAL',
+    confidence: 0.99,
+    explanation: 'Bytecode matches a confirmed drainer family.',
+    hops: 0,
+    evidence: [evidence()],
+    status: 'ACTIVE',
+    createdAt: NOW.toISOString(),
+    lastSeen: NOW.toISOString(),
+    ...overrides,
+  };
+}
+
+/** Classified by Protect's own model, not asserted here. */
+const CLEAN: Assessment = classify({ now: NOW });
+const KNOWN_MALICIOUS: Assessment = classify({
+  now: NOW,
+  threatSignals: [signal({ evidence: [evidence({ analystVerified: true })] })],
+});
+const ELEVATED: Assessment = classify({
+  now: NOW,
+  threatSignals: [signal({
+    type: 'STOLEN_FUNDS_DIRECT', severity: 'HIGH', confidence: 0.9,
+    explanation: 'Received assets directly from a wallet attributed to incident INC-2026-0012.',
+  })],
+});
+
+// ---------------------------------------------------------------------------
+// The operator is not the agent
+// ---------------------------------------------------------------------------
+
+describe('an agent cannot exceed the policy it was given', () => {
+  /**
+   * The central claim of the package. An agent handed a reference to its own
+   * policy — which any in-process tool wrapper effectively is — must not be
+   * able to edit the number that bounds it. If this can be done at all, every
+   * other control in this file is decoration.
+   */
+  it('cannot mutate a sealed policy', () => {
+    const sealed = sealPolicy({ maxValuePerActionUsd: 1_000 });
+
+    expect(() => {
+      (sealed.policy as { maxValuePerActionUsd?: number }).maxValuePerActionUsd = 10_000_000;
+    }).toThrow(TypeError);
+    expect(sealed.policy.maxValuePerActionUsd).toBe(1_000);
+  });
+
+  it('cannot push a counterparty onto a sealed allowlist', () => {
+    const sealed = sealPolicy({ allowedCounterparties: ['0xaaa'] });
+    expect(() => (sealed.policy.allowedCounterparties as string[]).push('0xbbb')).toThrow(TypeError);
+    expect(sealed.policy.allowedCounterparties).toEqual(['0xaaa']);
+  });
+
+  /**
+   * Freezing what we were handed is not enough. An operator — or an agent
+   * that talked one into it — who keeps a reference to the array they passed
+   * could otherwise grow a live allowlist with nothing in the record showing
+   * the policy had changed.
+   */
+  it('takes a copy, so the caller\'s own array is not the live allowlist', () => {
+    const counterparties = ['0xaaa'];
+    const sealed = sealPolicy({ allowedCounterparties: counterparties });
+
+    counterparties.push('0xbbb');
+
+    expect(sealed.policy.allowedCounterparties).toEqual(['0xaaa']);
+    const decision = evaluatePolicy({
+      action: action({ to: '0xbbb' }), policy: sealed, assessment: CLEAN, now: NOW,
+    });
+    expect(decision.verdict).toBe('deny');
+  });
+
+  /** A per-call restriction is the only derivation there is, and it tightens. */
+  it('narrows a value cap and never raises one', () => {
+    const base = sealPolicy({ maxValuePerActionUsd: 1_000 });
+
+    expect(narrowPolicy(base, { maxValuePerActionUsd: 10_000 }).policy.maxValuePerActionUsd).toBe(1_000);
+    expect(narrowPolicy(base, { maxValuePerActionUsd: 100 }).policy.maxValuePerActionUsd).toBe(100);
+  });
+
+  it('intersects allowlists and unions blocklists', () => {
+    const base = sealPolicy({
+      allowedCounterparties: ['0xaaa', '0xbbb'],
+      blockedCounterparties: ['0xdead'],
+    });
+    const narrowed = narrowPolicy(base, {
+      allowedCounterparties: ['0xbbb', '0xccc'],
+      blockedCounterparties: ['0xbeef'],
+    });
+
+    // '0xccc' was not on the operator's list, so adding it to a restriction
+    // does not put it on the agent's.
+    expect(narrowed.policy.allowedCounterparties).toEqual(['0xbbb']);
+    expect(narrowed.policy.blockedCounterparties).toEqual(['0xdead', '0xbeef']);
+  });
+
+  /**
+   * Two allowlists with nothing in common intersect to the empty list, and an
+   * empty allowlist must mean "nothing is permitted". Reading it as "no
+   * allowlist configured" would turn the strictest possible narrowing into a
+   * complete removal of the control.
+   */
+  it('treats an allowlist narrowed to nothing as permitting nothing', () => {
+    const base = sealPolicy({ allowedCounterparties: ['0xaaa'] });
+    const narrowed = narrowPolicy(base, { allowedCounterparties: ['0xbbb'] });
+
+    expect(narrowed.policy.allowedCounterparties).toEqual([]);
+    expect(evaluatePolicy({
+      action: action({ to: '0xaaa' }), policy: narrowed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('deny');
+  });
+
+  it('cannot loosen an unlimited-approval refusal', () => {
+    const base = sealPolicy({ allowUnlimitedApprovals: false });
+    expect(narrowPolicy(base, { allowUnlimitedApprovals: true }).policy.allowUnlimitedApprovals).toBe(false);
+  });
+
+  it('cannot loosen failMode or a risk ceiling', () => {
+    const base = sealPolicy({ failMode: 'closed', maxRiskLevel: 'CAUTION' });
+    const narrowed = narrowPolicy(base, { failMode: 'open', maxRiskLevel: 'HIGH_RISK' });
+
+    expect(narrowed.policy.failMode).toBe('closed');
+    expect(narrowed.policy.maxRiskLevel).toBe('CAUTION');
+  });
+
+  it('takes the stricter action at each risk level', () => {
+    const base = sealPolicy({ risk: { ELEVATED_RISK: 'block' } });
+    expect(narrowPolicy(base, { risk: { ELEVATED_RISK: 'allow' } }).policy.risk?.ELEVATED_RISK).toBe('block');
+  });
+
+  /**
+   * A policy bound to one agent cannot be re-pointed at another. Silently
+   * resolving the contradiction either way would hide whose limits are in
+   * force, which is the one thing an incident review needs to establish.
+   */
+  it('refuses to re-bind a policy to a different agent', () => {
+    const base = sealPolicy({ agentId: AGENT });
+    expect(() => narrowPolicy(base, { agentId: 'agent-other' })).toThrow(/different agent|cannot narrow/i);
+  });
+
+  it('denies an action proposed by an agent this policy is not bound to', () => {
+    const sealed = sealPolicy({ agentId: AGENT });
+    const decision = evaluatePolicy({
+      action: action({ agentId: 'agent-impostor' }), policy: sealed, assessment: CLEAN, now: NOW,
+    });
+
+    expect(decision.verdict).toBe('deny');
+    expect(decision.evaluations.find((e) => e.rule === 'AGENT_BINDING')?.outcome).toBe('fail');
+  });
+
+  /**
+   * A decision has to name the rules it ran under. Two decisions with the same
+   * fingerprint were made under the same policy; two with different ones were
+   * not, whatever anyone remembers afterwards.
+   */
+  it('fingerprints the policy, and the fingerprint changes when the policy does', () => {
+    const a = sealPolicy({ maxValuePerActionUsd: 1_000 });
+    const b = sealPolicy({ maxValuePerActionUsd: 1_001 });
+    const same = sealPolicy({ maxValuePerActionUsd: 1_000 });
+
+    expect(a.fingerprint).toBe(same.fingerprint);
+    expect(a.fingerprint).not.toBe(b.fingerprint);
+    expect(evaluatePolicy({ action: action(), policy: a, assessment: CLEAN, now: NOW }).policyFingerprint)
+      .toBe(a.fingerprint);
+  });
+
+  /**
+   * `warn` is Protect's most useful action and is meaningless here. Silently
+   * upgrading it to an escalation would change the operator's meaning without
+   * telling them; silently treating it as an allow would ship a control that
+   * does nothing.
+   */
+  it('refuses a warn action in an agent risk policy rather than reinterpreting it', () => {
+    expect(() => sealPolicy({ risk: { CAUTION: 'warn' } })).toThrow(/nobody to warn/i);
+  });
+
+  it('says so when a policy permits confirmed-malicious counterparties', () => {
+    const permissive = sealPolicy({ risk: { KNOWN_MALICIOUS: 'allow' } });
+    expect(permissive.warnings.join(' ')).toMatch(/KNOWN_MALICIOUS/);
+    expect(sealPolicy({ maxValuePerActionUsd: 10 }).warnings.join(' ')).not.toMatch(/KNOWN_MALICIOUS/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Value
+// ---------------------------------------------------------------------------
+
+describe('per-action value cap', () => {
+  it('denies an action above the cap and permits one at it', () => {
+    const sealed = sealPolicy({ maxValuePerActionUsd: 1_000 });
+
+    expect(evaluatePolicy({
+      action: action({ valueUsd: 1_000.01 }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('deny');
+    expect(evaluatePolicy({
+      action: action({ valueUsd: 1_000 }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('allow');
+  });
+
+  /**
+   * A cap enforced against an unknown is not a cap. For a person, "we could
+   * not price this" is information they weigh; for an agent it must not
+   * resolve to "so we signed it", because that is the shape every unpriced
+   * exotic asset arrives in.
+   */
+  it('denies an action whose value was never stated', () => {
+    const sealed = sealPolicy({ maxValuePerActionUsd: 1_000 });
+    const decision = evaluatePolicy({
+      action: { agentId: AGENT, chain: 'ethereum', type: 'transfer', from: '0x11', to: '0x22' },
+      policy: sealed, assessment: CLEAN, now: NOW,
+    });
+
+    expect(decision.verdict).toBe('deny');
+    expect(decision.reasons.join(' ')).toMatch(/value was not stated/i);
+  });
+
+  it('accepts an explicit zero for an action that moves nothing', () => {
+    const sealed = sealPolicy({ maxValuePerActionUsd: 1_000 });
+    expect(evaluatePolicy({
+      action: action({ type: 'sign_message', valueUsd: 0, to: undefined }),
+      policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('allow');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Cumulative spend
+// ---------------------------------------------------------------------------
+
+describe('a cumulative cap actually accumulates', () => {
+  /**
+   * The failure a per-transaction cap cannot catch: a hundred individually
+   * reasonable transfers. No single one of these trips a $1,000 per-action
+   * limit, and together they are the treasury.
+   */
+  it('denies the action that would take the running total past the window', () => {
+    const clock = () => NOW.getTime();
+    const ledger = new SpendLedger({ clock });
+    const sealed = sealPolicy({
+      spendWindows: [{ label: 'daily', windowMs: 86_400_000, maxValueUsd: 1_000 }],
+    });
+
+    const admitted: number[] = [];
+    for (let i = 0; i < 5; i += 1) {
+      const decision = evaluatePolicy({
+        action: action({ valueUsd: 400 }), policy: sealed, usage: ledger, assessment: CLEAN, now: NOW,
+      });
+      if (decision.verdict !== 'deny') {
+        admitted.push(400);
+        ledger.reserve({ decisionId: decision.decisionId, agentId: AGENT, valueUsd: 400, now: NOW });
+      }
+    }
+
+    // $400 + $400 fits under $1,000; the third would reach $1,200.
+    expect(admitted).toEqual([400, 400]);
+    expect(ledger.spentUsdSince(AGENT, NOW.getTime() - 86_400_000)).toBe(800);
+  });
+
+  it('reports the running total and the limit on the decision, not just a refusal', () => {
+    const clock = () => NOW.getTime();
+    const ledger = new SpendLedger({ clock });
+    const sealed = sealPolicy({
+      spendWindows: [{ label: 'daily', windowMs: 86_400_000, maxValueUsd: 1_000 }],
+    });
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 900, now: NOW });
+
+    const decision = evaluatePolicy({
+      action: action({ valueUsd: 200 }), policy: sealed, usage: ledger, assessment: CLEAN, now: NOW,
+    });
+
+    expect(decision.verdict).toBe('deny');
+    const rule = decision.evaluations.find((e) => e.rule === 'CUMULATIVE_SPEND');
+    expect(rule?.statement).toMatch(/\$900 committed/);
+    expect(rule?.statement).toMatch(/\$1,100 with this action/);
+    expect(rule?.statement).toMatch(/against \$1,000/);
+  });
+
+  /** The window rolls. A cap that never releases is a one-off budget. */
+  it('forgets spend that has aged out of the window', () => {
+    const ledger = new SpendLedger({ clock: () => NOW.getTime() });
+    const twoHoursAgo = new Date(NOW.getTime() - 7_200_000);
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 900, now: twoHoursAgo });
+    ledger.confirm('d1', { txHash: '0xabc', now: twoHoursAgo });
+
+    expect(ledger.spentUsdSince(AGENT, NOW.getTime() - 86_400_000)).toBe(900);
+    expect(ledger.spentUsdSince(AGENT, NOW.getTime() - 3_600_000)).toBe(0);
+  });
+
+  it('keeps one agent\'s spend off another agent\'s budget', () => {
+    const ledger = new SpendLedger({ clock: () => NOW.getTime() });
+    ledger.reserve({ decisionId: 'd1', agentId: 'agent-other', valueUsd: 5_000, now: NOW });
+
+    expect(ledger.spentUsdSince(AGENT, 0)).toBe(0);
+  });
+
+  it('denies an unpriced action when a cumulative cap exists', () => {
+    const sealed = sealPolicy({
+      spendWindows: [{ label: 'daily', windowMs: 86_400_000, maxValueUsd: 1_000 }],
+    });
+    const decision = evaluatePolicy({
+      action: { agentId: AGENT, chain: 'ethereum', type: 'swap', from: '0x11', to: '0x22' },
+      policy: sealed, assessment: CLEAN, now: NOW,
+    });
+
+    expect(decision.verdict).toBe('deny');
+    expect(decision.reasons.join(' ')).toMatch(/cannot be added to a running total/i);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rate
+// ---------------------------------------------------------------------------
+
+describe('rate ceiling', () => {
+  /**
+   * An agent in a loop is the failure mode with no human equivalent. A person
+   * making the same mistake makes it once a minute; a process makes it a
+   * thousand times before anyone reads the first alert.
+   */
+  it('stops an agent that keeps going', () => {
+    const ledger = new SpendLedger({ clock: () => NOW.getTime() });
+    const sealed = sealPolicy({
+      rateWindows: [{ label: 'per-minute', windowMs: 60_000, maxActions: 3 }],
+    });
+
+    let admitted = 0;
+    for (let i = 0; i < 10; i += 1) {
+      const decision = evaluatePolicy({
+        action: action({ valueUsd: 1 }), policy: sealed, usage: ledger, assessment: CLEAN, now: NOW,
+      });
+      if (decision.verdict === 'deny') continue;
+      admitted += 1;
+      ledger.reserve({ decisionId: decision.decisionId, agentId: AGENT, valueUsd: 1, now: NOW });
+    }
+
+    expect(admitted).toBe(3);
+  });
+
+  /**
+   * The ceiling counts decisions the guard admitted, not transactions that
+   * landed. An agent that assesses and abandons in a tight loop is exactly
+   * what the ceiling is for, and a counter watching only confirmed
+   * transactions would never see it.
+   */
+  it('counts an admitted action that was later released', () => {
+    const ledger = new SpendLedger({ clock: () => NOW.getTime() });
+    ledger.reserve({ decisionId: 'd1', agentId: AGENT, valueUsd: 100, now: NOW });
+    ledger.release('d1', { now: NOW });
+
+    expect(ledger.spentUsdSince(AGENT, 0)).toBe(0);
+    expect(ledger.actionsSince(AGENT, 0)).toBe(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Risk — delegated to Protect, applied for an agent
+// ---------------------------------------------------------------------------
+
+describe('a KNOWN_MALICIOUS counterparty', () => {
+  /**
+   * The requirement stated without qualification: no amount is small enough.
+   * A per-action cap is a limit on loss; this is a limit on who the agent
+   * deals with at all, and the two must not be able to trade against each
+   * other.
+   */
+  it.each([0, 1, 0.01, 5_000_000])('is denied at a value of $%s', (valueUsd) => {
+    const sealed = sealPolicy({ maxValuePerActionUsd: 10_000_000 });
+    const decision = evaluatePolicy({
+      action: action({ valueUsd }), policy: sealed, assessment: KNOWN_MALICIOUS, now: NOW,
+    });
+
+    expect(decision.verdict).toBe('deny');
+    expect(decision.reasons.join(' ')).toMatch(/KNOWN_MALICIOUS/);
+  });
+
+  /**
+   * Denied, not escalated. A denial that a human can wave through is a
+   * denial an agent's operator can be socially engineered past, and
+   * KNOWN_MALICIOUS is the one level that already required an analyst to
+   * confirm the evidence.
+   */
+  it('is denied rather than routed to a person, even under a low approval threshold', () => {
+    const sealed = sealPolicy({ humanApprovalAboveUsd: 1 });
+    const decision = evaluatePolicy({
+      action: action({ valueUsd: 5_000 }), policy: sealed, assessment: KNOWN_MALICIOUS, now: NOW,
+    });
+
+    expect(decision.verdict).toBe('deny');
+  });
+
+  it('is denied by the default policy without the operator writing a rule', () => {
+    expect(DEFAULT_AGENT_RISK_POLICY.KNOWN_MALICIOUS).toBe('block');
+    expect(evaluatePolicy({
+      action: action(), policy: sealPolicy({}), assessment: KNOWN_MALICIOUS, now: NOW,
+    }).verdict).toBe('deny');
+  });
+});
+
+describe('risk levels below confirmed malice', () => {
+  /**
+   * Evidence-backed threat signals are where a person adds value: they can
+   * read the evidence. So ELEVATED_RISK goes to a human rather than being
+   * denied outright or waved through.
+   */
+  it('routes an evidence-backed elevated risk to a person', () => {
+    const decision = evaluatePolicy({
+      action: action(), policy: sealPolicy({}), assessment: ELEVATED, now: NOW,
+    });
+    expect(decision.verdict).toBe('require_human_approval');
+  });
+
+  /**
+   * CAUTION is reached by a single SIGNIFICANT capability — a pausable token,
+   * an upgradeable router. Most serious protocols have one. Escalating there
+   * would hand a human hundreds of approvals a day, and a human approving 500
+   * of those approves the 501st unread.
+   */
+  it('permits a mere capability rather than paging a human about a pausable token', () => {
+    const caution = classify({
+      now: NOW,
+      capabilities: [{ type: 'PAUSABLE', severity: 'SIGNIFICANT', statement: 'Transfers can be paused.' }],
+    });
+
+    expect(caution.riskLevel).toBe('CAUTION');
+    const decision = evaluatePolicy({ action: action(), policy: sealPolicy({}), assessment: caution, now: NOW });
+    expect(decision.verdict).toBe('allow');
+    // Permitted, but not invisible: the capability is on the record.
+    expect(decision.evaluations.find((e) => e.rule === 'RISK_LEVEL')?.observed).toBe('CAUTION');
+  });
+
+  it('lets an operator be stricter than the default without touching the classifier', () => {
+    const strict = sealPolicy({ maxRiskLevel: 'INFORMATIONAL' });
+    const caution = classify({
+      now: NOW,
+      capabilities: [{ type: 'PAUSABLE', severity: 'SIGNIFICANT', statement: 'Transfers can be paused.' }],
+    });
+
+    expect(evaluatePolicy({ action: action(), policy: strict, assessment: caution, now: NOW }).verdict)
+      .toBe('deny');
+    // The assessment itself is untouched — policy changes behaviour, not facts.
+    expect(caution.riskLevel).toBe('CAUTION');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Availability
+// ---------------------------------------------------------------------------
+
+describe('when Decentrys could not be reached', () => {
+  const unreachable = { assessment: null, assessmentUnavailable: 'timeout after 4000ms' };
+
+  /**
+   * Protect's consumer default is `warn`, and it does not transfer: there is
+   * nobody to warn, so a warning is an allow that logs. Of the three
+   * remaining options, `escalate` is the only one that loses nothing —
+   * `open` signs unscreened during precisely the window an attacker would
+   * choose, and `closed` halts the agent completely, which pushes operators
+   * to configure `open` to avoid it.
+   */
+  it('escalates to a person by default', () => {
+    const decision = evaluatePolicy({
+      action: action(), policy: sealPolicy({}), ...unreachable, now: NOW,
+    });
+
+    expect(decision.verdict).toBe('require_human_approval');
+    expect(decision.reasons.join(' ')).toMatch(/needs a person/i);
+  });
+
+  it('stops under failMode closed', () => {
+    expect(evaluatePolicy({
+      action: action(), policy: sealPolicy({ failMode: 'closed' }), ...unreachable, now: NOW,
+    }).verdict).toBe('deny');
+  });
+
+  it('proceeds on local limits alone under failMode open', () => {
+    expect(evaluatePolicy({
+      action: action({ valueUsd: 10 }),
+      policy: sealPolicy({ failMode: 'open', maxValuePerActionUsd: 100 }),
+      ...unreachable, now: NOW,
+    }).verdict).toBe('allow');
+  });
+
+  /**
+   * An outage removes one input; it does not suspend the operator's limits.
+   * A guard that fell open on everything the moment a service blipped would
+   * be worth less than no guard, because it would be trusted.
+   */
+  it('still applies the operator\'s own limits under failMode open', () => {
+    expect(evaluatePolicy({
+      action: action({ valueUsd: 5_000 }),
+      policy: sealPolicy({ failMode: 'open', maxValuePerActionUsd: 100 }),
+      ...unreachable, now: NOW,
+    }).verdict).toBe('deny');
+  });
+
+  it('records why no risk level was applied rather than leaving the rule silent', () => {
+    const decision = evaluatePolicy({
+      action: action(), policy: sealPolicy({}), ...unreachable, now: NOW,
+    });
+
+    expect(decision.evaluations.find((e) => e.rule === 'RISK_LEVEL')?.outcome).toBe('not_applicable');
+    expect(decision.assessmentUnavailable).toBe('timeout after 4000ms');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// What the agent may do, and with whom
+// ---------------------------------------------------------------------------
+
+describe('action-type restrictions', () => {
+  it('lets an operator say "may swap, may not approve"', () => {
+    const sealed = sealPolicy({ allowedActions: ['swap'], deniedActions: ['approve'] });
+
+    expect(evaluatePolicy({
+      action: action({ type: 'swap' }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('allow');
+    expect(evaluatePolicy({
+      action: action({ type: 'approve', approvalAmount: '1000' }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('deny');
+  });
+
+  /**
+   * An agent should not be able to do something by virtue of nobody being
+   * able to say what it is. Under an allowlist, an unclassifiable action is
+   * simply not on the list.
+   */
+  it('denies an action nobody could classify, under an allowlist', () => {
+    const sealed = sealPolicy({ allowedActions: ['swap', 'transfer'] });
+    expect(evaluatePolicy({
+      action: action({ type: 'unknown' }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('deny');
+  });
+});
+
+describe('unlimited approvals', () => {
+  /**
+   * The one action that converts a bounded mistake into an unbounded one.
+   * Defaulting it open would make the safe configuration the one an operator
+   * has to remember to write.
+   */
+  it('is refused unless the operator explicitly permitted it', () => {
+    const maxUint256 = (2n ** 256n - 1n).toString();
+    const sealed = sealPolicy({});
+
+    for (const amount of ['unlimited', maxUint256, '0x' + 'f'.repeat(64)]) {
+      const decision = evaluatePolicy({
+        action: action({ type: 'approve', token: '0xtoken', approvalAmount: amount, valueUsd: 0 }),
+        policy: sealed, assessment: CLEAN, now: NOW,
+      });
+      expect(decision.verdict, amount).toBe('deny');
+      expect(decision.reasons.join(' ')).toMatch(/unbounded loss/i);
+    }
+  });
+
+  it('permits a bounded allowance', () => {
+    expect(evaluatePolicy({
+      action: action({ type: 'approve', token: '0xtoken', approvalAmount: '1000000', valueUsd: 0 }),
+      policy: sealPolicy({}), assessment: CLEAN, now: NOW,
+    }).verdict).toBe('allow');
+  });
+
+  it('permits an unlimited allowance when the operator asked for it', () => {
+    expect(evaluatePolicy({
+      action: action({ type: 'approve', token: '0xtoken', approvalAmount: 'unlimited', valueUsd: 0 }),
+      policy: sealPolicy({ allowUnlimitedApprovals: true }), assessment: CLEAN, now: NOW,
+    }).verdict).toBe('allow');
+  });
+
+  /** An unstated allowance is the whole of what is being granted, unbounded. */
+  it('denies an approval that does not say how much it grants', () => {
+    expect(evaluatePolicy({
+      action: action({ type: 'approve', token: '0xtoken', valueUsd: 0 }),
+      policy: sealPolicy({}), assessment: CLEAN, now: NOW,
+    }).verdict).toBe('deny');
+  });
+});
+
+describe('counterparty and contract lists', () => {
+  it('denies a counterparty that is not on the allowlist', () => {
+    const sealed = sealPolicy({ allowedCounterparties: ['0xaaa'] });
+    expect(evaluatePolicy({
+      action: action({ to: '0xbbb' }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('deny');
+  });
+
+  /**
+   * EVM addresses arrive in mixed checksum case, and an allowlist an operator
+   * typed in lowercase must still match. Passing a case-variant of an
+   * allowlisted address on a case-sensitive chain would require holding a
+   * private key for that variant, which is not something an attacker searches
+   * for — so the looser comparison costs nothing.
+   */
+  it('matches an allowlist across address casing', () => {
+    const sealed = sealPolicy({ allowedCounterparties: ['0xAbCdEf0000000000000000000000000000000001'] });
+    expect(evaluatePolicy({
+      action: action({ to: '0xabcdef0000000000000000000000000000000001' }),
+      policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('allow');
+  });
+
+  /** An address on both lists is an operator error; guessing towards permission is the wrong guess. */
+  it('lets the blocklist win over the allowlist', () => {
+    const sealed = sealPolicy({ allowedCounterparties: ['0xaaa'], blockedCounterparties: ['0xaaa'] });
+    expect(evaluatePolicy({
+      action: action({ to: '0xaaa' }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('deny');
+  });
+
+  it('applies a contract allowlist only to actions that call code', () => {
+    const sealed = sealPolicy({ allowedContracts: ['0xrouter'] });
+
+    expect(evaluatePolicy({
+      action: action({ type: 'swap', to: '0xrouter' }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).evaluations.find((e) => e.rule === 'CONTRACT')?.outcome).toBe('pass');
+    expect(evaluatePolicy({
+      action: action({ type: 'transfer', to: '0xfriend' }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).evaluations.find((e) => e.rule === 'CONTRACT')?.outcome).toBe('not_applicable');
+  });
+});
+
+describe('human approval thresholds', () => {
+  it('routes a large but otherwise clean action to a person', () => {
+    const sealed = sealPolicy({ maxValuePerActionUsd: 100_000, humanApprovalAboveUsd: 10_000 });
+    expect(evaluatePolicy({
+      action: action({ valueUsd: 25_000 }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('require_human_approval');
+  });
+
+  /** A deny is not negotiable by a threshold that would otherwise escalate. */
+  it('does not let an escalation soften a denial', () => {
+    const sealed = sealPolicy({ maxValuePerActionUsd: 1_000, humanApprovalAboveUsd: 100 });
+    expect(evaluatePolicy({
+      action: action({ valueUsd: 5_000 }), policy: sealed, assessment: CLEAN, now: NOW,
+    }).verdict).toBe('deny');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The record
+// ---------------------------------------------------------------------------
+
+describe('the audit trail', () => {
+  /**
+   * "The agent spent the treasury" is answered by the record of the allow, not
+   * of the denials. A decision that lists only what went wrong cannot answer
+   * why anything was permitted.
+   */
+  it('records every rule it applied, including the ones that passed', () => {
+    const sealed = sealPolicy({
+      maxValuePerActionUsd: 1_000,
+      allowedCounterparties: ['0x2222222222222222222222222222222222222222'],
+      rateWindows: [{ label: 'per-minute', windowMs: 60_000, maxActions: 10 }],
+    });
+    const decision = evaluatePolicy({ action: action(), policy: sealed, assessment: CLEAN, now: NOW });
+
+    expect(decision.verdict).toBe('allow');
+    expect(decision.reasons).toEqual([]);
+
+    const value = decision.evaluations.find((e) => e.rule === 'VALUE_PER_ACTION');
+    expect(value?.outcome).toBe('pass');
+    expect(value?.limit).toBe(1_000);
+    expect(value?.observed).toBe(100);
+
+    const counterparty = decision.evaluations.find((e) => e.rule === 'COUNTERPARTY');
+    expect(counterparty?.outcome).toBe('pass');
+    expect(counterparty?.observed).toBe('0x2222222222222222222222222222222222222222');
+  });
+
+  /** Every rule is evaluated, so a record cannot hide a second reason. */
+  it('reports all the reasons an action failed, not only the first', () => {
+    const sealed = sealPolicy({
+      maxValuePerActionUsd: 100,
+      allowedCounterparties: ['0xaaa'],
+      deniedActions: ['approve'],
+    });
+    const decision = evaluatePolicy({
+      action: action({ type: 'approve', valueUsd: 5_000, to: '0xbbb', approvalAmount: 'unlimited' }),
+      policy: sealed, assessment: KNOWN_MALICIOUS, now: NOW,
+    });
+
+    const failed = decision.evaluations.filter((e) => e.outcome === 'fail').map((e) => e.rule);
+    expect(failed).toContain('ACTION_TYPE');
+    expect(failed).toContain('COUNTERPARTY');
+    expect(failed).toContain('VALUE_PER_ACTION');
+    expect(failed).toContain('APPROVAL_ALLOWANCE');
+    expect(failed).toContain('RISK_LEVEL');
+  });
+
+  /**
+   * The evaluator reads no clock and touches no network, so an investigator
+   * can replay a recorded decision and get the same answer.
+   */
+  it('is reproducible from the same inputs', () => {
+    const sealed = sealPolicy({ maxValuePerActionUsd: 1_000 });
+    const first = evaluatePolicy({ action: action(), policy: sealed, assessment: CLEAN, now: NOW });
+    const second = evaluatePolicy({ action: action(), policy: sealed, assessment: CLEAN, now: NOW });
+
+    expect(second.verdict).toBe(first.verdict);
+    expect(second.actionDigest).toBe(first.actionDigest);
+    expect(second.policyFingerprint).toBe(first.policyFingerprint);
+    expect(second.evaluations).toEqual(first.evaluations);
+    // The id is the one thing that differs — two decisions are two events.
+    expect(second.decisionId).not.toBe(first.decisionId);
+  });
+
+  it('distinguishes an unbounded axis from one that was checked and passed', () => {
+    const decision = evaluatePolicy({
+      action: action(), policy: sealPolicy({ maxValuePerActionUsd: 1_000 }), assessment: CLEAN, now: NOW,
+    });
+
+    expect(decision.evaluations.find((e) => e.rule === 'VALUE_PER_ACTION')?.outcome).toBe('pass');
+    expect(decision.evaluations.find((e) => e.rule === 'RATE_LIMIT')?.outcome).toBe('not_configured');
+  });
+});