@crediolabs/policy-synth 0.1.3 → 0.1.4

package/dist/codegen/compile-gate.js

@@ -0,0 +1,119 @@
+// src/codegen/compile-gate.ts - toolchain-gated `cargo check` for the
+// codegen escape hatch.
+//
+// The escape hatch ships as the `policy-builder escape-hatch` CLI subcommand
+// (a later phase). This gate is its safety net, NOT the happy path. Property:
+// generated Rust compiles against the pinned OZ crate; broken source returns
+// `COMPILE_GATE_FAILED` with `stderr`; an absent toolchain returns `SKIPPED`
+// (does NOT fail - we cannot make build tools a hard runtime requirement for
+// a TypeScript package).
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Probe the host for the Rust toolchain the gate requires. We require BOTH
+ *  `cargo` AND `stellar` (the Soroban CLI) because a real gate run invokes
+ *  `stellar contract build`; absent either, the gate returns `SKIPPED`. */
+export async function hasRustToolchain() {
+    const probe = await probeToolchain();
+    return probe.present;
+}
+async function probeToolchain() {
+    const cargo = await which('cargo');
+    if (!cargo)
+        return { present: false, reason: 'cargo not found on PATH' };
+    const stellar = await which('stellar');
+    if (!stellar)
+        return { present: false, reason: 'stellar not found on PATH' };
+    return { present: true, reason: `${cargo} + ${stellar}` };
+}
+async function which(bin) {
+    try {
+        const out = await runProcess('sh', ['-c', `command -v ${bin}`], { capture: true });
+        const path = out.stdout.trim();
+        return path.length > 0 ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+function runProcess(cmd, args, opts) {
+    return new Promise((resolve, reject) => {
+        if (opts.signal?.aborted) {
+            reject(new Error('aborted'));
+            return;
+        }
+        const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (b) => {
+            stdout += b.toString('utf8');
+        });
+        child.stderr.on('data', (b) => {
+            stderr += b.toString('utf8');
+        });
+        const onAbort = () => {
+            child.kill('SIGTERM');
+            reject(new Error('aborted'));
+        };
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        child.on('error', (e) => {
+            opts.signal?.removeEventListener('abort', onAbort);
+            reject(e);
+        });
+        child.on('close', (code) => {
+            opts.signal?.removeEventListener('abort', onAbort);
+            resolve({ stdout, stderr, code: code ?? -1 });
+        });
+    });
+}
+const CARGO_MANIFEST = `[package]
+name = "escape-hatch-gate"
+version = "0.0.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+soroban-sdk = "22"
+
+[workspace]
+`;
+/** Compile-check a Rust source string against the pinned Soroban SDK.
+ *
+ *  - Toolchain absent -> `{ code: 'SKIPPED', reason }` (NOT a failure).
+ *  - Toolchain present, source compiles -> `{ code: 'COMPILE_OK' }`.
+ *  - Toolchain present, source broken -> `{ code: 'COMPILE_GATE_FAILED', stderr }`.
+ *
+ *  The gate writes the source to a temporary crate and runs `cargo check`
+ *  against it; the crate is cleaned up whether or not compilation succeeds.
+ *  The caller is expected to surface `COMPILE_GATE_FAILED.stderr` to the
+ *  user (the LLM agent) so the user can iterate. */
+export async function compileCheck(rustSource, opts = {}) {
+    if (opts.signal?.aborted) {
+        return { code: 'SKIPPED', reason: 'aborted before probe' };
+    }
+    const probe = await probeToolchain();
+    if (!probe.present) {
+        return { code: 'SKIPPED', reason: probe.reason };
+    }
+    let dir = null;
+    try {
+        dir = await mkdtemp(join(opts.tempDir ?? tmpdir(), 'codegen-gate-'));
+        await writeFile(join(dir, 'Cargo.toml'), CARGO_MANIFEST);
+        await writeFile(join(dir, 'lib.rs'), rustSource);
+        const runOpts = opts.signal ? { signal: opts.signal } : {};
+        const result = await runProcess(opts.cargoBin ?? 'cargo', ['check', '--quiet', '--offline', '--manifest-path', join(dir, 'Cargo.toml')], runOpts).catch((e) => ({ stdout: '', stderr: e.message, code: -1 }));
+        if (result.code === 0) {
+            return { code: 'COMPILE_OK' };
+        }
+        return { code: 'COMPILE_GATE_FAILED', stderr: result.stderr || result.stdout };
+    }
+    finally {
+        if (dir) {
+            await rm(dir, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}

package/dist/codegen/index.d.ts

@@ -0,0 +1,2 @@
+export { type CompileGateOpts, type CompileGateResult, compileCheck, hasRustToolchain, } from './compile-gate.ts';
+export { type EscapeHatchSpec, generateRust, } from './template.ts';

package/dist/codegen/index.js

@@ -0,0 +1,8 @@
+// src/codegen/index.ts - re-export the codegen escape-hatch surface.
+//
+// The escape hatch is OUT of the audited happy path: the synthesiser never
+// calls `generateRust` itself; the CLI subcommand (a later phase) is the only
+// entry point. Keeping the surface in one file makes that boundary visible
+// in import statements.
+export { compileCheck, hasRustToolchain, } from "./compile-gate.js";
+export { generateRust, } from "./template.js";

package/dist/codegen/template.d.ts

@@ -0,0 +1,18 @@
+/** A small typed description of one uncovered constraint the v1 DSL refused
+ *  to express. The synthesiser surfaces these from `CompileResult.uncovered`
+ *  and the codegen escape hatch wraps them into a hand-auditable skeleton. */
+export interface EscapeHatchSpec {
+    /** Address of the policy contract the skeleton is generated for. */
+    contract: string;
+    /** The trait method the predicate lives inside (default: 'enforce'). */
+    fnName?: string;
+    /** Human-readable description of each construct the DSL could not cover. */
+    uncovered: string[];
+}
+/** Generate a deterministic OZ `Policy` skeleton for an uncovered constraint.
+ *
+ *  The skeleton is NOT a finished policy; the user fills in the predicate
+ *  logic in the marked TODO(user) holes and audits the result themselves.
+ *
+ *  Same `(spec, name)` always produces byte-identical output. */
+export declare function generateRust(spec: EscapeHatchSpec, name: string): string;

package/dist/codegen/template.js

@@ -0,0 +1,131 @@
+// src/codegen/template.ts - deterministic Rust source generator for the OZ
+// `Policy` escape-hatch skeleton.
+//
+// This is the LAST-RESORT tool for constraints the v1 DSL cannot express. It
+// lives OUT of the audited happy-path surface; the synthesiser never emits it
+// automatically. It mirrors Zodiac Roles' `Custom` operator: a hand-written
+// (here: scaffolded) policy the operator assumes responsibility for.
+//
+// The skeleton carries five storage invariants the user MUST preserve when
+// filling in the predicate logic:
+//   1. `smart_account.require_auth()` is invoked INSIDE `enforce`.
+//   2. Storage is keyed by the composite `(smart_account, rule_id)`.
+//   3. Chain reads use `unwrap_or_default()` so a missing key is a permitted
+//      default, not a panic.
+//   4. Storage is `persistent()` (NOT `instance()`) so the policy survives
+//      contract instance lifecycle changes.
+//   5. `uninstall` removes the stored state.
+//
+// Determinism: same `(spec, name)` -> byte-identical output. No clock, no RNG,
+// no environment reads.
+/** Format a name for use as a Rust identifier. The input is constrained by
+ *  the caller (a kebab-case policy name + alphanumeric addresses); this is a
+ *  belt-and-braces sanitiser that maps anything non-identifier to '_'. */
+function asRustIdent(s) {
+    let out = '';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s.charCodeAt(i);
+        const ok = (ch >= 48 && ch <= 57) || // 0-9
+            (ch >= 65 && ch <= 90) || // A-Z
+            (ch >= 97 && ch <= 122) || // a-z
+            ch === 95; // _
+        out += ok ? s[i] : '_';
+    }
+    // Identifiers may not start with a digit.
+    if (out.length > 0 && out.charCodeAt(0) >= 48 && out.charCodeAt(0) <= 57) {
+        out = `_${out}`;
+    }
+    return out || 'policy';
+}
+/** Render the `uncovered` list as a `//` comment block (one line per item). */
+function renderUncovered(uncovered) {
+    if (uncovered.length === 0) {
+        return '    // (no specific uncovered constructs reported)';
+    }
+    return uncovered.map((line) => `    // - ${line}`).join('\n');
+}
+/** Generate a deterministic OZ `Policy` skeleton for an uncovered constraint.
+ *
+ *  The skeleton is NOT a finished policy; the user fills in the predicate
+ *  logic in the marked TODO(user) holes and audits the result themselves.
+ *
+ *  Same `(spec, name)` always produces byte-identical output. */
+export function generateRust(spec, name) {
+    const contract = spec.contract;
+    const fnName = spec.fnName ?? 'enforce';
+    const structName = asRustIdent(name);
+    const dataKeyName = `${asRustIdent(name)}_data`;
+    const uncoveredBlock = renderUncovered(spec.uncovered);
+    return `// Auto-generated by the OZ Policy Builder codegen escape hatch.
+// THIS OUTPUT IS THE USER'S TO COMPLETE AND AUDIT.
+// The synthesiser never emits it on the happy path; reach for it only when
+// a constraint cannot be expressed in the v1 DSL grammar (same shape as
+// Zodiac Roles' \`Custom\` operator).
+
+#![no_std]
+
+use soroban_sdk::{contract, contractimpl, contracttype, Address, Env, Vec};
+
+#[contracttype]
+pub enum DataKey {
+    /// Composite key \`(smart_account, rule_id)\` so multiple policies on
+    /// one smart account coexist without collision.
+    State(Address, u32),
+}
+
+#[contract]
+pub struct ${structName};
+
+#[contractimpl]
+impl ${structName} {
+    pub fn install(e: &Env, smart_account: Address, rule_id: u32) {
+        // TODO(user): initialise policy state for this (smart_account, rule_id).
+        // The skeleton leaves the stored value empty; the predicate body
+        // (in \`enforce\`) decides what to read.
+        e.storage().persistent().set(
+            &DataKey::State(smart_account.clone(), rule_id),
+            &(),
+        );
+    }
+
+    pub fn enforce(
+        e: &Env,
+        smart_account: Address,
+        rule_id: u32,
+        _signers: Vec<Address>,
+    ) {
+        // Invariant 1: authorise the smart account BEFORE any state read or
+        // predicate evaluation. Removing this call opens the policy to
+        // impersonation by any caller with a valid rule_id.
+        smart_account.require_auth();
+
+        // Invariant 2 + 4: read stored state through the composite key on
+        // \`persistent()\` storage. \`unwrap_or_default()\` (invariant 3)
+        // makes an empty key a permitted default rather than a panic.
+        let _state: () = e
+            .storage()
+            .persistent()
+            .get(&DataKey::State(smart_account.clone(), rule_id))
+            .unwrap_or_default();
+
+        // --- uncovered constraints the v1 DSL refused to express ---
+${uncoveredBlock}
+
+        // TODO(user): replace the placeholder below with the real predicate
+        // body. The recorded flow's \`(contract, fn_name, args)\` is the
+        // single authorised call \`Policy::enforce\` receives; match against
+        // \`e\` here.
+        let _ = (_state, &e);
+    }
+
+    pub fn uninstall(e: &Env, smart_account: Address, rule_id: u32) {
+        // Invariant 5: \`uninstall\` removes the stored state so a subsequent
+        // install starts from a clean slate (and the nonce returns to its
+        // post-uninstall value).
+        e.storage()
+            .persistent()
+            .remove(&DataKey::State(smart_account, rule_id));
+    }
+}
+`;
+}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = 'RECORDING_FAILED' | 'RECORDING_VALIDATION_FAILED' | 'SCOPE_UNRESOLVED' | 'SYNTHESIS_ERROR' | 'MALFORMED_PREDICATE' | 'SIMULATION_ERROR' | 'VERIFICATION_FAILED' | 'DENY_CASE_FAILURE' | 'PERMIT_CASE_FAILED' | 'SUMMARY_DRIFT' | 'INSTALL_BUILD_FAILED' | 'INSTALL_CONFIRM_MISSING' | 'INSTALL_CONFIRM_EXPIRED' | 'REVOKE_BUILD_FAILED' | 'REVOKE_CONFIRM_MISSING' | 'USER_REJECTED_SIGN' | 'WALLET_TIMEOUT' | 'WALLET_UNAVAILABLE' | 'PREDICATE_TOO_LARGE' | 'PREDICATE_TOO_DEEP' | 'PREDICATE_ORACLE_OVER_LIMIT' | 'POLICY_CAP_EXCEEDED' | 'WASM_TOO_LARGE' | 'MASTER_AUTH_REQUIRED' | 'NONCE_REPLAY' | 'VERSION_MISMATCH' | 'ARITHMETIC_OVERFLOW' | 'AMOUNT_OVERFLOW' | 'RULE_SIGNERS_CHANGED' | 'SCOPE_SELF_CALL' | 'ORACLE_STALE' | 'ORACLE_MISSING' | 'ORACLE_DEVIATION_EXCEEDED' | 'ORACLE_MALFORMED_HISTORY' | 'ORACLE_FINGERPRINT_DRIFT' | 'ORACLE_PAUSED' | 'ORACLE_LEAF_INVALID_POSITION' | 'ORACLE_PARAMS_OUT_OF_RANGE' | 'ORACLE_DECIMALS_MISMATCH' | 'COMPILE_OK' | 'COMPILE_GATE_FAILED';
+export type ErrorCode = 'RECORDING_FAILED' | 'RECORDING_VALIDATION_FAILED' | 'SCOPE_UNRESOLVED' | 'SYNTHESIS_ERROR' | 'MALFORMED_PREDICATE' | 'SIMULATION_ERROR' | 'VERIFICATION_FAILED' | 'DENY_CASE_FAILURE' | 'PERMIT_CASE_FAILED' | 'SUMMARY_DRIFT' | 'INSTALL_BUILD_FAILED' | 'INSTALL_CONFIRM_MISSING' | 'INSTALL_CONFIRM_EXPIRED' | 'REVOKE_BUILD_FAILED' | 'REVOKE_CONFIRM_MISSING' | 'USER_REJECTED_SIGN' | 'WALLET_TIMEOUT' | 'WALLET_UNAVAILABLE' | 'PREDICATE_TOO_LARGE' | 'PREDICATE_TOO_DEEP' | 'TOO_MANY_LEAVES' | 'IN_OPERAND_LIMIT' | 'PREDICATE_ORACLE_OVER_LIMIT' | 'POLICY_CAP_EXCEEDED' | 'WASM_TOO_LARGE' | 'MASTER_AUTH_REQUIRED' | 'NONCE_REPLAY' | 'VERSION_MISMATCH' | 'ARITHMETIC_OVERFLOW' | 'AMOUNT_OVERFLOW' | 'RULE_SIGNERS_CHANGED' | 'SCOPE_SELF_CALL' | 'ORACLE_STALE' | 'ORACLE_MISSING' | 'ORACLE_DEVIATION_EXCEEDED' | 'ORACLE_MALFORMED_HISTORY' | 'ORACLE_FINGERPRINT_DRIFT' | 'ORACLE_PAUSED' | 'ORACLE_LEAF_INVALID_POSITION' | 'ORACLE_PARAMS_OUT_OF_RANGE' | 'ORACLE_DECIMALS_MISMATCH' | 'COMPILE_OK' | 'COMPILE_GATE_FAILED';
 export interface ToolError {
     code: ErrorCode;
     message: string;

package/dist/index.d.ts

@@ -2,8 +2,10 @@ export * from './adapters/oz/index.ts';
 export * from './errors.ts';
 export * from './ir/index.ts';
 export * from './mandate/index.ts';
+export * from './predicate/index.ts';
 export * from './record/index.ts';
 export * from './registry/index.ts';
+export * from './review-card/index.ts';
 export * from './seams/index.ts';
 export * from './synth/index.ts';
 export * from './types.ts';

package/dist/index.js

@@ -2,8 +2,10 @@ export * from "./adapters/oz/index.js";
 export * from "./errors.js";
 export * from "./ir/index.js";
 export * from "./mandate/index.js";
+export * from "./predicate/index.js";
 export * from "./record/index.js";
 export * from "./registry/index.js";
+export * from "./review-card/index.js";
 export * from "./seams/index.js";
 export * from "./synth/index.js";
 export * from "./types.js";

package/dist/ir/types.d.ts

@@ -46,8 +46,9 @@ export interface IRCompare {
     value: string;
 }
 /** Condition tree. NEAR-V2 guard/constraint are flat And/Or; the IR allows
- *  nesting + `not` + `in` so the same IR can later lower to the OZ predicate
- *  DSL. Week-1 adapters only lower the flat supported subset and flag the rest. */
+ *  nesting + `not` + `in` + `eq_seq` so the same IR can later lower to the OZ
+ *  predicate DSL. Week-1 adapters only lower the flat supported subset and flag
+ *  the rest. */
 export type IRCondition = {
     op: 'and' | 'or';
     children: IRCondition[];
@@ -61,6 +62,16 @@ export type IRCondition = {
     op: 'in';
     selector: IRSelector;
     values: string[];
+}
+/** Exact ordered sequence equality. The IR-level selector value MUST EQUAL
+ *  `values` as an ORDERED sequence (e.g. a swap hop `path`). `in` is pure
+ *  set membership and cannot express order; `eq_seq` is the construct that
+ *  does. Adapters that cannot express an exact ordered vector (OZ built-ins)
+ *  flag this as `uncovered` rather than silently dropping it. */
+ | {
+    op: 'eq_seq';
+    selector: IRSelector;
+    values: string[];
 };
 export interface IRPolicyRule {
     /** NEAR-V2 roles whitelist (empty = any; owner exempt). */

package/dist/predicate/encode.d.ts

@@ -0,0 +1,10 @@
+import { type PredicateNode } from '../types.ts';
+export interface EncodedPredicate {
+    /** base64 of the canonical ScVal XDR of the predicate root. */
+    encodedPredicate: string;
+    /** sha256 hex digest of the raw XDR bytes (post-canonicalisation). */
+    predicateHash: string;
+}
+/** Encode a `PredicateNode` to the canonical ScVal wire format and hash it.
+ *  Pure function: same input -> byte-identical output every run. */
+export declare function encodePredicate(node: PredicateNode): EncodedPredicate;

package/dist/predicate/encode.js

@@ -0,0 +1,249 @@
+// src/predicate/encode.ts - canonical predicate encoder.
+//
+// Pure function. Maps a `PredicateNode` AST to the canonical ScVal wire format
+// described in `packages/policy-interpreter/INTERPRETER_INSTALL_PARAMS.md`:
+//   - every node is a `ScVal::Vec` whose head element is the tag `ScVal::Symbol`
+//   - children of `and` / `or` are sorted ascending by their canonical XDR bytes
+//   - `in` haystacks are ALWAYS sorted by canonical XDR bytes (pure set
+//     membership); an EXACT ordered sequence is expressed as
+//     `eq(selector, literal_vec)` where the `literal_vec` element order is
+//     preserved verbatim (the order IS the semantic)
+//   - `literal_vec` encodes to a bare `ScVal::Vec` of its element encodings;
+//     order is preserved, NOT sorted
+//   - i128 uses `Int128Parts{hi: Int64 (signed), lo: Uint64 (unsigned)}`,
+//     value = hi*2^64 + lo (NOT signed-magnitude)
+//   - no `ScMap` anywhere in the predicate
+//   - `encodedPredicate = base64(root.toXDR())`,
+//     `predicateHash = sha256(raw XDR bytes)` as hex
+//
+// Caps from `PREDICATE_CAPS` are enforced BEFORE returning; a cap breach throws
+// a `ToolError` with the matching error code and `severity: 'error'`.
+import { createHash } from 'node:crypto';
+import { Address, xdr } from '@stellar/stellar-sdk';
+import { PREDICATE_CAPS } from "../types.js";
+const INT64_MAX = (1n << 63n) - 1n;
+const INT64_MIN = -(1n << 63n);
+const UINT64_MAX = (1n << 64n) - 1n;
+/** Encode a `PredicateNode` to the canonical ScVal wire format and hash it.
+ *  Pure function: same input -> byte-identical output every run. */
+export function encodePredicate(node) {
+    // --- pass 1: structural cap checks (no encoding needed) ---
+    const stats = computeStats(node);
+    if (stats.depth > PREDICATE_CAPS.MAX_DEPTH) {
+        throw capError('PREDICATE_TOO_DEEP', `predicate depth ${stats.depth} exceeds MAX_DEPTH ${PREDICATE_CAPS.MAX_DEPTH}`);
+    }
+    if (stats.leaves > PREDICATE_CAPS.MAX_LEAVES) {
+        throw capError('TOO_MANY_LEAVES', `predicate leaf count ${stats.leaves} exceeds MAX_LEAVES ${PREDICATE_CAPS.MAX_LEAVES}`);
+    }
+    for (const c of stats.inCounts) {
+        if (c.count > PREDICATE_CAPS.MAX_IN_OPERAND_COUNT) {
+            throw capError('IN_OPERAND_LIMIT', `\`in\` operand count ${c.count} exceeds MAX_IN_OPERAND_COUNT ${PREDICATE_CAPS.MAX_IN_OPERAND_COUNT}`);
+        }
+    }
+    // Two-round confirmation costs 2 oracle reads per UNIQUE asset referenced.
+    const oracleReads = stats.oracleAssets.size * 2;
+    if (oracleReads > PREDICATE_CAPS.MAX_ORACLE_READS) {
+        throw capError('PREDICATE_ORACLE_OVER_LIMIT', `oracle reads ${oracleReads} exceed MAX_ORACLE_READS ${PREDICATE_CAPS.MAX_ORACLE_READS}`);
+    }
+    // --- pass 2: build + canonicalise the ScVal ---
+    const root = encodeNode(node);
+    const rawBytes = root.toXDR();
+    if (rawBytes.length > PREDICATE_CAPS.MAX_PREDICATE_BYTES) {
+        throw capError('PREDICATE_TOO_LARGE', `predicate bytes ${rawBytes.length} exceed MAX_PREDICATE_BYTES ${PREDICATE_CAPS.MAX_PREDICATE_BYTES}`);
+    }
+    const encodedPredicate = rawBytes.toString('base64');
+    const predicateHash = createHash('sha256').update(rawBytes).digest('hex');
+    return { encodedPredicate, predicateHash };
+}
+function computeStats(node) {
+    const inCounts = [];
+    const oracleAssets = new Set();
+    const { depth, leaves } = walk(node, inCounts, oracleAssets);
+    return { depth, leaves, inCounts, oracleAssets };
+}
+function walk(node, inCounts, oracleAssets) {
+    switch (node.op) {
+        case 'and':
+        case 'or': {
+            if (node.children.length === 0)
+                return { depth: 1, leaves: 0 };
+            let maxChildDepth = 0;
+            let totalLeaves = 0;
+            for (const c of node.children) {
+                const child = walk(c, inCounts, oracleAssets);
+                if (child.depth > maxChildDepth)
+                    maxChildDepth = child.depth;
+                totalLeaves += child.leaves;
+            }
+            return { depth: maxChildDepth + 1, leaves: totalLeaves };
+        }
+        case 'not': {
+            const child = walk(node.child, inCounts, oracleAssets);
+            return { depth: child.depth + 1, leaves: child.leaves };
+        }
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            collectOracle(node.left, oracleAssets);
+            collectOracle(node.right, oracleAssets);
+            return { depth: 1, leaves: leafCount(node.left) + leafCount(node.right) };
+        }
+        case 'in': {
+            inCounts.push({ count: node.haystack.length });
+            collectOracle(node.needle, oracleAssets);
+            let haystackLeaves = 0;
+            for (const h of node.haystack) {
+                collectOracle(h, oracleAssets);
+                haystackLeaves += leafCount(h);
+            }
+            return {
+                depth: 1,
+                leaves: leafCount(node.needle) + haystackLeaves,
+            };
+        }
+    }
+}
+/** Leaf-count contribution of one PredicateLeaf: 1 for any flat leaf, and the
+ *  sum of element leaf counts for `literal_vec` so MAX_LEAVES caps see nested
+ *  vector elements. */
+function leafCount(leaf) {
+    if (leaf.kind === 'literal_vec') {
+        let total = 1; // the literal_vec itself counts as one leaf node
+        for (const el of leaf.elements)
+            total += leafCount(el);
+        return total;
+    }
+    return 1;
+}
+function collectOracle(leaf, oracleAssets) {
+    // literal_vec is the only nested leaf; recurse so an oracle_price buried in a
+    // vector literal (which the lowering would forbid, but the cap-walker must
+    // still see) is counted toward the oracle-read budget.
+    if (leaf.kind === 'oracle_price') {
+        oracleAssets.add(leaf.asset);
+    }
+    else if (leaf.kind === 'literal_vec') {
+        for (const el of leaf.elements)
+            collectOracle(el, oracleAssets);
+    }
+}
+function encodeNode(node) {
+    switch (node.op) {
+        case 'and':
+        case 'or': {
+            const encoded = node.children.map(encodeNode);
+            // sort children by their canonical XDR bytes ascending.
+            const sorted = sortByCanonicalBytes(encoded);
+            return xdr.ScVal.scvVec([symbol(node.op), xdr.ScVal.scvVec(sorted)]);
+        }
+        case 'not': {
+            return xdr.ScVal.scvVec([symbol('not'), encodeNode(node.child)]);
+        }
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            return xdr.ScVal.scvVec([symbol(node.op), encodeLeaf(node.left), encodeLeaf(node.right)]);
+        }
+        case 'in': {
+            const needle = encodeLeaf(node.needle);
+            // `in` is PURE set membership: the haystack is ALWAYS sorted by canonical
+            // XDR bytes ascending. An exact ordered sequence (e.g. a swap hop path)
+            // is expressed as `eq(selector, literal_vec)` where the vec's element
+            // order is preserved verbatim (handled in `encodeLeaf(literal_vec)`).
+            const haystack = sortByCanonicalBytes(node.haystack.map(encodeLeaf));
+            return xdr.ScVal.scvVec([symbol('in'), needle, xdr.ScVal.scvVec(haystack)]);
+        }
+    }
+}
+function encodeLeaf(leaf) {
+    switch (leaf.kind) {
+        case 'call_contract':
+            return xdr.ScVal.scvVec([symbol('call_contract')]);
+        case 'call_fn':
+            return xdr.ScVal.scvVec([symbol('call_fn')]);
+        case 'call_arg':
+            return xdr.ScVal.scvVec([symbol('call_arg'), xdr.ScVal.scvU32(leaf.index)]);
+        case 'amount':
+            return xdr.ScVal.scvVec([symbol('amount'), scvAddressFromStrkey(leaf.token)]);
+        case 'window_spent':
+            return xdr.ScVal.scvVec([
+                symbol('window_spent'),
+                scvAddressFromStrkey(leaf.token),
+                scvU64FromValue(leaf.windowSeconds),
+            ]);
+        case 'now':
+            return xdr.ScVal.scvVec([symbol('now')]);
+        case 'valid_until':
+            return xdr.ScVal.scvVec([symbol('valid_until')]);
+        case 'invocation_count_in_window':
+            return xdr.ScVal.scvVec([symbol('invocation_count'), scvU64FromValue(leaf.windowSecs)]);
+        case 'oracle_price':
+            return xdr.ScVal.scvVec([symbol('oracle_price'), scvAddressFromStrkey(leaf.asset)]);
+        case 'literal_address':
+            return scvAddressFromStrkey(leaf.value);
+        case 'literal_i128':
+            return scvI128FromDecimal(leaf.value);
+        case 'literal_symbol':
+            return xdr.ScVal.scvSymbol(leaf.value);
+        case 'literal_u32':
+            return xdr.ScVal.scvU32(leaf.value);
+        case 'literal_u64':
+            return scvU64FromValue(leaf.value);
+        case 'literal_bytes':
+            return xdr.ScVal.scvBytes(Buffer.from(leaf.value, 'hex'));
+        case 'literal_vec':
+            // Bare ScVal::Vec of element encodings - order is preserved verbatim
+            // because the order IS the semantic (exact ordered sequence equality).
+            return xdr.ScVal.scvVec(leaf.elements.map(encodeLeaf));
+    }
+}
+function symbol(s) {
+    return xdr.ScVal.scvSymbol(s);
+}
+function sortByCanonicalBytes(values) {
+    const pairs = values.map((v) => ({ v, bytes: v.toXDR() }));
+    pairs.sort((a, b) => Buffer.compare(a.bytes, b.bytes));
+    return pairs.map((p) => p.v);
+}
+function scvAddressFromStrkey(strkey) {
+    return xdr.ScVal.scvAddress(Address.fromString(strkey).toScAddress());
+}
+function scvU64FromValue(value) {
+    // The Uint64 (UnsignedHyper) constructor accepts string | bigint | number;
+    // string is safest for values > 2^53.
+    return xdr.ScVal.scvU64(new xdr.Uint64(String(value)));
+}
+/** Build `ScVal::I128(Int128Parts{hi, lo})` from a signed decimal string.
+ *  `Int128Parts` encodes the value as `(hi << 64) + lo` with `hi` a SIGNED
+ *  64-bit int and `lo` an UNSIGNED 64-bit int (this is NOT signed-magnitude).
+ *  The inverse split is `hi = v >> 64n` (arithmetic right shift) and
+ *  `lo = v & 0xFFFF...`. The SDK's `Int64` constructor takes a signed
+ *  bigint/string/number. */
+function scvI128FromDecimal(decimal) {
+    const v = BigInt(decimal);
+    const hi = v >> 64n;
+    const lo = v & UINT64_MAX;
+    // Guard against accidental over-range. Int128Parts.hi must be a valid Int64
+    // (-2^63 .. 2^63-1); values outside this range are invalid i128 entirely.
+    if (hi < INT64_MIN || hi > INT64_MAX) {
+        throw capError('MALFORMED_PREDICATE', `literal_i128 value ${decimal} is outside the Int128 range`);
+    }
+    if (lo < 0n || lo > UINT64_MAX) {
+        throw capError('MALFORMED_PREDICATE', `literal_i128 value ${decimal} has an invalid Int128Parts.lo`);
+    }
+    return xdr.ScVal.scvI128(new xdr.Int128Parts({
+        hi: new xdr.Int64(hi),
+        lo: new xdr.Uint64(lo),
+    }));
+}
+function capError(code, message) {
+    const err = new Error(message);
+    err.code = code;
+    err.severity = 'error';
+    err.retryable = false;
+    throw err;
+}

package/dist/predicate/index.d.ts

@@ -0,0 +1 @@
+export { type EncodedPredicate, encodePredicate } from './encode.ts';

package/dist/predicate/index.js

@@ -0,0 +1,2 @@
+// src/predicate/index.ts - re-export the canonical predicate encoder.
+export { encodePredicate } from "./encode.js";

package/dist/review-card/builder.d.ts

@@ -0,0 +1,14 @@
+import type { ContextRuleDraft, PolicyRef, PredicateNode } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
+export interface ReviewCardSummary {
+    ruleName: string;
+    plainEnglish: string;
+    constraints: string[];
+    expiry: string;
+    backend: 'interpreter-v1' | 'ts-model';
+    /** Stable hash of the builder inputs - identical policy + summary = identical hash. */
+    contentHash: string;
+}
+/** Build a deterministic review-card summary from a policy + context rule +
+ *  simulation result. Pure: same inputs -> byte-identical output. */
+export declare function buildReviewCardSummary(predicate: PredicateNode | null, policyRefs: PolicyRef[], contextRule: ContextRuleDraft, simulation: SimulationResult): ReviewCardSummary;