@crediolabs/policy-synth 0.1.0

package/src/registry/index.ts

@@ -0,0 +1,24 @@
+// src/registry/index.ts - re-export the protocol adjacency registry.
+
+export {
+  type IdentifiedProtocol,
+  identifyProtocol,
+} from './identify.ts'
+
+export {
+  addressToProtocol,
+  KNOWN_ADDRESSES,
+  type KnownAddressesByNetwork,
+  type KnownAddressesByProtocol,
+} from './known-addresses.ts'
+export {
+  type AbiArg,
+  type AbiEntry,
+  BLEND_ABI,
+  getAbi,
+  PROTOCOL_ABIS,
+  type ProtocolAbi,
+  type ProtocolId,
+  SEP41_ABI,
+  SOROSWAP_ABI,
+} from './protocols.ts'

package/src/registry/known-addresses.ts

@@ -0,0 +1,71 @@
+// src/registry/known-addresses.ts - pinned real protocol contract addresses.
+//
+// Addresses here are fetched from authoritative public sources:
+//   - Blend mainnet: docs.blend.capital/mainnet-deployments
+//     https://docs.blend.capital/mainnet-deployments
+//   - SoroSwap mainnet: github.com/soroswap (organisation README)
+//     https://github.com/soroswap
+//
+// Testnet addresses are intentionally NOT pinned: the public docs do not
+// publish them, and per the task brief, unconfirmed addresses are marked
+// [VERIFY] and excluded from the active set rather than invented.
+//
+// SEP-41 is recognised by interface (any token), so no address list is needed
+// for it - see identify.ts.
+
+import type { ProtocolId } from './protocols.ts'
+
+/** Pinned contract addresses per (network, protocol). Empty list = no
+ *  addresses pinned for that cell. */
+export interface KnownAddressesByProtocol {
+  blend: string[]
+  soroswap: string[]
+}
+
+export interface KnownAddressesByNetwork {
+  mainnet: KnownAddressesByProtocol
+  testnet: KnownAddressesByProtocol
+}
+
+// Source: https://docs.blend.capital/mainnet-deployments (Blend Pool Factory
+// mainnet deployment, fetched 2026-07-23).
+const BLEND_MAINNET_POOL_FACTORY = 'CDSYOAVXFY7SM5S64IZPPPYB4GVGGLMQVFREPSQQEZVIWXX5R23G4QSU'
+
+// Source: https://github.com/soroswap (organisation README, fetched 2026-07-23)
+// SoroswapRouter mainnet deployment.
+const SOROSWAP_MAINNET_ROUTER = 'CAG5LRYQ5JVEUI5TEID72EYOVX44TTUJT5BQR2J6J77FH65PCCFAJDDH'
+
+// Source: https://github.com/soroswap (organisation README, fetched 2026-07-23)
+// SoroswapFactory mainnet deployment.
+const SOROSWAP_MAINNET_FACTORY = 'CA4HEQTL2WPEUYKYKCDOHCDNIV4QHNJ7EL4J4NQ6VADP7SYHVRYZ7AW2'
+
+export const KNOWN_ADDRESSES: KnownAddressesByNetwork = {
+  mainnet: {
+    blend: [BLEND_MAINNET_POOL_FACTORY],
+    soroswap: [SOROSWAP_MAINNET_ROUTER, SOROSWAP_MAINNET_FACTORY],
+  },
+  testnet: {
+    // [VERIFY] Blend testnet pool factory address: not published in the
+    // public docs as of 2026-07-23. Excluded from the active set until an
+    // authoritative source is found.
+    blend: [],
+    // [VERIFY] SoroSwap testnet router / factory addresses: not published in
+    // the public docs as of 2026-07-23. Excluded from the active set.
+    soroswap: [],
+  },
+}
+
+/** Map a (contract, network) pair to its pinned protocol id. Returns null
+ *  when the address is not pinned for that network - callers MUST preserve
+ *  the fail-closed posture for unpinned contracts. */
+export function addressToProtocol(
+  contract: string,
+  network: 'mainnet' | 'testnet'
+): ProtocolId | null {
+  for (const protocol of ['blend', 'soroswap'] as const) {
+    if (KNOWN_ADDRESSES[network][protocol].includes(contract)) {
+      return protocol
+    }
+  }
+  return null
+}

package/src/registry/protocols.ts

