@crediolabs/policy-synth 0.1.17 → 0.2.0

package/dist-cjs/install/read-account-rules.js

@@ -0,0 +1,296 @@
+"use strict";
+//! Reading an OpenZeppelin smart account's context rules back off chain.
+//!
+//! `authority-overlap.ts` needs to know what a signer can already do before a
+//! new policy is installed. That means every rule on the account: its context
+//! type, its signers, its attached policies, and - for rules our interpreter
+//! polices - the predicate itself.
+//!
+//! The predicate is NOT reachable through a contract call. The interpreter
+//! exposes no getter for `StoredDoc` (`lib.rs` publishes only `grammar_version`,
+//! `install`, `enforce`, the pause pair, `uninstall` and
+//! `rotate_master_signer_set`), so it is read as a ledger entry instead. That
+//! keeps this a pure client-side capability: adding a getter would change a
+//! deployed contract's ABI and force a redeploy plus re-audit to obtain data
+//! the ledger already exposes.
+//!
+//! The decoders here are pure so they can be tested without a network; the
+//! caller supplies raw `ScVal`s.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RULE_ID_SCAN = exports.K_NONCE = exports.K_DOC = void 0;
+exports.docKeyScVal = docKeyScVal;
+exports.docLedgerKey = docLedgerKey;
+exports.decodeContextType = decodeContextType;
+exports.decodeSigner = decodeSigner;
+exports.decodeContextRule = decodeContextRule;
+exports.nonceLedgerKey = nonceLedgerKey;
+exports.decodeStoredOracleBounds = decodeStoredOracleBounds;
+exports.decodeStoredPredicateBytes = decodeStoredPredicateBytes;
+exports.collectObservedRules = collectObservedRules;
+exports.accountRuleReaderFromServer = accountRuleReaderFromServer;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const decode_ts_1 = require("../predicate/decode.js");
+/** `storage.rs:295` - the third element of the persistent doc key tuple. */
+exports.K_DOC = 1;
+/** Persistent-storage key for a rule's stored document:
+ *  `(account, rule_id, K_DOC)`, per `storage.rs:4`. */
+function docKeyScVal(smartAccount, ruleId) {
+    return stellar_sdk_1.xdr.ScVal.scvVec([
+        new stellar_sdk_1.Address(smartAccount).toScVal(),
+        stellar_sdk_1.xdr.ScVal.scvU32(ruleId),
+        stellar_sdk_1.xdr.ScVal.scvU32(exports.K_DOC),
+    ]);
+}
+/** Ledger key for the interpreter's persistent entry holding that document. */
+function docLedgerKey(interpreter, smartAccount, ruleId) {
+    return stellar_sdk_1.xdr.LedgerKey.contractData(new stellar_sdk_1.xdr.LedgerKeyContractData({
+        contract: new stellar_sdk_1.Address(interpreter).toScAddress(),
+        key: docKeyScVal(smartAccount, ruleId),
+        durability: stellar_sdk_1.xdr.ContractDataDurability.persistent(),
+    }));
+}
+// ---- ScVal helpers -----
+/** Field of a `#[contracttype]` struct, which the host encodes as a map keyed
+ *  by field-name symbol. Returns undefined when the field is absent so a
+ *  caller can distinguish "not there" from "there and empty". */
+function mapField(v, name) {
+    if (v.switch() !== stellar_sdk_1.xdr.ScValType.scvMap())
+        return undefined;
+    for (const entry of v.map() ?? []) {
+        const key = entry.key();
+        if (key.switch() === stellar_sdk_1.xdr.ScValType.scvSymbol() && key.sym().toString() === name) {
+            return entry.val();
+        }
+    }
+    return undefined;
+}
+function u32Of(v) {
+    return v?.switch() === stellar_sdk_1.xdr.ScValType.scvU32() ? v.u32() : undefined;
+}
+function addressOf(v) {
+    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvAddress())
+        return undefined;
+    return stellar_sdk_1.Address.fromScAddress(v.address()).toString();
+}
+/** An enum variant of a `#[contracttype]` enum: `ScVal::Vec([Symbol, ...args])`. */
+function enumVariant(v) {
+    if (!v || v.switch() !== stellar_sdk_1.xdr.ScValType.scvVec())
+        return undefined;
+    const items = v.vec() ?? [];
+    const head = items[0];
+    if (!head || head.switch() !== stellar_sdk_1.xdr.ScValType.scvSymbol())
+        return undefined;
+    return { tag: head.sym().toString(), args: items.slice(1) };
+}
+// ---- decoders -----
+/** OZ `ContextRuleType`. An unrecognised tag is reported as `default`, which
+ *  is the widest reading and therefore the safe one: it makes the rule look
+ *  like it could serve any call, so overlap is over-reported, never missed. */
+function decodeContextType(v) {
+    const variant = enumVariant(v);
+    if (!variant)
+        return { kind: 'default' };
+    if (variant.tag === 'CallContract') {
+        const addr = addressOf(variant.args[0]);
+        return addr ? { kind: 'call_contract', address: addr } : { kind: 'default' };
+    }
+    if (variant.tag === 'CreateContract') {
+        const arg = variant.args[0];
+        const hash = arg?.switch() === stellar_sdk_1.xdr.ScValType.scvBytes() ? arg.bytes().toString('hex') : '';
+        return { kind: 'create_contract', wasmHash: hash };
+    }
+    return { kind: 'default' };
+}
+/** OZ `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
+function decodeSigner(v) {
+    const variant = enumVariant(v);
+    if (!variant)
+        return undefined;
+    if (variant.tag === 'Delegated') {
+        const addr = addressOf(variant.args[0]);
+        return addr ? { kind: 'delegated', address: addr } : undefined;
+    }
+    if (variant.tag === 'External') {
+        const verifier = addressOf(variant.args[0]);
+        const keyArg = variant.args[1];
+        const keyBytes = keyArg?.switch() === stellar_sdk_1.xdr.ScValType.scvBytes() ? keyArg.bytes().toString('hex') : '';
+        return verifier ? { kind: 'external', verifier, keyBytes } : undefined;
+    }
+    return undefined;
+}
+/** A full OZ `ContextRule` as returned by `get_context_rule(id)`.
+ *  `predicate` is filled in separately from the ledger entry. */
+function decodeContextRule(v) {
+    const id = u32Of(mapField(v, 'id'));
+    if (id === undefined)
+        return undefined;
+    const signersVal = mapField(v, 'signers');
+    const signers = [];
+    if (signersVal?.switch() === stellar_sdk_1.xdr.ScValType.scvVec()) {
+        for (const s of signersVal.vec() ?? []) {
+            const decoded = decodeSigner(s);
+            if (decoded)
+                signers.push(decoded);
+        }
+    }
+    const policiesVal = mapField(v, 'policies');
+    const policyAddresses = [];
+    if (policiesVal?.switch() === stellar_sdk_1.xdr.ScValType.scvVec()) {
+        for (const p of policiesVal.vec() ?? []) {
+            const addr = addressOf(p);
+            if (addr)
+                policyAddresses.push(addr);
+        }
+    }
+    // `policy_ids` is index-aligned with `policies` in OZ's ContextRule. Only
+    // the ids can be passed to `remove_policy`, so a detach is impossible
+    // without them; they are read here rather than looked up again later.
+    const policyIdsVal = mapField(v, 'policy_ids');
+    const policyIds = [];
+    if (policyIdsVal?.switch() === stellar_sdk_1.xdr.ScValType.scvVec()) {
+        for (const pid of policyIdsVal.vec() ?? []) {
+            const n = u32Of(pid);
+            if (n !== undefined)
+                policyIds.push(n);
+        }
+    }
+    return {
+        id,
+        contextType: decodeContextType(mapField(v, 'context_type')),
+        signers,
+        policyAddresses,
+        ...(policyIds.length > 0 ? { policyIds } : {}),
+    };
+}
+/** `storage.rs:296` - the third element of the persistent nonce key tuple. */
+exports.K_NONCE = 2;
+/** Ledger key for a rule's stored install nonce. Read directly for the same
+ *  reason as the document: the interpreter publishes no getter. */
+function nonceLedgerKey(interpreter, smartAccount, ruleId) {
+    return stellar_sdk_1.xdr.LedgerKey.contractData(new stellar_sdk_1.xdr.LedgerKeyContractData({
+        contract: new stellar_sdk_1.Address(interpreter).toScAddress(),
+        key: stellar_sdk_1.xdr.ScVal.scvVec([
+            new stellar_sdk_1.Address(smartAccount).toScVal(),
+            stellar_sdk_1.xdr.ScVal.scvU32(ruleId),
+            stellar_sdk_1.xdr.ScVal.scvU32(exports.K_NONCE),
+        ]),
+        durability: stellar_sdk_1.xdr.ContractDataDurability.persistent(),
+    }));
+}
+function decodeStoredOracleBounds(v) {
+    const read = (name) => u32Of(mapField(v, name));
+    const staleness = read('oracle_max_staleness_seconds');
+    const deviation = read('oracle_max_deviation_bps');
+    const xfeed = read('oracle_max_xfeed_dev_bps');
+    return {
+        ...(staleness !== undefined ? { maxStalenessSeconds: staleness } : {}),
+        ...(deviation !== undefined ? { maxDeviationBps: deviation } : {}),
+        ...(xfeed !== undefined ? { maxCrossFeedDeviationBps: xfeed } : {}),
+    };
+}
+/** Raw predicate bytes out of a `StoredDoc` ledger entry value. */
+function decodeStoredPredicateBytes(v) {
+    const field = mapField(v, 'predicate_bytes');
+    if (!field || field.switch() !== stellar_sdk_1.xdr.ScValType.scvBytes())
+        return undefined;
+    return field.bytes();
+}
+/** How far the id scan will probe before giving up. OZ imposes no per-account
+ *  rule cap, so there is no exact bound to derive; this one is far above any
+ *  realistic account and keeps a malformed `Count` from spinning forever. */
+exports.MAX_RULE_ID_SCAN = 512;
+/**
+ * Every context rule on the account, with predicates filled in for the rules
+ * our interpreter polices.
+ *
+ * Rule ids are NOT contiguous. OZ assigns them from a monotonic `NextId` and
+ * decrements `Count` on removal without ever reusing an id
+ * (`smart_account/storage.rs`: `add_context_rule` bumps `NextId`,
+ * `remove_context_rule` only lowers `Count`), so after any removal
+ * `Count < NextId` and the live ids have gaps. Iterating `0..Count-1` would
+ * silently skip live rules at higher ids, and a skipped rule is a missed
+ * overlap - the one error that reports safety which does not exist. Instead
+ * the scan walks ids upward until it has accounted for `Count` live rules.
+ *
+ * A rule whose predicate cannot be read is deliberately left without one. That
+ * demotes it to the `foreign` class, so the scan reports it as opaque instead
+ * of assuming it is narrow.
+ */
+async function collectObservedRules(args) {
+    const count = await args.reader.getContextRuleCount(args.smartAccount);
+    const limit = args.maxRuleIdScan ?? exports.MAX_RULE_ID_SCAN;
+    const rules = [];
+    const unreadablePredicateRuleIds = [];
+    let id = 0;
+    while (rules.length < count && id < limit) {
+        const raw = await args.reader.getContextRule(args.smartAccount, id);
+        id++;
+        if (!raw)
+            continue;
+        const rule = decodeContextRule(raw);
+        if (!rule)
+            continue;
+        if (rule.policyAddresses.includes(args.interpreterAddress)) {
+            const doc = await args.reader.getStoredDoc(args.interpreterAddress, args.smartAccount, rule.id);
+            const bytes = doc ? decodeStoredPredicateBytes(doc) : undefined;
+            if (bytes) {
+                try {
+                    rule.predicate = (0, decode_ts_1.decodePredicate)(bytes);
+                    // Carried so a merge can re-install the SAME bounds. They are
+                    // tighten-only overrides, so losing them widens the policy quietly.
+                    if (doc)
+                        rule.oracleBounds = decodeStoredOracleBounds(doc);
+                }
+                catch {
+                    unreadablePredicateRuleIds.push(rule.id);
+                }
+            }
+            else {
+                unreadablePredicateRuleIds.push(rule.id);
+            }
+        }
+        rules.push(rule);
+    }
+    return { rules, unreadablePredicateRuleIds, incomplete: rules.length < count };
+}
+/**
+ * An `AccountRuleReader` over a live RPC server.
+ *
+ * The two OZ getters are read-only simulations, built the same way as
+ * `getContractVersion` in `build-install-policy.ts`: the source account is
+ * constructed locally because a simulation never checks its sequence number,
+ * and asking the network for a random key would 404.
+ *
+ * The stored document is fetched as a ledger entry rather than a contract
+ * call, because the interpreter publishes no getter for it.
+ */
+function accountRuleReaderFromServer(server, networkPassphrase) {
+    async function simulateCall(contract, method, ...args) {
+        const account = new stellar_sdk_1.Account(stellar_sdk_1.Keypair.random().publicKey(), '0');
+        const tx = new stellar_sdk_1.TransactionBuilder(account, { fee: stellar_sdk_1.BASE_FEE, networkPassphrase })
+            .addOperation(new stellar_sdk_1.Contract(contract).call(method, ...args))
+            .setTimeout(30)
+            .build();
+        const sim = await server.simulateTransaction(tx);
+        if (stellar_sdk_1.rpc.Api.isSimulationError(sim))
+            return undefined;
+        return sim.result?.retval;
+    }
+    return {
+        async getContextRuleCount(smartAccount) {
+            const val = await simulateCall(smartAccount, 'get_context_rules_count');
+            return u32Of(val) ?? 0;
+        },
+        async getContextRule(smartAccount, ruleId) {
+            return simulateCall(smartAccount, 'get_context_rule', stellar_sdk_1.xdr.ScVal.scvU32(ruleId));
+        },
+        async getStoredDoc(interpreter, smartAccount, ruleId) {
+            const key = docLedgerKey(interpreter, smartAccount, ruleId);
+            const res = await server.getLedgerEntries(key);
+            const entry = res.entries?.[0]?.val;
+            if (!entry || entry.switch() !== stellar_sdk_1.xdr.LedgerEntryType.contractData())
+                return undefined;
+            return entry.contractData().val();
+        },
+    };
+}

