@crediolabs/policy-synth 0.1.17 → 0.2.0

package/src/adapters/interpreter/adapter.ts

@@ -1,26 +1,9 @@
 // src/adapters/interpreter/adapter.ts - the interpreter-policy CustodyAdapter.
 //
 // Compiles a PolicyIR to a single interpreter `PolicyDocument` + `PolicyRef`
-// carrying the canonical predicate encoding defined in
-// `packages/policy-interpreter/INTERPRETER_INSTALL_PARAMS.md`. The adapter is
-// the second backend (the OZ built-in adapter is the first); together they
-// cover the canonical language subset. The compose step (P3) routes IR
-// constructs between them.
-//
-// What it lowers (every IR construct the predicate DSL expresses):
-//   - IRLogic and/or    -> PredicateNode and/or
-//   - IRLogic not       -> PredicateNode not
-//   - IRCompare         -> selector(left) vs literal(right), op carried over
-//   - IR `in`           -> needle=selector, haystack=literals (PURESET
-//                          membership; the haystack is always sorted by the
-//                          encoder)
-//   - IR `eq_seq`       -> eq(selectorLeaf, literal_vec([...])) - exact ordered
-//                          sequence equality; element order is preserved
-//                          verbatim (the encoder does NOT sort the vec)
-//   - IRSelector        -> matching PredicateLeaf (see lowerSelector)
-//   - scope.contract    -> sibling `call_contract == <contract>` (always
-//                          emitted when set)
-//   - scope.method      -> sibling `call_fn == <method>`
+// carrying the canonical predicate encoding from `predicate/encode.ts`. Second
+// backend (the OZ built-in adapter is the first); the compose step (P3) routes
+// IR constructs between them.
 //
 // Three fail-closed enforcement gates (per spec):
 //   - oracle_price leaves MUST sit directly under the top-level `and`; nesting
