@crediolabs/policy-synth 0.3.0 → 0.4.0

package/dist-cjs/record/freshness.js

@@ -44,17 +44,23 @@ function isBelowThreshold(c) {
  *  under-confidence recording.
  *
  *  The remediation text branches on which diagnostic bucket is non-empty:
- *    - unknownContracts only -> user MUST supply an ABI (or re-capture
- *      against a known protocol version). The contract is real, the
- *      recorder just cannot decode it.
- *    - opaqueScVals only -> the recorder encountered a value shape it
- *      should support but did not decode. The user cannot supply an ABI
- *      to fix a decoder bug; the guidance explicitly says so and points at
- *      re-running after a tool upgrade / reporting the path.
- *    - both -> list both diagnostics AND chain the right remediation for
- *      each (the user supplies an ABI AND reports the decoder gap).
- *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
- *      text; the user did not actually hit a code-level barrier. */
+ *    - unknownContracts only -> the contract is not in the compiled-in
+ *      registry. NOT "the contract has no interface": most Soroban
+ *      contracts publish a typed spec on chain, this package just never
+ *      reads one. The reason code stays `no-abi` because it is a published
+ *      enum value, so the TEXT has to carry the correction.
+ *    - opaqueScVals only -> the recorder met a value shape it should
+ *      support but did not decode. That is a decoder bug, and the guidance
+ *      says so rather than implying the caller can fix it.
+ *    - both -> list both diagnostics and chain the right remediation.
+ *    - neither (the "denom === 0" path) -> the caller did not actually hit
+ *      a code-level barrier.
+ *
+ *  Do NOT tell the caller to supply an ABI. There is no input for one:
+ *  recognition runs off the compiled-in registry plus a known-contract set
+ *  that no public tool boundary exposes. The old text named an action
+ *  nobody could take and sent users looking for a file they do not have and
+ *  would not need. */
 function buildLowConfidenceQuestion(c) {
     const hasUnknown = c.unknownContracts.length > 0;
     const hasOpaque = c.opaqueScVals.length > 0;
@@ -67,16 +73,20 @@ function buildLowConfidenceQuestion(c) {
     }
     const why = reasons.length === 0 ? 'no diagnostic reason available' : reasons.join('; ');
     const header = `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}.`;
-    // The two remediation branches are explicit so the user (or the agent)
-    // can dispatch on the verb. The "unknown contract" branch is the only
-    // one that asks for an ABI; the "opaque ScVal" branch asks the user to
-    // report the path and re-run after a tool upgrade.
+    // The remediation branches are explicit so the user (or the agent) can
+    // dispatch on the verb. Neither branch asks for an ABI: there is no input
+    // that accepts one, and for the unknown-contract branch the contract's
+    // own spec is usually on chain already - it is this package that does not
+    // read it.
+    const unknownAdvice = `The contract is not in this package's built-in registry - "no-abi" means unrecognised here, not that the contract lacks an interface. ` +
+        `You cannot supply one: the registry is compiled in. Either build the policy without deriving it from this transaction, or re-capture against a protocol the registry covers. ` +
+        `Passing confidenceOverride accepts the recording as it stands, including the arguments this tool could not attribute - do that only if you have checked them yourself.`;
     if (hasUnknown && hasOpaque) {
-        return (`${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version; ` +
-            `also file the opaque ScVal path against the recorder (decoder limitation) and re-run record_transaction after a tool upgrade.`);
+        return (`${header} ${unknownAdvice} Separately, file the opaque ScVal path against the recorder (a decoder limitation) ` +
+            `and re-run record_transaction after a tool upgrade.`);
     }
     if (hasUnknown) {
-        return `${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+        return `${header} ${unknownAdvice}`;
     }
     if (hasOpaque) {
         return `${header} This is a recorder decoder limitation (the value shape is supported in principle but not yet decoded) - the agent cannot fix it by supplying an ABI. Report the opaque ScVal path above against the recorder and re-run record_transaction after a tool upgrade.`;

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

@@ -1,4 +1,5 @@
 import type { ToolResponse } from '../errors.ts';
+import { type SpecFetcher } from '../registry/on-chain-spec.ts';
 import type { Network, RecordedTransaction } from '../types.ts';
 import { type RpcFetcher } from './rpc.ts';
 /** Public input shape. The brief pins:
@@ -27,6 +28,15 @@ export interface RecordInput {
      *  automatically; tests can pass a deterministic stub. */
     crossNetworkFetcher?: RpcFetcher;
     confidenceOverride?: number;
+    /** Read a contract's own interface off chain when the compiled-in registry
+     *  does not recognise it. Default ON: the registry covers the protocols we
+     *  pinned by hand, and refusing everything else reported `no-abi` for
+     *  contracts that publish a full typed spec. Set false to record against
+     *  the registry alone (no extra RPC). */
+    resolveContractSpecs?: boolean;
+    /** Test seam for the spec lookup. Unset in production, where it is built
+     *  from the network's pinned RPC URL. */
+    specFetcher?: SpecFetcher;
 }
 export type RecordResult = ToolResponse<RecordedTransaction>;
 export declare function recordTransaction(input: RecordInput): Promise<RecordResult>;

package/dist-cjs/record/index.js

@@ -19,11 +19,40 @@
 // defined in src/errors.ts.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordTransaction = recordTransaction;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const on_chain_spec_ts_1 = require("../registry/on-chain-spec.js");
 const decode_ts_1 = require("./decode.js");
 const freshness_ts_1 = require("./freshness.js");
 const movements_ts_1 = require("./movements.js");
 const rpc_ts_1 = require("./rpc.js");
 const validate_ts_1 = require("./validate.js");
+/** Second pass over the contracts the compiled-in registry did not recognise.
+ *
+ *  Each candidate's own interface is read off chain and every call it received
+ *  is checked against it; the ones that verify are fed back through the decoder
+ *  as known. Re-decoding rather than patching the first result keeps ONE code
+ *  path computing parseConfidence - a hand-adjusted count here would be a
+ *  second implementation of the gate, free to drift from the real one.
+ *
+ *  Only ever ADDS recognition. A missing spec, an unreachable RPC or a call the
+ *  interface does not describe all leave the recording exactly as it was. */
+async function resolveByOnChainSpec(input, decoded, redecode) {
+    if (input.resolveContractSpecs === false)
+        return decoded;
+    if (decoded.unknownContracts.length === 0)
+        return decoded;
+    const fetcher = input.specFetcher ??
+        (0, on_chain_spec_ts_1.specFetcherFromRpc)(rpc_ts_1.PUBLIC_RPC_URLS[input.network], input.network === 'mainnet' ? stellar_sdk_1.Networks.PUBLIC : stellar_sdk_1.Networks.TESTNET);
+    let resolved;
+    try {
+        resolved = await (0, on_chain_spec_ts_1.resolveContractsByOnChainSpec)(decoded.invocations, decoded.unknownContracts.map((u) => u.contract), fetcher);
+    }
+    catch {
+        // A lookup failure must not fail the recording that already succeeded.
+        return decoded;
+    }
+    return resolved.size === 0 ? decoded : redecode(resolved);
+}
 async function recordTransaction(input) {
     if (!input.network) {
         return err('RECORDING_FAILED', 'network required', false);
@@ -79,6 +108,7 @@ async function recordTransaction(input) {
                 return err('RECORDING_FAILED', e.message, false);
             throw e;
         }
+        decoded = await resolveByOnChainSpec(input, decoded, (known) => (0, decode_ts_1.decodeEnvelope)(fetched.envelopeXdr, events, [], fetched.ledger, known, input.network));
         return finish(input.network, decoded, input.confidenceOverride);
     }
     // XDR mode has no raw on-chain events, so the events-based cross-check is
@@ -96,6 +126,7 @@ async function recordTransaction(input) {
             return err('RECORDING_FAILED', e.message, false);
         return err('RECORDING_FAILED', `failed to decode base64 envelope XDR: ${e.message}`, false);
     }
+    decoded = await resolveByOnChainSpec(input, decoded, (known) => (0, decode_ts_1.decodeEnvelopeXdr)(xdrStr, [], [], 0, known, input.network));
     return finish(input.network, decoded, input.confidenceOverride);
 }
 function combineEvents(raw) {

package/dist-cjs/record/rpc.d.ts

@@ -14,6 +14,10 @@ export interface SorobanTxResponse {
     events: rpc.Api.TransactionEvents;
 }
 export type RpcFetcher = (hash: string) => Promise<SorobanTxResponse | null>;
+/** Exported so the on-chain spec lookup reads from the SAME endpoint the
+ *  recorder fetched the transaction from. Two different endpoints could
+ *  disagree about what a contract is. */
+export declare const PUBLIC_RPC_URLS: Record<Network, string>;
 /** Build a fetcher backed by the public Soroban RPC for the given network.
  *  Injectable by tests via the `fetcher` parameter to `recordTransaction`. */
 export declare function createRpcServer(network: Network): RpcFetcher;

package/dist-cjs/record/rpc.js

@@ -5,10 +5,14 @@
 // Unit tests inject a fetcher so they never hit the network; the integration test
 // uses the real Soroban RPC through `createRpcServer`.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PUBLIC_RPC_URLS = void 0;
 exports.createRpcServer = createRpcServer;
 exports.probeNetwork = probeNetwork;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
-const PUBLIC_RPC_URLS = {
+/** Exported so the on-chain spec lookup reads from the SAME endpoint the
+ *  recorder fetched the transaction from. Two different endpoints could
+ *  disagree about what a contract is. */
+exports.PUBLIC_RPC_URLS = {
     testnet: 'https://soroban-testnet.stellar.org',
     // The brief pins testnet; mainnet is left to the caller via injection. We keep
     // a public default that matches the brief's note ("e.g. https://mainnet.sorobanrpc.com").
@@ -17,7 +21,7 @@ const PUBLIC_RPC_URLS = {
 /** Build a fetcher backed by the public Soroban RPC for the given network.
  *  Injectable by tests via the `fetcher` parameter to `recordTransaction`. */
 function createRpcServer(network) {
-    const server = new stellar_sdk_1.rpc.Server(PUBLIC_RPC_URLS[network], { allowHttp: false });
+    const server = new stellar_sdk_1.rpc.Server(exports.PUBLIC_RPC_URLS[network], { allowHttp: false });
     return async (hash) => {
         const resp = await server.getTransaction(hash);
         if (resp.status === stellar_sdk_1.rpc.Api.GetTransactionStatus.NOT_FOUND) {
@@ -50,7 +54,7 @@ function createRpcServer(network) {
 /** Lightweight reachability probe used by the integration test to decide whether
  *  to run or self-skip. Sends a JSON-RPC `getHealth` to the public endpoint. */
 async function probeNetwork(network, timeoutMs = 3000) {
-    const url = PUBLIC_RPC_URLS[network];
+    const url = exports.PUBLIC_RPC_URLS[network];
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {

package/dist-cjs/registry/identify.d.ts

@@ -1,5 +1,5 @@
 import type { ScVal } from '../types.ts';
-import type { ProtocolId } from './protocols.ts';
+import type { AbiArg, ProtocolId } from './protocols.ts';
 export interface IdentifiedProtocol {
     protocol: ProtocolId;
     fn: string;
@@ -9,3 +9,12 @@ export interface IdentifiedProtocol {
  *  off, or unknown method on a pinned address). The caller MUST keep the
  *  null path fail-closed. */
 export declare function identifyProtocol(contract: string, method: string, args: ScVal[], network?: 'mainnet' | 'testnet'): IdentifiedProtocol | null;
+/** Compare the decoded args against the ABI signature. Returns true only when
+ *  the arg count matches AND every arg's ScVal subset type matches the ABI's
+ *  declared type. `other` is intentionally NOT a valid ABI match - it means
+ *  the decoder couldn't classify the value, which is exactly the signal
+ *  fail-closed should refuse. */
+/** Exported so the on-chain-spec path checks a call the SAME way a pinned
+ *  protocol does. Reimplementing it there would let the two drift, and a
+ *  looser copy would be the fail-OPEN direction. */
+export declare function argsMatchAbi(expected: AbiArg[], actual: ScVal[]): boolean;

package/dist-cjs/registry/identify.js

@@ -31,6 +31,7 @@
 // ScVal subset type against the ABI signature; mismatch -> null.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.identifyProtocol = identifyProtocol;
+exports.argsMatchAbi = argsMatchAbi;
 const known_addresses_ts_1 = require("./known-addresses.js");
 const protocols_ts_1 = require("./protocols.js");
 /** Identify the protocol for a single (contract, method, args) invocation.
@@ -91,6 +92,9 @@ function identifyProtocol(contract, method, args, network) {
  *  declared type. `other` is intentionally NOT a valid ABI match - it means
  *  the decoder couldn't classify the value, which is exactly the signal
  *  fail-closed should refuse. */
+/** Exported so the on-chain-spec path checks a call the SAME way a pinned
+ *  protocol does. Reimplementing it there would let the two drift, and a
+ *  looser copy would be the fail-OPEN direction. */
 function argsMatchAbi(expected, actual) {
     if (expected.length !== actual.length)
         return false;

package/dist-cjs/registry/on-chain-spec.d.ts

@@ -0,0 +1,37 @@
+import { contract as sdkContract } from '@stellar/stellar-sdk';
+import type { ContractInvocation } from '../types.ts';
+import type { AbiArgType, ProtocolAbi } from './protocols.ts';
+/** 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 declare function abiTypeFromSpecType(specTypeName: string): AbiArgType | null;
+/** The RPC surface this module needs. Narrowed to one method so a test can
+ *  supply a stub without standing up a server, and so the recorder's existing
+ *  RPC client can be passed straight in. */
+export interface SpecFetcher {
+    contractSpec(contractId: string): Promise<sdkContract.Spec | null>;
+}
+/** Build a `SpecFetcher` over the SDK's contract client. */
+export declare function specFetcherFromRpc(rpcUrl: string, networkPassphrase: string): SpecFetcher;
+/** 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 declare function abiFromSpec(spec: sdkContract.Spec): ProtocolAbi;
+/** Fetch and convert in one step. Returns null when no usable interface was
+ *  obtained, which the caller must treat as "unrecognised". */
+export declare function fetchContractAbi(contractId: string, fetcher: SpecFetcher): Promise<ProtocolAbi | null>;
+/** 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 declare function resolveContractsByOnChainSpec(invocations: ReadonlyArray<ContractInvocation>, candidates: ReadonlyArray<string>, fetcher: SpecFetcher): Promise<Set<string>>;

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

@@ -0,0 +1,159 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.abiTypeFromSpecType = abiTypeFromSpecType;
+exports.specFetcherFromRpc = specFetcherFromRpc;
+exports.abiFromSpec = abiFromSpec;
+exports.fetchContractAbi = fetchContractAbi;
+exports.resolveContractsByOnChainSpec = resolveContractsByOnChainSpec;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const identify_ts_1 = require("./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. */
+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. */
+function specFetcherFromRpc(rpcUrl, networkPassphrase) {
+    return {
+        async contractSpec(contractId) {
+            try {
+                const client = await stellar_sdk_1.contract.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. */
+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". */
+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. */
+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 && (0, identify_ts_1.argsMatchAbi)(entry.args, c.args);
+        });
+        if (everyCallVerifies)
+            resolved.add(contract);
+    }
+    return resolved;
+}

package/dist-cjs/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-cjs/run/index.js

@@ -18,20 +18,23 @@
 // No business logic. No retries. No session state. The same call shape can
 // drive the CLI (which calls into the same core directly without MCP).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolErrorSchema = exports.TESTNET_RPC_URL = exports.SynthesizePolicyInputSchema = exports.RPC_URL_BY_NETWORK = exports.RevokePolicyInputSchema = exports.RecordTransactionInputSchema = exports.RecordedTransactionSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.NetworkSchema = exports.MAINNET_RPC_URL = exports.InterpreterOptionsSchema = exports.InstallPolicyInputSchema = exports.GetInterpreterInfoInputSchema = exports.ComposeUserResponsesSchema = void 0;
+exports.ToolErrorSchema = exports.TESTNET_RPC_URL = exports.SynthesizePolicyInputSchema = exports.RPC_URL_BY_NETWORK = exports.RevokePolicyInputSchema = exports.RecordTransactionInputSchema = exports.RecordedTransactionSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.NetworkSchema = exports.MAINNET_RPC_URL = exports.InterpreterOptionsSchema = exports.InstallPolicyInputSchema = exports.GetInterpreterInfoInputSchema = exports.DeclarePolicyInputSchema = exports.ComposeUserResponsesSchema = void 0;
 exports.runRecordTransaction = runRecordTransaction;
 exports.runSynthesizePolicy = runSynthesizePolicy;
 exports.runInstallPolicy = runInstallPolicy;
 exports.runRevokePolicy = runRevokePolicy;
 exports.runSimulatePolicy = runSimulatePolicy;
+exports.runDeclarePolicy = runDeclarePolicy;
 exports.runVerifyPolicy = runVerifyPolicy;
 exports.runGetInterpreterInfo = runGetInterpreterInfo;
 exports.caughtError = caughtError;
 const node_crypto_1 = require("node:crypto");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const index_ts_1 = require("../index.js");
+const authority_overlap_ts_1 = require("../install/authority-overlap.js");
 const build_install_policy_ts_1 = require("../install/build-install-policy.js");
 const get_interpreter_info_ts_1 = require("../install/get-interpreter-info.js");
+const decode_ts_1 = require("../predicate/decode.js");
 const index_ts_2 = require("../simulate/index.js");
 const schemas_ts_1 = require("./schemas.js");
 // Re-export the underlying Zod schemas so the MCP package (and any other
@@ -40,6 +43,7 @@ const schemas_ts_1 = require("./schemas.js");
 // truth - MCP tool shapes are derived from them.
 var schemas_ts_2 = require("./schemas.js");
 Object.defineProperty(exports, "ComposeUserResponsesSchema", { enumerable: true, get: function () { return schemas_ts_2.ComposeUserResponsesSchema; } });
+Object.defineProperty(exports, "DeclarePolicyInputSchema", { enumerable: true, get: function () { return schemas_ts_2.DeclarePolicyInputSchema; } });
 Object.defineProperty(exports, "GetInterpreterInfoInputSchema", { enumerable: true, get: function () { return schemas_ts_2.GetInterpreterInfoInputSchema; } });
 Object.defineProperty(exports, "InstallPolicyInputSchema", { enumerable: true, get: function () { return schemas_ts_2.InstallPolicyInputSchema; } });
 Object.defineProperty(exports, "InterpreterOptionsSchema", { enumerable: true, get: function () { return schemas_ts_2.InterpreterOptionsSchema; } });
@@ -65,6 +69,7 @@ Object.defineProperty(exports, "ToolErrorSchema", { enumerable: true, get: funct
 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',
@@ -179,7 +184,27 @@ async function runInstallPolicy(raw) {
             rpc: rpcClient,
             ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
         });
-        return { ok: true, data: result };
+        // Cross-rule scan, when the caller supplied what else is on the account.
+        // ABSENT is reported as `null` rather than an empty list: "we did not
+        // look" and "we looked and found nothing" are different answers, and
+        // collapsing them would let a caller read silence as safety.
+        const authorityScan = input.existingRules === undefined
+            ? null
+            : (0, authority_overlap_ts_1.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: (0, decode_ts_1.decodePredicate)(encodedPredicate),
+                },
+                // The schema types `predicate` loosely (it is the shared
+                // PredicateNodeSchema); the shape is already validated.
+                existing: input.existingRules,
+            });
+        return { ok: true, data: { ...result, authorityScan } };
     }
     catch (e) {
         return toolFailure('install_policy', e);
@@ -298,6 +323,44 @@ 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. */
+function runDeclarePolicy(raw) {
+    const parsed = schemas_ts_1.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 } = (0, index_ts_1.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 } : {}),
+        });
+        const { encodedPredicate, predicateHash } = (0, index_ts_1.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.
  *