@crediolabs/policy-synth 0.1.2 → 0.1.4

package/dist/adapters/interpreter/adapter.js

@@ -0,0 +1,522 @@
+// src/adapters/interpreter/adapter.ts - the interpreter-policy CustodyAdapter.
+//
+// Compiles a PolicyIR to a single interpreter `PolicyDocument` + `PolicyRef`
+// carrying the canonical predicate encoding defined in
+// `packages/policy-interpreter/INTERPRETER_INSTALL_PARAMS.md`. The adapter is
+// the second backend (the OZ built-in adapter is the first); together they
+// cover the canonical language subset. The compose step (P3) routes IR
+// constructs between them.
+//
+// What it lowers (every IR construct the predicate DSL expresses):
+//   - IRLogic and/or    -> PredicateNode and/or
+//   - IRLogic not       -> PredicateNode not
+//   - IRCompare         -> selector(left) vs literal(right), op carried over
+//   - IR `in`           -> needle=selector, haystack=literals (PURESET
+//                          membership; the haystack is always sorted by the
+//                          encoder)
+//   - IR `eq_seq`       -> eq(selectorLeaf, literal_vec([...])) - exact ordered
+//                          sequence equality; element order is preserved
+//                          verbatim (the encoder does NOT sort the vec)
+//   - IRSelector        -> matching PredicateLeaf (see lowerSelector)
+//   - scope.contract    -> sibling `call_contract == <contract>` (always
+//                          emitted when set)
+//   - scope.method      -> sibling `call_fn == <method>`
+//
+// Three fail-closed enforcement gates (per spec):
+//   - oracle_price leaves MUST sit directly under the top-level `and`; nesting
+//     under `not` / `or` / inside `in` throws ORACLE_LEAF_INVALID_POSITION.
+//   - oracleParams overrides may only TIGHTEN vs wasm defaults
+//     (maxStalenessSeconds <= 600, maxDeviationBps <= 200); a widening value
+//     throws ORACLE_PARAMS_OUT_OF_RANGE at compile time.
+//   - an `in` allowlist (or a `compare eq` vs an address, or any value in an
+//     `eq_seq`) that targets the smart account's own address throws
+//     SCOPE_SELF_CALL.
+//
+// Anything the adapter genuinely cannot express (EVM calldata / value, unix
+// expiry, etc.) is named in `uncovered` rather than silently dropped.
+import { encodePredicate } from "../../predicate/encode.js";
+/** [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 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 const ORACLE_DEFAULTS = {
+    maxStalenessSeconds: 600,
+    maxDeviationBps: 200,
+};
+const CAPABILITIES = {
+    supportsSpendWindow: true,
+    supportsThreshold: false, // thresholds are the OZ adapter's job
+    supportsTimeExpiry: true, // via valid_until ledger expiry
+    supportsOraclePrice: true,
+    supportsInvocationCount: true,
+    supportsGeneralPredicate: true,
+};
+/** Parse confidence for a deterministic (non-decoded) input: full, with an
+ *  empty unknown/opaque breakdown. A mandate needs no decoding, so the gate is
+ *  not applicable and confidence is 1. */
+const FULL_PARSE_CONFIDENCE = {
+    overall: 1,
+    knownContracts: [],
+    unknownContracts: [],
+    opaqueScVals: [],
+    thresholdUsed: 1,
+};
+export function createInterpreterAdapter(config) {
+    return {
+        name: 'interpreter',
+        mode: 'enforce',
+        capabilities: () => ({ ...CAPABILITIES }),
+        compile: (ir) => compile(ir, config),
+        simulate: () => simulateStub(),
+        export: (ir) => canonicalStringify(ir),
+    };
+}
+/** 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 function lowerRuleToPredicate(rule, config) {
+    return lowerRule(rule, config).predicate;
+}
+function compile(ir, config) {
+    // Tighten-only oracle-params gate (config-time). Widening -> throw at compile
+    // time before any lowering happens, so a misuse fails closed loudly.
+    assertOracleParamsTighten(config.oracleParams);
+    const firstRule = ir.rules[0];
+    if (!firstRule) {
+        return { covered: false, uncovered: ['empty PolicyIR (no rules to compile)'] };
+    }
+    if (ir.rules.length > 1) {
+        return {
+            covered: false,
+            uncovered: [
+                `multi-rule PolicyIR: ${ir.rules.length - 1} rule(s) beyond the first are not compiled (the interpreter adapter handles one rule per document in this slice)`,
+            ],
+        };
+    }
+    const lowered = lowerRule(firstRule, config);
+    if (lowered.uncovered.length > 0) {
+        return { covered: false, uncovered: lowered.uncovered };
+    }
+    const { encodedPredicate, predicateHash } = encodePredicate(lowered.predicate);
+    const policyDocument = {
+        grammarVersion: 1,
+        installNonce: config.installNonce,
+        encodedPredicate,
+        predicateHash,
+        ...(config.oracleParams ? { oracleParams: config.oracleParams } : {}),
+    };
+    const policyRef = {
+        kind: 'interpreter',
+        interpreterAddress: PLACEHOLDER_INTERPRETER_ADDRESS,
+        predicateBlobBase64: encodedPredicate,
+    };
+    const proposed = {
+        contextRule: lowered.contextRule,
+        policyDocuments: [policyDocument],
+        policyRefs: [policyRef],
+        parseConfidence: { ...FULL_PARSE_CONFIDENCE },
+        warnings: [],
+        ambiguities: [],
+    };
+    return { covered: true, uncovered: [], proposed };
+}
+function lowerRule(rule, config) {
+    const uncovered = [];
+    // scope -> context rule + sibling predicates. contract/method each become
+    // their own `eq` leaf and are merged into the top-level and alongside the
+    // constraints. This keeps the top-level shape `and` (mandatory per the oracle
+    // position rule and the canonical hash stability for `and`).
+    const scopeContract = rule.scope.contract;
+    const scopeMethod = rule.scope.method;
+    if (rule.scope.chainId !== undefined) {
+        uncovered.push(`chainId \`${rule.scope.chainId}\` not bindable by the interpreter adapter (network is per-context, not per-rule)`);
+    }
+    if (rule.roles.length > 0) {
+        uncovered.push(`roles [${rule.roles.join(', ')}] dropped (role-to-signer mapping is a later phase; interpreter policies reference addresses, not role names)`);
+    }
+    if (rule.guard) {
+        uncovered.push(`guard: ${describeCondition(rule.guard)} (interpreter adapter currently treats guards as uncovered)`);
+    }
+    // expiry -> context rule validUntilLedger only. Unix-timestamp expiry is
+    // honoured by the interpreter (the `valid_until` selector), but we surface
+    // it here as Path-B because the IR contract already says "OZ context rules
+    // expire by ledger sequence" and we keep one expiry model for both adapters.
+    let validUntilLedger = null;
+    if (rule.expiry) {
+        if (rule.expiry.validUntilLedger !== undefined) {
+            validUntilLedger = rule.expiry.validUntilLedger;
+        }
+        else if (rule.expiry.validUntilUnixSeconds !== undefined) {
+            uncovered.push('time expiry given as a unix timestamp (interpreter adapter currently lowers expiry only via the OZ context-rule validUntilLedger; supply expiry.validUntilLedger)');
+        }
+    }
+    // approval is the OZ adapter's job (it lowers to simple_threshold /
+    // weighted_threshold primitives). Surface it here so a caller that drops it
+    // through to the interpreter adapter sees an explicit uncovered entry
+    // instead of a silently-dropped M-of-N gate.
+    if (rule.approval) {
+        uncovered.push(`approval threshold ${rule.approval.threshold} not emitted by the interpreter adapter (thresholds lower to OZ built-in primitives in the OZ adapter)`);
+    }
+    // Pre-scan constraints: anything the interpreter adapter cannot express is
+    // named in `uncovered` and skipped from the predicate lowering. We surface
+    // these BEFORE lowering so the predicate is built from only the
+    // expressible subset.
+    const expressibleConstraints = [];
+    for (const c of rule.constraints) {
+        const unsupp = unsupportedConstruct(c);
+        if (unsupp !== null) {
+            uncovered.push(unsupp);
+        }
+        else {
+            expressibleConstraints.push(c);
+        }
+    }
+    // Build the top-level `and` of scope + expressible constraints. The
+    // top-level MUST be `and` so oracle leaves sit directly under it - the
+    // position rule is enforced inside `lowerCondition`.
+    const topChildren = [];
+    if (scopeContract !== undefined) {
+        topChildren.push({
+            op: 'eq',
+            left: { kind: 'call_contract' },
+            right: { kind: 'literal_address', value: scopeContract },
+        });
+    }
+    if (scopeMethod !== undefined) {
+        topChildren.push({
+            op: 'eq',
+            left: { kind: 'call_fn' },
+            right: { kind: 'literal_symbol', value: scopeMethod },
+        });
+    }
+    for (const c of expressibleConstraints) {
+        topChildren.push(lowerCondition(c, config));
+    }
+    const predicate = topChildren.length === 1 && topChildren[0] !== undefined
+        ? topChildren[0]
+        : { op: 'and', children: topChildren };
+    const contextRule = {
+        contextRuleType: { kind: 'default' },
+        name: 'interpreter',
+        validUntilLedger,
+        signers: [],
+        policies: [],
+    };
+    return { predicate, contextRule, uncovered };
+}
+/** Detect IR constructs the interpreter adapter cannot express; return a
+ *  human-readable descriptor (or null if the construct IS expressible). Used
+ *  by `lowerRule` to populate `uncovered` before lowering. */
+function unsupportedConstruct(cond) {
+    switch (cond.op) {
+        case 'in':
+            return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+                ? `EVM \`${cond.selector.kind}\` selector on allowlist (predicate DSL)`
+                : null;
+        case 'eq_seq':
+            return cond.selector.kind === 'calldata' || cond.selector.kind === 'value'
+                ? `EVM \`${cond.selector.kind}\` selector on ordered-sequence equality (predicate DSL)`
+                : null;
+        case 'compare': {
+            const s = cond.compare.selector;
+            if (s.kind === 'calldata')
+                return 'EVM calldata comparison (predicate DSL)';
+            if (s.kind === 'value')
+                return 'tx.value comparison (predicate DSL)';
+            return null;
+        }
+        case 'and':
+        case 'or':
+        case 'not':
+            return null;
+    }
+}
+/** Lower one IR condition to a PredicateNode. Enforces the oracle position
+ *  rule (oracle_price leaves must sit directly under the top-level `and`) and
+ *  the self-call rule (`in` allowlist / `compare eq` vs the smart account
+ *  address -> SCOPE_SELF_CALL). */
+function lowerCondition(cond, config) {
+    switch (cond.op) {
+        case 'and':
+            return { op: 'and', children: cond.children.map((c) => lowerCondition(c, config)) };
+        case 'or':
+            // `or` at this depth: oracle_price anywhere inside is invalid (would
+            // not be a direct child of the top-level `and`).
+            assertNoOracleDescendants(cond);
+            return { op: 'or', children: cond.children.map((c) => lowerCondition(c, config)) };
+        case 'not':
+            // `not` at this depth: oracle_price anywhere inside is invalid.
+            assertNoOracleDescendants(cond);
+            return { op: 'not', child: lowerCondition(cond.child, config) };
+        case 'in': {
+            assertNoOracleDescendants(cond);
+            for (const v of cond.values) {
+                assertNotSelfCallAddress(v, config);
+            }
+            // `in` is PURE set membership; the encoder sorts the haystack. An exact
+            // ordered sequence (e.g. swap hop path) is expressed as `eq_seq` and
+            // lowers to `eq(selector, literal_vec)` instead - never to `in` with an
+            // `ordered` flag.
+            return {
+                op: 'in',
+                needle: lowerSelector(cond.selector),
+                haystack: cond.values.map((v) => literalFromScalar(v, selectorScalarType(cond.selector))),
+            };
+        }
+        case 'eq_seq': {
+            assertNoOracleDescendants(cond);
+            for (const v of cond.values) {
+                assertNotSelfCallAddress(v, config);
+            }
+            // Exact ordered sequence equality: the right-hand side is a literal_vec
+            // whose element order is preserved verbatim by the encoder. `eq` does
+            // deep equality at evaluate time - this is the ONLY way to express an
+            // exact ordered sequence in the predicate grammar (the path of a swap).
+            return {
+                op: 'eq',
+                left: lowerSelector(cond.selector),
+                right: {
+                    kind: 'literal_vec',
+                    elements: cond.values.map((v) => literalFromScalar(v, selectorScalarType(cond.selector))),
+                },
+            };
+        }
+        case 'compare': {
+            // Self-call on an address eq.
+            if (cond.compare.operator === 'eq' &&
+                cond.compare.selector.kind === 'arg' &&
+                cond.compare.selector.scalarType === 'address') {
+                assertNotSelfCallAddress(cond.compare.value, config);
+            }
+            return {
+                op: cond.compare.operator,
+                left: lowerSelector(cond.compare.selector),
+                right: literalFromIRCompare(cond.compare),
+            };
+        }
+    }
+}
+/** Lower an IR selector to the matching PredicateLeaf. */
+function lowerSelector(s) {
+    switch (s.kind) {
+        case 'arg':
+            return { kind: 'call_arg', index: s.argIndex };
+        case 'amount':
+            return { kind: 'amount', token: s.token };
+        case 'window_spent':
+            return { kind: 'window_spent', token: s.token, windowSeconds: s.windowSeconds };
+        case 'invocation_count':
+            return { kind: 'invocation_count_in_window', windowSecs: s.windowSeconds };
+        case 'now':
+            return { kind: 'now' };
+        case 'valid_until':
+            return { kind: 'valid_until' };
+        case 'oracle_price':
+            return { kind: 'oracle_price', asset: s.asset };
+        case 'calldata':
+        case 'value':
+            // Unreachable: the caller flagged these as Path-B before reaching here.
+            throw toolError('SYNTHESIS_ERROR', `selector kind \`${s.kind}\` is not lowerable to a predicate leaf`);
+    }
+}
+/** Build a literal leaf from the right-hand side of an IRCompare, mapping the
+ *  selector kind to the matching `literal_*` kind. The IR compare value is a
+ *  raw string (i128-safe); the selector kind fixes the canonical wire type:
+ *    - arg       -> IR scalarType (set by the recorder/parser)
+ *    - amount    -> i128 (canonical Stellar token amount encoding)
+ *    - window_spent -> i128 (canonical amount encoding)
+ *    - oracle_price  -> i128 (canonical price encoding)
+ *    - invocation_count -> u32 (counts are small non-negative integers)
+ *    - now / valid_until -> u64 (unix timestamps in seconds) */
+function literalFromIRCompare(c) {
+    const scalarType = c.selector.kind === 'arg' ? c.selector.scalarType : literalScalarForSelector(c.selector.kind);
+    return literalFromScalar(c.value, scalarType);
+}
+function literalScalarForSelector(kind) {
+    switch (kind) {
+        case 'amount':
+        case 'window_spent':
+        case 'oracle_price':
+            return 'i128';
+        case 'invocation_count':
+            return 'u32';
+        case 'now':
+        case 'valid_until':
+            return 'u64';
+        case 'arg':
+        case 'calldata':
+        case 'value':
+            // arg -> caller handles scalarType; calldata/value -> unreachable (Path-B).
+            return 'i128';
+    }
+}
+/** Build a literal leaf from a raw string value + an IRScalarType hint. */
+function literalFromScalar(value, scalarType) {
+    switch (scalarType) {
+        case 'address':
+            return { kind: 'literal_address', value };
+        case 'i128':
+        case 'u128':
+            return { kind: 'literal_i128', value };
+        case 'u32':
+            return { kind: 'literal_u32', value: Number.parseInt(value, 10) };
+        case 'u64':
+        case 'i64':
+            return { kind: 'literal_u64', value };
+        case 'symbol':
+            return { kind: 'literal_symbol', value };
+        case 'bytes':
+            return { kind: 'literal_bytes', value };
+        case 'bool':
+            throw toolError('MALFORMED_PREDICATE', `boolean literal not supported in v1 predicate grammar`);
+    }
+}
+/** Scalar type of an IRSelector for the purpose of building literal leaves
+ *  (the right-hand side of `eq` / elements of an `in` haystack / elements of
+ *  a `literal_vec`). Mirrors `literalScalarForSelector` for OZ extensions and
+ *  uses the selector's own `scalarType` for `arg` selectors. */
+function selectorScalarType(selector) {
+    if (selector.kind === 'arg')
+        return selector.scalarType;
+    return literalScalarForSelector(selector.kind);
+}
+/** Walk a condition tree and throw if any oracle_price leaf is found anywhere
+ *  inside. Used by `lowerCondition` for `not`, `or`, and `in` - the three
+ *  positions where oracle leaves would not be direct children of the
+ *  top-level `and`. */
+function assertNoOracleDescendants(node) {
+    if (containsOracle(node)) {
+        throw toolError('ORACLE_LEAF_INVALID_POSITION', 'oracle_price leaves must sit directly under the top-level `and`');
+    }
+}
+function containsOracle(node) {
+    switch (node.op) {
+        case 'compare':
+            return node.compare.selector.kind === 'oracle_price';
+        case 'in':
+            return node.selector.kind === 'oracle_price';
+        case 'eq_seq':
+            return node.selector.kind === 'oracle_price';
+        case 'not':
+            return containsOracle(node.child);
+        case 'and':
+        case 'or':
+            return node.children.some(containsOracle);
+    }
+}
+/** Reject a value that targets the smart account's own address (a self-call
+ *  is a structural privilege-escalation hole the interpreter forbids). */
+function assertNotSelfCallAddress(value, config) {
+    if (value === config.smartAccountAddress) {
+        throw toolError('SCOPE_SELF_CALL', `value \`${value}\` is the smart account's own address (self-call in an allowlist / compare is rejected)`);
+    }
+}
+/** Tighten-only oracle-params gate. Any widening value (above the wasm-level
+ *  defaults) throws ORACLE_PARAMS_OUT_OF_RANGE at compile time. */
+function assertOracleParamsTighten(params) {
+    if (!params)
+        return;
+    if (params.maxStalenessSeconds !== undefined &&
+        params.maxStalenessSeconds > ORACLE_DEFAULTS.maxStalenessSeconds) {
+        throw toolError('ORACLE_PARAMS_OUT_OF_RANGE', `maxStalenessSeconds ${params.maxStalenessSeconds} exceeds default ${ORACLE_DEFAULTS.maxStalenessSeconds}`);
+    }
+    if (params.maxDeviationBps !== undefined &&
+        params.maxDeviationBps > ORACLE_DEFAULTS.maxDeviationBps) {
+        throw toolError('ORACLE_PARAMS_OUT_OF_RANGE', `maxDeviationBps ${params.maxDeviationBps} exceeds default ${ORACLE_DEFAULTS.maxDeviationBps}`);
+    }
+}
+/** Human-readable descriptor for a construct the interpreter adapter cannot
+ *  express. Mirrors the OZ adapter's `describeCondition` for parity. */
+function describeCondition(cond) {
+    switch (cond.op) {
+        case 'in':
+            return `value allowlist on ${describeSelector(cond.selector)} (predicate DSL)`;
+        case 'eq_seq':
+            return `exact ordered sequence on ${describeSelector(cond.selector)} (predicate DSL)`;
+        case 'not':
+            return 'negated condition (predicate DSL)';
+        case 'and':
+        case 'or':
+            return `nested ${cond.op} condition (predicate DSL)`;
+        case 'compare': {
+            const s = cond.compare.selector;
+            switch (s.kind) {
+                case 'oracle_price':
+                    return `oracle price condition on ${s.asset}`;
+                case 'invocation_count':
+                    return `invocation-count window (${s.windowSeconds}s) condition`;
+                case 'window_spent':
+                    return `spend-window comparison with operator '${cond.compare.operator}'`;
+                case 'amount':
+                    return `per-call amount comparison on ${s.token}`;
+                case 'arg':
+                    return `argument comparison on arg ${s.argIndex}`;
+                case 'calldata':
+                    return 'EVM calldata comparison';
+                case 'value':
+                    return 'tx.value comparison';
+                case 'now':
+                case 'valid_until':
+                    return 'time comparison';
+            }
+        }
+    }
+}
+function describeSelector(s) {
+    switch (s.kind) {
+        case 'arg':
+            return `arg ${s.argIndex}`;
+        case 'amount':
+            return `amount(${s.token})`;
+        case 'window_spent':
+            return `window_spent(${s.token})`;
+        case 'oracle_price':
+            return `oracle_price(${s.asset})`;
+        case 'invocation_count':
+            return `invocation_count(${s.windowSeconds}s)`;
+        case 'calldata':
+            return `calldata[${s.offset}:${s.offset + s.length}]`;
+        default:
+            return s.kind;
+    }
+}
+function simulateStub() {
+    return {
+        backend: 'ts-model',
+        permitted: null,
+        evaluations: [],
+        notes: ['stub: real permit/deny semantics wiring is a later phase'],
+    };
+}
+/** 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;
+}
+/** Build a synthetic Error carrying the ToolError code/severity/retryable
+ *  fields the existing ToolError shape uses (the encoder pattern). Callers
+ *  inspect `e.code` in catch blocks. */
+function toolError(code, message) {
+    const err = new Error(message);
+    err.code = code;
+    err.severity = 'error';
+    err.retryable = false;
+    return err;
+}

