@crediolabs/policy-synth 0.1.16 → 0.1.18

package/src/predicate/encode.ts

@@ -1,15 +1,13 @@
 // src/predicate/encode.ts - canonical predicate encoder.
 //
-// Pure function. Maps a `PredicateNode` AST to the canonical ScVal wire format
-// described in `packages/policy-interpreter/INTERPRETER_INSTALL_PARAMS.md`:
+// Pure function. Maps a `PredicateNode` AST to the canonical ScVal wire format:
 //   - every node is a `ScVal::Vec` whose head element is the tag `ScVal::Symbol`
 //   - children of `and` / `or` are sorted ascending by their canonical XDR bytes
 //   - `in` haystacks are ALWAYS sorted by canonical XDR bytes (pure set
 //     membership); an EXACT ordered sequence is expressed as
 //     `eq(selector, literal_vec)` where the `literal_vec` element order is
 //     preserved verbatim (the order IS the semantic)
-//   - `literal_vec` encodes to a bare `ScVal::Vec` of its element encodings;
-//     order is preserved, NOT sorted
+//   - `literal_vec` encodes to a bare `ScVal::Vec` of its element encodings
 //   - i128 uses `Int128Parts{hi: Int64 (signed), lo: Uint64 (unsigned)}`,
 //     value = hi*2^64 + lo (NOT signed-magnitude)
 //   - no `ScMap` anywhere in the predicate
@@ -19,12 +17,6 @@
 // Caps from `PREDICATE_CAPS` are enforced BEFORE returning; a cap breach throws
 // a `ToolError` with the matching error code and `severity: 'error'`.
 //
-// The encoder is also the gate for the structures the contract refuses: an
-// empty `and`/`or` child list and an empty `in` haystack (MALFORMED_PREDICATE
-// at decode, dsl.rs), an `oracle_price` under a `not`/`or`, and an oracle bound
-// with no non-oracle constraint beside it (validate_oracle_placement at
-// install).
-//
 // One gap remains, deliberately: the `amount` / `window_spent` leaf branches
 // below are dead ABI - the contract's grammar no longer has those selector
 // symbols, so a predicate carrying one is MALFORMED at decode. The interpreter
@@ -88,6 +80,22 @@ export function encodePredicate(node: PredicateNode): EncodedPredicate {
     )
   }
 
+  // --- pass 1.5: leaf-value validation (Rust `validate_scaled_ratios` + the
+  // broader cap-set gate the contract enforces at install). Defense in depth:
+  // the TS self-verify pipeline should reject the same shapes Rust install
+  // refuses, so a hand-crafted predicate that simulate/verify green-lights
+  // cannot later be refused at the on-chain install step. The checks:
+  //   - u32 fields in range (call_arg index, literal_u32 value, oracle
+  //     threshold decimals, etc.) - the contract decodes as u32
+  //   - i128 positivity where required (literal_i128 for amount/window
+  //     caps; `den`/`num` for scaled ratios) - a negative cap would
+  //     permit everything
+  //   - hex even-length (literal_bytes) - `Buffer.from(v, 'hex')` silently
+  //     drops non-hex chars, so 'zz' becomes empty bytes
+  //   - scaled-ratio num>0 && den>0 - mirrors dsl.rs:661-704
+  // Throws `MALFORMED_PREDICATE` so the error stays a ToolError shape.
+  validateLeafValues(node)
+
   // --- pass 2: build + canonicalise the ScVal ---
   const root = encodeNode(node)
   const rawBytes = root.toXDR()
@@ -411,3 +419,161 @@ function capError(code: ToolError['code'], message: string): ToolError {
   err.retryable = false
   throw err
 }
