@crediolabs/policy-synth 0.2.0 → 0.3.0

package/dist/run/index.js

@@ -17,23 +17,17 @@
 // 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).
 import { createHash } from 'node:crypto';
-import { rpc, xdr } from '@stellar/stellar-sdk';
-import { placeholderOzConfig, recordTransaction, synthesizeFromMandate, synthesizeFromRecording, } from "../index.js";
-import { findAuthorityOverlaps, } from "../install/authority-overlap.js";
+import { rpc } from '@stellar/stellar-sdk';
+import { recordTransaction, synthesizeFromRecording, } from "../index.js";
 import { buildInstallPolicyXdr, buildRevokePolicyXdr, rpcClientFromServer, } from "../install/build-install-policy.js";
-import { buildMergePolicyXdr } from "../install/build-merge-policy.js";
 import { getInterpreterInfo } from "../install/get-interpreter-info.js";
-import { planMergePolicy } from "../install/plan-merge-policy.js";
-import { accountRuleReaderFromServer, collectObservedRules, nonceLedgerKey, } from "../install/read-account-rules.js";
-import { decodePredicate } from "../predicate/decode.js";
-import { encodePredicate } from "../predicate/encode.js";
-import { simulatePolicy, verifyPolicy } from "../verify/index.js";
-import { GetInterpreterInfoInputSchema, InstallPolicyInputSchema, MergePolicyInputSchema, NETWORK_PASSPHRASES, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, VerifyPolicyInputSchema, } from "./schemas.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";
 // 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, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, VerifyPolicyInputSchema, } from "./schemas.js";
+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";
 /** 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. */
@@ -60,10 +54,7 @@ const TOOL_ERROR_CODE = {
 export async function runRecordTransaction(raw) {
     const parsed = RecordTransactionInputSchema.safeParse(raw);
     if (!parsed.success) {
-        return {
-            ok: false,
-            error: validationError('record_transaction', parsed.error.issues),
-        };
+        return { ok: false, error: validationError('record_transaction', parsed.error.issues) };
     }
     const input = parsed.data;
     // Strip the wire-only `confidenceOverride` and pass the rest straight through.
@@ -79,14 +70,10 @@ export async function runRecordTransaction(raw) {
         return await recordTransaction(coreInput);
     }
     catch (e) {
-        return {
-            ok: false,
-            error: caughtError('record_transaction', 'RECORDING_FAILED', e),
-        };
+        return toolFailure('record_transaction', e);
     }
 }
 /** `synthesize_policy` body - discriminated union on `source`:
- *    - `mandate`   -> synthesizeFromMandate
  *    - `recording` -> synthesizeFromRecording
  *  Exposing BOTH front-ends through ONE tool keeps the MCP surface tiny while
  *  letting the agent pick the deterministic or the inferred path. The CLI
@@ -100,21 +87,10 @@ export async function runRecordTransaction(raw) {
 export async function runSynthesizePolicy(raw) {
     const parsed = SynthesizePolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
-        return {
-            ok: false,
-            error: validationError('synthesize_policy', parsed.error.issues),
-        };
+        return { ok: false, error: validationError('synthesize_policy', parsed.error.issues) };
     }
     const input = parsed.data;
-    const ozConfig = resolveOzConfig(input);
     try {
-        if (input.source === 'mandate') {
-            // Zod's optional fields widen to `T | undefined`, which the core's
-            // exact-optional MandateSpec rejects; the schema already validated the
-            // shape, so assert it (same pattern as the recordedTx cast below).
-            return await synthesizeFromMandate(input.mandate, ozConfig, input.explain === true ? { explain: true } : {});
-        }
-        // recording source
         const recorded = input.recordedTx;
         return await synthesizeFromRecording(recorded, {
             network: input.network,
@@ -124,112 +100,16 @@ export async function runSynthesizePolicy(raw) {
                 : {}),
             ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
             ...(input.explain === true ? { explain: true } : {}),
-        }, ozConfig);
-    }
-    catch (e) {
-        return {
-            ok: false,
-            error: caughtError('synthesize_policy', 'SYNTHESIS_ERROR', e),
-        };
-    }
-}
-function resolveOzConfig(input) {
-    if (input.ozConfig)
-        return input.ozConfig;
-    // The mandate path is network-agnostic; fall back to mainnet so the
-    // placeholder OZ instance addresses are deterministic.
-    return placeholderOzConfig('mainnet');
-}
-/** `simulate_policy` body - thin wrapper over `simulatePolicy`. The engine
- *  already returns fail-closed `{ok:false, error}` for runtime failures
- *  (SIMULATION_ERROR), so the try/catch envelope is for raw SDK throws
- *  only - same pattern as the other two wrappers. The predicate is
- *  passed inline (stateless by design; no `proposed_policy_id` lookup). */
-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;
-    try {
-        // The recursive PredicateNodeSchema + ContractInvocationSchema are
-        // typed `z.ZodType<unknown>` to survive TS's circular inference; the
-        // engine wants typed `PredicateNode | null` + `RecordedTransaction`.
-        // The schema already validated the shape, so assert through the
-        // unknown back to the core types. Same pattern as the recordedTx
-        // cast in `runSynthesizePolicy`.
-        return simulatePolicy(input.predicate, input.permitTx, {
-            ...(input.validUntilLedger !== undefined
-                ? { validUntilLedger: input.validUntilLedger }
-                : {}),
-            ...(input.oraclePricesByAsset !== undefined
-                ? { oraclePricesByAsset: input.oraclePricesByAsset }
-                : {}),
         });
     }
     catch (e) {
-        return {
-            ok: false,
-            error: caughtError('simulate_policy', 'SIMULATION_ERROR', e),
-        };
+        return toolFailure('synthesize_policy', e);
     }
 }
