@crediolabs/policy-synth 0.1.3 → 0.1.5

package/dist/synth/evaluate.js

@@ -0,0 +1,425 @@
+// src/synth/evaluate.ts - the model evaluator.
+//
+// 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.
+//
+// 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).
+import { literalNumericBigInt } from "./predicate-literals.js";
+/** 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. */
+class OracleError extends Error {
+    code;
+    constructor(code) {
+        super(`oracle fatal: ${code}`);
+        this.code = code;
+    }
+}
+const ORACLE_ERROR_CODES = {
+    stale: 'ORACLE_STALE',
+    missing: 'ORACLE_MISSING',
+    deviation: 'ORACLE_DEVIATION_EXCEEDED',
+    paused: 'ORACLE_PAUSED',
+    decimals: 'ORACLE_DECIMALS_MISMATCH',
+    fingerprint: 'ORACLE_FINGERPRINT_DRIFT',
+};
+/** Evaluate a `PredicateNode` against the candidate call described by `ctx`.
+ *  Pure function. Returns `{ permit: true }` or `{ permit: false; reason }`. */
+export function evaluate(predicate, ctx) {
+    try {
+        // --- step 1: ledger-time expiry ---
+        if (ctx.validUntilLedger !== undefined && ctx.atLedger > ctx.validUntilLedger) {
+            return { permit: false, reason: 'EXPIRED' };
+        }
+        // --- step 2..9: predicate tree ---
+        const decision = walk(predicate, ctx);
+        // --- step 10: signer threshold gate (only when the predicate permitted) ---
+        if (decision.permit && ctx.signerWeights !== undefined) {
+            let totalWeight = 0n;
+            for (const w of Object.values(ctx.signerWeights)) {
+                // weights are non-negative integers; BigInt keeps the gate bounded
+                totalWeight += BigInt(w);
+            }
+            if (totalWeight === 0n)
+                return { permit: false, reason: 'THRESHOLD_NOT_MET' };
+        }
+        return decision;
+    }
+    catch (e) {
+        if (e instanceof OracleError) {
+            return { permit: false, reason: e.code };
+        }
+        throw e;
+    }
+}
+/** Walk the predicate tree. Returns the FIRST deny reason encountered on
+ *  the active branch (so `and` fails-fast; `or` accepts the first permit). */
+function walk(node, ctx) {
+    switch (node.op) {
+        case 'and': {
+            let lastDeny = null;
+            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.
+                    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 };
+        }
+        case 'or': {
+            let lastDeny = null;
+            for (const child of node.children) {
+                const r = walk(child, ctx);
+                if (r.permit)
+                    return r;
+                lastDeny = r;
+            }
+            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.
+            const r = walk(node.child, ctx);
+            if (r.permit)
+                return { permit: false, reason: 'FN_MISMATCH' };
+            return { permit: true };
+        }
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            return evalCompare(node.op, node.left, node.right, ctx);
+        case 'in':
+            return evalIn(node.needle, node.haystack, ctx);
+    }
+}
+/** Step 2..8: comparison leaf evaluation. */
+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.
+        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 };
+    }
+    if (right.kind === 'now' && left.kind === 'valid_until') {
+        return evalCompare(op, right, left, ctx);
+    }
+    // --- step 3: CONTRACT_SCOPE on call_contract eq ---
+    if (left.kind === 'call_contract' && op === 'eq') {
+        if (right.kind !== 'literal_address')
+            return { permit: false, reason: 'CONTRACT_SCOPE' };
+        return right.value === ctx.contract
+            ? { permit: true }
+            : { permit: false, reason: 'CONTRACT_SCOPE' };
+    }
+    // --- step 4a: call_fn equality ---
+    if (left.kind === 'call_fn' && op === 'eq') {
+        if (right.kind !== 'literal_symbol')
+            return { permit: false, reason: 'FN_MISMATCH' };
+        return right.value === ctx.fn ? { permit: true } : { permit: false, reason: 'FN_MISMATCH' };
+    }
+    // --- step 4b: call_arg comparison (eq / exact-vec, or an ordered numeric bound) ---
+    if (left.kind === 'call_arg') {
+        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);
+    }
+    // --- step 6: AMOUNT_BOUND ---
+    if (left.kind === 'amount' && op !== 'eq') {
+        return evalAmountCompare(op, left.token, right, ctx);
+    }
+    if (left.kind === 'window_spent' && op !== 'eq') {
+        return evalWindowSpentCompare(op, left.token, right, ctx);
+    }
+    // `eq` on amount / window_spent not defined as a bound - fall through.
+    // --- step 7: FREQUENCY ---
+    if (left.kind === 'invocation_count_in_window') {
+        return evalFrequencyCompare(op, left.windowSecs, right, ctx);
+    }
+    // --- step 8: oracle_price (FATAL via throw) ---
+    if (left.kind === 'oracle_price') {
+        return evalOracleCompare(op, left.asset, right, ctx);
+    }
+    // Unknown leaf/op combination - structural fail-closed.
+    return { permit: false, reason: 'FN_MISMATCH' };
+}
+/** Step 4b: per-ScVal equality. Handles literal_vec as an EXACT ordered
+ *  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
+    if (op === 'eq' && right.kind === 'literal_vec') {
+        if (actual?.type !== 'vec')
+            return { permit: false, reason: 'ARG_MISMATCH' };
+        return compareVecExact(actual.value, right.elements, 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' };
+        if (actual.type === 'other')
+            return { permit: false, reason: 'ARG_MISMATCH' };
+        return actual.type === 'address' && actual.value === right.value
+            ? { 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' };
+        return BigInt(actual.value) === BigInt(right.value)
+            ? { 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' };
+        return actual.type === 'symbol' && actual.value === right.value
+            ? { 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' };
+        return actual.type === 'u32' && actual.value === String(right.value)
+            ? { 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' };
+        return actual.type === 'u64' && actual.value === right.value
+            ? { 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' };
+        return actual.type === 'bytes' && actual.value === right.value
+            ? { permit: true }
+            : { permit: false, reason: 'ARG_MISMATCH' };
+    }
+    // Anything else: fail closed on opacity (cannot decode the arg reliably).
+    if (!actual || actual.type === 'other')
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    return { permit: false, reason: 'ARG_MISMATCH' };
+}
+/** 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
+ *  or a non-numeric literal fails closed (ARG_MISMATCH) rather than permitting
+ *  an undecidable bound. Backs the SoroSwap input-amount cap
+ *  (`call_arg[0] <= limit`). */
+function evalArgOrderedCompare(op, actual, right) {
+    const actualInt = argNumericBigInt(actual);
+    const literalInt = literalNumericBigInt(right);
+    if (actualInt === null || literalInt === null) {
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    }
+    return bigintCmp(op, actualInt.toString(), literalInt.toString())
+        ? { permit: true }
+        : { permit: false, reason: 'ARG_MISMATCH' };
+}
+/** BigInt value of a numeric-integer ScVal arg (i128 / u64 / u32), or null when
+ *  the arg is absent, opaque, or a non-numeric type. */
+function argNumericBigInt(actual) {
+    if (!actual)
+        return null;
+    if (actual.type === 'i128' || actual.type === 'u64' || actual.type === 'u32') {
+        try {
+            return BigInt(actual.value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/** Element-by-element ordered comparison of an `ScVal[]` against a
+ *  `PredicateLeaf[]`. Equal-length and equal at every index => permit.
+ *  Length mismatch OR any element mismatch => deny ARG_MISMATCH. */
+function compareVecExact(actual, expected, ctx) {
+    if (actual.length !== expected.length)
+        return false;
+    for (let i = 0; i < expected.length; i++) {
+        const e = expected[i];
+        const a = actual[i];
+        if (!e || !a)
+            return false;
+        const r = evalArgEq('eq', a, e, ctx);
+        if (!r.permit)
+            return false;
+    }
+    return true;
+}
+/** Step 5: `in` membership. Empty haystack ALWAYS denies. Opaque needle
+ *  fails closed. */
+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' };
+    for (const h of haystack) {
+        const r = evalArgEq('eq', actual, h, ctx);
+        if (r.permit)
+            return { permit: true };
+    }
+    return { permit: false, reason: 'NOT_IN_ALLOWLIST' };
+}
+/** Resolve a selector leaf to its current ScVal against the candidate call. */
+function resolveLeaf(leaf, ctx) {
+    switch (leaf.kind) {
+        case 'call_contract':
+            return { type: 'address', value: ctx.contract };
+        case 'call_fn':
+            return { type: 'symbol', value: ctx.fn };
+        case 'call_arg':
+            return ctx.args[leaf.index];
+        case 'amount':
+        case 'window_spent':
+        case 'oracle_price':
+        case 'invocation_count_in_window':
+        case 'now':
+        case 'valid_until':
+            return undefined; // selector leaves with no ScVal projection
+        case 'literal_address':
+            return { type: 'address', value: leaf.value };
+        case 'literal_i128':
+            return { type: 'i128', value: leaf.value };
+        case 'literal_symbol':
+            return { type: 'symbol', value: leaf.value };
+        case 'literal_u32':
+            return { type: 'u32', value: String(leaf.value) };
+        case 'literal_u64':
+            return { type: 'u64', value: leaf.value };
+        case 'literal_bytes':
+            return { type: 'bytes', value: leaf.value };
+        case 'literal_vec':
+            return undefined;
+    }
+}
+/** Step 6: amount compare on BigInt. */
+function evalAmountCompare(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.amountByToken[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' };
+}
+/** Step 7: invocation_count_in_window compare. */
+function evalFrequencyCompare(op, windowSecs, right, ctx) {
+    const literal = right.kind === 'literal_u32' ? String(right.value) : null;
+    if (literal === null)
+        return { permit: false, reason: 'FREQUENCY' };
+    const actual = String(ctx.invocationCountByWindow[windowSecs] ?? 0);
+    return bigintCmp(op, actual, literal) ? { permit: true } : { permit: false, reason: 'FREQUENCY' };
+}
+/** Step 8: oracle_price compare. Reads `ctx.oraclePriceByAsset[asset]`. Any
+ *  error entry OR a missing key throws `OracleError` (FATAL). A satisfied
+ *  compare permits. */
+function evalOracleCompare(op, asset, right, ctx) {
+    const entry = ctx.oraclePriceByAsset[asset];
+    if (!entry)
+        throw new OracleError('ORACLE_STALE');
+    if ('error' in entry) {
+        const mapped = ORACLE_ERROR_CODES[entry.error];
+        if (!mapped)
+            throw new OracleError('ORACLE_STALE');
+        throw new OracleError(mapped);
+    }
+    const literal = right.kind === 'literal_i128' ? right.value : null;
+    if (literal === null)
+        throw new OracleError('ORACLE_DECIMALS_MISMATCH');
+    return bigintCmp(op, entry.price, literal)
+        ? { permit: true }
+        : { permit: false, reason: 'FN_MISMATCH' };
+}
+/** 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)`. */
+function bigintCmp(op, aStr, bStr) {
+    const a = BigInt(aStr);
+    const b = BigInt(bStr);
+    switch (op) {
+        case 'eq':
+            return a === b;
+        case 'lt':
+            return a < b;
+        case 'lte':
+            return a <= b;
+        case 'gt':
+            return a > b;
+        case 'gte':
+            return a >= b;
+    }
+}

package/dist/synth/harness.d.ts

@@ -0,0 +1,16 @@
+import type { PredicateNode } from '../types.ts';
+import type { GeneratedCases } from './deny-cases.ts';
+export interface HarnessFailure {
+    dimension: string;
+    expected: 'permit' | 'deny';
+    got: 'permit' | 'deny';
+    reason?: string;
+}
+export type HarnessResult = {
+    ok: true;
+} | {
+    ok: false;
+    failures: HarnessFailure[];
+};
+/** Evaluate the intended call and every generated denial without side effects. */
+export declare function runHarness(predicate: PredicateNode, cases: GeneratedCases): HarnessResult;

package/dist/synth/harness.js

@@ -0,0 +1,26 @@
+import { evaluate } from "./evaluate.js";
+/** Evaluate the intended call and every generated denial without side effects. */
+export function runHarness(predicate, cases) {
+    const failures = [];
+    const permitResult = evaluate(predicate, cases.permit);
+    if (!permitResult.permit) {
+        failures.push({
+            dimension: 'PERMIT_CASE_FAILED',
+            expected: 'permit',
+            got: 'deny',
+            reason: permitResult.reason,
+        });
+    }
+    for (const deny of cases.denies) {
+        const result = evaluate(predicate, deny.ctx);
+        if (result.permit) {
+            failures.push({
+                dimension: deny.dimension,
+                expected: 'deny',
+                got: 'permit',
+                reason: 'DENY_CASE_FAILURE',
+            });
+        }
+    }
+    return failures.length === 0 ? { ok: true } : { ok: false, failures };
+}

package/dist/synth/index.d.ts

@@ -1,5 +1,9 @@
 export { type ComposeOptions, type ComposeResult, composeFromRecording, } from './compose-from-recording.ts';
+export { type DenyCase, type GeneratedCases, generateCases, } from './deny-cases.ts';
+export { type EvalContext, type EvalResult, evaluate } from './evaluate.ts';
+export { type HarnessFailure, type HarnessResult, runHarness, } from './harness.ts';
 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';

package/dist/synth/index.js

@@ -1,6 +1,10 @@
 // src/synth/index.ts - re-export the synthesizer front-ends.
 export { composeFromRecording, } from "./compose-from-recording.js";
+export { generateCases, } from "./deny-cases.js";
+export { evaluate } from "./evaluate.js";
+export { runHarness, } from "./harness.js";
 export { lower } from "./lower.js";
+export { minimize } from "./minimize.js";
 export { decideScope, scopeToContextRuleType, } from "./scope.js";
 export { synthesizeFromMandate } from "./synthesize-from-mandate.js";
 export { synthesizeFromRecording, } from "./synthesize-from-recording.js";

package/dist/synth/minimize.d.ts

@@ -0,0 +1,4 @@
+import type { PredicateNode } from '../types.ts';
+import type { EvalContext } from './evaluate.ts';
+/** Remove top-level conjuncts only when the current and regenerated batteries still deny. */
+export declare function minimize(predicate: PredicateNode, permitCtx: EvalContext): PredicateNode;

package/dist/synth/minimize.js

@@ -0,0 +1,38 @@
+import { generateCases } from "./deny-cases.js";
+import { runHarness } from "./harness.js";
+/** Remove top-level conjuncts only when the current and regenerated batteries still deny. */
+export function minimize(predicate, permitCtx) {
+    if (predicate.op !== 'and')
+        return predicate;
+    let children = [...predicate.children];
+    let index = 0;
+    while (index < children.length) {
+        const current = { op: 'and', children };
+        const currentCases = generateCases(current, permitCtx);
+        const candidateChildren = children.filter((_, childIndex) => childIndex !== index);
+        const candidate = { op: 'and', children: candidateChildren };
+        const candidateCases = generateCases(candidate, permitCtx);
+        const verificationCases = {
+            permit: candidateCases.permit,
+            denies: mergeDenyCases(currentCases.denies, candidateCases.denies),
+        };
+        if (runHarness(candidate, verificationCases).ok) {
+            children = candidateChildren;
+            continue;
+        }
+        index += 1;
+    }
+    return { op: 'and', children };
+}
+function mergeDenyCases(current, candidate) {
+    const merged = [];
+    const seen = new Set();
+    for (const deny of [...current, ...candidate]) {
+        const key = `${deny.dimension}:${JSON.stringify(deny.ctx)}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(deny);
+    }
+    return merged;
+}

package/dist/synth/predicate-literals.d.ts

@@ -0,0 +1,5 @@
+import type { PredicateLeaf } from '../types.ts';
+/** BigInt value of a numeric-integer literal leaf (`literal_i128` / `literal_u64`
+ *  / `literal_u32`), or null for a non-numeric literal (address / symbol / bytes
+ *  / vec). Callers fail closed on null. */
+export declare function literalNumericBigInt(leaf: PredicateLeaf): bigint | null;

package/dist/synth/predicate-literals.js

@@ -0,0 +1,25 @@
+// src/synth/predicate-literals.ts - read scalar values out of predicate literal leaves.
+//
+// Small shared helpers for interpreting a `PredicateLeaf` literal. Kept out of
+// `evaluate.ts` so the evaluator stays focused on the deny-order semantics; the
+// deny-case generator uses the same reader so both sides agree on what a numeric
+// literal means.
+/** BigInt value of a numeric-integer literal leaf (`literal_i128` / `literal_u64`
+ *  / `literal_u32`), or null for a non-numeric literal (address / symbol / bytes
+ *  / vec). Callers fail closed on null. */
+export function literalNumericBigInt(leaf) {
+    switch (leaf.kind) {
+        case 'literal_i128':
+        case 'literal_u64':
+            try {
+                return BigInt(leaf.value);
+            }
+            catch {
+                return null;
+            }
+        case 'literal_u32':
+            return BigInt(leaf.value);
+        default:
+            return null;
+    }
+}

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

@@ -1,17 +1,49 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
-import type { ToolResponse } from '../errors.ts';
-import { type Network, type ProposedPolicy, type RecordedTransaction } from '../types.ts';
+import type { ToolError, ToolResponse } from '../errors.ts';
+import { type Network, type PredicateNode, type ProposedPolicy, type RecordedTransaction } from '../types.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
+ *  constraints OZ cannot express). */
+export interface InterpreterAdapterOptions {
+    /** The smart account this interpreter policy will be installed against.
+     *  Must be a C... contract address - the on-chain policy-bound account.
+     *  The G... source account from the recording is a separate concept. */
+    smartAccountAddress: string;
+    /** Per-rule install nonce (first install = 1). Defaults to 1. */
+    installNonce?: number;
+    /** Per-policy oracle overrides. Tighten-only vs the wasm defaults
+     *  (maxStalenessSeconds <= 600, maxDeviationBps <= 200); widening is
+     *  rejected at the options boundary. */
+    oracleParams?: {
+        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). `confidenceOverride` relaxes the recorder's
- *  gate. */
+ *  limitAmount, invocationLimit, oraclePriceBound, swapRecipientAllowlist).
+ *  `interpreter` opts the recording path into the interpreter adapter. */
 export interface SynthesizeFromRecordingOptions {
     network: Network;
     userResponses?: ComposeUserResponses;
     confidenceOverride?: {
         threshold: number;
     };
+    interpreter?: InterpreterAdapterOptions;
 }
-/** Synthesize a ProposedPolicy from a recorded transaction. */
 export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+/** 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;
+export { throwToolError };