@crediolabs/policy-synth 0.1.17 → 0.2.0

package/dist/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/synth/deny-cases.js

@@ -6,16 +6,29 @@ 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'];
-// 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
@@ -61,7 +74,7 @@ export 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) {
@@ -70,6 +83,15 @@ export 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 = [
@@ -81,7 +103,7 @@ export 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'),
@@ -90,19 +112,19 @@ export 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')
@@ -111,7 +133,7 @@ export 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
@@ -126,7 +148,7 @@ export 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) {
@@ -144,6 +166,15 @@ export 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));
@@ -163,6 +194,14 @@ export 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');
@@ -172,7 +211,7 @@ export 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) {
@@ -225,10 +264,10 @@ export 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)
@@ -256,7 +295,7 @@ export 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] = {

package/dist/synth/evaluate.js

@@ -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 { literalNumericBigInt } from "./predicate-literals.js";
 /** Oracle prices normalise to this many decimals; mirrors NORMALISED_DECIMALS
  *  in oracle.rs. A threshold on any other basis must say so. */
@@ -35,8 +25,8 @@ const NORMALISED_DECIMALS = 9;
 /** Mirrors MAX_ORACLE_THRESHOLD_DECIMALS in dsl.rs. */
 const MAX_ORACLE_THRESHOLD_DECIMALS = 18;
 /** 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 {
     code;
     constructor(code) {
@@ -90,12 +80,9 @@ function walk(node, ctx) {
             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 };
@@ -111,11 +98,9 @@ function walk(node, ctx) {
             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' };
@@ -136,17 +121,14 @@ function evalCompare(op, left, right, ctx) {
     // --- 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 };
@@ -178,11 +160,6 @@ function evalCompare(op, left, right, ctx) {
             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);
@@ -192,11 +169,11 @@ function evalCompare(op, left, right, ctx) {
     if (left.kind === 'call_arg_scaled') {
         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')
+        if (actual?.type !== 'vec')
             return { permit: false, reason: 'ARG_MISMATCH' };
         if (right.kind !== 'literal_u32')
             return { permit: false, reason: 'ARG_MISMATCH' };
@@ -204,16 +181,14 @@ function evalCompare(op, left, right, ctx) {
             ? { 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')
+        if (actual?.type !== 'vec')
             return { permit: false, reason: 'ARG_MISMATCH' };
         const element = actual.value[left.element];
-        if (!element || element.type !== 'map')
+        if (element?.type !== 'map')
             return { permit: false, reason: 'ARG_MISMATCH' };
         if (!Array.isArray(element.value))
             return { permit: false, reason: 'ARG_MISMATCH' };
@@ -226,7 +201,7 @@ function evalCompare(op, left, right, ctx) {
     }
     // --- 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);
@@ -247,7 +222,7 @@ function evalCompare(op, left, right, ctx) {
  *  sequence: compare element-by-element in order; deny if length or any
  *  element differs. Opaque args (`type: 'other'`) fail closed. */
 function evalArgEq(op, actual, right, ctx) {
-    // 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' };
@@ -255,7 +230,6 @@ function evalArgEq(op, actual, right, ctx) {
             ? { permit: true }
             : { 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' };
@@ -265,7 +239,6 @@ function evalArgEq(op, actual, right, ctx) {
             ? { permit: true }
             : { 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' };
@@ -273,7 +246,6 @@ function evalArgEq(op, actual, right, ctx) {
             ? { permit: true }
             : { 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' };
@@ -281,7 +253,6 @@ function evalArgEq(op, actual, right, ctx) {
             ? { permit: true }
             : { 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' };
@@ -289,7 +260,6 @@ function evalArgEq(op, actual, right, ctx) {
             ? { permit: true }
             : { 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' };
@@ -297,7 +267,6 @@ function evalArgEq(op, actual, right, ctx) {
             ? { permit: true }
             : { 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' };
@@ -310,20 +279,14 @@ function evalArgEq(op, actual, right, ctx) {
         return { permit: false, reason: 'ARG_MISMATCH' };
     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, left, right, ctx) {
-    // Identify which side is scaled, and pull the other side as a number.
     let scaled;
     let other;
     let scaledOnRight;
@@ -338,14 +301,12 @@ function evalScaledArgCompare(op, left, right, ctx) {
         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' };
     }
@@ -362,16 +323,11 @@ function evalScaledArgCompare(op, left, right, ctx) {
         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;
     try {
         // BigInt division truncates toward zero (matches Rust `i128::checked_div`).
@@ -380,18 +336,13 @@ function evalScaledArgCompare(op, left, right, ctx) {
     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;
     if (other.kind === 'call_arg') {
         otherVal = argNumericBigInt(ctx.args[other.index]);
@@ -459,7 +410,6 @@ function compareVecExact(actual, expected, ctx) {
 function evalIn(needle, haystack, ctx) {
     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' };
@@ -486,10 +436,10 @@ function resolveLeaf(leaf, ctx) {
             return undefined;
         case 'call_arg_field': {
             const actual = ctx.args[leaf.index];
-            if (!actual || actual.type !== 'vec')
+            if (actual?.type !== 'vec')
                 return undefined;
             const element = actual.value[leaf.element];
-            if (!element || element.type !== 'map')
+            if (element?.type !== 'map')
                 return undefined;
             if (!Array.isArray(element.value))
                 return undefined;
@@ -520,25 +470,21 @@ function resolveLeaf(leaf, ctx) {
             return undefined;
     }
 }
-/** Step 6: amount compare on BigInt. */
-function evalAmountCompare(op, token, right, ctx) {
+/** 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, token, right, ctx, record) {
     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' };
 }
 /** Step 6: window_spent compare on BigInt. */
 function evalWindowSpentCompare(op, token, right, ctx) {
-    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. */
 function evalFrequencyCompare(op, windowSecs, right, ctx) {
@@ -562,24 +508,28 @@ function evalOracleCompare(op, asset, right, ctx) {
         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
  *  equal checks), but the dedicated arg path uses it via `BigInt(actual) === BigInt(right)`. */

package/dist/synth/harness.d.ts

@@ -5,6 +5,13 @@ 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;
@@ -12,5 +19,10 @@ export type HarnessResult = {
     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 declare function runHarness(predicate: PredicateNode, cases: GeneratedCases): HarnessResult;

package/dist/synth/harness.js

@@ -1,5 +1,10 @@
 import { evaluate } from "./evaluate.js";
-/** 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, cases) {
     const failures = [];
     const permitResult = evaluate(predicate, cases.permit);
@@ -20,6 +25,22 @@ export function runHarness(predicate, cases) {
                 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,
+            });
         }
     }
     return failures.length === 0 ? { ok: true } : { ok: false, failures };

package/dist/synth/index.d.ts

@@ -7,4 +7,4 @@ export { type IntentFacts, lower } from './lower.ts';
 export { minimize } from './minimize.ts';
 export { type DecideScopeOptions, decideScope, type ScopeDecision, scopeToContextRuleType, } from './scope.ts';
 export { synthesizeFromMandate } from './synthesize-from-mandate.ts';
-export { type SynthesizeFromRecordingOptions, synthesizeFromRecording, } from './synthesize-from-recording.ts';
+export { type __TestInterpreterAdapterOptions, type SynthesizeFromRecordingOptions, synthesizeFromRecording, } from './synthesize-from-recording.ts';