@crediolabs/policy-synth 0.1.4 → 0.1.6

package/dist-cjs/synth/minimize.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.minimize = minimize;
+const deny_cases_ts_1 = require("./deny-cases.js");
+const harness_ts_1 = require("./harness.js");
+/** Remove top-level conjuncts only when the current and regenerated batteries still deny. */
+function minimize(predicate, permitCtx, dimensions) {
+    if (predicate.op !== 'and')
+        return predicate;
+    let children = [...predicate.children];
+    let index = 0;
+    while (index < children.length) {
+        const current = { op: 'and', children };
+        const currentCases = (0, deny_cases_ts_1.generateCases)(current, permitCtx, dimensions);
+        const candidateChildren = children.filter((_, childIndex) => childIndex !== index);
+        const candidate = { op: 'and', children: candidateChildren };
+        const candidateCases = (0, deny_cases_ts_1.generateCases)(candidate, permitCtx, dimensions);
+        const verificationCases = {
+            permit: candidateCases.permit,
+            denies: mergeDenyCases(currentCases.denies, candidateCases.denies),
+        };
+        if ((0, harness_ts_1.runHarness)(candidate, verificationCases).ok) {
+            children = candidateChildren;
+            continue;
+        }
+        index += 1;
+    }
+    return { op: 'and', children };
+}
+function mergeDenyCases(current, candidate) {
+    const merged = [];
+    const seen = new Set();
+    for (const deny of [...current, ...candidate]) {
+        const key = `${deny.dimension}:${JSON.stringify(deny.ctx)}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(deny);
+    }
+    return merged;
+}

package/dist-cjs/synth/predicate-literals.d.ts

@@ -0,0 +1,5 @@
+import type { PredicateLeaf } from '../types.ts';
+/** BigInt value of a numeric-integer literal leaf (`literal_i128` / `literal_u64`
+ *  / `literal_u32`), or null for a non-numeric literal (address / symbol / bytes
+ *  / vec). Callers fail closed on null. */
+export declare function literalNumericBigInt(leaf: PredicateLeaf): bigint | null;

package/dist-cjs/synth/predicate-literals.js

@@ -0,0 +1,28 @@
+"use strict";
+// src/synth/predicate-literals.ts - read scalar values out of predicate literal leaves.
+//
+// Small shared helpers for interpreting a `PredicateLeaf` literal. Kept out of
+// `evaluate.ts` so the evaluator stays focused on the deny-order semantics; the
+// deny-case generator uses the same reader so both sides agree on what a numeric
+// literal means.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.literalNumericBigInt = literalNumericBigInt;
+/** BigInt value of a numeric-integer literal leaf (`literal_i128` / `literal_u64`
+ *  / `literal_u32`), or null for a non-numeric literal (address / symbol / bytes
+ *  / vec). Callers fail closed on null. */
+function literalNumericBigInt(leaf) {
+    switch (leaf.kind) {
+        case 'literal_i128':
+        case 'literal_u64':
+            try {
+                return BigInt(leaf.value);
+            }
+            catch {
+                return null;
+            }
+        case 'literal_u32':
+            return BigInt(leaf.value);
+        default:
+            return null;
+    }
+}

package/dist-cjs/synth/scope.d.ts

@@ -0,0 +1,26 @@
+import type { ToolResponse } from '../errors.ts';
+import type { AmbiguityPrompt, ContextRuleDraft, Network } from '../types.ts';
+import type { IntentFacts } from './lower.ts';
+export type ScopeDecision = {
+    kind: 'call_contract';
+    contract: string;
+    ambiguities: AmbiguityPrompt[];
+} | {
+    kind: 'default';
+    ambiguities: AmbiguityPrompt[];
+};
+/** Options for the scope decision. `validUntilLedger` may be supplied via the
+ *  synth opts; when absent the DURATION_UNSPECIFIED ambiguity is surfaced so
+ *  the LLM can ask the user rather than the synth fabricating a window. */
+export interface DecideScopeOptions {
+    network: Network;
+    validUntilLedger?: number;
+}
+/** Decide the OZ context-rule scope. Returns `ScopeDecision` on success or a
+ *  `ToolError` with code `SCOPE_UNRESOLVED` when the recorded tx spans
+ *  multiple unrelated call targets. */
+export declare function decideScope(facts: IntentFacts, opts: DecideScopeOptions): ToolResponse<ScopeDecision>;
+/** Helper to project a `ScopeDecision` into the OZ `ContextRuleDraft`
+ *  contextRuleType shape consumed by `composeFromRecording` and the OZ
+ *  adapter. */
+export declare function scopeToContextRuleType(scope: ScopeDecision): ContextRuleDraft['contextRuleType'];

package/dist-cjs/synth/scope.js

@@ -0,0 +1,81 @@
+"use strict";
+// src/synth/scope.ts - decide the OZ context-rule scope from IntentFacts.
+//
+// Pure decision function. Three branches:
+//   - single call target                   -> CallContract(target)
+//   - multiple targets w/ sharedRouter     -> CallContract(sharedRouter)
+//   - multiple unrelated targets           -> SCOPE_UNRESOLVED ToolError
+//
+// `decideScope` also surfaces the `DURATION_UNSPECIFIED` ambiguity when the
+// caller has NOT supplied a validUntilLedger - the synth never fabricates a
+// window. The orchestrator is responsible for assembling any
+// `AmbiguityPrompt[]` from this and other decision points into the
+// `ProposedPolicy.ambiguities` field.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideScope = decideScope;
+exports.scopeToContextRuleType = scopeToContextRuleType;
+/** Decide the OZ context-rule scope. Returns `ScopeDecision` on success or a
+ *  `ToolError` with code `SCOPE_UNRESOLVED` when the recorded tx spans
+ *  multiple unrelated call targets. */
+function decideScope(facts, opts) {
+    const ambiguities = [];
+    if (opts.validUntilLedger === undefined) {
+        ambiguities.push({
+            code: 'DURATION_UNSPECIFIED',
+            question: 'No expiry supplied for this policy. What `validUntilLedger` should the policy carry?',
+        });
+    }
+    // Single target -> scope directly.
+    if (facts.callTargets.length === 1) {
+        const contract = facts.callTargets[0];
+        if (contract === undefined) {
+            return {
+                ok: false,
+                error: scopeUnresolvedError(facts, 'no contract address resolvable from the recording'),
+            };
+        }
+        return {
+            ok: true,
+            data: { kind: 'call_contract', contract, ambiguities },
+        };
+    }
+    // Multiple targets with a shared router -> scope by the router.
+    if (facts.sharedRouter) {
+        return {
+            ok: true,
+            data: {
+                kind: 'call_contract',
+                contract: facts.sharedRouter,
+                ambiguities,
+            },
+        };
+    }
+    // Multiple unrelated targets -> fail closed.
+    return {
+        ok: false,
+        error: scopeUnresolvedError(facts, `multiple unrelated call targets: ${facts.callTargets.join(', ')}`),
+    };
+}
+/** Helper to project a `ScopeDecision` into the OZ `ContextRuleDraft`
+ *  contextRuleType shape consumed by `composeFromRecording` and the OZ
+ *  adapter. */
+function scopeToContextRuleType(scope) {
+    return scope.kind === 'call_contract'
+        ? { kind: 'call_contract', contract: scope.contract }
+        : { kind: 'default' };
+}
+function scopeUnresolvedError(facts, message) {
+    return {
+        code: 'SCOPE_UNRESOLVED',
+        message,
+        severity: 'error',
+        retryable: false,
+        details: { callTargets: facts.callTargets, sharedRouter: facts.sharedRouter ?? null },
+        remediation: {
+            userQuestion: {
+                code: 'MULTIPLE_UNRELATED_TARGETS',
+                question: `Recording spans ${facts.callTargets.length} call targets (${facts.callTargets.join(', ')}). Which contract (or shared router) should this policy scope to?`,
+            },
+        },
+    };
+}

package/dist-cjs/synth/synthesize-from-mandate.d.ts

@@ -0,0 +1,5 @@
+import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
+import type { ToolResponse } from '../errors.ts';
+import type { MandateSpec } from '../mandate/types.ts';
+import type { ProposedPolicy } from '../types.ts';
+export declare function synthesizeFromMandate(spec: MandateSpec, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;

package/dist-cjs/synth/synthesize-from-mandate.js

@@ -0,0 +1,37 @@
+"use strict";
+// src/synth/synthesize-from-mandate.ts - the deterministic Mandate front-end.
+//
+// synthesizeFromMandate is the clean end-to-end demo path: a declarative
+// MandateSpec is lowered deterministically to a PolicyIR and compiled by the OZ
+// adapter to a ProposedPolicy. No decoding, no inference, so parseConfidence is
+// the full/not-applicable value. Constructs the OZ built-in primitives cannot
+// express (compile's `uncovered`) are surfaced in `ProposedPolicy.warnings`
+// rather than failing the call - the covered primitives still install; the
+// uncovered ones are reported.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeFromMandate = synthesizeFromMandate;
+const adapter_ts_1 = require("../adapters/oz/adapter.js");
+const to_ir_ts_1 = require("../mandate/to-ir.js");
+const UNCOVERED_PREFIX = 'Not covered by OZ built-in primitives: ';
+function synthesizeFromMandate(spec, ozConfig) {
+    const ir = (0, to_ir_ts_1.mandateToPolicyIR)(spec);
+    const adapter = (0, adapter_ts_1.createOzAdapter)(ozConfig);
+    const result = adapter.compile(ir);
+    if (!result.proposed) {
+        return {
+            ok: false,
+            error: {
+                code: 'SYNTHESIS_ERROR',
+                message: `mandate lowered to no installable OZ policy: ${result.uncovered.join('; ')}`,
+                severity: 'error',
+                retryable: false,
+                details: { uncovered: result.uncovered },
+            },
+        };
+    }
+    const proposed = {
+        ...result.proposed,
+        warnings: result.uncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
+    };
+    return { ok: true, data: proposed };
+}

package/dist-cjs/synth/synthesize-from-recording.d.ts

@@ -0,0 +1,49 @@
+import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
+import type { ToolError, ToolResponse } from '../errors.ts';
+import { type Network, type PredicateNode, type ProposedPolicy, type RecordedTransaction } from '../types.ts';
+import { type ComposeUserResponses } from './compose-from-recording.ts';
+/** Per-policy interpreter adapter config the caller opts into. Absent ->
+ *  recording path runs in week-1 mode (OZ adapter only, warnings for the
+ *  constraints OZ cannot express). */
+export interface InterpreterAdapterOptions {
+    /** The smart account this interpreter policy will be installed against.
+     *  Must be a C... contract address - the on-chain policy-bound account.
+     *  The G... source account from the recording is a separate concept. */
+    smartAccountAddress: string;
+    /** Per-rule install nonce (first install = 1). Defaults to 1. */
+    installNonce?: number;
+    /** Per-policy oracle overrides. Tighten-only vs the wasm defaults
+     *  (maxStalenessSeconds <= 600, maxDeviationBps <= 200); widening is
+     *  rejected at the options boundary. */
+    oracleParams?: {
+        maxStalenessSeconds?: number;
+        maxDeviationBps?: number;
+    };
+    /** @internal Test-only seam. When set, the orchestrator uses this
+     *  PredicateNode as the starting point for self-verify + minimise instead
+     *  of calling the interpreter adapter's compile(). Production callers MUST
+     *  NOT set this; the field exists so the self-verify pipeline can be
+     *  exercised on hand-crafted predicates (redundant conjuncts for
+     *  minimise, deliberately over-broad leaves for DENY_CASE_FAILURE). The
+     *  `smartAccountAddress` + `installNonce` + `oracleParams` are still
+     *  carried through so the emitted PolicyRef + PolicyDocument match the
+     *  recorded call shape. */
+    __testPredicateNode?: PredicateNode;
+}
+/** Top-level orchestrator inputs. `userResponses` carries the LLM-collected
+ *  answers to the ambiguity prompts (windowSeconds, validUntilLedger,
+ *  limitAmount, invocationLimit, oraclePriceBound, swapRecipientAllowlist).
+ *  `interpreter` opts the recording path into the interpreter adapter. */
+export interface SynthesizeFromRecordingOptions {
+    network: Network;
+    userResponses?: ComposeUserResponses;
+    confidenceOverride?: {
+        threshold: number;
+    };
+    interpreter?: InterpreterAdapterOptions;
+}
+export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;
+/** ToolError-shaped error helper used by the body to surface a structured
+ *  failure that the envelope converts to `{ok:false, error}`. */
+declare function throwToolError(code: ToolError['code'], message: string): never;
+export { throwToolError };