@crediolabs/policy-synth 0.1.2 → 0.1.4

package/src/adapters/oz/adapter.ts

@@ -1,7 +1,7 @@
-// src/adapters/oz/adapter.ts - the OZ Accounts CustodyAdapter (Path-A lowering).
+// src/adapters/oz/adapter.ts - the OZ Accounts CustodyAdapter.
 //
 // Compiles a PolicyIR to an OZ `ProposedPolicy` using OZ built-in policy
-// primitives (Path A). Only the constructs OZ can express natively are lowered:
+// primitives. Only the constructs OZ can express natively are lowered:
 //   scope.contract            -> ContextRuleType.call_contract (else default)
 //   expiry.validUntilLedger   -> ContextRuleDraft.validUntilLedger
 //   window_spent(t,w) <= L    -> `spending_limit` primitive
@@ -9,7 +9,7 @@
 // Anything needing a capability this backend lacks (oracle price, invocation
 // count, per-arg comparison/allowlist, guard, nested boolean predicate) is NOT
 // emitted: it is named in `uncovered` and `covered` is set false. Nothing is
-// silently dropped - the uncovered constructs are the Path-B markers.
+// silently dropped - the uncovered constructs are named instead.
 //
 // OZ built-in policy instance addresses are per-network deploy artifacts we do
 // not have yet (install is a later phase). They are injected via config; week-1
@@ -132,8 +132,8 @@ function lowerRule(rule: IRPolicyRule, config: OzAdapterConfig): LoweredRule {
   const policyRefs: PolicyRef[] = []
 
   // scope -> context rule type. OZ scopes by contract (CallContract); a finer
-  // method-level restriction is a predicate concern and must be flagged Path-B
-  // because CallContract alone permits other methods on the same contract
+  // method-level restriction is a predicate concern and must be flagged as not
+  // covered because CallContract alone permits other methods on the same contract
   // (e.g. an unbounded approve alongside a capped transfer).
   const contextRuleType: ContextRuleDraft['contextRuleType'] =
     rule.scope.contract !== undefined
@@ -171,12 +171,12 @@ function lowerRule(rule: IRPolicyRule, config: OzAdapterConfig): LoweredRule {
     }
   }
 
-  // guard -> Path B (applicability predicates are not an OZ built-in).
+  // guard -> not covered (applicability predicates are not an OZ built-in).
   if (rule.guard) {
     uncovered.push(`guard: ${describeCondition(rule.guard)}`)
   }
 
-  // constraints -> spending_limit where they match; else Path B. The OZ
+  // constraints -> spending_limit where they match; else not covered. The OZ
   // spending_limit policy takes `{ spending_limit: i128, period_ledgers: u32 }`
   // and has NO token param: it only accepts a CallContract context rule
   // (OnlyCallContractAllowed) and limits transfers of that context's contract,