-/** `verify_policy` body - thin wrapper over `verifyPolicy`. The engine
- *  already returns `{ok:false, error}` with code VERIFICATION_FAILED when
- *  the minimality check fails; the try/catch envelope is for raw SDK
- *  throws only. Mirrors `runSimulatePolicy` exactly. */
-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;
-    try {
-        // Same cast as runSimulatePolicy: the recursive schemas are typed
-        // `unknown`; the engine wants typed `PredicateNode` +
-        // `RecordedTransaction`. The schema already validated the shape.
-        return verifyPolicy(input.predicate, input.permitTx, {
-            ...(input.validUntilLedger !== undefined ? { validUntilLedger: input.validUntilLedger } : {}),
-            ...(input.oraclePricesByAsset !== undefined
-                ? { oraclePricesByAsset: input.oraclePricesByAsset }
-                : {}),
-        });
-    }
-    catch (e) {
-        return {
-            ok: false,
-            error: caughtError('verify_policy', 'VERIFICATION_FAILED', e),
-        };
-    }
-}
-/** `install_policy` body - thin wrapper over `buildInstallPolicyXdr`.
- *  Returns the unsigned Soroban transaction envelope (base64 XDR) the
- *  wallet signs. The wallet signature IS the user-confirmation step - no
- *  `action_id` two-call pair (the server is stateless, see server.ts:10-12).
- *  One call installs the policy outright: `add_context_rule` carries the
- *  predicate to the interpreter in its `policies` install_param, so no
- *  separate `interpreter.install` call is needed or possible.
- *
- *  Default-deny: an interpreter policy address other than the pinned
- *  interpreter for the selected network is REFUSED (the smart account
- *  would delegate to an interpreter the caller controls); the same
- *  applies to a non-pinned RPC URL (the auth nonce the wallet signs
- *  comes from the RPC). Both gates accept an explicit opt-in flag.
- *  Pin selection follows `input.network` (defaults to `testnet` so the
- *  pre-mainnet callers keep working unchanged). */
 export async function runInstallPolicy(raw) {
     const parsed = InstallPolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
-        return {
-            ok: false,
-            error: validationError('install_policy', parsed.error.issues),
-        };
+        return { ok: false, error: validationError('install_policy', parsed.error.issues) };
     }
     const input = parsed.data;
     const network = input.network ?? 'testnet';