@@ -0,0 +1,176 @@
+// src/registry/protocols.ts - protocol ABI definitions (no addresses).
+//
+// A protocol is identified by EITHER:
+//   - by interface (function-name signature + arg shape): a contract calling
+//     one of these well-known fns with the expected arg shape IS that
+//     protocol, regardless of address. SEP-41 is the canonical case - ANY
+//     token contract calling `transfer` with the right arg shape is a
+//     SEP-41 token. Blend pool `submit`/`claim` are similarly recognised by
+//     interface (the pool factory address doesn't cover per-pool instances).
+//   - by address: the contract is in the pinned `known-addresses` set (see
+//     known-addresses.ts). SoroSwap uses address recognition because the
+//     router is a single deployed contract; Blend uses it to recognise factory
+//     calls in addition to its interface recognition.
+//
+// Args entries pin a ScVal subset type (matching the normalised `ScVal`
+// vocabulary in src/types.ts) plus a human meaning string. The registry
+// fails closed: a method call whose decoded args do NOT match the ABI
+// signature is treated as unknown.
+
+import type { ScVal } from '../types.ts'
+
+export type ProtocolId = 'sep41' | 'blend' | 'soroswap'
+
+/** ScVal subset type vocabulary the ABI uses. Mirrors `ScVal['type']` minus
+ *  `other` (which by definition cannot be matched against an ABI arg). */
+export type AbiArgType = Exclude<ScVal['type'], 'other'>
+
+export interface AbiArg {
+  name: string
+  /** ScVal subset type the decoded arg must conform to. */
+  type: AbiArgType
+  /** Human-readable meaning for the downstream reviewer. */
+  meaning: string
+}
+
+export interface AbiEntry {
+  args: AbiArg[]
+}
+
+export type ProtocolAbi = Record<string, AbiEntry>
+
+/** SEP-41 token interface - pinned from the SEP-41 spec (any token). */
+export const SEP41_ABI: ProtocolAbi = {
+  transfer: {
+    args: [
+      {
+        name: 'from',
+        type: 'address',
+        meaning: 'source address (the `from` of the token transfer)',
+      },
+      {
+        name: 'to',
+        type: 'address',
+        meaning: 'destination address (the `to` of the token transfer)',
+      },
+      {
+        name: 'amount',
+        type: 'i128',
+        meaning: 'amount of tokens to move (i128, signed-decimal string)',
+      },
+    ],
+  },
+  mint: {
+    args: [
+      { name: 'to', type: 'address', meaning: 'recipient of the newly minted tokens' },
+      { name: 'amount', type: 'i128', meaning: 'amount to mint (i128, signed-decimal string)' },
+    ],
+  },
+  burn: {
+    args: [
+      { name: 'from', type: 'address', meaning: 'address whose balance is decremented' },
+      { name: 'amount', type: 'i128', meaning: 'amount to burn (i128, signed-decimal string)' },
+    ],
+  },
+  approve: {
+    args: [
+      { name: 'from', type: 'address', meaning: 'token holder granting the allowance' },
+      {
+        name: 'spender',
+        type: 'address',
+        meaning: 'address authorised to move tokens on behalf of `from`',
+      },
+      { name: 'amount', type: 'i128', meaning: 'allowance amount (i128, signed-decimal string)' },
+      {
+        name: 'expiration_ledger',
+        type: 'u32',
+        meaning: 'ledger sequence after which the allowance is invalid',
+      },
+    ],
+  },
+}
+
+/** Blend pool interface (v2). Pinning the two fns the recorder surfaces.
+ *  Pool-level recognition is by INTERFACE (real pool calls hit per-pool
+ *  instances, not the factory). Arg shapes verified against the Blend v2
+ *  pool contract source (blend-capital/blend-contracts-v2 `pool/src/contract.rs`,
+ *  fetched 2026-07-23):
+ *    submit(env, from: Address, spender: Address, to: Address, requests: Vec<Request>)
+ *      -> Positions
+ *    claim(env, from: Address, reserve_token_ids: Vec<u32>, to: Address) -> i128
+ *  Other pool fns (add_reserves, withdraw, etc.) are intentionally omitted -
+ *  they are too version-sensitive to bind by interface. */
+export const BLEND_ABI: ProtocolAbi = {
+  submit: {
+    args: [
+      { name: 'from', type: 'address', meaning: 'address supplying collateral or repaying debt' },
+      { name: 'spender', type: 'address', meaning: 'address authorising the supply / repay' },
+      { name: 'to', type: 'address', meaning: 'address receiving the resulting position shares' },
+      { name: 'requests', type: 'vec', meaning: 'vec<Request> describing the action per reserve' },
+    ],
+  },
+  claim: {
+    args: [
+      { name: 'from', type: 'address', meaning: 'address whose position is being claimed against' },
+      {
+        name: 'reserve_token_ids',
+        type: 'vec',
+        meaning: 'vec<u32> reserve token ids to claim emissions for',
+      },
+      { name: 'to', type: 'address', meaning: 'address receiving the claimed tokens' },
+    ],
+  },
+}
+
+/** SoroSwap router interface. Standard Uniswap-V2-style swap fn signatures
+ *  pinned from the SoroSwap router source. Recognised by address only (the
+ *  router is a single pinned contract); FIX 4 requires the method to also be
+ *  in this ABI for address recognition to succeed. The `path` arg is a
+ *  `vec<address>` - we record it as the outer `vec` subset and leave the
+ *  per-element shape to the downstream reviewer. */
+export const SOROSWAP_ABI: ProtocolAbi = {
+  swap_exact_tokens_for_tokens: {
+    args: [
+      { name: 'amount_in', type: 'i128', meaning: 'exact input amount (i128)' },
+      { name: 'amount_out_min', type: 'i128', meaning: 'minimum acceptable output (i128)' },
+      { name: 'path', type: 'vec', meaning: 'vec<address> hop path through pools' },
+      { name: 'to', type: 'address', meaning: 'recipient of the output tokens' },
+      {
+        name: 'deadline',
+        type: 'u64',
+        meaning: 'unix-seconds deadline after which the swap is refused',
+      },
+    ],
+  },
+  swap_tokens_for_exact_tokens: {
+    args: [
+      { name: 'amount_out', type: 'i128', meaning: 'exact output amount desired (i128)' },
+      { name: 'amount_in_max', type: 'i128', meaning: 'maximum input willing to spend (i128)' },
+      { name: 'path', type: 'vec', meaning: 'vec<address> hop path through pools' },
+      { name: 'to', type: 'address', meaning: 'recipient of the output tokens' },
+      {
+        name: 'deadline',
+        type: 'u64',
+        meaning: 'unix-seconds deadline after which the swap is refused',
+      },
+    ],
+  },
+  swap_exact_in_for_tokens: {
+    args: [
+      { name: 'amount_in', type: 'i128', meaning: 'exact input amount (i128)' },
+      { name: 'amount_out_min', type: 'i128', meaning: 'minimum acceptable output (i128)' },
+      { name: 'path', type: 'vec', meaning: 'vec<address> hop path through pools' },
+      { name: 'to', type: 'address', meaning: 'recipient of the output tokens' },
+    ],
+  },
+}
+
+export const PROTOCOL_ABIS: Record<ProtocolId, ProtocolAbi> = {
+  sep41: SEP41_ABI,
+  blend: BLEND_ABI,
+  soroswap: SOROSWAP_ABI,
+}
+
+export function getAbi(protocol: ProtocolId): ProtocolAbi {
+  return PROTOCOL_ABIS[protocol]
+}

