@crediolabs/policy-synth 0.1.4 → 0.1.5

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

@@ -43,6 +43,7 @@ import type { ToolError, ToolResponse } from '../errors.ts'
 import { encodePredicate } from '../predicate/encode.ts'
 import {
   type ContractInvocation,
+  MAX_SCVAL_CLONE_DEPTH,
   type Network,
   OZ_LIMITS,
   type PredicateLeaf,
@@ -102,16 +103,86 @@ export interface SynthesizeFromRecordingOptions {
   interpreter?: InterpreterAdapterOptions
 }
 
-/** Synthesize a ProposedPolicy from a recorded transaction. */
 export function synthesizeFromRecording(
   tx: RecordedTransaction,
   opts: SynthesizeFromRecordingOptions,
   ozConfig: OzAdapterConfig
+): ToolResponse<ProposedPolicy> {
+  // 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
+  // instead of being silently swallowed. The envelope must wrap the entire
+  // synthesis body so a thrown `encodePredicate` cap error (PREDICATE_TOO_DEEP,
+  // TOO_MANY_LEAVES, etc.) or a depth-cap throw from `cloneScVal` surfaces as
+  // a structured ToolError rather than a thrown RangeError.
+  try {
+    return synthesizeFromRecordingInner(tx, opts, ozConfig)
+  } catch (e) {
+    if (isToolErrorShape(e)) {
+      return {
+        ok: false,
+        error: {
+          code: e.code as ToolError['code'],
+          message: e.message,
+          severity: 'error',
+          retryable: false,
+        },
+      }
+    }
+    throw e
+  }
+}
+
+/** True when `e` is the ToolError-shaped throw the internal pipeline uses to
+ *  signal a structured failure (e.g. `encodePredicate` cap errors, `cloneScVal`
+ *  depth-cap throws). Detected by a string `code` field — the only contract
+ *  the body's internal helpers agree on. */
+function isToolErrorShape(e: unknown): e is { code: string; message: string } {
+  if (e === null || typeof e !== 'object') return false
+  const code = (e as { code?: unknown }).code
+  const message = (e as { message?: unknown }).message
+  return typeof code === 'string' && typeof message === 'string'
+}
+
+/** ToolError-shaped error helper used by the body to surface a structured
+ *  failure that the envelope converts to `{ok:false, error}`. */
+function throwToolError(code: ToolError['code'], message: string): never {
+  const err = new Error(message) as Error & { code: string; severity: string; retryable: boolean }
+  err.code = code
+  err.severity = 'error'
+  err.retryable = false
+  throw err
+}
+
+/** Synthesize a ProposedPolicy from a recorded transaction. */
+function synthesizeFromRecordingInner(
+  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 }
 
+  // 0a. per-movement amount validation (item 2). Synthesizing from a recording
+  //     whose `tokenMovements[].amount` does not match the canonical positive
+  //     decimal integer format is a malformed-input failure, not a runtime
+  //     one - reject it here so the downstream `BigInt(m.amount)` in
+  //     `buildPermitContext` cannot throw a SyntaxError past the envelope.
+  for (const [i, m] of tx.tokenMovements.entries()) {
+    if (!/^[0-9]+$/.test(m.amount)) {
+      return {
+        ok: false,
+        error: {
+          code: 'RECORDING_VALIDATION_FAILED',
+          message: `tokenMovements[${i}].amount must be a positive decimal integer string, got: ${m.amount}`,
+          severity: 'error',
+          retryable: false,
+        },
+      }
+    }
+  }
+
   // 1. parseConfidence gate.
   const threshold = opts.confidenceOverride?.threshold ?? tx.parseConfidence.thresholdUsed
   if (tx.parseConfidence.overall < threshold) {
@@ -154,9 +225,6 @@ export function synthesizeFromRecording(
   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 covered flow;
-    // surface SYNTHESIS_ERROR so the orchestrator never silently emits an
-    // over-broad default-scoped policy.
     return {
       ok: false,
       error: {
@@ -196,17 +264,6 @@ export function synthesizeFromRecording(
 
   // 6. Interpreter compile (opt-in; fail-closed when the user routed real
   //    restrictions to the interpreter).
-  //
-  //    When the caller opts in, the interpreter always runs - even for a
-  //    scope-only interpreter IR (no routed constraints) - because the
-  //    interpreter adapter lowers `scope.contract` + `scope.method` into a
-  //    `call_contract == ...` and `call_fn == ...` predicate sibling pair.
-  //    This is the real per-method enforcement the OZ adapter cannot do.
-  //
-  //    When the caller does NOT opt in: today's behaviour is preserved. The
-  //    compose step routes every constraint to the OZ IR; OZ flags the ones
-  //    it cannot lower as `uncovered` and the orchestrator surfaces them as
-  //    warnings. No interpreter doc is produced.
   const interpreterOpts = opts.interpreter
 
   let interpreterPolicyDocument: ProposedPolicy['policyDocuments'][number] | null = null
@@ -220,18 +277,6 @@ export function synthesizeFromRecording(
       ...(interpreterOpts.oracleParams ? { oracleParams: interpreterOpts.oracleParams } : {}),
     }
 
-    // The starting PredicateNode the self-verify + minimise pipeline drives.
-    // Two paths populate it:
-    //   - Test seam (`__testPredicateNode` set): use it directly, skipping the
-    //     adapter's compile(). Production code MUST NOT set the seam; it
-    //     exists so the pipeline can be exercised on hand-crafted predicates
-    //     (redundant conjuncts for minimise, deliberately over-broad leaves
-    //     for DENY_CASE_FAILURE).
-    //   - Normal: call the interpreter adapter's compile() so the existing
-    //     enforcement gates (SCOPE_SELF_CALL / ORACLE_LEAF_INVALID_POSITION /
-    //     ORACLE_PARAMS_OUT_OF_RANGE + uncovered reporting) fire first, then
-    //     re-derive the pre-encoding PredicateNode via `lowerRuleToPredicate`
-    //     so minimise + harness see the same shape the encoder will see.
     let startingPredicate: PredicateNode | null = null
     const testSeam = interpreterOpts.__testPredicateNode
     if (testSeam !== undefined) {
@@ -243,11 +288,6 @@ export function synthesizeFromRecording(
       try {
         interpreterRes = interpreterAdapter.compile(composed.interpreterIr)
       } catch (e) {
-        // Interpreter enforcement-gate throws (SCOPE_SELF_CALL,
-        // ORACLE_LEAF_INVALID_POSITION, ORACLE_PARAMS_OUT_OF_RANGE). Surface
-        // the gate code so the caller can act; never install an OZ-only
-        // partial policy - the user explicitly asked for these constraints
-        // to be enforced and silently dropping them yields an over-broad rule.
         const code = (e as { code?: ToolError['code'] }).code
         const allowedCodes: ToolError['code'][] = [
           'SCOPE_SELF_CALL',
@@ -338,15 +378,8 @@ export function synthesizeFromRecording(
       }
     }
 
-    // 6b. Self-verify + minimise. We always build the same permit EvalContext
-    //     from the recorded tx + synthesised constraints so the harness
-    //     reasons about the intended call (the only one the user actually
-    //     recorded). The recorded call MUST permit under the predicate; the
-    //     generated deny battery MUST all deny.
+    // 6b. Self-verify + minimise.
     if (!topLevel) {
-      // The orchestrator guarantees this for the call_contract branch above;
-      // a default-scoped policy never reaches the interpreter block. Fail
-      // closed rather than attempt to self-verify a vague shape.
       return {
         ok: false,
         error: {
@@ -370,10 +403,6 @@ export function synthesizeFromRecording(
     }
     const permitCtx = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate)
 
-    // Top-level `and` predicates are what generateCases + minimize assume;
-    // for any other shape we skip minimise (encode as-is) but still assert
-    // the permit case permits. An over-broad non-and predicate is still
-    // caught by the harness on the next step.
     const finalPredicate: PredicateNode =
       startingPredicate.op === 'and' ? minimize(startingPredicate, permitCtx) : startingPredicate
 
@@ -407,15 +436,13 @@ export function synthesizeFromRecording(
     }
 
     // 6c. Re-encode the (possibly minimised) PredicateNode and stamp the
-    //     canonical bytes back onto the PolicyDocument + PolicyRef. minimize
-    //     and encodePredicate are pure and deterministic, so the re-encoded
-    //     doc is byte-identical to what compile() would have produced for
-    //     the minimised tree.
+    //     canonical bytes back onto the PolicyDocument + PolicyRef. The
+    //     `encodePredicate` helper throws ToolError-shaped errors on cap
+    //     breaches (PREDICATE_TOO_DEEP, TOO_MANY_LEAVES, etc.) - the outer
+    //     envelope converts them to a structured `{ok:false, error}`.
     const { encodedPredicate, predicateHash } = encodePredicate(finalPredicate)
 
     if (testSeam !== undefined) {
-      // Test seam: build the PolicyDocument + PolicyRef now (compile() was
-      // skipped). Shape mirrors the adapter's output exactly.
       interpreterPolicyDocument = {
         grammarVersion: 1,
         installNonce: interpreterOpts.installNonce ?? 1,
@@ -455,17 +482,14 @@ export function synthesizeFromRecording(
   }
 
   // When the interpreter succeeds, OZ-side `uncovered` warnings that the
-  // interpreter actually lowered (per-method scoping, recipient allowlists,
-  // eq_seq paths, oracle_price / invocation_count / token-mismatch
-  // window_spent) are misleading: OZ really did not lower them, but the
-  // interpreter did. Drop those so the user-facing warnings reflect what is
-  // still UN-enforced, not what OZ alone could not do.
+  // interpreter actually lowered are misleading: OZ really did not lower them,
+  // but the interpreter did. Drop those so the user-facing warnings reflect
+  // what is still UN-enforced, not what OZ alone could not do.
   const ozUncovered = interpreterPolicyRef
     ? compileRes.uncovered.filter((u) => !INTERPRETER_COVERED_OZ_PATTERN.test(u))
     : compileRes.uncovered
 
-  // 7. Merge into the OZ-shaped ProposedPolicy. Order:
-  //    [interpreterRef?, ...oz_builtinRefs]; cap = OZ_LIMITS.maxPoliciesPerRule.
+  // 7. Merge into the OZ-shaped ProposedPolicy.
   const ozRefs = compileRes.proposed.policyRefs
   const mergedRefs: ProposedPolicy['policyRefs'] = []
   if (interpreterPolicyRef) mergedRefs.push(interpreterPolicyRef)
@@ -502,6 +526,10 @@ export function synthesizeFromRecording(
   return { ok: true, data: proposed }
 }
 
+// Re-export the throwToolError helper for callers that need to surface a
+// ToolError-shaped throw inside the body (e.g. tests).
+export { throwToolError }
+
 /** OZ-side `uncovered` warning patterns that the interpreter adapter
  *  actually lowers when wired in. When the interpreter adapter succeeds, we
  *  drop matching entries from the OZ uncovered list so the user-facing
@@ -562,14 +590,31 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
         `interpreter.smartAccountAddress must be a non-empty string, got: ${String(sa)}`
       )
     }
+    // Blocklist placeholder / stub prefixes (item 5). Runs BEFORE the
+    // C.../56-char shape check so a fixture/LLM-seam marker is reported
+    // with the specific placeholder error (not a generic "must be a
+    // C... contract" message). A real install routes a C... contract
+    // address derivable from the on-chain account; any
+    // 'VERIFY-*' / 'PLACEHOLDER-*' / 'TODO-*' prefix is an LLM seam /
+    // fixture marker that must never reach the install payload.
+    if (PLACEHOLDER_SMART_ACCOUNT_PREFIX.test(sa)) {
+      return synthesisError(
+        `interpreter.smartAccountAddress must not be a placeholder/stub address (matches /${PLACEHOLDER_SMART_ACCOUNT_PREFIX.source}/), got: ${sa}`
+      )
+    }
     if (!isContractAddress(sa)) {
       return synthesisError(
         `interpreter.smartAccountAddress must be a C... Stellar contract address (the on-chain policy-bound account, not the G... source account), got: ${sa}`
       )
     }
     const nonce = opts.interpreter.installNonce
-    if (nonce !== undefined && !isPositiveInt(nonce)) {
-      return synthesisError(`interpreter.installNonce must be a positive integer, got: ${nonce}`)
+    // Item 4: installNonce must fit u32 (the on-chain per-rule nonce is a
+    // u32; values above SOROBAN_LIMITS.u32Max cannot be installed). Mirrors
+    // the validUntilLedger SOROBAN_LIMITS.u32Max check above.
+    if (nonce !== undefined && (!isPositiveInt(nonce) || nonce > SOROBAN_LIMITS.u32Max)) {
+      return synthesisError(
+        `interpreter.installNonce must be a positive u32 integer (<= ${SOROBAN_LIMITS.u32Max}), got: ${nonce}`
+      )
     }
     const op = opts.interpreter.oracleParams
     if (op) {
@@ -596,6 +641,13 @@ function validateOptions(opts: SynthesizeFromRecordingOptions): ToolError | null
   return null
 }
 
+/** Placeholder/stub smart-account prefixes (item 5). Mirrors the
+ *  `PLACEHOLDER_INTERPRETER_ADDRESS` marker the interpreter adapter uses for
+ *  the interpreter-contract strkey; a real install must point at a C...
+ *  contract address derivable from the on-chain account, never a
+ *  fixture/LLM-seam marker. */
+const PLACEHOLDER_SMART_ACCOUNT_PREFIX = /^(VERIFY-|PLACEHOLDER-|TODO-)/i
+
 function isPositiveInt(n: number): boolean {
   return Number.isInteger(n) && n > 0
 }
@@ -689,19 +741,46 @@ function buildPermitContext(
   return ctx
 }
 
-function cloneScVal(value: { type: string; value: unknown }): ContractInvocation['args'][number] {
+function cloneScVal(
+  value: { type: string; value: unknown },
+  depth = 0
+): ContractInvocation['args'][number] {
   // EvalContext.args is an ScVal[]; the recorded args are already ScVal-shaped
   // (decoded by the recorder). We clone top-level shells so the harness can
-  // mutate deny cases without aliasing the recorded call.
+  // mutate deny cases without aliasing the recorded call. Recursion is
+  // bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec payload
+  // cannot RangeError the JS stack; the over-depth branch throws a
+  // ToolError-shaped error that the `synthesizeFromRecording` envelope
+  // (item 3) converts to `{ok:false, error}`.
   if (value.type === 'vec') {
+    if (depth >= MAX_SCVAL_CLONE_DEPTH) {
+      throw cloneDepthError(value)
+    }
     return {
       type: 'vec',
-      value: (value.value as ContractInvocation['args'][number][]).map(cloneScVal),
+      value: (value.value as ContractInvocation['args'][number][]).map((v) =>
+        cloneScVal(v, depth + 1)
+      ),
     }
   }
   return { ...value } as ContractInvocation['args'][number]
 }
 
+/** Throw a ToolError-shaped error when the clone exceeds MAX_SCVAL_CLONE_DEPTH.
+ *  The shape (object with string `code`) is what the `synthesizeFromRecording`
+ *  envelope detects and converts to a structured `{ok:false, error}`. */
+function cloneDepthError(value: { type: string; value: unknown }): 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
+  // Tag the offending value so failures are diagnosable.
+  err.depthContext = value.type
+  throw err
+}
+
 /** Walk every `oracle_price` leaf in the predicate and return a price map
  *  whose entries satisfy the bound so the intended call permits. The
  *  timestamp is pinned to `nowSeconds` (the recorded `fetchedAt`) so the

package/src/types.ts

@@ -33,6 +33,25 @@ export const SOROBAN_LIMITS = {
   secondsPerLedger: 5,
 } as const
 
+/** Maximum recursion depth for decoding Recursive `ScVal` shapes (vec-in-vec).
+ *  A real Stellar tx caps nesting well below this; the bound hard-caps a
+ *  hand-crafted payload so the recorder fails CLOSED (records the over-depth
+ *  branch as opaque `depth-exceeded`) rather than RangeErroring the JS stack.
+ *  Mirrors the `MAX_AUTH_TREE_DEPTH = 16` boundary the auth-tree decoder
+ *  already enforces; lifted to 30 so legitimate nested args (a path vec
+ *  inside an order vec inside a market-data vec) decode cleanly while a
+ *  malformed ~10000-deep payload still trips the cap. */
+export const MAX_SCVAL_DEPTH = 30 as const
+
+/** Maximum recursion depth for cloning nested `ScVal` shapes (vec-in-vec) into
+ *  the simulator / verify / harness contexts. Mirrors `MAX_SCVAL_DEPTH` above
+ *  so a hand-crafted nested-vec payload cannot RangeError the JS stack during
+ *  context building. Over-depth throws a ToolError (caught by the
+ *  `synthesizeFromRecording` envelope + the simulator/verify boundaries) so
+ *  the caller gets a structured `{ok:false, error}` instead of a thrown
+ *  RangeError. */
+export const MAX_SCVAL_CLONE_DEPTH = 30 as const
+
 /** Predicate-document caps - enforced fail-closed at install by BOTH the synth (TS)
  *  AND the interpreter (Rust). Single source: a CI test asserts the two cap sets are
  *  byte-identical (TS reads the same JSON manifest the Rust build emits). If they

package/src/verify/simulate.ts

@@ -37,6 +37,7 @@ import type {
   RecordedTransaction,
   ScVal,
 } from '../types.ts'
+import { MAX_SCVAL_CLONE_DEPTH } from '../types.ts'
 import type { SimulationResult } from './envelope.ts'
 
 const SIMULATOR_VERSION = 'ts-model-1.0.0'
@@ -227,13 +228,31 @@ function buildPermitContext(
   return ctx
 }
 
-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 context building. Over-depth
+  // throws a ToolError-shaped error that the simulator's existing try/catch
+  // converts to a structured `{ok:false, error}` (not a thrown RangeError).
   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 = 'SIMULATION_ERROR'
+  err.severity = 'error'
+  err.retryable = false
+  err.depthContext = value.type
+  throw err
+}
+
 function visitOracleLeaves(
   node: PredicateNode,
   visit: (asset: string, op: 'eq' | 'lt' | 'lte' | 'gt' | 'gte', bound: bigint) => void

package/src/verify/verify.ts

@@ -32,6 +32,7 @@ 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'
+import { MAX_SCVAL_CLONE_DEPTH } from '../types.ts'
 
 /** Options for `verifyPolicy`. Mirrors the orchestrator's permit-context
  *  knobs (expiry; oracle fixture) so verify sees the same shape
@@ -171,13 +172,31 @@ function buildPermitContextForVerify(
   return ctx
 }
 
-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 context building. Over-depth
+  // throws a ToolError-shaped error that the verifier's existing try/catch
+  // converts to a structured `{ok:false, error}` (not a thrown RangeError).
   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 = 'VERIFICATION_FAILED'
+  err.severity = 'error'
+  err.retryable = false
+  err.depthContext = value.type
+  throw err
+}
+
 function fingerprint(node: PredicateNode): string {
   return JSON.stringify(node, replacer)
 }