@crediolabs/policy-synth 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,249 @@
+export type Network = 'mainnet' | 'testnet';
+/** Decoded Soroban value - the normalised subset synthesis needs. */
+export type ScVal = {
+    type: 'address';
+    value: string;
+} | {
+    type: 'i128';
+    value: string;
+} | {
+    type: 'u64';
+    value: string;
+} | {
+    type: 'u32';
+    value: string;
+} | {
+    type: 'symbol';
+    value: string;
+} | {
+    type: 'vec';
+    value: ScVal[];
+} | {
+    type: 'bytes';
+    value: string;
+} | {
+    type: 'other';
+    value: string;
+};
+/** OZ Accounts framework hard limits (verified against canonical OZ source). */
+export declare const OZ_LIMITS: {
+    readonly maxPoliciesPerRule: 5;
+    readonly maxSignersPerRule: 15;
+};
+/** Soroban / Stellar protocol limits used to bound inputs fail-closed. Single
+ *  source so the schema boundary and the core validators cannot drift. */
+export declare const SOROBAN_LIMITS: {
+    /** `valid_until` and other ledger-sequence fields are u32. */
+    readonly u32Max: 4294967295;
+    /** Upper bound on top-level invocations in a recorded transaction; a real
+     *  Stellar tx caps operations well below this. Bounds a hand-crafted payload. */
+    readonly maxInvocations: 512;
+    /** Stellar targets a ~5s ledger close time (DAY_IN_LEDGERS = 17280 = 86400/5),
+     *  used to convert a spend window in seconds to OZ `period_ledgers`. */
+    readonly secondsPerLedger: 5;
+};
+/** 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
+ *  disagree, the interpreter is authoritative. Rationale per cap:
+ *    - MAX_DEPTH = 5:             3 walkthroughs need depth 2; budget = 2x growth + 1 for `not` chain.
+ *    - MAX_LEAVES = 200:         allowlists (recipients, paths) typically < 100; budget = 2x + 1 nested allowlist.
+ *    - MAX_PREDICATE_BYTES = 32 KB: well under the per-ledger-entry 64 KB persistent-storage limit.
+ *    - MAX_ORACLE_READS = 6:     two-round confirmation per asset consumes 2 reads; cap accommodates a predicate that references up to 3 unique oracle assets (3 * 2 = 6 reads). Stays a fail-closed install-time cap.
+ *    - MAX_IN_OPERAND_COUNT = 32: allowlist < 32 is a UX-natural bound. */
+export declare const PREDICATE_CAPS: {
+    readonly MAX_DEPTH: 5;
+    readonly MAX_LEAVES: 200;
+    readonly MAX_PREDICATE_BYTES: number;
+    readonly MAX_ORACLE_READS: 6;
+    readonly MAX_IN_OPERAND_COUNT: 32;
+};
+/** OZ context-rule draft - the unit the install builder builds add_context_rule from. */
+export type ContextRuleDraft = {
+    contextRuleType: {
+        kind: 'default';
+    } | {
+        kind: 'call_contract';
+        contract: string;
+    } | {
+        kind: 'create_contract';
+        wasmHash: string;
+    };
+    name: string;
+    /** Ledger sequence (u32). Soroban `valid_until: Option<u32>`. */
+    validUntilLedger: number | null;
+    /** Mirrors OZ `Signer` enum exactly: `Delegated(Address) | External(Address, Bytes)`.
+     *  The verifier address + key bytes for an external signer are carried in the
+     *  `External` variant - there is no `Key` or `SmartAccount` variant, and no
+     *  master/non-master discriminator lives on the type itself. */
+    signers: SignerDraft[];
+    policies: PolicyRef[];
+};
+/** Mirrors OZ `Signer` exactly: `Signer::Delegated(Address) | Signer::External(Address, Bytes)`. */
+export type SignerDraft = {
+    kind: 'delegated';
+    address: string;
+} | {
+    kind: 'external';
+    verifier: string;
+    keyBytes: string;
+};
+/** Reference to one policy attached to a context rule. */
+export type PolicyRef = {
+    kind: 'oz_builtin';
+    primitive: OZPrimitiveConfig;
+    instanceAddress: string;
+} | {
+    kind: 'interpreter';
+    interpreterAddress: string;
+    predicateBlobBase64: string;
+};
+/** A serialised predicate document stored against a (smart_account, rule_id) pair. */
+export interface PolicyDocument {
+    /** Grammar version baked into the interpreter wasm. Fail-closed strict match at install
+     *  AND at evaluate (defence in depth). NOT the per-edit revision. */
+    grammarVersion: 1;
+    /** Per-rule install nonce. Must equal the interpreter's stored nonce + 1 at install.
+     *  First install accepts nonce = 1 with stored nonce = 0. Re-install is structurally
+     *  possible by incrementing the nonce; uninstall removes the nonce with state so a
+     *  subsequent install returns to nonce = 1. Replay of an old install denied. */
+    installNonce: number;
+    /** Canonical ScVal encoding (NOT JSON) - the version-match bypass is closed by the
+     *  on-chain serialisation, not by a parser. */
+    encodedPredicate: string;
+    /** Hash of the post-canonicalisation bytes of encodedPredicate. Stored alongside the
+     *  doc and re-verified at evaluate. */
+    predicateHash: string;
+    /** Per-policy overrides of oracle thresholds; absent = use defaults.
+     *  Overrides may TIGHTEN only (never widen) - the interpreter rejects any per-policy
+     *  value looser than the wasm-level defaults at install. */
+    oracleParams?: {
+        /** Seconds; must be <= MAX_ORACLE_STALENESS_SECONDS (600). */
+        maxStalenessSeconds?: number;
+        /** Basis points; must be <= MAX_ORACLE_DEVIATION_BPS (200). */
+        maxDeviationBps?: number;
+    };
+}
+/** The versioned predicate AST (interpreter side). Tagged union. */
+export type PredicateNode = {
+    op: 'and';
+    children: PredicateNode[];
+} | {
+    op: 'or';
+    children: PredicateNode[];
+} | {
+    op: 'not';
+    child: PredicateNode;
+} | {
+    op: 'eq';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
+} | {
+    op: 'lt' | 'lte' | 'gt' | 'gte';
+    left: PredicateLeaf;
+    right: PredicateLeaf;
+} | {
+    op: 'in';
+    needle: PredicateLeaf;
+    haystack: PredicateLeaf[];
+};
+export type PredicateLeaf = {
+    kind: 'call_contract';
+} | {
+    kind: 'call_fn';
+} | {
+    kind: 'call_arg';
+    index: number;
+} | {
+    kind: 'amount';
+    token: string;
+} | {
+    kind: 'window_spent';
+    token: string;
+} | {
+    kind: 'now';
+} | {
+    kind: 'valid_until';
+} | {
+    kind: 'invocation_count_in_window';
+    windowSecs: number;
+} | {
+    kind: 'oracle_price';
+    asset: string;
+};
+export interface OZPrimitiveConfig {
+    primitive: 'spending_limit' | 'simple_threshold' | 'weighted_threshold';
+    params: Record<string, unknown>;
+}
+export interface ContractInvocation {
+    contract: string;
+    fn: string;
+    args: ScVal[];
+    subInvocations: ContractInvocation[];
+}
+export interface TokenMovement {
+    token: string;
+    from: string;
+    to: string;
+    amount: string;
+}
+export interface OnChainEvent {
+    contract: string;
+    topics: string[];
+    data: ScVal;
+}
+export interface RecordedTransaction {
+    network: Network;
+    /** Authorising signers (the agent / owner set). */
+    signers: string[];
+    /** Top-level call + nested sub-invocations captured for analysis:
+     *  v1 grammar matches only the top-level call's own `(contract, fn_name, args)`
+     *  that `Policy::enforce` receives - sub-invocations are NOT walked in v1. */
+    invocations: ContractInvocation[];
+    /** All token movements (from events). */
+    tokenMovements: TokenMovement[];
+    /** Raw on-chain events from getTransaction (used for validation). */
+    events: OnChainEvent[];
+    /** Soroban auth entries (which signers, which contracts, which fns). */
+    authEntries: unknown[];
+    ledgerSequence: number;
+    fetchedAt: number;
+    /** The parsed-decoding freshness, computed by the recorder. The synth refuses on
+     *  parseConfidence.overall < parseConfidence.thresholdUsed. */
+    parseConfidence: ParseConfidence;
+    /** Source account (already recorded, needed by install + reviewer). */
+    sourceAccount: string;
+}
+export interface ProposedPolicy {
+    contextRule: ContextRuleDraft;
+    policyDocuments: PolicyDocument[];
+    policyRefs: PolicyRef[];
+    /** Parsed-decoding freshness mirror; the orchestrator refuses when below threshold. */
+    parseConfidence: ParseConfidence;
+    warnings: string[];
+    ambiguities: AmbiguityPrompt[];
+}
+export interface AmbiguityPrompt {
+    code: AmbiguityCode;
+    question: string;
+}
+/** Catalogue of named ambiguity codes (the skill's prompt files are one-per-code).
+ *  Adding a code is a synthesizer decision; the prompt authoring must not
+ *  invent codes outside this union. */
+export type AmbiguityCode = 'DURATION_UNSPECIFIED' | 'AMOUNT_BOUND_MISSING' | 'RECIPIENT_ALLOWLIST_EMPTY' | 'FREQUENCY_BOUND_MISSING' | 'ORACLE_ASSET_UNKNOWN' | 'MULTIPLE_UNRELATED_TARGETS';
+/** Structured recording freshness. `overall` is the gate threshold (default 1.0); the
+ *  breakdown is the diagnostic the user / agent sees when the gate fires. The
+ *  computation rule is pinned: `overall = 1 - (unknownContracts + opaqueScVals) / total`. */
+export interface ParseConfidence {
+    overall: number;
+    knownContracts: string[];
+    unknownContracts: Array<{
+        contract: string;
+        reason: 'no-abi' | 'version-mismatch' | 'opaque-result';
+    }>;
+    opaqueScVals: Array<{
+        path: string;
+        type: string;
+    }>;
+    thresholdUsed: number;
+}