@@ -249,10 +129,7 @@ export async function runInstallPolicy(raw) {
         rpcClient = buildRpcClientFromInput(input.rpcUrl, network);
     }
     catch (e) {
-        return {
-            ok: false,
-            error: caughtError('install_policy', 'INSTALL_BUILD_FAILED', e),
-        };
+        return toolFailure('install_policy', e);
     }
     try {
         const interpreterPolicy = input.rule.policies.find((p) => p.kind === 'interpreter');
@@ -260,25 +137,6 @@ export async function runInstallPolicy(raw) {
         const predicateHash = createHash('sha256')
             .update(Buffer.from(encodedPredicate, 'base64'))
             .digest('hex');
-        // ---- Cross-rule authority scan ----
-        // OZ enforces only the policies of the rule the caller names, so a signer
-        // who also sits in a wider rule keeps that wider authority no matter what
-        // this predicate says. Refuse by default when the wider rule has no policy
-        // at all, because that makes this install decorative.
-        const authorityScan = input.skipAuthorityScan
-            ? { ran: false, skipped: true, reason: 'skipped at caller request', overlaps: [] }
-            : await scanAuthorityOverlap({
-                smartAccount: input.smartAccount,
-                interpreterAddress: expectedInterpreter,
-                rule: input.rule,
-                encodedPredicate,
-                rpcUrl: input.rpcUrl ?? expectedRpc,
-                network,
-            });
-        const overlapError = enforceAuthorityScan(authorityScan, input.allowAuthorityOverlap);
-        if (overlapError) {
-            return { ok: false, error: overlapError };
-        }
         const result = await buildInstallPolicyXdr({
             smartAccount: input.smartAccount,
             sourceAccount: input.sourceAccount,
@@ -290,259 +148,10 @@ export async function runInstallPolicy(raw) {
             rpc: rpcClient,
             ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
         });
-        return { ok: true, data: authorityScan ? { ...result, authorityScan } : result };
-    }
-    catch (e) {
-        return {
-            ok: false,
-            error: caughtError('install_policy', 'INSTALL_BUILD_FAILED', e),
-        };
-    }
-}
-/** Default-deny on the cross-rule scan.
- *
- *  Refuses whenever the scan cannot establish that this policy binds the calls
- *  it names. An unpoliced neighbour provably does not constrain them. An
- *  opaque one, policed by a contract this tool cannot decode, is not KNOWN to,
- *  and "not known to" is not "safe" - the same posture as the interpreter and
- *  RPC pins. An incomplete scan is refused for the same reason: the overlap
- *  list is then a subset of the account, so an empty list proves nothing.
- *
- *  `not-restricting` is reported but does NOT block. Both rules are ours and
- *  both constrain the calls, and the conjunction remedy is offered; refusing
- *  there would also block the legitimate act of adding a separate capability,
- *  which OZ composes correctly as a union.
- *
- *  Returns a ToolError or null, matching `enforceInterpreterPin`. */
-export function enforceAuthorityScan(scan, allowOverlap) {
-    if (!scan || allowOverlap === true)
-        return null;
-    // Default-deny by exclusion rather than by enumeration: anything that is not
-    // the one known-safe severity blocks. Listing the blocking severities
-    // instead would mean a severity added later silently passes until someone
-    // remembers to add it here, and the safe direction is the opposite.
-    const blocking = scan.overlaps.filter((o) => o.severity !== 'not-restricting');
-    const unpoliced = blocking.filter((o) => o.severity === 'bypass').map((o) => o.ruleId);
-    const opaque = blocking.filter((o) => o.severity === 'unknown').map((o) => o.ruleId);
-    const unrecognised = blocking
-        .filter((o) => o.severity !== 'bypass' && o.severity !== 'unknown')
-        .map((o) => o.ruleId);
-    if (blocking.length > 0) {
-        const parts = [
-            unpoliced.length > 0 ? `rule ${unpoliced.join(', ')} has no policy attached` : '',
-            opaque.length > 0
-                ? `rule ${opaque.join(', ')} is policed by a contract this tool cannot decode`
-                : '',
-            unrecognised.length > 0
-                ? `rule ${unrecognised.join(', ')} carries an overlap this build does not recognise`
-                : '',
-        ].filter(Boolean);
-        return {
-            code: 'INSTALL_BUILD_FAILED',
-            message: `install_policy: a signer of this rule can already make the same calls through another context rule, so this policy is not established to restrict them: ${parts.join('; ')}. Remove the shared signer from that rule, attach a policy this tool can read, or set allowAuthorityOverlap: true to install anyway`,
-            severity: 'error',
-            retryable: false,
-            remediation: { toolCall: { name: 'install_policy', args: {} } },
-        };
-    }
-    // A scan that was meant to run and threw tells us nothing. Reporting it in
-    // a string field and proceeding is the same fail-open shape as an incomplete
-    // scan, and a caller that does not read `ran` cannot tell it from a clean
-    // result.
-    if (scan.ran === false && scan.skipped !== true) {
-        return {
-            code: 'INSTALL_BUILD_FAILED',
-            message: `install_policy: the cross-rule authority scan could not run (${scan.reason ?? 'unknown error'}), so it cannot establish that this policy restricts anything; retry, or set allowAuthorityOverlap: true to install without that assurance`,
-            severity: 'error',
-            retryable: true,
-            remediation: { toolCall: { name: 'install_policy', args: {} } },
-        };
-    }
-    if (scan.incomplete === true) {
-        return {
-            code: 'INSTALL_BUILD_FAILED',
-            message: 'install_policy: the account has more context rules than the scan could account for, so the overlap result is incomplete and cannot establish that this policy restricts anything; set allowAuthorityOverlap: true to install without that assurance',
-            severity: 'error',
-            retryable: false,
-            remediation: { toolCall: { name: 'install_policy', args: {} } },
-        };
-    }
-    return null;
-}
-/** Read the account's other context rules and report where this install's
- *  signers already hold authority over the same calls.
- *
- *  A failure to read is reported rather than thrown, and the caller-facing
- *  decision is made by `enforceAuthorityScan`: a scan that tried and failed
- *  tells us nothing, so it refuses rather than passing as a clean account.
- *
- *  The account data this trusts comes from whichever RPC answered, so a
- *  hostile RPC could describe an account with no overlapping rules. That is
- *  bounded by the pin already enforced above: `enforceRpcPin` returns before
- *  this runs, so the URL is the pinned one for the network unless the caller
- *  explicitly set `allowUnpinnedRpcUrl`. This scan deliberately does not add a
- *  second pin check, because two places deciding the same thing drift. */
-async function scanAuthorityOverlap(args) {
-    try {
-        if (!args.encodedPredicate) {
-            // Not applicable rather than failed: this rule installs no interpreter
-            // predicate, so there is nothing of ours for another rule to undercut.
-            // Returning undefined keeps it out of the refusal path, which is
-            // reserved for scans that were meant to run and could not.
-            return undefined;
-        }
-        const server = new rpc.Server(args.rpcUrl, { allowHttp: false });
-        const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[args.network]);
-        const collected = await collectObservedRules({
-            reader,
-            smartAccount: args.smartAccount,
-            interpreterAddress: args.interpreterAddress,
-        });
-        const overlaps = findAuthorityOverlaps({
-            intended: {
-                // `add_context_rule` always creates a NEW rule, so there is no id to
-                // exclude; -1 matches nothing on the account.
-                ruleId: -1,
-                contextType: toOverlapContextType(args.rule.contextRuleType),
-                signers: args.rule.signers,
-                predicate: decodePredicate(args.encodedPredicate),
-            },
-            existing: collected.rules,
-        });
-        return { ran: true, incomplete: collected.incomplete, overlaps };
-    }
-    catch (e) {
-        return {
-            ran: false,
-            reason: e instanceof Error ? e.message : String(e),
-            overlaps: [],
-        };
-    }
-}
-/** The rule draft names the callee `contract`; the analyser calls it
- *  `address`. Same value, two vocabularies. */
-function toOverlapContextType(ct) {
-    switch (ct.kind) {
-        case 'call_contract':
-            return { kind: 'call_contract', address: ct.contract };
-        case 'create_contract':
-            return { kind: 'create_contract', wasmHash: ct.wasmHash };
-        default:
-            return { kind: 'default' };
-    }
-}
-/** `merge_policy` body - the tightening remedy for a cross-rule overlap.
- *
- *  Replaces a rule's predicate with the conjunction of it and a new one. This
- *  is the action `install_policy` recommends when it reports an overlap
- *  between two rules our interpreter polices, and it is deliberately NOT
- *  something `install_policy` does on its own: it detaches a live policy, so
- *  the operator has to ask for it.
- *
- *  Two transactions in order. `add_policy` refuses a policy already on the
- *  rule, so the old attachment goes first, and the second transaction cannot
- *  be simulated until the first confirms. */
-export async function runMergePolicy(raw) {
-    const parsed = MergePolicyInputSchema.safeParse(raw);
-    if (!parsed.success) {
-        return { ok: false, error: validationError('install_policy', parsed.error.issues) };
-    }
-    const input = parsed.data;
-    const network = input.network ?? 'testnet';
-    const expectedInterpreter = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network];
-    const expectedRpc = RPC_URL_BY_NETWORK[network];
-    const rpcPinningError = enforceRpcPin('install_policy', input.rpcUrl, input.allowUnpinnedRpcUrl, expectedRpc, network);
-    if (rpcPinningError)
-        return { ok: false, error: rpcPinningError };
-    try {
-        const rpcUrl = input.rpcUrl ?? expectedRpc;
-        const server = new rpc.Server(rpcUrl, { allowHttp: false });
-        const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network]);
-        const collected = await collectObservedRules({
-            reader,
-            smartAccount: input.smartAccount,
-            interpreterAddress: expectedInterpreter,
-        });
-        const rule = collected.rules.find((r) => r.id === input.ruleId);
-        if (!rule) {
-            return {
-                ok: false,
-                error: {
-                    code: 'INSTALL_BUILD_FAILED',
-                    message: `merge_policy: rule ${input.ruleId} was not found on ${input.smartAccount}${collected.incomplete
-                        ? ' (the rule scan was incomplete, so it may exist but was not reached)'
-                        : ''}`,
-                    severity: 'error',
-                    retryable: false,
-                    remediation: { toolCall: { name: 'install_policy', args: {} } },
-                },
-            };
-        }
-        const plan = planMergePolicy({
-            rule,
-            interpreterAddress: expectedInterpreter,
-            incoming: decodePredicate(input.incomingPredicateBlobBase64),
-            step: input.step,
-        });
-        if (!plan.ok) {
-            return {
-                ok: false,
-                error: {
-                    code: 'INSTALL_BUILD_FAILED',
-                    message: `merge_policy: ${plan.reason}`,
-                    severity: 'error',
-                    retryable: false,
-                    remediation: { toolCall: { name: 'install_policy', args: {} } },
-                },
-            };
-        }
-        const encoded = encodePredicate(plan.predicate);
-        // The nonce is read, not assumed. OZ's `remove_policy` discards the result
-        // of `try_uninstall`, so a detach whose uninstall panicked - our
-        // `uninstall` panics MissingState when the master set has been archived -
-        // detaches the policy while leaving our nonce behind. Re-installing at 1
-        // would then be refused as a replay and the rule would sit unpoliced.
-        let installNonce = 1;
-        const nonceWarnings = [];
-        if (input.step === 'reinstall') {
-            const entries = await server.getLedgerEntries(nonceLedgerKey(expectedInterpreter, input.smartAccount, input.ruleId));
-            const raw = entries.entries?.[0]?.val;
-            const stored = raw && raw.switch() === xdr.LedgerEntryType.contractData()
-                ? raw.contractData().val()
-                : undefined;
-            if (stored && stored.switch() === xdr.ScValType.scvU32()) {
-                installNonce = stored.u32() + 1;
-                nonceWarnings.push(`the previous uninstall did not complete: rule ${input.ruleId} still holds interpreter state at nonce ${stored.u32()}, so this reinstalls at ${installNonce} rather than 1. The rule's counters were NOT reset.`);
-            }
-        }
-        const built = await buildMergePolicyXdr({
-            smartAccount: input.smartAccount,
-            sourceAccount: input.sourceAccount,
-            networkPassphrase: NETWORK_PASSPHRASES[network],
-            ruleId: input.ruleId,
-            policyId: plan.policyId,
-            interpreterAddress: expectedInterpreter,
-            step: input.step,
-            encodedPredicate: encoded.encodedPredicate,
-            predicateHash: encoded.predicateHash,
-            installNonce,
-            ...(plan.oracleParams ? { oracleParams: plan.oracleParams } : {}),
-            rpc: rpcClientFromServer(server, NETWORK_PASSPHRASES[network]),
-            ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
-        });
-        return {
-            ok: true,
-            data: {
-                ...built,
-                mergedPredicateHash: encoded.predicateHash,
-                mergedPredicateBlobBase64: encoded.encodedPredicate,
-                warnings: [...plan.warnings, ...nonceWarnings],
-                followUp: plan.followUp,
-            },
-        };
+        return { ok: true, data: result };
     }
     catch (e) {
-        return { ok: false, error: caughtError('install_policy', 'INSTALL_BUILD_FAILED', e) };
+        return toolFailure('install_policy', e);
     }
 }
 /** `revoke_policy` body - thin wrapper over `buildRevokePolicyXdr`.
@@ -557,10 +166,7 @@ export async function runMergePolicy(raw) {
 export async function runRevokePolicy(raw) {
     const parsed = RevokePolicyInputSchema.safeParse(raw);
     if (!parsed.success) {
-        return {
-            ok: false,
-            error: validationError('revoke_policy', parsed.error.issues),
-        };
+        return { ok: false, error: validationError('revoke_policy', parsed.error.issues) };
     }
     const input = parsed.data;
     const network = input.network ?? 'testnet';
@@ -574,10 +180,7 @@ export async function runRevokePolicy(raw) {
         rpcClient = buildRpcClientFromInput(input.rpcUrl, network);
     }
     catch (e) {
-        return {
-            ok: false,
-            error: caughtError('revoke_policy', 'REVOKE_BUILD_FAILED', e),
-        };
+        return toolFailure('revoke_policy', e);
     }
     try {
         const result = await buildRevokePolicyXdr({
@@ -591,10 +194,7 @@ export async function runRevokePolicy(raw) {
         return { ok: true, data: result };
     }
     catch (e) {
-        return {
-            ok: false,
-            error: caughtError('revoke_policy', 'REVOKE_BUILD_FAILED', e),
-        };
+        return toolFailure('revoke_policy', e);
     }
 }
 /** `get_interpreter_info` body - thin wrapper over `getInterpreterInfo`.
@@ -604,26 +204,117 @@ export async function runRevokePolicy(raw) {
  *  fabricating it would be a lie on a security surface; the live
  *  mismatch check is worth MORE).
  *
- *  Network-aware: `input.network` selects the interpreter address, the RPC
- *  and the wasm hash. The networks run different binaries - testnet carries
- *  the selector-leaf minimum and the signer-set cap, mainnet predates both -
- *  so the hash is read through
- *  `PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK`. UNAUDITED at the time of
- *  writing.
+ *  Network-aware: `input.network` selects which interpreter pin and RPC
+ *  to use. Mainnet was rolled out 2026-08-04 - the same wasm hash was
+ *  uploaded to mainnet as was exercised on testnet, so a single
+ *  `PINNED_INTERPRETER_WASM_SHA256` constant backs both networks.
+ *  The address differs because instance ids are network-scoped.
+ *  UNAUDITED at the time of writing.
  *
  *  Same RPC pin as install/revoke: when `verifyLive` triggers an outbound
  *  call, the auth-digest + the answer bind to whichever RPC answered, so
  *  a non-pinned `rpcUrl` would silently bind the caller to a host they
  *  picked. The pin is enforced here too, with the same `allowUnpinnedRpcUrl`
  *  opt-in as install/revoke. */
