@crediolabs/policy-synth 1.2.0 → 1.3.0

package/dist/install/authority-overlap.d.ts

@@ -24,6 +24,24 @@ export type ContextType = {
  *  - `unpoliced`: no policy at all. Whatever its context type allows, its
  *    signers may do without constraint. */
 export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced';
+/** An OZ `spending_limit`'s parameters. `amount` is in the token's smallest
+ *  unit; the period is a LEDGER count, not seconds. */
+export interface SpendCap {
+    amount: string;
+    periodLedgers: number;
+}
+/** The policy contracts this tool can recognise by address. Supplying them lets
+ *  the scan reason about a neighbour's SPEND CAP instead of treating any
+ *  non-interpreter policy as opaque.
+ *
+ *  Recognition is what licenses the strong conclusion. "This rule has no spend
+ *  cap" is only sound when every policy on it is accounted for; a single
+ *  unrecognised address could be somebody else's cap, so such a rule stays
+ *  advisory. */
+export interface KnownPolicies {
+    interpreter: string;
+    spendingLimit: string;
+}
 export interface ObservedRule {
     id: number;
     contextType: ContextType;
@@ -33,6 +51,11 @@ export interface ObservedRule {
     /** Decoded predicate. Present only when the rule is policed by OUR
      *  interpreter and the stored document was readable. */
     predicate?: PredicateNode;
+    /** The attached spend cap's parameters, when the reader could read them from
+     *  the policy's own storage. Attachment is decided from `policyAddresses`, so
+     *  this being absent does NOT mean the rule is uncapped - only that the
+     *  numbers are unknown. */
+    spendCap?: SpendCap;
 }
 export interface IntendedInstall {
     /** Rule the predicate is being installed onto. A re-install onto the same
@@ -42,9 +65,15 @@ export interface IntendedInstall {
     contextType: ContextType;
     signers: SignerDraft[];
     predicate: PredicateNode;
+    /** The rolling cap being installed alongside the predicate, when one is.
+     *  Its presence is what makes a neighbour's LACK of a cap a finding: without
+     *  it there is no total for a neighbour to route around. */
+    spendCap?: SpendCap;
 }
 export type OverlapSeverity = 
-/** A neighbouring rule imposes no constraint at all on the shared calls. */
+/** A neighbouring rule imposes no constraint at all on the shared calls, or
+ *  imposes no ROLLING TOTAL on calls the new rule caps. Either way the new
+ *  rule's bound does not hold for a signer who can name this one. */
 'bypass'
 /** A neighbouring policy exists but what it permits cannot be read. */
  | 'unknown'
@@ -60,6 +89,14 @@ export interface AuthorityOverlap {
     sharedSigners: SignerDraft[];
     /** The selectors both rules can serve. Non-empty by construction. */
     sharedSelectors: Selector[];
+    /** This neighbour's own rolling cap, when it has one this tool could read.
+     *  A spend cap is keyed by (account, RULE id), so two capped rules do not
+     *  share a budget - a signer on both may spend the SUM. */
+    spendCap?: SpendCap;
+    /** True when the new rule installs a rolling total and this neighbour serves
+     *  some of the same calls WITHOUT one, which voids the total rather than
+     *  merely widening it. Only set when every policy here was recognised. */
+    capBypass?: true;
     advice: string;
 }
 /** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
@@ -98,4 +135,7 @@ export declare function effectiveSelectors(rule: ObservedRule): Selector[];
 export declare function findAuthorityOverlaps(args: {
     intended: IntendedInstall;
     existing: ObservedRule[];
+    /** Omit to skip spend-cap reasoning entirely: every neighbour is then judged
+     *  exactly as before, on its policies' presence rather than their meaning. */
+    knownPolicies?: KnownPolicies;
 }): AuthorityOverlap[];

package/dist/install/authority-overlap.js

@@ -191,14 +191,38 @@ function classifyRule(rule) {
         return 'unpoliced';
     return rule.predicate ? 'interpreter' : 'foreign';
 }