@@ -66,7 +49,7 @@ import type {
  *  deploy artifact we do not have yet; install is a later phase. */
 export const PLACEHOLDER_INTERPRETER_ADDRESS = 'VERIFY-interpreter-address'
 
-/** Wasm-level oracle defaults (mirrors INTERPRETER_INSTALL_PARAMS.md OracleParams).
+/** Wasm-level oracle defaults (mirrors the interpreter's `OracleParams`).
  *  Per-policy overrides may TIGHTEN only - they may never exceed these. */
 export const ORACLE_DEFAULTS = {
   maxStalenessSeconds: 600,
@@ -90,18 +73,16 @@ export interface InterpreterAdapterConfig {
 const CAPABILITIES: CustodyCapabilities = {
   supportsSpendWindow: true,
   supportsThreshold: false, // thresholds are the OZ adapter's job
-  // False for the predicate-leaf path: the interpreter refuses a `valid_until`
-  // leaf at install. Expiry is still available, but as the context rule's
-  // validUntilLedger, which the smart account enforces - not as a predicate.
+  // Expiry is via the context rule's validUntilLedger, not a predicate - the
+  // interpreter refuses a `valid_until` leaf at install.
   supportsTimeExpiry: false,
   supportsOraclePrice: true,
   supportsInvocationCount: true,
   supportsGeneralPredicate: true,
 }
 
-/** Parse confidence for a deterministic (non-decoded) input: full, with an
- *  empty unknown/opaque breakdown. A mandate needs no decoding, so the gate is
- *  not applicable and confidence is 1. */
+/** Parse confidence for a deterministic (non-decoded) input: full (1.0). A
+ *  mandate needs no decoding, so the gate is not applicable. */
 const FULL_PARSE_CONFIDENCE: ParseConfidence = {
   overall: 1,
   knownContracts: [],
@@ -123,12 +104,11 @@ export function createInterpreterAdapter(config: InterpreterAdapterConfig): Cust
 
 /** Lower a single IR rule to the canonical pre-encoding `PredicateNode`. The
  *  orchestrator uses this to wire the self-verify + minimise pipeline: after
- *  `compile(ir)` succeeds (`covered === true`, `proposed` set), the
- *  orchestrator re-derives the PredicateNode via this helper to drive
- *  `minimize` and `runHarness` on the SAME shape the encoder saw. Pure and
- *  deterministic: same `rule + config` -> byte-identical PredicateNode. The
- *  `uncovered` list the adapter surfaces during compile is NOT re-derived
- *  here; callers that need it should use the result of `compile(ir)`. */
+ *  `compile(ir)` succeeds it re-derives the PredicateNode via this helper to
+ *  drive `minimize` and `runHarness` on the SAME shape the encoder saw. Pure
+ *  and deterministic: same `rule + config` -> byte-identical PredicateNode.
+ *  The `uncovered` list is NOT re-derived - callers needing it must use
+ *  `compile(ir)`. */
 export function lowerRuleToPredicate(
   rule: IRPolicyRule,
   config: InterpreterAdapterConfig
@@ -193,9 +173,9 @@ function lowerRule(rule: IRPolicyRule, config: InterpreterAdapterConfig): Lowere
   const uncovered: string[] = []
 
   // scope -> context rule + sibling predicates. contract/method each become
-  // their own `eq` leaf and are merged into the top-level and alongside the
-  // constraints. This keeps the top-level shape `and` (mandatory per the oracle
-  // position rule and the canonical hash stability for `and`).
+  // their own `eq` leaf and are merged into the top-level `and` alongside the
+  // constraints. The top-level MUST be `and` so oracle leaves sit directly
+  // under it (mandatory per the oracle position rule + canonical hash stability).
   const scopeContract: string | undefined = rule.scope.contract
   const scopeMethod: string | undefined = rule.scope.method
   if (rule.scope.chainId !== undefined) {
@@ -324,18 +304,18 @@ function unsupportedConstruct(cond: IRCondition): string | null {
       const s = cond.compare.selector
       if (s.kind === 'calldata') return 'EVM calldata comparison (predicate DSL)'
       if (s.kind === 'value') return 'tx.value comparison (predicate DSL)'
-      // The on-chain interpreter sees ONE authorized call - there is no
-      // `Context.sub_invocations` in v1 - so it cannot observe the
-      // transaction's token movements. `amount` has no value to read, and
-      // `window_spent` accumulates BY that amount, so its counter would never
-      // move. Deriving either from the call payload would quietly swap "value
+      // The on-chain interpreter sees ONE authorized call - no
+      // `Context.sub_invocations` in v1 - so it cannot observe token
+      // movements. `amount` has no value to read, and `window_spent`
+      // accumulates BY that amount, so its counter would never move.
+      // Deriving either from the call payload would quietly swap "value
       // actually moved" for "value the caller declared" - a weaker guarantee
       // than the review card would be claiming.
       //
-      // Rolling spend caps belong to the OZ `spending_limit` primitive, which
-      // is already audited and which the OZ adapter emits. A per-call cap is
-      // expressible here as `arg_field`; bounding it with `invocation_count`
-      // gives an enforceable ceiling per window.
+      // Rolling spend caps belong to the OZ `spending_limit` primitive (already
+      // audited, emitted by the OZ adapter). A per-call cap is expressible here
+      // as `arg_field`; bounding it with `invocation_count` gives an enforceable
+      // ceiling per window.
       return unsourceableSelector(s)
     }
     // Recurse: a nested `and`/`or`/`not` must not smuggle a selector past the
@@ -454,9 +434,9 @@ function lowerSelector(s: IRSelector): PredicateLeaf {
     case 'arg_field':
       return { kind: 'call_arg_field', index: s.argIndex, element: s.element, field: s.field }
     // `amount` / `window_spent` are filtered out by `unsupportedConstruct`
-    // before lowering - the interpreter cannot source either on chain. Reaching
-    // here means the pre-scan was bypassed, so fail loudly rather than emit a
-    // leaf the contract will refuse.
+    // before lowering - the interpreter cannot source either on chain.
+    // Reaching here means the pre-scan was bypassed; fail loudly rather than
+    // emit a leaf the contract will refuse.
     case 'amount':
     case 'window_spent':
       throw new Error(

package/src/adapters/oz/adapter.ts

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

package/src/codegen/compile-gate.ts

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

package/src/codegen/template.ts

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

package/src/install/build-add-context-rule.ts

@@ -226,15 +226,13 @@ function encodePoliciesMap(args: BuildAddContextRuleArgs): xdr.ScVal {
   const entries: xdr.ScMapEntry[] = []
   for (const ref of args.policies) {
     if (ref.kind === 'interpreter') {
-      const val = encodePolicyInstallParams(args)
       entries.push(
         new xdr.ScMapEntry({
           key: Address.fromString(ref.interpreterAddress).toScVal(),
-          val,
+          val: encodePolicyInstallParams(args),
         })
       )
-    }
-    if (ref.kind === 'oz_builtin') {
+    } else if (ref.kind === 'oz_builtin') {
       entries.push(
         new xdr.ScMapEntry({
           key: Address.fromString(ref.instanceAddress).toScVal(),
@@ -320,7 +318,18 @@ function encodeI128(value: string): xdr.ScVal {
   )
 }
 
-function encodePolicyInstallParams(args: BuildAddContextRuleArgs): xdr.ScVal {
+/** The `PolicyInstallParams` ScVal an interpreter policy receives.
+ *
+ *  Exported so the merge remedy can re-install a policy through `add_policy`
+ *  using the SAME encoder as a fresh install. Re-implementing it would risk
+ *  exactly the drift this file warns about: the field order is ABI-significant
+ *  and a differing encoding yields a rule that denies every call. */
+export type PolicyInstallParamArgs = Pick<
+  BuildAddContextRuleArgs,
+  'encodedPredicate' | 'predicateHash' | 'installNonce' | 'oracleParams' | 'grammarVersion'
+>
+
+export function encodePolicyInstallParams(args: PolicyInstallParamArgs): xdr.ScVal {
   const predicate = Buffer.from(args.encodedPredicate, 'base64')
   const computedHash = createHash('sha256').update(predicate).digest('hex')
   if (computedHash !== args.predicateHash) {
@@ -329,58 +338,22 @@ function encodePolicyInstallParams(args: BuildAddContextRuleArgs): xdr.ScVal {
       `predicateHash ${args.predicateHash.slice(0, 16)}... does not match sha256(encodedPredicate) ${computedHash.slice(0, 16)}...`
     )
   }
-  const entries: xdr.ScMapEntry[] = []
-  for (const k of POLICY_INSTALL_PARAM_FIELDS) {
-    const key = xdr.ScVal.scvSymbol(k)
-    switch (k) {
-      case 'grammar_version':
-        entries.push(
-          new xdr.ScMapEntry({
-            key,
-            val: xdr.ScVal.scvU32(args.grammarVersion ?? DEFAULT_GRAMMAR_VERSION),
-          })
-        )
-        break
-      case 'install_nonce':
-        entries.push(new xdr.ScMapEntry({ key, val: xdr.ScVal.scvU32(args.installNonce) }))
-        break
-      case 'predicate':
-        entries.push(new xdr.ScMapEntry({ key, val: xdr.ScVal.scvBytes(predicate) }))
-        break
-      case 'predicate_hash':
-        entries.push(
-          new xdr.ScMapEntry({
-            key,
-            val: xdr.ScVal.scvBytes(Buffer.from(args.predicateHash, 'hex')),
-          })
-        )
-        break
-      case 'oracle_max_staleness_seconds':
-        entries.push(
-          new xdr.ScMapEntry({
-            key,
-            val: encodeOptionU32(args.oracleParams?.maxStalenessSeconds),
-          })
-        )
-        break
-      case 'oracle_max_deviation_bps':
-        entries.push(
-          new xdr.ScMapEntry({
-            key,
-            val: encodeOptionU32(args.oracleParams?.maxDeviationBps),
-          })
-        )
-        break
-      case 'oracle_max_xfeed_dev_bps':
-        entries.push(
-          new xdr.ScMapEntry({
-            key,
-            val: encodeOptionU32(args.oracleParams?.maxCrossFeedDeviationBps),
-          })
-        )
-        break
-    }
+  // Per-field value encoders. Each entry returns the ScVal to drop into the
+  // map; the key symbol comes from the surrounding loop. Adding a field is
+  // one row here plus the symbol in POLICY_INSTALL_PARAM_FIELDS.
+  const oracleParams = args.oracleParams
+  const valueFor: Record<(typeof POLICY_INSTALL_PARAM_FIELDS)[number], () => xdr.ScVal> = {
+    grammar_version: () => xdr.ScVal.scvU32(args.grammarVersion ?? DEFAULT_GRAMMAR_VERSION),
+    install_nonce: () => xdr.ScVal.scvU32(args.installNonce),
+    predicate: () => xdr.ScVal.scvBytes(predicate),
+    predicate_hash: () => xdr.ScVal.scvBytes(Buffer.from(args.predicateHash, 'hex')),
+    oracle_max_staleness_seconds: () => encodeOptionU32(oracleParams?.maxStalenessSeconds),
+    oracle_max_deviation_bps: () => encodeOptionU32(oracleParams?.maxDeviationBps),
+    oracle_max_xfeed_dev_bps: () => encodeOptionU32(oracleParams?.maxCrossFeedDeviationBps),
   }
+  const entries = POLICY_INSTALL_PARAM_FIELDS.map(
+    (k) => new xdr.ScMapEntry({ key: xdr.ScVal.scvSymbol(k), val: valueFor[k]() })
+  )
   // The host orders map entries by the SYMBOL STRING, not by XDR bytes. A
   // length prefix in the XDR encoding would otherwise put `amount` before
   // `address` and produce a struct the contract reads differently. Emit the

package/src/install/build-install-policy.ts

@@ -1,24 +1,21 @@
-// src/install/build-install-policy.ts - builds the unsigned Soroban
-// transaction XDR for `account.add_context_rule(...)` and
-// `account.remove_context_rule(...)`.
+// src/install/build-install-policy.ts - builds the unsigned Soroban transaction
+// XDR for `account.add_context_rule(...)` and `account.remove_context_rule(...)`.
 //
-// The MCP server is stateless and holds no key material (server.ts:10-12),
-// so this module NEVER signs. The caller (the wallet / CLI / SDK consumer)
-// wraps the returned XDR in a transaction envelope and signs that envelope
-// with their wallet; the wallet signature IS the user-confirmation step.
+// The MCP server is stateless and holds no key material, so this module NEVER
+// signs. The caller (wallet / CLI / SDK consumer) wraps the returned XDR in a
+// transaction envelope and signs that envelope with their wallet; the wallet
+// signature IS the user-confirmation step.
 //
-// We deliberately depart from the spec in plans/phase-04 which calls for a
+// We deliberately depart from the original design, which called for a
 // two-call `install_policy`/`confirm_install` pair backed by a host-signed
-// short-TTL `action_id`. That contract requires (a) a stateful store and
-// (b) key material the server does not have, so we ship the simpler ONE-CALL
-// shape. The wallet signature covers the change.
+// short-TTL `action_id`. That contract requires stateful store + key material
+// the server does not have, so we ship the simpler ONE-CALL shape. The wallet
+// signature covers the change.
 //
 // `buildInstallPolicyXdr` installs the policy in ONE call. `add_context_rule`
 // takes `policies` as a `Map<policy_address, install_param>` and the account
 // forwards each install_param to that policy, so the interpreter stores the
-// predicate document as part of this same transaction. Earlier revisions
-// documented a second `interpreter.install` call; that was wrong, and issuing
-// it fails - the account re-enters the interpreter while it is mid-install.
+// predicate document as part of this same transaction.
 
 import { createHash } from 'node:crypto'
 import {
@@ -59,11 +56,10 @@ export interface InstallRpcClient {
  *  `getContractVersion` lookup uses `simulateTransaction` against
  *  `contract.call('grammar_version')` and decodes the returned u32.
  *
- *  The passphrase is a REQUIRED argument rather than something read off the
- *  server: `rpc.Server` does not carry one, so reaching for
- *  `server.networkPassphrase` yielded a non-string and every version probe
- *  died with "Invalid passphrase provided to Transaction". The caller knows
- *  which network it dialled; make it say so. */
+ *  The passphrase is a REQUIRED argument (not read off the server): `rpc.Server`
+ *  does not carry one, so reaching for `server.networkPassphrase` returned a
+ *  non-string and every version probe died with "Invalid passphrase provided to
+ *  Transaction". The caller knows which network it dialled; make it say so. */
 export function rpcClientFromServer(
   server: rpc.Server,
   networkPassphrase: string
@@ -183,6 +179,14 @@ export interface InstallCallDescribes {
    *  is not material to the review card and stays opaque to keep the
    *  description focused on what the human has to recognise. */
   signers: Array<{ kind: 'delegated'; address: string } | { kind: 'external'; verifier: string }>
+  /** Cross-layer L1: a human-readable note about the OZ any-of-N signer
+   *  semantic that fires for rules with multiple signers. Present only
+   *  when `signers.length >= 2` (a single-signer rule is trivially any-of-1,
+   *  and the note would just add noise). The note is purely additive to
+   *  the review card text - it does NOT alter the wire bytes or the
+   *  signer-set constraint, only the description a human reads before
+   *  signing the install. */
+  signerNote: string | null
   /** One entry per policy attached to the rule, decoded from the policies
    *  map (args[4]). The address is the map key; the kind + extras below
    *  describe the value. The interpreter policy also reports the
@@ -616,7 +620,7 @@ function decodeInstallCallDescribes(
     const tag = tuple[0]?.sym().toString()
     const inner = tuple[1]
     if (tag === 'Delegated') {
-      if (!inner || inner.switch().name !== 'scvAddress') {
+      if (inner?.switch().name !== 'scvAddress') {
         throw new Error('install_policy: a Delegated signer is missing its Address')
       }
       signers.push({
@@ -626,7 +630,7 @@ function decodeInstallCallDescribes(
       continue
     }
     if (tag === 'External') {
-      if (!inner || inner.switch().name !== 'scvAddress') {
+      if (inner?.switch().name !== 'scvAddress') {
         throw new Error('install_policy: an External signer is missing its verifier Address')
       }
       signers.push({
@@ -671,14 +675,14 @@ function decodeInstallCallDescribes(
     // OZ primitives carry spending_limit/period_ledgers/threshold/signers.
     if (fields.has('predicate') || fields.has('grammar_version') || fields.has('install_nonce')) {
       const installNonceScv = fields.get('install_nonce')
-      if (!installNonceScv || installNonceScv.switch().name !== 'scvU32') {
+      if (installNonceScv?.switch().name !== 'scvU32') {
         throw new Error(
           `install_policy: interpreter policy ${address} is missing a u32 install_nonce`
         )
       }
       const installNonce = installNonceScv.u32()
       const predicateScv = fields.get('predicate')
-      if (!predicateScv || predicateScv.switch().name !== 'scvBytes') {
+      if (predicateScv?.switch().name !== 'scvBytes') {
         throw new Error(
           `install_policy: interpreter policy ${address} is missing its bytes predicate`
         )
@@ -724,12 +728,26 @@ function decodeInstallCallDescribes(
   // `observedInstallNonce` is the nonce baked into whichever interpreter
   // policy is present; when none, fall back to the caller-supplied value.
   const installNonce = observedInstallNonce ?? expectedInstallNonce
+  // Cross-layer L1: OZ Accounts context rules follow any-of-N semantics for
+  // the signers they accept - any ONE attached signer may authorise a
+  // permitted op under the rule. A user with multiple signers attached
+  // therefore has a strict superset of authority of a single-signer rule,
+  // not a stricter one; the install succeeds as written, but a human
+  // reviewing the install card may expect the opposite (and choose the
+  // wrong threshold because of it). Surface the any-of-N note on the
+  // description so the human reads the same wire-level semantic the
+  // contract enforces.
+  const signerNote =
+    signers.length >= 2
+      ? 'any ONE signer may authorise a permitted op under this rule (OZ any-of-N semantic)'
+      : null
   return {
     targetContract,
     fnName: 'add_context_rule',
     ruleName,
     validUntilLedger,
     signers,
+    signerNote,
     policies,
     installNonce,
   }