package/dist/adapters/interpreter/index.d.ts

@@ -0,0 +1 @@
+export { createInterpreterAdapter, type InterpreterAdapterConfig, ORACLE_DEFAULTS, PLACEHOLDER_INTERPRETER_ADDRESS, } from './adapter.ts';

package/dist/adapters/interpreter/index.js

@@ -0,0 +1,2 @@
+// src/adapters/interpreter/index.ts - re-export the interpreter-policy CustodyAdapter.
+export { createInterpreterAdapter, ORACLE_DEFAULTS, PLACEHOLDER_INTERPRETER_ADDRESS, } from "./adapter.js";

package/dist/adapters/oz/adapter.js

@@ -1,7 +1,7 @@
-// src/adapters/oz/adapter.ts - the OZ Accounts CustodyAdapter (Path-A lowering).
+// src/adapters/oz/adapter.ts - the OZ Accounts CustodyAdapter.
 //
 // Compiles a PolicyIR to an OZ `ProposedPolicy` using OZ built-in policy
-// primitives (Path A). Only the constructs OZ can express natively are lowered:
+// primitives. Only the constructs OZ can express natively are lowered:
 //   scope.contract            -> ContextRuleType.call_contract (else default)
 //   expiry.validUntilLedger   -> ContextRuleDraft.validUntilLedger
 //   window_spent(t,w) <= L    -> `spending_limit` primitive
@@ -9,7 +9,7 @@
 // Anything needing a capability this backend lacks (oracle price, invocation
 // count, per-arg comparison/allowlist, guard, nested boolean predicate) is NOT
 // emitted: it is named in `uncovered` and `covered` is set false. Nothing is
-// silently dropped - the uncovered constructs are the Path-B markers.
+// silently dropped - the uncovered constructs are named instead.
 //
 // OZ built-in policy instance addresses are per-network deploy artifacts we do
 // not have yet (install is a later phase). They are injected via config; week-1
@@ -84,8 +84,8 @@ function lowerRule(rule, config) {
     const uncovered = [];
     const policyRefs = [];
     // scope -> context rule type. OZ scopes by contract (CallContract); a finer
-    // method-level restriction is a predicate concern and must be flagged Path-B
-    // because CallContract alone permits other methods on the same contract
+    // method-level restriction is a predicate concern and must be flagged as not
+    // covered because CallContract alone permits other methods on the same contract
     // (e.g. an unbounded approve alongside a capped transfer).
     const contextRuleType = rule.scope.contract !== undefined
         ? { kind: 'call_contract', contract: rule.scope.contract }
@@ -110,11 +110,11 @@ function lowerRule(rule, config) {
             uncovered.push('time expiry given as a unix timestamp (OZ context rules expire by ledger sequence; supply expiry.validUntilLedger)');
         }
     }
