@crediolabs/policy-synth 0.1.3 → 0.1.5

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

@@ -1,33 +1,117 @@
 // src/synth/synthesize-from-recording.ts - recording-path orchestrator.
 //
 // `synthesizeFromRecording` is the second Synthesizer front-end: it INFERS a
-// bounded policy from a `RecordedTransaction` via the same `PolicyIR` +
-// `createOzAdapter` pair used by the deterministic Mandate path. The flow:
+// bounded policy from a `RecordedTransaction` via the same `PolicyIR` + adapter
+// pair used by the deterministic Mandate path. The flow:
 //
 //   1. parseConfidence gate - refuse when `overall < threshold` (default 1.0;
 //      the caller may relax via `confidenceOverride.threshold`).
 //   2. `lower(tx)` -> IntentFacts.
 //   3. `decideScope(facts)` -> scope | SCOPE_UNRESOLVED ToolError.
-//   4. `composeFromRecording(facts, scope, opts)` -> PolicyIR + ambiguities.
+//   4. `composeFromRecording(facts, scope, opts)` -> { ir (OZ-shape),
+//      interpreterIr (predicate-shape), ambiguities, warnings }.
 //   5. `ozAdapter.compile(ir)` -> CompileResult.
-//   6. Assemble ProposedPolicy carrying parseConfidence (from tx), warnings
-//      (the OZ `uncovered` markers, prefixed), and ambiguities
-//      (DURATION_UNSPECIFIED etc.).
+//   6. If `interpreterIr.rules[0].constraints.length > 0` AND the caller
+//      opted in to the interpreter adapter:
+//        a. Run `interpreterAdapter.compile(interpreterIr)`.
+//        b. Throw -> SYNTHESIS_ERROR carrying the gate code
+//           (SCOPE_SELF_CALL, ORACLE_LEAF_INVALID_POSITION,
+//           ORACLE_PARAMS_OUT_OF_RANGE). Never install an OZ-only partial
+//           policy - a warning can be ignored and yields an over-broad rule.
+//        c. `covered === false` -> SYNTHESIS_ERROR carrying the uncovered
+//           descriptor (the user asked for the interpreter to enforce these
+//           constraints; refusing them silently is the audit failure mode).
+//        d. `covered === true` -> merge its PolicyDocument + PolicyRef into
+//           the OZ-shaped ProposedPolicy; the merged `contextRule.policies`
+//           is `[interpreterRef?, ...oz_builtinRefs]` and must satisfy
+//           `OZ_LIMITS.maxPoliciesPerRule` (= 5).
+//   7. Assemble ProposedPolicy carrying parseConfidence (from tx), warnings
+//      (the OZ `uncovered` markers, prefixed), and ambiguities.
 //
 // Determinism: same (tx, opts, ozConfig) -> byte-identical ProposedPolicy.
 // No randomness, no clock, no globals.
+import { createInterpreterAdapter, lowerRuleToPredicate, PLACEHOLDER_INTERPRETER_ADDRESS, } from "../adapters/interpreter/adapter.js";
 import { createOzAdapter } from "../adapters/oz/adapter.js";
