@crediolabs/policy-synth 0.1.17 → 0.1.18

package/dist/run/index.js

@@ -28,6 +28,18 @@ import { GetInterpreterInfoInputSchema, InstallPolicyInputSchema, NETWORK_PASSPH
 // 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";
+/** 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 +234,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 {
@@ -290,17 +294,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 {
@@ -340,10 +336,15 @@ export 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. */
 export async function runGetInterpreterInfo(raw) {
     const parsed = GetInterpreterInfoInputSchema.safeParse(raw);
     if (!parsed.success) {
@@ -354,6 +355,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;
@@ -391,15 +405,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 +431,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:

package/dist/run/schemas.d.ts

@@ -352,7 +352,7 @@ export declare const RecordedTransactionSchema: z.ZodObject<{
 /** MandateSpec mirrors the core MandateSpec. The deterministic Mandate
  *  front-end needs no parseConfidence; the tool adapter injects the full
  *  confidence after synthesis so the orchestrator can compare. */
-export declare const MandateSpecSchema: z.ZodObject<{
+export declare const MandateSpecSchema: z.ZodEffects<z.ZodObject<{
     chain: z.ZodLiteral<"stellar">;
     contract: z.ZodString;
     method: z.ZodOptional<z.ZodString>;
@@ -439,6 +439,64 @@ export declare const MandateSpecSchema: z.ZodObject<{
         validUntilLedger?: number | undefined;
         validUntilUnixSeconds?: number | undefined;
     }>>;
+}, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+    chain: z.ZodLiteral<"stellar">;
+    contract: z.ZodString;
+    method: z.ZodOptional<z.ZodString>;
+    spendingLimit: z.ZodOptional<z.ZodObject<{
+        token: z.ZodString;
+        limit: z.ZodString;
+        windowSeconds: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        token: string;
+        limit: string;
+        windowSeconds: number;
+    }, {
+        token: string;
+        limit: string;
+        windowSeconds: number;
+    }>>;
+    approvalThreshold: z.ZodOptional<z.ZodNumber>;
+    recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    expiry: z.ZodOptional<z.ZodObject<{
+        validUntilLedger: z.ZodOptional<z.ZodNumber>;
+        validUntilUnixSeconds: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        validUntilLedger?: number | undefined;
+        validUntilUnixSeconds?: number | undefined;
+    }, {
+        validUntilLedger?: number | undefined;
+        validUntilUnixSeconds?: number | undefined;
+    }>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    chain: z.ZodLiteral<"stellar">;
+    contract: z.ZodString;
+    method: z.ZodOptional<z.ZodString>;
+    spendingLimit: z.ZodOptional<z.ZodObject<{
+        token: z.ZodString;
+        limit: z.ZodString;
+        windowSeconds: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        token: string;
+        limit: string;
+        windowSeconds: number;
+    }, {
+        token: string;
+        limit: string;
+        windowSeconds: number;
+    }>>;
+    approvalThreshold: z.ZodOptional<z.ZodNumber>;
+    recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    expiry: z.ZodOptional<z.ZodObject<{
+        validUntilLedger: z.ZodOptional<z.ZodNumber>;
+        validUntilUnixSeconds: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        validUntilLedger?: number | undefined;
+        validUntilUnixSeconds?: number | undefined;
+    }, {
+        validUntilLedger?: number | undefined;
+        validUntilUnixSeconds?: number | undefined;
+    }>>;
 }, z.ZodTypeAny, "passthrough">>;
 /** ComposeUserResponses mirrors the core. */
 export declare const ComposeUserResponsesSchema: z.ZodObject<{
@@ -530,7 +588,7 @@ export declare const RecordTransactionInputSchema: z.ZodEffects<z.ZodEffects<z.Z
 export type RecordTransactionInput = z.infer<typeof RecordTransactionInputSchema>;
 export declare const SynthesizePolicyMandateInputSchema: z.ZodObject<{
     source: z.ZodLiteral<"mandate">;
-    mandate: z.ZodObject<{
+    mandate: z.ZodEffects<z.ZodObject<{
         chain: z.ZodLiteral<"stellar">;
         contract: z.ZodString;
         method: z.ZodOptional<z.ZodString>;
@@ -617,6 +675,64 @@ export declare const SynthesizePolicyMandateInputSchema: z.ZodObject<{
             validUntilLedger?: number | undefined;
             validUntilUnixSeconds?: number | undefined;
         }>>;
+    }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+        chain: z.ZodLiteral<"stellar">;
+        contract: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        spendingLimit: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+            limit: z.ZodString;
+            windowSeconds: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }>>;
+        approvalThreshold: z.ZodOptional<z.ZodNumber>;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        expiry: z.ZodOptional<z.ZodObject<{
+            validUntilLedger: z.ZodOptional<z.ZodNumber>;
+            validUntilUnixSeconds: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        chain: z.ZodLiteral<"stellar">;
+        contract: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        spendingLimit: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+            limit: z.ZodString;
+            windowSeconds: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }>>;
+        approvalThreshold: z.ZodOptional<z.ZodNumber>;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        expiry: z.ZodOptional<z.ZodObject<{
+            validUntilLedger: z.ZodOptional<z.ZodNumber>;
+            validUntilUnixSeconds: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }>>;
     }, z.ZodTypeAny, "passthrough">>;
     ozConfig: z.ZodOptional<z.ZodObject<{
         network: z.ZodEnum<["mainnet", "testnet"]>;
@@ -1222,7 +1338,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
 }>;
 export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"source", [z.ZodObject<{
     source: z.ZodLiteral<"mandate">;
-    mandate: z.ZodObject<{
+    mandate: z.ZodEffects<z.ZodObject<{
         chain: z.ZodLiteral<"stellar">;
         contract: z.ZodString;
         method: z.ZodOptional<z.ZodString>;
@@ -1309,6 +1425,64 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             validUntilLedger?: number | undefined;
             validUntilUnixSeconds?: number | undefined;
         }>>;
+    }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
+        chain: z.ZodLiteral<"stellar">;
+        contract: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        spendingLimit: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+            limit: z.ZodString;
+            windowSeconds: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }>>;
+        approvalThreshold: z.ZodOptional<z.ZodNumber>;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        expiry: z.ZodOptional<z.ZodObject<{
+            validUntilLedger: z.ZodOptional<z.ZodNumber>;
+            validUntilUnixSeconds: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        chain: z.ZodLiteral<"stellar">;
+        contract: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        spendingLimit: z.ZodOptional<z.ZodObject<{
+            token: z.ZodString;
+            limit: z.ZodString;
+            windowSeconds: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }, {
+            token: string;
+            limit: string;
+            windowSeconds: number;
+        }>>;
+        approvalThreshold: z.ZodOptional<z.ZodNumber>;
+        recipients: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        expiry: z.ZodOptional<z.ZodObject<{
+            validUntilLedger: z.ZodOptional<z.ZodNumber>;
+            validUntilUnixSeconds: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }, {
+            validUntilLedger?: number | undefined;
+            validUntilUnixSeconds?: number | undefined;
+        }>>;
     }, z.ZodTypeAny, "passthrough">>;
     ozConfig: z.ZodOptional<z.ZodObject<{
         network: z.ZodEnum<["mainnet", "testnet"]>;
@@ -2641,20 +2815,19 @@ export declare const VerifyPolicyInputSchema: z.ZodObject<{
     }> | undefined;
 }>;
 export type VerifyPolicyInput = z.infer<typeof VerifyPolicyInputSchema>;
-/** Pinned interpreter address (testnet). Mirrors DEPLOYMENTS.md:128.
+/** Pinned interpreter address (testnet).
  *  Single source for the MCP layer; do not embed elsewhere. */
 export declare const PINNED_INTERPRETER_TESTNET_ADDRESS = "CDR4NLV22STCXFGZPNKDQTEANWLF7LZ6AJLY6B7CLJXKHDZGYJWIOKGP";
-/** Pinned interpreter address (mainnet). Mirrors DEPLOYMENTS.md:18. Mainnet
+/** Pinned interpreter address (mainnet). Mainnet
  *  has now been deployed (2026-08-04); the mainnet interpreter IS the binary
  *  that was exercised on testnet (same wasm sha256, see
  *  PINNED_INTERPRETER_WASM_SHA256). The address differs because instance
- *  ids are network-scoped. UNAUDITED at the time of writing - see
- *  DEPLOYMENTS.md:29-32 for the recorded decision and what is still pending. */
+ *  ids are network-scoped. UNAUDITED at the time of writing. */
 export declare const PINNED_INTERPRETER_MAINNET_ADDRESS = "CALZAMUPREIRY4TULBEXIK77AUTOEJG63XLCPUWEHHQDOVK6ZVVS7VQ2";
-/** Pinned interpreter wasm sha256 (hex). Mirrors DEPLOYMENTS.md:156-157. */
+/** Pinned interpreter wasm sha256 (hex). */
 export declare const PINNED_INTERPRETER_WASM_SHA256 = "6e6c13d93e197aa380303a42cd120f5ddb080dd36ef2a343ee1dbd04ca52a443";
 /** The grammar version the interpreter enforces (matches SELF_VERSION in
- *  packages/policy-interpreter/src/version.rs). */
+ *  contracts/policy-interpreter/src/version.rs). */
 export declare const PINNED_INTERPRETER_GRAMMAR_VERSION = 1;
 /** Default Soroban RPC for the install / revoke / info tools. The recorder
  *  keeps its own copy in record/rpc.ts because it hands back a fetcher rather
@@ -2668,7 +2841,7 @@ export declare const TESTNET_RPC_URL = "https://soroban-testnet.stellar.org";
 export declare const MAINNET_RPC_URL = "https://mainnet.sorobanrpc.com";
 /** Pin + RPC lookup for the gate enforcement. The interpreters' wasm sha256
  *  is identical across both networks (the same binary was uploaded both
- *  places; DEPLOYMENTS.md:25-27), so `PINNED_INTERPRETER_WASM_SHA256` stays
+ *  places), so `PINNED_INTERPRETER_WASM_SHA256` stays
  *  a single constant - only the addresses and RPCs are network-scoped. */
 export declare const PINNED_INTERPRETER_ADDRESS_BY_NETWORK: Record<Network, string>;
 export declare const RPC_URL_BY_NETWORK: Record<Network, string>;
@@ -3403,15 +3576,24 @@ export declare const GetInterpreterInfoInputSchema: z.ZodObject<{
     /** When true, perform an optional live `grammar_version()` RPC call to
      *  verify the deployed contract matches the pin. */
     verifyLive: z.ZodOptional<z.ZodBoolean>;
-    /** Optional RPC URL override. */
+    /** Optional RPC URL override. When `verifyLive` is true, the URL must
+     *  equal the pinned RPC for the selected network unless
+     *  `allowUnpinnedRpcUrl: true` is also set (same opt-in shape as
+     *  install/revoke - the live grammar_version() answer binds to whichever
+     *  RPC returned it). */
     rpcUrl: z.ZodOptional<z.ZodString>;
+    /** Opt-in to using a non-pinned RPC URL when `verifyLive` is true. Same
+     *  semantics as install/revoke: the caller accepts the trust shift. */
+    allowUnpinnedRpcUrl: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     network?: "mainnet" | "testnet" | undefined;
     rpcUrl?: string | undefined;
+    allowUnpinnedRpcUrl?: boolean | undefined;
     verifyLive?: boolean | undefined;
 }, {
     network?: "mainnet" | "testnet" | undefined;
     rpcUrl?: string | undefined;
+    allowUnpinnedRpcUrl?: boolean | undefined;
     verifyLive?: boolean | undefined;
 }>;
 export type GetInterpreterInfoInput = z.infer<typeof GetInterpreterInfoInputSchema>;

package/dist/run/schemas.js

@@ -7,9 +7,9 @@
 // step with the TS source of truth.
 //
 // i128 amounts and other large integers are carried as base-10 decimal strings
-// end-to-end (no JS number coercion). Networks are pinned to the same closed
-// set the core defines. The discriminated union on `source` exposes BOTH
-// synthesize_policy front-ends through a single tool input.
+// end-to-end. Networks are pinned to the same closed set the core defines.
+// The discriminated union on `source` exposes BOTH synthesize_policy
+// front-ends through a single tool input.
 //
 // This module is the SINGLE source of truth for these shapes. The MCP package
 // imports them here so its tool-shape bindings stay in step; the CLI imports
@@ -123,7 +123,21 @@ export const MandateSpecSchema = z
     })
         .optional(),
 })
-    .passthrough();
+    .passthrough()
+    // TS-F4/F6: a `recipients` allowlist is only meaningful against a SEP-41
+    // method whose arg 1 IS the recipient (SAC/SEP-41 `transfer(from, to,
+    // amount)` and SEP-41 `mint(to, amount)`). Without this gate the
+    // `to-ir.ts` lowering pins the allowlist to `RECIPIENT_ARG_INDEX = 1`
+    // for any contract+method, which would let a non-SEP-41 method's
+    // arg[1] (e.g. an amount, an op type, an arbitrary address payload)
+    // be silently constrained as if it were a recipient. Refusing
+    // non-SEP-41 methods at the boundary is the fail-closed shape.
+    .refine((v) => v.recipients === undefined ||
+    v.recipients.length === 0 ||
+    v.method === 'transfer' ||
+    v.method === 'mint', {
+    message: 'recipients is only valid when method is a SEP-41 method (transfer or mint); other methods do not have a recipient at arg[1]',
+});
 /** ComposeUserResponses mirrors the core. */
 export const ComposeUserResponsesSchema = z
     .object({
@@ -264,7 +278,12 @@ export const PredicateLeafSchema = z.lazy(() => z.union([
         windowSeconds: z.number().int().positive(),
     }),
     z.object({ kind: z.literal('now') }),
-    z.object({ kind: z.literal('valid_until') }),
+    // `valid_until` is NOT in the public predicate grammar: the encoder +
+    // decoder already throw on it, so accepting it here would let a
+    // hand-crafted payload through the schema and only surface a 200+
+    // character internal-commentary error at encode time. Drop it - the
+    // policy's expiry is carried at the install layer (MandateSpec +
+    // validUntilLedger) instead.
     z.object({
         kind: z.literal('invocation_count_in_window'),
         windowSecs: z.number().int().positive(),
@@ -424,20 +443,19 @@ const MandateSpecSchemaForRule = z
 // install/revoke/get_info schemas live HERE (after the helper) so the const
 // reference resolves at module init. They are the new tools on top of the
 // existing four.
-/** Pinned interpreter address (testnet). Mirrors DEPLOYMENTS.md:128.
+/** Pinned interpreter address (testnet).
  *  Single source for the MCP layer; do not embed elsewhere. */
 export const PINNED_INTERPRETER_TESTNET_ADDRESS = 'CDR4NLV22STCXFGZPNKDQTEANWLF7LZ6AJLY6B7CLJXKHDZGYJWIOKGP';
-/** Pinned interpreter address (mainnet). Mirrors DEPLOYMENTS.md:18. Mainnet
+/** Pinned interpreter address (mainnet). Mainnet
  *  has now been deployed (2026-08-04); the mainnet interpreter IS the binary
  *  that was exercised on testnet (same wasm sha256, see
  *  PINNED_INTERPRETER_WASM_SHA256). The address differs because instance
- *  ids are network-scoped. UNAUDITED at the time of writing - see
- *  DEPLOYMENTS.md:29-32 for the recorded decision and what is still pending. */
+ *  ids are network-scoped. UNAUDITED at the time of writing. */
 export const PINNED_INTERPRETER_MAINNET_ADDRESS = 'CALZAMUPREIRY4TULBEXIK77AUTOEJG63XLCPUWEHHQDOVK6ZVVS7VQ2';
-/** Pinned interpreter wasm sha256 (hex). Mirrors DEPLOYMENTS.md:156-157. */
+/** Pinned interpreter wasm sha256 (hex). */
 export const PINNED_INTERPRETER_WASM_SHA256 = '6e6c13d93e197aa380303a42cd120f5ddb080dd36ef2a343ee1dbd04ca52a443';
 /** The grammar version the interpreter enforces (matches SELF_VERSION in
- *  packages/policy-interpreter/src/version.rs). */
+ *  contracts/policy-interpreter/src/version.rs). */
 export const PINNED_INTERPRETER_GRAMMAR_VERSION = 1;
 /** Default Soroban RPC for the install / revoke / info tools. The recorder
  *  keeps its own copy in record/rpc.ts because it hands back a fetcher rather
@@ -451,7 +469,7 @@ export const TESTNET_RPC_URL = 'https://soroban-testnet.stellar.org';
 export const MAINNET_RPC_URL = 'https://mainnet.sorobanrpc.com';
 /** Pin + RPC lookup for the gate enforcement. The interpreters' wasm sha256
  *  is identical across both networks (the same binary was uploaded both
- *  places; DEPLOYMENTS.md:25-27), so `PINNED_INTERPRETER_WASM_SHA256` stays
+ *  places), so `PINNED_INTERPRETER_WASM_SHA256` stays
  *  a single constant - only the addresses and RPCs are network-scoped. */
 export const PINNED_INTERPRETER_ADDRESS_BY_NETWORK = {
     testnet: PINNED_INTERPRETER_TESTNET_ADDRESS,
@@ -471,13 +489,26 @@ export const NETWORK_PASSPHRASES = {
     testnet: 'Test SDF Network ; September 2015',
     mainnet: 'Public Global Stellar Network ; September 2015',
 };
+// Stellar strkey shapes (StrKey base32, no checksum byte, version byte
+// 0x30/0x40 prefixed by the decoder, then 32 base32 chars giving a 56-char
+// total). The shared `isStellarAddress` helper accepts BOTH wallet (G...) and
+// contract (C...) addresses; the install schema has to distinguish them
+// because the smart account is a contract (C...) - a wallet address would
+// mean the rule is being installed against the WRONG account kind entirely.
+// `sourceAccount` is the signing wallet (G...).
+const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/;
+const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/;
 export const InstallPolicyInputSchema = z
     .object({
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z.string(),
+    smartAccount: z
+        .string()
+        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z.string(),
+    sourceAccount: z
+        .string()
+        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -516,12 +547,16 @@ export const InstallPolicyInputSchema = z
 export const RevokePolicyInputSchema = z
     .object({
     /** The smart account contract address (C...). */
-    smartAccount: z.string(),
+    smartAccount: z
+        .string()
+        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z.string(),
+    sourceAccount: z
+        .string()
+        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: NetworkSchema.optional(),
@@ -543,8 +578,15 @@ export const GetInterpreterInfoInputSchema = z.object({
     /** When true, perform an optional live `grammar_version()` RPC call to
      *  verify the deployed contract matches the pin. */
     verifyLive: z.boolean().optional(),
-    /** Optional RPC URL override. */
+    /** Optional RPC URL override. When `verifyLive` is true, the URL must
+     *  equal the pinned RPC for the selected network unless
+     *  `allowUnpinnedRpcUrl: true` is also set (same opt-in shape as
+     *  install/revoke - the live grammar_version() answer binds to whichever
+     *  RPC returned it). */
     rpcUrl: z.string().url().optional(),
+    /** Opt-in to using a non-pinned RPC URL when `verifyLive` is true. Same
+     *  semantics as install/revoke: the caller accepts the trust shift. */
+    allowUnpinnedRpcUrl: z.boolean().optional(),
 });
 // ===== Error envelope (canonical) =====
 //