@crediolabs/policy-synth 0.1.11 → 0.1.13

package/src/install/get-interpreter-info.ts

@@ -0,0 +1,68 @@
+// src/install/get-interpreter-info.ts - read-only fingerprint lookup for
+// the interpreter contract.
+//
+// Returns the pinned deployment fingerprint + (optionally) compares a
+// caller-supplied live `grammar_version` against the pin. No fabricated
+// audit field; a real deployed-contract check is worth more than a fake
+// reference.
+//
+// Per design decision 5: phase-04's "audit #44" is aspirational and has no
+// source-of-truth in the repo. Returning a fabricated audit id would be a
+// lie on a security surface. The honest outputs are:
+//   - the pinned address (DEPLOYMENTS.md)
+//   - the pinned grammar version (SELF_VERSION in version.rs)
+//   - the pinned wasm sha256 (DEPLOYMENTS.md)
+//   - an OPTIONAL `deployedGrammarVersion` returned by a live `grammar_version()`
+//     RPC call, with a `liveMatchesPin` boolean the caller can dispatch on. A
+//     mismatch means the deployed wasm is NOT the pinned artifact - the caller
+//     should refuse to install until they redeploy.
+//
+// The RPC plumbing lives in the run layer (`run/index.ts`); this module
+// stays pure so it is testable without a network.
+
+import type { Network } from '../types.ts'
+
+export interface InterpreterInfo {
+  /** Pinned interpreter contract address. */
+  pinnedAddress: string
+  /** Pinned grammar version (matches SELF_VERSION in version.rs). */
+  pinnedGrammarVersion: number
+  /** Pinned wasm sha256 (hex). */
+  pinnedWasmHash: string
+  /** Network this pin applies to (the address + hash are network-scoped). */
+  network: Network
+  /** Present only when the caller supplied a live `deployedGrammarVersion`. */
+  deployedGrammarVersion?: number
+  /** True when `deployedGrammarVersion` matches `pinnedGrammarVersion`.
+   *  Absent when no live verification was performed. */
+  liveMatchesPin?: boolean
+}
+
+/** Build the interpreter-info response. When `deployedGrammarVersion` is
+ *  supplied (after a live RPC `grammar_version()` call by the run layer),
+ *  compares it to the pin and sets `liveMatchesPin`. When absent, returns
+ *  the pin alone. */
+export function getInterpreterInfo(args: {
+  pinnedAddress: string
+  pinnedGrammarVersion: number
+  pinnedWasmHash: string
+  network: Network
+  /** When supplied, the u32 returned by the live contract's
+   *  `grammar_version()` RPC call. */
+  deployedGrammarVersion?: number
+}): InterpreterInfo {
+  const info: InterpreterInfo = {
+    pinnedAddress: args.pinnedAddress,
+    pinnedGrammarVersion: args.pinnedGrammarVersion,
+    pinnedWasmHash: args.pinnedWasmHash,
+    network: args.network,
+  }
+  if (typeof args.deployedGrammarVersion === 'number') {
+    return {
+      ...info,
+      deployedGrammarVersion: args.deployedGrammarVersion,
+      liveMatchesPin: args.deployedGrammarVersion === args.pinnedGrammarVersion,
+    }
+  }
+  return info
+}

package/src/ir/types.ts

@@ -86,6 +86,25 @@ export type IRCondition =
    *  does. Adapters that cannot express an exact ordered vector (OZ built-ins)
    *  flag this as `uncovered` rather than silently dropping it. */
   | { op: 'eq_seq'; selector: IRSelector; values: string[] }