package/dist/types.js

@@ -0,0 +1,35 @@
+// src/types.ts - shared domain types (single source of truth)
+/** OZ Accounts framework hard limits (verified against canonical OZ source). */
+export const OZ_LIMITS = {
+    maxPoliciesPerRule: 5,
+    maxSignersPerRule: 15,
+    // NO per-account rule cap - OZ imposes none.
+};
+/** Soroban / Stellar protocol limits used to bound inputs fail-closed. Single
+ *  source so the schema boundary and the core validators cannot drift. */
+export const SOROBAN_LIMITS = {
+    /** `valid_until` and other ledger-sequence fields are u32. */
+    u32Max: 4294967295,
+    /** Upper bound on top-level invocations in a recorded transaction; a real
+     *  Stellar tx caps operations well below this. Bounds a hand-crafted payload. */
+    maxInvocations: 512,
+    /** Stellar targets a ~5s ledger close time (DAY_IN_LEDGERS = 17280 = 86400/5),
+     *  used to convert a spend window in seconds to OZ `period_ledgers`. */
+    secondsPerLedger: 5,
+};
+/** 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
+ *  disagree, the interpreter is authoritative. Rationale per cap:
+ *    - MAX_DEPTH = 5:             3 walkthroughs need depth 2; budget = 2x growth + 1 for `not` chain.
+ *    - MAX_LEAVES = 200:         allowlists (recipients, paths) typically < 100; budget = 2x + 1 nested allowlist.
+ *    - MAX_PREDICATE_BYTES = 32 KB: well under the per-ledger-entry 64 KB persistent-storage limit.
+ *    - MAX_ORACLE_READS = 6:     two-round confirmation per asset consumes 2 reads; cap accommodates a predicate that references up to 3 unique oracle assets (3 * 2 = 6 reads). Stays a fail-closed install-time cap.
+ *    - MAX_IN_OPERAND_COUNT = 32: allowlist < 32 is a UX-natural bound. */
+export const PREDICATE_CAPS = {
+    MAX_DEPTH: 5,
+    MAX_LEAVES: 200,
+    MAX_PREDICATE_BYTES: 32 * 1024,
+    MAX_ORACLE_READS: 6,
+    MAX_IN_OPERAND_COUNT: 32,
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@crediolabs/policy-synth",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "14.4.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.5",
+    "@types/node": "^26.1.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/adapters/oz/adapter.ts

@@ -0,0 +1,363 @@
+// src/adapters/oz/adapter.ts - the OZ Accounts CustodyAdapter (Path-A lowering).
+//
+// Compiles a PolicyIR to an OZ `ProposedPolicy` using OZ built-in policy
+// primitives (Path A). 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
+//   approval.threshold        -> `simple_threshold` / `weighted_threshold`
+// 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.
+//
+// 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
+// ships a clearly-labelled [VERIFY] placeholder so nothing invents an address.
+
+import type { IRCondition, IRPolicyRule, IRSelector, PolicyIR } from '../../ir/types.ts'
+import type {
+  CompileResult,
+  CustodyAdapter,
+  CustodyCapabilities,
+  SimulationResult,
+} from '../../seams/types.ts'
+import type {
+  ContextRuleDraft,
+  Network,
+  ParseConfidence,
+  PolicyRef,
+  ProposedPolicy,
+} from '../../types.ts'
+import { OZ_LIMITS, SOROBAN_LIMITS } from '../../types.ts'
+
+/** OZ built-in policy contract instance addresses, per primitive. */
+export interface OzPrimitiveInstances {
+  spending_limit: string
+  simple_threshold: string
+  weighted_threshold: string
+}
+
+/** Per-network config for the OZ adapter. */
+export interface OzAdapterConfig {
+  network: Network
+  instances: OzPrimitiveInstances
+}
+
+/** [VERIFY] NOT real deployed addresses. The OZ built-in policy instances are
+ *  per-network deploy artifacts we do not have yet; install is a later phase.
+ *  Injected so the adapter never invents a Stellar contract address. */
+export const PLACEHOLDER_OZ_INSTANCES: OzPrimitiveInstances = {
+  spending_limit: 'VERIFY-oz-spending-limit-instance-address',
+  simple_threshold: 'VERIFY-oz-simple-threshold-instance-address',
+  weighted_threshold: 'VERIFY-oz-weighted-threshold-instance-address',
+}
+
+/** Week-1 OZ adapter config with placeholder instance addresses. */
+export function placeholderOzConfig(network: Network): OzAdapterConfig {
+  return { network, instances: PLACEHOLDER_OZ_INSTANCES }
+}
+
+/** Parse confidence for a deterministic (non-decoded) input: full, with an
+ *  empty unknown/opaque breakdown. A mandate needs no decoding, so the gate is
+ *  not applicable and confidence is 1. */
+const FULL_PARSE_CONFIDENCE: ParseConfidence = {
+  overall: 1,
+  knownContracts: [],
+  unknownContracts: [],
+  opaqueScVals: [],
+  thresholdUsed: 1,
+}
+
+const CAPABILITIES: CustodyCapabilities = {
+  supportsSpendWindow: true,
+  supportsThreshold: true,
+  supportsTimeExpiry: true,
+  supportsOraclePrice: false,
+  supportsInvocationCount: false,
+  supportsGeneralPredicate: false,
+}
+
+export function createOzAdapter(config: OzAdapterConfig): CustodyAdapter {
+  return {
+    name: 'oz-accounts',
+    mode: 'enforce',
+    capabilities: () => ({ ...CAPABILITIES }),
+    compile: (ir) => compile(ir, config),
+    simulate: () => simulateStub(),
+    export: (ir) => canonicalStringify(ir),
+  }
+}
+
+function compile(ir: PolicyIR, config: OzAdapterConfig): CompileResult {
+  const uncovered: string[] = []
+
+  const firstRule = ir.rules[0]
+  if (!firstRule) {
+    return { covered: false, uncovered: ['empty PolicyIR (no rules to compile)'] }
+  }
+  if (ir.rules.length > 1) {
+    uncovered.push(
+      `multi-rule PolicyIR: ${ir.rules.length - 1} rule(s) beyond the first are not compiled (a ProposedPolicy carries a single context rule in this slice)`
+    )
+  }
+
+  const lowered = lowerRule(firstRule, config)
+  uncovered.push(...lowered.uncovered)
+
+  const result: CompileResult = { covered: uncovered.length === 0, uncovered }
+  if (!lowered.capExceeded) {
+    const proposed: ProposedPolicy = {
+      contextRule: lowered.contextRule,
+      policyDocuments: [],
+      policyRefs: lowered.policyRefs,
+      parseConfidence: { ...FULL_PARSE_CONFIDENCE },
+      warnings: [],
+      ambiguities: [],
+    }
+    result.proposed = proposed
+  }
+  return result
+}
+
+interface LoweredRule {
+  contextRule: ContextRuleDraft
+  policyRefs: PolicyRef[]
+  uncovered: string[]
+  capExceeded: boolean
+}
+
+function lowerRule(rule: IRPolicyRule, config: OzAdapterConfig): LoweredRule {
+  const uncovered: string[] = []
+  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
+  // (e.g. an unbounded approve alongside a capped transfer).
+  const contextRuleType: ContextRuleDraft['contextRuleType'] =
+    rule.scope.contract !== undefined
+      ? { kind: 'call_contract', contract: rule.scope.contract }
+      : { kind: 'default' }
+
+  if (rule.scope.method !== undefined && rule.scope.contract !== undefined) {
+    uncovered.push(
+      `per-method scoping to \`${rule.scope.method}\` (OZ CallContract scopes by contract only; requires the interpreter predicate)`
+    )
+  }
+
+  if (rule.scope.chainId !== undefined) {
+    uncovered.push(
+      `chainId \`${rule.scope.chainId}\` not bindable by the Stellar OZ adapter (network is per-context, not per-rule)`
+    )
+  }
+
+  if (rule.roles.length > 0) {
+    uncovered.push(
+      `roles [${rule.roles.join(', ')}] dropped (role-to-signer mapping is a later phase; OZ signers carry addresses, not role names)`
+    )
+  }
+
+  // expiry -> validUntilLedger. Unix-timestamp expiry cannot be expressed by an
+  // OZ context rule (it expires by ledger sequence), so flag it.
+  let validUntilLedger: number | null = null
+  if (rule.expiry) {
+    if (rule.expiry.validUntilLedger !== undefined) {
+      validUntilLedger = rule.expiry.validUntilLedger
+    } else if (rule.expiry.validUntilUnixSeconds !== undefined) {
+      uncovered.push(
+        'time expiry given as a unix timestamp (OZ context rules expire by ledger sequence; supply expiry.validUntilLedger)'
+      )
+    }
+  }
+
+  // guard -> Path B (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
+  // 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,
+  // so the spent token must equal the scope contract, and the window is a
+  // ledger count (~5s/ledger), not seconds.
+  for (const c of rule.constraints) {
+    const spend = matchSpendingLimit(c)
+    if (!spend) {
+      uncovered.push(describeCondition(c))
+      continue
+    }
+    if (contextRuleType.kind !== 'call_contract' || spend.token !== contextRuleType.contract) {
+      uncovered.push(
+        `spending_limit on token ${spend.token} needs a CallContract context scoped to that token (OZ pins the limit to the context contract, not a token param)`
+      )
+      continue
+    }
+    policyRefs.push({
+      kind: 'oz_builtin',
+      primitive: {
+        primitive: 'spending_limit',
+        params: {
+          spending_limit: spend.limit,
+          period_ledgers: secondsToLedgers(spend.windowSeconds),
+        },
+      },
+      instanceAddress: config.instances.spending_limit,
+    })
+  }
+
+  // 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.
+  if (rule.approval) {
+    if (!Number.isInteger(rule.approval.threshold) || rule.approval.threshold < 1) {
+      uncovered.push(
+        `approval threshold ${rule.approval.threshold} is not a positive integer (a 0 or negative threshold is not an M-of-N gate)`
+      )
+    } else {
+      const weights = rule.approval.weights
+      if (weights && Object.keys(weights).length > 0) {
+        policyRefs.push({
+          kind: 'oz_builtin',
+          primitive: {
+            primitive: 'weighted_threshold',
+            params: { threshold: rule.approval.threshold, weights },
+          },
+          instanceAddress: config.instances.weighted_threshold,
+        })
+      } else {
+        policyRefs.push({
+          kind: 'oz_builtin',
+          primitive: {
+            primitive: 'simple_threshold',
+            params: { threshold: rule.approval.threshold },
+          },
+          instanceAddress: config.instances.simple_threshold,
+        })
+      }
+    }
+  }
+
+  const capExceeded = policyRefs.length > OZ_LIMITS.maxPoliciesPerRule
+  if (capExceeded) {
+    uncovered.push(
+      `policy count ${policyRefs.length} exceeds OZ maxPoliciesPerRule (${OZ_LIMITS.maxPoliciesPerRule})`
+    )
+  }
+
+  const contextRule: ContextRuleDraft = {
+    contextRuleType,
+    name:
+      contextRuleType.kind === 'call_contract'
+        ? `call_contract:${contextRuleType.contract}`
+        : 'default',
+    validUntilLedger,
+    signers: [],
+    policies: policyRefs,
+  }
+
+  return { contextRule, policyRefs, uncovered, capExceeded }
+}
+
+/** Convert a spend window in seconds to OZ `period_ledgers` (u32, >= 1).
+ *  Stellar targets a ~5s ledger close time. */
+function secondsToLedgers(windowSeconds: number): number {
+  return Math.max(1, Math.round(windowSeconds / SOROBAN_LIMITS.secondsPerLedger))
+}
+
+interface SpendingLimitMatch {
+  token: string
+  limit: string
+  windowSeconds: number
+}
+
+/** Match the `window_spent(token, window) <= limit` compare that lowers to the
+ *  OZ `spending_limit` primitive. Only `lte` matches (the spend-cap semantic). */
+function matchSpendingLimit(c: IRCondition): SpendingLimitMatch | null {
+  if (c.op !== 'compare') return null
+  const { selector, operator, value } = c.compare
+  if (selector.kind !== 'window_spent' || operator !== 'lte') return 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). */
+function describeCondition(cond: IRCondition): string {
+  switch (cond.op) {
+    case 'in':
+      return `value allowlist on ${describeSelector(cond.selector)} (arg allowlist, Path B)`
+    case 'not':
+      return 'negated condition (predicate DSL, Path B)'
+    case 'and':
+    case 'or':
+      return `nested ${cond.op} condition (predicate DSL, Path B)`
+    case 'compare': {
+      const s = cond.compare.selector
+      switch (s.kind) {
+        case 'oracle_price':
+          return `oracle price condition on ${s.asset} (oracle price not supported in week-1)`
+        case 'invocation_count':
+          return `invocation-count window (${s.windowSeconds}s) condition (not supported in week-1)`
+        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)`
+        case 'arg':
+          return `argument comparison on arg ${s.argIndex} (predicate DSL, Path B)`
+        case 'calldata':
+          return 'EVM calldata comparison (predicate DSL, Path B)'
+        case 'value':
+          return 'tx.value comparison (predicate DSL, Path B)'
+        case 'now':
+        case 'valid_until':
+          return 'time comparison (predicate DSL, Path B)'
+      }
+    }
+  }
+}
+
+function describeSelector(s: IRSelector): string {
+  switch (s.kind) {
+    case 'arg':
+      return `arg ${s.argIndex}`
+    case 'amount':
+      return `amount(${s.token})`
+    case 'window_spent':
+      return `window_spent(${s.token})`
+    case 'oracle_price':
+      return `oracle_price(${s.asset})`
+    case 'invocation_count':
+      return `invocation_count(${s.windowSeconds}s)`
+    case 'calldata':
+      return `calldata[${s.offset}:${s.offset + s.length}]`
+    default:
+      return s.kind
+  }
+}
+
+function simulateStub(): SimulationResult {
+  return {
+    backend: 'ts-model',
+    permitted: null,
+    evaluations: [],
+    notes: ['stub: real permit/deny semantics wiring is a later phase'],
+  }
+}
+
+/** Canonical JSON with recursively sorted object keys (stable across runs). */
+function canonicalStringify(value: unknown): string {
+  return JSON.stringify(sortKeys(value))
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys)
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = sortKeys((value as Record<string, unknown>)[key])
+    }
+    return out
+  }
+  return value
+}

package/src/adapters/oz/index.ts

@@ -0,0 +1,9 @@
+// src/adapters/oz/index.ts - re-export the OZ Accounts CustodyAdapter.
+
+export {
+  createOzAdapter,
+  type OzAdapterConfig,
+  type OzPrimitiveInstances,
+  PLACEHOLDER_OZ_INSTANCES,
+  placeholderOzConfig,
+} from './adapter.ts'