@crediolabs/policy-synth 0.1.9 → 0.1.10

package/dist/review-card/builder.js

@@ -138,6 +138,36 @@ function renderComparison(node) {
     if (left.kind === 'call_arg' && node.op === 'eq' && right.kind === 'literal_vec') {
         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`;

package/dist/review-card/cross-check.js

@@ -67,6 +67,44 @@ function pushComparison(left, right, op, out) {
         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;

package/dist/run/index.d.ts

@@ -1,4 +1,5 @@
-import { type ErrorCode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
+import { type ErrorCode, type PredicateNode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
 import { type RecordTransactionInput, type SynthesizePolicyInput } from './schemas.ts';
 export type { RecordTransactionInput, SynthesizePolicyInput } from './schemas.ts';
 export { ComposeUserResponsesSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OzAdapterConfigSchema, RecordedTransactionSchema, RecordTransactionInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from './schemas.ts';
@@ -28,7 +29,12 @@ export declare function runRecordTransaction(raw: unknown): Promise<ToolResponse
  *  `{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 declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>>;
+export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy> & {
+    explain?: {
+        predicateTree: PredicateNode | null;
+        simulation: SimulationResult;
+    };
+}>;
 /** Build a canonical ToolError for a thrown exception caught by the tool
  *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
  *  default, so we extract a string-friendly message and tag the original

package/dist/run/index.js

@@ -89,7 +89,7 @@ export async function runSynthesizePolicy(raw) {
             // 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, ozConfig);
+            return await synthesizeFromMandate(input.mandate, ozConfig, input.explain === true ? { explain: true } : {});
         }
         // recording source
         const recorded = input.recordedTx;
@@ -100,6 +100,7 @@ export async function runSynthesizePolicy(raw) {
                 ? { confidenceOverride: input.confidenceOverride }
                 : {}),
             ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
+            ...(input.explain === true ? { explain: true } : {}),
         }, ozConfig);
     }
     catch (e) {

package/dist/run/schemas.d.ts

@@ -648,6 +648,7 @@ export declare const SynthesizePolicyMandateInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     }>>;
+    explain: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     source: "mandate";
     mandate: {
@@ -676,6 +677,7 @@ export declare const SynthesizePolicyMandateInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }, {
     source: "mandate";
     mandate: {
@@ -704,6 +706,7 @@ export declare const SynthesizePolicyMandateInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }>;
 /** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
  *  express (per-method scoping, invocation-count windows, oracle bounds, exact
@@ -1085,6 +1088,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     }>>;
+    explain: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     network: "mainnet" | "testnet";
     source: "recording";
@@ -1149,6 +1153,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }, {
     network: "mainnet" | "testnet";
     source: "recording";
@@ -1213,6 +1218,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }>;
 export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"source", [z.ZodObject<{
     source: z.ZodLiteral<"mandate">;
@@ -1334,6 +1340,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     }>>;
+    explain: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     source: "mandate";
     mandate: {
@@ -1362,6 +1369,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }, {
     source: "mandate";
     mandate: {
@@ -1390,6 +1398,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }>, z.ZodObject<{
     source: z.ZodLiteral<"recording">;
     recordedTx: z.ZodObject<{
@@ -1736,6 +1745,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     }>>;
+    explain: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     network: "mainnet" | "testnet";
     source: "recording";
@@ -1800,6 +1810,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }, {
     network: "mainnet" | "testnet";
     source: "recording";
@@ -1864,6 +1875,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }>]>;
 export type SynthesizePolicyInput = z.infer<typeof SynthesizePolicyInputSchema>;
 export declare const ToolErrorSchema: z.ZodObject<{

package/dist/run/schemas.js

@@ -175,6 +175,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
  *  express (per-method scoping, invocation-count windows, oracle bounds, exact
@@ -200,6 +205,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', [
     SynthesizePolicyMandateInputSchema,

package/dist/synth/synthesize-from-mandate.d.ts

@@ -1,5 +1,20 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
 import type { ToolResponse } from '../errors.ts';
 import type { MandateSpec } from '../mandate/types.ts';
-import type { ProposedPolicy } from '../types.ts';
-export declare function synthesizeFromMandate(spec: MandateSpec, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+import type { PredicateNode, ProposedPolicy } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
+export declare function synthesizeFromMandate(spec: MandateSpec, 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;
+    };
+};

package/dist/synth/synthesize-from-mandate.js

@@ -10,7 +10,14 @@
 import { createOzAdapter } from "../adapters/oz/adapter.js";
 import { mandateToPolicyIR } from "../mandate/to-ir.js";
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
-export function synthesizeFromMandate(spec, ozConfig) {
+export function synthesizeFromMandate(spec, ozConfig, 
+/** --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) {
     const ir = mandateToPolicyIR(spec);
     const adapter = createOzAdapter(ozConfig);
     const result = adapter.compile(ir);
@@ -30,5 +37,23 @@ export function synthesizeFromMandate(spec, ozConfig) {
         ...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 = { 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/dist/synth/synthesize-from-recording.d.ts

@@ -1,6 +1,7 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
 import type { ToolError, ToolResponse } from '../errors.ts';
 import { type Network, type PredicateNode, type ProposedPolicy, type RecordedTransaction } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
 import { type ComposeUserResponses } from './compose-from-recording.ts';
 /** Per-policy interpreter adapter config the caller opts into. Absent ->
  *  recording path runs in week-1 mode (OZ adapter only, warnings for the
@@ -41,8 +42,31 @@ export interface SynthesizeFromRecordingOptions {
         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 declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): 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;
+    };
+};
 /** ToolError-shaped error helper used by the body to surface a structured
  *  failure that the envelope converts to `{ok:false, error}`. */
 declare function throwToolError(code: ToolError['code'], message: string): never;

package/dist/synth/synthesize-from-recording.js

@@ -195,6 +195,14 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
     };
     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 = null;
+    let explainSim = null;
     // 5. OZ compile (always runs).
     const ozAdapter = createOzAdapter(ozConfig);
     const compileRes = ozAdapter.compile(composed.ir);
@@ -372,6 +380,36 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
                 },
             };
         }
