@crediolabs/policy-synth 1.0.0 → 1.1.0

package/dist/install/build-add-context-rule.js

@@ -48,6 +48,7 @@
 // the account refuses with `Error(Auth, InvalidAction)`.
 import { createHash } from 'node:crypto';
 import { Address, xdr } from '@stellar/stellar-sdk';
+import { scvI128FromDecimal } from "../predicate/encode.js";
 import { GRAMMAR_VERSION, OZ_LIMITS, } from "../types.js";
 export const DEFAULT_GRAMMAR_VERSION = GRAMMAR_VERSION;
 /** The verb `add_context_rule` takes on the wire. */
@@ -121,27 +122,58 @@ function encodeSigner(s) {
 function encodePoliciesMap(args) {
     const entries = [];
     for (const ref of args.policies) {
-        // Refuse anything that is not an interpreter policy rather than skipping
-        // it. This loop used to `if (kind === 'interpreter')` and drop everything
-        // else in silence, so a caller attaching an OZ `spending_limit` beside the
-        // interpreter got a rule WITHOUT the cap and no indication of it - the
-        // policy the user asked for was simply absent from the install they signed.
-        // `PolicyRef` has one shape today, so TypeScript narrows this branch to
-        // `never`; the guard is for callers reaching the built JS untyped, and for
-        // the next kind added to `PolicyRef` without a case here. Failing loudly is
-        // the only safe direction: a dropped policy is a missing restriction.
-        if (ref.kind !== 'interpreter') {
-            const kind = JSON.stringify(ref.kind ?? null);
-            throw limitError('INSTALL_BUILD_FAILED', `policy kind ${kind} is not supported; this builder attaches interpreter policies only. Attach an OpenZeppelin built-in through the account layer instead - dropping it here would install a rule missing the restriction you asked for.`);
+        // Each policy carries its OWN params. This loop once applied one set of
+        // install params to every entry, which is why nothing but the interpreter
+        // could be expressed; before that it dropped other kinds in silence, so a
+        // caller attaching a cap received a rule without it and no indication.
+        // Both directions were wrong. An unknown kind still fails loudly below - a
+        // dropped policy is a missing restriction.
+        switch (ref.kind) {
+            case 'interpreter':
+                entries.push(new xdr.ScMapEntry({
+                    key: Address.fromString(ref.interpreterAddress).toScVal(),
+                    val: encodePolicyInstallParams(args),
+                }));
+                break;
+            case 'spending_limit':
+                entries.push(new xdr.ScMapEntry({
+                    key: Address.fromString(ref.policyAddress).toScVal(),
+                    val: encodeSpendingLimitParams(ref),
+                }));
+                break;
+            default: {
+                const kind = JSON.stringify(ref.kind ?? null);
+                throw limitError('INSTALL_BUILD_FAILED', `policy kind ${kind} is not supported; dropping it here would install a rule missing the restriction you asked for`);
+            }
         }
-        entries.push(new xdr.ScMapEntry({
-            key: Address.fromString(ref.interpreterAddress).toScVal(),
-            val: encodePolicyInstallParams(args),
-        }));
     }
     entries.sort(sortByScValSymbolString);
     return xdr.ScVal.scvMap(entries);
 }
+/** OpenZeppelin `spending_limit`'s install params: `{ period_ledgers: u32,
+ *  spending_limit: i128 }`, emitted in symbol-string order. Validated here
+ *  rather than left to the chain, because a rolling cap that fails at submit
+ *  has already cost the caller a signature. */
+function encodeSpendingLimitParams(ref) {
+    if (!Number.isInteger(ref.periodLedgers) || ref.periodLedgers <= 0) {
+        throw limitError('INSTALL_BUILD_FAILED', `spending_limit periodLedgers must be a positive integer - it counts LEDGERS, not seconds; got: ${ref.periodLedgers}`);
+    }
+    if (!/^[0-9]+$/.test(ref.spendingLimit) || BigInt(ref.spendingLimit) <= 0n) {
+        throw limitError('INSTALL_BUILD_FAILED', `spending_limit must be a positive integer in the token's smallest unit; got: ${ref.spendingLimit}`);
+    }
+    const entries = [
+        new xdr.ScMapEntry({
+            key: xdr.ScVal.scvSymbol('period_ledgers'),
+            val: xdr.ScVal.scvU32(ref.periodLedgers),
+        }),
+        new xdr.ScMapEntry({
+            key: xdr.ScVal.scvSymbol('spending_limit'),
+            val: scvI128FromDecimal(ref.spendingLimit),
+        }),
+    ];
+    entries.sort((a, b) => sortBySymbolString(a.key(), b.key()));
+    return xdr.ScVal.scvMap(entries);
+}
 function encodePolicyInstallParams(args) {
     const predicate = Buffer.from(args.encodedPredicate, 'base64');
     const computedHash = createHash('sha256').update(predicate).digest('hex');

package/dist/install/build-install-policy.d.ts

@@ -93,6 +93,13 @@ export interface InstallCallDescribes {
         installNonce: number;
         predicateHash: string;
         predicateSha256OfEmbeddedBytes: string;
+    } | {
+        /** An OpenZeppelin built-in bounding the SUM across calls, which the
+         *  predicate cannot: the interpreter sees one call and keeps no state. */
+        kind: 'spending_limit';
+        address: string;
+        periodLedgers: number;
+        spendingLimit: string;
     }>;
     /** The install nonce, decoded from the interpreter policy's
      *  `install_nonce` field. Echoed at the top level for reviewer convenience;
@@ -172,3 +179,17 @@ export interface BuildRevokePolicyResult {
     authValidUntilLedger: number;
     rootInvocationXdr: string;
 }
+/** The actionable half of a failed simulation, with the transport half left out.
+ *
+ *  `sim.error` names both why the chain refused the call and which host was
+ *  asked, and the second half must not reach a caller. So we return only
+ *  Soroban's own `Error(Type, #Code)` forms: those are contract state, and they
+ *  are what tells an operator whether the source account lacks authority, a
+ *  nonce is stale, or a predicate refused. Without them "simulateTransaction
+ *  failed" names nothing a caller can act on.
+ *
+ *  Returns "" when the error carries no such form, so the caller keeps its short
+ *  stable message rather than gaining an empty parenthesis. */
+export declare function simulationReason(sim: {
+    error?: string;
+}): string;

package/dist/install/build-install-policy.js

@@ -131,6 +131,21 @@ export async function buildRevokePolicyXdr(args) {
 /** ~25 minutes at 5s/ledger. */
 const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
 // ---- internals ----
+/** The actionable half of a failed simulation, with the transport half left out.
+ *
+ *  `sim.error` names both why the chain refused the call and which host was
+ *  asked, and the second half must not reach a caller. So we return only
+ *  Soroban's own `Error(Type, #Code)` forms: those are contract state, and they
+ *  are what tells an operator whether the source account lacks authority, a
+ *  nonce is stale, or a predicate refused. Without them "simulateTransaction
+ *  failed" names nothing a caller can act on.
+ *
+ *  Returns "" when the error carries no such form, so the caller keeps its short
+ *  stable message rather than gaining an empty parenthesis. */
+export function simulationReason(sim) {
+    const codes = [...new Set((sim.error ?? '').match(/Error\([^)]*\)/g) ?? [])];
+    return codes.length > 0 ? ` (${codes.join(', ')})` : '';
+}
 /** Record a bare call to the smart account, attach the deploy-time admin rule's
  *  auth entries, and re-simulate to assemble the footprint.
  *
@@ -160,8 +175,10 @@ async function buildAuthorisedSmartAccountTx(args, functionName, callArgs, error
         // Short, stable reason. The full `simulateTransaction` error (which
         // carries host + URL detail) stays in the SDK's own logs - never
         // reflected back into a user-facing message where it would
-        // reconnoitre the RPC.
-        throw new Error(`${errorPrefix}: simulateTransaction failed`);
+        // reconnoitre the RPC. `simulationReason` re-adds only the chain's own
+        // error codes, which say why the call was refused without saying where
+        // the RPC lives.
+        throw new Error(`${errorPrefix}: simulateTransaction failed${simulationReason(recorded)}`);
     }
     const original = (recorded.result?.auth ?? []).find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
         Address.fromScAddress(entry.credentials().address().address()).toString() ===
@@ -180,7 +197,7 @@ async function buildAuthorisedSmartAccountTx(args, functionName, callArgs, error
     const txWithAuth = buildTx(makeOperation(authEntries));
     const enforcing = await args.rpc.simulateTransaction(txWithAuth);
     if (rpc.Api.isSimulationError(enforcing)) {
-        throw new Error(`${errorPrefix}: auth simulateTransaction failed`);
+        throw new Error(`${errorPrefix}: auth simulateTransaction failed${simulationReason(enforcing)}`);
     }
     return {
         finalTx: rpc.assembleTransaction(txWithAuth, enforcing).build(),
@@ -354,6 +371,27 @@ function decodeInstallCallDescribes(tx, expectedInstallNonce) {
             observedInstallNonce = installNonce;
             continue;
         }
+        // OpenZeppelin `spending_limit`: { period_ledgers: u32, spending_limit: i128 }.
+        if (fields.has('period_ledgers') || fields.has('spending_limit')) {
+            const periodScv = fields.get('period_ledgers');
+            if (periodScv?.switch().name !== 'scvU32') {
+                throw new Error(`install_policy: spending_limit policy ${address} is missing a u32 period_ledgers`);
+            }
+            const limitScv = fields.get('spending_limit');
+            if (limitScv?.switch().name !== 'scvI128') {
+                throw new Error(`install_policy: spending_limit policy ${address} is missing an i128 spending_limit`);
+            }
+            const parts = limitScv.i128();
+            const spendingLimit = ((BigInt(parts.hi().toString()) << 64n) +
+                BigInt(parts.lo().toString())).toString();
+            policies.push({
+                kind: 'spending_limit',
+                address,
+                periodLedgers: periodScv.u32(),
+                spendingLimit,
+            });
+            continue;
+        }
         throw new Error(`install_policy: policies[${address}] value has an unknown field set; the encoder may have drifted`);
     }
     // `observedInstallNonce` is the nonce baked into whichever interpreter

package/dist/predicate/encode.d.ts

@@ -1,3 +1,4 @@
+import { xdr } from '@stellar/stellar-sdk';
 import { type PredicateNode } from '../types.ts';
 export interface EncodedPredicate {
     /** base64 of the canonical ScVal XDR of the predicate root. */
@@ -8,3 +9,14 @@ export interface EncodedPredicate {
 /** Encode a `PredicateNode` to the canonical ScVal wire format and hash it.
  *  Pure function: same input -> byte-identical output every run. */
 export declare function encodePredicate(node: PredicateNode): EncodedPredicate;
+/** Build `ScVal::I128(Int128Parts{hi, lo})` from a signed decimal string.
+ *  `Int128Parts` encodes the value as `(hi << 64) + lo` with `hi` a SIGNED
+ *  64-bit int and `lo` an UNSIGNED 64-bit int (this is NOT signed-magnitude).
+ *  The inverse split is `hi = v >> 64n` (arithmetic right shift) and
+ *  `lo = v & 0xFFFF...`. The SDK's `Int64` constructor takes a signed
+ *  bigint/string/number. */
+/** Canonical i128 encoding of a base-10 decimal string, with the Int64 range
+ *  guard on the high word. Exported so the install builder encodes an
+ *  OpenZeppelin amount the same way a predicate literal is encoded - a second
+ *  implementation is how a value above 2^64 silently loses its high word. */
+export declare function scvI128FromDecimal(decimal: string): xdr.ScVal;

package/dist/predicate/encode.js

@@ -231,7 +231,11 @@ function scvAddressFromStrkey(strkey) {
  *  The inverse split is `hi = v >> 64n` (arithmetic right shift) and
  *  `lo = v & 0xFFFF...`. The SDK's `Int64` constructor takes a signed
  *  bigint/string/number. */
-function scvI128FromDecimal(decimal) {
+/** Canonical i128 encoding of a base-10 decimal string, with the Int64 range
+ *  guard on the high word. Exported so the install builder encodes an
+ *  OpenZeppelin amount the same way a predicate literal is encoded - a second
+ *  implementation is how a value above 2^64 silently loses its high word. */
+export function scvI128FromDecimal(decimal) {
     const v = BigInt(decimal);
     const hi = v >> 64n;
     const lo = v & UINT64_MAX;

package/dist/run/index.d.ts

@@ -2,7 +2,7 @@ import { type ErrorCode, type PredicateNode, type ProposedPolicy, type RecordedT
 import { type AuthorityOverlap } from '../install/authority-overlap.ts';
 import { type BuildInstallPolicyResult, type BuildRevokePolicyResult } from '../install/build-install-policy.ts';
 import { getInterpreterInfo } from '../install/get-interpreter-info.ts';
-import { type RecordTransactionInput, type SimulatePolicyInput, type SynthesizePolicyInput, type VerifyPolicyInput } from './schemas.ts';
+import { type InstallPolicyInput, type RecordTransactionInput, type SimulatePolicyInput, type SynthesizePolicyInput, type VerifyPolicyInput } from './schemas.ts';
 export type { DeclarePolicyInput, GetInterpreterInfoInput, InstallPolicyInput, OzBuiltinPolicy, RecordTransactionInput, RevokePolicyInput, SimulatePolicyInput, SynthesizePolicyInput, VerifyPolicyInput, } from './schemas.ts';
 export { ComposeUserResponsesSchema, DeclarePolicyInputSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MAINNET_RPC_URL, NetworkSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256, PINNED_OZ_POLICY_ADDRESS_BY_NETWORK, PINNED_OZ_POLICY_WASM_SHA256, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, } from './schemas.ts';
 export type RunRecordTransactionInput = RecordTransactionInput;
@@ -51,13 +51,22 @@ export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<Bui
  *  policy payload, so the interpreter pin is not re-checked here.
  *  Pin selection follows `input.network` (defaults to `testnet`). */
 export declare function runRevokePolicy(raw: unknown): Promise<ToolResponse<BuildRevokePolicyResult>>;
+/** Scope a rule to whatever contract its predicate pins.
+ *
+ *  Taking this from the predicate rather than from a separate argument means
+ *  the rule's scope cannot drift from what the predicate actually checks. A
+ *  predicate that pins no contract yields the default (account-wide) type,
+ *  which is what an unpinned predicate means. Only the top level is walked:
+ *  a contract pin nested under an `or` does not scope the rule, because the
+ *  other branch would not be covered by it. */
+export declare function contextTypeForPredicate(predicate: PredicateNode): NonNullable<InstallPolicyInput['rule']>['contextRuleType'];
 /** `simulate_policy` body - evaluate a predicate against one recorded call.
  *
  *  The evaluator is a second implementation of the on-chain semantics, and the
  *  conformance harness asserts it agrees with the Rust interpreter case for
  *  case. A verdict here is therefore a claim about what the contract would do,
  *  not a guess. */
-export declare function runSimulatePolicy(raw: unknown): ToolResponse<{
+export declare function runSimulatePolicy(raw: unknown): Promise<ToolResponse<{
     permitted: boolean;
     reason: string | null;
     call: {
@@ -65,7 +74,7 @@ export declare function runSimulatePolicy(raw: unknown): ToolResponse<{
         fn: string;
         argCount: number;
     };
-}>;
+}>>;
 /** `declare_policy` body - the DECLARATIVE front-end.
  *
  *  `synthesize_policy` infers a predicate from a transaction that happened;
@@ -92,7 +101,7 @@ export declare function runDeclarePolicy(raw: unknown): ToolResponse<{
  *  very transaction it was synthesised from. A deny case that permits means it
  *  is too LOOSE: some mutation of that transaction still gets through. `ok` is
  *  true only when neither holds. */
-export declare function runVerifyPolicy(raw: unknown): ToolResponse<{
+export declare function runVerifyPolicy(raw: unknown): Promise<ToolResponse<{
     ok: boolean;
     permit: {
         permitted: boolean;
@@ -104,6 +113,6 @@ export declare function runVerifyPolicy(raw: unknown): ToolResponse<{
         reason: string | null;
     }>;
     dimensionsCovered: number;
-}>;
+}>>;
 export declare function runGetInterpreterInfo(raw: unknown): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>>;
 export declare function caughtError(toolName: RunToolName, code: ErrorCode, e: unknown): ToolError;

package/dist/run/index.js

@@ -18,6 +18,7 @@
 // drive the CLI (which calls into the same core directly without MCP).
 import { createHash } from 'node:crypto';
 import { rpc } from '@stellar/stellar-sdk';
+import { PLACEHOLDER_INTERPRETER_ADDRESS } from "../adapters/interpreter/adapter.js";
 import { declarePredicate, encodePredicate, recordTransaction, synthesizeFromRecording, } from "../index.js";
 import { findAuthorityOverlaps, } from "../install/authority-overlap.js";
 import { buildInstallPolicyXdr, buildRevokePolicyXdr, rpcClientFromServer, } from "../install/build-install-policy.js";
@@ -25,7 +26,7 @@ import { getInterpreterInfo } from "../install/get-interpreter-info.js";
 import { accountRuleReaderFromServer, collectObservedRules } from "../install/read-account-rules.js";
 import { decodePredicate } from "../predicate/decode.js";
 import { evaluate, generateCases } from "../simulate/index.js";
-import { DeclarePolicyInputSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, NETWORK_PASSPHRASES, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_WASM_SHA256, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, VerifyPolicyInputSchema, } from "./schemas.js";
+import { DeclarePolicyInputSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, NETWORK_PASSPHRASES, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_WASM_SHA256, PINNED_OZ_POLICY_ADDRESS_BY_NETWORK, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, VerifyPolicyInputSchema, } from "./schemas.js";
 // Re-export the underlying Zod schemas so the MCP package (and any other
 // downstream consumer) can import the canonical input shapes from the same
 // module that owns the tool-body glue. The strict schemas are the source of
@@ -95,7 +96,24 @@ export async function runSynthesizePolicy(raw) {
     }
     const input = parsed.data;
     try {
-        const recorded = input.recordedTx;
+        // `hash` is the agent-friendly alternative to `recordedTx`: re-record here
+        // rather than make the caller retype a recording it cannot copy faithfully.
+        // A recording failure is returned as-is, so the caller sees why the hash was
+        // refused instead of a synthesis error about a payload it never sent.
+        let recorded;
+        if (input.recordedTx === undefined) {
+            const rerecorded = await runRecordTransaction({
+                hash: input.transactionHash,
+                network: input.network,
+            });
+            if (!rerecorded.ok) {
+                return { ok: false, error: rerecorded.error };
+            }
+            recorded = rerecorded.data;
+        }
+        else {
+            recorded = input.recordedTx;
+        }
         return await synthesizeFromRecording(recorded, {
             network: input.network,
             ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
@@ -117,10 +135,143 @@ export async function runInstallPolicy(raw) {
     }
     const input = parsed.data;
     const network = input.network ?? 'testnet';
+    // `fromHash` builds the rule here rather than accepting a transcribed copy.
+    // The pinning gates below then run against the rule we just synthesized, so
+    // this path is gated identically to a caller-supplied one - it is a shortcut
+    // for the caller, never for the checks.
+    let rule = input.rule;
+    if (rule === undefined && input.fromPredicate !== undefined) {
+        const fp = input.fromPredicate;
+        let scope;
+        try {
+            scope = contextTypeForPredicate(decodePredicate(fp.encodedPredicate));
+        }
+        catch (e) {
+            return toolFailure('install_policy', e);
+        }
+        rule = {
+            contextRuleType: scope,
+            name: fp.name ?? 'policy',
+            validUntilLedger: fp.validUntilLedger ?? null,
+            signers: fp.signers.map((address) => ({ kind: 'delegated', address })),
+            policies: [
+                {
+                    kind: 'interpreter',
+                    interpreterAddress: PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network],
+                    predicateBlobBase64: fp.encodedPredicate,
+                },
+            ],
+        };
+    }
+    if (rule === undefined) {
+        // Typed rather than inline: every tool body takes `unknown`, so a
+        // misspelled key here would compile and fail only at runtime, as a
+        // validation error blamed on the caller. Naming the type restores the
+        // check on this hop.
+        const synthArgs = {
+            source: 'recording',
+            network,
+            transactionHash: input.fromHash?.transactionHash,
+            interpreter: { smartAccountAddress: input.smartAccount },
+            ...(input.fromHash?.userResponses !== undefined
+                ? { userResponses: input.fromHash.userResponses }
+                : {}),
+        };
+        const synthesized = await runSynthesizePolicy(synthArgs);
+        if (!synthesized.ok) {
+            return { ok: false, error: synthesized.error };
+        }
+        // The synthesizer saw a spend it could not bound. Installing anyway yields
+        // a rule that reads as a cap and enforces nothing, and nothing downstream
+        // catches it: it installs cleanly and verifies cleanly, because a missing
+        // constraint generates no deny case that could fail. That combination
+        // reached the chain once. Refuse rather than emit a warning to skim past.
+        const unbounded = synthesized.data.ambiguities.some((a) => a.code === 'AMOUNT_BOUND_MISSING');
+        if (unbounded && input.allowUnboundedAmount !== true) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: 'install_policy: the recorded call spends an amount this policy does not bound, so the rule would constrain everything about the call except how much it moves; set `fromHash.userResponses.limitAmount` to the per-call cap, or `allowUnboundedAmount: true` to install an unbounded rule deliberately',
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        // Synthesis leaves the signer set empty - it reads a transaction, and which
+        // keys a rule binds is a security decision no single recording answers.
+        // The caller names them here.
+        rule = {
+            ...synthesized.data.contextRule,
+            signers: (input.fromHash?.signers ?? []).map((address) => ({
+                kind: 'delegated',
+                address,
+            })),
+        };
+    }
+    // A rule that governs no key is refused on chain, and the refusal arrives as
+    // a bare contract error code with nothing to act on. Say what is missing
+    // instead, while the caller still has the recording in hand.
+    if (rule.signers.length === 0) {
+        return {
+            ok: false,
+            error: {
+                code: 'INSTALL_BUILD_FAILED',
+                message: 'install_policy: the rule names no signer, so it would govern no key; name the keys it applies to',
+                severity: 'error',
+                retryable: false,
+                remediation: { toolCall: { name: 'install_policy', args: {} } },
+            },
+        };
+    }
     // ---- Pinning gates (default-deny) ----
     const expectedInterpreter = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network];
     const expectedRpc = RPC_URL_BY_NETWORK[network];
-    const pinningError = enforceInterpreterPin(input.rule.policies, input.allowUnpinnedInterpreter, expectedInterpreter);
+    // Synthesis stamps every interpreter policy with the placeholder marker: it
+    // is handed a recording, not a network, so it emits a marker rather than
+    // inventing a deploy address. Install DOES know the network, and resolves
+    // the pin just above, so it fills the marker in here - otherwise the
+    // synthesize -> install path is unreachable, because the marker is not a
+    // strkey and fails the pin on every call. Only the exact marker is replaced;
+    // a caller-supplied address is still checked against the pin unchanged, so
+    // this widens nothing.
+    rule = {
+        ...rule,
+        policies: rule.policies.map((p) => p.kind === 'interpreter' && p.interpreterAddress === PLACEHOLDER_INTERPRETER_ADDRESS
+            ? { ...p, interpreterAddress: expectedInterpreter }
+            : p),
+    };
+    // A rolling total, when asked for. The predicate bounds each call; this
+    // bounds the sum across calls, which is state the interpreter does not keep.
+    // Both sit on the one rule and compose as all-of.
+    if (input.spendingLimit !== undefined) {
+        if (rule.contextRuleType.kind !== 'call_contract') {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: `install_policy: a spending limit meters transfers of one token, so the rule must be scoped to that token's contract; this rule's scope is "${rule.contextRuleType.kind}"`,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        rule = {
+            ...rule,
+            policies: [
+                ...rule.policies,
+                {
+                    kind: 'spending_limit',
+                    policyAddress: PINNED_OZ_POLICY_ADDRESS_BY_NETWORK[network].spending_limit,
+                    periodLedgers: input.spendingLimit.periodLedgers,
+                    spendingLimit: input.spendingLimit.amount,
+                },
+            ],
+        };
+    }
+    const pinningError = enforceInterpreterPin(rule.policies, input.allowUnpinnedInterpreter, expectedInterpreter);
     if (pinningError) {
         return { ok: false, error: pinningError };
     }
@@ -136,7 +287,7 @@ export async function runInstallPolicy(raw) {
         return toolFailure('install_policy', e);
     }
     try {
-        const interpreterPolicy = input.rule.policies.find((p) => p.kind === 'interpreter');
+        const interpreterPolicy = rule.policies.find((p) => p.kind === 'interpreter');
         const encodedPredicate = interpreterPolicy?.predicateBlobBase64 ?? '';
         const predicateHash = createHash('sha256')
             .update(Buffer.from(encodedPredicate, 'base64'))
@@ -145,8 +296,10 @@ export async function runInstallPolicy(raw) {
             smartAccount: input.smartAccount,
             sourceAccount: input.sourceAccount,
             networkPassphrase: NETWORK_PASSPHRASES[network],
-            rule: input.rule,
-            installNonce: input.installNonce,
+            rule,
+            // A fresh rule has no stored nonce, so 1 is the value the interpreter
+            // expects unless the caller is deliberately re-installing.
+            installNonce: input.installNonce ?? 1,
             encodedPredicate,
             predicateHash,
             rpc: rpcClient,
@@ -171,8 +324,8 @@ export async function runInstallPolicy(raw) {
                     // no existing rule this install replaces. A sentinel no real id
                     // can equal keeps every observed rule in scope.
                     ruleId: -1,
-                    contextType: input.rule.contextRuleType,
-                    signers: input.rule.signers,
+                    contextType: rule.contextRuleType,
+                    signers: rule.signers,
                     predicate: decodePredicate(encodedPredicate),
                 },
                 existing: observed,
@@ -266,23 +419,116 @@ function noInvocationError(toolName) {
         retryable: false,
     };
 }
+/** Scope a rule to whatever contract its predicate pins.
+ *
+ *  Taking this from the predicate rather than from a separate argument means
+ *  the rule's scope cannot drift from what the predicate actually checks. A
+ *  predicate that pins no contract yields the default (account-wide) type,
+ *  which is what an unpinned predicate means. Only the top level is walked:
+ *  a contract pin nested under an `or` does not scope the rule, because the
+ *  other branch would not be covered by it. */
+export function contextTypeForPredicate(predicate) {
+    const conjuncts = predicate.op === 'and' ? predicate.children : [predicate];
+    for (const node of conjuncts) {
+        if (node.op !== 'eq')
+            continue;
+        if (node.left?.kind !== 'call_contract')
+            continue;
+        if (node.right?.kind !== 'literal_address')
+            continue;
+        return { kind: 'call_contract', contract: node.right.value };
+    }
+    return { kind: 'default' };
+}
+/** Resolve what `simulate_policy` and `verify_policy` evaluate.
+ *
+ *  Both want a predicate TREE plus the recording it came from, and neither is
+ *  something a caller holds by default: the tree is only returned by
+ *  `synthesize_policy` under `explain`, so a caller who did not ask for it has
+ *  nothing to pass and skips the check. Skipping is the worst outcome here -
+ *  these two ARE the check - so a transaction hash is accepted instead and the
+ *  server rebuilds both from it. Recording is deterministic for a settled
+ *  transaction, so this evaluates the same predicate the synthesiser produced. */
+async function resolveCheckInputs(input, tool) {
+    const network = input.network ?? 'testnet';
+    // The call to check against: whichever the caller supplied, recording only
+    // when they gave a hash instead.
+    let permitTx;
+    if (input.permitTx !== undefined) {
+        permitTx = input.permitTx;
+    }
+    else {
+        const recordArgs = { hash: input.transactionHash, network };
+        const recorded = await runRecordTransaction(recordArgs);
+        if (!recorded.ok)
+            return { ok: false, error: recorded.error };
+        permitTx = recorded.data;
+    }
+    // The thing to check. A caller-supplied predicate wins over re-synthesis,
+    // in either form: a DECLARED policy has no recording behind it, so
+    // re-deriving one from the transaction would check a different predicate
+    // than the one the caller is asking about.
+    if (input.predicate !== undefined) {
+        return { ok: true, data: { predicate: input.predicate, permitTx } };
+    }
+    if (input.encodedPredicate !== undefined) {
+        try {
+            return { ok: true, data: { predicate: decodePredicate(input.encodedPredicate), permitTx } };
+        }
+        catch (e) {
+            return toolFailure(tool, e);
+        }
+    }
+    const synthArgs = {
+        source: 'recording',
+        network,
+        // The schema's inferred type is `passthrough`, so it carries an index
+        // signature the core type does not; the shapes agree field for field.
+        recordedTx: permitTx,
+        explain: true,
+        ...(input.smartAccount !== undefined
+            ? { interpreter: { smartAccountAddress: input.smartAccount } }
+            : {}),
+        ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
+    };
+    const synthesized = await runSynthesizePolicy(synthArgs);
+    if (!synthesized.ok)
+        return { ok: false, error: synthesized.error };
+    const tree = synthesized.explain?.predicateTree;
+    if (!tree) {
+        return {
+            ok: false,
+            error: {
+                code: TOOL_ERROR_CODE[tool],
+                message: `${tool}: synthesis produced no predicate to check for that transaction`,
+                severity: 'error',
+                retryable: false,
+                remediation: { toolCall: { name: tool, args: {} } },
+            },
+        };
+    }
+    return { ok: true, data: { predicate: tree, permitTx } };
+}
 /** `simulate_policy` body - evaluate a predicate against one recorded call.
  *
  *  The evaluator is a second implementation of the on-chain semantics, and the
  *  conformance harness asserts it agrees with the Rust interpreter case for
  *  case. A verdict here is therefore a claim about what the contract would do,
  *  not a guess. */
-export function runSimulatePolicy(raw) {
+export async function runSimulatePolicy(raw) {
     const parsed = SimulatePolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
         return { ok: false, error: validationError('simulate_policy', parsed.error.issues) };
     }
     const input = parsed.data;
-    const ctx = evalContextFromRecording(input.permitTx);
+    const resolved = await resolveCheckInputs(input, 'simulate_policy');
+    if (!resolved.ok)
+        return { ok: false, error: resolved.error };
+    const ctx = evalContextFromRecording(resolved.data.permitTx);
     if (!ctx)
         return { ok: false, error: noInvocationError('simulate_policy') };
     try {
-        const res = evaluate(input.predicate, ctx);
+        const res = evaluate(resolved.data.predicate, ctx);
         return {
             ok: true,
             data: {
@@ -356,17 +602,20 @@ export function runDeclarePolicy(raw) {
  *  very transaction it was synthesised from. A deny case that permits means it
  *  is too LOOSE: some mutation of that transaction still gets through. `ok` is
  *  true only when neither holds. */
-export function runVerifyPolicy(raw) {
+export async function runVerifyPolicy(raw) {
     const parsed = VerifyPolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
         return { ok: false, error: validationError('verify_policy', parsed.error.issues) };
     }
     const input = parsed.data;
-    const ctx = evalContextFromRecording(input.permitTx);
+    const resolved = await resolveCheckInputs(input, 'verify_policy');
+    if (!resolved.ok)
+        return { ok: false, error: resolved.error };
+    const ctx = evalContextFromRecording(resolved.data.permitTx);
     if (!ctx)
         return { ok: false, error: noInvocationError('verify_policy') };
     try {
-        const predicate = input.predicate;
+        const predicate = resolved.data.predicate;
         const cases = generateCases(predicate, ctx);
         const permitRes = evaluate(predicate, cases.permit);
         const denies = cases.denies.map((d) => {