@crediolabs/policy-synth 0.1.18 → 0.3.0

package/src/types.ts

@@ -64,13 +64,11 @@ export const MAX_SCVAL_CLONE_DEPTH = 30 as const
  *    - MAX_DEPTH = 5:             3 walkthroughs need depth 2; budget = 2x growth + 1 for `not` chain.
  *    - MAX_LEAVES = 200:         allowlists (recipients, paths) typically < 100; budget = 2x + 1 nested allowlist.
  *    - MAX_PREDICATE_BYTES = 32 KB: well under the per-ledger-entry 64 KB persistent-storage limit.
- *    - MAX_ORACLE_READS = 6:     two-round confirmation per asset consumes 2 reads; cap accommodates a predicate that references up to 3 unique oracle assets (3 * 2 = 6 reads). Stays a fail-closed install-time cap.
  *    - MAX_IN_OPERAND_COUNT = 32: allowlist < 32 is a UX-natural bound. */
 export const PREDICATE_CAPS = {
   MAX_DEPTH: 5,
   MAX_LEAVES: 200,
   MAX_PREDICATE_BYTES: 32 * 1024,
-  MAX_ORACLE_READS: 6,
   MAX_IN_OPERAND_COUNT: 32,
 } as const
 
@@ -97,15 +95,23 @@ export type SignerDraft =
   | { kind: 'external'; verifier: string; keyBytes: string }
 
 /** Reference to one policy attached to a context rule. */
-export type PolicyRef =
-  | { kind: 'oz_builtin'; primitive: OZPrimitiveConfig; instanceAddress: string }
-  | { kind: 'interpreter'; interpreterAddress: string; predicateBlobBase64: string }
+export type PolicyRef = {
+  kind: 'interpreter'
+  interpreterAddress: string
+  predicateBlobBase64: string
+}
+
+/** Grammar version baked into the interpreter wasm, mirroring `SELF_VERSION` in
+ *  `contracts/policy-interpreter/src/version.rs`. Every value this package puts on
+ *  the wire derives from here; `grammar-version-parity.test.ts` pins it to the
+ *  contract so a skew cannot pass a green test run. */
+export const GRAMMAR_VERSION = 3 as const
 
 /** A serialised predicate document stored against a (smart_account, rule_id) pair. */
 export interface PolicyDocument {
   /** Grammar version baked into the interpreter wasm. Fail-closed strict match at install
    *  AND at evaluate (defence in depth). NOT the per-edit revision. */
-  grammarVersion: 1
+  grammarVersion: typeof GRAMMAR_VERSION
   /** Per-rule install nonce. Must equal the interpreter's stored nonce + 1 at install.
    *  First install accepts nonce = 1 with stored nonce = 0. Re-install is structurally
    *  possible by incrementing the nonce; uninstall removes the nonce with state so a
@@ -117,24 +123,13 @@ export interface PolicyDocument {
   /** Hash of the post-canonicalisation bytes of encodedPredicate. Stored alongside the
    *  doc and re-verified at evaluate. */
   predicateHash: string
-  /** Per-policy overrides of oracle thresholds; absent = use defaults.
-   *  Overrides may TIGHTEN only (never widen) - the interpreter rejects any per-policy
-   *  value looser than the wasm-level defaults at install. */
-  oracleParams?: {
-    /** Seconds; must be <= MAX_ORACLE_STALENESS_SECONDS (600). */
-    maxStalenessSeconds?: number
-    /** Basis points; must be <= MAX_ORACLE_DEVIATION_BPS (200). */
-    maxDeviationBps?: number
-  }
 }
 
 /** The versioned predicate AST (interpreter side). Tagged union. */
 export type PredicateNode =
   | { op: 'and'; children: PredicateNode[] }
-  | { op: 'or'; children: PredicateNode[] }
-  | { op: 'not'; child: PredicateNode }
   | { op: 'eq'; left: PredicateLeaf; right: PredicateLeaf }
