@crediolabs/policy-synth 0.1.4 → 0.1.5

package/dist/verify/simulate.js

@@ -28,6 +28,7 @@
 // suite to stay in lockstep.
 import { generateCases } from "../synth/deny-cases.js";
 import { evaluate } from "../synth/evaluate.js";
+import { MAX_SCVAL_CLONE_DEPTH } from "../types.js";
 const SIMULATOR_VERSION = 'ts-model-1.0.0';
 /** Replay a recorded transaction against a proposed predicate and emit the
  *  `SimulationResult` envelope. The simulator returns the SAME permit
@@ -177,12 +178,27 @@ function buildPermitContext(predicate, tx, topLevel, opts) {
     }
     return ctx;
 }
-function cloneScVal(value) {
+function cloneScVal(value, depth = 0) {
+    // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+    // payload cannot RangeError the JS stack during context building. Over-depth
+    // throws a ToolError-shaped error that the simulator's existing try/catch
+    // converts to a structured `{ok:false, error}` (not a thrown RangeError).
     if (value.type === 'vec') {
-        return { type: 'vec', value: value.value.map(cloneScVal) };
+        if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+            throw cloneDepthError(value);
+        }
+        return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) };
     }
     return { ...value };
 }
+function cloneDepthError(value) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'SIMULATION_ERROR';
+    err.severity = 'error';
+    err.retryable = false;
+    err.depthContext = value.type;
+    throw err;
+}
 function visitOracleLeaves(node, visit) {
     switch (node.op) {
         case 'and':

package/dist/verify/verify.js

@@ -28,6 +28,7 @@
 //
 // Determinism: same `(predicate, permitTx)` -> byte-identical verdict.
 import { minimize } from "../synth/minimize.js";
+import { MAX_SCVAL_CLONE_DEPTH } from "../types.js";
 /** Run the static minimality check on a proposed predicate + recorded tx.
  *  Returns `{ ok: true }` when the predicate is minimal (every top-level
  *  conjunct carries load) and `VERIFICATION_FAILED` when a conjunct could
@@ -125,12 +126,27 @@ function buildPermitContextForVerify(tx, topLevel, opts) {
     }
     return ctx;
 }
-function cloneScVal(value) {
+function cloneScVal(value, depth = 0) {
+    // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+    // payload cannot RangeError the JS stack during context building. Over-depth
+    // throws a ToolError-shaped error that the verifier's existing try/catch
+    // converts to a structured `{ok:false, error}` (not a thrown RangeError).
     if (value.type === 'vec') {
-        return { type: 'vec', value: value.value.map(cloneScVal) };
+        if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+            throw cloneDepthError(value);
+        }
+        return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) };
     }
     return { ...value };
 }
+function cloneDepthError(value) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'VERIFICATION_FAILED';
+    err.severity = 'error';
+    err.retryable = false;
+    err.depthContext = value.type;
+    throw err;
+}
 function fingerprint(node) {
     return JSON.stringify(node, replacer);
 }

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

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

package/dist-cjs/adapters/interpreter/adapter.js

@@ -0,0 +1,527 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORACLE_DEFAULTS = exports.PLACEHOLDER_INTERPRETER_ADDRESS = void 0;
+exports.createInterpreterAdapter = createInterpreterAdapter;
+exports.lowerRuleToPredicate = lowerRuleToPredicate;
+const encode_ts_1 = require("../../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. */
+exports.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. */
+exports.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,
+};
+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)`. */
+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 } = (0, encode_ts_1.encodePredicate)(lowered.predicate);
+    const policyDocument = {
+        grammarVersion: 1,
+        installNonce: config.installNonce,
+        encodedPredicate,
+        predicateHash,
+        ...(config.oracleParams ? { oracleParams: config.oracleParams } : {}),
+    };
+    const policyRef = {
+        kind: 'interpreter',
+        interpreterAddress: exports.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 > exports.ORACLE_DEFAULTS.maxStalenessSeconds) {
+        throw toolError('ORACLE_PARAMS_OUT_OF_RANGE', `maxStalenessSeconds ${params.maxStalenessSeconds} exceeds default ${exports.ORACLE_DEFAULTS.maxStalenessSeconds}`);
+    }
+    if (params.maxDeviationBps !== undefined &&
+        params.maxDeviationBps > exports.ORACLE_DEFAULTS.maxDeviationBps) {
+        throw toolError('ORACLE_PARAMS_OUT_OF_RANGE', `maxDeviationBps ${params.maxDeviationBps} exceeds default ${exports.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-cjs/adapters/interpreter/index.d.ts

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

package/dist-cjs/adapters/interpreter/index.js

@@ -0,0 +1,8 @@
+"use strict";
+// src/adapters/interpreter/index.ts - re-export the interpreter-policy CustodyAdapter.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLACEHOLDER_INTERPRETER_ADDRESS = exports.ORACLE_DEFAULTS = exports.createInterpreterAdapter = void 0;
+var adapter_ts_1 = require("./adapter.js");
+Object.defineProperty(exports, "createInterpreterAdapter", { enumerable: true, get: function () { return adapter_ts_1.createInterpreterAdapter; } });
+Object.defineProperty(exports, "ORACLE_DEFAULTS", { enumerable: true, get: function () { return adapter_ts_1.ORACLE_DEFAULTS; } });
+Object.defineProperty(exports, "PLACEHOLDER_INTERPRETER_ADDRESS", { enumerable: true, get: function () { return adapter_ts_1.PLACEHOLDER_INTERPRETER_ADDRESS; } });

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

@@ -0,0 +1,20 @@
+import type { CustodyAdapter } from '../../seams/types.ts';
+import type { Network } from '../../types.ts';
+/** OZ built-in policy contract instance addresses, per primitive. */
+export interface OzPrimitiveInstances {
+    spending_limit: string;
+    simple_threshold: string;
+    weighted_threshold: string;
+}
+/** Per-network config for the OZ adapter. */
+export interface OzAdapterConfig {
+    network: Network;
+    instances: OzPrimitiveInstances;
+}
+/** [VERIFY] NOT real deployed addresses. The OZ built-in policy instances are
+ *  per-network deploy artifacts we do not have yet; install is a later phase.
+ *  Injected so the adapter never invents a Stellar contract address. */
+export declare const PLACEHOLDER_OZ_INSTANCES: OzPrimitiveInstances;
+/** Week-1 OZ adapter config with placeholder instance addresses. */
+export declare function placeholderOzConfig(network: Network): OzAdapterConfig;
+export declare function createOzAdapter(config: OzAdapterConfig): CustodyAdapter;