@crediolabs/policy-synth 0.1.4 → 0.1.6

package/dist-cjs/run/schemas.js

@@ -0,0 +1,226 @@
+"use strict";
+// packages/policy-synth/src/run/schemas.ts
+//
+// Zod schemas mirroring the policy-synth core domain types. These are the
+// public input / output shapes exposed over MCP and the CLI. They are kept
+// hand-written (rather than derived) because the MCP SDK needs a runtime
+// Zod object at the transport boundary; a drift test asserts they stay in
+// step with the TS source of truth.
+//
+// i128 amounts and other large integers are carried as base-10 decimal strings
+// end-to-end (no JS number coercion). Networks are pinned to the same closed
+// set the core defines. The discriminated union on `source` exposes BOTH
+// synthesize_policy front-ends through a single tool input.
+//
+// This module is the SINGLE source of truth for these shapes. The MCP package
+// imports them here so its tool-shape bindings stay in step; the CLI imports
+// them here so it can build the same args envelope the MCP transport builds.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolErrorSchema = exports.SynthesizePolicyInputSchema = exports.SynthesizePolicyRecordingInputSchema = exports.InterpreterOptionsSchema = exports.SynthesizePolicyMandateInputSchema = exports.RecordTransactionInputSchema = exports.OzAdapterConfigSchema = exports.ComposeUserResponsesSchema = exports.MandateSpecSchema = exports.RecordedTransactionSchema = exports.ParseConfidenceSchema = exports.OnChainEventSchema = exports.TokenMovementSchema = exports.ContractInvocationSchema = exports.ScValSchema = exports.NetworkSchema = void 0;
+const zod_1 = require("zod");
+const address_ts_1 = require("../synth/address.js");
+/** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
+ *  installed on-chain, so reject it at the boundary (fail-closed). */
+const U32_MAX = 4294967295;
+/** Upper bound on top-level invocations in a recorded transaction. A real
+ *  Stellar tx caps operations well below this; the bound stops a hand-crafted
+ *  payload from turning one request into an unbounded synthesis (DoS). */
+const MAX_INVOCATIONS = 512;
+exports.NetworkSchema = zod_1.z.enum(['mainnet', 'testnet']);
+/** ScVal subset - normalised subset the synth consumes. Mirrors
+ *  `ScVal` in packages/policy-synth/src/types.ts. */
+exports.ScValSchema = zod_1.z.lazy(() => zod_1.z.union([
+    zod_1.z.object({ type: zod_1.z.literal('address'), value: zod_1.z.string() }),
+    // i128 is SIGNED: real events carry negatives (e.g. a fee-adjustment/refund),
+    // so the recorder's own output must round-trip through this schema. u64/u32
+    // are unsigned and stay non-negative.
+    zod_1.z.object({ type: zod_1.z.literal('i128'), value: zod_1.z.string().regex(/^-?[0-9]+$/) }),
+    zod_1.z.object({ type: zod_1.z.literal('u64'), value: zod_1.z.string().regex(/^[0-9]+$/) }),
+    zod_1.z.object({ type: zod_1.z.literal('u32'), value: zod_1.z.string().regex(/^[0-9]+$/) }),
+    zod_1.z.object({ type: zod_1.z.literal('symbol'), value: zod_1.z.string() }),
+    zod_1.z.object({ type: zod_1.z.literal('vec'), value: zod_1.z.array(exports.ScValSchema) }),
+    zod_1.z.object({ type: zod_1.z.literal('bytes'), value: zod_1.z.string() }),
+    zod_1.z.object({ type: zod_1.z.literal('other'), value: zod_1.z.string() }),
+]));
+/** ContractInvocation mirrors the core. Annotated with an explicit
+ *  `z.ZodType<unknown>` (like ScValSchema above) so the self-referential
+ *  `subInvocations` field does not trip TS's circular type inference. */
+exports.ContractInvocationSchema = zod_1.z.object({
+    contract: zod_1.z.string(),
+    fn: zod_1.z.string(),
+    args: zod_1.z.array(exports.ScValSchema),
+    subInvocations: zod_1.z.array(zod_1.z.lazy(() => exports.ContractInvocationSchema)),
+});
+exports.TokenMovementSchema = zod_1.z.object({
+    token: zod_1.z.string(),
+    from: zod_1.z.string(),
+    to: zod_1.z.string(),
+    // The recorder reads the amount straight from the signed i128 event value
+    // (record/movements.ts readAmount), so a non-standard token that emits a
+    // negative transfer/mint/burn amount round-trips as a negative string. Mirror
+    // that here; the synth gate, not the wire schema, decides what to do with it.
+    amount: zod_1.z.string().regex(/^-?[0-9]+$/),
+});
+exports.OnChainEventSchema = zod_1.z.object({
+    contract: zod_1.z.string(),
+    topics: zod_1.z.array(zod_1.z.string()),
+    data: exports.ScValSchema,
+});
+exports.ParseConfidenceSchema = zod_1.z.object({
+    overall: zod_1.z.number().min(0).max(1),
+    knownContracts: zod_1.z.array(zod_1.z.string()),
+    unknownContracts: zod_1.z.array(zod_1.z.object({
+        contract: zod_1.z.string(),
+        reason: zod_1.z.enum(['no-abi', 'version-mismatch', 'opaque-result']),
+    })),
+    opaqueScVals: zod_1.z.array(zod_1.z.object({ path: zod_1.z.string(), type: zod_1.z.string() })),
+    thresholdUsed: zod_1.z.number().min(0).max(1),
+});
+/** RecordedTransaction mirrors the core RecordedTransaction. The output shape
+ *  is referenced by name in the tool result structured content; we deliberately
+ *  type it loosely (`z.unknown()`) on the success path so the core remains the
+ *  single source of truth for the wire payload. */
+exports.RecordedTransactionSchema = zod_1.z
+    .object({
+    network: exports.NetworkSchema,
+    signers: zod_1.z.array(zod_1.z.string()),
+    invocations: zod_1.z.array(exports.ContractInvocationSchema).max(MAX_INVOCATIONS),
+    tokenMovements: zod_1.z.array(exports.TokenMovementSchema),
+    events: zod_1.z.array(exports.OnChainEventSchema),
+    authEntries: zod_1.z.array(zod_1.z.unknown()),
+    ledgerSequence: zod_1.z.number().int().nonnegative(),
+    fetchedAt: zod_1.z.number().int().nonnegative(),
+    parseConfidence: exports.ParseConfidenceSchema,
+    sourceAccount: zod_1.z.string(),
+})
+    .passthrough();
+/** MandateSpec mirrors the core MandateSpec. The deterministic Mandate
+ *  front-end needs no parseConfidence; the tool adapter injects the full
+ *  confidence after synthesis so the orchestrator can compare. */
+exports.MandateSpecSchema = zod_1.z
+    .object({
+    chain: zod_1.z.literal('stellar'),
+    contract: zod_1.z.string(),
+    method: zod_1.z.string().optional(),
+    spendingLimit: zod_1.z
+        .object({
+        token: zod_1.z.string(),
+        limit: zod_1.z.string().regex(/^[0-9]+$/),
+        windowSeconds: zod_1.z.number().int().positive(),
+    })
+        .optional(),
+    // A threshold of 0 means "0 approvals", which is not a real M-of-N gate.
+    approvalThreshold: zod_1.z.number().int().positive().optional(),
+    recipients: zod_1.z.array(zod_1.z.string()).optional(),
+    expiry: zod_1.z
+        .object({
+        validUntilLedger: zod_1.z.number().int().positive().max(U32_MAX).optional(),
+        validUntilUnixSeconds: zod_1.z.number().int().positive().optional(),
+    })
+        .optional(),
+})
+    .passthrough();
+/** ComposeUserResponses mirrors the core. */
+exports.ComposeUserResponsesSchema = zod_1.z
+    .object({
+    windowSeconds: zod_1.z.number().int().positive().optional(),
+    validUntilLedger: zod_1.z.number().int().positive().max(U32_MAX).optional(),
+    limitAmount: zod_1.z
+        .string()
+        .regex(/^[0-9]+$/)
+        .optional(),
+    invocationLimit: zod_1.z.number().int().positive().optional(),
+    // Swap recipient allowlist (SoroSwap call_arg[3]). Each entry must be a
+    // Stellar address (G... wallet or C... contract); supplying it REPLACES the
+    // default pin to the recorded recipient. Validated with the shared StrKey
+    // helper (no hand-rolled regex).
+    swapRecipientAllowlist: zod_1.z
+        .array(zod_1.z.string().refine(address_ts_1.isStellarAddress, 'must be a Stellar address (G... or C...)'))
+        .optional(),
+})
+    .passthrough();
+/** OzAdapterConfig - the per-network OZ built-in instance addresses. */
+exports.OzAdapterConfigSchema = zod_1.z.object({
+    network: exports.NetworkSchema,
+    instances: zod_1.z.object({
+        spending_limit: zod_1.z.string(),
+        simple_threshold: zod_1.z.string(),
+        weighted_threshold: zod_1.z.string(),
+    }),
+});
+// ===== record_transaction =====
+exports.RecordTransactionInputSchema = zod_1.z
+    .object({
+    hash: zod_1.z.string().min(1).optional(),
+    xdr: zod_1.z.string().min(1).optional(),
+    network: exports.NetworkSchema,
+    confidenceOverride: zod_1.z.number().min(0).max(1).optional(),
+})
+    .refine((v) => !(v.hash && v.xdr), {
+    message: 'provide exactly one of `hash` or `xdr`, not both',
+})
+    .refine((v) => Boolean(v.hash) || Boolean(v.xdr), {
+    message: 'one of `hash` or `xdr` is required',
+});
+// ===== synthesize_policy =====
+//
+// Discriminated union on `source` exposes BOTH front-ends through ONE tool.
+// - `source: 'mandate'` -> calls synthesizeFromMandate
+// - `source: 'recording'` -> calls synthesizeFromRecording
+exports.SynthesizePolicyMandateInputSchema = zod_1.z.object({
+    source: zod_1.z.literal('mandate'),
+    mandate: exports.MandateSpecSchema,
+    ozConfig: exports.OzAdapterConfigSchema.optional(),
+});
+/** Interpreter opt-in for the recording path. Present -> constraints OZ cannot
+ *  express (per-method scoping, invocation-count windows, oracle bounds, exact
+ *  hop paths) lower to a real interpreter predicate document instead of being
+ *  surfaced as warnings. The core deep-validates `smartAccountAddress` (a C...
+ *  contract, not the recording's G... source) and the tighten-only oracle
+ *  bounds; the schema stays light so the core owns the friendly ToolErrors. */
+exports.InterpreterOptionsSchema = zod_1.z.object({
+    smartAccountAddress: zod_1.z.string(),
+    installNonce: zod_1.z.number().int().positive().optional(),
+    oracleParams: zod_1.z
+        .object({
+        maxStalenessSeconds: zod_1.z.number().int().positive().optional(),
+        maxDeviationBps: zod_1.z.number().int().positive().optional(),
+    })
+        .optional(),
+});
+exports.SynthesizePolicyRecordingInputSchema = zod_1.z.object({
+    source: zod_1.z.literal('recording'),
+    recordedTx: exports.RecordedTransactionSchema,
+    network: exports.NetworkSchema,
+    userResponses: exports.ComposeUserResponsesSchema.optional(),
+    confidenceOverride: zod_1.z.object({ threshold: zod_1.z.number().min(0).max(1) }).optional(),
+    interpreter: exports.InterpreterOptionsSchema.optional(),
+    ozConfig: exports.OzAdapterConfigSchema.optional(),
+});
+exports.SynthesizePolicyInputSchema = zod_1.z.discriminatedUnion('source', [
+    exports.SynthesizePolicyMandateInputSchema,
+    exports.SynthesizePolicyRecordingInputSchema,
+]);
+// ===== Error envelope (canonical) =====
+//
+// Mirrors ToolError from packages/policy-synth/src/errors.ts. We use a
+// `z.string()` for `code` (not an enum) because the core's ErrorCode union
+// evolves over time; the transport contract only promises a string code the
+// caller can dispatch on. A drift test asserts the canonical codes still
+// pass through unchanged.
+exports.ToolErrorSchema = zod_1.z
+    .object({
+    code: zod_1.z.string(),
+    message: zod_1.z.string(),
+    severity: zod_1.z.enum(['info', 'warning', 'error', 'fatal']),
+    retryable: zod_1.z.boolean(),
+    remediation: zod_1.z
+        .object({
+        toolCall: zod_1.z.object({ name: zod_1.z.string(), args: zod_1.z.record(zod_1.z.unknown()) }).optional(),
+        userQuestion: zod_1.z.object({ code: zod_1.z.string(), question: zod_1.z.string() }).optional(),
+        docsUrl: zod_1.z.string().optional(),
+    })
+        .optional(),
+    details: zod_1.z.unknown().optional(),
+})
+    .passthrough();

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

