@crediolabs/policy-synth 1.1.1 → 1.3.0

package/dist-cjs/run/index.js

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolErrorSchema = exports.TESTNET_RPC_URL = exports.SynthesizePolicyInputSchema = exports.RPC_URL_BY_NETWORK = exports.RevokePolicyInputSchema = exports.RecordTransactionInputSchema = exports.RecordedTransactionSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.PINNED_OZ_POLICY_WASM_SHA256 = exports.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.NetworkSchema = exports.MAINNET_RPC_URL = exports.InterpreterOptionsSchema = exports.InstallPolicyInputSchema = exports.GetInterpreterInfoInputSchema = exports.DeclarePolicyInputSchema = exports.ComposeUserResponsesSchema = void 0;
 exports.runRecordTransaction = runRecordTransaction;
 exports.runSynthesizePolicy = runSynthesizePolicy;
+exports.authorityBypassRefusal = authorityBypassRefusal;
 exports.runInstallPolicy = runInstallPolicy;
 exports.runRevokePolicy = runRevokePolicy;
 exports.contextTypeForPredicate = contextTypeForPredicate;
@@ -30,6 +31,7 @@ exports.runVerifyPolicy = runVerifyPolicy;
 exports.runGetInterpreterInfo = runGetInterpreterInfo;
 exports.caughtError = caughtError;
 const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const adapter_ts_1 = require("../adapters/interpreter/adapter.js");
 const index_ts_1 = require("../index.js");
@@ -164,6 +166,36 @@ async function runSynthesizePolicy(raw) {
         return toolFailure('synthesize_policy', e);
     }
 }
+/** The refusal message for an install the cross-rule scan proves cannot bind,
+ *  or `undefined` when the install may proceed.
+ *
+ *  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
+ *  evidence of a bypass and must not refuse on its own.
+ *
+ *  Separated from the tool body so the decision can be tested without a
+ *  network: the install it guards cannot be built without one. */
+function authorityBypassRefusal(scan, allowAuthorityOverlap) {
+    if (scan === null || allowAuthorityOverlap === true)
+        return undefined;
+    const proven = scan.filter((o) => o.severity === 'bypass');
+    if (proven.length === 0)
+        return undefined;
+    const ids = proven.map((o) => o.ruleId).join(', ');
+    // 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.`;
+}
 async function runInstallPolicy(raw) {
     const parsed = schemas_ts_1.InstallPolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
@@ -363,10 +395,71 @@ async function runInstallPolicy(raw) {
                     contextType: rule.contextRuleType,
                     signers: rule.signers,
                     predicate: (0, decode_ts_1.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: schemas_ts_1.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
+                },
             });
-        return { ok: true, data: { ...result, authorityScan } };
+        // 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
+        // names that rule instead and the predicate never runs. Returning `ok` with
+        // the finding buried in `authorityScan` puts the whole protection on the
+        // caller reading a field, and the caller here is usually an agent that
+        // checks whether the call succeeded. Refuse, and let the caller opt in.
+        //
+        // Only the provable class. `unknown` - a neighbour whose policy this tool
+        // cannot decode - stays advisory: it may well be tighter, and refusing on
+        // "cannot decode" would block installs on a guess.
+        const bypassRefusal = authorityBypassRefusal(authorityScan, input.allowAuthorityOverlap);
+        if (bypassRefusal !== undefined) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: bypassRefusal,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        // Write the envelope here when asked, so it never travels through the
+        // caller. `writtenTo` is what the caller should hand to a signer.
+        let writtenTo;
+        if (input.outPath !== undefined) {
+            // Write beside the target and rename, which is atomic within a
+            // filesystem. A plain write truncates first, so anything watching the
+            // directory - a signer picking up envelopes is the obvious case - can
+            // read a half-written file and report a malformed TRANSACTION. With a
+            // rename the path either does not exist or holds the whole envelope.
+            const staging = `${input.outPath}.partial`;
+            await (0, promises_1.writeFile)(staging, result.unsignedXdr, 'utf8');
+            const readBack = await (0, promises_1.readFile)(staging, 'utf8');
+            if (readBack !== result.unsignedXdr) {
+                await (0, promises_1.rm)(staging, { force: true });
+                throw new Error(`outPath: wrote ${result.unsignedXdr.length} characters to ${input.outPath} but read back ${readBack.length}; the file was not persisted intact`);
+            }
+            await (0, promises_1.rename)(staging, input.outPath);
+            writtenTo = input.outPath;
+        }
+        return {
+            ok: true,
+            data: { ...result, authorityScan, ...(writtenTo !== undefined ? { writtenTo } : {}) },
+        };
     }
     catch (e) {
         return toolFailure('install_policy', e);
@@ -744,6 +837,7 @@ async function resolveExistingRules(input, network, interpreterAddress) {
             reader: (0, read_account_rules_ts_1.accountRuleReaderFromServer)(server, schemas_ts_1.NETWORK_PASSPHRASES[network]),
             smartAccount: input.smartAccount,
             interpreterAddress,
+            spendingLimitAddress: schemas_ts_1.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
         });
         if (collected.incomplete)
             return null;

