@crediolabs/policy-synth 0.1.18 → 0.3.0

package/src/codegen/template.ts

@@ -1,165 +0,0 @@
-// src/codegen/template.ts - deterministic Rust source generator for the OZ
-// `Policy` escape-hatch skeleton.
-//
-// SUPERSEDED. The architecture this belongs to no longer exists. A deployed
-// policy involves exactly two contracts, the OZ smart account and one
-// immutable interpreter, and the synthesiser emits policy DATA rather than
-// code. Nothing on the synthesis path reaches this module, and no install can
-// produce a contract from it. When a constraint falls outside the grammar the
-// answer is to version the synthesiser and the interpreter together, not to
-// put unaudited Rust on chain per policy.
-//
-// Deleting it is a decision nobody has taken yet, not a dependency question.
-// `compile-gate.ts` takes a Rust string and knows nothing about this module,
-// and its tests compile a hardcoded fixture, so the gate keeps working either
-// way. What deleting this would remove is the only in-repo producer of policy
-// Rust for the gate to check. Do not read its presence as the product
-// generating contracts, and do not wire it into the synthesis path.
-//
-// What follows describes the abandoned design.
-//
-// 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/ir/index.ts

@@ -1,13 +0,0 @@
-// src/ir/index.ts - re-export the PolicyIR ("Policy Tree") types.
-
-export type {
-  IRCompare,
-  IRCompOp,
-  IRCondition,
-  IRLogic,
-  IRPolicyRule,
-  IRScalarType,
-  IRSelector,
-  IRVecMode,
-  PolicyIR,
-} from './types.ts'

package/src/ir/types.ts

@@ -1,132 +0,0 @@
-// src/ir/types.ts - the PolicyIR ("Policy Tree").
-//
-// `PolicyIR` is the custody-agnostic "Policy Tree" hub (the diagram's Policy
-// Tree) that every CustodyAdapter compiles FROM. It generalizes the NEAR-V2
-// policy schema (roles / scope filter / guard / constraint / comparison leaves /
-// default behaviour) into one chain-neutral shape and extends it with the
-// OZ-only selectors (spend window, oracle price, invocation count, time) so a
-// single IR can serve every backend. NEAR-V2 has no stateful spend window,
-// oracle, time/expiry, or invocation-count; those are marked as OZ extensions
-// below and are only lowered by adapters that declare support for them.
-
-/** Comparison operator. Mirrors NEAR-V2 `CompOp`. */
-export type IRCompOp = 'eq' | 'lt' | 'lte' | 'gt' | 'gte'
-
-/** Boolean combinator. Mirrors NEAR-V2 `LogicOp`. */
-export type IRLogic = 'and' | 'or'
-
-/** Vector match mode for a repeated arg. Mirrors NEAR-V2 `VecMode`. */
-export type IRVecMode = 'all' | 'any'
-
-/** Scalar value type. Mirrors NEAR-V2 `ScValType`, superset for OZ. */
-export type IRScalarType =
-  | 'address'
-  | 'i128'
-  | 'u128'
-  | 'u32'
-  | 'u64'
-  | 'i64'
-  | 'symbol'
-  | 'bytes'
-  | 'bool'
-
-/** WHERE in the authorized call a value is read. NEAR-V2 selectors first, OZ
- *  extensions after (an adapter that cannot express an extension flags it). */
-export type IRSelector =
-  // --- NEAR-V2 selectors ---
-  | {
-      kind: 'arg'
-      argIndex: number
-      fieldIndex?: number
-      vecMode?: IRVecMode
-      scalarType: IRScalarType
-    } // Stellar StellarComp
-  | { kind: 'arg_len'; argIndex: number } // length of a vec-typed argument as u32
-  | {
-      kind: 'arg_field'
-      argIndex: number
-      element: number
-      field: string
-      scalarType: IRScalarType
-    } // field of a map element within a vec-typed argument
-  | { kind: 'calldata'; offset: number; length: number } // EVM ByteComp
-  | { kind: 'value' } // EVM tx.value
-  // --- OZ extensions (not in NEAR-V2; lowered only by adapters that support them) ---
-  | { kind: 'amount'; token: string } // token amount this call moves
-  | { kind: 'window_spent'; token: string; windowSeconds: number } // stateful cumulative spend
-  | { kind: 'invocation_count'; windowSeconds: number }
-  | { kind: 'now' }
-  | { kind: 'valid_until' }
-  | { kind: 'oracle_price'; asset: string }
-
-/** A single comparison leaf. `value` is a decimal/hex string (i128-safe;
- *  never a JS number). */
-export interface IRCompare {
-  selector: IRSelector
-  operator: IRCompOp
-  value: string
-  /** Decimal basis of `value`, for selectors whose comparand is not on a basis
-   *  the contract can infer. Set for `oracle_price`, where prices normalise to
-   *  9 dp and an undeclared basis fails OPEN. */
-  valueDecimals?: number
-}
-
-/** Condition tree. NEAR-V2 guard/constraint are flat And/Or; the IR allows
- *  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[] }
-  /** A swap's output floor, expressed against its own input: the output arg
-   *  must be at least `inArgIndex * num / den`.
-   *
-   *  It is its own construct because `compare` bounds a selector against a
-   *  CONSTANT, and a slippage floor has no constant to bound against - the
-   *  acceptable output depends on the input of the same call. Encoding the
-   *  recorded output as a constant would pin a policy to one trade size.
-   *
-   *  `num/den` is the caller's minimum acceptable output per unit of input.
-   *  It is never derived from the recording: the recorded rate is a price at
-   *  one moment, and freezing it as policy would deny normal trades later.
-   *  Adapters that cannot express it (the OZ built-ins) flag it `uncovered`. */
-  | {
-      op: 'slippage_floor'
-      outArgIndex: number
-      inArgIndex: number
-      num: string
-      den: string
-    }
-
-export interface IRPolicyRule {
-  /** NEAR-V2 roles whitelist (empty = any; owner exempt). */
-  roles: string[]
-  /** NEAR-V2 scope filter; each field optional (absent = wildcard). */
-  scope: { chainId?: number; contract?: string; method?: string }
-  /** NEAR-V2 guard (applicability; skip the rule when it fails). */
-  guard?: IRCondition
-  /** NEAR-V2 constraint (AND; reject the transaction when any fails). */
-  constraints: IRCondition[]
-  // --- OZ extensions ---
-  /** M-of-N approval (OZ threshold primitives). */
-  approval?: { kind: 'threshold'; threshold: number; weights?: Record<string, number> }
-  /** OZ context-rule expiry. */
-  expiry?: { validUntilLedger?: number; validUntilUnixSeconds?: number }
-}
-
-export interface PolicyIR {
-  /** NEAR-V2 PolicyChain. */
-  chain: 'stellar' | 'evm'
-  /** NEAR-V2 DefaultBehavior. OZ context rules are deny-by-default, so
-   *  `deny_all` is the OZ default fallback when no rule matches. */
-  defaultBehavior: 'allow_all' | 'deny_all'
-  rules: IRPolicyRule[]
-}

