@crediolabs/policy-synth 0.1.16 → 0.1.18

package/dist-cjs/predicate/encode.js

@@ -1,16 +1,14 @@
 "use strict";
 // 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
@@ -20,12 +18,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
@@ -64,6 +56,21 @@ function encodePredicate(node) {
     if (stats.oracleAssets.size > 0 && stats.nonOracleSelectorLeaves === 0) {
         throw capError('MALFORMED_PREDICATE', 'predicate constrains nothing but an oracle price: the contract refuses it at install (dsl.rs MissingNonOracleEnvelope). Pin the call itself (contract / method / argument) alongside the price bound.');
     }
+    // --- 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();
@@ -324,3 +331,157 @@ function capError(code, message) {
     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) {
+    function walkLeaf(leaf, path) {
+        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;
+                let den;
+                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, path) {
+        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) {
+    return capError('MALFORMED_PREDICATE', message);
+}

package/dist-cjs/record/decode.js

@@ -8,8 +8,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
@@ -46,14 +46,13 @@ function decodeEnvelope(envelope, events = [], _authEntries = [], ledgerSequence
         // 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/dist-cjs/registry/protocols.d.ts

@@ -63,7 +63,7 @@ export declare 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/dist-cjs/registry/protocols.js

@@ -172,7 +172,7 @@ exports.SOROSWAP_ABI = {
  *     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/dist-cjs/review-card/builder.d.ts

@@ -5,6 +5,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;

package/dist-cjs/review-card/builder.js

@@ -52,15 +52,23 @@ function buildReviewCardSummary(predicate, policyRefs, contextRule, simulation)
     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({
         ruleName,
         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
  *  quoted by the review card (it is the only primitive that defines a

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

@@ -9,6 +9,7 @@ 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';
 /** `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.
@@ -86,20 +87,20 @@ export declare function runRevokePolicy(raw: unknown): Promise<ToolResponse<Buil
  *  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 declare function runGetInterpreterInfo(raw: unknown): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>>;
 /** 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 declare function caughtError(toolName: 'record_transaction' | 'synthesize_policy' | 'simulate_policy' | 'verify_policy' | 'install_policy' | 'revoke_policy' | 'get_interpreter_info', code: ErrorCode, e: unknown): ToolError;
+ *  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 declare function caughtError(toolName: RunToolName, code: ErrorCode, e: unknown): ToolError;

package/dist-cjs/run/index.js

@@ -64,6 +64,18 @@ Object.defineProperty(exports, "SynthesizePolicyInputSchema", { enumerable: true
 Object.defineProperty(exports, "TESTNET_RPC_URL", { enumerable: true, get: function () { return schemas_ts_2.TESTNET_RPC_URL; } });
 Object.defineProperty(exports, "ToolErrorSchema", { enumerable: true, get: function () { return schemas_ts_2.ToolErrorSchema; } });
 Object.defineProperty(exports, "VerifyPolicyInputSchema", { enumerable: true, get: function () { return schemas_ts_2.VerifyPolicyInputSchema; } });
+/** 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_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.
@@ -258,17 +270,9 @@ async function runInstallPolicy(raw) {
     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;
     try {
@@ -326,17 +330,9 @@ async function runRevokePolicy(raw) {
     const input = parsed.data;
     const network = input.network ?? 'testnet';
     const expectedRpc = schemas_ts_1.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;
     try {
@@ -376,10 +372,15 @@ async function runRevokePolicy(raw) {
  *  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. */
 async function runGetInterpreterInfo(raw) {
     const parsed = schemas_ts_1.GetInterpreterInfoInputSchema.safeParse(raw);
     if (!parsed.success) {
@@ -390,6 +391,19 @@ async function runGetInterpreterInfo(raw) {
     }
     const input = parsed.data;
     const network = input.network ?? 'testnet';
+    const expectedRpc = schemas_ts_1.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 = schemas_ts_1.PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network];
     try {
         let deployedGrammarVersion;
@@ -427,15 +441,14 @@ function buildRpcClientFromInput(urlOverride, network) {
     // needs the full Server surface.
     return (0, build_install_policy_ts_1.rpcClientFromServer)(new stellar_sdk_1.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, allowUnpinned, expectedInterpreterAddress) {
     for (const p of policies) {
         if (p.kind !== 'interpreter')
@@ -454,58 +467,58 @@ function enforceInterpreterPin(policies, allowUnpinned, expectedInterpreterAddre
     }
     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, 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,
+        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, issues) {
-    const code = 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. */
+ *  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. */
 function caughtError(toolName, code, e) {
-    const message = describeThrown(e, toolName);
-    const details = { thrown: safeStringify(e) };
     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) },
     };
 }
 /** Build a human-readable message for an unknown caught value. Order matters: