@crediolabs/policy-synth 0.1.5 → 0.1.6

package/dist/record/decode.js

@@ -268,6 +268,26 @@ export function scValToSubset(val, path, opaqueScVals, depth = 0) {
                 value: arr.map((v, i) => scValToSubset(v, `${path}[${i}]`, opaqueScVals, depth + 1)),
             };
         }
+        case 'scvMap': {
+            if (depth >= MAX_SCVAL_DEPTH) {
+                opaqueScVals.push({ path, type: 'depth-exceeded' });
+                return { type: 'other', value: 'depth-exceeded' };
+            }
+            // Map<Symbol, ScVal> is the canonical data shape for SAC/SEP-41
+            // transfer/mint/burn events on Stellar mainnet (verified empirically
+            // against txs 112d2392..., eb39f493..., 50d36f5c...). The entry key is
+            // carried forward so readAmount can route to the conventional field
+            // name without re-decoding the full XDR. Non-symbol / non-string keys
+            // are stringified via the same key-to-string rule used for topics.
+            const entries = (val.map() ?? []);
+            return {
+                type: 'map',
+                value: entries.map((entry, i) => ({
+                    key: mapKeyToString(entry.key(), `${path}.key[${i}]`, opaqueScVals),
+                    val: scValToSubset(entry.val(), `${path}.val[${i}]`, opaqueScVals, depth + 1),
+                })),
+            };
+        }
         case 'scvBytes': {
             return { type: 'bytes', value: Buffer.from(val.bytes()).toString('hex') };
         }
@@ -345,6 +365,29 @@ export function scValToTopicString(val) {
         return Buffer.from(val.bytes()).toString('hex');
     return `<${kind}>`;
 }
+/** Convert a Map<Symbol, ...> key ScVal to the string used in the normalised
+ *  ScVal map representation. Uses the same string-form rule as
+ *  `scValToTopicString` so SAC/SEP-41 event Map keys ("amount", "to_muxed_id")
+ *  resolve to the same string in both the topic path and the map-entry path.
+ *  Non-symbol / non-string keys record an opaque diagnostic and return a
+ *  placeholder so the Map entry is still carried forward. */
+function mapKeyToString(val, path, opaqueScVals) {
+    const kind = val.switch().name;
+    if (kind === 'scvSymbol')
+        return val.sym().toString();
+    if (kind === 'scvString')
+        return val.str().toString();
+    if (kind === 'scvU64')
+        return u64PartsToBigInt(val.u64()).toString();
+    if (kind === 'scvU32')
+        return val.u32().toString();
+    if (kind === 'scvI128')
+        return i128PartsToBigInt(val.i128()).toString();
+    if (kind === 'scvBytes')
+        return Buffer.from(val.bytes()).toString('hex');
+    opaqueScVals.push({ path, type: `unsupported-map-key:${kind}` });
+    return `<${kind}>`;
+}
 /** Build the OnChainEvent[] view from raw contract events. Diagnostic-only:
  *  captures the topics + data + emitter contract for the downstream
  *  validator. */

package/dist/record/freshness.d.ts

@@ -13,5 +13,18 @@ export declare function computeParseConfidence(input: FreshnessInput): ParseConf
  *  ToolError with the ParseConfidence payload attached as `details`. */
 export declare function isBelowThreshold(c: ParseConfidence): boolean;
 /** Convenience: build the user-facing remediation question for an
- *  under-confidence recording. */
+ *  under-confidence recording.
+ *
+ *  The remediation text branches on which diagnostic bucket is non-empty:
+ *    - unknownContracts only -> user MUST supply an ABI (or re-capture
+ *      against a known protocol version). The contract is real, the
+ *      recorder just cannot decode it.
+ *    - opaqueScVals only -> the recorder encountered a value shape it
+ *      should support but did not decode. The user cannot supply an ABI
+ *      to fix a decoder bug; the guidance explicitly says so and points at
+ *      re-running after a tool upgrade / reporting the path.
+ *    - both -> list both diagnostics AND chain the right remediation for
+ *      each (the user supplies an ABI AND reports the decoder gap).
+ *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
+ *      text; the user did not actually hit a code-level barrier. */
 export declare function buildLowConfidenceQuestion(c: ParseConfidence): string;

