@crediolabs/policy-synth 0.1.9 → 0.1.11

package/dist/synth/evaluate.js

@@ -29,6 +29,11 @@
 // Amounts: BigInt on decimal strings (never JS `number`). Oracle errors
 // modelled by throwing (never a boolean-false that `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. */
+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. */
@@ -165,6 +170,13 @@ function evalCompare(op, left, right, ctx) {
     }
     // --- step 4b: call_arg comparison (eq / exact-vec, or an ordered numeric bound) ---
     if (left.kind === 'call_arg') {
+        // The swap's canonical form is `call_arg[out] >= call_arg_scaled(in, num, den)`.
+        // Dispatched here so the floor's dedicated reason codes (ARITHMETIC_OVERFLOW
+        // -> SLIPPAGE_FLOOR) reach the user; routing the scaled RHS through the
+        // generic `evalArgOrderedCompare` would mask overflow as ARG_MISMATCH.
+        if (right.kind === 'call_arg_scaled') {
+            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
@@ -175,6 +187,11 @@ function evalCompare(op, left, right, ctx) {
             return evalArgOrderedCompare(op, actual, right);
         return evalArgEq(op, actual, right, ctx);
     }
+    // --- step 4b': scaled leaf on the LEFT (`call_arg_scaled(in, num, den) <= call_arg[out]`).
+    // Symmetric form so a policy that phrases the floor either way works.
+    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.
     if (left.kind === 'call_arg_len') {
@@ -293,6 +310,102 @@ 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`. */
+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;
+    if (left.kind === 'call_arg_scaled') {
+        scaled = left;
+        other = right;
+        scaledOnRight = false;
+    }
+    else if (right.kind === 'call_arg_scaled') {
+        scaled = right;
+        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.
+        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.
+    if (scaled.index >= ctx.args.length) {
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    }
+    const input = argNumericBigInt(ctx.args[scaled.index]);
+    if (input === null)
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    let num;
+    let den;
+    try {
+        num = BigInt(scaled.num);
+        den = BigInt(scaled.den);
+    }
+    catch {
+        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.
+    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`).
+        scaledValue = product / den;
+    }
+    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.
+    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]);
+    }
+    else {
+        otherVal = literalNumericBigInt(other);
+    }
+    if (otherVal === null)
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    const pass = scaledOnRight
+        ? bigintCmp(op, otherVal.toString(), scaledValue.toString())
+        : bigintCmp(op, scaledValue.toString(), otherVal.toString());
+    return pass ? { permit: true } : { permit: false, reason: 'SLIPPAGE_FLOOR' };
+}
 /** Ordered numeric comparison (lt/lte/gt/gte) on a `call_arg`. The interpreter
  *  reads the arg as an integer (i128 / u64 / u32 on the recorder's ScVal
  *  surface) and compares it to a numeric literal via BigInt. A non-numeric arg
@@ -389,6 +502,7 @@ function resolveLeaf(leaf, ctx) {
         case 'invocation_count_in_window':
         case 'now':
         case 'valid_until':
+        case 'call_arg_scaled':
             return undefined; // selector leaves with no ScVal projection
         case 'literal_address':
             return { type: 'address', value: leaf.value };
@@ -447,10 +561,23 @@ function evalOracleCompare(op, asset, right, ctx) {
             throw new OracleError('ORACLE_STALE');
         throw new OracleError(mapped);
     }
-    const literal = right.kind === 'literal_i128' ? right.value : null;
-    if (literal === null)
+    // 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.
+    if (right.kind !== 'oracle_threshold')
         throw new OracleError('ORACLE_DECIMALS_MISMATCH');
-    return bigintCmp(op, entry.price, literal)
+    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.
+    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);
+    return bigintCmp(op, String(priceScaled), String(literalScaled))
         ? { permit: true }
         : { permit: false, reason: 'FN_MISMATCH' };
 }

package/dist/synth/permit-context.d.ts

@@ -0,0 +1,15 @@
+import type { PredicateNode, RecordedTransaction } from '../types.ts';
+import type { EvalContext } from './evaluate.ts';
+export interface PermitContextResponses {
+    windowSeconds: number;
+    invocationLimit?: number;
+    limitAmount?: string;
+    validUntilLedger: number;
+    oraclePriceBound?: Array<{
+        asset: string;
+        operator: string;
+        value: string;
+        decimals: number;
+    }>;
+}
+export declare function buildPermitContext(tx: RecordedTransaction, responses: PermitContextResponses, predicate: PredicateNode): EvalContext;

package/dist/synth/permit-context.js

@@ -0,0 +1,116 @@
+// src/synth/permit-context.ts - build the EvalContext that represents the
+// recorded call being replayed.
+//
+// Extracted from the over-permissiveness harness so the same construction
+// feeds both the in-process battery and the on-chain replay
+// (scripts/verify-mutations-testnet.ts). Two callers building this
+// separately would be two chances to disagree about what "the recorded
+// call" means, which is the one thing both must share.
+import { cloneScVal } from "./deny-cases.js";
+export function buildPermitContext(tx, responses, predicate) {
+    const amountByToken = {};
+    const totals = new Map();
+    for (const m of tx.tokenMovements) {
+        const current = totals.get(m.token) ?? 0n;
+        totals.set(m.token, current + BigInt(m.amount));
+    }
+    for (const [token, total] of totals) {
+        amountByToken[token] = total.toString();
+    }
+    const topLevel = tx.invocations[0];
+    const scopeContract = topLevel?.contract ?? '';
+    const oraclePriceByAsset = {};
+    visitOracleLeaves(predicate, (asset, op, bound) => {
+        let price;
+        switch (op) {
+            case 'lt':
+                price = bound - 1n;
+                break;
+            case 'gt':
+                price = bound + 1n;
+                break;
+            default:
+                price = bound;
+        }
+        if (price < 0n)
+            price = 0n;
+        oraclePriceByAsset[asset] = { price: price.toString(), timestampSeconds: tx.fetchedAt };
+    });
+    const ctx = {
+        contract: scopeContract,
+        fn: topLevel?.fn ?? '',
+        args: (topLevel?.args ?? []).map(cloneScVal),
+        atLedger: tx.ledgerSequence,
+        nowSeconds: tx.fetchedAt,
+        amountByToken,
+        windowSpentByToken: {},
+        invocationCountByWindow: {},
+        oraclePriceByAsset,
+    };
+    if (responses.validUntilLedger !== undefined) {
+        ctx.validUntilLedger = responses.validUntilLedger;
+    }
+    return ctx;
+}
+function visitOracleLeaves(node, visit) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                visitOracleLeaves(child, visit);
+            return;
+        case 'not':
+            visitOracleLeaves(node.child, visit);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            const leftIsOracle = node.left.kind === 'oracle_price';
+            const rightIsOracle = node.right.kind === 'oracle_price';
+            let asset;
+            let literal;
+            if (leftIsOracle) {
+                asset = node.left.kind === 'oracle_price' ? node.left.asset : undefined;
+                literal = oracleThresholdNormalised(node.right);
+            }
+            else if (rightIsOracle) {
+                asset = node.right.kind === 'oracle_price' ? node.right.asset : undefined;
+                literal = oracleThresholdNormalised(node.left);
+            }
+            if (asset !== undefined && literal !== undefined) {
+                visit(asset, node.op, literal);
+            }
+            return;
+        }
+        case 'in':
+            return;
+    }
+}
+/** Oracle prices normalise to 9 decimals; mirrors NORMALISED_DECIMALS in
+ *  oracle.rs. */
+const NORMALISED_DECIMALS = 9n;
+/** A threshold restated on the normalised basis, so a derived permit price is
+ *  comparable to it. Thresholds carry their own basis, so the conversion has
+ *  to happen here - reading the digits raw would build a context off by a
+ *  factor of 10^(decimals-9). Returns undefined for any other leaf. */
+function oracleThresholdNormalised(leaf) {
+    if (leaf.kind !== 'oracle_threshold')
+        return undefined;
+    let value;
+    try {
+        value = BigInt(leaf.value);
+    }
+    catch {
+        return undefined;
+    }
+    const decimals = BigInt(leaf.decimals);
+    if (decimals <= NORMALISED_DECIMALS) {
+        return value * 10n ** (NORMALISED_DECIMALS - decimals);
+    }
+    // Floor: a finer-grained threshold has no exact 9-dp representation. The
+    // caller only needs a price that lands on the right side of the bound, and
+    // it offsets by one from here.
+    return value / 10n ** (decimals - NORMALISED_DECIMALS);
+}

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

