@crediolabs/policy-synth 0.3.0 → 0.4.0

package/dist/verify/simulate.js

@@ -1,172 +0,0 @@
-// 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
-//     without a satisfying price fixture, or a non-runtime propagation (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.
-import { generateCases } from "../synth/deny-cases.js";
-import { evaluate } from "../synth/evaluate.js";
-import { MAX_SCVAL_CLONE_DEPTH } from "../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
- *  `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. */
-export 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(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 = 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 = generateCases(evaluatePredicate, permitCtx);
-    for (const deny of cases.denies) {
-        let result;
-        try {
-            result = 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(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 ctx = {
-        contract: topLevel.contract,
-        fn: topLevel.fn,
-        args: topLevel.args.map(cloneScVal),
-        atLedger: tx.ledgerSequence,
-        nowSeconds: tx.fetchedAt,
-        amountByToken,
-        windowSpentByToken: {},
-    };
-    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 >= 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 (${MAX_SCVAL_CLONE_DEPTH})`);
-    err.code = 'SIMULATION_ERROR';
-    err.severity = 'error';
-    err.retryable = false;
-    err.depthContext = value.type;
-    throw err;
-}
-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/verify/verify.d.ts

@@ -1,15 +0,0 @@
-import type { ToolResponse } from '../errors.ts';
-import type { PredicateNode, RecordedTransaction } from '../types.ts';
-/** Options for `verifyPolicy`. Mirrors the orchestrator's permit-context
- *  knobs (expiry) so verify sees the same shape
- *  `simulatePolicy` sees. */
-export interface VerifyOptions {
-    validUntilLedger?: number;
-}
-/** 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/verify/verify.js

@@ -1,181 +0,0 @@
-// 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.
-import { minimize } from "../synth/minimize.js";
-import { MAX_SCVAL_CLONE_DEPTH } from "../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. */
-export 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 = 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 ctx = {
-        contract: topLevel.contract,
-        fn: topLevel.fn,
-        args: topLevel.args.map(cloneScVal),
-        atLedger: tx.ledgerSequence,
-        nowSeconds: tx.fetchedAt,
-        amountByToken,
-        windowSpentByToken: {},
-    };
-    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 >= 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 (${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/dist-cjs/adapters/interpreter/index.d.ts

@@ -1 +0,0 @@
-export { createInterpreterAdapter, type InterpreterAdapterConfig, PLACEHOLDER_INTERPRETER_ADDRESS, } from './adapter.ts';

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

@@ -1,7 +0,0 @@
-"use strict";
-// src/adapters/interpreter/index.ts - re-export the interpreter-policy CustodyAdapter.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PLACEHOLDER_INTERPRETER_ADDRESS = exports.createInterpreterAdapter = void 0;
-var adapter_ts_1 = require("./adapter.js");
-Object.defineProperty(exports, "createInterpreterAdapter", { enumerable: true, get: function () { return adapter_ts_1.createInterpreterAdapter; } });
-Object.defineProperty(exports, "PLACEHOLDER_INTERPRETER_ADDRESS", { enumerable: true, get: function () { return adapter_ts_1.PLACEHOLDER_INTERPRETER_ADDRESS; } });

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

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