@crediolabs/policy-synth 0.1.4 → 0.1.6

package/dist-cjs/review-card/conflict.d.ts

@@ -0,0 +1,40 @@
+/** Minimal rule reference the classifier needs to compute the conflict kind.
+ *  Carries the rule id (used in the annotation), the scope (contract +
+ *  method), and an optional spending cap. The cap captures both the
+ *  amount and the window so the classifier can compare apples to apples. */
+export interface RuleRef {
+    id: string;
+    scope: {
+        contract?: string;
+        method?: string;
+    };
+    /** When set, the rule enforces this per-window spend cap (token +
+     *  decimal-string amount + seconds window). */
+    spendingLimit?: {
+        token: string;
+        amount: string;
+        windowSeconds: number;
+    };
+}
+/** Structured annotation a single new-vs-existing rule comparison yields.
+ *  Four mutually exclusive kinds; the union is exhaustive (the classifier
+ *  never throws). */
+export type ConflictAnnotation = {
+    kind: 'subsume';
+    existingRuleId: string;
+    detail: string;
+} | {
+    kind: 'disjoint';
+} | {
+    kind: 'counter_permissive';
+    existingRuleId: string;
+    newLimit: string;
+    existingLimit: string;
+} | {
+    kind: 'window_divergent';
+    existingRuleId: string;
+    effectiveUnion: string;
+};
+/** Classify the relationship between a new rule and one existing rule.
+ *  Pure: same pair -> same annotation. */
+export declare function classifyConflict(newRule: RuleRef, existingRule: RuleRef): ConflictAnnotation;

package/dist-cjs/review-card/conflict.js