-function adviceFor(cls, ruleId) {
+/** Is the OZ spend cap attached to this rule? Decided by ADDRESS, so it holds
+ *  whether or not the cap's parameters could be read. */
+function hasSpendCap(rule, known) {
+    return rule.policyAddresses.includes(known.spendingLimit);
+}
+/** Every policy on the rule is one this tool knows the semantics of, so
+ *  "there is no spend cap here" is an observation rather than an assumption. */
+function allPoliciesRecognised(rule, known) {
+    return rule.policyAddresses.every((addr) => addr === known.interpreter || addr === known.spendingLimit);
+}
+function capBypassAdvice(ruleId) {
+    return `the rolling total you are installing will not bind: rule ${ruleId} serves some of the same calls for a shared signer and carries NO spend cap, so that signer spends through it without one. A cap is stored per RULE, never per key. Remove the shared signer from rule ${ruleId}, put an equivalent cap on it, or narrow it so it no longer serves these calls.`;
+}
+/** How a signer's spend adds up across two capped rules. Same period or not,
+ *  the budgets are separate; saying so with the numbers beats saying it in the
+ *  abstract, which is what the caller has to reason about. */
+function combinedCapNote(mine, theirs) {
+    if (mine.periodLedgers === theirs.periodLedgers) {
+        const total = (BigInt(mine.amount) + BigInt(theirs.amount)).toString();
+        return ` Its cap is ${theirs.amount} over the same ${theirs.periodLedgers}-ledger period as yours, and the two budgets are separate, so a shared signer may spend ${total} in total.`;
+    }
+    return ` Its cap is ${theirs.amount} over ${theirs.periodLedgers} ledgers against your ${mine.amount} over ${mine.periodLedgers}; the periods differ, so the two budgets neither share nor cancel and a shared signer draws on both.`;
+}
+function adviceFor(cls, ruleId, theirCap, myCap) {
+    const capNote = theirCap !== undefined && myCap !== undefined ? combinedCapNote(myCap, theirCap) : '';
     switch (cls) {
         case 'unpoliced':
             return `rule ${ruleId} has no policy attached, so a shared signer may make these calls with no constraint at all - the predicate you are installing will never run for them. Remove the shared signer from rule ${ruleId}, or attach a policy to it.`;
         case 'foreign':
-            return `rule ${ruleId} is policed by a contract this tool cannot decode, so its authority over these calls is unknown. Review it by hand before relying on the new rule.`;
+            return `rule ${ruleId} is policed by a contract this tool cannot decode, so its authority over these calls is unknown. Review it by hand before relying on the new rule.${capNote}`;
         case 'interpreter':
-            return `a shared signer may name rule ${ruleId} instead, so the new rule will not restrict these calls. To TIGHTEN, edit rule ${ruleId} itself rather than adding a second rule. To ADD a separate capability, keep both and expect neither to constrain the other.`;
+            return `a shared signer may name rule ${ruleId} instead, so the new rule will not restrict these calls. To TIGHTEN, edit rule ${ruleId} itself rather than adding a second rule. To ADD a separate capability, keep both and expect neither to constrain the other.${capNote}`;
     }
 }
 /**
@@ -222,17 +246,42 @@ export function findAuthorityOverlaps(args) {
         if (sharedSelectors.length === 0)
             continue;
         const ruleClass = classifyRule(rule);
+        // A rolling total is keyed by (account, rule id), so it constrains THIS
+        // rule and nothing else. If the new rule carries one and a neighbour serves
+        // the same calls without one, the signer names the neighbour and spends
+        // without limit - the total was never a bound on the key. Proven on testnet
+        // in `docs/audit/evidence/oz-two-rule-blend-cap.log`, where an uncapped
+        // sibling rule passed the very amount the capped rule refused.
+        //
+        // Sound only when every policy on the neighbour was recognised. One
+        // unrecognised address could be another spend cap, and refusing an install
+        // over a policy we cannot read would be a guess, not a proof.
+        // An unpoliced neighbour is excluded deliberately. It has no policies, so
+        // it passes the "everything recognised, no cap" test vacuously - but the
+        // finding there is not that a total leaks, it is that NOTHING constrains
+        // those calls. Reporting the narrower cause would send the reader looking
+        // for a spend cap when the rule needs a policy at all.
+        const capBypass = ruleClass !== 'unpoliced' &&
+            args.knownPolicies !== undefined &&
+            args.intended.spendCap !== undefined &&
+            allPoliciesRecognised(rule, args.knownPolicies) &&
+            !hasSpendCap(rule, args.knownPolicies);
+        const severity = ruleClass === 'unpoliced' || capBypass
+            ? 'bypass'
+            : ruleClass === 'foreign'
+                ? 'unknown'
+                : 'not-restricting';
         out.push({
             ruleId: rule.id,
             ruleClass,
-            severity: ruleClass === 'unpoliced'
-                ? 'bypass'
-                : ruleClass === 'foreign'
-                    ? 'unknown'
-                    : 'not-restricting',
+            severity,
             sharedSigners: shared,
             sharedSelectors,
-            advice: adviceFor(ruleClass, rule.id),
+            ...(rule.spendCap !== undefined ? { spendCap: rule.spendCap } : {}),
+            ...(capBypass ? { capBypass: true } : {}),
+            advice: capBypass
+                ? capBypassAdvice(rule.id)
+                : adviceFor(ruleClass, rule.id, rule.spendCap, args.intended.spendCap),
         });
     }
     return out;

package/dist/install/read-account-rules.d.ts

@@ -1,6 +1,6 @@
 import { rpc, xdr } from '@stellar/stellar-sdk';
 import type { SignerDraft } from '../types.ts';
-import type { ContextType, ObservedRule } from './authority-overlap.ts';
+import type { ContextType, ObservedRule, SpendCap } from './authority-overlap.ts';
 /** `storage.rs` - the third element of the persistent doc key tuple. */
 export declare const K_DOC = 1;
 /** Persistent-storage key for a rule's stored document:
@@ -19,6 +19,20 @@ export declare function decodeSigner(v: xdr.ScVal): SignerDraft | undefined;
 export declare function decodeContextRule(v: xdr.ScVal): ObservedRule | undefined;
 /** The interpreter's `StoredDoc { predicate_bytes }`. */
 export declare function decodeStoredPredicateBytes(v: xdr.ScVal): Buffer | undefined;
+/** Persistent-storage key for a rule's spend-cap data:
+ *  `SpendingLimitStorageKey::AccountContext(account, rule_id)`, which the host
+ *  encodes as an enum variant - the symbol first, then the payload. */
+export declare function spendCapKeyScVal(smartAccount: string, ruleId: number): xdr.ScVal;
+/** Ledger key for the OZ spend cap's own persistent entry. The policy exposes
+ *  `get_spending_limit_data`, but that PANICS when nothing is installed, and a
+ *  panic is indistinguishable from an RPC fault at the call site. Reading the
+ *  entry lets "no cap here" come back as an absence instead. */
+export declare function spendCapLedgerKey(spendingLimit: string, smartAccount: string, ruleId: number): xdr.LedgerKey;
+/** `SpendingLimitData`, of which only the two installed parameters matter here.
+ *  The running total and the history are deliberately ignored: they say what
+ *  has been spent so far, which changes every call, while the scan is about
+ *  what the rule PERMITS. */
+export declare function decodeSpendCap(v: xdr.ScVal): SpendCap | undefined;
 /** The three reads the scan needs. Kept as an interface so the collection
  *  below is testable without a network. */
 export interface AccountRuleReader {
@@ -29,6 +43,10 @@ export interface AccountRuleReader {
     /** The interpreter's persistent `StoredDoc` entry, read as a ledger entry.
      *  Undefined when no document is stored for that rule. */
     getStoredDoc(interpreter: string, smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
+    /** The OZ spend cap's persistent entry for this rule, read as a ledger entry.
+     *  Optional so an existing reader keeps working: without it the scan simply
+     *  reports no cap parameters, which is the same as it behaved before. */
+    getSpendCapData?(spendingLimit: string, smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
 }
 /** How far the id scan will probe before giving up. OZ imposes no per-account
  *  rule cap, so there is no exact bound to derive; this one is far above any
@@ -64,6 +82,10 @@ export declare function collectObservedRules(args: {
     reader: AccountRuleReader;
     smartAccount: string;
     interpreterAddress: string;
+    /** The pinned OZ spend cap. Supplying it fills in the PARAMETERS of a
+     *  neighbour's cap; whether one is attached at all is decided from the
+     *  rule's policy addresses and does not depend on this read succeeding. */
+    spendingLimitAddress?: string;
     maxRuleIdScan?: number;
 }): Promise<CollectedRules>;
 /**

package/dist/install/read-account-rules.js

@@ -19,7 +19,7 @@
 //!
 //! The decoders are pure so they can be tested without a network; the caller
 //! supplies raw `ScVal`s.
-import { Account, Address, BASE_FEE, Contract, Keypair, rpc, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
+import { Account, Address, BASE_FEE, Contract, Keypair, rpc, scValToNative, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
 import { decodePredicate } from "../predicate/decode.js";
 /** `storage.rs` - the third element of the persistent doc key tuple. */
 export const K_DOC = 1;
@@ -147,6 +147,43 @@ export function decodeStoredPredicateBytes(v) {
         return undefined;
     return field.bytes();
 }
+/** Persistent-storage key for a rule's spend-cap data:
+ *  `SpendingLimitStorageKey::AccountContext(account, rule_id)`, which the host
+ *  encodes as an enum variant - the symbol first, then the payload. */
+export function spendCapKeyScVal(smartAccount, ruleId) {
+    return xdr.ScVal.scvVec([
+        xdr.ScVal.scvSymbol('AccountContext'),
+        new Address(smartAccount).toScVal(),
+        xdr.ScVal.scvU32(ruleId),
+    ]);
+}
+/** Ledger key for the OZ spend cap's own persistent entry. The policy exposes
+ *  `get_spending_limit_data`, but that PANICS when nothing is installed, and a
+ *  panic is indistinguishable from an RPC fault at the call site. Reading the
+ *  entry lets "no cap here" come back as an absence instead. */
+export function spendCapLedgerKey(spendingLimit, smartAccount, ruleId) {
+    return xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
+        contract: new Address(spendingLimit).toScAddress(),
+        key: spendCapKeyScVal(smartAccount, ruleId),
+        durability: xdr.ContractDataDurability.persistent(),
+    }));
+}
+/** `SpendingLimitData`, of which only the two installed parameters matter here.
+ *  The running total and the history are deliberately ignored: they say what
+ *  has been spent so far, which changes every call, while the scan is about
+ *  what the rule PERMITS. */
+export function decodeSpendCap(v) {
+    const periodLedgers = u32Of(mapField(v, 'period_ledgers'));
+    const limit = mapField(v, 'spending_limit');
+    if (periodLedgers === undefined || !limit)
+        return undefined;
+    if (limit.switch() !== xdr.ScValType.scvI128())
+        return undefined;
+    const amount = scValToNative(limit);
+    if (typeof amount !== 'bigint')
+        return undefined;
+    return { amount: amount.toString(), periodLedgers };
+}
 /** How far the id scan will probe before giving up. OZ imposes no per-account
  *  rule cap, so there is no exact bound to derive; this one is far above any
  *  realistic account and keeps a malformed `Count` from spinning forever. */
