@crediolabs/policy-synth 0.1.16 → 0.1.18

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';

package/dist/synth/synthesize-from-recording.d.ts

@@ -20,21 +20,18 @@ export interface InterpreterAdapterOptions {
         maxStalenessSeconds?: number;
         maxDeviationBps?: number;
     };
-    /** @internal Test-only seam. When set, the orchestrator uses this
-     *  PredicateNode as the starting point for self-verify + minimise instead
-     *  of calling the interpreter adapter's compile(). Production callers MUST
-     *  NOT set this; the field exists so the self-verify pipeline can be
-     *  exercised on hand-crafted predicates (redundant conjuncts for
-     *  minimise, deliberately over-broad leaves for DENY_CASE_FAILURE). The
-     *  `smartAccountAddress` + `installNonce` + `oracleParams` are still
-     *  carried through so the emitted PolicyRef + PolicyDocument match the
-     *  recorded call shape. */
-    __testPredicateNode?: PredicateNode;
 }
-/** Top-level orchestrator inputs. `userResponses` carries the LLM-collected
- *  answers to the ambiguity prompts (windowSeconds, validUntilLedger,
- *  limitAmount, invocationLimit, oraclePriceBound, swapRecipientAllowlist).
- *  `interpreter` opts the recording path into the interpreter adapter. */
+/** PRIVATE test-only extension of `InterpreterAdapterOptions` for the
+ *  `__testPredicateNode` seam. Exported under a `__` prefix so production
+ *  callers can grep for it and see it is a test hook. The seam is read in
+ *  `synthesizeFromRecordingInner` only when `process.env.NODE_ENV === 'test'`
+ *  - a hard RUNTIME guard throws otherwise so a misconfigured production
+ *  caller cannot bypass the recording -> interpreter adapter compile path. */
+export type __TestInterpreterAdapterOptions = InterpreterAdapterOptions & {
+    /** @internal Test-only seam. Throws at runtime when NODE_ENV !== 'test'. */
+    __testPredicateNode?: PredicateNode;
+};
+/** Top-level orchestrator inputs. */
 export interface SynthesizeFromRecordingOptions {
     network: Network;
     userResponses?: ComposeUserResponses;
@@ -42,13 +39,8 @@ export interface SynthesizeFromRecordingOptions {
         threshold: number;
     };
     interpreter?: InterpreterAdapterOptions;
-    /** --explain opt-in. When true, the orchestrator attaches the
-     *  in-memory `PredicateNode` + the corresponding `SimulationResult`
-     *  to the success envelope so the CLI can render a human-readable
-     *  review card. Absent or false -> the success envelope is unchanged
-     *  (byte-identical to today). The flag is ADDITIVE: the existing
-     *  ProposedPolicy fields (encodedPredicate, predicateHash, etc.) are
-     *  never altered by enabling explain. */
+    /** --explain opt-in. The flag is ADDITIVE: existing ProposedPolicy fields are
+     *  never altered by enabling explain. Absent -> success envelope is byte-identical. */
     explain?: true;
 }
 export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy> & {
@@ -71,3 +63,21 @@ export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: S
  *  failure that the envelope converts to `{ok:false, error}`. */
 declare function throwToolError(code: ToolError['code'], message: string): never;
 export { throwToolError };
+/** Diagnostic reported by `visitOracleLeaves` when an oracle comparison
+ *  cannot be normalised to oracle-on-left. Currently only "oracle-on-right
+ *  with a non-literal LHS" - the other branches already produce a parseable
+ *  threshold and are returned to the caller. */
+export interface OracleNormalisationWarning {
+    /** The dimension name (currently always "oracle_normalisation_dropped"). */
+    dimension: 'oracle_normalisation_dropped';
+    /** The operator as written. */
+    op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte';
+    /** The asset the oracle leaf is bound to. */
+    asset: string;
+    /** The non-literal RHS (oracle-on-left) or LHS (oracle-on-right) leaf
+     *  whose shape stopped the normalisation. Surfaced for diagnostics;
+     *  intentionally a partial view - the full leaf is the caller's job. */
+    otherKind: string;
+    /** Human-readable message (matches the warn-on-drop text). */
+    message: string;
+}