@crediolabs/policy-synth 0.1.4 → 0.1.6

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

@@ -33,21 +33,85 @@
 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 { generateCases, ORIGINAL_DIMENSIONS } from "./deny-cases.js";
 import { evaluate } from "./evaluate.js";
 import { runHarness } from "./harness.js";
 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) {
@@ -62,6 +126,31 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
             },
         };
     }
+    // 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) {
@@ -88,9 +177,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 +212,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 +222,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 +234,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 +318,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,12 +342,10 @@ 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 finalPredicate = startingPredicate.op === 'and'
+            ? minimize(startingPredicate, permitCtx, ORIGINAL_DIMENSIONS)
+            : startingPredicate;
+        const harnessCases = generateCases(finalPredicate, permitCtx, ORIGINAL_DIMENSIONS);
         const harnessResult = runHarness(finalPredicate, harnessCases);
         if (!harnessResult.ok) {
             return {
@@ -324,14 +373,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 +418,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)
@@ -402,12 +446,24 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
         ...compileRes.proposed.contextRule,
         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 = {
         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}`),
         ],
@@ -415,6 +471,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
@@ -453,7 +512,7 @@ function validateOptions(opts) {
             return synthesisError(`invocationLimit must be a positive integer, got: ${ur.invocationLimit}`);
         }
         if (ur.limitAmount !== undefined && !isPositiveI128(ur.limitAmount)) {
-            return synthesisError(`limitAmount must be a positive i128 decimal string, got: ${ur.limitAmount}`);
+            return synthesisError(`limitAmount must be a positive i128 decimal string within [1, ${I128_MAX}] (2^127-1), got: ${ur.limitAmount}`);
         }
     }
     if (opts.interpreter) {
@@ -461,12 +520,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,15 +556,30 @@ 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;
+/** 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) {
     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) {
     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;
@@ -561,18 +648,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

@@ -21,6 +21,17 @@ export type 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;
@@ -42,6 +53,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
@@ -255,7 +283,15 @@ export interface AmbiguityPrompt {
 export type AmbiguityCode = 'DURATION_UNSPECIFIED' | 'AMOUNT_BOUND_MISSING' | 'RECIPIENT_ALLOWLIST_EMPTY' | 'FREQUENCY_BOUND_MISSING' | 'ORACLE_ASSET_UNKNOWN' | 'MULTIPLE_UNRELATED_TARGETS';
 /** 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;
     knownContracts: string[];
@@ -268,4 +304,8 @@ export interface ParseConfidence {
         type: string;
     }>;
     thresholdUsed: number;
+    /** 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/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

package/dist/verify/simulate.js

@@ -28,6 +28,7 @@
 // suite to stay in lockstep.
 import { generateCases } from "../synth/deny-cases.js";
 import { evaluate } from "../synth/evaluate.js";
+import { MAX_SCVAL_CLONE_DEPTH } from "../types.js";
 const SIMULATOR_VERSION = 'ts-model-1.0.0';
 /** Replay a recorded transaction against a proposed predicate and emit the
  *  `SimulationResult` envelope. The simulator returns the SAME permit
@@ -177,12 +178,27 @@ function buildPermitContext(predicate, tx, topLevel, opts) {
     }
     return ctx;
 }
-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 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) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'SIMULATION_ERROR';
+    err.severity = 'error';
+    err.retryable = false;
+    err.depthContext = value.type;
+    throw err;
+}
 function visitOracleLeaves(node, visit) {
     switch (node.op) {
         case 'and':

package/dist/verify/verify.js

@@ -28,6 +28,7 @@
 //
 // Determinism: same `(predicate, permitTx)` -> byte-identical verdict.
 import { minimize } from "../synth/minimize.js";
+import { MAX_SCVAL_CLONE_DEPTH } from "../types.js";
 /** Run the static minimality check on a proposed predicate + recorded tx.
  *  Returns `{ ok: true }` when the predicate is minimal (every top-level
  *  conjunct carries load) and `VERIFICATION_FAILED` when a conjunct could
@@ -125,12 +126,27 @@ function buildPermitContextForVerify(tx, topLevel, opts) {
     }
     return ctx;
 }
-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 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) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'VERIFICATION_FAILED';
+    err.severity = 'error';
+    err.retryable = false;
+    err.depthContext = value.type;
+    throw err;
+}
 function fingerprint(node) {
     return JSON.stringify(node, replacer);
 }

package/dist-cjs/adapters/interpreter/adapter.d.ts

@@ -0,0 +1,38 @@
+import type { IRPolicyRule } from '../../ir/types.ts';
+import type { CustodyAdapter } from '../../seams/types.ts';
+import type { Network, PredicateNode } from '../../types.ts';
+/** [VERIFY] NOT a real deployed address. The interpreter is a per-network
+ *  deploy artifact we do not have yet; install is a later phase. */
+export declare const PLACEHOLDER_INTERPRETER_ADDRESS = "VERIFY-interpreter-address";
+/** Wasm-level oracle defaults (mirrors INTERPRETER_INSTALL_PARAMS.md OracleParams).
+ *  Per-policy overrides may TIGHTEN only - they may never exceed these. */
+export declare const ORACLE_DEFAULTS: {
+    readonly maxStalenessSeconds: 600;
+    readonly maxDeviationBps: 200;
+};
+export interface InterpreterAdapterConfig {
+    network: Network;
+    /** Per-rule install nonce (first install = 1; replay-protected). */
+    installNonce: number;
+    /** The smart account this interpreter policy will be installed against. Used
+     *  by the self-call gate: any `in`-allowlist containing this address is
+     *  rejected as `SCOPE_SELF_CALL`. */
+    smartAccountAddress: string;
+    /** Optional per-policy oracle overrides. Must TIGHTEN vs ORACLE_DEFAULTS
+     *  (i.e. <= each default). A widening value throws ORACLE_PARAMS_OUT_OF_RANGE
+     *  at compile time. */
+    oracleParams?: {
+        maxStalenessSeconds?: number;
+        maxDeviationBps?: number;
+    };
+}
+export declare function createInterpreterAdapter(config: InterpreterAdapterConfig): CustodyAdapter;
+/** Lower a single IR rule to the canonical pre-encoding `PredicateNode`. The
+ *  orchestrator uses this to wire the self-verify + minimise pipeline: after
+ *  `compile(ir)` succeeds (`covered === true`, `proposed` set), the
+ *  orchestrator re-derives the PredicateNode via this helper to drive
+ *  `minimize` and `runHarness` on the SAME shape the encoder saw. Pure and
+ *  deterministic: same `rule + config` -> byte-identical PredicateNode. The
+ *  `uncovered` list the adapter surfaces during compile is NOT re-derived
+ *  here; callers that need it should use the result of `compile(ir)`. */
+export declare function lowerRuleToPredicate(rule: IRPolicyRule, config: InterpreterAdapterConfig): PredicateNode;