@decentrys/agent 0.1.0

package/dist/policy.js

@@ -0,0 +1,845 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AGENT_RISK_POLICY = void 0;
+exports.sealPolicy = sealPolicy;
+exports.narrowPolicy = narrowPolicy;
+exports.evaluatePolicy = evaluatePolicy;
+exports.isUnlimitedAllowance = isUnlimitedAllowance;
+exports.describeDuration = describeDuration;
+exports.fingerprint = fingerprint;
+exports.newDecisionId = newDecisionId;
+const protect_1 = require("@decentrys/protect");
+const model_1 = require("./model");
+// ---------------------------------------------------------------------------
+// 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.
+ */
+exports.DEFAULT_AGENT_RISK_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 = {
+    allow: 0, inform: 1, warn: 2, warn_strong: 3, require_confirmation: 4, block: 5,
+};
+const FAIL_MODE_STRICTNESS = { 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 = Symbol('decentrys.agent.sealedPolicy');
+function sealPolicy(policy) {
+    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 = [];
+    const effectiveRisk = { ...exports.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,
+        policy: cloned,
+        fingerprint: fingerprint(cloned),
+        warnings,
+    });
+}
+/**
+ * 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.
+ */
+function narrowPolicy(base, restriction) {
+    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),
+    });
+}
+/**
+ * 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.
+ */
+function evaluatePolicy(input) {
+    const now = input.now ?? new Date();
+    const nowMs = now.getTime();
+    const { action } = input;
+    const policy = input.policy.policy;
+    const evaluations = [];
+    // --- 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 = { ...exports.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: model_1.AGENT_MODEL_VERSION,
+        decidedAt: now.toISOString(),
+    };
+}
+function verdictFrom(evaluations) {
+    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, allowed, denied) {
+    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, label, value, allowed) {
+    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 = ['contract_call', 'approve', 'swap', 'bridge', 'stake', 'unstake'];
+function evaluateCounterparty(action, policy) {
+    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, policy) {
+    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, allowUnlimited) {
+    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. */
+function isUnlimitedAllowance(amount) {
+    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, cap) {
+    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, windows, usage, nowMs) {
+    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 = [];
+    const lines = [];
+    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, windows, usage, nowMs) {
+    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 = [];
+    const lines = [];
+    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, unavailable, failMode) {
+    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 = 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',
+    };
+}
+function evaluateRisk(assessment, risk, maxRiskLevel) {
+    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 = (0, protect_1.applyPolicy)(assessment, risk);
+    const outcome = 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, policy, assessment) {
+    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 = [];
+    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) {
+    return protect_1.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, list) {
+    const needle = value.trim().toLowerCase();
+    return list.some((entry) => entry.trim().toLowerCase() === needle);
+}
+function describeSpendWindow(window) {
+    return `$${window.maxValueUsd.toLocaleString('en-US')} per ${describeDuration(window.windowMs)} (${window.label})`;
+}
+function describeDuration(ms) {
+    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, unit) {
+    return count === 1 ? unit : `${count} ${unit}s`;
+}
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
+function hasAnyLimit(policy) {
+    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) {
+    const cloned = {};
+    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(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    for (const key of Object.getOwnPropertyNames(value)) {
+        deepFreeze(value[key]);
+    }
+    return Object.freeze(value);
+}
+function minDefined(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return Math.min(a, b);
+}
+function lowerRiskLevel(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return riskRank(a) <= riskRank(b) ? a : b;
+}
+function stricterFailMode(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return FAIL_MODE_STRICTNESS[a] >= FAIL_MODE_STRICTNESS[b] ? a : b;
+}
+function strictestRisk(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const merged = { ...a };
+    for (const level of protect_1.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(a, b) {
+    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(a, b) {
+    if (!a && !b)
+        return undefined;
+    const seen = new Set();
+    const out = [];
+    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(a, b) {
+    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) {
+    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.
+ */
+function fingerprint(value) {
+    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) {
+    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)
+        .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. */
+function newDecisionId() {
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.randomUUID === 'function')
+        return `ad_${webCrypto.randomUUID()}`;
+    decisionCounter += 1;
+    return `ad_${Date.now().toString(36)}_${decisionCounter.toString(36)}`;
+}
+//# sourceMappingURL=policy.js.map