package/src/seams/index.ts

@@ -0,0 +1,11 @@
+// src/seams/index.ts - re-export the three custody-seam contracts.
+
+export type {
+  ChainDecoder,
+  CompileResult,
+  CustodyAdapter,
+  CustodyCapabilities,
+  CustodyMode,
+  PolicySource,
+  SimulationResult,
+} from './types.ts'

package/src/seams/types.ts

@@ -0,0 +1,81 @@
+// src/seams/types.ts - the three custody seams (contracts, not implementations).
+//
+// The synthesizer is decoupled from its edges by three seams:
+//   - PolicySource  (INPUT):  produces a normalized RecordedTransaction. The
+//                             recorder is the reference source; a MandateSpec
+//                             lowering is a second, deterministic source.
+//   - ChainDecoder  (DECODE): chain-specific call data -> normalized facts.
+//   - CustodyAdapter (OUTPUT): compile a PolicyIR to a backend-native policy +
+//                             verify/export it (OZ is the first adapter).
+// These are INTERFACES only. Implementations live in their own modules.
+
+import type { ToolResponse } from '../errors.ts'
+import type { PolicyIR } from '../ir/types.ts'
+import type { Network, ProposedPolicy, RecordedTransaction, ScVal } from '../types.ts'
+
+/** INPUT: something that produces a normalized RecordedTransaction. */
+export interface PolicySource {
+  readonly name: string
+  capture(input: {
+    hash?: string
+    xdr?: string
+    network: Network
+  }): Promise<ToolResponse<RecordedTransaction>>
+}
+
+/** DECODE: chain-specific call data -> the normalized facts the synth reasons
+ *  over. */
+export interface ChainDecoder {
+  readonly chain: 'stellar' | 'evm'
+  decodeInvocation(tx: RecordedTransaction): { contract: string; method: string; args: ScVal[] }
+}
+
+/** OZ = enforce; `log_only` is reserved for shadow mode (out of scope). */
+export type CustodyMode = 'enforce' | 'log_only'
+
+/** What a backend can express. A construct needing a false flag is flagged
+ *  `uncovered` by the adapter, never silently dropped. */
+export interface CustodyCapabilities {
+  supportsOraclePrice: boolean
+  supportsSpendWindow: boolean
+  supportsInvocationCount: boolean
+  supportsTimeExpiry: boolean
+  supportsThreshold: boolean
+  supportsGeneralPredicate: boolean
+}
+
+/** The result of compiling a PolicyIR for one backend. */
+export interface CompileResult {
+  /** false => some IR construct this backend cannot express (see `uncovered`). */
+  covered: boolean
+  /** Human-readable list of unsupported constructs (the Path-B markers). */
+  uncovered: string[]
+  /** The backend-native installable policy, assembled when a rule lowered. */
+  proposed?: ProposedPolicy
+}
+
+/** Result of a simulate() dry-run. `ts-model` is the off-chain TS evaluator.
+ *  Real permit/deny semantics wiring is a later phase; week-1 returns a
+ *  clearly-marked stub (empty `evaluations`, `permitted: null`). */
+export interface SimulationResult {
+  backend: 'ts-model'
+  /** Whether the permit tx would be allowed; null until real semantics land. */
+  permitted: boolean | null
+  /** Per-construct evaluation trace; empty placeholder in this slice. */
+  evaluations: unknown[]
+  /** Diagnostics; marks the stub explicitly. */
+  notes: string[]
+}
+
+/** OUTPUT: compile a PolicyIR to a backend-specific installable policy. */
+export interface CustodyAdapter {
+  readonly name: string
+  readonly mode: CustodyMode
+  capabilities(): CustodyCapabilities
+  compile(ir: PolicyIR): CompileResult
+  /** Phase-03 wiring; a clearly-marked stub in week-1. */
+  simulate(ir: PolicyIR, permitTx: RecordedTransaction): SimulationResult
+  /** Canonical JSON of the IR (portability / audit). */
+  export(ir: PolicyIR): string
+  // install(...) lands with a later phase; not part of this slice.
+}

