@crediolabs/policy-synth 0.1.0

package/src/errors.ts

@@ -0,0 +1,79 @@
+// src/errors.ts
+
+export type ErrorCode =
+  // --- recorder ---
+  | 'RECORDING_FAILED'
+  | 'RECORDING_VALIDATION_FAILED'
+  // --- synthesis ---
+  | 'SCOPE_UNRESOLVED'
+  | 'SYNTHESIS_ERROR'
+  | 'MALFORMED_PREDICATE'
+  // --- simulate / verify ---
+  | 'SIMULATION_ERROR'
+  | 'VERIFICATION_FAILED'
+  | 'DENY_CASE_FAILURE'
+  | 'PERMIT_CASE_FAILED'
+  | 'SUMMARY_DRIFT'
+  // --- install / revoke ---
+  | 'INSTALL_BUILD_FAILED'
+  | 'INSTALL_CONFIRM_MISSING'
+  | 'INSTALL_CONFIRM_EXPIRED'
+  | 'REVOKE_BUILD_FAILED'
+  | 'REVOKE_CONFIRM_MISSING'
+  | 'USER_REJECTED_SIGN'
+  | 'WALLET_TIMEOUT'
+  | 'WALLET_UNAVAILABLE'
+  // --- predicate caps (fail-closed at install) ---
+  | 'PREDICATE_TOO_LARGE'
+  | 'PREDICATE_TOO_DEEP'
+  | 'PREDICATE_ORACLE_OVER_LIMIT'
+  | 'POLICY_CAP_EXCEEDED'
+  | 'WASM_TOO_LARGE'
+  // --- interpreter-side denies (canonical names; matches Rust DenyCode) ---
+  | 'MASTER_AUTH_REQUIRED'
+  | 'NONCE_REPLAY'
+  | 'VERSION_MISMATCH'
+  | 'ARITHMETIC_OVERFLOW'
+  | 'AMOUNT_OVERFLOW'
+  | 'RULE_SIGNERS_CHANGED'
+  | 'SCOPE_SELF_CALL'
+  // --- oracle denies (fatal evaluator errors) ---
+  | 'ORACLE_STALE'
+  | 'ORACLE_MISSING'
+  | 'ORACLE_DEVIATION_EXCEEDED'
+  | 'ORACLE_MALFORMED_HISTORY'
+  | 'ORACLE_FINGERPRINT_DRIFT'
+  | 'ORACLE_PAUSED'
+  | 'ORACLE_LEAF_INVALID_POSITION'
+  | 'ORACLE_PARAMS_OUT_OF_RANGE'
+  | 'ORACLE_DECIMALS_MISMATCH'
+  // --- escape-hatch compile gate ---
+  | 'COMPILE_OK'
+  | 'COMPILE_GATE_FAILED'
+
+export interface ToolError {
+  code: ErrorCode
+  message: string
+  /** LLM-actionable hint for the agent skill. Per-code severity is pinned
+   *  in CODE_SEVERITY below; this field is the resolved value at runtime. */
+  severity: 'info' | 'warning' | 'error' | 'fatal'
+  retryable: boolean
+  remediation?: {
+    toolCall?: { name: string; args: Record<string, unknown> }
+    userQuestion?: { code: string; question: string }
+    docsUrl?: string
+  }
+  /** Precedence rule for an LLM agent that sees BOTH toolCall AND userQuestion:
+   *    - toolCall + userQuestion together = userQuestion wins (the human decides).
+   *    - toolCall alone              = agent proceeds.
+   *    - userQuestion alone          = agent stops and asks.
+   *  No silent ambiguity. */
+  details?: unknown
+}
+
+export type ToolResponse<T> = { ok: true; data: T } | { ok: false; error: ToolError }
+
+/** Unsigned Soroban transaction envelope, base64-encoded XDR (Soroban SDK convention).
+ *  Pinned for CLI + MCP + WalletAdapter compatibility. Hex / raw-bytes / TS objects
+ *  are NOT accepted - the contract is base64 string, full stop. */
+export type UnsignedXdrB64 = string

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './adapters/oz/index.ts'
+export * from './errors.ts'
+export * from './ir/index.ts'
+export * from './mandate/index.ts'
+export * from './record/index.ts'
+export * from './registry/index.ts'
+export * from './seams/index.ts'
+export * from './synth/index.ts'
+export * from './types.ts'

package/src/ir/index.ts

@@ -0,0 +1,13 @@
+// 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

@@ -0,0 +1,94 @@
+// 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: '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
+}
+
+/** 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. */
+export type IRCondition =
+  | { op: 'and' | 'or'; children: IRCondition[] }
+  | { op: 'not'; child: IRCondition }
+  | { op: 'compare'; compare: IRCompare }
+  | { op: 'in'; selector: IRSelector; values: 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

@@ -0,0 +1,4 @@
+// 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

@@ -0,0 +1,71 @@
+// 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 (Path-B flagged
+//                       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 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. */
+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

@@ -0,0 +1,21 @@
+// 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 (flagged Path-B in week-1). */
+  recipients?: string[]
+  /** -> OZ context-rule expiry. */
+  expiry?: { validUntilLedger?: number; validUntilUnixSeconds?: number }
+}