@crediolabs/policy-synth 0.1.17 → 0.2.0

package/dist/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/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/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),
@@ -215,54 +214,26 @@ function encodeI128(value) {
         lo: new xdr.Uint64(BigInt.asUintN(64, v)),
     }));
 }
-function encodePolicyInstallParams(args) {
+export function encodePolicyInstallParams(args) {
     const predicate = Buffer.from(args.encodedPredicate, 'base64');
     const computedHash = createHash('sha256').update(predicate).digest('hex');
     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/build-merge-policy.d.ts

@@ -0,0 +1,70 @@
+import type { InstallRpcClient } from './build-install-policy.ts';
+import type { MergeStep } from './plan-merge-policy.ts';
+/**
+ * The context rule the merge authorises AGAINST, which is not the rule being
+ * merged.
+ *
+ * Both calls mutate the smart account itself, so they need the account's own
+ * authorisation, and this builder asks rule 0 for it - the same assumption the
+ * install and revoke builders make. OpenZeppelin does NOT enforce any
+ * admin semantic for rule 0: it is simply the first rule the account's
+ * constructor created, and OZ's reference account creates it as `Default`
+ * covering every context.
+ *
+ * The assumption is therefore load-bearing and unverified at build time. If
+ * rule 0 does not exist, does not cover `CallContract(<smart account>)`, or
+ * does not list the source account as a signer, the transaction is built and
+ * then fails when submitted, and the operator pays the fee for a transaction
+ * that was never signable. Changing it is a wire-visible change: the id is
+ * hashed into the auth digest.
+ */
+export declare const ADMIN_CONTEXT_RULE_ID = 0;
+export interface BuildMergePolicyArgs {
+    smartAccount: string;
+    sourceAccount: string;
+    networkPassphrase: string;
+    ruleId: number;
+    /** OZ registry id of the interpreter policy on this rule, from the plan. */
+    policyId: number;
+    interpreterAddress: string;
+    step: MergeStep;
+    /** Only needed for `reinstall`: the merged predicate, already encoded. */
+    encodedPredicate?: string;
+    predicateHash?: string;
+    /** Nonce for the reinstall. Read from chain rather than assumed: a detach
+     *  whose uninstall panicked leaves the old nonce in place. */
+    installNonce?: number;
+    /** Oracle bounds to carry over from the document being replaced. */
+    oracleParams?: {
+        maxStalenessSeconds?: number;
+        maxDeviationBps?: number;
+        maxCrossFeedDeviationBps?: number;
+    };
+    rpc: InstallRpcClient;
+    baseFee?: number;
+    authValidUntilLedgers?: number;
+}
+export interface BuildMergePolicyResult {
+    unsignedXdr: string;
+    smartAccount: string;
+    sourceAccount: string;
+    step: MergeStep;
+    call: {
+        contract: string;
+        fn: 'remove_policy' | 'add_policy';
+        ruleId: number;
+    };
+    authNonce: string;
+    authValidUntilLedger: number;
+    rootInvocationXdr: string;
+}
+/**
+ * Build the unsigned transaction for one step of the merge.
+ *
+ * The auth dance mirrors `buildRevokePolicyXdr`: simulate once to record the
+ * account's auth entry, rebuild with the payload bound to that recorded
+ * `rootInvocation`, then assemble. Binding to the recorded invocation rather
+ * than to the input arguments is what makes the signature commit to the exact
+ * rule and policy being changed.
+ */
+export declare function buildMergePolicyXdr(args: BuildMergePolicyArgs): Promise<BuildMergePolicyResult>;

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

@@ -0,0 +1,130 @@
+//! Transactions for the merge remedy.
+//!
+//! `plan-merge-policy.ts` decides WHAT should happen; this builds the XDR for
+//! the step the caller asked for. Two calls, in order, because OZ refuses to
+//! attach a policy that is already on the rule:
+//!
+//!   step 1 `detach`    -> `account.remove_policy(rule_id, policy_id)`
+//!   step 2 `reinstall` -> `account.add_policy(rule_id, interpreter, param)`
+//!
+//! The two cannot be emitted together. Simulating step 2 while the old
+//! attachment is still there hits `DuplicatePolicy`, so the second transaction
+//! is only buildable once the first has confirmed.
+//!
+//! Both calls route through the smart account and are authorised the same way
+//! as `revoke_policy`: against the deploy-time admin rule, with the recorded
+//! `rootInvocation` binding the auth payload to this exact rule and policy.
+//! Detaching runs our `uninstall`, which is master-gated, so the signer has to
+//! be a master of the rule either way.
+import { Account, Address, BASE_FEE, Operation, rpc, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
+import { DEFAULT_GRAMMAR_VERSION, encodePolicyInstallParams } from "./build-add-context-rule.js";
+import { accountEntry, authDigest, authPayload, delegatedSignerEntry, signaturePayload, } from "./oz-auth.js";
+/** Matches the window the install and revoke builders use. */
+const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 100;
+/**
+ * The context rule the merge authorises AGAINST, which is not the rule being
+ * merged.
+ *
+ * Both calls mutate the smart account itself, so they need the account's own
+ * authorisation, and this builder asks rule 0 for it - the same assumption the
+ * install and revoke builders make. OpenZeppelin does NOT enforce any
+ * admin semantic for rule 0: it is simply the first rule the account's
+ * constructor created, and OZ's reference account creates it as `Default`
+ * covering every context.
+ *
+ * The assumption is therefore load-bearing and unverified at build time. If
+ * rule 0 does not exist, does not cover `CallContract(<smart account>)`, or
+ * does not list the source account as a signer, the transaction is built and
+ * then fails when submitted, and the operator pays the fee for a transaction
+ * that was never signable. Changing it is a wire-visible change: the id is
+ * hashed into the auth digest.
+ */
+export const ADMIN_CONTEXT_RULE_ID = 0;
+function hostFunctionFor(args) {
+    if (args.step === 'detach') {
+        return xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+            contractAddress: new Address(args.smartAccount).toScAddress(),
+            functionName: 'remove_policy',
+            args: [xdr.ScVal.scvU32(args.ruleId), xdr.ScVal.scvU32(args.policyId)],
+        }));
+    }
+    if (!args.encodedPredicate || !args.predicateHash) {
+        throw new Error('merge_policy: reinstall needs the merged predicate and its hash');
+    }
+    return xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
+        contractAddress: new Address(args.smartAccount).toScAddress(),
+        functionName: 'add_policy',
+        args: [
+            xdr.ScVal.scvU32(args.ruleId),
+            new Address(args.interpreterAddress).toScVal(),
+            // Same encoder as a fresh install: the field order is ABI-significant
+            // and it re-hashes the predicate to confirm the supplied hash.
+            encodePolicyInstallParams({
+                encodedPredicate: args.encodedPredicate,
+                predicateHash: args.predicateHash,
+                installNonce: args.installNonce ?? 1,
+                grammarVersion: DEFAULT_GRAMMAR_VERSION,
+                ...(args.oracleParams ? { oracleParams: args.oracleParams } : {}),
+            }),
+        ],
+    }));
+}
+/**
+ * Build the unsigned transaction for one step of the merge.
+ *
+ * The auth dance mirrors `buildRevokePolicyXdr`: simulate once to record the
+ * account's auth entry, rebuild with the payload bound to that recorded
+ * `rootInvocation`, then assemble. Binding to the recorded invocation rather
+ * than to the input arguments is what makes the signature commit to the exact
+ * rule and policy being changed.
+ */
+export async function buildMergePolicyXdr(args) {
+    const fn = args.step === 'detach' ? 'remove_policy' : 'add_policy';
+    const source = await args.rpc.getAccount(args.sourceAccount);
+    const hostFunction = hostFunctionFor(args);
+    const makeOperation = (auth = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
+    const buildTx = (op) => new TransactionBuilder(new Account(args.sourceAccount, source.sequenceNumber()), {
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+    })
+        .addOperation(op)
+        .setTimeout(0)
+        .build();
+    const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()));
+    if (rpc.Api.isSimulationError(recorded)) {
+        // Short and stable, like the other builders: the SDK's full error carries
+        // host and URL detail that has no business in a user-facing message.
+        throw new Error(`merge_policy: ${fn} simulateTransaction failed`);
+    }
+    const original = (recorded.result?.auth ?? []).find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
+        Address.fromScAddress(entry.credentials().address().address()).toString() ===
+            args.smartAccount);
+    if (!original) {
+        throw new Error(`merge_policy: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
+    }
+    const validUntilLedger = (await args.rpc.getLatestLedger()).sequence +
+        (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS);
+    const contextRuleIds = [ADMIN_CONTEXT_RULE_ID];
+    const digest = authDigest(signaturePayload(args.networkPassphrase, original.credentials().address().nonce(), validUntilLedger, original.rootInvocation()), contextRuleIds);
+    const authEntries = [
+        accountEntry(original, validUntilLedger, authPayload([args.sourceAccount], contextRuleIds, () => Buffer.alloc(0))),
+        ...contextRuleIds.map(() => delegatedSignerEntry(args.smartAccount, digest)),
+    ];
+    const txWithAuth = buildTx(makeOperation(authEntries));
+    const enforcing = await args.rpc.simulateTransaction(txWithAuth);
+    if (rpc.Api.isSimulationError(enforcing)) {
+        throw new Error(`merge_policy: ${fn} auth simulateTransaction failed`);
+    }
+    const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build();
+    return {
+        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        smartAccount: args.smartAccount,
+        sourceAccount: args.sourceAccount,
+        step: args.step,
+        call: { contract: args.smartAccount, fn, ruleId: args.ruleId },
+        authNonce: original.credentials().address().nonce().toString(),
+        authValidUntilLedger: validUntilLedger,
+        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
+    };
+}

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

@@ -1 +1,3 @@
-export { ADD_CONTEXT_RULE_SYMBOL, DEFAULT_GRAMMAR_VERSION, buildAddContextRuleArgs, type AddContextRuleArgs, type BuildAddContextRuleArgs, } from './build-add-context-rule.ts';
+export { ANY, type AuthorityOverlap, type ContextType, effectiveSelectors, findAuthorityOverlaps, type IntendedInstall, intersectSelectors, type MergeResult, mergeIntoAnd, type ObservedRule, type OverlapSeverity, permittedSelectors, type RuleClass, type Selector, signerKey, } from './authority-overlap.ts';
+export { ADD_CONTEXT_RULE_SYMBOL, type AddContextRuleArgs, type BuildAddContextRuleArgs, buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION, } from './build-add-context-rule.ts';
+export { type AccountRuleReader, accountRuleReaderFromServer, type CollectedRules, collectObservedRules, decodeContextRule, decodeContextType, decodeSigner, docLedgerKey, MAX_RULE_ID_SCAN, } from './read-account-rules.ts';

package/dist/install/index.js

@@ -12,4 +12,11 @@
 // 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, DEFAULT_GRAMMAR_VERSION, buildAddContextRuleArgs, } from "./build-add-context-rule.js";
+// Cross-rule authority analysis. A caller installing a policy needs to know
+// whether its signers can already reach the same calls through another context
+// rule, because OZ lets the signer name the rule and enforces only that one's
+// policies. Without this, a second, tighter rule reads as a restriction while
+// restricting nothing.
+export { ANY, effectiveSelectors, findAuthorityOverlaps, intersectSelectors, mergeIntoAnd, permittedSelectors, signerKey, } from "./authority-overlap.js";
+export { ADD_CONTEXT_RULE_SYMBOL, buildAddContextRuleArgs, DEFAULT_GRAMMAR_VERSION, } from "./build-add-context-rule.js";
+export { accountRuleReaderFromServer, collectObservedRules, decodeContextRule, decodeContextType, decodeSigner, docLedgerKey, MAX_RULE_ID_SCAN, } from "./read-account-rules.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()]);