@crediolabs/policy-synth 0.1.0

package/dist/synth/lower.js

@@ -0,0 +1,116 @@
+// src/synth/lower.ts - lower a RecordedTransaction to IntentFacts.
+//
+// Reads the top-level invocations only (the single authorized call that
+// `Policy::enforce` receives; v1 grammar does not walk sub-invocations) and
+// the recorded token movements. Produces the deterministic facts the synth
+// reasons over: distinct call targets, functions per target, cumulative spend
+// per token (outgoing movements from the recorded source account only),
+// authorising signers, an optional shared-router marker when multiple top-level
+// invocations hit the same contract, and the per-contract hop-path lists for
+// router calls (SoroSwap `path`).
+/** Lower a recorded transaction to the canonical IntentFacts. Pure (no
+ *  randomness, no clock); same `RecordedTransaction` -> byte-identical facts. */
+export function lower(tx) {
+    const invocations = tx.invocations;
+    const callTargets = uniqueOrdered(invocations.map((i) => i.contract));
+    const functionsByContract = groupFunctionsByContract(invocations);
+    const spendByToken = aggregateOutgoingSpend(tx.tokenMovements, tx.sourceAccount);
+    const allowedPaths = extractPathsByContract(invocations);
+    const sharedRouter = inferSharedRouter(invocations);
+    const facts = {
+        callTargets,
+        functionsByContract,
+        spendByToken,
+        signers: [...tx.signers],
+    };
+    if (sharedRouter)
+        facts.sharedRouter = sharedRouter;
+    if (Object.keys(allowedPaths).length > 0)
+        facts.allowedPaths = allowedPaths;
+    return facts;
+}
+/** Preserve first-seen ordering, drop duplicates. */
+function uniqueOrdered(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (seen.has(item))
+            continue;
+        seen.add(item);
+        out.push(item);
+    }
+    return out;
+}
+/** Group the function names invoked per top-level contract. Order preserved
+ *  per contract in first-seen order. */
+function groupFunctionsByContract(invocations) {
+    const out = {};
+    for (const inv of invocations) {
+        const existing = out[inv.contract] ?? [];
+        if (!existing.includes(inv.fn))
+            existing.push(inv.fn);
+        out[inv.contract] = existing;
+    }
+    return out;
+}
+/** Sum outgoing TokenMovement amounts per token, where `from === source`.
+ *  BigInt throughout; never lossy. Movements whose `from` does not match the
+ *  recorded source account are NOT counted (incoming yield, refund, etc.). */
+function aggregateOutgoingSpend(movements, sourceAccount) {
+    const totals = new Map();
+    for (const m of movements) {
+        if (m.from !== sourceAccount)
+            continue;
+        const current = totals.get(m.token) ?? 0n;
+        totals.set(m.token, current + BigInt(m.amount));
+    }
+    const out = {};
+    for (const [token, total] of totals) {
+        out[token] = total.toString();
+    }
+    return out;
+}
+/** Walk the top-level invocations looking for a `vec` arg whose elements are
+ *  addresses (the SoroSwap `path` shape). Only the FIRST arg in each
+ *  invocation is examined in v1 - the recorder emits the top-level args
+ *  in declaration order and the only contract-call convention we bind by is
+ *  the router's first vec-arg path. */
+function extractPathsByContract(invocations) {
+    const out = {};
+    for (const inv of invocations) {
+        const path = findAddressVec(inv.args);
+        if (path) {
+            const existing = out[inv.contract] ?? [];
+            existing.push(path);
+            out[inv.contract] = existing;
+        }
+    }
+    return out;
+}
+function findAddressVec(args) {
+    for (const arg of args) {
+        if (arg.type === 'vec') {
+            const addresses = arg.value.filter((v) => v.type === 'address');
+            if (addresses.length === arg.value.length && addresses.length > 0) {
+                return addresses.map((a) => a.value);
+            }
+        }
+    }
+    return null;
+}
+/** When multiple top-level invocations share the same target contract, that
+ *  contract is the shared router. Single-call transactions return undefined
+ *  (the default flow doesn't need the marker). */
+function inferSharedRouter(invocations) {
+    if (invocations.length < 2)
+        return undefined;
+    const counts = new Map();
+    for (const inv of invocations) {
+        counts.set(inv.contract, (counts.get(inv.contract) ?? 0) + 1);
+    }
+    for (const [contract, count] of counts) {
+        if (count >= 2)
+            return contract;
+    }
+    return undefined;
+}

package/dist/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/synth/scope.js

@@ -0,0 +1,77 @@
+// 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.
+/** 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 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. */
+export 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/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/synth/synthesize-from-mandate.js

