@crediolabs/policy-synth 0.1.17 → 0.2.0

package/dist-cjs/synth/compose-from-recording.js

@@ -1,53 +1,43 @@
 "use strict";
-// src/synth/compose-from-recording.ts - facts + scope -> PolicyIR (OZ-shape + interpreter-shape).
-//
-// Composes the canonical IR rules the two backends compile FROM. Fail-closed
-// composition rules:
-//
-//   - identify the protocol of the top-level call (registry.identifyProtocol).
-//     When it is unknown (null), emit NO OZ-primitive-producing IR node: the
-//     scope is kept (CallContract + method) and every inferred bound is surfaced
-//     as a descriptive warning. An unrecognised call never compiles to a
-//     permissive OZ primitive.
+// src/synth/compose-from-recording.ts - facts + scope -> PolicyIR (OZ + interpreter).
 //
+// Fail-closed composition rules:
+//   - unknown top-level protocol (registry.identifyProtocol returns null) ->
+//     emit no OZ-primitive-producing IR node; scope is kept (CallContract + method)
+//     and every inferred bound surfaces as a descriptive warning. An unrecognised
+//     call never compiles to a permissive OZ primitive.
 //   - carry the recorded top-level function into `rule.scope.method` so the OZ
 //     adapter flags per-method scoping as not covered (CallContract permits every
-//     method on the contract; a per-method restriction needs the interpreter predicate).
-//
-//   - a `spending_limit` (window_spent(token, w) <= limit) is emitted ONLY when
-//     the caller supplies BOTH the limit (userResponses.limitAmount) and the
-//     window (userResponses.windowSeconds). A single recorded spend does NOT
-//     authorise that amount every window, so the observed amount is NEVER used as
-//     an auto-ceiling: a missing limit surfaces AMOUNT_BOUND_MISSING (the observed
-//     amount is offered as a suggestion), a missing window surfaces
-//     DURATION_UNSPECIFIED. EVERY spent token is handled - none is silently
-//     dropped; a single caller limit binds only an unambiguous single-token spend.
-//
-//   - incoming-only flows (e.g. Blend yield claim) emit an `invocation_count`
-//     bound ONLY when the caller supplies the count (userResponses.invocationLimit)
-//     and a window; otherwise FREQUENCY_BOUND_MISSING is surfaced with no
-//     fabricated count.
-//
-//   - the IR carries ONLY constraints justified by the recording (observed
-//     recipient allowlist) + explicit user input. Nothing invented: no oracle
-//     price fabricated from a slippage bound, no synthetic exact-path compare.
-//     Those needs are surfaced as descriptive warnings instead.
+//     method; a per-method restriction needs the interpreter predicate).
+//   - `spending_limit` (window_spent(token, w) <= limit) is emitted ONLY when
+//     the caller supplies BOTH limit (userResponses.limitAmount) AND window
+//     (userResponses.windowSeconds). A single recorded spend does NOT authorise
+//     that amount every window, so the observed amount is NEVER used as an
+//     auto-ceiling: missing limit -> AMOUNT_BOUND_MISSING (observed amount
+//     offered as a suggestion); missing window -> DURATION_UNSPECIFIED. EVERY
+//     spent token is handled - none is silently dropped.
+//   - incoming-only flows emit an `invocation_count` bound ONLY when the caller
+//     supplies both the count and the window; otherwise FREQUENCY_BOUND_MISSING
+//     with no fabricated count.
+//   - the IR carries ONLY constraints justified by the recording + explicit
+//     user input. Nothing invented: no oracle price fabricated from a slippage
+//     bound, no synthetic exact-path compare. Those needs surface as warnings.
 //
 // Split rule (P3 wiring): `ComposeResult` carries BOTH `ir` (OZ-shape) and
 // `interpreterIr` (predicate-shape). Each constraint is routed to EXACTLY ONE
 // adapter:
