@crediolabs/policy-synth 0.1.17 → 0.2.0

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

@@ -2,26 +2,9 @@
 // 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>`
+// carrying the canonical predicate encoding from `predicate/encode.ts`. Second
+// backend (the OZ built-in adapter is the first); the compose step (P3) routes
+// IR constructs between them.
 //
 // Three fail-closed enforcement gates (per spec):
 //   - oracle_price leaves MUST sit directly under the top-level `and`; nesting
@@ -43,7 +26,7 @@ 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).
+/** Wasm-level oracle defaults (mirrors the interpreter's `OracleParams`).
  *  Per-policy overrides may TIGHTEN only - they may never exceed these. */
 exports.ORACLE_DEFAULTS = {
     maxStalenessSeconds: 600,
@@ -52,17 +35,15 @@ exports.ORACLE_DEFAULTS = {
 const CAPABILITIES = {
     supportsSpendWindow: true,
     supportsThreshold: false, // thresholds are the OZ adapter's job
-    // False for the predicate-leaf path: the interpreter refuses a `valid_until`
-    // leaf at install. Expiry is still available, but as the context rule's
-    // validUntilLedger, which the smart account enforces - not as a predicate.
+    // Expiry is via the context rule's validUntilLedger, not a predicate - the
+    // interpreter refuses a `valid_until` leaf at install.
     supportsTimeExpiry: false,
     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. */
+/** Parse confidence for a deterministic (non-decoded) input: full (1.0). A
+ *  mandate needs no decoding, so the gate is not applicable. */
 const FULL_PARSE_CONFIDENCE = {
     overall: 1,
     knownContracts: [],
@@ -82,12 +63,11 @@ function createInterpreterAdapter(config) {
 }
 /** 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)`. */
+ *  `compile(ir)` succeeds it 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 is NOT re-derived - callers needing it must use
+ *  `compile(ir)`. */
 function lowerRuleToPredicate(rule, config) {
     return lowerRule(rule, config).predicate;
 }
@@ -137,9 +117,9 @@ function compile(ir, config) {
 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`).
+    // their own `eq` leaf and are merged into the top-level `and` alongside the
+    // constraints. The top-level MUST be `and` so oracle leaves sit directly
+    // under it (mandatory per the oracle position rule + canonical hash stability).
     const scopeContract = rule.scope.contract;
     const scopeMethod = rule.scope.method;
     if (rule.scope.chainId !== undefined) {
@@ -247,18 +227,18 @@ function unsupportedConstruct(cond) {
                 return 'EVM calldata comparison (predicate DSL)';
             if (s.kind === 'value')
                 return 'tx.value comparison (predicate DSL)';
-            // The on-chain interpreter sees ONE authorized call - there is no
-            // `Context.sub_invocations` in v1 - so it cannot observe the
-            // transaction's token movements. `amount` has no value to read, and
-            // `window_spent` accumulates BY that amount, so its counter would never
-            // move. Deriving either from the call payload would quietly swap "value
+            // The on-chain interpreter sees ONE authorized call - no
+            // `Context.sub_invocations` in v1 - so it cannot observe token
+            // movements. `amount` has no value to read, and `window_spent`
+            // accumulates BY that amount, so its counter would never move.
+            // Deriving either from the call payload would quietly swap "value
             // actually moved" for "value the caller declared" - a weaker guarantee
             // than the review card would be claiming.
             //
-            // Rolling spend caps belong to the OZ `spending_limit` primitive, which
-            // is already audited and which the OZ adapter emits. A per-call cap is
-            // expressible here as `arg_field`; bounding it with `invocation_count`
-            // gives an enforceable ceiling per window.
+            // Rolling spend caps belong to the OZ `spending_limit` primitive (already
+            // audited, emitted by the OZ adapter). A per-call cap is expressible here
+            // as `arg_field`; bounding it with `invocation_count` gives an enforceable
+            // ceiling per window.
             return unsourceableSelector(s);
         }
         // Recurse: a nested `and`/`or`/`not` must not smuggle a selector past the
@@ -372,9 +352,9 @@ function lowerSelector(s) {
         case 'arg_field':
             return { kind: 'call_arg_field', index: s.argIndex, element: s.element, field: s.field };
         // `amount` / `window_spent` are filtered out by `unsupportedConstruct`
-        // before lowering - the interpreter cannot source either on chain. Reaching
-        // here means the pre-scan was bypassed, so fail loudly rather than emit a
-        // leaf the contract will refuse.
+        // before lowering - the interpreter cannot source either on chain.
+        // Reaching here means the pre-scan was bypassed; fail loudly rather than
+        // emit a leaf the contract will refuse.
         case 'amount':
         case 'window_spent':
             throw new Error(`interpreter adapter cannot lower \`${s.kind}\`: it should have been reported as uncovered`);

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

@@ -10,7 +10,7 @@
 // Anything needing a capability this backend lacks (oracle price, invocation
 // count, per-arg comparison/allowlist, guard, nested boolean predicate) is NOT
 // emitted: it is named in `uncovered` and `covered` is set false. Nothing is
-// silently dropped - the uncovered constructs are named instead.
+// silently dropped.
 //
 // OZ built-in policy instance addresses are per-network deploy artifacts we do
 // not have yet (install is a later phase). They are injected via config; week-1
@@ -32,9 +32,8 @@ exports.PLACEHOLDER_OZ_INSTANCES = {
 function placeholderOzConfig(network) {
     return { network, instances: exports.PLACEHOLDER_OZ_INSTANCES };
 }
-/** 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. */
+/** Parse confidence for a deterministic (non-decoded) input: full (1.0). A
+ *  mandate needs no decoding, so the gate is not applicable. */
 const FULL_PARSE_CONFIDENCE = {
     overall: 1,
     knownContracts: [],
@@ -88,10 +87,10 @@ function compile(ir, config) {
 function lowerRule(rule, config) {
     const uncovered = [];
     const policyRefs = [];
-    // scope -> context rule type. OZ scopes by contract (CallContract); a finer
-    // method-level restriction is a predicate concern and must be flagged as not
-    // covered because CallContract alone permits other methods on the same contract
-    // (e.g. an unbounded approve alongside a capped transfer).
+    // scope -> context rule type. OZ scopes by contract (CallContract); a
+    // method-level restriction is flagged as not covered because CallContract
+    // alone permits other methods on the same contract (e.g. an unbounded approve
+    // alongside a capped transfer).
     const contextRuleType = rule.scope.contract !== undefined
         ? { kind: 'call_contract', contract: rule.scope.contract }
         : { kind: 'default' };
@@ -120,8 +119,8 @@ function lowerRule(rule, config) {
         uncovered.push(`guard: ${describeCondition(rule.guard)}`);
     }
     // constraints -> spending_limit where they match; else not covered. The OZ
-    // spending_limit policy takes `{ spending_limit: i128, period_ledgers: u32 }`
-    // and has NO token param: it only accepts a CallContract context rule
+    // spending_limit takes `{ spending_limit: i128, period_ledgers: u32 }` and
+    // has NO token param: it only accepts a CallContract context rule
     // (OnlyCallContractAllowed) and limits transfers of that context's contract,
     // so the spent token must equal the scope contract, and the window is a
     // ledger count (~5s/ledger), not seconds.
@@ -149,7 +148,7 @@ function lowerRule(rule, config) {
     }
     // approval.threshold -> simple/weighted threshold primitive. A threshold < 1
     // is not a real M-of-N gate (0 approvals authorises everything), so refuse to
-    // emit a no-op primitive and flag it as not covered instead.
+    // emit a no-op primitive and flag it as not covered.
     if (rule.approval) {
         if (!Number.isInteger(rule.approval.threshold) || rule.approval.threshold < 1) {
             uncovered.push(`approval threshold ${rule.approval.threshold} is not a positive integer (a 0 or negative threshold is not an M-of-N gate)`);
@@ -213,8 +212,8 @@ function matchSpendingLimit(c) {
 function describeCondition(cond) {
     switch (cond.op) {
         case 'slippage_floor':
-            // The OZ primitives bound a value against a constant; this bounds one
-            // call argument against another, which none of them can express.
+            // OZ primitives bound a value against a constant; this bounds one call
+            // argument against another, which none of them can express.
             return `slippage floor on arg[${cond.outArgIndex}] (OZ built-ins cannot bound one argument against another)`;
         case 'in':
             return `value allowlist on ${describeSelector(cond.selector)} (arg allowlist)`;

package/dist-cjs/codegen/compile-gate.js

@@ -79,6 +79,11 @@ publish = false
 
 [lib]
 crate-type = ["cdylib"]
+# The gate writes the source beside the manifest rather than under src/, so
+# the path is stated. Without it cargo looks for src/lib.rs and fails to
+# parse the manifest before it ever compiles anything, which reads as a
+# broken generator rather than a broken scaffold.
+path = "lib.rs"
 
 [dependencies]
 soroban-sdk = "22"

package/dist-cjs/codegen/template.js

@@ -2,6 +2,23 @@
 // src/codegen/template.ts - deterministic Rust source generator for the OZ
 // `Policy` escape-hatch skeleton.
 //
+// SUPERSEDED. The architecture this belongs to no longer exists. A deployed
+// policy involves exactly two contracts, the OZ smart account and one
+// immutable interpreter, and the synthesiser emits policy DATA rather than
+// code. Nothing on the synthesis path reaches this module, and no install can
+// produce a contract from it. When a constraint falls outside the grammar the
+// answer is to version the synthesiser and the interpreter together, not to
+// put unaudited Rust on chain per policy.
+//
+// Deleting it is a decision nobody has taken yet, not a dependency question.
+// `compile-gate.ts` takes a Rust string and knows nothing about this module,
+// and its tests compile a hardcoded fixture, so the gate keeps working either
+// way. What deleting this would remove is the only in-repo producer of policy
+// Rust for the gate to check. Do not read its presence as the product
+// generating contracts, and do not wire it into the synthesis path.
+//
+// What follows describes the abandoned design.
+//
 // This is the LAST-RESORT tool for constraints the v1 DSL cannot express. It
 // lives OUT of the audited happy-path surface; the synthesiser never emits it
 // automatically. It mirrors Zodiac Roles' `Custom` operator: a hand-written

package/dist-cjs/install/authority-overlap.d.ts

@@ -0,0 +1,134 @@
+import type { PredicateNode, SignerDraft } from '../types.ts';
+/** Wildcard component of a `Selector`: the predicate does not pin this half. */
+export declare const ANY = "*";
+/** A (contract, function) pair a predicate may permit. `ANY` in either half
+ *  means unconstrained, so `{contract: ANY, fn: ANY}` is "any call at all". */
+export interface Selector {
+    contract: string;
+    fn: string;
+}
+export type ContextType = {
+    kind: 'default';
+} | {
+    kind: 'call_contract';
+    address: string;
+} | {
+    kind: 'create_contract';
+    wasmHash: string;
+};
+/** How much we can say about a neighbouring rule.
+ *  - `interpreter`: policed by our interpreter and the predicate was readable,
+ *    so its authority is known exactly and it can be merged.
+ *  - `foreign`: policed by some other contract. The address is visible, the
+ *    semantics are not, so it must be reviewed by hand.
+ *  - `unpoliced`: no policy at all. Whatever the rule's context type allows,
+ *    its signers may do without constraint. */
+export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced';
+export interface ObservedRule {
+    id: number;
+    contextType: ContextType;
+    signers: SignerDraft[];
+    /** Policy contract addresses attached to the rule, in OZ's order. */
+    policyAddresses: string[];
+    /** OZ's global registry ids for those policies, index-aligned with
+     *  `policyAddresses`. `remove_policy` takes the id, not the address, so
+     *  detaching a policy is impossible without them. */
+    policyIds?: number[];
+    /** Per-policy oracle bounds from the stored document, when it was
+     *  readable. A merge must re-install these or it silently widens them. */
+    oracleBounds?: {
+        maxStalenessSeconds?: number;
+        maxDeviationBps?: number;
+        maxCrossFeedDeviationBps?: number;
+    };
+    /** Decoded predicate. Present only when the rule is policed by our
+     *  interpreter AND the stored document was readable. */
+    predicate?: PredicateNode;
+}
+export interface IntendedInstall {
+    /** Rule the predicate is being installed onto. A re-install onto the same
+     *  id is a replacement, not an overlap, so this id is skipped. */
+    ruleId: number;
+    contextType: ContextType;
+    signers: SignerDraft[];
+    predicate: PredicateNode;
+}
+export type OverlapSeverity = 
+/** A neighbouring rule imposes no constraint at all on the shared calls. */
+'bypass'
+/** A neighbouring policy exists but we cannot read what it permits. */
+ | 'unknown'
+/** Both rules are ours. The new rule will not restrict the shared calls,
+ *  because the signer can name whichever rule is more permissive. */
+ | 'not-restricting';
+export interface AuthorityOverlap {
+    ruleId: number;
+    ruleClass: RuleClass;
+    severity: OverlapSeverity;
+    /** Signers present in both rules. Overlap is only reachable by a signer who
+     *  can name both rules, so a rule sharing no signer is not a collision. */
+    sharedSigners: SignerDraft[];
+    /** The selectors both rules can serve. Non-empty by construction. */
+    sharedSelectors: Selector[];
+    /** True when the neighbour is ours and can therefore be replaced by the
+     *  conjunction of the two predicates. */
+    mergeable: boolean;
+    advice: string;
+}
+/** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
+ *  signer is its address, an external signer is the verifier plus the key
+ *  bytes, since one verifier may hold many keys. */
+export declare function signerKey(s: SignerDraft): string;
+/** Intersection of two selector SETS: every compatible pairing survives. */
+export declare function intersectSelectors(a: Selector[], b: Selector[]): Selector[];
+/**
+ * The set of `(contract, fn)` selectors a predicate may permit.
+ *
+ * This is a deliberate OVER-approximation: every call the predicate actually
+ * permits is covered by some returned selector, and unrecognised structure
+ * widens to the wildcard rather than narrowing. That direction is what makes
+ * the emptiness test below sound. A call carries exactly one `(contract, fn)`,
+ * so if two predicates' over-approximations do not intersect, no single call
+ * can be routed to either of them and the rules provably cannot collide.
+ *
+ * `not` is treated as unconstrained. Complementing a selector set would need
+ * the universe of addresses and function names, which is not available and
+ * would not be sound to guess.
+ */
+export declare function permittedSelectors(node: PredicateNode): Selector[];
+/** Selectors a context type admits, before the predicate narrows them. */
+export declare function selectorsForContextType(ct: ContextType): Selector[];
+/** What a rule can actually authorise: its context type narrowed by its
+ *  predicate. An unpoliced or unreadable rule contributes no narrowing. */
+export declare function effectiveSelectors(rule: ObservedRule): Selector[];
+/**
+ * Every existing rule that a signer of the intended install could name instead.
+ *
+ * A rule collides when it shares at least one signer AND at least one selector,
+ * because both conditions are needed for the signer to have a choice. The rule
+ * being installed onto is skipped: re-installing over it replaces its
+ * predicate rather than adding a second source of authority.
+ */
+export declare function findAuthorityOverlaps(args: {
+    intended: IntendedInstall;
+    existing: ObservedRule[];
+}): AuthorityOverlap[];
+export interface MergeResult {
+    ok: boolean;
+    predicate?: PredicateNode;
+    /** Set when `ok` is false. */
+    reason?: string;
+}
+/**
+ * Conjunction of an existing predicate with a new one, for the tightening case.
+ *
+ * `and` children are flattened so repeated merges do not nest, which keeps the
+ * encoded form closer to the byte cap.
+ *
+ * The guard matters more than the merge. `and` is only correct when the caller
+ * means to tighten. Applied to two predicates that pin DIFFERENT selectors it
+ * produces a predicate permitting nothing, which silently disables the policy
+ * instead of restricting it. That case is refused, because the caller wanted
+ * two capabilities and two rules already express that correctly.
+ */
+export declare function mergeIntoAnd(existing: PredicateNode, incoming: PredicateNode): MergeResult;

package/dist-cjs/install/build-add-context-rule.d.ts

@@ -46,3 +46,11 @@ export type AddContextRuleArgs = readonly [
 /** Build the `add_context_rule` invocation args. Throws a `ToolError`-shaped
  *  error on limit breaches or malformed input. */
 export declare function buildAddContextRuleArgs(draft: ContextRuleDraft, args: BuildAddContextRuleArgs): AddContextRuleArgs;
+/** The `PolicyInstallParams` ScVal an interpreter policy receives.
+ *
+ *  Exported so the merge remedy can re-install a policy through `add_policy`
+ *  using the SAME encoder as a fresh install. Re-implementing it would risk
+ *  exactly the drift this file warns about: the field order is ABI-significant
+ *  and a differing encoding yields a rule that denies every call. */
+export type PolicyInstallParamArgs = Pick<BuildAddContextRuleArgs, 'encodedPredicate' | 'predicateHash' | 'installNonce' | 'oracleParams' | 'grammarVersion'>;
+export declare function encodePolicyInstallParams(args: PolicyInstallParamArgs): xdr.ScVal;

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

@@ -50,6 +50,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ADD_CONTEXT_RULE_SYMBOL = exports.DEFAULT_GRAMMAR_VERSION = void 0;
 exports.buildAddContextRuleArgs = buildAddContextRuleArgs;
+exports.encodePolicyInstallParams = encodePolicyInstallParams;
 const node_crypto_1 = require("node:crypto");
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const types_ts_1 = require("../types.js");
@@ -144,13 +145,12 @@ function encodePoliciesMap(args) {
     const entries = [];
     for (const ref of args.policies) {
         if (ref.kind === 'interpreter') {
-            const val = encodePolicyInstallParams(args);
             entries.push(new stellar_sdk_1.xdr.ScMapEntry({
                 key: stellar_sdk_1.Address.fromString(ref.interpreterAddress).toScVal(),
-                val,
+                val: encodePolicyInstallParams(args),
             }));
         }
-        if (ref.kind === 'oz_builtin') {
+        else if (ref.kind === 'oz_builtin') {
             entries.push(new stellar_sdk_1.xdr.ScMapEntry({
                 key: stellar_sdk_1.Address.fromString(ref.instanceAddress).toScVal(),
                 val: encodeOzPrimitiveParams(ref.primitive),
@@ -225,48 +225,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 = stellar_sdk_1.xdr.ScVal.scvSymbol(k);
-        switch (k) {
-            case 'grammar_version':
-                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
-                    key,
-                    val: stellar_sdk_1.xdr.ScVal.scvU32(args.grammarVersion ?? exports.DEFAULT_GRAMMAR_VERSION),
-                }));
-                break;
-            case 'install_nonce':
-                entries.push(new stellar_sdk_1.xdr.ScMapEntry({ key, val: stellar_sdk_1.xdr.ScVal.scvU32(args.installNonce) }));
-                break;
-            case 'predicate':
-                entries.push(new stellar_sdk_1.xdr.ScMapEntry({ key, val: stellar_sdk_1.xdr.ScVal.scvBytes(predicate) }));
-                break;
-            case 'predicate_hash':
-                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
-                    key,
-                    val: stellar_sdk_1.xdr.ScVal.scvBytes(Buffer.from(args.predicateHash, 'hex')),
-                }));
-                break;
-            case 'oracle_max_staleness_seconds':
-                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
-                    key,
-                    val: encodeOptionU32(args.oracleParams?.maxStalenessSeconds),
-                }));
-                break;
-            case 'oracle_max_deviation_bps':
-                entries.push(new stellar_sdk_1.xdr.ScMapEntry({
-                    key,
-                    val: encodeOptionU32(args.oracleParams?.maxDeviationBps),
-                }));
-                break;
-            case 'oracle_max_xfeed_dev_bps':
-                entries.push(new stellar_sdk_1.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: () => stellar_sdk_1.xdr.ScVal.scvU32(args.grammarVersion ?? exports.DEFAULT_GRAMMAR_VERSION),
+        install_nonce: () => stellar_sdk_1.xdr.ScVal.scvU32(args.installNonce),
+        predicate: () => stellar_sdk_1.xdr.ScVal.scvBytes(predicate),
+        predicate_hash: () => stellar_sdk_1.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 stellar_sdk_1.xdr.ScMapEntry({ key: stellar_sdk_1.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-cjs/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-cjs/install/build-install-policy.js

@@ -1,25 +1,22 @@
 "use strict";
-// 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.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_GRAMMAR_VERSION = exports.Contract = void 0;
 exports.rpcClientFromServer = rpcClientFromServer;
@@ -35,11 +32,10 @@ const oz_auth_ts_1 = require("./oz-auth.js");
  *  `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. */
 function rpcClientFromServer(server, networkPassphrase) {
     return {
         getAccount: (address) => server.getAccount(address),
@@ -345,7 +341,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({
@@ -355,7 +351,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({
@@ -397,12 +393,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());
@@ -443,12 +439,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,
     };