-export async function runGetInterpreterInfo(raw) {
-    const parsed = GetInterpreterInfoInputSchema.safeParse(raw);
+/** The call a predicate is evaluated against: the single top-level invocation
+ *  the smart account authorises. `Policy::enforce` receives one `Context`, not
+ *  a sub-invocation tree, so simulating anything deeper would claim a
+ *  guarantee the contract does not make. */
+function evalContextFromRecording(tx) {
+    const top = tx.invocations[0];
+    if (!top)
+        return null;
+    return { contract: top.contract, fn: top.fn, args: top.args };
+}
+/** Both `simulate_policy` and `verify_policy` evaluate against a context derived
+ *  from `permitTx`; neither has anything to evaluate when the recording carries
+ *  no top-level invocation. */
+function noInvocationError(toolName) {
+    return {
+        code: TOOL_ERROR_CODE[toolName],
+        message: `${toolName}: permitTx carries no invocation to evaluate`,
+        severity: 'error',
+        retryable: false,
+    };
+}
+/** `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) {
+    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);
+    if (!ctx)
+        return { ok: false, error: noInvocationError('simulate_policy') };
+    try {
+        const res = evaluate(input.predicate, ctx);
         return {
-            ok: false,
-            error: validationError('get_interpreter_info', parsed.error.issues),
+            ok: true,
+            data: {
+                permitted: res.permit,
+                reason: res.permit ? null : res.reason,
+                call: { contract: ctx.contract, fn: ctx.fn, argCount: ctx.args.length },
+            },
         };
     }
+    catch (e) {
+        return toolFailure('simulate_policy', e);
+    }
+}
+/** `verify_policy` body - the permit case plus a generated deny case per
+ *  dimension.
+ *
+ *  Two failure modes are being checked, and they are not the same thing. A
+ *  permit case that denies means the policy is too STRICT: it would refuse the
+ *  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) {
+    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);
+    if (!ctx)
+        return { ok: false, error: noInvocationError('verify_policy') };
+    try {
+        const predicate = input.predicate;
+        const cases = generateCases(predicate, ctx);
+        const permitRes = evaluate(predicate, cases.permit);
+        const denies = cases.denies.map((d) => {
+            const r = evaluate(predicate, d.ctx);
+            return {
+                dimension: d.dimension,
+                denied: !r.permit,
+                reason: r.permit ? null : r.reason,
+            };
+        });
+        return {
+            ok: true,
+            data: {
+                ok: permitRes.permit && denies.every((d) => d.denied),
+                permit: { permitted: permitRes.permit, reason: permitRes.permit ? null : permitRes.reason },
+                denies,
+                dimensionsCovered: denies.length,
+            },
+        };
+    }
+    catch (e) {
+        return toolFailure('verify_policy', e);
+    }
+}
+export async function runGetInterpreterInfo(raw) {
+    const parsed = GetInterpreterInfoInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, error: validationError('get_interpreter_info', parsed.error.issues) };
+    }
     const input = parsed.data;
     const network = input.network ?? 'testnet';
     const expectedRpc = RPC_URL_BY_NETWORK[network];
@@ -649,17 +340,14 @@ export async function runGetInterpreterInfo(raw) {
         const info = getInterpreterInfo({
             pinnedAddress,
             pinnedGrammarVersion: PINNED_INTERPRETER_GRAMMAR_VERSION,
-            pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK[network],
+            pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256,
             network,
             ...(deployedGrammarVersion !== undefined ? { deployedGrammarVersion } : {}),
         });
         return { ok: true, data: info };
     }
     catch (e) {
-        return {
-            ok: false,
-            error: caughtError('get_interpreter_info', 'RECORDING_FAILED', e),
-        };
+        return toolFailure('get_interpreter_info', e);
     }
 }
 /** Build an InstallRpcClient from an optional URL override + selected
@@ -713,13 +401,8 @@ function enforceInterpreterPin(policies, allowUnpinned, expectedInterpreterAddre
 function enforceRpcPin(toolName, rpcUrl, allowUnpinned, expectedRpc, network) {
     if (!rpcUrl || rpcUrl === expectedRpc || allowUnpinned === true)
         return null;
-    const code = toolName === 'install_policy'
-        ? 'INSTALL_BUILD_FAILED'
-        : toolName === 'revoke_policy'
-            ? 'REVOKE_BUILD_FAILED'
-            : 'RECORDING_FAILED';
     return {
-        code,
+        code: TOOL_ERROR_CODE[toolName],
         message: `${toolName}: rpcUrl must equal the pinned ${expectedRpc} (${network}); set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
         severity: 'error',
         retryable: false,
@@ -746,6 +429,11 @@ function validationError(toolName, issues) {
  *  error in `details` for the agent to inspect. Exported as a test-only seam
  *  so the suite in run/index.test.ts can drive the envelope path without
  *  standing up a full recordTransaction pipeline. */
+/** The fail-closed return every tool body uses in its `catch`. Taking only the
+ *  tool name keeps the tool -> error-code mapping in TOOL_ERROR_CODE alone. */
+function toolFailure(toolName, e) {
+    return { ok: false, error: caughtError(toolName, TOOL_ERROR_CODE[toolName], e) };
+}
 export function caughtError(toolName, code, e) {
     return {
         code,