@crediolabs/policy-synth 0.1.2 → 0.1.4

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

@@ -1,27 +1,52 @@
 // src/synth/synthesize-from-recording.ts - recording-path orchestrator.
 //
 // `synthesizeFromRecording` is the second Synthesizer front-end: it INFERS a
-// bounded policy from a `RecordedTransaction` via the same `PolicyIR` +
-// `createOzAdapter` pair used by the deterministic Mandate path. The flow:
+// bounded policy from a `RecordedTransaction` via the same `PolicyIR` + adapter
+// pair used by the deterministic Mandate path. The flow:
 //
 //   1. parseConfidence gate - refuse when `overall < threshold` (default 1.0;
 //      the caller may relax via `confidenceOverride.threshold`).
 //   2. `lower(tx)` -> IntentFacts.
 //   3. `decideScope(facts)` -> scope | SCOPE_UNRESOLVED ToolError.
-//   4. `composeFromRecording(facts, scope, opts)` -> PolicyIR + ambiguities.
+//   4. `composeFromRecording(facts, scope, opts)` -> { ir (OZ-shape),
+//      interpreterIr (predicate-shape), ambiguities, warnings }.
 //   5. `ozAdapter.compile(ir)` -> CompileResult.
-//   6. Assemble ProposedPolicy carrying parseConfidence (from tx), warnings
-//      (the OZ `uncovered` Path-B markers, prefixed), and ambiguities
-//      (DURATION_UNSPECIFIED etc.).
+//   6. If `interpreterIr.rules[0].constraints.length > 0` AND the caller
+//      opted in to the interpreter adapter:
+//        a. Run `interpreterAdapter.compile(interpreterIr)`.
+//        b. Throw -> SYNTHESIS_ERROR carrying the gate code
+//           (SCOPE_SELF_CALL, ORACLE_LEAF_INVALID_POSITION,
+//           ORACLE_PARAMS_OUT_OF_RANGE). Never install an OZ-only partial
+//           policy - a warning can be ignored and yields an over-broad rule.
+//        c. `covered === false` -> SYNTHESIS_ERROR carrying the uncovered
+//           descriptor (the user asked for the interpreter to enforce these
+//           constraints; refusing them silently is the audit failure mode).
+//        d. `covered === true` -> merge its PolicyDocument + PolicyRef into
+//           the OZ-shaped ProposedPolicy; the merged `contextRule.policies`
+//           is `[interpreterRef?, ...oz_builtinRefs]` and must satisfy
+//           `OZ_LIMITS.maxPoliciesPerRule` (= 5).
+//   7. Assemble ProposedPolicy carrying parseConfidence (from tx), warnings
+//      (the OZ `uncovered` markers, prefixed), and ambiguities.
 //
 // Determinism: same (tx, opts, ozConfig) -> byte-identical ProposedPolicy.
 // No randomness, no clock, no globals.
 
+import type { InterpreterAdapterConfig } from '../adapters/interpreter/adapter.ts'
+import {
+  createInterpreterAdapter,
+  lowerRuleToPredicate,
+  PLACEHOLDER_INTERPRETER_ADDRESS,
+} from '../adapters/interpreter/adapter.ts'
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts'
 import { createOzAdapter } from '../adapters/oz/adapter.ts'
 import type { ToolError, ToolResponse } from '../errors.ts'
