@crediolabs/policy-synth 0.3.1 → 0.5.0

package/dist-cjs/run/schemas.js

@@ -16,7 +16,7 @@
 // imports them here so its tool-shape bindings stay in step; the CLI imports
 // them here so it can build the same args envelope the MCP transport builds.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolErrorSchema = exports.GetInterpreterInfoInputSchema = exports.RevokePolicyInputSchema = exports.InstallPolicyInputSchema = exports.NETWORK_PASSPHRASES = exports.RPC_URL_BY_NETWORK = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.MAINNET_RPC_URL = exports.TESTNET_RPC_URL = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.VerifyPolicyInputSchema = exports.SimulatePolicyInputSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.SynthesizePolicyInputSchema = exports.InterpreterOptionsSchema = exports.RecordTransactionInputSchema = exports.ComposeUserResponsesSchema = exports.RecordedTransactionSchema = exports.ParseConfidenceSchema = exports.OnChainEventSchema = exports.TokenMovementSchema = exports.ContractInvocationSchema = exports.ScValSchema = exports.NetworkSchema = void 0;
+exports.ToolErrorSchema = exports.GetInterpreterInfoInputSchema = exports.RevokePolicyInputSchema = exports.InstallPolicyInputSchema = exports.DeclarePolicyInputSchema = exports.NETWORK_PASSPHRASES = exports.RPC_URL_BY_NETWORK = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.MAINNET_RPC_URL = exports.TESTNET_RPC_URL = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.ObservedRuleSchema = exports.VerifyPolicyInputSchema = exports.SimulatePolicyInputSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.SynthesizePolicyInputSchema = exports.InterpreterOptionsSchema = exports.RecordTransactionInputSchema = exports.ComposeUserResponsesSchema = exports.RecordedTransactionSchema = exports.ParseConfidenceSchema = exports.OnChainEventSchema = exports.TokenMovementSchema = exports.ContractInvocationSchema = exports.ScValSchema = exports.NetworkSchema = void 0;
 const zod_1 = require("zod");
 const address_ts_1 = require("../synth/address.js");
 /** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
@@ -180,6 +180,15 @@ exports.PredicateLeafSchema = zod_1.z.lazy(() => zod_1.z.union([
         element: zod_1.z.number().int().nonnegative(),
         field: zod_1.z.string(),
     }),
+    // num/den are i128 decimal strings, matching `literal_i128`. The regex
+    // is the boundary guard; the ratio's SIGN is checked at encode, where
+    // the message can explain that a negative ratio inverts the comparison.
+    zod_1.z.object({
+        kind: zod_1.z.literal('call_arg_scaled'),
+        index: zod_1.z.number().int().nonnegative(),
+        num: zod_1.z.string().regex(/^-?[0-9]+$/),
+        den: zod_1.z.string().regex(/^-?[0-9]+$/),
+    }),
     zod_1.z.object({ kind: zod_1.z.literal('literal_address'), value: zod_1.z.string() }),
     zod_1.z.object({ kind: zod_1.z.literal('literal_i128'), value: zod_1.z.string().regex(/^-?[0-9]+$/) }),
     zod_1.z.object({ kind: zod_1.z.literal('literal_symbol'), value: zod_1.z.string() }),
@@ -198,16 +207,32 @@ exports.PredicateLeafSchema = zod_1.z.lazy(() => zod_1.z.union([
  *  `and`; the lazy + annotation pattern keeps the recursion type-safe. */
 exports.PredicateNodeSchema = zod_1.z.lazy(() => zod_1.z.union([
     zod_1.z.object({ op: zod_1.z.literal('and'), children: zod_1.z.array(exports.PredicateNodeSchema) }),
+    zod_1.z.object({ op: zod_1.z.literal('or'), children: zod_1.z.array(exports.PredicateNodeSchema) }),
     zod_1.z.object({
         op: zod_1.z.literal('eq'),
         left: exports.PredicateLeafSchema,
         right: exports.PredicateLeafSchema,
     }),
+    zod_1.z.object({
+        op: zod_1.z.literal('lt'),
+        left: exports.PredicateLeafSchema,
+        right: exports.PredicateLeafSchema,
+    }),
     zod_1.z.object({
         op: zod_1.z.literal('lte'),
         left: exports.PredicateLeafSchema,
         right: exports.PredicateLeafSchema,
     }),
+    zod_1.z.object({
+        op: zod_1.z.literal('gt'),
+        left: exports.PredicateLeafSchema,
+        right: exports.PredicateLeafSchema,
+    }),
+    zod_1.z.object({
+        op: zod_1.z.literal('gte'),
+        left: exports.PredicateLeafSchema,
+        right: exports.PredicateLeafSchema,
+    }),
     zod_1.z.object({
         op: zod_1.z.literal('in'),
         needle: exports.PredicateLeafSchema,
@@ -249,6 +274,26 @@ exports.VerifyPolicyInputSchema = exports.SimulatePolicyInputSchema;
  *  the temporal dead zone (no JS hoisting for `const`). */
 const MAX_SIGNERS_PER_RULE = 15;
 const MAX_POLICIES_PER_RULE = 5;
+const SignerDraftSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal('delegated'), address: zod_1.z.string() }),
+    zod_1.z.object({ kind: zod_1.z.literal('external'), verifier: zod_1.z.string(), keyBytes: zod_1.z.string() }),
+]);
+const ContextTypeSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal('default') }),
+    zod_1.z.object({ kind: zod_1.z.literal('call_contract'), contract: zod_1.z.string() }),
+    zod_1.z.object({ kind: zod_1.z.literal('create_contract'), wasmHash: zod_1.z.string() }),
+]);
+/** A rule ALREADY on the account, as the caller observed it. Supplying these
+ *  turns on the cross-rule authority scan: a signer belonging to several rules
+ *  picks which one applies, so a predicate only constrains a key when the
+ *  policed rule is the only rule that key is on. */
+exports.ObservedRuleSchema = zod_1.z.object({
+    id: zod_1.z.number().int().nonnegative(),
+    contextType: ContextTypeSchema,
+    signers: zod_1.z.array(SignerDraftSchema),
+    policyAddresses: zod_1.z.array(zod_1.z.string()),
+    predicate: exports.PredicateNodeSchema.optional(),
+});
 const ContextRuleDraftSchema = zod_1.z
     .object({
     contextRuleType: zod_1.z.discriminatedUnion('kind', [
@@ -283,23 +328,23 @@ const ContextRuleDraftSchema = zod_1.z
 // existing four.
 /** Pinned interpreter address (testnet).
  *  Single source for the MCP layer; do not embed elsewhere. */
-exports.PINNED_INTERPRETER_TESTNET_ADDRESS = 'CCL336TCK2Y5OFNRCMN2M3HVPBCEX4PW5H6EQ5VW5NPMXOCP4ESB5XR4';
-/** Pinned interpreter address (mainnet), redeployed 2026-08-22 from a reproducible build. The mainnet
+exports.PINNED_INTERPRETER_TESTNET_ADDRESS = 'CCBHVZ6HGGV7C4SNHCZ3S5665Z2WEMHTMBAEPO4XW6PKON464BEBANU5';
+/** Pinned interpreter address (mainnet), redeployed 2026-08-22 for grammar 4, from a reproducible build. The mainnet
  *  interpreter IS the binary exercised on testnet - both instances were created
  *  from the same uploaded wasm hash (see PINNED_INTERPRETER_WASM_SHA256), and
- *  both were read back with `grammar_version()` returning 3. The address differs
+ *  both were read back with `grammar_version()` returning 4. The address differs
  *  because instance ids are network-scoped. UNAUDITED at the time of writing.
  *
  *  These four constants move together or not at all. The grammar version and
  *  wasm hash are single values covering BOTH networks, so re-pinning one network
  *  alone would have the builder emit a version the other network refuses - with
  *  a green test run, since `grammar-version-parity.test.ts` would then pass. */
-exports.PINNED_INTERPRETER_MAINNET_ADDRESS = 'CBZXLSTQUITBFZHQH6XRXF3XIVRQR4RHRI64Q5WELS5KGY3ZKJPFWDPF';
+exports.PINNED_INTERPRETER_MAINNET_ADDRESS = 'CDN755TDYZM3ZQ5OXTJ6TIBUBWZV2KRI2BYJPBXD2MVWED4STT3VBN52';
 /** Pinned interpreter wasm sha256 (hex). */
-exports.PINNED_INTERPRETER_WASM_SHA256 = 'a2b36e8ac5a61caf3757af26aa79e83f2995b451099f44772383806a55fe3414';
+exports.PINNED_INTERPRETER_WASM_SHA256 = 'b5ba1e35ccf20cd8c13c3a2c3098bf337033a92bcaf475d63c03ddc0cba0fcae';
 /** The grammar version the interpreter enforces (matches SELF_VERSION in
  *  contracts/policy-interpreter/src/version.rs). */
-exports.PINNED_INTERPRETER_GRAMMAR_VERSION = 3;
+exports.PINNED_INTERPRETER_GRAMMAR_VERSION = 4;
 /** Default Soroban RPC for the install / revoke / info tools. The recorder
  *  keeps its own copy in record/rpc.ts because it hands back a fetcher rather
  *  than a Server; the two are deliberately different surfaces, so this is
@@ -338,8 +383,52 @@ exports.NETWORK_PASSPHRASES = {
 // `sourceAccount` is the signing wallet (G...).
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/;
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/;
+// ===== declare_policy =====
+//
+// The declarative front-end: the constraint stated outright, with no
+// transaction to decode. Deliberately NOT a revival of the removed
+// `MandateSpec` - that carried a rolling `spendingLimit` the interpreter
+// cannot evaluate and an `approvalThreshold` needing OZ primitives nobody
+// deployed. Only fields grammar 3 can actually enforce appear here.
+exports.DeclarePolicyInputSchema = zod_1.z
+    .object({
+    fn: zod_1.z.string().min(1, 'fn must name the method to pin'),
+    contract: zod_1.z
+        .string()
+        .regex(STELLAR_CONTRACT_ADDRESS, 'contract must be a Stellar contract address (C...)')
+        .optional(),
+    /** Smallest unit, unsigned decimal STRING - an i128 is wider than
+     *  Number.MAX_SAFE_INTEGER, so a number here would silently round. */
+    maxAmount: zod_1.z
+        .string()
+        .regex(/^[0-9]+$/, 'maxAmount must be an unsigned integer in the smallest unit')
+        .optional(),
+    amountArgIndex: zod_1.z.number().int().nonnegative().max(U32_MAX).optional(),
+    recipients: zod_1.z.array(zod_1.z.string()).min(1, 'recipients must not be empty').optional(),
+    recipientArgIndex: zod_1.z.number().int().nonnegative().max(U32_MAX).optional(),
+    allowZeroCap: zod_1.z.boolean().optional(),
+    /** Minimum output as a ratio of the call's own input. num/den are decimal
+     *  STRINGS for the same reason maxAmount is: an i128 ratio does not
+     *  survive a JS number. */
+    minOutputRatio: zod_1.z
+        .object({
+        num: zod_1.z.string().regex(/^[0-9]+$/, 'num must be an unsigned integer'),
+        den: zod_1.z.string().regex(/^[0-9]+$/, 'den must be an unsigned integer'),
+        inputArgIndex: zod_1.z.number().int().nonnegative().max(U32_MAX),
+        outputArgIndex: zod_1.z.number().int().nonnegative().max(U32_MAX),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
 exports.InstallPolicyInputSchema = zod_1.z
     .object({
+    /** Rules already on the account. Supplying them turns on the cross-rule
+     *  authority scan, which reports every existing rule a signer of this
+     *  install could name INSTEAD - including an unpoliced one, against which
+     *  the predicate never runs. Absent means the scan is skipped, and the
+     *  result says so rather than reporting "no overlaps found". */
+    existingRules: zod_1.z.array(exports.ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
     smartAccount: zod_1.z
         .string()

package/dist-cjs/simulate/deny-cases.js

@@ -205,11 +205,22 @@ function visit(node, facts) {
             for (const child of node.children)
                 visit(child, facts);
             return;
+        // NOT descended into. A deny case works by violating ONE constraint and
+        // asserting the predicate refuses the call. Violating one branch of an
+        // `or` proves nothing, because another branch can still permit, so the
+        // generated case would either fail or pass for the wrong reason. A sound
+        // deny case for a disjunction must violate EVERY branch at once, which
+        // this generator does not construct - so it emits none.
+        case 'or':
+            return;
         case 'in':
             facts.memberships.push(node);
             return;
         case 'eq':
+        case 'lt':
         case 'lte':
+        case 'gt':
+        case 'gte':
             facts.comparisons.push(node);
     }
 }

package/dist-cjs/simulate/evaluate.js

@@ -1,5 +1,5 @@
 "use strict";
-// src/simulate/evaluate.ts - TypeScript reference evaluator for grammar version 3.
+// src/simulate/evaluate.ts - TypeScript reference evaluator for grammar version 4.
 //
 // Pure function. Determinism: same `(predicate, ctx)` -> byte-identical result,
 // no clock, no randomness. Deny order (deny on FIRST violation, stable reason):
@@ -9,12 +9,13 @@
 //   3. `in` membership; empty haystack ALWAYS denies         -> 'NOT_IN_ALLOWLIST'
 //   4. otherwise permit.
 //
-// Grammar version 3 nodes: and, eq, lte
-// Grammar version 3 leaves: call_contract, call_fn, call_arg(i),
+// Grammar version 4 nodes: and, or, eq, lt, lte, gt, gte, in
+// Grammar version 4 leaves: call_contract, call_fn, call_arg(i),
 //   call_arg_len(i), call_arg_field(i, element, field),
+//   call_arg_scaled(i, num, den),
 //   literal_address, literal_i128, literal_symbol, literal_u32, literal_vec
-// Grammar version 3 deny reasons: ARG_MISMATCH, CONTRACT_SCOPE,
-//   UNSUPPORTED_NODE, NOT_IN_ALLOWLIST
+// Grammar version 4 deny reasons: ARG_MISMATCH, CONTRACT_SCOPE,
+//   ARITHMETIC_OVERFLOW, UNSUPPORTED_NODE, NOT_IN_ALLOWLIST, SLIPPAGE_FLOOR
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.evaluate = evaluate;
 /** Evaluate a `PredicateNode` against the candidate call described by `ctx`.
@@ -36,8 +37,25 @@ function walk(node, ctx) {
             }
             return lastDeny ?? { permit: true };
         }
+        // Permits on the first branch that holds; when none does, reports the
+        // FIRST branch's reason. Mirrors `Node::Or` in the Rust evaluator, which
+        // the conformance suite pins.
+        case 'or': {
+            let firstDeny = null;
+            for (const child of node.children) {
+                const r = walk(child, ctx);
+                if (r.permit)
+                    return r;
+                if (firstDeny === null)
+                    firstDeny = r;
+            }
+            return firstDeny ?? { permit: false, reason: 'UNSUPPORTED_NODE' };
+        }
         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);
@@ -45,6 +63,16 @@ function walk(node, ctx) {
 }
 /** Comparison leaf evaluation. */
 function evalCompare(op, left, right, ctx) {
+    // Scaled operands first, so the dedicated reasons reach the caller instead
+    // of a generic mismatch. Right-hand dispatch leads because
+    // `out >= in * num / den` is the canonical swap form. Mirrors the order in
+    // `eval_compare` on the Rust side.
+    if (right.kind === 'call_arg_scaled') {
+        return evalScaledCompare(op, left, right, true, ctx);
+    }
+    if (left.kind === 'call_arg_scaled') {
+        return evalScaledCompare(op, right, left, false, ctx);
+    }
     // CONTRACT_SCOPE on call_contract eq
     if (left.kind === 'call_contract' && op === 'eq') {
         if (right.kind !== 'literal_address')
@@ -99,6 +127,53 @@ function evalCompare(op, left, right, ctx) {
     // Unknown leaf/op combination - structural fail-closed.
     return { permit: false, reason: 'UNSUPPORTED_NODE' };
 }
+/** i128 bounds. The contract computes in i128 and denies on overflow, so the
+ *  reference has to draw the same line or the two layers disagree on inputs
+ *  near the boundary. */
+const I128_MIN = -(2n ** 127n);
+const I128_MAX = 2n ** 127n - 1n;
+/** Comparison where one side is `call_arg_scaled`. Mirrors
+ *  `eval_scaled_arg_compare`: `args[index] * num / den` truncating toward
+ *  zero, ARITHMETIC_OVERFLOW on arithmetic that does not fit or a zero
+ *  denominator, SLIPPAGE_FLOOR on a comparison that simply fails. */
+function evalScaledCompare(op, other, scaled, scaledOnRight, ctx) {
+    // Chaining two computed operands has no meaning a review card could state.
+    if (other.kind === 'call_arg_scaled')
+        return { permit: false, reason: 'UNSUPPORTED_NODE' };
+    // Could not READ the operand is a different failure from read-and-missed.
+    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' };
+    }
+    if (den === 0n)
+        return { permit: false, reason: 'ARITHMETIC_OVERFLOW' };
+    const product = input * num;
+    if (product < I128_MIN || product > I128_MAX) {
+        return { permit: false, reason: 'ARITHMETIC_OVERFLOW' };
+    }
+    // BigInt division already truncates toward zero, matching i128 semantics.
+    const quotient = product / den;
+    if (quotient < I128_MIN || quotient > I128_MAX) {
+        return { permit: false, reason: 'ARITHMETIC_OVERFLOW' };
+    }
+    const otherVal = other.kind === 'call_arg'
+        ? argNumericBigInt(ctx.args[other.index])
+        : literalNumericBigInt(other);
+    if (otherVal === null)
+        return { permit: false, reason: 'ARG_MISMATCH' };
+    const [a, b] = scaledOnRight ? [otherVal, quotient] : [quotient, otherVal];
+    return bigintCmp(op, a.toString(), b.toString())
+        ? { permit: true }
+        : { permit: false, reason: 'SLIPPAGE_FLOOR' };
+}
 /** 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. */
@@ -268,7 +343,13 @@ function bigintCmp(op, aStr, 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/declare.d.ts

@@ -0,0 +1,43 @@
+import type { PredicateNode } from '../types.ts';
+export interface PolicyDeclaration {
+    /** Method to pin. Required: a predicate with no selector leaf constrains
+     *  nothing and the contract refuses it at install. */
+    fn: string;
+    /** Contract to pin, already resolved to a `C...` address. */
+    contract?: string;
+    /** Upper bound on the call's amount argument, in the token's SMALLEST
+     *  unit as an unsigned decimal string (25 XLM = "250000000"). */
+    maxAmount?: string;
+    /** Which argument carries the amount. Defaults to the SEP-41 position. */
+    amountArgIndex?: number;
+    /** Recipient allowlist. */
+    recipients?: string[];
+    /** Which argument carries the recipient. Defaults to the SEP-41 position. */
+    recipientArgIndex?: number;
+    /** A cap of "0" denies every call, so it is refused unless asked for
+     *  explicitly. A rule that permits nothing is a plausible thing to want and
+     *  an implausible thing to want by accident. */
+    allowZeroCap?: boolean;
+    /** Minimum output as a ratio of the call's own input: the output argument
+     *  must be at least `input * num / den`.
+     *
+     *  A swap's acceptable output depends on the size of the trade, so a fixed
+     *  floor would pin the policy to one trade size. The ratio is DECLARED, never
+     *  inferred from a recording: a recorded rate is a price at one moment, and
+     *  freezing it as policy would deny ordinary trades later. */
+    minOutputRatio?: {
+        num: string;
+        den: string;
+        inputArgIndex: number;
+        outputArgIndex: number;
+    };
+}
+export interface DeclaredPredicate {
+    predicate: PredicateNode;
+    /** Assumptions the caller should check. Never empty when an argument index
+     *  was defaulted rather than supplied. */
+    warnings: string[];
+}
+/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+ *  the same declaration always produces the same predicate. */
+export declare function declarePredicate(d: PolicyDeclaration): DeclaredPredicate;

package/dist-cjs/synth/declare.js

@@ -0,0 +1,130 @@
+"use strict";
+// src/synth/declare.ts - build a predicate from a DECLARED constraint.
+//
+// The second synthesis front-end, beside `synthesizeFromRecording`. That one
+// infers a predicate from a transaction that happened; this one takes the
+// constraint the user states outright. No transaction, no decoding, no
+// inference, no RPC: the same declaration always lowers to a byte-identical
+// predicate.
+//
+// This is the surviving half of the removed `MandateSpec`. Two of that type's
+// five fields lowered to things that do not exist - `spendingLimit` became a
+// `window_spent` compare the interpreter cannot evaluate (it is handed one
+// call and keeps no state), and `approvalThreshold` needed OZ built-in policy
+// contracts that were never deployed. Both are deliberately absent here, and
+// the per-call `maxAmount` bound below is the honest replacement for the
+// first: it constrains the amount in THIS call rather than implying a rolling
+// total nothing tracks.
+//
+// What a declaration can say maps one-to-one onto grammar 4:
+//   fn            -> eq(call_fn, literal_symbol)
+//   contract      -> eq(call_contract, literal_address)
+//   maxAmount     -> lte(call_arg(i), literal_i128)
+//   recipients    -> in(call_arg(j), [literal_address, ...])
+//   minOutputRatio-> gte(call_arg(out), call_arg_scaled(in, num, den))
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.declarePredicate = declarePredicate;
+const address_ts_1 = require("./address.js");
+/** Argument positions of the SEP-41 `transfer(from, to, amount)` shape. A
+ *  declaration that names a different method almost certainly has different
+ *  positions, which is why using either default emits a warning naming the
+ *  index it assumed - a bound on the wrong argument constrains something the
+ *  user did not mean and fails silently. */
+const SEP41_RECIPIENT_ARG = 1;
+const SEP41_AMOUNT_ARG = 2;
+/** Lower a declared constraint to a grammar-3 predicate. Pure and total:
+ *  the same declaration always produces the same predicate. */
+function declarePredicate(d) {
+    if (!d.fn || d.fn.trim() === '') {
+        throw declareError('SYNTHESIS_ERROR', 'a declaration needs `fn`: the method to pin');
+    }
+    const warnings = [];
+    const children = [
+        { op: 'eq', left: { kind: 'call_fn' }, right: { kind: 'literal_symbol', value: d.fn } },
+    ];
+    if (d.contract !== undefined) {
+        if (!(0, address_ts_1.isStellarAddress)(d.contract) || !d.contract.startsWith('C')) {
+            throw declareError('SYNTHESIS_ERROR', `contract must be a Stellar contract address (C...), got ${d.contract}`);
+        }
+        children.push({
+            op: 'eq',
+            left: { kind: 'call_contract' },
+            right: { kind: 'literal_address', value: d.contract },
+        });
+    }
+    if (d.recipients !== undefined) {
+        if (d.recipients.length === 0) {
+            throw declareError('SYNTHESIS_ERROR', 'recipients was supplied but empty; an empty `in` haystack is refused at decode. Omit it to leave recipients unconstrained.');
+        }
+        for (const r of d.recipients) {
+            if (!(0, address_ts_1.isStellarAddress)(r)) {
+                throw declareError('SYNTHESIS_ERROR', `recipient is not a Stellar address: ${r}`);
+            }
+        }
+        const idx = d.recipientArgIndex ?? SEP41_RECIPIENT_ARG;
+        if (d.recipientArgIndex === undefined) {
+            warnings.push(`recipient allowlist bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the recipient elsewhere this constrains the wrong argument - pass recipientArgIndex.`);
+        }
+        children.push({
+            op: 'in',
+            needle: { kind: 'call_arg', index: idx },
+            haystack: d.recipients.map((value) => ({ kind: 'literal_address', value })),
+        });
+    }
+    if (d.maxAmount !== undefined) {
+        if (!/^[0-9]+$/.test(d.maxAmount)) {
+            throw declareError('SYNTHESIS_ERROR', `maxAmount must be an unsigned integer in the token's smallest unit, got "${d.maxAmount}" (25 XLM = "250000000")`);
+        }
+        if (d.maxAmount === '0' && d.allowZeroCap !== true) {
+            throw declareError('SYNTHESIS_ERROR', 'maxAmount "0" denies every call: no amount satisfies the bound. Set allowZeroCap to declare that deliberately.');
+        }
+        const idx = d.amountArgIndex ?? SEP41_AMOUNT_ARG;
+        if (d.amountArgIndex === undefined) {
+            warnings.push(`amount cap bound to call_arg(${idx}), the SEP-41 \`transfer\` position. If \`${d.fn}\` carries the amount elsewhere this caps the wrong argument - pass amountArgIndex.`);
+        }
+        children.push({
+            op: 'lte',
+            left: { kind: 'call_arg', index: idx },
+            right: { kind: 'literal_i128', value: d.maxAmount },
+        });
+    }
+    if (d.minOutputRatio !== undefined) {
+        const { num, den, inputArgIndex, outputArgIndex } = d.minOutputRatio;
+        if (!/^[0-9]+$/.test(num) || !/^[0-9]+$/.test(den)) {
+            throw declareError('SYNTHESIS_ERROR', `minOutputRatio num/den must be unsigned integers, got "${num}"/"${den}" (a 1% slippage tolerance is num "99", den "100")`);
+        }
+        // Both are refused on chain at install (INVALID_SCALED_RATIO). Refusing
+        // here too means the caller learns before a transaction is built.
+        if (den === '0') {
+            throw declareError('SYNTHESIS_ERROR', 'minOutputRatio.den is zero: the ratio has no value');
+        }
+        if (num === '0') {
+            throw declareError('SYNTHESIS_ERROR', 'minOutputRatio.num is zero: the floor would be zero, which constrains nothing. Omit it instead.');
+        }
+        if (inputArgIndex === outputArgIndex) {
+            throw declareError('SYNTHESIS_ERROR', `minOutputRatio bounds arg[${inputArgIndex}] against itself, which is true for any ratio at or below 1 and false above it - never a slippage floor. Pass the distinct input and output positions.`);
+        }
+        if (BigInt(num) > BigInt(den)) {
+            // Demanding MORE out than went in is not slippage protection; it is a
+            // rule that denies every honest trade. Loud beats a policy that never
+            // permits.
+            warnings.push(`minOutputRatio ${num}/${den} is above 1: it requires the output to EXCEED the input, which no ordinary swap satisfies. Check the ratio is not inverted.`);
+        }
+        children.push({
+            op: 'gte',
+            left: { kind: 'call_arg', index: outputArgIndex },
+            right: { kind: 'call_arg_scaled', index: inputArgIndex, num, den },
+        });
+    }
+    // A single conjunct is emitted bare. `and` with one child encodes to
+    // different bytes than the child alone, and the extra node buys nothing.
+    const predicate = children.length === 1 ? children[0] : { op: 'and', children };
+    return { predicate, warnings };
+}
+function declareError(code, message) {
+    const err = new Error(message);
+    err.code = code;
+    err.severity = 'error';
+    err.retryable = false;
+    throw err;
+}

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

@@ -1,5 +1,6 @@
 export { isStellarAddress } from './address.ts';
 export { type ComposeOptions, type ComposeResult, composeFromRecording, } from './compose-from-recording.ts';
+export { type DeclaredPredicate, declarePredicate, type PolicyDeclaration, } from './declare.ts';
 export { type IntentFacts, lower } from './lower.ts';
 export { type DecideScopeOptions, decideScope, type ScopeDecision, scopeToContextRuleType, } from './scope.ts';
 export { type __TestInterpreterAdapterOptions, type SynthesizeFromRecordingOptions, synthesizeFromRecording, } from './synthesize-from-recording.ts';

package/dist-cjs/synth/index.js

@@ -1,7 +1,7 @@
 "use strict";
 // src/synth/index.ts - re-export the synthesizer front-ends.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.synthesizeFromRecording = exports.scopeToContextRuleType = exports.decideScope = exports.lower = exports.composeFromRecording = exports.isStellarAddress = void 0;
+exports.synthesizeFromRecording = exports.scopeToContextRuleType = exports.decideScope = exports.lower = exports.declarePredicate = exports.composeFromRecording = exports.isStellarAddress = void 0;
 // Exported because `swapRecipientAllowlist` is part of the public synthesis
 // input: a caller assembling one needs the same validator the schema applies,
 // and re-deriving it elsewhere means a second address check that can drift.
@@ -9,6 +9,8 @@ var address_ts_1 = require("./address.js");
 Object.defineProperty(exports, "isStellarAddress", { enumerable: true, get: function () { return address_ts_1.isStellarAddress; } });
 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 declare_ts_1 = require("./declare.js");
+Object.defineProperty(exports, "declarePredicate", { enumerable: true, get: function () { return declare_ts_1.declarePredicate; } });
 var lower_ts_1 = require("./lower.js");
 Object.defineProperty(exports, "lower", { enumerable: true, get: function () { return lower_ts_1.lower; } });
 var scope_ts_1 = require("./scope.js");

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

@@ -2,7 +2,7 @@
 // src/synth/synthesize-from-recording.ts - recording-path orchestrator.
 //
 // `synthesizeFromRecording` INFERS a bounded policy from a `RecordedTransaction`
-// via the `PolicyIR` + interpreter adapter pair.
+// via the composer + interpreter adapter pair.
 // Flow: validate -> parseConfidence gate -> lower -> decideScope -> composeFromRecording
 // -> interpreter compile + self-verify.
 // Same (tx, opts) -> byte-identical ProposedPolicy (no randomness, clock, globals).

package/dist-cjs/types.d.ts

@@ -124,7 +124,7 @@ export type PolicyRef = {
  *  `contracts/policy-interpreter/src/version.rs`. Every value this package puts on
  *  the wire derives from here; `grammar-version-parity.test.ts` pins it to the
  *  contract so a skew cannot pass a green test run. */
-export declare const GRAMMAR_VERSION: 3;
+export declare const GRAMMAR_VERSION: 4;
 /** A serialised predicate document stored against a (smart_account, rule_id) pair. */
 export interface PolicyDocument {
     /** Grammar version baked into the interpreter wasm. Fail-closed strict match at install
@@ -146,14 +146,29 @@ export interface PolicyDocument {
 export type PredicateNode = {
     op: 'and';
     children: PredicateNode[];
+} | {
+    op: 'or';
+    children: PredicateNode[];
 } | {
     op: 'eq';
     left: PredicateLeaf;
     right: PredicateLeaf;
+} | {
+    op: 'lt';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
 } | {
     op: 'lte';
     left: PredicateLeaf;
     right: PredicateLeaf;
+} | {
+    op: 'gt';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
+} | {
+    op: 'gte';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
 } | {
     op: 'in';
     needle: PredicateLeaf;
@@ -174,6 +189,11 @@ export type PredicateLeaf = {
     index: number;
     element: number;
     field: string;
+} | {
+    kind: 'call_arg_scaled';
+    index: number;
+    num: string;
+    den: string;
 } | {
     kind: 'literal_address';
     value: string;

package/dist-cjs/types.js

@@ -55,4 +55,4 @@ exports.PREDICATE_CAPS = {
  *  `contracts/policy-interpreter/src/version.rs`. Every value this package puts on
  *  the wire derives from here; `grammar-version-parity.test.ts` pins it to the
  *  contract so a skew cannot pass a green test run. */
-exports.GRAMMAR_VERSION = 3;
+exports.GRAMMAR_VERSION = 4;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",

package/src/adapters/interpreter/adapter.ts

@@ -1,6 +1,6 @@
-// src/adapters/interpreter/adapter.ts - the interpreter-policy CustodyAdapter.
+// src/adapters/interpreter/adapter.ts - the interpreter-policy adapter.
 //
-// Compiles a PolicyIR to a single interpreter `PolicyDocument` + `PolicyRef`
+// Compiles a `ComposedRule` to a single interpreter `PolicyDocument` + `PolicyRef`
 // carrying the canonical predicate encoding from `predicate/encode.ts`. This is
 // the only backend; the compose step lowers every constraint to it.
 //
@@ -41,9 +41,9 @@ export interface InterpreterAdapterConfig {
   smartAccountAddress: string
 }
 
-/** The result of compiling a PolicyIR for this backend. */
+/** The result of compiling a `ComposedRule` for this backend. */
 export interface CompileResult {
-  /** false => some IR construct this backend cannot express (see `uncovered`). */
+  /** false => some constraint this backend cannot express (see `uncovered`). */
   covered: boolean
   /** Human-readable list of unsupported constructs. */
   uncovered: string[]
@@ -195,14 +195,22 @@ function assertNoSelfCall(node: PredicateNode, config: InterpreterAdapterConfig)
     }
   }
   switch (node.op) {
+    // Both boolean nodes recurse. `or` is listed explicitly rather than left
+    // to a default branch: this is a security check, and a new node kind must
+    // fail to compile here rather than silently skip it.
     case 'and':
+    case 'or':
       for (const c of node.children) assertNoSelfCall(c, config)
       return
     case 'in':
       // The needle is a selector; only the haystack carries literals.
       for (const h of node.haystack) checkLeaf(h)
       return
-    default:
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
       checkLeaf(node.left)
       checkLeaf(node.right)
   }