@@ -209,7 +209,7 @@ function lowerRule(rule: IRPolicyRule, config: OzAdapterConfig): LoweredRule {
 
   // approval.threshold -> simple/weighted threshold primitive. A threshold < 1
   // is not a real M-of-N gate (0 approvals authorises everything), so refuse to
-  // emit a no-op primitive and flag it Path-B instead.
+  // emit a no-op primitive and flag it as not covered instead.
   if (rule.approval) {
     if (!Number.isInteger(rule.approval.threshold) || rule.approval.threshold < 1) {
       uncovered.push(
@@ -281,17 +281,19 @@ function matchSpendingLimit(c: IRCondition): SpendingLimitMatch | null {
   return { token: selector.token, limit: value, windowSeconds: selector.windowSeconds }
 }
 
-/** Human-readable descriptor for a construct the OZ Path-A backend cannot
- *  express, used to populate `uncovered` (the Path-B markers). */
+/** Human-readable descriptor for a construct the OZ built-in-primitive backend
+ *  cannot express, used to populate `uncovered`. */
 function describeCondition(cond: IRCondition): string {
   switch (cond.op) {
     case 'in':
-      return `value allowlist on ${describeSelector(cond.selector)} (arg allowlist, Path B)`
+      return `value allowlist on ${describeSelector(cond.selector)} (arg allowlist)`
+    case 'eq_seq':
+      return `exact ordered sequence on ${describeSelector(cond.selector)} (OZ built-ins cannot express an exact vector)`
     case 'not':
-      return 'negated condition (predicate DSL, Path B)'
+      return 'negated condition (predicate DSL)'
     case 'and':
     case 'or':
-      return `nested ${cond.op} condition (predicate DSL, Path B)`
+      return `nested ${cond.op} condition (predicate DSL)`
     case 'compare': {
       const s = cond.compare.selector
       switch (s.kind) {
@@ -302,16 +304,16 @@ function describeCondition(cond: IRCondition): string {
         case 'window_spent':
           return `spend-window comparison with operator '${cond.compare.operator}' (only 'lte' lowers to spending_limit)`
         case 'amount':
-          return `per-call amount comparison on ${s.token} (predicate DSL, Path B)`
+          return `per-call amount comparison on ${s.token} (predicate DSL)`
         case 'arg':
-          return `argument comparison on arg ${s.argIndex} (predicate DSL, Path B)`
+          return `argument comparison on arg ${s.argIndex} (predicate DSL)`
         case 'calldata':
-          return 'EVM calldata comparison (predicate DSL, Path B)'
+          return 'EVM calldata comparison (predicate DSL)'
         case 'value':
-          return 'tx.value comparison (predicate DSL, Path B)'
+          return 'tx.value comparison (predicate DSL)'
         case 'now':
         case 'valid_until':
-          return 'time comparison (predicate DSL, Path B)'
+          return 'time comparison (predicate DSL)'
       }
     }
   }

package/src/codegen/compile-gate.ts

@@ -0,0 +1,162 @@
+// src/codegen/compile-gate.ts - toolchain-gated `cargo check` for the
+// codegen escape hatch.
+//
+// The escape hatch ships as the `policy-builder escape-hatch` CLI subcommand
+// (a later phase). This gate is its safety net, NOT the happy path. Property:
+// generated Rust compiles against the pinned OZ crate; broken source returns
+// `COMPILE_GATE_FAILED` with `stderr`; an absent toolchain returns `SKIPPED`
+// (does NOT fail - we cannot make build tools a hard runtime requirement for
+// a TypeScript package).
+
+import { spawn } from 'node:child_process'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export type CompileGateResult =
+  | { code: 'COMPILE_OK' }
+  | { code: 'COMPILE_GATE_FAILED'; stderr: string }
+  | { code: 'SKIPPED'; reason: string }
+
+export interface CompileGateOpts {
+  /** Caller-controlled abort signal; aborting before toolchain probe resolves
+   *  the gate to `SKIPPED` rather than starting a cargo invocation. */
+  signal?: AbortSignal
+  /** Override the `cargo` binary (mostly for tests). */
+  cargoBin?: string
+  /** Override the target directory (mostly for tests). */
+  tempDir?: string
+}
+
+interface ToolchainProbe {
+  present: boolean
+  reason: string
+}
+
+/** Probe the host for the Rust toolchain the gate requires. We require BOTH
+ *  `cargo` AND `stellar` (the Soroban CLI) because a real gate run invokes
+ *  `stellar contract build`; absent either, the gate returns `SKIPPED`. */
+export async function hasRustToolchain(): Promise<boolean> {
+  const probe = await probeToolchain()
+  return probe.present
+}
+
+async function probeToolchain(): Promise<ToolchainProbe> {
+  const cargo = await which('cargo')
+  if (!cargo) return { present: false, reason: 'cargo not found on PATH' }
+  const stellar = await which('stellar')
+  if (!stellar) return { present: false, reason: 'stellar not found on PATH' }
+  return { present: true, reason: `${cargo} + ${stellar}` }
+}
+
+async function which(bin: string): Promise<string | null> {
+  try {
+    const out = await runProcess('sh', ['-c', `command -v ${bin}`], { capture: true })
+    const path = out.stdout.trim()
+    return path.length > 0 ? path : null
+  } catch {
+    return null
+  }
+}
+
+interface RunOpts {
+  capture?: boolean
+  signal?: AbortSignal
+}
+
+function runProcess(
+  cmd: string,
+  args: string[],
+  opts: RunOpts
+): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((resolve, reject) => {
+    if (opts.signal?.aborted) {
+      reject(new Error('aborted'))
+      return
+    }
+    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.on('data', (b: Buffer) => {
+      stdout += b.toString('utf8')
+    })
+    child.stderr.on('data', (b: Buffer) => {
+      stderr += b.toString('utf8')
+    })
+    const onAbort = () => {
+      child.kill('SIGTERM')
+      reject(new Error('aborted'))
+    }
+    opts.signal?.addEventListener('abort', onAbort, { once: true })
+    child.on('error', (e) => {
+      opts.signal?.removeEventListener('abort', onAbort)
+      reject(e)
+    })
+    child.on('close', (code) => {
+      opts.signal?.removeEventListener('abort', onAbort)
+      resolve({ stdout, stderr, code: code ?? -1 })
+    })
+  })
+}
+
+const CARGO_MANIFEST = `[package]
+name = "escape-hatch-gate"
+version = "0.0.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+soroban-sdk = "22"
+
+[workspace]
+`
+
+/** Compile-check a Rust source string against the pinned Soroban SDK.
+ *
+ *  - Toolchain absent -> `{ code: 'SKIPPED', reason }` (NOT a failure).
+ *  - Toolchain present, source compiles -> `{ code: 'COMPILE_OK' }`.
+ *  - Toolchain present, source broken -> `{ code: 'COMPILE_GATE_FAILED', stderr }`.
+ *
+ *  The gate writes the source to a temporary crate and runs `cargo check`
+ *  against it; the crate is cleaned up whether or not compilation succeeds.
+ *  The caller is expected to surface `COMPILE_GATE_FAILED.stderr` to the
+ *  user (the LLM agent) so the user can iterate. */
+export async function compileCheck(
+  rustSource: string,
+  opts: CompileGateOpts = {}
+): Promise<CompileGateResult> {
+  if (opts.signal?.aborted) {
+    return { code: 'SKIPPED', reason: 'aborted before probe' }
+  }
+
+  const probe = await probeToolchain()
+  if (!probe.present) {
+    return { code: 'SKIPPED', reason: probe.reason }
+  }
+
+  let dir: string | null = null
+  try {
+    dir = await mkdtemp(join(opts.tempDir ?? tmpdir(), 'codegen-gate-'))
+    await writeFile(join(dir, 'Cargo.toml'), CARGO_MANIFEST)
+    await writeFile(join(dir, 'lib.rs'), rustSource)
+
+    const runOpts: RunOpts = opts.signal ? { signal: opts.signal } : {}
+    const result = await runProcess(
+      opts.cargoBin ?? 'cargo',
+      ['check', '--quiet', '--offline', '--manifest-path', join(dir, 'Cargo.toml')],
+      runOpts
+    ).catch((e: Error) => ({ stdout: '', stderr: e.message, code: -1 }))
+
+    if (result.code === 0) {
+      return { code: 'COMPILE_OK' }
+    }
+    return { code: 'COMPILE_GATE_FAILED', stderr: result.stderr || result.stdout }
+  } finally {
+    if (dir) {
+      await rm(dir, { recursive: true, force: true }).catch(() => {})
+    }
+  }
+}

package/src/codegen/index.ts

@@ -0,0 +1,17 @@
+// src/codegen/index.ts - re-export the codegen escape-hatch surface.
+//
+// The escape hatch is OUT of the audited happy path: the synthesiser never
+// calls `generateRust` itself; the CLI subcommand (a later phase) is the only
+// entry point. Keeping the surface in one file makes that boundary visible
+// in import statements.
+
+export {
+  type CompileGateOpts,
+  type CompileGateResult,
+  compileCheck,
+  hasRustToolchain,
+} from './compile-gate.ts'
+export {
+  type EscapeHatchSpec,
+  generateRust,
+} from './template.ts'

package/src/codegen/template.ts

@@ -0,0 +1,148 @@
+// src/codegen/template.ts - deterministic Rust source generator for the OZ
+// `Policy` escape-hatch skeleton.
+//
+// This is the LAST-RESORT tool for constraints the v1 DSL cannot express. It
+// lives OUT of the audited happy-path surface; the synthesiser never emits it
+// automatically. It mirrors Zodiac Roles' `Custom` operator: a hand-written
+// (here: scaffolded) policy the operator assumes responsibility for.
+//
+// The skeleton carries five storage invariants the user MUST preserve when
+// filling in the predicate logic:
+//   1. `smart_account.require_auth()` is invoked INSIDE `enforce`.
+//   2. Storage is keyed by the composite `(smart_account, rule_id)`.
+//   3. Chain reads use `unwrap_or_default()` so a missing key is a permitted
+//      default, not a panic.
+//   4. Storage is `persistent()` (NOT `instance()`) so the policy survives
+//      contract instance lifecycle changes.
+//   5. `uninstall` removes the stored state.
+//
+// Determinism: same `(spec, name)` -> byte-identical output. No clock, no RNG,
+// no environment reads.
+
+/** A small typed description of one uncovered constraint the v1 DSL refused
+ *  to express. The synthesiser surfaces these from `CompileResult.uncovered`
+ *  and the codegen escape hatch wraps them into a hand-auditable skeleton. */
+export interface EscapeHatchSpec {
+  /** Address of the policy contract the skeleton is generated for. */
+  contract: string
+  /** The trait method the predicate lives inside (default: 'enforce'). */
+  fnName?: string
+  /** Human-readable description of each construct the DSL could not cover. */
+  uncovered: string[]
+}
+
+/** Format a name for use as a Rust identifier. The input is constrained by
+ *  the caller (a kebab-case policy name + alphanumeric addresses); this is a
+ *  belt-and-braces sanitiser that maps anything non-identifier to '_'. */
+function asRustIdent(s: string): string {
+  let out = ''
+  for (let i = 0; i < s.length; i++) {
+    const ch = s.charCodeAt(i)
+    const ok =
+      (ch >= 48 && ch <= 57) || // 0-9
+      (ch >= 65 && ch <= 90) || // A-Z
+      (ch >= 97 && ch <= 122) || // a-z
+      ch === 95 // _
+    out += ok ? s[i] : '_'
+  }
+  // Identifiers may not start with a digit.
+  if (out.length > 0 && out.charCodeAt(0) >= 48 && out.charCodeAt(0) <= 57) {
+    out = `_${out}`
+  }
+  return out || 'policy'
+}
+
+/** Render the `uncovered` list as a `//` comment block (one line per item). */
+function renderUncovered(uncovered: string[]): string {
+  if (uncovered.length === 0) {
+    return '    // (no specific uncovered constructs reported)'
+  }
+  return uncovered.map((line) => `    // - ${line}`).join('\n')
+}
+
+/** Generate a deterministic OZ `Policy` skeleton for an uncovered constraint.
+ *
+ *  The skeleton is NOT a finished policy; the user fills in the predicate
+ *  logic in the marked TODO(user) holes and audits the result themselves.
+ *
+ *  Same `(spec, name)` always produces byte-identical output. */
+export function generateRust(spec: EscapeHatchSpec, name: string): string {
+  const contract = spec.contract
+  const fnName = spec.fnName ?? 'enforce'
+  const structName = asRustIdent(name)
+  const dataKeyName = `${asRustIdent(name)}_data`
+  const uncoveredBlock = renderUncovered(spec.uncovered)
+
+  return `// Auto-generated by the OZ Policy Builder codegen escape hatch.
+// THIS OUTPUT IS THE USER'S TO COMPLETE AND AUDIT.
+// The synthesiser never emits it on the happy path; reach for it only when
+// a constraint cannot be expressed in the v1 DSL grammar (same shape as
+// Zodiac Roles' \`Custom\` operator).
+
+#![no_std]
+
+use soroban_sdk::{contract, contractimpl, contracttype, Address, Env, Vec};
+
+#[contracttype]
+pub enum DataKey {
+    /// Composite key \`(smart_account, rule_id)\` so multiple policies on
+    /// one smart account coexist without collision.
+    State(Address, u32),
+}
+
+#[contract]
+pub struct ${structName};
+
+#[contractimpl]
+impl ${structName} {
+    pub fn install(e: &Env, smart_account: Address, rule_id: u32) {
+        // TODO(user): initialise policy state for this (smart_account, rule_id).
+        // The skeleton leaves the stored value empty; the predicate body
+        // (in \`enforce\`) decides what to read.
+        e.storage().persistent().set(
+            &DataKey::State(smart_account.clone(), rule_id),
+            &(),
+        );
+    }
+
+    pub fn enforce(
+        e: &Env,
+        smart_account: Address,
+        rule_id: u32,
+        _signers: Vec<Address>,
+    ) {
+        // Invariant 1: authorise the smart account BEFORE any state read or
+        // predicate evaluation. Removing this call opens the policy to
+        // impersonation by any caller with a valid rule_id.
+        smart_account.require_auth();
+
+        // Invariant 2 + 4: read stored state through the composite key on
+        // \`persistent()\` storage. \`unwrap_or_default()\` (invariant 3)
+        // makes an empty key a permitted default rather than a panic.
+        let _state: () = e
+            .storage()
+            .persistent()
+            .get(&DataKey::State(smart_account.clone(), rule_id))
+            .unwrap_or_default();
+
+        // --- uncovered constraints the v1 DSL refused to express ---
+${uncoveredBlock}
+
+        // TODO(user): replace the placeholder below with the real predicate
+        // body. The recorded flow's \`(contract, fn_name, args)\` is the
+        // single authorised call \`Policy::enforce\` receives; match against
+        // \`e\` here.
+        let _ = (_state, &e);
+    }
+
+    pub fn uninstall(e: &Env, smart_account: Address, rule_id: u32) {
+        // Invariant 5: \`uninstall\` removes the stored state so a subsequent
+        // install starts from a clean slate (and the nonce returns to its
+        // post-uninstall value).
+        e.storage()
+            .persistent()
+            .remove(&DataKey::State(smart_account, rule_id));
+    }
+}
+`
+}

package/src/errors.ts

@@ -26,6 +26,8 @@ export type ErrorCode =
   // --- predicate caps (fail-closed at install) ---
   | 'PREDICATE_TOO_LARGE'
   | 'PREDICATE_TOO_DEEP'
+  | 'TOO_MANY_LEAVES'
+  | 'IN_OPERAND_LIMIT'
   | 'PREDICATE_ORACLE_OVER_LIMIT'
   | 'POLICY_CAP_EXCEEDED'
   | 'WASM_TOO_LARGE'

package/src/index.ts

@@ -2,8 +2,10 @@ export * from './adapters/oz/index.ts'
 export * from './errors.ts'
 export * from './ir/index.ts'
 export * from './mandate/index.ts'
+export * from './predicate/index.ts'
 export * from './record/index.ts'
 export * from './registry/index.ts'
+export * from './review-card/index.ts'
 export * from './seams/index.ts'
 export * from './synth/index.ts'
 export * from './types.ts'

package/src/ir/types.ts

@@ -60,13 +60,20 @@ export interface IRCompare {
 }
 
 /** Condition tree. NEAR-V2 guard/constraint are flat And/Or; the IR allows
- *  nesting + `not` + `in` so the same IR can later lower to the OZ predicate
- *  DSL. Week-1 adapters only lower the flat supported subset and flag the rest. */
+ *  nesting + `not` + `in` + `eq_seq` so the same IR can later lower to the OZ
+ *  predicate DSL. Week-1 adapters only lower the flat supported subset and flag
+ *  the rest. */
 export type IRCondition =
   | { op: 'and' | 'or'; children: IRCondition[] }
   | { op: 'not'; child: IRCondition }
   | { op: 'compare'; compare: IRCompare }
   | { op: 'in'; selector: IRSelector; values: string[] }
+  /** Exact ordered sequence equality. The IR-level selector value MUST EQUAL
+   *  `values` as an ORDERED sequence (e.g. a swap hop `path`). `in` is pure
+   *  set membership and cannot express order; `eq_seq` is the construct that
+   *  does. Adapters that cannot express an exact ordered vector (OZ built-ins)
+   *  flag this as `uncovered` rather than silently dropping it. */
+  | { op: 'eq_seq'; selector: IRSelector; values: string[] }
 
 export interface IRPolicyRule {
   /** NEAR-V2 roles whitelist (empty = any; owner exempt). */

package/src/mandate/to-ir.ts

@@ -6,8 +6,8 @@
 //   contract/method  -> rule.scope
 //   spendingLimit    -> a `window_spent(token,window) <= limit` compare
 //   approvalThreshold-> rule.approval.threshold
-//   recipients       -> an `in` condition on the recipient arg (Path-B flagged
-//                       by the OZ adapter; that is expected)
+//   recipients       -> an `in` condition on the recipient arg (flagged as not
+//                       covered by the OZ adapter; that is expected)
 //   expiry           -> rule.expiry
 // The top-level default is `deny_all` (OZ context rules are deny-by-default).
 
@@ -16,8 +16,8 @@ import type { MandateSpec } from './types.ts'
 
 /** Arg index the recipient allowlist constrains. Pinned to the SEP-41
  *  `transfer(from, to, amount)` convention where `to` is arg 1. This condition
- *  is flagged Path-B by the OZ adapter (no built-in primitive expresses an arg
- *  allowlist), so the index only needs to be deterministic in week-1. */
+ *  is flagged as not covered by the OZ adapter (no built-in primitive expresses
+ *  an arg allowlist), so the index only needs to be deterministic in week-1. */
 const RECIPIENT_ARG_INDEX = 1
 
 export function mandateToPolicyIR(spec: MandateSpec): PolicyIR {

package/src/mandate/types.ts

@@ -14,7 +14,7 @@ export interface MandateSpec {
   spendingLimit?: { token: string; limit: string; windowSeconds: number }
   /** -> OZ `simple_threshold` / `weighted_threshold` primitive. */
   approvalThreshold?: number
-  /** Recipient allowlist -> an `in` arg condition (flagged Path-B in week-1). */
+  /** Recipient allowlist -> an `in` arg condition (not covered by an OZ built-in). */
   recipients?: string[]
   /** -> OZ context-rule expiry. */
   expiry?: { validUntilLedger?: number; validUntilUnixSeconds?: number }