package/src/mandate/index.ts

@@ -1,4 +0,0 @@
-// src/mandate/index.ts - re-export the Mandate source.
-
-export { mandateToPolicyIR } from './to-ir.ts'
-export type { MandateSpec } from './types.ts'

package/src/mandate/to-ir.ts

@@ -1,71 +0,0 @@
-// src/mandate/to-ir.ts - deterministic lowering of a MandateSpec to a PolicyIR.
-//
-// `mandateToPolicyIR` is pure and total: the same spec always lowers to a
-// byte-identical PolicyIR. No decoding, no inference, no clock. Each mandate
-// field maps to exactly one IR construct:
-//   contract/method  -> rule.scope
-//   spendingLimit    -> a `window_spent(token,window) <= limit` compare
-//   approvalThreshold-> rule.approval.threshold
-//   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).
-
-import type { IRCondition, IRPolicyRule, IRSelector, PolicyIR } from '../ir/types.ts'
-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 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 {
-  const scope: IRPolicyRule['scope'] = { contract: spec.contract }
-  if (spec.method !== undefined) scope.method = spec.method
-
-  const constraints: IRCondition[] = []
-
-  if (spec.spendingLimit) {
-    constraints.push({
-      op: 'compare',
-      compare: {
-        selector: {
-          kind: 'window_spent',
-          token: spec.spendingLimit.token,
-          windowSeconds: spec.spendingLimit.windowSeconds,
-        },
-        operator: 'lte',
-        value: spec.spendingLimit.limit,
-      },
-    })
-  }
-
-  if (spec.recipients && spec.recipients.length > 0) {
-    const selector: IRSelector = {
-      kind: 'arg',
-      argIndex: RECIPIENT_ARG_INDEX,
-      scalarType: 'address',
-    }
-    constraints.push({ op: 'in', selector, values: [...spec.recipients] })
-  }
-
-  const rule: IRPolicyRule = { roles: [], scope, constraints }
-
-  if (spec.approvalThreshold !== undefined) {
-    rule.approval = { kind: 'threshold', threshold: spec.approvalThreshold }
-  }
-
-  if (spec.expiry) {
-    const expiry: NonNullable<IRPolicyRule['expiry']> = {}
-    if (spec.expiry.validUntilLedger !== undefined) {
-      expiry.validUntilLedger = spec.expiry.validUntilLedger
-    }
-    if (spec.expiry.validUntilUnixSeconds !== undefined) {
-      expiry.validUntilUnixSeconds = spec.expiry.validUntilUnixSeconds
-    }
-    rule.expiry = expiry
-  }
-
-  return { chain: spec.chain, defaultBehavior: 'deny_all', rules: [rule] }
-}

package/src/mandate/types.ts

