@crediolabs/policy-synth 0.1.2 → 0.1.4

package/src/types.ts

@@ -111,7 +111,11 @@ export type PredicateNode =
   | { op: 'not'; child: PredicateNode }
   | { op: 'eq'; left: PredicateLeaf; right: PredicateLeaf }
   | { op: 'lt' | 'lte' | 'gt' | 'gte'; left: PredicateLeaf; right: PredicateLeaf }
-  | { op: 'in'; needle: PredicateLeaf; haystack: PredicateLeaf[] }
+  | {
+      op: 'in'
+      needle: PredicateLeaf
+      haystack: PredicateLeaf[] /** set-valued only - the haystack is always sorted by canonical XDR bytes (pure membership). */
+    }
 
 export type PredicateLeaf =
   | { kind: 'call_contract' }
@@ -123,11 +127,24 @@ export type PredicateLeaf =
   // enforce Context. Scope is per-authorized-context; a v1.1 sub-invocation
   // tree leaf is gated on the enforce-Context-shape spike result.
   | { kind: 'amount'; token: string }
-  | { kind: 'window_spent'; token: string }
+  | { kind: 'window_spent'; token: string; windowSeconds: number }
   | { kind: 'now' }
   | { kind: 'valid_until' }
   | { kind: 'invocation_count_in_window'; windowSecs: number }
   | { kind: 'oracle_price'; asset: string } // Stellar Address (SAC address for SEP-41; XLM uses its network SAC)
+  // Literal leaves: bare ScVal on the wire (no selector-tuple wrapper). Right-hand side of
+  // comparisons, elements of `in` haystacks, and operands to future arithmetic nodes.
+  | { kind: 'literal_address'; value: string }
+  | { kind: 'literal_i128'; value: string }
+  | { kind: 'literal_symbol'; value: string }
+  | { kind: 'literal_u32'; value: number }
+  | { kind: 'literal_u64'; value: string }
+  | { kind: 'literal_bytes'; value: string } // hex string; wrapped as ScVal::Bytes at encode time
+  // Exact ordered vector of literals (e.g. a swap hop path). Encodes to a bare
+  // ScVal::Vec with the caller's order preserved verbatim - the order IS the
+  // semantic. An exact ordered sequence equality is expressed by `eq(selector,
+  // literal_vec([...]))`. `in` is reserved for pure set membership (sorted).
+  | { kind: 'literal_vec'; elements: PredicateLeaf[] }
 
 export interface OZPrimitiveConfig {
   primitive: 'spending_limit' | 'simple_threshold' | 'weighted_threshold'

package/src/verify/envelope.ts

@@ -0,0 +1,28 @@
+// src/verify/envelope.ts - the post-simulation result envelope used by
+// review-card rendering and verification.
+//
+// `SimulationResult` is the structured verdict a `simulate_policy` run
+// produces; the review-card builder reads it as one of its inputs (so the
+// rendered card can quote the backend that evaluated the policy) and the
+// verification pipeline reads `permit` + `evaluatedCases` to confirm every
+// generated deny case really did deny.
+//
+// This envelope is intentionally separate from the CustodyAdapter
+// `SimulationResult` in `src/seams/types.ts` (which is the dry-run stub
+// returned by `adapter.simulate(ir, permitTx)`); the seam result is the
+// adapter contract, this envelope is the post-simulation record consumed by
+// downstream rendering + verification.
+//
+// Fields:
+//   - `permit` is the single verdict for the candidate recorded tx.
+//   - `evaluatedCases` is the deny-case battery outcome (every dimension
+//     must report `deny` when the policy is minimal).
+//   - `backend` is the actual evaluator that produced the verdict.
+//   - `simulatorVersion` lets the reviewer / audit log distinguish runs.
+
+export type SimulationResult = {
+  permit: { tx: 'permit' } | { tx: 'deny'; reason: string }
+  evaluatedCases: Array<{ dimension: string; outcome: 'permit' | 'deny'; reason: string }>
+  backend: 'interpreter-v1' | 'ts-model'
+  simulatorVersion: string
+}

package/src/verify/index.ts

@@ -0,0 +1,5 @@
+// src/verify/index.ts - re-export the simulation / verification surface.
+
+export type { SimulationResult } from './envelope.ts'
+export { type SimulateOptions, simulatePolicy } from './simulate.ts'
+export { type VerifyOptions, verifyPolicy } from './verify.ts'

package/src/verify/simulate.ts

@@ -0,0 +1,292 @@
+// src/verify/simulate.ts - the post-simulation verdict for `simulate_policy`.
+//
+// `simulatePolicy` replays a recorded transaction against a proposed
+// `PredicateNode` and emits the `SimulationResult` envelope the review-card
+// builder + the verification pipeline consume.
+//
+// Boundary (pinned, must not drift):
+//   - `SIMULATION_ERROR`        = RUNTIME evaluation failed. Surfaced by
+//     `simulatePolicy`. Reasons: malformed `permitTx` input (no top-level
+//     invocation to build an EvalContext from), a referenced oracle asset
+//     without a satisfying price fixture, or a non-runtime propagation (a
+//     throw that is not an oracle error or a controlled deny). A
+//     runtime evaluation failure is NOT a policy-minimality problem; the
+//     policy may still be minimal. Re-running with a complete fixture MAY
+//     succeed.
+//   - `VERIFICATION_FAILED`     = STATIC minimality check failed. Surfaced
+//     by `verifyPolicy`. The minimiser identified a load-bearing-free
+//     constraint; the policy is structurally over-broad regardless of how
+//     any concrete call evaluates. Re-running with a different fixture
+//     will NOT fix it; the policy must be trimmed.
+//
+// Determinism: same `(predicate, permitTx, opts)` -> byte-identical
+// envelope, no clock, no randomness.
+//
+// The permit EvalContext is built locally (mirror of the helper used in
+// `synthesize-from-recording.ts`) so this module does not couple to the
+// orchestrator's private build helpers. The shape is pinned by the test
+// suite to stay in lockstep.
+
+import type { ToolError, ToolResponse } from '../errors.ts'
+import { generateCases } from '../synth/deny-cases.ts'
+import { type EvalContext, evaluate } from '../synth/evaluate.ts'
+import type {
+  ContractInvocation,
+  PredicateLeaf,
+  PredicateNode,
+  RecordedTransaction,
+  ScVal,
+} from '../types.ts'
+import type { SimulationResult } from './envelope.ts'
+
+const SIMULATOR_VERSION = 'ts-model-1.0.0'
+
+/** Options for `simulatePolicy`. `validUntilLedger` is propagated onto the
+ *  permit EvalContext so the simulator exercises the expiry gate; absent ->
+ *  no expiry check (mirrors the orchestrator's "no `validUntilLedger`
+ *  supplied" path). `oraclePricesByAsset` is the test fixture the simulator
+ *  uses to satisfy `oracle_price` leaves so the permit call evaluates under
+ *  the bound; absent -> derive satisfying prices from the predicate itself
+ *  (the orchestrator's oracle-satisfying-price logic). */
+export interface SimulateOptions {
+  validUntilLedger?: number
+  /** Pre-populated oracle-price entries keyed by asset address. The fixture
+   *  must satisfy every `oracle_price` leaf in the predicate; absent or
+   *  unsatisfying entries cause `SIMULATION_ERROR`. */
+  oraclePricesByAsset?: Record<
+    string,
+    | { price: string; timestampSeconds: number }
+    | {
+        error: 'stale' | 'missing' | 'deviation' | 'paused' | 'decimals' | 'fingerprint'
+      }
+  >
+}
+
+/** Replay a recorded transaction against a proposed predicate and emit the
+ *  `SimulationResult` envelope. The simulator returns the SAME permit
+ *  verdict `runHarness` expects: the intended recorded call must permit; every
+ *  generated deny dimension must deny. A runtime evaluation failure
+ *  (malformed input, missing oracle fixture, etc.) returns a `SIMULATION_ERROR`
+ *  `ToolError` - NOT a deny verdict, NOT `VERIFICATION_FAILED`. The boundary
+ *  is pinned: minimality is a verify-time concern, runtime evaluation is a
+ *  simulate-time concern. */
+export function simulatePolicy(
+  predicate: PredicateNode | null,
+  permitTx: RecordedTransaction,
+  opts: SimulateOptions = {}
+): ToolResponse<SimulationResult> {
+  // The permit EvalContext requires a top-level invocation. A recorded tx
+  // with no invocations is structurally malformed input - we surface a
+  // runtime `SIMULATION_ERROR` rather than fabricating a permit verdict.
+  const topLevel = permitTx.invocations[0]
+  if (!topLevel) {
+    return {
+      ok: false,
+      error: simulationError('recorded transaction has no top-level invocation to simulate'),
+    }
+  }
+
+  let permitCtx: EvalContext
+  try {
+    permitCtx = buildPermitContext(predicate, permitTx, topLevel, opts)
+  } catch (e) {
+    return {
+      ok: false,
+      error: simulationError(`could not build permit evaluation context: ${(e as Error).message}`),
+    }
+  }
+
+  // `predicate === null` means the policy is OZ-only (no interpreter
+  // predicate). We still emit the envelope so the review card + verifier
+  // can consume it: the permit verdict evaluates an always-permit empty
+  // tree, and the deny battery is empty (nothing to verify at the
+  // interpreter layer).
+  const evaluatePredicate: PredicateNode = predicate ?? { op: 'and', children: [] }
+
+  const evaluatedCases: SimulationResult['evaluatedCases'] = []
+
+  let permitVerdict: { permit: true } | { permit: false; reason: string }
+  try {
+    permitVerdict = evaluate(evaluatePredicate, permitCtx)
+  } catch (e) {
+    return {
+      ok: false,
+      error: simulationError(`permit evaluation threw at runtime: ${(e as Error).message}`, e),
+    }
+  }
+  evaluatedCases.push({
+    dimension: 'permit',
+    outcome: permitVerdict.permit ? 'permit' : 'deny',
+    reason: permitVerdict.permit ? 'matches recorded call' : permitVerdict.reason,
+  })
+
+  // The deny battery is generated against the SAME permit context. A
+  // runtime evaluation failure on ANY deny case is a `SIMULATION_ERROR` -
+  // not a deny verdict (an evaluate-throws is not a deny) and not a
+  // minimality problem.
+  const cases = generateCases(evaluatePredicate, permitCtx)
+  for (const deny of cases.denies) {
+    let result: { permit: true } | { permit: false; reason: string }
+    try {
+      result = evaluate(evaluatePredicate, deny.ctx)
+    } catch (e) {
+      return {
+        ok: false,
+        error: simulationError(
+          `deny case "${deny.dimension}" threw at runtime: ${(e as Error).message}`,
+          e
+        ),
+      }
+    }
+    evaluatedCases.push({
+      dimension: deny.dimension,
+      outcome: result.permit ? 'permit' : 'deny',
+      reason: result.permit ? 'no matching deny' : result.reason,
+    })
+  }
+
+  const envelope: SimulationResult = {
+    permit: permitVerdict.permit ? { tx: 'permit' } : { tx: 'deny', reason: permitVerdict.reason },
+    evaluatedCases,
+    backend: 'ts-model',
+    simulatorVersion: SIMULATOR_VERSION,
+  }
+  return { ok: true, data: envelope }
+}
+
+/** Build the permit `EvalContext` the simulator drives. Mirrors the
+ *  helper in `synthesize-from-recording.ts` so the simulator sees the same
+ *  shape the orchestrator's self-verify pipeline sees; we mirror here
+ *  rather than import to keep `src/verify/` decoupled from the
+ *  orchestrator's private helpers. The shape is pinned by tests so the
+ *  two implementations stay in lockstep. */
+function buildPermitContext(
+  predicate: PredicateNode | null,
+  tx: RecordedTransaction,
+  topLevel: ContractInvocation,
+  opts: SimulateOptions
+): EvalContext {
+  const amountByToken: Record<string, string> = {}
+  const totals = new Map<string, bigint>()
+  for (const m of tx.tokenMovements) {
+    const current = totals.get(m.token) ?? 0n
+    totals.set(m.token, current + BigInt(m.amount))
+  }
+  for (const [token, total] of totals) {
+    amountByToken[token] = total.toString()
+  }
+
+  // Oracle prices: when the caller supplies a fixture, use it; otherwise
+  // derive a satisfying entry per `oracle_price` leaf in the predicate so
+  // the permit call permits. Negatives are clamped at 0 (Stellar oracle
+  // prices are non-negative).
+  const oraclePriceByAsset: EvalContext['oraclePriceByAsset'] = {}
+  if (opts.oraclePricesByAsset) {
+    for (const [asset, entry] of Object.entries(opts.oraclePricesByAsset)) {
+      oraclePriceByAsset[asset] = entry
+    }
+  }
+  if (predicate !== null) {
+    visitOracleLeaves(predicate, (asset, op, bound) => {
+      // A caller-supplied fixture entry always wins; we only fill gaps.
+      if (oraclePriceByAsset[asset] !== undefined) return
+      let price: bigint
+      switch (op) {
+        case 'lt':
+        case 'gt':
+          price = op === 'lt' ? bound - 1n : bound + 1n
+          break
+        case 'lte':
+        case 'gte':
+        case 'eq':
+          price = bound
+          break
+      }
+      if (price < 0n) price = 0n
+      oraclePriceByAsset[asset] = {
+        price: price.toString(),
+        timestampSeconds: tx.fetchedAt,
+      }
+    })
+  }
+
+  const ctx: EvalContext = {
+    contract: topLevel.contract,
+    fn: topLevel.fn,
+    args: topLevel.args.map(cloneScVal),
+    atLedger: tx.ledgerSequence,
+    nowSeconds: tx.fetchedAt,
+    amountByToken,
+    windowSpentByToken: {},
+    invocationCountByWindow: {},
+    oraclePriceByAsset,
+  }
+  if (opts.validUntilLedger !== undefined) {
+    ctx.validUntilLedger = opts.validUntilLedger
+  }
+  return ctx
+}
+
+function cloneScVal(value: ScVal): ScVal {
+  if (value.type === 'vec') {
+    return { type: 'vec', value: value.value.map(cloneScVal) }
+  }
+  return { ...value }
+}
+
+function visitOracleLeaves(
+  node: PredicateNode,
+  visit: (asset: string, op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte', bound: bigint) => void
+): void {
+  switch (node.op) {
+    case 'and':
+    case 'or':
+      for (const child of node.children) visitOracleLeaves(child, visit)
+      return
+    case 'not':
+      visitOracleLeaves(node.child, visit)
+      return
+    case 'eq':
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte': {
+      const leftLeaf = node.left
+      const rightLeaf = node.right
+      let oracleAsset: string | undefined
+      let literal: bigint | undefined
+      if (leftLeaf.kind === 'oracle_price') {
+        oracleAsset = leftLeaf.asset
+        literal = oracleLiteralFromLeaf(rightLeaf)
+      } else if (rightLeaf.kind === 'oracle_price') {
+        oracleAsset = rightLeaf.asset
+        literal = oracleLiteralFromLeaf(leftLeaf)
+      }
+      if (oracleAsset === undefined || literal === undefined) return
+      visit(oracleAsset, node.op, literal)
+      return
+    }
+    case 'in':
+      return
+  }
+}
+
+function oracleLiteralFromLeaf(leaf: PredicateLeaf): bigint | undefined {
+  if (leaf.kind !== 'literal_i128') return undefined
+  try {
+    return BigInt(leaf.value)
+  } catch {
+    return undefined
+  }
+}
+
+function simulationError(message: string, cause?: unknown): ToolError {
+  const error: ToolError = {
+    code: 'SIMULATION_ERROR',
+    message,
+    severity: 'error',
+    retryable: false,
+  }
+  if (cause !== undefined) error.details = { cause: String(cause) }
+  return error
+}

package/src/verify/verify.ts

@@ -0,0 +1,224 @@
+// src/verify/verify.ts - the static minimality check for `verify_policy`.
+//
+// `verifyPolicy` proves the policy is MINIMAL: no top-level conjunct is
+// load-bearing-free. It is the static sibling of `simulatePolicy` and emits
+// `VERIFICATION_FAILED` (not `SIMULATION_ERROR`) on failure. The boundary is
+// pinned:
+//
+//   - `VERIFICATION_FAILED`  = STATIC minimality check failed. The policy is
+//     structurally over-broad: a constraint could be dropped without losing
+//     a deny-case. Surfaced by `verifyPolicy`. Runtime evaluation is not
+//     part of this check; the policy may evaluate to a permit/deny just
+//     fine, the failure is shape-only.
+//
+//   - `SIMULATION_ERROR`     = RUNTIME evaluation failed (see simulate.ts).
+//     This module never emits SIMULATION_ERROR. A minimality failure is
+//     never a simulation error and vice-versa.
+//
+// Algorithm:
+//   1. Build the permit EvalContext from `permitTx` (mirror of the
+//      orchestrator's helper so verify is self-contained).
+//   2. Run `minimize(predicate, permitCtx)` to strip load-bearing-free
+//      top-level conjuncts (only `and` predicates are minimisable; other
+//      shapes are returned unchanged by `minimize`).
+//   3. If the minimised tree has fewer top-level conjuncts than the input,
+//      return `VERIFICATION_FAILED` listing the dropped conjuncts by their
+//      structural fingerprint.
+//   4. Otherwise `{ ok: true }`.
+//
+// Determinism: same `(predicate, permitTx)` -> byte-identical verdict.
+
+import type { ToolError, ToolResponse } from '../errors.ts'
+import type { EvalContext } from '../synth/evaluate.ts'
+import { minimize } from '../synth/minimize.ts'
+import type { ContractInvocation, PredicateNode, RecordedTransaction, ScVal } from '../types.ts'
+
+/** Options for `verifyPolicy`. Mirrors the orchestrator's permit-context
+ *  knobs (expiry; oracle fixture) so verify sees the same shape
+ *  `simulatePolicy` sees. */
+export interface VerifyOptions {
+  validUntilLedger?: number
+  oraclePricesByAsset?: Record<
+    string,
+    | { price: string; timestampSeconds: number }
+    | {
+        error: 'stale' | 'missing' | 'deviation' | 'paused' | 'decimals' | 'fingerprint'
+      }
+  >
+}
+
+/** Run the static minimality check on a proposed predicate + recorded tx.
+ *  Returns `{ ok: true }` when the predicate is minimal (every top-level
+ *  conjunct carries load) and `VERIFICATION_FAILED` when a conjunct could
+ *  be dropped without losing a deny-case. The dropped conjuncts are
+ *  reported in `details.droppedConstraints` so the caller can render a
+ *  review-card warning. */
+export function verifyPolicy(
+  predicate: PredicateNode,
+  permitTx: RecordedTransaction,
+  opts: VerifyOptions = {}
+): ToolResponse<true> {
+  const topLevel = permitTx.invocations[0]
+  if (!topLevel) {
+    return {
+      ok: false,
+      error: verificationFailed(
+        'recorded transaction has no top-level invocation to verify against',
+        { droppedConstraints: [] }
+      ),
+    }
+  }
+
+  let permitCtx: EvalContext
+  try {
+    permitCtx = buildPermitContextForVerify(permitTx, topLevel, opts)
+  } catch (e) {
+    return {
+      ok: false,
+      error: verificationFailed(
+        `could not build permit evaluation context: ${(e as Error).message}`,
+        { droppedConstraints: [] }
+      ),
+    }
+  }
+
+  // `minimize` only reduces `and` predicates; other shapes are returned
+  // unchanged. A non-`and` predicate therefore trivially passes the static
+  // minimality check (its top-level structure carries no removable
+  // conjuncts). The runtime harness in `simulatePolicy` covers the
+  // OR / NOT / comparison shapes.
+  const minimised = minimize(predicate, permitCtx)
+
+  // Drop count: only meaningful for `and`. For other shapes we already
+  // returned the input unchanged; report ok.
+  if (predicate.op !== 'and' || minimised.op !== 'and') {
+    if (!structuralEqual(predicate, minimised)) {
+      return {
+        ok: false,
+        error: verificationFailed(
+          'minimizer returned a structurally different tree for a non-and predicate',
+          { droppedConstraints: [fingerprint(minimised)] }
+        ),
+      }
+    }
+    return { ok: true, data: true }
+  }
+
+  const inputChildren = predicate.children
+  const minimisedChildren = minimised.children
+  if (minimisedChildren.length >= inputChildren.length) {
+    return { ok: true, data: true }
+  }
+
+  // Over-broad: identify the dropped conjuncts by structural fingerprint
+  // (so the review card can quote exactly which constraint was redundant).
+  // We use a multiset comparison because two structurally identical
+  // conjuncts (e.g. a duplicate `call_fn == transfer`) collapse to the
+  // same fingerprint - the dropped item is the one whose fingerprint
+  // count drops between input and minimised.
+  const inputCounts = fingerprintCounts(inputChildren)
+  const minimisedCounts = fingerprintCounts(minimisedChildren)
+  const dropped: string[] = []
+  for (const [fp, count] of inputCounts) {
+    const kept = minimisedCounts.get(fp) ?? 0
+    for (let i = 0; i < count - kept; i++) dropped.push(fp)
+  }
+  return {
+    ok: false,
+    error: verificationFailed(
+      `policy is structurally over-broad: ${dropped.length} redundant conjunct(s) can be dropped without losing a deny case`,
+      { droppedConstraints: dropped }
+    ),
+  }
+}
+
+function buildPermitContextForVerify(
+  tx: RecordedTransaction,
+  topLevel: ContractInvocation,
+  opts: VerifyOptions
+): EvalContext {
+  const amountByToken: Record<string, string> = {}
+  const totals = new Map<string, bigint>()
+  for (const m of tx.tokenMovements) {
+    const current = totals.get(m.token) ?? 0n
+    totals.set(m.token, current + BigInt(m.amount))
+  }
+  for (const [token, total] of totals) {
+    amountByToken[token] = total.toString()
+  }
+
+  const oraclePriceByAsset: EvalContext['oraclePriceByAsset'] = {}
+  if (opts.oraclePricesByAsset) {
+    for (const [asset, entry] of Object.entries(opts.oraclePricesByAsset)) {
+      oraclePriceByAsset[asset] = entry
+    }
+  }
+
+  const ctx: EvalContext = {
+    contract: topLevel.contract,
+    fn: topLevel.fn,
+    args: topLevel.args.map(cloneScVal),
+    atLedger: tx.ledgerSequence,
+    nowSeconds: tx.fetchedAt,
+    amountByToken,
+    windowSpentByToken: {},
+    invocationCountByWindow: {},
+    oraclePriceByAsset,
+  }
+  if (opts.validUntilLedger !== undefined) {
+    ctx.validUntilLedger = opts.validUntilLedger
+  }
+  return ctx
+}
+
+function cloneScVal(value: ScVal): ScVal {
+  if (value.type === 'vec') {
+    return { type: 'vec', value: value.value.map(cloneScVal) }
+  }
+  return { ...value }
+}
+
+function fingerprint(node: PredicateNode): string {
+  return JSON.stringify(node, replacer)
+}
+
+/** Multiset fingerprint counts for a list of conjuncts. Two structurally
+ *  identical conjuncts (e.g. a duplicate `call_fn == transfer`) each
+ *  contribute their own count. The minimiser may drop one of them; we
+ *  surface exactly the surplus via the count difference. */
+function fingerprintCounts(children: PredicateNode[]): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const child of children) {
+    const fp = fingerprint(child)
+    counts.set(fp, (counts.get(fp) ?? 0) + 1)
+  }
+  return counts
+}
+
+/** Deterministic JSON key order for fingerprinting. Object keys are sorted
+ *  recursively so the same shape produces the same string. */
+function replacer(_key: string, value: unknown): unknown {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>
+    const sorted: Record<string, unknown> = {}
+    for (const k of Object.keys(obj).sort()) {
+      sorted[k] = obj[k]
+    }
+    return sorted
+  }
+  return value
+}
+
+function structuralEqual(a: PredicateNode, b: PredicateNode): boolean {
+  return fingerprint(a) === fingerprint(b)
+}
+
+function verificationFailed(message: string, details: unknown): ToolError {
+  return {
+    code: 'VERIFICATION_FAILED',
+    message,
+    severity: 'error',
+    retryable: false,
+    details,
+  }
+}