@crediolabs/policy-synth 0.1.4 → 0.1.6

package/dist-cjs/verify/simulate.js

@@ -0,0 +1,261 @@
+"use strict";
+// src/verify/simulate.ts - the post-simulation verdict for `simulate_policy`.
+//
+// `simulatePolicy` replays a recorded transaction against a proposed
+// `PredicateNode` and emits the `SimulationResult` envelope the review-card
+// builder + the verification pipeline consume.
+//
+// Boundary (pinned, must not drift):
+//   - `SIMULATION_ERROR`        = RUNTIME evaluation failed. Surfaced by
+//     `simulatePolicy`. Reasons: malformed `permitTx` input (no top-level
+//     invocation to build an EvalContext from), a referenced oracle asset
+//     without a satisfying price fixture, or a non-runtime propagation (a
+//     throw that is not an oracle error or a controlled deny). A
+//     runtime evaluation failure is NOT a policy-minimality problem; the
+//     policy may still be minimal. Re-running with a complete fixture MAY
+//     succeed.
+//   - `VERIFICATION_FAILED`     = STATIC minimality check failed. Surfaced
+//     by `verifyPolicy`. The minimiser identified a load-bearing-free
+//     constraint; the policy is structurally over-broad regardless of how
+//     any concrete call evaluates. Re-running with a different fixture
+//     will NOT fix it; the policy must be trimmed.
+//
+// Determinism: same `(predicate, permitTx, opts)` -> byte-identical
+// envelope, no clock, no randomness.
+//
+// The permit EvalContext is built locally (mirror of the helper used in
+// `synthesize-from-recording.ts`) so this module does not couple to the
+// orchestrator's private build helpers. The shape is pinned by the test
+// suite to stay in lockstep.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.simulatePolicy = simulatePolicy;
+const deny_cases_ts_1 = require("../synth/deny-cases.js");
+const evaluate_ts_1 = require("../synth/evaluate.js");
+const types_ts_1 = require("../types.js");
+const SIMULATOR_VERSION = 'ts-model-1.0.0';
+/** Replay a recorded transaction against a proposed predicate and emit the
+ *  `SimulationResult` envelope. The simulator returns the SAME permit
+ *  verdict `runHarness` expects: the intended recorded call must permit; every
+ *  generated deny dimension must deny. A runtime evaluation failure
+ *  (malformed input, missing oracle fixture, etc.) returns a `SIMULATION_ERROR`
+ *  `ToolError` - NOT a deny verdict, NOT `VERIFICATION_FAILED`. The boundary
+ *  is pinned: minimality is a verify-time concern, runtime evaluation is a
+ *  simulate-time concern. */
+function simulatePolicy(predicate, permitTx, opts = {}) {
+    // The permit EvalContext requires a top-level invocation. A recorded tx
+    // with no invocations is structurally malformed input - we surface a
+    // runtime `SIMULATION_ERROR` rather than fabricating a permit verdict.
+    const topLevel = permitTx.invocations[0];
+    if (!topLevel) {
+        return {
+            ok: false,
+            error: simulationError('recorded transaction has no top-level invocation to simulate'),
+        };
+    }
+    let permitCtx;
+    try {
+        permitCtx = buildPermitContext(predicate, permitTx, topLevel, opts);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: simulationError(`could not build permit evaluation context: ${e.message}`),
+        };
+    }
+    // `predicate === null` means the policy is OZ-only (no interpreter
+    // predicate). We still emit the envelope so the review card + verifier
+    // can consume it: the permit verdict evaluates an always-permit empty
+    // tree, and the deny battery is empty (nothing to verify at the
+    // interpreter layer).
+    const evaluatePredicate = predicate ?? { op: 'and', children: [] };
+    const evaluatedCases = [];
+    let permitVerdict;
+    try {
+        permitVerdict = (0, evaluate_ts_1.evaluate)(evaluatePredicate, permitCtx);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: simulationError(`permit evaluation threw at runtime: ${e.message}`, e),
+        };
+    }
+    evaluatedCases.push({
+        dimension: 'permit',
+        outcome: permitVerdict.permit ? 'permit' : 'deny',
+        reason: permitVerdict.permit ? 'matches recorded call' : permitVerdict.reason,
+    });
+    // The deny battery is generated against the SAME permit context. A
+    // runtime evaluation failure on ANY deny case is a `SIMULATION_ERROR` -
+    // not a deny verdict (an evaluate-throws is not a deny) and not a
+    // minimality problem.
+    const cases = (0, deny_cases_ts_1.generateCases)(evaluatePredicate, permitCtx);
+    for (const deny of cases.denies) {
+        let result;
+        try {
+            result = (0, evaluate_ts_1.evaluate)(evaluatePredicate, deny.ctx);
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: simulationError(`deny case "${deny.dimension}" threw at runtime: ${e.message}`, e),
+            };
+        }
+        evaluatedCases.push({
+            dimension: deny.dimension,
+            outcome: result.permit ? 'permit' : 'deny',
+            reason: result.permit ? 'no matching deny' : result.reason,
+        });
+    }
+    const envelope = {
+        permit: permitVerdict.permit ? { tx: 'permit' } : { tx: 'deny', reason: permitVerdict.reason },
+        evaluatedCases,
+        backend: 'ts-model',
+        simulatorVersion: SIMULATOR_VERSION,
+    };
+    return { ok: true, data: envelope };
+}
+/** Build the permit `EvalContext` the simulator drives. Mirrors the
+ *  helper in `synthesize-from-recording.ts` so the simulator sees the same
+ *  shape the orchestrator's self-verify pipeline sees; we mirror here
+ *  rather than import to keep `src/verify/` decoupled from the
+ *  orchestrator's private helpers. The shape is pinned by tests so the
+ *  two implementations stay in lockstep. */
+function buildPermitContext(predicate, tx, topLevel, opts) {
+    const amountByToken = {};
+    const totals = new Map();
+    for (const m of tx.tokenMovements) {
+        const current = totals.get(m.token) ?? 0n;
+        totals.set(m.token, current + BigInt(m.amount));
+    }
+    for (const [token, total] of totals) {
+        amountByToken[token] = total.toString();
+    }
+    // Oracle prices: when the caller supplies a fixture, use it; otherwise
+    // derive a satisfying entry per `oracle_price` leaf in the predicate so
+    // the permit call permits. Negatives are clamped at 0 (Stellar oracle
+    // prices are non-negative).
+    const oraclePriceByAsset = {};
+    if (opts.oraclePricesByAsset) {
+        for (const [asset, entry] of Object.entries(opts.oraclePricesByAsset)) {
+            oraclePriceByAsset[asset] = entry;
+        }
+    }
+    if (predicate !== null) {
+        visitOracleLeaves(predicate, (asset, op, bound) => {
+            // A caller-supplied fixture entry always wins; we only fill gaps.
+            if (oraclePriceByAsset[asset] !== undefined)
+                return;
+            let price;
+            switch (op) {
+                case 'lt':
+                case 'gt':
+                    price = op === 'lt' ? bound - 1n : bound + 1n;
+                    break;
+                case 'lte':
+                case 'gte':
+                case 'eq':
+                    price = bound;
+                    break;
+            }
+            if (price < 0n)
+                price = 0n;
+            oraclePriceByAsset[asset] = {
+                price: price.toString(),
+                timestampSeconds: tx.fetchedAt,
+            };
+        });
+    }
+    const ctx = {
+        contract: topLevel.contract,
+        fn: topLevel.fn,
+        args: topLevel.args.map(cloneScVal),
+        atLedger: tx.ledgerSequence,
+        nowSeconds: tx.fetchedAt,
+        amountByToken,
+        windowSpentByToken: {},
+        invocationCountByWindow: {},
+        oraclePriceByAsset,
+    };
+    if (opts.validUntilLedger !== undefined) {
+        ctx.validUntilLedger = opts.validUntilLedger;
+    }
+    return ctx;
+}
+function cloneScVal(value, depth = 0) {
+    // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+    // payload cannot RangeError the JS stack during context building. Over-depth
+    // throws a ToolError-shaped error that the simulator's existing try/catch
+    // converts to a structured `{ok:false, error}` (not a thrown RangeError).
+    if (value.type === 'vec') {
+        if (depth >= types_ts_1.MAX_SCVAL_CLONE_DEPTH) {
+            throw cloneDepthError(value);
+        }
+        return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) };
+    }
+    return { ...value };
+}
+function cloneDepthError(value) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${types_ts_1.MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'SIMULATION_ERROR';
+    err.severity = 'error';
+    err.retryable = false;
+    err.depthContext = value.type;
+    throw err;
+}
+function visitOracleLeaves(node, visit) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                visitOracleLeaves(child, visit);
+            return;
+        case 'not':
+            visitOracleLeaves(node.child, visit);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte': {
+            const leftLeaf = node.left;
+            const rightLeaf = node.right;
+            let oracleAsset;
+            let literal;
+            if (leftLeaf.kind === 'oracle_price') {
+                oracleAsset = leftLeaf.asset;
+                literal = oracleLiteralFromLeaf(rightLeaf);
+            }
+            else if (rightLeaf.kind === 'oracle_price') {
+                oracleAsset = rightLeaf.asset;
+                literal = oracleLiteralFromLeaf(leftLeaf);
+            }
+            if (oracleAsset === undefined || literal === undefined)
+                return;
+            visit(oracleAsset, node.op, literal);
+            return;
+        }
+        case 'in':
+            return;
+    }
+}
+function oracleLiteralFromLeaf(leaf) {
+    if (leaf.kind !== 'literal_i128')
+        return undefined;
+    try {
+        return BigInt(leaf.value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function simulationError(message, cause) {
+    const error = {
+        code: 'SIMULATION_ERROR',
+        message,
+        severity: 'error',
+        retryable: false,
+    };
+    if (cause !== undefined)
+        error.details = { cause: String(cause) };
+    return error;
+}

package/dist-cjs/verify/verify.d.ts

@@ -0,0 +1,21 @@
+import type { ToolResponse } from '../errors.ts';
+import type { PredicateNode, RecordedTransaction } from '../types.ts';
+/** Options for `verifyPolicy`. Mirrors the orchestrator's permit-context
+ *  knobs (expiry; oracle fixture) so verify sees the same shape
+ *  `simulatePolicy` sees. */
+export interface VerifyOptions {
+    validUntilLedger?: number;
+    oraclePricesByAsset?: Record<string, {
+        price: string;
+        timestampSeconds: number;
+    } | {
+        error: 'stale' | 'missing' | 'deviation' | 'paused' | 'decimals' | 'fingerprint';
+    }>;
+}
+/** Run the static minimality check on a proposed predicate + recorded tx.
+ *  Returns `{ ok: true }` when the predicate is minimal (every top-level
+ *  conjunct carries load) and `VERIFICATION_FAILED` when a conjunct could
+ *  be dropped without losing a deny-case. The dropped conjuncts are
+ *  reported in `details.droppedConstraints` so the caller can render a
+ *  review-card warning. */
+export declare function verifyPolicy(predicate: PredicateNode, permitTx: RecordedTransaction, opts?: VerifyOptions): ToolResponse<true>;

package/dist-cjs/verify/verify.js

@@ -0,0 +1,192 @@
+"use strict";
+// src/verify/verify.ts - the static minimality check for `verify_policy`.
+//
+// `verifyPolicy` proves the policy is MINIMAL: no top-level conjunct is
+// load-bearing-free. It is the static sibling of `simulatePolicy` and emits
+// `VERIFICATION_FAILED` (not `SIMULATION_ERROR`) on failure. The boundary is
+// pinned:
+//
+//   - `VERIFICATION_FAILED`  = STATIC minimality check failed. The policy is
+//     structurally over-broad: a constraint could be dropped without losing
+//     a deny-case. Surfaced by `verifyPolicy`. Runtime evaluation is not
+//     part of this check; the policy may evaluate to a permit/deny just
+//     fine, the failure is shape-only.
+//
+//   - `SIMULATION_ERROR`     = RUNTIME evaluation failed (see simulate.ts).
+//     This module never emits SIMULATION_ERROR. A minimality failure is
+//     never a simulation error and vice-versa.
+//
+// Algorithm:
+//   1. Build the permit EvalContext from `permitTx` (mirror of the
+//      orchestrator's helper so verify is self-contained).
+//   2. Run `minimize(predicate, permitCtx)` to strip load-bearing-free
+//      top-level conjuncts (only `and` predicates are minimisable; other
+//      shapes are returned unchanged by `minimize`).
+//   3. If the minimised tree has fewer top-level conjuncts than the input,
+//      return `VERIFICATION_FAILED` listing the dropped conjuncts by their
+//      structural fingerprint.
+//   4. Otherwise `{ ok: true }`.
+//
+// Determinism: same `(predicate, permitTx)` -> byte-identical verdict.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyPolicy = verifyPolicy;
+const minimize_ts_1 = require("../synth/minimize.js");
+const types_ts_1 = require("../types.js");
+/** Run the static minimality check on a proposed predicate + recorded tx.
+ *  Returns `{ ok: true }` when the predicate is minimal (every top-level
+ *  conjunct carries load) and `VERIFICATION_FAILED` when a conjunct could
+ *  be dropped without losing a deny-case. The dropped conjuncts are
+ *  reported in `details.droppedConstraints` so the caller can render a
+ *  review-card warning. */
+function verifyPolicy(predicate, permitTx, opts = {}) {
+    const topLevel = permitTx.invocations[0];
+    if (!topLevel) {
+        return {
+            ok: false,
+            error: verificationFailed('recorded transaction has no top-level invocation to verify against', { droppedConstraints: [] }),
+        };
+    }
+    let permitCtx;
+    try {
+        permitCtx = buildPermitContextForVerify(permitTx, topLevel, opts);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: verificationFailed(`could not build permit evaluation context: ${e.message}`, { droppedConstraints: [] }),
+        };
+    }
+    // `minimize` only reduces `and` predicates; other shapes are returned
+    // unchanged. A non-`and` predicate therefore trivially passes the static
+    // minimality check (its top-level structure carries no removable
+    // conjuncts). The runtime harness in `simulatePolicy` covers the
+    // OR / NOT / comparison shapes.
+    const minimised = (0, minimize_ts_1.minimize)(predicate, permitCtx);
+    // Drop count: only meaningful for `and`. For other shapes we already
+    // returned the input unchanged; report ok.
+    if (predicate.op !== 'and' || minimised.op !== 'and') {
+        if (!structuralEqual(predicate, minimised)) {
+            return {
+                ok: false,
+                error: verificationFailed('minimizer returned a structurally different tree for a non-and predicate', { droppedConstraints: [fingerprint(minimised)] }),
+            };
+        }
+        return { ok: true, data: true };
+    }
+    const inputChildren = predicate.children;
+    const minimisedChildren = minimised.children;
+    if (minimisedChildren.length >= inputChildren.length) {
+        return { ok: true, data: true };
+    }
+    // Over-broad: identify the dropped conjuncts by structural fingerprint
+    // (so the review card can quote exactly which constraint was redundant).
+    // We use a multiset comparison because two structurally identical
+    // conjuncts (e.g. a duplicate `call_fn == transfer`) collapse to the
+    // same fingerprint - the dropped item is the one whose fingerprint
+    // count drops between input and minimised.
+    const inputCounts = fingerprintCounts(inputChildren);
+    const minimisedCounts = fingerprintCounts(minimisedChildren);
+    const dropped = [];
+    for (const [fp, count] of inputCounts) {
+        const kept = minimisedCounts.get(fp) ?? 0;
+        for (let i = 0; i < count - kept; i++)
+            dropped.push(fp);
+    }
+    return {
+        ok: false,
+        error: verificationFailed(`policy is structurally over-broad: ${dropped.length} redundant conjunct(s) can be dropped without losing a deny case`, { droppedConstraints: dropped }),
+    };
+}
+function buildPermitContextForVerify(tx, topLevel, opts) {
+    const amountByToken = {};
+    const totals = new Map();
+    for (const m of tx.tokenMovements) {
+        const current = totals.get(m.token) ?? 0n;
+        totals.set(m.token, current + BigInt(m.amount));
+    }
+    for (const [token, total] of totals) {
+        amountByToken[token] = total.toString();
+    }
+    const oraclePriceByAsset = {};
+    if (opts.oraclePricesByAsset) {
+        for (const [asset, entry] of Object.entries(opts.oraclePricesByAsset)) {
+            oraclePriceByAsset[asset] = entry;
+        }
+    }
+    const ctx = {
+        contract: topLevel.contract,
+        fn: topLevel.fn,
+        args: topLevel.args.map(cloneScVal),
+        atLedger: tx.ledgerSequence,
+        nowSeconds: tx.fetchedAt,
+        amountByToken,
+        windowSpentByToken: {},
+        invocationCountByWindow: {},
+        oraclePriceByAsset,
+    };
+    if (opts.validUntilLedger !== undefined) {
+        ctx.validUntilLedger = opts.validUntilLedger;
+    }
+    return ctx;
+}
+function cloneScVal(value, depth = 0) {
+    // Recursion is bounded by MAX_SCVAL_CLONE_DEPTH so a hand-crafted nested-vec
+    // payload cannot RangeError the JS stack during context building. Over-depth
+    // throws a ToolError-shaped error that the verifier's existing try/catch
+    // converts to a structured `{ok:false, error}` (not a thrown RangeError).
+    if (value.type === 'vec') {
+        if (depth >= types_ts_1.MAX_SCVAL_CLONE_DEPTH) {
+            throw cloneDepthError(value);
+        }
+        return { type: 'vec', value: value.value.map((v) => cloneScVal(v, depth + 1)) };
+    }
+    return { ...value };
+}
+function cloneDepthError(value) {
+    const err = new Error(`ScVal clone depth exceeds MAX_SCVAL_CLONE_DEPTH (${types_ts_1.MAX_SCVAL_CLONE_DEPTH})`);
+    err.code = 'VERIFICATION_FAILED';
+    err.severity = 'error';
+    err.retryable = false;
+    err.depthContext = value.type;
+    throw err;
+}
+function fingerprint(node) {
+    return JSON.stringify(node, replacer);
+}
+/** Multiset fingerprint counts for a list of conjuncts. Two structurally
+ *  identical conjuncts (e.g. a duplicate `call_fn == transfer`) each
+ *  contribute their own count. The minimiser may drop one of them; we
+ *  surface exactly the surplus via the count difference. */
+function fingerprintCounts(children) {
+    const counts = new Map();
+    for (const child of children) {
+        const fp = fingerprint(child);
+        counts.set(fp, (counts.get(fp) ?? 0) + 1);
+    }
+    return counts;
+}
+/** Deterministic JSON key order for fingerprinting. Object keys are sorted
+ *  recursively so the same shape produces the same string. */
+function replacer(_key, value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        const sorted = {};
+        for (const k of Object.keys(obj).sort()) {
+            sorted[k] = obj[k];
+        }
+        return sorted;
+    }
+    return value;
+}
+function structuralEqual(a, b) {
+    return fingerprint(a) === fingerprint(b);
+}
+function verificationFailed(message, details) {
+    return {
+        code: 'VERIFICATION_FAILED',
+        message,
+        severity: 'error',
+        retryable: false,
+        details,
+    };
+}

package/package.json

@@ -1,22 +1,57 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
+  "engines": {
+    "node": ">=22.12",
+    "bun": ">=1.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/untangledfinance/oz-policy-builder.git",
+    "directory": "packages/policy-synth"
+  },
+  "homepage": "https://github.com/untangledfinance/oz-policy-builder#readme",
+  "bugs": {
+    "url": "https://github.com/untangledfinance/oz-policy-builder/issues"
+  },
+  "keywords": [
+    "stellar",
+    "soroban",
+    "openzeppelin",
+    "policy",
+    "smart-account",
+    "authorization"
+  ],
+  "sideEffects": false,
+  "author": {
+    "name": "Untangled Finance Limited",
+    "url": "https://untangled.finance"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "bun": "./src/index.ts",
       "import": "./dist/index.js",
+      "require": "./dist-cjs/index.js",
       "default": "./dist/index.js"
     },
+    "./run": {
+      "types": "./dist/run/index.d.ts",
+      "bun": "./src/run/index.ts",
+      "import": "./dist/run/index.js",
+      "require": "./dist-cjs/run/index.js",
+      "default": "./dist/run/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "dist-cjs",
     "src",
     "!src/**/*.test.ts"
   ],
@@ -25,10 +60,15 @@
   },
   "scripts": {
     "test": "bun test",
-    "build": "tsc -p tsconfig.build.json"
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.build.cjs.json && node scripts/write-cjs-package-json.cjs",
+    "build:esm": "tsc -p tsconfig.build.json",
+    "build:cjs": "tsc -p tsconfig.build.cjs.json && node scripts/write-cjs-package-json.cjs",
+    "prepublishOnly": "bun run build && bun test",
+    "prepack": "bun run build"
   },
   "dependencies": {
-    "@stellar/stellar-sdk": "14.4.0"
+    "@stellar/stellar-sdk": "14.4.0",
+    "zod": "3.25.76"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",

package/src/codegen/template.ts

@@ -67,10 +67,10 @@ function renderUncovered(uncovered: string[]): string {
  *
  *  Same `(spec, name)` always produces byte-identical output. */
 export function generateRust(spec: EscapeHatchSpec, name: string): string {
-  const contract = spec.contract
-  const fnName = spec.fnName ?? 'enforce'
+  const _contract = spec.contract
+  const _fnName = spec.fnName ?? 'enforce'
   const structName = asRustIdent(name)
-  const dataKeyName = `${asRustIdent(name)}_data`
+  const _dataKeyName = `${asRustIdent(name)}_data`
   const uncoveredBlock = renderUncovered(spec.uncovered)
 
   return `// Auto-generated by the OZ Policy Builder codegen escape hatch.