-import { SOROBAN_LIMITS, } from "../types.js";
+import { encodePredicate } from "../predicate/encode.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";
+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) {
@@ -68,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: {
@@ -85,12 +166,13 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
     const topLevel = tx.invocations[0] ?? null;
     const composeOpts = {
         network: opts.network,
+        interpreterEnabled: opts.interpreter !== undefined,
         ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
     };
     const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts);
-    // 5. OZ compile.
-    const adapter = createOzAdapter(ozConfig);
-    const compileRes = adapter.compile(composed.ir);
+    // 5. OZ compile (always runs).
+    const ozAdapter = createOzAdapter(ozConfig);
+    const compileRes = ozAdapter.compile(composed.ir);
     if (!compileRes.proposed) {
         return {
             ok: false,
@@ -103,21 +185,271 @@ export function synthesizeFromRecording(tx, opts, ozConfig) {
             },
         };
     }
-    // 6. assemble ProposedPolicy.
+    // 6. Interpreter compile (opt-in; fail-closed when the user routed real
+    //    restrictions to the interpreter).
+    const interpreterOpts = opts.interpreter;
+    let interpreterPolicyDocument = null;
+    let interpreterPolicyRef = null;
+    if (interpreterOpts) {
+        const interpreterConfig = {
+            network: opts.network,
+            installNonce: interpreterOpts.installNonce ?? 1,
+            smartAccountAddress: interpreterOpts.smartAccountAddress,
+            ...(interpreterOpts.oracleParams ? { oracleParams: interpreterOpts.oracleParams } : {}),
+        };
+        let startingPredicate = null;
+        const testSeam = interpreterOpts.__testPredicateNode;
+        if (testSeam !== undefined) {
+            startingPredicate = testSeam;
+        }
+        else {
+            const interpreterAdapter = createInterpreterAdapter(interpreterConfig);
+            let interpreterRes;
+            try {
+                interpreterRes = interpreterAdapter.compile(composed.interpreterIr);
+            }
+            catch (e) {
+                const code = e.code;
+                const allowedCodes = [
+                    'SCOPE_SELF_CALL',
+                    'ORACLE_LEAF_INVALID_POSITION',
+                    'ORACLE_PARAMS_OUT_OF_RANGE',
+                    'MALFORMED_PREDICATE',
+                    'PREDICATE_TOO_LARGE',
+                    'PREDICATE_TOO_DEEP',
+                    'TOO_MANY_LEAVES',
+                    'IN_OPERAND_LIMIT',
+                    'PREDICATE_ORACLE_OVER_LIMIT',
+                ];
+                const surfacedCode = code && allowedCodes.includes(code) ? code : 'SYNTHESIS_ERROR';
+                return {
+                    ok: false,
+                    error: {
+                        code: surfacedCode,
+                        message: `interpreter predicate could not be compiled: ${e.message}`,
+                        severity: 'error',
+                        retryable: false,
+                    },
+                };
+            }
+            if (!interpreterRes.covered) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'SYNTHESIS_ERROR',
+                        message: `interpreter predicate is not fully covered: ${interpreterRes.uncovered.join('; ')}`,
+                        severity: 'error',
+                        retryable: false,
+                        details: { uncovered: interpreterRes.uncovered },
+                    },
+                };
+            }
+            if (!interpreterRes.proposed) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'SYNTHESIS_ERROR',
+                        message: 'interpreter adapter returned no installable policy',
+                        severity: 'error',
+                        retryable: false,
+                    },
+                };
+            }
+            interpreterPolicyDocument = interpreterRes.proposed.policyDocuments[0] ?? null;
+            interpreterPolicyRef = interpreterRes.proposed.policyRefs[0] ?? null;
+            if (!interpreterPolicyDocument || !interpreterPolicyRef) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'SYNTHESIS_ERROR',
+                        message: 'interpreter adapter returned a policy missing the document or ref',
+                        severity: 'error',
+                        retryable: false,
+                    },
+                };
+            }
+            const firstInterpreterRule = composed.interpreterIr.rules[0];
+            if (!firstInterpreterRule) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'SYNTHESIS_ERROR',
+                        message: 'interpreter IR has no rules to lower',
+                        severity: 'error',
+                        retryable: false,
+                    },
+                };
+            }
+            startingPredicate = lowerRuleToPredicate(firstInterpreterRule, interpreterConfig);
+        }
+        if (!startingPredicate) {
+            return {
+                ok: false,
+                error: {
+                    code: 'SYNTHESIS_ERROR',
+                    message: 'interpreter predicate was not derived',
+                    severity: 'error',
+                    retryable: false,
+                },
+            };
+        }
+        // 6b. Self-verify + minimise.
+        if (!topLevel) {
+            return {
+                ok: false,
+                error: {
+                    code: 'SYNTHESIS_ERROR',
+                    message: 'self-verify requires a recorded top-level invocation',
+                    severity: 'error',
+                    retryable: false,
+                },
+            };
+        }
+        if (scope.kind !== 'call_contract') {
+            return {
+                ok: false,
+                error: {
+                    code: 'SYNTHESIS_ERROR',
+                    message: 'self-verify requires a call_contract scope',
+                    severity: 'error',
+                    retryable: false,
+                },
+            };
+        }
+        const permitCtx = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate);
+        const finalPredicate = startingPredicate.op === 'and' ? minimize(startingPredicate, permitCtx) : startingPredicate;
+        const harnessCases = generateCases(finalPredicate, permitCtx);
+        const harnessResult = runHarness(finalPredicate, harnessCases);
+        if (!harnessResult.ok) {
+            return {
+                ok: false,
+                error: {
+                    code: 'DENY_CASE_FAILURE',
+                    message: `self-verify harness failed for the interpreter predicate (${harnessResult.failures.length} failure(s))`,
+                    severity: 'error',
+                    retryable: false,
+                    details: { failures: harnessResult.failures },
+                },
+            };
+        }
+        const evalResult = evaluate(finalPredicate, permitCtx);
+        if (!evalResult.permit) {
+            return {
+                ok: false,
+                error: {
+                    code: 'DENY_CASE_FAILURE',
+                    message: `intended recorded call was denied by the interpreter predicate: ${evalResult.reason}`,
+                    severity: 'error',
+                    retryable: false,
+                    details: { reason: evalResult.reason },
+                },
+            };
+        }
+        // 6c. Re-encode the (possibly minimised) PredicateNode and stamp the
+        //     canonical bytes back onto the PolicyDocument + PolicyRef. The
+        //     `encodePredicate` helper throws ToolError-shaped errors on cap
+        //     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) {
+            interpreterPolicyDocument = {
+                grammarVersion: 1,
+                installNonce: interpreterOpts.installNonce ?? 1,
+                encodedPredicate,
+                predicateHash,
+                ...(interpreterOpts.oracleParams ? { oracleParams: interpreterOpts.oracleParams } : {}),
+            };
+            interpreterPolicyRef = {
+                kind: 'interpreter',
+                interpreterAddress: PLACEHOLDER_INTERPRETER_ADDRESS,
+                predicateBlobBase64: encodedPredicate,
+            };
+        }
+        else {
+            if (!interpreterPolicyDocument || !interpreterPolicyRef) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'SYNTHESIS_ERROR',
+                        message: 'interpreter policy document or ref was lost before re-encode',
+                        severity: 'error',
+                        retryable: false,
+                    },
+                };
+            }
+            interpreterPolicyDocument = {
+                ...interpreterPolicyDocument,
+                encodedPredicate,
+                predicateHash,
+            };
+            if (interpreterPolicyRef.kind === 'interpreter') {
+                interpreterPolicyRef = {
+                    ...interpreterPolicyRef,
+                    predicateBlobBase64: encodedPredicate,
+                };
+            }
+        }
+    }
+    // When the interpreter succeeds, OZ-side `uncovered` warnings that the
+    // 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.
+    const ozRefs = compileRes.proposed.policyRefs;
+    const mergedRefs = [];
+    if (interpreterPolicyRef)
+        mergedRefs.push(interpreterPolicyRef);
+    for (const r of ozRefs)
+        mergedRefs.push(r);
+    if (mergedRefs.length > OZ_LIMITS.maxPoliciesPerRule) {
+        return {
+            ok: false,
+            error: {
+                code: 'POLICY_CAP_EXCEEDED',
+                message: `merged policy count ${mergedRefs.length} exceeds OZ maxPoliciesPerRule (${OZ_LIMITS.maxPoliciesPerRule})`,
+                severity: 'error',
+                retryable: false,
+            },
+        };
+    }
+    const mergedContextRule = {
+        ...compileRes.proposed.contextRule,
+        policies: mergedRefs,
+    };
     const proposed = {
-        ...compileRes.proposed,
+        contextRule: mergedContextRule,
+        policyDocuments: interpreterPolicyDocument ? [interpreterPolicyDocument] : [],
+        policyRefs: mergedRefs,
         parseConfidence: { ...tx.parseConfidence },
         warnings: [
-            ...compileRes.uncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
+            ...ozUncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
             ...composed.warnings.map((w) => `${UNCOVERED_PREFIX}${w}`),
         ],
         ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
     };
     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
