@crediolabs/policy-synth 0.1.3 → 0.1.5

package/dist-cjs/adapters/oz/adapter.js

@@ -0,0 +1,289 @@
+"use strict";
+// src/adapters/oz/adapter.ts - the OZ Accounts CustodyAdapter.
+//
+// Compiles a PolicyIR to an OZ `ProposedPolicy` using OZ built-in policy
+// 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
+//   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 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
+// ships a clearly-labelled [VERIFY] placeholder so nothing invents an address.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLACEHOLDER_OZ_INSTANCES = void 0;
+exports.placeholderOzConfig = placeholderOzConfig;
+exports.createOzAdapter = createOzAdapter;
+const types_ts_1 = require("../../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. */
+exports.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. */
+function placeholderOzConfig(network) {
+    return { network, instances: exports.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,
+};
+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 as not
+    // covered 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 -> 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 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,
+    // 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 as not covered 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 > types_ts_1.OZ_LIMITS.maxPoliciesPerRule;
+    if (capExceeded) {
+        uncovered.push(`policy count ${policyRefs.length} exceeds OZ maxPoliciesPerRule (${types_ts_1.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 / types_ts_1.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 built-in-primitive backend
+ *  cannot express, used to populate `uncovered`. */
+function describeCondition(cond) {
+    switch (cond.op) {
+        case 'in':
+            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)';
+        case 'and':
+        case 'or':
+            return `nested ${cond.op} condition (predicate DSL)`;
+        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)`;
+                case 'arg':
+                    return `argument comparison on arg ${s.argIndex} (predicate DSL)`;
+                case 'calldata':
+                    return 'EVM calldata comparison (predicate DSL)';
+                case 'value':
+                    return 'tx.value comparison (predicate DSL)';
+                case 'now':
+                case 'valid_until':
+                    return 'time comparison (predicate DSL)';
+            }
+        }
+    }
+}
+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-cjs/adapters/oz/index.d.ts

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

package/dist-cjs/adapters/oz/index.js

@@ -0,0 +1,8 @@
+"use strict";
+// src/adapters/oz/index.ts - re-export the OZ Accounts CustodyAdapter.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.placeholderOzConfig = exports.PLACEHOLDER_OZ_INSTANCES = exports.createOzAdapter = void 0;
+var adapter_ts_1 = require("./adapter.js");
+Object.defineProperty(exports, "createOzAdapter", { enumerable: true, get: function () { return adapter_ts_1.createOzAdapter; } });
+Object.defineProperty(exports, "PLACEHOLDER_OZ_INSTANCES", { enumerable: true, get: function () { return adapter_ts_1.PLACEHOLDER_OZ_INSTANCES; } });
+Object.defineProperty(exports, "placeholderOzConfig", { enumerable: true, get: function () { return adapter_ts_1.placeholderOzConfig; } });

package/dist-cjs/codegen/compile-gate.d.ts

@@ -0,0 +1,33 @@
+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;
+}
+/** 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 declare function hasRustToolchain(): Promise<boolean>;
+/** 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 declare function compileCheck(rustSource: string, opts?: CompileGateOpts): Promise<CompileGateResult>;

package/dist-cjs/codegen/compile-gate.js

@@ -0,0 +1,123 @@
+"use strict";
+// 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).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasRustToolchain = hasRustToolchain;
+exports.compileCheck = compileCheck;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** 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`. */
+async function hasRustToolchain() {
+    const probe = await probeToolchain();
+    return probe.present;
+}
+async function probeToolchain() {
+    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) {
+    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;
+    }
+}
+function runProcess(cmd, args, opts) {
+    return new Promise((resolve, reject) => {
+        if (opts.signal?.aborted) {
+            reject(new Error('aborted'));
+            return;
+        }
+        const child = (0, node_child_process_1.spawn)(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (b) => {
+            stdout += b.toString('utf8');
+        });
+        child.stderr.on('data', (b) => {
+            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. */
+async function compileCheck(rustSource, opts = {}) {
+    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 = null;
+    try {
+        dir = await (0, promises_1.mkdtemp)((0, node_path_1.join)(opts.tempDir ?? (0, node_os_1.tmpdir)(), 'codegen-gate-'));
+        await (0, promises_1.writeFile)((0, node_path_1.join)(dir, 'Cargo.toml'), CARGO_MANIFEST);
+        await (0, promises_1.writeFile)((0, node_path_1.join)(dir, 'lib.rs'), rustSource);
+        const runOpts = opts.signal ? { signal: opts.signal } : {};
+        const result = await runProcess(opts.cargoBin ?? 'cargo', ['check', '--quiet', '--offline', '--manifest-path', (0, node_path_1.join)(dir, 'Cargo.toml')], runOpts).catch((e) => ({ 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 (0, promises_1.rm)(dir, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+}

package/dist-cjs/codegen/index.d.ts

@@ -0,0 +1,2 @@
+export { type CompileGateOpts, type CompileGateResult, compileCheck, hasRustToolchain, } from './compile-gate.ts';
+export { type EscapeHatchSpec, generateRust, } from './template.ts';

package/dist-cjs/codegen/index.js

@@ -0,0 +1,14 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRust = exports.hasRustToolchain = exports.compileCheck = void 0;
+var compile_gate_ts_1 = require("./compile-gate.js");
+Object.defineProperty(exports, "compileCheck", { enumerable: true, get: function () { return compile_gate_ts_1.compileCheck; } });
+Object.defineProperty(exports, "hasRustToolchain", { enumerable: true, get: function () { return compile_gate_ts_1.hasRustToolchain; } });
+var template_ts_1 = require("./template.js");
+Object.defineProperty(exports, "generateRust", { enumerable: true, get: function () { return template_ts_1.generateRust; } });

package/dist-cjs/codegen/template.d.ts

@@ -0,0 +1,18 @@
+/** 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[];
+}
+/** 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 declare function generateRust(spec: EscapeHatchSpec, name: string): string;

package/dist-cjs/codegen/template.js

@@ -0,0 +1,134 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRust = generateRust;
+/** 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) {
+    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) {
+    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. */
+function generateRust(spec, name) {
+    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/dist-cjs/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' | 'TOO_MANY_LEAVES' | 'IN_OPERAND_LIMIT' | '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;