package/dist/record/freshness.js

@@ -36,8 +36,23 @@ export function isBelowThreshold(c) {
     return c.overall < c.thresholdUsed;
 }
 /** Convenience: build the user-facing remediation question for an
- *  under-confidence recording. */
+ *  under-confidence recording.
+ *
+ *  The remediation text branches on which diagnostic bucket is non-empty:
+ *    - unknownContracts only -> user MUST supply an ABI (or re-capture
+ *      against a known protocol version). The contract is real, the
+ *      recorder just cannot decode it.
+ *    - opaqueScVals only -> the recorder encountered a value shape it
+ *      should support but did not decode. The user cannot supply an ABI
+ *      to fix a decoder bug; the guidance explicitly says so and points at
+ *      re-running after a tool upgrade / reporting the path.
+ *    - both -> list both diagnostics AND chain the right remediation for
+ *      each (the user supplies an ABI AND reports the decoder gap).
+ *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
+ *      text; the user did not actually hit a code-level barrier. */
 export function buildLowConfidenceQuestion(c) {
+    const hasUnknown = c.unknownContracts.length > 0;
+    const hasOpaque = c.opaqueScVals.length > 0;
     const reasons = [];
     for (const u of c.unknownContracts) {
         reasons.push(`unknown contract ${u.contract} (${u.reason})`);
@@ -46,5 +61,20 @@ export function buildLowConfidenceQuestion(c) {
         reasons.push(`opaque ScVal at ${o.path} (${o.type})`);
     }
     const why = reasons.length === 0 ? 'no diagnostic reason available' : reasons.join('; ');
-    return `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}. Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+    const header = `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}.`;
+    // The two remediation branches are explicit so the user (or the agent)
+    // can dispatch on the verb. The "unknown contract" branch is the only
+    // one that asks for an ABI; the "opaque ScVal" branch asks the user to
+    // report the path and re-run after a tool upgrade.
+    if (hasUnknown && hasOpaque) {
+        return (`${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version; ` +
+            `also file the opaque ScVal path against the recorder (decoder limitation) and re-run record_transaction after a tool upgrade.`);
+    }
+    if (hasUnknown) {
+        return `${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+    }
+    if (hasOpaque) {
+        return `${header} This is a recorder decoder limitation (the value shape is supported in principle but not yet decoded) - the agent cannot fix it by supplying an ABI. Report the opaque ScVal path above against the recorder and re-run record_transaction after a tool upgrade.`;
+    }
+    return `${header} No actionable diagnostic was recorded; re-run record_transaction against a fresh fetch and inspect the events.`;
 }

package/dist/record/index.d.ts

@@ -5,6 +5,9 @@ import { type RpcFetcher } from './rpc.ts';
  *    - exactly one of `hash` / `xdr`
  *    - `network` for hash mode (selects the public RPC)
  *    - optional injected `fetcher` for tests + custom RPC endpoints
+ *    - optional `crossNetworkFetcher` (item 2) for tests + offline use;
+ *      production builds the cross-network probe from `createRpcServer` when
+ *      this field is absent
  *    - optional `confidenceOverride` to relax the gate (default 1.0)
  *
  *  In xdr mode `network` is still required so the caller documents intent
@@ -15,6 +18,14 @@ export interface RecordInput {
     xdr?: string;
     network: Network;
     fetcher?: RpcFetcher;
+    /** Test-only seam + explicit production override for the cross-network
+     *  probe (item 2). When the primary fetcher returns null on hash mode,
+     *  the recorder also tries this fetcher against the OTHER network. If it
+     *  finds the hash there, the recorder returns a specific actionable
+     *  error mentioning the actual network. When unset, the recorder builds
+     *  this fetcher from `createRpcServer(otherNetwork)` so the help fires
+     *  automatically; tests can pass a deterministic stub. */
+    crossNetworkFetcher?: RpcFetcher;
     confidenceOverride?: number;
 }
 export type RecordResult = ToolResponse<RecordedTransaction>;

package/dist/record/index.js

@@ -50,6 +50,21 @@ export async function recordTransaction(input) {
             return err('RECORDING_FAILED', 'hash required for on-chain mode', false);
         const fetched = await fetcher(hash);
         if (!fetched) {
+            // Item 2: cross-network sanity check. The default NOT_FOUND message
+            // ("transaction X not found on <network>") is not actionable when the
+            // user just used the wrong --network. Probe the OTHER network's
+            // fetcher before giving up: if the hash actually exists there, the
+            // user almost certainly passed the wrong network flag. Trade-off:
+            // one extra RPC round-trip ONLY on the NOT_FOUND path (the happy
+            // path is unchanged; NOT_FOUND is rare). The probe is auto-built
+            // from createRpcServer(otherNetwork) when the caller did not inject
+            // one; tests pass an explicit stub for offline determinism.
+            const otherNetwork = input.network === 'mainnet' ? 'testnet' : 'mainnet';
+            const crossFetcher = input.crossNetworkFetcher ?? createRpcServer(otherNetwork);
+            const crossFetched = await crossFetcher(hash);
+            if (crossFetched) {
+                return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}; it exists on ${otherNetwork}. Re-run with --network ${otherNetwork} (or the corresponding MCP / API field).`, true);
+            }
             return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}`, true);
         }
         const events = combineEvents(fetched.events);
@@ -125,6 +140,16 @@ function finish(network, decoded, confidenceOverride) {
         unknownContracts: decoded.unknownContracts,
         opaqueScVals: decoded.opaqueScVals,
     });
