@crediolabs/policy-synth 0.3.1 → 0.5.0

package/dist/registry/on-chain-spec.js

@@ -0,0 +1,152 @@
+// src/registry/on-chain-spec.ts - read a contract's own interface off chain.
+//
+// The compiled-in registry covers the protocols we pinned by hand. Everything
+// else was reported as `no-abi`, which read as "this contract does not
+// describe itself" when it almost always does: a Soroban contract embeds a
+// typed spec in its wasm, and the network will hand it over. The recorder was
+// refusing calls whose interface was one RPC round-trip away.
+//
+// What this buys is NARROW and deliberately so. A fetched spec says what the
+// contract's arguments ARE, not what they MEAN. So a call verified against it
+// is recognised - the decode is trustworthy, the confidence gate stops
+// refusing it - but the arguments carry the contract's own parameter NAMES
+// rather than a curated meaning, and nothing here infers which argument is a
+// spend or a recipient. A pinned protocol still outranks a fetched spec for
+// exactly that reason, and `identifyProtocol` is consulted first.
+import { contract as sdkContract } from '@stellar/stellar-sdk';
+import { argsMatchAbi } from "./identify.js";
+/** Map an XDR spec type to the ScVal subset vocabulary the matcher uses.
+ *
+ *  Returns null for a type the recorder's ScVal subset cannot represent. That
+ *  is deliberate: an argument we cannot type is an argument we cannot check,
+ *  and claiming a match on it would be the fail-OPEN direction. A function
+ *  with any such argument is dropped from the derived ABI, so a call to it
+ *  stays unrecognised rather than being waved through. */
+export function abiTypeFromSpecType(specTypeName) {
+    switch (specTypeName) {
+        case 'scSpecTypeAddress':
+            return 'address';
+        case 'scSpecTypeI128':
+            return 'i128';
+        case 'scSpecTypeU64':
+        case 'scSpecTypeI64':
+            return 'u64';
+        case 'scSpecTypeU32':
+        case 'scSpecTypeI32':
+            return 'u32';
+        case 'scSpecTypeSymbol':
+            return 'symbol';
+        case 'scSpecTypeVec':
+            return 'vec';
+        case 'scSpecTypeBytes':
+        case 'scSpecTypeBytesN':
+            return 'bytes';
+        case 'scSpecTypeMap':
+            return 'map';
+        default:
+            return null;
+    }
+}
+/** Build a `SpecFetcher` over the SDK's contract client. */
+export function specFetcherFromRpc(rpcUrl, networkPassphrase) {
+    return {
+        async contractSpec(contractId) {
+            try {
+                const client = await sdkContract.Client.from({ contractId, networkPassphrase, rpcUrl });
+                return client.spec ?? null;
+            }
+            catch {
+                // A contract with no spec, an unreachable RPC and a bad address all
+                // land here and all mean the same thing to the caller: no interface
+                // was obtained, so the contract stays unrecognised. Fail closed.
+                return null;
+            }
+        },
+    };
+}
+/** Convert a fetched spec into the ABI shape `identifyProtocol` already
+ *  matches against. Functions with an argument outside the ScVal subset are
+ *  OMITTED rather than partially typed. */
+export function abiFromSpec(spec) {
+    const abi = {};
+    for (const fn of spec.funcs()) {
+        const name = fn.name().toString();
+        // The constructor is not callable after deployment, so a recorded
+        // invocation can never be one. Keeping it would only widen the surface.
+        if (name === '__constructor')
+            continue;
+        const args = [];
+        let usable = true;
+        for (const input of fn.inputs()) {
+            const type = abiTypeFromSpecType(input.type().switch().name);
+            if (type === null) {
+                usable = false;
+                break;
+            }
+            const argName = input.name().toString();
+            args.push({
+                name: argName,
+                type,
+                // The contract's own parameter name is the honest description. It is
+                // NOT a curated meaning - nothing here knows whether `value` is a
+                // spend - so downstream must not treat it as one.
+                meaning: `${argName} (from the contract's on-chain interface)`,
+            });
+        }
+        if (usable)
+            abi[name] = { args };
+    }
+    return abi;
+}
+/** Fetch and convert in one step. Returns null when no usable interface was
+ *  obtained, which the caller must treat as "unrecognised". */
+export async function fetchContractAbi(contractId, fetcher) {
+    const spec = await fetcher.contractSpec(contractId);
+    if (spec === null)
+        return null;
+    const abi = abiFromSpec(spec);
+    return Object.keys(abi).length === 0 ? null : abi;
+}
+/** Every contract invoked anywhere in the tree, with the calls made on it. */
+function callsByContract(invocations) {
+    const out = new Map();
+    const walk = (inv) => {
+        const list = out.get(inv.contract) ?? [];
+        list.push({ fn: inv.fn, args: inv.args });
+        out.set(inv.contract, list);
+        for (const sub of inv.subInvocations)
+            walk(sub);
+    };
+    for (const inv of invocations)
+        walk(inv);
+    return out;
+}
+/** Contracts whose EVERY recorded call matches their own published interface.
+ *
+ *  All-or-nothing per contract, deliberately. A contract where one call
+ *  verifies and another does not is a contract we do not understand, and
+ *  marking it recognised would raise confidence on the strength of the call
+ *  we happened to check. The unverified call is the one that matters.
+ *
+ *  A contract with no fetchable spec, or a call naming a function absent from
+ *  it, simply stays unknown - this only ever ADDS recognition, so a failure
+ *  here degrades to today's behaviour rather than to a wrong answer. */
+export async function resolveContractsByOnChainSpec(invocations, candidates, fetcher) {
+    const resolved = new Set();
+    const calls = callsByContract(invocations);
+    for (const contract of new Set(candidates)) {
+        const made = calls.get(contract);
+        if (!made || made.length === 0)
+            continue;
+        const abi = await fetchContractAbi(contract, fetcher);
+        if (abi === null)
+            continue;
+        const everyCallVerifies = made.every((c) => {
+            const entry = abi[c.fn];
+            return entry !== undefined && argsMatchAbi(entry.args, c.args);
+        });
+        if (everyCallVerifies)
+            resolved.add(contract);
+    }
+    return resolved;
+}

