@crediolabs/policy-synth 0.1.4 → 0.1.5

package/dist/run/schemas.js

@@ -0,0 +1,215 @@
+// packages/policy-synth/src/run/schemas.ts
+//
+// Zod schemas mirroring the policy-synth core domain types. These are the
+// public input / output shapes exposed over MCP and the CLI. They are kept
+// hand-written (rather than derived) because the MCP SDK needs a runtime
+// Zod object at the transport boundary; a drift test asserts they stay in
+// step with the TS source of truth.
+//
+// i128 amounts and other large integers are carried as base-10 decimal strings
+// end-to-end (no JS number coercion). Networks are pinned to the same closed
+// set the core defines. The discriminated union on `source` exposes BOTH
+// synthesize_policy front-ends through a single tool input.
+//
+// This module is the SINGLE source of truth for these shapes. The MCP package
+// imports them here so its tool-shape bindings stay in step; the CLI imports
+// them here so it can build the same args envelope the MCP transport builds.
+import { z } from 'zod';
+/** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
+ *  installed on-chain, so reject it at the boundary (fail-closed). */
+const U32_MAX = 4294967295;
+/** Upper bound on top-level invocations in a recorded transaction. A real
+ *  Stellar tx caps operations well below this; the bound stops a hand-crafted
+ *  payload from turning one request into an unbounded synthesis (DoS). */
+const MAX_INVOCATIONS = 512;
+export const NetworkSchema = z.enum(['mainnet', 'testnet']);
+/** ScVal subset - normalised subset the synth consumes. Mirrors
+ *  `ScVal` in packages/policy-synth/src/types.ts. */
+export const ScValSchema = z.lazy(() => z.union([
+    z.object({ type: z.literal('address'), value: z.string() }),
+    // i128 is SIGNED: real events carry negatives (e.g. a fee-adjustment/refund),
+    // so the recorder's own output must round-trip through this schema. u64/u32
+    // are unsigned and stay non-negative.
+    z.object({ type: z.literal('i128'), value: z.string().regex(/^-?[0-9]+$/) }),
+    z.object({ type: z.literal('u64'), value: z.string().regex(/^[0-9]+$/) }),
+    z.object({ type: z.literal('u32'), value: z.string().regex(/^[0-9]+$/) }),
+    z.object({ type: z.literal('symbol'), value: z.string() }),
+    z.object({ type: z.literal('vec'), value: z.array(ScValSchema) }),
+    z.object({ type: z.literal('bytes'), value: z.string() }),
+    z.object({ type: z.literal('other'), value: z.string() }),
+]));
+/** ContractInvocation mirrors the core. Annotated with an explicit
+ *  `z.ZodType<unknown>` (like ScValSchema above) so the self-referential
+ *  `subInvocations` field does not trip TS's circular type inference. */
+export const ContractInvocationSchema = z.object({
+    contract: z.string(),
+    fn: z.string(),
+    args: z.array(ScValSchema),
+    subInvocations: z.array(z.lazy(() => ContractInvocationSchema)),
+});
+export const TokenMovementSchema = z.object({
+    token: z.string(),
+    from: z.string(),
+    to: z.string(),
+    // The recorder reads the amount straight from the signed i128 event value
+    // (record/movements.ts readAmount), so a non-standard token that emits a
+    // negative transfer/mint/burn amount round-trips as a negative string. Mirror
+    // that here; the synth gate, not the wire schema, decides what to do with it.
+    amount: z.string().regex(/^-?[0-9]+$/),
+});
+export const OnChainEventSchema = z.object({
+    contract: z.string(),
+    topics: z.array(z.string()),
+    data: ScValSchema,
+});
+export const ParseConfidenceSchema = z.object({
+    overall: z.number().min(0).max(1),
+    knownContracts: z.array(z.string()),
+    unknownContracts: z.array(z.object({
+        contract: z.string(),
+        reason: z.enum(['no-abi', 'version-mismatch', 'opaque-result']),
+    })),
+    opaqueScVals: z.array(z.object({ path: z.string(), type: z.string() })),
+    thresholdUsed: z.number().min(0).max(1),
+});
+/** RecordedTransaction mirrors the core RecordedTransaction. The output shape
+ *  is referenced by name in the tool result structured content; we deliberately
+ *  type it loosely (`z.unknown()`) on the success path so the core remains the
+ *  single source of truth for the wire payload. */
+export const RecordedTransactionSchema = z
+    .object({
+    network: NetworkSchema,
+    signers: z.array(z.string()),
+    invocations: z.array(ContractInvocationSchema).max(MAX_INVOCATIONS),
+    tokenMovements: z.array(TokenMovementSchema),
+    events: z.array(OnChainEventSchema),
+    authEntries: z.array(z.unknown()),
+    ledgerSequence: z.number().int().nonnegative(),
+    fetchedAt: z.number().int().nonnegative(),
+    parseConfidence: ParseConfidenceSchema,
+    sourceAccount: z.string(),
+})
+    .passthrough();
+/** MandateSpec mirrors the core MandateSpec. The deterministic Mandate
+ *  front-end needs no parseConfidence; the tool adapter injects the full
+ *  confidence after synthesis so the orchestrator can compare. */
+export const MandateSpecSchema = z
+    .object({
+    chain: z.literal('stellar'),
+    contract: z.string(),
+    method: z.string().optional(),
+    spendingLimit: z
+        .object({
+        token: z.string(),
+        limit: z.string().regex(/^[0-9]+$/),
+        windowSeconds: z.number().int().positive(),
+    })
+        .optional(),
+    // A threshold of 0 means "0 approvals", which is not a real M-of-N gate.
+    approvalThreshold: z.number().int().positive().optional(),
+    recipients: z.array(z.string()).optional(),
+    expiry: z
+        .object({
+        validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+        validUntilUnixSeconds: z.number().int().positive().optional(),
+    })
+        .optional(),
+})
+    .passthrough();
+/** ComposeUserResponses mirrors the core. */
+export const ComposeUserResponsesSchema = z
+    .object({
+    windowSeconds: z.number().int().positive().optional(),
+    validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+    limitAmount: z
+        .string()
+        .regex(/^[0-9]+$/)
+        .optional(),
+    invocationLimit: z.number().int().positive().optional(),
+})
+    .passthrough();
+/** OzAdapterConfig - the per-network OZ built-in instance addresses. */
+export const OzAdapterConfigSchema = z.object({
+    network: NetworkSchema,
+    instances: z.object({
+        spending_limit: z.string(),
+        simple_threshold: z.string(),
+        weighted_threshold: z.string(),
+    }),
+});
+// ===== record_transaction =====
+export const RecordTransactionInputSchema = z
+    .object({
+    hash: z.string().min(1).optional(),
+    xdr: z.string().min(1).optional(),
+    network: NetworkSchema,
+    confidenceOverride: z.number().min(0).max(1).optional(),
+})
+    .refine((v) => !(v.hash && v.xdr), {
+    message: 'provide exactly one of `hash` or `xdr`, not both',
+})
+    .refine((v) => Boolean(v.hash) || Boolean(v.xdr), {
+    message: 'one of `hash` or `xdr` is required',
+});
+// ===== synthesize_policy =====
+//
+// Discriminated union on `source` exposes BOTH front-ends through ONE tool.
+// - `source: 'mandate'` -> calls synthesizeFromMandate
+// - `source: 'recording'` -> calls synthesizeFromRecording
+export const SynthesizePolicyMandateInputSchema = z.object({
+    source: z.literal('mandate'),
+    mandate: MandateSpecSchema,
+    ozConfig: OzAdapterConfigSchema.optional(),
+});
+/** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
+ *  express (per-method scoping, invocation-count windows, oracle bounds, exact
+ *  hop paths) lower to a real interpreter predicate document instead of being
+ *  surfaced as warnings. The core deep-validates `smartAccountAddress` (a C...
+ *  contract, not the recording's G... source) and the tighten-only oracle
+ *  bounds; the schema stays light so the core owns the friendly ToolErrors. */
+export const InterpreterOptionsSchema = z.object({
+    smartAccountAddress: z.string(),
+    installNonce: z.number().int().positive().optional(),
+    oracleParams: z
+        .object({
+        maxStalenessSeconds: z.number().int().positive().optional(),
+        maxDeviationBps: z.number().int().positive().optional(),
+    })
+        .optional(),
+});
+export const SynthesizePolicyRecordingInputSchema = z.object({
+    source: z.literal('recording'),
+    recordedTx: RecordedTransactionSchema,
+    network: NetworkSchema,
+    userResponses: ComposeUserResponsesSchema.optional(),
+    confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
+    interpreter: InterpreterOptionsSchema.optional(),
+    ozConfig: OzAdapterConfigSchema.optional(),
+});
+export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [
+    SynthesizePolicyMandateInputSchema,
+    SynthesizePolicyRecordingInputSchema,
+]);
+// ===== Error envelope (canonical) =====
+//
+// Mirrors ToolError from packages/policy-synth/src/errors.ts. We use a
+// `z.string()` for `code` (not an enum) because the core's ErrorCode union
+// evolves over time; the transport contract only promises a string code the
+// caller can dispatch on. A drift test asserts the canonical codes still
+// pass through unchanged.
+export const ToolErrorSchema = z
+    .object({
+    code: z.string(),
+    message: z.string(),
+    severity: z.enum(['info', 'warning', 'error', 'fatal']),
+    retryable: z.boolean(),
+    remediation: z
+        .object({
+        toolCall: z.object({ name: z.string(), args: z.record(z.unknown()) }).optional(),
+        userQuestion: z.object({ code: z.string(), question: z.string() }).optional(),
+        docsUrl: z.string().optional(),
+    })
+        .optional(),
+    details: z.unknown().optional(),
+})
+    .passthrough();