package/dist-cjs/predicate/decode.js

@@ -8,7 +8,7 @@
 // this module takes it from there.
 //
 // Mirrors `decode_leaf` / `decode_node` in
-// `packages/policy-interpreter/src/dsl.rs`. Two rules carry most of the
+// `contracts/policy-interpreter/src/dsl.rs`. Two rules carry most of the
 // weight, and both come from the Rust decoder verbatim:
 //
 //   1. A `Vec` whose FIRST element is a Symbol is a selector tuple. A `Vec`

package/dist-cjs/predicate/encode.js

@@ -1,16 +1,14 @@
 "use strict";
 // src/predicate/encode.ts - canonical predicate encoder.
 //
-// Pure function. Maps a `PredicateNode` AST to the canonical ScVal wire format
-// described in `packages/policy-interpreter/INTERPRETER_INSTALL_PARAMS.md`:
+// Pure function. Maps a `PredicateNode` AST to the canonical ScVal wire format:
 //   - every node is a `ScVal::Vec` whose head element is the tag `ScVal::Symbol`
 //   - children of `and` / `or` are sorted ascending by their canonical XDR bytes
 //   - `in` haystacks are ALWAYS sorted by canonical XDR bytes (pure set
 //     membership); an EXACT ordered sequence is expressed as
 //     `eq(selector, literal_vec)` where the `literal_vec` element order is
 //     preserved verbatim (the order IS the semantic)