+  /** A swap's output floor, expressed against its own input: the output arg
+   *  must be at least `inArgIndex * num / den`.
+   *
+   *  It is its own construct because `compare` bounds a selector against a
+   *  CONSTANT, and a slippage floor has no constant to bound against - the
+   *  acceptable output depends on the input of the same call. Encoding the
+   *  recorded output as a constant would pin a policy to one trade size.
+   *
+   *  `num/den` is the caller's minimum acceptable output per unit of input.
+   *  It is never derived from the recording: the recorded rate is a price at
+   *  one moment, and freezing it as policy would deny normal trades later.
+   *  Adapters that cannot express it (the OZ built-ins) flag it `uncovered`. */
+  | {
+      op: 'slippage_floor'
+      outArgIndex: number
+      inArgIndex: number
+      num: string
+      den: string
+    }
 
 export interface IRPolicyRule {
   /** NEAR-V2 roles whitelist (empty = any; owner exempt). */

package/src/predicate/index.ts

@@ -2,6 +2,6 @@
 // untrusted-JSON parser that feeds it. A consumer accepting a hand-written
 // policy needs both halves.
 
-export { type EncodedPredicate, encodePredicate } from './encode.ts'
 export { decodeLeaf, decodeNode, decodePredicate } from './decode.ts'
+export { type EncodedPredicate, encodePredicate } from './encode.ts'
 export { jsonToAst } from './from-json.ts'

package/src/review-card/builder.ts

@@ -222,6 +222,33 @@ function renderComparison(
     return `At most ${allowed} calls per ${left.windowSecs} seconds`
   }
 
+  // OP(call_arg[i], <scalar literal>) -> arg[i] OP <value>
+  //
+  // The per-call cap. It has to be here because the `amount` template below
+  // is unreachable for an interpreter policy: `amount` is deliberately not in
+  // the contract's grammar (dsl.rs - the interpreter sees one authorized
+  // call, not the transaction's token movements), so a predicate using it is
+  // refused at install. A bound on the call's own amount ARGUMENT is how a
+  // cap is actually written, and it was rendering nothing at all - the card
+  // silently understated the policy.
+  //
+  // Placed after the literal_vec case above so an exact-sequence `eq` still
+  // reads as a path rather than as a comparison.
+  if (left.kind === 'call_arg') {
+    const head = `arg[${left.index}]`
+    const sep = node.op === 'eq' ? '=' : comparisonOpText(node.op)
+    if (right.kind === 'literal_i128') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_u64') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_u32') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_address') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_symbol') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_bytes') return `${head} ${sep} ${right.value}`
+    // call_arg_scaled is the slippage floor and reads as itself.
+    if (right.kind === 'call_arg_scaled') {
+      return `${head} >= arg[${right.index}] * ${right.num}/${right.den}`
+    }
+  }
+
   // amount <= v -> Amount <= v
   if (left.kind === 'amount' && right.kind === 'literal_i128') {
     return `Amount <= ${right.value}`

package/src/review-card/cross-check.ts

@@ -125,12 +125,36 @@ function pushComparison(
     out.push(`At most ${allowed} calls per ${left.windowSecs} seconds`)
     return
   }
+  // Mirrors the builder's per-call cap line. Both sides must render the same
+  // string: cross-check compares the summary against the predicate, so a
+  // shape only ONE of them renders would read as a dropped constraint.
+  if (left.kind === 'call_arg') {
+    const head = `arg[${left.index}]`
+    const sep = op === 'eq' ? '=' : comparisonOpText(op)
+    if (
+      right.kind === 'literal_i128' ||
+      right.kind === 'literal_u64' ||
+      right.kind === 'literal_u32' ||
+      right.kind === 'literal_address' ||
+      right.kind === 'literal_symbol' ||
+      right.kind === 'literal_bytes'
+    ) {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'call_arg_scaled') {
+      out.push(`${head} >= arg[${right.index}] * ${right.num}/${right.den}`)
+      return
+    }
+  }
   if (left.kind === 'amount' && right.kind === 'literal_i128') {
     out.push(`Amount <= ${right.value}`)
     return
   }
   if (left.kind === 'oracle_price' && right.kind === 'oracle_threshold') {
-    out.push(`Only when oracle_price(${left.asset}) ${comparisonOpText(op)} ${right.value} (${right.decimals} dp)`)
+    out.push(
+      `Only when oracle_price(${left.asset}) ${comparisonOpText(op)} ${right.value} (${right.decimals} dp)`
+    )
     return
   }
 }

package/src/run/index.ts