package/dist/synth/deny-cases.js

@@ -1,3 +1,4 @@
+import { MAX_SCVAL_CLONE_DEPTH } from "../types.js";
 import { literalNumericBigInt } from "./predicate-literals.js";
 const ORACLE_CASES = [
     ['oracle_stale', 'stale'],
@@ -353,9 +354,24 @@ function cloneContext(ctx) {
         cloned.signerWeights = { ...ctx.signerWeights };
     return cloned;
 }
-function cloneScVal(value) {
+function cloneScVal(value, depth = 0) {
+    // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+    // payload cannot RangeError the JS stack during deny-case mutation. Over-depth
+    // throws a ToolError-shaped error that the `synthesizeFromRecording` envelope
+    // (item 3) converts to a structured `{ok:false, error}`.
     if (value.type === 'vec') {
-        return { type: 'vec', value: value.value.map(cloneScVal) };
+        if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+            throw cloneDepthError(value);
+        }
+        return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) };
     }
     return { ...value };
 }
+function cloneDepthError(value) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'SYNTHESIS_ERROR';
+    err.severity = 'error';
+    err.retryable = false;
+    err.depthContext = value.type;
+    throw err;
+}

package/dist/synth/evaluate.js

@@ -200,7 +200,7 @@ function evalCompare(op, left, right, ctx) {
 function evalArgEq(op, actual, right, ctx) {
     // eq(call_arg[i], literal_vec) -> EXACT ordered vector equality
     if (op === 'eq' && right.kind === 'literal_vec') {
-        if (!actual || actual.type !== 'vec')
+        if (actual?.type !== 'vec')
             return { permit: false, reason: 'ARG_MISMATCH' };
         return compareVecExact(actual.value, right.elements, ctx)
             ? { permit: true }
@@ -218,7 +218,7 @@ function evalArgEq(op, actual, right, ctx) {
     }
     // eq(call_arg[i], literal_i128) -> BigInt compare
     if (op === 'eq' && right.kind === 'literal_i128') {
-        if (!actual || actual.type !== 'i128')
+        if (actual?.type !== 'i128')
             return { permit: false, reason: 'ARG_MISMATCH' };
         return BigInt(actual.value) === BigInt(right.value)
             ? { permit: true }

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

@@ -1,5 +1,5 @@
 import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
-import type { ToolResponse } from '../errors.ts';
+import type { ToolError, ToolResponse } from '../errors.ts';
 import { type Network, type PredicateNode, type ProposedPolicy, type RecordedTransaction } from '../types.ts';
 import { type ComposeUserResponses } from './compose-from-recording.ts';
 /** Per-policy interpreter adapter config the caller opts into. Absent ->
@@ -42,5 +42,8 @@ export interface SynthesizeFromRecordingOptions {
     };
     interpreter?: InterpreterAdapterOptions;
 }
-/** Synthesize a ProposedPolicy from a recorded transaction. */
 export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+/** 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;
+export { throwToolError };

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

@@ -33,7 +33,7 @@
 import { createInterpreterAdapter, lowerRuleToPredicate, PLACEHOLDER_INTERPRETER_ADDRESS, } from "../adapters/interpreter/adapter.js";
 import { createOzAdapter } from "../adapters/oz/adapter.js";
 import { encodePredicate } from "../predicate/encode.js";
-import { OZ_LIMITS, SOROBAN_LIMITS, } from "../types.js";
+import { MAX_SCVAL_CLONE_DEPTH, OZ_LIMITS, SOROBAN_LIMITS, } from "../types.js";
 import { composeFromRecording, } from "./compose-from-recording.js";
 import { generateCases } from "./deny-cases.js";
 import { evaluate } from "./evaluate.js";
@@ -42,12 +42,76 @@ import { lower } from "./lower.js";
 import { minimize } from "./minimize.js";
 import { decideScope } from "./scope.js";
 const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
-/** Synthesize a ProposedPolicy from a recorded transaction. */
 export function synthesizeFromRecording(tx, opts, ozConfig) {
+    // 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
+    // instead of being silently swallowed. The envelope must wrap the entire
+    // synthesis body so a thrown `encodePredicate` cap error (PREDICATE_TOO_DEEP,
+    // TOO_MANY_LEAVES, etc.) or a depth-cap throw from `cloneScVal` surfaces as
+    // a structured ToolError rather than a thrown RangeError.
+    try {
+        return synthesizeFromRecordingInner(tx, opts, ozConfig);
+    }
+    catch (e) {
+        if (isToolErrorShape(e)) {
+            return {
+                ok: false,
+                error: {
+                    code: e.code,
+                    message: e.message,
+                    severity: 'error',
+                    retryable: false,
+                },
+            };
+        }
+        throw e;
+    }
+}
+/** True when `e` is the ToolError-shaped throw the internal pipeline uses to
+ *  signal a structured failure (e.g. `encodePredicate` cap errors, `cloneScVal`
+ *  depth-cap throws). Detected by a string `code` field — the only contract
+ *  the body's internal helpers agree on. */
+function isToolErrorShape(e) {
+    if (e === null || typeof e !== 'object')
+        return false;
+    const code = e.code;
+    const message = e.message;
+    return typeof code === 'string' && typeof message === 'string';
+}
+/** ToolError-shaped error helper used by the body to surface a structured
+ *  failure that the envelope converts to `{ok:false, error}`. */
+function throwToolError(code, message) {
+    const err = new Error(message);
+    err.code = code;
+    err.severity = 'error';
+    err.retryable = false;
+    throw err;
+}
+/** Synthesize a ProposedPolicy from a recorded transaction. */
+function synthesizeFromRecordingInner(tx, opts, ozConfig) {
     // 0. validate inputs (fail closed - never synthesize from garbage).
     const invalid = validateOptions(opts);
     if (invalid)
         return { ok: false, error: invalid };
+    // 0a. per-movement amount validation (item 2). Synthesizing from a recording
+    //     whose `tokenMovements[].amount` does not match the canonical positive
+    //     decimal integer format is a malformed-input failure, not a runtime
+    //     one - reject it here so the downstream `BigInt(m.amount)` in
+    //     `buildPermitContext` cannot throw a SyntaxError past the envelope.
+    for (const [i, m] of tx.tokenMovements.entries()) {
+        if (!/^[0-9]+$/.test(m.amount)) {
+            return {
+                ok: false,
+                error: {
+                    code: 'RECORDING_VALIDATION_FAILED',
+                    message: `tokenMovements[${i}].amount must be a positive decimal integer string, got: ${m.amount}`,
+                    severity: 'error',
+                    retryable: false,
+                },
+            };
+        }
+    }
     // 1. parseConfidence gate.
     const threshold = opts.confidenceOverride?.threshold ?? tx.parseConfidence.thresholdUsed;
     if (tx.parseConfidence.overall < threshold) {
@@ -88,9 +152,6 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
         return scopeRes;
     const scope = scopeRes.data;
     if (scope.kind !== 'call_contract') {
-        // A default scope on the recording-path is not currently a covered flow;
-        // surface SYNTHESIS_ERROR so the orchestrator never silently emits an
-        // over-broad default-scoped policy.
         return {
             ok: false,
             error: {
@@ -126,17 +187,6 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
     }
     // 6. Interpreter compile (opt-in; fail-closed when the user routed real
     //    restrictions to the interpreter).
-    //
-    //    When the caller opts in, the interpreter always runs - even for a
-    //    scope-only interpreter IR (no routed constraints) - because the
-    //    interpreter adapter lowers `scope.contract` + `scope.method` into a
-    //    `call_contract == ...` and `call_fn == ...` predicate sibling pair.
-    //    This is the real per-method enforcement the OZ adapter cannot do.
-    //
-    //    When the caller does NOT opt in: today's behaviour is preserved. The
-    //    compose step routes every constraint to the OZ IR; OZ flags the ones
-    //    it cannot lower as `uncovered` and the orchestrator surfaces them as
-    //    warnings. No interpreter doc is produced.
     const interpreterOpts = opts.interpreter;
     let interpreterPolicyDocument = null;
     let interpreterPolicyRef = null;
@@ -147,18 +197,6 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
             smartAccountAddress: interpreterOpts.smartAccountAddress,
             ...(interpreterOpts.oracleParams ? { oracleParams: interpreterOpts.oracleParams } : {}),
         };
-        // The starting PredicateNode the self-verify + minimise pipeline drives.
-        // Two paths populate it:
-        //   - Test seam (`__testPredicateNode` set): use it directly, skipping the
-        //     adapter's compile(). Production code MUST NOT set the seam; it
-        //     exists so the pipeline can be exercised on hand-crafted predicates
-        //     (redundant conjuncts for minimise, deliberately over-broad leaves
-        //     for DENY_CASE_FAILURE).
-        //   - Normal: call the interpreter adapter's compile() so the existing
-        //     enforcement gates (SCOPE_SELF_CALL / ORACLE_LEAF_INVALID_POSITION /
-        //     ORACLE_PARAMS_OUT_OF_RANGE + uncovered reporting) fire first, then
-        //     re-derive the pre-encoding PredicateNode via `lowerRuleToPredicate`
-        //     so minimise + harness see the same shape the encoder will see.
         let startingPredicate = null;
         const testSeam = interpreterOpts.__testPredicateNode;
         if (testSeam !== undefined) {
@@ -171,11 +209,6 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
                 interpreterRes = interpreterAdapter.compile(composed.interpreterIr);
             }
             catch (e) {
-                // Interpreter enforcement-gate throws (SCOPE_SELF_CALL,
-                // ORACLE_LEAF_INVALID_POSITION, ORACLE_PARAMS_OUT_OF_RANGE). Surface
-                // the gate code so the caller can act; never install an OZ-only
-                // partial policy - the user explicitly asked for these constraints
-                // to be enforced and silently dropping them yields an over-broad rule.
                 const code = e.code;
                 const allowedCodes = [
                     'SCOPE_SELF_CALL',
@@ -260,15 +293,8 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
                 },
             };
         }
-        // 6b. Self-verify + minimise. We always build the same permit EvalContext
-        //     from the recorded tx + synthesised constraints so the harness
-        //     reasons about the intended call (the only one the user actually
-        //     recorded). The recorded call MUST permit under the predicate; the
-        //     generated deny battery MUST all deny.
+        // 6b. Self-verify + minimise.
         if (!topLevel) {
-            // The orchestrator guarantees this for the call_contract branch above;
-            // a default-scoped policy never reaches the interpreter block. Fail
-            // closed rather than attempt to self-verify a vague shape.
             return {
                 ok: false,
                 error: {
@@ -291,10 +317,6 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
             };
         }
         const permitCtx = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate);
-        // Top-level `and` predicates are what generateCases + minimize assume;
-        // for any other shape we skip minimise (encode as-is) but still assert
-        // the permit case permits. An over-broad non-and predicate is still
-        // caught by the harness on the next step.
         const finalPredicate = startingPredicate.op === 'and' ? minimize(startingPredicate, permitCtx) : startingPredicate;
         const harnessCases = generateCases(finalPredicate, permitCtx);
         const harnessResult = runHarness(finalPredicate, harnessCases);
@@ -324,14 +346,12 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
             };
         }
         // 6c. Re-encode the (possibly minimised) PredicateNode and stamp the
-        //     canonical bytes back onto the PolicyDocument + PolicyRef. minimize
-        //     and encodePredicate are pure and deterministic, so the re-encoded
-        //     doc is byte-identical to what compile() would have produced for
-        //     the minimised tree.
+        //     canonical bytes back onto the PolicyDocument + PolicyRef. The
+        //     `encodePredicate` helper throws ToolError-shaped errors on cap
+        //     breaches (PREDICATE_TOO_DEEP, TOO_MANY_LEAVES, etc.) - the outer
+        //     envelope converts them to a structured `{ok:false, error}`.
         const { encodedPredicate, predicateHash } = encodePredicate(finalPredicate);
         if (testSeam !== undefined) {
-            // Test seam: build the PolicyDocument + PolicyRef now (compile() was
-            // skipped). Shape mirrors the adapter's output exactly.
             interpreterPolicyDocument = {
                 grammarVersion: 1,
                 installNonce: interpreterOpts.installNonce ?? 1,
@@ -371,16 +391,13 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
         }
     }
     // When the interpreter succeeds, OZ-side `uncovered` warnings that the
-    // interpreter actually lowered (per-method scoping, recipient allowlists,
-    // eq_seq paths, oracle_price / invocation_count / token-mismatch
-    // window_spent) are misleading: OZ really did not lower them, but the
-    // interpreter did. Drop those so the user-facing warnings reflect what is
-    // still UN-enforced, not what OZ alone could not do.
+    // interpreter actually lowered are misleading: OZ really did not lower them,
+    // but the interpreter did. Drop those so the user-facing warnings reflect
+    // what is still UN-enforced, not what OZ alone could not do.
     const ozUncovered = interpreterPolicyRef
         ? compileRes.uncovered.filter((u) => !INTERPRETER_COVERED_OZ_PATTERN.test(u))
         : compileRes.uncovered;
-    // 7. Merge into the OZ-shaped ProposedPolicy. Order:
-    //    [interpreterRef?, ...oz_builtinRefs]; cap = OZ_LIMITS.maxPoliciesPerRule.
+    // 7. Merge into the OZ-shaped ProposedPolicy.
     const ozRefs = compileRes.proposed.policyRefs;
     const mergedRefs = [];
     if (interpreterPolicyRef)
@@ -415,6 +432,9 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
     };
     return { ok: true, data: proposed };
 }
+// Re-export the throwToolError helper for callers that need to surface a
+// ToolError-shaped throw inside the body (e.g. tests).
+export { throwToolError };
 /** OZ-side `uncovered` warning patterns that the interpreter adapter
  *  actually lowers when wired in. When the interpreter adapter succeeds, we
  *  drop matching entries from the OZ uncovered list so the user-facing
@@ -461,12 +481,25 @@ function validateOptions(opts) {
         if (typeof sa !== 'string' || sa.length === 0) {
             return synthesisError(`interpreter.smartAccountAddress must be a non-empty string, got: ${String(sa)}`);
         }
+        // Blocklist placeholder / stub prefixes (item 5). Runs BEFORE the
+        // C.../56-char shape check so a fixture/LLM-seam marker is reported
+        // with the specific placeholder error (not a generic "must be a
+        // C... contract" message). A real install routes a C... contract
+        // address derivable from the on-chain account; any
+        // 'VERIFY-*' / 'PLACEHOLDER-*' / 'TODO-*' prefix is an LLM seam /
+        // fixture marker that must never reach the install payload.
+        if (PLACEHOLDER_SMART_ACCOUNT_PREFIX.test(sa)) {
+            return synthesisError(`interpreter.smartAccountAddress must not be a placeholder/stub address (matches /${PLACEHOLDER_SMART_ACCOUNT_PREFIX.source}/), got: ${sa}`);
+        }
         if (!isContractAddress(sa)) {
             return synthesisError(`interpreter.smartAccountAddress must be a C... Stellar contract address (the on-chain policy-bound account, not the G... source account), got: ${sa}`);
         }
         const nonce = opts.interpreter.installNonce;
-        if (nonce !== undefined && !isPositiveInt(nonce)) {
-            return synthesisError(`interpreter.installNonce must be a positive integer, got: ${nonce}`);
+        // Item 4: installNonce must fit u32 (the on-chain per-rule nonce is a
+        // u32; values above SOROBAN_LIMITS.u32Max cannot be installed). Mirrors
+        // the validUntilLedger SOROBAN_LIMITS.u32Max check above.
+        if (nonce !== undefined && (!isPositiveInt(nonce) || nonce > SOROBAN_LIMITS.u32Max)) {
+            return synthesisError(`interpreter.installNonce must be a positive u32 integer (<= ${SOROBAN_LIMITS.u32Max}), got: ${nonce}`);
         }
         const op = opts.interpreter.oracleParams;
         if (op) {
@@ -484,6 +517,12 @@ function validateOptions(opts) {
     }
     return null;
 }
+/** Placeholder/stub smart-account prefixes (item 5). Mirrors the
+ *  `PLACEHOLDER_INTERPRETER_ADDRESS` marker the interpreter adapter uses for
+ *  the interpreter-contract strkey; a real install must point at a C...
+ *  contract address derivable from the on-chain account, never a
+ *  fixture/LLM-seam marker. */
+const PLACEHOLDER_SMART_ACCOUNT_PREFIX = /^(VERIFY-|PLACEHOLDER-|TODO-)/i;
 function isPositiveInt(n) {
     return Number.isInteger(n) && n > 0;
 }
@@ -561,18 +600,37 @@ function buildPermitContext(tx, scope, topLevel, userResponses, predicate) {
     }
     return ctx;
 }
-function cloneScVal(value) {
+function cloneScVal(value, depth = 0) {
     // EvalContext.args is an ScVal[]; the recorded args are already ScVal-shaped
     // (decoded by the recorder). We clone top-level shells so the harness can
-    // mutate deny cases without aliasing the recorded call.
+    // mutate deny cases without aliasing the recorded call. Recursion is
+    // bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec payload
+    // cannot RangeError the JS stack; the over-depth branch throws a
+    // ToolError-shaped error that the `synthesizeFromRecording` envelope
+    // (item 3) converts to `{ok:false, error}`.
     if (value.type === 'vec') {
+        if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+            throw cloneDepthError(value);
+        }
         return {
             type: 'vec',
-            value: value.value.map(cloneScVal),
+            value: value.value.map((v) => cloneScVal(v, depth + 1)),
         };
     }
     return { ...value };
 }
+/** Throw a ToolError-shaped error when the clone exceeds MAX_SCVAL_CLONE_DEPTH.
+ *  The shape (object with string `code`) is what the `synthesizeFromRecording`
+ *  envelope detects and converts to a structured `{ok:false, error}`. */
+function cloneDepthError(value) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'SYNTHESIS_ERROR';
+    err.severity = 'error';
+    err.retryable = false;
+    // Tag the offending value so failures are diagnosable.
+    err.depthContext = value.type;
+    throw err;
+}
 /** Walk every `oracle_price` leaf in the predicate and return a price map
  *  whose entries satisfy the bound so the intended call permits. The
  *  timestamp is pinned to `nowSeconds` (the recorded `fetchedAt`) so the

package/dist/types.d.ts

@@ -42,6 +42,23 @@ export declare const SOROBAN_LIMITS: {
      *  used to convert a spend window in seconds to OZ `period_ledgers`. */
     readonly secondsPerLedger: 5;
 };
