@crediolabs/policy-synth 0.1.3 → 0.1.5

package/dist/run/schemas.js

@@ -0,0 +1,215 @@
+// packages/policy-synth/src/run/schemas.ts
+//
+// Zod schemas mirroring the policy-synth core domain types. These are the
+// public input / output shapes exposed over MCP and the CLI. They are kept
+// hand-written (rather than derived) because the MCP SDK needs a runtime
+// Zod object at the transport boundary; a drift test asserts they stay in
+// 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.
+//
+// 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
+// them here so it can build the same args envelope the MCP transport builds.
+import { z } from 'zod';
+/** 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;
+/** Upper bound on top-level invocations in a recorded transaction. A real
+ *  Stellar tx caps operations well below this; the bound stops a hand-crafted
+ *  payload from turning one request into an unbounded synthesis (DoS). */
+const MAX_INVOCATIONS = 512;
+export const NetworkSchema = z.enum(['mainnet', 'testnet']);
+/** ScVal subset - normalised subset the synth consumes. Mirrors
+ *  `ScVal` in packages/policy-synth/src/types.ts. */
+export const ScValSchema = z.lazy(() => z.union([
+    z.object({ type: z.literal('address'), value: z.string() }),
+    // i128 is SIGNED: real events carry negatives (e.g. a fee-adjustment/refund),
+    // so the recorder's own output must round-trip through this schema. u64/u32
+    // are unsigned and stay non-negative.
+    z.object({ type: z.literal('i128'), value: z.string().regex(/^-?[0-9]+$/) }),
+    z.object({ type: z.literal('u64'), value: z.string().regex(/^[0-9]+$/) }),
+    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) }),
+    z.object({ type: z.literal('bytes'), value: z.string() }),
+    z.object({ type: z.literal('other'), value: z.string() }),
+]));
+/** ContractInvocation mirrors the core. Annotated with an explicit
+ *  `z.ZodType<unknown>` (like ScValSchema above) so the self-referential
+ *  `subInvocations` field does not trip TS's circular type inference. */
+export const ContractInvocationSchema = z.object({
+    contract: z.string(),
+    fn: z.string(),
+    args: z.array(ScValSchema),
+    subInvocations: z.array(z.lazy(() => ContractInvocationSchema)),
+});
+export const TokenMovementSchema = z.object({
+    token: z.string(),
+    from: z.string(),
+    to: z.string(),
+    // The recorder reads the amount straight from the signed i128 event value
+    // (record/movements.ts readAmount), so a non-standard token that emits a
+    // negative transfer/mint/burn amount round-trips as a negative string. Mirror
+    // that here; the synth gate, not the wire schema, decides what to do with it.
+    amount: z.string().regex(/^-?[0-9]+$/),
+});
+export const OnChainEventSchema = z.object({
+    contract: z.string(),
+    topics: z.array(z.string()),
+    data: ScValSchema,
+});
+export const ParseConfidenceSchema = z.object({
+    overall: z.number().min(0).max(1),
+    knownContracts: z.array(z.string()),
+    unknownContracts: z.array(z.object({
+        contract: z.string(),
+        reason: z.enum(['no-abi', 'version-mismatch', 'opaque-result']),
+    })),
+    opaqueScVals: z.array(z.object({ path: z.string(), type: z.string() })),
+    thresholdUsed: z.number().min(0).max(1),
+});
+/** RecordedTransaction mirrors the core RecordedTransaction. The output shape
+ *  is referenced by name in the tool result structured content; we deliberately
+ *  type it loosely (`z.unknown()`) on the success path so the core remains the
+ *  single source of truth for the wire payload. */
+export const RecordedTransactionSchema = z
+    .object({
+    network: NetworkSchema,
+    signers: z.array(z.string()),
+    invocations: z.array(ContractInvocationSchema).max(MAX_INVOCATIONS),
+    tokenMovements: z.array(TokenMovementSchema),
+    events: z.array(OnChainEventSchema),
+    authEntries: z.array(z.unknown()),
+    ledgerSequence: z.number().int().nonnegative(),
+    fetchedAt: z.number().int().nonnegative(),
+    parseConfidence: ParseConfidenceSchema,
+    sourceAccount: z.string(),
+})
+    .passthrough();
+/** 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 const MandateSpecSchema = z
+    .object({
+    chain: z.literal('stellar'),
+    contract: z.string(),
+    method: z.string().optional(),
+    spendingLimit: z
+        .object({
+        token: z.string(),
+        limit: z.string().regex(/^[0-9]+$/),
+        windowSeconds: z.number().int().positive(),
+    })
+        .optional(),
+    // A threshold of 0 means "0 approvals", which is not a real M-of-N gate.
+    approvalThreshold: z.number().int().positive().optional(),
+    recipients: z.array(z.string()).optional(),
+    expiry: z
+        .object({
+        validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+        validUntilUnixSeconds: z.number().int().positive().optional(),
+    })
+        .optional(),
+})
+    .passthrough();
+/** ComposeUserResponses mirrors the core. */
+export const ComposeUserResponsesSchema = z
+    .object({
+    windowSeconds: z.number().int().positive().optional(),
+    validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+    limitAmount: z
+        .string()
+        .regex(/^[0-9]+$/)
+        .optional(),
+    invocationLimit: z.number().int().positive().optional(),
+})
+    .passthrough();
+/** OzAdapterConfig - the per-network OZ built-in instance addresses. */
+export const OzAdapterConfigSchema = z.object({
+    network: NetworkSchema,
+    instances: z.object({
+        spending_limit: z.string(),
+        simple_threshold: z.string(),
+        weighted_threshold: z.string(),
+    }),
+});
+// ===== record_transaction =====
+export const RecordTransactionInputSchema = z
+    .object({
+    hash: z.string().min(1).optional(),
+    xdr: z.string().min(1).optional(),
+    network: NetworkSchema,
+    confidenceOverride: z.number().min(0).max(1).optional(),
+})
+    .refine((v) => !(v.hash && v.xdr), {
+    message: 'provide exactly one of `hash` or `xdr`, not both',
+})
+    .refine((v) => Boolean(v.hash) || Boolean(v.xdr), {
+    message: 'one of `hash` or `xdr` is required',
+});
+// ===== synthesize_policy =====
+//
+// Discriminated union on `source` exposes BOTH front-ends through ONE tool.
+// - `source: 'mandate'` -> calls synthesizeFromMandate
+// - `source: 'recording'` -> calls synthesizeFromRecording
+export const SynthesizePolicyMandateInputSchema = z.object({
+    source: z.literal('mandate'),
+    mandate: MandateSpecSchema,
+    ozConfig: OzAdapterConfigSchema.optional(),
+});
+/** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
+ *  express (per-method scoping, invocation-count windows, oracle bounds, exact
+ *  hop paths) lower to a real interpreter predicate document instead of being
+ *  surfaced as warnings. The core deep-validates `smartAccountAddress` (a C...
+ *  contract, not the recording's G... source) and the tighten-only oracle
+ *  bounds; the schema stays light so the core owns the friendly ToolErrors. */
+export const InterpreterOptionsSchema = z.object({
+    smartAccountAddress: z.string(),
+    installNonce: z.number().int().positive().optional(),
+    oracleParams: z
+        .object({
+        maxStalenessSeconds: z.number().int().positive().optional(),
+        maxDeviationBps: z.number().int().positive().optional(),
+    })
+        .optional(),
+});
+export const SynthesizePolicyRecordingInputSchema = z.object({
+    source: z.literal('recording'),
+    recordedTx: RecordedTransactionSchema,
+    network: NetworkSchema,
+    userResponses: ComposeUserResponsesSchema.optional(),
+    confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
+    interpreter: InterpreterOptionsSchema.optional(),
+    ozConfig: OzAdapterConfigSchema.optional(),
+});
+export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [
+    SynthesizePolicyMandateInputSchema,
+    SynthesizePolicyRecordingInputSchema,
+]);
+// ===== Error envelope (canonical) =====
+//
+// Mirrors ToolError from packages/policy-synth/src/errors.ts. We use a
+// `z.string()` for `code` (not an enum) because the core's ErrorCode union
+// evolves over time; the transport contract only promises a string code the
+// caller can dispatch on. A drift test asserts the canonical codes still
+// pass through unchanged.
+export const ToolErrorSchema = z
+    .object({
+    code: z.string(),
+    message: z.string(),
+    severity: z.enum(['info', 'warning', 'error', 'fatal']),
+    retryable: z.boolean(),
+    remediation: z
+        .object({
+        toolCall: z.object({ name: z.string(), args: z.record(z.unknown()) }).optional(),
+        userQuestion: z.object({ code: z.string(), question: z.string() }).optional(),
+        docsUrl: z.string().optional(),
+    })
+        .optional(),
+    details: z.unknown().optional(),
+})
+    .passthrough();

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

