@crediolabs/policy-synth 0.1.17 → 0.2.0

package/src/synth/deny-cases.ts

@@ -6,6 +6,11 @@ import { literalNumericBigInt } from './predicate-literals.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 {
@@ -39,18 +44,32 @@ const ORACLE_CASES = [
   ['oracle_paused', 'paused'],
 ] as const
 
+// 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: Record<(typeof ORACLE_CASES)[number][1], string> = {
+  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',
 ] as const
 
-// 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'] as const
 
-// 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
@@ -106,7 +125,7 @@ export function generateCases(
       comparison.left.token,
       comparison
     )
-    if (mutated) denies.push({ dimension: 'amount', ctx: mutated })
+    if (mutated) denies.push({ dimension: 'amount', ctx: mutated, expectedReason: 'AMOUNT_BOUND' })
   }
 
   const movedTokens = new Set<string>()
@@ -116,6 +135,15 @@ export function generateCases(
     }
   }
   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) })
   }
 
@@ -131,7 +159,7 @@ export function generateCases(
   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 = [
@@ -144,13 +172,13 @@ export function generateCases(
   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) {
@@ -162,7 +190,8 @@ export function generateCases(
       comparison,
       false
     )
-    if (mutated) denies.push({ dimension: 'time_window', ctx: mutated })
+    if (mutated)
+      denies.push({ dimension: 'time_window', ctx: mutated, expectedReason: 'AMOUNT_BOUND' })
   }
 
   for (const comparison of facts.comparisons) {
@@ -173,7 +202,7 @@ export function generateCases(
       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
@@ -187,7 +216,7 @@ export function generateCases(
     if (!violating) 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: Array<{ index: number }> = []
@@ -208,6 +237,15 @@ export function generateCases(
   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 })
   }
 
@@ -232,6 +270,14 @@ export function generateCases(
     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 })
   }
 
@@ -241,7 +287,7 @@ export function generateCases(
       if (comparison.left.kind !== 'oracle_price') continue
       const ctx = cloneContext(permitCtx)
       ctx.oraclePriceByAsset[comparison.left.asset] = { error }
-      denies.push({ dimension, ctx })
+      denies.push({ dimension, ctx, expectedReason: ORACLE_ERROR_REASON[error] })
     }
   }
 
