@decentrys/agent 0.1.0

package/src/policy.ts

@@ -0,0 +1,951 @@
+/**
+ * The policy engine.
+ *
+ * Two things live here, and keeping them together is deliberate.
+ *
+ * **Sealing** is how "the agent cannot widen its own limits" stops being a
+ * convention. An operator writes an `AgentPolicy` and calls `sealPolicy()`.
+ * What comes back is deep-frozen, cloned away from the caller's own arrays,
+ * and carries a fingerprint of its contents. `AgentGuard` accepts nothing
+ * else, exposes no setter, and records the fingerprint on every decision. An
+ * agent handed a reference to that object can read it and cannot change it,
+ * and a policy that changed between two decisions cannot pretend it did not.
+ *
+ * The only way to derive a new policy is `narrowPolicy()`, which takes the
+ * stricter of every field. There is no widening path in this file at all —
+ * not a guarded one, not an admin one. A capability that does not exist
+ * cannot be reached by a sufficiently persuasive prompt.
+ *
+ * **Evaluation** is a pure function. `evaluatePolicy()` performs no I/O and
+ * reads no clock it was not given, so the same action, policy, assessment and
+ * usage always produce the same decision. That is what makes an audit record
+ * checkable rather than merely readable: an investigator can re-run it.
+ */
+
+import {
+  RISK_LEVELS, applyPolicy,
+  type Assessment, type Policy, type PolicyAction, type RiskLevel,
+} from '@decentrys/protect';
+
+import {
+  AGENT_MODEL_VERSION,
+  type AgentAction, type AgentActionType, type AgentDecision, type AgentFailMode,
+  type AgentPolicy, type AgentVerdict, type RateWindow, type RuleEvaluation,
+  type SpendWindow,
+} from './model';
+import type { AgentUsage } from './ledger';
+
+// ---------------------------------------------------------------------------
+// The default risk policy for an autonomous actor
+// ---------------------------------------------------------------------------
+
+/**
+ * How risk levels map to behaviour when nobody is watching.
+ *
+ * Protect's consumer default warns from CAUTION upward and blocks only
+ * `KNOWN_MALICIOUS`, because a person is reading the warning. Neither half of
+ * that transfers:
+ *
+ *  - **`warn` is not available to an agent.** It is mapped out entirely; see
+ *    `sealPolicy`, which refuses a `warn` in an agent risk policy rather than
+ *    quietly reinterpreting it.
+ *  - **CAUTION stays `allow`, and that is not laziness.** CAUTION is reached
+ *    by a single SIGNIFICANT *capability* — a pausable token, an upgradeable
+ *    router. Most serious protocols have one. Escalating there would send a
+ *    human hundreds of approvals a day, and a human who approves 500
+ *    escalations approves the 501st unread. The Sentinel stage recorded the
+ *    same failure for alerts; it is worse here, because the 501st is the one
+ *    that empties the treasury. The capability is still recorded on the
+ *    decision, so it is visible without being an interrupt.
+ *  - **ELEVATED_RISK upward escalates**, because at that point actual threat
+ *    signals with evidence exist and a person can weigh them.
+ *  - **`KNOWN_MALICIOUS` denies, and a denial is not escalatable.** It is the
+ *    one level that requires analyst-verified evidence, and there is no value
+ *    at which signing to confirmed malicious infrastructure is the right call.
+ *
+ * `CRITICAL_THREAT` escalates rather than denies for the reason Protect draws
+ * the same line: severe evidence that no analyst has confirmed is exactly the
+ * case where a person should look at the evidence.
+ */
+export const DEFAULT_AGENT_RISK_POLICY: Required<Policy> = {
+  NO_CRITICAL_RISK_DETECTED: 'allow',
+  INFORMATIONAL: 'allow',
+  CAUTION: 'allow',
+  ELEVATED_RISK: 'require_confirmation',
+  HIGH_RISK: 'require_confirmation',
+  CRITICAL_THREAT: 'require_confirmation',
+  KNOWN_MALICIOUS: 'block',
+};
+
+/**
+ * An allowance this large cannot be exhausted by any real token supply, so it
+ * is unlimited in every sense that matters to the holder. Wallets and routers
+ * use several different sentinels (`2^256-1`, `2^255-1`, and others); a
+ * threshold catches all of them without a table of magic constants.
+ */
+const UNLIMITED_ALLOWANCE_THRESHOLD = 1n << 255n;
+
+/** How strict each action is, for narrowing. Higher is stricter. */
+const POLICY_ACTION_STRICTNESS: Record<PolicyAction, number> = {
+  allow: 0, inform: 1, warn: 2, warn_strong: 3, require_confirmation: 4, block: 5,
+};
+
+const FAIL_MODE_STRICTNESS: Record<AgentFailMode, number> = { open: 0, escalate: 1, closed: 2 };
+
+// ---------------------------------------------------------------------------
+// Sealing
+// ---------------------------------------------------------------------------
+
+/**
+ * The brand, as a real runtime symbol rather than a `declare`d type-only one.
+ *
+ * A type-only brand is erased at compile time, so an object cast to
+ * `SealedPolicy` would satisfy every check and carry no mark at all. This
+ * symbol is module-private and never exported, so the only way to obtain an
+ * object bearing it is to call `sealPolicy()` — which clones and freezes.
+ */
+const SEALED_POLICY: unique symbol = Symbol('decentrys.agent.sealedPolicy');
+
+export interface SealedPolicy {
+  /**
+   * Structural, not decorative. A plain object literal is not assignable to
+   * `SealedPolicy`, so there is no way to hand `AgentGuard` a policy that did
+   * not go through `sealPolicy()` — including from inside a tool an agent
+   * controls.
+   */
+  readonly [SEALED_POLICY]: true;
+  readonly policy: Readonly<AgentPolicy>;
+  /**
+   * A content fingerprint. Not a cryptographic commitment — it exists so two
+   * decisions can be shown to have run under the same rules, and so a policy
+   * that changed mid-incident cannot be described afterwards as unchanged.
+   */
+  readonly fingerprint: string;
+  /**
+   * Configurations that are legal but deserve to be said out loud — a policy
+   * that permits confirmed-malicious counterparties, or one with no limits at
+   * all. Surfaced rather than refused: policy belongs to the integrator.
+   */
+  readonly warnings: readonly string[];
+}
+
+export function sealPolicy(policy: AgentPolicy): SealedPolicy {
+  const risk = policy.risk ?? {};
+  for (const [level, action] of Object.entries(risk)) {
+    if (action === 'warn' || action === 'warn_strong') {
+      // Refused rather than reinterpreted. An agent has no eyes; a `warn` here
+      // would either be silently upgraded to an escalation (changing the
+      // operator's meaning without telling them) or silently treated as an
+      // allow (a control that does nothing). Both are worse than an error at
+      // wiring time.
+      throw new Error(
+        `AgentGuard: '${action}' is not a valid action for an agent policy (at ${level}). `
+        + 'There is nobody to warn. Use \'allow\' to permit and record it, or '
+        + '\'require_confirmation\' to route it to a person.',
+      );
+    }
+  }
+
+  const cloned = clonePolicy(policy);
+  const warnings: string[] = [];
+
+  const effectiveRisk = { ...DEFAULT_AGENT_RISK_POLICY, ...cloned.risk };
+  if (effectiveRisk.KNOWN_MALICIOUS !== 'block') {
+    warnings.push(
+      'This policy does not deny KNOWN_MALICIOUS counterparties. That level requires '
+      + 'analyst-verified evidence and is the one classification Decentrys treats as an accusation.',
+    );
+  }
+  if (!hasAnyLimit(cloned)) {
+    warnings.push(
+      'This policy sets no value cap, no cumulative window, no allowlist and no rate ceiling. '
+      + 'The agent is bounded only by risk classification.',
+    );
+  }
+
+  return deepFreeze({
+    [SEALED_POLICY]: true as const,
+    policy: cloned,
+    fingerprint: fingerprint(cloned),
+    warnings,
+  }) as SealedPolicy;
+}
+
+/**
+ * Derive a stricter policy. There is no counterpart that loosens one.
+ *
+ * Every field is combined by taking the tighter side: caps become the minimum,
+ * allowlists intersect, blocklists union, windows accumulate, and
+ * `allowUnlimitedApprovals` is true only if both sides say so. So a
+ * restriction supplied at call time — including one an agent composed itself —
+ * can only ever reduce what is permitted.
+ */
+export function narrowPolicy(base: SealedPolicy, restriction: AgentPolicy): SealedPolicy {
+  const a = base.policy;
+  const b = clonePolicy(restriction);
+
+  if (a.agentId && b.agentId && a.agentId !== b.agentId) {
+    // Not a narrowing — it is a contradiction, and silently resolving it either
+    // way would hide which agent's limits are actually in force.
+    throw new Error(
+      `AgentGuard: cannot narrow a policy bound to agent '${a.agentId}' with one bound to '${b.agentId}'.`,
+    );
+  }
+
+  return sealPolicy({
+    version: [a.version, b.version].filter(Boolean).join('+') || undefined,
+    agentId: a.agentId ?? b.agentId,
+    risk: strictestRisk(a.risk, b.risk),
+    maxRiskLevel: lowerRiskLevel(a.maxRiskLevel, b.maxRiskLevel),
+    maxValuePerActionUsd: minDefined(a.maxValuePerActionUsd, b.maxValuePerActionUsd),
+    spendWindows: concatWindows(a.spendWindows, b.spendWindows),
+    rateWindows: concatWindows(a.rateWindows, b.rateWindows),
+    allowedCounterparties: intersectLists(a.allowedCounterparties, b.allowedCounterparties),
+    blockedCounterparties: unionLists(a.blockedCounterparties, b.blockedCounterparties),
+    allowedContracts: intersectLists(a.allowedContracts, b.allowedContracts),
+    allowedTokens: intersectLists(a.allowedTokens, b.allowedTokens),
+    allowedActions: intersectLists(a.allowedActions, b.allowedActions),
+    deniedActions: unionLists(a.deniedActions, b.deniedActions),
+    allowedChains: intersectLists(a.allowedChains, b.allowedChains),
+    allowUnlimitedApprovals: (a.allowUnlimitedApprovals ?? false) && (b.allowUnlimitedApprovals ?? false),
+    humanApprovalAboveUsd: minDefined(a.humanApprovalAboveUsd, b.humanApprovalAboveUsd),
+    humanApprovalAtRiskLevel: lowerRiskLevel(a.humanApprovalAtRiskLevel, b.humanApprovalAtRiskLevel),
+    failMode: stricterFailMode(a.failMode, b.failMode),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+
+export interface EvaluatePolicyInput {
+  action: AgentAction;
+  policy: SealedPolicy;
+  /** The Protect assessment, when one was obtained. */
+  assessment?: Assessment | null;
+  /** Why no assessment was obtained. Drives the `failMode` rule. */
+  assessmentUnavailable?: string;
+  /** Committed spend and admitted actions so far. Absent means none recorded. */
+  usage?: AgentUsage;
+  now?: Date;
+  /** Supplied by the caller so a decision and its reservation share an id. */
+  decisionId?: string;
+}
+
+/**
+ * Evaluate an action against a sealed policy.
+ *
+ * Every rule is evaluated, including after one has already failed. Stopping at
+ * the first failure would produce a record saying an action exceeded its value
+ * cap while omitting that its counterparty was also confirmed malicious — and
+ * an operator reading that would tune the cap and ship the same hole.
+ *
+ * The verdict is the worst outcome any rule reached: one `fail` denies, one
+ * `escalate` sends it to a person, and everything else allows.
+ */
+export function evaluatePolicy(input: EvaluatePolicyInput): AgentDecision {
+  const now = input.now ?? new Date();
+  const nowMs = now.getTime();
+  const { action } = input;
+  const policy = input.policy.policy;
+  const evaluations: RuleEvaluation[] = [];
+
+  // --- 1. Is this policy even this agent's? --------------------------------
+  if (policy.agentId) {
+    const bound = policy.agentId === action.agentId;
+    evaluations.push({
+      rule: 'AGENT_BINDING',
+      outcome: bound ? 'pass' : 'fail',
+      statement: bound
+        ? `This policy is bound to agent '${policy.agentId}', which proposed the action.`
+        : `This policy is bound to agent '${policy.agentId}'; the action was proposed by '${action.agentId}'.`,
+      limit: policy.agentId,
+      observed: action.agentId,
+    });
+  } else {
+    evaluations.push({
+      rule: 'AGENT_BINDING',
+      outcome: 'not_configured',
+      statement: 'This policy is not bound to a specific agent.',
+    });
+  }
+
+  // --- 2. What the agent is permitted to do --------------------------------
+  evaluations.push(evaluateActionType(action.type, policy.allowedActions, policy.deniedActions));
+  evaluations.push(evaluateAllowlist(
+    'CHAIN', 'chain', action.chain, policy.allowedChains,
+  ));
+
+  // --- 3. Who it may deal with ---------------------------------------------
+  evaluations.push(evaluateCounterparty(action, policy));
+  evaluations.push(evaluateContract(action, policy));
+  evaluations.push(evaluateAllowlist('TOKEN', 'token', action.token, policy.allowedTokens));
+
+  // --- 4. Allowances --------------------------------------------------------
+  evaluations.push(evaluateAllowance(action, policy.allowUnlimitedApprovals ?? false));
+
+  // --- 5. Value -------------------------------------------------------------
+  evaluations.push(evaluatePerActionValue(action, policy.maxValuePerActionUsd));
+  evaluations.push(evaluateCumulativeSpend(action, policy.spendWindows, input.usage, nowMs));
+
+  // --- 6. Rate --------------------------------------------------------------
+  evaluations.push(evaluateRate(action, policy.rateWindows, input.usage, nowMs));
+
+  // --- 7. Risk, from the Protect model — not reimplemented here -------------
+  const effectiveRisk: Policy = { ...DEFAULT_AGENT_RISK_POLICY, ...policy.risk };
+  evaluations.push(evaluateAvailability(input.assessment, input.assessmentUnavailable, policy.failMode ?? 'escalate'));
+  evaluations.push(evaluateRisk(input.assessment, effectiveRisk, policy.maxRiskLevel));
+
+  // --- 8. Thresholds a human owns even when everything passed ---------------
+  evaluations.push(evaluateHumanApproval(action, policy, input.assessment));
+
+  const verdict = verdictFrom(evaluations);
+  const reasons = evaluations
+    .filter((e) => e.outcome === 'fail' || e.outcome === 'escalate')
+    .map((e) => e.statement);
+
+  return {
+    decisionId: input.decisionId ?? newDecisionId(),
+    agentId: action.agentId,
+    verdict,
+    reasons,
+    evaluations,
+    ...(input.assessment ? { assessment: input.assessment } : {}),
+    ...(input.assessmentUnavailable ? { assessmentUnavailable: input.assessmentUnavailable } : {}),
+    policyFingerprint: input.policy.fingerprint,
+    ...(policy.version ? { policyVersion: policy.version } : {}),
+    actionDigest: fingerprint(canonicalAction(action)),
+    modelVersion: AGENT_MODEL_VERSION,
+    decidedAt: now.toISOString(),
+  };
+}
+
+function verdictFrom(evaluations: RuleEvaluation[]): AgentVerdict {
+  if (evaluations.some((e) => e.outcome === 'fail')) return 'deny';
+  if (evaluations.some((e) => e.outcome === 'escalate')) return 'require_human_approval';
+  return 'allow';
+}
+
+// ---------------------------------------------------------------------------
+// Individual rules
+// ---------------------------------------------------------------------------
+
+function evaluateActionType(
+  type: AgentActionType,
+  allowed: readonly AgentActionType[] | undefined,
+  denied: readonly AgentActionType[] | undefined,
+): RuleEvaluation {
+  if (denied?.includes(type)) {
+    return {
+      rule: 'ACTION_TYPE', outcome: 'fail',
+      statement: `Actions of type '${type}' are denied by this policy.`,
+      limit: `denied: ${denied.join(', ')}`, observed: type,
+    };
+  }
+  // An empty allowlist is an allowlist that nothing is on. Treating it as
+  // "unconfigured" would make `narrowPolicy` able to *widen* a policy whenever
+  // two allowlists it intersected had nothing in common.
+  if (allowed) {
+    const ok = allowed.includes(type);
+    return {
+      rule: 'ACTION_TYPE', outcome: ok ? 'pass' : 'fail',
+      statement: ok
+        ? `'${type}' is one of the action types this agent may perform.`
+        // `unknown` lands here whenever the integrator could not classify the
+        // action. Under an allowlist that is a denial, which is the right way
+        // round: an agent should not be able to do something by virtue of
+        // nobody being able to say what it is.
+        : `'${type}' is not among the action types this agent may perform.`,
+      limit: allowed.join(', '), observed: type,
+    };
+  }
+  return {
+    rule: 'ACTION_TYPE', outcome: 'not_configured',
+    statement: 'This policy does not restrict which action types the agent may perform.',
+    observed: type,
+  };
+}
+
+function evaluateAllowlist(
+  rule: 'CHAIN' | 'TOKEN', label: string, value: string | undefined,
+  allowed: readonly string[] | undefined,
+): RuleEvaluation {
+  if (!allowed) {
+    return {
+      rule, outcome: 'not_configured',
+      statement: `This policy does not restrict the ${label}.`,
+      ...(value === undefined ? {} : { observed: value }),
+    };
+  }
+  if (value === undefined) {
+    return {
+      rule, outcome: 'not_applicable',
+      statement: `The action carries no ${label}, so the ${label} allowlist does not apply.`,
+      limit: allowed.join(', '),
+    };
+  }
+  const ok = matchesList(value, allowed);
+  return {
+    rule, outcome: ok ? 'pass' : 'fail',
+    statement: ok
+      ? `The ${label} '${value}' is on the allowlist.`
+      : `The ${label} '${value}' is not on the allowlist.`,
+    limit: allowed.join(', '), observed: value,
+  };
+}
+
+/** Action types that address code rather than a plain recipient. */
+const CODE_ADDRESSED: AgentActionType[] = ['contract_call', 'approve', 'swap', 'bridge', 'stake', 'unstake'];
+
+function evaluateCounterparty(action: AgentAction, policy: AgentPolicy): RuleEvaluation {
+  const to = action.to;
+  const blocked = policy.blockedCounterparties;
+  const allowed = policy.allowedCounterparties;
+
+  if (to && blocked && matchesList(to, blocked)) {
+    // Denial wins over the allowlist. A counterparty on both lists is an
+    // operator error, and resolving it towards permission is the wrong guess.
+    return {
+      rule: 'COUNTERPARTY', outcome: 'fail',
+      statement: `The counterparty ${to} is on this policy's blocklist.`,
+      limit: 'blocklist', observed: to,
+    };
+  }
+  if (!allowed) {
+    return {
+      rule: 'COUNTERPARTY',
+      outcome: blocked && blocked.length > 0 ? 'pass' : 'not_configured',
+      statement: blocked && blocked.length > 0
+        ? `The counterparty ${to ?? '(none)'} is not on this policy's blocklist.`
+        : 'This policy does not restrict counterparties.',
+      ...(to === undefined ? {} : { observed: to }),
+    };
+  }
+  if (!to) {
+    return {
+      rule: 'COUNTERPARTY', outcome: 'fail',
+      statement: 'This policy allowlists counterparties, and the action names none. '
+        + 'An action with no identifiable recipient cannot be checked against an allowlist.',
+      limit: `${allowed.length} allowlisted`,
+    };
+  }
+  const ok = matchesList(to, allowed);
+  return {
+    rule: 'COUNTERPARTY', outcome: ok ? 'pass' : 'fail',
+    statement: ok
+      ? `The counterparty ${to} is on this policy's allowlist.`
+      : `The counterparty ${to} is not on this policy's allowlist.`,
+    limit: `${allowed.length} allowlisted`, observed: to,
+  };
+}
+
+function evaluateContract(action: AgentAction, policy: AgentPolicy): RuleEvaluation {
+  const allowed = policy.allowedContracts;
+  if (!allowed) {
+    return {
+      rule: 'CONTRACT', outcome: 'not_configured',
+      statement: 'This policy does not restrict which contracts the agent may call.',
+    };
+  }
+  if (!CODE_ADDRESSED.includes(action.type)) {
+    return {
+      rule: 'CONTRACT', outcome: 'not_applicable',
+      statement: `A '${action.type}' action does not call a contract, so the contract allowlist does not apply.`,
+      limit: `${allowed.length} allowlisted`,
+    };
+  }
+  if (!action.to) {
+    return {
+      rule: 'CONTRACT', outcome: 'fail',
+      statement: `A '${action.type}' action must name the contract it calls for the allowlist to be applied.`,
+      limit: `${allowed.length} allowlisted`,
+    };
+  }
+  const ok = matchesList(action.to, allowed);
+  return {
+    rule: 'CONTRACT', outcome: ok ? 'pass' : 'fail',
+    statement: ok
+      ? `The contract ${action.to} is on this policy's allowlist.`
+      : `The contract ${action.to} is not on this policy's allowlist.`,
+    limit: `${allowed.length} allowlisted`, observed: action.to,
+  };
+}
+
+function evaluateAllowance(action: AgentAction, allowUnlimited: boolean): RuleEvaluation {
+  if (action.type !== 'approve') {
+    return {
+      rule: 'APPROVAL_ALLOWANCE', outcome: 'not_applicable',
+      statement: `A '${action.type}' action grants no allowance.`,
+    };
+  }
+  const amount = action.approvalAmount;
+  if (amount === undefined) {
+    return {
+      rule: 'APPROVAL_ALLOWANCE', outcome: 'fail',
+      statement: 'An approval was proposed without stating the allowance. The size of an allowance is '
+        + 'the whole of what is being granted, and an unstated one cannot be bounded.',
+    };
+  }
+  const unlimited = isUnlimitedAllowance(amount);
+  if (!unlimited) {
+    return {
+      rule: 'APPROVAL_ALLOWANCE', outcome: 'pass',
+      statement: `The approval grants a bounded allowance of ${amount} base units.`,
+      observed: amount,
+    };
+  }
+  return {
+    rule: 'APPROVAL_ALLOWANCE',
+    outcome: allowUnlimited ? 'pass' : 'fail',
+    statement: allowUnlimited
+      ? 'The approval is unlimited, which this policy explicitly permits.'
+      : 'The approval grants an unlimited allowance. This policy does not permit one — an unlimited '
+        + 'allowance turns any later compromise of the spender into an unbounded loss.',
+    limit: allowUnlimited ? 'unlimited permitted' : 'bounded allowances only',
+    observed: 'unlimited',
+  };
+}
+
+/** `unlimited`, or a number large enough that no real supply could exhaust it. */
+export function isUnlimitedAllowance(amount: string): boolean {
+  const trimmed = amount.trim();
+  if (/^unlimited$/i.test(trimmed) || /^max$/i.test(trimmed) || /^infinite$/i.test(trimmed)) return true;
+  try {
+    const parsed = /^0x[0-9a-f]+$/i.test(trimmed) ? BigInt(trimmed) : BigInt(trimmed.replace(/^\+/, ''));
+    return parsed >= UNLIMITED_ALLOWANCE_THRESHOLD;
+  } catch {
+    // Not a number and not a keyword. Reported as bounded here; the value is
+    // still recorded on the decision, and an integrator passing prose into
+    // this field has a wiring problem this function should not paper over.
+    return false;
+  }
+}
+
+function evaluatePerActionValue(action: AgentAction, cap: number | undefined): RuleEvaluation {
+  if (cap === undefined) {
+    return {
+      rule: 'VALUE_PER_ACTION', outcome: 'not_configured',
+      statement: 'This policy sets no per-action value cap.',
+      ...(action.valueUsd === undefined ? {} : { observed: action.valueUsd }),
+    };
+  }
+  if (action.valueUsd === undefined) {
+    // The only defensible answer. A cap enforced against an unknown value is
+    // not a cap, and for an autonomous signer "we could not price it" must not
+    // resolve to "so we signed it". `valueUsd: 0` is available and explicit
+    // for actions that genuinely move nothing.
+    return {
+      rule: 'VALUE_PER_ACTION', outcome: 'fail',
+      statement: `This policy caps a single action at $${cap.toLocaleString('en-US')}, and the action's `
+        + 'value was not stated. An unpriced action cannot be shown to be under a cap. Pass `valueUsd` — '
+        + 'use 0 for an action that moves nothing.',
+      limit: cap, observed: 'unknown',
+    };
+  }
+  const ok = action.valueUsd <= cap;
+  return {
+    rule: 'VALUE_PER_ACTION', outcome: ok ? 'pass' : 'fail',
+    statement: ok
+      ? `$${action.valueUsd.toLocaleString('en-US')} is within the $${cap.toLocaleString('en-US')} per-action cap.`
+      : `$${action.valueUsd.toLocaleString('en-US')} exceeds the $${cap.toLocaleString('en-US')} per-action cap.`,
+    limit: cap, observed: action.valueUsd,
+  };
+}
+
+function evaluateCumulativeSpend(
+  action: AgentAction, windows: readonly SpendWindow[] | undefined,
+  usage: AgentUsage | undefined, nowMs: number,
+): RuleEvaluation {
+  if (!windows || windows.length === 0) {
+    return {
+      rule: 'CUMULATIVE_SPEND', outcome: 'not_configured',
+      statement: 'This policy sets no cumulative spend limit.',
+    };
+  }
+  if (action.valueUsd === undefined) {
+    return {
+      rule: 'CUMULATIVE_SPEND', outcome: 'fail',
+      statement: 'This policy limits cumulative spend, and the action\'s value was not stated. '
+        + 'An unpriced action cannot be added to a running total.',
+      limit: windows.map(describeSpendWindow).join('; '), observed: 'unknown',
+    };
+  }
+
+  const breached: string[] = [];
+  const lines: string[] = [];
+  for (const window of windows) {
+    const spent = usage?.spentUsdSince(action.agentId, nowMs - window.windowMs) ?? 0;
+    const projected = spent + action.valueUsd;
+    lines.push(
+      `${window.label}: $${round2(spent).toLocaleString('en-US')} committed, `
+      + `$${round2(projected).toLocaleString('en-US')} with this action, `
+      + `against $${window.maxValueUsd.toLocaleString('en-US')}`,
+    );
+    if (projected > window.maxValueUsd) breached.push(window.label);
+  }
+
+  return {
+    rule: 'CUMULATIVE_SPEND',
+    outcome: breached.length > 0 ? 'fail' : 'pass',
+    statement: breached.length > 0
+      ? `This action would take the agent past its ${breached.join(' and ')} spend limit. ${lines.join('; ')}.`
+      : `Within every cumulative spend limit. ${lines.join('; ')}.`,
+    limit: windows.map(describeSpendWindow).join('; '),
+    observed: action.valueUsd,
+  };
+}
+
+function evaluateRate(
+  action: AgentAction, windows: readonly RateWindow[] | undefined,
+  usage: AgentUsage | undefined, nowMs: number,
+): RuleEvaluation {
+  if (!windows || windows.length === 0) {
+    return {
+      rule: 'RATE_LIMIT', outcome: 'not_configured',
+      statement: 'This policy sets no rate ceiling. An agent in a loop is bounded only by its value limits.',
+    };
+  }
+
+  const breached: string[] = [];
+  const lines: string[] = [];
+  for (const window of windows) {
+    const admitted = usage?.actionsSince(action.agentId, nowMs - window.windowMs) ?? 0;
+    lines.push(`${window.label}: ${admitted} admitted, ${admitted + 1} with this action, against ${window.maxActions}`);
+    if (admitted + 1 > window.maxActions) breached.push(window.label);
+  }
+
+  return {
+    rule: 'RATE_LIMIT',
+    outcome: breached.length > 0 ? 'fail' : 'pass',
+    statement: breached.length > 0
+      ? `This action would exceed the agent's ${breached.join(' and ')} rate ceiling. ${lines.join('; ')}.`
+      : `Within every rate ceiling. ${lines.join('; ')}.`,
+    limit: windows.map((w) => `${w.maxActions} per ${describeDuration(w.windowMs)} (${w.label})`).join('; '),
+  };
+}
+
+function evaluateAvailability(
+  assessment: Assessment | null | undefined, unavailable: string | undefined, failMode: AgentFailMode,
+): RuleEvaluation {
+  if (assessment) {
+    return {
+      rule: 'ASSESSMENT_AVAILABILITY', outcome: 'pass',
+      statement: 'A Decentrys assessment was obtained for this action.',
+      observed: assessment.riskLevel,
+    };
+  }
+  const why = unavailable ?? 'no assessment was supplied';
+  const outcome: RuleOutcomeForFailMode = failMode === 'closed'
+    ? 'fail' : failMode === 'escalate' ? 'escalate' : 'pass';
+  return {
+    rule: 'ASSESSMENT_AVAILABILITY', outcome,
+    statement: failMode === 'closed'
+      ? `No risk assessment could be obtained (${why}), and this policy is configured to stop rather than `
+        + 'act on unscreened actions.'
+      : failMode === 'escalate'
+        ? `No risk assessment could be obtained (${why}). The operator's own limits still applied and still `
+          + 'bind; only the external check is missing, so this action needs a person.'
+        : `No risk assessment could be obtained (${why}). This policy is configured to proceed on the `
+          + 'operator\'s own limits alone.',
+    limit: `failMode: ${failMode}`, observed: 'unavailable',
+  };
+}
+
+type RuleOutcomeForFailMode = 'pass' | 'fail' | 'escalate';
+
+function evaluateRisk(
+  assessment: Assessment | null | undefined, risk: Policy, maxRiskLevel: RiskLevel | undefined,
+): RuleEvaluation {
+  if (!assessment) {
+    return {
+      rule: 'RISK_LEVEL', outcome: 'not_applicable',
+      statement: 'No assessment was available, so no risk level was applied. See ASSESSMENT_AVAILABILITY.',
+    };
+  }
+
+  const level = assessment.riskLevel;
+  if (maxRiskLevel && riskRank(level) > riskRank(maxRiskLevel)) {
+    return {
+      rule: 'RISK_LEVEL', outcome: 'fail',
+      statement: `The subject classified as ${level}, above this policy's ceiling of ${maxRiskLevel}. `
+        + (assessment.explanation[0] ?? ''),
+      limit: maxRiskLevel, observed: level,
+    };
+  }
+
+  // Delegated to Protect. The risk model is not reimplemented here — this
+  // package decides what an *agent* does with a level, never what the level is.
+  const decision = applyPolicy(assessment, risk);
+  const outcome: RuleOutcomeForFailMode = decision.action === 'block'
+    ? 'fail' : decision.action === 'require_confirmation' ? 'escalate' : 'pass';
+
+  const statement = decision.action === 'block'
+    ? `The subject classified as ${level} and this policy denies at that level. ${decision.reason}`
+    : decision.action === 'require_confirmation'
+      ? `The subject classified as ${level}, which this policy routes to a person. ${decision.reason}`
+      : `The subject classified as ${level}, which this policy permits. ${decision.reason}`;
+
+  return { rule: 'RISK_LEVEL', outcome, statement, limit: `${level} → ${decision.action}`, observed: level };
+}
+
+function evaluateHumanApproval(
+  action: AgentAction, policy: AgentPolicy, assessment: Assessment | null | undefined,
+): RuleEvaluation {
+  const valueThreshold = policy.humanApprovalAboveUsd;
+  const riskThreshold = policy.humanApprovalAtRiskLevel;
+
+  if (valueThreshold === undefined && riskThreshold === undefined) {
+    return {
+      rule: 'HUMAN_APPROVAL_THRESHOLD', outcome: 'not_configured',
+      statement: 'This policy sets no threshold above which a person must approve.',
+    };
+  }
+
+  const triggers: string[] = [];
+  if (valueThreshold !== undefined) {
+    if (action.valueUsd === undefined) {
+      triggers.push(
+        `a person approves anything above $${valueThreshold.toLocaleString('en-US')} and this action's `
+        + 'value was not stated, so it cannot be shown to be below that',
+      );
+    } else if (action.valueUsd > valueThreshold) {
+      triggers.push(
+        `$${action.valueUsd.toLocaleString('en-US')} is above the $${valueThreshold.toLocaleString('en-US')} `
+        + 'threshold for human approval',
+      );
+    }
+  }
+  if (riskThreshold && assessment && riskRank(assessment.riskLevel) >= riskRank(riskThreshold)) {
+    triggers.push(`the subject classified as ${assessment.riskLevel}, at or above the ${riskThreshold} threshold`);
+  }
+
+  if (triggers.length === 0) {
+    return {
+      rule: 'HUMAN_APPROVAL_THRESHOLD', outcome: 'pass',
+      statement: 'Below every threshold that would require a person to approve.',
+      ...(valueThreshold === undefined ? {} : { limit: valueThreshold }),
+      ...(action.valueUsd === undefined ? {} : { observed: action.valueUsd }),
+    };
+  }
+
+  return {
+    rule: 'HUMAN_APPROVAL_THRESHOLD', outcome: 'escalate',
+    statement: `A person must approve this action: ${triggers.join('; ')}.`,
+    ...(valueThreshold === undefined ? {} : { limit: valueThreshold }),
+    ...(action.valueUsd === undefined ? {} : { observed: action.valueUsd }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function riskRank(level: RiskLevel): number {
+  return RISK_LEVELS.indexOf(level);
+}
+
+/**
+ * Addresses are compared case-insensitively.
+ *
+ * EVM addresses arrive in mixed checksum case and must still match an
+ * allowlist an operator wrote in lowercase. For a case-sensitive family such
+ * as Solana's base58, passing a case-variant of an allowlisted address would
+ * require holding a private key for that variant, which is not something an
+ * attacker can search for. The looser comparison therefore costs nothing and
+ * removes a class of allowlist that silently fails to match.
+ */
+function matchesList(value: string, list: readonly string[]): boolean {
+  const needle = value.trim().toLowerCase();
+  return list.some((entry) => entry.trim().toLowerCase() === needle);
+}
+
+function describeSpendWindow(window: SpendWindow): string {
+  return `$${window.maxValueUsd.toLocaleString('en-US')} per ${describeDuration(window.windowMs)} (${window.label})`;
+}
+
+export function describeDuration(ms: number): string {
+  if (ms % 86_400_000 === 0) return plural(ms / 86_400_000, 'day');
+  if (ms % 3_600_000 === 0) return plural(ms / 3_600_000, 'hour');
+  if (ms % 60_000 === 0) return plural(ms / 60_000, 'minute');
+  if (ms % 1_000 === 0) return plural(ms / 1_000, 'second');
+  return `${ms}ms`;
+}
+
+function plural(count: number, unit: string): string {
+  return count === 1 ? unit : `${count} ${unit}s`;
+}
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function hasAnyLimit(policy: AgentPolicy): boolean {
+  return policy.maxValuePerActionUsd !== undefined
+    || (policy.spendWindows?.length ?? 0) > 0
+    || (policy.rateWindows?.length ?? 0) > 0
+    || policy.allowedCounterparties !== undefined
+    || (policy.blockedCounterparties?.length ?? 0) > 0
+    || policy.allowedContracts !== undefined
+    || policy.allowedTokens !== undefined
+    || policy.allowedActions !== undefined
+    || (policy.deniedActions?.length ?? 0) > 0
+    || policy.allowedChains !== undefined
+    || policy.humanApprovalAboveUsd !== undefined
+    || policy.humanApprovalAtRiskLevel !== undefined;
+}
+
+/**
+ * Clone every array and object out of the caller's hands.
+ *
+ * Freezing the caller's own arrays would be both rude and insufficient: an
+ * operator who keeps a reference to the array they passed could otherwise
+ * push a new counterparty onto a live allowlist, and nothing in the audit
+ * record would show the policy had changed.
+ */
+function clonePolicy(policy: AgentPolicy): AgentPolicy {
+  const cloned: AgentPolicy = {};
+  if (policy.version !== undefined) cloned.version = policy.version;
+  if (policy.agentId !== undefined) cloned.agentId = policy.agentId;
+  if (policy.risk !== undefined) cloned.risk = { ...policy.risk };
+  if (policy.maxRiskLevel !== undefined) cloned.maxRiskLevel = policy.maxRiskLevel;
+  if (policy.maxValuePerActionUsd !== undefined) cloned.maxValuePerActionUsd = policy.maxValuePerActionUsd;
+  if (policy.spendWindows !== undefined) cloned.spendWindows = policy.spendWindows.map((w) => ({ ...w }));
+  if (policy.rateWindows !== undefined) cloned.rateWindows = policy.rateWindows.map((w) => ({ ...w }));
+  if (policy.allowedCounterparties !== undefined) cloned.allowedCounterparties = [...policy.allowedCounterparties];
+  if (policy.blockedCounterparties !== undefined) cloned.blockedCounterparties = [...policy.blockedCounterparties];
+  if (policy.allowedContracts !== undefined) cloned.allowedContracts = [...policy.allowedContracts];
+  if (policy.allowedTokens !== undefined) cloned.allowedTokens = [...policy.allowedTokens];
+  if (policy.allowedActions !== undefined) cloned.allowedActions = [...policy.allowedActions];
+  if (policy.deniedActions !== undefined) cloned.deniedActions = [...policy.deniedActions];
+  if (policy.allowedChains !== undefined) cloned.allowedChains = [...policy.allowedChains];
+  if (policy.allowUnlimitedApprovals !== undefined) cloned.allowUnlimitedApprovals = policy.allowUnlimitedApprovals;
+  if (policy.humanApprovalAboveUsd !== undefined) cloned.humanApprovalAboveUsd = policy.humanApprovalAboveUsd;
+  if (policy.humanApprovalAtRiskLevel !== undefined) cloned.humanApprovalAtRiskLevel = policy.humanApprovalAtRiskLevel;
+  if (policy.failMode !== undefined) cloned.failMode = policy.failMode;
+  return cloned;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value === null || typeof value !== 'object') return value;
+  for (const key of Object.getOwnPropertyNames(value)) {
+    deepFreeze((value as Record<string, unknown>)[key]);
+  }
+  return Object.freeze(value);
+}
+
+function minDefined(a: number | undefined, b: number | undefined): number | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return Math.min(a, b);
+}
+
+function lowerRiskLevel(a: RiskLevel | undefined, b: RiskLevel | undefined): RiskLevel | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return riskRank(a) <= riskRank(b) ? a : b;
+}
+
+function stricterFailMode(a: AgentFailMode | undefined, b: AgentFailMode | undefined): AgentFailMode | undefined {
+  if (a === undefined) return b;
+  if (b === undefined) return a;
+  return FAIL_MODE_STRICTNESS[a] >= FAIL_MODE_STRICTNESS[b] ? a : b;
+}
+
+function strictestRisk(a: Policy | undefined, b: Policy | undefined): Policy | undefined {
+  if (!a) return b;
+  if (!b) return a;
+  const merged: Policy = { ...a };
+  for (const level of RISK_LEVELS) {
+    const left = a[level];
+    const right = b[level];
+    if (left === undefined) {
+      if (right !== undefined) merged[level] = right;
+      continue;
+    }
+    if (right === undefined) continue;
+    merged[level] = POLICY_ACTION_STRICTNESS[left] >= POLICY_ACTION_STRICTNESS[right] ? left : right;
+  }
+  return merged;
+}
+
+function intersectLists<T extends string>(a: readonly T[] | undefined, b: readonly T[] | undefined): T[] | undefined {
+  if (!a) return b ? [...b] : undefined;
+  if (!b) return [...a];
+  const right = new Set(b.map((v) => v.trim().toLowerCase()));
+  return a.filter((v) => right.has(v.trim().toLowerCase()));
+}
+
+function unionLists<T extends string>(a: readonly T[] | undefined, b: readonly T[] | undefined): T[] | undefined {
+  if (!a && !b) return undefined;
+  const seen = new Set<string>();
+  const out: T[] = [];
+  for (const v of [...(a ?? []), ...(b ?? [])]) {
+    const key = v.trim().toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(v);
+  }
+  return out;
+}
+
+function concatWindows<T extends { label: string }>(
+  a: readonly T[] | undefined, b: readonly T[] | undefined,
+): T[] | undefined {
+  if (!a && !b) return undefined;
+  // Every window applies, so more windows is strictly tighter. Labels are
+  // disambiguated rather than deduplicated: two windows sharing a label are
+  // two different limits, and collapsing them would drop one.
+  const out = [...(a ?? [])];
+  for (const window of b ?? []) {
+    out.push(out.some((existing) => existing.label === window.label)
+      ? { ...window, label: `${window.label} (narrowed)` }
+      : window);
+  }
+  return out;
+}
+
+/** A stable object shape for hashing, with keys in a fixed order. */
+function canonicalAction(action: AgentAction): Record<string, unknown> {
+  return {
+    agentId: action.agentId, chain: action.chain, type: action.type, from: action.from,
+    to: action.to ?? null, token: action.token ?? null, value: action.value ?? null,
+    valueUsd: action.valueUsd ?? null, data: action.data ?? null, raw: action.raw ?? null,
+    origin: action.origin ?? null, approvalAmount: action.approvalAmount ?? null,
+  };
+}
+
+/**
+ * FNV-1a over canonical JSON.
+ *
+ * A change detector, not a commitment. It answers "were these two decisions
+ * made under the same rules" without a dependency and without a claim it
+ * cannot support; anyone needing tamper evidence should sign the record.
+ */
+export function fingerprint(value: unknown): string {
+  const json = canonicalJson(value);
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < json.length; i += 1) {
+    hash ^= json.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+}
+
+let decisionCounter = 0;
+
+/** `crypto.randomUUID` where it exists; a monotonic fallback everywhere else. */
+export function newDecisionId(): string {
+  const webCrypto = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
+  if (typeof webCrypto?.randomUUID === 'function') return `ad_${webCrypto.randomUUID()}`;
+  decisionCounter += 1;
+  return `ad_${Date.now().toString(36)}_${decisionCounter.toString(36)}`;
+}