@@ -0,0 +1,34 @@
+// 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` as
+// Path-B markers rather than failing the call - the covered primitives still
+// install; the uncovered ones are reported.
+import { createOzAdapter } from "../adapters/oz/adapter.js";
+import { mandateToPolicyIR } from "../mandate/to-ir.js";
+const PATH_B_PREFIX = 'Path B (not covered by OZ built-in primitives): ';
+export function synthesizeFromMandate(spec, ozConfig) {
+    const ir = mandateToPolicyIR(spec);
+    const adapter = 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) => `${PATH_B_PREFIX}${u}`),
+    };
+    return { ok: true, data: proposed };
+}

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

@@ -0,0 +1,17 @@
+import type { OzAdapterConfig } from '../adapters/oz/adapter.ts';
+import type { ToolResponse } from '../errors.ts';
+import { type Network, type ProposedPolicy, type RecordedTransaction } from '../types.ts';
+import { type ComposeUserResponses } from './compose-from-recording.ts';
+/** Top-level orchestrator inputs. `userResponses` carries the LLM-collected
+ *  answers to the ambiguity prompts (windowSeconds, validUntilLedger,
+ *  limitAmount, invocationLimit). `confidenceOverride` relaxes the recorder's
+ *  gate. */
+export interface SynthesizeFromRecordingOptions {
+    network: Network;
+    userResponses?: ComposeUserResponses;
+    confidenceOverride?: {
+        threshold: number;
+    };
+}
+/** Synthesize a ProposedPolicy from a recorded transaction. */
+export declare function synthesizeFromRecording(tx: RecordedTransaction, opts: SynthesizeFromRecordingOptions, ozConfig: OzAdapterConfig): ToolResponse<ProposedPolicy>;

package/dist/synth/synthesize-from-recording.js