+ *  warnings reflect what is still UN-enforced rather than what OZ alone
+ *  could not do. Match the exact descriptor strings the OZ adapter emits
+ *  (see `src/adapters/oz/adapter.ts#describeCondition` /
+ *  `describeSelector`). */
+const INTERPRETER_COVERED_OZ_PATTERN = /^per-method scoping to|^value allowlist on arg|^exact ordered sequence on arg|^oracle price condition on|^invocation-count window|^spending_limit on token .+ needs a CallContract context scoped to that token/;
 /** Reject non-sane inputs before any policy is synthesized. windowSeconds /
  *  validUntilLedger / invocationLimit must be positive integers; limitAmount a
- *  positive i128 decimal string; network mainnet|testnet. */
+ *  positive i128 decimal string; network mainnet|testnet. When the caller
+ *  opts into the interpreter adapter, `smartAccountAddress` must be a C...
+ *  contract address (the on-chain policy-bound account, NOT the G... source
+ *  account from the recording), `installNonce` must be a positive integer
+ *  (default 1), and `oracleParams` must tighten-only vs the wasm defaults. */
 function validateOptions(opts) {
     if (opts.network !== 'mainnet' && opts.network !== 'testnet') {
         return synthesisError(`network must be 'mainnet' or 'testnet', got: ${String(opts.network)}`);
@@ -144,8 +476,53 @@ function validateOptions(opts) {
             return synthesisError(`limitAmount must be a positive i128 decimal string, got: ${ur.limitAmount}`);
         }
     }
+    if (opts.interpreter) {
+        const sa = opts.interpreter.smartAccountAddress;
+        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;
+        // 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) {
+            const MAX_STALE = 600;
+            const MAX_DEV = 200;
+            if (op.maxStalenessSeconds !== undefined &&
+                (!isPositiveInt(op.maxStalenessSeconds) || op.maxStalenessSeconds > MAX_STALE)) {
+                return synthesisError(`interpreter.oracleParams.maxStalenessSeconds must be a positive integer <= ${MAX_STALE} (tighten-only), got: ${op.maxStalenessSeconds}`);
+            }
+            if (op.maxDeviationBps !== undefined &&
+                (!isPositiveInt(op.maxDeviationBps) || op.maxDeviationBps > MAX_DEV)) {
+                return synthesisError(`interpreter.oracleParams.maxDeviationBps must be a positive integer <= ${MAX_DEV} (tighten-only), got: ${op.maxDeviationBps}`);
+            }
+        }
+    }
     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;
 }
