@crediolabs/policy-synth 0.1.9 → 0.1.11

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

@@ -80,16 +80,57 @@ function pushComparison(
     out.push(`Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`)
     return
   }
+  if (left.kind === 'call_arg_len' && op === 'eq' && right.kind === 'literal_u32') {
+    out.push(`Length of arg[${left.index}] is ${right.value}`)
+    return
+  }
+  // call_arg_field: must mirror the builder's templates byte-for-byte so
+  // the cross-check can assert a faithful summary.
+  if (left.kind === 'call_arg_field') {
+    const head = `arg[${left.index}] element[${left.element}].${left.field}`
+    const sep = op === 'eq' ? '=' : comparisonOpText(op)
+    if (right.kind === 'literal_address') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_symbol') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_bytes') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_u64') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_i128') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_u32') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_vec') {
+      out.push(`${head} ${sep} [${right.elements.map(renderVecElement).join(', ')}]`)
+      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
   }
   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
   }
 }
@@ -121,6 +162,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':
@@ -128,6 +170,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/run/index.ts

@@ -21,6 +21,7 @@ import {
   type ErrorCode,
   type MandateSpec,
   type OzAdapterConfig,
+  type PredicateNode,
   type ProposedPolicy,
   placeholderOzConfig,
   type RecordedTransaction,
@@ -31,6 +32,7 @@ import {
   type ToolError,
   type ToolResponse,
 } from '../index.ts'
+import type { SimulationResult } from '../verify/envelope.ts'
 import {
   type RecordTransactionInput,
   RecordTransactionInputSchema,
@@ -112,7 +114,14 @@ export async function runRecordTransaction(
  *  `{ok:false, error}`, but a raw throw from the SDK (e.g. an unexpected
  *  XDR decode error in the adapter) would otherwise surface as
  *  "[object Object]" in the MCP transport. */
-export async function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>> {
+export async function runSynthesizePolicy(raw: unknown): Promise<
+  ToolResponse<ProposedPolicy> & {
+    explain?: {
+      predicateTree: PredicateNode | null
+      simulation: SimulationResult
+    }
+  }
+> {
   const parsed = SynthesizePolicyInputSchema.safeParse(raw)
   if (!parsed.success) {
     return {
@@ -128,7 +137,11 @@ export async function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<Pr
       // Zod's optional fields widen to `T | undefined`, which the core's
       // exact-optional MandateSpec rejects; the schema already validated the
       // shape, so assert it (same pattern as the recordedTx cast below).
-      return await synthesizeFromMandate(input.mandate as MandateSpec, ozConfig)
+      return await synthesizeFromMandate(
+        input.mandate as MandateSpec,
+        ozConfig,
+        input.explain === true ? { explain: true } : {}
+      )
     }
     // recording source
     const recorded: RecordedTransaction = input.recordedTx as RecordedTransaction
@@ -141,6 +154,7 @@ export async function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<Pr
           ? { confidenceOverride: input.confidenceOverride }
           : {}),
         ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
+        ...(input.explain === true ? { explain: true } : {}),
       } as SynthesizeFromRecordingOptions,
       ozConfig
     )

package/src/run/schemas.ts

@@ -197,6 +197,11 @@ export const SynthesizePolicyMandateInputSchema = z.object({
   source: z.literal('mandate'),
   mandate: MandateSpecSchema,
   ozConfig: OzAdapterConfigSchema.optional(),
+  // --explain opt-in. When true, the orchestrator attaches the
+  // in-memory predicate tree (null for the mandate path) + a minimal
+  // honest SimulationResult to the success envelope. Absent or false
+  // -> the success envelope is unchanged (byte-identical to today).
+  explain: z.boolean().optional(),
 })
 
 /** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
@@ -224,6 +229,15 @@ export const SynthesizePolicyRecordingInputSchema = z.object({
   confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
   interpreter: InterpreterOptionsSchema.optional(),
   ozConfig: OzAdapterConfigSchema.optional(),
+  // --explain opt-in. When true, the orchestrator attaches the
+  // in-memory PredicateNode + the corresponding SimulationResult
+  // (real one from the self-verify pipeline when the interpreter is
+  // engaged, minimal honest value otherwise) to the success envelope.
+  // Absent or false -> the success envelope is unchanged (byte-identical
+  // to today). The flag is ADDITIVE: the existing ProposedPolicy fields
+  // (encodedPredicate, predicateHash, etc.) are never altered by enabling
+  // explain.
+  explain: z.boolean().optional(),
 })
 
 export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [

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
@@ -184,10 +188,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 +226,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 +261,7 @@ export function composeFromRecording(
           selector: { kind: 'oracle_price', asset: b.asset },
           operator: b.operator,
           value: b.value,
+          valueDecimals: b.decimals,
         },
       }
       if (interpreterEnabled) {
@@ -405,7 +422,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 +448,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: {

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,13 @@
 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 +213,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 +230,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 +357,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 +544,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 +622,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' }
 }

package/src/synth/permit-context.ts

@@ -0,0 +1,137 @@
+// src/synth/permit-context.ts - build the EvalContext that represents the
+// recorded call being replayed.
+//
+// Extracted from the over-permissiveness harness so the same construction
+// feeds both the in-process battery and the on-chain replay
+// (scripts/verify-mutations-testnet.ts). Two callers building this
+// separately would be two chances to disagree about what "the recorded
+// call" means, which is the one thing both must share.
+
+import type { PredicateLeaf, PredicateNode, RecordedTransaction } from '../types.ts'
+import { cloneScVal } from './deny-cases.ts'
+import type { EvalContext } from './evaluate.ts'
+import { literalNumericBigInt } from './predicate-literals.ts'
+
+export interface PermitContextResponses {
+  windowSeconds: number
+  invocationLimit?: number
+  limitAmount?: string
+  validUntilLedger: number
+  oraclePriceBound?: Array<{ asset: string; operator: string; value: string; decimals: number }>
+}
+
+export function buildPermitContext(
+  tx: RecordedTransaction,
+  responses: PermitContextResponses,
+  predicate: PredicateNode
+): EvalContext {
+  const amountByToken: Record<string, string> = {}
+  const totals = new Map<string, bigint>()
+  for (const m of tx.tokenMovements) {
+    const current = totals.get(m.token) ?? 0n
+    totals.set(m.token, current + BigInt(m.amount))
+  }
+  for (const [token, total] of totals) {
+    amountByToken[token] = total.toString()
+  }
+
+  const topLevel = tx.invocations[0]
+  const scopeContract = topLevel?.contract ?? ''
+
+  const oraclePriceByAsset: EvalContext['oraclePriceByAsset'] = {}
+  visitOracleLeaves(predicate, (asset, op, bound) => {
+    let price: bigint
+    switch (op) {
+      case 'lt':
+        price = bound - 1n
+        break
+      case 'gt':
+        price = bound + 1n
+        break
+      default:
+        price = bound
+    }
+    if (price < 0n) price = 0n
+    oraclePriceByAsset[asset] = { price: price.toString(), timestampSeconds: tx.fetchedAt }
+  })
+
+  const ctx: EvalContext = {
+    contract: scopeContract,
+    fn: topLevel?.fn ?? '',
+    args: (topLevel?.args ?? []).map(cloneScVal),
+    atLedger: tx.ledgerSequence,
+    nowSeconds: tx.fetchedAt,
+    amountByToken,
+    windowSpentByToken: {},
+    invocationCountByWindow: {},
+    oraclePriceByAsset,
+  }
+  if (responses.validUntilLedger !== undefined) {
+    ctx.validUntilLedger = responses.validUntilLedger
+  }
+  return ctx
+}
+
+function visitOracleLeaves(
+  node: PredicateNode,
+  visit: (asset: string, op: string, bound: bigint) => void
+): void {
+  switch (node.op) {
+    case 'and':
+    case 'or':
+      for (const child of node.children) visitOracleLeaves(child, visit)
+      return
+    case 'not':
+      visitOracleLeaves(node.child, visit)
+      return
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte': {
+      const leftIsOracle = node.left.kind === 'oracle_price'
+      const rightIsOracle = node.right.kind === 'oracle_price'
+      let asset: string | undefined
+      let literal: bigint | undefined
+      if (leftIsOracle) {
+        asset = node.left.kind === 'oracle_price' ? node.left.asset : undefined
+        literal = oracleThresholdNormalised(node.right)
+      } else if (rightIsOracle) {
+        asset = node.right.kind === 'oracle_price' ? node.right.asset : undefined
+        literal = oracleThresholdNormalised(node.left)
+      }
+      if (asset !== undefined && literal !== undefined) {
+        visit(asset, node.op, literal)
+      }
+      return
+    }
+    case 'in':
+      return
+  }
+}
+
+/** Oracle prices normalise to 9 decimals; mirrors NORMALISED_DECIMALS in
+ *  oracle.rs. */
+const NORMALISED_DECIMALS = 9n
+
+/** A threshold restated on the normalised basis, so a derived permit price is
+ *  comparable to it. Thresholds carry their own basis, so the conversion has
+ *  to happen here - reading the digits raw would build a context off by a
+ *  factor of 10^(decimals-9). Returns undefined for any other leaf. */
+function oracleThresholdNormalised(leaf: PredicateLeaf): bigint | undefined {
+  if (leaf.kind !== 'oracle_threshold') return undefined
+  let value: bigint
+  try {
+    value = BigInt(leaf.value)
+  } catch {
+    return undefined
+  }
+  const decimals = BigInt(leaf.decimals)
+  if (decimals <= NORMALISED_DECIMALS) {
+    return value * 10n ** (NORMALISED_DECIMALS - decimals)
+  }
+  // Floor: a finer-grained threshold has no exact 9-dp representation. The
+  // caller only needs a price that lands on the right side of the bound, and
+  // it offsets by one from here.
+  return value / 10n ** (decimals - NORMALISED_DECIMALS)
+}

package/src/synth/synthesize-from-mandate.ts

@@ -13,14 +13,27 @@ import { createOzAdapter } from '../adapters/oz/adapter.ts'
 import type { ToolResponse } from '../errors.ts'
 import { mandateToPolicyIR } from '../mandate/to-ir.ts'
 import type { MandateSpec } from '../mandate/types.ts'
-import type { ProposedPolicy } from '../types.ts'
+import type { PredicateNode, ProposedPolicy } from '../types.ts'
+import type { SimulationResult } from '../verify/envelope.ts'
 
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: '
 
 export function synthesizeFromMandate(
   spec: MandateSpec,
-  ozConfig: OzAdapterConfig
-): ToolResponse<ProposedPolicy> {
+  ozConfig: OzAdapterConfig,
+  /** --explain opt-in. When true, the success envelope carries the
+   *  in-memory predicate tree (always null for the mandate path - the
+   *  declarative MandateSpec lowers to OZ built-ins, not to an
+   *  interpreter predicate) + a minimal honest SimulationResult. The
+   *  flag is ADDITIVE: the existing ProposedPolicy fields are never
+   *  altered. */
+  opts?: { explain?: true }
+): ToolResponse<ProposedPolicy> & {
+  explain?: {
+    predicateTree: PredicateNode | null
+    simulation: SimulationResult
+  }
+} {
   const ir = mandateToPolicyIR(spec)
   const adapter = createOzAdapter(ozConfig)
   const result = adapter.compile(ir)
@@ -42,5 +55,28 @@ export function synthesizeFromMandate(
     ...result.proposed,
     warnings: result.uncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
   }
-  return { ok: true, data: proposed }
+  // Same --explain envelope pattern as the recording path. The mandate path
+  // never produces an interpreter predicate, so predicateTree is null and
+  // the simulation is a minimal honest deny (no self-verify was performed).
+  const envelope: ToolResponse<ProposedPolicy> & {
+    explain?: {
+      predicateTree: PredicateNode | null
+      simulation: SimulationResult
+    }
+  } = { ok: true, data: proposed }
+  if (opts?.explain) {
+    envelope.explain = {
+      predicateTree: null,
+      simulation: {
+        permit: {
+          tx: 'deny',
+          reason: 'No self-verification was performed (mandate path is OZ-only)',
+        },
+        evaluatedCases: [],
+        backend: 'ts-model',
+        simulatorVersion: 'not-run',
+      },
+    }
+  }
+  return envelope
 }