@crediolabs/policy-synth 0.1.3 → 0.1.4

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;