@crediolabs/policy-synth 0.1.10 → 0.1.12

package/src/registry/protocols.ts

@@ -19,7 +19,7 @@
 
 import type { ScVal } from '../types.ts'
 
-export type ProtocolId = 'sep41' | 'blend' | 'soroswap'
+export type ProtocolId = 'sep41' | 'blend' | 'soroswap' | 'oz_account'
 
 /** ScVal subset type vocabulary the ABI uses. Mirrors `ScVal['type']` minus
  *  `other` (which by definition cannot be matched against an ABI arg). */
@@ -165,10 +165,99 @@ export const SOROSWAP_ABI: ProtocolAbi = {
   },
 }
 
+/** OpenZeppelin smart-account ABI subset.
+ *
+ *  Why this lives in the recogniser: every user's smart account has a
+ *  different C-address, so a per-deployment pin would never cover them.
+ *  What is the same across every OpenZeppelin multisig account is the
+ *  small set of public context-rule entrypoints. A recording that
+ *  invokes `batch_add_signer(u32, vec<signer>)` on an arbitrary contract
+ *  is overwhelmingly likely to be calling the user's own OpenZeppelin
+ *  smart account (the canonical reason this product exists); we
+ *  recognise that pattern by interface, the same way SEP-41 is
+ *  recognised by interface.
+ *
+ *  SECURITY PROPERTY (load-bearing):
+ *   - Recognition claims the call TARGETS a particular protocol. We
+ *     only claim `oz_account` when the (fn, args) shape uniquely matches
+ *     one of the three entrypoints below AND the call looks like a real
+ *     context-rule operation. The match is exact: off-by-one arg count,
+ *     off-by-one arg type, or a method name close-but-wrong returns null
+ *     (fail-closed). A contract that incidentally happens to expose a
+ *     single matching fn is not sufficient - the recorder requires ALL
+ *     invocations to individually match, so a hostile contract with
+ *     exactly one matching fn would still contribute to the unknown
+ *     bucket for any other calls.
+ *   - We do NOT claim `oz_account` for unknown calls, for arg-shape
+ *     mismatches, or for calls where the recorder could not pin down
+ *     the (fn, args) shape. The freshness gate then runs at the same
+ *     1.0 threshold - lowering the gate for unknown protocols remains
+ *     a separate, opt-in production override (see RecordInput below).
+ *
+ *  ABI source: packages/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
+ *  pinned from the OpenZeppelin Reloaded `multisig_account_example`
+ *  contract (commit ef82b65, fetched 2026-07-28).
+ *
+ *  SCOPE NOTE: this ABI only covers the three entrypoints whose args
+ *  map cleanly onto the normalised `AbiArgType` vocabulary (u32, vec,
+ *  ...). `add_context_rule` - the install path - takes `(Symbol,
+ *  String, Option<u32>, Vec<SignerKey>, Map<Address, Val>)`. The
+ *  `String`, `Option<u32>` (`scvVoid`), and `Map<...>` arg types are
+ *  not in the AbiArgType set today (the recogniser's `argsMatchAbi`
+ *  helper rejects `other` deliberately so a close-but-wrong call does
+ *  not slip through). Excluding `add_context_rule` is the right
+ *  trade-off for now - it never blocks OZ smart-account recognition,
+ *  because the install tx always follows a recognised
+ *  `batch_add_signer` (the demo's first-pass tx), so the
+ *  contract still ends up in `knownContracts`. Updating the Arg type
+ *  vocabulary to cover these shapes is a separate concern (and would
+ *  also lift the SEP-41 / Blend recognition in the same change).
+ */
+export const OZ_ACCOUNT_ABI: ProtocolAbi = {
+  batch_add_signer: {
+    args: [
+      {
+        name: 'context_rule_id',
+        type: 'u32',
+        meaning: 'OZ context rule id this signer is added to',
+      },
+      {
+        name: 'signers',
+        type: 'vec',
+        meaning: 'vec<SignerKey> signers to add (Delegated G-address or Account C-address)',
+      },
+    ],
+  },
+  batch_remove_signer: {
+    args: [
+      {
+        name: 'context_rule_id',
+        type: 'u32',
+        meaning: 'OZ context rule id to remove signers from',
+      },
+      {
+        name: 'signers',
+        type: 'vec',
+        meaning: 'vec<SignerKey> signers to remove from the rule',
+      },
+    ],
+  },
+  remove_context_rule: {
+    args: [
+      {
+        name: 'context_rule_id',
+        type: 'u32',
+        meaning: 'OZ context rule id to delete',
+      },
+    ],
+  },
+}
+
 export const PROTOCOL_ABIS: Record<ProtocolId, ProtocolAbi> = {
   sep41: SEP41_ABI,
   blend: BLEND_ABI,
   soroswap: SOROSWAP_ABI,
+  oz_account: OZ_ACCOUNT_ABI,
 }
 
 export function getAbi(protocol: ProtocolId): ProtocolAbi {

package/src/review-card/builder.ts

@@ -16,7 +16,7 @@
 //
 //   2. The interpreter `PredicateNode`. One string per constraint leaf,
 //      rendered by enclosing-comparison kind. Templates (Task 7b):
-//        - invocation_count_in_window <= N    -> Invocations <= N per <window> seconds
+//        - invocation_count_in_window < N     -> At most N calls per <window> seconds
 //        - call_arg[i] in [list]              -> Recipient/arg must be one of [list]
 //        - eq(call_arg[i], literal_vec[...])  -> Path must be exactly [list]
 //        - oracle_price(asset) OP price       -> Only when oracle_price(asset) OP price
@@ -107,6 +107,23 @@ function renderOzPrimitive(ref: PolicyRef): string | null {
  *  `visit` on each. The walk is depth-first, left-to-right, so the
  *  constraint list is stable across runs. Pure boolean nodes contribute no
  *  constraint lines themselves; their leaf children do, via the visitor. */
+/** Every constraint sentence for one predicate, in walk order.
+ *
+ *  `buildReviewCardSummary` renders a policy the synthesiser just PRODUCED,
+ *  and needs the refs / context rule / simulation to do it. This renders a
+ *  predicate on its own, which is what a caller holding a policy already
+ *  INSTALLED on chain has: it can read the document out of the interpreter's
+ *  storage and decode it, but there is no proposal around it. Same renderers,
+ *  so an installed rule reads exactly as it did on the review card. */
+export function describePredicate(predicate: PredicateNode): string[] {
+  const constraints: string[] = []
+  walkPredicate(predicate, (node) => {
+    const line = renderConstraint(node)
+    if (line !== null) constraints.push(line)
+  })
+  return constraints
+}
+
 function walkPredicate(node: PredicateNode, visit: (node: PredicateNode) => void): void {
   switch (node.op) {
     case 'and':
@@ -197,9 +214,39 @@ function renderComparison(
     }
   }
 
-  // invocation_count_in_window <= N -> Invocations <= N per <window> seconds
+  // The bound is compared against the calls ALREADY made in the window, so
+  // `< N` permits N of them and `<= N` permits one more. Report how many
+  // calls the rule allows rather than restating the comparison.
   if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
-    return `Invocations <= ${right.value} per ${left.windowSecs} seconds`
+    const allowed = node.op === 'lt' ? right.value : right.value + 1
+    return `At most ${allowed} calls per ${left.windowSecs} seconds`
+  }
+
+  // OP(call_arg[i], <scalar literal>) -> arg[i] OP <value>
+  //
+  // The per-call cap. It has to be here because the `amount` template below
+  // is unreachable for an interpreter policy: `amount` is deliberately not in
+  // the contract's grammar (dsl.rs - the interpreter sees one authorized
+  // call, not the transaction's token movements), so a predicate using it is
+  // refused at install. A bound on the call's own amount ARGUMENT is how a
+  // cap is actually written, and it was rendering nothing at all - the card
+  // silently understated the policy.
+  //
+  // Placed after the literal_vec case above so an exact-sequence `eq` still
+  // reads as a path rather than as a comparison.
+  if (left.kind === 'call_arg') {
+    const head = `arg[${left.index}]`
+    const sep = node.op === 'eq' ? '=' : comparisonOpText(node.op)
+    if (right.kind === 'literal_i128') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_u64') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_u32') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_address') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_symbol') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_bytes') return `${head} ${sep} ${right.value}`
+    // call_arg_scaled is the slippage floor and reads as itself.
+    if (right.kind === 'call_arg_scaled') {
+      return `${head} >= arg[${right.index}] * ${right.num}/${right.den}`
+    }
   }
 
   // amount <= v -> Amount <= v