@@ -1,5 +1,20 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
 import type { ToolResponse } from '../errors.ts';
 import type { MandateSpec } from '../mandate/types.ts';
-import type { ProposedPolicy } from '../types.ts';
-export declare function synthesizeFromMandate(spec: MandateSpec, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+import type { PredicateNode, ProposedPolicy } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
+export declare function synthesizeFromMandate(spec: MandateSpec, ozConfig: OzAdapterConfig, 
+/** --explain opt-in. When true, the success envelope carries the
+ *  in-memory predicate tree (always null for the mandate path - the
+ *  declarative MandateSpec lowers to OZ built-ins, not to an
+ *  interpreter predicate) + a minimal honest SimulationResult. The
+ *  flag is ADDITIVE: the existing ProposedPolicy fields are never
+ *  altered. */
+opts?: {
+    explain?: true;
+}): ToolResponse<ProposedPolicy> & {
+    explain?: {
+        predicateTree: PredicateNode | null;
+        simulation: SimulationResult;
+    };
+};

package/dist/synth/synthesize-from-mandate.js

@@ -10,7 +10,14 @@
 import { createOzAdapter } from "../adapters/oz/adapter.js";
 import { mandateToPolicyIR } from "../mandate/to-ir.js";
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
-export function synthesizeFromMandate(spec, ozConfig) {
+export function synthesizeFromMandate(spec, ozConfig, 
+/** --explain opt-in. When true, the success envelope carries the
+ *  in-memory predicate tree (always null for the mandate path - the
+ *  declarative MandateSpec lowers to OZ built-ins, not to an
+ *  interpreter predicate) + a minimal honest SimulationResult. The
+ *  flag is ADDITIVE: the existing ProposedPolicy fields are never
+ *  altered. */
+opts) {
     const ir = mandateToPolicyIR(spec);
     const adapter = createOzAdapter(ozConfig);
     const result = adapter.compile(ir);
@@ -30,5 +37,23 @@ export function synthesizeFromMandate(spec, ozConfig) {
         ...result.proposed,
         warnings: result.uncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
     };
-    return { ok: true, data: proposed };
+    // Same --explain envelope pattern as the recording path. The mandate path
+    // never produces an interpreter predicate, so predicateTree is null and
+    // the simulation is a minimal honest deny (no self-verify was performed).
+    const envelope = { ok: true, data: proposed };
+    if (opts?.explain) {
+        envelope.explain = {
+            predicateTree: null,
+            simulation: {
+                permit: {
+                    tx: 'deny',
+                    reason: 'No self-verification was performed (mandate path is OZ-only)',
+                },
+                evaluatedCases: [],
+                backend: 'ts-model',
+                simulatorVersion: 'not-run',
+            },
+        };
+    }
+    return envelope;
 }

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

@@ -1,6 +1,7 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
 import type { ToolError, ToolResponse } from '../errors.ts';
 import { type Network, type PredicateNode, type ProposedPolicy, type RecordedTransaction } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
 import { type ComposeUserResponses } from './compose-from-recording.ts';
 /** Per-policy interpreter adapter config the caller opts into. Absent ->
  *  recording path runs in week-1 mode (OZ adapter only, warnings for the
@@ -41,8 +42,31 @@ 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?: true;
 }
-export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy> & {
+    /** Present iff `opts.explain === true` and the synthesis succeeded. The
+     *  `predicateTree` is the exact in-memory `PredicateNode` (canonical
+     *  JSON shape) that was encoded into `proposed.policyDocuments[*].encodedPredicate`
+     *  - reading the predicate tree from the policy document is therefore
+     *  unnecessary; the orchestrator carries it through. The `simulation`
+     *  is the verdict produced by the same self-verify pipeline that already
+     *  runs in the recording path (runHarness + evaluate), so the value is
+     *  REAL not synthetic. Absent when the synthesis did not engage the
+     *  interpreter (no interpreter opts supplied) - in that case the CLI
+     *  builds a minimal honest SimulationResult downstream. */
+    explain?: {
+        predicateTree: PredicateNode | null;
+        simulation: SimulationResult;
+    };
+};
 /** ToolError-shaped error helper used by the body to surface a structured
  *  failure that the envelope converts to `{ok:false, error}`. */
 declare function throwToolError(code: ToolError['code'], message: string): never;

package/dist/synth/synthesize-from-recording.js

@@ -195,6 +195,14 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
     };
     const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts);
