@crediolabs/policy-synth 0.1.18 → 0.3.0

package/src/simulate/deny-cases.ts

@@ -0,0 +1,334 @@
+import { Address } from '@stellar/stellar-sdk'
+import type { PredicateLeaf, PredicateNode, ScVal } from '../types.ts'
+import { MAX_SCVAL_CLONE_DEPTH } from '../types.ts'
+import type { EvalContext } from './evaluate.ts'
+
+export interface DenyCase {
+  dimension: string
+  ctx: EvalContext
+  /** Canonical reason the Rust interpreter returns for this dimension.
+   *  Optional: when set, `runHarness` asserts the TS evaluator emits this
+   *  exact string, so a future TS/Rust reason divergence fails CI. When
+   *  absent the case is only checked on the boolean decision. */
+  expectedReason?: string
+}
+
+export interface GeneratedCases {
+  permit: EvalContext
+  denies: DenyCase[]
+}
+
+/** A contract address that is not the pinned one. It must be a REAL strkey:
+ *  the host rejects a malformed one with `Error(Value, InvalidInput)` before
+ *  the predicate is ever evaluated, which would make the deny case pass for
+ *  the wrong reason. */
+const OTHER_CONTRACT = Address.contract(Buffer.alloc(32, 0x5a)).toString()
+
+type ComparisonOperator = 'eq' | 'lte'
+
+type ComparisonNode = {
+  op: ComparisonOperator
+  left: PredicateLeaf
+  right: PredicateLeaf
+}
+
+type MembershipNode = {
+  op: 'in'
+  needle: PredicateLeaf
+  haystack: PredicateLeaf[]
+}
+
+interface PredicateFacts {
+  comparisons: ComparisonNode[]
+  memberships: MembershipNode[]
+}
+
+/** Build deterministic model-evaluated alternatives without mutating the intended call.
+ *
+ * @param predicate   - the synthesized predicate
+ * @param permitCtx  - EvalContext for the intended (permitted) call
+ * @param dimensions - optional whitelist of dimension names to emit; when omitted
+ *                    all known dimensions (including over-permissiveness mutations)
+ *                    are emitted. */
+export function generateCases(
+  predicate: PredicateNode,
+  permitCtx: EvalContext,
+  dimensions?: string[]
+): GeneratedCases {
+  const facts = inspectPredicate(predicate)
+  const denies: DenyCase[] = []
+
+  // contract_scope: the same call sent to a different contract. The predicate
+  // pins `call_contract`, so this is the most direct bypass attempt there is -
+  // point the agent's authorised call at another contract entirely.
+  if (facts.comparisons.some((c) => c.op === 'eq' && c.left.kind === 'call_contract')) {
+    denies.push({
+      dimension: 'contract_scope',
+      ctx: { ...permitCtx, contract: OTHER_CONTRACT },
+      expectedReason: 'CONTRACT_SCOPE',
+    })
+  }
+
+  // function_scope: the same arguments sent to a different method on the
+  // pinned contract. `transfer` and `burn` take the same shape; only the
+  // `call_fn` pin separates them.
+  if (facts.comparisons.some((c) => c.op === 'eq' && c.left.kind === 'call_fn')) {
+    denies.push({
+      dimension: 'function_scope',
+      ctx: { ...permitCtx, fn: `${permitCtx.fn}_not` },
+      expectedReason: 'ARG_MISMATCH',
+    })
+  }
+
+  // arg_bound: set a constrained arg to an opaque ScVal.
+  // The reason depends on the predicate shape:
+  //   - an `eq(call_arg[i], literal)` denies with ARG_MISMATCH
+  //   - an `in(call_arg[i], [literals])` denies with NOT_IN_ALLOWLIST
+  // Both are correct in the TS evaluator; the reason is predicate-dependent
+  // so we cannot pin a single canonical reason here.
+  const argumentConstraints: Array<{ index: number }> = []
+  for (const comparison of facts.comparisons) {
+    if (
+      comparison.op === 'eq' &&
+      comparison.left.kind === 'call_arg' &&
+      comparison.right.kind !== 'literal_vec'
+    ) {
+      argumentConstraints.push({ index: comparison.left.index })
+    }
+  }
+  for (const membership of facts.memberships) {
+    if (membership.needle.kind === 'call_arg') {
+      argumentConstraints.push({ index: membership.needle.index })
+    }
+  }
+  for (const constraint of argumentConstraints) {
+    const ctx = cloneContext(permitCtx)
+    ctx.args[constraint.index] = { type: 'other', value: 'deny-case-opaque-argument' }
+    denies.push({ dimension: 'arg_bound', ctx })
+  }
+
+  // soroswap_allowed_path: replace a bound vec arg with a different vector.
+  // Still valid for eq comparisons on literal_vec leaves.
+  for (const comparison of facts.comparisons) {
+    if (
+      comparison.op !== 'eq' ||
+      comparison.left.kind !== 'call_arg' ||
+      comparison.right.kind !== 'literal_vec'
+    ) {
+      continue
+    }
+    const ctx = cloneContext(permitCtx)
+    ctx.args[comparison.left.index] = differentVector(ctx.args[comparison.left.index])
+    denies.push({ dimension: 'soroswap_allowed_path', ctx })
+  }
+
+  // argument_reorder: swap first two address args.
+  // Skipped when dimensions filter is active so the synth pipeline can emit a policy;
+  // the over-permissiveness harness then tests this mutation as a FINDING.
+  const constrainedArgIndices = new Set<number>()
+  for (const comparison of facts.comparisons) {
+    if (comparison.left.kind === 'call_arg') constrainedArgIndices.add(comparison.left.index)
+  }
+  for (const membership of facts.memberships) {
+    if (membership.needle.kind === 'call_arg') constrainedArgIndices.add(membership.needle.index)
+  }
+  const hasConstrainedArg = constrainedArgIndices.size > 0
+  if (
+    (!dimensions || dimensions.includes('argument_reorder')) &&
+    hasConstrainedArg &&
+    permitCtx.args.length >= 2 &&
+    permitCtx.args[0]?.type === 'address' &&
+    permitCtx.args[1]?.type === 'address' &&
+    (permitCtx.args[0] as { type: 'address'; value: string }).value !==
+      (permitCtx.args[1] as { type: 'address'; value: string }).value
+  ) {
+    const ctx = cloneContext(permitCtx)
+    // Guard above guarantees args[0] and args[1] exist and are address-typed.
+    const a0 = ctx.args[0] as ScVal
+    const a1 = ctx.args[1] as ScVal
+    ctx.args[0] = a1
+    ctx.args[1] = a0
+    denies.push({ dimension: 'argument_reorder', ctx })
+  }
+
+  // map_field_flip: flip a bound map field to a different valid value of
+  // the same type. OPT-IN only, never ORIGINAL.
+  // Targets each `call_arg_field` leaf and produces a ctx whose vec element
+  // has a different value of the recorded field. ---
+  if (!dimensions || dimensions.includes('map_field_flip')) {
+    for (const comparison of facts.comparisons) {
+      const sel = comparison.left
+      if (sel.kind !== 'call_arg_field') continue
+      const arg = permitCtx.args[sel.index]
+      if (arg?.type !== 'vec') continue
+      const element = arg.value[sel.element]
+      if (element?.type !== 'map' || !Array.isArray(element.value)) continue
+      const entry = element.value.find((e) => e.key === sel.field)
+      if (!entry) continue
+      const flipped = flipFieldValue(entry.val)
+      if (flipped === null) continue
+      const ctx = cloneContext(permitCtx)
+      const clonedVec = arg.value.map(cloneScVal)
+      const clonedElement = clonedVec[sel.element]
+      if (clonedElement?.type !== 'map' || !Array.isArray(clonedElement.value)) continue
+      clonedElement.value = clonedElement.value.map((e) =>
+        e.key === sel.field ? { key: e.key, val: flipped } : e
+      )
+      clonedVec[sel.element] = clonedElement
+      ctx.args[sel.index] = { type: 'vec', value: clonedVec }
+      denies.push({ dimension: 'map_field_flip', ctx })
+    }
+  }
+
+  // amount_over_cap: push a capped value one unit past its cap.
+  //
+  // Every value bound is an `lte`, and `arg_bound` only targets `eq`, so
+  // without this the headline guarantee - "never more than this much per
+  // call" - had nothing exercising it. One over the cap is the smallest
+  // mutation that must be refused; if the cap held only for larger overshoots
+  // it would not be a cap.
+  if (!dimensions || dimensions.includes('amount_over_cap')) {
+    for (const comparison of facts.comparisons) {
+      if (comparison.op !== 'lte') continue
+      const cap = literalInteger(comparison.right)
+      if (cap === null) continue
+      const over: ScVal = { type: 'i128', value: (cap + 1n).toString() }
+      const sel = comparison.left
+      if (sel.kind === 'call_arg') {
+        const ctx = cloneContext(permitCtx)
+        ctx.args[sel.index] = over
+        denies.push({ dimension: 'amount_over_cap', ctx, expectedReason: 'ARG_MISMATCH' })
+        continue
+      }
+      if (sel.kind !== 'call_arg_field') continue
+      const arg = permitCtx.args[sel.index]
+      if (arg?.type !== 'vec') continue
+      const ctx = cloneContext(permitCtx)
+      const clonedVec = arg.value.map(cloneScVal)
+      const clonedElement = clonedVec[sel.element]
+      if (clonedElement?.type !== 'map' || !Array.isArray(clonedElement.value)) continue
+      clonedElement.value = clonedElement.value.map((e) =>
+        e.key === sel.field ? { key: e.key, val: over } : e
+      )
+      clonedVec[sel.element] = clonedElement
+      ctx.args[sel.index] = { type: 'vec', value: clonedVec }
+      denies.push({ dimension: 'amount_over_cap', ctx, expectedReason: 'ARG_MISMATCH' })
+    }
+  }
+
+  // vec_append: append a new element to a bound vec. OPT-IN only, never ORIGINAL.
+  // Targets every `call_arg_len` leaf; without the length pin a caller can
+  // append an extra element to defeat per-element binds. ---
+  if (!dimensions || dimensions.includes('vec_append')) {
+    for (const comparison of facts.comparisons) {
+      const sel = comparison.left
+      if (sel.kind !== 'call_arg_len') continue
+      const arg = permitCtx.args[sel.index]
+      if (arg?.type !== 'vec') continue
+      const ctx = cloneContext(permitCtx)
+      ctx.args[sel.index] = {
+        type: 'vec',
+        value: [...arg.value, { type: 'other', value: 'deny-case-vec-append' }],
+      }
+      denies.push({ dimension: 'vec_append', ctx })
+    }
+  }
+
+  return { permit: cloneContext(permitCtx), denies }
+}
+
+function inspectPredicate(predicate: PredicateNode): PredicateFacts {
+  const facts: PredicateFacts = { comparisons: [], memberships: [] }
+  visit(predicate, facts)
+  return facts
+}
+
+function visit(node: PredicateNode, facts: PredicateFacts): void {
+  switch (node.op) {
+    case 'and':
+      for (const child of node.children) visit(child, facts)
+      return
+    case 'in':
+      facts.memberships.push(node)
+      return
+    case 'eq':
+    case 'lte':
+      facts.comparisons.push(node)
+  }
+}
+
+/** The integer a numeric literal leaf carries, or null when the leaf is not
+ *  numeric (an address or a vector has no cap to exceed). */
+function literalInteger(leaf: PredicateLeaf): bigint | null {
+  if (leaf.kind === 'literal_i128') return BigInt(leaf.value)
+  if (leaf.kind === 'literal_u32') return BigInt(leaf.value)
+  return null
+}
+
+function differentVector(actual: ScVal | undefined): ScVal {
+  if (actual?.type !== 'vec') return { type: 'vec', value: [] }
+  if (actual.value.length === 0) {
+    return { type: 'vec', value: [{ type: 'other', value: 'deny-case-extra-hop' }] }
+  }
+  if (actual.value.length > 1) {
+    const reversed = actual.value.map(cloneScVal).reverse()
+    if (JSON.stringify(reversed) !== JSON.stringify(actual.value)) {
+      return { type: 'vec', value: reversed }
+    }
+  }
+  const value = actual.value.map(cloneScVal)
+  value[0] = { type: 'other', value: 'deny-case-different-hop' }
+  return { type: 'vec', value }
+}
+
+function cloneContext(ctx: EvalContext): EvalContext {
+  return {
+    contract: ctx.contract,
+    fn: ctx.fn,
+    args: ctx.args.map(cloneScVal),
+  }
+}
+
+/** Deep-copy an ScVal so a mutation cannot alias the recorded call.
+ *  Exported so the permit-context builder shares this one implementation. */
+export function cloneScVal(value: ScVal, depth = 0): ScVal {
+  if (value.type === 'vec') {
+    if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+      throw cloneDepthError(value)
+    }
+    return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) }
+  }
+  return { ...value }
+}
+
+function cloneDepthError(value: ScVal): never {
+  const err = new Error(
+    `ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`
+  ) as Error & { code: string; severity: string; retryable: boolean; depthContext: unknown }
+  err.code = 'SYNTHESIS_ERROR'
+  err.severity = 'error'
+  err.retryable = false
+  err.depthContext = value.type
+  throw err
+}
+
+/** Build a value of the SAME ScVal type that differs from the recorded one,
+ *  used by the `map_field_flip` mutation to defeat a per-element pin without
+ *  changing the wire type. Returns null when the ScVal type has no obvious
+ *  different value (e.g. opaque/other). */
+function flipFieldValue(val: ScVal): ScVal | null {
+  switch (val.type) {
+    case 'address': {
+      const a = 'GBFKRGJYZXLTDEI36ZCQEIM225NMOCR2VDBOIHJTXJ54FEFFVL2FKALE'
+      const b = 'GD6XSMQJ47EHHJOWXQOND5YDVZC37JWZJHYHBKE6QJFSLLJ5KQXM5QS5'
+      return { type: 'address', value: val.value === a ? b : a }
+    }
+    case 'i128':
+    case 'u32':
+      return { type: val.type, value: String(BigInt(val.value) + 1n) }
+    case 'symbol':
+      return { type: 'symbol', value: `${val.value}x` }
+    default:
+      return null
+  }
+}

