@crediolabs/policy-synth 0.3.1 → 0.4.0

package/src/install/authority-overlap.ts

@@ -0,0 +1,312 @@
+// src/install/authority-overlap.ts - cross-rule authority analysis.
+//
+// An OZ smart account selects a context rule by CALLER DECLARATION and enforces
+// only the policies of the rule that was named. A signer belonging to several
+// rules therefore picks which one applies, so for any given call their
+// authority is the MAXIMUM over the matching rules, never the intersection.
+//
+// The consequence is the one that catches people: installing a second, tighter
+// rule restricts nothing. A key that also sits on an unpoliced rule is not
+// constrained at all - it names that rule and the predicate never runs. This
+// module detects that at install time, before the caller acts on a policy that
+// looks binding and is not.
+//
+// Not theoretical. Proven on chain 2026-08-22: the same key, the same account
+// and the same forbidden call was denied `#100` naming the policed rule and
+// PERMITTED naming an unpoliced one. It happened in this project's own end-to-
+// end harness, written by the author of the grammar, and was caught by review
+// rather than by tooling - which is why the tooling now exists.
+//
+// Adapted to grammar 3 from the version published in `@crediolabs/policy-synth`
+// 0.2.0, which came from the `octogate` repository and was lost when the npm
+// lineage moved here. `or` and `not` are gone from the grammar, so the cases
+// handling them are gone too; oracle bounds are gone from the stored document.
+//
+// Pure: no network. The caller supplies the account's rules.
+
+import type { PredicateLeaf, PredicateNode, SignerDraft } from '../types.ts'
+
+/** Wildcard component of a `Selector`: the predicate does not pin this half. */
+export const ANY = '*'
+
+/** A (contract, function) pair a predicate may permit. `ANY` in either half
+ *  means unconstrained, so `{contract: ANY, fn: ANY}` is "any call at all". */
+export interface Selector {
+  contract: string
+  fn: string
+}
+
+export type ContextType =
+  | { kind: 'default' }
+  | { kind: 'call_contract'; contract: string }
+  | { kind: 'create_contract'; wasmHash: string }
+
+/** How much can be said about a neighbouring rule.
+ *  - `interpreter`: policed by our interpreter and the predicate was readable,
+ *    so its authority is known exactly.
+ *  - `foreign`: policed by some other contract. The address is visible, the
+ *    semantics are not, so it needs review by hand.
+ *  - `unpoliced`: no policy at all. Whatever its context type allows, its
+ *    signers may do without constraint. */
+export type RuleClass = 'interpreter' | 'foreign' | 'unpoliced'
+
+export interface ObservedRule {
+  id: number
+  contextType: ContextType
+  signers: SignerDraft[]
+  /** Policy contract addresses attached to the rule, in OZ's order. */
+  policyAddresses: string[]
+  /** Decoded predicate. Present only when the rule is policed by OUR
+   *  interpreter and the stored document was readable. */
+  predicate?: PredicateNode
+}
+
+export interface IntendedInstall {
+  /** Rule the predicate is being installed onto. A re-install onto the same
+   *  id REPLACES its predicate rather than adding a second source of
+   *  authority, so that id is skipped. */
+  ruleId: number
+  contextType: ContextType
+  signers: SignerDraft[]
+  predicate: PredicateNode
+}
+
+export type OverlapSeverity =
+  /** A neighbouring rule imposes no constraint at all on the shared calls. */
+  | 'bypass'
+  /** A neighbouring policy exists but what it permits cannot be read. */
+  | 'unknown'
+  /** Both rules are ours. The new rule will not restrict the shared calls,
+   *  because the signer names whichever is more permissive. */
+  | 'not-restricting'
+
+export interface AuthorityOverlap {
+  ruleId: number
+  ruleClass: RuleClass
+  severity: OverlapSeverity
+  /** Signers present in BOTH rules. An overlap is only reachable by a signer
+   *  who can name both, so a rule sharing no signer is not a collision. */
+  sharedSigners: SignerDraft[]
+  /** The selectors both rules can serve. Non-empty by construction. */
+  sharedSelectors: Selector[]
+  advice: string
+}
+
+// ---- signer identity ----
+
+/** Canonical key for signer equality. Mirrors OZ's `Signer` enum: a delegated
+ *  signer is its address, an external signer is the verifier plus the key
+ *  bytes, since one verifier may hold many keys. */
+export function signerKey(s: SignerDraft): string {
+  return s.kind === 'delegated' ? `delegated:${s.address}` : `external:${s.verifier}:${s.keyBytes}`
+}
+
+function sharedSigners(a: SignerDraft[], b: SignerDraft[]): SignerDraft[] {
+  const bKeys = new Set(b.map(signerKey))
+  return a.filter((s) => bKeys.has(signerKey(s)))
+}
+
+// ---- selector extraction ----
+
+const WILDCARD: Selector = { contract: ANY, fn: ANY }
+
+function selectorKey(s: Selector): string {
+  return `${s.contract} ${s.fn}`
+}
+
+function dedupe(sels: Selector[]): Selector[] {
+  const seen = new Map<string, Selector>()
+  for (const s of sels) seen.set(selectorKey(s), s)
+  return [...seen.values()]
+}
+
+/** Intersect one pair. `ANY` absorbs, equal literals survive, and two
+ *  different literals cannot both hold for a single call. */
+function intersectOne(a: Selector, b: Selector): Selector | null {
+  const contract =
+    a.contract === ANY
+      ? b.contract
+      : b.contract === ANY
+        ? a.contract
+        : a.contract === b.contract
+          ? a.contract
+          : null
+  if (contract === null) return null
+  const fn = a.fn === ANY ? b.fn : b.fn === ANY ? a.fn : a.fn === b.fn ? a.fn : null
+  if (fn === null) return null
+  return { contract, fn }
+}
+
+/** Intersection of two selector SETS: every compatible pairing survives. */
+export function intersectSelectors(a: Selector[], b: Selector[]): Selector[] {
+  const out: Selector[] = []
+  for (const x of a) {
+    for (const y of b) {
+      const hit = intersectOne(x, y)
+      if (hit) out.push(hit)
+    }
+  }
+  return dedupe(out)
+}
+
+function literalAddress(leaf: PredicateLeaf): string | null {
+  return leaf.kind === 'literal_address' ? leaf.value : null
+}
+
+function literalSymbol(leaf: PredicateLeaf): string | null {
+  return leaf.kind === 'literal_symbol' ? leaf.value : null
+}
+
+/** Selector pinned by a single `eq`, whichever side the literal sits on. */
+function selectorFromEq(left: PredicateLeaf, right: PredicateLeaf): Selector | null {
+  if (left.kind === 'call_contract') {
+    const addr = literalAddress(right)
+    return addr === null ? null : { contract: addr, fn: ANY }
+  }
+  if (right.kind === 'call_contract') {
+    const addr = literalAddress(left)
+    return addr === null ? null : { contract: addr, fn: ANY }
+  }
+  if (left.kind === 'call_fn') {
+    const sym = literalSymbol(right)
+    return sym === null ? null : { contract: ANY, fn: sym }
+  }
+  if (right.kind === 'call_fn') {
+    const sym = literalSymbol(left)
+    return sym === null ? null : { contract: ANY, fn: sym }
+  }
+  return null
+}
+
+/**
+ * The set of `(contract, fn)` selectors a predicate may permit.
+ *
+ * A deliberate OVER-approximation: every call the predicate actually permits is
+ * covered by some returned selector, and unrecognised structure widens to the
+ * wildcard rather than narrowing. That direction is what makes the emptiness
+ * test sound. A call carries exactly one `(contract, fn)`, so if two
+ * predicates' over-approximations do not intersect, no single call can be
+ * routed to either and the rules provably cannot collide.
+ *
+ * Narrowing instead would be the fail-OPEN direction: it would let this report
+ * "no overlap" for rules that do collide.
+ */
+export function permittedSelectors(node: PredicateNode): Selector[] {
+  switch (node.op) {
+    case 'and': {
+      // Every conjunct must hold at once, so the permitted set is the
+      // intersection. Intersecting over-approximations stays one.
+      let acc: Selector[] = [WILDCARD]
+      for (const child of node.children) acc = intersectSelectors(acc, permittedSelectors(child))
+      return acc
+    }
+    case 'eq': {
+      const sel = selectorFromEq(node.left, node.right)
+      return sel === null ? [WILDCARD] : [sel]
+    }
+    case 'in': {
+      // Set membership over the selector halves: `call_fn in {a, b}` permits
+      // both. A haystack element that is not the matching literal kind makes
+      // the node uninformative rather than narrower.
+      if (node.needle.kind === 'call_contract') {
+        const addrs = node.haystack.map(literalAddress)
+        if (addrs.some((a) => a === null)) return [WILDCARD]
+        return dedupe((addrs as string[]).map((a) => ({ contract: a, fn: ANY })))
+      }
+      if (node.needle.kind === 'call_fn') {
+        const syms = node.haystack.map(literalSymbol)
+        if (syms.some((s) => s === null)) return [WILDCARD]
+        return dedupe((syms as string[]).map((s) => ({ contract: ANY, fn: s })))
+      }
+      return [WILDCARD]
+    }
+    default:
+      // `lte` binds an amount, never the selector.
+      return [WILDCARD]
+  }
+}
+
+/** Selectors a context type admits, before the predicate narrows them. */
+export function selectorsForContextType(ct: ContextType): Selector[] {
+  switch (ct.kind) {
+    case 'default':
+      return [WILDCARD]
+    case 'call_contract':
+      return [{ contract: ct.contract, fn: ANY }]
+    case 'create_contract':
+      // A contract-creation context is a different `Context` shape. The
+      // interpreter refuses anything that is not `Context::Contract`, and a
+      // creation rule can never serve a call, so it shares no selector.
+      return []
+  }
+}
+
+/** What a rule can actually authorise: its context type narrowed by its
+ *  predicate. An unpoliced or unreadable rule contributes no narrowing. */
+export function effectiveSelectors(rule: ObservedRule): Selector[] {
+  const fromType = selectorsForContextType(rule.contextType)
+  if (!rule.predicate) return fromType
+  return intersectSelectors(fromType, permittedSelectors(rule.predicate))
+}
+
+function classifyRule(rule: ObservedRule): RuleClass {
+  if (rule.policyAddresses.length === 0) return 'unpoliced'
+  return rule.predicate ? 'interpreter' : 'foreign'
+}
+
+function adviceFor(cls: RuleClass, ruleId: number): string {
+  switch (cls) {
+    case 'unpoliced':
+      return `rule ${ruleId} has no policy attached, so a shared signer may make these calls with no constraint at all - the predicate you are installing will never run for them. Remove the shared signer from rule ${ruleId}, or attach a policy to it.`
+    case 'foreign':
+      return `rule ${ruleId} is policed by a contract this tool cannot decode, so its authority over these calls is unknown. Review it by hand before relying on the new rule.`
+    case 'interpreter':
+      return `a shared signer may name rule ${ruleId} instead, so the new rule will not restrict these calls. To TIGHTEN, edit rule ${ruleId} itself rather than adding a second rule. To ADD a separate capability, keep both and expect neither to constrain the other.`
+  }
+}
+
+/**
+ * Every existing rule a signer of the intended install could name instead.
+ *
+ * A rule collides when it shares at least one signer AND at least one selector.
+ * Both are needed for the signer to have a choice: same signer but disjoint
+ * calls means no call can be rerouted, and same calls but no shared signer
+ * means nobody can reroute them.
+ */
+export function findAuthorityOverlaps(args: {
+  intended: IntendedInstall
+  existing: ObservedRule[]
+}): AuthorityOverlap[] {
+  const intendedSelectors = intersectSelectors(
+    selectorsForContextType(args.intended.contextType),
+    permittedSelectors(args.intended.predicate)
+  )
+  const out: AuthorityOverlap[] = []
+
+  for (const rule of args.existing) {
+    if (rule.id === args.intended.ruleId) continue
+
+    const shared = sharedSigners(args.intended.signers, rule.signers)
+    if (shared.length === 0) continue
+
+    const sharedSelectors = intersectSelectors(intendedSelectors, effectiveSelectors(rule))
+    if (sharedSelectors.length === 0) continue
+
+    const ruleClass = classifyRule(rule)
+    out.push({
+      ruleId: rule.id,
+      ruleClass,
+      severity:
+        ruleClass === 'unpoliced'
+          ? 'bypass'
+          : ruleClass === 'foreign'
+            ? 'unknown'
+            : 'not-restricting',
+      sharedSigners: shared,
+      sharedSelectors,
+      advice: adviceFor(ruleClass, rule.id),
+    })
+  }
+
+  return out
+}

