@crediolabs/policy-synth 0.1.5 → 0.1.7

package/src/record/decode.ts

@@ -383,6 +383,26 @@ export function scValToSubset(
         ),
       }
     }
+    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() ?? []) as xdr.ScMapEntry[]
+      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() as Uint8Array).toString('hex') }
     }
@@ -469,6 +489,28 @@ export function scValToTopicString(val: xdr.ScVal): string {
   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: xdr.ScVal,
+  path: string,
+  opaqueScVals: ParseConfidence['opaqueScVals']
+): string {
+  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() as Uint8Array).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/src/record/freshness.ts

@@ -49,8 +49,23 @@ export 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 function buildLowConfidenceQuestion(c: ParseConfidence): string {
+  const hasUnknown = c.unknownContracts.length > 0
+  const hasOpaque = c.opaqueScVals.length > 0
   const reasons: string[] = []
   for (const u of c.unknownContracts) {
     reasons.push(`unknown contract ${u.contract} (${u.reason})`)
@@ -59,5 +74,22 @@ export function buildLowConfidenceQuestion(c: ParseConfidence): string {
     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/src/record/index.ts

@@ -41,6 +41,9 @@ import { validateAgainstEvents } from './validate.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
@@ -51,6 +54,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
 }
 
@@ -92,6 +103,25 @@ export async function recordTransaction(input: RecordInput): Promise<RecordResul
     if (!hash) 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: Network = 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)
@@ -184,6 +214,16 @@ function finish(
     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/src/record/movements.ts

@@ -87,20 +87,53 @@ function parseSingleEvent(evt: OnChainEvent): TokenMovement | null {
 
 /** 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: OnChainEvent['data']): string | null {
   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: Array<{ key: string; val: OnChainEvent['data'] }>
+): string | null {
+  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
 }
 

package/src/run/index.ts

@@ -181,25 +181,23 @@ function validationError(
 }
 
 /** 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(
+ *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
+ *  default, so we extract a string-friendly message and tag the original
+ *  error in `details` for the agent to inspect. The `code` is the tool's
+ *  domain code (RECORDING_FAILED for `record_transaction`, SYNTHESIS_ERROR
+ *  for `synthesize_policy`) so the agent dispatches on the same code the
+ *  structured ToolError would carry.
+ *
+ *  Exported as `_caughtError` (the leading underscore signals the test-only
+ *  seam) so the suite in run/index.test.ts can drive the envelope path
+ *  without standing up a full recordTransaction pipeline. */
+export function caughtError(
   toolName: 'record_transaction' | 'synthesize_policy',
   code: ErrorCode,
   e: unknown
 ): ToolError {
-  let message: string
-  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}`
-  }
+  const message = describeThrown(e, toolName)
+  const details = { thrown: safeStringify(e) }
   return {
     code,
     message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
@@ -208,6 +206,72 @@ function caughtError(
     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: unknown, toolName: string): string {
+  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 as Record<string, unknown>
+    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: unknown): string {
+  const seen = new WeakSet<object>()
+  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: string, cap = MAX_MESSAGE_LEN): string {
+  if (s.length <= cap) return s
+  return `${s.slice(0, cap)}\n…[truncated ${s.length - cap} chars]`
+}

package/src/run/schemas.ts

@@ -16,6 +16,7 @@
 // them here so it can build the same args envelope the MCP transport builds.
 
 import { z } from 'zod'
+import { isStellarAddress } from '../synth/address.ts'
 
 /** 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). */
@@ -41,6 +42,13 @@ export const ScValSchema: z.ZodType<unknown> = z.lazy(() =>
     z.object({ type: z.literal('u32'), value: z.string().regex(/^[0-9]+$/) }),
     z.object({ type: z.literal('symbol'), value: z.string() }),
     z.object({ type: z.literal('vec'), value: z.array(ScValSchema) }),
+    // Map mirrors the core ScVal. Real Blend `submit` calls carry a vec of maps
+    // as the request argument, so omitting it here made the synthesizer reject a
+    // recording its own recorder had just produced at full confidence.
+    z.object({
+      type: z.literal('map'),
+      value: z.array(z.object({ key: z.string(), val: ScValSchema })),
+    }),
     z.object({ type: z.literal('bytes'), value: z.string() }),
     z.object({ type: z.literal('other'), value: z.string() }),
   ])
@@ -142,6 +150,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()
 

package/src/synth/address.ts

@@ -0,0 +1,14 @@
+// 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: string): boolean {
+  return StrKey.isValidEd25519PublicKey(s) || StrKey.isValidContract(s)
+}

package/src/synth/compose-from-recording.ts

@@ -81,9 +81,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[]
 }
 
@@ -416,11 +417,16 @@ function appendProtocolSpecificConstraints(
 
     // 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: IRCondition = {
@@ -434,9 +440,14 @@ function appendProtocolSpecificConstraints(
         ozConstraints.push(cond)
       }
     } 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/src/synth/deny-cases.ts

@@ -45,8 +45,45 @@ const ADJACENT_ASSETS = [
   'CCWCLTASNDT57N3BCHOSVB5QWMV5URK4BXLDDF6ZZQYMBQ4OKZA3ZB2N',
 ] as const
 
-/** Build deterministic model-evaluated alternatives without mutating the intended call. */
-export function generateCases(predicate: PredicateNode, permitCtx: EvalContext): GeneratedCases {
+// Phase 1 property-harness mutation dimensions excluded from the synth pipeline's
+// self-verify call so existing fixtures still emit policies. The harness tests
+// them as FINDINGS against the already-emitted policy.
+const OVERPERMISSIVE_DIMENSIONS = ['argument_reorder'] as const
+
+// The 15 dimensions the synth pipeline uses for self-verify and minimise.
+const ORIGINAL_DIMENSIONS: string[] = [
+  'amount',
+  'asset',
+  'contract',
+  'function',
+  'timing',
+  'time_window',
+  'invocation_count',
+  'arg_amount_bound',
+  'arg_bound',
+  'scope_contract_fn_arg',
+  'oracle_stale',
+  'oracle_missing',
+  'oracle_deviation_exceeded',
+  'oracle_paused',
+  'soroswap_allowed_path',
+]
+
+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 function generateCases(
+  predicate: PredicateNode,
+  permitCtx: EvalContext,
+  dimensions?: string[]
+): GeneratedCases {
   const facts = inspectPredicate(predicate)
   const denies: DenyCase[] = []
 
@@ -210,6 +247,33 @@ export function generateCases(predicate: PredicateNode, permitCtx: EvalContext):
     denies.push({ dimension: 'soroswap_allowed_path', ctx })
   }
 
+  // --- argument_reorder: swap first two address args ---
+  // Skipped when dimensions filter is active so the synth pipeline can emit a policy;
+  // the over-permissiveness harness then tests this mutation as a FINDING.
+  const constrainedArgIndices = new Set<number>()
+  for (const comparison of facts.comparisons) {
+    if (comparison.left.kind === 'call_arg') constrainedArgIndices.add(comparison.left.index)
+  }
+  for (const membership of facts.memberships) {
+    if (membership.needle.kind === 'call_arg') constrainedArgIndices.add(membership.needle.index)
+  }
+  const hasConstrainedArg = constrainedArgIndices.size > 0
+  if (
+    (!dimensions || dimensions.includes('argument_reorder')) &&
+    hasConstrainedArg &&
+    permitCtx.args.length >= 2 &&
+    permitCtx.args[0]?.type === 'address' &&
+    permitCtx.args[1]?.type === 'address'
+  ) {
+    const ctx = cloneContext(permitCtx)
+    // Guard above guarantees args[0] and args[1] exist and are address-typed.
+    const a0 = ctx.args[0] as ScVal
+    const a1 = ctx.args[1] as ScVal
+    ctx.args[0] = a1
+    ctx.args[1] = a0
+    denies.push({ dimension: 'argument_reorder', ctx })
+  }
+
   // Version mismatch, malformed predicates, master authorization, and nonce replay are install-time checks and are intentionally omitted from model-evaluated cases.
   return { permit: cloneContext(permitCtx), denies }
 }

package/src/synth/index.ts

@@ -1,5 +1,9 @@
 // src/synth/index.ts - re-export the synthesizer front-ends.
 
+// Exported because `swapRecipientAllowlist` is part of the public synthesis
+// input: a caller assembling one needs the same validator the schema applies,
+// and re-deriving it elsewhere means a second address check that can drift.
+export { isStellarAddress } from './address.ts'
 export {
   type ComposeOptions,
   type ComposeResult,

package/src/synth/minimize.ts

@@ -4,7 +4,11 @@ import type { EvalContext } from './evaluate.ts'
 import { runHarness } from './harness.ts'
 
 /** Remove top-level conjuncts only when the current and regenerated batteries still deny. */
-export function minimize(predicate: PredicateNode, permitCtx: EvalContext): PredicateNode {
+export function minimize(
+  predicate: PredicateNode,
+  permitCtx: EvalContext,
+  dimensions?: string[]
+): PredicateNode {
   if (predicate.op !== 'and') return predicate
 
   let children = [...predicate.children]
@@ -12,10 +16,10 @@ export function minimize(predicate: PredicateNode, permitCtx: EvalContext): Pred
 
   while (index < children.length) {
     const current: PredicateNode = { op: 'and', children }
-    const currentCases = generateCases(current, permitCtx)
+    const currentCases = generateCases(current, permitCtx, dimensions)
     const candidateChildren = children.filter((_, childIndex) => childIndex !== index)
     const candidate: PredicateNode = { op: 'and', children: candidateChildren }
-    const candidateCases = generateCases(candidate, permitCtx)
+    const candidateCases = generateCases(candidate, permitCtx, dimensions)
     const verificationCases = {
       permit: candidateCases.permit,
       denies: mergeDenyCases(currentCases.denies, candidateCases.denies),