@crediolabs/policy-synth 0.1.17 → 0.2.0

package/dist/run/index.js

@@ -17,17 +17,35 @@
 // 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 { rpc, xdr } from '@stellar/stellar-sdk';
 import { placeholderOzConfig, recordTransaction, synthesizeFromMandate, synthesizeFromRecording, } from "../index.js";
+import { findAuthorityOverlaps, } from "../install/authority-overlap.js";
 import { buildInstallPolicyXdr, buildRevokePolicyXdr, rpcClientFromServer, } from "../install/build-install-policy.js";
+import { buildMergePolicyXdr } from "../install/build-merge-policy.js";
 import { getInterpreterInfo } from "../install/get-interpreter-info.js";
+import { planMergePolicy } from "../install/plan-merge-policy.js";
+import { accountRuleReaderFromServer, collectObservedRules, nonceLedgerKey, } from "../install/read-account-rules.js";
+import { decodePredicate } from "../predicate/decode.js";
+import { encodePredicate } from "../predicate/encode.js";
 import { simulatePolicy, verifyPolicy } from "../verify/index.js";
-import { GetInterpreterInfoInputSchema, InstallPolicyInputSchema, NETWORK_PASSPHRASES, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_WASM_SHA256, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, VerifyPolicyInputSchema, } from "./schemas.js";
+import { GetInterpreterInfoInputSchema, InstallPolicyInputSchema, MergePolicyInputSchema, NETWORK_PASSPHRASES, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, VerifyPolicyInputSchema, } from "./schemas.js";
 // Re-export the underlying Zod schemas so the MCP package (and any other
 // downstream consumer) can import the canonical input shapes from the same
 // module that owns the tool-body glue. The strict schemas are the source of
 // truth - MCP tool shapes are derived from them.