@@ -208,8 +255,8 @@ function renderComparison(
   }
 
   // oracle_price(asset) OP price -> Only when oracle_price(asset) OP price
-  if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
-    return `Only when oracle_price(${left.asset}) ${comparisonOpText(node.op)} ${right.value}`
+  if (left.kind === 'oracle_price' && right.kind === 'oracle_threshold') {
+    return `Only when oracle_price(${left.asset}) ${comparisonOpText(node.op)} ${right.value} (${right.decimals} dp)`
   }
 
   // Any other comparison shape is a structural fail-closed: do not surface
@@ -250,6 +297,7 @@ function renderVecElement(leaf: PredicateLeaf): string {
     case 'call_arg':
     case 'call_arg_len':
     case 'call_arg_field':
+    case 'call_arg_scaled':
     case 'amount':
     case 'window_spent':
     case 'now':
@@ -257,6 +305,11 @@ function renderVecElement(leaf: PredicateLeaf): string {
     case 'invocation_count_in_window':
     case 'oracle_price':
       return `<${leaf.kind}>`
+    // Show the declared basis, not just the digits. A threshold on the wrong
+    // basis is the one policy error the contract cannot detect, so the review
+    // card is where a human has to be able to see it.
+    case 'oracle_threshold':
+      return `${leaf.value} (${leaf.decimals} dp)`
   }
 }
 