-  | { op: 'lt' | 'lte' | 'gt' | 'gte'; left: PredicateLeaf; right: PredicateLeaf }
+  | { op: 'lte'; left: PredicateLeaf; right: PredicateLeaf }
   | {
       op: 'in'
       needle: PredicateLeaf
@@ -155,48 +150,18 @@ export type PredicateLeaf =
   // recorded ScVal type. A non-vec arg, missing element, missing field, or
   // type mismatch all DENY (fail-closed).
   | { kind: 'call_arg_field'; index: number; element: number; field: string }
-  // `call_arg_scaled(index, num, den)` evaluates to `args[index] * num / den`
-  // (truncating toward zero). The slippage-floor leaf: a swap policy
-  // expresses `call_arg[out] >= call_arg_scaled(in, num, den)` as "the
-  // minimum output must be at least this ratio of the input". `num`/`den`
-  // are decimal strings on i128 (mirrors `literal_i128`); the contract
-  // refuses `den == 0` and `num <= 0` / `den <= 0` at install.
-  | { kind: 'call_arg_scaled'; index: number; num: string; den: string }
-  // `call_sub_invocation[i]` is NOT in v1 grammar. OZ `Policy::enforce`
-  // receives one `Context`, not a sub-invocation tree; sub-invocations live under
-  // `InvokerContractAuthEntry::Contract(SubContractInvocation)`, not in the
-  // enforce Context. Scope is per-authorized-context; a v1.1 sub-invocation
-  // tree leaf is gated on the enforce-Context-shape spike result.
-  | { kind: 'amount'; token: string }
-  | { kind: 'window_spent'; token: string; windowSeconds: number }
-  | { kind: 'now' }
-  | { kind: 'valid_until' }
-  | { kind: 'invocation_count_in_window'; windowSecs: number }
-  | { kind: 'oracle_price'; asset: string } // Stellar Address (SAC address for SEP-41; XLM uses its network SAC)
-  // The right-hand side of an oracle comparison. It carries its own decimal
-  // basis because the contract cannot recover it: prices normalise to 9 dp, so
-  // a raw 14-dp threshold is ~10^5 too large and `price <= threshold` becomes
-  // trivially true. `value` is a decimal string on i128, like `literal_i128`.
-  | { kind: 'oracle_threshold'; value: string; decimals: number }
   // Literal leaves: bare ScVal on the wire (no selector-tuple wrapper). Right-hand side of
   // comparisons, elements of `in` haystacks, and operands to future arithmetic nodes.
   | { kind: 'literal_address'; value: string }
   | { kind: 'literal_i128'; value: string }
   | { kind: 'literal_symbol'; value: string }
   | { kind: 'literal_u32'; value: number }
-  | { kind: 'literal_u64'; value: string }
-  | { kind: 'literal_bytes'; value: string } // hex string; wrapped as ScVal::Bytes at encode time
   // Exact ordered vector of literals (e.g. a swap hop path). Encodes to a bare
   // ScVal::Vec with the caller's order preserved verbatim - the order IS the
   // semantic. An exact ordered sequence equality is expressed by `eq(selector,
   // literal_vec([...]))`. `in` is reserved for pure set membership (sorted).
   | { kind: 'literal_vec'; elements: PredicateLeaf[] }
 
-export interface OZPrimitiveConfig {
-  primitive: 'spending_limit' | 'simple_threshold' | 'weighted_threshold'
-  params: Record<string, unknown>
-}
-
 export interface ContractInvocation {
   contract: string
   fn: string
@@ -263,7 +228,6 @@ export type AmbiguityCode =
   | 'AMOUNT_BOUND_MISSING'
   | 'RECIPIENT_ALLOWLIST_EMPTY'
   | 'FREQUENCY_BOUND_MISSING'
-  | 'ORACLE_ASSET_UNKNOWN'
   | 'MULTIPLE_UNRELATED_TARGETS'
 
 /** Structured recording freshness. `overall` is the gate threshold (default 1.0); the

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

@@ -1,96 +0,0 @@
-import { Contract } from '@stellar/stellar-sdk';
-import type { InstallRpcClient } from './build-install-policy.ts';
-/** Inputs for the install-predicate build. */
-export interface BuildInstallPredicateArgs {
-    /** The smart account contract address (C...). The interpreter hashes
-     *  this rule's `signers` at install; we fetch it via `get_context_rule`
-     *  on this address, not reconstruct it. */
-    smartAccount: string;
-    /** The signer that authorises the install (G... wallet). */
-    sourceAccount: string;
-    /** The rule id the account assigned in call 1. */
-    ruleId: number;
-    /** The interpreter contract address (C...). */
-    interpreterAddress: string;
-    /** Network passphrase - pins the hash the auth digest binds. */
-    networkPassphrase: string;
-    /** Already-encoded (base64) canonical ScVal of the predicate. */
-    encodedPredicate: string;
-    /** Hex sha256 of the canonical predicate XDR bytes. */
-    predicateHash: string;
-    /** Grammar version override; defaults to 1. */
-    grammarVersion?: number;
-    /** Base fee in stroops; defaults to BASE_FEE (100). */
-    baseFee?: number;
-    /** RPC client to use for the simulation pass; injected for tests. */
-    rpc: InstallRpcClient;
-    /** Ledger window (in ledgers) for the auth entry's `validUntil`. */
-    authValidUntilLedgers?: number;
-}
-/** Human-readable description of the install-predicate call, decoded FROM
- *  the built XDR (not from the input args). The wallet signature binds
- *  to bytes; the review card has to bind to the same bytes, so this is
- *  the only safe source.
- *
- *  `ruleId` is NOT decoded from the XDR - it lives inside
- *  `raw_context_rule`, which is passed through verbatim. Decoding it
- *  here would re-introduce the client-side reconstruction the file
- *  header warns against. The top-level `BuildInstallPredicateResult`
- *  echoes the caller-supplied rule id instead. */
-export interface InstallPredicateCallDescribes {
-    /** The interpreter that will hold the predicate. */
-    targetContract: string;
-    /** The fn name on the target (always `install` today). */
-    fnName: 'install';
-    /** Grammar version the interpreter enforces; read off the wire. */
-    grammarVersion: number;
-    /** Per-rule install nonce; read off the wire. */
-    installNonce: number;
-    /** Hex sha256 of the encoded predicate blob; read off the wire. */
-    predicateHash: string;
-    /** Hex sha256 of the predicate bytes embedded in the params map. The
-     *  two values MUST match; a difference is a wire tampering signal. */
-    predicateSha256OfEmbeddedBytes: string;
-    /** The smart account address encoded in args[2], read off the wire. */
-    smartAccountOnWire: string;
-}
-/** Output of the install-predicate build. The unsigned XDR is the
- *  wallet's input; the wallet signs it (single envelope signature) and
- *  submits. The auth tree matches install_policy: account entry
- *  carrying OZ's AuthPayload + a source-account delegated signer entry.
- *  Both are covered by the envelope signature. */
-export interface BuildInstallPredicateResult {
-    /** Unsigned Soroban transaction envelope, base64 XDR. */
-    unsignedXdr: string;
-    /** Smart account contract address (echo). */
-    smartAccount: string;
-    /** Source account (echo) - the address that signs the envelope. */
-    sourceAccount: string;
-    /** The interpreter contract address (echo). */
-    interpreterAddress: string;
-    /** The rule id the account assigned in call 1 (echo). */
-    ruleId: number;
-    /** The host-call target + fn name. */
-    call: {
-        contract: string;
-        fn: 'install';
-    };
-    /** The smart-account auth nonce (snapshot). */
-    authNonce: string;
-    /** The ledger sequence + window the auth entry expires at. */
-    authValidUntilLedger: number;
-    /** The captured rootInvocation for the smart-account entry. */
-    rootInvocationXdr: string;
-    /** Human-readable description of the install call, decoded FROM the
-     *  built unsigned XDR (not from the input args). The wallet signature
-     *  binds to bytes; the review card has to bind to the same bytes, so
-     *  this is the only safe source. */
-    describes: InstallPredicateCallDescribes;
-}
-/** Build the unsigned transaction envelope for
- *  `interpreter.install(params, raw_context_rule, smart_account)`. The
- *  output XDR is signed by the wallet, not by us. */
-export declare function buildInstallPredicateXdr(args: BuildInstallPredicateArgs): Promise<BuildInstallPredicateResult>;
-/** Re-export `Contract` so the run-layer does not need to import the
- *  SDK directly. Mirrors the build-install-policy.ts convention. */
-export { Contract };

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

@@ -1,444 +0,0 @@
-// src/install/build-install-predicate.ts - builds the unsigned Soroban
-// transaction XDR for `interpreter.install(params, raw_context_rule, smart_account)`.
-//
-// Call 2 of the install sequence. The OZ smart account's `add_context_rule`
-// (call 1, see build-install-policy.ts) attaches the rule to the account and
-// the interpreter POLICY address, but the interpreter itself needs the
-// encoded predicate bytes + the matching hash + the verbatim context rule
-// it will hash at enforce. Storing those is what `interpreter.install`
-// does; without it the interpreter returns MissingState and the rule denies
-// EVERYTHING - which on a deny-only demo is indistinguishable from a
-// working policy.
-//
-// CALL 1 / CALL 2 NONCE LIAISON (critical invariant, empirically verified
-// on testnet 2026-08-01):
-//   - The OZ smart account's `add_context_rule` increments the
-//     interpreter's stored nonce for `(smart_account, rule_id)` from 0
-//     to 1. (Verified via getLedgerEntries after call 1.)
-//   - `interpreter.install` requires
-//     `install_params.install_nonce == stored_nonce.saturating_add(1)`.
-//   - Therefore call 2 MUST derive its install_nonce from the stored
-//     nonce via getLedgerEntries - taking it as caller input is a design
-//     bug that produces NonceReplay (#202) for the caller every time
-//     call 1 has bumped the counter. (octopos historically accepts an
-//     arbitrary install_nonce and the user has to know to pass 2; this
-//     builder reads the stored nonce instead.)
-//
-// AUTH TREE (empirically verified on testnet 2026-08-01):
-//   The recording simulation of `interpreter.install` returns ONE
-//   address-credential auth entry:
-//     auth[0] credentials=address address=<SMART_ACCOUNT> root=install
-//   (The previously hypothesised second entry for the rule signer does
-//   not materialise on this pinned interpreter: `__check_auth` for the
-//   rule id in `contextRuleIds` runs the rule's `policy.enforce`, but
-//   because the rule's policy is the interpreter we are CALLING, the
-//   interpreter's own `install` does not recurse into require_auth on
-//   the rule signer; the only require_auth is the smart account's
-//   `__check_auth` from the rule the auth payload names.)
-//
-//   The auth tree is therefore the same shape as `buildInstallPolicyXdr`:
-//     [0] accountEntry(original, validUntil, AuthPayload([sourceAccount], [ruleId], () => Bytes()))
-//     [1] delegatedSignerEntry(smartAccount, digest)
-//   The second entry is a `sorobanCredentialsSourceAccount` and the
-//   source-account envelope signature covers it. The wallet signs only
-//   the envelope. Verified on testnet 2026-08-01 against the pinned
-//   interpreter CDR4NLV22STCXFGZPNKDQTEANWLF7LZ6AJLY6B7CLJXKHDZGYJWIOKGP.
-//
-// CONTEXT RULE (empirically verified on testnet 2026-08-01):
-//   `contextRuleIds` is the NEW rule id assigned in call 1 - exactly
-//   what octopos's `installPredicateDoc` passes. Earlier reasoning
-//   claimed rule 0 was required (chicken-and-egg: the new rule's
-//   interpreter policy denies `install` because no predicate is
-//   installed yet); that reasoning is wrong. The smart account
-//   consults the rule's interpreter policy for the `install` host call
-//   and the interpreter permits it - the rule's own install is a
-//   privileged install-only path that the interpreter lets through. A
-//   `[0]` choice was producing a structurally different auth tree
-//   whose digest bound to the wrong rule and whose `AuthPayload`'s
-//   context_rule_ids never matched the rule the interpreter recorded.
-//
-// `params` is an ScMap for a #[contracttype] struct. The host unpacks by
-// field count, so a missing or extra field traps with WasmVm UnexpectedSize
-// rather than a clean code. Keys MUST be in this sorted order:
-//   grammar_version, install_nonce, oracle_max_deviation_bps,
-//   oracle_max_staleness_seconds, oracle_max_xfeed_dev_bps,
-//   predicate, predicate_hash
-//
-// `raw_context_rule` MUST be the ScVal `get_context_rule(ruleId)` returned,
-// passed through VERBATIM. The interpreter hashes `context_rule.signers` at
-// install and re-checks at enforce; any reconstruction that differs in any
-// field denies RULE_SIGNERS_CHANGED forever, bricking the rule. So this
-// builder fetches the rule itself - callers do not get to hand-build it.
-//
-// SECURITY INVARIANT: the auth_digest binds to networkPassphrase +
-// per-credential nonce + the call's root invocation + context_rule_ids.
-// Replaying the envelope against another call or another account is
-// impossible without re-signing.
-import { createHash } from 'node:crypto';
-import { Account, Address, BASE_FEE, Contract, Operation, rpc, TransactionBuilder, xdr, } from '@stellar/stellar-sdk';
-import { accountEntry, authDigest, authPayload, delegatedSignerEntry, signaturePayload, } from "./oz-auth.js";
-/** Build the unsigned transaction envelope for
- *  `interpreter.install(params, raw_context_rule, smart_account)`. The
- *  output XDR is signed by the wallet, not by us. */
-export async function buildInstallPredicateXdr(args) {
-    // 1. Fetch the raw context rule from the smart account via simulation.
-    //    The interpreter hashes the rule's signers at install; we MUST hand
-    //    it the exact bytes the account holds, not a reconstruction.
-    const rawContextRule = await fetchRawContextRule(args.rpc, args.sourceAccount, args.smartAccount, args.ruleId, args.networkPassphrase);
-    // 2. Read the interpreter's stored nonce for this (smart_account,
-    //    rule_id) so call 2's install_nonce is exactly stored+1. Anything
-    //    else trips NonceReplay (#202). The key shape matches
-    //    `packages/policy-interpreter/src/storage.rs`:
-    //      K_NONCE: u32 = 2
-    //      key = (Address(smart_account), u32(rule_id), u32(2))
-    //    A value of `None` means stored_nonce = 0 (first install).
-    const storedNonce = await fetchStoredNonce(args.rpc, args.interpreterAddress, args.smartAccount, args.ruleId);
-    const installNonce = storedNonce + 1;
-    // 3. Build the params ScMap. Field order is sorted by symbol string;
-    //    the host unpacks by field count and any missing/extra field traps
-    //    with WasmVm UnexpectedSize rather than a clean code.
-    const grammarVersion = args.grammarVersion ?? 1;
-    const predicateBytes = Buffer.from(args.encodedPredicate, 'base64');
-    const predicateHashBytes = Buffer.from(args.predicateHash, 'hex');
-    const params = buildInstallParams({
-        grammarVersion,
-        installNonce,
-        predicateBytes,
-        predicateHashBytes,
-    });
-    // 4. Build the host function. `interpreter.install(params, raw_rule,
-    //    smart_account)`.
-    const hostFunction = xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
-        contractAddress: new Address(args.interpreterAddress).toScAddress(),
-        functionName: 'install',
-        args: [params, rawContextRule, new Address(args.smartAccount).toScVal()],
-    }));
-    const source = await args.rpc.getAccount(args.sourceAccount);
-    const makeOperation = (auth = []) => Operation.invokeHostFunction({ func: hostFunction, auth });
-    const baseFee = args.baseFee !== undefined ? String(args.baseFee) : BASE_FEE;
-    const buildTx = (op) => buildUnsignedTx({
-        sourceAccount: args.sourceAccount,
-        sequence: source.sequenceNumber(),
-        fee: baseFee,
-        networkPassphrase: args.networkPassphrase,
-        op,
-    });
-    // 5. Recording simulation: capture the smart-account auth entry.
-    //    `contextRuleIds = [ruleId]` - the rule the account assigned in
-    //    call 1 - is what octopos's `installPredicateDoc` passes (see
-    //    apps/web/ui/octopos/smart-account-install.ts:313-320). The rule's
-    //    own interpreter policy permits the `install` host call (it is a
-    //    privileged install path), so authorising via the rule itself is
-    //    safe and is the only choice whose auth tree binds to the rule
-    //    the interpreter recorded.
-    const recordingTx = buildTx(makeOperation());
-    const recorded = await args.rpc.simulateTransaction(recordingTx);
-    if (rpc.Api.isSimulationError(recorded)) {
-        throw new Error('install_predicate: simulateTransaction failed');
-    }
-    const recordedAuth = recorded.result?.auth ?? [];
-    const original = recordedAuth.find((entry) => entry.credentials().switch().name === 'sorobanCredentialsAddress' &&
-        Address.fromScAddress(entry.credentials().address().address()).toString() ===
-            args.smartAccount);
-    if (!original) {
-        throw new Error(`install_predicate: no Soroban auth entry for smart account ${args.smartAccount}; this call does not route through the smart account`);
-    }
-    // 6. Build the OZ auth entries (same shape as install_policy).
-    //    `contextRuleIds = [args.ruleId]` binds the AuthPayload's
-    //    context_rule_ids + the authDigest to the rule the interpreter
-    //    recorded. The delegated signer entry uses source-account
-    //    credentials so the envelope signature covers it; the wallet
-    //    supplies only the ordinary envelope signature.
-    const validUntilLedger = (await args.rpc.getLatestLedger()).sequence +
-        (args.authValidUntilLedgers ?? DEFAULT_AUTH_VALID_UNTIL_LEDGERS);
-    const contextRuleIds = [args.ruleId];
-    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)),
-    ];
-    // 7. Enforcing simulation + assemble. Same pattern as
-    //    buildInstallPolicyXdr: the SDK preserves the OZ auth entries
-    //    during assembly and adds the simulated Soroban footprint +
-    //    resource fee, yielding a complete unsigned envelope.
-    const txWithAuth = buildTx(makeOperation(authEntries));
-    const enforcing = await args.rpc.simulateTransaction(txWithAuth);
-    if (rpc.Api.isSimulationError(enforcing)) {
-        throw new Error('install_predicate: auth simulateTransaction failed');
-    }
-    const finalTx = rpc.assembleTransaction(txWithAuth, enforcing).build();
-    // 8. Decode the structured description FROM the final assembled
-    //    transaction. The bytes are the source of truth.
-    const describes = decodeInstallPredicateCallDescribes(finalTx, args.predicateHash);
-    return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
-        smartAccount: args.smartAccount,
-        sourceAccount: args.sourceAccount,
-        interpreterAddress: args.interpreterAddress,
-        ruleId: args.ruleId,
-        call: { contract: args.interpreterAddress, fn: 'install' },
-        authNonce: original.credentials().address().nonce().toString(),
-        authValidUntilLedger: validUntilLedger,
-        rootInvocationXdr: original.rootInvocation().toXDR().toString('base64'),
-        describes,
-    };
-}
-// ---- internals ----
-/** ~25 minutes at 5s/ledger. Same default as build-install-policy so the
- *  two-call sequence can be signed inside the same window without a
- *  fresh source account bump between calls. */
-const DEFAULT_AUTH_VALID_UNTIL_LEDGERS = 300;
-/** K_NONCE constant from packages/policy-interpreter/src/storage.rs.
- *  The interpreter's persistent-storage key shape is the tuple
- *  `(Address, u32, u32)` where the third u32 is the namespace. We hard-
- *  code 2 here because the interpreter source is pinned and out of this
- *  builder's scope; a drift test should assert these stay in lockstep
- *  if the storage layout ever changes. */
-const K_NONCE = 2;
-/** Read the interpreter's stored nonce for `(smart_account, rule_id)`
- *  via a direct ledger read. No public getter exists on the pinned
- *  interpreter, so we read the contract-data ledger entry directly.
- *  Returns 0 when the entry is absent (a fresh (account, rule_id) that
- *  has never been installed). Used to derive `install_nonce =
- *  stored_nonce + 1` for `interpreter.install`.
- *
- *  The InstallRpcClient interface intentionally omits `getLedgerEntries`
- *  (the install pipeline uses getAccount / simulateTransaction /
- *  getLatestLedger only); we hit the real Soroban RPC through the
- *  shared sdk module rather than extending the interface, since this
- *  single read keeps the read surface scoped.
- *
- *  If the read errors (network blip, pinned interpreter still deploying,
- *  etc.) we treat the read as if no entry exists and return 0 - the
- *  enforcing simulation will fail closed on NonceReplay if we got it
- *  wrong, with a clean error the caller can act on. */
-async function fetchStoredNonce(rpc, interpreterAddress, smartAccount, ruleId) {
-    // Recover the underlying RPC URL by probing `getLatestLedger` - this
-    // works for both the real-server and mock clients (mocks return a
-    // sequence but not a URL). For tests, this returns 0 unless the mock
-    // also surfaces an URL. We accept the limit: tests for the install
-    // pipeline drive the nonce via the recorded context_rule rather than
-    // this read (see build-install-predicate.test.ts).
-    //
-    // Production reads go through the Soroban RPC directly. We import the
-    // sdk module lazily here so the test-time mock surface does not have
-    // to grow.
-    const { rpc: sdkRpc } = await import('@stellar/stellar-sdk');
-    // The InstallRpcClient does not carry the URL; the run-layer wires a
-    // real rpc.Server for production. We construct one from the pinned
-    // TESTNET_RPC_URL here. This is hard-coded because the read surface
-    // is testnet-only today; mainnet would need its own pinned address
-    // and a separate URL pin.
-    const TESTNET_RPC_URL = 'https://soroban-testnet.stellar.org';
-    const server = new sdkRpc.Server(TESTNET_RPC_URL, { allowHttp: false });
-    const key = xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
-        contract: new Address(interpreterAddress).toScAddress(),
-        key: xdr.ScVal.scvVec([
-            new Address(smartAccount).toScVal(),
-            xdr.ScVal.scvU32(ruleId),
-            xdr.ScVal.scvU32(K_NONCE),
-        ]),
-        durability: xdr.ContractDataDurability.persistent(),
-    }));
-    try {
-        const r = await server.getLedgerEntries(key);
-        if (!r.entries || r.entries.length === 0)
-            return 0;
-        const entry = r.entries[0];
-        if (!entry)
-            return 0;
-        const data = entry.val?.contractData();
-        if (!data)
-            return 0;
-        const val = data.val();
-        if (val.switch().name === 'scvU32')
-            return val.u32();
-        return 0;
-    }
-    catch {
-        // Treat ledger read errors as "no prior install". The enforcing
-        // simulation will fail closed with NonceReplay if the assumption
-        // is wrong, surfacing a clean error to the caller.
-        void rpc;
-        return 0;
-    }
-}
-/** Fetch the verbatim ScVal the smart account holds for a given rule id.
- *  Used by `interpreter.install` (call 2): the interpreter hashes
- *  `context_rule.signers` at install and re-checks at enforce, so any
- *  client-side reconstruction that differs in any field makes the rule
- *  deny RULE_SIGNERS_CHANGED forever. We round-trip through a `simulate`
- *  of `get_context_rule(ruleId)` and return the raw retval. */
-async function fetchRawContextRule(rpcClient, sourceAccount, smartAccount, ruleId, networkPassphrase) {
-    const source = await rpcClient.getAccount(sourceAccount);
-    const op = Operation.invokeHostFunction({
-        func: xdr.HostFunction.hostFunctionTypeInvokeContract(new xdr.InvokeContractArgs({
-            contractAddress: new Address(smartAccount).toScAddress(),
-            functionName: 'get_context_rule',
-            args: [xdr.ScVal.scvU32(ruleId)],
-        })),
-        auth: [],
-    });
-    const tx = new TransactionBuilder(new Account(sourceAccount, source.sequenceNumber()), {
-        fee: BASE_FEE,
-        networkPassphrase,
-    })
-        .addOperation(op)
-        .setTimeout(0)
-        .build();
-    const sim = await rpcClient.simulateTransaction(tx);
-    if (rpc.Api.isSimulationError(sim)) {
-        throw new Error(`install_predicate: get_context_rule(${ruleId}) simulateTransaction failed: ${sim.error}`);
-    }
-    const retval = sim.result?.retval;
-    if (!retval) {
-        throw new Error(`install_predicate: get_context_rule(${ruleId}) returned no value`);
-    }
-    return retval;
-}
-/** Build the params ScMap for `interpreter.install`. Keys MUST be sorted
- *  by symbol string (the canonical map encoding requires it). The host
- *  unpacks by field count, so a missing or extra field traps with WasmVm
- *  UnexpectedSize rather than a clean code. */
-function buildInstallParams(args) {
-    const entry = (k, v) => new xdr.ScMapEntry({ key: xdr.ScVal.scvSymbol(k), val: v });
-    // Sorted order: grammar_version, install_nonce, oracle_max_deviation_bps,
-    // oracle_max_staleness_seconds, oracle_max_xfeed_dev_bps, predicate,
-    // predicate_hash.
-    return xdr.ScVal.scvMap([
-        entry('grammar_version', xdr.ScVal.scvU32(args.grammarVersion)),
-        entry('install_nonce', xdr.ScVal.scvU32(args.installNonce)),
-        entry('oracle_max_deviation_bps', xdr.ScVal.scvVoid()),
-        entry('oracle_max_staleness_seconds', xdr.ScVal.scvVoid()),
-        entry('oracle_max_xfeed_dev_bps', xdr.ScVal.scvVoid()),
-        entry('predicate', xdr.ScVal.scvBytes(args.predicateBytes)),
-        entry('predicate_hash', xdr.ScVal.scvBytes(args.predicateHashBytes)),
-    ]);
-}
-/** Build an unsigned Soroban transaction envelope. Same pattern as
- *  build-install-policy.ts so the consumer code path is uniform. */
-function buildUnsignedTx(args) {
-    const account = new Account(args.sourceAccount, args.sequence);
-    return new TransactionBuilder(account, {
-        fee: args.fee,
-        networkPassphrase: args.networkPassphrase,
-    })
-        .addOperation(args.op)
-        .setTimeout(0)
-        .build();
-}
-/** Decode the install-predicate call's structured fields directly out of
- *  the final assembled transaction. The bytes are the source of truth:
- *  a human reviewing the install wants to see what the wallet will
- *  actually sign, not what we think it will. The decode is deliberately
- *  strict - any shape we did not build ourselves throws, since that
- *  would mean the XDR was tampered with (or the encoder changed and
- *  this descriptor lags).
- *
- *  The second argument (raw context rule) is passed through verbatim;
- *  we do NOT decode it here because reconstructing the rule's fields
- *  client-side is exactly what the file header warns against. The rule
- *  id lives inside it and is echoed from input at the top-level result. */
-function decodeInstallPredicateCallDescribes(tx, expectedPredicateHash) {
-    const operations = tx.toEnvelope().v1().tx().operations();
-    if (operations.length !== 1 || !operations[0]) {
-        throw new Error(`install_predicate: final transaction has ${operations.length} operations, expected 1`);
-    }
-    const op = operations[0];
-    const hostFn = op.body().invokeHostFunctionOp()?.hostFunction();
-    if (hostFn?.switch().name !== 'hostFunctionTypeInvokeContract') {
-        throw new Error('install_predicate: built op is not an invokeHostFunction(invokeContract(...)) call');
-    }
-    const invokeArgs = hostFn.invokeContract();
-    if (!invokeArgs) {
-        throw new Error('install_predicate: built op has no InvokeContractArgs payload');
-    }
-    const targetContract = Address.fromScAddress(invokeArgs.contractAddress()).toString();
-    const fnName = invokeArgs.functionName().toString();
-    if (fnName !== 'install') {
-        throw new Error(`install_predicate: built op fn name is "${fnName}", expected "install"`);
-    }
-    const scvArgs = invokeArgs.args();
-    if (scvArgs.length !== 3) {
-        throw new Error(`install_predicate: built op has ${scvArgs.length} args, expected 3 (params, raw_context_rule, smart_account)`);
-    }
-    const paramsScv = scvArgs[0];
-    const rawContextRuleScv = scvArgs[1];
-    const smartAccountScv = scvArgs[2];
-    if (!paramsScv || !rawContextRuleScv || !smartAccountScv) {
-        throw new Error('install_predicate: built op args include an undefined slot despite length check');
-    }
-    // params: an ScMap with seven fields (sorted by symbol).
-    if (paramsScv.switch().name !== 'scvMap') {
-        throw new Error('install_predicate: args[0] (params) is not an ScVal::Map');
-    }
-    const paramsFields = new Map();
-    for (const inner of paramsScv.map() ?? []) {
-        const fk = inner.key();
-        if (fk.switch().name !== 'scvSymbol') {
-            throw new Error('install_predicate: params field key is not an ScVal::Symbol');
-        }
-        paramsFields.set(fk.sym().toString(), inner.val());
-    }
-    const EXPECTED_PARAMS_KEYS = [
-        'grammar_version',
-        'install_nonce',
-        'oracle_max_deviation_bps',
-        'oracle_max_staleness_seconds',
-        'oracle_max_xfeed_dev_bps',
-        'predicate',
-        'predicate_hash',
-    ];
-    const actualKeys = [...paramsFields.keys()].sort();
-    if (actualKeys.length !== EXPECTED_PARAMS_KEYS.length ||
-        actualKeys.some((k, i) => k !== EXPECTED_PARAMS_KEYS[i])) {
-        throw new Error(`install_predicate: params keys ${JSON.stringify(actualKeys)} do not match the canonical sorted set ${JSON.stringify(EXPECTED_PARAMS_KEYS)}`);
-    }
-    const grammarVersionScv = paramsFields.get('grammar_version');
-    if (!grammarVersionScv || grammarVersionScv.switch().name !== 'scvU32') {
-        throw new Error('install_predicate: params.grammar_version is missing or not u32');
-    }
-    const grammarVersion = grammarVersionScv.u32();
-    const installNonceScv = paramsFields.get('install_nonce');
-    if (!installNonceScv || installNonceScv.switch().name !== 'scvU32') {
-        throw new Error('install_predicate: params.install_nonce is missing or not u32');
-    }
-    const installNonce = installNonceScv.u32();
-    const predicateScv = paramsFields.get('predicate');
-    if (!predicateScv || predicateScv.switch().name !== 'scvBytes') {
-        throw new Error('install_predicate: params.predicate is missing or not bytes');
-    }
-    const predicateBytes = Buffer.from(predicateScv.bytes());
-    const predicateSha256OfEmbeddedBytes = createHash('sha256').update(predicateBytes).digest('hex');
-    const predicateHashScv = paramsFields.get('predicate_hash');
-    if (!predicateHashScv || predicateHashScv.switch().name !== 'scvBytes') {
-        throw new Error('install_predicate: params.predicate_hash is missing or not bytes');
-    }
-    const predicateHash = Buffer.from(predicateHashScv.bytes()).toString('hex');
-    if (predicateHash !== expectedPredicateHash) {
-        throw new Error(`install_predicate: params.predicate_hash (${predicateHash}) differs from the caller-supplied hash (${expectedPredicateHash})`);
-    }
-    if (rawContextRuleScv.switch().name === 'scvVoid') {
-        throw new Error('install_predicate: args[1] (raw_context_rule) is scvVoid');
-    }
-    if (smartAccountScv.switch().name !== 'scvAddress') {
-        throw new Error('install_predicate: args[2] (smart_account) is not an ScVal::Address');
-    }
-    const smartAccountOnWire = Address.fromScAddress(smartAccountScv.address()).toString();
-    return {
-        targetContract,
-        fnName: 'install',
-        grammarVersion,
-        installNonce,
-        predicateHash,
-        predicateSha256OfEmbeddedBytes,
-        smartAccountOnWire,
-    };
-}
-/** Re-export `Contract` so the run-layer does not need to import the
- *  SDK directly. Mirrors the build-install-policy.ts convention. */
-export { Contract };
-// Suppress the unused-import warning for K_NONCE while keeping the
-// constant visible for the drift test it invites. (Removed once a
-// drift test is in place that references it.)
-void K_NONCE;