package/dist-cjs/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. */
@@ -3366,6 +3408,17 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: z.ZodOptional<z.ZodNumber>;
+    /** Absolute path to write the unsigned envelope to.
+     *
+     *  The envelope runs to several thousand characters, and without this the
+     *  only route onto disk is the CALLER re-emitting it - through a model, a
+     *  shell argument, or both. That transport mangles it: observed in practice
+     *  as a file of the right length whose bytes no longer parse
+     *  ("xdr padding contains non-zero bytes"), and as silent truncation.
+     *  Writing it here takes the caller out of the transport entirely.
+     *
+     *  Opt-in: omitted, nothing is written and behaviour is unchanged. */
+    outPath: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -3411,6 +3464,18 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: z.ZodOptional<z.ZodBoolean>;
+    /** Opt-in to installing a rule that the cross-rule scan proves cannot bind.
+     *
+     *  An OZ account resolves a call against the rule the caller NAMES, so a
+     *  key on several rules gets the MAXIMUM authority over them, never the
+     *  intersection. A key that also sits on a rule with no policy is therefore
+     *  unconstrained: it names that rule and the new predicate never runs.
+     *
+     *  Default-deny, and only for the case the scan can PROVE - an unpoliced
+     *  neighbour sharing signers and selectors. A neighbour carrying a policy
+     *  this tool cannot decode stays advisory, because "cannot decode" is not
+     *  "proved unsafe" and refusing it would block installs on a guess. */
+    allowAuthorityOverlap: z.ZodOptional<z.ZodBoolean>;
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit
@@ -3448,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<{
@@ -3549,9 +3618,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -3583,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<{
@@ -3684,9 +3759,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>, {
@@ -3718,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<{
@@ -3819,9 +3900,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -3853,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<{
@@ -3954,9 +4041,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>, {
@@ -3988,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<{
@@ -4089,9 +4182,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }, {
@@ -4123,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<{
@@ -4224,9 +4323,11 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         validUntilLedger?: number | undefined;
         name?: string | undefined;
     } | undefined;
+    outPath?: string | undefined;
     rpcUrl?: string | undefined;
     allowUnpinnedRpcUrl?: boolean | undefined;
     allowUnboundedAmount?: boolean | undefined;
+    allowAuthorityOverlap?: boolean | undefined;
     allowUnpinnedInterpreter?: boolean | undefined;
     baseFee?: number | undefined;
 }>;

package/dist-cjs/run/schemas.js

@@ -341,6 +341,15 @@ exports.ObservedRuleSchema = zod_1.z.object({
     signers: zod_1.z.array(SignerDraftSchema),
     policyAddresses: zod_1.z.array(zod_1.z.string()),
     predicate: exports.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: zod_1.z
+        .object({
+        amount: zod_1.z.string().regex(/^[0-9]+$/),
+        periodLedgers: zod_1.z.number().int().positive().max(U32_MAX),
+    })
+        .optional(),
 });
 const ContextRuleDraftSchema = zod_1.z
     .object({
@@ -626,6 +635,22 @@ exports.InstallPolicyInputSchema = zod_1.z
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: zod_1.z.number().int().positive().optional(),
+    /** Absolute path to write the unsigned envelope to.
+     *
+     *  The envelope runs to several thousand characters, and without this the
+     *  only route onto disk is the CALLER re-emitting it - through a model, a
+     *  shell argument, or both. That transport mangles it: observed in practice
+     *  as a file of the right length whose bytes no longer parse
+     *  ("xdr padding contains non-zero bytes"), and as silent truncation.
+     *  Writing it here takes the caller out of the transport entirely.
+     *
+     *  Opt-in: omitted, nothing is written and behaviour is unchanged. */
+    outPath: zod_1.z
+        .string()
+        .min(1)
+        .refine((p) => p.startsWith('/'), 'outPath must be an absolute path')
+        .refine((p) => !p.includes('\0'), 'outPath must not contain a null byte')
+        .optional(),
     /** Optional RPC URL override. Defaults to the pinned RPC for the
      *  selected `network` (testnet by default, mainnet when
      *  `network: 'mainnet'`); the override is refused unless
@@ -669,6 +694,18 @@ exports.InstallPolicyInputSchema = zod_1.z
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: zod_1.z.boolean().optional(),
+    /** Opt-in to installing a rule that the cross-rule scan proves cannot bind.
+     *
+     *  An OZ account resolves a call against the rule the caller NAMES, so a
+     *  key on several rules gets the MAXIMUM authority over them, never the
+     *  intersection. A key that also sits on a rule with no policy is therefore
+     *  unconstrained: it names that rule and the new predicate never runs.
+     *
+     *  Default-deny, and only for the case the scan can PROVE - an unpoliced
+     *  neighbour sharing signers and selectors. A neighbour carrying a policy
+     *  this tool cannot decode stays advisory, because "cannot decode" is not
+     *  "proved unsafe" and refusing it would block installs on a guess. */
+    allowAuthorityOverlap: zod_1.z.boolean().optional(),
     /** Opt-in to pointing the rule's interpreter policy at any address
      *  other than the pinned interpreter for the selected network.
      *  Default-deny: a caller that controls the interpreter can permit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",

package/src/install/authority-overlap.ts

@@ -50,6 +50,26 @@ export type ContextType =
  *    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
@@ -59,6 +79,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 {
@@ -69,10 +94,16 @@ 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'
@@ -89,6 +120,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
 }
 
@@ -265,14 +304,45 @@ function classifyRule(rule: ObservedRule): RuleClass {
   return rule.predicate ? 'interpreter' : 'foreign'
 }
 
-function adviceFor(cls: RuleClass, ruleId: number): string {
+/** 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: ObservedRule, known: KnownPolicies): boolean {
+  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: ObservedRule, known: KnownPolicies): boolean {
+  return rule.policyAddresses.every(
+    (addr) => addr === known.interpreter || addr === known.spendingLimit
+  )
+}
+
+function capBypassAdvice(ruleId: number): string {
+  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: SpendCap, theirs: SpendCap): string {
+  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: RuleClass, ruleId: number, theirCap?: SpendCap, myCap?: SpendCap): string {
+  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}`
   }
 }
 
@@ -287,6 +357,9 @@ function adviceFor(cls: RuleClass, ruleId: number): string {
 export 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[] {
   const intendedSelectors = intersectSelectors(
     selectorsForContextType(args.intended.contextType),
@@ -304,18 +377,46 @@ 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: OverlapSeverity =
+      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 as const } : {}),
+      advice: capBypass
+        ? capBypassAdvice(rule.id)
+        : adviceFor(ruleClass, rule.id, rule.spendCap, args.intended.spendCap),
     })
   }