@crediolabs/policy-synth 0.1.8 → 0.1.10

package/dist/synth/evaluate.js

@@ -175,6 +175,38 @@ function evalCompare(op, left, right, ctx) {
             return evalArgOrderedCompare(op, actual, right);
         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);
@@ -334,6 +366,23 @@ function resolveLeaf(leaf, ctx) {
             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/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/types.d.ts

@@ -182,6 +182,14 @@ export type PredicateLeaf = {
 } | {
     kind: 'call_arg';
     index: number;
+} | {
+    kind: 'call_arg_len';
+    index: number;
+} | {
+    kind: 'call_arg_field';
+    index: number;
+    element: number;
+    field: string;
 } | {
     kind: 'amount';
     token: string;

package/dist-cjs/adapters/interpreter/adapter.js

@@ -312,6 +312,10 @@ function lowerSelector(s) {
     switch (s.kind) {
         case 'arg':
             return { kind: 'call_arg', index: s.argIndex };
+        case 'arg_len':
+            return { kind: 'call_arg_len', index: s.argIndex };
+        case 'arg_field':
+            return { kind: 'call_arg_field', index: s.argIndex, element: s.element, field: s.field };
         case 'amount':
             return { kind: 'amount', token: s.token };
         case 'window_spent':
@@ -334,13 +338,15 @@ function lowerSelector(s) {
  *  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)
+ *    - arg_len   -> u32 (vec length is a small non-negative integer)
+ *    - arg_field -> IR scalarType (the field's recorded type)
  *    - 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) {
-    const scalarType = c.selector.kind === 'arg' ? c.selector.scalarType : literalScalarForSelector(c.selector.kind);
+    const scalarType = selectorScalarType(c.selector);
     return literalFromScalar(c.value, scalarType);
 }
 function literalScalarForSelector(kind) {
@@ -350,14 +356,16 @@ function literalScalarForSelector(kind) {
         case 'oracle_price':
             return 'i128';
         case 'invocation_count':
+        case 'arg_len':
             return 'u32';
         case 'now':
         case 'valid_until':
             return 'u64';
         case 'arg':
+        case 'arg_field':
         case 'calldata':
         case 'value':
-            // arg -> caller handles scalarType; calldata/value -> unreachable (Path-B).
+            // arg / arg_field -> caller handles scalarType; calldata/value -> unreachable (Path-B).
             return 'i128';
     }
 }
@@ -385,10 +393,12 @@ function literalFromScalar(value, scalarType) {
 /** 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. */
+ *  uses the selector's own `scalarType` for `arg` and `arg_field` selectors. */
 function selectorScalarType(selector) {
     if (selector.kind === 'arg')
         return selector.scalarType;
+    if (selector.kind === 'arg_field')
+        return selector.scalarType;
     return literalScalarForSelector(selector.kind);
 }
 /** Walk a condition tree and throw if any oracle_price leaf is found anywhere
@@ -462,6 +472,10 @@ function describeCondition(cond) {
                     return `per-call amount comparison on ${s.token}`;
                 case 'arg':
                     return `argument comparison on arg ${s.argIndex}`;
+                case 'arg_len':
+                    return `vec length comparison on arg ${s.argIndex}`;
+                case 'arg_field':
+                    return `map field comparison on arg ${s.argIndex}.${s.field}`;
                 case 'calldata':
                     return 'EVM calldata comparison';
                 case 'value':
@@ -477,6 +491,10 @@ function describeSelector(s) {
     switch (s.kind) {
         case 'arg':
             return `arg ${s.argIndex}`;
+        case 'arg_len':
+            return `arg_len(${s.argIndex})`;
+        case 'arg_field':
+            return `arg_field(${s.argIndex}, ${s.element}, ${s.field})`;
         case 'amount':
             return `amount(${s.token})`;
         case 'window_spent':

package/dist-cjs/adapters/oz/adapter.js

@@ -234,6 +234,10 @@ function describeCondition(cond) {
                     return `per-call amount comparison on ${s.token} (predicate DSL)`;
                 case 'arg':
                     return `argument comparison on arg ${s.argIndex} (predicate DSL)`;
+                case 'arg_len':
+                    return `vec length comparison on arg ${s.argIndex} (predicate DSL)`;
+                case 'arg_field':
+                    return `map field comparison on arg ${s.argIndex}.${s.field} (predicate DSL)`;
                 case 'calldata':
                     return 'EVM calldata comparison (predicate DSL)';
                 case 'value':
@@ -249,6 +253,10 @@ function describeSelector(s) {
     switch (s.kind) {
         case 'arg':
             return `arg ${s.argIndex}`;
+        case 'arg_len':
+            return `arg_len(${s.argIndex})`;
+        case 'arg_field':
+            return `arg_field(${s.argIndex}, ${s.element}, ${s.field})`;
         case 'amount':
             return `amount(${s.token})`;
         case 'window_spent':

package/dist-cjs/ir/types.d.ts

@@ -14,6 +14,15 @@ export type IRSelector = {
     fieldIndex?: number;
     vecMode?: IRVecMode;
     scalarType: IRScalarType;
+} | {
+    kind: 'arg_len';
+    argIndex: number;
+} | {
+    kind: 'arg_field';
+    argIndex: number;
+    element: number;
+    field: string;
+    scalarType: IRScalarType;
 } | {
     kind: 'calldata';
     offset: number;

package/dist-cjs/predicate/encode.js

@@ -170,6 +170,15 @@ function encodeLeaf(leaf) {
             return stellar_sdk_1.xdr.ScVal.scvVec([symbol('call_fn')]);
         case 'call_arg':
             return stellar_sdk_1.xdr.ScVal.scvVec([symbol('call_arg'), stellar_sdk_1.xdr.ScVal.scvU32(leaf.index)]);
+        case 'call_arg_len':
+            return stellar_sdk_1.xdr.ScVal.scvVec([symbol('call_arg_len'), stellar_sdk_1.xdr.ScVal.scvU32(leaf.index)]);
+        case 'call_arg_field':
+            return stellar_sdk_1.xdr.ScVal.scvVec([
+                symbol('call_arg_field'),
+                stellar_sdk_1.xdr.ScVal.scvU32(leaf.index),
+                stellar_sdk_1.xdr.ScVal.scvU32(leaf.element),
+                stellar_sdk_1.xdr.ScVal.scvSymbol(leaf.field),
+            ]);
         case 'amount':
             return stellar_sdk_1.xdr.ScVal.scvVec([symbol('amount'), scvAddressFromStrkey(leaf.token)]);
         case 'window_spent':

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`;
@@ -187,6 +217,8 @@ function renderVecElement(leaf) {
         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/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;
@@ -108,6 +146,8 @@ function renderVecElement(leaf) {
         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/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<{