@@ -0,0 +1 @@
+export type { ChainDecoder, CompileResult, CustodyAdapter, CustodyCapabilities, CustodyMode, PolicySource, SimulationResult, } from './types.ts';

package/dist-cjs/seams/index.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/seams/index.ts - re-export the three custody-seam contracts.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/seams/types.d.ts

@@ -0,0 +1,66 @@
+import type { ToolResponse } from '../errors.ts';
+import type { PolicyIR } from '../ir/types.ts';
+import type { Network, ProposedPolicy, RecordedTransaction, ScVal } from '../types.ts';
+/** INPUT: something that produces a normalized RecordedTransaction. */
+export interface PolicySource {
+    readonly name: string;
+    capture(input: {
+        hash?: string;
+        xdr?: string;
+        network: Network;
+    }): Promise<ToolResponse<RecordedTransaction>>;
+}
+/** DECODE: chain-specific call data -> the normalized facts the synth reasons
+ *  over. */
+export interface ChainDecoder {
+    readonly chain: 'stellar' | 'evm';
+    decodeInvocation(tx: RecordedTransaction): {
+        contract: string;
+        method: string;
+        args: ScVal[];
+    };
+}
+/** OZ = enforce; `log_only` is reserved for shadow mode (out of scope). */
+export type CustodyMode = 'enforce' | 'log_only';
+/** What a backend can express. A construct needing a false flag is flagged
+ *  `uncovered` by the adapter, never silently dropped. */
+export interface CustodyCapabilities {
+    supportsOraclePrice: boolean;
+    supportsSpendWindow: boolean;
+    supportsInvocationCount: boolean;
+    supportsTimeExpiry: boolean;
+    supportsThreshold: boolean;
+    supportsGeneralPredicate: boolean;
+}
+/** The result of compiling a PolicyIR for one backend. */
+export interface CompileResult {
+    /** false => some IR construct this backend cannot express (see `uncovered`). */
+    covered: boolean;
+    /** Human-readable list of unsupported constructs. */
+    uncovered: string[];
+    /** The backend-native installable policy, assembled when a rule lowered. */
+    proposed?: ProposedPolicy;
+}
+/** Result of a simulate() dry-run. `ts-model` is the off-chain TS evaluator.
+ *  Real permit/deny semantics wiring is a later phase; week-1 returns a
+ *  clearly-marked stub (empty `evaluations`, `permitted: null`). */
+export interface SimulationResult {
+    backend: 'ts-model';
+    /** Whether the permit tx would be allowed; null until real semantics land. */
+    permitted: boolean | null;
+    /** Per-construct evaluation trace; empty placeholder in this slice. */
+    evaluations: unknown[];
+    /** Diagnostics; marks the stub explicitly. */
+    notes: string[];
+}
+/** OUTPUT: compile a PolicyIR to a backend-specific installable policy. */
+export interface CustodyAdapter {
+    readonly name: string;
+    readonly mode: CustodyMode;
+    capabilities(): CustodyCapabilities;
+    compile(ir: PolicyIR): CompileResult;
+    /** Phase-03 wiring; a clearly-marked stub in week-1. */
+    simulate(ir: PolicyIR, permitTx: RecordedTransaction): SimulationResult;
+    /** Canonical JSON of the IR (portability / audit). */
+    export(ir: PolicyIR): string;
+}