+import { encodePredicate } from '../predicate/encode.ts'
 import {
+  type ContractInvocation,
   type Network,
+  OZ_LIMITS,
+  type PredicateLeaf,
+  type PredicateNode,
   type ProposedPolicy,
   type RecordedTransaction,
   SOROBAN_LIMITS,
@@ -31,19 +56,50 @@ import {
   type ComposeUserResponses,
   composeFromRecording,
 } from './compose-from-recording.ts'
+import { generateCases } from './deny-cases.ts'
+import { type EvalContext, evaluate } from './evaluate.ts'
+import { runHarness } from './harness.ts'
 import { lower } from './lower.ts'
+import { minimize } from './minimize.ts'
 import { decideScope, type ScopeDecision } from './scope.ts'
 
-const PATH_B_PREFIX = 'Path B (not covered by OZ built-in primitives): '
+const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: '
+
+/** Per-policy interpreter adapter config the caller opts into. Absent ->
+ *  recording path runs in week-1 mode (OZ adapter only, warnings for the
+ *  constraints OZ cannot express). */
+export interface InterpreterAdapterOptions {
+  /** The smart account this interpreter policy will be installed against.
+   *  Must be a C... contract address - the on-chain policy-bound account.
+   *  The G... source account from the recording is a separate concept. */
+  smartAccountAddress: string
+  /** Per-rule install nonce (first install = 1). Defaults to 1. */
+  installNonce?: number
+  /** Per-policy oracle overrides. Tighten-only vs the wasm defaults
+   *  (maxStalenessSeconds <= 600, maxDeviationBps <= 200); widening is
+   *  rejected at the options boundary. */
+  oracleParams?: { maxStalenessSeconds?: number; maxDeviationBps?: number }
+  /** @internal Test-only seam. When set, the orchestrator uses this
+   *  PredicateNode as the starting point for self-verify + minimise instead
+   *  of calling the interpreter adapter's compile(). Production callers MUST
+   *  NOT set this; the field exists so the self-verify pipeline can be
+   *  exercised on hand-crafted predicates (redundant conjuncts for
+   *  minimise, deliberately over-broad leaves for DENY_CASE_FAILURE). The
+   *  `smartAccountAddress` + `installNonce` + `oracleParams` are still
+   *  carried through so the emitted PolicyRef + PolicyDocument match the
+   *  recorded call shape. */
+  __testPredicateNode?: PredicateNode
+}
 
 /** Top-level orchestrator inputs. `userResponses` carries the LLM-collected
  *  answers to the ambiguity prompts (windowSeconds, validUntilLedger,
- *  limitAmount, invocationLimit). `confidenceOverride` relaxes the recorder's
- *  gate. */
+ *  limitAmount, invocationLimit, oraclePriceBound, swapRecipientAllowlist).
+ *  `interpreter` opts the recording path into the interpreter adapter. */
 export interface SynthesizeFromRecordingOptions {
   network: Network
   userResponses?: ComposeUserResponses
   confidenceOverride?: { threshold: number }
+  interpreter?: InterpreterAdapterOptions
 }
 
 /** Synthesize a ProposedPolicy from a recorded transaction. */
