@crediolabs/policy-synth 0.1.17 → 0.2.0

package/dist-cjs/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-cjs/install/build-merge-policy.js

@@ -0,0 +1,134 @@
+"use strict";
+//! 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADMIN_CONTEXT_RULE_ID = void 0;
+exports.buildMergePolicyXdr = buildMergePolicyXdr;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const build_add_context_rule_ts_1 = require("./build-add-context-rule.js");
+const oz_auth_ts_1 = require("./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.
+ */
+exports.ADMIN_CONTEXT_RULE_ID = 0;
+function hostFunctionFor(args) {
+    if (args.step === 'detach') {
+        return stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+            contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
+            functionName: 'remove_policy',
+            args: [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId), stellar_sdk_1.xdr.ScVal.scvU32(args.policyId)],
+        }));
+    }
+    if (!args.encodedPredicate || !args.predicateHash) {
+        throw new Error('merge_policy: reinstall needs the merged predicate and its hash');
+    }
+    return stellar_sdk_1.xdr.HostFunction.hostFunctionTypeInvokeContract(new stellar_sdk_1.xdr.InvokeContractArgs({
+        contractAddress: new stellar_sdk_1.Address(args.smartAccount).toScAddress(),
+        functionName: 'add_policy',
+        args: [
+            stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId),
+            new stellar_sdk_1.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.
+            (0, build_add_context_rule_ts_1.encodePolicyInstallParams)({
+                encodedPredicate: args.encodedPredicate,
+                predicateHash: args.predicateHash,
+                installNonce: args.installNonce ?? 1,
+                grammarVersion: build_add_context_rule_ts_1.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.
+ */
+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 = []) => stellar_sdk_1.Operation.invokeHostFunction({ func: hostFunction, auth });
+    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : stellar_sdk_1.BASE_FEE;
+    const buildTx = (op) => new stellar_sdk_1.TransactionBuilder(new stellar_sdk_1.Account(args.sourceAccount, source.sequenceNumber()), {
+        fee: baseFee,
+        networkPassphrase: args.networkPassphrase,
+    })
+        .addOperation(op)
+        .setTimeout(0)
+        .build();
+    const recorded = await args.rpc.simulateTransaction(buildTx(makeOperation()));
+    if (stellar_sdk_1.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' &&
+        stellar_sdk_1.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 = [exports.ADMIN_CONTEXT_RULE_ID];
+    const digest = (0, oz_auth_ts_1.authDigest)((0, oz_auth_ts_1.signaturePayload)(args.networkPassphrase, original.credentials().address().nonce(), validUntilLedger, original.rootInvocation()), contextRuleIds);
+    const authEntries = [
+        (0, oz_auth_ts_1.accountEntry)(original, validUntilLedger, (0, oz_auth_ts_1.authPayload)([args.sourceAccount], contextRuleIds, () => Buffer.alloc(0))),
+        ...contextRuleIds.map(() => (0, oz_auth_ts_1.delegatedSignerEntry)(args.smartAccount, digest)),
+    ];
+    const txWithAuth = buildTx(makeOperation(authEntries));
+    const enforcing = await args.rpc.simulateTransaction(txWithAuth);
+    if (stellar_sdk_1.rpc.Api.isSimulationError(enforcing)) {
+        throw new Error(`merge_policy: ${fn} auth simulateTransaction failed`);
+    }
+    const finalTx = stellar_sdk_1.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-cjs/install/get-interpreter-info.js

@@ -10,9 +10,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-cjs/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-cjs/install/index.js

@@ -1,6 +1,4 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildAddContextRuleArgs = exports.DEFAULT_GRAMMAR_VERSION = exports.ADD_CONTEXT_RULE_SYMBOL = void 0;
 // Public entry for the install-argument builders.
 //
 // `buildAddContextRuleArgs` is the encoder `runInstallPolicy` uses to turn a
@@ -15,7 +13,30 @@ exports.buildAddContextRuleArgs = exports.DEFAULT_GRAMMAR_VERSION = exports.ADD_
 // 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RULE_ID_SCAN = exports.docLedgerKey = exports.decodeSigner = exports.decodeContextType = exports.decodeContextRule = exports.collectObservedRules = exports.accountRuleReaderFromServer = exports.DEFAULT_GRAMMAR_VERSION = exports.buildAddContextRuleArgs = exports.ADD_CONTEXT_RULE_SYMBOL = exports.signerKey = exports.permittedSelectors = exports.mergeIntoAnd = exports.intersectSelectors = exports.findAuthorityOverlaps = exports.effectiveSelectors = exports.ANY = void 0;
+// 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.
+var authority_overlap_ts_1 = require("./authority-overlap.js");
+Object.defineProperty(exports, "ANY", { enumerable: true, get: function () { return authority_overlap_ts_1.ANY; } });
+Object.defineProperty(exports, "effectiveSelectors", { enumerable: true, get: function () { return authority_overlap_ts_1.effectiveSelectors; } });
+Object.defineProperty(exports, "findAuthorityOverlaps", { enumerable: true, get: function () { return authority_overlap_ts_1.findAuthorityOverlaps; } });
+Object.defineProperty(exports, "intersectSelectors", { enumerable: true, get: function () { return authority_overlap_ts_1.intersectSelectors; } });
+Object.defineProperty(exports, "mergeIntoAnd", { enumerable: true, get: function () { return authority_overlap_ts_1.mergeIntoAnd; } });
+Object.defineProperty(exports, "permittedSelectors", { enumerable: true, get: function () { return authority_overlap_ts_1.permittedSelectors; } });
+Object.defineProperty(exports, "signerKey", { enumerable: true, get: function () { return authority_overlap_ts_1.signerKey; } });
 var build_add_context_rule_ts_1 = require("./build-add-context-rule.js");
 Object.defineProperty(exports, "ADD_CONTEXT_RULE_SYMBOL", { enumerable: true, get: function () { return build_add_context_rule_ts_1.ADD_CONTEXT_RULE_SYMBOL; } });
-Object.defineProperty(exports, "DEFAULT_GRAMMAR_VERSION", { enumerable: true, get: function () { return build_add_context_rule_ts_1.DEFAULT_GRAMMAR_VERSION; } });
 Object.defineProperty(exports, "buildAddContextRuleArgs", { enumerable: true, get: function () { return build_add_context_rule_ts_1.buildAddContextRuleArgs; } });
+Object.defineProperty(exports, "DEFAULT_GRAMMAR_VERSION", { enumerable: true, get: function () { return build_add_context_rule_ts_1.DEFAULT_GRAMMAR_VERSION; } });
+var read_account_rules_ts_1 = require("./read-account-rules.js");
+Object.defineProperty(exports, "accountRuleReaderFromServer", { enumerable: true, get: function () { return read_account_rules_ts_1.accountRuleReaderFromServer; } });
+Object.defineProperty(exports, "collectObservedRules", { enumerable: true, get: function () { return read_account_rules_ts_1.collectObservedRules; } });
+Object.defineProperty(exports, "decodeContextRule", { enumerable: true, get: function () { return read_account_rules_ts_1.decodeContextRule; } });
+Object.defineProperty(exports, "decodeContextType", { enumerable: true, get: function () { return read_account_rules_ts_1.decodeContextType; } });
+Object.defineProperty(exports, "decodeSigner", { enumerable: true, get: function () { return read_account_rules_ts_1.decodeSigner; } });
+Object.defineProperty(exports, "docLedgerKey", { enumerable: true, get: function () { return read_account_rules_ts_1.docLedgerKey; } });
+Object.defineProperty(exports, "MAX_RULE_ID_SCAN", { enumerable: true, get: function () { return read_account_rules_ts_1.MAX_RULE_ID_SCAN; } });

package/dist-cjs/install/oz-auth.js

@@ -39,9 +39,11 @@ const u32 = (n) => stellar_sdk_1.xdr.ScVal.scvU32(n);
 const vec = (i) => stellar_sdk_1.xdr.ScVal.scvVec(i);
 const bytes = (b) => stellar_sdk_1.xdr.ScVal.scvBytes(b);
 function struct(fields) {
-    return stellar_sdk_1.xdr.ScVal.scvMap(Object.keys(fields)
-        .sort()
-        .map((k) => new stellar_sdk_1.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 stellar_sdk_1.xdr.ScVal.scvMap(Object.entries(fields)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => new stellar_sdk_1.xdr.ScMapEntry({ key: sym(k), val: v })));
 }
 /** `Signer::Delegated(addr)`. */
 const delegatedSigner = (a) => vec([sym('Delegated'), new stellar_sdk_1.Address(a).toScVal()]);

package/dist-cjs/install/plan-merge-policy.d.ts

@@ -0,0 +1,49 @@
+import type { PredicateNode } from '../types.ts';
+import type { ObservedRule } from './authority-overlap.ts';
+export type MergeStep = 'detach' | 'reinstall';
+export interface MergePlanRefused {
+    ok: false;
+    /** Why the merge cannot proceed, in terms the caller can act on. */
+    reason: string;
+}
+export interface MergePlanAccepted {
+    ok: true;
+    /** The conjunction to install in step 2. */
+    predicate: PredicateNode;
+    /** OZ registry id of the interpreter policy on this rule, for
+     *  `remove_policy`. */
+    policyId: number;
+    /** Oracle bounds to re-install with the merged predicate. Carried from the
+     *  document being replaced: they are tighten-only overrides against the wasm
+     *  defaults, so omitting them would quietly widen the policy while the
+     *  operator believed they were tightening it. */
+    oracleParams?: {
+        maxStalenessSeconds?: number;
+        maxDeviationBps?: number;
+        maxCrossFeedDeviationBps?: number;
+    };
+    /** Consequences the caller must see BEFORE signing step 1, because step 1 is
+     *  the destructive one. */
+    warnings: string[];
+    /** What the caller should do after the requested step confirms. */
+    followUp: string;
+}
+export type MergePlan = MergePlanRefused | MergePlanAccepted;
+/** The interpreter's registry id on a rule, or null when it is not attached
+ *  or the ids were not readable. */
+export declare function interpreterPolicyId(rule: ObservedRule, interpreterAddress: string): number | null;
+/**
+ * Decide whether the merge can proceed, and say what it will cost.
+ *
+ * Refuses rather than guesses whenever the account is not in the shape the
+ * remedy assumes: the rule must be policed by our interpreter, its predicate
+ * must have been readable, and the ids needed to detach it must be present. A
+ * merge built on a predicate we could not read would silently replace a rule
+ * with something narrower or wider than its author wrote.
+ */
+export declare function planMergePolicy(args: {
+    rule: ObservedRule;
+    interpreterAddress: string;
+    incoming: PredicateNode;
+    step: MergeStep;
+}): MergePlan;

package/dist-cjs/install/plan-merge-policy.js

@@ -0,0 +1,90 @@
+"use strict";
+//! Planning the merge remedy for a cross-rule authority overlap.
+//!
+//! When two rules our interpreter polices can serve the same calls, the
+//! tightening remedy is to replace one rule's predicate with the conjunction
+//! of both (see `authority-overlap.ts`). Carrying that out against an OZ smart
+//! account is not one call, and the reasons are worth stating because they
+//! shape the whole tool:
+//!
+//!   1. A Soroban transaction carries exactly ONE operation - "smart contract
+//!      transactions can only have one operation per transaction" - so the
+//!      detach and the re-attach cannot be bundled even though the host would
+//!      run them in order happily. And `add_policy` panics `DuplicatePolicy`
+//!      while the policy is still attached (`smart_account/storage.rs`
+//!      `add_policy`), so the second transaction cannot even be simulated
+//!      until the first has confirmed.
+//!   2. `remove_policy` calls `try_uninstall` and DISCARDS the result
+//!      (`smart_account/storage.rs`: `let _ = ...try_uninstall(...)`), so the
+//!      policy is detached whether or not our `uninstall` succeeded. When it
+//!      succeeded the document, nonce, signer hash, master set and counters
+//!      are gone and the re-install is a fresh install at nonce 1. When it
+//!      panicked - our `uninstall` panics `MissingState` if the master set has
+//!      been archived - the nonce SURVIVES, and re-installing at 1 would be
+//!      refused on chain as a replay, leaving the rule stuck unpoliced. The
+//!      nonce is therefore READ at reinstall time rather than assumed.
+//!   3. Because of (2), any rate-limit or spend window on that rule is reset
+//!      by the merge. A signer who had consumed most of a window gets a clean
+//!      one. That is a real cost of tightening this way and the caller has to
+//!      be told, not discover it.
+//!   4. So the caller performs step 1, waits for it to confirm, then asks for
+//!      step 2.
+//!
+//! This module is pure. It decides what should happen and why; the XDR is
+//! built by `build-merge-policy.ts`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interpreterPolicyId = interpreterPolicyId;
+exports.planMergePolicy = planMergePolicy;
+const authority_overlap_ts_1 = require("./authority-overlap.js");
+/** The interpreter's registry id on a rule, or null when it is not attached
+ *  or the ids were not readable. */
+function interpreterPolicyId(rule, interpreterAddress) {
+    const index = rule.policyAddresses.indexOf(interpreterAddress);
+    if (index < 0)
+        return null;
+    const id = rule.policyIds?.[index];
+    return typeof id === 'number' ? id : null;
+}
+/**
+ * Decide whether the merge can proceed, and say what it will cost.
+ *
+ * Refuses rather than guesses whenever the account is not in the shape the
+ * remedy assumes: the rule must be policed by our interpreter, its predicate
+ * must have been readable, and the ids needed to detach it must be present. A
+ * merge built on a predicate we could not read would silently replace a rule
+ * with something narrower or wider than its author wrote.
+ */
+function planMergePolicy(args) {
+    const policyId = interpreterPolicyId(args.rule, args.interpreterAddress);
+    if (policyId === null) {
+        return {
+            ok: false,
+            reason: `rule ${args.rule.id} is not policed by the interpreter at ${args.interpreterAddress}, or its policy ids could not be read, so there is nothing to merge into and no id to detach. The merge hard-pins to that interpreter and has no opt-out: the auth digest it builds binds to the audited deployment. A rule installed against a different interpreter has to be replaced rather than merged.`,
+        };
+    }
+    const existing = args.rule.predicate;
+    if (!existing) {
+        return {
+            ok: false,
+            reason: `the predicate installed on rule ${args.rule.id} could not be read, so it cannot be conjoined; merging against an unknown predicate would replace the rule with something other than what its author wrote`,
+        };
+    }
+    const merged = (0, authority_overlap_ts_1.mergeIntoAnd)(existing, args.incoming);
+    if (!merged.ok || !merged.predicate) {
+        return { ok: false, reason: merged.reason ?? 'the two predicates cannot be conjoined' };
+    }
+    const warnings = [
+        `detaching the policy uninstalls it, which removes every counter on rule ${args.rule.id}: any rate limit or spend window there restarts from zero after the merge`,
+        'the rule is unpoliced between the two transactions, so a signer of it is unconstrained by this policy until step 2 confirms',
+    ];
+    return {
+        ok: true,
+        predicate: merged.predicate,
+        policyId,
+        ...(args.rule.oracleBounds ? { oracleParams: args.rule.oracleBounds } : {}),
+        warnings,
+        followUp: args.step === 'detach'
+            ? "sign and submit this transaction, wait for it to confirm, then call again with step: 'reinstall' to install the merged predicate"
+            : 'sign and submit this transaction; the merged predicate is then the only policy governing this rule',
+    };
+}

package/dist-cjs/install/read-account-rules.d.ts

@@ -0,0 +1,100 @@
+import { rpc, xdr } from '@stellar/stellar-sdk';
+import type { SignerDraft } from '../types.ts';
+import type { ContextType, ObservedRule } from './authority-overlap.ts';
+/** `storage.rs:295` - the third element of the persistent doc key tuple. */
+export declare const K_DOC = 1;
+/** Persistent-storage key for a rule's stored document:
+ *  `(account, rule_id, K_DOC)`, per `storage.rs:4`. */
+export declare function docKeyScVal(smartAccount: string, ruleId: number): xdr.ScVal;
+/** Ledger key for the interpreter's persistent entry holding that document. */
+export declare function docLedgerKey(interpreter: string, smartAccount: string, ruleId: number): xdr.LedgerKey;
+/** OZ `ContextRuleType`. An unrecognised tag is reported as `default`, which
+ *  is the widest reading and therefore the safe one: it makes the rule look
+ *  like it could serve any call, so overlap is over-reported, never missed. */
+export declare function decodeContextType(v: xdr.ScVal | undefined): ContextType;
+/** OZ `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
+export declare function decodeSigner(v: xdr.ScVal): SignerDraft | undefined;
+/** A full OZ `ContextRule` as returned by `get_context_rule(id)`.
+ *  `predicate` is filled in separately from the ledger entry. */
+export declare function decodeContextRule(v: xdr.ScVal): ObservedRule | undefined;
+/** `storage.rs:296` - the third element of the persistent nonce key tuple. */
+export declare const K_NONCE = 2;
+/** Ledger key for a rule's stored install nonce. Read directly for the same
+ *  reason as the document: the interpreter publishes no getter. */
+export declare function nonceLedgerKey(interpreter: string, smartAccount: string, ruleId: number): xdr.LedgerKey;
+/** Per-policy oracle bounds carried on a `StoredDoc`.
+ *
+ *  These must survive a merge. They are tighten-only overrides against the
+ *  wasm defaults, so dropping them does not fail loudly: the rule keeps
+ *  working and silently tolerates staler prices and wider deviation than its
+ *  author chose. */
+export interface StoredOracleBounds {
+    maxStalenessSeconds?: number;
+    maxDeviationBps?: number;
+    maxCrossFeedDeviationBps?: number;
+}
+export declare function decodeStoredOracleBounds(v: xdr.ScVal): StoredOracleBounds;
+/** Raw predicate bytes out of a `StoredDoc` ledger entry value. */
+export declare function decodeStoredPredicateBytes(v: xdr.ScVal): Buffer | undefined;
+/** The three reads the scan needs. Kept as an interface so the collection
+ *  below is testable without a network, matching the `InstallRpcClient`
+ *  pattern in `build-install-policy.ts`. */
+export interface AccountRuleReader {
+    /** OZ `get_context_rules_count()`. */
+    getContextRuleCount(smartAccount: string): Promise<number>;
+    /** OZ `get_context_rule(id)`. Undefined when the id is absent. */
+    getContextRule(smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
+    /** The interpreter's persistent `StoredDoc` entry, read as a ledger entry.
+     *  Undefined when no document is stored for that rule. */
+    getStoredDoc(interpreter: string, smartAccount: string, ruleId: number): Promise<xdr.ScVal | undefined>;
+}
+/** How far the id scan will probe before giving up. OZ imposes no per-account
+ *  rule cap, so there is no exact bound to derive; this one is far above any
+ *  realistic account and keeps a malformed `Count` from spinning forever. */
+export declare const MAX_RULE_ID_SCAN = 512;
+export interface CollectedRules {
+    rules: ObservedRule[];
+    /** Rule ids whose stored predicate could not be read even though the
+     *  interpreter is attached. Such a rule is reported without a predicate,
+     *  which classifies it as opaque rather than as safely narrow. */
+    unreadablePredicateRuleIds: number[];
+    /** True when the scan stopped before accounting for every live rule. The
+     *  result is then a SUBSET of the account's rules, so an empty overlap list
+     *  proves nothing and the caller must not present it as safety. */
+    incomplete: boolean;
+}
+/**
+ * Every context rule on the account, with predicates filled in for the rules
+ * our interpreter polices.
+ *
+ * Rule ids are NOT contiguous. OZ assigns them from a monotonic `NextId` and
+ * decrements `Count` on removal without ever reusing an id
+ * (`smart_account/storage.rs`: `add_context_rule` bumps `NextId`,
+ * `remove_context_rule` only lowers `Count`), so after any removal
+ * `Count < NextId` and the live ids have gaps. Iterating `0..Count-1` would
+ * silently skip live rules at higher ids, and a skipped rule is a missed
+ * overlap - the one error that reports safety which does not exist. Instead
+ * the scan walks ids upward until it has accounted for `Count` live rules.
+ *
+ * A rule whose predicate cannot be read is deliberately left without one. That
+ * demotes it to the `foreign` class, so the scan reports it as opaque instead
+ * of assuming it is narrow.
+ */
+export declare function collectObservedRules(args: {
+    reader: AccountRuleReader;
+    smartAccount: string;
+    interpreterAddress: string;
+    maxRuleIdScan?: number;
+}): Promise<CollectedRules>;
+/**
+ * An `AccountRuleReader` over a live RPC server.
+ *
+ * The two OZ getters are read-only simulations, built the same way as
+ * `getContractVersion` in `build-install-policy.ts`: the source account is
+ * constructed locally because a simulation never checks its sequence number,
+ * and asking the network for a random key would 404.
+ *
+ * The stored document is fetched as a ledger entry rather than a contract
+ * call, because the interpreter publishes no getter for it.
+ */
+export declare function accountRuleReaderFromServer(server: rpc.Server, networkPassphrase: string): AccountRuleReader;