@@ -160,6 +537,12 @@ function isPositiveI128(s) {
         return false;
     }
 }
+/** True when `s` looks like a Stellar C... contract address (strkey). The
+ *  source account from the recording is a G... account; the smart account is
+ *  a separate C... contract. */
+function isContractAddress(s) {
+    return s.startsWith('C') && s.length === 56;
+}
 function synthesisError(message) {
     return { code: 'SYNTHESIS_ERROR', message, severity: 'error', retryable: false };
 }
@@ -176,3 +559,152 @@ function mergeAmbiguities(...lists) {
     }
     return out;
 }
+/** Build the permit `EvalContext` the self-verify harness drives. The shape
+ *  mirrors the intended recorded call (the only call the user actually
+ *  performed) so:
+ *    - `evaluate(predicate, ctx).permit === true` must hold (the predicate
+ *      permits the recorded call it was derived from); a failure surfaces
+ *      as DENY_CASE_FAILURE.
+ *    - `generateCases(predicate, ctx)` produces a deny battery that reflects
+ *      the actual recorded move (real amount, real args, real window start).
+ *  Amounts are summed per-token over all movements of the recorded tx
+ *  (BigInt accumulation; never lossy). The `oraclePriceByAsset` map
+ *  contains a price+timestamp satisfying each `oracle_price` leaf in the
+ *  predicate so the intended call permits under every bound; the harness
+ *  then mutates those entries (stale / missing / deviation / paused) to
+ *  exercise the ORACLE_* deny paths. */
+function buildPermitContext(tx, scope, topLevel, userResponses, predicate) {
+    const amountByToken = {};
+    const totals = new Map();
+    for (const m of tx.tokenMovements) {
+        const current = totals.get(m.token) ?? 0n;
+        totals.set(m.token, current + BigInt(m.amount));
+    }
+    for (const [token, total] of totals) {
+        amountByToken[token] = total.toString();
+    }
+    const oraclePriceByAsset = oracleSatisfyingPrices(predicate, tx.fetchedAt);
+    const ctx = {
+        contract: scope.contract,
+        fn: topLevel.fn,
+        args: topLevel.args.map(cloneScVal),
+        atLedger: tx.ledgerSequence,
+        nowSeconds: tx.fetchedAt,
+        amountByToken,
+        windowSpentByToken: {},
+        invocationCountByWindow: {},
+        oraclePriceByAsset,
+    };
+    if (userResponses?.validUntilLedger !== undefined) {
+        ctx.validUntilLedger = userResponses.validUntilLedger;
+    }
+    return ctx;
+}
+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. 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((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
+ *  fresh-oracle deny case in `generateCases` is the only path that flips
+ *  this map. Negatives are clamped at 0 - oracle prices are non-negative on
+ *  Stellar. */
+function oracleSatisfyingPrices(predicate, nowSeconds) {
+    const out = {};
+    visitOracleLeaves(predicate, (asset, op, bound) => {
+        let price;
+        switch (op) {
+            case 'lt':
+            case 'gt':
+                price = op === 'lt' ? bound - 1n : bound + 1n;
+                break;
+            case 'lte':
+            case 'gte':
+            case 'eq':
+                price = bound;
+                break;
+        }
+        if (price < 0n)
+            price = 0n;
+        out[asset] = { price: price.toString(), timestampSeconds: nowSeconds };
+    });
+    return out;
+}
+function visitOracleLeaves(node, visit) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                visitOracleLeaves(child, visit);
+            return;
+        case 'not':
+            visitOracleLeaves(node.child, visit);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            const leftLeaf = node.left;
+            const rightLeaf = node.right;
+            const leftIsOracle = leftLeaf.kind === 'oracle_price';
+            const rightIsOracle = rightLeaf.kind === 'oracle_price';
+            let oracleAsset;
+            let literal;
+            if (leftIsOracle) {
+                oracleAsset = leftLeaf.asset;
+                literal = oracleLiteralFromLeaf(rightLeaf);
+            }
+            else if (rightIsOracle) {
+                oracleAsset = rightLeaf.asset;
+                literal = oracleLiteralFromLeaf(leftLeaf);
+            }
+            if (oracleAsset === undefined || literal === undefined)
+                return;
+            visit(oracleAsset, node.op, literal);
+            return;
+        }
+        case 'in':
+            // `in` is pure membership; oracle leaves inside haystacks are
+            // forbidden by the position rule, so there's nothing to set up here.
+            return;
+    }
+}
+function oracleLiteralFromLeaf(leaf) {
+    if (leaf.kind !== 'literal_i128')
+        return undefined;
+    try {
+        return BigInt(leaf.value);
+    }
+    catch {
+        return undefined;
+    }
+}