package/dist-cjs/seams/types.js

@@ -0,0 +1,12 @@
+"use strict";
+// src/seams/types.ts - the three custody seams (contracts, not implementations).
+//
+// The synthesizer is decoupled from its edges by three seams:
+//   - PolicySource  (INPUT):  produces a normalized RecordedTransaction. The
+//                             recorder is the reference source; a MandateSpec
+//                             lowering is a second, deterministic source.
+//   - ChainDecoder  (DECODE): chain-specific call data -> normalized facts.
+//   - CustodyAdapter (OUTPUT): compile a PolicyIR to a backend-native policy +
+//                             verify/export it (OZ is the first adapter).
+// These are INTERFACES only. Implementations live in their own modules.
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,7 @@
+/** True when `s` is a valid Stellar address strkey - either an Ed25519 public
+ *  key (`G...`) or a contract address (`C...`). Backed by the SDK's `StrKey`
+ *  decoder (the same one the recorder uses in `record/decode.ts`); no
+ *  hand-rolled regex. Used to validate a caller-supplied swap recipient
+ *  allowlist, whose entries may be either a wallet (`G...`) or a contract
+ *  (`C...`). */
+export declare function isStellarAddress(s: string): boolean;

package/dist-cjs/synth/address.js

@@ -0,0 +1,15 @@
+"use strict";
+// src/synth/address.ts - Stellar address validation shared by the CLI + the
+// run-layer Zod schema.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStellarAddress = isStellarAddress;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+/** True when `s` is a valid Stellar address strkey - either an Ed25519 public
+ *  key (`G...`) or a contract address (`C...`). Backed by the SDK's `StrKey`
+ *  decoder (the same one the recorder uses in `record/decode.ts`); no
+ *  hand-rolled regex. Used to validate a caller-supplied swap recipient
+ *  allowlist, whose entries may be either a wallet (`G...`) or a contract
+ *  (`C...`). */
+function isStellarAddress(s) {
+    return stellar_sdk_1.StrKey.isValidEd25519PublicKey(s) || stellar_sdk_1.StrKey.isValidContract(s);
+}

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