package/src/install/index.ts

@@ -12,6 +12,26 @@
 // 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.
+
+// Cross-rule authority analysis. Exported because the check has to happen
+// wherever an install is BUILT, and a client that assembles its own
+// `add_context_rule` call never reaches `runInstallPolicy`.
+export {
+  ANY,
+  type AuthorityOverlap,
+  type ContextType,
+  effectiveSelectors,
+  findAuthorityOverlaps,
+  type IntendedInstall,
+  intersectSelectors,
+  type ObservedRule,
+  type OverlapSeverity,
+  permittedSelectors,
+  type RuleClass,
+  type Selector,
+  selectorsForContextType,
+  signerKey,
+} from './authority-overlap.ts'
 export {
   ADD_CONTEXT_RULE_SYMBOL,
   type AddContextRuleArgs,

package/src/record/index.ts

@@ -17,8 +17,13 @@
 // Returns ToolResponse<RecordedTransaction> per the canonical envelope
 // defined in src/errors.ts.
 
-import type { xdr } from '@stellar/stellar-sdk'
+import { Networks, type xdr } from '@stellar/stellar-sdk'
 import type { ToolError, ToolResponse } from '../errors.ts'
+import {
+  resolveContractsByOnChainSpec,
+  type SpecFetcher,
+  specFetcherFromRpc,
+} from '../registry/on-chain-spec.ts'
 import type { Network, ParseConfidence, RecordedTransaction } from '../types.ts'
 import type { DecodedTransaction } from './decode.ts'
 import {
@@ -34,7 +39,7 @@ import {
   isBelowThreshold,
 } from './freshness.ts'
 import { extractTokenMovements } from './movements.ts'
-import { createRpcServer, type RpcFetcher } from './rpc.ts'
+import { createRpcServer, PUBLIC_RPC_URLS, type RpcFetcher } from './rpc.ts'
 import { validateAgainstEvents } from './validate.ts'
 
 /** Public input shape. The brief pins:
@@ -63,10 +68,56 @@ export interface RecordInput {
    *  automatically; tests can pass a deterministic stub. */
   crossNetworkFetcher?: RpcFetcher
   confidenceOverride?: number
+  /** Read a contract's own interface off chain when the compiled-in registry
+   *  does not recognise it. Default ON: the registry covers the protocols we
+   *  pinned by hand, and refusing everything else reported `no-abi` for
+   *  contracts that publish a full typed spec. Set false to record against
+   *  the registry alone (no extra RPC). */
+  resolveContractSpecs?: boolean
+  /** Test seam for the spec lookup. Unset in production, where it is built
+   *  from the network's pinned RPC URL. */
+  specFetcher?: SpecFetcher
 }
 
 export type RecordResult = ToolResponse<RecordedTransaction>
 
+/** Second pass over the contracts the compiled-in registry did not recognise.
+ *
+ *  Each candidate's own interface is read off chain and every call it received
+ *  is checked against it; the ones that verify are fed back through the decoder
+ *  as known. Re-decoding rather than patching the first result keeps ONE code
+ *  path computing parseConfidence - a hand-adjusted count here would be a
+ *  second implementation of the gate, free to drift from the real one.
+ *
+ *  Only ever ADDS recognition. A missing spec, an unreachable RPC or a call the
+ *  interface does not describe all leave the recording exactly as it was. */
+async function resolveByOnChainSpec(
+  input: RecordInput,
+  decoded: DecodedTransaction,
+  redecode: (known: ReadonlySet<string>) => DecodedTransaction
+): Promise<DecodedTransaction> {
+  if (input.resolveContractSpecs === false) return decoded
+  if (decoded.unknownContracts.length === 0) return decoded
+  const fetcher =
+    input.specFetcher ??
+    specFetcherFromRpc(
+      PUBLIC_RPC_URLS[input.network],
+      input.network === 'mainnet' ? Networks.PUBLIC : Networks.TESTNET
+    )
+  let resolved: ReadonlySet<string>
+  try {
+    resolved = await resolveContractsByOnChainSpec(
+      decoded.invocations,
+      decoded.unknownContracts.map((u) => u.contract),
+      fetcher
+    )
+  } catch {
+    // A lookup failure must not fail the recording that already succeeded.
+    return decoded
+  }
+  return resolved.size === 0 ? decoded : redecode(resolved)
+}
+
 export async function recordTransaction(input: RecordInput): Promise<RecordResult> {
   if (!input.network) {
     return err('RECORDING_FAILED', 'network required', false)
@@ -138,6 +189,9 @@ export async function recordTransaction(input: RecordInput): Promise<RecordResul
       if (e instanceof DecodeError) return err('RECORDING_FAILED', e.message, false)
       throw e
     }
+    decoded = await resolveByOnChainSpec(input, decoded, (known) =>
+      decodeEnvelope(fetched.envelopeXdr, events, [], fetched.ledger, known, input.network)
+    )
     return finish(input.network, decoded, input.confidenceOverride)
   }
 
@@ -157,6 +211,9 @@ export async function recordTransaction(input: RecordInput): Promise<RecordResul
       false
     )
   }