@@ -98,7 +154,7 @@ export function synthesizeFromRecording(
   if (!scopeRes.ok) return scopeRes
   const scope: ScopeDecision = scopeRes.data
   if (scope.kind !== 'call_contract') {
-    // A default scope on the recording-path is not currently a Path-A flow;
+    // A default scope on the recording-path is not currently a covered flow;
     // surface SYNTHESIS_ERROR so the orchestrator never silently emits an
     // over-broad default-scoped policy.
     return {
@@ -116,13 +172,14 @@ export function synthesizeFromRecording(
   const topLevel = tx.invocations[0] ?? null
   const composeOpts: ComposeOptions = {
     network: opts.network,
+    interpreterEnabled: opts.interpreter !== undefined,
     ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
   }
   const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts)
 
-  // 5. OZ compile.
-  const adapter = createOzAdapter(ozConfig)
-  const compileRes = adapter.compile(composed.ir)
+  // 5. OZ compile (always runs).
+  const ozAdapter = createOzAdapter(ozConfig)
+  const compileRes = ozAdapter.compile(composed.ir)
 
   if (!compileRes.proposed) {
     return {
@@ -137,22 +194,331 @@ export function synthesizeFromRecording(
     }
   }
 
-  // 6. assemble ProposedPolicy.
+  // 6. Interpreter compile (opt-in; fail-closed when the user routed real
+  //    restrictions to the interpreter).
+  //
+  //    When the caller opts in, the interpreter always runs - even for a
+  //    scope-only interpreter IR (no routed constraints) - because the
+  //    interpreter adapter lowers `scope.contract` + `scope.method` into a
+  //    `call_contract == ...` and `call_fn == ...` predicate sibling pair.
+  //    This is the real per-method enforcement the OZ adapter cannot do.
+  //
+  //    When the caller does NOT opt in: today's behaviour is preserved. The
+  //    compose step routes every constraint to the OZ IR; OZ flags the ones
+  //    it cannot lower as `uncovered` and the orchestrator surfaces them as
+  //    warnings. No interpreter doc is produced.
+  const interpreterOpts = opts.interpreter
+
+  let interpreterPolicyDocument: ProposedPolicy['policyDocuments'][number] | null = null
+  let interpreterPolicyRef: ProposedPolicy['policyRefs'][number] | null = null
+
+  if (interpreterOpts) {
+    const interpreterConfig: InterpreterAdapterConfig = {
+      network: opts.network,
+      installNonce: interpreterOpts.installNonce ?? 1,
+      smartAccountAddress: interpreterOpts.smartAccountAddress,
+      ...(interpreterOpts.oracleParams ? { oracleParams: interpreterOpts.oracleParams } : {}),
+    }
+
+    // The starting PredicateNode the self-verify + minimise pipeline drives.
+    // Two paths populate it:
+    //   - Test seam (`__testPredicateNode` set): use it directly, skipping the
+    //     adapter's compile(). Production code MUST NOT set the seam; it
+    //     exists so the pipeline can be exercised on hand-crafted predicates
+    //     (redundant conjuncts for minimise, deliberately over-broad leaves
+    //     for DENY_CASE_FAILURE).
+    //   - Normal: call the interpreter adapter's compile() so the existing
+    //     enforcement gates (SCOPE_SELF_CALL / ORACLE_LEAF_INVALID_POSITION /
+    //     ORACLE_PARAMS_OUT_OF_RANGE + uncovered reporting) fire first, then
+    //     re-derive the pre-encoding PredicateNode via `lowerRuleToPredicate`
+    //     so minimise + harness see the same shape the encoder will see.
+    let startingPredicate: PredicateNode | null = null
+    const testSeam = interpreterOpts.__testPredicateNode
+    if (testSeam !== undefined) {
+      startingPredicate = testSeam
+    } else {
+      const interpreterAdapter = createInterpreterAdapter(interpreterConfig)
+
+      let interpreterRes: Awaited<ReturnType<typeof interpreterAdapter.compile>>
+      try {
+        interpreterRes = interpreterAdapter.compile(composed.interpreterIr)
+      } catch (e) {
+        // Interpreter enforcement-gate throws (SCOPE_SELF_CALL,
+        // ORACLE_LEAF_INVALID_POSITION, ORACLE_PARAMS_OUT_OF_RANGE). Surface
+        // the gate code so the caller can act; never install an OZ-only
+        // partial policy - the user explicitly asked for these constraints
+        // to be enforced and silently dropping them yields an over-broad rule.
+        const code = (e as { code?: ToolError['code'] }).code
+        const allowedCodes: ToolError['code'][] = [
+          'SCOPE_SELF_CALL',
+          'ORACLE_LEAF_INVALID_POSITION',
+          'ORACLE_PARAMS_OUT_OF_RANGE',
+          'MALFORMED_PREDICATE',
+          'PREDICATE_TOO_LARGE',
+          'PREDICATE_TOO_DEEP',
+          'TOO_MANY_LEAVES',
+          'IN_OPERAND_LIMIT',
+          'PREDICATE_ORACLE_OVER_LIMIT',
+        ]
+        const surfacedCode = code && allowedCodes.includes(code) ? code : 'SYNTHESIS_ERROR'
+        return {
+          ok: false,
+          error: {
+            code: surfacedCode,
+            message: `interpreter predicate could not be compiled: ${(e as Error).message}`,
+            severity: 'error',
+            retryable: false,
+          },
+        }
+      }
+
+      if (!interpreterRes.covered) {
+        return {
+          ok: false,
+          error: {
+            code: 'SYNTHESIS_ERROR',
+            message: `interpreter predicate is not fully covered: ${interpreterRes.uncovered.join('; ')}`,
+            severity: 'error',
+            retryable: false,
+            details: { uncovered: interpreterRes.uncovered },
+          },
+        }
+      }
+
+      if (!interpreterRes.proposed) {
+        return {
+          ok: false,
+          error: {
+            code: 'SYNTHESIS_ERROR',
+            message: 'interpreter adapter returned no installable policy',
+            severity: 'error',
+            retryable: false,
+          },
+        }
+      }
+
+      interpreterPolicyDocument = interpreterRes.proposed.policyDocuments[0] ?? null
+      interpreterPolicyRef = interpreterRes.proposed.policyRefs[0] ?? null
+      if (!interpreterPolicyDocument || !interpreterPolicyRef) {
+        return {
+          ok: false,
+          error: {
+            code: 'SYNTHESIS_ERROR',
+            message: 'interpreter adapter returned a policy missing the document or ref',
+            severity: 'error',
+            retryable: false,
+          },
+        }
+      }
+
+      const firstInterpreterRule = composed.interpreterIr.rules[0]
+      if (!firstInterpreterRule) {
+        return {
+          ok: false,
+          error: {
+            code: 'SYNTHESIS_ERROR',
+            message: 'interpreter IR has no rules to lower',
+            severity: 'error',
+            retryable: false,
+          },
+        }
+      }
+      startingPredicate = lowerRuleToPredicate(firstInterpreterRule, interpreterConfig)
+    }
+
+    if (!startingPredicate) {
+      return {
+        ok: false,
+        error: {
+          code: 'SYNTHESIS_ERROR',
+          message: 'interpreter predicate was not derived',
+          severity: 'error',
+          retryable: false,
+        },
+      }
+    }
+
+    // 6b. Self-verify + minimise. We always build the same permit EvalContext
+    //     from the recorded tx + synthesised constraints so the harness
+    //     reasons about the intended call (the only one the user actually
+    //     recorded). The recorded call MUST permit under the predicate; the
+    //     generated deny battery MUST all deny.
+    if (!topLevel) {
+      // The orchestrator guarantees this for the call_contract branch above;
+      // a default-scoped policy never reaches the interpreter block. Fail
+      // closed rather than attempt to self-verify a vague shape.
+      return {
+        ok: false,
+        error: {
+          code: 'SYNTHESIS_ERROR',
+          message: 'self-verify requires a recorded top-level invocation',
+          severity: 'error',
+          retryable: false,
+        },
+      }
+    }
+    if (scope.kind !== 'call_contract') {
+      return {
+        ok: false,
+        error: {
+          code: 'SYNTHESIS_ERROR',
+          message: 'self-verify requires a call_contract scope',
+          severity: 'error',
+          retryable: false,
+        },
+      }
+    }
+    const permitCtx = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate)
+
+    // Top-level `and` predicates are what generateCases + minimize assume;
+    // for any other shape we skip minimise (encode as-is) but still assert
+    // the permit case permits. An over-broad non-and predicate is still
+    // caught by the harness on the next step.
+    const finalPredicate: PredicateNode =
+      startingPredicate.op === 'and' ? minimize(startingPredicate, permitCtx) : startingPredicate
+
+    const harnessCases = generateCases(finalPredicate, permitCtx)
+    const harnessResult = runHarness(finalPredicate, harnessCases)
+    if (!harnessResult.ok) {
+      return {
+        ok: false,
+        error: {
+          code: 'DENY_CASE_FAILURE',
+          message: `self-verify harness failed for the interpreter predicate (${harnessResult.failures.length} failure(s))`,
+          severity: 'error',
+          retryable: false,
+          details: { failures: harnessResult.failures },
+        },
+      }
+    }
+
+    const evalResult = evaluate(finalPredicate, permitCtx)
+    if (!evalResult.permit) {
+      return {
+        ok: false,
+        error: {
+          code: 'DENY_CASE_FAILURE',
+          message: `intended recorded call was denied by the interpreter predicate: ${evalResult.reason}`,
+          severity: 'error',
+          retryable: false,
+          details: { reason: evalResult.reason },
+        },
+      }
+    }
+
+    // 6c. Re-encode the (possibly minimised) PredicateNode and stamp the
+    //     canonical bytes back onto the PolicyDocument + PolicyRef. minimize
+    //     and encodePredicate are pure and deterministic, so the re-encoded
+    //     doc is byte-identical to what compile() would have produced for
+    //     the minimised tree.
+    const { encodedPredicate, predicateHash } = encodePredicate(finalPredicate)
+
+    if (testSeam !== undefined) {
+      // Test seam: build the PolicyDocument + PolicyRef now (compile() was
+      // skipped). Shape mirrors the adapter's output exactly.
+      interpreterPolicyDocument = {
+        grammarVersion: 1,
+        installNonce: interpreterOpts.installNonce ?? 1,
+        encodedPredicate,
+        predicateHash,
+        ...(interpreterOpts.oracleParams ? { oracleParams: interpreterOpts.oracleParams } : {}),
+      }
+      interpreterPolicyRef = {
+        kind: 'interpreter',
+        interpreterAddress: PLACEHOLDER_INTERPRETER_ADDRESS,
+        predicateBlobBase64: encodedPredicate,
+      }
+    } else {
+      if (!interpreterPolicyDocument || !interpreterPolicyRef) {
+        return {
+          ok: false,
+          error: {
+            code: 'SYNTHESIS_ERROR',
+            message: 'interpreter policy document or ref was lost before re-encode',
+            severity: 'error',
+            retryable: false,
+          },
+        }
+      }
+      interpreterPolicyDocument = {
+        ...interpreterPolicyDocument,
+        encodedPredicate,
+        predicateHash,
+      }
+      if (interpreterPolicyRef.kind === 'interpreter') {
+        interpreterPolicyRef = {
+          ...interpreterPolicyRef,
+          predicateBlobBase64: encodedPredicate,
+        }
+      }
+    }
+  }
+
+  // When the interpreter succeeds, OZ-side `uncovered` warnings that the
+  // interpreter actually lowered (per-method scoping, recipient allowlists,
+  // eq_seq paths, oracle_price / invocation_count / token-mismatch
+  // window_spent) are misleading: OZ really did not lower them, but the
+  // interpreter did. Drop those so the user-facing warnings reflect what is
+  // still UN-enforced, not what OZ alone could not do.
+  const ozUncovered = interpreterPolicyRef
+    ? compileRes.uncovered.filter((u) => !INTERPRETER_COVERED_OZ_PATTERN.test(u))
+    : compileRes.uncovered
+
+  // 7. Merge into the OZ-shaped ProposedPolicy. Order:
+  //    [interpreterRef?, ...oz_builtinRefs]; cap = OZ_LIMITS.maxPoliciesPerRule.
+  const ozRefs = compileRes.proposed.policyRefs
+  const mergedRefs: ProposedPolicy['policyRefs'] = []
+  if (interpreterPolicyRef) mergedRefs.push(interpreterPolicyRef)
+  for (const r of ozRefs) mergedRefs.push(r)
+
+  if (mergedRefs.length > OZ_LIMITS.maxPoliciesPerRule) {
+    return {
+      ok: false,
+      error: {
+        code: 'POLICY_CAP_EXCEEDED',
+        message: `merged policy count ${mergedRefs.length} exceeds OZ maxPoliciesPerRule (${OZ_LIMITS.maxPoliciesPerRule})`,
+        severity: 'error',
+        retryable: false,
+      },
+    }
+  }
+
+  const mergedContextRule = {
+    ...compileRes.proposed.contextRule,
+    policies: mergedRefs,
+  }
+
   const proposed: ProposedPolicy = {
-    ...compileRes.proposed,
+    contextRule: mergedContextRule,
+    policyDocuments: interpreterPolicyDocument ? [interpreterPolicyDocument] : [],
+    policyRefs: mergedRefs,
     parseConfidence: { ...tx.parseConfidence },
     warnings: [
-      ...compileRes.uncovered.map((u) => `${PATH_B_PREFIX}${u}`),
-      ...composed.warnings.map((w) => `${PATH_B_PREFIX}${w}`),
+      ...ozUncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
+      ...composed.warnings.map((w) => `${UNCOVERED_PREFIX}${w}`),
     ],
     ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
   }
   return { ok: true, data: proposed }
 }
 
+/** OZ-side `uncovered` warning patterns that the interpreter adapter
+ *  actually lowers when wired in. When the interpreter adapter succeeds, we
+ *  drop matching entries from the OZ uncovered list so the user-facing
+ *  warnings reflect what is still UN-enforced rather than what OZ alone
+ *  could not do. Match the exact descriptor strings the OZ adapter emits
+ *  (see `src/adapters/oz/adapter.ts#describeCondition` /
+ *  `describeSelector`). */
+const INTERPRETER_COVERED_OZ_PATTERN =
+  /^per-method scoping to|^value allowlist on arg|^exact ordered sequence on arg|^oracle price condition on|^invocation-count window|^spending_limit on token .+ needs a CallContract context scoped to that token/
+
 /** Reject non-sane inputs before any policy is synthesized. windowSeconds /
  *  validUntilLedger / invocationLimit must be positive integers; limitAmount a
- *  positive i128 decimal string; network mainnet|testnet. */
+ *  positive i128 decimal string; network mainnet|testnet. When the caller
+ *  opts into the interpreter adapter, `smartAccountAddress` must be a C...
+ *  contract address (the on-chain policy-bound account, NOT the G... source
+ *  account from the recording), `installNonce` must be a positive integer
+ *  (default 1), and `oracleParams` must tighten-only vs the wasm defaults. */
 function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null {
   if (opts.network !== 'mainnet' && opts.network !== 'testnet') {
     return synthesisError(`network must be 'mainnet' or 'testnet', got: ${String(opts.network)}`)
@@ -189,6 +555,44 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
       )
     }
   }
+  if (opts.interpreter) {
+    const sa = opts.interpreter.smartAccountAddress
+    if (typeof sa !== 'string' || sa.length === 0) {
+      return synthesisError(
+        `interpreter.smartAccountAddress must be a non-empty string, got: ${String(sa)}`
+      )
+    }
+    if (!isContractAddress(sa)) {
+      return synthesisError(
+        `interpreter.smartAccountAddress must be a C... Stellar contract address (the on-chain policy-bound account, not the G... source account), got: ${sa}`
+      )
+    }
+    const nonce = opts.interpreter.installNonce
+    if (nonce !== undefined && !isPositiveInt(nonce)) {
+      return synthesisError(`interpreter.installNonce must be a positive integer, got: ${nonce}`)
+    }
+    const op = opts.interpreter.oracleParams
+    if (op) {
+      const MAX_STALE = 600
+      const MAX_DEV = 200
+      if (
+        op.maxStalenessSeconds !== undefined &&
+        (!isPositiveInt(op.maxStalenessSeconds) || op.maxStalenessSeconds > MAX_STALE)
+      ) {
+        return synthesisError(
+          `interpreter.oracleParams.maxStalenessSeconds must be a positive integer <= ${MAX_STALE} (tighten-only), got: ${op.maxStalenessSeconds}`
+        )
+      }
+      if (
+        op.maxDeviationBps !== undefined &&
+        (!isPositiveInt(op.maxDeviationBps) || op.maxDeviationBps > MAX_DEV)
+      ) {
+        return synthesisError(
+          `interpreter.oracleParams.maxDeviationBps must be a positive integer <= ${MAX_DEV} (tighten-only), got: ${op.maxDeviationBps}`
+        )
+      }
+    }
+  }
   return null
 }
 
