@crediolabs/policy-synth 0.1.9 → 0.1.11

package/src/predicate/encode.ts

@@ -18,6 +18,19 @@
 //
 // Caps from `PREDICATE_CAPS` are enforced BEFORE returning; a cap breach throws
 // a `ToolError` with the matching error code and `severity: 'error'`.
+//
+// The encoder is also the gate for the structures the contract refuses: an
+// empty `and`/`or` child list and an empty `in` haystack (MALFORMED_PREDICATE
+// at decode, dsl.rs), an `oracle_price` under a `not`/`or`, and an oracle bound
+// with no non-oracle constraint beside it (validate_oracle_placement at
+// install).
+//
+// One gap remains, deliberately: the `amount` / `window_spent` leaf branches
+// below are dead ABI - the contract's grammar no longer has those selector
+// symbols, so a predicate carrying one is MALFORMED at decode. The interpreter
+// adapter reports them as uncovered before lowering, so the product path
+// cannot emit one; removing the branches (and the leaf kinds) is a separate
+// change.
 
 import { createHash } from 'node:crypto'
 import { Address, xdr } from '@stellar/stellar-sdk'
@@ -68,6 +81,12 @@ export function encodePredicate(node: PredicateNode): EncodedPredicate {
       `oracle reads ${oracleReads} exceed MAX_ORACLE_READS ${PREDICATE_CAPS.MAX_ORACLE_READS}`
     )
   }
+  if (stats.oracleAssets.size > 0 && stats.nonOracleSelectorLeaves === 0) {
+    throw capError(
+      'MALFORMED_PREDICATE',
+      'predicate constrains nothing but an oracle price: the contract refuses it at install (dsl.rs MissingNonOracleEnvelope). Pin the call itself (contract / method / argument) alongside the price bound.'
+    )
+  }
 
   // --- pass 2: build + canonicalise the ScVal ---
   const root = encodeNode(node)
@@ -89,35 +108,63 @@ interface PredicateStats {
   inCounts: Array<{ count: number }>
   /** Unique assets referenced by `oracle_price` leaves - each costs 2 reads. */
   oracleAssets: Set<string>
+  /** Selector leaves that are NOT `oracle_price`. The contract refuses a
+   *  predicate whose only constraint is an oracle read (dsl.rs
+   *  `validate_oracle_placement` -> MissingNonOracleEnvelope): a price bound
+   *  alone pins nothing about the call itself. Literals are operands, not
+   *  constraints, so they do not count. */
+  nonOracleSelectorLeaves: number
 }
 
 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 }