@@ -0,0 +1,178 @@
+// src/synth/synthesize-from-recording.ts - recording-path orchestrator.
+//
+// `synthesizeFromRecording` is the second Synthesizer front-end: it INFERS a
+// bounded policy from a `RecordedTransaction` via the same `PolicyIR` +
+// `createOzAdapter` pair used by the deterministic Mandate path. The flow:
+//
+//   1. parseConfidence gate - refuse when `overall < threshold` (default 1.0;
+//      the caller may relax via `confidenceOverride.threshold`).
+//   2. `lower(tx)` -> IntentFacts.
+//   3. `decideScope(facts)` -> scope | SCOPE_UNRESOLVED ToolError.
+//   4. `composeFromRecording(facts, scope, opts)` -> PolicyIR + ambiguities.
+//   5. `ozAdapter.compile(ir)` -> CompileResult.
+//   6. Assemble ProposedPolicy carrying parseConfidence (from tx), warnings
+//      (the OZ `uncovered` Path-B markers, prefixed), and ambiguities
+//      (DURATION_UNSPECIFIED etc.).
+//
+// Determinism: same (tx, opts, ozConfig) -> byte-identical ProposedPolicy.
+// No randomness, no clock, no globals.
+import { createOzAdapter } from "../adapters/oz/adapter.js";
+import { SOROBAN_LIMITS, } from "../types.js";
+import { composeFromRecording, } from "./compose-from-recording.js";
+import { lower } from "./lower.js";
+import { decideScope } from "./scope.js";
+const PATH_B_PREFIX = 'Path B (not covered by OZ built-in primitives): ';
+/** Synthesize a ProposedPolicy from a recorded transaction. */
+export function synthesizeFromRecording(tx, opts, ozConfig) {
+    // 0. validate inputs (fail closed - never synthesize from garbage).
+    const invalid = validateOptions(opts);
+    if (invalid)
+        return { ok: false, error: invalid };
+    // 1. parseConfidence gate.
+    const threshold = opts.confidenceOverride?.threshold ?? tx.parseConfidence.thresholdUsed;
+    if (tx.parseConfidence.overall < threshold) {
+        return {
+            ok: false,
+            error: {
+                code: 'RECORDING_VALIDATION_FAILED',
+                message: `parseConfidence ${tx.parseConfidence.overall} < threshold ${threshold}`,
+                severity: 'error',
+                retryable: false,
+                details: tx.parseConfidence,
+            },
+        };
+    }
+    // Bound the recording size fail-closed (defense-in-depth for direct callers;
+    // the MCP schema caps this too).
+    if (tx.invocations.length > SOROBAN_LIMITS.maxInvocations) {
+        return {
+            ok: false,
+            error: {
+                code: 'RECORDING_VALIDATION_FAILED',
+                message: `recorded transaction has ${tx.invocations.length} invocations, exceeding the cap of ${SOROBAN_LIMITS.maxInvocations}`,
+                severity: 'error',
+                retryable: false,
+            },
+        };
+    }
+    // 2. lower.
+    const facts = lower(tx);
+    // 3. decideScope.
+    const scopeRes = decideScope(facts, {
+        network: opts.network,
+        ...(opts.userResponses?.validUntilLedger !== undefined
+            ? { validUntilLedger: opts.userResponses.validUntilLedger }
+            : {}),
+    });
+    if (!scopeRes.ok)
+        return scopeRes;
+    const scope = scopeRes.data;
+    if (scope.kind !== 'call_contract') {
+        // A default scope on the recording-path is not currently a Path-A flow;
+        // surface SYNTHESIS_ERROR so the orchestrator never silently emits an
+        // over-broad default-scoped policy.
+        return {
+            ok: false,
+            error: {
+                code: 'SYNTHESIS_ERROR',
+                message: 'recording path requires a scoped contract; no default-scoped policies emitted',
+                severity: 'error',
+                retryable: false,
+            },
+        };
+    }
+    // 4. compose.
+    const topLevel = tx.invocations[0] ?? null;
+    const composeOpts = {
+        network: opts.network,
+        ...(opts.userResponses !== undefined ? { userResponses: opts.userResponses } : {}),
+    };
+    const composed = composeFromRecording(facts, scope.contract, topLevel, composeOpts);
+    // 5. OZ compile.
+    const adapter = createOzAdapter(ozConfig);
+    const compileRes = adapter.compile(composed.ir);
+    if (!compileRes.proposed) {
+        return {
+            ok: false,
+            error: {
+                code: 'SYNTHESIS_ERROR',
+                message: `recording lowered to no installable OZ policy: ${compileRes.uncovered.join('; ')}`,
+                severity: 'error',
+                retryable: false,
+                details: { uncovered: compileRes.uncovered },
+            },
+        };
+    }
+    // 6. assemble ProposedPolicy.
+    const proposed = {
+        ...compileRes.proposed,
+        parseConfidence: { ...tx.parseConfidence },
+        warnings: [
+            ...compileRes.uncovered.map((u) => `${PATH_B_PREFIX}${u}`),
+            ...composed.warnings.map((w) => `${PATH_B_PREFIX}${w}`),
+        ],
+        ambiguities: mergeAmbiguities(composed.ambiguities, scope.ambiguities),
+    };
+    return { ok: true, data: proposed };
+}
+/** Reject non-sane inputs before any policy is synthesized. windowSeconds /
+ *  validUntilLedger / invocationLimit must be positive integers; limitAmount a
+ *  positive i128 decimal string; network mainnet|testnet. */
+function validateOptions(opts) {
+    if (opts.network !== 'mainnet' && opts.network !== 'testnet') {
+        return synthesisError(`network must be 'mainnet' or 'testnet', got: ${String(opts.network)}`);
+    }
+    // A confidenceOverride outside [0, 1] would disable the recorder gate (a
+    // negative threshold can never be exceeded), so reject it fail-closed.
+    const co = opts.confidenceOverride?.threshold;
+    if (co !== undefined && (!Number.isFinite(co) || co < 0 || co > 1)) {
+        return synthesisError(`confidenceOverride.threshold must be a finite number within [0, 1], got: ${co}`);
+    }
+    const ur = opts.userResponses;
+    if (ur) {
+        if (ur.windowSeconds !== undefined && !isPositiveInt(ur.windowSeconds)) {
+            return synthesisError(`windowSeconds must be a positive integer, got: ${ur.windowSeconds}`);
+        }
+        if (ur.validUntilLedger !== undefined &&
+            (!isPositiveInt(ur.validUntilLedger) || ur.validUntilLedger > SOROBAN_LIMITS.u32Max)) {
+            return synthesisError(`validUntilLedger must be a positive u32 ledger sequence (<= ${SOROBAN_LIMITS.u32Max}), got: ${ur.validUntilLedger}`);
+        }
+        if (ur.invocationLimit !== undefined && !isPositiveInt(ur.invocationLimit)) {
+            return synthesisError(`invocationLimit must be a positive integer, got: ${ur.invocationLimit}`);
+        }
+        if (ur.limitAmount !== undefined && !isPositiveI128(ur.limitAmount)) {
+            return synthesisError(`limitAmount must be a positive i128 decimal string, got: ${ur.limitAmount}`);
+        }
+    }
+    return null;
+}
+function isPositiveInt(n) {
+    return Number.isInteger(n) && n > 0;
+}
+/** True when `s` is a canonical positive decimal integer (i128-safe via BigInt). */
+function isPositiveI128(s) {
+    if (!/^[0-9]+$/.test(s))
+        return false;
+    try {
+        return BigInt(s) > 0n;
+    }
+    catch {
+        return false;
+    }
+}
+function synthesisError(message) {
+    return { code: 'SYNTHESIS_ERROR', message, severity: 'error', retryable: false };
+}
+function mergeAmbiguities(...lists) {
+    const out = [];
+    const seen = new Set();
+    for (const list of lists) {
+        for (const a of list) {
+            if (seen.has(a.code))
+                continue;
+            seen.add(a.code);
+            out.push(a);
+        }
+    }
+    return out;
+}