@@ -0,0 +1,65 @@
+import type { IRCompOp, PolicyIR } from '../ir/types.ts';
+import type { AmbiguityPrompt, ContractInvocation, Network } from '../types.ts';
+import type { IntentFacts } from './lower.ts';
+/** Per-asset oracle-price bound supplied by the caller (e.g. swap allowed only
+ *  if oracle_price(XLM) < 5.00 USDC). One entry per asset; the recorder never
+ *  fabricates a price bound from a slippage value (different units). */
+export interface OraclePriceBound {
+    asset: string;
+    operator: IRCompOp;
+    value: string;
+}
+/** Caller-supplied answers to the ambiguity prompts. Every numeric bound the
+ *  synth might apply must come from here - the recording supplies observed
+ *  amounts (offered only as suggestions), never authorised ceilings. */
+export interface ComposeUserResponses {
+    /** Rolling window (seconds) for a spending_limit / invocation_count. */
+    windowSeconds?: number;
+    /** OZ context-rule expiry (ledger sequence). */
+    validUntilLedger?: number;
+    /** Per-window spend ceiling (i128 decimal string). Required to emit a
+     *  spending_limit; absent -> AMOUNT_BOUND_MISSING. */
+    limitAmount?: string;
+    /** Max invocations per window for an incoming-only flow. Required to emit an
+     *  invocation_count bound; absent -> FREQUENCY_BOUND_MISSING. */
+    invocationLimit?: number;
+    /** Per-asset oracle-price bound(s). Each entry lowers to a single
+     *  `oracle_price(asset) OP value` compare in the interpreter IR. Multiple
+     *  entries on the same asset emit multiple leaves. */
+    oraclePriceBound?: OraclePriceBound[];
+    /** Recipient allowlist for a swap (call_arg[3] on SoroSwap's
+     *  swap_exact_tokens_for_tokens). When supplied, it REPLACES the default
+     *  pin. Absent -> the recipient is pinned to the recorded value (mirroring
+     *  SEP-41) and RECIPIENT_ALLOWLIST_EMPTY is surfaced as informational, never
+     *  a silent free pass. */
+    swapRecipientAllowlist?: string[];
+}
+/** Composition options. */
+export interface ComposeOptions {
+    network: Network;
+    userResponses?: ComposeUserResponses;
+    /** When true, constraints the OZ adapter cannot lower are routed to
+     *  `interpreterIr` (the predicate-shape IR) so the orchestrator can compile
+     *  them via the interpreter adapter. When false (the default for callers
+     *  who have not opted in), every constraint goes to `ir` and the OZ
+     *  adapter's `uncovered` machinery generates the descriptive warnings -
+     *  today's behaviour. The orchestrator passes this flag through based on
+     *  whether `opts.interpreter` was supplied. */
+    interpreterEnabled?: boolean;
+}
+/** Result of composition: the OZ-shape PolicyIR, the predicate-shape PolicyIR
+ *  (contains the constraints the OZ adapter cannot lower; empty when
+ *  `interpreterEnabled` is false), any ambiguities surfaced during inference,
+ *  and descriptive warnings for needs that are NOT expressed as an IR node
+ *  (so no fabricated constraint is emitted). The orchestrator carries
+ *  ambiguities into `ProposedPolicy.ambiguities` and merges warnings into
+ *  `ProposedPolicy.warnings`. */
+export interface ComposeResult {
+    ir: PolicyIR;
+    interpreterIr: PolicyIR;
+    ambiguities: AmbiguityPrompt[];
+    warnings: string[];
+}
+/** Compose a PolicyIR pair from the lowered facts + the resolved scope.
+ *  Pure (no randomness, no clock); same inputs -> byte-identical result. */
+export declare function composeFromRecording(facts: IntentFacts, scopeContract: string, topLevel: ContractInvocation | null, opts: ComposeOptions): ComposeResult;