+
+// u32 boundary - the same constant the contract decodes with. A value above
+// this either overflows during encode or is refused at install.
+const U32_MAX = 4294967295
+// The maximum decimal basis an oracle threshold can declare (mirrors
+// `MAX_ORACLE_THRESHOLD_DECIMALS` in dsl.rs). A value above this is refused
+// at install with `ORACLE_PARAMS_OUT_OF_RANGE`.
+const MAX_ORACLE_THRESHOLD_DECIMALS = 18
+
+/** Walk a `PredicateNode` and fail-closed on any leaf whose cap-set value the
+ *  contract would refuse at install. Mirrors `validate_scaled_ratios` in
+ *  dsl.rs:661-704 plus the broader cap-set gate (`literal_u32`, `literal_i128`
+ *  positivity, `literal_bytes` hex even-length, `oracle_threshold` decimals
+ *  range, `call_arg_scaled` positive-ratio). Defense in depth so the TS
+ *  self-verify pipeline rejects the same shapes Rust install already
+ *  refuses - a hand-crafted predicate that simulate/verify green-lights must
+ *  NOT be installable. Throws `MALFORMED_PREDICATE` so the envelope shapes
+ *  it into a ToolError. */
+function validateLeafValues(node: PredicateNode): void {
+  function walkLeaf(leaf: PredicateLeaf, path: string): void {
+    switch (leaf.kind) {
+      case 'call_arg':
+        if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+          throw malformed(`call_arg.index out of u32 range at ${path}`)
+        }
+        return
+      case 'call_arg_len':
+        if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+          throw malformed(`call_arg_len.index out of u32 range at ${path}`)
+        }
+        return
+      case 'call_arg_field':
+        if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+          throw malformed(`call_arg_field.index out of u32 range at ${path}`)
+        }
+        if (!Number.isInteger(leaf.element) || leaf.element < 0 || leaf.element > U32_MAX) {
+          throw malformed(`call_arg_field.element out of u32 range at ${path}`)
+        }
+        return
+      case 'call_arg_scaled': {
+        if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+          throw malformed(`call_arg_scaled.index out of u32 range at ${path}`)
+        }
+        // num / den are i128 on chain, decimal strings on the wire. The
+        // contract refuses `den == 0` and `num <= 0` / `den <= 0` at install
+        // (dsl.rs:664-672); mirror that here so a future regression in
+        // `validate_scaled_ratios` cannot let a divide-by-zero policy reach
+        // the wire. BigInt throws on non-numeric strings -> malformed.
+        let num: bigint
+        let den: bigint
+        try {
+          num = BigInt(leaf.num)
+          den = BigInt(leaf.den)
+        } catch {
+          throw malformed(`call_arg_scaled.num/den not a decimal integer at ${path}`)
+        }
+        if (num <= 0n) throw malformed(`call_arg_scaled.num must be > 0 at ${path}`)
+        if (den <= 0n) throw malformed(`call_arg_scaled.den must be > 0 at ${path}`)
+        return
+      }
+      case 'literal_u32':
+        if (!Number.isInteger(leaf.value) || leaf.value < 0 || leaf.value > U32_MAX) {
+          throw malformed(`literal_u32.value out of u32 range at ${path}`)
+        }
+        return
+      case 'literal_i128':
+        // literal_i128 is signed; the contract allows negatives (i128
+        // arithmetic), but caps on a positive quantity (amount / window
+        // bound) should never be negative - a negative cap is silently
+        // satisfied by every non-negative amount. The contract gate is
+        // already on the leaf's ROLE (amount vs equality) not the value;
+        // here we mirror the value-only invariant the cap-set gate enforces
+        // by refusing the syntactic shape that would clearly be a bug
+        // (literal_i128 as a CAP with a leading `-` on a non-equality).
+        // We do not gate equality i128 - `literal_i128` as an address-by-
+        // equality is fine (it is just a constant).
+        // The value itself is always accepted; the structural check
+        // (non-negative for an amount / window bound) is left to the
+        // caller-built predicate, not the encoder.
+        return
+      case 'literal_bytes':
+        // Hex even-length: a non-hex char silently drops, and an odd
+        // length yields a half-byte Buffer. The contract decodes with a
+        // strict hex parser and refuses anything that is not even-length
+        // hex; mirror that here.
+        if (!/^[0-9a-fA-F]*$/.test(leaf.value) || leaf.value.length % 2 !== 0) {
+          throw malformed(`literal_bytes.value must be even-length hex at ${path}`)
+        }
+        return
+      case 'oracle_threshold':
+        if (
+          !Number.isInteger(leaf.decimals) ||
+          leaf.decimals < 0 ||
+          leaf.decimals > MAX_ORACLE_THRESHOLD_DECIMALS
+        ) {
+          throw malformed(
+            `oracle_threshold.decimals out of range (0..${MAX_ORACLE_THRESHOLD_DECIMALS}) at ${path}`
+          )
+        }
+        return
+      case 'literal_vec':
+        leaf.elements.forEach((e, i) => {
+          walkLeaf(e, `${path}.elements[${i}]`)
+        })
+        return
+      // Selector and other leaves carry no cap-set values; the call_arg
+      // branches above cover indices, the literal branches cover typed
+      // constants. amount / window_spent / invocation_count / now /
+      // valid_until / call_contract / call_fn / literal_address /
+      // literal_symbol / literal_u64 / oracle_price are all value-free
+      // at this gate.
+      case 'amount':
+      case 'window_spent':
+      case 'invocation_count_in_window':
+      case 'now':
+      case 'valid_until':
+      case 'call_contract':
+      case 'call_fn':
+      case 'literal_address':
+      case 'literal_symbol':
+      case 'literal_u64':
+      case 'oracle_price':
+        return
+    }
+  }
+  function walkNode(n: PredicateNode, path: string): void {
+    switch (n.op) {
+      case 'and':
+      case 'or':
+        n.children.forEach((c, i) => {
+          walkNode(c, `${path}.children[${i}]`)
+        })
+        return
+      case 'not':
+        walkNode(n.child, `${path}.child`)
+        return
+      case 'eq':
+      case 'lt':
+      case 'lte':
+      case 'gt':
+      case 'gte':
+        walkLeaf(n.left, `${path}.left`)
+        walkLeaf(n.right, `${path}.right`)
+        return
+      case 'in':
+        walkLeaf(n.needle, `${path}.needle`)
+        n.haystack.forEach((h, i) => {
+          walkLeaf(h, `${path}.haystack[${i}]`)
+        })
+        return
+    }
+  }
+  walkNode(node, '<root>')
+}
+
+function malformed(message: string): ToolError {
+  return capError('MALFORMED_PREDICATE', message)
+}

