@crediolabs/policy-synth 0.1.16 → 0.1.18

package/dist/install/build-add-context-rule.js

@@ -140,13 +140,12 @@ function encodePoliciesMap(args) {
     const entries = [];
     for (const ref of args.policies) {
         if (ref.kind === 'interpreter') {
-            const val = encodePolicyInstallParams(args);
             entries.push(new xdr.ScMapEntry({
                 key: Address.fromString(ref.interpreterAddress).toScVal(),
-                val,
+                val: encodePolicyInstallParams(args),
             }));
         }
-        if (ref.kind === 'oz_builtin') {
+        else if (ref.kind === 'oz_builtin') {
             entries.push(new xdr.ScMapEntry({
                 key: Address.fromString(ref.instanceAddress).toScVal(),
                 val: encodeOzPrimitiveParams(ref.primitive),
@@ -221,48 +220,20 @@ function encodePolicyInstallParams(args) {
     if (computedHash !== args.predicateHash) {
         throw limitError('INSTALL_BUILD_FAILED', `predicateHash ${args.predicateHash.slice(0, 16)}... does not match sha256(encodedPredicate) ${computedHash.slice(0, 16)}...`);
     }
-    const entries = [];
-    for (const k of POLICY_INSTALL_PARAM_FIELDS) {
-        const key = xdr.ScVal.scvSymbol(k);
-        switch (k) {
-            case 'grammar_version':
-                entries.push(new xdr.ScMapEntry({
-                    key,
-                    val: xdr.ScVal.scvU32(args.grammarVersion ?? DEFAULT_GRAMMAR_VERSION),
-                }));
-                break;
-            case 'install_nonce':
-                entries.push(new xdr.ScMapEntry({ key, val: xdr.ScVal.scvU32(args.installNonce) }));
-                break;
-            case 'predicate':
-                entries.push(new xdr.ScMapEntry({ key, val: xdr.ScVal.scvBytes(predicate) }));
-                break;
-            case 'predicate_hash':
-                entries.push(new xdr.ScMapEntry({
-                    key,
-                    val: xdr.ScVal.scvBytes(Buffer.from(args.predicateHash, 'hex')),
-                }));
-                break;
-            case 'oracle_max_staleness_seconds':
-                entries.push(new xdr.ScMapEntry({
-                    key,
-                    val: encodeOptionU32(args.oracleParams?.maxStalenessSeconds),
-                }));
-                break;
-            case 'oracle_max_deviation_bps':
-                entries.push(new xdr.ScMapEntry({
-                    key,
-                    val: encodeOptionU32(args.oracleParams?.maxDeviationBps),
-                }));
-                break;
-            case 'oracle_max_xfeed_dev_bps':
-                entries.push(new xdr.ScMapEntry({
-                    key,
-                    val: encodeOptionU32(args.oracleParams?.maxCrossFeedDeviationBps),
-                }));
-                break;
-        }
-    }
+    // Per-field value encoders. Each entry returns the ScVal to drop into the
+    // map; the key symbol comes from the surrounding loop. Adding a field is
+    // one row here plus the symbol in POLICY_INSTALL_PARAM_FIELDS.
+    const oracleParams = args.oracleParams;
+    const valueFor = {
+        grammar_version: () => xdr.ScVal.scvU32(args.grammarVersion ?? DEFAULT_GRAMMAR_VERSION),
+        install_nonce: () => xdr.ScVal.scvU32(args.installNonce),
+        predicate: () => xdr.ScVal.scvBytes(predicate),
+        predicate_hash: () => xdr.ScVal.scvBytes(Buffer.from(args.predicateHash, 'hex')),
+        oracle_max_staleness_seconds: () => encodeOptionU32(oracleParams?.maxStalenessSeconds),
+        oracle_max_deviation_bps: () => encodeOptionU32(oracleParams?.maxDeviationBps),
+        oracle_max_xfeed_dev_bps: () => encodeOptionU32(oracleParams?.maxCrossFeedDeviationBps),
+    };
+    const entries = POLICY_INSTALL_PARAM_FIELDS.map((k) => new xdr.ScMapEntry({ key: xdr.ScVal.scvSymbol(k), val: valueFor[k]() }));
     // The host orders map entries by the SYMBOL STRING, not by XDR bytes. A
     // length prefix in the XDR encoding would otherwise put `amount` before
     // `address` and produce a struct the contract reads differently. Emit the

package/dist/install/build-install-policy.d.ts

@@ -18,11 +18,10 @@ export interface InstallRpcClient {
  *  `getContractVersion` lookup uses `simulateTransaction` against
  *  `contract.call('grammar_version')` and decodes the returned u32.
  *
- *  The passphrase is a REQUIRED argument rather than something read off the
- *  server: `rpc.Server` does not carry one, so reaching for
- *  `server.networkPassphrase` yielded a non-string and every version probe
- *  died with "Invalid passphrase provided to Transaction". The caller knows
- *  which network it dialled; make it say so. */
+ *  The passphrase is a REQUIRED argument (not read off the server): `rpc.Server`
+ *  does not carry one, so reaching for `server.networkPassphrase` returned a
+ *  non-string and every version probe died with "Invalid passphrase provided to
+ *  Transaction". The caller knows which network it dialled; make it say so. */
 export declare function rpcClientFromServer(server: rpc.Server, networkPassphrase: string): InstallRpcClient;
 /** Inputs for the install-policy build. */
 export interface BuildInstallPolicyArgs {
@@ -115,6 +114,14 @@ export interface InstallCallDescribes {
         kind: 'external';
         verifier: string;
     }>;
+    /** Cross-layer L1: a human-readable note about the OZ any-of-N signer
+     *  semantic that fires for rules with multiple signers. Present only
+     *  when `signers.length >= 2` (a single-signer rule is trivially any-of-1,
+     *  and the note would just add noise). The note is purely additive to
+     *  the review card text - it does NOT alter the wire bytes or the
+     *  signer-set constraint, only the description a human reads before
+     *  signing the install. */
+    signerNote: string | null;
     /** One entry per policy attached to the rule, decoded from the policies
      *  map (args[4]). The address is the map key; the kind + extras below
      *  describe the value. The interpreter policy also reports the

package/dist/install/build-install-policy.js

@@ -1,24 +1,21 @@
-// src/install/build-install-policy.ts - builds the unsigned Soroban
-// transaction XDR for `account.add_context_rule(...)` and
-// `account.remove_context_rule(...)`.
+// src/install/build-install-policy.ts - builds the unsigned Soroban transaction
+// XDR for `account.add_context_rule(...)` and `account.remove_context_rule(...)`.
 //
-// The MCP server is stateless and holds no key material (server.ts:10-12),
-// so this module NEVER signs. The caller (the wallet / CLI / SDK consumer)
-// wraps the returned XDR in a transaction envelope and signs that envelope
-// with their wallet; the wallet signature IS the user-confirmation step.
+// The MCP server is stateless and holds no key material, so this module NEVER
+// signs. The caller (wallet / CLI / SDK consumer) wraps the returned XDR in a
+// transaction envelope and signs that envelope with their wallet; the wallet
+// signature IS the user-confirmation step.
 //
-// We deliberately depart from the spec in plans/phase-04 which calls for a
+// We deliberately depart from the original design, which called for a
 // two-call `install_policy`/`confirm_install` pair backed by a host-signed
-// short-TTL `action_id`. That contract requires (a) a stateful store and
-// (b) key material the server does not have, so we ship the simpler ONE-CALL
-// shape. The wallet signature covers the change.
+// short-TTL `action_id`. That contract requires stateful store + key material
+// the server does not have, so we ship the simpler ONE-CALL shape. The wallet
+// signature covers the change.
 //
 // `buildInstallPolicyXdr` installs the policy in ONE call. `add_context_rule`
 // takes `policies` as a `Map<policy_address, install_param>` and the account
 // forwards each install_param to that policy, so the interpreter stores the
-// predicate document as part of this same transaction. Earlier revisions
-// documented a second `interpreter.install` call; that was wrong, and issuing
-// it fails - the account re-enters the interpreter while it is mid-install.
+// predicate document as part of this same transaction.
 import { createHash } from 'node:crypto';
 import { Address, BASE_FEE, Contract, Keypair, Operation, rpc, scValToBigInt, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
 import { buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION } from "./build-add-context-rule.js";
@@ -27,11 +24,10 @@ import { accountEntry, authDigest, authPayload, delegatedSignerEntry, signatureP
  *  `getContractVersion` lookup uses `simulateTransaction` against
  *  `contract.call('grammar_version')` and decodes the returned u32.
  *
- *  The passphrase is a REQUIRED argument rather than something read off the
- *  server: `rpc.Server` does not carry one, so reaching for
- *  `server.networkPassphrase` yielded a non-string and every version probe
- *  died with "Invalid passphrase provided to Transaction". The caller knows
- *  which network it dialled; make it say so. */
+ *  The passphrase is a REQUIRED argument (not read off the server): `rpc.Server`
+ *  does not carry one, so reaching for `server.networkPassphrase` returned a
+ *  non-string and every version probe died with "Invalid passphrase provided to
+ *  Transaction". The caller knows which network it dialled; make it say so. */
 export function rpcClientFromServer(server, networkPassphrase) {
     return {
         getAccount: (address) => server.getAccount(address),
@@ -337,7 +333,7 @@ function decodeInstallCallDescribes(tx, expectedInstallNonce) {
         const tag = tuple[0]?.sym().toString();
         const inner = tuple[1];
         if (tag === 'Delegated') {
-            if (!inner || inner.switch().name !== 'scvAddress') {
+            if (inner?.switch().name !== 'scvAddress') {
                 throw new Error('install_policy: a Delegated signer is missing its Address');
             }
             signers.push({
@@ -347,7 +343,7 @@ function decodeInstallCallDescribes(tx, expectedInstallNonce) {
             continue;
         }
         if (tag === 'External') {
-            if (!inner || inner.switch().name !== 'scvAddress') {
+            if (inner?.switch().name !== 'scvAddress') {
                 throw new Error('install_policy: an External signer is missing its verifier Address');
             }
             signers.push({
@@ -389,12 +385,12 @@ function decodeInstallCallDescribes(tx, expectedInstallNonce) {
         // OZ primitives carry spending_limit/period_ledgers/threshold/signers.
         if (fields.has('predicate') || fields.has('grammar_version') || fields.has('install_nonce')) {
             const installNonceScv = fields.get('install_nonce');
-            if (!installNonceScv || installNonceScv.switch().name !== 'scvU32') {
+            if (installNonceScv?.switch().name !== 'scvU32') {
                 throw new Error(`install_policy: interpreter policy ${address} is missing a u32 install_nonce`);
             }
             const installNonce = installNonceScv.u32();
             const predicateScv = fields.get('predicate');
-            if (!predicateScv || predicateScv.switch().name !== 'scvBytes') {
+            if (predicateScv?.switch().name !== 'scvBytes') {
                 throw new Error(`install_policy: interpreter policy ${address} is missing its bytes predicate`);
             }
             const predicateBytes = Buffer.from(predicateScv.bytes());
@@ -435,12 +431,25 @@ function decodeInstallCallDescribes(tx, expectedInstallNonce) {
     // `observedInstallNonce` is the nonce baked into whichever interpreter
     // policy is present; when none, fall back to the caller-supplied value.
     const installNonce = observedInstallNonce ?? expectedInstallNonce;
+    // Cross-layer L1: OZ Accounts context rules follow any-of-N semantics for
+    // the signers they accept - any ONE attached signer may authorise a
+    // permitted op under the rule. A user with multiple signers attached
+    // therefore has a strict superset of authority of a single-signer rule,
+    // not a stricter one; the install succeeds as written, but a human
+    // reviewing the install card may expect the opposite (and choose the
+    // wrong threshold because of it). Surface the any-of-N note on the
+    // description so the human reads the same wire-level semantic the
+    // contract enforces.
+    const signerNote = signers.length >= 2
+        ? 'any ONE signer may authorise a permitted op under this rule (OZ any-of-N semantic)'
+        : null;
     return {
         targetContract,
         fnName: 'add_context_rule',
         ruleName,
         validUntilLedger,
         signers,
+        signerNote,
         policies,
         installNonce,
     };

package/dist/install/get-interpreter-info.js

@@ -9,9 +9,9 @@
 // Per design decision 5: phase-04's "audit #44" is aspirational and has no
 // source-of-truth in the repo. Returning a fabricated audit id would be a
 // lie on a security surface. The honest outputs are:
-//   - the pinned address (DEPLOYMENTS.md)
+//   - the pinned address (`PINNED_INTERPRETER_*_ADDRESS` in run/schemas.ts)
 //   - the pinned grammar version (SELF_VERSION in version.rs)
-//   - the pinned wasm sha256 (DEPLOYMENTS.md)
+//   - the pinned wasm sha256 (`PINNED_INTERPRETER_WASM_SHA256` in run/schemas.ts)
 //   - an OPTIONAL `deployedGrammarVersion` returned by a live `grammar_version()`
 //     RPC call, with a `liveMatchesPin` boolean the caller can dispatch on. A
 //     mismatch means the deployed wasm is NOT the pinned artifact - the caller

package/dist/install/index.d.ts

@@ -0,0 +1 @@
+export { ADD_CONTEXT_RULE_SYMBOL, type AddContextRuleArgs, type BuildAddContextRuleArgs, buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION, } from './build-add-context-rule.ts';

package/dist/install/index.js

@@ -0,0 +1,15 @@
+// Public entry for the install-argument builders.
+//
+// `buildAddContextRuleArgs` is the encoder `runInstallPolicy` uses to turn a
+// ContextRuleDraft into the `add_context_rule` arguments. It was reachable
+// only from inside this package, so a browser client that wants to build the
+// same call had the choice of re-implementing the encoding or going without.
+// Re-implementing it is not a real option: the interpreter compares
+// sha256(context_rule.signers) at enforce time, so an encoding that differs in
+// any field yields a rule that denies every call, and an omitted policy yields
+// one that permits every call. Both failure modes have happened.
+//
+// Exported here rather than from the package root to keep the root surface
+// about synthesis, and because these are transaction-building primitives whose
+// callers should know they are reaching for them.
+export { ADD_CONTEXT_RULE_SYMBOL, buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION, } from "./build-add-context-rule.js";

package/dist/install/oz-auth.js

@@ -31,9 +31,11 @@ const u32 = (n) => xdr.ScVal.scvU32(n);
 const vec = (i) => xdr.ScVal.scvVec(i);
 const bytes = (b) => xdr.ScVal.scvBytes(b);
 function struct(fields) {
-    return xdr.ScVal.scvMap(Object.keys(fields)
-        .sort()
-        .map((k) => new xdr.ScMapEntry({ key: sym(k), val: fields[k] })));
+    // Entries sorted by key with the default string comparison - ScMap
+    // encoding requires the same order Object.keys().sort() produced.
+    return xdr.ScVal.scvMap(Object.entries(fields)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => new xdr.ScMapEntry({ key: sym(k), val: v })));
 }
 /** `Signer::Delegated(addr)`. */
 export const delegatedSigner = (a) => vec([sym('Delegated'), new Address(a).toScVal()]);

package/dist/predicate/decode.js

@@ -7,7 +7,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/predicate/encode.js

@@ -1,15 +1,13 @@
 // 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
@@ -19,12 +17,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
@@ -61,6 +53,21 @@ export 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();
@@ -321,3 +328,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/record/decode.js

@@ -7,8 +7,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
@@ -31,14 +31,13 @@ export function decodeEnvelope(envelope, events = [], _authEntries = [], ledgerS
         // 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/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/registry/protocols.js

@@ -168,7 +168,7 @@ export const 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/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/review-card/builder.js

@@ -48,15 +48,23 @@ export function buildReviewCardSummary(predicate, policyRefs, contextRule, simul
     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

package/dist/run/index.d.ts

@@ -9,6 +9,7 @@ export type RunRecordTransactionInput = RecordTransactionInput;
 export type RunSynthesizePolicyInput = SynthesizePolicyInput;
 export type RunSimulatePolicyInput = SimulatePolicyInput;
 export type RunVerifyPolicyInput = VerifyPolicyInput;
+type RunToolName = 'record_transaction' | 'synthesize_policy' | 'simulate_policy' | 'verify_policy' | 'install_policy' | 'revoke_policy' | 'get_interpreter_info';
 /** `record_transaction` body - wraps `recordTransaction`. The tool input
  *  matches the core RecordInput minus the injected `fetcher` (the transport
  *  layer does not own the RPC). Returns the core ToolResponse unchanged.
@@ -86,20 +87,20 @@ export declare function runRevokePolicy(raw: unknown): Promise<ToolResponse<Buil
  *  Network-aware: `input.network` selects which interpreter pin and RPC
  *  to use. Mainnet was rolled out 2026-08-04 - the same wasm hash was
  *  uploaded to mainnet as was exercised on testnet, so a single
- *  `PINNED_INTERPRETER_WASM_SHA256` constant backs both networks
- *  (DEPLOYMENTS.md:25-27). The address differs because instance ids are
- *  network-scoped. UNAUDITED at the time of writing - see
- *  DEPLOYMENTS.md:29-32 for what is still pending. */
+ *  `PINNED_INTERPRETER_WASM_SHA256` constant backs both networks.
+ *  The address differs because instance ids are network-scoped.
+ *  UNAUDITED at the time of writing.
+ *
+ *  Same RPC pin as install/revoke: when `verifyLive` triggers an outbound
+ *  call, the auth-digest + the answer bind to whichever RPC answered, so
+ *  a non-pinned `rpcUrl` would silently bind the caller to a host they
+ *  picked. The pin is enforced here too, with the same `allowUnpinnedRpcUrl`
+ *  opt-in as install/revoke. */
 export declare function runGetInterpreterInfo(raw: unknown): Promise<ToolResponse<ReturnType<typeof getInterpreterInfo>>>;
 /** Build a canonical ToolError for a thrown exception caught by the tool
  *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
  *  default, so we extract a string-friendly message and tag the original
- *  error in `details` for the agent to inspect. The `code` is the tool's
- *  domain code (RECORDING_FAILED for `record_transaction`, SYNTHESIS_ERROR
- *  for `synthesize_policy`) so the agent dispatches on the same code the
- *  structured ToolError would carry.
- *
- *  Exported as `_caughtError` (the leading underscore signals the test-only
- *  seam) so the suite in run/index.test.ts can drive the envelope path
- *  without standing up a full recordTransaction pipeline. */
-export declare function caughtError(toolName: 'record_transaction' | 'synthesize_policy' | 'simulate_policy' | 'verify_policy' | 'install_policy' | 'revoke_policy' | 'get_interpreter_info', code: ErrorCode, e: unknown): ToolError;
+ *  error in `details` for the agent to inspect. Exported as a test-only seam
+ *  so the suite in run/index.test.ts can drive the envelope path without
+ *  standing up a full recordTransaction pipeline. */
+export declare function caughtError(toolName: RunToolName, code: ErrorCode, e: unknown): ToolError;