@crediolabs/policy-synth 0.1.0

package/src/synth/lower.ts

@@ -0,0 +1,144 @@
+// src/synth/lower.ts - lower a RecordedTransaction to IntentFacts.
+//
+// Reads the top-level invocations only (the single authorized call that
+// `Policy::enforce` receives; v1 grammar does not walk sub-invocations) and
+// the recorded token movements. Produces the deterministic facts the synth
+// reasons over: distinct call targets, functions per target, cumulative spend
+// per token (outgoing movements from the recorded source account only),
+// authorising signers, an optional shared-router marker when multiple top-level
+// invocations hit the same contract, and the per-contract hop-path lists for
+// router calls (SoroSwap `path`).
+
+import type { ContractInvocation, RecordedTransaction, ScVal, TokenMovement } from '../types.ts'
+
+/** Facts the recording-path synth reasons over. */
+export interface IntentFacts {
+  callTargets: string[]
+  functionsByContract: Record<string, string[]>
+  /** Aggregate outgoing spend per token (i128-safe decimal string). A single
+   *  token entry is the Path-A prerequisite for `spending_limit`. Movements
+   *  with from != sourceAccount are NOT counted as "spend" by this synth
+   *  (incoming yield, refund, etc.). */
+  spendByToken: Record<string, string>
+  signers: string[]
+  /** Set when more than one top-level invocation shares a target contract
+   *  (a router); decideScope uses this to scope by the router instead of
+   *  returning SCOPE_UNRESOLVED. */
+  sharedRouter?: string
+  /** Router hop paths, keyed by target contract. SoroSwap exposes its `path`
+   *  arg directly on the top-level call; this is the input the compose step
+   *  passes to a per-arg `in` condition (flagged Path-B by the OZ adapter). */
+  allowedPaths?: Record<string, string[][]>
+}
+
+/** Lower a recorded transaction to the canonical IntentFacts. Pure (no
+ *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts. */
+export function lower(tx: RecordedTransaction): IntentFacts {
+  const invocations = tx.invocations
+  const callTargets = uniqueOrdered(invocations.map((i) => i.contract))
+  const functionsByContract = groupFunctionsByContract(invocations)
+  const spendByToken = aggregateOutgoingSpend(tx.tokenMovements, tx.sourceAccount)
+  const allowedPaths = extractPathsByContract(invocations)
+  const sharedRouter = inferSharedRouter(invocations)
+
+  const facts: IntentFacts = {
+    callTargets,
+    functionsByContract,
+    spendByToken,
+    signers: [...tx.signers],
+  }
+  if (sharedRouter) facts.sharedRouter = sharedRouter
+  if (Object.keys(allowedPaths).length > 0) facts.allowedPaths = allowedPaths
+  return facts
+}
+
+/** Preserve first-seen ordering, drop duplicates. */
+function uniqueOrdered(items: string[]): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const item of items) {
+    if (seen.has(item)) continue
+    seen.add(item)
+    out.push(item)
+  }
+  return out
+}
+
+/** Group the function names invoked per top-level contract. Order preserved
+ *  per contract in first-seen order. */
+function groupFunctionsByContract(invocations: ContractInvocation[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {}
+  for (const inv of invocations) {
+    const existing = out[inv.contract] ?? []
+    if (!existing.includes(inv.fn)) existing.push(inv.fn)
+    out[inv.contract] = existing
+  }
+  return out
+}
+
+/** Sum outgoing TokenMovement amounts per token, where `from === source`.
+ *  BigInt throughout; never lossy. Movements whose `from` does not match the
+ *  recorded source account are NOT counted (incoming yield, refund, etc.). */
+function aggregateOutgoingSpend(
+  movements: TokenMovement[],
+  sourceAccount: string
+): Record<string, string> {
+  const totals = new Map<string, bigint>()
+  for (const m of movements) {
+    if (m.from !== sourceAccount) continue
+    const current = totals.get(m.token) ?? 0n
+    totals.set(m.token, current + BigInt(m.amount))
+  }
+  const out: Record<string, string> = {}
+  for (const [token, total] of totals) {
+    out[token] = total.toString()
+  }
+  return out
+}
+
+/** Walk the top-level invocations looking for a `vec` arg whose elements are
+ *  addresses (the SoroSwap `path` shape). Only the FIRST arg in each
+ *  invocation is examined in v1 - the recorder emits the top-level args
+ *  in declaration order and the only contract-call convention we bind by is
+ *  the router's first vec-arg path. */
+function extractPathsByContract(invocations: ContractInvocation[]): Record<string, string[][]> {
+  const out: Record<string, string[][]> = {}
+  for (const inv of invocations) {
+    const path = findAddressVec(inv.args)
+    if (path) {
+      const existing = out[inv.contract] ?? []
+      existing.push(path)
+      out[inv.contract] = existing
+    }
+  }
+  return out
+}
+
+function findAddressVec(args: ScVal[]): string[] | null {
+  for (const arg of args) {
+    if (arg.type === 'vec') {
+      const addresses = arg.value.filter(
+        (v): v is Extract<ScVal, { type: 'address' }> => v.type === 'address'
+      )
+      if (addresses.length === arg.value.length && addresses.length > 0) {
+        return addresses.map((a) => a.value)
+      }
+    }
+  }
+  return null
+}
+
+/** When multiple top-level invocations share the same target contract, that
+ *  contract is the shared router. Single-call transactions return undefined
+ *  (the default flow doesn't need the marker). */
+function inferSharedRouter(invocations: ContractInvocation[]): string | undefined {
+  if (invocations.length < 2) return undefined
+  const counts = new Map<string, number>()
+  for (const inv of invocations) {
+    counts.set(inv.contract, (counts.get(inv.contract) ?? 0) + 1)
+  }
+  for (const [contract, count] of counts) {
+    if (count >= 2) return contract
+  }
+  return undefined
+}

package/src/synth/scope.ts

@@ -0,0 +1,108 @@
+// src/synth/scope.ts - decide the OZ context-rule scope from IntentFacts.
+//
+// Pure decision function. Three branches:
+//   - single call target                   -> CallContract(target)
+//   - multiple targets w/ sharedRouter     -> CallContract(sharedRouter)
+//   - multiple unrelated targets           -> SCOPE_UNRESOLVED ToolError
+//
+// `decideScope` also surfaces the `DURATION_UNSPECIFIED` ambiguity when the
+// caller has NOT supplied a validUntilLedger - the synth never fabricates a
+// window. The orchestrator is responsible for assembling any
+// `AmbiguityPrompt[]` from this and other decision points into the
+// `ProposedPolicy.ambiguities` field.
+
+import type { ToolError, ToolResponse } from '../errors.ts'
+import type { AmbiguityPrompt, ContextRuleDraft, Network } from '../types.ts'
+import type { IntentFacts } from './lower.ts'
+
+export type ScopeDecision =
+  | { kind: 'call_contract'; contract: string; ambiguities: AmbiguityPrompt[] }
+  | { kind: 'default'; ambiguities: AmbiguityPrompt[] }
+
+/** Options for the scope decision. `validUntilLedger` may be supplied via the
+ *  synth opts; when absent the DURATION_UNSPECIFIED ambiguity is surfaced so
+ *  the LLM can ask the user rather than the synth fabricating a window. */
+export interface DecideScopeOptions {
+  network: Network
+  validUntilLedger?: number
+}
+
+/** Decide the OZ context-rule scope. Returns `ScopeDecision` on success or a
+ *  `ToolError` with code `SCOPE_UNRESOLVED` when the recorded tx spans
+ *  multiple unrelated call targets. */
+export function decideScope(
+  facts: IntentFacts,
+  opts: DecideScopeOptions
+): ToolResponse<ScopeDecision> {
+  const ambiguities: AmbiguityPrompt[] = []
+  if (opts.validUntilLedger === undefined) {
+    ambiguities.push({
+      code: 'DURATION_UNSPECIFIED',
+      question:
+        'No expiry supplied for this policy. What `validUntilLedger` should the policy carry?',
+    })
+  }
+
+  // Single target -> scope directly.
+  if (facts.callTargets.length === 1) {
+    const contract = facts.callTargets[0]
+    if (contract === undefined) {
+      return {
+        ok: false,
+        error: scopeUnresolvedError(facts, 'no contract address resolvable from the recording'),
+      }
+    }
+    return {
+      ok: true,
+      data: { kind: 'call_contract', contract, ambiguities },
+    }
+  }
+
+  // Multiple targets with a shared router -> scope by the router.
+  if (facts.sharedRouter) {
+    return {
+      ok: true,
+      data: {
+        kind: 'call_contract',
+        contract: facts.sharedRouter,
+        ambiguities,
+      },
+    }
+  }
+
+  // Multiple unrelated targets -> fail closed.
+  return {
+    ok: false,
+    error: scopeUnresolvedError(
+      facts,
+      `multiple unrelated call targets: ${facts.callTargets.join(', ')}`
+    ),
+  }
+}
+
+/** Helper to project a `ScopeDecision` into the OZ `ContextRuleDraft`
+ *  contextRuleType shape consumed by `composeFromRecording` and the OZ
+ *  adapter. */
+export function scopeToContextRuleType(scope: ScopeDecision): ContextRuleDraft['contextRuleType'] {
+  return scope.kind === 'call_contract'
+    ? { kind: 'call_contract', contract: scope.contract }
+    : { kind: 'default' }
+}
+
+function scopeUnresolvedError(facts: IntentFacts, message: string): ToolError {
+  return {
+    code: 'SCOPE_UNRESOLVED',
+    message,
+    severity: 'error',
+    retryable: false,
+    details: { callTargets: facts.callTargets, sharedRouter: facts.sharedRouter ?? null },
+    remediation: {
+      userQuestion: {
+        code: 'MULTIPLE_UNRELATED_TARGETS',
+        question: `Recording spans ${facts.callTargets.length} call targets (${facts.callTargets.join(
+          ', '
+        )}). Which contract (or shared router) should this policy scope to?`,
+      },
+    },
+  }
+}

package/src/synth/synthesize-from-mandate.ts

@@ -0,0 +1,46 @@
+// src/synth/synthesize-from-mandate.ts - the deterministic Mandate front-end.
+//
+// synthesizeFromMandate is the clean end-to-end demo path: a declarative
+// MandateSpec is lowered deterministically to a PolicyIR and compiled by the OZ
+// adapter to a ProposedPolicy. No decoding, no inference, so parseConfidence is
+// the full/not-applicable value. Constructs the OZ built-in primitives cannot
+// express (compile's `uncovered`) are surfaced in `ProposedPolicy.warnings` as
+// Path-B markers rather than failing the call - the covered primitives still
+// install; the uncovered ones are reported.
+
+import type { OzAdapterConfig } from '../adapters/oz/adapter.ts'
+import { createOzAdapter } from '../adapters/oz/adapter.ts'
+import type { ToolResponse } from '../errors.ts'
+import { mandateToPolicyIR } from '../mandate/to-ir.ts'
+import type { MandateSpec } from '../mandate/types.ts'
+import type { ProposedPolicy } from '../types.ts'
+
+const PATH_B_PREFIX = 'Path B (not covered by OZ built-in primitives): '
+
+export function synthesizeFromMandate(
+  spec: MandateSpec,
+  ozConfig: OzAdapterConfig
+): ToolResponse<ProposedPolicy> {
+  const ir = mandateToPolicyIR(spec)
+  const adapter = createOzAdapter(ozConfig)
+  const result = adapter.compile(ir)
+
+  if (!result.proposed) {
+    return {
+      ok: false,
+      error: {
+        code: 'SYNTHESIS_ERROR',
+        message: `mandate lowered to no installable OZ policy: ${result.uncovered.join('; ')}`,
+        severity: 'error',
+        retryable: false,
+        details: { uncovered: result.uncovered },
+      },
+    }
+  }
+
+  const proposed: ProposedPolicy = {
+    ...result.proposed,
+    warnings: result.uncovered.map((u) => `${PATH_B_PREFIX}${u}`),
+  }
+  return { ok: true, data: proposed }
+}

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

@@ -0,0 +1,226 @@
+// src/synth/synthesize-from-recording.ts - recording-path orchestrator.
+//
+// `synthesizeFromRecording` is the second Synthesizer front-end: it INFERS a
+// bounded policy from a `RecordedTransaction` via the same `PolicyIR` +
+// `createOzAdapter` pair used by the deterministic Mandate path. The flow:
+//
+//   1. parseConfidence gate - refuse when `overall < threshold` (default 1.0;
+//      the caller may relax via `confidenceOverride.threshold`).
+//   2. `lower(tx)` -> IntentFacts.
+//   3. `decideScope(facts)` -> scope | SCOPE_UNRESOLVED ToolError.
+//   4. `composeFromRecording(facts, scope, opts)` -> PolicyIR + ambiguities.
+//   5. `ozAdapter.compile(ir)` -> CompileResult.
+//   6. Assemble ProposedPolicy carrying parseConfidence (from tx), warnings
+//      (the OZ `uncovered` Path-B markers, prefixed), and ambiguities
+//      (DURATION_UNSPECIFIED etc.).
+//
+// Determinism: same (tx, opts, ozConfig) -> byte-identical ProposedPolicy.
+// No randomness, no clock, no globals.
+
+import type { OzAdapterConfig } from '../adapters/oz/adapter.ts'
+import { createOzAdapter } from '../adapters/oz/adapter.ts'
+import type { ToolError, ToolResponse } from '../errors.ts'
+import {
+  type Network,
+  type ProposedPolicy,
+  type RecordedTransaction,
+  SOROBAN_LIMITS,
+} from '../types.ts'
+import {
+  type ComposeOptions,
+  type ComposeUserResponses,
+  composeFromRecording,
+} from './compose-from-recording.ts'
+import { lower } from './lower.ts'
+import { decideScope, type ScopeDecision } from './scope.ts'
+
+const PATH_B_PREFIX = 'Path B (not covered by OZ built-in primitives): '
+
+/** Top-level orchestrator inputs. `userResponses` carries the LLM-collected
+ *  answers to the ambiguity prompts (windowSeconds, validUntilLedger,
+ *  limitAmount, invocationLimit). `confidenceOverride` relaxes the recorder's
+ *  gate. */
+export interface SynthesizeFromRecordingOptions {
+  network: Network
+  userResponses?: ComposeUserResponses
+  confidenceOverride?: { threshold: number }
+}
+
+/** Synthesize a ProposedPolicy from a recorded transaction. */
+export function synthesizeFromRecording(
+  tx: RecordedTransaction,
+  opts: SynthesizeFromRecordingOptions,
+  ozConfig: OzAdapterConfig
+): ToolResponse<ProposedPolicy> {
+  // 0. validate inputs (fail closed - never synthesize from garbage).
+  const invalid = validateOptions(opts)
+  if (invalid) return { ok: false, error: invalid }
+
+  // 1. parseConfidence gate.
+  const threshold = opts.confidenceOverride?.threshold ?? tx.parseConfidence.thresholdUsed
+  if (tx.parseConfidence.overall < threshold) {
+    return {
+      ok: false,
+      error: {
+        code: 'RECORDING_VALIDATION_FAILED',
+        message: `parseConfidence ${tx.parseConfidence.overall} < threshold ${threshold}`,
+        severity: 'error',
+        retryable: false,
+        details: tx.parseConfidence,
+      },
+    }
+  }
+
+  // Bound the recording size fail-closed (defense-in-depth for direct callers;
+  // the MCP schema caps this too).
+  if (tx.invocations.length > SOROBAN_LIMITS.maxInvocations) {
+    return {
+      ok: false,
+      error: {
+        code: 'RECORDING_VALIDATION_FAILED',
+        message: `recorded transaction has ${tx.invocations.length} invocations, exceeding the cap of ${SOROBAN_LIMITS.maxInvocations}`,
+        severity: 'error',
+        retryable: false,
+      },
+    }
+  }
+
+  // 2. lower.
+  const facts = lower(tx)
+
+  // 3. decideScope.
+  const scopeRes = decideScope(facts, {
+    network: opts.network,
+    ...(opts.userResponses?.validUntilLedger !== undefined
+      ? { validUntilLedger: opts.userResponses.validUntilLedger }
+      : {}),
+  })
+  if (!scopeRes.ok) return scopeRes
+  const scope: ScopeDecision = scopeRes.data
+  if (scope.kind !== 'call_contract') {
+    // A default scope on the recording-path is not currently a Path-A flow;
+    // surface SYNTHESIS_ERROR so the orchestrator never silently emits an
+    // over-broad default-scoped policy.
+    return {
+      ok: false,
+      error: {
+        code: 'SYNTHESIS_ERROR',
+        message: 'recording path requires a scoped contract; no default-scoped policies emitted',
+        severity: 'error',
+        retryable: false,
+      },
+    }
+  }
+
+  // 4. compose.
+  const topLevel = tx.invocations[0] ?? null
+  const composeOpts: ComposeOptions = {
+    network: opts.network,
+    ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
+  }
+  const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts)
+
+  // 5. OZ compile.
+  const adapter = createOzAdapter(ozConfig)
+  const compileRes = adapter.compile(composed.ir)
+
+  if (!compileRes.proposed) {
+    return {
+      ok: false,
+      error: {
+        code: 'SYNTHESIS_ERROR',
+        message: `recording lowered to no installable OZ policy: ${compileRes.uncovered.join('; ')}`,
+        severity: 'error',
+        retryable: false,
+        details: { uncovered: compileRes.uncovered },
+      },
+    }
+  }
+
+  // 6. assemble ProposedPolicy.
+  const proposed: ProposedPolicy = {
+    ...compileRes.proposed,
+    parseConfidence: { ...tx.parseConfidence },
+    warnings: [
+      ...compileRes.uncovered.map((u) => `${PATH_B_PREFIX}${u}`),
+      ...composed.warnings.map((w) => `${PATH_B_PREFIX}${w}`),
+    ],
+    ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
+  }
+  return { ok: true, data: proposed }
+}
+
+/** Reject non-sane inputs before any policy is synthesized. windowSeconds /
+ *  validUntilLedger / invocationLimit must be positive integers; limitAmount a
+ *  positive i128 decimal string; network mainnet|testnet. */
+function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null {
+  if (opts.network !== 'mainnet' && opts.network !== 'testnet') {
+    return synthesisError(`network must be 'mainnet' or 'testnet', got: ${String(opts.network)}`)
+  }
+  // A confidenceOverride outside [0, 1] would disable the recorder gate (a
+  // negative threshold can never be exceeded), so reject it fail-closed.
+  const co = opts.confidenceOverride?.threshold
+  if (co !== undefined && (!Number.isFinite(co) || co < 0 || co > 1)) {
+    return synthesisError(
+      `confidenceOverride.threshold must be a finite number within [0, 1], got: ${co}`
+    )
+  }
+  const ur = opts.userResponses
+  if (ur) {
+    if (ur.windowSeconds !== undefined && !isPositiveInt(ur.windowSeconds)) {
+      return synthesisError(`windowSeconds must be a positive integer, got: ${ur.windowSeconds}`)
+    }
+    if (
+      ur.validUntilLedger !== undefined &&
+      (!isPositiveInt(ur.validUntilLedger) || ur.validUntilLedger > SOROBAN_LIMITS.u32Max)
+    ) {
+      return synthesisError(
+        `validUntilLedger must be a positive u32 ledger sequence (<= ${SOROBAN_LIMITS.u32Max}), got: ${ur.validUntilLedger}`
+      )
+    }
+    if (ur.invocationLimit !== undefined && !isPositiveInt(ur.invocationLimit)) {
+      return synthesisError(
+        `invocationLimit must be a positive integer, got: ${ur.invocationLimit}`
+      )
+    }
+    if (ur.limitAmount !== undefined && !isPositiveI128(ur.limitAmount)) {
+      return synthesisError(
+        `limitAmount must be a positive i128 decimal string, got: ${ur.limitAmount}`
+      )
+    }
+  }
+  return null
+}
+
+function isPositiveInt(n: number): boolean {
+  return Number.isInteger(n) && n > 0
+}
+
+/** True when `s` is a canonical positive decimal integer (i128-safe via BigInt). */
+function isPositiveI128(s: string): boolean {
+  if (!/^[0-9]+$/.test(s)) return false
+  try {
+    return BigInt(s) > 0n
+  } catch {
+    return false
+  }
+}
+
+function synthesisError(message: string): ToolError {
+  return { code: 'SYNTHESIS_ERROR', message, severity: 'error', retryable: false }
+}
+
+function mergeAmbiguities(
+  ...lists: ProposedPolicy['ambiguities'][]
+): ProposedPolicy['ambiguities'] {
+  const out: ProposedPolicy['ambiguities'] = []
+  const seen = new Set<string>()
+  for (const list of lists) {
+    for (const a of list) {
+      if (seen.has(a.code)) continue
+      seen.add(a.code)
+      out.push(a)
+    }
+  }
+  return out
+}