@crediolabs/policy-synth 0.1.4 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Untangled Finance Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/codegen/template.js

@@ -51,10 +51,10 @@ function renderUncovered(uncovered) {
  *
  *  Same `(spec, name)` always produces byte-identical output. */
 export function generateRust(spec, name) {
-    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.
 // THIS OUTPUT IS THE USER'S TO COMPLETE AND AUDIT.

package/dist/record/decode.d.ts

@@ -1,5 +1,5 @@
 import { xdr } from '@stellar/stellar-sdk';
-import type { ContractInvocation, Network, OnChainEvent, ParseConfidence, ScVal, TokenMovement } from '../types.ts';
+import { type ContractInvocation, type Network, type OnChainEvent, type ParseConfidence, type ScVal, type TokenMovement } from '../types.ts';
 /** Result of decoding an envelope XDR plus the surrounding metadata from
  *  `getTransaction` (events + auth entries). All fields are plain JSON; the
  *  caller decides how to interpret them. */
@@ -44,8 +44,11 @@ export declare function decodeScAddressToC(scAddr: xdr.ScAddress): string;
 /** Map an arbitrary ScVal into the normalised `ScVal` subset defined in
  *  types.ts. Anything outside the subset is wrapped as `{type:'other', value}`
  *  AND recorded in `opaqueScVals` so the freshness module can reduce
- *  parseConfidence. */
-export declare function scValToSubset(val: xdr.ScVal, path: string, opaqueScVals: ParseConfidence['opaqueScVals']): ScVal;
+ *  parseConfidence. Recursion is bounded by `MAX_SCVAL_DEPTH` so a
+ *  hand-crafted nested-vec payload cannot RangeError the JS stack; the
+ *  over-depth branch is collapsed to a single opaque `depth-exceeded` token
+ *  (the recorder's parseConfidence gate then fails the recording closed). */
+export declare function scValToSubset(val: xdr.ScVal, path: string, opaqueScVals: ParseConfidence['opaqueScVals'], depth?: number): ScVal;
 /** Convert Int128Parts (hi: Int64, lo: Uint64) to a BigInt.
  *  hi is a signed 64-bit value; lo is unsigned. We use the SDK-provided
  *  `toString()` form which gives the signed decimal representation of the 64-bit

package/dist/record/decode.js

@@ -17,6 +17,7 @@
 // No network calls. No randomness. No globals.
 import { Address, StrKey, xdr } from '@stellar/stellar-sdk';
 import { identifyProtocol } from "../registry/identify.js";
+import { MAX_SCVAL_DEPTH, } from "../types.js";
 /** Decode a TransactionEnvelope XDR (base64) into a fully parsed invocation tree. */
 export function decodeEnvelopeXdr(envelopeXdrB64, events = [], _authEntries = [], ledgerSequence = 0, knownContracts = new Set(), network = null) {
     const envelope = xdr.TransactionEnvelope.fromXDR(envelopeXdrB64, 'base64');
@@ -226,8 +227,11 @@ function symbolValueFromBufferOrString(s) {
 /** Map an arbitrary ScVal into the normalised `ScVal` subset defined in
  *  types.ts. Anything outside the subset is wrapped as `{type:'other', value}`
  *  AND recorded in `opaqueScVals` so the freshness module can reduce
- *  parseConfidence. */
-export function scValToSubset(val, path, opaqueScVals) {
+ *  parseConfidence. Recursion is bounded by `MAX_SCVAL_DEPTH` so a
+ *  hand-crafted nested-vec payload cannot RangeError the JS stack; the
+ *  over-depth branch is collapsed to a single opaque `depth-exceeded` token
+ *  (the recorder's parseConfidence gate then fails the recording closed). */
+export function scValToSubset(val, path, opaqueScVals, depth = 0) {
     const kind = val.switch().name;
     switch (kind) {
         case 'scvAddress': {
@@ -252,10 +256,16 @@ export function scValToSubset(val, path, opaqueScVals) {
             return { type: 'symbol', value: val.sym().toString() };
         }
         case 'scvVec': {
+            if (depth >= MAX_SCVAL_DEPTH) {
+                // Over-depth branch: collapse to a single opaque terminal so the
+                // downstream parseConfidence gate sees the fail-closed freshness hit.
+                opaqueScVals.push({ path, type: 'depth-exceeded' });
+                return { type: 'other', value: 'depth-exceeded' };
+            }
             const arr = (val.vec() ?? []);
             return {
                 type: 'vec',
-                value: arr.map((v, i) => scValToSubset(v, `${path}[${i}]`, opaqueScVals)),
+                value: arr.map((v, i) => scValToSubset(v, `${path}[${i}]`, opaqueScVals, depth + 1)),
             };
         }
         case 'scvBytes': {

package/dist/run/index.d.ts

@@ -0,0 +1,31 @@
+import { type ProposedPolicy, type RecordedTransaction, type ToolResponse } from '../index.ts';
+import { type RecordTransactionInput, type SynthesizePolicyInput } from './schemas.ts';
+export type { RecordTransactionInput, SynthesizePolicyInput } from './schemas.ts';
+export { ComposeUserResponsesSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OzAdapterConfigSchema, RecordedTransactionSchema, RecordTransactionInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from './schemas.ts';
+export type RunRecordTransactionInput = RecordTransactionInput;
+export type RunSynthesizePolicyInput = SynthesizePolicyInput;
+/** `record_transaction` body - wraps `recordTransaction`. The tool input
+ *  matches the core RecordInput minus the injected `fetcher` (the transport
+ *  layer does not own the RPC). Returns the core ToolResponse unchanged.
+ *
+ *  Item 6: a try/catch envelope wraps the core call. The core's own
+ *  `recordTransaction` already returns `{ok:false, error}` for Zod + decoder
+ *  failures, but a throw from the SDK (e.g. a malformed hash handed to
+ *  `@stellar/stellar-sdk`'s StrKey decoder) would otherwise surface as
+ *  "[object Object]" in the MCP transport. The envelope converts any
+ *  non-ToolResponse throw into a structured `RECORDING_FAILED` ToolError so
+ *  the agent always sees a machine-readable error code. */
+export declare function runRecordTransaction(raw: unknown): Promise<ToolResponse<RecordedTransaction>>;
+/** `synthesize_policy` body - discriminated union on `source`:
+ *    - `mandate`   -> synthesizeFromMandate
+ *    - `recording` -> synthesizeFromRecording
+ *  Exposing BOTH front-ends through ONE tool keeps the MCP surface tiny while
+ *  letting the agent pick the deterministic or the inferred path. The CLI
+ *  routes the same way.
+ *
+ *  Item 6: same try/catch envelope as `runRecordTransaction`. The core
+ *  `synthesizeFromRecording` already converts ToolError-shaped throws to
+ *  `{ok:false, error}`, but a raw throw from the SDK (e.g. an unexpected
+ *  XDR decode error in the adapter) would otherwise surface as
+ *  "[object Object]" in the MCP transport. */
+export declare function runSynthesizePolicy(raw: unknown): Promise<ToolResponse<ProposedPolicy>>;

package/dist/run/index.js

@@ -0,0 +1,164 @@
+// packages/policy-synth/src/run/index.ts
+//
+// Tool-body adapters for the two core front-ends. Reachable as
+// `@crediolabs/policy-synth/run` from both the MCP server (which re-exports
+// for tool-registration glue) and the CLI (which calls them directly). Each
+// body is a THIN adapter over the pure core:
+//
+//   1. Re-validate the parsed input via Zod. This is a defence-in-depth check -
+//      the SDK has already parsed it through the registered schema, but we never
+//      want a tool body to throw on garbage (the SDK treats uncaught throws as
+//      transport errors and the agent loses the machine-readable ToolError).
+//   2. Dispatch to the matching core entry point with the minimum required
+//      inputs.
+//   3. Return the core's ToolResponse<T> unchanged. The server layer maps it
+//      to the MCP envelope; nothing here knows about MCP.
+//
+// No business logic. No retries. No session state. The same call shape can
+// drive the CLI (which calls into the same core directly without MCP).
+import { placeholderOzConfig, recordTransaction, synthesizeFromMandate, synthesizeFromRecording, } from "../index.js";
+import { RecordTransactionInputSchema, SynthesizePolicyInputSchema, } from "./schemas.js";
+// Re-export the underlying Zod schemas so the MCP package (and any other
+// downstream consumer) can import the canonical input shapes from the same
+// module that owns the tool-body glue. The strict schemas are the source of
+// truth - MCP tool shapes are derived from them.
+export { ComposeUserResponsesSchema, InterpreterOptionsSchema, MandateSpecSchema, NetworkSchema, OzAdapterConfigSchema, RecordedTransactionSchema, RecordTransactionInputSchema, SynthesizePolicyInputSchema, ToolErrorSchema, } from "./schemas.js";
+/** `record_transaction` body - wraps `recordTransaction`. The tool input
+ *  matches the core RecordInput minus the injected `fetcher` (the transport
+ *  layer does not own the RPC). Returns the core ToolResponse unchanged.
+ *
+ *  Item 6: a try/catch envelope wraps the core call. The core's own
+ *  `recordTransaction` already returns `{ok:false, error}` for Zod + decoder
+ *  failures, but a throw from the SDK (e.g. a malformed hash handed to
+ *  `@stellar/stellar-sdk`'s StrKey decoder) would otherwise surface as
+ *  "[object Object]" in the MCP transport. The envelope converts any
+ *  non-ToolResponse throw into a structured `RECORDING_FAILED` ToolError so
+ *  the agent always sees a machine-readable error code. */
+export async function runRecordTransaction(raw) {
+    const parsed = RecordTransactionInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: validationError('record_transaction', parsed.error.issues),
+        };
+    }
+    const input = parsed.data;
+    // Strip the wire-only `confidenceOverride` and pass the rest straight through.
+    const coreInput = {
+        network: input.network,
+        ...(input.hash !== undefined ? { hash: input.hash } : {}),
+        ...(input.xdr !== undefined ? { xdr: input.xdr } : {}),
+        ...(input.confidenceOverride !== undefined
+            ? { confidenceOverride: input.confidenceOverride }
+            : {}),
+    };
+    try {
+        return await recordTransaction(coreInput);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: caughtError('record_transaction', 'RECORDING_FAILED', e),
+        };
+    }
+}
+/** `synthesize_policy` body - discriminated union on `source`:
+ *    - `mandate`   -> synthesizeFromMandate
+ *    - `recording` -> synthesizeFromRecording
+ *  Exposing BOTH front-ends through ONE tool keeps the MCP surface tiny while
+ *  letting the agent pick the deterministic or the inferred path. The CLI
+ *  routes the same way.
+ *
+ *  Item 6: same try/catch envelope as `runRecordTransaction`. The core
+ *  `synthesizeFromRecording` already converts ToolError-shaped throws to
+ *  `{ok:false, error}`, but a raw throw from the SDK (e.g. an unexpected
+ *  XDR decode error in the adapter) would otherwise surface as
+ *  "[object Object]" in the MCP transport. */
+export async function runSynthesizePolicy(raw) {
+    const parsed = SynthesizePolicyInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: validationError('synthesize_policy', parsed.error.issues),
+        };
+    }
+    const input = parsed.data;
+    const ozConfig = resolveOzConfig(input);
+    try {
+        if (input.source === 'mandate') {
+            // Zod's optional fields widen to `T | undefined`, which the core's
+            // exact-optional MandateSpec rejects; the schema already validated the
+            // shape, so assert it (same pattern as the recordedTx cast below).
+            return await synthesizeFromMandate(input.mandate, ozConfig);
+        }
+        // recording source
+        const recorded = input.recordedTx;
+        return await synthesizeFromRecording(recorded, {
+            network: input.network,
+            ...(input.userResponses !== undefined ? { userResponses: input.userResponses } : {}),
+            ...(input.confidenceOverride !== undefined
+                ? { confidenceOverride: input.confidenceOverride }
+                : {}),
+            ...(input.interpreter !== undefined ? { interpreter: input.interpreter } : {}),
+        }, ozConfig);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            error: caughtError('synthesize_policy', 'SYNTHESIS_ERROR', e),
+        };
+    }
+}
+function resolveOzConfig(input) {
+    if (input.ozConfig)
+        return input.ozConfig;
+    // The mandate path is network-agnostic; fall back to mainnet so the
+    // placeholder OZ instance addresses are deterministic.
+    return placeholderOzConfig('mainnet');
+}
+/** Build a canonical ToolError for a Zod validation failure. The remediation
+ *  hint points the agent back at the right tool with an empty arg bag - the
+ *  tool name IS the machine-readable hint. */
+function validationError(toolName, issues) {
+    const code = toolName === 'record_transaction' ? 'RECORDING_FAILED' : 'SYNTHESIS_ERROR';
+    return {
+        code,
+        message: `${toolName}: invalid input: ${issues
+            .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
+            .join('; ')}`,
+        severity: 'error',
+        retryable: false,
+        remediation: {
+            toolCall: { name: toolName, args: {} },
+        },
+    };
+}
+/** Build a canonical ToolError for a thrown exception caught by the tool
+ *  envelope. We refuse to surface the raw exception's text (the MCP SDK
+ *  stringifies thrown objects as "[object Object]"), so we extract a
+ *  string-friendly message and tag the original error in `details` for the
+ *  agent to inspect. The `code` is the tool's domain code (RECORDING_FAILED
+ *  for `record_transaction`, SYNTHESIS_ERROR for `synthesize_policy`) so the
+ *  agent dispatches on the same code the structured ToolError would carry. */
+function caughtError(toolName, code, e) {
+    let message;
+    if (e instanceof Error) {
+        message = e.message || `${toolName}: unknown error`;
+    }
+    else if (typeof e === 'string') {
+        message = e;
+    }
+    else {
+        message = `${toolName}: caught non-Error throw of type ${typeof e}`;
+    }
+    return {
+        code,
+        message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
+        severity: 'error',
+        retryable: false,
+        remediation: {
+            toolCall: { name: toolName, args: {} },
+        },
+        details: { thrown: String(e) },
+    };
+}