@@ -298,9 +344,9 @@ export function generateCases(
       const sel = comparison.left
       if (sel.kind !== 'call_arg_field') continue
       const arg = permitCtx.args[sel.index]
-      if (!arg || arg.type !== 'vec') continue
+      if (arg?.type !== 'vec') continue
       const element = arg.value[sel.element]
-      if (!element || element.type !== 'map' || !Array.isArray(element.value)) continue
+      if (element?.type !== 'map' || !Array.isArray(element.value)) continue
       const entry = element.value.find((e) => e.key === sel.field)
       if (!entry) continue
       const flipped = flipFieldValue(entry.val)
@@ -326,7 +372,7 @@ export function generateCases(
       const sel = comparison.left
       if (sel.kind !== 'call_arg_len') continue
       const arg = permitCtx.args[sel.index]
-      if (!arg || arg.type !== 'vec') continue
+      if (arg?.type !== 'vec') continue
       const ctx = cloneContext(permitCtx)
       ctx.args[sel.index] = {
         type: 'vec',

package/src/synth/evaluate.ts

@@ -1,33 +1,23 @@
-// src/synth/evaluate.ts - the model evaluator.
+// src/synth/evaluate.ts - the model evaluator (TS model of interpreter semantics).
 //
-// Pure function. The single semantic evaluator every deny-case runs through
-// (TS model of the interpreter's semantics; real-semantics wiring is Phase 03).
-// Determinism: same `(predicate, ctx)` -> byte-identical result, no clock, no
-// randomness.
+// Pure function. Determinism: same `(predicate, ctx)` -> byte-identical result,
+// no clock, no randomness. Deny order (deny on FIRST violation, stable reason):
+//   1. ledger expiry                                         -> 'EXPIRED'
+//   2. `now` past valid_until                                 -> 'EXPIRED'
+//   3. contract mismatch                                     -> 'CONTRACT_SCOPE'
+//   4. per-ScVal equality on fn/args; EXACT ordered vector
+//      equality; fail-closed on opaque args                   -> 'ARG_MISMATCH' / 'FN_MISMATCH'
+//   5. `in` membership; empty haystack ALWAYS denies         -> 'NOT_IN_ALLOWLIST'
+//   6. amount / window_spent via BigInt                       -> 'AMOUNT_BOUND'
+//   7. invocation_count_in_window                            -> 'FREQUENCY'
+//   8. oracle_price: fatal -> throw OracleError, deny with
+//      underlying ORACLE_* reason                             -> 'ORACLE_*'
+//   9. boolean nodes (and/or/not)
+//  10. signer threshold gate                                  -> 'THRESHOLD_NOT_MET'
+//  11. otherwise permit.
 //
-// Deny order (deny on FIRST violation, stable `reason` string):
-//   1. `atLedger > validUntilLedger` (when set)                 -> 'EXPIRED'
-//   2. a `now` leaf compared past `valid_until` semantics        -> 'EXPIRED'
-//   3. a `call_contract` eq whose literal != ctx.contract       -> 'CONTRACT_SCOPE'
-//   4. per-ScVal equality on `call_fn` / `call_arg[i]`;
-//      `eq(selector, literal_vec)` = EXACT ordered vector equality
-//      (compare element-by-element, deny if length or any differs);
-//      fail-closed on opaque/undecodable args                   -> 'ARG_MISMATCH' / 'FN_MISMATCH'
-//   5. `in` membership: needle NOT in haystack; an EMPTY
-//      haystack ALWAYS denies                                   -> 'NOT_IN_ALLOWLIST'
-//   6. amount / window_spent comparisons via BigInt             -> 'AMOUNT_BOUND'
-//   7. `invocation_count_in_window` compare                     -> 'FREQUENCY'
-//   8. `oracle_price`: missing/stale/deviation/etc. is FATAL -
-//      throw `OracleError`, catch at the top, deny with the
-//      underlying `ORACLE_*` reason                             -> 'ORACLE_*'
-//   9. boolean nodes: `and` = all children permit;
-//      `or` = any child permits; `not` = invert a non-oracle child
-//   10. signer threshold gate (when `signerWeights` provided,
-//       no positive-weight signer -> deny 'THRESHOLD_NOT_MET')
-//   11. otherwise `{ permit: true }`.
-//
-// Amounts: BigInt on decimal strings (never JS `number`). Oracle errors
-// modelled by throwing (never a boolean-false that `not`/`or` could mask).
+// Amounts: BigInt on decimal strings. Oracle errors thrown (never
+// boolean-false `not`/`or` could mask).
 
 import type { PredicateLeaf, PredicateNode, ScVal } from '../types.ts'
 import { literalNumericBigInt } from './predicate-literals.ts'
@@ -70,8 +60,8 @@ export interface EvalContext {
 export type EvalResult = { permit: true } | { permit: false; reason: string }
 
 /** Internal fatal thrown by the oracle path; caught at the top of `evaluate`
- *  and converted to the matching `ORACLE_*` deny reason. NOT a
- *  boolean-false that `not` / `or` could mask. */
+ *  and converted to the matching `ORACLE_*` deny reason. NOT a boolean-false
+ *  that `not` / `or` could mask. */
 class OracleError extends Error {
   readonly code: string
   constructor(code: string) {
@@ -129,12 +119,9 @@ function walk(node: PredicateNode, ctx: EvalContext): EvalResult {
       for (const child of node.children) {
         const r = walk(child, ctx)
         if (!r.permit) {
-          // deny-on-first: short-circuit. The "active branch" is the failing
-          // child, so the reason we surface is from that child.
+          // deny-on-first: short-circuit on the failing child.
           return r
         }
-        // keep a reference to the last permit so unused-variable analysis
-        // doesn't complain; this is purely structural.
         lastDeny = r
       }
       return lastDeny ?? { permit: true }
@@ -149,11 +136,9 @@ function walk(node: PredicateNode, ctx: EvalContext): EvalResult {
       return lastDeny ?? { permit: false, reason: 'NOT_IN_ALLOWLIST' }
     }
     case 'not': {
-      // `not` structurally inverts the child UNLESS the child contains an
-      // oracle leaf (compile-time rule: no oracle leaf under not/or). Here we
-      // walk the child; if it throws `OracleError`, the catch at the top of
-      // `evaluate` re-throws and surfaces the ORACLE_* deny. A non-oracle
-      // deny is inverted to a permit, and a permit is inverted to a deny.
+      // `not` structurally inverts the child unless the child contains an
+      // oracle leaf (compile-time rule: no oracle leaf under not/or). A
+      // child `OracleError` is re-thrown to the catch at the top of `evaluate`.
       const r = walk(node.child, ctx)
       if (r.permit) return { permit: false, reason: 'FN_MISMATCH' }
       return { permit: true }
@@ -179,15 +164,12 @@ function evalCompare(
   // --- step 2: `now` vs `valid_until` semantics ---
   if (left.kind === 'now' && right.kind === 'valid_until') {
     const expired = op === 'gt' || op === 'gte' ? ctx.nowSeconds >= 0 : ctx.nowSeconds < 0
-    // only `gt` / `gte` / `lt` / `lte` are meaningful here. Treat `eq` /
-    // any other combo as: "expired iff nowSeconds > validUntilSeconds".
-    // We model `valid_until` as a synthetic future timestamp far past
-    // `nowSeconds` so the only true-positive expired path is the
-    // `gt`/`gte` shapes callers actually write.
+    // `valid_until` is modelled as a synthetic future timestamp far past
+    // `nowSeconds` so the only true-positive expired path is the `gt`/`gte`
+    // shapes callers actually write.
     if (op === 'gt' || op === 'gte') {
       if (ctx.nowSeconds > 0) return { permit: false, reason: 'EXPIRED' }
     } else if (op === 'lt' || op === 'lte') {
-      // permits when valid_until is in the future
       return { permit: true }
     }
     return expired ? { permit: false, reason: 'EXPIRED' } : { permit: true }
@@ -220,11 +202,6 @@ function evalCompare(
       return evalScaledArgCompare(op, left, right, ctx)
     }
     const actual = ctx.args[left.index]
-    // An ordered comparison (lt/lte/gt/gte) reads the arg as an integer and
-    // compares it to a numeric literal via BigInt (e.g. a SoroSwap input-amount
-    // cap `call_arg[0] <= limit`). The per-ScVal-type equality semantics live
-    // in evalArgEq (`eq` only); ordered ops are numeric-only and fail closed on
-    // a non-numeric arg or literal.
     if (op !== 'eq') return evalArgOrderedCompare(op, actual, right)
     return evalArgEq(op, actual, right, ctx)
   }
@@ -235,26 +212,24 @@ function evalCompare(
     return evalScaledArgCompare(op, right, left, ctx)
   }
 
-  // --- step 4c: call_arg_len: the length of a vec-typed argument as a u32.
-  // Fails closed on a non-vec arg, an absent arg, or a non-u32 literal.
+  // --- step 4c: call_arg_len: length of a vec-typed argument as u32.
+  // Fails closed on a non-vec / absent arg or a non-u32 literal.
   if (left.kind === 'call_arg_len') {
     const actual = ctx.args[left.index]
-    if (!actual || actual.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
+    if (actual?.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
     if (right.kind !== 'literal_u32') return { permit: false, reason: 'ARG_MISMATCH' }
     return actual.value.length === right.value
       ? { permit: true }
       : { permit: false, reason: 'ARG_MISMATCH' }
   }
 
-  // --- step 4d: call_arg_field: the value of a field in the map at element i
-  // of the vec at argument index. Fails closed on a non-vec arg, an
-  // out-of-range element, a missing field, a non-map element, or a type
-  // mismatch between the field ScVal and the literal leaf.
+  // --- step 4d: call_arg_field: value of a field in the map at element i of
+  // the vec at argument index. Fails closed on shape / type / range issues.
   if (left.kind === 'call_arg_field') {
     const actual = ctx.args[left.index]
-    if (!actual || actual.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
+    if (actual?.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
     const element = actual.value[left.element]
-    if (!element || element.type !== 'map') return { permit: false, reason: 'ARG_MISMATCH' }
+    if (element?.type !== 'map') return { permit: false, reason: 'ARG_MISMATCH' }
     if (!Array.isArray(element.value)) return { permit: false, reason: 'ARG_MISMATCH' }
     const entry = element.value.find((e) => e.key === left.field)
     if (!entry) return { permit: false, reason: 'ARG_MISMATCH' }
@@ -264,7 +239,7 @@ function evalCompare(
 
   // --- step 6: AMOUNT_BOUND ---
   if (left.kind === 'amount' && op !== 'eq') {
-    return evalAmountCompare(op, left.token, right, ctx)
+    return evalAmountCompare(op, left.token, right, ctx, 'amountByToken')
   }
   if (left.kind === 'window_spent' && op !== 'eq') {
     return evalWindowSpentCompare(op, left.token, right, ctx)
@@ -294,7 +269,7 @@ function evalArgEq(
   right: PredicateLeaf,
   ctx: EvalContext
 ): EvalResult {
-  // eq(call_arg[i], literal_vec) -> EXACT ordered vector equality
+  // eq(call_arg[i], literal_vec) -> EXACT ordered vector equality.
   if (op === 'eq' && right.kind === 'literal_vec') {
     if (actual?.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
     return compareVecExact(actual.value, right.elements, ctx)
@@ -302,7 +277,6 @@ function evalArgEq(
       : { permit: false, reason: 'ARG_MISMATCH' }
   }
 
-  // eq(call_arg[i], literal_address) -> address compare
   if (op === 'eq' && right.kind === 'literal_address') {
     if (!actual) return { permit: false, reason: 'ARG_MISMATCH' }
     if (actual.type === 'other') return { permit: false, reason: 'ARG_MISMATCH' }
@@ -311,7 +285,6 @@ function evalArgEq(
       : { permit: false, reason: 'ARG_MISMATCH' }
   }
 
-  // eq(call_arg[i], literal_i128) -> BigInt compare
   if (op === 'eq' && right.kind === 'literal_i128') {
     if (actual?.type !== 'i128') return { permit: false, reason: 'ARG_MISMATCH' }
     return BigInt(actual.value) === BigInt(right.value)
@@ -319,7 +292,6 @@ function evalArgEq(
       : { permit: false, reason: 'ARG_MISMATCH' }
   }
 
-  // eq(call_arg[i], literal_symbol)
   if (op === 'eq' && right.kind === 'literal_symbol') {
     if (!actual) return { permit: false, reason: 'ARG_MISMATCH' }
     return actual.type === 'symbol' && actual.value === right.value
@@ -327,7 +299,6 @@ function evalArgEq(
       : { permit: false, reason: 'ARG_MISMATCH' }
   }
 
-  // eq(call_arg[i], literal_u32)
   if (op === 'eq' && right.kind === 'literal_u32') {
     if (!actual) return { permit: false, reason: 'ARG_MISMATCH' }
     return actual.type === 'u32' && actual.value === String(right.value)
@@ -335,7 +306,6 @@ function evalArgEq(
       : { permit: false, reason: 'ARG_MISMATCH' }
   }
 
-  // eq(call_arg[i], literal_u64)
   if (op === 'eq' && right.kind === 'literal_u64') {
     if (!actual) return { permit: false, reason: 'ARG_MISMATCH' }
     return actual.type === 'u64' && actual.value === right.value
@@ -343,7 +313,6 @@ function evalArgEq(
       : { permit: false, reason: 'ARG_MISMATCH' }
   }
 
-  // eq(call_arg[i], literal_bytes)
   if (op === 'eq' && right.kind === 'literal_bytes') {
     if (!actual) return { permit: false, reason: 'ARG_MISMATCH' }
     return actual.type === 'bytes' && actual.value === right.value
@@ -356,25 +325,19 @@ function evalArgEq(
   return { permit: false, reason: 'ARG_MISMATCH' }
 }
 
-/** Step 4b': slippage-floor comparison. Mirrors the Rust `eval_scaled_arg_compare`
- *  path: the scaled leaf is `args[index] * num / den` (truncating toward
- *  zero). On `checked_mul` / `checked_div` failure (overflow or
- *  divide-by-zero) the comparison denies with `ARITHMETIC_OVERFLOW`. A
- *  failed comparison denies with `SLIPPAGE_FLOOR` (the dedicated reason)
- *  rather than the generic `ARG_MISMATCH`.
- *
- *  `left` is whichever side of the compare is NOT the scaled leaf. A
- *  scaled-on-scaled compare denies `ARG_MISMATCH` (pipelining two scaled
- *  leaves has no definable semantics). The other operand must be a
- *  numeric shape (`call_arg` carrying a number, or a numeric literal);
- *  anything else is `ARG_MISMATCH`. */
+/** Step 4b': slippage-floor comparison. Mirrors the Rust `eval_scaled_arg_compare`:
+ *  the scaled leaf is `args[index] * num / den` (truncating toward zero). On
+ *  overflow or divide-by-zero deny with `ARITHMETIC_OVERFLOW`; a failed bound
+ *  denies with `SLIPPAGE_FLOOR` (the dedicated reason) rather than the generic
+ *  `ARG_MISMATCH`. A scaled-on-scaled compare denies `ARG_MISMATCH`
+ *  (no definable semantics). The non-scaled operand must be numeric
+ *  (`call_arg` carrying a number, or a numeric literal); else `ARG_MISMATCH`. */
 function evalScaledArgCompare(
   op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte',
   left: PredicateLeaf,
   right: PredicateLeaf,
   ctx: EvalContext
 ): EvalResult {
-  // Identify which side is scaled, and pull the other side as a number.
   let scaled: { index: number; num: string; den: string }
   let other: PredicateLeaf
   let scaledOnRight: boolean
@@ -387,14 +350,12 @@ function evalScaledArgCompare(
     other = left
     scaledOnRight = true
   } else {
-    // Neither side is scaled - this is a programming error in the
-    // dispatcher; the contract returns ARG_MISMATCH to fail closed.
+    // Programming error in the dispatcher; fail closed.
     return { permit: false, reason: 'ARG_MISMATCH' }
   }
-  // Source `args[index]` -> BigInt. An out-of-bounds index or a
-  // non-numeric arg fails closed as ARG_MISMATCH (not SLIPPAGE_FLOOR) -
-  // a violated floor is the wrong code when the operand itself could
-  // not be read.
+  // Out-of-bounds or non-numeric arg fails closed as ARG_MISMATCH (not
+  // SLIPPAGE_FLOOR) - a violated floor is the wrong code when the operand
+  // itself could not be read.
   if (scaled.index >= ctx.args.length) {
     return { permit: false, reason: 'ARG_MISMATCH' }
   }
@@ -409,15 +370,10 @@ function evalScaledArgCompare(
     return { permit: false, reason: 'ARG_MISMATCH' }
   }
   // Install refuses `den == 0` and `num <= 0` / `den <= 0`. The runtime
-  // check is a defensive belt-and-braces - a future validator
-  // regression cannot panic the frame on a divide-by-zero.
+  // check is defensive belt-and-braces so a validator regression cannot
+  // panic the frame on a divide-by-zero.
   if (den === 0n) return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
   const product = input * num
-  // BigInt overflow is silent in JS (it does not throw on multiplication).
-  // We can detect over-range by dividing and checking the result against
-  // i128 bounds, but the more practical check is whether the result
-  // divides cleanly. We rely on BigInt's arbitrary precision and then
-  // surface ARITHMETIC_OVERFLOW if the result is outside i128.
   let scaledValue: bigint
   try {
     // BigInt division truncates toward zero (matches Rust `i128::checked_div`).
@@ -425,18 +381,13 @@ function evalScaledArgCompare(
   } catch {
     return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
   }
-  // i128 range check: if the scaled value is outside i128, the contract
-  // would have wrapped on i128 arithmetic; surface the same deny.
+  // i128 range check: the contract would have wrapped on i128 arithmetic;
+  // surface the same deny.
   const I128_MAX = (1n << 127n) - 1n
   const I128_MIN = -(1n << 127n)
   if (scaledValue > I128_MAX || scaledValue < I128_MIN) {
     return { permit: false, reason: 'ARITHMETIC_OVERFLOW' }
   }
-  // Resolving the operand when the scaled side is on the right: the
-  // operand is `left`; the scaled value is the RHS. The AST order is
-  // `left <op> scaled`, so the comparator applies to `other <op> scaled`.
-  // When the scaled side is on the left, the order is `scaled <op> other`,
-  // i.e. `scaled <op> other_val`.
   let otherVal: bigint | null
   if (other.kind === 'call_arg') {
     otherVal = argNumericBigInt(ctx.args[other.index])
@@ -504,7 +455,6 @@ function compareVecExact(actual: ScVal[], expected: PredicateLeaf[], ctx: EvalCo
  *  fails closed. */
 function evalIn(needle: PredicateLeaf, haystack: PredicateLeaf[], ctx: EvalContext): EvalResult {
   if (haystack.length === 0) return { permit: false, reason: 'NOT_IN_ALLOWLIST' }
-  // Resolve the needle's ScVal against the candidate call.
   const actual = resolveLeaf(needle, ctx)
   if (!actual || actual.type === 'other') return { permit: false, reason: 'NOT_IN_ALLOWLIST' }
   for (const h of haystack) {
@@ -530,9 +480,9 @@ function resolveLeaf(leaf: PredicateLeaf, ctx: EvalContext): ScVal | undefined {
       return undefined
     case 'call_arg_field': {
       const actual = ctx.args[leaf.index]
-      if (!actual || actual.type !== 'vec') return undefined
+      if (actual?.type !== 'vec') return undefined
       const element = actual.value[leaf.element]
-      if (!element || element.type !== 'map') return undefined
+      if (element?.type !== 'map') return undefined
       if (!Array.isArray(element.value)) return undefined
       const entry = element.value.find((e) => e.key === leaf.field)
       return entry ? entry.val : undefined
@@ -562,16 +512,19 @@ function resolveLeaf(leaf: PredicateLeaf, ctx: EvalContext): ScVal | undefined {
   }
 }
 
-/** Step 6: amount compare on BigInt. */
+/** Step 6: amount / window_spent compare on BigInt. Both leaves compare a
+ *  per-token BigInt record (current vs. rolling) to an i128 literal; the
+ *  compare + denial reason are identical, so a single helper handles both. */
 function evalAmountCompare(
   op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte',
   token: string,
   right: PredicateLeaf,
-  ctx: EvalContext
+  ctx: EvalContext,
+  record: 'amountByToken' | 'windowSpentByToken'
 ): EvalResult {
   const literal = right.kind === 'literal_i128' ? right.value : null
   if (literal === null) return { permit: false, reason: 'AMOUNT_BOUND' }
-  const actual = ctx.amountByToken[token] ?? '0'
+  const actual = ctx[record][token] ?? '0'
   return bigintCmp(op, actual, literal)
     ? { permit: true }
     : { permit: false, reason: 'AMOUNT_BOUND' }
@@ -584,12 +537,7 @@ function evalWindowSpentCompare(
   right: PredicateLeaf,
   ctx: EvalContext
 ): EvalResult {
-  const literal = right.kind === 'literal_i128' ? right.value : null
-  if (literal === null) return { permit: false, reason: 'AMOUNT_BOUND' }
-  const actual = ctx.windowSpentByToken[token] ?? '0'
-  return bigintCmp(op, actual, literal)
-    ? { permit: true }
-    : { permit: false, reason: 'AMOUNT_BOUND' }
+  return evalAmountCompare(op, token, right, ctx, 'windowSpentByToken')
 }
 
 /** Step 7: invocation_count_in_window compare. */
@@ -622,23 +570,27 @@ function evalOracleCompare(
     throw new OracleError(mapped)
   }
   // Mirrors eval_oracle_compare in dsl.rs. The threshold MUST declare its
-  // decimal basis: prices are on the normalised 9-dp basis, and assuming a
-  // bare literal shares it is what let a raw 14-dp threshold permit
-  // everything. A bare literal is refused rather than assumed.
+  // decimal basis: prices are on the normalised 9-dp basis, and a bare literal
+  // is refused (not assumed) because a raw 14-dp threshold that assumed the
+  // 9-dp basis would permit everything.
   if (right.kind !== 'oracle_threshold') throw new OracleError('ORACLE_DECIMALS_MISMATCH')
   if (right.decimals > MAX_ORACLE_THRESHOLD_DECIMALS) {
     throw new OracleError('ORACLE_THRESHOLD_DECIMALS_OUT_OF_RANGE')
   }
-  // Scale BOTH sides up to the wider basis rather than dividing the threshold
-  // down: dividing truncates, and a truncated bound moves the permit boundary.
+  // Scale BOTH sides up to the wider basis; dividing the threshold down
+  // truncates and moves the permit boundary.
   const decimals = BigInt(right.decimals)
   const normalised = BigInt(NORMALISED_DECIMALS)
   const common = decimals > normalised ? decimals : normalised
   const priceScaled = BigInt(entry.price) * 10n ** (common - normalised)
   const literalScaled = BigInt(right.value) * 10n ** (common - decimals)
+  // A violated oracle threshold is a stateful bound (Rust dsl.rs:276 returns
+  // `DenyReason::StatefulBound`, deny code #104). The TS evaluator must mirror
+  // the same reason so a future TS/Rust reason divergence fails CI; the
+  // cross-layer harness in this file now asserts reason codes match.
   return bigintCmp(op, String(priceScaled), String(literalScaled))
     ? { permit: true }
-    : { permit: false, reason: 'FN_MISMATCH' }
+    : { permit: false, reason: 'STATEFUL_BOUND' }
 }
 
 /** BigInt compare helper. `eq` is also supported by callers (selector-vs-literal

package/src/synth/harness.ts

@@ -7,11 +7,23 @@ export interface HarnessFailure {
   expected: 'permit' | 'deny'
   got: 'permit' | 'deny'
   reason?: string
+  /** When `expectedReason` is set on the deny case and the case actually
+   *  denies, this carries the canonical reason the TS evaluator MUST emit
+   *  to stay in lockstep with the Rust interpreter (the cross-layer
+   *  reason-code contract). A future TS/Rust reason divergence surfaces
+   *  here in CI. */
+  expectedReason?: string
+  actualReason?: string
 }
 
 export type HarnessResult = { ok: true } | { ok: false; failures: HarnessFailure[] }
 
-/** Evaluate the intended call and every generated denial without side effects. */
+/** Evaluate the intended call and every generated denial without side effects.
+ *  Asserts both the boolean decision AND, for deny cases that carry an
+ *  `expectedReason`, the concrete reason the TS evaluator emits. The reason
+ *  is what the Rust interpreter returns; the cross-layer conformance test in
+ *  `contracts/policy-interpreter/tests/conformance` mirrors the same contract
+ *  for the verifyLive path. */
 export function runHarness(predicate: PredicateNode, cases: GeneratedCases): HarnessResult {
   const failures: HarnessFailure[] = []
   const permitResult = evaluate(predicate, cases.permit)
@@ -33,6 +45,22 @@ export function runHarness(predicate: PredicateNode, cases: GeneratedCases): Har
         got: 'permit',
         reason: 'DENY_CASE_FAILURE',
       })
+      continue
+    }
+    // Reason-code assertion (cross-layer contract). When a deny case carries
+    // an expected reason, the TS evaluator MUST emit that exact string; a
+    // divergence means the TS model and the Rust interpreter disagree on
+    // what the user sees in CI - the harness fails so the diff is visible
+    // here, not at runtime in production.
+    if (deny.expectedReason !== undefined && result.reason !== deny.expectedReason) {
+      failures.push({
+        dimension: deny.dimension,
+        expected: 'deny',
+        got: 'deny',
+        reason: 'REASON_MISMATCH',
+        expectedReason: deny.expectedReason,
+        actualReason: result.reason,
+      })
     }
   }
 

package/src/synth/index.ts

@@ -30,6 +30,7 @@ export {
 } from './scope.ts'
 export { synthesizeFromMandate } from './synthesize-from-mandate.ts'
 export {
+  type __TestInterpreterAdapterOptions,
   type SynthesizeFromRecordingOptions,
   synthesizeFromRecording,
 } from './synthesize-from-recording.ts'