+  decoded = await resolveByOnChainSpec(input, decoded, (known) =>
+    decodeEnvelopeXdr(xdrStr, [], [], 0, known, input.network)
+  )
   return finish(input.network, decoded, input.confidenceOverride)
 }
 

package/src/record/rpc.ts

@@ -23,7 +23,10 @@ export interface SorobanTxResponse {
 
 export type RpcFetcher = (hash: string) => Promise<SorobanTxResponse | null>
 
-const PUBLIC_RPC_URLS: Record<Network, string> = {
+/** Exported so the on-chain spec lookup reads from the SAME endpoint the
+ *  recorder fetched the transaction from. Two different endpoints could
+ *  disagree about what a contract is. */
+export const PUBLIC_RPC_URLS: Record<Network, string> = {
   testnet: 'https://soroban-testnet.stellar.org',
   // The brief pins testnet; mainnet is left to the caller via injection. We keep
   // a public default that matches the brief's note ("e.g. https://mainnet.sorobanrpc.com").

package/src/registry/identify.ts

@@ -107,7 +107,10 @@ export function identifyProtocol(
  *  declared type. `other` is intentionally NOT a valid ABI match - it means
  *  the decoder couldn't classify the value, which is exactly the signal
  *  fail-closed should refuse. */
-function argsMatchAbi(expected: AbiArg[], actual: ScVal[]): boolean {
+/** Exported so the on-chain-spec path checks a call the SAME way a pinned
+ *  protocol does. Reimplementing it there would let the two drift, and a
+ *  looser copy would be the fail-OPEN direction. */
+export function argsMatchAbi(expected: AbiArg[], actual: ScVal[]): boolean {
   if (expected.length !== actual.length) return false
   for (let i = 0; i < expected.length; i += 1) {
     const want = expected[i]

package/src/registry/on-chain-spec.ts

@@ -0,0 +1,168 @@
+// src/registry/on-chain-spec.ts - read a contract's own interface off chain.
+//
+// The compiled-in registry covers the protocols we pinned by hand. Everything
+// else was reported as `no-abi`, which read as "this contract does not
+// describe itself" when it almost always does: a Soroban contract embeds a
+// typed spec in its wasm, and the network will hand it over. The recorder was
+// refusing calls whose interface was one RPC round-trip away.
+//
+// What this buys is NARROW and deliberately so. A fetched spec says what the
+// contract's arguments ARE, not what they MEAN. So a call verified against it
+// is recognised - the decode is trustworthy, the confidence gate stops
+// refusing it - but the arguments carry the contract's own parameter NAMES
+// rather than a curated meaning, and nothing here infers which argument is a
+// spend or a recipient. A pinned protocol still outranks a fetched spec for
+// exactly that reason, and `identifyProtocol` is consulted first.
+
+import { contract as sdkContract } from '@stellar/stellar-sdk'
+import type { ContractInvocation, ScVal } from '../types.ts'
+import { argsMatchAbi } from './identify.ts'
+import type { AbiArg, AbiArgType, ProtocolAbi } from './protocols.ts'
+
+/** Map an XDR spec type to the ScVal subset vocabulary the matcher uses.
+ *
+ *  Returns null for a type the recorder's ScVal subset cannot represent. That
+ *  is deliberate: an argument we cannot type is an argument we cannot check,
+ *  and claiming a match on it would be the fail-OPEN direction. A function
+ *  with any such argument is dropped from the derived ABI, so a call to it
+ *  stays unrecognised rather than being waved through. */
+export function abiTypeFromSpecType(specTypeName: string): AbiArgType | null {
+  switch (specTypeName) {
+    case 'scSpecTypeAddress':
+      return 'address'
+    case 'scSpecTypeI128':
+      return 'i128'
+    case 'scSpecTypeU64':
+    case 'scSpecTypeI64':
+      return 'u64'
+    case 'scSpecTypeU32':
+    case 'scSpecTypeI32':
+      return 'u32'
+    case 'scSpecTypeSymbol':
+      return 'symbol'
+    case 'scSpecTypeVec':
+      return 'vec'
+    case 'scSpecTypeBytes':
+    case 'scSpecTypeBytesN':
+      return 'bytes'
+    case 'scSpecTypeMap':
+      return 'map'
+    default:
+      return null
+  }
+}
+
+/** The RPC surface this module needs. Narrowed to one method so a test can
+ *  supply a stub without standing up a server, and so the recorder's existing
+ *  RPC client can be passed straight in. */
+export interface SpecFetcher {
+  contractSpec(contractId: string): Promise<sdkContract.Spec | null>
+}
+
+/** Build a `SpecFetcher` over the SDK's contract client. */
+export function specFetcherFromRpc(rpcUrl: string, networkPassphrase: string): SpecFetcher {
+  return {
+    async contractSpec(contractId: string): Promise<sdkContract.Spec | null> {
+      try {
+        const client = await sdkContract.Client.from({ contractId, networkPassphrase, rpcUrl })
+        return (client as unknown as { spec: sdkContract.Spec }).spec ?? null
+      } catch {
+        // A contract with no spec, an unreachable RPC and a bad address all
+        // land here and all mean the same thing to the caller: no interface
+        // was obtained, so the contract stays unrecognised. Fail closed.
+        return null
+      }
+    },
+  }
+}
+
+/** Convert a fetched spec into the ABI shape `identifyProtocol` already
+ *  matches against. Functions with an argument outside the ScVal subset are
+ *  OMITTED rather than partially typed. */
+export function abiFromSpec(spec: sdkContract.Spec): ProtocolAbi {
+  const abi: ProtocolAbi = {}
+  for (const fn of spec.funcs()) {
+    const name = fn.name().toString()
+    // The constructor is not callable after deployment, so a recorded
+    // invocation can never be one. Keeping it would only widen the surface.
+    if (name === '__constructor') continue
+    const args: AbiArg[] = []
+    let usable = true
+    for (const input of fn.inputs()) {
+      const type = abiTypeFromSpecType(input.type().switch().name)
+      if (type === null) {
+        usable = false
+        break
+      }
+      const argName = input.name().toString()
+      args.push({
+        name: argName,
+        type,
+        // The contract's own parameter name is the honest description. It is
+        // NOT a curated meaning - nothing here knows whether `value` is a
+        // spend - so downstream must not treat it as one.
+        meaning: `${argName} (from the contract's on-chain interface)`,
+      })
+    }
+    if (usable) abi[name] = { args }
+  }
+  return abi
+}
+
+/** Fetch and convert in one step. Returns null when no usable interface was
+ *  obtained, which the caller must treat as "unrecognised". */
+export async function fetchContractAbi(
+  contractId: string,
+  fetcher: SpecFetcher
+): Promise<ProtocolAbi | null> {
+  const spec = await fetcher.contractSpec(contractId)
+  if (spec === null) return null
+  const abi = abiFromSpec(spec)
+  return Object.keys(abi).length === 0 ? null : abi
+}
+
+/** Every contract invoked anywhere in the tree, with the calls made on it. */
+function callsByContract(
+  invocations: ReadonlyArray<ContractInvocation>
+): Map<string, Array<{ fn: string; args: ScVal[] }>> {
+  const out = new Map<string, Array<{ fn: string; args: ScVal[] }>>()
+  const walk = (inv: ContractInvocation): void => {
+    const list = out.get(inv.contract) ?? []
+    list.push({ fn: inv.fn, args: inv.args })
+    out.set(inv.contract, list)
+    for (const sub of inv.subInvocations) walk(sub)
+  }
+  for (const inv of invocations) walk(inv)
+  return out
+}
+
+/** Contracts whose EVERY recorded call matches their own published interface.
+ *
+ *  All-or-nothing per contract, deliberately. A contract where one call
+ *  verifies and another does not is a contract we do not understand, and
+ *  marking it recognised would raise confidence on the strength of the call
+ *  we happened to check. The unverified call is the one that matters.
+ *
+ *  A contract with no fetchable spec, or a call naming a function absent from
+ *  it, simply stays unknown - this only ever ADDS recognition, so a failure
+ *  here degrades to today's behaviour rather than to a wrong answer. */
+export async function resolveContractsByOnChainSpec(
+  invocations: ReadonlyArray<ContractInvocation>,
+  candidates: ReadonlyArray<string>,
+  fetcher: SpecFetcher
+): Promise<Set<string>> {
+  const resolved = new Set<string>()
+  const calls = callsByContract(invocations)
+  for (const contract of new Set(candidates)) {
+    const made = calls.get(contract)
+    if (!made || made.length === 0) continue
+    const abi = await fetchContractAbi(contract, fetcher)
+    if (abi === null) continue
+    const everyCallVerifies = made.every((c) => {
+      const entry = abi[c.fn]
+      return entry !== undefined && argsMatchAbi(entry.args, c.args)
+    })
+    if (everyCallVerifies) resolved.add(contract)
+  }
+  return resolved
+}