@crediolabs/policy-synth 0.1.3 → 0.1.5

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

@@ -1,27 +1,53 @@
 // 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` 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,
+  MAX_SCVAL_CLONE_DEPTH,
   type Network,
+  OZ_LIMITS,
+  type PredicateLeaf,
+  type PredicateNode,
   type ProposedPolicy,
   type RecordedTransaction,
   SOROBAN_LIMITS,
@@ -31,31 +57,132 @@ 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 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. */
 export function synthesizeFromRecording(
   tx: RecordedTransaction,
   opts: SynthesizeFromRecordingOptions,
   ozConfig: OzAdapterConfig
+): ToolResponse<ProposedPolicy> {
+  // Item 3: ToolError try/catch envelope. Any ToolError-shaped throw (object
+  // with a string `.code`) inside the body is converted to a structured
+  // `{ok:false, error}`; anything else is rethrown so genuine bugs crash
+  // instead of being silently swallowed. The envelope must wrap the entire
+  // synthesis body so a thrown `encodePredicate` cap error (PREDICATE_TOO_DEEP,
+  // TOO_MANY_LEAVES, etc.) or a depth-cap throw from `cloneScVal` surfaces as
+  // a structured ToolError rather than a thrown RangeError.
+  try {
+    return synthesizeFromRecordingInner(tx, opts, ozConfig)
+  } catch (e) {
+    if (isToolErrorShape(e)) {
+      return {
+        ok: false,
+        error: {
+          code: e.code as ToolError['code'],
+          message: e.message,
+          severity: 'error',
+          retryable: false,
+        },
+      }
+    }
+    throw e
+  }
+}
+
+/** True when `e` is the ToolError-shaped throw the internal pipeline uses to
+ *  signal a structured failure (e.g. `encodePredicate` cap errors, `cloneScVal`
+ *  depth-cap throws). Detected by a string `code` field — the only contract
+ *  the body's internal helpers agree on. */
+function isToolErrorShape(e: unknown): e is { code: string; message: string } {
+  if (e === null || typeof e !== 'object') return false
+  const code = (e as { code?: unknown }).code
+  const message = (e as { message?: unknown }).message
+  return typeof code === 'string' && typeof message === 'string'
+}
+
+/** ToolError-shaped error helper used by the body to surface a structured
+ *  failure that the envelope converts to `{ok:false, error}`. */
+function throwToolError(code: ToolError['code'], message: string): never {
+  const err = new Error(message) as Error & { code: string; severity: string; retryable: boolean }
+  err.code = code
+  err.severity = 'error'
+  err.retryable = false
+  throw err
+}
+
+/** Synthesize a ProposedPolicy from a recorded transaction. */
+function synthesizeFromRecordingInner(
+  tx: RecordedTransaction,
+  opts: SynthesizeFromRecordingOptions,
+  ozConfig: OzAdapterConfig
 ): ToolResponse<ProposedPolicy> {
   // 0. validate inputs (fail closed - never synthesize from garbage).
   const invalid = validateOptions(opts)
   if (invalid) return { ok: false, error: invalid }
 
+  // 0a. per-movement amount validation (item 2). Synthesizing from a recording
+  //     whose `tokenMovements[].amount` does not match the canonical positive
+  //     decimal integer format is a malformed-input failure, not a runtime
+  //     one - reject it here so the downstream `BigInt(m.amount)` in
+  //     `buildPermitContext` cannot throw a SyntaxError past the envelope.
+  for (const [i, m] of tx.tokenMovements.entries()) {
+    if (!/^[0-9]+$/.test(m.amount)) {
+      return {
+        ok: false,
+        error: {
+          code: 'RECORDING_VALIDATION_FAILED',
+          message: `tokenMovements[${i}].amount must be a positive decimal integer string, got: ${m.amount}`,
+          severity: 'error',
+          retryable: false,
+        },
+      }
+    }
+  }
+
   // 1. parseConfidence gate.
   const threshold = opts.confidenceOverride?.threshold ?? tx.parseConfidence.thresholdUsed
   if (tx.parseConfidence.overall < threshold) {
@@ -98,9 +225,6 @@ 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 covered flow;
-    // surface SYNTHESIS_ERROR so the orchestrator never silently emits an
-    // over-broad default-scoped policy.
     return {
       ok: false,
       error: {
@@ -116,13 +240,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,12 +262,263 @@ export function synthesizeFromRecording(
     }
   }
 
-  // 6. assemble ProposedPolicy.
+  // 6. Interpreter compile (opt-in; fail-closed when the user routed real
+  //    restrictions to the interpreter).
+  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 } : {}),
+    }
+
+    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) {
+        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.
+    if (!topLevel) {
+      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)
+
+    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. The
+    //     `encodePredicate` helper throws ToolError-shaped errors on cap
+    //     breaches (PREDICATE_TOO_DEEP, TOO_MANY_LEAVES, etc.) - the outer
+    //     envelope converts them to a structured `{ok:false, error}`.
+    const { encodedPredicate, predicateHash } = encodePredicate(finalPredicate)
+
+    if (testSeam !== undefined) {
+      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 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.
+  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) => `${UNCOVERED_PREFIX}${u}`),
+      ...ozUncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
       ...composed.warnings.map((w) => `${UNCOVERED_PREFIX}${w}`),
     ],
     ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
