@crediolabs/policy-synth 0.1.3 → 0.1.5

package/src/adapters/interpreter/adapter.ts

@@ -0,0 +1,642 @@
+// src/adapters/interpreter/adapter.ts - the interpreter-policy CustodyAdapter.
+//
+// Compiles a PolicyIR to a single interpreter `PolicyDocument` + `PolicyRef`
+// carrying the canonical predicate encoding defined in
+// `packages/policy-interpreter/INTERPRETER_INSTALL_PARAMS.md`. The adapter is
+// the second backend (the OZ built-in adapter is the first); together they
+// cover the canonical language subset. The compose step (P3) routes IR
+// constructs between them.
+//
+// What it lowers (every IR construct the predicate DSL expresses):
+//   - IRLogic and/or    -> PredicateNode and/or
+//   - IRLogic not       -> PredicateNode not
+//   - IRCompare         -> selector(left) vs literal(right), op carried over
+//   - IR `in`           -> needle=selector, haystack=literals (PURESET
+//                          membership; the haystack is always sorted by the
+//                          encoder)
+//   - IR `eq_seq`       -> eq(selectorLeaf, literal_vec([...])) - exact ordered
+//                          sequence equality; element order is preserved
+//                          verbatim (the encoder does NOT sort the vec)
+//   - IRSelector        -> matching PredicateLeaf (see lowerSelector)
+//   - scope.contract    -> sibling `call_contract == <contract>` (always
+//                          emitted when set)
+//   - scope.method      -> sibling `call_fn == <method>`
+//
+// Three fail-closed enforcement gates (per spec):
+//   - oracle_price leaves MUST sit directly under the top-level `and`; nesting
+//     under `not` / `or` / inside `in` throws ORACLE_LEAF_INVALID_POSITION.
+//   - oracleParams overrides may only TIGHTEN vs wasm defaults
+//     (maxStalenessSeconds <= 600, maxDeviationBps <= 200); a widening value
+//     throws ORACLE_PARAMS_OUT_OF_RANGE at compile time.
+//   - an `in` allowlist (or a `compare eq` vs an address, or any value in an
+//     `eq_seq`) that targets the smart account's own address throws
+//     SCOPE_SELF_CALL.
+//
+// Anything the adapter genuinely cannot express (EVM calldata / value, unix
+// expiry, etc.) is named in `uncovered` rather than silently dropped.
+
+import type { ToolError } from '../../errors.ts'
+import type {
+  IRCompare,
+  IRCondition,
+  IRPolicyRule,
+  IRScalarType,
+  IRSelector,
+  PolicyIR,
+} from '../../ir/types.ts'
+import { encodePredicate } from '../../predicate/encode.ts'
+import type {
+  CompileResult,
+  CustodyAdapter,
+  CustodyCapabilities,
+  SimulationResult,
+} from '../../seams/types.ts'
+import type {
+  ContextRuleDraft,
+  Network,
+  ParseConfidence,
+  PolicyDocument,
+  PolicyRef,
+  PredicateLeaf,
+  PredicateNode,
+  ProposedPolicy,
+} from '../../types.ts'
+
+/** [VERIFY] NOT a real deployed address. The interpreter is a per-network
+ *  deploy artifact we do not have yet; install is a later phase. */
+export const PLACEHOLDER_INTERPRETER_ADDRESS = 'VERIFY-interpreter-address'
+
+/** Wasm-level oracle defaults (mirrors INTERPRETER_INSTALL_PARAMS.md OracleParams).
+ *  Per-policy overrides may TIGHTEN only - they may never exceed these. */
+export const ORACLE_DEFAULTS = {
+  maxStalenessSeconds: 600,
+  maxDeviationBps: 200,
+} as const
+
+export interface InterpreterAdapterConfig {
+  network: Network
+  /** Per-rule install nonce (first install = 1; replay-protected). */
+  installNonce: number
+  /** The smart account this interpreter policy will be installed against. Used
+   *  by the self-call gate: any `in`-allowlist containing this address is
+   *  rejected as `SCOPE_SELF_CALL`. */
+  smartAccountAddress: string
+  /** Optional per-policy oracle overrides. Must TIGHTEN vs ORACLE_DEFAULTS
+   *  (i.e. <= each default). A widening value throws ORACLE_PARAMS_OUT_OF_RANGE
+   *  at compile time. */
+  oracleParams?: { maxStalenessSeconds?: number; maxDeviationBps?: number }
+}
+
+const CAPABILITIES: CustodyCapabilities = {
+  supportsSpendWindow: true,
+  supportsThreshold: false, // thresholds are the OZ adapter's job
+  supportsTimeExpiry: true, // via valid_until ledger expiry
+  supportsOraclePrice: true,
+  supportsInvocationCount: true,
+  supportsGeneralPredicate: true,
+}
+
+/** Parse confidence for a deterministic (non-decoded) input: full, with an
+ *  empty unknown/opaque breakdown. A mandate needs no decoding, so the gate is
+ *  not applicable and confidence is 1. */
+const FULL_PARSE_CONFIDENCE: ParseConfidence = {
+  overall: 1,
+  knownContracts: [],
+  unknownContracts: [],
+  opaqueScVals: [],
+  thresholdUsed: 1,
+}
+
+export function createInterpreterAdapter(config: InterpreterAdapterConfig): CustodyAdapter {
+  return {
+    name: 'interpreter',
+    mode: 'enforce',
+    capabilities: () => ({ ...CAPABILITIES }),
+    compile: (ir) => compile(ir, config),
+    simulate: () => simulateStub(),
+    export: (ir) => canonicalStringify(ir),
+  }
+}
+
+/** Lower a single IR rule to the canonical pre-encoding `PredicateNode`. The
+ *  orchestrator uses this to wire the self-verify + minimise pipeline: after
+ *  `compile(ir)` succeeds (`covered === true`, `proposed` set), the
+ *  orchestrator re-derives the PredicateNode via this helper to drive
+ *  `minimize` and `runHarness` on the SAME shape the encoder saw. Pure and
+ *  deterministic: same `rule + config` -> byte-identical PredicateNode. The
+ *  `uncovered` list the adapter surfaces during compile is NOT re-derived
+ *  here; callers that need it should use the result of `compile(ir)`. */
+export function lowerRuleToPredicate(
+  rule: IRPolicyRule,
+  config: InterpreterAdapterConfig
+): PredicateNode {
+  return lowerRule(rule, config).predicate
+}
+
+function compile(ir: PolicyIR, config: InterpreterAdapterConfig): CompileResult {
+  // Tighten-only oracle-params gate (config-time). Widening -> throw at compile
+  // time before any lowering happens, so a misuse fails closed loudly.
+  assertOracleParamsTighten(config.oracleParams)
+
+  const firstRule = ir.rules[0]
+  if (!firstRule) {
+    return { covered: false, uncovered: ['empty PolicyIR (no rules to compile)'] }
+  }
+  if (ir.rules.length > 1) {
+    return {
+      covered: false,
+      uncovered: [
+        `multi-rule PolicyIR: ${ir.rules.length - 1} rule(s) beyond the first are not compiled (the interpreter adapter handles one rule per document in this slice)`,
+      ],
+    }
+  }
+
+  const lowered = lowerRule(firstRule, config)
+  if (lowered.uncovered.length > 0) {
+    return { covered: false, uncovered: lowered.uncovered }
+  }
+
+  const { encodedPredicate, predicateHash } = encodePredicate(lowered.predicate)
+  const policyDocument: PolicyDocument = {
+    grammarVersion: 1,
+    installNonce: config.installNonce,
+    encodedPredicate,
+    predicateHash,
+    ...(config.oracleParams ? { oracleParams: config.oracleParams } : {}),
+  }
+  const policyRef: PolicyRef = {
+    kind: 'interpreter',
+    interpreterAddress: PLACEHOLDER_INTERPRETER_ADDRESS,
+    predicateBlobBase64: encodedPredicate,
+  }
+  const proposed: ProposedPolicy = {
+    contextRule: lowered.contextRule,
+    policyDocuments: [policyDocument],
+    policyRefs: [policyRef],
+    parseConfidence: { ...FULL_PARSE_CONFIDENCE },
+    warnings: [],
+    ambiguities: [],
+  }
+  return { covered: true, uncovered: [], proposed }
+}
+
+interface LoweredRule {
+  predicate: PredicateNode
+  contextRule: ContextRuleDraft
+  uncovered: string[]
+}
+
+function lowerRule(rule: IRPolicyRule, config: InterpreterAdapterConfig): LoweredRule {
+  const uncovered: string[] = []
+
+  // scope -> context rule + sibling predicates. contract/method each become
+  // their own `eq` leaf and are merged into the top-level and alongside the
+  // constraints. This keeps the top-level shape `and` (mandatory per the oracle
+  // position rule and the canonical hash stability for `and`).
+  const scopeContract: string | undefined = rule.scope.contract
+  const scopeMethod: string | undefined = rule.scope.method
+  if (rule.scope.chainId !== undefined) {
+    uncovered.push(
+      `chainId \`${rule.scope.chainId}\` not bindable by the interpreter adapter (network is per-context, not per-rule)`
+    )
+  }
+
+  if (rule.roles.length > 0) {
+    uncovered.push(
+      `roles [${rule.roles.join(', ')}] dropped (role-to-signer mapping is a later phase; interpreter policies reference addresses, not role names)`
+    )
+  }
+
+  if (rule.guard) {
+    uncovered.push(
+      `guard: ${describeCondition(rule.guard)} (interpreter adapter currently treats guards as uncovered)`
+    )
+  }
+
+  // expiry -> context rule validUntilLedger only. Unix-timestamp expiry is
+  // honoured by the interpreter (the `valid_until` selector), but we surface
+  // it here as Path-B because the IR contract already says "OZ context rules
+  // expire by ledger sequence" and we keep one expiry model for both adapters.
+  let validUntilLedger: number | null = null
+  if (rule.expiry) {
+    if (rule.expiry.validUntilLedger !== undefined) {
+      validUntilLedger = rule.expiry.validUntilLedger
+    } else if (rule.expiry.validUntilUnixSeconds !== undefined) {
+      uncovered.push(
+        'time expiry given as a unix timestamp (interpreter adapter currently lowers expiry only via the OZ context-rule validUntilLedger; supply expiry.validUntilLedger)'
+      )
+    }
+  }
+
+  // approval is the OZ adapter's job (it lowers to simple_threshold /
+  // weighted_threshold primitives). Surface it here so a caller that drops it
+  // through to the interpreter adapter sees an explicit uncovered entry
+  // instead of a silently-dropped M-of-N gate.
+  if (rule.approval) {
+    uncovered.push(
+      `approval threshold ${rule.approval.threshold} not emitted by the interpreter adapter (thresholds lower to OZ built-in primitives in the OZ adapter)`
+    )
+  }
+
+  // Pre-scan constraints: anything the interpreter adapter cannot express is
+  // named in `uncovered` and skipped from the predicate lowering. We surface
+  // these BEFORE lowering so the predicate is built from only the
+  // expressible subset.
+  const expressibleConstraints: IRCondition[] = []
+  for (const c of rule.constraints) {
+    const unsupp = unsupportedConstruct(c)
+    if (unsupp !== null) {
+      uncovered.push(unsupp)
+    } else {
+      expressibleConstraints.push(c)
+    }
+  }
+
+  // Build the top-level `and` of scope + expressible constraints. The
+  // top-level MUST be `and` so oracle leaves sit directly under it - the
+  // position rule is enforced inside `lowerCondition`.
+  const topChildren: PredicateNode[] = []
+  if (scopeContract !== undefined) {
+    topChildren.push({
+      op: 'eq',
+      left: { kind: 'call_contract' },
+      right: { kind: 'literal_address', value: scopeContract },
+    })
+  }
+  if (scopeMethod !== undefined) {
+    topChildren.push({
+      op: 'eq',
+      left: { kind: 'call_fn' },
+      right: { kind: 'literal_symbol', value: scopeMethod },
+    })
+  }
+  for (const c of expressibleConstraints) {
+    topChildren.push(lowerCondition(c, config))
+  }
+
+  const predicate: PredicateNode =
+    topChildren.length === 1 && topChildren[0] !== undefined
+      ? topChildren[0]
+      : { op: 'and', children: topChildren }
+
+  const contextRule: ContextRuleDraft = {
+    contextRuleType: { kind: 'default' },
+    name: 'interpreter',
+    validUntilLedger,
+    signers: [],
+    policies: [],
+  }
+
+  return { predicate, contextRule, uncovered }
+}
+
+/** Detect IR constructs the interpreter adapter cannot express; return a
+ *  human-readable descriptor (or null if the construct IS expressible). Used
+ *  by `lowerRule` to populate `uncovered` before lowering. */
+function unsupportedConstruct(cond: IRCondition): string | null {
+  switch (cond.op) {
+    case 'in':
+      return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+        ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
+        : null
+    case 'eq_seq':
+      return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+        ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
+        : null
+    case 'compare': {
+      const s = cond.compare.selector
+      if (s.kind === 'calldata') return 'EVM calldata comparison (predicate DSL)'
+      if (s.kind === 'value') return 'tx.value comparison (predicate DSL)'
+      return null
+    }
+    case 'and':
+    case 'or':
+    case 'not':
+      return null
+  }
+}
+
+/** Lower one IR condition to a PredicateNode. Enforces the oracle position
+ *  rule (oracle_price leaves must sit directly under the top-level `and`) and
+ *  the self-call rule (`in` allowlist / `compare eq` vs the smart account
+ *  address -> SCOPE_SELF_CALL). */
+function lowerCondition(cond: IRCondition, config: InterpreterAdapterConfig): PredicateNode {
+  switch (cond.op) {
+    case 'and':
+      return { op: 'and', children: cond.children.map((c) => lowerCondition(c, config)) }
+    case 'or':
+      // `or` at this depth: oracle_price anywhere inside is invalid (would
+      // not be a direct child of the top-level `and`).
+      assertNoOracleDescendants(cond)
+      return { op: 'or', children: cond.children.map((c) => lowerCondition(c, config)) }
+    case 'not':
+      // `not` at this depth: oracle_price anywhere inside is invalid.
+      assertNoOracleDescendants(cond)
+      return { op: 'not', child: lowerCondition(cond.child, config) }
+    case 'in': {
+      assertNoOracleDescendants(cond)
+      for (const v of cond.values) {
+        assertNotSelfCallAddress(v, config)
+      }
+      // `in` is PURE set membership; the encoder sorts the haystack. An exact
+      // ordered sequence (e.g. swap hop path) is expressed as `eq_seq` and
+      // lowers to `eq(selector, literal_vec)` instead - never to `in` with an
+      // `ordered` flag.
+      return {
+        op: 'in',
+        needle: lowerSelector(cond.selector),
+        haystack: cond.values.map((v) => literalFromScalar(v, selectorScalarType(cond.selector))),
+      }
+    }
+    case 'eq_seq': {
+      assertNoOracleDescendants(cond)
+      for (const v of cond.values) {
+        assertNotSelfCallAddress(v, config)
+      }
+      // Exact ordered sequence equality: the right-hand side is a literal_vec
+      // whose element order is preserved verbatim by the encoder. `eq` does
+      // deep equality at evaluate time - this is the ONLY way to express an
+      // exact ordered sequence in the predicate grammar (the path of a swap).
+      return {
+        op: 'eq',
+        left: lowerSelector(cond.selector),
+        right: {
+          kind: 'literal_vec',
+          elements: cond.values.map((v) => literalFromScalar(v, selectorScalarType(cond.selector))),
+        },
+      }
+    }
+    case 'compare': {
+      // Self-call on an address eq.
+      if (
+        cond.compare.operator === 'eq' &&
+        cond.compare.selector.kind === 'arg' &&
+        cond.compare.selector.scalarType === 'address'
+      ) {
+        assertNotSelfCallAddress(cond.compare.value, config)
+      }
+      return {
+        op: cond.compare.operator,
+        left: lowerSelector(cond.compare.selector),
+        right: literalFromIRCompare(cond.compare),
+      }
+    }
+  }
+}
+
+/** Lower an IR selector to the matching PredicateLeaf. */
+function lowerSelector(s: IRSelector): PredicateLeaf {
+  switch (s.kind) {
+    case 'arg':
+      return { kind: 'call_arg', index: s.argIndex }
+    case 'amount':
+      return { kind: 'amount', token: s.token }
+    case 'window_spent':
+      return { kind: 'window_spent', token: s.token, windowSeconds: s.windowSeconds }
+    case 'invocation_count':
+      return { kind: 'invocation_count_in_window', windowSecs: s.windowSeconds }
+    case 'now':
+      return { kind: 'now' }
+    case 'valid_until':
+      return { kind: 'valid_until' }
+    case 'oracle_price':
+      return { kind: 'oracle_price', asset: s.asset }
+    case 'calldata':
+    case 'value':
+      // Unreachable: the caller flagged these as Path-B before reaching here.
+      throw toolError(
+        'SYNTHESIS_ERROR',
+        `selector kind \`${s.kind}\` is not lowerable to a predicate leaf`
+      )
+  }
+}
+
+/** Build a literal leaf from the right-hand side of an IRCompare, mapping the
+ *  selector kind to the matching `literal_*` kind. The IR compare value is a
+ *  raw string (i128-safe); the selector kind fixes the canonical wire type:
+ *    - arg       -> IR scalarType (set by the recorder/parser)
+ *    - amount    -> i128 (canonical Stellar token amount encoding)
+ *    - window_spent -> i128 (canonical amount encoding)
+ *    - oracle_price  -> i128 (canonical price encoding)
+ *    - invocation_count -> u32 (counts are small non-negative integers)
+ *    - now / valid_until -> u64 (unix timestamps in seconds) */
+function literalFromIRCompare(c: IRCompare): PredicateLeaf {
+  const scalarType: IRScalarType =
+    c.selector.kind === 'arg' ? c.selector.scalarType : literalScalarForSelector(c.selector.kind)
+  return literalFromScalar(c.value, scalarType)
+}
+
+function literalScalarForSelector(kind: IRSelector['kind']): IRScalarType {
+  switch (kind) {
+    case 'amount':
+    case 'window_spent':
+    case 'oracle_price':
+      return 'i128'
+    case 'invocation_count':
+      return 'u32'
+    case 'now':
+    case 'valid_until':
+      return 'u64'
+    case 'arg':
+    case 'calldata':
+    case 'value':
+      // arg -> caller handles scalarType; calldata/value -> unreachable (Path-B).
+      return 'i128'
+  }
+}
+
+/** Build a literal leaf from a raw string value + an IRScalarType hint. */
+function literalFromScalar(value: string, scalarType: IRScalarType): PredicateLeaf {
+  switch (scalarType) {
+    case 'address':
+      return { kind: 'literal_address', value }
+    case 'i128':
+    case 'u128':
+      return { kind: 'literal_i128', value }
+    case 'u32':
+      return { kind: 'literal_u32', value: Number.parseInt(value, 10) }
+    case 'u64':
+    case 'i64':
+      return { kind: 'literal_u64', value }
+    case 'symbol':
+      return { kind: 'literal_symbol', value }
+    case 'bytes':
+      return { kind: 'literal_bytes', value }
+    case 'bool':
+      throw toolError(
+        'MALFORMED_PREDICATE',
+        `boolean literal not supported in v1 predicate grammar`
+      )
+  }
+}
+
+/** Scalar type of an IRSelector for the purpose of building literal leaves
+ *  (the right-hand side of `eq` / elements of an `in` haystack / elements of
+ *  a `literal_vec`). Mirrors `literalScalarForSelector` for OZ extensions and
+ *  uses the selector's own `scalarType` for `arg` selectors. */
+function selectorScalarType(selector: IRSelector): IRScalarType {
+  if (selector.kind === 'arg') return selector.scalarType
+  return literalScalarForSelector(selector.kind)
+}
+
+/** Walk a condition tree and throw if any oracle_price leaf is found anywhere
+ *  inside. Used by `lowerCondition` for `not`, `or`, and `in` - the three
+ *  positions where oracle leaves would not be direct children of the
+ *  top-level `and`. */
+function assertNoOracleDescendants(node: IRCondition): void {
+  if (containsOracle(node)) {
+    throw toolError(
+      'ORACLE_LEAF_INVALID_POSITION',
+      'oracle_price leaves must sit directly under the top-level `and`'
+    )
+  }
+}
+
+function containsOracle(node: IRCondition): boolean {
+  switch (node.op) {
+    case 'compare':
+      return node.compare.selector.kind === 'oracle_price'
+    case 'in':
+      return node.selector.kind === 'oracle_price'
+    case 'eq_seq':
+      return node.selector.kind === 'oracle_price'
+    case 'not':
+      return containsOracle(node.child)
+    case 'and':
+    case 'or':
+      return node.children.some(containsOracle)
+  }
+}
+
+/** Reject a value that targets the smart account's own address (a self-call
+ *  is a structural privilege-escalation hole the interpreter forbids). */
+function assertNotSelfCallAddress(value: string, config: InterpreterAdapterConfig): void {
+  if (value === config.smartAccountAddress) {
+    throw toolError(
+      'SCOPE_SELF_CALL',
+      `value \`${value}\` is the smart account's own address (self-call in an allowlist / compare is rejected)`
+    )
+  }
+}
+
+/** Tighten-only oracle-params gate. Any widening value (above the wasm-level
+ *  defaults) throws ORACLE_PARAMS_OUT_OF_RANGE at compile time. */
+function assertOracleParamsTighten(params: InterpreterAdapterConfig['oracleParams']): void {
+  if (!params) return
+  if (
+    params.maxStalenessSeconds !== undefined &&
+    params.maxStalenessSeconds > ORACLE_DEFAULTS.maxStalenessSeconds
+  ) {
+    throw toolError(
+      'ORACLE_PARAMS_OUT_OF_RANGE',
+      `maxStalenessSeconds ${params.maxStalenessSeconds} exceeds default ${ORACLE_DEFAULTS.maxStalenessSeconds}`
+    )
+  }
+  if (
+    params.maxDeviationBps !== undefined &&
+    params.maxDeviationBps > ORACLE_DEFAULTS.maxDeviationBps
+  ) {
+    throw toolError(
+      'ORACLE_PARAMS_OUT_OF_RANGE',
+      `maxDeviationBps ${params.maxDeviationBps} exceeds default ${ORACLE_DEFAULTS.maxDeviationBps}`
+    )
+  }
+}
+
+/** Human-readable descriptor for a construct the interpreter adapter cannot
+ *  express. Mirrors the OZ adapter's `describeCondition` for parity. */
+function describeCondition(cond: IRCondition): string {
+  switch (cond.op) {
+    case 'in':
+      return `value allowlist on ${describeSelector(cond.selector)} (predicate DSL)`
+    case 'eq_seq':
+      return `exact ordered sequence on ${describeSelector(cond.selector)} (predicate DSL)`
+    case 'not':
+      return 'negated condition (predicate DSL)'
+    case 'and':
+    case 'or':
+      return `nested ${cond.op} condition (predicate DSL)`
+    case 'compare': {
+      const s = cond.compare.selector
+      switch (s.kind) {
+        case 'oracle_price':
+          return `oracle price condition on ${s.asset}`
+        case 'invocation_count':
+          return `invocation-count window (${s.windowSeconds}s) condition`
+        case 'window_spent':
+          return `spend-window comparison with operator '${cond.compare.operator}'`
+        case 'amount':
+          return `per-call amount comparison on ${s.token}`
+        case 'arg':
+          return `argument comparison on arg ${s.argIndex}`
+        case 'calldata':
+          return 'EVM calldata comparison'
+        case 'value':
+          return 'tx.value comparison'
+        case 'now':
+        case 'valid_until':
+          return 'time comparison'
+      }
+    }
+  }
+}
+
+function describeSelector(s: IRSelector): string {
+  switch (s.kind) {
+    case 'arg':
+      return `arg ${s.argIndex}`
+    case 'amount':
+      return `amount(${s.token})`
+    case 'window_spent':
+      return `window_spent(${s.token})`
+    case 'oracle_price':
+      return `oracle_price(${s.asset})`
+    case 'invocation_count':
+      return `invocation_count(${s.windowSeconds}s)`
+    case 'calldata':
+      return `calldata[${s.offset}:${s.offset + s.length}]`
+    default:
+      return s.kind
+  }
+}
+
+function simulateStub(): SimulationResult {
+  return {
+    backend: 'ts-model',
+    permitted: null,
+    evaluations: [],
+    notes: ['stub: real permit/deny semantics wiring is a later phase'],
+  }
+}
+
+/** 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
+}
+
+/** Build a synthetic Error carrying the ToolError code/severity/retryable
+ *  fields the existing ToolError shape uses (the encoder pattern). Callers
+ *  inspect `e.code` in catch blocks. */
+function toolError(code: ToolError['code'], message: string): Error {
+  const err = new Error(message) as Error & {
+    code: ToolError['code']
+    severity: ToolError['severity']
+    retryable: boolean
+  }
+  err.code = code
+  err.severity = 'error'
+  err.retryable = false
+  return err
+}

package/src/adapters/interpreter/index.ts

@@ -0,0 +1,8 @@
+// src/adapters/interpreter/index.ts - re-export the interpreter-policy CustodyAdapter.
+
+export {
+  createInterpreterAdapter,
+  type InterpreterAdapterConfig,
+  ORACLE_DEFAULTS,
+  PLACEHOLDER_INTERPRETER_ADDRESS,
+} from './adapter.ts'

package/src/adapters/oz/adapter.ts

@@ -287,6 +287,8 @@ function describeCondition(cond: IRCondition): string {
   switch (cond.op) {
     case 'in':
       return `value allowlist on ${describeSelector(cond.selector)} (arg allowlist)`
+    case 'eq_seq':
+      return `exact ordered sequence on ${describeSelector(cond.selector)} (OZ built-ins cannot express an exact vector)`
     case 'not':
       return 'negated condition (predicate DSL)'
     case 'and':