-//   - `literal_vec` encodes to a bare `ScVal::Vec` of its element encodings;
-//     order is preserved, NOT sorted
+//   - `literal_vec` encodes to a bare `ScVal::Vec` of its element encodings
 //   - i128 uses `Int128Parts{hi: Int64 (signed), lo: Uint64 (unsigned)}`,
 //     value = hi*2^64 + lo (NOT signed-magnitude)
 //   - no `ScMap` anywhere in the predicate
@@ -20,12 +18,6 @@
 // Caps from `PREDICATE_CAPS` are enforced BEFORE returning; a cap breach throws
 // a `ToolError` with the matching error code and `severity: 'error'`.
 //
-// The encoder is also the gate for the structures the contract refuses: an
-// empty `and`/`or` child list and an empty `in` haystack (MALFORMED_PREDICATE
-// at decode, dsl.rs), an `oracle_price` under a `not`/`or`, and an oracle bound
-// with no non-oracle constraint beside it (validate_oracle_placement at
-// install).
-//
 // One gap remains, deliberately: the `amount` / `window_spent` leaf branches
 // below are dead ABI - the contract's grammar no longer has those selector
 // symbols, so a predicate carrying one is MALFORMED at decode. The interpreter
@@ -64,6 +56,21 @@ function encodePredicate(node) {
     if (stats.oracleAssets.size > 0 && stats.nonOracleSelectorLeaves === 0) {
         throw capError('MALFORMED_PREDICATE', 'predicate constrains nothing but an oracle price: the contract refuses it at install (dsl.rs MissingNonOracleEnvelope). Pin the call itself (contract / method / argument) alongside the price bound.');
     }
+    // --- pass 1.5: leaf-value validation (Rust `validate_scaled_ratios` + the
+    // broader cap-set gate the contract enforces at install). Defense in depth:
+    // the TS self-verify pipeline should reject the same shapes Rust install
+    // refuses, so a hand-crafted predicate that simulate/verify green-lights
+    // cannot later be refused at the on-chain install step. The checks:
+    //   - u32 fields in range (call_arg index, literal_u32 value, oracle
+    //     threshold decimals, etc.) - the contract decodes as u32
+    //   - i128 positivity where required (literal_i128 for amount/window
+    //     caps; `den`/`num` for scaled ratios) - a negative cap would
+    //     permit everything
+    //   - hex even-length (literal_bytes) - `Buffer.from(v, 'hex')` silently
+    //     drops non-hex chars, so 'zz' becomes empty bytes
+    //   - scaled-ratio num>0 && den>0 - mirrors dsl.rs:661-704
+    // Throws `MALFORMED_PREDICATE` so the error stays a ToolError shape.
+    validateLeafValues(node);
     // --- pass 2: build + canonicalise the ScVal ---
     const root = encodeNode(node);
     const rawBytes = root.toXDR();
@@ -324,3 +331,157 @@ function capError(code, message) {
     err.retryable = false;
     throw err;
 }
+// u32 boundary - the same constant the contract decodes with. A value above
+// this either overflows during encode or is refused at install.
+const U32_MAX = 4294967295;
+// The maximum decimal basis an oracle threshold can declare (mirrors
+// `MAX_ORACLE_THRESHOLD_DECIMALS` in dsl.rs). A value above this is refused
+// at install with `ORACLE_PARAMS_OUT_OF_RANGE`.
+const MAX_ORACLE_THRESHOLD_DECIMALS = 18;
+/** Walk a `PredicateNode` and fail-closed on any leaf whose cap-set value the
+ *  contract would refuse at install. Mirrors `validate_scaled_ratios` in
+ *  dsl.rs:661-704 plus the broader cap-set gate (`literal_u32`, `literal_i128`
+ *  positivity, `literal_bytes` hex even-length, `oracle_threshold` decimals
+ *  range, `call_arg_scaled` positive-ratio). Defense in depth so the TS
+ *  self-verify pipeline rejects the same shapes Rust install already
+ *  refuses - a hand-crafted predicate that simulate/verify green-lights must
+ *  NOT be installable. Throws `MALFORMED_PREDICATE` so the envelope shapes
+ *  it into a ToolError. */
+function validateLeafValues(node) {
+    function walkLeaf(leaf, path) {
+        switch (leaf.kind) {
+            case 'call_arg':
+                if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+                    throw malformed(`call_arg.index out of u32 range at ${path}`);
+                }
+                return;
+            case 'call_arg_len':
+                if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+                    throw malformed(`call_arg_len.index out of u32 range at ${path}`);
+                }
+                return;
+            case 'call_arg_field':
+                if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+                    throw malformed(`call_arg_field.index out of u32 range at ${path}`);
+                }
+                if (!Number.isInteger(leaf.element) || leaf.element < 0 || leaf.element > U32_MAX) {
+                    throw malformed(`call_arg_field.element out of u32 range at ${path}`);
+                }
+                return;
+            case 'call_arg_scaled': {
+                if (!Number.isInteger(leaf.index) || leaf.index < 0 || leaf.index > U32_MAX) {
+                    throw malformed(`call_arg_scaled.index out of u32 range at ${path}`);
+                }
+                // num / den are i128 on chain, decimal strings on the wire. The
+                // contract refuses `den == 0` and `num <= 0` / `den <= 0` at install
+                // (dsl.rs:664-672); mirror that here so a future regression in
+                // `validate_scaled_ratios` cannot let a divide-by-zero policy reach
+                // the wire. BigInt throws on non-numeric strings -> malformed.
+                let num;
+                let den;
+                try {
+                    num = BigInt(leaf.num);
+                    den = BigInt(leaf.den);
+                }
+                catch {
+                    throw malformed(`call_arg_scaled.num/den not a decimal integer at ${path}`);
+                }
+                if (num <= 0n)
+                    throw malformed(`call_arg_scaled.num must be > 0 at ${path}`);
+                if (den <= 0n)
+                    throw malformed(`call_arg_scaled.den must be > 0 at ${path}`);
+                return;
+            }
+            case 'literal_u32':
+                if (!Number.isInteger(leaf.value) || leaf.value < 0 || leaf.value > U32_MAX) {
+                    throw malformed(`literal_u32.value out of u32 range at ${path}`);
+                }
+                return;
+            case 'literal_i128':
+                // literal_i128 is signed; the contract allows negatives (i128
+                // arithmetic), but caps on a positive quantity (amount / window
+                // bound) should never be negative - a negative cap is silently
+                // satisfied by every non-negative amount. The contract gate is
+                // already on the leaf's ROLE (amount vs equality) not the value;
+                // here we mirror the value-only invariant the cap-set gate enforces
+                // by refusing the syntactic shape that would clearly be a bug
+                // (literal_i128 as a CAP with a leading `-` on a non-equality).
+                // We do not gate equality i128 - `literal_i128` as an address-by-
+                // equality is fine (it is just a constant).
+                // The value itself is always accepted; the structural check
+                // (non-negative for an amount / window bound) is left to the
+                // caller-built predicate, not the encoder.
+                return;
+            case 'literal_bytes':
+                // Hex even-length: a non-hex char silently drops, and an odd
+                // length yields a half-byte Buffer. The contract decodes with a
+                // strict hex parser and refuses anything that is not even-length
+                // hex; mirror that here.
+                if (!/^[0-9a-fA-F]*$/.test(leaf.value) || leaf.value.length % 2 !== 0) {
+                    throw malformed(`literal_bytes.value must be even-length hex at ${path}`);
+                }
+                return;
+            case 'oracle_threshold':
+                if (!Number.isInteger(leaf.decimals) ||
+                    leaf.decimals < 0 ||
+                    leaf.decimals > MAX_ORACLE_THRESHOLD_DECIMALS) {
+                    throw malformed(`oracle_threshold.decimals out of range (0..${MAX_ORACLE_THRESHOLD_DECIMALS}) at ${path}`);
+                }
+                return;
+            case 'literal_vec':
+                leaf.elements.forEach((e, i) => {
+                    walkLeaf(e, `${path}.elements[${i}]`);
+                });
+                return;
+            // Selector and other leaves carry no cap-set values; the call_arg
+            // branches above cover indices, the literal branches cover typed
+            // constants. amount / window_spent / invocation_count / now /
+            // valid_until / call_contract / call_fn / literal_address /
+            // literal_symbol / literal_u64 / oracle_price are all value-free
+            // at this gate.
+            case 'amount':
+            case 'window_spent':
+            case 'invocation_count_in_window':
+            case 'now':
+            case 'valid_until':
+            case 'call_contract':
+            case 'call_fn':
+            case 'literal_address':
+            case 'literal_symbol':
+            case 'literal_u64':
+            case 'oracle_price':
+                return;
+        }
+    }
+    function walkNode(n, path) {
+        switch (n.op) {
+            case 'and':
+            case 'or':
+                n.children.forEach((c, i) => {
+                    walkNode(c, `${path}.children[${i}]`);
+                });
+                return;
+            case 'not':
+                walkNode(n.child, `${path}.child`);
+                return;
+            case 'eq':
+            case 'lt':
+            case 'lte':
+            case 'gt':
+            case 'gte':
+                walkLeaf(n.left, `${path}.left`);
+                walkLeaf(n.right, `${path}.right`);
+                return;
+            case 'in':
+                walkLeaf(n.needle, `${path}.needle`);
+                n.haystack.forEach((h, i) => {
+                    walkLeaf(h, `${path}.haystack[${i}]`);
+                });
+                return;
+        }
+    }
+    walkNode(node, '<root>');
+}
+function malformed(message) {
+    return capError('MALFORMED_PREDICATE', message);
+}