-//   - `compare window_spent(token, w) <= limit` where `token === scope.contract`
-//     and the protocol is known -> `ir` (OZ lowers to spending_limit).
-//   - everything else the compose step emits (recipient allowlists, per-method
-//     scoping via scope.method, invocation_count bounds, eq_seq swap paths,
-//     oracle_price bounds, AND window_spent where token != scope.contract, i.e.
-//     a SoroSwap input-token cap) -> `interpreterIr`.
+//   - `window_spent(token, w) <= limit` where `token === scope.contract` and
+//     protocol is known -> `ir` (OZ lowers to spending_limit).
+//   - everything else (recipient allowlists, per-method scope.method,
+//     invocation_count, eq_seq swap paths, oracle_price, AND window_spent
+//     where token != scope.contract i.e. SoroSwap input-token cap) ->
+//     `interpreterIr`.
 //
 // This prevents the interpreter adapter from emitting a duplicate
 // `window_spent` predicate leaf alongside an OZ `spending_limit` primitive
 // covering the same spend semantic - the two adapters never overlap.
 //
-// The default behavior is `deny_all` (OZ context rules are deny-by-default).
+// Default policy is `deny_all` (OZ context rules are deny-by-default).
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.composeFromRecording = composeFromRecording;
 const identify_ts_1 = require("../registry/identify.js");
@@ -59,6 +49,15 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
     const warnings = [];
     const ozConstraints = [];
     const interpreterConstraints = [];
+    // Route to the matching IR. When the interpreter is enabled, constraints the
+    // OZ adapter cannot lower go there; otherwise they go to OZ (which flags them
+    // as uncovered) so today's warning-driven behaviour is preserved.
+    const routeToAdapter = (cond) => {
+        if (interpreterEnabled)
+            interpreterConstraints.push(cond);
+        else
+            ozConstraints.push(cond);
+    };
     const protocol = topLevel
         ? (0, identify_ts_1.identifyProtocol)(topLevel.contract, topLevel.fn, topLevel.args, opts.network)
         : null;
@@ -66,14 +65,15 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
     const windowSeconds = opts.userResponses?.windowSeconds;
     const limitAmount = opts.userResponses?.limitAmount;
     const spendTokens = Object.keys(facts.spendByToken);
-    // Outgoing spend -> one spending_limit per spent token. A single caller limit
-    // binds only an unambiguous single-token spend; a multi-token flow needs a
-    // per-token limit, so each unmatched token surfaces AMOUNT_BOUND_MISSING.
+    // Outgoing spend -> one spending_limit per spent token. A single caller
+    // limit binds only an unambiguous single-token spend; a multi-token flow
+    // needs a per-token limit, so each unmatched token surfaces
+    // AMOUNT_BOUND_MISSING.
     //
     // Routing: a `window_spent(token, w) <= limit` constraint goes to the OZ IR
     // only when token === scope.contract (OZ's spending_limit binds the
     // CallContract target, not a token parameter). Otherwise it goes to the
-    // interpreter IR (the interpreter lowers window_spent to a predicate leaf).
+    // interpreter IR.
     if (spendTokens.length > 0 && topLevel) {
         let durationFlagged = false;
         for (const token of spendTokens) {
@@ -99,24 +99,23 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
                 });
                 continue;
             }
