@crediolabs/policy-synth 0.1.2 → 0.1.4

package/dist/review-card/builder.js

@@ -0,0 +1,261 @@
+// src/review-card/builder.ts - deterministic, pure review-card summary
+// builder.
+//
+// `buildReviewCardSummary` renders the per-policy text the user-facing review
+// card quotes. The whole DX win of non-engineer reviewability hinges on the
+// summary being REPRODUCIBLE + TESTABLE + NON-HALLUCINABLE, so this module is
+// pure: same inputs -> byte-identical output, no clock, no randomness, no I/O.
+//
+// The builder walks two inputs and emits ONE constraint string per leaf or
+// primitive, in a fixed deterministic order:
+//
+//   1. The OZ built-in `PolicyRef`s. Each `spending_limit` primitive becomes a
+//      `spending_limit(token, limitAmount, windowSecs)` line; other OZ
+//      primitives (threshold) are skipped - the review card does not quote
+//      them (they are signer-config concerns, not transactional bounds).
+//
+//   2. The interpreter `PredicateNode`. One string per constraint leaf,
+//      rendered by enclosing-comparison kind. Templates (Task 7b):
+//        - invocation_count_in_window <= N    -> Invocations <= N per <window> seconds
+//        - call_arg[i] in [list]              -> Recipient/arg must be one of [list]
+//        - eq(call_arg[i], literal_vec[...])  -> Path must be exactly [list]
+//        - oracle_price(asset) OP price       -> Only when oracle_price(asset) OP price
+//        - call_fn == x                       -> Function must be x
+//        - call_contract == c                 -> Contract must be c
+//        - amount <= v                        -> Amount <= v
+//
+// The content hash is a stable sha256 hex of a canonical JSON of
+// { ruleName, plainEnglish, constraints, expiry, backend } - identical
+// inputs (incl. the context-rule expiry and simulation backend) -> identical
+// hash. There is no clock; the hash never includes a timestamp.
+import { createHash } from 'node:crypto';
+/** Build a deterministic review-card summary from a policy + context rule +
+ *  simulation result. Pure: same inputs -> byte-identical output. */
+export function buildReviewCardSummary(predicate, policyRefs, contextRule, simulation) {
+    const constraints = [];
+    for (const ref of policyRefs) {
+        const line = renderOzPrimitive(ref);
+        if (line !== null)
+            constraints.push(line);
+    }
+    if (predicate !== null) {
+        walkPredicate(predicate, (node) => {
+            const line = renderConstraint(node);
+            if (line !== null)
+                constraints.push(line);
+        });
+    }
+    const ruleName = contextRule.name;
+    const plainEnglish = renderPlainEnglish(ruleName, constraints);
+    const expiry = renderExpiry(contextRule.validUntilLedger);
+    const backend = simulation.backend;
+    const contentHash = computeContentHash({
+        ruleName,
+        plainEnglish,
+        constraints,
+        expiry,
+        backend,
+    });
+    return { ruleName, plainEnglish, constraints, expiry, backend, contentHash };
+}
+/** Render the OZ built-in primitive summary line. Only `spending_limit` is
+ *  quoted by the review card (it is the only primitive that defines a
+ *  transactional bound). Other primitives (threshold) are signer-config
+ *  concerns handled by the OZ adapter's own `uncovered` machinery.
+ *  Spending_limit takes `period_ledgers` on-chain (~5s/ledger); the card
+ *  states the window in seconds so the user reads it consistently with the
+ *  interpreter templates. */
+function renderOzPrimitive(ref) {
+    if (ref.kind !== 'oz_builtin')
+        return null;
+    const primitive = ref.primitive;
+    if (primitive.primitive !== 'spending_limit')
+        return null;
+    const params = primitive.params;
+    const limit = params.spending_limit ?? '0';
+    const periodLedgers = params.period_ledgers ?? 0;
+    const windowSecs = periodLedgers * 5;
+    return `spending_limit(${limit}, ${windowSecs})`;
+}
+/** Walk every comparison / membership node of the predicate and invoke
+ *  `visit` on each. The walk is depth-first, left-to-right, so the
+ *  constraint list is stable across runs. Pure boolean nodes contribute no
+ *  constraint lines themselves; their leaf children do, via the visitor. */
+function walkPredicate(node, visit) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                walkPredicate(child, visit);
+            return;
+        case 'not':
+            walkPredicate(node.child, visit);
+            return;
+        case 'in':
+            visit(node);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            visit(node);
+            return;
+    }
+}
+/** Render ONE constraint sentence for ONE interpreter predicate node. The
+ *  shape of the output is pinned by Task 7b so the test suite can assert
+ *  byte-for-byte equality. Returns `null` when the node is a structural
+ *  boolean (`and` / `or` / `not`) - those are not constraint leaves. */
+function renderConstraint(node) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+        case 'not':
+            return null;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            return renderComparison(node);
+        case 'in':
+            return renderMembership(node);
+    }
+}
+function renderComparison(node) {
+    const left = node.left;
+    const right = node.right;
+    // eq(call_contract, literal_address) -> Contract must be <addr>
+    if (left.kind === 'call_contract' && node.op === 'eq' && right.kind === 'literal_address') {
+        return `Contract must be ${right.value}`;
+    }
+    // eq(call_fn, literal_symbol) -> Function must be <sym>
+    if (left.kind === 'call_fn' && node.op === 'eq' && right.kind === 'literal_symbol') {
+        return `Function must be ${right.value}`;
+    }
+    // eq(call_arg[i], literal_vec) -> Path must be exactly [list]
+    if (left.kind === 'call_arg' && node.op === 'eq' && right.kind === 'literal_vec') {
+        return `Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`;
+    }
+    // invocation_count_in_window <= N -> Invocations <= N per <window> seconds
+    if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
+        return `Invocations <= ${right.value} per ${left.windowSecs} seconds`;
+    }
+    // amount <= v -> Amount <= v
+    if (left.kind === 'amount' && right.kind === 'literal_i128') {
+        return `Amount <= ${right.value}`;
+    }
+    // oracle_price(asset) OP price -> Only when oracle_price(asset) OP price
+    if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
+        return `Only when oracle_price(${left.asset}) ${comparisonOpText(node.op)} ${right.value}`;
+    }
+    // Any other comparison shape is a structural fail-closed: do not surface
+    // a misleading line. Cross-check still requires every leaf produce a
+    // constraint string; the only leaves we emit lines for are the ones we
+    // recognise above, so the test fixtures cover exactly the supported
+    // shapes.
+    return null;
+}
+function renderMembership(node) {
+    // call_arg[i] in [list] -> Recipient/arg must be one of [list]
+    if (node.needle.kind === 'call_arg') {
+        const list = node.haystack.map(renderHaystackElement).join(', ');
+        return `Recipient/arg must be one of [${list}]`;
+    }
+    return null;
+}
+function renderVecElement(leaf) {
+    switch (leaf.kind) {
+        case 'literal_address':
+            return leaf.value;
+        case 'literal_i128':
+            return leaf.value;
+        case 'literal_symbol':
+            return leaf.value;
+        case 'literal_u32':
+            return String(leaf.value);
+        case 'literal_u64':
+            return leaf.value;
+        case 'literal_bytes':
+            return leaf.value;
+        case 'literal_vec':
+            return `[${leaf.elements.map(renderVecElement).join(', ')}]`;
+        case 'call_contract':
+        case 'call_fn':
+        case 'call_arg':
+        case 'amount':
+        case 'window_spent':
+        case 'now':
+        case 'valid_until':
+        case 'invocation_count_in_window':
+        case 'oracle_price':
+            return `<${leaf.kind}>`;
+    }
+}
+function renderHaystackElement(leaf) {
+    if (leaf.kind === 'literal_address')
+        return leaf.value;
+    if (leaf.kind === 'literal_i128')
+        return leaf.value;
+    if (leaf.kind === 'literal_symbol')
+        return leaf.value;
+    if (leaf.kind === 'literal_u32')
+        return String(leaf.value);
+    if (leaf.kind === 'literal_u64')
+        return leaf.value;
+    if (leaf.kind === 'literal_bytes')
+        return leaf.value;
+    if (leaf.kind === 'literal_vec') {
+        return `[${leaf.elements.map(renderHaystackElement).join(', ')}]`;
+    }
+    return `<${leaf.kind}>`;
+}
+function comparisonOpText(op) {
+    switch (op) {
+        case 'lt':
+            return '<';
+        case 'lte':
+            return '<=';
+        case 'gt':
+            return '>';
+        case 'gte':
+            return '>=';
+        case 'eq':
+            return '==';
+    }
+}
+/** Render the plain-English one-liner. Format: `<ruleName>: <constraints>`,
+ *  joined by `; ` so the user reads one sentence per constraint. */
+function renderPlainEnglish(ruleName, constraints) {
+    if (constraints.length === 0)
+        return `${ruleName}: (no constraints)`;
+    return `${ruleName}: ${constraints.join('; ')}`;
+}
+/** Render the expiry line. `null` -> "No expiry"; a ledger sequence -> the
+ *  ledger number so the user reads it in the same units the OZ context rule
+ *  applies it. */
+function renderExpiry(validUntilLedger) {
+    if (validUntilLedger === null)
+        return 'No expiry';
+    return `Valid until ledger ${validUntilLedger}`;
+}
+function computeContentHash(input) {
+    return createHash('sha256').update(canonicalStringify(input)).digest('hex');
+}
+/** Canonical JSON with recursively sorted object keys (stable across runs). */
+function canonicalStringify(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortKeys(value[key]);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/review-card/conflict.d.ts

@@ -0,0 +1,40 @@
+/** Minimal rule reference the classifier needs to compute the conflict kind.
+ *  Carries the rule id (used in the annotation), the scope (contract +
+ *  method), and an optional spending cap. The cap captures both the
+ *  amount and the window so the classifier can compare apples to apples. */
+export interface RuleRef {
+    id: string;
+    scope: {
+        contract?: string;
+        method?: string;
+    };
+    /** When set, the rule enforces this per-window spend cap (token +
+     *  decimal-string amount + seconds window). */
+    spendingLimit?: {
+        token: string;
+        amount: string;
+        windowSeconds: number;
+    };
+}
+/** Structured annotation a single new-vs-existing rule comparison yields.
+ *  Four mutually exclusive kinds; the union is exhaustive (the classifier
+ *  never throws). */
+export type ConflictAnnotation = {
+    kind: 'subsume';
+    existingRuleId: string;
+    detail: string;
+} | {
+    kind: 'disjoint';
+} | {
+    kind: 'counter_permissive';
+    existingRuleId: string;
+    newLimit: string;
+    existingLimit: string;
+} | {
+    kind: 'window_divergent';
+    existingRuleId: string;
+    effectiveUnion: string;
+};
+/** Classify the relationship between a new rule and one existing rule.
+ *  Pure: same pair -> same annotation. */
+export declare function classifyConflict(newRule: RuleRef, existingRule: RuleRef): ConflictAnnotation;

package/dist/review-card/conflict.js

@@ -0,0 +1,111 @@
+// src/review-card/conflict.ts - the ConflictAnnotation 4-kind enum + the
+// `classifyConflict` classifier.
+//
+// When a user installs a new policy alongside an existing rule set, the
+// review card surfaces the relationship between the new rule and each
+// existing rule as a structured annotation. A boolean (conflict / no
+// conflict) is wrong: four qualitatively different shapes are possible, and
+// each one tells the user something different about what would happen if
+// both rules installed together.
+//
+//   - subsume            new rule's scope is a SUPERSET of an existing
+//                        rule's. The new rule is broader; installing it on
+//                        top of the existing rule weakens the existing
+//                        restriction. The existing rule becomes a no-op.
+//   - disjoint           new rule and existing rule are unrelated: their
+//                        scopes do not overlap. Safe to install both.
+//   - counter_permissive new rule and existing rule allow CONFLICTING
+//                        things at the same scope (one caps lower than the
+//                        other on the same axis). The stricter one wins
+//                        at evaluate; the looser is dead weight.
+//   - window_divergent   new rule and existing rule have the same scope
+//                        and the same per-window limit but DIFFERENT
+//                        rolling windows. Effective union = sum (the user
+//                        can spend `limit` per each window, independently).
+//
+// The classifier consumes a minimal `RuleRef` shape: the rule id, scope
+// (contract + method), and an optional spending limit + window. Shapes
+// without a limit fall back to scope-only classification.
+/** Classify the relationship between a new rule and one existing rule.
+ *  Pure: same pair -> same annotation. */
+export function classifyConflict(newRule, existingRule) {
+    // --- step 1: subsume? (new.scope ⊋ existing.scope) ---
+    //
+    // Subsume requires existing to be fully scoped (both contract AND method
+    // pinned) AND new to be at least partially broader than existing. A new
+    // rule with identical scope to existing is NOT a superset - it is the
+    // same rule and falls through to the same-scope branch below. If existing
+    // is "any contract" / "any method" then it is the wildest rule in the
+    // rule set; a new rule covering it is just a duplicate, not a subsume -
+    // fall through to disjoint.
+    const existingHasContract = existingRule.scope.contract !== undefined;
+    const existingHasMethod = existingRule.scope.method !== undefined;
+    const newIsBroaderOnContract = newRule.scope.contract === undefined && existingHasContract;
+    const newIsBroaderOnMethod = newRule.scope.method === undefined && existingHasMethod;
+    const newMatchesOnContract = newRule.scope.contract === undefined ||
+        (existingHasContract && newRule.scope.contract === existingRule.scope.contract);
+    const newMatchesOnMethod = newRule.scope.method === undefined ||
+        (existingHasMethod && newRule.scope.method === existingRule.scope.method);
+    if (existingHasContract &&
+        existingHasMethod &&
+        newMatchesOnContract &&
+        newMatchesOnMethod &&
+        (newIsBroaderOnContract || newIsBroaderOnMethod)) {
+        return {
+            kind: 'subsume',
+            existingRuleId: existingRule.id,
+            detail: `new rule scope (${describeScope(newRule)}) is a superset of existing rule (${describeScope(existingRule)})`,
+        };
+    }
+    // --- step 2: disjoint by scope? ---
+    if (existingHasContract && newRule.scope.contract !== undefined) {
+        if (newRule.scope.contract !== existingRule.scope.contract) {
+            return { kind: 'disjoint' };
+        }
+    }
+    if (existingHasMethod &&
+        newRule.scope.method !== undefined &&
+        newRule.scope.method !== existingRule.scope.method) {
+        return { kind: 'disjoint' };
+    }
+    // --- step 3: same scope -> compare spend caps (when both sides carry them) ---
+    if (newRule.spendingLimit && existingRule.spendingLimit) {
+        const a = newRule.spendingLimit;
+        const b = existingRule.spendingLimit;
+        if (a.token !== b.token) {
+            // Same scope, different tokens: each binds a different axis. They
+            // do not counter each other; treat as disjoint.
+            return { kind: 'disjoint' };
+        }
+        if (a.windowSeconds === b.windowSeconds) {
+            // Same scope, same token, same window: counter-permissive when the
+            // amounts disagree (the stricter wins at evaluate; the looser is
+            // dead weight). Equal amounts -> duplicate rule, treat as disjoint.
+            if (a.amount === b.amount) {
+                return { kind: 'disjoint' };
+            }
+            return {
+                kind: 'counter_permissive',
+                existingRuleId: existingRule.id,
+                newLimit: `${a.amount} ${a.token} / ${a.windowSeconds}s`,
+                existingLimit: `${b.amount} ${b.token} / ${b.windowSeconds}s`,
+            };
+        }
+        // Same scope + token, different windows: effective union is the sum
+        // of the two per-window caps (each window ticks independently).
+        const union = (BigInt(a.amount) + BigInt(b.amount)).toString();
+        return {
+            kind: 'window_divergent',
+            existingRuleId: existingRule.id,
+            effectiveUnion: `${union} ${a.token} per ${a.windowSeconds}s (new) + ${b.windowSeconds}s (existing)`,
+        };
+    }
+    // Same scope without comparable spend caps on both sides -> disjoint.
+    return { kind: 'disjoint' };
+}
+function describeScope(rule) {
+    const parts = [];
+    parts.push(rule.scope.contract ? `contract=${rule.scope.contract}` : 'contract=*');
+    parts.push(rule.scope.method ? `method=${rule.scope.method}` : 'method=*');
+    return parts.join(', ');
+}

package/dist/review-card/cross-check.d.ts

@@ -0,0 +1,11 @@
+import type { PredicateNode } from '../types.ts';
+import type { ReviewCardSummary } from './builder.ts';
+/** Assert every leaf in the predicate appears as a constraint string in
+ *  `summary.constraints`. Returns the missing templates (without the leaf
+ *  values filled in) when any leaf was dropped. */
+export declare function summaryCrossCheck(predicate: PredicateNode | null, summary: ReviewCardSummary): {
+    ok: true;
+} | {
+    ok: false;
+    missingConstraints: string[];
+};

package/dist/review-card/cross-check.js

@@ -0,0 +1,148 @@
+// src/review-card/cross-check.ts - the non-hallucination guard.
+//
+// `summaryCrossCheck` walks EVERY leaf of the predicate and asserts the
+// review-card summary quoted a constraint string for it. Returns
+// `{ ok: false, missingConstraints }` if any leaf was dropped (or rendered
+// into a template shape the cross-check does not recognise). A
+// `PredicateNode = null` is always ok - the policy is OZ-only and the
+// interpreter predicate did not exist.
+//
+// The guard is structural: every leaf the builder is supposed to render has
+// exactly one template shape. The cross-check enumerates those shapes and
+// demands the summary carries the corresponding string. A naive summary
+// that drops a leaf (or fabricates a string not in the predicate) trips the
+// guard.
+/** Assert every leaf in the predicate appears as a constraint string in
+ *  `summary.constraints`. Returns the missing templates (without the leaf
+ *  values filled in) when any leaf was dropped. */
+export function summaryCrossCheck(predicate, summary) {
+    if (predicate === null)
+        return { ok: true };
+    const expected = [];
+    collect(predicate, expected);
+    if (expected.length === 0)
+        return { ok: true };
+    const present = new Set(summary.constraints);
+    const missing = expected.filter((s) => !present.has(s));
+    if (missing.length === 0)
+        return { ok: true };
+    return { ok: false, missingConstraints: missing };
+}
+/** Walk the predicate and emit the EXACT constraint string the builder is
+ *  expected to produce for each leaf, in walk order. Strings here MUST
+ *  match the templates in `builder.ts` byte-for-byte; the cross-check is
+ *  the structural claim that "every supported leaf shape is rendered". */
+function collect(node, out) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                collect(child, out);
+            return;
+        case 'not':
+            collect(node.child, out);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            pushComparison(node.left, node.right, node.op, out);
+            return;
+        case 'in':
+            pushMembership(node.needle, node.haystack, out);
+            return;
+    }
+}
+function pushComparison(left, right, op, out) {
+    if (left.kind === 'call_contract' && op === 'eq' && right.kind === 'literal_address') {
+        out.push(`Contract must be ${right.value}`);
+        return;
+    }
+    if (left.kind === 'call_fn' && op === 'eq' && right.kind === 'literal_symbol') {
+        out.push(`Function must be ${right.value}`);
+        return;
+    }
+    if (left.kind === 'call_arg' && op === 'eq' && right.kind === 'literal_vec') {
+        out.push(`Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`);
+        return;
+    }
+    if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
+        out.push(`Invocations <= ${right.value} per ${left.windowSecs} seconds`);
+        return;
+    }
+    if (left.kind === 'amount' && right.kind === 'literal_i128') {
+        out.push(`Amount <= ${right.value}`);
+        return;
+    }
+    if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
+        out.push(`Only when oracle_price(${left.asset}) ${comparisonOpText(op)} ${right.value}`);
+        return;
+    }
+}
+function pushMembership(needle, haystack, out) {
+    if (needle.kind !== 'call_arg')
+        return;
+    const list = haystack.map(renderHaystackElement).join(', ');
+    out.push(`Recipient/arg must be one of [${list}]`);
+}
+function renderVecElement(leaf) {
+    switch (leaf.kind) {
+        case 'literal_address':
+            return leaf.value;
+        case 'literal_i128':
+            return leaf.value;
+        case 'literal_symbol':
+            return leaf.value;
+        case 'literal_u32':
+            return String(leaf.value);
+        case 'literal_u64':
+            return leaf.value;
+        case 'literal_bytes':
+            return leaf.value;
+        case 'literal_vec':
+            return `[${leaf.elements.map(renderVecElement).join(', ')}]`;
+        case 'call_contract':
+        case 'call_fn':
+        case 'call_arg':
+        case 'amount':
+        case 'window_spent':
+        case 'now':
+        case 'valid_until':
+        case 'invocation_count_in_window':
+        case 'oracle_price':
+            return `<${leaf.kind}>`;
+    }
+}
+function renderHaystackElement(leaf) {
+    if (leaf.kind === 'literal_address')
+        return leaf.value;
+    if (leaf.kind === 'literal_i128')
+        return leaf.value;
+    if (leaf.kind === 'literal_symbol')
+        return leaf.value;
+    if (leaf.kind === 'literal_u32')
+        return String(leaf.value);
+    if (leaf.kind === 'literal_u64')
+        return leaf.value;
+    if (leaf.kind === 'literal_bytes')
+        return leaf.value;
+    if (leaf.kind === 'literal_vec') {
+        return `[${leaf.elements.map(renderHaystackElement).join(', ')}]`;
+    }
+    return `<${leaf.kind}>`;
+}
+function comparisonOpText(op) {
+    switch (op) {
+        case 'lt':
+            return '<';
+        case 'lte':
+            return '<=';
+        case 'gt':
+            return '>';
+        case 'gte':
+            return '>=';
+        case 'eq':
+            return '==';
+    }
+}

