@crediolabs/policy-synth 0.1.3 → 0.1.5

package/src/codegen/compile-gate.ts

@@ -0,0 +1,162 @@
+// 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'
+
+export type CompileGateResult =
+  | { code: 'COMPILE_OK' }
+  | { code: 'COMPILE_GATE_FAILED'; stderr: string }
+  | { code: 'SKIPPED'; reason: string }
+
+export interface CompileGateOpts {
+  /** Caller-controlled abort signal; aborting before toolchain probe resolves
+   *  the gate to `SKIPPED` rather than starting a cargo invocation. */
+  signal?: AbortSignal
+  /** Override the `cargo` binary (mostly for tests). */
+  cargoBin?: string
+  /** Override the target directory (mostly for tests). */
+  tempDir?: string
+}
+
+interface ToolchainProbe {
+  present: boolean
+  reason: string
+}
+
+/** 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(): Promise<boolean> {
+  const probe = await probeToolchain()
+  return probe.present
+}
+
+async function probeToolchain(): Promise<ToolchainProbe> {
+  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: string): Promise<string | null> {
+  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
+  }
+}
+
+interface RunOpts {
+  capture?: boolean
+  signal?: AbortSignal
+}
+
+function runProcess(
+  cmd: string,
+  args: string[],
+  opts: RunOpts
+): Promise<{ stdout: string; stderr: string; code: number }> {
+  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: Buffer) => {
+      stdout += b.toString('utf8')
+    })
+    child.stderr.on('data', (b: Buffer) => {
+      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: string,
+  opts: CompileGateOpts = {}
+): Promise<CompileGateResult> {
+  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: string | null = 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: 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: Error) => ({ 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/src/codegen/index.ts

@@ -0,0 +1,17 @@
+// 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 {
+  type CompileGateOpts,
+  type CompileGateResult,
+  compileCheck,
+  hasRustToolchain,
+} from './compile-gate.ts'
+export {
+  type EscapeHatchSpec,
+  generateRust,
+} from './template.ts'

package/src/codegen/template.ts

@@ -0,0 +1,148 @@
+// 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.
+
+/** 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[]
+}
+
+/** 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: string): string {
+  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: string[]): string {
+  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: EscapeHatchSpec, name: string): string {
+  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/src/errors.ts

@@ -26,6 +26,8 @@ export type ErrorCode =
   // --- predicate caps (fail-closed at install) ---
   | 'PREDICATE_TOO_LARGE'
   | 'PREDICATE_TOO_DEEP'
+  | 'TOO_MANY_LEAVES'
+  | 'IN_OPERAND_LIMIT'
   | 'PREDICATE_ORACLE_OVER_LIMIT'
   | 'POLICY_CAP_EXCEEDED'
   | 'WASM_TOO_LARGE'

package/src/index.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/src/ir/types.ts

@@ -60,13 +60,20 @@ export interface IRCompare {
 }
 
 /** 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[] }
   | { op: 'not'; child: IRCondition }
   | { op: 'compare'; compare: IRCompare }
   | { 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/src/predicate/encode.ts

@@ -0,0 +1,307 @@
+// 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 type { ToolError } from '../errors.ts'
+import { PREDICATE_CAPS, type PredicateLeaf, 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
+}
+
+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: PredicateNode): EncodedPredicate {
+  // --- 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 }
+}
+
+interface PredicateStats {
+  depth: number
+  leaves: number
+  inCounts: Array<{ count: number }>
+  /** Unique assets referenced by `oracle_price` leaves - each costs 2 reads. */
+  oracleAssets: Set<string>
+}
+
+function computeStats(node: PredicateNode): PredicateStats {
+  const inCounts: Array<{ count: number }> = []
+  const oracleAssets = new Set<string>()
+  const { depth, leaves } = walk(node, inCounts, oracleAssets)
+  return { depth, leaves, inCounts, oracleAssets }
+}
+
+function walk(
+  node: PredicateNode,
+  inCounts: Array<{ count: number }>,
+  oracleAssets: Set<string>
+): { depth: number; leaves: number } {
+  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: PredicateLeaf): number {
+  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: PredicateLeaf, oracleAssets: Set<string>): void {
+  // 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: PredicateNode): xdr.ScVal {
+  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: PredicateLeaf): xdr.ScVal {
+  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: string): xdr.ScVal {
+  return xdr.ScVal.scvSymbol(s)
+}
+
+function sortByCanonicalBytes(values: xdr.ScVal[]): xdr.ScVal[] {
+  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: string): xdr.ScVal {
+  return xdr.ScVal.scvAddress(Address.fromString(strkey).toScAddress())
+}
+
+function scvU64FromValue(value: number | string): xdr.ScVal {
+  // 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: string): xdr.ScVal {
+  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: ToolError['code'], message: string): ToolError {
+  const err = new Error(message) as Error & {
+    code: ToolError['code']
+    severity: string
+    retryable: boolean
+  }
+  err.code = code
+  err.severity = 'error'
+  err.retryable = false
+  throw err
+}

package/src/predicate/index.ts

@@ -0,0 +1,3 @@
+// src/predicate/index.ts - re-export the canonical predicate encoder.
+
+export { type EncodedPredicate, encodePredicate } from './encode.ts'