@crediolabs/policy-synth 0.1.0

package/dist/adapters/oz/adapter.d.ts

@@ -0,0 +1,20 @@
+import type { CustodyAdapter } from '../../seams/types.ts';
+import type { Network } 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 declare const PLACEHOLDER_OZ_INSTANCES: OzPrimitiveInstances;
+/** Week-1 OZ adapter config with placeholder instance addresses. */
+export declare function placeholderOzConfig(network: Network): OzAdapterConfig;
+export declare function createOzAdapter(config: OzAdapterConfig): CustodyAdapter;

package/dist/adapters/oz/adapter.js

@@ -0,0 +1,282 @@
+// 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 { OZ_LIMITS, SOROBAN_LIMITS } from "../../types.js";
+/** [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 = {
+    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) {
+    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 = {
+    overall: 1,
+    knownContracts: [],
+    unknownContracts: [],
+    opaqueScVals: [],
+    thresholdUsed: 1,
+};
+const CAPABILITIES = {
+    supportsSpendWindow: true,
+    supportsThreshold: true,
+    supportsTimeExpiry: true,
+    supportsOraclePrice: false,
+    supportsInvocationCount: false,
+    supportsGeneralPredicate: false,
+};
+export function createOzAdapter(config) {
+    return {
+        name: 'oz-accounts',
+        mode: 'enforce',
+        capabilities: () => ({ ...CAPABILITIES }),
+        compile: (ir) => compile(ir, config),
+        simulate: () => simulateStub(),
+        export: (ir) => canonicalStringify(ir),
+    };
+}
+function compile(ir, config) {
+    const uncovered = [];
+    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 = { covered: uncovered.length === 0, uncovered };
+    if (!lowered.capExceeded) {
+        const proposed = {
+            contextRule: lowered.contextRule,
+            policyDocuments: [],
+            policyRefs: lowered.policyRefs,
+            parseConfidence: { ...FULL_PARSE_CONFIDENCE },
+            warnings: [],
+            ambiguities: [],
+        };
+        result.proposed = proposed;
+    }
+    return result;
+}
+function lowerRule(rule, config) {
+    const uncovered = [];
+    const policyRefs = [];
+    // 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 = 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 = 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 = {
+        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) {
+    return Math.max(1, Math.round(windowSeconds / SOROBAN_LIMITS.secondsPerLedger));
+}
+/** 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) {
+    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) {
+    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) {
+    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() {
+    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) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortKeys(value[key]);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/adapters/oz/index.d.ts

@@ -0,0 +1 @@
+export { createOzAdapter, type OzAdapterConfig, type OzPrimitiveInstances, PLACEHOLDER_OZ_INSTANCES, placeholderOzConfig, } from './adapter.ts';

package/dist/adapters/oz/index.js

@@ -0,0 +1,2 @@
+// src/adapters/oz/index.ts - re-export the OZ Accounts CustodyAdapter.
+export { createOzAdapter, PLACEHOLDER_OZ_INSTANCES, placeholderOzConfig, } from "./adapter.js";

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+export type ErrorCode = 'RECORDING_FAILED' | 'RECORDING_VALIDATION_FAILED' | 'SCOPE_UNRESOLVED' | 'SYNTHESIS_ERROR' | 'MALFORMED_PREDICATE' | 'SIMULATION_ERROR' | 'VERIFICATION_FAILED' | 'DENY_CASE_FAILURE' | 'PERMIT_CASE_FAILED' | 'SUMMARY_DRIFT' | 'INSTALL_BUILD_FAILED' | 'INSTALL_CONFIRM_MISSING' | 'INSTALL_CONFIRM_EXPIRED' | 'REVOKE_BUILD_FAILED' | 'REVOKE_CONFIRM_MISSING' | 'USER_REJECTED_SIGN' | 'WALLET_TIMEOUT' | 'WALLET_UNAVAILABLE' | 'PREDICATE_TOO_LARGE' | 'PREDICATE_TOO_DEEP' | 'PREDICATE_ORACLE_OVER_LIMIT' | 'POLICY_CAP_EXCEEDED' | 'WASM_TOO_LARGE' | 'MASTER_AUTH_REQUIRED' | 'NONCE_REPLAY' | 'VERSION_MISMATCH' | 'ARITHMETIC_OVERFLOW' | 'AMOUNT_OVERFLOW' | 'RULE_SIGNERS_CHANGED' | 'SCOPE_SELF_CALL' | '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' | '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/dist/errors.js

@@ -0,0 +1,2 @@
+// src/errors.ts
+export {};

package/dist/index.d.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/dist/index.js

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

package/dist/ir/index.d.ts

@@ -0,0 +1 @@
+export type { IRCompare, IRCompOp, IRCondition, IRLogic, IRPolicyRule, IRScalarType, IRSelector, IRVecMode, PolicyIR, } from './types.ts';

package/dist/ir/index.js

@@ -0,0 +1,2 @@
+// src/ir/index.ts - re-export the PolicyIR ("Policy Tree") types.
+export {};

package/dist/ir/types.d.ts

@@ -0,0 +1,97 @@
+/** 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 = {
+    kind: 'arg';
+    argIndex: number;
+    fieldIndex?: number;
+    vecMode?: IRVecMode;
+    scalarType: IRScalarType;
+} | {
+    kind: 'calldata';
+    offset: number;
+    length: number;
+} | {
+    kind: 'value';
+} | {
+    kind: 'amount';
+    token: string;
+} | {
+    kind: 'window_spent';
+    token: string;
+    windowSeconds: number;
+} | {
+    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[];
+    /** 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/dist/ir/types.js

@@ -0,0 +1,11 @@
+// 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.
+export {};

package/dist/mandate/index.d.ts

@@ -0,0 +1,2 @@
+export { mandateToPolicyIR } from './to-ir.ts';
+export type { MandateSpec } from './types.ts';

package/dist/mandate/index.js

@@ -0,0 +1,2 @@
+// src/mandate/index.ts - re-export the Mandate source.
+export { mandateToPolicyIR } from "./to-ir.js";

package/dist/mandate/to-ir.d.ts

@@ -0,0 +1,3 @@
+import type { PolicyIR } from '../ir/types.ts';
+import type { MandateSpec } from './types.ts';
+export declare function mandateToPolicyIR(spec: MandateSpec): PolicyIR;

package/dist/mandate/to-ir.js

@@ -0,0 +1,60 @@
+// 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).
+/** 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) {
+    const scope = { contract: spec.contract };
+    if (spec.method !== undefined)
+        scope.method = spec.method;
+    const constraints = [];
+    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 = {
+            kind: 'arg',
+            argIndex: RECIPIENT_ARG_INDEX,
+            scalarType: 'address',
+        };
+        constraints.push({ op: 'in', selector, values: [...spec.recipients] });
+    }
+    const rule = { roles: [], scope, constraints };
+    if (spec.approvalThreshold !== undefined) {
+        rule.approval = { kind: 'threshold', threshold: spec.approvalThreshold };
+    }
+    if (spec.expiry) {
+        const 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/dist/mandate/types.d.ts

@@ -0,0 +1,20 @@
+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;
+    };
+}

package/dist/mandate/types.js

@@ -0,0 +1,8 @@
+// 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 {};