@@ -17,9 +17,12 @@
 // 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 } from '@stellar/stellar-sdk'
 import {
   type ErrorCode,
   type MandateSpec,
+  type Network,
   type OzAdapterConfig,
   type PredicateNode,
   type ProposedPolicy,
@@ -32,35 +35,83 @@ import {
   type ToolError,
   type ToolResponse,
 } from '../index.ts'
+import {
+  type BuildInstallPolicyResult,
+  type BuildRevokePolicyResult,
+  buildInstallPolicyXdr,
+  buildRevokePolicyXdr,
+  type InstallRpcClient,
+  rpcClientFromServer,
+} from '../install/build-install-policy.ts'
+import { getInterpreterInfo } from '../install/get-interpreter-info.ts'
 import type { SimulationResult } from '../verify/envelope.ts'
+import { simulatePolicy, verifyPolicy } from '../verify/index.ts'
 import {
+  type GetInterpreterInfoInput,
+  GetInterpreterInfoInputSchema,
+  type InstallPolicyInput,
+  InstallPolicyInputSchema,
+  NETWORK_PASSPHRASES,
+  PINNED_INTERPRETER_GRAMMAR_VERSION,
+  PINNED_INTERPRETER_TESTNET_ADDRESS,
+  PINNED_INTERPRETER_WASM_SHA256,
   type RecordTransactionInput,
   RecordTransactionInputSchema,
+  type RevokePolicyInput,
+  RevokePolicyInputSchema,
+  type SimulatePolicyInput,
+  SimulatePolicyInputSchema,
   type SynthesizePolicyInput,
   SynthesizePolicyInputSchema,
+  TESTNET_RPC_URL,
+  type VerifyPolicyInput,
+  VerifyPolicyInputSchema,
 } from './schemas.ts'
 
-export type { RecordTransactionInput, SynthesizePolicyInput } from './schemas.ts'
+export type {
+  GetInterpreterInfoInput,
+  InstallPolicyInput,
+  RecordTransactionInput,
+  RevokePolicyInput,
+  SimulatePolicyInput,
+  SynthesizePolicyInput,
+  VerifyPolicyInput,
+} from './schemas.ts'
 // 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,
   MandateSpecSchema,
   NetworkSchema,
+  OraclePriceFixtureSchema,
   OzAdapterConfigSchema,
+  PINNED_INTERPRETER_GRAMMAR_VERSION,
+  PINNED_INTERPRETER_TESTNET_ADDRESS,
+  PINNED_INTERPRETER_WASM_SHA256,
+  PredicateLeafSchema,
+  PredicateNodeSchema,
   RecordedTransactionSchema,
   RecordTransactionInputSchema,
+  RevokePolicyInputSchema,
+  SimulatePolicyInputSchema,
   SynthesizePolicyInputSchema,
   ToolErrorSchema,
+  VerifyPolicyInputSchema,
 } from './schemas.ts'
 
 export type RunRecordTransactionInput = RecordTransactionInput
 
 export type RunSynthesizePolicyInput = SynthesizePolicyInput
 
