@crediolabs/policy-synth 0.1.18 → 0.2.0

package/src/run/index.ts

@@ -18,7 +18,7 @@
 // drive the CLI (which calls into the same core directly without MCP).
 
 import { createHash } from 'node:crypto'
-import { rpc } from '@stellar/stellar-sdk'
+import { rpc, xdr } from '@stellar/stellar-sdk'
 import {
   type ErrorCode,
   type MandateSpec,
@@ -35,6 +35,11 @@ import {
   type ToolError,
   type ToolResponse,
 } from '../index.ts'
+import {
+  type AuthorityOverlap,
+  type ContextType,
+  findAuthorityOverlaps,
+} from '../install/authority-overlap.ts'
 import {
   type BuildInstallPolicyResult,
   type BuildRevokePolicyResult,
@@ -43,7 +48,16 @@ import {
   type InstallRpcClient,
   rpcClientFromServer,
 } from '../install/build-install-policy.ts'
+import { buildMergePolicyXdr } from '../install/build-merge-policy.ts'
 import { getInterpreterInfo } from '../install/get-interpreter-info.ts'
+import { planMergePolicy } from '../install/plan-merge-policy.ts'
+import {
+  accountRuleReaderFromServer,
+  collectObservedRules,
+  nonceLedgerKey,
+} from '../install/read-account-rules.ts'
+import { decodePredicate } from '../predicate/decode.ts'
+import { encodePredicate } from '../predicate/encode.ts'
 import type { SimulationResult } from '../verify/envelope.ts'
 import { simulatePolicy, verifyPolicy } from '../verify/index.ts'
 import {
@@ -51,10 +65,12 @@ import {
   GetInterpreterInfoInputSchema,
   type InstallPolicyInput,
   InstallPolicyInputSchema,
+  type MergePolicyInput,
+  MergePolicyInputSchema,
   NETWORK_PASSPHRASES,
   PINNED_INTERPRETER_ADDRESS_BY_NETWORK,
   PINNED_INTERPRETER_GRAMMAR_VERSION,
-  PINNED_INTERPRETER_WASM_SHA256,
+  PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK,
   type RecordTransactionInput,
   RecordTransactionInputSchema,
   type RevokePolicyInput,
@@ -95,7 +111,7 @@ export {
   PINNED_INTERPRETER_GRAMMAR_VERSION,
   PINNED_INTERPRETER_MAINNET_ADDRESS,
   PINNED_INTERPRETER_TESTNET_ADDRESS,
-  PINNED_INTERPRETER_WASM_SHA256,
+  PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK,
   PredicateLeafSchema,
   PredicateNodeSchema,
   RecordedTransactionSchema,
@@ -335,9 +351,7 @@ export async function runVerifyPolicy(raw: unknown): Promise<ToolResponse<true>>
  *  comes from the RPC). Both gates accept an explicit opt-in flag.
  *  Pin selection follows `input.network` (defaults to `testnet` so the
  *  pre-mainnet callers keep working unchanged). */
-export async function runInstallPolicy(
-  raw: unknown
-): Promise<ToolResponse<BuildInstallPolicyResult>> {
+export async function runInstallPolicy(raw: unknown): Promise<ToolResponse<InstallPolicyResult>> {
   const parsed = InstallPolicyInputSchema.safeParse(raw)
   if (!parsed.success) {
     return {
@@ -383,6 +397,27 @@ export async function runInstallPolicy(
     const predicateHash = createHash('sha256')
       .update(Buffer.from(encodedPredicate, 'base64'))
       .digest('hex')
+
+    // ---- Cross-rule authority scan ----
+    // OZ enforces only the policies of the rule the caller names, so a signer
+    // who also sits in a wider rule keeps that wider authority no matter what
+    // this predicate says. Refuse by default when the wider rule has no policy
+    // at all, because that makes this install decorative.
+    const authorityScan: AuthorityScanReport | undefined = input.skipAuthorityScan
+      ? { ran: false, skipped: true, reason: 'skipped at caller request', overlaps: [] }
+      : await scanAuthorityOverlap({
+          smartAccount: input.smartAccount,
+          interpreterAddress: expectedInterpreter,
+          rule: input.rule,
+          encodedPredicate,
+          rpcUrl: input.rpcUrl ?? expectedRpc,
+          network,
+        })
+    const overlapError = enforceAuthorityScan(authorityScan, input.allowAuthorityOverlap)
+    if (overlapError) {
+      return { ok: false, error: overlapError }
+    }
+
     const result = await buildInstallPolicyXdr({
       smartAccount: input.smartAccount,
       sourceAccount: input.sourceAccount,
@@ -394,7 +429,7 @@ export async function runInstallPolicy(
       rpc: rpcClient,
       ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
     })
-    return { ok: true, data: result }
+    return { ok: true, data: authorityScan ? { ...result, authorityScan } : result }
   } catch (e) {
     return {
       ok: false,
@@ -403,6 +438,343 @@ export async function runInstallPolicy(
   }
 }
 
+/** Default-deny on the cross-rule scan.
+ *
+ *  Refuses whenever the scan cannot establish that this policy binds the calls
+ *  it names. An unpoliced neighbour provably does not constrain them. An
+ *  opaque one, policed by a contract this tool cannot decode, is not KNOWN to,
+ *  and "not known to" is not "safe" - the same posture as the interpreter and
+ *  RPC pins. An incomplete scan is refused for the same reason: the overlap
+ *  list is then a subset of the account, so an empty list proves nothing.
+ *
+ *  `not-restricting` is reported but does NOT block. Both rules are ours and
+ *  both constrain the calls, and the conjunction remedy is offered; refusing
+ *  there would also block the legitimate act of adding a separate capability,
+ *  which OZ composes correctly as a union.
+ *
+ *  Returns a ToolError or null, matching `enforceInterpreterPin`. */
+export function enforceAuthorityScan(
+  scan: AuthorityScanReport | undefined,
+  allowOverlap: boolean | undefined
+): ToolError | null {
+  if (!scan || allowOverlap === true) return null
+
+  // Default-deny by exclusion rather than by enumeration: anything that is not
+  // the one known-safe severity blocks. Listing the blocking severities
+  // instead would mean a severity added later silently passes until someone
+  // remembers to add it here, and the safe direction is the opposite.
+  const blocking = scan.overlaps.filter((o) => o.severity !== 'not-restricting')
+  const unpoliced = blocking.filter((o) => o.severity === 'bypass').map((o) => o.ruleId)
+  const opaque = blocking.filter((o) => o.severity === 'unknown').map((o) => o.ruleId)
+  const unrecognised = blocking
+    .filter((o) => o.severity !== 'bypass' && o.severity !== 'unknown')
+    .map((o) => o.ruleId)
+
+  if (blocking.length > 0) {
+    const parts = [
+      unpoliced.length > 0 ? `rule ${unpoliced.join(', ')} has no policy attached` : '',
+      opaque.length > 0
+        ? `rule ${opaque.join(', ')} is policed by a contract this tool cannot decode`
+        : '',
+      unrecognised.length > 0
+        ? `rule ${unrecognised.join(', ')} carries an overlap this build does not recognise`
+        : '',
+    ].filter(Boolean)
+    return {
+      code: 'INSTALL_BUILD_FAILED',
+      message: `install_policy: a signer of this rule can already make the same calls through another context rule, so this policy is not established to restrict them: ${parts.join('; ')}. Remove the shared signer from that rule, attach a policy this tool can read, or set allowAuthorityOverlap: true to install anyway`,
+      severity: 'error',
+      retryable: false,
+      remediation: { toolCall: { name: 'install_policy', args: {} } },
+    }
+  }
+
+  // A scan that was meant to run and threw tells us nothing. Reporting it in
+  // a string field and proceeding is the same fail-open shape as an incomplete
+  // scan, and a caller that does not read `ran` cannot tell it from a clean
+  // result.
+  if (scan.ran === false && scan.skipped !== true) {
+    return {
+      code: 'INSTALL_BUILD_FAILED',
+      message: `install_policy: the cross-rule authority scan could not run (${scan.reason ?? 'unknown error'}), so it cannot establish that this policy restricts anything; retry, or set allowAuthorityOverlap: true to install without that assurance`,
+      severity: 'error',
+      retryable: true,
+      remediation: { toolCall: { name: 'install_policy', args: {} } },
+    }
+  }
+
+  if (scan.incomplete === true) {
+    return {
+      code: 'INSTALL_BUILD_FAILED',
+      message:
+        'install_policy: the account has more context rules than the scan could account for, so the overlap result is incomplete and cannot establish that this policy restricts anything; set allowAuthorityOverlap: true to install without that assurance',
+      severity: 'error',
+      retryable: false,
+      remediation: { toolCall: { name: 'install_policy', args: {} } },
+    }
+  }
+
+  return null
+}
+
+/** The install response, plus what the cross-rule scan found. The scan is
+ *  advisory data about the account, not part of the transaction, so it is
+ *  additive: a caller that ignores it gets exactly the previous shape. */
+export type InstallPolicyResult = BuildInstallPolicyResult & {
+  authorityScan?: AuthorityScanReport
+}
+
+/** What the cross-rule scan found, carried on the install response so the
+ *  review surface can show it alongside the transaction being signed.
+ *
+ *  SCOPE, and it is narrow: this answers "can a signer OF THIS RULE reach the
+ *  same calls through a different rule". A rule sharing no signer with this
+ *  one cannot be reached by this rule's signers, so it is not a way around
+ *  this policy; it is a different principal's authority, which no policy
+ *  installed here was ever going to constrain. Other rules keep their own
+ *  signers, and an account administrator can add signers or rules afterwards.
+ *
+ *  An empty `overlaps` is therefore NOT a statement that the account is safe,
+ *  only that this rule's own signers gain no unconstrained path through the
+ *  rules that exist right now. */
+export interface AuthorityScanReport {
+  /** False when the scan did not run. `reason` then says why, and the absence
+   *  of overlaps proves nothing. */
+  ran: boolean
+  /** True when the caller passed `skipAuthorityScan`. Distinguishes a
+   *  deliberate skip from a scan that tried and failed: both carry
+   *  `ran: false`, but only the failure refuses the install. Recorded rather
+   *  than omitted so the response shows that no opinion was formed, instead
+   *  of looking like a version that never had the check. */
+  skipped?: boolean
+  /** True when the account has more rules than the scan accounted for, so the
+   *  overlap list is a subset. */
+  incomplete?: boolean
+  reason?: string
+  overlaps: AuthorityOverlap[]
+}
+
+/** Read the account's other context rules and report where this install's
+ *  signers already hold authority over the same calls.
+ *
+ *  A failure to read is reported rather than thrown, and the caller-facing
+ *  decision is made by `enforceAuthorityScan`: a scan that tried and failed
+ *  tells us nothing, so it refuses rather than passing as a clean account.
+ *
+ *  The account data this trusts comes from whichever RPC answered, so a
+ *  hostile RPC could describe an account with no overlapping rules. That is
+ *  bounded by the pin already enforced above: `enforceRpcPin` returns before
+ *  this runs, so the URL is the pinned one for the network unless the caller
+ *  explicitly set `allowUnpinnedRpcUrl`. This scan deliberately does not add a
+ *  second pin check, because two places deciding the same thing drift. */
+async function scanAuthorityOverlap(args: {
+  smartAccount: string
+  interpreterAddress: string
+  rule: InstallPolicyInput['rule']
+  encodedPredicate: string
+  rpcUrl: string
+  network: Network
+}): Promise<AuthorityScanReport | undefined> {
+  try {
+    if (!args.encodedPredicate) {
+      // Not applicable rather than failed: this rule installs no interpreter
+      // predicate, so there is nothing of ours for another rule to undercut.
+      // Returning undefined keeps it out of the refusal path, which is
+      // reserved for scans that were meant to run and could not.
+      return undefined
+    }
+    const server = new rpc.Server(args.rpcUrl, { allowHttp: false })
+    const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[args.network])
+    const collected = await collectObservedRules({
+      reader,
+      smartAccount: args.smartAccount,
+      interpreterAddress: args.interpreterAddress,
+    })
+    const overlaps = findAuthorityOverlaps({
+      intended: {
+        // `add_context_rule` always creates a NEW rule, so there is no id to
+        // exclude; -1 matches nothing on the account.
+        ruleId: -1,
+        contextType: toOverlapContextType(args.rule.contextRuleType),
+        signers: args.rule.signers,
+        predicate: decodePredicate(args.encodedPredicate),
+      },
+      existing: collected.rules,
+    })
+    return { ran: true, incomplete: collected.incomplete, overlaps }
+  } catch (e) {
+    return {
+      ran: false,
+      reason: e instanceof Error ? e.message : String(e),
+      overlaps: [],
+    }
+  }
+}
+
+/** The rule draft names the callee `contract`; the analyser calls it
+ *  `address`. Same value, two vocabularies. */
+function toOverlapContextType(ct: InstallPolicyInput['rule']['contextRuleType']): ContextType {
+  switch (ct.kind) {
+    case 'call_contract':
+      return { kind: 'call_contract', address: ct.contract }
+    case 'create_contract':
+      return { kind: 'create_contract', wasmHash: ct.wasmHash }
+    default:
+      return { kind: 'default' }
+  }
+}
+
+/** The merge response: one step's transaction plus what it will cost. */
+export interface MergePolicyResult {
+  unsignedXdr: string
+  smartAccount: string
+  sourceAccount: string
+  step: 'detach' | 'reinstall'
+  call: { contract: string; fn: string; ruleId: number }
+  authNonce: string
+  authValidUntilLedger: number
+  rootInvocationXdr: string
+  /** sha256 of the merged predicate, so the caller can pin what step 2 will
+   *  install while they are still looking at step 1. */
+  mergedPredicateHash: string
+  mergedPredicateBlobBase64: string
+  warnings: string[]
+  followUp: string
+}
+
+/** `merge_policy` body - the tightening remedy for a cross-rule overlap.
+ *
+ *  Replaces a rule's predicate with the conjunction of it and a new one. This
+ *  is the action `install_policy` recommends when it reports an overlap
+ *  between two rules our interpreter polices, and it is deliberately NOT
+ *  something `install_policy` does on its own: it detaches a live policy, so
+ *  the operator has to ask for it.
+ *
+ *  Two transactions in order. `add_policy` refuses a policy already on the
+ *  rule, so the old attachment goes first, and the second transaction cannot
+ *  be simulated until the first confirms. */
+export async function runMergePolicy(raw: unknown): Promise<ToolResponse<MergePolicyResult>> {
+  const parsed = MergePolicyInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return { ok: false, error: validationError('install_policy', parsed.error.issues) }
+  }
+  const input: MergePolicyInput = parsed.data
+  const network: Network = input.network ?? 'testnet'
+  const expectedInterpreter = PINNED_INTERPRETER_ADDRESS_BY_NETWORK[network]
+  const expectedRpc = RPC_URL_BY_NETWORK[network]
+
+  const rpcPinningError = enforceRpcPin(
+    'install_policy',
+    input.rpcUrl,
+    input.allowUnpinnedRpcUrl,
+    expectedRpc,
+    network
+  )
+  if (rpcPinningError) return { ok: false, error: rpcPinningError }
+
+  try {
+    const rpcUrl = input.rpcUrl ?? expectedRpc
+    const server = new rpc.Server(rpcUrl, { allowHttp: false })
+    const reader = accountRuleReaderFromServer(server, NETWORK_PASSPHRASES[network])
+    const collected = await collectObservedRules({
+      reader,
+      smartAccount: input.smartAccount,
+      interpreterAddress: expectedInterpreter,
+    })
+    const rule = collected.rules.find((r) => r.id === input.ruleId)
+    if (!rule) {
+      return {
+        ok: false,
+        error: {
+          code: 'INSTALL_BUILD_FAILED',
+          message: `merge_policy: rule ${input.ruleId} was not found on ${input.smartAccount}${
+            collected.incomplete
+              ? ' (the rule scan was incomplete, so it may exist but was not reached)'
+              : ''
+          }`,
+          severity: 'error',
+          retryable: false,
+          remediation: { toolCall: { name: 'install_policy', args: {} } },
+        },
+      }
+    }
+
+    const plan = planMergePolicy({
+      rule,
+      interpreterAddress: expectedInterpreter,
+      incoming: decodePredicate(input.incomingPredicateBlobBase64),
+      step: input.step,
+    })
+    if (!plan.ok) {
+      return {
+        ok: false,
+        error: {
+          code: 'INSTALL_BUILD_FAILED',
+          message: `merge_policy: ${plan.reason}`,
+          severity: 'error',
+          retryable: false,
+          remediation: { toolCall: { name: 'install_policy', args: {} } },
+        },
+      }
+    }
+
+    const encoded = encodePredicate(plan.predicate)
+
+    // The nonce is read, not assumed. OZ's `remove_policy` discards the result
+    // of `try_uninstall`, so a detach whose uninstall panicked - our
+    // `uninstall` panics MissingState when the master set has been archived -
+    // detaches the policy while leaving our nonce behind. Re-installing at 1
+    // would then be refused as a replay and the rule would sit unpoliced.
+    let installNonce = 1
+    const nonceWarnings: string[] = []
+    if (input.step === 'reinstall') {
+      const entries = await server.getLedgerEntries(
+        nonceLedgerKey(expectedInterpreter, input.smartAccount, input.ruleId)
+      )
+      const raw = entries.entries?.[0]?.val
+      const stored =
+        raw && raw.switch() === xdr.LedgerEntryType.contractData()
+          ? raw.contractData().val()
+          : undefined
+      if (stored && stored.switch() === xdr.ScValType.scvU32()) {
+        installNonce = stored.u32() + 1
+        nonceWarnings.push(
+          `the previous uninstall did not complete: rule ${input.ruleId} still holds interpreter state at nonce ${stored.u32()}, so this reinstalls at ${installNonce} rather than 1. The rule's counters were NOT reset.`
+        )
+      }
+    }
+
+    const built = await buildMergePolicyXdr({
+      smartAccount: input.smartAccount,
+      sourceAccount: input.sourceAccount,
+      networkPassphrase: NETWORK_PASSPHRASES[network],
+      ruleId: input.ruleId,
+      policyId: plan.policyId,
+      interpreterAddress: expectedInterpreter,
+      step: input.step,
+      encodedPredicate: encoded.encodedPredicate,
+      predicateHash: encoded.predicateHash,
+      installNonce,
+      ...(plan.oracleParams ? { oracleParams: plan.oracleParams } : {}),
+      rpc: rpcClientFromServer(server, NETWORK_PASSPHRASES[network]),
+      ...(input.baseFee !== undefined ? { baseFee: input.baseFee } : {}),
+    })
+
+    return {
+      ok: true,
+      data: {
+        ...built,
+        mergedPredicateHash: encoded.predicateHash,
+        mergedPredicateBlobBase64: encoded.encodedPredicate,
+        warnings: [...plan.warnings, ...nonceWarnings],
+        followUp: plan.followUp,
+      },
+    }
+  } catch (e) {
+    return { ok: false, error: caughtError('install_policy', 'INSTALL_BUILD_FAILED', e) }
+  }
+}
+
 /** `revoke_policy` body - thin wrapper over `buildRevokePolicyXdr`.
  *  Emits an unsigned XDR for `account.remove_context_rule(ruleId)`; the
  *  smart account itself handles uninstalling each attached policy. Auth
@@ -469,12 +841,12 @@ export async function runRevokePolicy(
  *  fabricating it would be a lie on a security surface; the live
  *  mismatch check is worth MORE).
  *
- *  Network-aware: `input.network` selects which interpreter pin and RPC
- *  to use. Mainnet was rolled out 2026-08-04 - the same wasm hash was
- *  uploaded to mainnet as was exercised on testnet, so a single
- *  `PINNED_INTERPRETER_WASM_SHA256` constant backs both networks.
- *  The address differs because instance ids are network-scoped.
- *  UNAUDITED at the time of writing.
+ *  Network-aware: `input.network` selects the interpreter address, the RPC
+ *  and the wasm hash. The networks run different binaries - testnet carries
+ *  the selector-leaf minimum and the signer-set cap, mainnet predates both -
+ *  so the hash is read through
+ *  `PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK`. UNAUDITED at the time of
+ *  writing.
  *
  *  Same RPC pin as install/revoke: when `verifyLive` triggers an outbound
  *  call, the auth-digest + the answer bind to whichever RPC answered, so
@@ -522,7 +894,7 @@ export async function runGetInterpreterInfo(
     const info = getInterpreterInfo({
       pinnedAddress,
       pinnedGrammarVersion: PINNED_INTERPRETER_GRAMMAR_VERSION,
-      pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256,
+      pinnedWasmHash: PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK[network],
       network,
       ...(deployedGrammarVersion !== undefined ? { deployedGrammarVersion } : {}),
     })

package/src/run/schemas.ts

@@ -176,6 +176,23 @@ export const ComposeUserResponsesSchema = z
     swapRecipientAllowlist: z
       .array(z.string().refine(isStellarAddress, 'must be a Stellar address (G... or C...)'))
       .optional(),
+    // Per-asset oracle-price bound, one entry per asset. Reaches
+    // `compose-from-recording` and emits an `oracle_price` compare. Declared
+    // here because the object is `.passthrough()`: the field already worked
+    // undeclared, which left the accepted surface wider than the documented
+    // one. `decimals` is REQUIRED - oracle prices normalise to 9 dp and a
+    // threshold silently assumed to share that basis is what let a raw 14-dp
+    // bound permit everything.
+    oraclePriceBound: z
+      .array(
+        z.object({
+          asset: z.string().refine(isStellarAddress, 'must be a Stellar address (G... or C...)'),
+          operator: z.enum(['eq', 'lt', 'lte', 'gt', 'gte']),
+          value: z.string().regex(/^[0-9]+$/),
+          decimals: z.number().int().min(0).max(U32_MAX),
+        })
+      )
+      .optional(),
   })
   .passthrough()
 
@@ -502,20 +519,31 @@ const MandateSpecSchemaForRule = z
 /** Pinned interpreter address (testnet).
  *  Single source for the MCP layer; do not embed elsewhere. */
 export const PINNED_INTERPRETER_TESTNET_ADDRESS =
-  'CDR4NLV22STCXFGZPNKDQTEANWLF7LZ6AJLY6B7CLJXKHDZGYJWIOKGP'
+  'CALHNU4LXZRKFAXYRBODTGDANTNXHJPBTJNYGLUWLIFIP24NWSGWIE4K'
 
-/** Pinned interpreter address (mainnet). Mainnet
- *  has now been deployed (2026-08-04); the mainnet interpreter IS the binary
- *  that was exercised on testnet (same wasm sha256, see
- *  PINNED_INTERPRETER_WASM_SHA256). The address differs because instance
- *  ids are network-scoped. UNAUDITED at the time of writing. */
+/** Pinned interpreter address (mainnet), deployed 2026-08-04.
+ *  UNAUDITED at the time of writing. */
 export const PINNED_INTERPRETER_MAINNET_ADDRESS =
   'CALZAMUPREIRY4TULBEXIK77AUTOEJG63XLCPUWEHHQDOVK6ZVVS7VQ2'
 
-/** Pinned interpreter wasm sha256 (hex). */
+/** Pinned interpreter wasm sha256 (hex), mainnet.
+ *
+ *  The two networks no longer run the same binary. Testnet carries the
+ *  selector-leaf minimum and the signer-set cap; mainnet predates both. Read
+ *  the hash through `PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK` rather than
+ *  this constant unless mainnet is specifically what is meant, or
+ *  `get_interpreter_info` will report a hash the queried network does not
+ *  run. */
 export const PINNED_INTERPRETER_WASM_SHA256 =
   '6e6c13d93e197aa380303a42cd120f5ddb080dd36ef2a343ee1dbd04ca52a443'
 
+/** Pinned interpreter wasm sha256 (hex), testnet. Byte-identical to the
+ *  artifact built from `contracts/policy-interpreter` at the commit that
+ *  introduced errors 216 and 217, verified by fetching the deployed wasm back
+ *  off chain. */
+export const PINNED_INTERPRETER_WASM_SHA256_TESTNET =
+  'a4d58bc88fd82bbb8e223941ba5889db919717fae92ced13f6f55bfe583b8e22'
+
 /** The grammar version the interpreter enforces (matches SELF_VERSION in
  *  contracts/policy-interpreter/src/version.rs). */
 export const PINNED_INTERPRETER_GRAMMAR_VERSION = 1
@@ -532,14 +560,18 @@ export const TESTNET_RPC_URL = 'https://soroban-testnet.stellar.org'
  *  the deploy script hit during the 2026-08-04 mainnet rollout. */
 export const MAINNET_RPC_URL = 'https://mainnet.sorobanrpc.com'
 
-/** Pin + RPC lookup for the gate enforcement. The interpreters' wasm sha256
- *  is identical across both networks (the same binary was uploaded both
- *  places), so `PINNED_INTERPRETER_WASM_SHA256` stays
- *  a single constant - only the addresses and RPCs are network-scoped. */
+/** Pin + RPC lookup for the gate enforcement. Addresses, RPCs and wasm
+ *  hashes are all network-scoped: the networks diverged when the
+ *  selector-leaf and signer-cap controls were deployed to testnet ahead of
+ *  mainnet. */
 export const PINNED_INTERPRETER_ADDRESS_BY_NETWORK: Record<Network, string> = {
   testnet: PINNED_INTERPRETER_TESTNET_ADDRESS,
   mainnet: PINNED_INTERPRETER_MAINNET_ADDRESS,
 }
+export const PINNED_INTERPRETER_WASM_SHA256_BY_NETWORK: Record<Network, string> = {
+  testnet: PINNED_INTERPRETER_WASM_SHA256_TESTNET,
+  mainnet: PINNED_INTERPRETER_WASM_SHA256,
+}
 export const RPC_URL_BY_NETWORK: Record<Network, string> = {
   testnet: TESTNET_RPC_URL,
   mainnet: MAINNET_RPC_URL,
@@ -607,6 +639,17 @@ export const InstallPolicyInputSchema = z
      *  everything. Selecting `network: 'mainnet'` is NOT an opt-in -
      *  the mainnet pin is its own deny-by-default anchor. */
     allowUnpinnedInterpreter: z.boolean().optional(),
+    /** Opt-in to installing when a signer of this rule can already reach the
+     *  same calls through a context rule that has NO policy attached. OZ lets
+     *  the signer choose which rule authorises a call and enforces only that
+     *  rule's policies, so an unpoliced rule covering the same calls makes
+     *  this policy decorative. Default-deny, because the caller almost
+     *  certainly believes they are restricting something. */
+    allowAuthorityOverlap: z.boolean().optional(),
+    /** Skip the cross-rule authority scan entirely. The scan costs one RPC
+     *  read per rule on the account; skipping it means the response carries
+     *  no statement about what the signers can already do. */
+    skipAuthorityScan: z.boolean().optional(),
     /** Base fee in stroops; defaults to BASE_FEE (100). */
     baseFee: z.number().int().positive().optional(),
   })
@@ -615,6 +658,36 @@ export const InstallPolicyInputSchema = z
   })
 export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>
 
+/** `merge_policy` input.
+ *
+ *  The tightening remedy for a cross-rule overlap: replace a rule's predicate
+ *  with the conjunction of it and a new one. Two transactions, in order,
+ *  because OZ refuses to re-attach a policy already on the rule - so the
+ *  caller runs `detach`, waits for it to confirm, then runs `reinstall`. */
+export const MergePolicyInputSchema = z
+  .object({
+    smartAccount: z
+      .string()
+      .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    sourceAccount: z
+      .string()
+      .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    /** The rule whose predicate is being tightened. */
+    ruleId: z.number().int().nonnegative(),
+    /** The predicate to conjoin, base64 canonical ScVal, as emitted by
+     *  `synthesize_policy`. */
+    incomingPredicateBlobBase64: z.string().min(1),
+    /** Which half of the remedy to build. */
+    step: z.enum(['detach', 'reinstall']),
+    network: NetworkSchema.optional(),
+    rpcUrl: z.string().url().optional(),
+    allowUnpinnedRpcUrl: z.boolean().optional(),
+    baseFee: z.number().int().positive().optional(),
+  })
+  .strict()
+
+export type MergePolicyInput = z.infer<typeof MergePolicyInputSchema>
+
 export const RevokePolicyInputSchema = z
   .object({
     /** The smart account contract address (C...). */