@@ -1,21 +0,0 @@
-// src/mandate/types.ts - the deterministic Mandate source.
-//
-// A MandateSpec is a declarative policy statement: "this account may call this
-// contract, spending at most L per window, requiring M approvals, to these
-// recipients, until this expiry". It carries NO transaction to decode, NO
-// parseConfidence, and NO inference - it lowers deterministically to a
-// PolicyIR. It is the clean end-to-end demo path, co-equal with the recorder.
-
-export interface MandateSpec {
-  chain: 'stellar'
-  contract: string
-  method?: string
-  /** -> OZ `spending_limit` primitive. `limit` is an i128 decimal string. */
-  spendingLimit?: { token: string; limit: string; windowSeconds: number }
-  /** -> OZ `simple_threshold` / `weighted_threshold` primitive. */
-  approvalThreshold?: number
-  /** Recipient allowlist -> an `in` arg condition (not covered by an OZ built-in). */
-  recipients?: string[]
-  /** -> OZ context-rule expiry. */
-  expiry?: { validUntilLedger?: number; validUntilUnixSeconds?: number }
-}

package/src/seams/index.ts

@@ -1,11 +0,0 @@
-// src/seams/index.ts - re-export the three custody-seam contracts.
-
-export type {
-  ChainDecoder,
-  CompileResult,
-  CustodyAdapter,
-  CustodyCapabilities,
-  CustodyMode,
-  PolicySource,
-  SimulationResult,
-} from './types.ts'

package/src/seams/types.ts

@@ -1,81 +0,0 @@
-// src/seams/types.ts - the three custody seams (contracts, not implementations).
-//
-// The synthesizer is decoupled from its edges by three seams:
-//   - PolicySource  (INPUT):  produces a normalized RecordedTransaction. The
-//                             recorder is the reference source; a MandateSpec
-//                             lowering is a second, deterministic source.
-//   - ChainDecoder  (DECODE): chain-specific call data -> normalized facts.
-//   - CustodyAdapter (OUTPUT): compile a PolicyIR to a backend-native policy +
-//                             verify/export it (OZ is the first adapter).
-// These are INTERFACES only. Implementations live in their own modules.
-
-import type { ToolResponse } from '../errors.ts'
-import type { PolicyIR } from '../ir/types.ts'
-import type { Network, ProposedPolicy, RecordedTransaction, ScVal } from '../types.ts'
-
-/** INPUT: something that produces a normalized RecordedTransaction. */
-export interface PolicySource {
-  readonly name: string
-  capture(input: {
-    hash?: string
-    xdr?: string
-    network: Network
-  }): Promise<ToolResponse<RecordedTransaction>>
-}
-
-/** DECODE: chain-specific call data -> the normalized facts the synth reasons
- *  over. */
-export interface ChainDecoder {
-  readonly chain: 'stellar' | 'evm'
-  decodeInvocation(tx: RecordedTransaction): { contract: string; method: string; args: ScVal[] }
-}
-
-/** OZ = enforce; `log_only` is reserved for shadow mode (out of scope). */
-export type CustodyMode = 'enforce' | 'log_only'
-
-/** What a backend can express. A construct needing a false flag is flagged
- *  `uncovered` by the adapter, never silently dropped. */
-export interface CustodyCapabilities {
-  supportsOraclePrice: boolean
-  supportsSpendWindow: boolean
-  supportsInvocationCount: boolean
-  supportsTimeExpiry: boolean
-  supportsThreshold: boolean
-  supportsGeneralPredicate: boolean
-}
-
-/** The result of compiling a PolicyIR for one backend. */
-export interface CompileResult {
-  /** false => some IR construct this backend cannot express (see `uncovered`). */
-  covered: boolean
-  /** Human-readable list of unsupported constructs. */
-  uncovered: string[]
-  /** The backend-native installable policy, assembled when a rule lowered. */
-  proposed?: ProposedPolicy
-}
-
-/** Result of a simulate() dry-run. `ts-model` is the off-chain TS evaluator.
- *  Real permit/deny semantics wiring is a later phase; week-1 returns a
- *  clearly-marked stub (empty `evaluations`, `permitted: null`). */
-export interface SimulationResult {
-  backend: 'ts-model'
-  /** Whether the permit tx would be allowed; null until real semantics land. */
-  permitted: boolean | null
-  /** Per-construct evaluation trace; empty placeholder in this slice. */
-  evaluations: unknown[]
-  /** Diagnostics; marks the stub explicitly. */
-  notes: string[]
-}
-
-/** OUTPUT: compile a PolicyIR to a backend-specific installable policy. */
-export interface CustodyAdapter {
-  readonly name: string
-  readonly mode: CustodyMode
-  capabilities(): CustodyCapabilities
-  compile(ir: PolicyIR): CompileResult
-  /** Phase-03 wiring; a clearly-marked stub in week-1. */
-  simulate(ir: PolicyIR, permitTx: RecordedTransaction): SimulationResult
-  /** Canonical JSON of the IR (portability / audit). */
-  export(ir: PolicyIR): string
-  // install(...) lands with a later phase; not part of this slice.
-}