@@ -195,6 +232,16 @@ export async function collectObservedRules(args) {
                 unreadablePredicateRuleIds.push(rule.id);
             }
         }
+        const spendCapAddress = args.spendingLimitAddress;
+        if (spendCapAddress !== undefined && rule.policyAddresses.includes(spendCapAddress)) {
+            const data = await args.reader.getSpendCapData?.(spendCapAddress, args.smartAccount, rule.id);
+            const cap = data ? decodeSpendCap(data) : undefined;
+            // An unreadable cap is left absent rather than guessed at. The rule still
+            // counts as capped, because attachment came from its policy addresses,
+            // so failing this read weakens the REPORT and never the refusal.
+            if (cap)
+                rule.spendCap = cap;
+        }
         rules.push(rule);
     }
     return { rules, unreadablePredicateRuleIds, incomplete: rules.length < count };
@@ -237,5 +284,13 @@ export function accountRuleReaderFromServer(server, networkPassphrase) {
                 return undefined;
             return entry.contractData().val();
         },
+        async getSpendCapData(spendingLimit, smartAccount, ruleId) {
+            const key = spendCapLedgerKey(spendingLimit, smartAccount, ruleId);
+            const res = await server.getLedgerEntries(key);
+            const entry = res.entries?.[0]?.val;
+            if (!entry || entry.switch() !== xdr.LedgerEntryType.contractData())
+                return undefined;
+            return entry.contractData().val();
+        },
     };
 }