@@ -0,0 +1,114 @@
+"use strict";
+// src/review-card/conflict.ts - the ConflictAnnotation 4-kind enum + the
+// `classifyConflict` classifier.
+//
+// When a user installs a new policy alongside an existing rule set, the
+// review card surfaces the relationship between the new rule and each
+// existing rule as a structured annotation. A boolean (conflict / no
+// conflict) is wrong: four qualitatively different shapes are possible, and
+// each one tells the user something different about what would happen if
+// both rules installed together.
+//
+//   - subsume            new rule's scope is a SUPERSET of an existing
+//                        rule's. The new rule is broader; installing it on
+//                        top of the existing rule weakens the existing
+//                        restriction. The existing rule becomes a no-op.
+//   - disjoint           new rule and existing rule are unrelated: their
+//                        scopes do not overlap. Safe to install both.
+//   - counter_permissive new rule and existing rule allow CONFLICTING
+//                        things at the same scope (one caps lower than the
+//                        other on the same axis). The stricter one wins
+//                        at evaluate; the looser is dead weight.
+//   - window_divergent   new rule and existing rule have the same scope
+//                        and the same per-window limit but DIFFERENT
+//                        rolling windows. Effective union = sum (the user
+//                        can spend `limit` per each window, independently).
+//
+// The classifier consumes a minimal `RuleRef` shape: the rule id, scope
+// (contract + method), and an optional spending limit + window. Shapes
+// without a limit fall back to scope-only classification.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyConflict = classifyConflict;
+/** Classify the relationship between a new rule and one existing rule.
+ *  Pure: same pair -> same annotation. */
+function classifyConflict(newRule, existingRule) {
+    // --- step 1: subsume? (new.scope ⊋ existing.scope) ---
+    //
+    // Subsume requires existing to be fully scoped (both contract AND method
+    // pinned) AND new to be at least partially broader than existing. A new
+    // rule with identical scope to existing is NOT a superset - it is the
+    // same rule and falls through to the same-scope branch below. If existing
+    // is "any contract" / "any method" then it is the wildest rule in the
+    // rule set; a new rule covering it is just a duplicate, not a subsume -
+    // fall through to disjoint.
+    const existingHasContract = existingRule.scope.contract !== undefined;
+    const existingHasMethod = existingRule.scope.method !== undefined;
+    const newIsBroaderOnContract = newRule.scope.contract === undefined && existingHasContract;
+    const newIsBroaderOnMethod = newRule.scope.method === undefined && existingHasMethod;
+    const newMatchesOnContract = newRule.scope.contract === undefined ||
+        (existingHasContract && newRule.scope.contract === existingRule.scope.contract);
+    const newMatchesOnMethod = newRule.scope.method === undefined ||
+        (existingHasMethod && newRule.scope.method === existingRule.scope.method);
+    if (existingHasContract &&
+        existingHasMethod &&
+        newMatchesOnContract &&
+        newMatchesOnMethod &&
+        (newIsBroaderOnContract || newIsBroaderOnMethod)) {
+        return {
+            kind: 'subsume',
+            existingRuleId: existingRule.id,
+            detail: `new rule scope (${describeScope(newRule)}) is a superset of existing rule (${describeScope(existingRule)})`,
+        };
+    }
+    // --- step 2: disjoint by scope? ---
+    if (existingHasContract && newRule.scope.contract !== undefined) {
+        if (newRule.scope.contract !== existingRule.scope.contract) {
+            return { kind: 'disjoint' };
+        }
+    }
+    if (existingHasMethod &&
+        newRule.scope.method !== undefined &&
+        newRule.scope.method !== existingRule.scope.method) {
+        return { kind: 'disjoint' };
+    }
+    // --- step 3: same scope -> compare spend caps (when both sides carry them) ---
+    if (newRule.spendingLimit && existingRule.spendingLimit) {
+        const a = newRule.spendingLimit;
+        const b = existingRule.spendingLimit;
+        if (a.token !== b.token) {
+            // Same scope, different tokens: each binds a different axis. They
+            // do not counter each other; treat as disjoint.
+            return { kind: 'disjoint' };
+        }
+        if (a.windowSeconds === b.windowSeconds) {
+            // Same scope, same token, same window: counter-permissive when the
+            // amounts disagree (the stricter wins at evaluate; the looser is
+            // dead weight). Equal amounts -> duplicate rule, treat as disjoint.
+            if (a.amount === b.amount) {
+                return { kind: 'disjoint' };
+            }
+            return {
+                kind: 'counter_permissive',
+                existingRuleId: existingRule.id,
+                newLimit: `${a.amount} ${a.token} / ${a.windowSeconds}s`,
+                existingLimit: `${b.amount} ${b.token} / ${b.windowSeconds}s`,
+            };
+        }
+        // Same scope + token, different windows: effective union is the sum
+        // of the two per-window caps (each window ticks independently).
+        const union = (BigInt(a.amount) + BigInt(b.amount)).toString();
+        return {
+            kind: 'window_divergent',
+            existingRuleId: existingRule.id,
+            effectiveUnion: `${union} ${a.token} per ${a.windowSeconds}s (new) + ${b.windowSeconds}s (existing)`,
+        };
+    }
+    // Same scope without comparable spend caps on both sides -> disjoint.
+    return { kind: 'disjoint' };
+}
+function describeScope(rule) {
+    const parts = [];
+    parts.push(rule.scope.contract ? `contract=${rule.scope.contract}` : 'contract=*');
+    parts.push(rule.scope.method ? `method=${rule.scope.method}` : 'method=*');
+    return parts.join(', ');
+}

package/dist-cjs/review-card/cross-check.d.ts

@@ -0,0 +1,11 @@
+import type { PredicateNode } from '../types.ts';
+import type { ReviewCardSummary } from './builder.ts';
+/** Assert every leaf in the predicate appears as a constraint string in
+ *  `summary.constraints`. Returns the missing templates (without the leaf
+ *  values filled in) when any leaf was dropped. */
+export declare function summaryCrossCheck(predicate: PredicateNode | null, summary: ReviewCardSummary): {
+    ok: true;
+} | {
+    ok: false;
+    missingConstraints: string[];
+};

package/dist-cjs/review-card/cross-check.js