@@ -1,6 +1,14 @@
-import type { PolicyIR } from '../ir/types.ts';
+import type { IRCompOp, PolicyIR } from '../ir/types.ts';
 import type { AmbiguityPrompt, ContractInvocation, Network } from '../types.ts';
 import type { IntentFacts } from './lower.ts';
+/** Per-asset oracle-price bound supplied by the caller (e.g. swap allowed only
+ *  if oracle_price(XLM) < 5.00 USDC). One entry per asset; the recorder never
+ *  fabricates a price bound from a slippage value (different units). */
+export interface OraclePriceBound {
+    asset: string;
+    operator: IRCompOp;
+    value: string;
+}
 /** Caller-supplied answers to the ambiguity prompts. Every numeric bound the
  *  synth might apply must come from here - the recording supplies observed
  *  amounts (offered only as suggestions), never authorised ceilings. */
@@ -15,22 +23,42 @@ export interface ComposeUserResponses {
     /** Max invocations per window for an incoming-only flow. Required to emit an
      *  invocation_count bound; absent -> FREQUENCY_BOUND_MISSING. */
     invocationLimit?: number;
+    /** Per-asset oracle-price bound(s). Each entry lowers to a single
+     *  `oracle_price(asset) OP value` compare in the interpreter IR. Multiple
+     *  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). */
+    swapRecipientAllowlist?: string[];
 }
 /** Composition options. */
 export interface ComposeOptions {
     network: Network;
     userResponses?: ComposeUserResponses;
+    /** When true, constraints the OZ adapter cannot lower are routed to
+     *  `interpreterIr` (the predicate-shape IR) so the orchestrator can compile
+     *  them via the interpreter adapter. When false (the default for callers
+     *  who have not opted in), every constraint goes to `ir` and the OZ
+     *  adapter's `uncovered` machinery generates the descriptive warnings -
+     *  today's behaviour. The orchestrator passes this flag through based on
+     *  whether `opts.interpreter` was supplied. */
+    interpreterEnabled?: boolean;
 }