-            if (windowSeconds !== undefined && limit !== undefined) {
-                const spendCond = {
+            if (windowSeconds !== undefined) {
+                // Rolling spend cap always goes to OZ (`spending_limit` is the audited
+                // implementation). The interpreter is NOT a fallback for token !=
+                // scopeContract: on chain it sees one authorized call, not the
+                // transaction's token movements, so it has no per-call amount to
+                // accumulate and the counter would never move. OZ reports the case it
+                // cannot cover (limit pins to the context contract) - the honest
+                // outcome; the old fallback produced an interpreter predicate that
+                // silently never bound.
+                ozConstraints.push({
                     op: 'compare',
                     compare: {
                         selector: { kind: 'window_spent', token, windowSeconds },
                         operator: 'lte',
                         value: limit,
                     },
-                };
-                // A rolling spend cap always goes to OZ, whose `spending_limit` is the
-                // audited implementation. The interpreter is NOT a fallback for the
-                // token != scopeContract case: on chain it sees one authorized call,
-                // not the transaction's token movements, so it has no per-call amount
-                // to accumulate and the counter would never move. OZ reports the case
-                // it cannot cover (it pins the limit to the context contract), which
-                // is the honest outcome - the old fallback produced an interpreter
-                // predicate that silently never bound.
-                ozConstraints.push(spendCond);
+                });
                 if (interpreterEnabled && token !== scopeContract) {
                     warnings.push(`rolling spend cap on ${token} cannot be enforced on chain: OZ spending_limit pins the limit to the context contract, and the interpreter cannot observe token movements. Bound the per-call value with an argument cap plus an invocation-count limit instead.`);
                 }
@@ -128,18 +127,18 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
     // Routed to the interpreter IR when interpreter is enabled (OZ cannot lower
     // invocation_count); otherwise to the OZ IR (which flags it as uncovered).
     //
-    // A recognised swap is NOT an incoming-only flow: it has an outgoing input leg
-    // whose spend simply was not attributed to the source account (the
-    // fee-sponsored / holder != source case). Its real restrictions - exact path,
-    // recipient, and the input-amount cap - come from the protocol-specific pass,
-    // so it does NOT get the incoming-only frequency prompt. A caller who wants to
+    // A recognised swap is NOT an incoming-only flow: it has an outgoing input
+    // leg whose spend simply was not attributed to the source account
+    // (fee-sponsored / holder != source). Its real restrictions - exact path,
+    // recipient, input-amount cap - come from the protocol-specific pass, so it
+    // does NOT get the incoming-only frequency prompt. A caller wanting to
     // rate-limit the swap can still supply an invocationLimit + window, which
     // lowers to an invocation_count for any flow.
     if (spendTokens.length === 0 && topLevel) {
         const invocationLimit = opts.userResponses?.invocationLimit;
         const isRecognisedSwap = protocol?.protocol === 'soroswap';
         if (known && windowSeconds !== undefined && invocationLimit !== undefined) {
-            const icCond = {
+            routeToAdapter({
                 op: 'compare',
                 compare: {
                     selector: { kind: 'invocation_count', windowSeconds },
@@ -149,13 +148,7 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
                     operator: 'lt',
                     value: String(invocationLimit),
                 },
-            };
-            if (interpreterEnabled) {
-                interpreterConstraints.push(icCond);
-            }
-            else {
-                ozConstraints.push(icCond);
-            }
+            });
         }
         else if (!isRecognisedSwap) {
             ambiguities.push({
@@ -171,7 +164,7 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
     const oracleBounds = opts.userResponses?.oraclePriceBound;
     if (oracleBounds) {
         for (const b of oracleBounds) {
-            const oracleCond = {
+            routeToAdapter({
                 op: 'compare',
                 compare: {
                     selector: { kind: 'oracle_price', asset: b.asset },
@@ -179,13 +172,7 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
                     value: b.value,
                     valueDecimals: b.decimals,
                 },
-            };
-            if (interpreterEnabled) {
-                interpreterConstraints.push(oracleCond);
-            }
-            else {
-                ozConstraints.push(oracleCond);
-            }
+            });
         }
     }
     // Observed recipient allowlist (SEP-41) is a real, recorded constraint the OZ
@@ -200,7 +187,7 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
         // the window_spent path above already consumed the limit, so the per-call
         // arg cap is skipped to avoid binding one limit to two different semantics.
         const swapInputAmountCap = spendTokens.length === 0 ? limitAmount : undefined;
-        appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, opts.userResponses?.swapRecipientAllowlist, swapInputAmountCap, opts.userResponses?.swapMinOutRatio, interpreterEnabled);
+        appendProtocolSpecificConstraints(interpreterConstraints, routeToAdapter, warnings, ambiguities, facts, topLevel, protocol, opts.userResponses?.swapRecipientAllowlist, swapInputAmountCap, opts.userResponses?.swapMinOutRatio, interpreterEnabled);
     }
     // `scope.method` is carried on BOTH IRs so each adapter produces a
     // self-consistent rule. The interpreter adapter lowers scope.method into a
@@ -242,32 +229,24 @@ function composeFromRecording(facts, scopeContract, topLevel, opts) {
  *  SoroSwap's slippage / oracle / exact-path needs come from `userResponses`
  *  (oraclePriceBound + limitAmount) + the recorded path (eq_seq on
  *  call_arg[2]). */
-function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints, warnings, ambiguities, facts, topLevel, protocol, swapRecipientAllowlist, swapInputAmountCap, swapMinOutRatio, interpreterEnabled) {
-    // SEP-41 transfer / mint: the `to` arg (index 1) is the recipient. Emit it as
-    // a single-element allowlist; the interpreter adapter lowers it to `in`.
+function appendProtocolSpecificConstraints(interpreterConstraints, routeToAdapter, warnings, ambiguities, facts, topLevel, protocol, swapRecipientAllowlist, swapInputAmountCap, swapMinOutRatio, interpreterEnabled) {
+    // SEP-41 transfer / mint: the `to` arg (index 1) is the recipient. Emit a
+    // single-element allowlist; the interpreter adapter lowers it to `in`.
     // When interpreter is not enabled, route to OZ so the caller sees today's
-    // `value allowlist on arg 1 (arg allowlist)` warning.
+    // `value allowlist on arg 1` warning.
     if (protocol.protocol === 'sep41' && (protocol.fn === 'transfer' || protocol.fn === 'mint')) {
         const toArg = topLevel.args[1];
         if (toArg && toArg.type === 'address') {
-            const cond = {
+            routeToAdapter({
                 op: 'in',
                 selector: { kind: 'arg', argIndex: 1, scalarType: 'address' },
                 values: [toArg.value],
-            };
-            if (interpreterEnabled) {
-                interpreterConstraints.push(cond);
-            }
-            else {
-                ozConstraints.push(cond);
-            }
+            });
         }
     }
     // Blend submit / claim: the `to` arg is the beneficiary - it receives the
     // resulting position shares on `submit` and the claimed tokens on `claim`.
-    // That is the same role as the SEP-41 recipient above and the SoroSwap swap
-    // recipient below, so it is pinned to the recorded address the same way:
-    // without it a policy scoped to a pool and method still lets an agent send
+    // Without it, a policy scoped to a pool + method still lets an agent send
     // the proceeds anywhere. `from` and `spender` are deliberately NOT pinned -
     // the call already requires their authorisation, so binding them adds no
     // restriction the chain is not already enforcing.
@@ -276,25 +255,19 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
         // claim(from, reserve_token_ids, to).
         const toArg = topLevel.args[2];
         if (toArg && toArg.type === 'address') {
-            const cond = {
+            routeToAdapter({
                 op: 'in',
                 selector: { kind: 'arg', argIndex: 2, scalarType: 'address' },
                 values: [toArg.value],
-            };
-            if (interpreterEnabled) {
-                interpreterConstraints.push(cond);
-            }
-            else {
-                ozConstraints.push(cond);
-            }
+            });
         }
     }
     // Blend `submit` ONLY (not `claim`, whose vec arg is a vec<u32> of
     // reserve_token_ids - no map fields to bind). The `requests` vec
     // (call_arg[3]) is a vec<Request{ address, amount, request_type }>. Each
-    // Request is the per-reserve action selector - 0 Supply, 1 Withdraw,
+    // Request is the per-reserve action selector (0 Supply, 1 Withdraw,
     // 2 SupplyCollateral, 3 WithdrawCollateral, 4 Borrow, 5 Repay, 6-9
-    // liquidation/auction fills. Pinning only one element is unsafe: a caller
+    // liquidation/auction fills). Pinning only one element is unsafe: a caller
     // can append a second element with a different action (WithdrawCollateral
     // -> Borrow on a different asset, any amount, then auction fills). Length
     // + per-element pinning is total; a quantifier over elements is not. If we
@@ -435,20 +408,14 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
             inputArgIndex !== undefined &&
             inputAmountArg &&
             inputAmountArg.type === 'i128') {
-            const cond = {
+            routeToAdapter({
                 op: 'compare',
                 compare: {
                     selector: { kind: 'arg', argIndex: inputArgIndex, scalarType: 'i128' },
                     operator: 'lte',
                     value: swapInputAmountCap,
                 },
-            };
-            if (interpreterEnabled) {
-                interpreterConstraints.push(cond);
-            }
-            else {
-                ozConstraints.push(cond);
-            }
+            });
         }
         // Slippage floor: `out >= in * num/den`. Only when the caller supplied the
         // ratio - see `swapMinOutRatio`. Without it the output arg stays free,
@@ -460,19 +427,13 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
             outMinArgIndex !== undefined &&
             inputAmountArg &&
             inputAmountArg.type === 'i128') {
-            const floor = {
+            routeToAdapter({
                 op: 'slippage_floor',
                 outArgIndex: outMinArgIndex,
                 inArgIndex: inputArgIndex,
                 num: minOutRatio.num,
                 den: minOutRatio.den,
-            };
-            if (interpreterEnabled) {
-                interpreterConstraints.push(floor);
-            }
-            else {
-                ozConstraints.push(floor);
-            }
+            });
         }
         // Swap recipient (call_arg[3]): when the caller supplies
         // swapRecipientAllowlist, emit it as an `in` constraint on the recipient
@@ -488,17 +449,11 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
         // (today's behaviour, matching the other SoroSwap constraints).
         const recipientArg = topLevel.args[3];
         if (swapRecipientAllowlist && swapRecipientAllowlist.length > 0) {
-            const cond = {
+            routeToAdapter({
                 op: 'in',
                 selector: { kind: 'arg', argIndex: 3, scalarType: 'address' },
                 values: [...swapRecipientAllowlist],
-            };
-            if (interpreterEnabled) {
-                interpreterConstraints.push(cond);
-            }
-            else {
-                ozConstraints.push(cond);
-            }
+            });
         }
         else if (interpreterEnabled && recipientArg && recipientArg.type === 'address') {
             interpreterConstraints.push({

package/dist-cjs/synth/deny-cases.d.ts

@@ -3,6 +3,11 @@ import type { EvalContext } from './evaluate.ts';
 export interface DenyCase {
     dimension: string;
     ctx: EvalContext;
+    /** Canonical reason the Rust interpreter returns for this dimension.
+     *  Optional: when set, `runHarness` asserts the TS evaluator emits this
+     *  exact string, so a future TS/Rust reason divergence fails CI. When
+     *  absent the case is only checked on the boolean decision. */
+    expectedReason?: string;
 }
 export interface GeneratedCases {
     permit: EvalContext;

package/dist-cjs/synth/deny-cases.js

@@ -11,17 +11,30 @@ const ORACLE_CASES = [
     ['oracle_deviation_exceeded', 'deviation'],
     ['oracle_paused', 'paused'],
 ];
+// Cross-layer reason contract: the TS evaluator's deny reason for each
+// oracle error category must match the Rust interpreter's `DenyReason` code
+// string (the same strings surface in the conformance fixture). The harness
+// asserts them via the per-case `expectedReason`; a future divergence
+// surfaces as a REASON_MISMATCH failure.
+const ORACLE_ERROR_REASON = {
+    stale: 'ORACLE_STALE',
+    missing: 'ORACLE_MISSING',
+    deviation: 'ORACLE_DEVIATION_EXCEEDED',
+    paused: 'ORACLE_PAUSED',
+};
 // Deterministic XLM/USDC adjacency fixture; the shared registry can replace this boundary later.
 const ADJACENT_ASSETS = [
     'CAS3J7GYLGXMF6TDJ5WQ2PEN4GRVNXJUIQ2TZU3ZB3OQ2V4DRCWI7WPF',
     'CCWCLTASNDT57N3BCHOSVB5QWMV5URK4BXLDDF6ZZQYMBQ4OKZA3ZB2N',
 ];
-// Phase 1 property-harness mutation dimensions excluded from the synth pipeline's
+// Property-harness mutation dimensions excluded from the synth pipeline's
 // self-verify call so existing fixtures still emit policies. The harness tests
 // them as FINDINGS against the already-emitted policy.
 const OVERPERMISSIVE_DIMENSIONS = ['argument_reorder'];
 exports.OVERPERMISSIVE_DIMENSIONS = OVERPERMISSIVE_DIMENSIONS;
-// The 15 dimensions the synth pipeline uses for self-verify and minimise.
+// The dimensions the synth pipeline uses for self-verify and minimise. No count
+// is written here on purpose: this comment said 15 while the array held 17, and
+// anyone checking the number should read the array rather than the prose.
 // Phase 1 grammar extension: `vec_append` and `map_field_flip` are listed below
 // alongside the existing dimensions so the per-element binds emitted for
 // Blend `submit` (call_arg_len + 3 call_arg_field per element) survive
@@ -67,7 +80,7 @@ function generateCases(predicate, permitCtx, dimensions) {
             continue;
         const mutated = mutateBigIntRecord(permitCtx, 'amountByToken', comparison.left.token, comparison);
         if (mutated)
-            denies.push({ dimension: 'amount', ctx: mutated });
+            denies.push({ dimension: 'amount', ctx: mutated, expectedReason: 'AMOUNT_BOUND' });
     }
     const movedTokens = new Set();
     for (const comparison of facts.comparisons) {
@@ -76,6 +89,15 @@ function generateCases(predicate, permitCtx, dimensions) {
         }
     }
     for (const token of movedTokens) {
+        // The `asset` deny case mutates BOTH the amount record AND the contract
+        // binding (token's value moved to an adjacent asset; the same swap applied
+        // to any address-typed `call_arg` / `call_contract` literal). The actual
+        // deny reason is therefore predicate-dependent - the order of evaluation
+        // is CONTRACT_SCOPE (step 3) before AMOUNT_BOUND (step 6), so a policy
+        // that has both bindings denies with CONTRACT_SCOPE, while a policy with
+        // only an amount binding denies with AMOUNT_BOUND. The reason assertion
+        // would be brittle here; the boolean decision is what we strictly need
+        // to pin. Leave `expectedReason` unset for this dimension.
         denies.push({ dimension: 'asset', ctx: mutateAsset(predicate, permitCtx, token) });
     }
     const contractConstraints = [
@@ -87,7 +109,7 @@ function generateCases(predicate, permitCtx, dimensions) {
     for (const _constraint of contractConstraints) {
         const ctx = cloneContext(permitCtx);
         ctx.contract = distinctText(permitCtx.contract, 'contract');
-        denies.push({ dimension: 'contract', ctx });
+        denies.push({ dimension: 'contract', ctx, expectedReason: 'CONTRACT_SCOPE' });
     }
     const functionConstraints = [
         ...facts.comparisons.filter((node) => node.op === 'eq' && node.left.kind === 'call_fn' && node.right.kind === 'literal_symbol'),
@@ -96,19 +118,19 @@ function generateCases(predicate, permitCtx, dimensions) {
     for (const _constraint of functionConstraints) {
         const ctx = cloneContext(permitCtx);
         ctx.fn = distinctText(permitCtx.fn, 'function');
-        denies.push({ dimension: 'function', ctx });
+        denies.push({ dimension: 'function', ctx, expectedReason: 'FN_MISMATCH' });
     }
     if (permitCtx.validUntilLedger !== undefined) {
         const ctx = cloneContext(permitCtx);
         ctx.atLedger = permitCtx.validUntilLedger + 1;
-        denies.push({ dimension: 'timing', ctx });
+        denies.push({ dimension: 'timing', ctx, expectedReason: 'EXPIRED' });
     }
     for (const comparison of facts.comparisons) {
         if (comparison.left.kind !== 'window_spent')
             continue;
         const mutated = mutateBigIntRecord(permitCtx, 'windowSpentByToken', comparison.left.token, comparison, false);
         if (mutated)
-            denies.push({ dimension: 'time_window', ctx: mutated });
+            denies.push({ dimension: 'time_window', ctx: mutated, expectedReason: 'AMOUNT_BOUND' });
     }
     for (const comparison of facts.comparisons) {
         if (comparison.left.kind !== 'invocation_count_in_window')
@@ -117,7 +139,7 @@ function generateCases(predicate, permitCtx, dimensions) {
             continue;
         const ctx = cloneContext(permitCtx);
         ctx.invocationCountByWindow[comparison.left.windowSecs] = violatingNumber(comparison.op, comparison.right.value);
-        denies.push({ dimension: 'invocation_count', ctx });
+        denies.push({ dimension: 'invocation_count', ctx, expectedReason: 'FREQUENCY' });
     }
     // Ordered numeric bound on a call_arg (e.g. a SoroSwap input-amount cap
     // `call_arg[0] <= limit`). A violating deny case pushes the arg past the
@@ -132,7 +154,7 @@ function generateCases(predicate, permitCtx, dimensions) {
             continue;
         const ctx = cloneContext(permitCtx);
         ctx.args[comparison.left.index] = violating;
-        denies.push({ dimension: 'arg_amount_bound', ctx });
+        denies.push({ dimension: 'arg_amount_bound', ctx, expectedReason: 'ARG_MISMATCH' });
     }
     const argumentConstraints = [];
     for (const comparison of facts.comparisons) {
@@ -150,6 +172,15 @@ function generateCases(predicate, permitCtx, dimensions) {
     for (const constraint of argumentConstraints) {
         const ctx = cloneContext(permitCtx);
         ctx.args[constraint.index] = { type: 'other', value: 'deny-case-opaque-argument' };
+        // The `arg_bound` case sets the arg to an opaque ScVal. The deny reason
+        // depends on the predicate shape:
+        //   - an `eq(call_arg[i], literal)` denies with ARG_MISMATCH
+        //   - an `in(call_arg[i], [literals])` denies with NOT_IN_ALLOWLIST
+        //     (opaque needles fail-closed at the `in` membership gate, step 5)
+        // Both are correct in the TS evaluator; the reason is predicate-dependent
+        // so we cannot pin a single canonical reason here. The boolean decision
+        // is what we strictly need to assert; the reason is recorded (not asserted)
+        // when the harness runs this case.
         denies.push({ dimension: 'arg_bound', ctx });
     }
     const scopedArgumentIndices = new Set(argumentConstraints.map(({ index }) => index));
@@ -169,6 +200,14 @@ function generateCases(predicate, permitCtx, dimensions) {
         for (const index of scopedArgumentIndices) {
             ctx.args[index] = { type: 'other', value: 'deny-case-authorized-call-argument' };
         }
+        // `scope_contract_fn_arg` changes contract, fn, AND args simultaneously.
+        // The first failing child of the AND decides the reason, and the contract
+        // check (step 3) does fire first in the evaluator. The reason is therefore
+        // CONTRACT_SCOPE for the canonical case, but a predicate that lists the
+        // call_fn leaf first (or that has a `call_arg_field` for that arg index)
+        // can flip the order. Pin the assertion here only when no `in` /
+        // call_arg_field binds the same arg index exist - the canonical blend
+        // case does have those binds, so the assertion would fire there.
         denies.push({ dimension: 'scope_contract_fn_arg', ctx });
     }
     const oracleComparisons = facts.comparisons.filter((node) => node.left.kind === 'oracle_price');
@@ -178,7 +217,7 @@ function generateCases(predicate, permitCtx, dimensions) {
                 continue;
             const ctx = cloneContext(permitCtx);
             ctx.oraclePriceByAsset[comparison.left.asset] = { error };
-            denies.push({ dimension, ctx });
+            denies.push({ dimension, ctx, expectedReason: ORACLE_ERROR_REASON[error] });
         }
     }
     for (const comparison of facts.comparisons) {
@@ -231,10 +270,10 @@ function generateCases(predicate, permitCtx, dimensions) {
             if (sel.kind !== 'call_arg_field')
                 continue;
             const arg = permitCtx.args[sel.index];
-            if (!arg || arg.type !== 'vec')
+            if (arg?.type !== 'vec')
                 continue;
             const element = arg.value[sel.element];
-            if (!element || element.type !== 'map' || !Array.isArray(element.value))
+            if (element?.type !== 'map' || !Array.isArray(element.value))
                 continue;
             const entry = element.value.find((e) => e.key === sel.field);
             if (!entry)
@@ -262,7 +301,7 @@ function generateCases(predicate, permitCtx, dimensions) {
             if (sel.kind !== 'call_arg_len')
                 continue;
             const arg = permitCtx.args[sel.index];
-            if (!arg || arg.type !== 'vec')
+            if (arg?.type !== 'vec')
                 continue;
             const ctx = cloneContext(permitCtx);
             ctx.args[sel.index] = {