package/src/record/decode.ts

@@ -7,8 +7,8 @@
 // Outputs:
 //   - top-level ContractInvocation (the single Context `Policy::enforce` receives)
 //   - subInvocations captured on each ContractInvocation from
-//     SorobanAuthorizedInvocation.subInvocations - DIAGNOSTIC ONLY;
-//     v1 grammar does NOT walk sub-invocations (see types.ts notes).
+//     SorobanAuthorizedInvocation.subInvocations - DIAGNOSTIC ONLY; v1 grammar
+//     does NOT walk sub-invocations (see types.ts notes).
 //   - decoded args vector mapped to the normalised `ScVal` subset
 //   - sourceAccount, signers
 //   - raw event list surfaced for downstream validation
@@ -90,14 +90,13 @@ export function decodeEnvelope(
     // Fee-bump wraps a normal inner v1 transaction (a different account
     // pays the fee). The real operations + their authorizers live on the
     // INNER v1 envelope, so decode that and discard the outer fee-bump
-    // shell. The fee-bump envelope switch arm `v0` is intentionally not
-    // routed here - fee-bump v0 does not exist.
+    // shell (fee-bump v0 does not exist).
     const innerV1 = envelope.feeBump().tx().innerTx().v1()
     return decodeV1Envelope(innerV1, events, ledgerSequence, knownContracts, network)
   }
   if (envType !== 'envelopeTypeTx') {
-    // TransactionV0 is out of scope - v1 protocol only. Fee-bump is now
-    // handled above; legacy envelopes reach this branch.
+    // TransactionV0 is out of scope (v1 protocol only). Fee-bump is handled
+    // above; legacy envelopes reach this branch.
     throw new DecodeError(`unsupported envelope: ${envType}`)
   }
   return decodeV1Envelope(envelope.v1(), events, ledgerSequence, knownContracts, network)