+  const counters = { nonOracleSelectorLeaves: 0 }
+  const { depth, leaves } = walk(node, inCounts, oracleAssets, counters, false)
+  return {
+    depth,
+    leaves,
+    inCounts,
+    oracleAssets,
+    nonOracleSelectorLeaves: counters.nonOracleSelectorLeaves,
+  }
 }
 
 function walk(
   node: PredicateNode,
   inCounts: Array<{ count: number }>,
-  oracleAssets: Set<string>
+  oracleAssets: Set<string>,
+  counters: { nonOracleSelectorLeaves: number },
+  /** True once the walk is under a `not` or an `or`, where an oracle read
+   *  becomes a condition the caller can satisfy by taking the other branch. */
+  negatedOrDisjunctive: boolean
 ): { depth: number; leaves: number } {
   switch (node.op) {
     case 'and':
     case 'or': {
-      if (node.children.length === 0) return { depth: 1, leaves: 0 }
+      if (node.children.length === 0) {
+        throw capError(
+          'MALFORMED_PREDICATE',
+          `\`${node.op}\` with no children: the contract refuses it at decode (MALFORMED_PREDICATE), so it can never be installed`
+        )
+      }
       let maxChildDepth = 0
       let totalLeaves = 0
       for (const c of node.children) {
-        const child = walk(c, inCounts, oracleAssets)
+        const child = walk(
+          c,
+          inCounts,
+          oracleAssets,
+          counters,
+          negatedOrDisjunctive || node.op === 'or'
+        )
         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)
+      const child = walk(node.child, inCounts, oracleAssets, counters, true)
       return { depth: child.depth + 1, leaves: child.leaves }
     }
     case 'eq':
@@ -125,16 +172,22 @@ function walk(
     case 'lte':
     case 'gt':
     case 'gte': {
-      collectOracle(node.left, oracleAssets)
-      collectOracle(node.right, oracleAssets)
+      collectOracle(node.left, oracleAssets, counters, negatedOrDisjunctive)
+      collectOracle(node.right, oracleAssets, counters, negatedOrDisjunctive)
       return { depth: 1, leaves: leafCount(node.left) + leafCount(node.right) }
     }
     case 'in': {
+      if (node.haystack.length === 0) {
+        throw capError(
+          'MALFORMED_PREDICATE',
+          '`in` with an empty haystack: the contract refuses it at decode (MALFORMED_PREDICATE), so it can never be installed'
+        )
+      }
       inCounts.push({ count: node.haystack.length })
-      collectOracle(node.needle, oracleAssets)
+      collectOracle(node.needle, oracleAssets, counters, negatedOrDisjunctive)
       let haystackLeaves = 0
       for (const h of node.haystack) {
-        collectOracle(h, oracleAssets)
+        collectOracle(h, oracleAssets, counters, negatedOrDisjunctive)
         haystackLeaves += leafCount(h)
       }
       return {
@@ -157,14 +210,31 @@ function leafCount(leaf: PredicateLeaf): number {
   return 1
 }
 
-function collectOracle(leaf: PredicateLeaf, oracleAssets: Set<string>): void {
+function collectOracle(
+  leaf: PredicateLeaf,
+  oracleAssets: Set<string>,
+  counters: { nonOracleSelectorLeaves: number },
+  negatedOrDisjunctive: boolean
+): 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') {
+    if (negatedOrDisjunctive) {
+      throw capError(
+        'ORACLE_LEAF_INVALID_POSITION',
+        `oracle_price(${leaf.asset}) sits under a \`not\`/\`or\`: the contract refuses that position at install (dsl.rs validate_oracle_placement). An oracle bound must be a conjunct the call has to satisfy.`
+      )
+    }
     oracleAssets.add(leaf.asset)
   } else if (leaf.kind === 'literal_vec') {
-    for (const el of leaf.elements) collectOracle(el, oracleAssets)
+    for (const el of leaf.elements) collectOracle(el, oracleAssets, counters, negatedOrDisjunctive)
+  } else if (!leaf.kind.startsWith('literal_') && leaf.kind !== 'oracle_threshold') {
+    // A threshold is the oracle compare's operand, not an independent
+    // constraint. Counting it would let an oracle-only predicate satisfy the
+    // non-oracle envelope with its own bound (mirrors collect_oracle_leaf in
+    // dsl.rs, where it sits with the literals).
+    counters.nonOracleSelectorLeaves += 1
   }
 }
 
@@ -216,6 +286,17 @@ function encodeLeaf(leaf: PredicateLeaf): xdr.ScVal {
         xdr.ScVal.scvU32(leaf.element),
         xdr.ScVal.scvSymbol(leaf.field),
       ])
+    case 'call_arg_scaled':
+      // Wire shape `vec[symbol, u32, i128, i128]` mirrors the Rust decoder's
+      // expectation in dsl.rs SEL_CALL_ARG_SCALED. `scvI128FromDecimal` is
+      // the same range-checked helper used by `literal_i128`; an out-of-range
+      // num/den is refused at encode time (rather than at install on chain).
+      return xdr.ScVal.scvVec([
+        symbol('call_arg_scaled'),
+        xdr.ScVal.scvU32(leaf.index),
+        scvI128FromDecimal(leaf.num),
+        scvI128FromDecimal(leaf.den),
+      ])
     case 'amount':
       return xdr.ScVal.scvVec([symbol('amount'), scvAddressFromStrkey(leaf.token)])
     case 'window_spent':
@@ -227,11 +308,27 @@ function encodeLeaf(leaf: PredicateLeaf): xdr.ScVal {
     case 'now':
       return xdr.ScVal.scvVec([symbol('now')])
     case 'valid_until':
-      return xdr.ScVal.scvVec([symbol('valid_until')])
+      // The interpreter refuses this leaf at install: it never sources
+      // valid_until_ledger, so a policy built on it would deny forever.
+      // Expiry belongs to the smart account, through the context rule's
+      // validUntilLedger. Refuse at synthesis so the author finds out here
+      // rather than from an install that always fails.
+      throw new Error(
+        'valid_until is not a usable predicate leaf: the interpreter never sources it and ' +
+          'refuses it at install. Put expiry on the context rule (validUntilLedger) instead.'
+      )
     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 'oracle_threshold':
+      // Arity 3, matching SEL_ORACLE_THRESHOLD in dsl.rs. The declared basis
+      // travels with the value so the contract never has to assume one.
+      return xdr.ScVal.scvVec([
+        symbol('oracle_threshold'),
+        scvI128FromDecimal(leaf.value),
+        xdr.ScVal.scvU32(leaf.decimals),
+      ])
     case 'literal_address':
       return scvAddressFromStrkey(leaf.value)
     case 'literal_i128':

package/src/predicate/from-json.ts

@@ -0,0 +1,124 @@
+// src/predicate/from-json.ts - parse untrusted JSON into a `PredicateNode`.
+//
+// The counterpart to `encodePredicate`: that turns a typed node into the
+// canonical wire bytes, this turns arbitrary parsed JSON into a typed node,
+// or throws. Anything accepting a hand-written policy needs both, so both
+// belong in this package rather than in whichever app happened to grow the
+// paste box first.
+//
+// Deliberately shape-only. Structural caps (depth, node count, argument
+// count) stay in the encoder, which is the gate the contract's decoder
+// mirrors; duplicating them here would give two places to drift.
+
+import type { PredicateLeaf, PredicateNode } from '../types.ts'
+
+/** Parse a JSON object back into a `PredicateNode`. Throws on shape
+ *  mismatches. The encoder's structural caps are the real gate. */
+export function jsonToAst(value: unknown): PredicateNode {
+  if (value === null || typeof value !== 'object') throw new Error('predicate must be an object')
+  const v = value as {
+    op?: unknown
+    children?: unknown
+    child?: unknown
+    left?: unknown
+    right?: unknown
+    needle?: unknown
+    haystack?: unknown
+  }
+  switch (v.op) {
+    case 'and':
+    case 'or':
+      return { op: v.op, children: arrayOf(v.children, jsonToAst) }
+    case 'not':
+      return { op: 'not', child: jsonToAst(v.child) }
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      return { op: v.op, left: jsonToLeaf(v.left), right: jsonToLeaf(v.right) }
+    case 'in':
+      return { op: 'in', needle: jsonToLeaf(v.needle), haystack: arrayOf(v.haystack, jsonToLeaf) }
+    default:
+      throw new Error(`unknown predicate op: ${String(v.op)}`)
+  }
+}
+
+function arrayOf<T>(v: unknown, f: (x: unknown) => T): T[] {
+  if (!Array.isArray(v)) throw new Error('expected array')
+  return v.map(f)
+}
+
+function jsonToLeaf(value: unknown): PredicateLeaf {
+  if (value === null || typeof value !== 'object') throw new Error('leaf must be an object')
+  const v = value as { kind?: unknown; [k: string]: unknown }
+  switch (v.kind) {
+    case 'call_contract':
+    case 'call_fn':
+    case 'now':
+    case 'valid_until':
+      return { kind: v.kind }
+    case 'call_arg':
+      return { kind: 'call_arg', index: numberField(v, 'index') }
+    case 'call_arg_len':
+      return { kind: 'call_arg_len', index: numberField(v, 'index') }
+    // num/den are strings, not numbers: they are i128 on chain, and a JSON
+    // number would silently lose precision past 2^53 before the encoder
+    // ever saw the value.
+    case 'call_arg_scaled':
+      return {
+        kind: 'call_arg_scaled',
+        index: numberField(v, 'index'),
+        num: stringField(v, 'num'),
+        den: stringField(v, 'den'),
+      }
+    case 'call_arg_field':
+      return {
+        kind: 'call_arg_field',
+        index: numberField(v, 'index'),
+        element: numberField(v, 'element'),
+        field: stringField(v, 'field'),
+      }
+    case 'amount':
+      return { kind: 'amount', token: stringField(v, 'token') }
+    case 'window_spent':
+      return {
+        kind: 'window_spent',
+        token: stringField(v, 'token'),
+        windowSeconds: numberField(v, 'windowSeconds'),
+      }
+    case 'invocation_count_in_window':
+      return { kind: 'invocation_count_in_window', windowSecs: numberField(v, 'windowSecs') }
+    case 'oracle_price':
+      return { kind: 'oracle_price', asset: stringField(v, 'asset') }
+    case 'literal_address':
+      return { kind: 'literal_address', value: stringField(v, 'value') }
+    case 'literal_i128':
+      return { kind: 'literal_i128', value: stringField(v, 'value') }
+    case 'literal_symbol':
+      return { kind: 'literal_symbol', value: stringField(v, 'value') }
+    case 'literal_u32':
+      return { kind: 'literal_u32', value: numberField(v, 'value') }
+    case 'literal_u64':
+      return { kind: 'literal_u64', value: stringField(v, 'value') }
+    case 'literal_bytes':
+      return { kind: 'literal_bytes', value: stringField(v, 'value') }
+    case 'literal_vec':
+      return { kind: 'literal_vec', elements: arrayOf(v.elements, jsonToLeaf) }
+    default:
+      throw new Error(`unknown leaf kind: ${String(v.kind)}`)
+  }
+}
+
+function numberField(v: { [k: string]: unknown }, key: string): number {
+  const x = v[key]
+  if (typeof x !== 'number' || !Number.isInteger(x))
+    throw new Error(`field ${key} must be an integer`)
+  return x
+}
+
+function stringField(v: { [k: string]: unknown }, key: string): string {
+  const x = v[key]
+  if (typeof x !== 'string') throw new Error(`field ${key} must be a string`)
+  return x
+}

package/src/predicate/index.ts

@@ -1,3 +1,7 @@
-// src/predicate/index.ts - re-export the canonical predicate encoder.
+// src/predicate/index.ts - re-export the canonical predicate encoder and the
+// untrusted-JSON parser that feeds it. A consumer accepting a hand-written
+// policy needs both halves.
 
 export { type EncodedPredicate, encodePredicate } from './encode.ts'
+export { decodeLeaf, decodeNode, decodePredicate } from './decode.ts'
+export { jsonToAst } from './from-json.ts'

package/src/registry/identify.ts

@@ -16,6 +16,13 @@
 //   3. SoroSwap: recognised by ADDRESS only - the router is a single pinned
 //      contract. FIX 4: the method must ALSO be present in the protocol's
 //      ABI; an unknown method on a pinned router -> null (fail-closed).
+//   4. OZ smart-account: recognised by INTERFACE - the user-facing context
+//      rule entrypoints (`batch_add_signer` / `batch_remove_signer` /
+//      `add_context_rule` / `remove_context_rule`) have a fixed (fn, args)
+//      shape across every OZ multisig deployment. Pinned per-deployment
+//      addresses are impossible (every user deploys their own smart
+//      account), so interface recognition is the only viable path - same
+//      reasoning SEP-41 uses for any token address.
 //
 // Method lookup uses `Object.hasOwn` rather than `in` so prototype-chain
 // names like `constructor`, `toString`, `hasOwnProperty` do NOT register as
@@ -25,7 +32,7 @@
 import type { ScVal } from '../types.ts'
 import { addressToProtocol } from './known-addresses.ts'
 import type { AbiArg, ProtocolId } from './protocols.ts'
-import { BLEND_ABI, SEP41_ABI, SOROSWAP_ABI } from './protocols.ts'
+import { BLEND_ABI, OZ_ACCOUNT_ABI, SEP41_ABI, SOROSWAP_ABI } from './protocols.ts'
 
 export interface IdentifiedProtocol {
   protocol: ProtocolId
@@ -62,7 +69,20 @@ export function identifyProtocol(
     return null
   }
 
-  // 3) Pinned-address recognition (Blend factory + SoroSwap router/factory).
+  // 3) OpenZeppelin smart-account by interface. The four context-rule
+  //    entrypoints have a fixed (fn, args) shape across every OZ
+  //    multisig deployment. `__check_auth` is private (host-invoked)
+  //    and is intentionally NOT in this ABI - the recogniser only
+  //    claims OZ for the public surface.
+  if (Object.hasOwn(OZ_ACCOUNT_ABI, method)) {
+    const sig = OZ_ACCOUNT_ABI[method]
+    if (sig && argsMatchAbi(sig.args, args)) {
+      return { protocol: 'oz_account', fn: method }
+    }
+    return null
+  }
+
+  // 4) Pinned-address recognition (Blend factory + SoroSwap router/factory).
   //    FIX 4: the method must also be in the protocol's ABI; an unknown
   //    method on a pinned address -> null.
   if (network) {

package/src/registry/protocols.ts

@@ -19,7 +19,7 @@
 
 import type { ScVal } from '../types.ts'
 
-export type ProtocolId = 'sep41' | 'blend' | 'soroswap'
+export type ProtocolId = 'sep41' | 'blend' | 'soroswap' | 'oz_account'
 
 /** ScVal subset type vocabulary the ABI uses. Mirrors `ScVal['type']` minus
  *  `other` (which by definition cannot be matched against an ABI arg). */
@@ -165,10 +165,99 @@ export const SOROSWAP_ABI: ProtocolAbi = {
   },
 }
 
+/** OpenZeppelin smart-account ABI subset.
+ *
+ *  Why this lives in the recogniser: every user's smart account has a
+ *  different C-address, so a per-deployment pin would never cover them.
+ *  What is the same across every OpenZeppelin multisig account is the
+ *  small set of public context-rule entrypoints. A recording that
+ *  invokes `batch_add_signer(u32, vec<signer>)` on an arbitrary contract
+ *  is overwhelmingly likely to be calling the user's own OpenZeppelin
+ *  smart account (the canonical reason this product exists); we
+ *  recognise that pattern by interface, the same way SEP-41 is
+ *  recognised by interface.
+ *
+ *  SECURITY PROPERTY (load-bearing):
+ *   - Recognition claims the call TARGETS a particular protocol. We
+ *     only claim `oz_account` when the (fn, args) shape uniquely matches
+ *     one of the three entrypoints below AND the call looks like a real
+ *     context-rule operation. The match is exact: off-by-one arg count,
+ *     off-by-one arg type, or a method name close-but-wrong returns null
+ *     (fail-closed). A contract that incidentally happens to expose a
+ *     single matching fn is not sufficient - the recorder requires ALL
+ *     invocations to individually match, so a hostile contract with
+ *     exactly one matching fn would still contribute to the unknown
+ *     bucket for any other calls.
+ *   - We do NOT claim `oz_account` for unknown calls, for arg-shape
+ *     mismatches, or for calls where the recorder could not pin down
+ *     the (fn, args) shape. The freshness gate then runs at the same
+ *     1.0 threshold - lowering the gate for unknown protocols remains
+ *     a separate, opt-in production override (see RecordInput below).
+ *
+ *  ABI source: packages/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
+ *  pinned from the OpenZeppelin Reloaded `multisig_account_example`
+ *  contract (commit ef82b65, fetched 2026-07-28).
+ *
+ *  SCOPE NOTE: this ABI only covers the three entrypoints whose args
+ *  map cleanly onto the normalised `AbiArgType` vocabulary (u32, vec,
+ *  ...). `add_context_rule` - the install path - takes `(Symbol,
+ *  String, Option<u32>, Vec<SignerKey>, Map<Address, Val>)`. The
+ *  `String`, `Option<u32>` (`scvVoid`), and `Map<...>` arg types are
+ *  not in the AbiArgType set today (the recogniser's `argsMatchAbi`
+ *  helper rejects `other` deliberately so a close-but-wrong call does
+ *  not slip through). Excluding `add_context_rule` is the right
+ *  trade-off for now - it never blocks OZ smart-account recognition,
+ *  because the install tx always follows a recognised
+ *  `batch_add_signer` (the demo's first-pass tx), so the
+ *  contract still ends up in `knownContracts`. Updating the Arg type
+ *  vocabulary to cover these shapes is a separate concern (and would
+ *  also lift the SEP-41 / Blend recognition in the same change).
+ */
+export const OZ_ACCOUNT_ABI: ProtocolAbi = {
+  batch_add_signer: {
+    args: [
+      {
+        name: 'context_rule_id',
+        type: 'u32',
+        meaning: 'OZ context rule id this signer is added to',
+      },
+      {
+        name: 'signers',
+        type: 'vec',
+        meaning: 'vec<SignerKey> signers to add (Delegated G-address or Account C-address)',
+      },
+    ],
+  },
+  batch_remove_signer: {
+    args: [
+      {
+        name: 'context_rule_id',
+        type: 'u32',
+        meaning: 'OZ context rule id to remove signers from',
+      },
+      {
+        name: 'signers',
+        type: 'vec',
+        meaning: 'vec<SignerKey> signers to remove from the rule',
+      },
+    ],
+  },
+  remove_context_rule: {
+    args: [
+      {
+        name: 'context_rule_id',
+        type: 'u32',
+        meaning: 'OZ context rule id to delete',
+      },
+    ],
+  },
+}
+
 export const PROTOCOL_ABIS: Record<ProtocolId, ProtocolAbi> = {
   sep41: SEP41_ABI,
   blend: BLEND_ABI,
   soroswap: SOROSWAP_ABI,
+  oz_account: OZ_ACCOUNT_ABI,
 }
 
 export function getAbi(protocol: ProtocolId): ProtocolAbi {

package/src/review-card/builder.ts

@@ -16,7 +16,7 @@
 //
 //   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
+//        - invocation_count_in_window < N     -> At most N calls 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
@@ -107,6 +107,23 @@ function renderOzPrimitive(ref: PolicyRef): string | null {
  *  `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. */
+/** Every constraint sentence for one predicate, in walk order.
+ *
+ *  `buildReviewCardSummary` renders a policy the synthesiser just PRODUCED,
+ *  and needs the refs / context rule / simulation to do it. This renders a
+ *  predicate on its own, which is what a caller holding a policy already
+ *  INSTALLED on chain has: it can read the document out of the interpreter's
+ *  storage and decode it, but there is no proposal around it. Same renderers,
+ *  so an installed rule reads exactly as it did on the review card. */
+export function describePredicate(predicate: PredicateNode): string[] {
+  const constraints: string[] = []
+  walkPredicate(predicate, (node) => {
+    const line = renderConstraint(node)
+    if (line !== null) constraints.push(line)
+  })
+  return constraints
+}
+
 function walkPredicate(node: PredicateNode, visit: (node: PredicateNode) => void): void {
   switch (node.op) {
     case 'and':
@@ -171,9 +188,38 @@ function renderComparison(
     return `Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`
   }
 
-  // invocation_count_in_window <= N -> Invocations <= N per <window> seconds
+  // eq(call_arg_len[i], literal_u32) -> Length of arg[i] is K
+  // Binds the OUTER vec length so a caller cannot append an element to
+  // defeat a per-element pin. Rendered as a single readable line so the
+  // review card surfaces the implicit "no new elements" guarantee.
+  if (left.kind === 'call_arg_len' && node.op === 'eq' && right.kind === 'literal_u32') {
+    return `Length of arg[${left.index}] is ${right.value}`
+  }
+
+  // eq/lte(call_arg_field[i, el, field], <literal>) -> arg[i] element[el].field = <value>
+  // The structured-argument bind pins a scalar field inside a vec element.
+  // For lt/gt/lte/gte the line reads "OP <value>" so the comparison kind
+  // is visible; eq reads "= <value>".
+  if (left.kind === 'call_arg_field') {
+    const head = `arg[${left.index}] element[${left.element}].${left.field}`
+    const sep = node.op === 'eq' ? '=' : comparisonOpText(node.op)
+    if (right.kind === 'literal_address') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_symbol') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_bytes') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_u64') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_i128') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_u32') return `${head} ${sep} ${right.value}`
+    if (right.kind === 'literal_vec') {
+      return `${head} ${sep} [${right.elements.map(renderVecElement).join(', ')}]`
+    }
+  }
+
+  // The bound is compared against the calls ALREADY made in the window, so
+  // `< N` permits N of them and `<= N` permits one more. Report how many
+  // calls the rule allows rather than restating the comparison.
   if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
-    return `Invocations <= ${right.value} per ${left.windowSecs} seconds`
+    const allowed = node.op === 'lt' ? right.value : right.value + 1
+    return `At most ${allowed} calls per ${left.windowSecs} seconds`
   }
 
   // amount <= v -> Amount <= v
@@ -182,8 +228,8 @@ function renderComparison(
   }
 
   // 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}`
+  if (left.kind === 'oracle_price' && right.kind === 'oracle_threshold') {
+    return `Only when oracle_price(${left.asset}) ${comparisonOpText(node.op)} ${right.value} (${right.decimals} dp)`
   }
 
   // Any other comparison shape is a structural fail-closed: do not surface
@@ -224,6 +270,7 @@ function renderVecElement(leaf: PredicateLeaf): string {
     case 'call_arg':
     case 'call_arg_len':
     case 'call_arg_field':
+    case 'call_arg_scaled':
     case 'amount':
     case 'window_spent':
     case 'now':
@@ -231,6 +278,11 @@ function renderVecElement(leaf: PredicateLeaf): string {
     case 'invocation_count_in_window':
     case 'oracle_price':
       return `<${leaf.kind}>`
+    // Show the declared basis, not just the digits. A threshold on the wrong
+    // basis is the one policy error the contract cannot detect, so the review
+    // card is where a human has to be able to see it.
+    case 'oracle_threshold':
+      return `${leaf.value} (${leaf.decimals} dp)`
   }
 }