package/src/simulate/evaluate.ts

@@ -0,0 +1,284 @@
+// src/simulate/evaluate.ts - TypeScript reference evaluator for grammar version 3.
+//
+// Pure function. Determinism: same `(predicate, ctx)` -> byte-identical result,
+// no clock, no randomness. Deny order (deny on FIRST violation, stable reason):
+//   1. contract mismatch                                     -> 'CONTRACT_SCOPE'
+//   2. per-ScVal equality on fn/args; EXACT ordered vector
+//      equality; fail-closed on opaque args                   -> 'ARG_MISMATCH'
+//   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),
+//   call_arg_len(i), call_arg_field(i, element, field),
+//   literal_address, literal_i128, literal_symbol, literal_u32, literal_vec
+// Grammar version 3 deny reasons: ARG_MISMATCH, CONTRACT_SCOPE,
+//   UNSUPPORTED_NODE, NOT_IN_ALLOWLIST
+
+import type { PredicateLeaf, PredicateNode, ScVal } from '../types.ts'
+
+export interface EvalContext {
+  /** Contract the interpreter is asked to enforce against. */
+  contract: string
+  /** Function name on that contract. */
+  fn: string
+  /** Decoded `ScVal[]` of the top-level authorized call. */
+  args: ScVal[]
+}
+
+export type EvalResult = { permit: true } | { permit: false; reason: string }
+
+/** Evaluate a `PredicateNode` against the candidate call described by `ctx`.
+ *  Pure function. Returns `{ permit: true }` or `{ permit: false; reason }`. */
+export function evaluate(predicate: PredicateNode, ctx: EvalContext): EvalResult {
+  return walk(predicate, ctx)
+}
+
+/** Walk the predicate tree. Returns the FIRST deny reason encountered on
+ *  the active branch (so `and` fails-fast). */
+function walk(node: PredicateNode, ctx: EvalContext): EvalResult {
+  switch (node.op) {
+    case 'and': {
+      let lastDeny: EvalResult | null = null
+      for (const child of node.children) {
+        const r = walk(child, ctx)
+        if (!r.permit) return r
+        lastDeny = r
+      }
+      return lastDeny ?? { permit: true }
+    }
+    case 'eq':
+    case 'lte':
+      return evalCompare(node.op, node.left, node.right, ctx)
+    case 'in':
+      return evalIn(node.needle, node.haystack, ctx)
+  }
+}
+
+/** Comparison leaf evaluation. */
+function evalCompare(
+  op: 'eq' | 'lte',
+  left: PredicateLeaf,
+  right: PredicateLeaf,
+  ctx: EvalContext
+): EvalResult {
+  // 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' }
+  }
+
+  // call_fn equality
+  if (left.kind === 'call_fn' && op === 'eq') {
+    if (right.kind !== 'literal_symbol') return { permit: false, reason: 'ARG_MISMATCH' }
+    return right.value === ctx.fn ? { permit: true } : { permit: false, reason: 'ARG_MISMATCH' }
+  }
+
+  // call_arg comparison (eq / exact-vec, or lte ordered numeric bound)
+  if (left.kind === 'call_arg') {
+    const actual = ctx.args[left.index]
+    if (op !== 'eq') return evalArgOrderedCompare(op, actual, right)
+    return evalArgEq(op, actual, right)
+  }
+
+  // call_arg_len: length of a vec-typed argument as u32.
+  // Fails closed on a non-vec / absent arg or a non-u32 literal.
+  if (left.kind === 'call_arg_len') {
+    const actual = ctx.args[left.index]
+    if (actual?.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
+    if (right.kind !== 'literal_u32') return { permit: false, reason: 'ARG_MISMATCH' }
+    return actual.value.length === right.value
+      ? { permit: true }
+      : { permit: false, reason: 'ARG_MISMATCH' }
+  }
+
+  // call_arg_field: value of a field in the map at element i of
+  // the vec at argument index. Fails closed on shape / type / range issues.
+  if (left.kind === 'call_arg_field') {
+    const actual = ctx.args[left.index]
+    if (actual?.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
+    const element = actual.value[left.element]
+    if (element?.type !== 'map') return { permit: false, reason: 'ARG_MISMATCH' }
+    if (!Array.isArray(element.value)) return { permit: false, reason: 'ARG_MISMATCH' }
+    const entry = element.value.find((e) => e.key === left.field)
+    if (!entry) return { permit: false, reason: 'ARG_MISMATCH' }
+    if (op === 'eq') return evalArgEq(op, entry.val, right)
+    return evalArgOrderedCompare(op, entry.val, right)
+  }
+
+  // Unknown leaf/op combination - structural fail-closed.
+  return { permit: false, reason: 'UNSUPPORTED_NODE' }
+}
+
+/** 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: 'eq' | 'lte', actual: ScVal | undefined, right: PredicateLeaf): EvalResult {
+  // 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)
+      ? { permit: true }
+      : { permit: false, reason: 'ARG_MISMATCH' }
+  }
+
+  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' }
+  }
+
+  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' }
+  }
+
+  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' }
+  }
+
+  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' }
+  }
+
+  // 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 (lte) on a `call_arg`. The interpreter reads the
+ *  arg as an integer (i128 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. */
+function evalArgOrderedCompare(
+  op: 'eq' | 'lte',
+  actual: ScVal | undefined,
+  right: PredicateLeaf
+): EvalResult {
+  const actualInt = argNumericBigInt(actual)
+  const literalInt = literalNumericBigInt(right)
+  if (actualInt === null || literalInt === null) {
+    return { permit: false, reason: 'ARG_MISMATCH' }
+  }
+  return bigintCmp(op, actualInt.toString(), literalInt.toString())
+    ? { permit: true }
+    : { permit: false, reason: 'ARG_MISMATCH' }
+}
+
+/** BigInt value of a numeric-integer ScVal arg (i128 / u32), or null when
+ *  the arg is absent, opaque, or a non-numeric type. */
+function argNumericBigInt(actual: ScVal | undefined): bigint | null {
+  if (!actual) return null
+  if (actual.type === 'i128' || actual.type === 'u32') {
+    try {
+      return BigInt(actual.value)
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+/** BigInt value of a numeric-integer literal leaf (`literal_i128` / `literal_u32`),
+ *  or null for a non-numeric literal. Callers fail closed on null. */
+function literalNumericBigInt(leaf: PredicateLeaf): bigint | null {
+  switch (leaf.kind) {
+    case 'literal_i128':
+      try {
+        return BigInt(leaf.value)
+      } catch {
+        return null
+      }
+    case 'literal_u32':
+      return BigInt(leaf.value)
+    default:
+      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: ScVal[], expected: PredicateLeaf[]): boolean {
+  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)
+    if (!r.permit) return false
+  }
+  return true
+}
+
+/** `in` membership. Empty haystack ALWAYS denies. Opaque needle fails closed. */
+function evalIn(needle: PredicateLeaf, haystack: PredicateLeaf[], ctx: EvalContext): EvalResult {
+  if (haystack.length === 0) return { permit: false, reason: 'NOT_IN_ALLOWLIST' }
+  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)
+    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: PredicateLeaf, ctx: EvalContext): ScVal | undefined {
+  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 'call_arg_len':
+      // No direct ScVal projection: the length is an integer the comparator
+      // resolves against the right-hand literal. Returning undefined keeps
+      // the `in` membership path structurally informed (no haystack match).
+      return undefined
+    case 'call_arg_field': {
+      const actual = ctx.args[leaf.index]
+      if (actual?.type !== 'vec') return undefined
+      const element = actual.value[leaf.element]
+      if (element?.type !== 'map') return undefined
+      if (!Array.isArray(element.value)) return undefined
+      const entry = element.value.find((e) => e.key === leaf.field)
+      return entry ? entry.val : undefined
+    }
+    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_vec':
+      return undefined
+  }
+}
+
+/** BigInt compare helper. */
+function bigintCmp(op: 'eq' | 'lte', aStr: string, bStr: string): boolean {
+  const a = BigInt(aStr)
+  const b = BigInt(bStr)
+  switch (op) {
+    case 'eq':
+      return a === b
+    case 'lte':
+      return a <= b
+  }
+}

package/src/simulate/index.ts

@@ -0,0 +1,11 @@
+// src/simulate/index.ts - the off-chain evaluation engine.
+//
+// `evaluate` is a second implementation of the on-chain predicate semantics.
+// The conformance harness runs it and the Rust interpreter against the same
+// predicate and asserts the verdicts match, so a divergence between the two
+// fails CI rather than reaching a user as a wrong simulation.
+
+export type { DenyCase, GeneratedCases } from './deny-cases.ts'
+export { generateCases } from './deny-cases.ts'
+export type { EvalContext, EvalResult } from './evaluate.ts'
+export { evaluate } from './evaluate.ts'