@crediolabs/policy-synth 1.1.1 → 1.3.0

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. */
@@ -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/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({
@@ -623,6 +632,22 @@ export const InstallPolicyInputSchema = z
      *  knows. Supply it only to re-install over an existing rule, where the
      *  interpreter wants `stored_nonce + 1`. */
     installNonce: 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: 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
@@ -666,6 +691,18 @@ export const InstallPolicyInputSchema = z
      *  unaffected; only the case the synthesizer explicitly flagged is
      *  refused. */
     allowUnboundedAmount: 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: 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/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[];

package/dist-cjs/install/authority-overlap.js

@@ -200,14 +200,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}`;
     }
 }
 /**
@@ -231,17 +255,42 @@ 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-cjs/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-cjs/install/read-account-rules.js

@@ -28,6 +28,9 @@ exports.decodeContextType = decodeContextType;
 exports.decodeSigner = decodeSigner;
 exports.decodeContextRule = decodeContextRule;
 exports.decodeStoredPredicateBytes = decodeStoredPredicateBytes;
+exports.spendCapKeyScVal = spendCapKeyScVal;
+exports.spendCapLedgerKey = spendCapLedgerKey;
+exports.decodeSpendCap = decodeSpendCap;
 exports.collectObservedRules = collectObservedRules;
 exports.accountRuleReaderFromServer = accountRuleReaderFromServer;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
@@ -158,6 +161,43 @@ 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. */
+function spendCapKeyScVal(smartAccount, ruleId) {
+    return stellar_sdk_1.xdr.ScVal.scvVec([
+        stellar_sdk_1.xdr.ScVal.scvSymbol('AccountContext'),
+        new stellar_sdk_1.Address(smartAccount).toScVal(),
+        stellar_sdk_1.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. */
+function spendCapLedgerKey(spendingLimit, smartAccount, ruleId) {
+    return stellar_sdk_1.xdr.LedgerKey.contractData(new stellar_sdk_1.xdr.LedgerKeyContractData({
+        contract: new stellar_sdk_1.Address(spendingLimit).toScAddress(),
+        key: spendCapKeyScVal(smartAccount, ruleId),
+        durability: stellar_sdk_1.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. */
+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() !== stellar_sdk_1.xdr.ScValType.scvI128())
+        return undefined;
+    const amount = (0, stellar_sdk_1.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. */
@@ -206,6 +246,16 @@ 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 };
@@ -248,5 +298,13 @@ 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() !== stellar_sdk_1.xdr.LedgerEntryType.contractData())
+                return undefined;
+            return entry.contractData().val();
+        },
     };
 }

package/dist-cjs/run/index.d.ts

@@ -38,6 +38,23 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
         predicateTree: PredicateNode | null;
     };
 }>;
+/** 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. */
+export declare function authorityBypassRefusal(scan: AuthorityOverlap[] | null, allowAuthorityOverlap: boolean | undefined): string | undefined;
 export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult & {
     authorityScan: AuthorityOverlap[] | null;
 }>>;