@crediolabs/policy-synth 0.1.4 → 0.1.5

package/dist-cjs/synth/evaluate.js

@@ -0,0 +1,428 @@
+"use strict";
+// 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).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluate = evaluate;
+const predicate_literals_ts_1 = require("./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 }`. */
+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 = (0, predicate_literals_ts_1.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-cjs/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-cjs/synth/harness.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHarness = runHarness;
+const evaluate_ts_1 = require("./evaluate.js");
+/** Evaluate the intended call and every generated denial without side effects. */
+function runHarness(predicate, cases) {
+    const failures = [];
+    const permitResult = (0, evaluate_ts_1.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 = (0, evaluate_ts_1.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-cjs/synth/index.d.ts

@@ -0,0 +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-cjs/synth/index.js

@@ -0,0 +1,23 @@
+"use strict";
+// src/synth/index.ts - re-export the synthesizer front-ends.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeFromRecording = exports.synthesizeFromMandate = exports.scopeToContextRuleType = exports.decideScope = exports.minimize = exports.lower = exports.runHarness = exports.evaluate = exports.generateCases = exports.composeFromRecording = void 0;
+var compose_from_recording_ts_1 = require("./compose-from-recording.js");
+Object.defineProperty(exports, "composeFromRecording", { enumerable: true, get: function () { return compose_from_recording_ts_1.composeFromRecording; } });
+var deny_cases_ts_1 = require("./deny-cases.js");
+Object.defineProperty(exports, "generateCases", { enumerable: true, get: function () { return deny_cases_ts_1.generateCases; } });
+var evaluate_ts_1 = require("./evaluate.js");
+Object.defineProperty(exports, "evaluate", { enumerable: true, get: function () { return evaluate_ts_1.evaluate; } });
+var harness_ts_1 = require("./harness.js");
+Object.defineProperty(exports, "runHarness", { enumerable: true, get: function () { return harness_ts_1.runHarness; } });
+var lower_ts_1 = require("./lower.js");
+Object.defineProperty(exports, "lower", { enumerable: true, get: function () { return lower_ts_1.lower; } });
+var minimize_ts_1 = require("./minimize.js");
+Object.defineProperty(exports, "minimize", { enumerable: true, get: function () { return minimize_ts_1.minimize; } });
+var scope_ts_1 = require("./scope.js");
+Object.defineProperty(exports, "decideScope", { enumerable: true, get: function () { return scope_ts_1.decideScope; } });
+Object.defineProperty(exports, "scopeToContextRuleType", { enumerable: true, get: function () { return scope_ts_1.scopeToContextRuleType; } });
+var synthesize_from_mandate_ts_1 = require("./synthesize-from-mandate.js");
+Object.defineProperty(exports, "synthesizeFromMandate", { enumerable: true, get: function () { return synthesize_from_mandate_ts_1.synthesizeFromMandate; } });
+var synthesize_from_recording_ts_1 = require("./synthesize-from-recording.js");
+Object.defineProperty(exports, "synthesizeFromRecording", { enumerable: true, get: function () { return synthesize_from_recording_ts_1.synthesizeFromRecording; } });

package/dist-cjs/synth/lower.d.ts

@@ -0,0 +1,23 @@
+import type { RecordedTransaction } from '../types.ts';
+/** Facts the recording-path synth reasons over. */
+export interface IntentFacts {
+    callTargets: string[];
+    functionsByContract: Record<string, string[]>;
+    /** Aggregate outgoing spend per token (i128-safe decimal string). A single
+     *  token entry is the prerequisite for `spending_limit`. Movements
+     *  with from != sourceAccount are NOT counted as "spend" by this synth
+     *  (incoming yield, refund, etc.). */
+    spendByToken: Record<string, string>;
+    signers: string[];
+    /** Set when more than one top-level invocation shares a target contract
+     *  (a router); decideScope uses this to scope by the router instead of
+     *  returning SCOPE_UNRESOLVED. */
+    sharedRouter?: string;
+    /** Router hop paths, keyed by target contract. SoroSwap exposes its `path`
+     *  arg directly on the top-level call; this is the input the compose step
+     *  passes to a per-arg `in` condition (flagged as not covered by the OZ adapter). */
+    allowedPaths?: Record<string, string[][]>;
+}
+/** Lower a recorded transaction to the canonical IntentFacts. Pure (no
+ *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts. */
+export declare function lower(tx: RecordedTransaction): IntentFacts;

package/dist-cjs/synth/lower.js

@@ -0,0 +1,119 @@
+"use strict";
+// src/synth/lower.ts - lower a RecordedTransaction to IntentFacts.
+//
+// Reads the top-level invocations only (the single authorized call that
+// `Policy::enforce` receives; v1 grammar does not walk sub-invocations) and
+// the recorded token movements. Produces the deterministic facts the synth
+// reasons over: distinct call targets, functions per target, cumulative spend
+// per token (outgoing movements from the recorded source account only),
+// authorising signers, an optional shared-router marker when multiple top-level
+// invocations hit the same contract, and the per-contract hop-path lists for
+// router calls (SoroSwap `path`).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lower = lower;
+/** Lower a recorded transaction to the canonical IntentFacts. Pure (no
+ *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts. */
+function lower(tx) {
+    const invocations = tx.invocations;
+    const callTargets = uniqueOrdered(invocations.map((i) => i.contract));
+    const functionsByContract = groupFunctionsByContract(invocations);
+    const spendByToken = aggregateOutgoingSpend(tx.tokenMovements, tx.sourceAccount);
+    const allowedPaths = extractPathsByContract(invocations);
+    const sharedRouter = inferSharedRouter(invocations);
+    const facts = {
+        callTargets,
+        functionsByContract,
+        spendByToken,
+        signers: [...tx.signers],
+    };
+    if (sharedRouter)
+        facts.sharedRouter = sharedRouter;
+    if (Object.keys(allowedPaths).length > 0)
+        facts.allowedPaths = allowedPaths;
+    return facts;
+}
+/** Preserve first-seen ordering, drop duplicates. */
+function uniqueOrdered(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (seen.has(item))
+            continue;
+        seen.add(item);
+        out.push(item);
+    }
+    return out;
+}
+/** Group the function names invoked per top-level contract. Order preserved
+ *  per contract in first-seen order. */
+function groupFunctionsByContract(invocations) {
+    const out = {};
+    for (const inv of invocations) {
+        const existing = out[inv.contract] ?? [];
+        if (!existing.includes(inv.fn))
+            existing.push(inv.fn);
+        out[inv.contract] = existing;
+    }
+    return out;
+}
+/** Sum outgoing TokenMovement amounts per token, where `from === source`.
+ *  BigInt throughout; never lossy. Movements whose `from` does not match the
+ *  recorded source account are NOT counted (incoming yield, refund, etc.). */
+function aggregateOutgoingSpend(movements, sourceAccount) {
+    const totals = new Map();
+    for (const m of movements) {
+        if (m.from !== sourceAccount)
+            continue;
+        const current = totals.get(m.token) ?? 0n;
+        totals.set(m.token, current + BigInt(m.amount));
+    }
+    const out = {};
+    for (const [token, total] of totals) {
+        out[token] = total.toString();
+    }
+    return out;
+}
+/** Walk the top-level invocations looking for a `vec` arg whose elements are
+ *  addresses (the SoroSwap `path` shape). Only the FIRST arg in each
+ *  invocation is examined in v1 - the recorder emits the top-level args
+ *  in declaration order and the only contract-call convention we bind by is
+ *  the router's first vec-arg path. */
+function extractPathsByContract(invocations) {
+    const out = {};
+    for (const inv of invocations) {
+        const path = findAddressVec(inv.args);
+        if (path) {
+            const existing = out[inv.contract] ?? [];
+            existing.push(path);
+            out[inv.contract] = existing;
+        }
+    }
+    return out;
+}
+function findAddressVec(args) {
+    for (const arg of args) {
+        if (arg.type === 'vec') {
+            const addresses = arg.value.filter((v) => v.type === 'address');
+            if (addresses.length === arg.value.length && addresses.length > 0) {
+                return addresses.map((a) => a.value);
+            }
+        }
+    }
+    return null;
+}
+/** When multiple top-level invocations share the same target contract, that
+ *  contract is the shared router. Single-call transactions return undefined
+ *  (the default flow doesn't need the marker). */
+function inferSharedRouter(invocations) {
+    if (invocations.length < 2)
+        return undefined;
+    const counts = new Map();
+    for (const inv of invocations) {
+        counts.set(inv.contract, (counts.get(inv.contract) ?? 0) + 1);
+    }
+    for (const [contract, count] of counts) {
+        if (count >= 2)
+            return contract;
+    }
+    return undefined;
+}

package/dist-cjs/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;