@crediolabs/policy-synth 0.1.2 → 0.1.4

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

@@ -1,27 +1,47 @@
 // 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` Path-B 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 { 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 PATH_B_PREFIX = 'Path B (not covered by OZ built-in primitives): ';
+const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
 /** Synthesize a ProposedPolicy from a recorded transaction. */
 export function synthesizeFromRecording(tx, opts, ozConfig) {
     // 0. validate inputs (fail closed - never synthesize from garbage).
@@ -68,7 +88,7 @@ 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 Path-A flow;
+        // 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 {
@@ -85,12 +105,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 +124,312 @@ 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).
+    //
+    //    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;
+    if (interpreterOpts) {
+        const interpreterConfig = {
+            network: opts.network,
+            installNonce: interpreterOpts.installNonce ?? 1,
+            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) {
+            startingPredicate = testSeam;
+        }
+        else {
+            const interpreterAdapter = createInterpreterAdapter(interpreterConfig);
+            let interpreterRes;
+            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.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. 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.
+        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: {
+                    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);
+        // 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);
+        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. 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.
+        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,
+                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 (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.
+    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.
+    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) => `${PATH_B_PREFIX}${u}`),
-            ...composed.warnings.map((w) => `${PATH_B_PREFIX}${w}`),
+            ...ozUncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
+            ...composed.warnings.map((w) => `${UNCOVERED_PREFIX}${w}`),
         ],
         ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
     };
     return { ok: true, data: proposed };
 }
+/** 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,6 +456,32 @@ 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)}`);
+        }
+        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}`);
+        }
+        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;
 }
 function isPositiveInt(n) {
@@ -160,6 +498,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 +520,133 @@ 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) {
+    // 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.
+    if (value.type === 'vec') {
+        return {
+            type: 'vec',
+            value: value.value.map(cloneScVal),
+        };
+    }
+    return { ...value };
+}
+/** 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;
+    }
+}

package/dist/types.d.ts

@@ -145,7 +145,7 @@ export type PredicateNode = {
 } | {
     op: 'in';
     needle: PredicateLeaf;
-    haystack: PredicateLeaf[];
+    haystack: PredicateLeaf[]; /** set-valued only - the haystack is always sorted by canonical XDR bytes (pure membership). */
 };
 export type PredicateLeaf = {
     kind: 'call_contract';
@@ -160,6 +160,7 @@ export type PredicateLeaf = {
 } | {
     kind: 'window_spent';
     token: string;
+    windowSeconds: number;
 } | {
     kind: 'now';
 } | {
@@ -170,6 +171,27 @@ export type PredicateLeaf = {
 } | {
     kind: 'oracle_price';
     asset: string;
+} | {
+    kind: 'literal_address';
+    value: string;
+} | {
+    kind: 'literal_i128';
+    value: string;
+} | {
+    kind: 'literal_symbol';
+    value: string;
+} | {
+    kind: 'literal_u32';
+    value: number;
+} | {
+    kind: 'literal_u64';
+    value: string;
+} | {
+    kind: 'literal_bytes';
+    value: string;
+} | {
+    kind: 'literal_vec';
+    elements: PredicateLeaf[];
 };
 export interface OZPrimitiveConfig {
     primitive: 'spending_limit' | 'simple_threshold' | 'weighted_threshold';

package/dist/verify/envelope.d.ts

@@ -0,0 +1,15 @@
+export type SimulationResult = {
+    permit: {
+        tx: 'permit';
+    } | {
+        tx: 'deny';
+        reason: string;
+    };
+    evaluatedCases: Array<{
+        dimension: string;
+        outcome: 'permit' | 'deny';
+        reason: string;
+    }>;
+    backend: 'interpreter-v1' | 'ts-model';
+    simulatorVersion: string;
+};

package/dist/verify/envelope.js

@@ -0,0 +1,22 @@
+// src/verify/envelope.ts - the post-simulation result envelope used by
+// review-card rendering and verification.
+//
+// `SimulationResult` is the structured verdict a `simulate_policy` run
+// produces; the review-card builder reads it as one of its inputs (so the
+// rendered card can quote the backend that evaluated the policy) and the
+// verification pipeline reads `permit` + `evaluatedCases` to confirm every
+// generated deny case really did deny.
+//
+// This envelope is intentionally separate from the CustodyAdapter
+// `SimulationResult` in `src/seams/types.ts` (which is the dry-run stub
+// returned by `adapter.simulate(ir, permitTx)`); the seam result is the
+// adapter contract, this envelope is the post-simulation record consumed by
+// downstream rendering + verification.
+//
+// Fields:
+//   - `permit` is the single verdict for the candidate recorded tx.
+//   - `evaluatedCases` is the deny-case battery outcome (every dimension
+//     must report `deny` when the policy is minimal).
+//   - `backend` is the actual evaluator that produced the verdict.
+//   - `simulatorVersion` lets the reviewer / audit log distinguish runs.
+export {};

package/dist/verify/index.d.ts

@@ -0,0 +1,3 @@
+export type { SimulationResult } from './envelope.ts';
+export { type SimulateOptions, simulatePolicy } from './simulate.ts';
+export { type VerifyOptions, verifyPolicy } from './verify.ts';

package/dist/verify/index.js

@@ -0,0 +1,3 @@
+// src/verify/index.ts - re-export the simulation / verification surface.
+export { simulatePolicy } from "./simulate.js";
+export { verifyPolicy } from "./verify.js";