@@ -206,6 +610,13 @@ function isPositiveI128(s: string): boolean {
   }
 }
 
+/** True when `s` looks like a Stellar C... contract address (strkey). The
+ *  source account from the recording is a G... account; the smart account is
+ *  a separate C... contract. */
+function isContractAddress(s: string): boolean {
+  return s.startsWith('C') && s.length === 56
+}
+
 function synthesisError(message: string): ToolError {
   return { code: 'SYNTHESIS_ERROR', message, severity: 'error', retryable: false }
 }
@@ -224,3 +635,149 @@ function mergeAmbiguities(
   }
   return out
 }
+
+/** Build the permit `EvalContext` the self-verify harness drives. The shape
+ *  mirrors the intended recorded call (the only call the user actually
+ *  performed) so:
+ *    - `evaluate(predicate, ctx).permit === true` must hold (the predicate
+ *      permits the recorded call it was derived from); a failure surfaces
+ *      as DENY_CASE_FAILURE.
+ *    - `generateCases(predicate, ctx)` produces a deny battery that reflects
+ *      the actual recorded move (real amount, real args, real window start).
+ *  Amounts are summed per-token over all movements of the recorded tx
+ *  (BigInt accumulation; never lossy). The `oraclePriceByAsset` map
+ *  contains a price+timestamp satisfying each `oracle_price` leaf in the
+ *  predicate so the intended call permits under every bound; the harness
+ *  then mutates those entries (stale / missing / deviation / paused) to
+ *  exercise the ORACLE_* deny paths. */
+function buildPermitContext(
+  tx: RecordedTransaction,
+  scope: Extract<ScopeDecision, { kind: 'call_contract' }>,
+  topLevel: ContractInvocation,
+  userResponses: ComposeUserResponses | undefined,
+  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 oraclePriceByAsset: EvalContext['oraclePriceByAsset'] = oracleSatisfyingPrices(
+    predicate,
+    tx.fetchedAt
+  )
+
+  const ctx: EvalContext = {
+    contract: scope.contract,
+    fn: topLevel.fn,
+    args: topLevel.args.map(cloneScVal),
+    atLedger: tx.ledgerSequence,
+    nowSeconds: tx.fetchedAt,
+    amountByToken,
+    windowSpentByToken: {},
+    invocationCountByWindow: {},
+    oraclePriceByAsset,
+  }
+  if (userResponses?.validUntilLedger !== undefined) {
+    ctx.validUntilLedger = userResponses.validUntilLedger
+  }
+  return ctx
+}
+
+function cloneScVal(value: { type: string; value: unknown }): ContractInvocation['args'][number] {
+  // EvalContext.args is an ScVal[]; the recorded args are already ScVal-shaped
+  // (decoded by the recorder). We clone top-level shells so the harness can
+  // mutate deny cases without aliasing the recorded call.
+  if (value.type === 'vec') {
+    return {
+      type: 'vec',
+      value: (value.value as ContractInvocation['args'][number][]).map(cloneScVal),
+    }
+  }
+  return { ...value } as ContractInvocation['args'][number]
+}
+
+/** Walk every `oracle_price` leaf in the predicate and return a price map
+ *  whose entries satisfy the bound so the intended call permits. The
+ *  timestamp is pinned to `nowSeconds` (the recorded `fetchedAt`) so the
+ *  fresh-oracle deny case in `generateCases` is the only path that flips
+ *  this map. Negatives are clamped at 0 - oracle prices are non-negative on
+ *  Stellar. */
+function oracleSatisfyingPrices(
+  predicate: PredicateNode,
+  nowSeconds: number
+): EvalContext['oraclePriceByAsset'] {
+  const out: EvalContext['oraclePriceByAsset'] = {}
+  visitOracleLeaves(predicate, (asset, op, bound) => {
+    let price: bigint
+    switch (op) {
+      case 'lt':
+      case 'gt':
+        price = op === 'lt' ? bound - 1n : bound + 1n
+        break
+      case 'lte':
+      case 'gte':
+      case 'eq':
+        price = bound
+        break
+    }
+    if (price < 0n) price = 0n
+    out[asset] = { price: price.toString(), timestampSeconds: nowSeconds }
+  })
+  return out
+}
+
+function visitOracleLeaves(
+  node: PredicateNode,
+  visit: (asset: string, op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte', 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 leftLeaf: PredicateLeaf = node.left
+      const rightLeaf: PredicateLeaf = node.right
+      const leftIsOracle = leftLeaf.kind === 'oracle_price'
+      const rightIsOracle = rightLeaf.kind === 'oracle_price'
+      let oracleAsset: string | undefined
+      let literal: bigint | undefined
+      if (leftIsOracle) {
+        oracleAsset = leftLeaf.asset
+        literal = oracleLiteralFromLeaf(rightLeaf)
+      } else if (rightIsOracle) {
+        oracleAsset = rightLeaf.asset
+        literal = oracleLiteralFromLeaf(leftLeaf)
+      }
+      if (oracleAsset === undefined || literal === undefined) return
+      visit(oracleAsset, node.op, literal)
+      return
+    }
+    case 'in':
+      // `in` is pure membership; oracle leaves inside haystacks are
+      // forbidden by the position rule, so there's nothing to set up here.
+      return
+  }
+}
+
+function oracleLiteralFromLeaf(leaf: PredicateLeaf): bigint | undefined {
+  if (leaf.kind !== 'literal_i128') return undefined
+  try {
+    return BigInt(leaf.value)
+  } catch {
+    return undefined
+  }
+}