+    // --explain hook: capture the in-memory predicate tree + the real
+    // self-verify verdict so the CLI can render a faithful review card.
+    // The verdict below is built from the SAME runHarness + evaluate that
+    // already gates the synthesis (it is not a parallel simulation); the
+    // intermediate inputs (harnessCases, evalResult) are otherwise discarded
+    // after the gate, so the explain hook reuses them - no extra work.
+    let explain = null;
+    let explainSim = null;
     // 5. OZ compile (always runs).
     const ozAdapter = createOzAdapter(ozConfig);
     const compileRes = ozAdapter.compile(composed.ir);
@@ -372,6 +380,36 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
                 },
             };
         }
+        // --explain capture: the interpreter path already produced the real
+        // self-verify verdict (runHarness passed, evalResult.permit is true).
+        // Build the SimulationResult from those outputs so the CLI card
+        // quotes the SAME verdict that gated the synthesis. We re-evaluate
+        // each deny case to surface its concrete reason; the harness only
+        // records whether the got-matches-expected boundary held.
+        if (opts.explain) {
+            explain = finalPredicate;
+            const evaluatedCases = [
+                {
+                    dimension: 'permit',
+                    outcome: evalResult.permit ? 'permit' : 'deny',
+                    reason: 'matches recorded call',
+                },
+            ];
+            for (const deny of harnessCases.denies) {
+                const r = evaluate(finalPredicate, deny.ctx);
+                evaluatedCases.push({
+                    dimension: deny.dimension,
+                    outcome: r.permit ? 'permit' : 'deny',
+                    reason: r.permit ? 'no matching deny' : r.reason,
+                });
+            }
+            explainSim = {
+                permit: { tx: 'permit' },
+                evaluatedCases,
+                backend: 'ts-model',
+                simulatorVersion: 'ts-model-1.0.0',
+            };
+        }
         // 6c. Re-encode the (possibly minimised) PredicateNode and stamp the
         //     canonical bytes back onto the PolicyDocument + PolicyRef. The
         //     `encodePredicate` helper throws ToolError-shaped errors on cap