package/dist/review-card/index.d.ts

@@ -0,0 +1,3 @@
+export { buildReviewCardSummary, type ReviewCardSummary, } from './builder.ts';
+export { type ConflictAnnotation, classifyConflict, type RuleRef, } from './conflict.ts';
+export { summaryCrossCheck } from './cross-check.ts';

package/dist/review-card/index.js

@@ -0,0 +1,4 @@
+// src/review-card/index.ts - re-export the deterministic review-card surface.
+export { buildReviewCardSummary, } from "./builder.js";
+export { classifyConflict, } from "./conflict.js";
+export { summaryCrossCheck } from "./cross-check.js";

package/dist/seams/types.d.ts

@@ -36,7 +36,7 @@ export interface CustodyCapabilities {
 export interface CompileResult {
     /** false => some IR construct this backend cannot express (see `uncovered`). */
     covered: boolean;
-    /** Human-readable list of unsupported constructs (the Path-B markers). */
+    /** Human-readable list of unsupported constructs. */
     uncovered: string[];
     /** The backend-native installable policy, assembled when a rule lowered. */
     proposed?: ProposedPolicy;

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

@@ -1,6 +1,14 @@
-import type { PolicyIR } from '../ir/types.ts';
+import type { IRCompOp, PolicyIR } from '../ir/types.ts';
 import type { AmbiguityPrompt, ContractInvocation, Network } from '../types.ts';
 import type { IntentFacts } from './lower.ts';
+/** Per-asset oracle-price bound supplied by the caller (e.g. swap allowed only
+ *  if oracle_price(XLM) < 5.00 USDC). One entry per asset; the recorder never
+ *  fabricates a price bound from a slippage value (different units). */
+export interface OraclePriceBound {
+    asset: string;
+    operator: IRCompOp;
+    value: string;
+}
 /** Caller-supplied answers to the ambiguity prompts. Every numeric bound the
  *  synth might apply must come from here - the recording supplies observed
  *  amounts (offered only as suggestions), never authorised ceilings. */
@@ -15,22 +23,42 @@ export interface ComposeUserResponses {
     /** Max invocations per window for an incoming-only flow. Required to emit an
      *  invocation_count bound; absent -> FREQUENCY_BOUND_MISSING. */
     invocationLimit?: number;
+    /** Per-asset oracle-price bound(s). Each entry lowers to a single
+     *  `oracle_price(asset) OP value` compare in the interpreter IR. Multiple
+     *  entries on the same asset emit multiple leaves. */
+    oraclePriceBound?: OraclePriceBound[];
+    /** Recipient allowlist for a swap (call_arg[3] on SoroSwap's
+     *  swap_exact_tokens_for_tokens). Absent -> RECIPIENT_ALLOWLIST_EMPTY
+     *  ambiguity (the caller is prompted; proceeding without an allowlist leaves
+     *  the recipient unconstrained). */
+    swapRecipientAllowlist?: string[];
 }
 /** Composition options. */
 export interface ComposeOptions {
     network: Network;
     userResponses?: ComposeUserResponses;
+    /** When true, constraints the OZ adapter cannot lower are routed to
+     *  `interpreterIr` (the predicate-shape IR) so the orchestrator can compile
+     *  them via the interpreter adapter. When false (the default for callers
+     *  who have not opted in), every constraint goes to `ir` and the OZ
+     *  adapter's `uncovered` machinery generates the descriptive warnings -
+     *  today's behaviour. The orchestrator passes this flag through based on
+     *  whether `opts.interpreter` was supplied. */
+    interpreterEnabled?: boolean;
 }
-/** Result of composition: the PolicyIR, any ambiguities surfaced during
- *  inference, and descriptive Path-B warnings for needs that are NOT expressed
- *  as an IR node (so no fabricated constraint is emitted). The orchestrator
- *  carries ambiguities into `ProposedPolicy.ambiguities` and merges warnings
- *  into `ProposedPolicy.warnings`. */
+/** Result of composition: the OZ-shape PolicyIR, the predicate-shape PolicyIR
+ *  (contains the constraints the OZ adapter cannot lower; empty when
+ *  `interpreterEnabled` is false), any ambiguities surfaced during inference,
+ *  and descriptive warnings for needs that are NOT expressed as an IR node
+ *  (so no fabricated constraint is emitted). The orchestrator carries
+ *  ambiguities into `ProposedPolicy.ambiguities` and merges warnings into
+ *  `ProposedPolicy.warnings`. */
 export interface ComposeResult {
     ir: PolicyIR;
+    interpreterIr: PolicyIR;
     ambiguities: AmbiguityPrompt[];
     warnings: string[];
 }
-/** Compose a PolicyIR from the lowered facts + the resolved scope.
+/** Compose a PolicyIR pair from the lowered facts + the resolved scope.
  *  Pure (no randomness, no clock); same inputs -> byte-identical result. */
 export declare function composeFromRecording(facts: IntentFacts, scopeContract: string, topLevel: ContractInvocation | null, opts: ComposeOptions): ComposeResult;