@@ -0,0 +1,151 @@
+"use strict";
+// src/review-card/cross-check.ts - the non-hallucination guard.
+//
+// `summaryCrossCheck` walks EVERY leaf of the predicate and asserts the
+// review-card summary quoted a constraint string for it. Returns
+// `{ ok: false, missingConstraints }` if any leaf was dropped (or rendered
+// into a template shape the cross-check does not recognise). A
+// `PredicateNode = null` is always ok - the policy is OZ-only and the
+// interpreter predicate did not exist.
+//
+// The guard is structural: every leaf the builder is supposed to render has
+// exactly one template shape. The cross-check enumerates those shapes and
+// demands the summary carries the corresponding string. A naive summary
+// that drops a leaf (or fabricates a string not in the predicate) trips the
+// guard.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summaryCrossCheck = summaryCrossCheck;
+/** Assert every leaf in the predicate appears as a constraint string in
+ *  `summary.constraints`. Returns the missing templates (without the leaf
+ *  values filled in) when any leaf was dropped. */
+function summaryCrossCheck(predicate, summary) {
+    if (predicate === null)
+        return { ok: true };
+    const expected = [];
+    collect(predicate, expected);
+    if (expected.length === 0)
+        return { ok: true };
+    const present = new Set(summary.constraints);
+    const missing = expected.filter((s) => !present.has(s));
+    if (missing.length === 0)
+        return { ok: true };
+    return { ok: false, missingConstraints: missing };
+}
+/** Walk the predicate and emit the EXACT constraint string the builder is
+ *  expected to produce for each leaf, in walk order. Strings here MUST
+ *  match the templates in `builder.ts` byte-for-byte; the cross-check is
+ *  the structural claim that "every supported leaf shape is rendered". */
+function collect(node, out) {
+    switch (node.op) {
+        case 'and':
+        case 'or':
+            for (const child of node.children)
+                collect(child, out);
+            return;
+        case 'not':
+            collect(node.child, out);
+            return;
+        case 'eq':
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+            pushComparison(node.left, node.right, node.op, out);
+            return;
+        case 'in':
+            pushMembership(node.needle, node.haystack, out);
+            return;
+    }
+}
+function pushComparison(left, right, op, out) {
+    if (left.kind === 'call_contract' && op === 'eq' && right.kind === 'literal_address') {
+        out.push(`Contract must be ${right.value}`);
+        return;
+    }
+    if (left.kind === 'call_fn' && op === 'eq' && right.kind === 'literal_symbol') {
+        out.push(`Function must be ${right.value}`);
+        return;
+    }
+    if (left.kind === 'call_arg' && op === 'eq' && right.kind === 'literal_vec') {
+        out.push(`Path must be exactly [${right.elements.map(renderVecElement).join(', ')}]`);
+        return;
+    }
+    if (left.kind === 'invocation_count_in_window' && right.kind === 'literal_u32') {
+        out.push(`Invocations <= ${right.value} per ${left.windowSecs} seconds`);
+        return;
+    }
+    if (left.kind === 'amount' && right.kind === 'literal_i128') {
+        out.push(`Amount <= ${right.value}`);
+        return;
+    }
+    if (left.kind === 'oracle_price' && right.kind === 'literal_i128') {
+        out.push(`Only when oracle_price(${left.asset}) ${comparisonOpText(op)} ${right.value}`);
+        return;
+    }
+}
+function pushMembership(needle, haystack, out) {
+    if (needle.kind !== 'call_arg')
+        return;
+    const list = haystack.map(renderHaystackElement).join(', ');
+    out.push(`Recipient/arg must be one of [${list}]`);
+}
+function renderVecElement(leaf) {
+    switch (leaf.kind) {
+        case 'literal_address':
+            return leaf.value;
+        case 'literal_i128':
+            return leaf.value;
+        case 'literal_symbol':
+            return leaf.value;
+        case 'literal_u32':
+            return String(leaf.value);
+        case 'literal_u64':
+            return leaf.value;
+        case 'literal_bytes':
+            return leaf.value;
+        case 'literal_vec':
+            return `[${leaf.elements.map(renderVecElement).join(', ')}]`;
+        case 'call_contract':
+        case 'call_fn':
+        case 'call_arg':
+        case 'amount':
+        case 'window_spent':
+        case 'now':
+        case 'valid_until':
+        case 'invocation_count_in_window':
+        case 'oracle_price':
+            return `<${leaf.kind}>`;
+    }
+}
+function renderHaystackElement(leaf) {
+    if (leaf.kind === 'literal_address')
+        return leaf.value;
+    if (leaf.kind === 'literal_i128')
+        return leaf.value;
+    if (leaf.kind === 'literal_symbol')
+        return leaf.value;
+    if (leaf.kind === 'literal_u32')
+        return String(leaf.value);
+    if (leaf.kind === 'literal_u64')
+        return leaf.value;
+    if (leaf.kind === 'literal_bytes')
+        return leaf.value;
+    if (leaf.kind === 'literal_vec') {
+        return `[${leaf.elements.map(renderHaystackElement).join(', ')}]`;
+    }
+    return `<${leaf.kind}>`;
+}
+function comparisonOpText(op) {
+    switch (op) {
+        case 'lt':
+            return '<';
+        case 'lte':
+            return '<=';
+        case 'gt':
+            return '>';
+        case 'gte':
+            return '>=';
+        case 'eq':
+            return '==';
+    }
+}