package/src/review-card/cross-check.ts

@@ -118,16 +118,43 @@ function pushComparison(
       return
     }
   }
+  // Mirrors the builder's wording byte-for-byte: how many calls the rule
+  // permits, since the bound counts the calls already made.
   if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
-    out.push(`Invocations <= ${right.value} per ${left.windowSecs} seconds`)
+    const allowed = op === 'lt' ? right.value : right.value + 1
+    out.push(`At most ${allowed} calls per ${left.windowSecs} seconds`)
     return
   }
+  // Mirrors the builder's per-call cap line. Both sides must render the same
+  // string: cross-check compares the summary against the predicate, so a
+  // shape only ONE of them renders would read as a dropped constraint.
+  if (left.kind === 'call_arg') {
+    const head = `arg[${left.index}]`
+    const sep = op === 'eq' ? '=' : comparisonOpText(op)
+    if (
+      right.kind === 'literal_i128' ||
+      right.kind === 'literal_u64' ||
+      right.kind === 'literal_u32' ||
+      right.kind === 'literal_address' ||
+      right.kind === 'literal_symbol' ||
+      right.kind === 'literal_bytes'
+    ) {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'call_arg_scaled') {
+      out.push(`${head} >= arg[${right.index}] * ${right.num}/${right.den}`)
+      return
+    }
+  }
   if (left.kind === 'amount' && right.kind === 'literal_i128') {
     out.push(`Amount <= ${right.value}`)
     return
   }