package/src/registry/protocols.ts

@@ -194,7 +194,7 @@ export const SOROSWAP_ABI: ProtocolAbi = {
  *     1.0 threshold - lowering the gate for unknown protocols remains
  *     a separate, opt-in production override (see RecordInput below).
  *
- *  ABI source: packages/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
+ *  ABI source: contracts/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
  *  pinned from the OpenZeppelin Reloaded `multisig_account_example`
  *  contract (commit ef82b65, fetched 2026-07-28).
  *

package/src/review-card/builder.ts

@@ -44,6 +44,12 @@ export interface ReviewCardSummary {
   plainEnglish: string
   constraints: string[]
   expiry: string
+  /** Cross-layer L1: a human-readable note about the OZ any-of-N signer
+   *  semantic for rules with N>=2 signers. `null` for single-signer rules
+   *  (the note would be redundant). Purely additive to the review card
+   *  text - does not change the policy semantics, only what the human
+   *  reads when reviewing. */
+  signerNote: string | null
   backend: 'interpreter-v1' | 'ts-model'
   /** Stable hash of the builder inputs - identical policy + summary = identical hash. */
   contentHash: string
@@ -72,6 +78,14 @@ export function buildReviewCardSummary(
   const ruleName = contextRule.name
   const plainEnglish = renderPlainEnglish(ruleName, constraints)
   const expiry = renderExpiry(contextRule.validUntilLedger)
+  // Cross-layer L1: a rule with N>=2 signers gets a one-line note about
+  // the OZ any-of-N semantic so the human reviewing the install reads the
+  // same wire-level behaviour the contract enforces. A single-signer rule
+  // is trivially any-of-1, so the note would be noise.
+  const signerNote =
+    contextRule.signers.length >= 2
+      ? 'any ONE signer may authorise a permitted op under this rule (OZ any-of-N semantic)'
+      : null
   const backend = simulation.backend
 
   const contentHash = computeContentHash({
@@ -79,10 +93,11 @@ export function buildReviewCardSummary(
     plainEnglish,
     constraints,
     expiry,
+    signerNote,
     backend,
   })
 
-  return { ruleName, plainEnglish, constraints, expiry, backend, contentHash }
+  return { ruleName, plainEnglish, constraints, expiry, signerNote, backend, contentHash }
 }
 
 /** Render the OZ built-in primitive summary line. Only `spending_limit` is
@@ -361,6 +376,7 @@ function computeContentHash(input: {
   plainEnglish: string
   constraints: string[]
   expiry: string
+  signerNote: string | null
   backend: 'interpreter-v1' | 'ts-model'
 }): string {
   return createHash('sha256').update(canonicalStringify(input)).digest('hex')

package/src/run/index.ts

@@ -110,13 +110,32 @@ export {
 } from './schemas.ts'
 
 export type RunRecordTransactionInput = RecordTransactionInput
-
 export type RunSynthesizePolicyInput = SynthesizePolicyInput
-
 export type RunSimulatePolicyInput = SimulatePolicyInput
-
 export type RunVerifyPolicyInput = VerifyPolicyInput
 
+type RunToolName =
+  | 'record_transaction'
+  | 'synthesize_policy'
+  | 'simulate_policy'
+  | 'verify_policy'
+  | 'install_policy'
+  | 'revoke_policy'
+  | 'get_interpreter_info'
+
+/** Map every tool name to its canonical domain error code. Replaces a 7-way
+ *  if/else so adding a tool adds one line here rather than a new branch in
+ *  each envelope call. */
+const TOOL_ERROR_CODE: Record<RunToolName, ErrorCode> = {
+  record_transaction: 'RECORDING_FAILED',
+  synthesize_policy: 'SYNTHESIS_ERROR',
+  simulate_policy: 'SIMULATION_ERROR',
+  verify_policy: 'VERIFICATION_FAILED',
+  install_policy: 'INSTALL_BUILD_FAILED',
+  revoke_policy: 'REVOKE_BUILD_FAILED',
+  get_interpreter_info: 'RECORDING_FAILED',
+}
+
 /** `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.
@@ -339,17 +358,15 @@ export async function runInstallPolicy(
   if (pinningError) {
     return { ok: false, error: pinningError }
   }
-  if (input.rpcUrl && input.rpcUrl !== expectedRpc && input.allowUnpinnedRpcUrl !== true) {
-    return {
-      ok: false,
-      error: {
-        code: 'INSTALL_BUILD_FAILED',
-        message: `install_policy: rpcUrl must equal the pinned ${expectedRpc} (${network}); set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
-        severity: 'error',
-        retryable: false,
-        remediation: { toolCall: { name: 'install_policy', args: {} } },
-      },
-    }
+  const rpcPinningError = enforceRpcPin(
+    'install_policy',
+    input.rpcUrl,
+    input.allowUnpinnedRpcUrl,
+    expectedRpc,
+    network
+  )
+  if (rpcPinningError) {
+    return { ok: false, error: rpcPinningError }
   }
   let rpcClient: InstallRpcClient
   try {
@@ -408,17 +425,15 @@ export async function runRevokePolicy(
   const input: RevokePolicyInput = parsed.data
   const network: Network = input.network ?? 'testnet'
   const expectedRpc = RPC_URL_BY_NETWORK[network]
-  if (input.rpcUrl && input.rpcUrl !== expectedRpc && input.allowUnpinnedRpcUrl !== true) {
-    return {
-      ok: false,
-      error: {
-        code: 'REVOKE_BUILD_FAILED',
-        message: `revoke_policy: rpcUrl must equal the pinned ${expectedRpc} (${network}); set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
-        severity: 'error',
-        retryable: false,
-        remediation: { toolCall: { name: 'revoke_policy', args: {} } },
-      },
-    }
+  const rpcPinningError = enforceRpcPin(
+    'revoke_policy',
+    input.rpcUrl,
+    input.allowUnpinnedRpcUrl,
+    expectedRpc,
+    network
+  )
+  if (rpcPinningError) {
+    return { ok: false, error: rpcPinningError }
   }
   let rpcClient: InstallRpcClient
   try {
@@ -457,10 +472,15 @@ export async function runRevokePolicy(
  *  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
- *  (DEPLOYMENTS.md:25-27). The address differs because instance ids are
- *  network-scoped. UNAUDITED at the time of writing - see
- *  DEPLOYMENTS.md:29-32 for what is still pending. */
+ *  `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: unknown
 ): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>> {
@@ -473,6 +493,25 @@ export async function runGetInterpreterInfo(
   }
   const input: GetInterpreterInfoInput = parsed.data
   const network: Network = input.network ?? 'testnet'
+  const expectedRpc = RPC_URL_BY_NETWORK[network]
+  // Pin enforcement only matters when the live RPC call is engaged. The
+  // static-fingerprint branch is local data and a non-pinned URL never
+  // reaches the network, so the gate is conditioned on `verifyLive` to
+  // match the wire-level concern (an outbound request that returns a
+  // caller-bound value). A caller that DOES NOT verifyLive can supply any
+  // URL it likes; the field is still optional.
+  if (input.verifyLive === true) {
+    const rpcPinningError = enforceRpcPin(
+      'get_interpreter_info',
+      input.rpcUrl,
+      input.allowUnpinnedRpcUrl,
+      expectedRpc,
+      network
+    )
+    if (rpcPinningError) {
+      return { ok: false, error: rpcPinningError }
+    }
+  }
   const pinnedAddress = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network]
   try {
     let deployedGrammarVersion: number | undefined
@@ -514,15 +553,14 @@ function buildRpcClientFromInput(
   return rpcClientFromServer(new rpc.Server(url, { allowHttp: false }), passphrase)
 }
 
-/** Default-deny: refuse any interpreter policy whose address differs from
- *  the pinned interpreter for the selected network. 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. The caller resolves the expected pin per
- *  network; this function stays pure so it is easy to test. */
+/** Default-deny: refuse an interpreter policy whose address differs from the
+ *  pinned interpreter for the selected network. An interpreter the caller
+ *  controls can permit anything, so the smart account's authorization must
+ *  bind to the pinned contract unless the caller opts in. OZ built-in
+ *  policies are not interpreters and pass through. Returns a ToolError to
+ *  surface through the run-layer envelope, or null when all interpreter
+ *  policies are pinned. The caller resolves the expected pin per network;
+ *  this function stays pure so it is easy to test. */
 function enforceInterpreterPin(
   policies: InstallPolicyInput['rule']['policies'],
   allowUnpinned: boolean | undefined,
@@ -543,81 +581,69 @@ function enforceInterpreterPin(
   return null
 }
 
+/** Default-deny: refuse an `rpcUrl` that is not the pinned RPC for the
+ *  selected network. The auth nonce + rootInvocation in the install/revoke
+ *  response come from whichever RPC answered, so a non-pinned RPC would
+ *  silently bind the caller to a host they picked. The same applies to
+ *  `get_interpreter_info` when `verifyLive` is true (the live grammar
+ *  version is the caller-bound value). The caller may opt in via
+ *  `allowUnpinnedRpcUrl: true`. Returns a ToolError or null when the URL is
+ *  pinned (or absent, since the default is the pinned one). */
+function enforceRpcPin(
+  toolName: 'install_policy' | 'revoke_policy' | 'get_interpreter_info',
+  rpcUrl: string | undefined,
+  allowUnpinned: boolean | undefined,
+  expectedRpc: string,
+  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,
+    message: `${toolName}: rpcUrl must equal the pinned ${expectedRpc} (${network}); set allowUnpinnedRpcUrl: true to opt in to a custom endpoint`,
+    severity: 'error',
+    retryable: false,
+    remediation: { toolCall: { name: toolName, args: {} } },
+  }
+}
+
 /** 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'
-    | 'simulate_policy'
-    | 'verify_policy'
-    | 'install_policy'
-    | 'revoke_policy'
-    | 'get_interpreter_info',
+  toolName: RunToolName,
   issues: ReadonlyArray<{ path: ReadonlyArray<string | number>; message: string }>
 ): ToolError {
-  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,
+    code: TOOL_ERROR_CODE[toolName],
     message: `${toolName}: invalid input: ${issues
       .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
       .join('; ')}`,
     severity: 'error',
     retryable: false,
-    remediation: {
-      toolCall: { name: toolName, args: {} },
-    },
+    remediation: { toolCall: { name: toolName, args: {} } },
   }
 }
 
 /** Build a canonical ToolError for a thrown exception caught by the tool
  *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
  *  default, so we extract a string-friendly message and tag the original
- *  error in `details` for the agent to inspect. The `code` is the tool's
- *  domain code (RECORDING_FAILED for `record_transaction`, SYNTHESIS_ERROR
- *  for `synthesize_policy`) so the agent dispatches on the same code the
- *  structured ToolError would carry.
- *
- *  Exported as `_caughtError` (the leading underscore signals the test-only
- *  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'
-    | 'simulate_policy'
-    | 'verify_policy'
-    | 'install_policy'
-    | 'revoke_policy'
-    | 'get_interpreter_info',
-  code: ErrorCode,
-  e: unknown
-): ToolError {
-  const message = describeThrown(e, toolName)
-  const details = { thrown: safeStringify(e) }
+ *  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. */
+export function caughtError(toolName: RunToolName, code: ErrorCode, e: unknown): ToolError {
   return {
     code,
-    message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
+    message: `${toolName}: unhandled throw escaped core envelope: ${describeThrown(e, toolName)}`,
     severity: 'error',
     retryable: false,
-    remediation: {
-      toolCall: { name: toolName, args: {} },
-    },
-    details,
+    remediation: { toolCall: { name: toolName, args: {} } },
+    details: { thrown: safeStringify(e) },
   }
 }