-/** Result of composition: the PolicyIR, any ambiguities surfaced during
- *  inference, and descriptive warnings for needs that are NOT expressed
- *  as an IR node (so no fabricated constraint is emitted). The orchestrator
- *  carries ambiguities into `ProposedPolicy.ambiguities` and merges warnings
- *  into `ProposedPolicy.warnings`. */
+/** Result of composition: the OZ-shape PolicyIR, the predicate-shape PolicyIR
+ *  (contains the constraints the OZ adapter cannot lower; empty when
+ *  `interpreterEnabled` is false), any ambiguities surfaced during inference,
+ *  and descriptive warnings for needs that are NOT expressed as an IR node
+ *  (so no fabricated constraint is emitted). The orchestrator carries
+ *  ambiguities into `ProposedPolicy.ambiguities` and merges warnings into
+ *  `ProposedPolicy.warnings`. */
 export interface ComposeResult {
     ir: PolicyIR;
+    interpreterIr: PolicyIR;
     ambiguities: AmbiguityPrompt[];
     warnings: string[];
 }
-/** Compose a PolicyIR from the lowered facts + the resolved scope.
+/** Compose a PolicyIR pair from the lowered facts + the resolved scope.
  *  Pure (no randomness, no clock); same inputs -> byte-identical result. */
 export declare function composeFromRecording(facts: IntentFacts, scopeContract: string, topLevel: ContractInvocation | null, opts: ComposeOptions): ComposeResult;

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