package/dist-cjs/review-card/index.d.ts

@@ -0,0 +1,3 @@
+export { buildReviewCardSummary, type ReviewCardSummary, } from './builder.ts';
+export { type ConflictAnnotation, classifyConflict, type RuleRef, } from './conflict.ts';
+export { summaryCrossCheck } from './cross-check.ts';

package/dist-cjs/review-card/index.js

@@ -0,0 +1,10 @@
+"use strict";
+// src/review-card/index.ts - re-export the deterministic review-card surface.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summaryCrossCheck = exports.classifyConflict = exports.buildReviewCardSummary = void 0;
+var builder_ts_1 = require("./builder.js");
+Object.defineProperty(exports, "buildReviewCardSummary", { enumerable: true, get: function () { return builder_ts_1.buildReviewCardSummary; } });
+var conflict_ts_1 = require("./conflict.js");
+Object.defineProperty(exports, "classifyConflict", { enumerable: true, get: function () { return conflict_ts_1.classifyConflict; } });
+var cross_check_ts_1 = require("./cross-check.js");
+Object.defineProperty(exports, "summaryCrossCheck", { enumerable: true, get: function () { return cross_check_ts_1.summaryCrossCheck; } });

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

@@ -0,0 +1,43 @@
+import { type ErrorCode, type ProposedPolicy, type RecordedTransaction, type ToolError, 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>>;
+/** Build a canonical ToolError for a thrown exception caught by the tool
+ *  envelope. The MCP SDK stringifies thrown objects as "[object Object]" by
+ *  default, 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.
+ *
+ *  Exported as `_caughtError` (the leading underscore signals the test-only
+ *  seam) so the suite in run/index.test.ts can drive the envelope path
+ *  without standing up a full recordTransaction pipeline. */
+export declare function caughtError(toolName: 'record_transaction' | 'synthesize_policy', code: ErrorCode, e: unknown): ToolError;

package/dist-cjs/run/index.js

@@ -0,0 +1,237 @@
+"use strict";
+// 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).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolErrorSchema = exports.SynthesizePolicyInputSchema = exports.RecordTransactionInputSchema = exports.RecordedTransactionSchema = exports.OzAdapterConfigSchema = exports.NetworkSchema = exports.MandateSpecSchema = exports.InterpreterOptionsSchema = exports.ComposeUserResponsesSchema = void 0;
+exports.runRecordTransaction = runRecordTransaction;
+exports.runSynthesizePolicy = runSynthesizePolicy;
+exports.caughtError = caughtError;
+const index_ts_1 = require("../index.js");
+const schemas_ts_1 = require("./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.
+var schemas_ts_2 = require("./schemas.js");
+Object.defineProperty(exports, "ComposeUserResponsesSchema", { enumerable: true, get: function () { return schemas_ts_2.ComposeUserResponsesSchema; } });
+Object.defineProperty(exports, "InterpreterOptionsSchema", { enumerable: true, get: function () { return schemas_ts_2.InterpreterOptionsSchema; } });
+Object.defineProperty(exports, "MandateSpecSchema", { enumerable: true, get: function () { return schemas_ts_2.MandateSpecSchema; } });
+Object.defineProperty(exports, "NetworkSchema", { enumerable: true, get: function () { return schemas_ts_2.NetworkSchema; } });
+Object.defineProperty(exports, "OzAdapterConfigSchema", { enumerable: true, get: function () { return schemas_ts_2.OzAdapterConfigSchema; } });
+Object.defineProperty(exports, "RecordedTransactionSchema", { enumerable: true, get: function () { return schemas_ts_2.RecordedTransactionSchema; } });
+Object.defineProperty(exports, "RecordTransactionInputSchema", { enumerable: true, get: function () { return schemas_ts_2.RecordTransactionInputSchema; } });
+Object.defineProperty(exports, "SynthesizePolicyInputSchema", { enumerable: true, get: function () { return schemas_ts_2.SynthesizePolicyInputSchema; } });
+Object.defineProperty(exports, "ToolErrorSchema", { enumerable: true, get: function () { return schemas_ts_2.ToolErrorSchema; } });
+/** `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. */
+async function runRecordTransaction(raw) {
+    const parsed = schemas_ts_1.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 (0, index_ts_1.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. */
+async function runSynthesizePolicy(raw) {
+    const parsed = schemas_ts_1.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 (0, index_ts_1.synthesizeFromMandate)(input.mandate, ozConfig);
+        }
+        // recording source
+        const recorded = input.recordedTx;
+        return await (0, index_ts_1.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 (0, index_ts_1.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. The MCP SDK stringifies thrown objects as "[object Object]" by
+ *  default, 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.
+ *
+ *  Exported as `_caughtError` (the leading underscore signals the test-only
+ *  seam) so the suite in run/index.test.ts can drive the envelope path
+ *  without standing up a full recordTransaction pipeline. */
+function caughtError(toolName, code, e) {
+    const message = describeThrown(e, toolName);
+    const details = { thrown: safeStringify(e) };
+    return {
+        code,
+        message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
+        severity: 'error',
+        retryable: false,
+        remediation: {
+            toolCall: { name: toolName, args: {} },
+        },
+        details,
+    };
+}
+/** Build a human-readable message for an unknown caught value. Order matters:
+ *    1. `Error` instances use `.message` (or fallback to the class name).
+ *    2. Native strings pass through verbatim.
+ *    3. Objects with a string `message` field use that field (mirrors the
+ *       shape thrown by some SDKs that package errors as plain objects).
+ *    4. Anything else falls back to a JSON-shaped summary, never to
+ *       "[object Object]".
+ *  The full payload is also captured in `details.thrown` via
+ *  `safeStringify` so the agent can inspect the original value without
+ *  risking an infinite loop on circular refs. */
+function describeThrown(e, toolName) {
+    if (e instanceof Error) {
+        return e.message || `${toolName}: ${e.name || 'Error'}`;
+    }
+    if (typeof e === 'string') {
+        return e;
+    }
+    if (e !== null && typeof e === 'object') {
+        const obj = e;
+        const m = obj.message;
+        if (typeof m === 'string' && m.length > 0) {
+            return truncate(m);
+        }
+        return truncate(safeStringify(e));
+    }
+    return `${toolName}: caught non-Error throw of type ${typeof e}`;
+}
+/** Hard cap on the human-readable message embedded in the ToolError. The full
+ *  payload is still preserved in `details.thrown` so the agent can inspect
+ *  it - the truncation is only to keep the top-level message small enough to
+ *  fit comfortably in transport logs. */
+const MAX_MESSAGE_LEN = 512;
+/** JSON.stringify that survives circular refs and very large payloads. The
+ *  output is itself bounded by the same `MAX_DETAILS_LEN` so a thrown object
+ *  with megabytes of buffer data cannot bloat the WHOLE envelope. */
+const MAX_DETAILS_LEN = 4096;
+function safeStringify(v) {
+    const seen = new WeakSet();
+    const json = JSON.stringify(v, (_k, value) => {
+        if (typeof value === 'bigint')
+            return value.toString();
+        if (typeof value === 'function')
+            return `[function ${value.name || 'anonymous'}]`;
+        if (value instanceof Error) {
+            return { name: value.name, message: value.message, stack: value.stack };
+        }
+        if (value !== null && typeof value === 'object') {
+            if (seen.has(value))
+                return '[Circular]';
+            seen.add(value);
+        }
+        return value;
+    }, 2);
+    if (json === undefined)
+        return '<unserializable>';
+    return truncate(json, MAX_DETAILS_LEN);
+}
+function truncate(s, cap = MAX_MESSAGE_LEN) {
+    if (s.length <= cap)
+        return s;
+    return `${s.slice(0, cap)}\n…[truncated ${s.length - cap} chars]`;
+}