package/dist/run/index.d.ts

@@ -41,9 +41,12 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
 /** The refusal message for an install the cross-rule scan proves cannot bind,
  *  or `undefined` when the install may proceed.
  *
- *  Only `bypass` refuses. That class means the neighbouring rule carries NO
- *  policy, so a shared signer names it and the new predicate never runs - a
- *  proof, from data already in hand, that the rule constrains nothing.
+ *  Only `bypass` refuses, and it covers two proofs. Either the neighbouring
+ *  rule carries NO policy, so a shared signer names it and the new predicate
+ *  never runs; or the install carries a rolling total and a fully recognised
+ *  neighbour serves the same calls without one, so the total is not a bound on
+ *  the key. Both are proofs from data already in hand.
+ *
  *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
  *  advisory: it may well be tighter, and refusing on "cannot decode" would
  *  block installs on a guess. A `null` scan is NOT CHECKED, which is not

package/dist/run/index.js

@@ -132,9 +132,12 @@ export async function runSynthesizePolicy(raw) {
 /** The refusal message for an install the cross-rule scan proves cannot bind,
  *  or `undefined` when the install may proceed.
  *
- *  Only `bypass` refuses. That class means the neighbouring rule carries NO
- *  policy, so a shared signer names it and the new predicate never runs - a
- *  proof, from data already in hand, that the rule constrains nothing.
+ *  Only `bypass` refuses, and it covers two proofs. Either the neighbouring
+ *  rule carries NO policy, so a shared signer names it and the new predicate
+ *  never runs; or the install carries a rolling total and a fully recognised
+ *  neighbour serves the same calls without one, so the total is not a bound on
+ *  the key. Both are proofs from data already in hand.
+ *
  *  `unknown` (a neighbour policed by a contract this tool cannot decode) stays
  *  advisory: it may well be tighter, and refusing on "cannot decode" would
  *  block installs on a guess. A `null` scan is NOT CHECKED, which is not
@@ -149,7 +152,12 @@ export function authorityBypassRefusal(scan, allowAuthorityOverlap) {
     if (proven.length === 0)
         return undefined;
     const ids = proven.map((o) => o.ruleId).join(', ');
-    return `install_policy: ${proven[0]?.advice ?? ''} This rule would install cleanly and constrain nothing, so it is refused (rule ${ids}); remove the shared signer from that rule, attach a policy to it, or set \`allowAuthorityOverlap: true\` to install anyway.`;
+    // A cap bypass leaves the predicate working, so "constrains nothing" would
+    // overstate it and send the caller looking for the wrong defect.
+    const consequence = proven.every((o) => o.capBypass === true)
+        ? 'This rule would install cleanly and its rolling total would not hold'
+        : 'This rule would install cleanly and constrain nothing';
+    return `install_policy: ${proven[0]?.advice ?? ''} ${consequence}, so it is refused (rule ${ids}); set \`allowAuthorityOverlap: true\` to install anyway.`;
 }
 export async function runInstallPolicy(raw) {
     const parsed = InstallPolicyInputSchema.safeParse(raw);
@@ -350,8 +358,24 @@ export async function runInstallPolicy(raw) {
                     contextType: rule.contextRuleType,
                     signers: rule.signers,
                     predicate: decodePredicate(encodedPredicate),
+                    ...(input.spendingLimit !== undefined
+                        ? {
+                            spendCap: {
+                                amount: input.spendingLimit.amount,
+                                periodLedgers: input.spendingLimit.periodLedgers,
+                            },
+                        }
+                        : {}),
                 },
                 existing: observed,
+                // Both addresses are pinned, so a neighbour's policies can be
+                // named rather than merely counted - which is what lets the scan
+                // say a rule has no spend cap instead of that it has something
+                // unreadable.
+                knownPolicies: {
+                    interpreter: expectedInterpreter,
+                    spendingLimit: PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
+                },
             });
         // A `bypass` overlap is not a warning, it is a proof that this rule cannot
         // bind the key it names: the neighbour carries NO policy, so the signer
@@ -776,6 +800,7 @@ async function resolveExistingRules(input, network, interpreterAddress) {
             reader: accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network]),
             smartAccount: input.smartAccount,
             interpreterAddress,
+            spendingLimitAddress: PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
         });
         if (collected.incomplete)
             return null;

package/dist/run/schemas.d.ts

@@ -2554,6 +2554,19 @@ export declare const ObservedRuleSchema: z.ZodObject<{
     }>]>, "many">;
     policyAddresses: z.ZodArray<z.ZodString, "many">;
     predicate: z.ZodOptional<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+    /** Parameters of an OZ spend cap already on this rule. Reporting only:
+     *  whether a neighbour is capped is read from `policyAddresses`, so omitting
+     *  this never turns a capped rule into an uncapped one. */
+    spendCap: z.ZodOptional<z.ZodObject<{
+        amount: z.ZodString;
+        periodLedgers: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        amount: string;
+        periodLedgers: number;
+    }, {
+        amount: string;
+        periodLedgers: number;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     signers: ({
         address: string;
@@ -2574,6 +2587,10 @@ export declare const ObservedRuleSchema: z.ZodObject<{
         kind: "create_contract";
         wasmHash: string;
     };
+    spendCap?: {
+        amount: string;
+        periodLedgers: number;
+    } | undefined;
     predicate?: unknown;
 }, {
     signers: ({
@@ -2595,6 +2612,10 @@ export declare const ObservedRuleSchema: z.ZodObject<{
         kind: "create_contract";
         wasmHash: string;
     };
+    spendCap?: {
+        amount: string;
+        periodLedgers: number;
+    } | undefined;
     predicate?: unknown;
 }>;
 /** Pinned interpreter address (testnet).
@@ -2805,6 +2826,19 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         }>]>, "many">;
         policyAddresses: z.ZodArray<z.ZodString, "many">;
         predicate: z.ZodOptional<z.ZodType<unknown, z.ZodTypeDef, unknown>>;
+        /** Parameters of an OZ spend cap already on this rule. Reporting only:
+         *  whether a neighbour is capped is read from `policyAddresses`, so omitting
+         *  this never turns a capped rule into an uncapped one. */
+        spendCap: z.ZodOptional<z.ZodObject<{
+            amount: z.ZodString;
+            periodLedgers: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            amount: string;
+            periodLedgers: number;
+        }, {
+            amount: string;
+            periodLedgers: number;
+        }>>;
     }, "strip", z.ZodTypeAny, {
         signers: ({
             address: string;
@@ -2825,6 +2859,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }, {
         signers: ({
@@ -2846,6 +2884,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }>, "many">>;
     /** The smart account contract address (C...) that will receive the rule. */
@@ -3471,6 +3513,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectOutputType<{
@@ -3608,6 +3654,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectInputType<{
@@ -3745,6 +3795,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectOutputType<{
@@ -3882,6 +3936,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectInputType<{
@@ -4019,6 +4077,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectOutputType<{
@@ -4156,6 +4218,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
             kind: "create_contract";
             wasmHash: string;
         };
+        spendCap?: {
+            amount: string;
+            periodLedgers: number;
+        } | undefined;
         predicate?: unknown;
     }[] | undefined;
     rule?: z.objectInputType<{

package/dist/run/schemas.js

@@ -338,6 +338,15 @@ export const ObservedRuleSchema = z.object({
     signers: z.array(SignerDraftSchema),
     policyAddresses: z.array(z.string()),
     predicate: PredicateNodeSchema.optional(),
+    /** Parameters of an OZ spend cap already on this rule. Reporting only:
+     *  whether a neighbour is capped is read from `policyAddresses`, so omitting
+     *  this never turns a capped rule into an uncapped one. */
+    spendCap: z
+        .object({
+        amount: z.string().regex(/^[0-9]+$/),
+        periodLedgers: z.number().int().positive().max(U32_MAX),
+    })
+        .optional(),
 });
 const ContextRuleDraftSchema = z
     .object({

package/dist-cjs/install/authority-overlap.d.ts

@@ -24,6 +24,24 @@ export type ContextType = {
  *  - `unpoliced`: no policy at all. Whatever its context type allows, its
  *    signers may do without constraint. */
 export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced';
+/** An OZ `spending_limit`'s parameters. `amount` is in the token's smallest
+ *  unit; the period is a LEDGER count, not seconds. */
+export interface SpendCap {
+    amount: string;
+    periodLedgers: number;
+}
+/** The policy contracts this tool can recognise by address. Supplying them lets
+ *  the scan reason about a neighbour's SPEND CAP instead of treating any
+ *  non-interpreter policy as opaque.
+ *
+ *  Recognition is what licenses the strong conclusion. "This rule has no spend
+ *  cap" is only sound when every policy on it is accounted for; a single
+ *  unrecognised address could be somebody else's cap, so such a rule stays
+ *  advisory. */
+export interface KnownPolicies {
+    interpreter: string;
+    spendingLimit: string;
+}
 export interface ObservedRule {
     id: number;
     contextType: ContextType;
@@ -33,6 +51,11 @@ export interface ObservedRule {
     /** Decoded predicate. Present only when the rule is policed by OUR
      *  interpreter and the stored document was readable. */
     predicate?: PredicateNode;
+    /** The attached spend cap's parameters, when the reader could read them from
+     *  the policy's own storage. Attachment is decided from `policyAddresses`, so
+     *  this being absent does NOT mean the rule is uncapped - only that the
+     *  numbers are unknown. */
+    spendCap?: SpendCap;
 }
 export interface IntendedInstall {
     /** Rule the predicate is being installed onto. A re-install onto the same
@@ -42,9 +65,15 @@ export interface IntendedInstall {
     contextType: ContextType;
     signers: SignerDraft[];
     predicate: PredicateNode;
+    /** The rolling cap being installed alongside the predicate, when one is.
+     *  Its presence is what makes a neighbour's LACK of a cap a finding: without
+     *  it there is no total for a neighbour to route around. */
+    spendCap?: SpendCap;
 }
 export type OverlapSeverity = 
-/** A neighbouring rule imposes no constraint at all on the shared calls. */
+/** A neighbouring rule imposes no constraint at all on the shared calls, or
+ *  imposes no ROLLING TOTAL on calls the new rule caps. Either way the new
+ *  rule's bound does not hold for a signer who can name this one. */
 'bypass'
 /** A neighbouring policy exists but what it permits cannot be read. */
  | 'unknown'
@@ -60,6 +89,14 @@ export interface AuthorityOverlap {
     sharedSigners: SignerDraft[];
     /** The selectors both rules can serve. Non-empty by construction. */
     sharedSelectors: Selector[];
+    /** This neighbour's own rolling cap, when it has one this tool could read.
+     *  A spend cap is keyed by (account, RULE id), so two capped rules do not
+     *  share a budget - a signer on both may spend the SUM. */
+    spendCap?: SpendCap;
+    /** True when the new rule installs a rolling total and this neighbour serves
+     *  some of the same calls WITHOUT one, which voids the total rather than
+     *  merely widening it. Only set when every policy here was recognised. */
+    capBypass?: true;
     advice: string;
 }
 /** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
@@ -98,4 +135,7 @@ export declare function effectiveSelectors(rule: ObservedRule): Selector[];
 export declare function findAuthorityOverlaps(args: {
     intended: IntendedInstall;
     existing: ObservedRule[];
+    /** Omit to skip spend-cap reasoning entirely: every neighbour is then judged
+     *  exactly as before, on its policies' presence rather than their meaning. */
+    knownPolicies?: KnownPolicies;
 }): AuthorityOverlap[];