@crediolabs/policy-synth 0.1.17 → 0.2.0

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

@@ -1,35 +1,10 @@
 // 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` + 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)` -> { ir (OZ-shape),
-//      interpreterIr (predicate-shape), ambiguities, warnings }.
-//   5. `ozAdapter.compile(ir)` -> CompileResult.
-//   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.
+// `synthesizeFromRecording` INFERS a bounded policy from a `RecordedTransaction`
+// via the same `PolicyIR` + adapter pair used by the deterministic Mandate path.
+// Flow: validate -> parseConfidence gate -> lower -> decideScope -> composeFromRecording
+// -> OZ compile -> (opt-in) interpreter compile + self-verify + minimise -> merge.
+// Same (tx, opts, ozConfig) -> byte-identical ProposedPolicy (no randomness, clock, globals).
 
 import type { InterpreterAdapterConfig } from '../adapters/interpreter/adapter.ts'
 import {
@@ -81,34 +56,27 @@ export interface InterpreterAdapterOptions {
    *  (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. */
+}
+
+/** PRIVATE test-only extension of `InterpreterAdapterOptions` for the
+ *  `__testPredicateNode` seam. Exported under a `__` prefix so production
+ *  callers can grep for it and see it is a test hook. The seam is read in
+ *  `synthesizeFromRecordingInner` only when `process.env.NODE_ENV === 'test'`
+ *  - a hard RUNTIME guard throws otherwise so a misconfigured production
+ *  caller cannot bypass the recording -> interpreter adapter compile path. */
+export type __TestInterpreterAdapterOptions = InterpreterAdapterOptions & {
+  /** @internal Test-only seam. Throws at runtime when NODE_ENV !== 'test'. */
   __testPredicateNode?: PredicateNode
 }
 
-/** Top-level orchestrator inputs. `userResponses` carries the LLM-collected
- *  answers to the ambiguity prompts (windowSeconds, validUntilLedger,
- *  limitAmount, invocationLimit, oraclePriceBound, swapRecipientAllowlist).
- *  `interpreter` opts the recording path into the interpreter adapter. */
+/** Top-level orchestrator inputs. */
 export interface SynthesizeFromRecordingOptions {
   network: Network
   userResponses?: ComposeUserResponses
   confidenceOverride?: { threshold: number }
   interpreter?: InterpreterAdapterOptions
-  /** --explain opt-in. When true, the orchestrator attaches the
-   *  in-memory `PredicateNode` + the corresponding `SimulationResult`
-   *  to the success envelope so the CLI can render a human-readable
-   *  review card. 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 opt-in. The flag is ADDITIVE: existing ProposedPolicy fields are
+   *  never altered by enabling explain. Absent -> success envelope is byte-identical. */
   explain?: true
 }
 
@@ -132,13 +100,11 @@ export function synthesizeFromRecording(
     simulation: SimulationResult
   }
 } {
-  // 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.
+  // Convert any ToolError-shaped throw (object with a string `.code`) to a
+  // structured `{ok:false, error}`; anything else is rethrown so genuine bugs
+  // crash instead of being silently swallowed. Wraps the entire body so
+  // cap errors (PREDICATE_TOO_DEEP, TOO_MANY_LEAVES) and cloneScVal depth
+  // throws surface as structured ToolErrors rather than RangeErrors.
   try {
     return synthesizeFromRecordingInner(tx, opts, ozConfig)
   } catch (e) {
@@ -157,10 +123,9 @@ export function synthesizeFromRecording(
   }
 }
 
-/** 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. */
+/** True when `e` is a ToolError-shaped throw (object with a string `code`).
+ *  Detected by 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
@@ -178,7 +143,6 @@ function throwToolError(code: ToolError['code'], message: string): never {
   throw err
 }
 
-/** Synthesize a ProposedPolicy from a recorded transaction. */
 function synthesizeFromRecordingInner(
   tx: RecordedTransaction,
   opts: SynthesizeFromRecordingOptions,
@@ -193,11 +157,9 @@ function synthesizeFromRecordingInner(
   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.
+  // 0a. per-movement amount validation. Reject malformed recordings 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 {
@@ -227,15 +189,9 @@ function synthesizeFromRecordingInner(
     }
   }
 
-  // 1a. Zero-invocation refusal (item 1). A recording with zero contract
-  //     invocations cleared the parseConfidence gate legitimately (the
-  //     `denom === 0` short-circuit pins overall to 1.0 for that case), but a
-  //     policy must scope to an authorized contract call. Refuse before any
-  //     lower/scope work so the failure is specific and actionable. The
-  //     recorder's silence is also made visible via `parseConfidence.noInvocations`
-  //     so consumers can pattern-match without inferring from `invocations: []`
-  //     next to `overall: 1.0`. The message does NOT ask for an ABI - the
-  //     failure mode is the recording shape, not decoding coverage.
+  // 1a. Zero-invocation refusal. A recording with zero invocations clears
+  //     parseConfidence legitimately (denom === 0 short-circuits overall to 1.0),
+  //     but a policy must scope to an authorized contract call. Refuse early.
   const hasNoInvocations = tx.parseConfidence.noInvocations === true || tx.invocations.length === 0
   if (hasNoInvocations) {
     return {
@@ -268,10 +224,8 @@ function synthesizeFromRecordingInner(
     }
   }
 
-  // 2. lower.
   const facts = lower(tx)
 
-  // 3. decideScope.
   const scopeRes = decideScope(facts, {
     network: opts.network,
     ...(opts.userResponses?.validUntilLedger !== undefined
@@ -302,11 +256,8 @@ function synthesizeFromRecordingInner(
   const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts)
 
   // --explain hook: capture the in-memory predicate tree + the real
-  // self-verify verdict so the CLI can render a faithful review card.
-  // The verdict below is built from the SAME runHarness + evaluate that
-  // already gates the synthesis (it is not a parallel simulation); the
-  // intermediate inputs (harnessCases, evalResult) are otherwise discarded
-  // after the gate, so the explain hook reuses them - no extra work.
+  // self-verify verdict (built from the SAME runHarness + evaluate that gated
+  // the synthesis, not a parallel simulation).
   let explain: PredicateNode | null = null
   let explainSim: SimulationResult | null = null
 
@@ -333,6 +284,10 @@ function synthesizeFromRecordingInner(
 
   let interpreterPolicyDocument: ProposedPolicy['policyDocuments'][number] | null = null
   let interpreterPolicyRef: ProposedPolicy['policyRefs'][number] | null = null
+  // Cross-layer L3: declared OUTSIDE the `if (interpreterOpts)` block so the
+  // warnings folded into `proposed.warnings[]` (which lives after that block)
+  // can read it. The block assigns it; the default is empty.
+  let permitCtxWarnings: string[] = []
 
   if (interpreterOpts) {
     const interpreterConfig: InterpreterAdapterConfig = {
@@ -343,8 +298,19 @@ function synthesizeFromRecordingInner(
     }
 
     let startingPredicate: PredicateNode | null = null
-    const testSeam = interpreterOpts.__testPredicateNode
+    // `__testPredicateNode` is a test-only seam. It is NOT in the public
+    // `InterpreterAdapterOptions` type, so a production caller cannot set it
+    // without bypassing the type system. We read it via a private cast and
+    // enforce a runtime NODE_ENV check so a misconfigured production caller
+    // that smuggles it in (any-cast, JSON-driven opt, etc.) is caught here
+    // rather than silently overriding the compiled predicate.
+    const testSeam = (interpreterOpts as __TestInterpreterAdapterOptions).__testPredicateNode
     if (testSeam !== undefined) {
+      if (process.env.NODE_ENV !== 'test') {
+        throw new Error(
+          'synthesizeFromRecording: __testPredicateNode is a test-only seam and is refused outside NODE_ENV=test'
+        )
+      }
       startingPredicate = testSeam
     } else {
       const interpreterAdapter = createInterpreterAdapter(interpreterConfig)
@@ -466,7 +432,18 @@ function synthesizeFromRecordingInner(
         },
       }
     }
-    const permitCtx = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate)
+    // Cross-layer L3: warnings collected from `buildPermitContext` (currently
+    // only the oracle-on-right normaliser) and folded into the proposed
+    // policy's `warnings[]` so the caller sees them on the success envelope.
+    const permitCtxResult = buildPermitContext(
+      tx,
+      scope,
+      topLevel,
+      opts.userResponses,
+      startingPredicate
+    )
+    const permitCtx = permitCtxResult.ctx
+    permitCtxWarnings = permitCtxResult.warnings
 
     const finalPredicate: PredicateNode =
       startingPredicate.op === 'and'
@@ -501,12 +478,9 @@ function synthesizeFromRecordingInner(
       }
     }
 
-    // --explain capture: the interpreter path already produced the real
-    // self-verify verdict (runHarness passed, evalResult.permit is true).
-    // Build the SimulationResult from those outputs so the CLI card
-    // quotes the SAME verdict that gated the synthesis. We re-evaluate
-    // each deny case to surface its concrete reason; the harness only
-    // records whether the got-matches-expected boundary held.
+    // --explain capture: quote the SAME verdict that gated the synthesis.
+    // Re-evaluate each deny case to surface its concrete reason (the harness
+    // only records whether the got-matches-expected boundary held).
     if (opts.explain) {
       explain = finalPredicate
       const evaluatedCases: SimulationResult['evaluatedCases'] = [
@@ -533,10 +507,9 @@ function synthesizeFromRecordingInner(
     }
 
     // 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}`.
+    //     canonical bytes back onto the PolicyDocument + PolicyRef. Cap breaches
+    //     (PREDICATE_TOO_DEEP, TOO_MANY_LEAVES) throw ToolError-shaped errors;
+    //     the outer envelope converts them to structured `{ok:false, error}`.
     const { encodedPredicate, predicateHash } = encodePredicate(finalPredicate)
 
     if (testSeam !== undefined) {
@@ -612,9 +585,7 @@ function synthesizeFromRecordingInner(
   // When nothing installable was synthesised (no interpreter doc AND no OZ
   // policy refs), an empty `policies` array reads as "no restrictions" rather
   // than "I synthesised nothing". Surface that explicitly so the empty result
-  // is never mistaken for a permissive policy - the context rule still exists,
-  // but it constrains nothing. (Kept as `{ok:true}` so the documented
-  // Path-A/Path-B demo behaviour is preserved - see F3.)
+  // is never mistaken for a permissive policy.
   const zeroPolicyWarning =
     mergedRefs.length === 0 && !interpreterPolicyDocument
       ? [
@@ -631,16 +602,14 @@ function synthesizeFromRecordingInner(
       ...zeroPolicyWarning,
       ...ozUncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
       ...composed.warnings.map((w) => `${UNCOVERED_PREFIX}${w}`),
+      ...permitCtxWarnings,
     ],
     ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
   }
-  // --explain success envelope. The interpreter path populated
-  // `explain` + `explainSim` from the real self-verify verdict above;
-  // the OZ-only path did not (no predicate tree exists). When opts.explain
-  // is set and the OZ-only path ran, construct the minimal honest
-  // SimulationResult: the verdict is NOT a passing simulation - the
-  // interpreter was never engaged, so permit is deny with a truthful
-  // reason and evaluatedCases is empty.
+  // --explain success envelope. When opts.explain is set and the OZ-only
+  // path ran, construct the minimal honest SimulationResult: the verdict
+  // is NOT a passing simulation - the interpreter was never engaged, so
+  // permit is deny with a truthful reason and evaluatedCases is empty.
   const envelope: ToolResponse<ProposedPolicy> & {
     explain?: {
       predicateTree: PredicateNode | null
@@ -668,27 +637,24 @@ function synthesizeFromRecordingInner(
   return envelope
 }
 
-// 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`). */
+/** OZ-side `uncovered` warning patterns the interpreter adapter actually lowers
+ *  when wired in. When the interpreter adapter succeeds, matching entries are
+ *  dropped from the OZ uncovered list so user-facing warnings reflect what is
+ *  still UN-enforced rather than what OZ alone could not do. Matches 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. 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. */
+ *  positive i128 decimal string; network mainnet|testnet. When the interpreter
+ *  adapter is opted in, `smartAccountAddress` must be a C... contract address
+ *  (the on-chain policy-bound account, NOT the G... source account),
+ *  `installNonce` must fit u32 (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)}`)
@@ -732,13 +698,9 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
         `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.
+    // Block placeholder/stub prefixes BEFORE the C.../56-char shape check so
+    // a fixture/LLM-seam marker is reported with the specific placeholder
+    // error. 'VERIFY-*' / 'PLACEHOLDER-*' / 'TODO-*' must never reach install.
     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}`
@@ -750,9 +712,7 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
       )
     }
     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.
+    // installNonce must fit u32 (the on-chain per-rule nonce is a u32).
     if (nonce !== undefined && (!isPositiveInt(nonce) || nonce > SOROBAN_LIMITS.u32Max)) {
       return synthesisError(
         `interpreter.installNonce must be a positive u32 integer (<= ${SOROBAN_LIMITS.u32Max}), got: ${nonce}`
@@ -783,7 +743,7 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
   return null
 }
 
-/** Placeholder/stub smart-account prefixes (item 5). Mirrors the
+/** Placeholder/stub smart-account prefixes. 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
@@ -792,18 +752,17 @@ const PLACEHOLDER_SMART_ACCOUNT_PREFIX = /^(VERIFY-|PLACEHOLDER-|TODO-)/i
 
 /** Maximum value a signed i128 can hold (2^127-1). A limitAmount above this
  *  cannot be represented on-chain, so reject it at the synthesis boundary
- *  (fail-closed) instead of passing it through as an over-broad spending_limit.
- *  Mirrors the SOROBAN_LIMITS.u32Max bound the ledger-sequence fields enforce. */
+ *  (fail-closed) instead of passing it through as an over-broad spending_limit. */
 const I128_MAX = 2n ** 127n - 1n
 
 function isPositiveInt(n: number): boolean {
   return Number.isInteger(n) && n > 0
 }
 
-/** True when `s` is a canonical positive decimal integer inside the signed-i128
- *  range [1, 2^127-1]. A value above the i128 ceiling is rejected (fail-closed):
- *  it cannot be installed on-chain, and accepting it would emit a spending_limit
- *  with an effectively unbounded cap. */
+/** True when `s` is a canonical positive decimal integer inside [1, 2^127-1].
+ *  Values above the i128 ceiling are rejected fail-closed: they cannot be
+ *  installed on-chain, and accepting them would emit a spending_limit with an
+ *  effectively unbounded cap. */
 function isPositiveI128(s: string): boolean {
   if (!/^[0-9]+$/.test(s)) return false
   try {
@@ -840,27 +799,24 @@ 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.
+/** Build the permit `EvalContext` the self-verify harness drives. Shape
+ *  mirrors the intended recorded call so:
+ *    - `evaluate(predicate, ctx).permit === true` must hold (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. */
+ *      the actual recorded move (real amount, args, window start).
+ *  Amounts are summed per-token over all movements (BigInt, never lossy).
+ *  `oraclePriceByAsset` contains a price+timestamp satisfying each
+ *  `oracle_price` leaf so the intended call permits under every bound;
+ *  the harness 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 {
+): { ctx: EvalContext; warnings: string[] } {
   const amountByToken: Record<string, string> = {}
   const totals = new Map<string, bigint>()
   for (const m of tx.tokenMovements) {
@@ -871,9 +827,11 @@ function buildPermitContext(
     amountByToken[token] = total.toString()
   }
 
+  const warnings: string[] = []
   const oraclePriceByAsset: EvalContext['oraclePriceByAsset'] = oracleSatisfyingPrices(
     predicate,
-    tx.fetchedAt
+    tx.fetchedAt,
+    warnings
   )
 
   const ctx: EvalContext = {
@@ -890,20 +848,18 @@ function buildPermitContext(
   if (userResponses?.validUntilLedger !== undefined) {
     ctx.validUntilLedger = userResponses.validUntilLedger
   }
-  return ctx
+  return { ctx, warnings }
 }
 
 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}`.
+  // Clone top-level shells so the harness can mutate deny cases without
+  // aliasing the recorded call. Recursion bounded by MAX_SCVAL_CLONE_DEPTH so
+  // a hand-crafted nested-vec cannot RangeError the JS stack; the over-depth
+  // branch throws a ToolError-shaped error the envelope converts to
+  // `{ok:false, error}`.
   if (value.type === 'vec') {
     if (depth >= MAX_SCVAL_CLONE_DEPTH) {
       throw cloneDepthError(value)
@@ -918,9 +874,6 @@ function cloneScVal(
   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})`
@@ -928,52 +881,96 @@ function cloneDepthError(value: { type: string; value: unknown }): never {
   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. */
+/** Walk every `oracle_price` leaf and return a price map whose entries satisfy
+ *  the bound. Timestamp pinned to `nowSeconds` (the recorded `fetchedAt`) so
+ *  the fresh-oracle deny case in `generateCases` is the only path that flips
+ *  this map. Negatives clamped at 0 - oracle prices are non-negative on Stellar. */
 function oracleSatisfyingPrices(
   predicate: PredicateNode,
-  nowSeconds: number
+  nowSeconds: number,
+  warnings: string[]
 ): 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
+  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 }
+    },
+    (warning) => {
+      // Cross-layer L3: oracle-on-right that cannot be normalised is
+      // surfaced as a warning, not silently dropped. The Rust interpreter
+      // would surface this as `UnsupportedNode`; the warning lets the
+      // caller decide whether to fix the predicate shape or accept the
+      // over-permissive hole.
+      warnings.push(warning.message)
     }
-    if (price < 0n) price = 0n
-    out[asset] = { price: price.toString(), timestampSeconds: nowSeconds }
-  })
+  )
   return out
 }
 
+// Cross-layer L3: surface oracle-on-right as a WARNING rather than silently
+// dropping it. The Rust interpreter only fires `eval_oracle_compare` when the
+// oracle leaf is on the LEFT (`oracle_price op threshold`); a predicate that
+// inverts the shape (`threshold op oracle_price`) falls through to
+// `UnsupportedNode` instead. The TS model and the lowering path both attempt
+// to normalise oracle-on-right by flipping the operator so the oracle ends
+// up on the left, but the normalisation is only possible when the other
+// side is a literal we can read as a bigint (an `oracle_threshold`, an
+// `i128`/`u32`/`u64` literal). When it isn't (e.g. `oracle_price < call_arg[i]`),
+// the case cannot be normalised - previously we silently dropped it, which
+// means the harness would never exercise the bound and `minimize` could
+// prune it. The warning is purely additive: the existing normalisation
+// path is preserved, the case is just also reported so callers can decide
+// to either fix the predicate shape or accept the over-permissive hole.
+
+/** Diagnostic reported by `visitOracleLeaves` when an oracle comparison
+ *  cannot be normalised to oracle-on-left. Currently only "oracle-on-right
+ *  with a non-literal LHS" - the other branches already produce a parseable
+ *  threshold and are returned to the caller. */
+export interface OracleNormalisationWarning {
+  /** The dimension name (currently always "oracle_normalisation_dropped"). */
+  dimension: 'oracle_normalisation_dropped'
+  /** The operator as written. */
+  op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte'
+  /** The asset the oracle leaf is bound to. */
+  asset: string
+  /** The non-literal RHS (oracle-on-left) or LHS (oracle-on-right) leaf
+   *  whose shape stopped the normalisation. Surfaced for diagnostics;
+   *  intentionally a partial view - the full leaf is the caller's job. */
+  otherKind: string
+  /** Human-readable message (matches the warn-on-drop text). */
+  message: string
+}
+
 function visitOracleLeaves(
   node: PredicateNode,
-  visit: (asset: string, op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte', bound: bigint) => void
+  visit: (asset: string, op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte', bound: bigint) => void,
+  onWarning?: (warning: OracleNormalisationWarning) => void
 ): void {
   switch (node.op) {
     case 'and':
     case 'or':
-      for (const child of node.children) visitOracleLeaves(child, visit)
+      for (const child of node.children) visitOracleLeaves(child, visit, onWarning)
       return
     case 'not':
-      visitOracleLeaves(node.child, visit)
+      visitOracleLeaves(node.child, visit, onWarning)
       return
     case 'eq':
     case 'lt':
@@ -993,7 +990,27 @@ function visitOracleLeaves(
         oracleAsset = rightLeaf.asset
         literal = oracleLiteralFromLeaf(leftLeaf)
       }
-      if (oracleAsset === undefined || literal === undefined) return
+      if (oracleAsset === undefined || literal === undefined) {
+        // Two reasons the case cannot be normalised:
+        //   - neither side is an oracle leaf (visitor has nothing to do)
+        //   - oracle-on-right with a non-literal LHS (Rust dispatch would
+        //     hit UnsupportedNode; the TS model cannot build a permit ctx
+        //     for it)
+        // Only the second is a meaningful warning; the first is a no-op
+        // (the visitor was called for a non-oracle comparison). Emit the
+        // warning when an oracle IS present on one side but the other
+        // side is not a parseable threshold literal.
+        if (rightIsOracle) {
+          onWarning?.({
+            dimension: 'oracle_normalisation_dropped',
+            op: node.op,
+            asset: rightLeaf.kind === 'oracle_price' ? rightLeaf.asset : '',
+            otherKind: leftLeaf.kind,
+            message: `oracle-on-right cannot be normalised: the LHS (kind=${leftLeaf.kind}) is not an oracle_threshold literal; the Rust interpreter would surface UnsupportedNode here`,
+          })
+        }
+        return
+      }
       visit(oracleAsset, node.op, literal)
       return
     }
@@ -1004,9 +1021,9 @@ function visitOracleLeaves(
   }
 }
 
-/** An oracle threshold restated on the normalised 9-dp basis prices use.
- *  Thresholds carry their own basis, so reading the digits raw would build a
- *  permit context off by 10^(decimals-9) and the intended call would not
+/** Restate an oracle threshold on the normalised 9-dp basis prices use.
+ *  Thresholds carry their own basis, so reading the digits raw would build
+ *  a permit context off by 10^(decimals-9) and the intended call would not
  *  satisfy its own bound. Mirrors NORMALISED_DECIMALS in oracle.rs. */
 function oracleLiteralFromLeaf(leaf: PredicateLeaf): bigint | undefined {
   if (leaf.kind !== 'oracle_threshold') return undefined