@crediolabs/policy-synth 0.1.4 → 0.1.6

package/src/run/schemas.ts

@@ -0,0 +1,250 @@
+// packages/policy-synth/src/run/schemas.ts
+//
+// Zod schemas mirroring the policy-synth core domain types. These are the
+// public input / output shapes exposed over MCP and the CLI. They are kept
+// hand-written (rather than derived) because the MCP SDK needs a runtime
+// Zod object at the transport boundary; a drift test asserts they stay in
+// step with the TS source of truth.
+//
+// i128 amounts and other large integers are carried as base-10 decimal strings
+// end-to-end (no JS number coercion). Networks are pinned to the same closed
+// set the core defines. The discriminated union on `source` exposes BOTH
+// synthesize_policy front-ends through a single tool input.
+//
+// This module is the SINGLE source of truth for these shapes. The MCP package
+// imports them here so its tool-shape bindings stay in step; the CLI imports
+// them here so it can build the same args envelope the MCP transport builds.
+
+import { z } from 'zod'
+import { isStellarAddress } from '../synth/address.ts'
+
+/** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
+ *  installed on-chain, so reject it at the boundary (fail-closed). */
+const U32_MAX = 4294967295
+/** Upper bound on top-level invocations in a recorded transaction. A real
+ *  Stellar tx caps operations well below this; the bound stops a hand-crafted
+ *  payload from turning one request into an unbounded synthesis (DoS). */
+const MAX_INVOCATIONS = 512
+
+export const NetworkSchema = z.enum(['mainnet', 'testnet'])
+export type Network = z.infer<typeof NetworkSchema>
+
+/** ScVal subset - normalised subset the synth consumes. Mirrors
+ *  `ScVal` in packages/policy-synth/src/types.ts. */
+export const ScValSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.object({ type: z.literal('address'), value: z.string() }),
+    // i128 is SIGNED: real events carry negatives (e.g. a fee-adjustment/refund),
+    // so the recorder's own output must round-trip through this schema. u64/u32
+    // are unsigned and stay non-negative.
+    z.object({ type: z.literal('i128'), value: z.string().regex(/^-?[0-9]+$/) }),
+    z.object({ type: z.literal('u64'), value: z.string().regex(/^[0-9]+$/) }),
+    z.object({ type: z.literal('u32'), value: z.string().regex(/^[0-9]+$/) }),
+    z.object({ type: z.literal('symbol'), value: z.string() }),
+    z.object({ type: z.literal('vec'), value: z.array(ScValSchema) }),
+    z.object({ type: z.literal('bytes'), value: z.string() }),
+    z.object({ type: z.literal('other'), value: z.string() }),
+  ])
+)
+
+/** ContractInvocation mirrors the core. Annotated with an explicit
+ *  `z.ZodType<unknown>` (like ScValSchema above) so the self-referential
+ *  `subInvocations` field does not trip TS's circular type inference. */
+export const ContractInvocationSchema: z.ZodType<unknown> = z.object({
+  contract: z.string(),
+  fn: z.string(),
+  args: z.array(ScValSchema),
+  subInvocations: z.array(z.lazy(() => ContractInvocationSchema)),
+})
+
+export const TokenMovementSchema = z.object({
+  token: z.string(),
+  from: z.string(),
+  to: z.string(),
+  // The recorder reads the amount straight from the signed i128 event value
+  // (record/movements.ts readAmount), so a non-standard token that emits a
+  // negative transfer/mint/burn amount round-trips as a negative string. Mirror
+  // that here; the synth gate, not the wire schema, decides what to do with it.
+  amount: z.string().regex(/^-?[0-9]+$/),
+})
+
+export const OnChainEventSchema = z.object({
+  contract: z.string(),
+  topics: z.array(z.string()),
+  data: ScValSchema,
+})
+
+export const ParseConfidenceSchema = z.object({
+  overall: z.number().min(0).max(1),
+  knownContracts: z.array(z.string()),
+  unknownContracts: z.array(
+    z.object({
+      contract: z.string(),
+      reason: z.enum(['no-abi', 'version-mismatch', 'opaque-result']),
+    })
+  ),
+  opaqueScVals: z.array(z.object({ path: z.string(), type: z.string() })),
+  thresholdUsed: z.number().min(0).max(1),
+})
+
+/** RecordedTransaction mirrors the core RecordedTransaction. The output shape
+ *  is referenced by name in the tool result structured content; we deliberately
+ *  type it loosely (`z.unknown()`) on the success path so the core remains the
+ *  single source of truth for the wire payload. */
+export const RecordedTransactionSchema = z
+  .object({
+    network: NetworkSchema,
+    signers: z.array(z.string()),
+    invocations: z.array(ContractInvocationSchema).max(MAX_INVOCATIONS),
+    tokenMovements: z.array(TokenMovementSchema),
+    events: z.array(OnChainEventSchema),
+    authEntries: z.array(z.unknown()),
+    ledgerSequence: z.number().int().nonnegative(),
+    fetchedAt: z.number().int().nonnegative(),
+    parseConfidence: ParseConfidenceSchema,
+    sourceAccount: z.string(),
+  })
+  .passthrough()
+
+/** MandateSpec mirrors the core MandateSpec. The deterministic Mandate
+ *  front-end needs no parseConfidence; the tool adapter injects the full
+ *  confidence after synthesis so the orchestrator can compare. */
+export const MandateSpecSchema = z
+  .object({
+    chain: z.literal('stellar'),
+    contract: z.string(),
+    method: z.string().optional(),
+    spendingLimit: z
+      .object({
+        token: z.string(),
+        limit: z.string().regex(/^[0-9]+$/),
+        windowSeconds: z.number().int().positive(),
+      })
+      .optional(),
+    // A threshold of 0 means "0 approvals", which is not a real M-of-N gate.
+    approvalThreshold: z.number().int().positive().optional(),
+    recipients: z.array(z.string()).optional(),
+    expiry: z
+      .object({
+        validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+        validUntilUnixSeconds: z.number().int().positive().optional(),
+      })
+      .optional(),
+  })
+  .passthrough()
+
+/** ComposeUserResponses mirrors the core. */
+export const ComposeUserResponsesSchema = z
+  .object({
+    windowSeconds: z.number().int().positive().optional(),
+    validUntilLedger: z.number().int().positive().max(U32_MAX).optional(),
+    limitAmount: z
+      .string()
+      .regex(/^[0-9]+$/)
+      .optional(),
+    invocationLimit: z.number().int().positive().optional(),
+    // Swap recipient allowlist (SoroSwap call_arg[3]). Each entry must be a
+    // Stellar address (G... wallet or C... contract); supplying it REPLACES the
+    // default pin to the recorded recipient. Validated with the shared StrKey
+    // helper (no hand-rolled regex).
+    swapRecipientAllowlist: z
+      .array(z.string().refine(isStellarAddress, 'must be a Stellar address (G... or C...)'))
+      .optional(),
+  })
+  .passthrough()
+
+/** OzAdapterConfig - the per-network OZ built-in instance addresses. */
+export const OzAdapterConfigSchema = z.object({
+  network: NetworkSchema,
+  instances: z.object({
+    spending_limit: z.string(),
+    simple_threshold: z.string(),
+    weighted_threshold: z.string(),
+  }),
+})
+
+// ===== record_transaction =====
+
+export const RecordTransactionInputSchema = z
+  .object({
+    hash: z.string().min(1).optional(),
+    xdr: z.string().min(1).optional(),
+    network: NetworkSchema,
+    confidenceOverride: z.number().min(0).max(1).optional(),
+  })
+  .refine((v) => !(v.hash && v.xdr), {
+    message: 'provide exactly one of `hash` or `xdr`, not both',
+  })
+  .refine((v) => Boolean(v.hash) || Boolean(v.xdr), {
+    message: 'one of `hash` or `xdr` is required',
+  })
+export type RecordTransactionInput = z.infer<typeof RecordTransactionInputSchema>
+
+// ===== synthesize_policy =====
+//
+// Discriminated union on `source` exposes BOTH front-ends through ONE tool.
+// - `source: 'mandate'` -> calls synthesizeFromMandate
+// - `source: 'recording'` -> calls synthesizeFromRecording
+
+export const SynthesizePolicyMandateInputSchema = z.object({
+  source: z.literal('mandate'),
+  mandate: MandateSpecSchema,
+  ozConfig: OzAdapterConfigSchema.optional(),
+})
+
+/** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
+ *  express (per-method scoping, invocation-count windows, oracle bounds, exact
+ *  hop paths) lower to a real interpreter predicate document instead of being
+ *  surfaced as warnings. The core deep-validates `smartAccountAddress` (a C...
+ *  contract, not the recording's G... source) and the tighten-only oracle
+ *  bounds; the schema stays light so the core owns the friendly ToolErrors. */
+export const InterpreterOptionsSchema = z.object({
+  smartAccountAddress: z.string(),
+  installNonce: z.number().int().positive().optional(),
+  oracleParams: z
+    .object({
+      maxStalenessSeconds: z.number().int().positive().optional(),
+      maxDeviationBps: z.number().int().positive().optional(),
+    })
+    .optional(),
+})
+
+export const SynthesizePolicyRecordingInputSchema = z.object({
+  source: z.literal('recording'),
+  recordedTx: RecordedTransactionSchema,
+  network: NetworkSchema,
+  userResponses: ComposeUserResponsesSchema.optional(),
+  confidenceOverride: z.object({ threshold: z.number().min(0).max(1) }).optional(),
+  interpreter: InterpreterOptionsSchema.optional(),
+  ozConfig: OzAdapterConfigSchema.optional(),
+})
+
+export const SynthesizePolicyInputSchema = z.discriminatedUnion('source', [
+  SynthesizePolicyMandateInputSchema,
+  SynthesizePolicyRecordingInputSchema,
+])
+export type SynthesizePolicyInput = z.infer<typeof SynthesizePolicyInputSchema>
+
+// ===== Error envelope (canonical) =====
+//
+// Mirrors ToolError from packages/policy-synth/src/errors.ts. We use a
+// `z.string()` for `code` (not an enum) because the core's ErrorCode union
+// evolves over time; the transport contract only promises a string code the
+// caller can dispatch on. A drift test asserts the canonical codes still
+// pass through unchanged.
+export const ToolErrorSchema = z
+  .object({
+    code: z.string(),
+    message: z.string(),
+    severity: z.enum(['info', 'warning', 'error', 'fatal']),
+    retryable: z.boolean(),
+    remediation: z
+      .object({
+        toolCall: z.object({ name: z.string(), args: z.record(z.unknown()) }).optional(),
+        userQuestion: z.object({ code: z.string(), question: z.string() }).optional(),
+        docsUrl: z.string().optional(),
+      })
+      .optional(),
+    details: z.unknown().optional(),
+  })
+  .passthrough()