@@ -469,7 +507,34 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ],
         ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
     };
-    return { ok: true, data: proposed };
+    // --explain success envelope. The interpreter path populated
+    // `explain` + `explainSim` from the real self-verify verdict above;
+    // the OZ-only path did not (no predicate tree exists). When opts.explain
+    // is set and the OZ-only path ran, construct the minimal honest
+    // SimulationResult: the verdict is NOT a passing simulation - the
+    // interpreter was never engaged, so permit is deny with a truthful
+    // reason and evaluatedCases is empty.
+    const envelope = { ok: true, data: proposed };
+    if (opts.explain) {
+        if (explainSim) {
+            envelope.explain = { predicateTree: explain, simulation: explainSim };
+        }
+        else {
+            envelope.explain = {
+                predicateTree: null,
+                simulation: {
+                    permit: {
+                        tx: 'deny',
+                        reason: 'No self-verification was performed (interpreter adapter was not engaged)',
+                    },
+                    evaluatedCases: [],
+                    backend: 'ts-model',
+                    simulatorVersion: 'not-run',
+                },
+            };
+        }
+    }
+    return envelope;
 }
 // Re-export the throwToolError helper for callers that need to surface a
 // ToolError-shaped throw inside the body (e.g. tests).
@@ -746,13 +811,25 @@ function visitOracleLeaves(node, visit) {
             return;
     }
 }