package/dist/review-card/builder.js

@@ -80,15 +80,31 @@ function walkPredicate(node, visit) {
             for (const child of node.children)
                 walkPredicate(child, visit);
             return;
+        // NOT descended into. Every line the card emits reads as a requirement,
+        // and `and` is what makes that true. Listing an `or`'s branches as
+        // separate lines would state the opposite of what the policy means, so
+        // the whole disjunction is rendered as ONE line instead.
+        case 'or':
+            visit(node);
+            return;
         case 'in':
             visit(node);
             return;
         case 'eq':
+        case 'lt':
         case 'lte':
+        case 'gt':
+        case 'gte':
             visit(node);
             return;
     }
 }
+/** Argument index of a `call_arg` leaf, for the scaled-comparison line. Any
+ *  other leaf renders as its kind so the line stays readable rather than
+ *  claiming an index that does not exist. */
+function leftArgLabel(leaf) {
+    return leaf.kind === 'call_arg' ? String(leaf.index) : `<${leaf.kind}>`;
+}
 /** Render ONE constraint sentence for ONE interpreter predicate node. The
  *  shape of the output is pinned by Task 7b so the test suite can assert
  *  byte-for-byte equality. Returns `null` when the node is a structural
@@ -97,14 +113,38 @@ function renderConstraint(node) {
     switch (node.op) {
         case 'and':
             return null;
+        case 'or': {
+            // One line for the whole disjunction. If any branch is a shape the
+            // card cannot render, the entire line is withheld rather than shown
+            // with a branch missing - a disjunction with a branch dropped reads
+            // as STRICTER than it is, which is the dangerous direction.
+            const parts = node.children.map(renderConstraint);
+            if (parts.some((p) => p === null))
+                return null;
+            return `Either: ${parts.join(' OR ')}`;
+        }
         case 'eq':
+        case 'lt':
         case 'lte':
+        case 'gt':
+        case 'gte':
             return renderComparison(node);
         case 'in':
             return renderMembership(node);
     }
 }
 function renderComparison(node) {
+    // The slippage floor: OP(call_arg[out], call_arg_scaled(in, num, den)).
+    // Rendered explicitly because the human approving the signature has to see
+    // that the bound is a RATIO of another argument, not a fixed amount.
+    if (node.right.kind === 'call_arg_scaled') {
+        const s = node.right;
+        return `arg[${leftArgLabel(node.left)}] ${comparisonOpText(node.op)} arg[${s.index}] * ${s.num}/${s.den}`;
+    }
+    if (node.left.kind === 'call_arg_scaled') {
+        const s = node.left;
+        return `arg[${s.index}] * ${s.num}/${s.den} ${comparisonOpText(node.op)} arg[${leftArgLabel(node.right)}]`;
+    }
     const left = node.left;
     const right = node.right;
     // eq(call_contract, literal_address) -> Contract must be <addr>

package/dist/review-card/cross-check.js

@@ -39,8 +39,30 @@ function collect(node, out) {
             for (const child of node.children)
                 collect(child, out);
             return;
+        // ONE line for the whole disjunction, mirroring the builder. Emitting a
+        // line per branch would claim every branch is required, which is the
+        // opposite of what `or` means. If any branch renders to nothing the whole
+        // line is withheld, again mirroring the builder - a disjunction missing a
+        // branch reads STRICTER than it is.
+        case 'or': {
+            const parts = [];
+            for (const child of node.children) {
+                const childOut = [];
+                collect(child, childOut);
+                if (childOut.length !== 1)
+                    return;
+                parts.push(childOut[0]);
+            }
+            if (parts.length === 0)
+                return;
+            out.push(`Either: ${parts.join(' OR ')}`);
+            return;
+        }
         case 'eq':
+        case 'lt':
         case 'lte':
+        case 'gt':
+        case 'gte':
             pushComparison(node.left, node.right, node.op, out);
             return;
         case 'in':
@@ -49,6 +71,18 @@ function collect(node, out) {
     }
 }
 function pushComparison(left, right, op, out) {
+    // Slippage floor, mirroring the builder. The human has to see that the
+    // bound is a RATIO of another argument, not a fixed amount.
+    if (right.kind === 'call_arg_scaled') {
+        const label = left.kind === 'call_arg' ? String(left.index) : `<${left.kind}>`;
+        out.push(`arg[${label}] ${comparisonOpText(op)} arg[${right.index}] * ${right.num}/${right.den}`);
+        return;
+    }
+    if (left.kind === 'call_arg_scaled') {
+        const label = right.kind === 'call_arg' ? String(right.index) : `<${right.kind}>`;
+        out.push(`arg[${left.index}] * ${left.num}/${left.den} ${comparisonOpText(op)} arg[${label}]`);
+        return;
+    }
     if (left.kind === 'call_contract' && op === 'eq' && right.kind === 'literal_address') {
         out.push(`Contract must be ${right.value}`);
         return;

package/dist/review-card/render-leaf.d.ts

@@ -1,4 +1,4 @@
 import type { PredicateLeaf } from '../types.ts';
 export declare function renderVecElement(leaf: PredicateLeaf): string;
 export declare function renderHaystackElement(leaf: PredicateLeaf): string;
-export declare function comparisonOpText(op: 'eq' | 'lte'): string;
+export declare function comparisonOpText(op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte'): string;

package/dist/review-card/render-leaf.js

@@ -20,6 +20,7 @@ export function renderVecElement(leaf) {
         case 'call_arg':
         case 'call_arg_len':
         case 'call_arg_field':
+        case 'call_arg_scaled':
             return `<${leaf.kind}>`;
     }
 }
@@ -39,8 +40,14 @@ export function renderHaystackElement(leaf) {
 }
 export function comparisonOpText(op) {
     switch (op) {
+        case 'lt':
+            return '<';
         case 'lte':
             return '<=';
+        case 'gt':
+            return '>';
+        case 'gte':
+            return '>=';
         case 'eq':
             return '==';
     }

package/dist/run/index.d.ts

@@ -1,14 +1,15 @@
 import { type ErrorCode, type PredicateNode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
+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';
-export type { GetInterpreterInfoInput, InstallPolicyInput, RecordTransactionInput, RevokePolicyInput, SimulatePolicyInput, SynthesizePolicyInput, VerifyPolicyInput, } from './schemas.ts';
-export { ComposeUserResponsesSchema, 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, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, } from './schemas.ts';
+export type { DeclarePolicyInput, GetInterpreterInfoInput, InstallPolicyInput, 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, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, } from './schemas.ts';
 export type RunRecordTransactionInput = RecordTransactionInput;
 export type RunSynthesizePolicyInput = SynthesizePolicyInput;
 export type RunSimulatePolicyInput = SimulatePolicyInput;
 export type RunVerifyPolicyInput = VerifyPolicyInput;
-type RunToolName = 'record_transaction' | 'synthesize_policy' | 'simulate_policy' | 'verify_policy' | 'install_policy' | 'revoke_policy' | 'get_interpreter_info';
+type RunToolName = 'record_transaction' | 'synthesize_policy' | 'declare_policy' | 'simulate_policy' | 'verify_policy' | 'install_policy' | 'revoke_policy' | 'get_interpreter_info';
 /** `record_transaction` body - wraps `recordTransaction`. The tool input
  *  matches the core RecordInput minus the injected `fetcher` (the transport
  *  layer does not own the RPC). Returns the core ToolResponse unchanged.
@@ -37,7 +38,9 @@ export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<
         predicateTree: PredicateNode | null;
     };
 }>;
-export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult>>;
+export declare function runInstallPolicy(raw: unknown): Promise<ToolResponse<BuildInstallPolicyResult & {
+    authorityScan: AuthorityOverlap[] | null;
+}>>;
 /** `revoke_policy` body - thin wrapper over `buildRevokePolicyXdr`.
  *  Emits an unsigned XDR for `account.remove_context_rule(ruleId)`; the
  *  smart account itself handles uninstalling each attached policy. Auth
@@ -63,6 +66,24 @@ export declare function runSimulatePolicy(raw: unknown): ToolResponse<{
         argCount: number;
     };
 }>;
+/** `declare_policy` body - the DECLARATIVE front-end.
+ *
+ *  `synthesize_policy` infers a predicate from a transaction that happened;
+ *  this takes the constraint stated outright. No RPC, no decoding and no
+ *  parseConfidence, so nothing here can be refused for a contract the registry
+ *  does not recognise - which is most of the point of having it.
+ *
+ *  The returned `warnings` are load-bearing, not decoration. An argument index
+ *  the caller did not supply is DEFAULTED to the SEP-41 position, and a bound
+ *  on the wrong argument constrains something the caller did not mean without
+ *  ever announcing itself, so a caller that ignores warnings can install a
+ *  predicate that reads correctly and binds nothing. */
+export declare function runDeclarePolicy(raw: unknown): ToolResponse<{
+    predicate: PredicateNode;
+    encodedPredicate: string;
+    predicateHash: string;
+    warnings: string[];
+}>;
 /** `verify_policy` body - the permit case plus a generated deny case per
  *  dimension.
  *

package/dist/run/index.js

@@ -18,22 +18,26 @@
 // drive the CLI (which calls into the same core directly without MCP).
 import { createHash } from 'node:crypto';
 import { rpc } from '@stellar/stellar-sdk';
-import { recordTransaction, synthesizeFromRecording, } from "../index.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";
 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 { 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, 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
 // truth - MCP tool shapes are derived from them.
-export { ComposeUserResponsesSchema, 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, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, } from "./schemas.js";
+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, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, } from "./schemas.js";
 /** Map every tool name to its canonical domain error code. Replaces a 7-way
  *  if/else so adding a tool adds one line here rather than a new branch in
  *  each envelope call. */
 const TOOL_ERROR_CODE = {
     record_transaction: 'RECORDING_FAILED',
     synthesize_policy: 'SYNTHESIS_ERROR',
+    declare_policy: 'SYNTHESIS_ERROR',
     simulate_policy: 'SIMULATION_ERROR',
     verify_policy: 'VERIFICATION_FAILED',
     install_policy: 'INSTALL_BUILD_FAILED',
@@ -148,7 +152,32 @@ export async function runInstallPolicy(raw) {
             rpc: rpcClient,
             ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
         });