+export type RunSimulatePolicyInput = SimulatePolicyInput
+
+export type RunVerifyPolicyInput = VerifyPolicyInput
+
 /** `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.
@@ -173,14 +224,353 @@ function resolveOzConfig(input: SynthesizePolicyInput): OzAdapterConfig {
   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 }
+        : {}),
+    })
+  } 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).
+ *  Per design decision 4, only CALL 1 (account.add_context_rule) is
+ *  emitted; CALL 2 (interpreter.install) requires the rule id the account
+ *  assigns in call 1 and is documented under `followUp` in the response.
+ *
+ *  Default-deny: an interpreter policy address other than the pinned
+ *  testnet interpreter 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. */
+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),
+    }
+  }
+  const input: InstallPolicyInput = parsed.data
+  // ---- Pinning gates (default-deny) ----
+  const pinningError = enforceInterpreterPin(input.rule.policies, input.allowUnpinnedInterpreter)
+  if (pinningError) {
+    return { ok: false, error: pinningError }
+  }
+  if (input.rpcUrl && input.rpcUrl !== TESTNET_RPC_URL && input.allowUnpinnedRpcUrl !== true) {
+    return {
+      ok: false,
+      error: {
+        code: 'INSTALL_BUILD_FAILED',
+        message: `install_policy: rpcUrl must equal the pinned TESTNET_RPC_URL; set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
+        severity: 'error',
+        retryable: false,
+        remediation: { toolCall: { name: 'install_policy', args: {} } },
+      },
+    }
+  }
+  let rpcClient: InstallRpcClient
+  try {
+    rpcClient = buildRpcClientFromInput(input.rpcUrl)
+  } catch (e) {
+    return {
+      ok: false,
+      error: caughtError('install_policy', 'INSTALL_BUILD_FAILED', e),
+    }
+  }
+  try {
+    const interpreterPolicy = input.rule.policies.find((p) => p.kind === 'interpreter')
+    const encodedPredicate = interpreterPolicy?.predicateBlobBase64 ?? ''
+    const predicateHash = createHash('sha256')
+      .update(Buffer.from(encodedPredicate, 'base64'))
+      .digest('hex')
+    const result = await buildInstallPolicyXdr({
+      smartAccount: input.smartAccount,
+      sourceAccount: input.sourceAccount,
+      networkPassphrase: NETWORK_PASSPHRASES.testnet,
+      rule: input.rule,
+      installNonce: input.installNonce,
+      encodedPredicate,
+      predicateHash,
+      rpc: rpcClient,
+      ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
+    })
+    return { ok: true, data: result }
+  } catch (e) {
+    return {
+      ok: false,
+      error: caughtError('install_policy', 'INSTALL_BUILD_FAILED', e),
+    }
+  }
+}
+
+/** `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
+ *  is master-only; the source account MUST be the master signer set.
+ *
+ *  Same RPC pin as install: a non-pinned `rpcUrl` is refused unless
+ *  `allowUnpinnedRpcUrl: true`. Revoke does not carry an interpreter
+ *  policy payload, so the interpreter pin is not re-checked here. */
+export async function runRevokePolicy(
+  raw: unknown
+): Promise<ToolResponse<BuildRevokePolicyResult>> {
+  const parsed = RevokePolicyInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: validationError('revoke_policy', parsed.error.issues),
+    }
+  }
+  const input: RevokePolicyInput = parsed.data
+  if (input.rpcUrl && input.rpcUrl !== TESTNET_RPC_URL && input.allowUnpinnedRpcUrl !== true) {
+    return {
+      ok: false,
+      error: {
+        code: 'REVOKE_BUILD_FAILED',
+        message: `revoke_policy: rpcUrl must equal the pinned TESTNET_RPC_URL; set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
+        severity: 'error',
+        retryable: false,
+        remediation: { toolCall: { name: 'revoke_policy', args: {} } },
+      },
+    }
+  }
+  let rpcClient: InstallRpcClient
+  try {
+    rpcClient = buildRpcClientFromInput(input.rpcUrl)
+  } catch (e) {
+    return {
+      ok: false,
+      error: caughtError('revoke_policy', 'REVOKE_BUILD_FAILED', e),
+    }
+  }
+  try {
+    const result = await buildRevokePolicyXdr({
+      smartAccount: input.smartAccount,
+      sourceAccount: input.sourceAccount,
+      ruleId: input.ruleId,
+      networkPassphrase: NETWORK_PASSPHRASES.testnet,
+      rpc: rpcClient,
+      ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
+    })
+    return { ok: true, data: result }
+  } catch (e) {
+    return {
+      ok: false,
+      error: caughtError('revoke_policy', 'REVOKE_BUILD_FAILED', e),
+    }
+  }
+}
+
+/** `get_interpreter_info` body - thin wrapper over `getInterpreterInfo`.
+ *  Returns the pinned deployment fingerprint + an optional live
+ *  `grammar_version()` comparison. The audit field is deliberately
+ *  OMITTED (phase-04's "audit #44" has no source of truth in the repo -
+ *  fabricating it would be a lie on a security surface; the live
+ *  mismatch check is worth MORE). */
+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),
+    }
+  }
+  const input: GetInterpreterInfoInput = parsed.data
+  const network: Network = input.network ?? 'testnet'
+  // Asking about mainnet used to return the TESTNET pin with `network:
+  // 'mainnet'` stamped on it. DEPLOYMENTS.md:3 says plainly "Testnet only.
+  // Nothing is deployed to mainnet yet", so that answer described a contract
+  // that does not exist at an address that is not on that network. This tool
+  // exists to tell a caller what they are installing against; inventing a
+  // mainnet deployment is the same failure as inventing an audit reference.
+  if (network === 'mainnet') {
+    return {
+      ok: false,
+      error: {
+        code: 'RECORDING_FAILED',
+        message:
+          'get_interpreter_info: no interpreter is deployed to mainnet. The pinned address and wasm hash are testnet-only; mainnet deployment is gated on the interpreter audit.',
+        severity: 'error',
+        retryable: false,
+        remediation: {
+          toolCall: { name: 'get_interpreter_info', args: { network: 'testnet' } },
+        },
+      },
+    }
+  }
+  try {
+    let deployedGrammarVersion: number | undefined
+    if (input.verifyLive === true) {
+      const rpcClient = buildRpcClientFromInput(input.rpcUrl)
+      deployedGrammarVersion = await rpcClient.getContractVersion(
+        PINNED_INTERPRETER_TESTNET_ADDRESS
+      )
+    }
+    const info = getInterpreterInfo({
+      pinnedAddress: PINNED_INTERPRETER_TESTNET_ADDRESS,
+      pinnedGrammarVersion: PINNED_INTERPRETER_GRAMMAR_VERSION,
+      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),
+    }
+  }
+}
+
+/** Build an InstallRpcClient from an optional URL override, falling back
+ *  to the public testnet RPC (matching the design-decision rule that we
+ *  reuse `record/rpc.ts` and never hard-code a different RPC client). */
+function buildRpcClientFromInput(urlOverride?: string): InstallRpcClient {
+  if (urlOverride) {
+    return rpcClientFromServer(
+      new rpc.Server(urlOverride, { allowHttp: false }),
+      NETWORK_PASSPHRASES.testnet
+    )
+  }
+  // Default: public testnet RPC. Matches the brief; the mainnet pin would
+  // need a separate deploy and is out of scope for this tool.
+  //
+  // NOT `createRpcServer` - that returns an RpcFetcher, a bare
+  // `(hash) => Promise<SorobanTxResponse|null>` for the RECORDER. Passing it
+  // here produced a client whose `getAccount` was undefined, so every live
+  // call died with "server.getAccount is not a function". The install path
+  // needs the full Server surface.
+  return rpcClientFromServer(
+    new rpc.Server(TESTNET_RPC_URL, { allowHttp: false }),
+    NETWORK_PASSPHRASES.testnet
+  )
+}
+
+/** Default-deny: refuse any interpreter policy whose address differs from
+ *  the pinned testnet interpreter. An interpreter the caller controls
+ *  can permit anything, so the smart account's authorization must bind
+ *  to the pinned contract unless the caller explicitly opts in via
+ *  `allowUnpinnedInterpreter`. OZ built-in policies are not interpreters
+ *  and pass through unchanged. Returns a ToolError to surface through
+ *  the run-layer envelope, or null when the policies are all pinned. */
+function enforceInterpreterPin(
+  policies: InstallPolicyInput['rule']['policies'],
+  allowUnpinned: boolean | undefined
+): ToolError | null {
+  for (const p of policies) {
+    if (p.kind !== 'interpreter') continue
+    if (p.interpreterAddress === PINNED_INTERPRETER_TESTNET_ADDRESS) continue
+    if (allowUnpinned === true) continue
+    return {
+      code: 'INSTALL_BUILD_FAILED',
+      message: `install_policy: interpreter policy address ${p.interpreterAddress} != pinned ${PINNED_INTERPRETER_TESTNET_ADDRESS}; set allowUnpinnedInterpreter: true to opt in to a non-pinned interpreter`,
+      severity: 'error',
+      retryable: false,
+      remediation: { toolCall: { name: 'install_policy', args: {} } },
+    }
+  }
+  return null
+}
+
 /** Build a canonical ToolError for a Zod validation failure. The remediation
  *  hint points the agent back at the right tool with an empty arg bag - the
  *  tool name IS the machine-readable hint. */
 function validationError(
-  toolName: 'record_transaction' | 'synthesize_policy',
+  toolName:
+    | 'record_transaction'
+    | 'synthesize_policy'
+    | 'simulate_policy'
+    | 'verify_policy'
+    | 'install_policy'
+    | 'revoke_policy'
+    | 'get_interpreter_info',
   issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>
 ): ToolError {
-  const code: ErrorCode = toolName === 'record_transaction' ? 'RECORDING_FAILED' : 'SYNTHESIS_ERROR'
+  const code: ErrorCode =
+    toolName === 'record_transaction'
+      ? 'RECORDING_FAILED'
+      : toolName === 'synthesize_policy'
+        ? 'SYNTHESIS_ERROR'
+        : toolName === 'simulate_policy'
+          ? 'SIMULATION_ERROR'
+          : toolName === 'verify_policy'
+            ? 'VERIFICATION_FAILED'
+            : toolName === 'install_policy'
+              ? 'INSTALL_BUILD_FAILED'
+              : toolName === 'revoke_policy'
+                ? 'REVOKE_BUILD_FAILED'
+                : 'RECORDING_FAILED'
   return {
     code,
     message: `${toolName}: invalid input: ${issues
@@ -206,7 +596,14 @@ function validationError(
  *  seam) so the suite in run/index.test.ts can drive the envelope path
  *  without standing up a full recordTransaction pipeline. */
 export function caughtError(
-  toolName: 'record_transaction' | 'synthesize_policy',
+  toolName:
+    | 'record_transaction'
+    | 'synthesize_policy'
+    | 'simulate_policy'
+    | 'verify_policy'
+    | 'install_policy'
+    | 'revoke_policy'
+    | 'get_interpreter_info',
   code: ErrorCode,
   e: unknown
 ): ToolError {
@@ -270,8 +667,11 @@ function safeStringify(v: unknown): string {
     (_k, value) => {
       if (typeof value === 'bigint') return value.toString()
       if (typeof value === 'function') return `[function ${value.name || 'anonymous'}]`
+      // `stack` is a server-controlled diagnostic. Stack traces from a host
+      // we do not own are reconnaissance, not a signal the caller can act on.
+      // Surface `name` + `message` only.
       if (value instanceof Error) {
-        return { name: value.name, message: value.message, stack: value.stack }
+        return { name: value.name, message: value.message }
       }
       if (value !== null && typeof value === 'object') {
         if (seen.has(value)) return '[Circular]'