@crediolabs/policy-synth 0.1.4 → 0.1.6

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

@@ -43,6 +43,7 @@ import type { ToolError, ToolResponse } from '../errors.ts'
 import { encodePredicate } from '../predicate/encode.ts'
 import {
   type ContractInvocation,
+  MAX_SCVAL_CLONE_DEPTH,
   type Network,
   OZ_LIMITS,
   type PredicateLeaf,
@@ -56,7 +57,7 @@ import {
   type ComposeUserResponses,
   composeFromRecording,
 } from './compose-from-recording.ts'
-import { generateCases } from './deny-cases.ts'
+import { generateCases, ORIGINAL_DIMENSIONS } from './deny-cases.ts'
 import { type EvalContext, evaluate } from './evaluate.ts'
 import { runHarness } from './harness.ts'
 import { lower } from './lower.ts'
@@ -102,16 +103,86 @@ export interface SynthesizeFromRecordingOptions {
   interpreter?: InterpreterAdapterOptions
 }
 
-/** Synthesize a ProposedPolicy from a recorded transaction. */
 export function synthesizeFromRecording(
   tx: RecordedTransaction,
   opts: SynthesizeFromRecordingOptions,
   ozConfig: OzAdapterConfig
+): ToolResponse<ProposedPolicy> {
+  // 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 as ToolError['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: unknown): e is { code: string; message: string } {
+  if (e === null || typeof e !== 'object') return false
+  const code = (e as { code?: unknown }).code
+  const message = (e as { message?: unknown }).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: ToolError['code'], message: string): never {
+  const err = new Error(message) as Error & { code: string; severity: string; retryable: boolean }
+  err.code = code
+  err.severity = 'error'
+  err.retryable = false
+  throw err
+}
+
+/** Synthesize a ProposedPolicy from a recorded transaction. */
+function synthesizeFromRecordingInner(
+  tx: RecordedTransaction,
+  opts: SynthesizeFromRecordingOptions,
+  ozConfig: OzAdapterConfig
 ): ToolResponse<ProposedPolicy> {
   // 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) {
@@ -127,6 +198,33 @@ export function synthesizeFromRecording(
     }
   }
 
+  // 1a. Zero-invocation refusal (item 1). A recording with zero contract
+  //     invocations cleared the parseConfidence gate legitimately (the
+  //     `denom === 0` short-circuit pins overall to 1.0 for that case), but a
+  //     policy must scope to an authorized contract call. Refuse before any
+  //     lower/scope work so the failure is specific and actionable. The
+  //     recorder's silence is also made visible via `parseConfidence.noInvocations`
+  //     so consumers can pattern-match without inferring from `invocations: []`
+  //     next to `overall: 1.0`. The message does NOT ask for an ABI - the
+  //     failure mode is the recording shape, not decoding coverage.
+  const hasNoInvocations = tx.parseConfidence.noInvocations === true || tx.invocations.length === 0
+  if (hasNoInvocations) {
+    return {
+      ok: false,
+      error: {
+        code: 'SYNTHESIS_ERROR',
+        message:
+          'Recording contains no contract invocation to scope a policy to. Re-record a transaction that invokes a Soroban contract function (e.g. an SAC/SEP-41 transfer, a Blend yield-claim, or a SoroSwap swap).',
+        severity: 'error',
+        retryable: false,
+        details: {
+          invocations: tx.invocations.length,
+          noInvocationsMarker: tx.parseConfidence.noInvocations === true,
+        },
+      },
+    }
+  }
+
   // Bound the recording size fail-closed (defense-in-depth for direct callers;
   // the MCP schema caps this too).
   if (tx.invocations.length > SOROBAN_LIMITS.maxInvocations) {
@@ -154,9 +252,6 @@ export function synthesizeFromRecording(
   if (!scopeRes.ok) return scopeRes
   const scope: ScopeDecision = 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: {
@@ -196,17 +291,6 @@ export function synthesizeFromRecording(
 
   // 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: ProposedPolicy['policyDocuments'][number] | null = null
@@ -220,18 +304,6 @@ export function synthesizeFromRecording(
       ...(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: PredicateNode | null = null
     const testSeam = interpreterOpts.__testPredicateNode
     if (testSeam !== undefined) {
@@ -243,11 +315,6 @@ export function synthesizeFromRecording(
       try {
         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 as { code?: ToolError['code'] }).code
         const allowedCodes: ToolError['code'][] = [
           'SCOPE_SELF_CALL',
@@ -338,15 +405,8 @@ export function synthesizeFromRecording(
       }
     }
 
-    // 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: {
@@ -370,14 +430,12 @@ export function synthesizeFromRecording(
     }
     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: PredicateNode =
-      startingPredicate.op === 'and' ? minimize(startingPredicate, permitCtx) : startingPredicate
+      startingPredicate.op === 'and'
+        ? minimize(startingPredicate, permitCtx, ORIGINAL_DIMENSIONS)
+        : startingPredicate
 
-    const harnessCases = generateCases(finalPredicate, permitCtx)
+    const harnessCases = generateCases(finalPredicate, permitCtx, ORIGINAL_DIMENSIONS)
     const harnessResult = runHarness(finalPredicate, harnessCases)
     if (!harnessResult.ok) {
       return {
@@ -407,15 +465,13 @@ export function synthesizeFromRecording(
     }
 
     // 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,
@@ -455,17 +511,14 @@ export function synthesizeFromRecording(
   }
 
   // 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: ProposedPolicy['policyRefs'] = []
   if (interpreterPolicyRef) mergedRefs.push(interpreterPolicyRef)
@@ -488,12 +541,26 @@ export function synthesizeFromRecording(
     policies: mergedRefs,
   }
 
+  // When nothing installable was synthesised (no interpreter doc AND no OZ
+  // policy refs), an empty `policies` array reads as "no restrictions" rather
+  // than "I synthesised nothing". Surface that explicitly so the empty result
+  // is never mistaken for a permissive policy - the context rule still exists,
+  // but it constrains nothing. (Kept as `{ok:true}` so the documented
+  // Path-A/Path-B demo behaviour is preserved - see F3.)
+  const zeroPolicyWarning =
+    mergedRefs.length === 0 && !interpreterPolicyDocument
+      ? [
+          'No policy constraints were synthesised: the call to this contract is UNCONSTRAINED by this policy. Enable the interpreter (supply a smart account) to enforce the surfaced constraints.',
+        ]
+      : []
+
   const proposed: ProposedPolicy = {
     contextRule: mergedContextRule,
     policyDocuments: interpreterPolicyDocument ? [interpreterPolicyDocument] : [],
     policyRefs: mergedRefs,
     parseConfidence: { ...tx.parseConfidence },
     warnings: [
+      ...zeroPolicyWarning,
       ...ozUncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
       ...composed.warnings.map((w) => `${UNCOVERED_PREFIX}${w}`),
     ],
@@ -502,6 +569,10 @@ export function synthesizeFromRecording(
   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
@@ -551,7 +622,7 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
     }
     if (ur.limitAmount !== undefined && !isPositiveI128(ur.limitAmount)) {
       return synthesisError(
-        `limitAmount must be a positive i128 decimal string, got: ${ur.limitAmount}`
+        `limitAmount must be a positive i128 decimal string within [1, ${I128_MAX}] (2^127-1), got: ${ur.limitAmount}`
       )
     }
   }
@@ -562,14 +633,31 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
         `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) {
@@ -596,15 +684,32 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
   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
+
+/** Maximum value a signed i128 can hold (2^127-1). A limitAmount above this
+ *  cannot be represented on-chain, so reject it at the synthesis boundary
+ *  (fail-closed) instead of passing it through as an over-broad spending_limit.
+ *  Mirrors the SOROBAN_LIMITS.u32Max bound the ledger-sequence fields enforce. */
+const I128_MAX = 2n ** 127n - 1n
+
 function isPositiveInt(n: number): boolean {
   return Number.isInteger(n) && n > 0
 }
 
-/** True when `s` is a canonical positive decimal integer (i128-safe via BigInt). */
+/** True when `s` is a canonical positive decimal integer inside the signed-i128
+ *  range [1, 2^127-1]. A value above the i128 ceiling is rejected (fail-closed):
+ *  it cannot be installed on-chain, and accepting it would emit a spending_limit
+ *  with an effectively unbounded cap. */
 function isPositiveI128(s: string): boolean {
   if (!/^[0-9]+$/.test(s)) return false
   try {
-    return BigInt(s) > 0n
+    const v = BigInt(s)
+    return v > 0n && v <= I128_MAX
   } catch {
     return false
   }
@@ -689,19 +794,46 @@ function buildPermitContext(
   return ctx
 }
 
-function cloneScVal(value: { type: string; value: unknown }): ContractInvocation['args'][number] {
+function cloneScVal(
+  value: { type: string; value: unknown },
+  depth = 0
+): ContractInvocation['args'][number] {
   // 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 as ContractInvocation['args'][number][]).map(cloneScVal),
+      value: (value.value as ContractInvocation['args'][number][]).map((v) =>
+        cloneScVal(v, depth + 1)
+      ),
     }
   }
   return { ...value } as ContractInvocation['args'][number]
 }
 
+/** 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: { type: string; value: unknown }): never {
+  const err = new Error(
+    `ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`
+  ) as Error & { code: string; severity: string; retryable: boolean; depthContext: unknown }
+  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/src/types.ts

@@ -11,6 +11,11 @@ export type ScVal =
   | { type: 'symbol'; value: string }
   | { type: 'vec'; value: ScVal[] }
   | { type: 'bytes'; value: string }
+  /** Map<Symbol, ScVal> carried forward for SAC/SEP-41 transfer event data,
+   *  which uses a Map shape (key "amount" -> I128) on Stellar mainnet. The
+   *  entry key is captured as its symbol/form string so readAmount can route
+   *  to the conventional field name without re-decoding the full XDR. */
+  | { type: 'map'; value: Array<{ key: string; val: ScVal }> }
   | { type: 'other'; value: string }
 
 /** OZ Accounts framework hard limits (verified against canonical OZ source). */
@@ -33,6 +38,25 @@ export const SOROBAN_LIMITS = {
   secondsPerLedger: 5,
 } as const
 
+/** 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 as const
+
+/** 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 as const
+
 /** 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
@@ -222,7 +246,15 @@ export type AmbiguityCode =
 
 /** Structured recording freshness. `overall` is the gate threshold (default 1.0); the
  *  breakdown is the diagnostic the user / agent sees when the gate fires. The
- *  computation rule is pinned: `overall = 1 - (unknownContracts + opaqueScVals) / total`. */
+ *  computation rule is pinned: `overall = 1 - (unknownContracts + opaqueScVals) / total`.
+ *
+ *  `noInvocations` (item 1) is a recorder-side marker set ONLY when the envelope
+ *  contained zero `invokeContract` host functions (e.g. a `createContract` or
+ *  `uploadContractWasm` op). The math is unchanged: that case still scores 1.0
+ *  via the `denom === 0` guard. The marker exists so a consumer does not have
+ *  to infer the situation from `invocations.length === 0` next to `overall: 1.0`
+ *  — a downstream synth refuses such recordings with a specific, actionable
+ *  error rather than silently producing a useless empty scope. */
 export interface ParseConfidence {
   overall: number // 0..1
   knownContracts: string[]
@@ -232,4 +264,8 @@ export interface ParseConfidence {
   }>
   opaqueScVals: Array<{ path: string; type: string }>
   thresholdUsed: number // 1.0 by default; > 0 only via explicit confidence_override
+  /** True iff the recorder decoded zero contract invocations. Absent on
+   *  recordings that pre-date this field; consumers should treat `undefined`
+   *  as "no marker" and rely on `invocations.length` as the fallback. */
+  noInvocations?: true
 }

package/src/verify/simulate.ts

@@ -37,6 +37,7 @@ import type {
   RecordedTransaction,
   ScVal,
 } from '../types.ts'
+import { MAX_SCVAL_CLONE_DEPTH } from '../types.ts'
 import type { SimulationResult } from './envelope.ts'
 
 const SIMULATOR_VERSION = 'ts-model-1.0.0'
@@ -227,13 +228,31 @@ function buildPermitContext(
   return ctx
 }
 
-function cloneScVal(value: ScVal): ScVal {
+function cloneScVal(value: ScVal, depth = 0): ScVal {
+  // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+  // payload cannot RangeError the JS stack during context building. Over-depth
+  // throws a ToolError-shaped error that the simulator's existing try/catch
+  // converts to a structured `{ok:false, error}` (not a thrown RangeError).
   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: ScVal): never {
+  const err = new Error(
+    `ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`
+  ) as Error & { code: string; severity: string; retryable: boolean; depthContext: unknown }
+  err.code = 'SIMULATION_ERROR'
+  err.severity = 'error'
+  err.retryable = false
+  err.depthContext = value.type
+  throw err
+}
+
 function visitOracleLeaves(
   node: PredicateNode,
   visit: (asset: string, op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte', bound: bigint) => void

package/src/verify/verify.ts

@@ -32,6 +32,7 @@ import type { ToolError, ToolResponse } from '../errors.ts'
 import type { EvalContext } from '../synth/evaluate.ts'
 import { minimize } from '../synth/minimize.ts'
 import type { ContractInvocation, PredicateNode, RecordedTransaction, ScVal } from '../types.ts'
+import { MAX_SCVAL_CLONE_DEPTH } from '../types.ts'
 
 /** Options for `verifyPolicy`. Mirrors the orchestrator's permit-context
  *  knobs (expiry; oracle fixture) so verify sees the same shape
@@ -171,13 +172,31 @@ function buildPermitContextForVerify(
   return ctx
 }
 
-function cloneScVal(value: ScVal): ScVal {
+function cloneScVal(value: ScVal, depth = 0): ScVal {
+  // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+  // payload cannot RangeError the JS stack during context building. Over-depth
+  // throws a ToolError-shaped error that the verifier's existing try/catch
+  // converts to a structured `{ok:false, error}` (not a thrown RangeError).
   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: ScVal): never {
+  const err = new Error(
+    `ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`
+  ) as Error & { code: string; severity: string; retryable: boolean; depthContext: unknown }
+  err.code = 'VERIFICATION_FAILED'
+  err.severity = 'error'
+  err.retryable = false
+  err.depthContext = value.type
+  throw err
+}
+
 function fingerprint(node: PredicateNode): string {
   return JSON.stringify(node, replacer)
 }