@crediolabs/policy-synth 0.1.8 → 0.1.10

package/src/review-card/builder.ts

@@ -171,6 +171,32 @@ function renderComparison(
     return `Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`
   }
 
+  // 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(', ')}]`
+    }
+  }
+
   // 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`
@@ -222,6 +248,8 @@ function renderVecElement(leaf: PredicateLeaf): string {
     case 'call_contract':
     case 'call_fn':
     case 'call_arg':
+    case 'call_arg_len':
+    case 'call_arg_field':
     case 'amount':
     case 'window_spent':
     case 'now':

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

@@ -80,6 +80,44 @@ function pushComparison(
     out.push(`Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`)
     return
   }
+  if (left.kind === 'call_arg_len' && op === 'eq' && right.kind === 'literal_u32') {
+    out.push(`Length of arg[${left.index}] is ${right.value}`)
+    return
+  }
+  // call_arg_field: must mirror the builder's templates byte-for-byte so
+  // the cross-check can assert a faithful summary.
+  if (left.kind === 'call_arg_field') {
+    const head = `arg[${left.index}] element[${left.element}].${left.field}`
+    const sep = op === 'eq' ? '=' : comparisonOpText(op)
+    if (right.kind === 'literal_address') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_symbol') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_bytes') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_u64') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_i128') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_u32') {
+      out.push(`${head} ${sep} ${right.value}`)
+      return
+    }
+    if (right.kind === 'literal_vec') {
+      out.push(`${head} ${sep} [${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
@@ -119,6 +157,8 @@ function renderVecElement(leaf: PredicateLeaf): string {
     case 'call_contract':
     case 'call_fn':
     case 'call_arg':
+    case 'call_arg_len':
+    case 'call_arg_field':
     case 'amount':
     case 'window_spent':
     case 'now':

package/src/run/index.ts

@@ -21,6 +21,7 @@ import {
   type ErrorCode,
   type MandateSpec,
   type OzAdapterConfig,
+  type PredicateNode,
   type ProposedPolicy,
   placeholderOzConfig,
   type RecordedTransaction,
@@ -31,6 +32,7 @@ import {
   type ToolError,
   type ToolResponse,
 } from '../index.ts'
+import type { SimulationResult } from '../verify/envelope.ts'
 import {
   type RecordTransactionInput,
   RecordTransactionInputSchema,
@@ -112,7 +114,14 @@ export async function runRecordTransaction(
  *  `{ok:false, error}`, but a raw throw from the SDK (e.g. an unexpected
  *  XDR decode error in the adapter) would otherwise surface as
  *  "[object Object]" in the MCP transport. */
-export async function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>> {
+export async function runSynthesizePolicy(raw: unknown): Promise<
+  ToolResponse<ProposedPolicy> & {
+    explain?: {
+      predicateTree: PredicateNode | null
+      simulation: SimulationResult
+    }
+  }
+> {
   const parsed = SynthesizePolicyInputSchema.safeParse(raw)
   if (!parsed.success) {
     return {
@@ -128,7 +137,11 @@ export async function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<Pr
       // Zod's optional fields widen to `T | undefined`, which the core's
       // exact-optional MandateSpec rejects; the schema already validated the
       // shape, so assert it (same pattern as the recordedTx cast below).
-      return await synthesizeFromMandate(input.mandate as MandateSpec, ozConfig)
+      return await synthesizeFromMandate(
+        input.mandate as MandateSpec,
+        ozConfig,
+        input.explain === true ? { explain: true } : {}
+      )
     }
     // recording source
     const recorded: RecordedTransaction = input.recordedTx as RecordedTransaction
@@ -141,6 +154,7 @@ export async function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<Pr
           ? { confidenceOverride: input.confidenceOverride }
           : {}),
         ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
+        ...(input.explain === true ? { explain: true } : {}),
       } as SynthesizeFromRecordingOptions,
       ozConfig
     )

package/src/run/schemas.ts

@@ -197,6 +197,11 @@ export const SynthesizePolicyMandateInputSchema = z.object({
   source: z.literal('mandate'),
   mandate: MandateSpecSchema,
   ozConfig: OzAdapterConfigSchema.optional(),
+  // --explain opt-in. When true, the orchestrator attaches the
+  // in-memory predicate tree (null for the mandate path) + a minimal
+  // honest SimulationResult to the success envelope. Absent or false
+  // -> the success envelope is unchanged (byte-identical to today).
+  explain: z.boolean().optional(),
 })
 
 /** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
@@ -224,6 +229,15 @@ export const SynthesizePolicyRecordingInputSchema = z.object({
   confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
   interpreter: InterpreterOptionsSchema.optional(),
   ozConfig: OzAdapterConfigSchema.optional(),
+  // --explain opt-in. When true, the orchestrator attaches the
+  // in-memory PredicateNode + the corresponding SimulationResult
+  // (real one from the self-verify pipeline when the interpreter is
+  // engaged, minimal honest value otherwise) to the success envelope.
+  // Absent or false -> the success envelope is unchanged (byte-identical
+  // to today). The flag is ADDITIVE: the existing ProposedPolicy fields
+  // (encodedPredicate, predicateHash, etc.) are never altered by enabling
+  // explain.
+  explain: z.boolean().optional(),
 })
 
 export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [

package/src/synth/compose-from-recording.ts

@@ -381,6 +381,93 @@ function appendProtocolSpecificConstraints(
     }
   }
 
+  // Blend `submit` ONLY (not `claim`, whose vec arg is a vec<u32> of
+  // reserve_token_ids - no map fields to bind). The `requests` vec
+  // (call_arg[3]) is a vec<Request{ address, amount, request_type }>. Each
+  // Request is the per-reserve action selector - 0 Supply, 1 Withdraw,
+  // 2 SupplyCollateral, 3 WithdrawCollateral, 4 Borrow, 5 Repay, 6-9
+  // liquidation/auction fills. Pinning only one element is unsafe: a caller
+  // can append a second element with a different action (WithdrawCollateral
+  // -> Borrow on a different asset, any amount, then auction fills). Length
+  // + per-element pinning is total; a quantifier over elements is not. If we
+  // cannot emit BOTH, we surface AMBIGUITY rather than emit a partial bind.
+  if (protocol.protocol === 'blend' && protocol.fn === 'submit' && interpreterEnabled) {
+    const requestsArg = topLevel.args[3]
+    if (requestsArg && requestsArg.type === 'vec') {
+      const elements = requestsArg.value
+      interpreterConstraints.push({
+        op: 'compare',
+        compare: {
+          selector: { kind: 'arg_len', argIndex: 3 },
+          operator: 'eq',
+          value: String(elements.length),
+        },
+      })
+      for (let i = 0; i < elements.length; i++) {
+        const element = elements[i]
+        if (!element || element.type !== 'map') continue
+        const fields = element.value
+        const fieldValue = (
+          name: string,
+          scalarType: 'address' | 'i128' | 'u32'
+        ): string | null => {
+          const entry = fields.find((e) => e.key === name)
+          if (!entry) return null
+          if (entry.val.type === 'address' && scalarType === 'address') return entry.val.value
+          if (entry.val.type === 'i128' && scalarType === 'i128') return entry.val.value
+          if (entry.val.type === 'u32' && scalarType === 'u32') return entry.val.value
+          return null
+        }
+        const address = fieldValue('address', 'address')
+        const amount = fieldValue('amount', 'i128')
+        const requestType = fieldValue('request_type', 'u32')
+        if (address === null || amount === null || requestType === null) continue
+        interpreterConstraints.push({
+          op: 'compare',
+          compare: {
+            selector: {
+              kind: 'arg_field',
+              argIndex: 3,
+              element: i,
+              field: 'request_type',
+              scalarType: 'u32',
+            },
+            operator: 'eq',
+            value: requestType,
+          },
+        })
+        interpreterConstraints.push({
+          op: 'compare',
+          compare: {
+            selector: {
+              kind: 'arg_field',
+              argIndex: 3,
+              element: i,
+              field: 'address',
+              scalarType: 'address',
+            },
+            operator: 'eq',
+            value: address,
+          },
+        })
+        interpreterConstraints.push({
+          op: 'compare',
+          compare: {
+            selector: {
+              kind: 'arg_field',
+              argIndex: 3,
+              element: i,
+              field: 'amount',
+              scalarType: 'i128',
+            },
+            operator: 'lte',
+            value: amount,
+          },
+        })
+      }
+    }
+  }
+
   // SoroSwap: the recorded hop path -> eq_seq on the path arg (call_arg[2]).
   // The interpreter adapter is the ONLY way to express an exact ordered
   // sequence (OZ built-ins cannot). Element order is preserved verbatim.

package/src/synth/deny-cases.ts

@@ -51,6 +51,15 @@ const ADJACENT_ASSETS = [
 const OVERPERMISSIVE_DIMENSIONS = ['argument_reorder'] as const
 
 // The 15 dimensions the synth pipeline uses for self-verify and minimise.
+// Phase 1 grammar extension: `vec_append` and `map_field_flip` are listed below
+// alongside the existing dimensions so the per-element binds emitted for
+// Blend `submit` (call_arg_len + 3 call_arg_field per element) survive
+// minimise. Without these, no deny case exercises the new leaves and the
+// minimise pass drops them as "redundant" - reopening the element-append
+// hole they were added to close. Both dimensions are no-ops for any fixture
+// whose predicate has no `call_arg_len` / `call_arg_field` leaves (the
+// generator short-circuits on leaf-kind), so they cannot make production
+// synthesis refuse for fixtures that do not exercise the new grammar.
 const ORIGINAL_DIMENSIONS: string[] = [
   'amount',
   'asset',
@@ -67,6 +76,8 @@ const ORIGINAL_DIMENSIONS: string[] = [
   'oracle_deviation_exceeded',
   'oracle_paused',
   'soroswap_allowed_path',
+  'vec_append',
+  'map_field_flip',
 ]
 
 export { ORIGINAL_DIMENSIONS, OVERPERMISSIVE_DIMENSIONS }
@@ -263,7 +274,9 @@ export function generateCases(
     hasConstrainedArg &&
     permitCtx.args.length >= 2 &&
     permitCtx.args[0]?.type === 'address' &&
-    permitCtx.args[1]?.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.
@@ -274,6 +287,55 @@ export function generateCases(
     denies.push({ dimension: 'argument_reorder', ctx })
   }
 
+  // --- map_field_flip: flip a bound map field to a different valid value of
+  // the same type. Mirrors argument_reorder: 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 (different request_type,
+  // different amount, different address). The blend-submit case uses this
+  // to detect a missing request_type pin. ---
+  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 || arg.type !== 'vec') continue
+      const element = arg.value[sel.element]
+      if (!element || 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 })
+    }
+  }
+
+  // --- vec_append: append a new element to a bound vec. Mirrors map_field_flip:
+  // 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 || 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 })
+    }
+  }
+
   // Version mismatch, malformed predicates, master authorization, and nonce replay are install-time checks and are intentionally omitted from model-evaluated cases.
   return { permit: cloneContext(permitCtx), denies }
 }
@@ -528,3 +590,26 @@ function cloneDepthError(value: ScVal): never {
   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 (a type/arity change is rejected by host dispatch
+ *  before Policy::enforce, so it is not the predicate's job). 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 'u64':
+    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/synth/evaluate.ts

@@ -216,6 +216,33 @@ function evalCompare(
     return evalArgEq(op, actual, right, ctx)
   }
 
+  // --- step 4c: call_arg_len: the length of a vec-typed argument as a u32.
+  // Fails closed on a non-vec arg, an absent arg, or a non-u32 literal.
+  if (left.kind === 'call_arg_len') {
+    const actual = ctx.args[left.index]
+    if (!actual || 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' }
+  }
+
+  // --- step 4d: call_arg_field: the value of a field in the map at element i
+  // of the vec at argument index. Fails closed on a non-vec arg, an
+  // out-of-range element, a missing field, a non-map element, or a type
+  // mismatch between the field ScVal and the literal leaf.
+  if (left.kind === 'call_arg_field') {
+    const actual = ctx.args[left.index]
+    if (!actual || actual.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
+    const element = actual.value[left.element]
+    if (!element || 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, ctx)
+    return evalArgOrderedCompare(op, entry.val, right)
+  }
+
   // --- step 6: AMOUNT_BOUND ---
   if (left.kind === 'amount' && op !== 'eq') {
     return evalAmountCompare(op, left.token, right, ctx)
@@ -383,6 +410,20 @@ function resolveLeaf(leaf: PredicateLeaf, ctx: EvalContext): ScVal | undefined {
       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 || actual.type !== 'vec') return undefined
+      const element = actual.value[leaf.element]
+      if (!element || 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 'amount':
     case 'window_spent':
     case 'oracle_price':

package/src/synth/synthesize-from-mandate.ts

@@ -13,14 +13,27 @@ import { createOzAdapter } from '../adapters/oz/adapter.ts'
 import type { ToolResponse } from '../errors.ts'
 import { mandateToPolicyIR } from '../mandate/to-ir.ts'
 import type { MandateSpec } from '../mandate/types.ts'
-import type { ProposedPolicy } from '../types.ts'
+import type { PredicateNode, ProposedPolicy } from '../types.ts'
+import type { SimulationResult } from '../verify/envelope.ts'
 
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: '
 
 export function synthesizeFromMandate(
   spec: MandateSpec,
-  ozConfig: OzAdapterConfig
-): ToolResponse<ProposedPolicy> {
+  ozConfig: OzAdapterConfig,
+  /** --explain opt-in. When true, the success envelope carries the
+   *  in-memory predicate tree (always null for the mandate path - the
+   *  declarative MandateSpec lowers to OZ built-ins, not to an
+   *  interpreter predicate) + a minimal honest SimulationResult. The
+   *  flag is ADDITIVE: the existing ProposedPolicy fields are never
+   *  altered. */
+  opts?: { explain?: true }
+): ToolResponse<ProposedPolicy> & {
+  explain?: {
+    predicateTree: PredicateNode | null
+    simulation: SimulationResult
+  }
+} {
   const ir = mandateToPolicyIR(spec)
   const adapter = createOzAdapter(ozConfig)
   const result = adapter.compile(ir)
@@ -42,5 +55,28 @@ export function synthesizeFromMandate(
     ...result.proposed,
     warnings: result.uncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
   }
-  return { ok: true, data: proposed }
+  // Same --explain envelope pattern as the recording path. The mandate path
+  // never produces an interpreter predicate, so predicateTree is null and
+  // the simulation is a minimal honest deny (no self-verify was performed).
+  const envelope: ToolResponse<ProposedPolicy> & {
+    explain?: {
+      predicateTree: PredicateNode | null
+      simulation: SimulationResult
+    }
+  } = { ok: true, data: proposed }
+  if (opts?.explain) {
+    envelope.explain = {
+      predicateTree: null,
+      simulation: {
+        permit: {
+          tx: 'deny',
+          reason: 'No self-verification was performed (mandate path is OZ-only)',
+        },
+        evaluatedCases: [],
+        backend: 'ts-model',
+        simulatorVersion: 'not-run',
+      },
+    }
+  }
+  return envelope
 }

package/src/synth/synthesize-from-recording.ts

@@ -52,6 +52,7 @@ import {
   type RecordedTransaction,
   SOROBAN_LIMITS,
 } from '../types.ts'
+import type { SimulationResult } from '../verify/envelope.ts'
 import {
   type ComposeOptions,
   type ComposeUserResponses,
@@ -101,13 +102,36 @@ export interface SynthesizeFromRecordingOptions {
   userResponses?: ComposeUserResponses
   confidenceOverride?: { threshold: number }
   interpreter?: InterpreterAdapterOptions
+  /** --explain opt-in. When true, the orchestrator attaches the
+   *  in-memory `PredicateNode` + the corresponding `SimulationResult`
+   *  to the success envelope so the CLI can render a human-readable
+   *  review card. Absent or false -> the success envelope is unchanged
+   *  (byte-identical to today). The flag is ADDITIVE: the existing
+   *  ProposedPolicy fields (encodedPredicate, predicateHash, etc.) are
+   *  never altered by enabling explain. */
+  explain?: true
 }
 
 export function synthesizeFromRecording(
   tx: RecordedTransaction,
   opts: SynthesizeFromRecordingOptions,
   ozConfig: OzAdapterConfig
-): ToolResponse<ProposedPolicy> {
+): ToolResponse<ProposedPolicy> & {
+  /** Present iff `opts.explain === true` and the synthesis succeeded. The
+   *  `predicateTree` is the exact in-memory `PredicateNode` (canonical
+   *  JSON shape) that was encoded into `proposed.policyDocuments[*].encodedPredicate`
+   *  - reading the predicate tree from the policy document is therefore
+   *  unnecessary; the orchestrator carries it through. The `simulation`
+   *  is the verdict produced by the same self-verify pipeline that already
+   *  runs in the recording path (runHarness + evaluate), so the value is
+   *  REAL not synthetic. Absent when the synthesis did not engage the
+   *  interpreter (no interpreter opts supplied) - in that case the CLI
+   *  builds a minimal honest SimulationResult downstream. */
+  explain?: {
+    predicateTree: PredicateNode | null
+    simulation: SimulationResult
+  }
+} {
   // Item 3: ToolError try/catch envelope. Any ToolError-shaped throw (object
   // with a string `.code`) inside the body is converted to a structured
   // `{ok:false, error}`; anything else is rethrown so genuine bugs crash
@@ -159,7 +183,12 @@ function synthesizeFromRecordingInner(
   tx: RecordedTransaction,
   opts: SynthesizeFromRecordingOptions,
   ozConfig: OzAdapterConfig
-): ToolResponse<ProposedPolicy> {
+): ToolResponse<ProposedPolicy> & {
+  explain?: {
+    predicateTree: PredicateNode | null
+    simulation: SimulationResult
+  }
+} {
   // 0. validate inputs (fail closed - never synthesize from garbage).
   const invalid = validateOptions(opts)
   if (invalid) return { ok: false, error: invalid }
@@ -272,6 +301,15 @@ function synthesizeFromRecordingInner(
   }
   const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts)
 
+  // --explain hook: capture the in-memory predicate tree + the real
+  // self-verify verdict so the CLI can render a faithful review card.
+  // The verdict below is built from the SAME runHarness + evaluate that
+  // already gates the synthesis (it is not a parallel simulation); the
+  // intermediate inputs (harnessCases, evalResult) are otherwise discarded
+  // after the gate, so the explain hook reuses them - no extra work.
+  let explain: PredicateNode | null = null
+  let explainSim: SimulationResult | null = null
+
   // 5. OZ compile (always runs).
   const ozAdapter = createOzAdapter(ozConfig)
   const compileRes = ozAdapter.compile(composed.ir)
@@ -449,7 +487,6 @@ function synthesizeFromRecordingInner(
         },
       }
     }
-
     const evalResult = evaluate(finalPredicate, permitCtx)
     if (!evalResult.permit) {
       return {
@@ -464,6 +501,37 @@ function synthesizeFromRecordingInner(
       }
     }
 
+    // --explain capture: the interpreter path already produced the real
+    // self-verify verdict (runHarness passed, evalResult.permit is true).
+    // Build the SimulationResult from those outputs so the CLI card
+    // quotes the SAME verdict that gated the synthesis. We re-evaluate
+    // each deny case to surface its concrete reason; the harness only
+    // records whether the got-matches-expected boundary held.
+    if (opts.explain) {
+      explain = finalPredicate
+      const evaluatedCases: SimulationResult['evaluatedCases'] = [
+        {
+          dimension: 'permit',
+          outcome: evalResult.permit ? 'permit' : 'deny',
+          reason: 'matches recorded call',
+        },
+      ]
+      for (const deny of harnessCases.denies) {
+        const r = evaluate(finalPredicate, deny.ctx)
+        evaluatedCases.push({
+          dimension: deny.dimension,
+          outcome: r.permit ? 'permit' : 'deny',
+          reason: r.permit ? 'no matching deny' : r.reason,
+        })
+      }
+      explainSim = {
+        permit: { tx: 'permit' },
+        evaluatedCases,
+        backend: 'ts-model',
+        simulatorVersion: 'ts-model-1.0.0',
+      }
+    }
+
     // 6c. Re-encode the (possibly minimised) PredicateNode and stamp the
     //     canonical bytes back onto the PolicyDocument + PolicyRef. The
     //     `encodePredicate` helper throws ToolError-shaped errors on cap
@@ -566,7 +634,38 @@ function synthesizeFromRecordingInner(
     ],
     ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
   }
-  return { ok: true, data: proposed }
+  // --explain success envelope. The interpreter path populated
+  // `explain` + `explainSim` from the real self-verify verdict above;
+  // the OZ-only path did not (no predicate tree exists). When opts.explain
+  // is set and the OZ-only path ran, construct the minimal honest
+  // SimulationResult: the verdict is NOT a passing simulation - the
+  // interpreter was never engaged, so permit is deny with a truthful
+  // reason and evaluatedCases is empty.
+  const envelope: ToolResponse<ProposedPolicy> & {
+    explain?: {
+      predicateTree: PredicateNode | null
+      simulation: SimulationResult
+    }
+  } = { ok: true, data: proposed }
+  if (opts.explain) {
+    if (explainSim) {
+      envelope.explain = { predicateTree: explain, simulation: explainSim }
+    } else {
+      envelope.explain = {
+        predicateTree: null,
+        simulation: {
+          permit: {
+            tx: 'deny',
+            reason: 'No self-verification was performed (interpreter adapter was not engaged)',
+          },
+          evaluatedCases: [],
+          backend: 'ts-model',
+          simulatorVersion: 'not-run',
+        },
+      }
+    }
+  }
+  return envelope
 }
 
 // Re-export the throwToolError helper for callers that need to surface a