@crediolabs/policy-synth 0.2.0 → 0.3.1

package/src/run/index.ts

@@ -18,28 +18,19 @@
 // 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 { rpc } from '@stellar/stellar-sdk'
 import {
   type ErrorCode,
-  type MandateSpec,
   type Network,
-  type OzAdapterConfig,
   type PredicateNode,
   type ProposedPolicy,
-  placeholderOzConfig,
   type RecordedTransaction,
   recordTransaction,
   type SynthesizeFromRecordingOptions,
-  synthesizeFromMandate,
   synthesizeFromRecording,
   type ToolError,
   type ToolResponse,
 } from '../index.ts'
-import {
-  type AuthorityOverlap,
-  type ContextType,
-  findAuthorityOverlaps,
-} from '../install/authority-overlap.ts'
 import {
   type BuildInstallPolicyResult,
   type BuildRevokePolicyResult,
@@ -48,29 +39,17 @@ import {
   type InstallRpcClient,
   rpcClientFromServer,
 } from '../install/build-install-policy.ts'
-import { buildMergePolicyXdr } from '../install/build-merge-policy.ts'
 import { getInterpreterInfo } from '../install/get-interpreter-info.ts'
-import { planMergePolicy } from '../install/plan-merge-policy.ts'
-import {
-  accountRuleReaderFromServer,
-  collectObservedRules,
-  nonceLedgerKey,
-} from '../install/read-account-rules.ts'
-import { decodePredicate } from '../predicate/decode.ts'
-import { encodePredicate } from '../predicate/encode.ts'
-import type { SimulationResult } from '../verify/envelope.ts'
-import { simulatePolicy, verifyPolicy } from '../verify/index.ts'
+import { type EvalContext, evaluate, generateCases } from '../simulate/index.ts'
 import {
   type GetInterpreterInfoInput,
   GetInterpreterInfoInputSchema,
   type InstallPolicyInput,
   InstallPolicyInputSchema,
-  type MergePolicyInput,
-  MergePolicyInputSchema,
   NETWORK_PASSPHRASES,
   PINNED_INTERPRETER_ADDRESS_BY_NETWORK,
   PINNED_INTERPRETER_GRAMMAR_VERSION,
-  PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK,
+  PINNED_INTERPRETER_WASM_SHA256,
   type RecordTransactionInput,
   RecordTransactionInputSchema,
   type RevokePolicyInput,
@@ -103,26 +82,21 @@ export {
   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,
+  PINNED_INTERPRETER_WASM_SHA256,
   PredicateLeafSchema,
   PredicateNodeSchema,
   RecordedTransactionSchema,
   RecordTransactionInputSchema,
   RevokePolicyInputSchema,
   RPC_URL_BY_NETWORK,
-  SimulatePolicyInputSchema,
   SynthesizePolicyInputSchema,
   TESTNET_RPC_URL,
   ToolErrorSchema,
-  VerifyPolicyInputSchema,
 } from './schemas.ts'
 
 export type RunRecordTransactionInput = RecordTransactionInput
@@ -168,10 +142,7 @@ export async function runRecordTransaction(
 ): Promise<ToolResponse<RecordedTransaction>> {
   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: RecordTransactionInput = parsed.data
   // Strip the wire-only `confidenceOverride` and pass the rest straight through.
@@ -186,15 +157,11 @@ export async function runRecordTransaction(
   try {
     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
@@ -209,155 +176,37 @@ export async function runSynthesizePolicy(raw: unknown): Promise<
   ToolResponse<ProposedPolicy> & {
     explain?: {
       predicateTree: PredicateNode | null
-      simulation: SimulationResult
     }
   }
 > {
   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: OzAdapterConfig = 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 as MandateSpec,
-        ozConfig,
-        input.explain === true ? { explain: true } : {}
-      )
-    }
-    // recording source
     const recorded: RecordedTransaction = input.recordedTx as RecordedTransaction
-    return await synthesizeFromRecording(
-      recorded,
-      {
-        network: input.network,
-        ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
-        ...(input.confidenceOverride !== undefined
-          ? { confidenceOverride: input.confidenceOverride }
-          : {}),
-        ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
-        ...(input.explain === true ? { explain: true } : {}),
-      } as SynthesizeFromRecordingOptions,
-      ozConfig
-    )
-  } catch (e) {
-    return {
-      ok: false,
-      error: caughtError('synthesize_policy', 'SYNTHESIS_ERROR', e),
-    }
-  }
-}
-
-function resolveOzConfig(input: SynthesizePolicyInput): OzAdapterConfig {
-  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: unknown): Promise<ToolResponse<SimulationResult>> {
-  const parsed = SimulatePolicyInputSchema.safeParse(raw)
-  if (!parsed.success) {
-    return {
-      ok: false,
-      error: validationError('simulate_policy', parsed.error.issues),
-    }
-  }
-  const input: SimulatePolicyInput = 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 as PredicateNode | null,
-      input.permitTx as RecordedTransaction,
-      {
-        ...(input.validUntilLedger !== undefined
-          ? { validUntilLedger: input.validUntilLedger }
-          : {}),
-        ...(input.oraclePricesByAsset !== undefined
-          ? { oraclePricesByAsset: input.oraclePricesByAsset }
-          : {}),
-      }
-    )
-  } catch (e) {
-    return {
-      ok: false,
-      error: caughtError('simulate_policy', 'SIMULATION_ERROR', 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: unknown): Promise<ToolResponse<true>> {
-  const parsed = VerifyPolicyInputSchema.safeParse(raw)
-  if (!parsed.success) {
-    return {
-      ok: false,
-      error: validationError('verify_policy', parsed.error.issues),
-    }
-  }
-  const input: VerifyPolicyInput = 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 as PredicateNode, input.permitTx as RecordedTransaction, {
-      ...(input.validUntilLedger !== undefined ? { validUntilLedger: input.validUntilLedger } : {}),
-      ...(input.oraclePricesByAsset !== undefined
-        ? { oraclePricesByAsset: input.oraclePricesByAsset }
+    return await synthesizeFromRecording(recorded, {
+      network: input.network,
+      ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
+      ...(input.confidenceOverride !== undefined
+        ? { confidenceOverride: input.confidenceOverride }
         : {}),
-    })
+      ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
+      ...(input.explain === true ? { explain: true } : {}),
+    } as SynthesizeFromRecordingOptions)
   } catch (e) {
-    return {
-      ok: false,
-      error: caughtError('verify_policy', 'VERIFICATION_FAILED', e),
-    }
+    return toolFailure('synthesize_policy', 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: unknown): Promise<ToolResponse<InstallPolicyResult>> {
+export async function runInstallPolicy(
+  raw: unknown
+): Promise<ToolResponse<BuildInstallPolicyResult>> {
   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: InstallPolicyInput = parsed.data
   const network: Network = input.network ?? 'testnet'
@@ -386,10 +235,7 @@ export async function runInstallPolicy(raw: unknown): Promise<ToolResponse<Insta
   try {
     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')
@@ -397,27 +243,6 @@ export async function runInstallPolicy(raw: unknown): Promise<ToolResponse<Insta
     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: AuthorityScanReport | undefined = 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,
@@ -429,349 +254,9 @@ export async function runInstallPolicy(raw: unknown): Promise<ToolResponse<Insta
       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: AuthorityScanReport | undefined,
-  allowOverlap: boolean | undefined
-): ToolError | null {
-  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
-}
-
-/** The install response, plus what the cross-rule scan found. The scan is
- *  advisory data about the account, not part of the transaction, so it is
- *  additive: a caller that ignores it gets exactly the previous shape. */
-export type InstallPolicyResult = BuildInstallPolicyResult & {
-  authorityScan?: AuthorityScanReport
-}
-
-/** What the cross-rule scan found, carried on the install response so the
- *  review surface can show it alongside the transaction being signed.
- *
- *  SCOPE, and it is narrow: this answers "can a signer OF THIS RULE reach the
- *  same calls through a different rule". A rule sharing no signer with this
- *  one cannot be reached by this rule's signers, so it is not a way around
- *  this policy; it is a different principal's authority, which no policy
- *  installed here was ever going to constrain. Other rules keep their own
- *  signers, and an account administrator can add signers or rules afterwards.
- *
- *  An empty `overlaps` is therefore NOT a statement that the account is safe,
- *  only that this rule's own signers gain no unconstrained path through the
- *  rules that exist right now. */
-export interface AuthorityScanReport {
-  /** False when the scan did not run. `reason` then says why, and the absence
-   *  of overlaps proves nothing. */
-  ran: boolean
-  /** True when the caller passed `skipAuthorityScan`. Distinguishes a
-   *  deliberate skip from a scan that tried and failed: both carry
-   *  `ran: false`, but only the failure refuses the install. Recorded rather
-   *  than omitted so the response shows that no opinion was formed, instead
-   *  of looking like a version that never had the check. */
-  skipped?: boolean
-  /** True when the account has more rules than the scan accounted for, so the
-   *  overlap list is a subset. */
-  incomplete?: boolean
-  reason?: string
-  overlaps: AuthorityOverlap[]
-}
-
-/** 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: {
-  smartAccount: string
-  interpreterAddress: string
-  rule: InstallPolicyInput['rule']
-  encodedPredicate: string
-  rpcUrl: string
-  network: Network
-}): Promise<AuthorityScanReport | undefined> {
-  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: InstallPolicyInput['rule']['contextRuleType']): ContextType {
-  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' }
-  }
-}
-
-/** The merge response: one step's transaction plus what it will cost. */
-export interface MergePolicyResult {
-  unsignedXdr: string
-  smartAccount: string
-  sourceAccount: string
-  step: 'detach' | 'reinstall'
-  call: { contract: string; fn: string; ruleId: number }
-  authNonce: string
-  authValidUntilLedger: number
-  rootInvocationXdr: string
-  /** sha256 of the merged predicate, so the caller can pin what step 2 will
-   *  install while they are still looking at step 1. */
-  mergedPredicateHash: string
-  mergedPredicateBlobBase64: string
-  warnings: string[]
-  followUp: string
-}
-
-/** `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: unknown): Promise<ToolResponse<MergePolicyResult>> {
-  const parsed = MergePolicyInputSchema.safeParse(raw)
-  if (!parsed.success) {
-    return { ok: false, error: validationError('install_policy', parsed.error.issues) }
-  }
-  const input: MergePolicyInput = parsed.data
-  const network: 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: string[] = []
-    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)
   }
 }
 
@@ -789,10 +274,7 @@ export async function runRevokePolicy(
 ): Promise<ToolResponse<BuildRevokePolicyResult>> {
   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: RevokePolicyInput = parsed.data
   const network: Network = input.network ?? 'testnet'
@@ -811,10 +293,7 @@ export async function runRevokePolicy(
   try {
     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({
@@ -827,10 +306,7 @@ export async function runRevokePolicy(
     })
     return { ok: true, data: result }
   } catch (e) {
-    return {
-      ok: false,
-      error: caughtError('revoke_policy', 'REVOKE_BUILD_FAILED', e),
-    }
+    return toolFailure('revoke_policy', e)
   }
 }
 
@@ -841,27 +317,126 @@ export async function runRevokePolicy(
  *  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. */
+/** 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: RecordedTransaction): EvalContext | null {
+  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: 'simulate_policy' | 'verify_policy'): ToolError {
+  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: unknown): ToolResponse<{
+  permitted: boolean
+  reason: string | null
+  call: { contract: string; fn: string; argCount: number }
+}> {
+  const parsed = SimulatePolicyInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return { ok: false, error: validationError('simulate_policy', parsed.error.issues) }
+  }
+  const input: SimulatePolicyInput = parsed.data
+  const ctx = evalContextFromRecording(input.permitTx as RecordedTransaction)
+  if (!ctx) return { ok: false, error: noInvocationError('simulate_policy') }
+  try {
+    const res = evaluate(input.predicate as PredicateNode, ctx)
+    return {
+      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: unknown): ToolResponse<{
+  ok: boolean
+  permit: { permitted: boolean; reason: string | null }
+  denies: Array<{ dimension: string; denied: boolean; reason: string | null }>
+  dimensionsCovered: number
+}> {
+  const parsed = VerifyPolicyInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return { ok: false, error: validationError('verify_policy', parsed.error.issues) }
+  }
+  const input: VerifyPolicyInput = parsed.data
+  const ctx = evalContextFromRecording(input.permitTx as RecordedTransaction)
+  if (!ctx) return { ok: false, error: noInvocationError('verify_policy') }
+  try {
+    const predicate = input.predicate as PredicateNode
+    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: unknown
 ): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>> {
   const parsed = GetInterpreterInfoInputSchema.safeParse(raw)
   if (!parsed.success) {
-    return {
-      ok: false,
-      error: validationError('get_interpreter_info', parsed.error.issues),
-    }
+    return { ok: false, error: validationError('get_interpreter_info', parsed.error.issues) }
   }
   const input: GetInterpreterInfoInput = parsed.data
   const network: Network = input.network ?? 'testnet'
@@ -894,16 +469,13 @@ export async function runGetInterpreterInfo(
     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)
   }
 }
 
@@ -969,14 +541,8 @@ function enforceRpcPin(
   network: Network
 ): ToolError | null {
   if (!rpcUrl || rpcUrl === expectedRpc || allowUnpinned === true) return null
-  const code: ErrorCode =
-    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,
@@ -1008,6 +574,12 @@ function validationError(
  *  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: RunToolName, e: unknown): { ok: false; error: ToolError } {
+  return { ok: false, error: caughtError(toolName, TOOL_ERROR_CODE[toolName], e) }
+}
+
 export function caughtError(toolName: RunToolName, code: ErrorCode, e: unknown): ToolError {
   return {
     code,