-export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MAINNET_RPC_URL, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, VerifyPolicyInputSchema, } from "./schemas.js";
+export { ComposeUserResponsesSchema, GetInterpreterInfoInputSchema, InstallPolicyInputSchema, InterpreterOptionsSchema, MAINNET_RPC_URL, MandateSpecSchema, NetworkSchema, OraclePriceFixtureSchema, OzAdapterConfigSchema, PINNED_INTERPRETER_ADDRESS_BY_NETWORK, PINNED_INTERPRETER_GRAMMAR_VERSION, PINNED_INTERPRETER_MAINNET_ADDRESS, PINNED_INTERPRETER_TESTNET_ADDRESS, PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK, PredicateLeafSchema, PredicateNodeSchema, RecordedTransactionSchema, RecordTransactionInputSchema, RevokePolicyInputSchema, RPC_URL_BY_NETWORK, SimulatePolicyInputSchema, SynthesizePolicyInputSchema, TESTNET_RPC_URL, ToolErrorSchema, VerifyPolicyInputSchema, } from "./schemas.js";
+/** 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.
@@ -222,17 +240,9 @@ export 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 {
@@ -250,6 +260,25 @@ export async function runInstallPolicy(raw) {
         const predicateHash = createHash('sha256')
             .update(Buffer.from(encodedPredicate, 'base64'))
             .digest('hex');
+        // ---- Cross-rule authority scan ----
+        // OZ enforces only the policies of the rule the caller names, so a signer
+        // who also sits in a wider rule keeps that wider authority no matter what
+        // this predicate says. Refuse by default when the wider rule has no policy
+        // at all, because that makes this install decorative.
+        const authorityScan = input.skipAuthorityScan
+            ? { ran: false, skipped: true, reason: 'skipped at caller request', overlaps: [] }
+            : await scanAuthorityOverlap({
+                smartAccount: input.smartAccount,
+                interpreterAddress: expectedInterpreter,
+                rule: input.rule,
+                encodedPredicate,
+                rpcUrl: input.rpcUrl ?? expectedRpc,
+                network,
+            });
+        const overlapError = enforceAuthorityScan(authorityScan, input.allowAuthorityOverlap);
+        if (overlapError) {
+            return { ok: false, error: overlapError };
+        }
         const result = await buildInstallPolicyXdr({
             smartAccount: input.smartAccount,
             sourceAccount: input.sourceAccount,
@@ -261,7 +290,7 @@ export async function runInstallPolicy(raw) {
             rpc: rpcClient,
             ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
         });
-        return { ok: true, data: result };
+        return { ok: true, data: authorityScan ? { ...result, authorityScan } : result };
     }
     catch (e) {
         return {
@@ -270,6 +299,252 @@ export async function runInstallPolicy(raw) {
         };
     }
 }
+/** Default-deny on the cross-rule scan.
+ *
+ *  Refuses whenever the scan cannot establish that this policy binds the calls
+ *  it names. An unpoliced neighbour provably does not constrain them. An
+ *  opaque one, policed by a contract this tool cannot decode, is not KNOWN to,
+ *  and "not known to" is not "safe" - the same posture as the interpreter and
+ *  RPC pins. An incomplete scan is refused for the same reason: the overlap
+ *  list is then a subset of the account, so an empty list proves nothing.
+ *
+ *  `not-restricting` is reported but does NOT block. Both rules are ours and
+ *  both constrain the calls, and the conjunction remedy is offered; refusing
+ *  there would also block the legitimate act of adding a separate capability,
+ *  which OZ composes correctly as a union.
+ *
+ *  Returns a ToolError or null, matching `enforceInterpreterPin`. */
+export function enforceAuthorityScan(scan, allowOverlap) {
+    if (!scan || allowOverlap === true)
+        return null;
+    // Default-deny by exclusion rather than by enumeration: anything that is not
+    // the one known-safe severity blocks. Listing the blocking severities
+    // instead would mean a severity added later silently passes until someone
+    // remembers to add it here, and the safe direction is the opposite.
+    const blocking = scan.overlaps.filter((o) => o.severity !== 'not-restricting');
+    const unpoliced = blocking.filter((o) => o.severity === 'bypass').map((o) => o.ruleId);
+    const opaque = blocking.filter((o) => o.severity === 'unknown').map((o) => o.ruleId);
+    const unrecognised = blocking
+        .filter((o) => o.severity !== 'bypass' && o.severity !== 'unknown')
+        .map((o) => o.ruleId);
+    if (blocking.length > 0) {
+        const parts = [
+            unpoliced.length > 0 ? `rule ${unpoliced.join(', ')} has no policy attached` : '',
+            opaque.length > 0
+                ? `rule ${opaque.join(', ')} is policed by a contract this tool cannot decode`
+                : '',
+            unrecognised.length > 0
+                ? `rule ${unrecognised.join(', ')} carries an overlap this build does not recognise`
+                : '',
+        ].filter(Boolean);
+        return {
+            code: 'INSTALL_BUILD_FAILED',
+            message: `install_policy: a signer of this rule can already make the same calls through another context rule, so this policy is not established to restrict them: ${parts.join('; ')}. Remove the shared signer from that rule, attach a policy this tool can read, or set allowAuthorityOverlap: true to install anyway`,
+            severity: 'error',
+            retryable: false,
+            remediation: { toolCall: { name: 'install_policy', args: {} } },
+        };
+    }
+    // A scan that was meant to run and threw tells us nothing. Reporting it in
+    // a string field and proceeding is the same fail-open shape as an incomplete
+    // scan, and a caller that does not read `ran` cannot tell it from a clean
+    // result.
+    if (scan.ran === false && scan.skipped !== true) {
+        return {
+            code: 'INSTALL_BUILD_FAILED',
+            message: `install_policy: the cross-rule authority scan could not run (${scan.reason ?? 'unknown error'}), so it cannot establish that this policy restricts anything; retry, or set allowAuthorityOverlap: true to install without that assurance`,
+            severity: 'error',
+            retryable: true,
+            remediation: { toolCall: { name: 'install_policy', args: {} } },
+        };
+    }
+    if (scan.incomplete === true) {
+        return {
+            code: 'INSTALL_BUILD_FAILED',
+            message: 'install_policy: the account has more context rules than the scan could account for, so the overlap result is incomplete and cannot establish that this policy restricts anything; set allowAuthorityOverlap: true to install without that assurance',
+            severity: 'error',
+            retryable: false,
+            remediation: { toolCall: { name: 'install_policy', args: {} } },
+        };
+    }
+    return null;
+}
+/** Read the account's other context rules and report where this install's
+ *  signers already hold authority over the same calls.
+ *
+ *  A failure to read is reported rather than thrown, and the caller-facing
+ *  decision is made by `enforceAuthorityScan`: a scan that tried and failed
+ *  tells us nothing, so it refuses rather than passing as a clean account.
+ *
+ *  The account data this trusts comes from whichever RPC answered, so a
+ *  hostile RPC could describe an account with no overlapping rules. That is
+ *  bounded by the pin already enforced above: `enforceRpcPin` returns before
+ *  this runs, so the URL is the pinned one for the network unless the caller
+ *  explicitly set `allowUnpinnedRpcUrl`. This scan deliberately does not add a
+ *  second pin check, because two places deciding the same thing drift. */
+async function scanAuthorityOverlap(args) {
+    try {
+        if (!args.encodedPredicate) {
+            // Not applicable rather than failed: this rule installs no interpreter
+            // predicate, so there is nothing of ours for another rule to undercut.
+            // Returning undefined keeps it out of the refusal path, which is
+            // reserved for scans that were meant to run and could not.
+            return undefined;
+        }
+        const server = new rpc.Server(args.rpcUrl, { allowHttp: false });
+        const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[args.network]);
+        const collected = await collectObservedRules({
+            reader,
+            smartAccount: args.smartAccount,
+            interpreterAddress: args.interpreterAddress,
+        });
+        const overlaps = findAuthorityOverlaps({
+            intended: {
+                // `add_context_rule` always creates a NEW rule, so there is no id to
+                // exclude; -1 matches nothing on the account.
+                ruleId: -1,
+                contextType: toOverlapContextType(args.rule.contextRuleType),
+                signers: args.rule.signers,
+                predicate: decodePredicate(args.encodedPredicate),
+            },
+            existing: collected.rules,
+        });
+        return { ran: true, incomplete: collected.incomplete, overlaps };
+    }
+    catch (e) {
+        return {
+            ran: false,
+            reason: e instanceof Error ? e.message : String(e),
+            overlaps: [],
+        };
+    }
+}
+/** The rule draft names the callee `contract`; the analyser calls it
+ *  `address`. Same value, two vocabularies. */
+function toOverlapContextType(ct) {
+    switch (ct.kind) {
+        case 'call_contract':
+            return { kind: 'call_contract', address: ct.contract };
+        case 'create_contract':
+            return { kind: 'create_contract', wasmHash: ct.wasmHash };
+        default:
+            return { kind: 'default' };
+    }
+}
+/** `merge_policy` body - the tightening remedy for a cross-rule overlap.
+ *
+ *  Replaces a rule's predicate with the conjunction of it and a new one. This
+ *  is the action `install_policy` recommends when it reports an overlap
+ *  between two rules our interpreter polices, and it is deliberately NOT
+ *  something `install_policy` does on its own: it detaches a live policy, so
+ *  the operator has to ask for it.
+ *
+ *  Two transactions in order. `add_policy` refuses a policy already on the
+ *  rule, so the old attachment goes first, and the second transaction cannot
+ *  be simulated until the first confirms. */
+export async function runMergePolicy(raw) {
+    const parsed = MergePolicyInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return { ok: false, error: validationError('install_policy', parsed.error.issues) };
+    }
+    const input = parsed.data;
+    const network = input.network ?? 'testnet';
+    const expectedInterpreter = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network];
+    const expectedRpc = RPC_URL_BY_NETWORK[network];
+    const rpcPinningError = enforceRpcPin('install_policy', input.rpcUrl, input.allowUnpinnedRpcUrl, expectedRpc, network);
+    if (rpcPinningError)
+        return { ok: false, error: rpcPinningError };
+    try {
+        const rpcUrl = input.rpcUrl ?? expectedRpc;
+        const server = new rpc.Server(rpcUrl, { allowHttp: false });
+        const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network]);
+        const collected = await collectObservedRules({
+            reader,
+            smartAccount: input.smartAccount,
+            interpreterAddress: expectedInterpreter,
+        });
+        const rule = collected.rules.find((r) => r.id === input.ruleId);
+        if (!rule) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: `merge_policy: rule ${input.ruleId} was not found on ${input.smartAccount}${collected.incomplete
+                        ? ' (the rule scan was incomplete, so it may exist but was not reached)'
+                        : ''}`,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        const plan = planMergePolicy({
+            rule,
+            interpreterAddress: expectedInterpreter,
+            incoming: decodePredicate(input.incomingPredicateBlobBase64),
+            step: input.step,
+        });
+        if (!plan.ok) {
+            return {
+                ok: false,
+                error: {
+                    code: 'INSTALL_BUILD_FAILED',
+                    message: `merge_policy: ${plan.reason}`,
+                    severity: 'error',
+                    retryable: false,
+                    remediation: { toolCall: { name: 'install_policy', args: {} } },
+                },
+            };
+        }
+        const encoded = encodePredicate(plan.predicate);
+        // The nonce is read, not assumed. OZ's `remove_policy` discards the result
+        // of `try_uninstall`, so a detach whose uninstall panicked - our
+        // `uninstall` panics MissingState when the master set has been archived -
+        // detaches the policy while leaving our nonce behind. Re-installing at 1
+        // would then be refused as a replay and the rule would sit unpoliced.
+        let installNonce = 1;
+        const nonceWarnings = [];
+        if (input.step === 'reinstall') {
+            const entries = await server.getLedgerEntries(nonceLedgerKey(expectedInterpreter, input.smartAccount, input.ruleId));
+            const raw = entries.entries?.[0]?.val;
+            const stored = raw && raw.switch() === xdr.LedgerEntryType.contractData()
+                ? raw.contractData().val()
+                : undefined;
+            if (stored && stored.switch() === xdr.ScValType.scvU32()) {
+                installNonce = stored.u32() + 1;
+                nonceWarnings.push(`the previous uninstall did not complete: rule ${input.ruleId} still holds interpreter state at nonce ${stored.u32()}, so this reinstalls at ${installNonce} rather than 1. The rule's counters were NOT reset.`);
+            }
+        }
+        const built = await buildMergePolicyXdr({
+            smartAccount: input.smartAccount,
+            sourceAccount: input.sourceAccount,
+            networkPassphrase: NETWORK_PASSPHRASES[network],
+            ruleId: input.ruleId,
+            policyId: plan.policyId,
+            interpreterAddress: expectedInterpreter,
+            step: input.step,
+            encodedPredicate: encoded.encodedPredicate,
+            predicateHash: encoded.predicateHash,
+            installNonce,
+            ...(plan.oracleParams ? { oracleParams: plan.oracleParams } : {}),
+            rpc: rpcClientFromServer(server, NETWORK_PASSPHRASES[network]),
+            ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
+        });
+        return {
+            ok: true,
+            data: {
+                ...built,
+                mergedPredicateHash: encoded.predicateHash,
+                mergedPredicateBlobBase64: encoded.encodedPredicate,
+                warnings: [...plan.warnings, ...nonceWarnings],
+                followUp: plan.followUp,
+            },
+        };
+    }
+    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
@@ -290,17 +565,9 @@ export async function runRevokePolicy(raw) {
     const input = parsed.data;
     const 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;
     try {
@@ -337,13 +604,18 @@ export async function runRevokePolicy(raw) {
  *  fabricating it would be a lie on a security surface; the live
  *  mismatch check is worth MORE).
  *
- *  Network-aware: `input.network` selects 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. */
+ *  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.
+ *
+ *  Same RPC pin as install/revoke: when `verifyLive` triggers an outbound
+ *  call, the auth-digest + the answer bind to whichever RPC answered, so
+ *  a non-pinned `rpcUrl` would silently bind the caller to a host they
+ *  picked. The pin is enforced here too, with the same `allowUnpinnedRpcUrl`
+ *  opt-in as install/revoke. */
 export async function runGetInterpreterInfo(raw) {
     const parsed = GetInterpreterInfoInputSchema.safeParse(raw);
     if (!parsed.success) {
@@ -354,6 +626,19 @@ export async function runGetInterpreterInfo(raw) {
     }
     const input = parsed.data;
     const 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;
@@ -364,7 +649,7 @@ export async function runGetInterpreterInfo(raw) {
         const info = getInterpreterInfo({
             pinnedAddress,
             pinnedGrammarVersion: PINNED_INTERPRETER_GRAMMAR_VERSION,
-            pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256,
+            pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK[network],
             network,
             ...(deployedGrammarVersion !== undefined ? { deployedGrammarVersion } : {}),
         });
@@ -391,15 +676,14 @@ function buildRpcClientFromInput(urlOverride, network) {
     // needs the full Server surface.
     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, allowUnpinned, expectedInterpreterAddress) {
     for (const p of policies) {
         if (p.kind !== 'interpreter')
@@ -418,58 +702,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. */
 export 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: