@crediolabs/policy-synth 0.1.9 → 0.1.11

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

@@ -52,6 +52,7 @@ import {
   type RecordedTransaction,
   SOROBAN_LIMITS,
 } from '../types.ts'
+import type { SimulationResult } from '../verify/envelope.ts'
 import {
   type ComposeOptions,
   type ComposeUserResponses,
@@ -101,13 +102,36 @@ export interface SynthesizeFromRecordingOptions {
   userResponses?: ComposeUserResponses
   confidenceOverride?: { threshold: number }
   interpreter?: InterpreterAdapterOptions
+  /** --explain opt-in. When true, the orchestrator attaches the
+   *  in-memory `PredicateNode` + the corresponding `SimulationResult`
+   *  to the success envelope so the CLI can render a human-readable
+   *  review card. Absent or false -> the success envelope is unchanged
+   *  (byte-identical to today). The flag is ADDITIVE: the existing
+   *  ProposedPolicy fields (encodedPredicate, predicateHash, etc.) are
+   *  never altered by enabling explain. */
+  explain?: true
 }
 
 export function synthesizeFromRecording(
   tx: RecordedTransaction,
   opts: SynthesizeFromRecordingOptions,
   ozConfig: OzAdapterConfig
-): ToolResponse<ProposedPolicy> {
+): ToolResponse<ProposedPolicy> & {
+  /** Present iff `opts.explain === true` and the synthesis succeeded. The
+   *  `predicateTree` is the exact in-memory `PredicateNode` (canonical
+   *  JSON shape) that was encoded into `proposed.policyDocuments[*].encodedPredicate`
+   *  - reading the predicate tree from the policy document is therefore
+   *  unnecessary; the orchestrator carries it through. The `simulation`
+   *  is the verdict produced by the same self-verify pipeline that already
+   *  runs in the recording path (runHarness + evaluate), so the value is
+   *  REAL not synthetic. Absent when the synthesis did not engage the
+   *  interpreter (no interpreter opts supplied) - in that case the CLI
+   *  builds a minimal honest SimulationResult downstream. */
+  explain?: {
+    predicateTree: PredicateNode | null
+    simulation: SimulationResult
+  }
+} {
   // Item 3: ToolError try/catch envelope. Any ToolError-shaped throw (object
   // with a string `.code`) inside the body is converted to a structured
   // `{ok:false, error}`; anything else is rethrown so genuine bugs crash
@@ -159,7 +183,12 @@ function synthesizeFromRecordingInner(
   tx: RecordedTransaction,
   opts: SynthesizeFromRecordingOptions,
   ozConfig: OzAdapterConfig
-): ToolResponse<ProposedPolicy> {
+): ToolResponse<ProposedPolicy> & {
+  explain?: {
+    predicateTree: PredicateNode | null
+    simulation: SimulationResult
+  }
+} {
   // 0. validate inputs (fail closed - never synthesize from garbage).
   const invalid = validateOptions(opts)
   if (invalid) return { ok: false, error: invalid }
@@ -272,6 +301,15 @@ function synthesizeFromRecordingInner(
   }
   const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts)
 
+  // --explain hook: capture the in-memory predicate tree + the real
+  // self-verify verdict so the CLI can render a faithful review card.
+  // The verdict below is built from the SAME runHarness + evaluate that
+  // already gates the synthesis (it is not a parallel simulation); the
+  // intermediate inputs (harnessCases, evalResult) are otherwise discarded
+  // after the gate, so the explain hook reuses them - no extra work.
+  let explain: PredicateNode | null = null
+  let explainSim: SimulationResult | null = null
+
   // 5. OZ compile (always runs).
   const ozAdapter = createOzAdapter(ozConfig)
   const compileRes = ozAdapter.compile(composed.ir)
@@ -449,7 +487,6 @@ function synthesizeFromRecordingInner(
         },
       }
     }
-
     const evalResult = evaluate(finalPredicate, permitCtx)
     if (!evalResult.permit) {
       return {
@@ -464,6 +501,37 @@ function synthesizeFromRecordingInner(
       }
     }
 
+    // --explain capture: the interpreter path already produced the real
+    // self-verify verdict (runHarness passed, evalResult.permit is true).
+    // Build the SimulationResult from those outputs so the CLI card
+    // quotes the SAME verdict that gated the synthesis. We re-evaluate
+    // each deny case to surface its concrete reason; the harness only
+    // records whether the got-matches-expected boundary held.
+    if (opts.explain) {
+      explain = finalPredicate
+      const evaluatedCases: SimulationResult['evaluatedCases'] = [
+        {
+          dimension: 'permit',
+          outcome: evalResult.permit ? 'permit' : 'deny',
+          reason: 'matches recorded call',
+        },
+      ]
+      for (const deny of harnessCases.denies) {
+        const r = evaluate(finalPredicate, deny.ctx)
+        evaluatedCases.push({
+          dimension: deny.dimension,
+          outcome: r.permit ? 'permit' : 'deny',
+          reason: r.permit ? 'no matching deny' : r.reason,
+        })
+      }
+      explainSim = {
+        permit: { tx: 'permit' },
+        evaluatedCases,
+        backend: 'ts-model',
+        simulatorVersion: 'ts-model-1.0.0',
+      }
+    }
+
     // 6c. Re-encode the (possibly minimised) PredicateNode and stamp the
     //     canonical bytes back onto the PolicyDocument + PolicyRef. The
     //     `encodePredicate` helper throws ToolError-shaped errors on cap
@@ -566,7 +634,38 @@ function synthesizeFromRecordingInner(
     ],
     ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
   }
-  return { ok: true, data: proposed }
+  // --explain success envelope. The interpreter path populated
+  // `explain` + `explainSim` from the real self-verify verdict above;
+  // the OZ-only path did not (no predicate tree exists). When opts.explain
+  // is set and the OZ-only path ran, construct the minimal honest
+  // SimulationResult: the verdict is NOT a passing simulation - the
+  // interpreter was never engaged, so permit is deny with a truthful
+  // reason and evaluatedCases is empty.
+  const envelope: ToolResponse<ProposedPolicy> & {
+    explain?: {
+      predicateTree: PredicateNode | null
+      simulation: SimulationResult
+    }
+  } = { ok: true, data: proposed }
+  if (opts.explain) {
+    if (explainSim) {
+      envelope.explain = { predicateTree: explain, simulation: explainSim }
+    } else {
+      envelope.explain = {
+        predicateTree: null,
+        simulation: {
+          permit: {
+            tx: 'deny',
+            reason: 'No self-verification was performed (interpreter adapter was not engaged)',
+          },
+          evaluatedCases: [],
+          backend: 'ts-model',
+          simulatorVersion: 'not-run',
+        },
+      }
+    }
+  }
+  return envelope
 }
 
 // Re-export the throwToolError helper for callers that need to surface a
@@ -905,11 +1004,22 @@ function visitOracleLeaves(
   }
 }
 
+/** An oracle threshold restated on the normalised 9-dp basis prices use.
+ *  Thresholds carry their own basis, so reading the digits raw would build a
+ *  permit context off by 10^(decimals-9) and the intended call would not
+ *  satisfy its own bound. Mirrors NORMALISED_DECIMALS in oracle.rs. */
 function oracleLiteralFromLeaf(leaf: PredicateLeaf): bigint | undefined {
-  if (leaf.kind !== 'literal_i128') return undefined
+  if (leaf.kind !== 'oracle_threshold') return undefined
+  let value: bigint
   try {
-    return BigInt(leaf.value)
+    value = BigInt(leaf.value)
   } catch {
     return undefined
   }
+  const normalised = 9n
+  const decimals = BigInt(leaf.decimals)
+  if (decimals <= normalised) return value * 10n ** (normalised - decimals)
+  // Floor: a finer-grained threshold has no exact 9-dp representation; the
+  // caller offsets by one from here to land on the right side of the bound.
+  return value / 10n ** (decimals - normalised)
 }

package/src/types.ts

@@ -155,6 +155,13 @@ export type PredicateLeaf =
   // recorded ScVal type. A non-vec arg, missing element, missing field, or
   // type mismatch all DENY (fail-closed).
   | { kind: 'call_arg_field'; index: number; element: number; field: string }
+  // `call_arg_scaled(index, num, den)` evaluates to `args[index] * num / den`
+  // (truncating toward zero). The slippage-floor leaf: a swap policy
+  // expresses `call_arg[out] >= call_arg_scaled(in, num, den)` as "the
+  // minimum output must be at least this ratio of the input". `num`/`den`
+  // are decimal strings on i128 (mirrors `literal_i128`); the contract
+  // refuses `den == 0` and `num <= 0` / `den <= 0` at install.
+  | { kind: 'call_arg_scaled'; index: number; num: string; den: string }
   // `call_sub_invocation[i]` is NOT in v1 grammar. OZ `Policy::enforce`
   // receives one `Context`, not a sub-invocation tree; sub-invocations live under
   // `InvokerContractAuthEntry::Contract(SubContractInvocation)`, not in the
@@ -166,6 +173,11 @@ export type PredicateLeaf =
   | { 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)
+  // The right-hand side of an oracle comparison. It carries its own decimal
+  // basis because the contract cannot recover it: prices normalise to 9 dp, so
+  // a raw 14-dp threshold is ~10^5 too large and `price <= threshold` becomes
+  // trivially true. `value` is a decimal string on i128, like `literal_i128`.
+  | { kind: 'oracle_threshold'; value: string; decimals: number }
   // 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 }