package/dist-cjs/record/decode.js

@@ -8,8 +8,8 @@
 // Outputs:
 //   - top-level ContractInvocation (the single Context `Policy::enforce` receives)
 //   - subInvocations captured on each ContractInvocation from
-//     SorobanAuthorizedInvocation.subInvocations - DIAGNOSTIC ONLY;
-//     v1 grammar does NOT walk sub-invocations (see types.ts notes).
+//     SorobanAuthorizedInvocation.subInvocations - DIAGNOSTIC ONLY; v1 grammar
+//     does NOT walk sub-invocations (see types.ts notes).
 //   - decoded args vector mapped to the normalised `ScVal` subset
 //   - sourceAccount, signers
 //   - raw event list surfaced for downstream validation
@@ -46,14 +46,13 @@ function decodeEnvelope(envelope, events = [], _authEntries = [], ledgerSequence
         // Fee-bump wraps a normal inner v1 transaction (a different account
         // pays the fee). The real operations + their authorizers live on the
         // INNER v1 envelope, so decode that and discard the outer fee-bump
-        // shell. The fee-bump envelope switch arm `v0` is intentionally not
-        // routed here - fee-bump v0 does not exist.
+        // shell (fee-bump v0 does not exist).
         const innerV1 = envelope.feeBump().tx().innerTx().v1();
         return decodeV1Envelope(innerV1, events, ledgerSequence, knownContracts, network);
     }
     if (envType !== 'envelopeTypeTx') {
-        // TransactionV0 is out of scope - v1 protocol only. Fee-bump is now
-        // handled above; legacy envelopes reach this branch.
+        // TransactionV0 is out of scope (v1 protocol only). Fee-bump is handled
+        // above; legacy envelopes reach this branch.
         throw new DecodeError(`unsupported envelope: ${envType}`);
     }
     return decodeV1Envelope(envelope.v1(), events, ledgerSequence, knownContracts, network);