+/** An oracle threshold restated on the normalised 9-dp basis prices use.
+ *  Thresholds carry their own basis, so reading the digits raw would build a
+ *  permit context off by 10^(decimals-9) and the intended call would not
+ *  satisfy its own bound. Mirrors NORMALISED_DECIMALS in oracle.rs. */
 function oracleLiteralFromLeaf(leaf) {
-    if (leaf.kind !== 'literal_i128')
+    if (leaf.kind !== 'oracle_threshold')
         return undefined;
+    let value;
     try {
-        return BigInt(leaf.value);
+        value = BigInt(leaf.value);
     }
     catch {
         return undefined;
     }
+    const normalised = 9n;
+    const decimals = BigInt(leaf.decimals);
+    if (decimals <= normalised)
+        return value * 10n ** (normalised - decimals);
+    // Floor: a finer-grained threshold has no exact 9-dp representation; the
+    // caller offsets by one from here to land on the right side of the bound.
+    return value / 10n ** (decimals - normalised);
 }

package/dist/types.d.ts

@@ -190,6 +190,11 @@ export type PredicateLeaf = {
     index: number;
     element: number;
     field: string;
+} | {
+    kind: 'call_arg_scaled';
+    index: number;
+    num: string;
+    den: string;
 } | {
     kind: 'amount';
     token: string;
@@ -207,6 +212,10 @@ export type PredicateLeaf = {
 } | {
     kind: 'oracle_price';
     asset: string;
+} | {
+    kind: 'oracle_threshold';
+    value: string;
+    decimals: number;
 } | {
     kind: 'literal_address';
     value: string;

package/dist-cjs/adapters/interpreter/adapter.js

@@ -52,7 +52,10 @@ exports.ORACLE_DEFAULTS = {
 const CAPABILITIES = {
     supportsSpendWindow: true,
     supportsThreshold: false, // thresholds are the OZ adapter's job
-    supportsTimeExpiry: true, // via valid_until ledger expiry
+    // False for the predicate-leaf path: the interpreter refuses a `valid_until`
+    // leaf at install. Expiry is still available, but as the context rule's
+    // validUntilLedger, which the smart account enforces - not as a predicate.
+    supportsTimeExpiry: false,
     supportsOraclePrice: true,
     supportsInvocationCount: true,
     supportsGeneralPredicate: true,
@@ -221,26 +224,61 @@ function lowerRule(rule, config) {
 function unsupportedConstruct(cond) {
     switch (cond.op) {
         case 'in':
-            return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
-                ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
-                : null;
+            // The oracle position rule is a hard error and must be raised before a
+            // construct can be written off as uncovered - otherwise a subtree that
+            // is BOTH misplaced-oracle and unsourceable would be silently dropped
+            // instead of rejected.
+            assertNoOracleDescendants(cond);
+            return (unsourceableSelector(cond.selector) ??
+                (cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+                    ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
+                    : null));
         case 'eq_seq':
-            return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
-                ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
-                : null;
+            return (unsourceableSelector(cond.selector) ??
+                (cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+                    ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
+                    : null));
         case 'compare': {
             const s = cond.compare.selector;
             if (s.kind === 'calldata')
                 return 'EVM calldata comparison (predicate DSL)';
             if (s.kind === 'value')
                 return 'tx.value comparison (predicate DSL)';
-            return null;
+            // The on-chain interpreter sees ONE authorized call - there is no
+            // `Context.sub_invocations` in v1 - so it cannot observe the
+            // transaction's token movements. `amount` has no value to read, and
+            // `window_spent` accumulates BY that amount, so its counter would never
+            // move. Deriving either from the call payload would quietly swap "value
+            // actually moved" for "value the caller declared" - a weaker guarantee
+            // than the review card would be claiming.
+            //
+            // Rolling spend caps belong to the OZ `spending_limit` primitive, which
+            // is already audited and which the OZ adapter emits. A per-call cap is
+            // expressible here as `arg_field`; bounding it with `invocation_count`
+            // gives an enforceable ceiling per window.
+            return unsourceableSelector(s);
         }
+        // Recurse: a nested `and`/`or`/`not` must not smuggle a selector past the
+        // pre-scan, which only sees top-level constraints.
         case 'and':
+            return cond.children.map(unsupportedConstruct).find((u) => u !== null) ?? null;
         case 'or':
+            assertNoOracleDescendants(cond);
+            return cond.children.map(unsupportedConstruct).find((u) => u !== null) ?? null;
         case 'not':
-            return null;
+            assertNoOracleDescendants(cond);
+            return unsupportedConstruct(cond.child);
+    }
+}
+/** Selectors whose value the on-chain interpreter has no way to obtain. */
+function unsourceableSelector(s) {
+    if (s.kind === 'amount') {
+        return `per-call amount comparison on ${s.token} - the interpreter cannot observe token movements; express a per-call cap with arg_field, or a rolling cap with the OZ spending_limit primitive`;
+    }
+    if (s.kind === 'window_spent') {
+        return `rolling spend cap on ${s.token} over ${s.windowSeconds}s - not enforceable by the interpreter; use the OZ spending_limit primitive, or bound per-call value with arg_field plus invocation_count`;
     }
+    return null;
 }
 /** Lower one IR condition to a PredicateNode. Enforces the oracle position
  *  rule (oracle_price leaves must sit directly under the top-level `and`) and
@@ -316,10 +354,13 @@ function lowerSelector(s) {
             return { kind: 'call_arg_len', index: s.argIndex };
         case 'arg_field':
             return { kind: 'call_arg_field', index: s.argIndex, element: s.element, field: s.field };
+        // `amount` / `window_spent` are filtered out by `unsupportedConstruct`
+        // before lowering - the interpreter cannot source either on chain. Reaching
+        // here means the pre-scan was bypassed, so fail loudly rather than emit a
+        // leaf the contract will refuse.
         case 'amount':
-            return { kind: 'amount', token: s.token };
         case 'window_spent':
-            return { kind: 'window_spent', token: s.token, windowSeconds: s.windowSeconds };
+            throw new Error(`interpreter adapter cannot lower \`${s.kind}\`: it should have been reported as uncovered`);
         case 'invocation_count':
             return { kind: 'invocation_count_in_window', windowSecs: s.windowSeconds };
         case 'now':
@@ -346,6 +387,16 @@ function lowerSelector(s) {
  *    - invocation_count -> u32 (counts are small non-negative integers)
  *    - now / valid_until -> u64 (unix timestamps in seconds) */
 function literalFromIRCompare(c) {
+    // An oracle comparand is not a bare literal: the interpreter refuses one,
+    // because assuming it shares the normalised 9-dp basis is what made a raw
+    // 14-dp threshold permit everything it was written to deny.
+    if (c.selector.kind === 'oracle_price') {
+        if (c.valueDecimals === undefined) {
+            throw toolError('ORACLE_THRESHOLD_BASIS_REQUIRED', 'An oracle price bound must declare the decimal basis of its threshold ' +
+                '(oracle prices normalise to 9 decimals).');
+        }
+        return { kind: 'oracle_threshold', value: c.value, decimals: c.valueDecimals };
+    }
     const scalarType = selectorScalarType(c.selector);
     return literalFromScalar(c.value, scalarType);
 }