@crediolabs/policy-synth 0.1.3 → 0.1.4

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

@@ -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,13 +32,36 @@
 //     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 type { IRCondition, IRPolicyRule, PolicyIR } from '../ir/types.ts'
+import type { IRCompOp, IRCondition, IRPolicyRule, PolicyIR } from '../ir/types.ts'
 import { type IdentifiedProtocol, identifyProtocol } from '../registry/identify.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. */
@@ -53,26 +76,46 @@ 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 function composeFromRecording(
   facts: IntentFacts,
@@ -80,9 +123,11 @@ export function composeFromRecording(
   topLevel: ContractInvocation | null,
   opts: ComposeOptions
 ): ComposeResult {
+  const interpreterEnabled = opts.interpreterEnabled === true
   const ambiguities: AmbiguityPrompt[] = []
   const warnings: string[] = []
-  const constraints: IRCondition[] = []
+  const ozConstraints: IRCondition[] = []
+  const interpreterConstraints: IRCondition[] = []
 
   const protocol = topLevel
     ? identifyProtocol(topLevel.contract, topLevel.fn, topLevel.args, opts.network)
@@ -96,6 +141,11 @@ export function composeFromRecording(
   // 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) {
@@ -124,33 +174,54 @@ export function composeFromRecording(
         })
         continue
       }
-      if (windowSeconds !== undefined) {
-        constraints.push({
+      if (windowSeconds !== undefined && limit !== undefined) {
+        const spendCond: IRCondition = {
           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: IRCondition = {
         op: 'compare',
         compare: {
           selector: { kind: 'invocation_count', windowSeconds },
           operator: 'lte',
           value: String(invocationLimit),
         },
-      })
-    } else {
+      }
+      if (interpreterEnabled) {
+        interpreterConstraints.push(icCond)
+      } else {
+        ozConstraints.push(icCond)
+      }
+    } else if (!isRecognisedSwap) {
       ambiguities.push({
         code: 'FREQUENCY_BOUND_MISSING',
         question: 'Incoming-only flow - what max invocations per window should the policy enforce?',
@@ -161,66 +232,229 @@ export function composeFromRecording(
     }
   }
 
+  // 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: IRCondition = {
+        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: IRPolicyRule['scope'] = { contract: scopeContract }
   if (topLevel?.fn) scope.method = topLevel.fn
 
-  const rule: IRPolicyRule = {
-    roles: [],
-    scope,
-    constraints,
-  }
-  if (opts.userResponses?.validUntilLedger !== undefined) {
-    rule.expiry = { validUntilLedger: opts.userResponses.validUntilLedger }
+  const buildRule = (constraints: IRCondition[]): IRPolicyRule => {
+    const rule: IRPolicyRule = {
+      roles: [],
+      scope: { ...scope },
+      constraints,
+    }
+    if (opts.userResponses?.validUntilLedger !== undefined) {
+      rule.expiry = { validUntilLedger: opts.userResponses.validUntilLedger }
+    }
+    return rule
   }
 
   const ir: PolicyIR = {
     chain: 'stellar',
     defaultBehavior: 'deny_all',
-    rules: [rule],
+    rules: [buildRule(ozConstraints)],
+  }
+  const interpreterIr: PolicyIR = {
+    chain: 'stellar',
+    defaultBehavior: 'deny_all',
+    rules: [buildRule(interpreterConstraints)],
   }
-  return { ir, ambiguities, warnings }
+  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. */
+ *  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(
-  constraints: IRCondition[],
+  ozConstraints: IRCondition[],
+  interpreterConstraints: IRCondition[],
   warnings: string[],
+  ambiguities: AmbiguityPrompt[],
   facts: IntentFacts,
   topLevel: ContractInvocation,
-  protocol: IdentifiedProtocol
+  protocol: IdentifiedProtocol,
+  swapRecipientAllowlist: string[] | undefined,
+  swapInputAmountCap: string | undefined,
+  interpreterEnabled: boolean
 ): void {
   // 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: IRCondition = {
         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: IRCondition = {
+        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: IRCondition = {
+        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: string): number | undefined {
+  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
   }
 }