+    // Item 1: surface the "zero contract invocations decoded" case explicitly.
+    // The math already pins overall = 1.0 via the `denom === 0` guard; the
+    // marker just makes the silence visible so a downstream synth can refuse
+    // the recording (a policy must scope to an authorized contract call)
+    // without inferring the situation from `invocations: []` next to a
+    // confidence of 1.0. Only set when zero invocations were actually decoded
+    // - the marker is a positive signal, not a default.
+    if (decoded.invocations.length === 0) {
+        confidence = { ...confidence, noInvocations: true };
+    }
     if (typeof confidenceOverride === 'number') {
         confidence = { ...confidence, thresholdUsed: confidenceOverride };
     }

package/dist/record/movements.d.ts

@@ -9,9 +9,21 @@ export declare function extractTokenMovements(events: OnChainEvent[], opaqueScVa
 }>): TokenMovement[];
 /** Read an I128 amount from an event data ScVal. Supports:
  *    - data is I128 directly
- *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128
- *    - data is a Vec whose [0] is a Map { 'amount': I128 }
- *    - data is U64 (fallback for amount fields encoded as u64) */
+ *    - data is U64 (fallback for amount fields encoded as u64)
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128 / U64
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 | U64 }
+ *    - data is a Map whose entry with key "amount" is I128 / U64
+ *
+ *  The Map shapes are the canonical data layout for SAC/SEP-41 `transfer`,
+ *  `mint`, and `burn` events on Stellar mainnet, e.g. the USDC SAC and every
+ *  Stellar Asset Contract. The key `amount` is the SEP-41-defined field name
+ *  (verified empirically against txs 112d2392..., eb39f493..., 50d36f5c...
+ *  where the data is `Map { amount: I128, to_muxed_id: ... }`). The other
+ *  Map entries we observe in the wild (to_muxed_id, from_muxed_id) are
+ *  muxed-address adjuncts that the recorder does not support as topic
+ *  addresses; they are ignored here on purpose. A Map without an `amount`
+ *  entry, or with an `amount` entry that is not I128/U64, returns null
+ *  (fail-closed). */
 export declare function readAmount(data: OnChainEvent['data']): string | null;
 /** Re-decode a single ContractEvent body into a TokenMovement-shaped tuple,
  *  given the raw xdr.ScVal form (NOT the OnChainEvent subset). Used by the

package/dist/record/movements.js

@@ -81,25 +81,60 @@ function parseSingleEvent(evt) {
 }
 /** Read an I128 amount from an event data ScVal. Supports:
  *    - data is I128 directly
- *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128
- *    - data is a Vec whose [0] is a Map { 'amount': I128 }
- *    - data is U64 (fallback for amount fields encoded as u64) */
+ *    - data is U64 (fallback for amount fields encoded as u64)
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128 / U64
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 | U64 }
+ *    - data is a Map whose entry with key "amount" is I128 / U64
+ *
+ *  The Map shapes are the canonical data layout for SAC/SEP-41 `transfer`,
+ *  `mint`, and `burn` events on Stellar mainnet, e.g. the USDC SAC and every
+ *  Stellar Asset Contract. The key `amount` is the SEP-41-defined field name
+ *  (verified empirically against txs 112d2392..., eb39f493..., 50d36f5c...
+ *  where the data is `Map { amount: I128, to_muxed_id: ... }`). The other
+ *  Map entries we observe in the wild (to_muxed_id, from_muxed_id) are
+ *  muxed-address adjuncts that the recorder does not support as topic
+ *  addresses; they are ignored here on purpose. A Map without an `amount`
+ *  entry, or with an `amount` entry that is not I128/U64, returns null
+ *  (fail-closed). */
 export function readAmount(data) {
     if (data.type === 'i128')
         return data.value;
     if (data.type === 'u64')
         return data.value;
+    if (data.type === 'map')
+        return readAmountFromMap(data.value);
     if (data.type !== 'vec')
         return null;
-    const v = data.value;
-    // SAC transfer event data shape (some clients): Vec<Address, I128>
-    for (const item of v) {
+    // Vec shape: walk the elements and accept the first I128/U64 OR a Map whose
+    // 'amount' entry is I128/U64. SAC transfer event data is sometimes
+    // Vec<Address, I128> and sometimes Vec<Map{amount: I128}, ...>; both reach
+    // the same code path below.
+    for (const item of data.value) {
         if (item.type === 'i128')
             return item.value;
         if (item.type === 'u64')
             return item.value;
+        if (item.type === 'map') {
+            const fromMap = readAmountFromMap(item.value);
+            if (fromMap !== null)
+                return fromMap;
+        }
+    }
+    return null;
+}
+/** Try to extract an I128/U64 amount from a Map's `amount` entry. Returns
+ *  null when the Map lacks an `amount` key or the entry is not a numeric
+ *  ScVal kind this recorder understands. */
+function readAmountFromMap(entries) {
+    for (const entry of entries) {
+        if (entry.key !== 'amount')
+            continue;
+        if (entry.val.type === 'i128')
+            return entry.val.value;
+        if (entry.val.type === 'u64')
+            return entry.val.value;
+        return null;
     }
-    // Some flavours wrap in a Map. We expose Map entries as other; bail.
     return null;
 }
 /** Extract a single address from an event data ScVal at the given vec index. */

package/dist/run/index.d.ts

@@ -1,4 +1,4 @@
-import { type ProposedPolicy, type RecordedTransaction, type ToolResponse } from '../index.ts';
+import { type ErrorCode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
 import { type RecordTransactionInput, type SynthesizePolicyInput } from './schemas.ts';
 export type { RecordTransactionInput, SynthesizePolicyInput } from './schemas.ts';
 export { ComposeUserResponsesSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OzAdapterConfigSchema, RecordedTransactionSchema, RecordTransactionInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from './schemas.ts';
@@ -29,3 +29,15 @@ export declare function runRecordTransaction(raw: unknown): Promise<ToolResponse
  *  XDR decode error in the adapter) would otherwise surface as
  *  "[object Object]" in the MCP transport. */
 export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>>;
+/** 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', code: ErrorCode, e: unknown): ToolError;

package/dist/run/index.js

@@ -134,23 +134,19 @@ function validationError(toolName, issues) {
     };
 }
 /** Build a canonical ToolError for a thrown exception caught by the tool
- *  envelope. We refuse to surface the raw exception's text (the MCP SDK
- *  stringifies thrown objects as "[object Object]"), 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. */
-function caughtError(toolName, code, e) {
-    let message;
-    if (e instanceof Error) {
-        message = e.message || `${toolName}: unknown error`;
-    }
-    else if (typeof e === 'string') {
-        message = e;
-    }
-    else {
-        message = `${toolName}: caught non-Error throw of type ${typeof e}`;
-    }
+ *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
+ *  default, so we extract a string-friendly message and tag the original
+ *  error in `details` for the agent to inspect. The `code` is the tool's
+ *  domain code (RECORDING_FAILED for `record_transaction`, SYNTHESIS_ERROR
+ *  for `synthesize_policy`) so the agent dispatches on the same code the
+ *  structured ToolError would carry.
+ *
+ *  Exported as `_caughtError` (the leading underscore signals the test-only
+ *  seam) so the suite in run/index.test.ts can drive the envelope path
+ *  without standing up a full recordTransaction pipeline. */
+export function caughtError(toolName, code, e) {
+    const message = describeThrown(e, toolName);
+    const details = { thrown: safeStringify(e) };
     return {
         code,
         message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
@@ -159,6 +155,68 @@ function caughtError(toolName, code, e) {
         remediation: {
             toolCall: { name: toolName, args: {} },
         },
-        details: { thrown: String(e) },
+        details,
     };
 }
+/** Build a human-readable message for an unknown caught value. Order matters:
+ *    1. `Error` instances use `.message` (or fallback to the class name).
+ *    2. Native strings pass through verbatim.
+ *    3. Objects with a string `message` field use that field (mirrors the
+ *       shape thrown by some SDKs that package errors as plain objects).
+ *    4. Anything else falls back to a JSON-shaped summary, never to
+ *       "[object Object]".
+ *  The full payload is also captured in `details.thrown` via
+ *  `safeStringify` so the agent can inspect the original value without
+ *  risking an infinite loop on circular refs. */
+function describeThrown(e, toolName) {
+    if (e instanceof Error) {
+        return e.message || `${toolName}: ${e.name || 'Error'}`;
+    }
+    if (typeof e === 'string') {
+        return e;
+    }
+    if (e !== null && typeof e === 'object') {
+        const obj = e;
+        const m = obj.message;
+        if (typeof m === 'string' && m.length > 0) {
+            return truncate(m);
+        }
+        return truncate(safeStringify(e));
+    }
+    return `${toolName}: caught non-Error throw of type ${typeof e}`;
+}
+/** Hard cap on the human-readable message embedded in the ToolError. The full
+ *  payload is still preserved in `details.thrown` so the agent can inspect
+ *  it - the truncation is only to keep the top-level message small enough to
+ *  fit comfortably in transport logs. */
+const MAX_MESSAGE_LEN = 512;
+/** JSON.stringify that survives circular refs and very large payloads. The
+ *  output is itself bounded by the same `MAX_DETAILS_LEN` so a thrown object
+ *  with megabytes of buffer data cannot bloat the WHOLE envelope. */
+const MAX_DETAILS_LEN = 4096;
+function safeStringify(v) {
+    const seen = new WeakSet();
+    const json = JSON.stringify(v, (_k, value) => {
+        if (typeof value === 'bigint')
+            return value.toString();
+        if (typeof value === 'function')
+            return `[function ${value.name || 'anonymous'}]`;
+        if (value instanceof Error) {
+            return { name: value.name, message: value.message, stack: value.stack };
+        }
+        if (value !== null && typeof value === 'object') {
+            if (seen.has(value))
+                return '[Circular]';
+            seen.add(value);
+        }
+        return value;
+    }, 2);
+    if (json === undefined)
+        return '<unserializable>';
+    return truncate(json, MAX_DETAILS_LEN);
+}
+function truncate(s, cap = MAX_MESSAGE_LEN) {
+    if (s.length <= cap)
+        return s;
+    return `${s.slice(0, cap)}\n…[truncated ${s.length - cap} chars]`;
+}

package/dist/run/schemas.d.ts

@@ -446,16 +446,19 @@ export declare const ComposeUserResponsesSchema: z.ZodObject<{
     validUntilLedger: z.ZodOptional<z.ZodNumber>;
     limitAmount: z.ZodOptional<z.ZodString>;
     invocationLimit: z.ZodOptional<z.ZodNumber>;
+    swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     windowSeconds: z.ZodOptional<z.ZodNumber>;
     validUntilLedger: z.ZodOptional<z.ZodNumber>;
     limitAmount: z.ZodOptional<z.ZodString>;
     invocationLimit: z.ZodOptional<z.ZodNumber>;
+    swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     windowSeconds: z.ZodOptional<z.ZodNumber>;
     validUntilLedger: z.ZodOptional<z.ZodNumber>;
     limitAmount: z.ZodOptional<z.ZodString>;
     invocationLimit: z.ZodOptional<z.ZodNumber>;
+    swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
 }, z.ZodTypeAny, "passthrough">>;
 /** OzAdapterConfig - the per-network OZ built-in instance addresses. */
 export declare const OzAdapterConfigSchema: z.ZodObject<{
@@ -1003,16 +1006,19 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough">>>;
     confidenceOverride: z.ZodOptional<z.ZodObject<{
         threshold: z.ZodNumber;
@@ -1130,6 +1136,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     confidenceOverride?: {
         threshold: number;
@@ -1193,6 +1200,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     confidenceOverride?: {
         threshold: number;
@@ -1649,16 +1657,19 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough">>>;
     confidenceOverride: z.ZodOptional<z.ZodObject<{
         threshold: z.ZodNumber;
@@ -1776,6 +1787,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     confidenceOverride?: {
         threshold: number;
@@ -1839,6 +1851,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     confidenceOverride?: {
         threshold: number;

package/dist/run/schemas.js

@@ -15,6 +15,7 @@
 // imports them here so its tool-shape bindings stay in step; the CLI imports
 // them here so it can build the same args envelope the MCP transport builds.
 import { z } from 'zod';
+import { isStellarAddress } from "../synth/address.js";
 /** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
  *  installed on-chain, so reject it at the boundary (fail-closed). */
 const U32_MAX = 4294967295;
@@ -126,6 +127,13 @@ export const ComposeUserResponsesSchema = z
         .regex(/^[0-9]+$/)
         .optional(),
     invocationLimit: z.number().int().positive().optional(),
+    // Swap recipient allowlist (SoroSwap call_arg[3]). Each entry must be a
+    // Stellar address (G... wallet or C... contract); supplying it REPLACES the
+    // default pin to the recorded recipient. Validated with the shared StrKey
+    // helper (no hand-rolled regex).
+    swapRecipientAllowlist: z
+        .array(z.string().refine(isStellarAddress, 'must be a Stellar address (G... or C...)'))
+        .optional(),
 })
     .passthrough();
 /** OzAdapterConfig - the per-network OZ built-in instance addresses. */

package/dist/synth/address.d.ts

@@ -0,0 +1,7 @@
+/** True when `s` is a valid Stellar address strkey - either an Ed25519 public
+ *  key (`G...`) or a contract address (`C...`). Backed by the SDK's `StrKey`
+ *  decoder (the same one the recorder uses in `record/decode.ts`); no
+ *  hand-rolled regex. Used to validate a caller-supplied swap recipient
+ *  allowlist, whose entries may be either a wallet (`G...`) or a contract
+ *  (`C...`). */
+export declare function isStellarAddress(s: string): boolean;

package/dist/synth/address.js

@@ -0,0 +1,12 @@
+// src/synth/address.ts - Stellar address validation shared by the CLI + the
+// run-layer Zod schema.
+import { StrKey } from '@stellar/stellar-sdk';
+/** True when `s` is a valid Stellar address strkey - either an Ed25519 public
+ *  key (`G...`) or a contract address (`C...`). Backed by the SDK's `StrKey`
+ *  decoder (the same one the recorder uses in `record/decode.ts`); no
+ *  hand-rolled regex. Used to validate a caller-supplied swap recipient
+ *  allowlist, whose entries may be either a wallet (`G...`) or a contract
+ *  (`C...`). */
+export function isStellarAddress(s) {
+    return StrKey.isValidEd25519PublicKey(s) || StrKey.isValidContract(s);
+}

package/dist/synth/compose-from-recording.d.ts

@@ -28,9 +28,10 @@ export interface ComposeUserResponses {
      *  entries on the same asset emit multiple leaves. */
     oraclePriceBound?: OraclePriceBound[];
     /** Recipient allowlist for a swap (call_arg[3] on SoroSwap's
-     *  swap_exact_tokens_for_tokens). Absent -> RECIPIENT_ALLOWLIST_EMPTY
-     *  ambiguity (the caller is prompted; proceeding without an allowlist leaves
-     *  the recipient unconstrained). */
+     *  swap_exact_tokens_for_tokens). When supplied, it REPLACES the default
+     *  pin. Absent -> the recipient is pinned to the recorded value (mirroring
+     *  SEP-41) and RECIPIENT_ALLOWLIST_EMPTY is surfaced as informational, never
+     *  a silent free pass. */
     swapRecipientAllowlist?: string[];
 }
 /** Composition options. */

package/dist/synth/compose-from-recording.js

@@ -308,11 +308,16 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
         }
         // Swap recipient (call_arg[3]): when the caller supplies
         // swapRecipientAllowlist, emit it as an `in` constraint on the recipient
-        // arg. When absent, surface RECIPIENT_ALLOWLIST_EMPTY so the caller is
-        // prompted; proceeding without an allowlist leaves the recipient
-        // unconstrained in the predicate. The ambiguity is only surfaced when
-        // the interpreter is enabled - if it isn't, the swap recipient is just
-        // ignored (today's behaviour).
+        // arg. When absent, PIN the recipient to the recorded value - mirroring the
+        // SEP-41 `to` arg above: the recorded flow went to exactly one recipient, so
+        // pinning it is the minimal policy that permits exactly that flow. Leaving
+        // it unconstrained would permit an arbitrary recipient (an evil twin with
+        // call_arg[3] = attacker_wallet). RECIPIENT_ALLOWLIST_EMPTY is still
+        // surfaced, but as INFORMATIONAL (the recipient was pinned; here is how to
+        // widen it), never as a silent free pass. The recipient is only enforceable
+        // via the interpreter predicate, so the pin (and the ambiguity) apply only
+        // when the interpreter is enabled - otherwise the swap recipient is ignored
+        // (today's behaviour, matching the other SoroSwap constraints).
         const recipientArg = topLevel.args[3];
         if (swapRecipientAllowlist && swapRecipientAllowlist.length > 0) {
             const cond = {
@@ -328,9 +333,14 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
             }
         }
         else if (interpreterEnabled && recipientArg && recipientArg.type === 'address') {
+            interpreterConstraints.push({
+                op: 'in',
+                selector: { kind: 'arg', argIndex: 3, scalarType: 'address' },
+                values: [recipientArg.value],
+            });
             ambiguities.push({
                 code: 'RECIPIENT_ALLOWLIST_EMPTY',
-                question: `Recording shows the swap sending to ${recipientArg.value}. What recipient allowlist should the interpreter predicate bind? (omit to leave recipient unconstrained)`,
+                question: `No recipient allowlist supplied; the swap recipient (call_arg[3]) was pinned to the recorded value ${recipientArg.value}. To permit additional recipients, supply an allowlist (CLI: --recipient <C...|G...>, repeatable; MCP: userResponses.swapRecipientAllowlist) - it REPLACES this default pin.`,
             });
         }
     }

package/dist/synth/deny-cases.d.ts

@@ -8,5 +8,15 @@ export interface GeneratedCases {
     permit: EvalContext;
     denies: DenyCase[];
 }
-/** Build deterministic model-evaluated alternatives without mutating the intended call. */
-export declare function generateCases(predicate: PredicateNode, permitCtx: EvalContext): GeneratedCases;
+declare const OVERPERMISSIVE_DIMENSIONS: readonly ["argument_reorder"];
+declare const ORIGINAL_DIMENSIONS: string[];
+export { ORIGINAL_DIMENSIONS, OVERPERMISSIVE_DIMENSIONS };
+/** Build deterministic model-evaluated alternatives without mutating the intended call.
+ *
+ * @param predicate   - the synthesized predicate
+ * @param permitCtx   - EvalContext for the intended (permitted) call
+ * @param dimensions  - optional whitelist of dimension names to emit; when omitted
+ *                     all known dimensions (including over-permissiveness mutations)
+ *                     are emitted. The synth pipeline passes ORIGINAL_DIMENSIONS so
+ *                     existing fixtures do not regress. */
+export declare function generateCases(predicate: PredicateNode, permitCtx: EvalContext, dimensions?: string[]): GeneratedCases;