-        return { ok: true, data: result };
+        // Cross-rule scan. The caller may supply `existingRules` (useful offline,
+        // and for testing); otherwise the account is READ, so the answer describes
+        // what is actually installed rather than what the caller happened to
+        // mention.
+        //
+        // `null` means NOT CHECKED and is returned whenever the scan cannot be
+        // trusted to be complete - the read failed, or it stopped before
+        // accounting for every live rule. An empty list would say "checked,
+        // nothing found", and a partial scan that reported `[]` would be claiming
+        // a safety it never established.
+        const observed = await resolveExistingRules(input, network, expectedInterpreter);
+        const authorityScan = observed === null
+            ? null
+            : findAuthorityOverlaps({
+                intended: {
+                    // `add_context_rule` gets its id FROM the account, so there is
+                    // 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,
+                    predicate: decodePredicate(encodedPredicate),
+                },
+                existing: observed,
+            });
+        return { ok: true, data: { ...result, authorityScan } };
     }
     catch (e) {
         return toolFailure('install_policy', e);
@@ -267,6 +296,45 @@ export function runSimulatePolicy(raw) {
         return toolFailure('simulate_policy', e);
     }
 }
+/** `declare_policy` body - the DECLARATIVE front-end.
+ *
+ *  `synthesize_policy` infers a predicate from a transaction that happened;
+ *  this takes the constraint stated outright. No RPC, no decoding and no
+ *  parseConfidence, so nothing here can be refused for a contract the registry
+ *  does not recognise - which is most of the point of having it.
+ *
+ *  The returned `warnings` are load-bearing, not decoration. An argument index
+ *  the caller did not supply is DEFAULTED to the SEP-41 position, and a bound
+ *  on the wrong argument constrains something the caller did not mean without
+ *  ever announcing itself, so a caller that ignores warnings can install a
+ *  predicate that reads correctly and binds nothing. */
+export function runDeclarePolicy(raw) {
+    const parsed = DeclarePolicyInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, error: validationError('declare_policy', parsed.error.issues) };
+    }
+    try {
+        // Rebuilt field-by-field rather than passed through: the schema's
+        // optionals are `T | undefined` and `PolicyDeclaration`'s are absent-or-T,
+        // which `exactOptionalPropertyTypes` treats as different.
+        const d = parsed.data;
+        const { predicate, warnings } = declarePredicate({
+            fn: d.fn,
+            ...(d.contract !== undefined ? { contract: d.contract } : {}),
+            ...(d.maxAmount !== undefined ? { maxAmount: d.maxAmount } : {}),
+            ...(d.amountArgIndex !== undefined ? { amountArgIndex: d.amountArgIndex } : {}),
+            ...(d.recipients !== undefined ? { recipients: d.recipients } : {}),
+            ...(d.recipientArgIndex !== undefined ? { recipientArgIndex: d.recipientArgIndex } : {}),
+            ...(d.allowZeroCap !== undefined ? { allowZeroCap: d.allowZeroCap } : {}),
+            ...(d.minOutputRatio !== undefined ? { minOutputRatio: d.minOutputRatio } : {}),
+        });
+        const { encodedPredicate, predicateHash } = encodePredicate(predicate);
+        return { ok: true, data: { predicate, encodedPredicate, predicateHash, warnings } };
+    }
+    catch (e) {
+        return toolFailure('declare_policy', e);
+    }
+}
 /** `verify_policy` body - the permit case plus a generated deny case per
  *  dimension.
  *
@@ -354,6 +422,42 @@ export async function runGetInterpreterInfo(raw) {
  *  network, falling back to the pinned RPC for the network. The caller
  *  has already been gated against the pinned URL elsewhere, so the
  *  fallback here only ever picks from a finite, audited pair. */