package/src/synth/compose-from-recording.ts

@@ -0,0 +1,226 @@
+// src/synth/compose-from-recording.ts - facts + scope -> PolicyIR (Path A).
+//
+// Composes the canonical IR rule the OZ Path-A backend can compile. Fail-closed
+// composition rules:
+//
+//   - identify the protocol of the top-level call (registry.identifyProtocol).
+//     When it is unknown (null), emit NO OZ-primitive-producing IR node: the
+//     scope is kept (CallContract + method) and every inferred bound is surfaced
+//     as a descriptive Path-B warning. An unrecognised call never compiles to a
+//     permissive OZ primitive.
+//
+//   - carry the recorded top-level function into `rule.scope.method` so the OZ
+//     adapter flags per-method scoping Path-B (CallContract permits every method
+//     on the contract; a per-method restriction needs the interpreter predicate).
+//
+//   - a `spending_limit` (window_spent(token, w) <= limit) is emitted ONLY when
+//     the caller supplies BOTH the limit (userResponses.limitAmount) and the
+//     window (userResponses.windowSeconds). A single recorded spend does NOT
+//     authorise that amount every window, so the observed amount is NEVER used as
+//     an auto-ceiling: a missing limit surfaces AMOUNT_BOUND_MISSING (the observed
+//     amount is offered as a suggestion), a missing window surfaces
+//     DURATION_UNSPECIFIED. EVERY spent token is handled - none is silently
+//     dropped; a single caller limit binds only an unambiguous single-token spend.
+//
+//   - incoming-only flows (e.g. Blend yield claim) emit an `invocation_count`
+//     bound ONLY when the caller supplies the count (userResponses.invocationLimit)
+//     and a window; otherwise FREQUENCY_BOUND_MISSING is surfaced with no
+//     fabricated count.
+//
+//   - the IR carries ONLY constraints justified by the recording (observed
+//     recipient allowlist) + explicit user input. Nothing invented: no oracle
+//     price fabricated from a slippage bound, no synthetic exact-path compare.
+//     Those needs are surfaced as descriptive Path-B warnings instead.
+//
+// The default behavior is `deny_all` (OZ context rules are deny-by-default).
+
+import type { IRCondition, IRPolicyRule, PolicyIR } from '../ir/types.ts'
+import { type IdentifiedProtocol, identifyProtocol } from '../registry/identify.ts'
+import type { AmbiguityPrompt, ContractInvocation, Network } from '../types.ts'
+import type { IntentFacts } from './lower.ts'
+
+/** Caller-supplied answers to the ambiguity prompts. Every numeric bound the
+ *  synth might apply must come from here - the recording supplies observed
+ *  amounts (offered only as suggestions), never authorised ceilings. */
+export interface ComposeUserResponses {
+  /** Rolling window (seconds) for a spending_limit / invocation_count. */
+  windowSeconds?: number
+  /** OZ context-rule expiry (ledger sequence). */
+  validUntilLedger?: number
+  /** Per-window spend ceiling (i128 decimal string). Required to emit a
+   *  spending_limit; absent -> AMOUNT_BOUND_MISSING. */
+  limitAmount?: string
+  /** Max invocations per window for an incoming-only flow. Required to emit an
+   *  invocation_count bound; absent -> FREQUENCY_BOUND_MISSING. */
+  invocationLimit?: number
+}
+
+/** Composition options. */
+export interface ComposeOptions {
+  network: Network
+  userResponses?: ComposeUserResponses
+}
+
+/** Result of composition: the PolicyIR, any ambiguities surfaced during
+ *  inference, and descriptive Path-B warnings for needs that are NOT expressed
+ *  as an IR node (so no fabricated constraint is emitted). The orchestrator
+ *  carries ambiguities into `ProposedPolicy.ambiguities` and merges warnings
+ *  into `ProposedPolicy.warnings`. */
+export interface ComposeResult {
+  ir: PolicyIR
+  ambiguities: AmbiguityPrompt[]
+  warnings: string[]
+}
+
+/** Compose a PolicyIR from the lowered facts + the resolved scope.
+ *  Pure (no randomness, no clock); same inputs -> byte-identical result. */
+export function composeFromRecording(
+  facts: IntentFacts,
+  scopeContract: string,
+  topLevel: ContractInvocation | null,
+  opts: ComposeOptions
+): ComposeResult {
+  const ambiguities: AmbiguityPrompt[] = []
+  const warnings: string[] = []
+  const constraints: IRCondition[] = []
+
+  const protocol = topLevel
+    ? identifyProtocol(topLevel.contract, topLevel.fn, topLevel.args, opts.network)
+    : null
+  const known = protocol !== null
+
+  const windowSeconds = opts.userResponses?.windowSeconds
+  const limitAmount = opts.userResponses?.limitAmount
+  const spendTokens = Object.keys(facts.spendByToken)
+
+  // Outgoing spend -> one spending_limit per spent token. A single caller limit
+  // binds only an unambiguous single-token spend; a multi-token flow needs a
+  // per-token limit, so each unmatched token surfaces AMOUNT_BOUND_MISSING.
+  if (spendTokens.length > 0 && topLevel) {
+    let durationFlagged = false
+    for (const token of spendTokens) {
+      const observed = facts.spendByToken[token]
+      if (observed === undefined) continue
+
+      if (!known) {
+        warnings.push(
+          `spend of ${observed} (token ${token}) not bounded: unrecognised protocol, spend cap needs the interpreter predicate (Path B)`
+        )
+        continue
+      }
+
+      const limit = spendTokens.length === 1 ? limitAmount : undefined
+      if (windowSeconds === undefined && !durationFlagged) {
+        ambiguities.push({
+          code: 'DURATION_UNSPECIFIED',
+          question: `Recording shows a ${observed}-${token} spend. What rolling window (seconds) should the spending_limit use?`,
+        })
+        durationFlagged = true
+      }
+      if (limit === undefined) {
+        ambiguities.push({
+          code: 'AMOUNT_BOUND_MISSING',
+          question: `Recording shows a ${observed}-${token} spend, but a single spend does not authorise that amount every window. What per-window spending_limit should apply? (observed amount, suggestion only: ${observed})`,
+        })
+        continue
+      }
+      if (windowSeconds !== undefined) {
+        constraints.push({
+          op: 'compare',
+          compare: {
+            selector: { kind: 'window_spent', token, windowSeconds },
+            operator: 'lte',
+            value: limit,
+          },
+        })
+      }
+    }
+  }
+
+  // Incoming-only / frequency intent: an invocation_count bound is emitted ONLY
+  // when the caller supplies the count AND a window - never a fabricated `<= 1`.
+  if (spendTokens.length === 0 && topLevel) {
+    const invocationLimit = opts.userResponses?.invocationLimit
+    if (known && windowSeconds !== undefined && invocationLimit !== undefined) {
+      constraints.push({
+        op: 'compare',
+        compare: {
+          selector: { kind: 'invocation_count', windowSeconds },
+          operator: 'lte',
+          value: String(invocationLimit),
+        },
+      })
+    } else {
+      ambiguities.push({
+        code: 'FREQUENCY_BOUND_MISSING',
+        question: 'Incoming-only flow - what max invocations per window should the policy enforce?',
+      })
+      warnings.push(
+        'frequency bound needed for the incoming-only flow (interpreter/Path B); no invocation cap inferred'
+      )
+    }
+  }
+
+  // Observed recipient allowlist (SEP-41) is a real, recorded constraint the OZ
+  // adapter flags Path-B. Unknown protocols emit nothing here.
+  if (topLevel && protocol !== null) {
+    appendProtocolSpecificConstraints(constraints, warnings, facts, topLevel, protocol)
+  }
+
+  const scope: IRPolicyRule['scope'] = { contract: scopeContract }
+  if (topLevel?.fn) scope.method = topLevel.fn
+
+  const rule: IRPolicyRule = {
+    roles: [],
+    scope,
+    constraints,
+  }
+  if (opts.userResponses?.validUntilLedger !== undefined) {
+    rule.expiry = { validUntilLedger: opts.userResponses.validUntilLedger }
+  }
+
+  const ir: PolicyIR = {
+    chain: 'stellar',
+    defaultBehavior: 'deny_all',
+    rules: [rule],
+  }
+  return { ir, ambiguities, warnings }
+}
+
+/** Add the constraints justified by the recording that the OZ backend cannot
+ *  express natively (the SEP-41 recipient the transfer moved to). The OZ adapter
+ *  flags them Path-B. SoroSwap's slippage / oracle / exact-path needs are
+ *  surfaced as descriptive warnings, NOT as fabricated comparison nodes. */
+function appendProtocolSpecificConstraints(
+  constraints: IRCondition[],
+  warnings: string[],
+  facts: IntentFacts,
+  topLevel: ContractInvocation,
+  protocol: IdentifiedProtocol
+): void {
+  // SEP-41 transfer / mint: the `to` arg (index 1) is the recipient. Emit it as
+  // a single-element allowlist; the OZ adapter flags it Path-B.
+  if (protocol.protocol === 'sep41' && (protocol.fn === 'transfer' || protocol.fn === 'mint')) {
+    const toArg = topLevel.args[1]
+    if (toArg && toArg.type === 'address') {
+      constraints.push({
+        op: 'in',
+        selector: { kind: 'arg', argIndex: 1, scalarType: 'address' },
+        values: [toArg.value],
+      })
+    }
+  }
+
+  // SoroSwap: the swap's slippage / oracle-price bound and its exact hop path
+  // need the interpreter predicate. We do NOT fabricate a comparison node
+  // (oracle price and amountOutMin are different units; a vec path is not a
+  // scalar compare). Surface the observed path descriptively instead.
+  if (protocol.protocol === 'soroswap') {
+    const paths = facts.allowedPaths?.[topLevel.contract]
+    const route = paths?.length === 1 ? paths[0] : undefined
+    const pathText = route && route.length > 0 ? `; observed path: ${route.join(' -> ')}` : ''
+    warnings.push(
+      `SoroSwap swap: slippage / oracle price bound and exact hop path need the interpreter predicate (Path B)${pathText}`
+    )
+  }
+}

package/src/synth/index.ts

@@ -0,0 +1,19 @@
+// src/synth/index.ts - re-export the synthesizer front-ends.
+
+export {
+  type ComposeOptions,
+  type ComposeResult,
+  composeFromRecording,
+} from './compose-from-recording.ts'
+export { type IntentFacts, lower } from './lower.ts'
+export {
+  type DecideScopeOptions,
+  decideScope,
+  type ScopeDecision,
+  scopeToContextRuleType,
+} from './scope.ts'
+export { synthesizeFromMandate } from './synthesize-from-mandate.ts'
+export {
+  type SynthesizeFromRecordingOptions,
+  synthesizeFromRecording,
+} from './synthesize-from-recording.ts'