@@ -150,9 +526,27 @@ export function synthesizeFromRecording(
   return { ok: true, data: proposed }
 }
 
+// Re-export the throwToolError helper for callers that need to surface a
+// ToolError-shaped throw inside the body (e.g. tests).
+export { throwToolError }
+
+/** 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,9 +583,71 @@ 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)}`
+      )
+    }
+    // Blocklist placeholder / stub prefixes (item 5). Runs BEFORE the
+    // C.../56-char shape check so a fixture/LLM-seam marker is reported
+    // with the specific placeholder error (not a generic "must be a
+    // C... contract" message). A real install routes a C... contract
+    // address derivable from the on-chain account; any
+    // 'VERIFY-*' / 'PLACEHOLDER-*' / 'TODO-*' prefix is an LLM seam /
+    // fixture marker that must never reach the install payload.
+    if (PLACEHOLDER_SMART_ACCOUNT_PREFIX.test(sa)) {
+      return synthesisError(
+        `interpreter.smartAccountAddress must not be a placeholder/stub address (matches /${PLACEHOLDER_SMART_ACCOUNT_PREFIX.source}/), got: ${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
+    // Item 4: installNonce must fit u32 (the on-chain per-rule nonce is a
+    // u32; values above SOROBAN_LIMITS.u32Max cannot be installed). Mirrors
+    // the validUntilLedger SOROBAN_LIMITS.u32Max check above.
+    if (nonce !== undefined && (!isPositiveInt(nonce) || nonce > SOROBAN_LIMITS.u32Max)) {
+      return synthesisError(
+        `interpreter.installNonce must be a positive u32 integer (<= ${SOROBAN_LIMITS.u32Max}), 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
 }
 
+/** Placeholder/stub smart-account prefixes (item 5). Mirrors the
+ *  `PLACEHOLDER_INTERPRETER_ADDRESS` marker the interpreter adapter uses for
+ *  the interpreter-contract strkey; a real install must point at a C...
+ *  contract address derivable from the on-chain account, never a
+ *  fixture/LLM-seam marker. */
+const PLACEHOLDER_SMART_ACCOUNT_PREFIX = /^(VERIFY-|PLACEHOLDER-|TODO-)/i
+
 function isPositiveInt(n: number): boolean {
   return Number.isInteger(n) && n > 0
 }
@@ -206,6 +662,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 +687,176 @@ 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 },
+  depth = 0
+): 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. Recursion is
+  // bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec payload
+  // cannot RangeError the JS stack; the over-depth branch throws a
+  // ToolError-shaped error that the `synthesizeFromRecording` envelope
+  // (item 3) converts to `{ok:false, error}`.
+  if (value.type === 'vec') {
+    if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+      throw cloneDepthError(value)
+    }
+    return {
+      type: 'vec',
+      value: (value.value as ContractInvocation['args'][number][]).map((v) =>
+        cloneScVal(v, depth + 1)
+      ),
+    }
+  }
+  return { ...value } as ContractInvocation['args'][number]
+}
+
+/** Throw a ToolError-shaped error when the clone exceeds MAX_SCVAL_CLONE_DEPTH.
+ *  The shape (object with string `code`) is what the `synthesizeFromRecording`
+ *  envelope detects and converts to a structured `{ok:false, error}`. */
+function cloneDepthError(value: { type: string; value: unknown }): never {
+  const err = new Error(
+    `ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`
+  ) as Error & { code: string; severity: string; retryable: boolean; depthContext: unknown }
+  err.code = 'SYNTHESIS_ERROR'
+  err.severity = 'error'
+  err.retryable = false
+  // Tag the offending value so failures are diagnosable.
+  err.depthContext = value.type
+  throw err
+}
+
+/** 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
+  }
+}