@@ -1,6 +1,6 @@
-// src/synth/compose-from-recording.ts - facts + scope -> PolicyIR.
+// src/synth/compose-from-recording.ts - facts + scope -> PolicyIR (OZ-shape + interpreter-shape).
 //
-// Composes the canonical IR rule the OZ built-in-primitive backend can compile. Fail-closed
+// Composes the canonical IR rules the two backends compile FROM. Fail-closed
 // composition rules:
 //
 //   - identify the protocol of the top-level call (registry.identifyProtocol).
@@ -32,14 +32,30 @@
 //     price fabricated from a slippage bound, no synthetic exact-path compare.
 //     Those needs are surfaced as descriptive warnings instead.
 //
+// Split rule (P3 wiring): `ComposeResult` carries BOTH `ir` (OZ-shape) and
+// `interpreterIr` (predicate-shape). Each constraint is routed to EXACTLY ONE
+// adapter:
+//   - `compare window_spent(token, w) <= limit` where `token === scope.contract`
+//     and the protocol is known -> `ir` (OZ lowers to spending_limit).
+//   - everything else the compose step emits (recipient allowlists, per-method
+//     scoping via scope.method, invocation_count bounds, eq_seq swap paths,
+//     oracle_price bounds, AND window_spent where token != scope.contract, i.e.
+//     a SoroSwap input-token cap) -> `interpreterIr`.
+//
+// This prevents the interpreter adapter from emitting a duplicate
+// `window_spent` predicate leaf alongside an OZ `spending_limit` primitive
+// covering the same spend semantic - the two adapters never overlap.
+//
 // The default behavior is `deny_all` (OZ context rules are deny-by-default).
 import { identifyProtocol } from "../registry/identify.js";