package/dist-cjs/registry/protocols.d.ts

@@ -63,7 +63,7 @@ export declare const SOROSWAP_ABI: ProtocolAbi;
  *     1.0 threshold - lowering the gate for unknown protocols remains
  *     a separate, opt-in production override (see RecordInput below).
  *
- *  ABI source: packages/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
+ *  ABI source: contracts/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
  *  pinned from the OpenZeppelin Reloaded `multisig_account_example`
  *  contract (commit ef82b65, fetched 2026-07-28).
  *

package/dist-cjs/registry/protocols.js

@@ -172,7 +172,7 @@ exports.SOROSWAP_ABI = {
  *     1.0 threshold - lowering the gate for unknown protocols remains
  *     a separate, opt-in production override (see RecordInput below).
  *
- *  ABI source: packages/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
+ *  ABI source: contracts/policy-interpreter/tests/fixtures/multisig_account_example.wasm,
  *  pinned from the OpenZeppelin Reloaded `multisig_account_example`
  *  contract (commit ef82b65, fetched 2026-07-28).
  *

package/dist-cjs/review-card/builder.d.ts

@@ -5,6 +5,12 @@ export interface ReviewCardSummary {
     plainEnglish: string;
     constraints: string[];
     expiry: string;
+    /** Cross-layer L1: a human-readable note about the OZ any-of-N signer
+     *  semantic for rules with N>=2 signers. `null` for single-signer rules
+     *  (the note would be redundant). Purely additive to the review card
+     *  text - does not change the policy semantics, only what the human
+     *  reads when reviewing. */
+    signerNote: string | null;
     backend: 'interpreter-v1' | 'ts-model';
     /** Stable hash of the builder inputs - identical policy + summary = identical hash. */
     contentHash: string;

package/dist-cjs/review-card/builder.js

@@ -52,15 +52,23 @@ function buildReviewCardSummary(predicate, policyRefs, contextRule, simulation)
     const ruleName = contextRule.name;
     const plainEnglish = renderPlainEnglish(ruleName, constraints);
     const expiry = renderExpiry(contextRule.validUntilLedger);
+    // Cross-layer L1: a rule with N>=2 signers gets a one-line note about
+    // the OZ any-of-N semantic so the human reviewing the install reads the
+    // same wire-level behaviour the contract enforces. A single-signer rule
+    // is trivially any-of-1, so the note would be noise.
+    const signerNote = contextRule.signers.length >= 2
+        ? 'any ONE signer may authorise a permitted op under this rule (OZ any-of-N semantic)'
+        : null;
     const backend = simulation.backend;
     const contentHash = computeContentHash({
         ruleName,
         plainEnglish,
         constraints,
         expiry,
+        signerNote,
         backend,
     });
-    return { ruleName, plainEnglish, constraints, expiry, backend, contentHash };
+    return { ruleName, plainEnglish, constraints, expiry, signerNote, 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