@crediolabs/policy-synth 0.1.3 → 0.1.5

package/src/record/decode.ts

@@ -18,13 +18,14 @@
 
 import { Address, StrKey, xdr } from '@stellar/stellar-sdk'
 import { identifyProtocol } from '../registry/identify.ts'
-import type {
-  ContractInvocation,
-  Network,
-  OnChainEvent,
-  ParseConfidence,
-  ScVal,
-  TokenMovement,
+import {
+  type ContractInvocation,
+  MAX_SCVAL_DEPTH,
+  type Network,
+  type OnChainEvent,
+  type ParseConfidence,
+  type ScVal,
+  type TokenMovement,
 } from '../types.ts'
 
 /** Result of decoding an envelope XDR plus the surrounding metadata from
@@ -334,11 +335,15 @@ function symbolValueFromBufferOrString(s: string | Buffer): string {
 /** Map an arbitrary ScVal into the normalised `ScVal` subset defined in
  *  types.ts. Anything outside the subset is wrapped as `{type:'other', value}`
  *  AND recorded in `opaqueScVals` so the freshness module can reduce
- *  parseConfidence. */
+ *  parseConfidence. Recursion is bounded by `MAX_SCVAL_DEPTH` so a
+ *  hand-crafted nested-vec payload cannot RangeError the JS stack; the
+ *  over-depth branch is collapsed to a single opaque `depth-exceeded` token
+ *  (the recorder's parseConfidence gate then fails the recording closed). */
 export function scValToSubset(
   val: xdr.ScVal,
   path: string,
-  opaqueScVals: ParseConfidence['opaqueScVals']
+  opaqueScVals: ParseConfidence['opaqueScVals'],
+  depth = 0
 ): ScVal {
   const kind = val.switch().name
   switch (kind) {
@@ -364,11 +369,17 @@ export function scValToSubset(
       return { type: 'symbol', value: val.sym().toString() }
     }
     case 'scvVec': {
+      if (depth >= MAX_SCVAL_DEPTH) {
+        // Over-depth branch: collapse to a single opaque terminal so the
+        // downstream parseConfidence gate sees the fail-closed freshness hit.
+        opaqueScVals.push({ path, type: 'depth-exceeded' })
+        return { type: 'other', value: 'depth-exceeded' }
+      }
       const arr = (val.vec() ?? []) as xdr.ScVal[]
       return {
         type: 'vec',
         value: arr.map((v: xdr.ScVal, i: number) =>
-          scValToSubset(v, `${path}[${i}]`, opaqueScVals)
+          scValToSubset(v, `${path}[${i}]`, opaqueScVals, depth + 1)
         ),
       }
     }

package/src/review-card/builder.ts

@@ -0,0 +1,303 @@
+// src/review-card/builder.ts - deterministic, pure review-card summary
+// builder.
+//
+// `buildReviewCardSummary` renders the per-policy text the user-facing review
+// card quotes. The whole DX win of non-engineer reviewability hinges on the
+// summary being REPRODUCIBLE + TESTABLE + NON-HALLUCINABLE, so this module is
+// pure: same inputs -> byte-identical output, no clock, no randomness, no I/O.
+//
+// The builder walks two inputs and emits ONE constraint string per leaf or
+// primitive, in a fixed deterministic order:
+//
+//   1. The OZ built-in `PolicyRef`s. Each `spending_limit` primitive becomes a
+//      `spending_limit(token, limitAmount, windowSecs)` line; other OZ
+//      primitives (threshold) are skipped - the review card does not quote
+//      them (they are signer-config concerns, not transactional bounds).
+//
+//   2. The interpreter `PredicateNode`. One string per constraint leaf,
+//      rendered by enclosing-comparison kind. Templates (Task 7b):
+//        - invocation_count_in_window <= N    -> Invocations <= N per <window> seconds
+//        - call_arg[i] in [list]              -> Recipient/arg must be one of [list]
+//        - eq(call_arg[i], literal_vec[...])  -> Path must be exactly [list]
+//        - oracle_price(asset) OP price       -> Only when oracle_price(asset) OP price
+//        - call_fn == x                       -> Function must be x
+//        - call_contract == c                 -> Contract must be c
+//        - amount <= v                        -> Amount <= v
+//
+// The content hash is a stable sha256 hex of a canonical JSON of
+// { ruleName, plainEnglish, constraints, expiry, backend } - identical
+// inputs (incl. the context-rule expiry and simulation backend) -> identical
+// hash. There is no clock; the hash never includes a timestamp.
+
+import { createHash } from 'node:crypto'
+import type {
+  ContextRuleDraft,
+  OZPrimitiveConfig,
+  PolicyRef,
+  PredicateLeaf,
+  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 function buildReviewCardSummary(
+  predicate: PredicateNode | null,
+  policyRefs: PolicyRef[],
+  contextRule: ContextRuleDraft,
+  simulation: SimulationResult
+): ReviewCardSummary {
+  const constraints: string[] = []
+  for (const ref of policyRefs) {
+    const line = renderOzPrimitive(ref)
+    if (line !== null) constraints.push(line)
+  }
+  if (predicate !== null) {
+    walkPredicate(predicate, (node) => {
+      const line = renderConstraint(node)
+      if (line !== null) constraints.push(line)
+    })
+  }
+
+  const ruleName = contextRule.name
+  const plainEnglish = renderPlainEnglish(ruleName, constraints)
+  const expiry = renderExpiry(contextRule.validUntilLedger)
+  const backend = simulation.backend
+
+  const contentHash = computeContentHash({
+    ruleName,
+    plainEnglish,
+    constraints,
+    expiry,
+    backend,
+  })
+
+  return { ruleName, plainEnglish, constraints, expiry, backend, contentHash }
+}
+
+/** Render the OZ built-in primitive summary line. Only `spending_limit` is
+ *  quoted by the review card (it is the only primitive that defines a
+ *  transactional bound). Other primitives (threshold) are signer-config
+ *  concerns handled by the OZ adapter's own `uncovered` machinery.
+ *  Spending_limit takes `period_ledgers` on-chain (~5s/ledger); the card
+ *  states the window in seconds so the user reads it consistently with the
+ *  interpreter templates. */
+function renderOzPrimitive(ref: PolicyRef): string | null {
+  if (ref.kind !== 'oz_builtin') return null
+  const primitive: OZPrimitiveConfig = ref.primitive
+  if (primitive.primitive !== 'spending_limit') return null
+  const params = primitive.params as { spending_limit?: string; period_ledgers?: number }
+  const limit = params.spending_limit ?? '0'
+  const periodLedgers = params.period_ledgers ?? 0
+  const windowSecs = periodLedgers * 5
+  return `spending_limit(${limit}, ${windowSecs})`
+}
+
+/** Walk every comparison / membership node of the predicate and invoke
+ *  `visit` on each. The walk is depth-first, left-to-right, so the
+ *  constraint list is stable across runs. Pure boolean nodes contribute no
+ *  constraint lines themselves; their leaf children do, via the visitor. */
+function walkPredicate(node: PredicateNode, visit: (node: PredicateNode) => void): void {
+  switch (node.op) {
+    case 'and':
+    case 'or':
+      for (const child of node.children) walkPredicate(child, visit)
+      return
+    case 'not':
+      walkPredicate(node.child, visit)
+      return
+    case 'in':
+      visit(node)
+      return
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      visit(node)
+      return
+  }
+}
+
+/** Render ONE constraint sentence for ONE interpreter predicate node. The
+ *  shape of the output is pinned by Task 7b so the test suite can assert
+ *  byte-for-byte equality. Returns `null` when the node is a structural
+ *  boolean (`and` / `or` / `not`) - those are not constraint leaves. */
+function renderConstraint(node: PredicateNode): string | null {
+  switch (node.op) {
+    case 'and':
+    case 'or':
+    case 'not':
+      return null
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      return renderComparison(node)
+    case 'in':
+      return renderMembership(node)
+  }
+}
+
+function renderComparison(
+  node: Extract<PredicateNode, { op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte' }>
+): string | null {
+  const left = node.left
+  const right = node.right
+
+  // eq(call_contract, literal_address) -> Contract must be <addr>
+  if (left.kind === 'call_contract' && node.op === 'eq' && right.kind === 'literal_address') {
+    return `Contract must be ${right.value}`
+  }
+
+  // eq(call_fn, literal_symbol) -> Function must be <sym>
+  if (left.kind === 'call_fn' && node.op === 'eq' && right.kind === 'literal_symbol') {
+    return `Function must be ${right.value}`
+  }
+
+  // eq(call_arg[i], literal_vec) -> Path must be exactly [list]
+  if (left.kind === 'call_arg' && node.op === 'eq' && right.kind === 'literal_vec') {
+    return `Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`
+  }
+
+  // invocation_count_in_window <= N -> Invocations <= N per <window> seconds
+  if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
+    return `Invocations <= ${right.value} per ${left.windowSecs} seconds`
+  }
+
+  // amount <= v -> Amount <= v
+  if (left.kind === 'amount' && right.kind === 'literal_i128') {
+    return `Amount <= ${right.value}`
+  }
+
+  // oracle_price(asset) OP price -> Only when oracle_price(asset) OP price
+  if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
+    return `Only when oracle_price(${left.asset}) ${comparisonOpText(node.op)} ${right.value}`
+  }
+
+  // Any other comparison shape is a structural fail-closed: do not surface
+  // a misleading line. Cross-check still requires every leaf produce a
+  // constraint string; the only leaves we emit lines for are the ones we
+  // recognise above, so the test fixtures cover exactly the supported
+  // shapes.
+  return null
+}
+
+function renderMembership(node: Extract<PredicateNode, { op: 'in' }>): string | null {
+  // call_arg[i] in [list] -> Recipient/arg must be one of [list]
+  if (node.needle.kind === 'call_arg') {
+    const list = node.haystack.map(renderHaystackElement).join(', ')
+    return `Recipient/arg must be one of [${list}]`
+  }
+  return null
+}
+
+function renderVecElement(leaf: PredicateLeaf): string {
+  switch (leaf.kind) {
+    case 'literal_address':
+      return leaf.value
+    case 'literal_i128':
+      return leaf.value
+    case 'literal_symbol':
+      return leaf.value
+    case 'literal_u32':
+      return String(leaf.value)
+    case 'literal_u64':
+      return leaf.value
+    case 'literal_bytes':
+      return leaf.value
+    case 'literal_vec':
+      return `[${leaf.elements.map(renderVecElement).join(', ')}]`
+    case 'call_contract':
+    case 'call_fn':
+    case 'call_arg':
+    case 'amount':
+    case 'window_spent':
+    case 'now':
+    case 'valid_until':
+    case 'invocation_count_in_window':
+    case 'oracle_price':
+      return `<${leaf.kind}>`
+  }
+}
+
+function renderHaystackElement(leaf: PredicateLeaf): string {
+  if (leaf.kind === 'literal_address') return leaf.value
+  if (leaf.kind === 'literal_i128') return leaf.value
+  if (leaf.kind === 'literal_symbol') return leaf.value
+  if (leaf.kind === 'literal_u32') return String(leaf.value)
+  if (leaf.kind === 'literal_u64') return leaf.value
+  if (leaf.kind === 'literal_bytes') return leaf.value
+  if (leaf.kind === 'literal_vec') {
+    return `[${leaf.elements.map(renderHaystackElement).join(', ')}]`
+  }
+  return `<${leaf.kind}>`
+}
+
+function comparisonOpText(op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte'): string {
+  switch (op) {
+    case 'lt':
+      return '<'
+    case 'lte':
+      return '<='
+    case 'gt':
+      return '>'
+    case 'gte':
+      return '>='
+    case 'eq':
+      return '=='
+  }
+}
+
+/** Render the plain-English one-liner. Format: `<ruleName>: <constraints>`,
+ *  joined by `; ` so the user reads one sentence per constraint. */
+function renderPlainEnglish(ruleName: string, constraints: string[]): string {
+  if (constraints.length === 0) return `${ruleName}: (no constraints)`
+  return `${ruleName}: ${constraints.join('; ')}`
+}
+
+/** Render the expiry line. `null` -> "No expiry"; a ledger sequence -> the
+ *  ledger number so the user reads it in the same units the OZ context rule
+ *  applies it. */
+function renderExpiry(validUntilLedger: number | null): string {
+  if (validUntilLedger === null) return 'No expiry'
+  return `Valid until ledger ${validUntilLedger}`
+}
+
+function computeContentHash(input: {
+  ruleName: string
+  plainEnglish: string
+  constraints: string[]
+  expiry: string
+  backend: 'interpreter-v1' | 'ts-model'
+}): string {
+  return createHash('sha256').update(canonicalStringify(input)).digest('hex')
+}
+
+/** Canonical JSON with recursively sorted object keys (stable across runs). */
+function canonicalStringify(value: unknown): string {
+  return JSON.stringify(sortKeys(value))
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = sortKeys((value as Record<string, unknown>)[key])
+    }
+    return out
+  }
+  return value
+}

package/src/review-card/conflict.ts

@@ -0,0 +1,143 @@
+// src/review-card/conflict.ts - the ConflictAnnotation 4-kind enum + the
+// `classifyConflict` classifier.
+//
+// When a user installs a new policy alongside an existing rule set, the
+// review card surfaces the relationship between the new rule and each
+// existing rule as a structured annotation. A boolean (conflict / no
+// conflict) is wrong: four qualitatively different shapes are possible, and
+// each one tells the user something different about what would happen if
+// both rules installed together.
+//
+//   - subsume            new rule's scope is a SUPERSET of an existing
+//                        rule's. The new rule is broader; installing it on
+//                        top of the existing rule weakens the existing
+//                        restriction. The existing rule becomes a no-op.
+//   - disjoint           new rule and existing rule are unrelated: their
+//                        scopes do not overlap. Safe to install both.
+//   - counter_permissive new rule and existing rule allow CONFLICTING
+//                        things at the same scope (one caps lower than the
+//                        other on the same axis). The stricter one wins
+//                        at evaluate; the looser is dead weight.
+//   - window_divergent   new rule and existing rule have the same scope
+//                        and the same per-window limit but DIFFERENT
+//                        rolling windows. Effective union = sum (the user
+//                        can spend `limit` per each window, independently).
+//
+// The classifier consumes a minimal `RuleRef` shape: the rule id, scope
+// (contract + method), and an optional spending limit + window. Shapes
+// without a limit fall back to scope-only classification.
+
+/** Minimal rule reference the classifier needs to compute the conflict kind.
+ *  Carries the rule id (used in the annotation), the scope (contract +
+ *  method), and an optional spending cap. The cap captures both the
+ *  amount and the window so the classifier can compare apples to apples. */
+export interface RuleRef {
+  id: string
+  scope: { contract?: string; method?: string }
+  /** When set, the rule enforces this per-window spend cap (token +
+   *  decimal-string amount + seconds window). */
+  spendingLimit?: { token: string; amount: string; windowSeconds: number }
+}
+
+/** Structured annotation a single new-vs-existing rule comparison yields.
+ *  Four mutually exclusive kinds; the union is exhaustive (the classifier
+ *  never throws). */
+export type ConflictAnnotation =
+  | { kind: 'subsume'; existingRuleId: string; detail: string }
+  | { kind: 'disjoint' }
+  | { kind: 'counter_permissive'; existingRuleId: string; newLimit: string; existingLimit: string }
+  | { kind: 'window_divergent'; existingRuleId: string; effectiveUnion: string }
+
+/** Classify the relationship between a new rule and one existing rule.
+ *  Pure: same pair -> same annotation. */
+export function classifyConflict(newRule: RuleRef, existingRule: RuleRef): ConflictAnnotation {
+  // --- step 1: subsume? (new.scope ⊋ existing.scope) ---
+  //
+  // Subsume requires existing to be fully scoped (both contract AND method
+  // pinned) AND new to be at least partially broader than existing. A new
+  // rule with identical scope to existing is NOT a superset - it is the
+  // same rule and falls through to the same-scope branch below. If existing
+  // is "any contract" / "any method" then it is the wildest rule in the
+  // rule set; a new rule covering it is just a duplicate, not a subsume -
+  // fall through to disjoint.
+  const existingHasContract = existingRule.scope.contract !== undefined
+  const existingHasMethod = existingRule.scope.method !== undefined
+  const newIsBroaderOnContract = newRule.scope.contract === undefined && existingHasContract
+  const newIsBroaderOnMethod = newRule.scope.method === undefined && existingHasMethod
+  const newMatchesOnContract =
+    newRule.scope.contract === undefined ||
+    (existingHasContract && newRule.scope.contract === existingRule.scope.contract)
+  const newMatchesOnMethod =
+    newRule.scope.method === undefined ||
+    (existingHasMethod && newRule.scope.method === existingRule.scope.method)
+  if (
+    existingHasContract &&
+    existingHasMethod &&
+    newMatchesOnContract &&
+    newMatchesOnMethod &&
+    (newIsBroaderOnContract || newIsBroaderOnMethod)
+  ) {
+    return {
+      kind: 'subsume',
+      existingRuleId: existingRule.id,
+      detail: `new rule scope (${describeScope(newRule)}) is a superset of existing rule (${describeScope(existingRule)})`,
+    }
+  }
+
+  // --- step 2: disjoint by scope? ---
+  if (existingHasContract && newRule.scope.contract !== undefined) {
+    if (newRule.scope.contract !== existingRule.scope.contract) {
+      return { kind: 'disjoint' }
+    }
+  }
+  if (
+    existingHasMethod &&
+    newRule.scope.method !== undefined &&
+    newRule.scope.method !== existingRule.scope.method
+  ) {
+    return { kind: 'disjoint' }
+  }
+
+  // --- step 3: same scope -> compare spend caps (when both sides carry them) ---
+  if (newRule.spendingLimit && existingRule.spendingLimit) {
+    const a = newRule.spendingLimit
+    const b = existingRule.spendingLimit
+    if (a.token !== b.token) {
+      // Same scope, different tokens: each binds a different axis. They
+      // do not counter each other; treat as disjoint.
+      return { kind: 'disjoint' }
+    }
+    if (a.windowSeconds === b.windowSeconds) {
+      // Same scope, same token, same window: counter-permissive when the
+      // amounts disagree (the stricter wins at evaluate; the looser is
+      // dead weight). Equal amounts -> duplicate rule, treat as disjoint.
+      if (a.amount === b.amount) {
+        return { kind: 'disjoint' }
+      }
+      return {
+        kind: 'counter_permissive',
+        existingRuleId: existingRule.id,
+        newLimit: `${a.amount} ${a.token} / ${a.windowSeconds}s`,
+        existingLimit: `${b.amount} ${b.token} / ${b.windowSeconds}s`,
+      }
+    }
+    // Same scope + token, different windows: effective union is the sum
+    // of the two per-window caps (each window ticks independently).
+    const union = (BigInt(a.amount) + BigInt(b.amount)).toString()
+    return {
+      kind: 'window_divergent',
+      existingRuleId: existingRule.id,
+      effectiveUnion: `${union} ${a.token} per ${a.windowSeconds}s (new) + ${b.windowSeconds}s (existing)`,
+    }
+  }
+
+  // Same scope without comparable spend caps on both sides -> disjoint.
+  return { kind: 'disjoint' }
+}
+
+function describeScope(rule: RuleRef): string {
+  const parts: string[] = []
+  parts.push(rule.scope.contract ? `contract=${rule.scope.contract}` : 'contract=*')
+  parts.push(rule.scope.method ? `method=${rule.scope.method}` : 'method=*')
+  return parts.join(', ')
+}

package/src/review-card/cross-check.ts

@@ -0,0 +1,158 @@
+// src/review-card/cross-check.ts - the non-hallucination guard.
+//
+// `summaryCrossCheck` walks EVERY leaf of the predicate and asserts the
+// review-card summary quoted a constraint string for it. Returns
+// `{ ok: false, missingConstraints }` if any leaf was dropped (or rendered
+// into a template shape the cross-check does not recognise). A
+// `PredicateNode = null` is always ok - the policy is OZ-only and the
+// interpreter predicate did not exist.
+//
+// The guard is structural: every leaf the builder is supposed to render has
+// exactly one template shape. The cross-check enumerates those shapes and
+// demands the summary carries the corresponding string. A naive summary
+// that drops a leaf (or fabricates a string not in the predicate) trips the
+// guard.
+
+import type { PredicateLeaf, PredicateNode } from '../types.ts'
+import type { ReviewCardSummary } from './builder.ts'
+
+/** Assert every leaf in the predicate appears as a constraint string in
+ *  `summary.constraints`. Returns the missing templates (without the leaf
+ *  values filled in) when any leaf was dropped. */
+export function summaryCrossCheck(
+  predicate: PredicateNode | null,
+  summary: ReviewCardSummary
+): { ok: true } | { ok: false; missingConstraints: string[] } {
+  if (predicate === null) return { ok: true }
+
+  const expected: string[] = []
+  collect(predicate, expected)
+
+  if (expected.length === 0) return { ok: true }
+
+  const present = new Set(summary.constraints)
+  const missing = expected.filter((s) => !present.has(s))
+  if (missing.length === 0) return { ok: true }
+  return { ok: false, missingConstraints: missing }
+}
+
+/** Walk the predicate and emit the EXACT constraint string the builder is
+ *  expected to produce for each leaf, in walk order. Strings here MUST
+ *  match the templates in `builder.ts` byte-for-byte; the cross-check is
+ *  the structural claim that "every supported leaf shape is rendered". */
+function collect(node: PredicateNode, out: string[]): void {
+  switch (node.op) {
+    case 'and':
+    case 'or':
+      for (const child of node.children) collect(child, out)
+      return
+    case 'not':
+      collect(node.child, out)
+      return
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      pushComparison(node.left, node.right, node.op, out)
+      return
+    case 'in':
+      pushMembership(node.needle, node.haystack, out)
+      return
+  }
+}
+
+function pushComparison(
+  left: PredicateLeaf,
+  right: PredicateLeaf,
+  op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte',
+  out: string[]
+): void {
+  if (left.kind === 'call_contract' && op === 'eq' && right.kind === 'literal_address') {
+    out.push(`Contract must be ${right.value}`)
+    return
+  }
+  if (left.kind === 'call_fn' && op === 'eq' && right.kind === 'literal_symbol') {
+    out.push(`Function must be ${right.value}`)
+    return
+  }
+  if (left.kind === 'call_arg' && op === 'eq' && right.kind === 'literal_vec') {
+    out.push(`Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`)
+    return
+  }
+  if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
+    out.push(`Invocations <= ${right.value} per ${left.windowSecs} seconds`)
+    return
+  }
+  if (left.kind === 'amount' && right.kind === 'literal_i128') {
+    out.push(`Amount <= ${right.value}`)
+    return
+  }
+  if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
+    out.push(`Only when oracle_price(${left.asset}) ${comparisonOpText(op)} ${right.value}`)
+    return
+  }
+}
+
+function pushMembership(needle: PredicateLeaf, haystack: PredicateLeaf[], out: string[]): void {
+  if (needle.kind !== 'call_arg') return
+  const list = haystack.map(renderHaystackElement).join(', ')
+  out.push(`Recipient/arg must be one of [${list}]`)
+}
+
+function renderVecElement(leaf: PredicateLeaf): string {
+  switch (leaf.kind) {
+    case 'literal_address':
+      return leaf.value
+    case 'literal_i128':
+      return leaf.value
+    case 'literal_symbol':
+      return leaf.value
+    case 'literal_u32':
+      return String(leaf.value)
+    case 'literal_u64':
+      return leaf.value
+    case 'literal_bytes':
+      return leaf.value
+    case 'literal_vec':
+      return `[${leaf.elements.map(renderVecElement).join(', ')}]`
+    case 'call_contract':
+    case 'call_fn':
+    case 'call_arg':
+    case 'amount':
+    case 'window_spent':
+    case 'now':
+    case 'valid_until':
+    case 'invocation_count_in_window':
+    case 'oracle_price':
+      return `<${leaf.kind}>`
+  }
+}
+
+function renderHaystackElement(leaf: PredicateLeaf): string {
+  if (leaf.kind === 'literal_address') return leaf.value
+  if (leaf.kind === 'literal_i128') return leaf.value
+  if (leaf.kind === 'literal_symbol') return leaf.value
+  if (leaf.kind === 'literal_u32') return String(leaf.value)
+  if (leaf.kind === 'literal_u64') return leaf.value
+  if (leaf.kind === 'literal_bytes') return leaf.value
+  if (leaf.kind === 'literal_vec') {
+    return `[${leaf.elements.map(renderHaystackElement).join(', ')}]`
+  }
+  return `<${leaf.kind}>`
+}
+
+function comparisonOpText(op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte'): string {
+  switch (op) {
+    case 'lt':
+      return '<'
+    case 'lte':
+      return '<='
+    case 'gt':
+      return '>'
+    case 'gte':
+      return '>='
+    case 'eq':
+      return '=='
+  }
+}

package/src/review-card/index.ts

@@ -0,0 +1,12 @@
+// src/review-card/index.ts - re-export the deterministic review-card surface.
+
+export {
+  buildReviewCardSummary,
+  type ReviewCardSummary,
+} from './builder.ts'
+export {
+  type ConflictAnnotation,
+  classifyConflict,
+  type RuleRef,
+} from './conflict.ts'
+export { summaryCrossCheck } from './cross-check.ts'