+/** Maximum recursion depth for decoding Recursive `ScVal` shapes (vec-in-vec).
+ *  A real Stellar tx caps nesting well below this; the bound hard-caps a
+ *  hand-crafted payload so the recorder fails CLOSED (records the over-depth
+ *  branch as opaque `depth-exceeded`) rather than RangeErroring the JS stack.
+ *  Mirrors the `MAX_AUTH_TREE_DEPTH = 16` boundary the auth-tree decoder
+ *  already enforces; lifted to 30 so legitimate nested args (a path vec
+ *  inside an order vec inside a market-data vec) decode cleanly while a
+ *  malformed ~10000-deep payload still trips the cap. */
+export declare const MAX_SCVAL_DEPTH: 30;
+/** Maximum recursion depth for cloning nested `ScVal` shapes (vec-in-vec) into
+ *  the simulator / verify / harness contexts. Mirrors `MAX_SCVAL_DEPTH` above
+ *  so a hand-crafted nested-vec payload cannot RangeError the JS stack during
+ *  context building. Over-depth throws a ToolError (caught by the
+ *  `synthesizeFromRecording` envelope + the simulator/verify boundaries) so
+ *  the caller gets a structured `{ok:false, error}` instead of a thrown
+ *  RangeError. */
+export declare const MAX_SCVAL_CLONE_DEPTH: 30;
 /** Predicate-document caps - enforced fail-closed at install by BOTH the synth (TS)
  *  AND the interpreter (Rust). Single source: a CI test asserts the two cap sets are
  *  byte-identical (TS reads the same JSON manifest the Rust build emits). If they

package/dist/types.js

@@ -17,6 +17,23 @@ export const SOROBAN_LIMITS = {
      *  used to convert a spend window in seconds to OZ `period_ledgers`. */
     secondsPerLedger: 5,
 };