+        // --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 = [
+                {
+                    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
@@ -469,7 +507,34 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ],
         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 = { 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
 // ToolError-shaped throw inside the body (e.g. tests).

package/dist-cjs/review-card/builder.js

@@ -141,6 +141,36 @@ function renderComparison(node) {
     if (left.kind === 'call_arg' && node.op === 'eq' && right.kind === 'literal_vec') {
         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`;

package/dist-cjs/review-card/cross-check.js

@@ -70,6 +70,44 @@ function pushComparison(left, right, op, out) {
         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;

package/dist-cjs/run/index.d.ts

@@ -1,4 +1,5 @@
-import { type ErrorCode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
+import { type ErrorCode, type PredicateNode, type ProposedPolicy, type RecordedTransaction, type ToolError, type ToolResponse } from '../index.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
 import { type RecordTransactionInput, type SynthesizePolicyInput } from './schemas.ts';
 export type { RecordTransactionInput, SynthesizePolicyInput } from './schemas.ts';
 export { ComposeUserResponsesSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OzAdapterConfigSchema, RecordedTransactionSchema, RecordTransactionInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from './schemas.ts';
@@ -28,7 +29,12 @@ export declare function runRecordTransaction(raw: unknown): Promise<ToolResponse
  *  `{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 declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>>;
+export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy> & {
+    explain?: {
+        predicateTree: PredicateNode | null;
+        simulation: SimulationResult;
+    };
+}>;
 /** Build a canonical ToolError for a thrown exception caught by the tool
  *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
  *  default, so we extract a string-friendly message and tag the original

package/dist-cjs/run/index.js

@@ -104,7 +104,7 @@ async function runSynthesizePolicy(raw) {
             // 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 (0, index_ts_1.synthesizeFromMandate)(input.mandate, ozConfig);
+            return await (0, index_ts_1.synthesizeFromMandate)(input.mandate, ozConfig, input.explain === true ? { explain: true } : {});
         }
         // recording source
         const recorded = input.recordedTx;
@@ -115,6 +115,7 @@ async function runSynthesizePolicy(raw) {
                 ? { confidenceOverride: input.confidenceOverride }
                 : {}),
             ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
+            ...(input.explain === true ? { explain: true } : {}),
         }, ozConfig);
     }
     catch (e) {

package/dist-cjs/run/schemas.d.ts

@@ -648,6 +648,7 @@ export declare const SynthesizePolicyMandateInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     }>>;
+    explain: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     source: "mandate";
     mandate: {
@@ -676,6 +677,7 @@ export declare const SynthesizePolicyMandateInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }, {
     source: "mandate";
     mandate: {
@@ -704,6 +706,7 @@ export declare const SynthesizePolicyMandateInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }>;
 /** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
  *  express (per-method scoping, invocation-count windows, oracle bounds, exact
@@ -1085,6 +1088,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     }>>;
+    explain: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     network: "mainnet" | "testnet";
     source: "recording";
@@ -1149,6 +1153,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }, {
     network: "mainnet" | "testnet";
     source: "recording";
@@ -1213,6 +1218,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }>;
 export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"source", [z.ZodObject<{
     source: z.ZodLiteral<"mandate">;
@@ -1334,6 +1340,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     }>>;
+    explain: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     source: "mandate";
     mandate: {
@@ -1362,6 +1369,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }, {
     source: "mandate";
     mandate: {
@@ -1390,6 +1398,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }>, z.ZodObject<{
     source: z.ZodLiteral<"recording">;
     recordedTx: z.ZodObject<{
@@ -1736,6 +1745,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     }>>;
+    explain: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     network: "mainnet" | "testnet";
     source: "recording";
@@ -1800,6 +1810,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }, {
     network: "mainnet" | "testnet";
     source: "recording";
@@ -1864,6 +1875,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
             weighted_threshold: string;
         };
     } | undefined;
+    explain?: boolean | undefined;
 }>]>;
 export type SynthesizePolicyInput = z.infer<typeof SynthesizePolicyInputSchema>;
 export declare const ToolErrorSchema: z.ZodObject<{

package/dist-cjs/run/schemas.js

@@ -178,6 +178,11 @@ exports.SynthesizePolicyMandateInputSchema = zod_1.z.object({
     source: zod_1.z.literal('mandate'),
     mandate: exports.MandateSpecSchema,
     ozConfig: exports.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: zod_1.z.boolean().optional(),
 });
 /** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
  *  express (per-method scoping, invocation-count windows, oracle bounds, exact
@@ -203,6 +208,15 @@ exports.SynthesizePolicyRecordingInputSchema = zod_1.z.object({
     confidenceOverride: zod_1.z.object({ threshold: zod_1.z.number().min(0).max(1) }).optional(),
     interpreter: exports.InterpreterOptionsSchema.optional(),
     ozConfig: exports.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: zod_1.z.boolean().optional(),
 });
 exports.SynthesizePolicyInputSchema = zod_1.z.discriminatedUnion('source', [
     exports.SynthesizePolicyMandateInputSchema,

package/dist-cjs/synth/synthesize-from-mandate.d.ts

@@ -1,5 +1,20 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
 import type { ToolResponse } from '../errors.ts';
 import type { MandateSpec } from '../mandate/types.ts';
-import type { ProposedPolicy } from '../types.ts';
-export declare function synthesizeFromMandate(spec: MandateSpec, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+import type { PredicateNode, ProposedPolicy } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
+export declare function synthesizeFromMandate(spec: MandateSpec, 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;
+    };
+};

package/dist-cjs/synth/synthesize-from-mandate.js

@@ -13,7 +13,14 @@ exports.synthesizeFromMandate = synthesizeFromMandate;
 const adapter_ts_1 = require("../adapters/oz/adapter.js");
 const to_ir_ts_1 = require("../mandate/to-ir.js");
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
-function synthesizeFromMandate(spec, ozConfig) {
+function synthesizeFromMandate(spec, ozConfig, 
+/** --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) {
     const ir = (0, to_ir_ts_1.mandateToPolicyIR)(spec);
     const adapter = (0, adapter_ts_1.createOzAdapter)(ozConfig);
     const result = adapter.compile(ir);
@@ -33,5 +40,23 @@ function synthesizeFromMandate(spec, ozConfig) {
         ...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 = { 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/dist-cjs/synth/synthesize-from-recording.d.ts

@@ -1,6 +1,7 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
 import type { ToolError, ToolResponse } from '../errors.ts';
 import { type Network, type PredicateNode, type ProposedPolicy, type RecordedTransaction } from '../types.ts';
+import type { SimulationResult } from '../verify/envelope.ts';
 import { type ComposeUserResponses } from './compose-from-recording.ts';
 /** Per-policy interpreter adapter config the caller opts into. Absent ->
  *  recording path runs in week-1 mode (OZ adapter only, warnings for the
@@ -41,8 +42,31 @@ export interface SynthesizeFromRecordingOptions {
         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 declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): 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;
+    };
+};
 /** ToolError-shaped error helper used by the body to surface a structured
  *  failure that the envelope converts to `{ok:false, error}`. */
 declare function throwToolError(code: ToolError['code'], message: string): never;

package/dist-cjs/synth/synthesize-from-recording.js

@@ -199,6 +199,14 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
     };
     const composed = (0, compose_from_recording_ts_1.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 = null;
+    let explainSim = null;
     // 5. OZ compile (always runs).
     const ozAdapter = (0, adapter_ts_2.createOzAdapter)(ozConfig);
     const compileRes = ozAdapter.compile(composed.ir);
@@ -376,6 +384,36 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
                 },
             };
         }
+        // --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 = [
+                {
+                    dimension: 'permit',
+                    outcome: evalResult.permit ? 'permit' : 'deny',
+                    reason: 'matches recorded call',
+                },
+            ];
+            for (const deny of harnessCases.denies) {
+                const r = (0, evaluate_ts_1.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
@@ -473,7 +511,34 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ],
         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 = { 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;
 }
 /** OZ-side `uncovered` warning patterns that the interpreter adapter
  *  actually lowers when wired in. When the interpreter adapter succeeds, we

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",

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`

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

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/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