-  if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
-    out.push(`Only when oracle_price(${left.asset}) ${comparisonOpText(op)} ${right.value}`)
+  if (left.kind === 'oracle_price' && right.kind === 'oracle_threshold') {
+    out.push(
+      `Only when oracle_price(${left.asset}) ${comparisonOpText(op)} ${right.value} (${right.decimals} dp)`
+    )
     return
   }
 }
@@ -159,6 +186,7 @@ function renderVecElement(leaf: PredicateLeaf): string {
     case 'call_arg':
     case 'call_arg_len':
     case 'call_arg_field':
+    case 'call_arg_scaled':
     case 'amount':
     case 'window_spent':
     case 'now':
@@ -166,6 +194,11 @@ function renderVecElement(leaf: PredicateLeaf): string {
     case 'invocation_count_in_window':
     case 'oracle_price':
       return `<${leaf.kind}>`
+    // Show the declared basis, not just the digits. A threshold on the wrong
+    // basis is the one policy error the contract cannot detect, so the review
+    // card is where a human has to be able to see it.
+    case 'oracle_threshold':
+      return `${leaf.value} (${leaf.decimals} dp)`
   }
 }
 

package/src/review-card/index.ts

@@ -2,6 +2,7 @@
 
 export {
   buildReviewCardSummary,
+  describePredicate,
   type ReviewCardSummary,
 } from './builder.ts'
 export {

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

@@ -60,6 +60,10 @@ export interface OraclePriceBound {
   asset: string
   operator: IRCompOp
   value: string
+  /** Decimal basis `value` is written on. REQUIRED: oracle prices normalise to
+   *  9 dp, and a threshold silently assumed to share that basis is what let a
+   *  raw 14-dp bound permit everything. The author states it; we convert. */
+  decimals: number
 }
 
 /** Caller-supplied answers to the ambiguity prompts. Every numeric bound the
@@ -80,6 +84,17 @@ export interface ComposeUserResponses {
    *  `oracle_price(asset) OP value` compare in the interpreter IR. Multiple
    *  entries on the same asset emit multiple leaves. */
   oraclePriceBound?: OraclePriceBound[]
+  /** Minimum acceptable swap output per unit of input, as `num/den` (e.g.
+   *  `{num:'95',den:'100'}` = accept losing at most 5%). Emitted as a
+   *  slippage floor bounding the output arg against the input arg of the same
+   *  call.
+   *
+   *  REQUIRED to be supplied by the caller: it is never derived from the
+   *  recording. The recorded in/out pair is a price at one moment, and
+   *  freezing it as policy would deny ordinary trades as soon as the rate
+   *  moves. Absent, no floor is emitted and the existing unbounded-output
+   *  warning stands. */
+  swapMinOutRatio?: { num: string; den: string }
   /** Recipient allowlist for a swap (call_arg[3] on SoroSwap's
    *  swap_exact_tokens_for_tokens). When supplied, it REPLACES the default
    *  pin. Absent -> the recipient is pinned to the recorded value (mirroring
@@ -184,10 +199,19 @@ export function composeFromRecording(
             value: limit,
           },
         }
-        if (!interpreterEnabled || token === scopeContract) {
-          ozConstraints.push(spendCond)
-        } else {
-          interpreterConstraints.push(spendCond)
+        // A rolling spend cap always goes to OZ, whose `spending_limit` is the
+        // audited implementation. The interpreter is NOT a fallback for the
+        // token != scopeContract case: on chain it sees one authorized call,
+        // not the transaction's token movements, so it has no per-call amount
+        // to accumulate and the counter would never move. OZ reports the case
+        // it cannot cover (it pins the limit to the context contract), which
+        // is the honest outcome - the old fallback produced an interpreter
+        // predicate that silently never bound.
+        ozConstraints.push(spendCond)
+        if (interpreterEnabled && token !== scopeContract) {
+          warnings.push(
+            `rolling spend cap on ${token} cannot be enforced on chain: OZ spending_limit pins the limit to the context contract, and the interpreter cannot observe token movements. Bound the per-call value with an argument cap plus an invocation-count limit instead.`
+          )
         }
       }
     }
@@ -213,7 +237,10 @@ export function composeFromRecording(
         op: 'compare',
         compare: {
           selector: { kind: 'invocation_count', windowSeconds },
-          operator: 'lte',
+          // `lt`, not `lte`: the leaf reports the calls ALREADY made in the
+          // window, so `< N` is what permits N of them. With `lte` a limit
+          // of N let an N+1th call through.
+          operator: 'lt',
           value: String(invocationLimit),
         },
       }
@@ -245,6 +272,7 @@ export function composeFromRecording(
           selector: { kind: 'oracle_price', asset: b.asset },
           operator: b.operator,
           value: b.value,
+          valueDecimals: b.decimals,
         },
       }
       if (interpreterEnabled) {
@@ -277,6 +305,7 @@ export function composeFromRecording(
       protocol,
       opts.userResponses?.swapRecipientAllowlist,
       swapInputAmountCap,
+      opts.userResponses?.swapMinOutRatio,
       interpreterEnabled
     )
   }
@@ -333,6 +362,7 @@ function appendProtocolSpecificConstraints(
   protocol: IdentifiedProtocol,
   swapRecipientAllowlist: string[] | undefined,
   swapInputAmountCap: string | undefined,
+  swapMinOutRatio: { num: string; den: string } | undefined,
   interpreterEnabled: boolean
 ): void {
   // SEP-41 transfer / mint: the `to` arg (index 1) is the recipient. Emit it as
@@ -405,7 +435,17 @@ function appendProtocolSpecificConstraints(
       })
       for (let i = 0; i < elements.length; i++) {
         const element = elements[i]
-        if (!element || element.type !== 'map') continue
+        // An element we cannot bind leaves that request's action, asset and
+        // amount free while the length pin makes the policy LOOK total. The
+        // length pin still stays (it is a real restriction, and dropping it
+        // would only widen the policy) - what must not happen is dropping the
+        // element quietly.
+        if (element?.type !== 'map') {
+          warnings.push(
+            `Blend submit requests element ${i} is not a Request map (recorded as ${element?.type ?? 'nothing'}): its request_type, address and amount are NOT pinned, so any action on any asset for any amount is permitted in that position`
+          )
+          continue
+        }
         const fields = element.value
         const fieldValue = (
           name: string,
@@ -421,7 +461,19 @@ function appendProtocolSpecificConstraints(
         const address = fieldValue('address', 'address')
         const amount = fieldValue('amount', 'i128')
         const requestType = fieldValue('request_type', 'u32')
-        if (address === null || amount === null || requestType === null) continue
+        if (address === null || amount === null || requestType === null) {
+          const missing = [
+            requestType === null ? 'request_type (u32)' : null,
+            address === null ? 'address' : null,
+            amount === null ? 'amount (i128)' : null,
+          ].filter((f): f is string => f !== null)
+          // Partial pins are deliberately NOT emitted (see the note above): a
+          // half-pinned request reads as a bound one on the review card.
+          warnings.push(
+            `Blend submit requests element ${i} could not be bound: ${missing.join(', ')} missing or of an unexpected type. That request's request_type, address and amount are NOT pinned, so any action on any asset for any amount is permitted in that position`
+          )
+          continue
+        }
         interpreterConstraints.push({
           op: 'compare',
           compare: {
@@ -528,6 +580,32 @@ function appendProtocolSpecificConstraints(
       }
     }
 
+    // Slippage floor: `out >= in * num/den`. Only when the caller supplied the
+    // ratio - see `swapMinOutRatio`. Without it the output arg stays free,
+    // which is the case the unbounded-swap warning above describes.
+    const outMinArgIndex = soroswapMinOutArgIndex(protocol.fn)
+    const minOutRatio = swapMinOutRatio
+    if (
+      minOutRatio !== undefined &&
+      inputArgIndex !== undefined &&
+      outMinArgIndex !== undefined &&
+      inputAmountArg &&
+      inputAmountArg.type === 'i128'
+    ) {
+      const floor: IRCondition = {
+        op: 'slippage_floor',
+        outArgIndex: outMinArgIndex,
+        inArgIndex: inputArgIndex,
+        num: minOutRatio.num,
+        den: minOutRatio.den,
+      }
+      if (interpreterEnabled) {
+        interpreterConstraints.push(floor)
+      } else {
+        ozConstraints.push(floor)
+      }
+    }
+
     // Swap recipient (call_arg[3]): when the caller supplies
     // swapRecipientAllowlist, emit it as an `in` constraint on the recipient
     // arg. When absent, PIN the recipient to the recorded value - mirroring the
@@ -571,6 +649,22 @@ function appendProtocolSpecificConstraints(
  *  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). */
+/** The argument carrying the swap's MINIMUM ACCEPTABLE OUTPUT.
+ *
+ *  Only the exact-input entrypoints have one: `swap_tokens_for_exact_tokens`
+ *  fixes the output and varies the input, so its output needs no floor (its
+ *  arg[1] is `amount_in_max`, already bounded by the input cap). Returning
+ *  undefined there keeps a floor from being pinned to the wrong argument. */
+function soroswapMinOutArgIndex(fn: string): number | undefined {
+  switch (fn) {
+    case 'swap_exact_tokens_for_tokens':
+    case 'swap_exact_in_for_tokens':
+      return 1
+    default:
+      return undefined
+  }
+}
+
 function soroswapInputAmountArgIndex(fn: string): number | undefined {
   switch (fn) {
     case 'swap_exact_tokens_for_tokens':

package/src/synth/deny-cases.ts

@@ -566,7 +566,9 @@ function cloneContext(ctx: EvalContext): EvalContext {
   return cloned
 }
 
-function cloneScVal(value: ScVal, depth = 0): ScVal {
+/** Deep-copy an ScVal so a mutation cannot alias the recorded call.
+ *  Exported so the permit-context builder shares this one implementation. */
+export function cloneScVal(value: ScVal, depth = 0): ScVal {
   // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
   // payload cannot RangeError the JS stack during deny-case mutation. Over-depth
   // throws a ToolError-shaped error that the `synthesizeFromRecording` envelope

package/src/synth/evaluate.ts

@@ -32,6 +32,12 @@
 import type { PredicateLeaf, PredicateNode, ScVal } from '../types.ts'
 import { literalNumericBigInt } from './predicate-literals.ts'
 
+/** Oracle prices normalise to this many decimals; mirrors NORMALISED_DECIMALS
+ *  in oracle.rs. A threshold on any other basis must say so. */
+const NORMALISED_DECIMALS = 9
+/** Mirrors MAX_ORACLE_THRESHOLD_DECIMALS in dsl.rs. */
+const MAX_ORACLE_THRESHOLD_DECIMALS = 18
+
 export interface EvalContext {
   /** Contract the interpreter is asked to enforce against. */
   contract: string
@@ -206,6 +212,13 @@ function evalCompare(
 
   // --- step 4b: call_arg comparison (eq / exact-vec, or an ordered numeric bound) ---
   if (left.kind === 'call_arg') {
+    // The swap's canonical form is `call_arg[out] >= call_arg_scaled(in, num, den)`.
+    // Dispatched here so the floor's dedicated reason codes (ARITHMETIC_OVERFLOW
+    // -> SLIPPAGE_FLOOR) reach the user; routing the scaled RHS through the
+    // generic `evalArgOrderedCompare` would mask overflow as ARG_MISMATCH.
+    if (right.kind === 'call_arg_scaled') {
+      return evalScaledArgCompare(op, left, right, ctx)
+    }
     const actual = ctx.args[left.index]
     // An ordered comparison (lt/lte/gt/gte) reads the arg as an integer and
     // compares it to a numeric literal via BigInt (e.g. a SoroSwap input-amount
@@ -216,6 +229,12 @@ function evalCompare(
     return evalArgEq(op, actual, right, ctx)
   }
 
+  // --- step 4b': scaled leaf on the LEFT (`call_arg_scaled(in, num, den) <= call_arg[out]`).
+  // Symmetric form so a policy that phrases the floor either way works.
+  if (left.kind === 'call_arg_scaled') {
+    return evalScaledArgCompare(op, right, left, ctx)
+  }
+
   // --- step 4c: call_arg_len: the length of a vec-typed argument as a u32.
   // Fails closed on a non-vec arg, an absent arg, or a non-u32 literal.
   if (left.kind === 'call_arg_len') {
@@ -337,6 +356,100 @@ function evalArgEq(
   return { permit: false, reason: 'ARG_MISMATCH' }
 }
 
+/** Step 4b': slippage-floor comparison. Mirrors the Rust `eval_scaled_arg_compare`
+ *  path: the scaled leaf is `args[index] * num / den` (truncating toward
+ *  zero). On `checked_mul` / `checked_div` failure (overflow or
+ *  divide-by-zero) the comparison denies with `ARITHMETIC_OVERFLOW`. A
+ *  failed comparison denies with `SLIPPAGE_FLOOR` (the dedicated reason)
+ *  rather than the generic `ARG_MISMATCH`.
+ *
+ *  `left` is whichever side of the compare is NOT the scaled leaf. A
+ *  scaled-on-scaled compare denies `ARG_MISMATCH` (pipelining two scaled
+ *  leaves has no definable semantics). The other operand must be a
+ *  numeric shape (`call_arg` carrying a number, or a numeric literal);
+ *  anything else is `ARG_MISMATCH`. */
+function evalScaledArgCompare(
+  op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte',
+  left: PredicateLeaf,
+  right: PredicateLeaf,
+  ctx: EvalContext
+): EvalResult {
+  // Identify which side is scaled, and pull the other side as a number.
+  let scaled: { index: number; num: string; den: string }
+  let other: PredicateLeaf
+  let scaledOnRight: boolean
+  if (left.kind === 'call_arg_scaled') {
+    scaled = left
+    other = right
+    scaledOnRight = false
+  } else if (right.kind === 'call_arg_scaled') {
+    scaled = right
+    other = left
+    scaledOnRight = true
+  } else {
+    // Neither side is scaled - this is a programming error in the
+    // dispatcher; the contract returns ARG_MISMATCH to fail closed.
+    return { permit: false, reason: 'ARG_MISMATCH' }
+  }
+  // Source `args[index]` -> BigInt. An out-of-bounds index or a
+  // non-numeric arg fails closed as ARG_MISMATCH (not SLIPPAGE_FLOOR) -
+  // a violated floor is the wrong code when the operand itself could
+  // not be read.
+  if (scaled.index >= ctx.args.length) {
+    return { permit: false, reason: 'ARG_MISMATCH' }
+  }
+  const input = argNumericBigInt(ctx.args[scaled.index])
+  if (input === null) return { permit: false, reason: 'ARG_MISMATCH' }
+  let num: bigint
+  let den: bigint
+  try {
+    num = BigInt(scaled.num)
+    den = BigInt(scaled.den)
+  } catch {
+    return { permit: false, reason: 'ARG_MISMATCH' }
+  }
+  // Install refuses `den == 0` and `num <= 0` / `den <= 0`. The runtime
+  // check is a defensive belt-and-braces - a future validator
+  // regression cannot panic the frame on a divide-by-zero.
+  if (den === 0n) return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
+  const product = input * num
+  // BigInt overflow is silent in JS (it does not throw on multiplication).
+  // We can detect over-range by dividing and checking the result against
+  // i128 bounds, but the more practical check is whether the result
+  // divides cleanly. We rely on BigInt's arbitrary precision and then
+  // surface ARITHMETIC_OVERFLOW if the result is outside i128.
+  let scaledValue: bigint
+  try {
+    // BigInt division truncates toward zero (matches Rust `i128::checked_div`).
+    scaledValue = product / den
+  } catch {
+    return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
+  }
+  // i128 range check: if the scaled value is outside i128, the contract
+  // would have wrapped on i128 arithmetic; surface the same deny.
+  const I128_MAX = (1n << 127n) - 1n
+  const I128_MIN = -(1n << 127n)
+  if (scaledValue > I128_MAX || scaledValue < I128_MIN) {
+    return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
+  }
+  // Resolving the operand when the scaled side is on the right: the
+  // operand is `left`; the scaled value is the RHS. The AST order is
+  // `left <op> scaled`, so the comparator applies to `other <op> scaled`.
+  // When the scaled side is on the left, the order is `scaled <op> other`,
+  // i.e. `scaled <op> other_val`.
+  let otherVal: bigint | null
+  if (other.kind === 'call_arg') {
+    otherVal = argNumericBigInt(ctx.args[other.index])
+  } else {
+    otherVal = literalNumericBigInt(other)
+  }
+  if (otherVal === null) return { permit: false, reason: 'ARG_MISMATCH' }
+  const pass = scaledOnRight
+    ? bigintCmp(op, otherVal.toString(), scaledValue.toString())
+    : bigintCmp(op, scaledValue.toString(), otherVal.toString())
+  return pass ? { permit: true } : { permit: false, reason: 'SLIPPAGE_FLOOR' }
+}
+
 /** Ordered numeric comparison (lt/lte/gt/gte) on a `call_arg`. The interpreter
  *  reads the arg as an integer (i128 / u64 / u32 on the recorder's ScVal
  *  surface) and compares it to a numeric literal via BigInt. A non-numeric arg
@@ -430,6 +543,7 @@ function resolveLeaf(leaf: PredicateLeaf, ctx: EvalContext): ScVal | undefined {
     case 'invocation_count_in_window':
     case 'now':
     case 'valid_until':
+    case 'call_arg_scaled':
       return undefined // selector leaves with no ScVal projection
     case 'literal_address':
       return { type: 'address', value: leaf.value }
@@ -507,9 +621,22 @@ function evalOracleCompare(
     if (!mapped) throw new OracleError('ORACLE_STALE')
     throw new OracleError(mapped)
   }
-  const literal = right.kind === 'literal_i128' ? right.value : null
-  if (literal === null) throw new OracleError('ORACLE_DECIMALS_MISMATCH')
-  return bigintCmp(op, entry.price, literal)
+  // Mirrors eval_oracle_compare in dsl.rs. The threshold MUST declare its
+  // decimal basis: prices are on the normalised 9-dp basis, and assuming a
+  // bare literal shares it is what let a raw 14-dp threshold permit
+  // everything. A bare literal is refused rather than assumed.
+  if (right.kind !== 'oracle_threshold') throw new OracleError('ORACLE_DECIMALS_MISMATCH')
+  if (right.decimals > MAX_ORACLE_THRESHOLD_DECIMALS) {
+    throw new OracleError('ORACLE_THRESHOLD_DECIMALS_OUT_OF_RANGE')
+  }
+  // Scale BOTH sides up to the wider basis rather than dividing the threshold
+  // down: dividing truncates, and a truncated bound moves the permit boundary.
+  const decimals = BigInt(right.decimals)
+  const normalised = BigInt(NORMALISED_DECIMALS)
+  const common = decimals > normalised ? decimals : normalised
+  const priceScaled = BigInt(entry.price) * 10n ** (common - normalised)
+  const literalScaled = BigInt(right.value) * 10n ** (common - decimals)
+  return bigintCmp(op, String(priceScaled), String(literalScaled))
     ? { permit: true }
     : { permit: false, reason: 'FN_MISMATCH' }
 }