+/** The account's other context rules, or `null` when they could not be
+ *  established completely.
+ *
+ *  Caller-supplied `existingRules` win: they let the scan run offline, and a
+ *  caller who passes them has said what to compare against. Otherwise the
+ *  account is read over RPC.
+ *
+ *  Every failure path returns `null` rather than a short list. A read that
+ *  threw, or one that stopped before accounting for every live rule, has not
+ *  ruled anything out - and reporting `[]` there would turn "we could not
+ *  check" into "there is nothing to worry about". */
+async function resolveExistingRules(input, network, interpreterAddress) {
+    if (input.existingRules !== undefined) {
+        // The schema types `predicate` loosely (it is the shared
+        // PredicateNodeSchema); the shape is already validated.
+        return input.existingRules;
+    }
+    try {
+        const url = input.rpcUrl ?? RPC_URL_BY_NETWORK[network];
+        const server = new rpc.Server(url, { allowHttp: false });
+        const collected = await collectObservedRules({
+            reader: accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network]),
+            smartAccount: input.smartAccount,
+            interpreterAddress,
+        });
+        if (collected.incomplete)
+            return null;
+        return collected.rules;
+    }
+    catch {
+        // The install itself is unaffected: the scan is advisory, so a failed
+        // read must not block a policy the user asked for. It just cannot be
+        // reported as a clean scan.
+        return null;
+    }
+}
 function buildRpcClientFromInput(urlOverride, network) {
     const url = urlOverride ?? RPC_URL_BY_NETWORK[network];
     const passphrase = NETWORK_PASSPHRASES[network];