+/** Maximum recursion depth for decoding Recursive `ScVal` shapes (vec-in-vec).
+ *  A real Stellar tx caps nesting well below this; the bound hard-caps a
+ *  hand-crafted payload so the recorder fails CLOSED (records the over-depth
+ *  branch as opaque `depth-exceeded`) rather than RangeErroring the JS stack.
+ *  Mirrors the `MAX_AUTH_TREE_DEPTH = 16` boundary the auth-tree decoder
+ *  already enforces; lifted to 30 so legitimate nested args (a path vec
+ *  inside an order vec inside a market-data vec) decode cleanly while a
+ *  malformed ~10000-deep payload still trips the cap. */
+export const MAX_SCVAL_DEPTH = 30;
+/** Maximum recursion depth for cloning nested `ScVal` shapes (vec-in-vec) into
+ *  the simulator / verify / harness contexts. Mirrors `MAX_SCVAL_DEPTH` above
+ *  so a hand-crafted nested-vec payload cannot RangeError the JS stack during
+ *  context building. Over-depth throws a ToolError (caught by the
+ *  `synthesizeFromRecording` envelope + the simulator/verify boundaries) so
+ *  the caller gets a structured `{ok:false, error}` instead of a thrown
+ *  RangeError. */
+export const MAX_SCVAL_CLONE_DEPTH = 30;
 /** Predicate-document caps - enforced fail-closed at install by BOTH the synth (TS)
  *  AND the interpreter (Rust). Single source: a CI test asserts the two cap sets are
  *  byte-identical (TS reads the same JSON manifest the Rust build emits). If they