-/** Compose a PolicyIR from the lowered facts + the resolved scope.
+/** Compose a PolicyIR pair from the lowered facts + the resolved scope.
  *  Pure (no randomness, no clock); same inputs -> byte-identical result. */
 export function composeFromRecording(facts, scopeContract, topLevel, opts) {
+    const interpreterEnabled = opts.interpreterEnabled === true;
     const ambiguities = [];
     const warnings = [];
-    const constraints = [];
+    const ozConstraints = [];
+    const interpreterConstraints = [];
     const protocol = topLevel
         ? identifyProtocol(topLevel.contract, topLevel.fn, topLevel.args, opts.network)
         : null;
@@ -50,6 +66,11 @@ export function composeFromRecording(facts, scopeContract, topLevel, opts) {
     // Outgoing spend -> one spending_limit per spent token. A single caller limit
     // binds only an unambiguous single-token spend; a multi-token flow needs a
     // per-token limit, so each unmatched token surfaces AMOUNT_BOUND_MISSING.
+    //
+    // Routing: a `window_spent(token, w) <= limit` constraint goes to the OZ IR
+    // only when token === scope.contract (OZ's spending_limit binds the
+    // CallContract target, not a token parameter). Otherwise it goes to the
+    // interpreter IR (the interpreter lowers window_spent to a predicate leaf).
     if (spendTokens.length > 0 && topLevel) {
         let durationFlagged = false;
         for (const token of spendTokens) {
@@ -75,33 +96,56 @@ export function composeFromRecording(facts, scopeContract, topLevel, opts) {
                 });
                 continue;
             }
-            if (windowSeconds !== undefined) {
-                constraints.push({
+            if (windowSeconds !== undefined && limit !== undefined) {
+                const spendCond = {
                     op: 'compare',
                     compare: {
                         selector: { kind: 'window_spent', token, windowSeconds },
                         operator: 'lte',
                         value: limit,
                     },
-                });
+                };
+                if (!interpreterEnabled || token === scopeContract) {
+                    ozConstraints.push(spendCond);
+                }
+                else {
+                    interpreterConstraints.push(spendCond);
+                }
             }
         }
     }
     // Incoming-only / frequency intent: an invocation_count bound is emitted ONLY
     // when the caller supplies the count AND a window - never a fabricated `<= 1`.
+    // Routed to the interpreter IR when interpreter is enabled (OZ cannot lower
+    // invocation_count); otherwise to the OZ IR (which flags it as uncovered).
+    //
+    // A recognised swap is NOT an incoming-only flow: it has an outgoing input leg
+    // whose spend simply was not attributed to the source account (the
+    // fee-sponsored / holder != source case). Its real restrictions - exact path,
+    // recipient, and the input-amount cap - come from the protocol-specific pass,
+    // so it does NOT get the incoming-only frequency prompt. A caller who wants to
+    // rate-limit the swap can still supply an invocationLimit + window, which
+    // lowers to an invocation_count for any flow.
     if (spendTokens.length === 0 && topLevel) {
         const invocationLimit = opts.userResponses?.invocationLimit;
+        const isRecognisedSwap = protocol?.protocol === 'soroswap';
         if (known && windowSeconds !== undefined && invocationLimit !== undefined) {
-            constraints.push({
+            const icCond = {
                 op: 'compare',
                 compare: {
                     selector: { kind: 'invocation_count', windowSeconds },
                     operator: 'lte',
                     value: String(invocationLimit),
                 },
-            });
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(icCond);
+            }
+            else {
+                ozConstraints.push(icCond);
+            }
         }
-        else {
+        else if (!isRecognisedSwap) {
             ambiguities.push({
                 code: 'FREQUENCY_BOUND_MISSING',
                 question: 'Incoming-only flow - what max invocations per window should the policy enforce?',
@@ -109,54 +153,201 @@ export function composeFromRecording(facts, scopeContract, topLevel, opts) {
             warnings.push('frequency bound needed for the incoming-only flow (needs the interpreter predicate); no invocation cap inferred');
         }
     }
+    // Per-asset oracle-price bound(s) supplied by the caller -> one
+    // oracle_price compare per entry. Routed to the interpreter IR when enabled;
+    // otherwise to the OZ IR (which flags it as uncovered).
+    const oracleBounds = opts.userResponses?.oraclePriceBound;
+    if (oracleBounds) {
+        for (const b of oracleBounds) {
+            const oracleCond = {
+                op: 'compare',
+                compare: {
+                    selector: { kind: 'oracle_price', asset: b.asset },
+                    operator: b.operator,
+                    value: b.value,
+                },
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(oracleCond);
+            }
+            else {
+                ozConstraints.push(oracleCond);
+            }
+        }
+    }
     // Observed recipient allowlist (SEP-41) is a real, recorded constraint the OZ
-    // adapter flags as not covered. Unknown protocols emit nothing here.
+    // adapter flags as not covered; the interpreter adapter lowers it to an `in`
+    // predicate. Unknown protocols emit nothing here. SoroSwap's swap recipient
+    // (arg[3]) is the source-of-truth for the swapRecipientAllowlist surface.
     if (topLevel && protocol !== null) {
-        appendProtocolSpecificConstraints(constraints, warnings, facts, topLevel, protocol);
+        // A SoroSwap input-amount cap binds the caller's limitAmount to call_arg[0]
+        // (the exact amount_in) ONLY when no cumulative outgoing spend was detected
+        // for the source account - i.e. the input token never moved FROM the source
+        // (fee-sponsored swaps, or a holder != source). When a spend WAS detected,
+        // the window_spent path above already consumed the limit, so the per-call
+        // arg cap is skipped to avoid binding one limit to two different semantics.
+        const swapInputAmountCap = spendTokens.length === 0 ? limitAmount : undefined;
+        appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, opts.userResponses?.swapRecipientAllowlist, swapInputAmountCap, interpreterEnabled);
     }
+    // `scope.method` is carried on BOTH IRs so each adapter produces a
+    // self-consistent rule. The interpreter adapter lowers scope.method into a
+    // `call_fn == <method>` predicate leaf (a real restriction); the OZ adapter
+    // flags it as uncovered (CallContract alone permits any method on the
+    // contract).
     const scope = { contract: scopeContract };
     if (topLevel?.fn)
         scope.method = topLevel.fn;
-    const rule = {
-        roles: [],
-        scope,
-        constraints,
+    const buildRule = (constraints) => {
+        const rule = {
+            roles: [],
+            scope: { ...scope },
+            constraints,
+        };
+        if (opts.userResponses?.validUntilLedger !== undefined) {
+            rule.expiry = { validUntilLedger: opts.userResponses.validUntilLedger };
+        }
+        return rule;
     };
-    if (opts.userResponses?.validUntilLedger !== undefined) {
-        rule.expiry = { validUntilLedger: opts.userResponses.validUntilLedger };
-    }
     const ir = {
         chain: 'stellar',
         defaultBehavior: 'deny_all',
-        rules: [rule],
+        rules: [buildRule(ozConstraints)],
     };
-    return { ir, ambiguities, warnings };
+    const interpreterIr = {
+        chain: 'stellar',
+        defaultBehavior: 'deny_all',
+        rules: [buildRule(interpreterConstraints)],
+    };
+    return { ir, interpreterIr, ambiguities, warnings };
 }
 /** Add the constraints justified by the recording that the OZ backend cannot
- *  express natively (the SEP-41 recipient the transfer moved to). The OZ adapter
- *  flags them as not covered. SoroSwap's slippage / oracle / exact-path needs are
- *  surfaced as descriptive warnings, NOT as fabricated comparison nodes. */
-function appendProtocolSpecificConstraints(constraints, warnings, facts, topLevel, protocol) {
+ *  express natively. Each constraint is routed to either `ozConstraints` (the
+ *  OZ adapter lowers it) or `interpreterConstraints` (the interpreter adapter
+ *  lowers it). When `interpreterEnabled` is false, every protocol-specific
+ *  constraint is routed to `ozConstraints` (which flags it as uncovered) so
+ *  callers who haven't opted in keep today's warning-driven behaviour.
+ *  SoroSwap's slippage / oracle / exact-path needs come from `userResponses`
+ *  (oraclePriceBound + limitAmount) + the recorded path (eq_seq on
+ *  call_arg[2]). */
+function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, swapRecipientAllowlist, swapInputAmountCap, interpreterEnabled) {
     // SEP-41 transfer / mint: the `to` arg (index 1) is the recipient. Emit it as
-    // a single-element allowlist; the OZ adapter flags it as not covered.
+    // a single-element allowlist; the interpreter adapter lowers it to `in`.
+    // When interpreter is not enabled, route to OZ so the caller sees today's
+    // `value allowlist on arg 1 (arg allowlist)` warning.
     if (protocol.protocol === 'sep41' && (protocol.fn === 'transfer' || protocol.fn === 'mint')) {
         const toArg = topLevel.args[1];
         if (toArg && toArg.type === 'address') {
-            constraints.push({
+            const cond = {
                 op: 'in',
                 selector: { kind: 'arg', argIndex: 1, scalarType: 'address' },
                 values: [toArg.value],
-            });
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(cond);
+            }
+            else {
+                ozConstraints.push(cond);
+            }
         }
     }
-    // SoroSwap: the swap's slippage / oracle-price bound and its exact hop path
-    // need the interpreter predicate. We do NOT fabricate a comparison node
-    // (oracle price and amountOutMin are different units; a vec path is not a
-    // scalar compare). Surface the observed path descriptively instead.
+    // SoroSwap: the recorded hop path -> eq_seq on the path arg (call_arg[2]).
+    // The interpreter adapter is the ONLY way to express an exact ordered
+    // sequence (OZ built-ins cannot). Element order is preserved verbatim.
+    // When multiple paths were recorded, the intersection is emitted as the
+    // canonical single path only if all observations agree; otherwise each is
+    // surfaced descriptively.
     if (protocol.protocol === 'soroswap') {
         const paths = facts.allowedPaths?.[topLevel.contract];
         const route = paths?.length === 1 ? paths[0] : undefined;
-        const pathText = route && route.length > 0 ? `; observed path: ${route.join(' -> ')}` : '';
-        warnings.push(`SoroSwap swap: slippage / oracle price bound and exact hop path need the interpreter predicate${pathText}`);
+        if (route && route.length > 0 && interpreterEnabled) {
+            const pathArgIndex = 2; // SoroSwap swap_exact_tokens_for_tokens: args = [amount_in, amount_out_min, path, to, deadline]
+            interpreterConstraints.push({
+                op: 'eq_seq',
+                selector: { kind: 'arg', argIndex: pathArgIndex, scalarType: 'address' },
+                values: route,
+            });
+        }
+        else {
+            const pathText = route && route.length > 0 ? `; observed path: ${route.join(' -> ')}` : '';
+            warnings.push(`SoroSwap swap: slippage / oracle price bound and exact hop path need the interpreter predicate${pathText}`);
+        }
+        // Input-amount cap: bind the caller's limitAmount to the swap's input-amount
+        // argument as `call_arg[i] <= limit`. The index is function-specific -
+        // SoroSwap has three swap entrypoints: `swap_exact_tokens_for_tokens` and
+        // `swap_exact_in_for_tokens` take the exact input as arg[0], while
+        // `swap_tokens_for_exact_tokens` takes the MAXIMUM input (`amount_in_max`)
+        // as arg[1] (its arg[0] is the exact OUTPUT, so binding arg[0] there would
+        // cap the wrong value and leave the input unbounded). This is a per-call cap
+        // that does NOT depend on attributing a token movement to the source account
+        // (the fee-sponsored / holder != source case, where the window_spent path
+        // detects no spend). Fail-closed: it only ever restricts the permitted input.
+        // Routed to the interpreter predicate (OZ built-ins cannot express a per-arg
+        // i128 bound); when the interpreter is not enabled it goes to OZ, which flags
+        // it uncovered (a warning). The `type === 'i128'` check is defense in depth -
+        // protocol identification's argsMatchAbi already pins the input arg to i128.
+        const inputArgIndex = soroswapInputAmountArgIndex(protocol.fn);
+        const inputAmountArg = inputArgIndex !== undefined ? topLevel.args[inputArgIndex] : undefined;
+        if (swapInputAmountCap !== undefined &&
+            inputArgIndex !== undefined &&
+            inputAmountArg &&
+            inputAmountArg.type === 'i128') {
+            const cond = {
+                op: 'compare',
+                compare: {
+                    selector: { kind: 'arg', argIndex: inputArgIndex, scalarType: 'i128' },
+                    operator: 'lte',
+                    value: swapInputAmountCap,
+                },
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(cond);
+            }
+            else {
+                ozConstraints.push(cond);
+            }
+        }
+        // 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).
+        const recipientArg = topLevel.args[3];
+        if (swapRecipientAllowlist && swapRecipientAllowlist.length > 0) {
+            const cond = {
+                op: 'in',
+                selector: { kind: 'arg', argIndex: 3, scalarType: 'address' },
+                values: [...swapRecipientAllowlist],
+            };
+            if (interpreterEnabled) {
+                interpreterConstraints.push(cond);
+            }
+            else {
+                ozConstraints.push(cond);
+            }
+        }
+        else if (interpreterEnabled && recipientArg && recipientArg.type === 'address') {
+            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)`,
+            });
+        }
+    }
+}
+/** Positional index of the input-amount argument for a recognized SoroSwap swap
+ *  function. `swap_exact_tokens_for_tokens` and `swap_exact_in_for_tokens` take
+ *  the exact input as arg[0]; `swap_tokens_for_exact_tokens` takes the maximum
+ *  input (`amount_in_max`) as arg[1] - its arg[0] is the exact OUTPUT. Any other
+ *  function has no positional input-amount argument -> undefined (no cap bound). */
+function soroswapInputAmountArgIndex(fn) {
+    switch (fn) {
+        case 'swap_exact_tokens_for_tokens':
+        case 'swap_exact_in_for_tokens':
+            return 0;
+        case 'swap_tokens_for_exact_tokens':
+            return 1;
+        default:
+            return undefined;
     }
 }

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

@@ -0,0 +1,12 @@
+import type { PredicateNode } from '../types.ts';
+import type { EvalContext } from './evaluate.ts';
+export interface DenyCase {
+    dimension: string;
+    ctx: EvalContext;
+}
+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;