package/src/synth/address.ts

@@ -0,0 +1,14 @@
+// src/synth/address.ts - Stellar address validation shared by the CLI + the
+// run-layer Zod schema.
+
+import { StrKey } from '@stellar/stellar-sdk'
+
+/** True when `s` is a valid Stellar address strkey - either an Ed25519 public
+ *  key (`G...`) or a contract address (`C...`). Backed by the SDK's `StrKey`
+ *  decoder (the same one the recorder uses in `record/decode.ts`); no
+ *  hand-rolled regex. Used to validate a caller-supplied swap recipient
+ *  allowlist, whose entries may be either a wallet (`G...`) or a contract
+ *  (`C...`). */
+export function isStellarAddress(s: string): boolean {
+  return StrKey.isValidEd25519PublicKey(s) || StrKey.isValidContract(s)
+}

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

@@ -81,9 +81,10 @@ export interface ComposeUserResponses {
    *  entries on the same asset emit multiple leaves. */
   oraclePriceBound?: OraclePriceBound[]
   /** Recipient allowlist for a swap (call_arg[3] on SoroSwap's
-   *  swap_exact_tokens_for_tokens). Absent -> RECIPIENT_ALLOWLIST_EMPTY
-   *  ambiguity (the caller is prompted; proceeding without an allowlist leaves
-   *  the recipient unconstrained). */
+   *  swap_exact_tokens_for_tokens). When supplied, it REPLACES the default
+   *  pin. Absent -> the recipient is pinned to the recorded value (mirroring
+   *  SEP-41) and RECIPIENT_ALLOWLIST_EMPTY is surfaced as informational, never
+   *  a silent free pass. */
   swapRecipientAllowlist?: string[]
 }
 
@@ -416,11 +417,16 @@ function appendProtocolSpecificConstraints(
 
     // Swap recipient (call_arg[3]): when the caller supplies
     // swapRecipientAllowlist, emit it as an `in` constraint on the recipient
-    // arg. When absent, surface RECIPIENT_ALLOWLIST_EMPTY so the caller is
-    // prompted; proceeding without an allowlist leaves the recipient
-    // unconstrained in the predicate. The ambiguity is only surfaced when
-    // the interpreter is enabled - if it isn't, the swap recipient is just
-    // ignored (today's behaviour).
+    // arg. When absent, PIN the recipient to the recorded value - mirroring the
+    // SEP-41 `to` arg above: the recorded flow went to exactly one recipient, so
+    // pinning it is the minimal policy that permits exactly that flow. Leaving
+    // it unconstrained would permit an arbitrary recipient (an evil twin with
+    // call_arg[3] = attacker_wallet). RECIPIENT_ALLOWLIST_EMPTY is still
+    // surfaced, but as INFORMATIONAL (the recipient was pinned; here is how to
+    // widen it), never as a silent free pass. The recipient is only enforceable
+    // via the interpreter predicate, so the pin (and the ambiguity) apply only
+    // when the interpreter is enabled - otherwise the swap recipient is ignored
+    // (today's behaviour, matching the other SoroSwap constraints).
     const recipientArg = topLevel.args[3]
     if (swapRecipientAllowlist && swapRecipientAllowlist.length > 0) {
       const cond: IRCondition = {
@@ -434,9 +440,14 @@ function appendProtocolSpecificConstraints(
         ozConstraints.push(cond)
       }
     } else if (interpreterEnabled && recipientArg && recipientArg.type === 'address') {
+      interpreterConstraints.push({
+        op: 'in',
+        selector: { kind: 'arg', argIndex: 3, scalarType: 'address' },
+        values: [recipientArg.value],
+      })
       ambiguities.push({
         code: 'RECIPIENT_ALLOWLIST_EMPTY',
-        question: `Recording shows the swap sending to ${recipientArg.value}. What recipient allowlist should the interpreter predicate bind? (omit to leave recipient unconstrained)`,
+        question: `No recipient allowlist supplied; the swap recipient (call_arg[3]) was pinned to the recorded value ${recipientArg.value}. To permit additional recipients, supply an allowlist (CLI: --recipient <C...|G...>, repeatable; MCP: userResponses.swapRecipientAllowlist) - it REPLACES this default pin.`,
       })
     }
   }

package/src/synth/deny-cases.ts

@@ -1,4 +1,5 @@
 import type { PredicateLeaf, PredicateNode, ScVal } from '../types.ts'
+import { MAX_SCVAL_CLONE_DEPTH } from '../types.ts'
 import type { EvalContext } from './evaluate.ts'
 import { literalNumericBigInt } from './predicate-literals.ts'
 
@@ -44,8 +45,45 @@ const ADJACENT_ASSETS = [
   'CCWCLTASNDT57N3BCHOSVB5QWMV5URK4BXLDDF6ZZQYMBQ4OKZA3ZB2N',
 ] as const
 
-/** Build deterministic model-evaluated alternatives without mutating the intended call. */
-export function generateCases(predicate: PredicateNode, permitCtx: EvalContext): GeneratedCases {
+// Phase 1 property-harness mutation dimensions excluded from the synth pipeline's
+// self-verify call so existing fixtures still emit policies. The harness tests
+// them as FINDINGS against the already-emitted policy.
+const OVERPERMISSIVE_DIMENSIONS = ['argument_reorder'] as const
+
+// The 15 dimensions the synth pipeline uses for self-verify and minimise.
+const ORIGINAL_DIMENSIONS: string[] = [
+  'amount',
+  'asset',
+  'contract',
+  'function',
+  'timing',
+  'time_window',
+  'invocation_count',
+  'arg_amount_bound',
+  'arg_bound',
+  'scope_contract_fn_arg',
+  'oracle_stale',
+  'oracle_missing',
+  'oracle_deviation_exceeded',
+  'oracle_paused',
+  'soroswap_allowed_path',
+]
+
+export { ORIGINAL_DIMENSIONS, OVERPERMISSIVE_DIMENSIONS }
+
+/** Build deterministic model-evaluated alternatives without mutating the intended call.
+ *
+ * @param predicate   - the synthesized predicate
+ * @param permitCtx   - EvalContext for the intended (permitted) call
+ * @param dimensions  - optional whitelist of dimension names to emit; when omitted
+ *                     all known dimensions (including over-permissiveness mutations)
+ *                     are emitted. The synth pipeline passes ORIGINAL_DIMENSIONS so
+ *                     existing fixtures do not regress. */
+export function generateCases(
+  predicate: PredicateNode,
+  permitCtx: EvalContext,
+  dimensions?: string[]
+): GeneratedCases {
   const facts = inspectPredicate(predicate)
   const denies: DenyCase[] = []
 
@@ -209,6 +247,33 @@ export function generateCases(predicate: PredicateNode, permitCtx: EvalContext):
     denies.push({ dimension: 'soroswap_allowed_path', ctx })
   }
 
+  // --- argument_reorder: swap first two address args ---
+  // Skipped when dimensions filter is active so the synth pipeline can emit a policy;
+  // the over-permissiveness harness then tests this mutation as a FINDING.
+  const constrainedArgIndices = new Set<number>()
+  for (const comparison of facts.comparisons) {
+    if (comparison.left.kind === 'call_arg') constrainedArgIndices.add(comparison.left.index)
+  }
+  for (const membership of facts.memberships) {
+    if (membership.needle.kind === 'call_arg') constrainedArgIndices.add(membership.needle.index)
+  }
+  const hasConstrainedArg = constrainedArgIndices.size > 0
+  if (
+    (!dimensions || dimensions.includes('argument_reorder')) &&
+    hasConstrainedArg &&
+    permitCtx.args.length >= 2 &&
+    permitCtx.args[0]?.type === 'address' &&
+    permitCtx.args[1]?.type === 'address'
+  ) {
+    const ctx = cloneContext(permitCtx)
+    // Guard above guarantees args[0] and args[1] exist and are address-typed.
+    const a0 = ctx.args[0] as ScVal
+    const a1 = ctx.args[1] as ScVal
+    ctx.args[0] = a1
+    ctx.args[1] = a0
+    denies.push({ dimension: 'argument_reorder', ctx })
+  }
+
   // Version mismatch, malformed predicates, master authorization, and nonce replay are install-time checks and are intentionally omitted from model-evaluated cases.
   return { permit: cloneContext(permitCtx), denies }
 }
@@ -439,9 +504,27 @@ function cloneContext(ctx: EvalContext): EvalContext {
   return cloned
 }
 
-function cloneScVal(value: ScVal): ScVal {
+function cloneScVal(value: ScVal, depth = 0): ScVal {
+  // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+  // payload cannot RangeError the JS stack during deny-case mutation. Over-depth
+  // throws a ToolError-shaped error that the `synthesizeFromRecording` envelope
+  // (item 3) converts to a structured `{ok:false, error}`.
   if (value.type === 'vec') {
-    return { type: 'vec', value: value.value.map(cloneScVal) }
+    if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+      throw cloneDepthError(value)
+    }
+    return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) }
   }
   return { ...value }
 }
+
+function cloneDepthError(value: ScVal): never {
+  const err = new Error(
+    `ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${MAX_SCVAL_CLONE_DEPTH})`
+  ) as Error & { code: string; severity: string; retryable: boolean; depthContext: unknown }
+  err.code = 'SYNTHESIS_ERROR'
+  err.severity = 'error'
+  err.retryable = false
+  err.depthContext = value.type
+  throw err
+}

package/src/synth/evaluate.ts

@@ -250,7 +250,7 @@ function evalArgEq(
 ): EvalResult {
   // eq(call_arg[i], literal_vec) -> EXACT ordered vector equality
   if (op === 'eq' && right.kind === 'literal_vec') {
-    if (!actual || actual.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
+    if (actual?.type !== 'vec') return { permit: false, reason: 'ARG_MISMATCH' }
     return compareVecExact(actual.value, right.elements, ctx)
       ? { permit: true }
       : { permit: false, reason: 'ARG_MISMATCH' }
@@ -267,7 +267,7 @@ function evalArgEq(
 
   // eq(call_arg[i], literal_i128) -> BigInt compare
   if (op === 'eq' && right.kind === 'literal_i128') {
-    if (!actual || actual.type !== 'i128') return { permit: false, reason: 'ARG_MISMATCH' }
+    if (actual?.type !== 'i128') return { permit: false, reason: 'ARG_MISMATCH' }
     return BigInt(actual.value) === BigInt(right.value)
       ? { permit: true }
       : { permit: false, reason: 'ARG_MISMATCH' }

package/src/synth/index.ts

@@ -1,5 +1,9 @@
 // src/synth/index.ts - re-export the synthesizer front-ends.
 
+// Exported because `swapRecipientAllowlist` is part of the public synthesis
+// input: a caller assembling one needs the same validator the schema applies,
+// and re-deriving it elsewhere means a second address check that can drift.
+export { isStellarAddress } from './address.ts'
 export {
   type ComposeOptions,
   type ComposeResult,

package/src/synth/minimize.ts

@@ -4,7 +4,11 @@ import type { EvalContext } from './evaluate.ts'
 import { runHarness } from './harness.ts'
 
 /** Remove top-level conjuncts only when the current and regenerated batteries still deny. */
-export function minimize(predicate: PredicateNode, permitCtx: EvalContext): PredicateNode {
+export function minimize(
+  predicate: PredicateNode,
+  permitCtx: EvalContext,
+  dimensions?: string[]
+): PredicateNode {
   if (predicate.op !== 'and') return predicate
 
   let children = [...predicate.children]
@@ -12,10 +16,10 @@ export function minimize(predicate: PredicateNode, permitCtx: EvalContext): Pred
 
   while (index < children.length) {
     const current: PredicateNode = { op: 'and', children }
-    const currentCases = generateCases(current, permitCtx)
+    const currentCases = generateCases(current, permitCtx, dimensions)
     const candidateChildren = children.filter((_, childIndex) => childIndex !== index)
     const candidate: PredicateNode = { op: 'and', children: candidateChildren }
-    const candidateCases = generateCases(candidate, permitCtx)
+    const candidateCases = generateCases(candidate, permitCtx, dimensions)
     const verificationCases = {
       permit: candidateCases.permit,
       denies: mergeDenyCases(currentCases.denies, candidateCases.denies),