-    // guard -> Path B (applicability predicates are not an OZ built-in).
+    // guard -> not covered (applicability predicates are not an OZ built-in).
     if (rule.guard) {
         uncovered.push(`guard: ${describeCondition(rule.guard)}`);
     }
-    // constraints -> spending_limit where they match; else Path B. The OZ
+    // constraints -> spending_limit where they match; else not covered. The OZ
     // spending_limit policy takes `{ spending_limit: i128, period_ledgers: u32 }`
     // and has NO token param: it only accepts a CallContract context rule
     // (OnlyCallContractAllowed) and limits transfers of that context's contract,
@@ -144,7 +144,7 @@ function lowerRule(rule, config) {
     }
     // approval.threshold -> simple/weighted threshold primitive. A threshold < 1
     // is not a real M-of-N gate (0 approvals authorises everything), so refuse to
-    // emit a no-op primitive and flag it Path-B instead.
+    // emit a no-op primitive and flag it as not covered instead.
     if (rule.approval) {
         if (!Number.isInteger(rule.approval.threshold) || rule.approval.threshold < 1) {
             uncovered.push(`approval threshold ${rule.approval.threshold} is not a positive integer (a 0 or negative threshold is not an M-of-N gate)`);
@@ -203,17 +203,19 @@ function matchSpendingLimit(c) {
         return null;
     return { token: selector.token, limit: value, windowSeconds: selector.windowSeconds };
 }
-/** Human-readable descriptor for a construct the OZ Path-A backend cannot
- *  express, used to populate `uncovered` (the Path-B markers). */
+/** Human-readable descriptor for a construct the OZ built-in-primitive backend
+ *  cannot express, used to populate `uncovered`. */
 function describeCondition(cond) {
     switch (cond.op) {
         case 'in':
-            return `value allowlist on ${describeSelector(cond.selector)} (arg allowlist, Path B)`;
+            return `value allowlist on ${describeSelector(cond.selector)} (arg allowlist)`;
+        case 'eq_seq':
+            return `exact ordered sequence on ${describeSelector(cond.selector)} (OZ built-ins cannot express an exact vector)`;
         case 'not':
-            return 'negated condition (predicate DSL, Path B)';
+            return 'negated condition (predicate DSL)';
         case 'and':
         case 'or':
-            return `nested ${cond.op} condition (predicate DSL, Path B)`;
+            return `nested ${cond.op} condition (predicate DSL)`;
         case 'compare': {
             const s = cond.compare.selector;
             switch (s.kind) {
@@ -224,16 +226,16 @@ function describeCondition(cond) {
                 case 'window_spent':
                     return `spend-window comparison with operator '${cond.compare.operator}' (only 'lte' lowers to spending_limit)`;
                 case 'amount':
-                    return `per-call amount comparison on ${s.token} (predicate DSL, Path B)`;
+                    return `per-call amount comparison on ${s.token} (predicate DSL)`;
                 case 'arg':
-                    return `argument comparison on arg ${s.argIndex} (predicate DSL, Path B)`;
+                    return `argument comparison on arg ${s.argIndex} (predicate DSL)`;
                 case 'calldata':
-                    return 'EVM calldata comparison (predicate DSL, Path B)';
+                    return 'EVM calldata comparison (predicate DSL)';
                 case 'value':
-                    return 'tx.value comparison (predicate DSL, Path B)';
+                    return 'tx.value comparison (predicate DSL)';
                 case 'now':
                 case 'valid_until':
-                    return 'time comparison (predicate DSL, Path B)';
+                    return 'time comparison (predicate DSL)';
             }
         }
     }

package/dist/codegen/compile-gate.d.ts

@@ -0,0 +1,33 @@
+export type CompileGateResult = {
+    code: 'COMPILE_OK';
+} | {
+    code: 'COMPILE_GATE_FAILED';
+    stderr: string;
+} | {
+    code: 'SKIPPED';
+    reason: string;
+};
+export interface CompileGateOpts {
+    /** Caller-controlled abort signal; aborting before toolchain probe resolves
+     *  the gate to `SKIPPED` rather than starting a cargo invocation. */
+    signal?: AbortSignal;
+    /** Override the `cargo` binary (mostly for tests). */
+    cargoBin?: string;
+    /** Override the target directory (mostly for tests). */
+    tempDir?: string;
+}
+/** Probe the host for the Rust toolchain the gate requires. We require BOTH
+ *  `cargo` AND `stellar` (the Soroban CLI) because a real gate run invokes
+ *  `stellar contract build`; absent either, the gate returns `SKIPPED`. */
+export declare function hasRustToolchain(): Promise<boolean>;
+/** Compile-check a Rust source string against the pinned Soroban SDK.
+ *
+ *  - Toolchain absent -> `{ code: 'SKIPPED', reason }` (NOT a failure).
+ *  - Toolchain present, source compiles -> `{ code: 'COMPILE_OK' }`.
+ *  - Toolchain present, source broken -> `{ code: 'COMPILE_GATE_FAILED', stderr }`.
+ *
+ *  The gate writes the source to a temporary crate and runs `cargo check`
+ *  against it; the crate is cleaned up whether or not compilation succeeds.
+ *  The caller is expected to surface `COMPILE_GATE_FAILED.stderr` to the
+ *  user (the LLM agent) so the user can iterate. */
+export declare function compileCheck(rustSource: string, opts?: CompileGateOpts): Promise<CompileGateResult>;