@crediolabs/policy-synth 0.1.5 → 0.1.6

package/dist-cjs/run/index.js

@@ -21,6 +21,7 @@ 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
@@ -148,23 +149,19 @@ function validationError(toolName, issues) {
     };
 }
 /** 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. */
+ *  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) {
-    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}`;
-    }
+    const message = describeThrown(e, toolName);
+    const details = { thrown: safeStringify(e) };
     return {
         code,
         message: `${toolName}: unhandled throw escaped core envelope: ${message}`,
@@ -173,6 +170,68 @@ function caughtError(toolName, code, e) {
         remediation: {
             toolCall: { name: toolName, args: {} },
         },
-        details: { thrown: String(e) },
+        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]`;
+}

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

@@ -446,16 +446,19 @@ export declare const ComposeUserResponsesSchema: z.ZodObject<{
     validUntilLedger: z.ZodOptional<z.ZodNumber>;
     limitAmount: z.ZodOptional<z.ZodString>;
     invocationLimit: z.ZodOptional<z.ZodNumber>;
+    swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     windowSeconds: z.ZodOptional<z.ZodNumber>;
     validUntilLedger: z.ZodOptional<z.ZodNumber>;
     limitAmount: z.ZodOptional<z.ZodString>;
     invocationLimit: z.ZodOptional<z.ZodNumber>;
+    swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     windowSeconds: z.ZodOptional<z.ZodNumber>;
     validUntilLedger: z.ZodOptional<z.ZodNumber>;
     limitAmount: z.ZodOptional<z.ZodString>;
     invocationLimit: z.ZodOptional<z.ZodNumber>;
+    swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
 }, z.ZodTypeAny, "passthrough">>;
 /** OzAdapterConfig - the per-network OZ built-in instance addresses. */
 export declare const OzAdapterConfigSchema: z.ZodObject<{
@@ -1003,16 +1006,19 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough">>>;
     confidenceOverride: z.ZodOptional<z.ZodObject<{
         threshold: z.ZodNumber;
@@ -1130,6 +1136,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     confidenceOverride?: {
         threshold: number;
@@ -1193,6 +1200,7 @@ export declare const SynthesizePolicyRecordingInputSchema: z.ZodObject<{
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     confidenceOverride?: {
         threshold: number;
@@ -1649,16 +1657,19 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
         windowSeconds: z.ZodOptional<z.ZodNumber>;
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough">>>;
     confidenceOverride: z.ZodOptional<z.ZodObject<{
         threshold: z.ZodNumber;
@@ -1776,6 +1787,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     confidenceOverride?: {
         threshold: number;
@@ -1839,6 +1851,7 @@ export declare const SynthesizePolicyInputSchema: z.ZodDiscriminatedUnion<"sourc
         validUntilLedger: z.ZodOptional<z.ZodNumber>;
         limitAmount: z.ZodOptional<z.ZodString>;
         invocationLimit: z.ZodOptional<z.ZodNumber>;
+        swapRecipientAllowlist: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
     confidenceOverride?: {
         threshold: number;

package/dist-cjs/run/schemas.js

@@ -18,6 +18,7 @@
 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;
@@ -129,6 +130,13 @@ exports.ComposeUserResponsesSchema = zod_1.z
         .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. */

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

@@ -28,9 +28,10 @@ export interface ComposeUserResponses {
      *  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). Absent -> RECIPIENT_ALLOWLIST_EMPTY
-     *  ambiguity (the caller is prompted; proceeding without an allowlist leaves
-     *  the recipient unconstrained). */
+     *  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. */

package/dist-cjs/synth/compose-from-recording.js

@@ -311,11 +311,16 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
         }
         // Swap recipient (call_arg[3]): when the caller supplies
         // swapRecipientAllowlist, emit it as an `in` constraint on the recipient
-        // arg. When absent, surface RECIPIENT_ALLOWLIST_EMPTY so the caller is
-        // prompted; proceeding without an allowlist leaves the recipient
-        // unconstrained in the predicate. The ambiguity is only surfaced when
-        // the interpreter is enabled - if it isn't, the swap recipient is just
-        // ignored (today's behaviour).
+        // arg. When absent, PIN the recipient to the recorded value - mirroring the
+        // SEP-41 `to` arg above: the recorded flow went to exactly one recipient, so
+        // pinning it is the minimal policy that permits exactly that flow. Leaving
+        // it unconstrained would permit an arbitrary recipient (an evil twin with
+        // call_arg[3] = attacker_wallet). RECIPIENT_ALLOWLIST_EMPTY is still
+        // surfaced, but as INFORMATIONAL (the recipient was pinned; here is how to
+        // widen it), never as a silent free pass. The recipient is only enforceable
+        // via the interpreter predicate, so the pin (and the ambiguity) apply only
+        // when the interpreter is enabled - otherwise the swap recipient is ignored
+        // (today's behaviour, matching the other SoroSwap constraints).
         const recipientArg = topLevel.args[3];
         if (swapRecipientAllowlist && swapRecipientAllowlist.length > 0) {
             const cond = {
@@ -331,9 +336,14 @@ function appendProtocolSpecificConstraints(ozConstraints, interpreterConstraints
             }
         }
         else if (interpreterEnabled && recipientArg && recipientArg.type === 'address') {
+            interpreterConstraints.push({
+                op: 'in',
+                selector: { kind: 'arg', argIndex: 3, scalarType: 'address' },
+                values: [recipientArg.value],
+            });
             ambiguities.push({
                 code: 'RECIPIENT_ALLOWLIST_EMPTY',
-                question: `Recording shows the swap sending to ${recipientArg.value}. What recipient allowlist should the interpreter predicate bind? (omit to leave recipient unconstrained)`,
+                question: `No recipient allowlist supplied; the swap recipient (call_arg[3]) was pinned to the recorded value ${recipientArg.value}. To permit additional recipients, supply an allowlist (CLI: --recipient <C...|G...>, repeatable; MCP: userResponses.swapRecipientAllowlist) - it REPLACES this default pin.`,
             });
         }
     }

package/dist-cjs/synth/deny-cases.d.ts

@@ -8,5 +8,15 @@ export interface GeneratedCases {
     permit: EvalContext;
     denies: DenyCase[];
 }
-/** Build deterministic model-evaluated alternatives without mutating the intended call. */
-export declare function generateCases(predicate: PredicateNode, permitCtx: EvalContext): GeneratedCases;
+declare const OVERPERMISSIVE_DIMENSIONS: readonly ["argument_reorder"];
+declare const ORIGINAL_DIMENSIONS: string[];
+export { ORIGINAL_DIMENSIONS, OVERPERMISSIVE_DIMENSIONS };
+/** Build deterministic model-evaluated alternatives without mutating the intended call.
+ *
+ * @param predicate   - the synthesized predicate
+ * @param permitCtx   - EvalContext for the intended (permitted) call
+ * @param dimensions  - optional whitelist of dimension names to emit; when omitted
+ *                     all known dimensions (including over-permissiveness mutations)
+ *                     are emitted. The synth pipeline passes ORIGINAL_DIMENSIONS so
+ *                     existing fixtures do not regress. */
+export declare function generateCases(predicate: PredicateNode, permitCtx: EvalContext, dimensions?: string[]): GeneratedCases;

package/dist-cjs/synth/deny-cases.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERPERMISSIVE_DIMENSIONS = exports.ORIGINAL_DIMENSIONS = void 0;
 exports.generateCases = generateCases;
 const types_ts_1 = require("../types.js");
 const predicate_literals_ts_1 = require("./predicate-literals.js");
@@ -14,8 +15,39 @@ const ADJACENT_ASSETS = [
     'CAS3J7GYLGXMF6TDJ5WQ2PEN4GRVNXJUIQ2TZU3ZB3OQ2V4DRCWI7WPF',
     'CCWCLTASNDT57N3BCHOSVB5QWMV5URK4BXLDDF6ZZQYMBQ4OKZA3ZB2N',
 ];
-/** Build deterministic model-evaluated alternatives without mutating the intended call. */
-function generateCases(predicate, permitCtx) {
+// Phase 1 property-harness mutation dimensions excluded from the synth pipeline's
+// self-verify call so existing fixtures still emit policies. The harness tests
+// them as FINDINGS against the already-emitted policy.
+const OVERPERMISSIVE_DIMENSIONS = ['argument_reorder'];
+exports.OVERPERMISSIVE_DIMENSIONS = OVERPERMISSIVE_DIMENSIONS;
+// The 15 dimensions the synth pipeline uses for self-verify and minimise.
+const ORIGINAL_DIMENSIONS = [
+    'amount',
+    'asset',
+    'contract',
+    'function',
+    'timing',
+    'time_window',
+    'invocation_count',
+    'arg_amount_bound',
+    'arg_bound',
+    'scope_contract_fn_arg',
+    'oracle_stale',
+    'oracle_missing',
+    'oracle_deviation_exceeded',
+    'oracle_paused',
+    'soroswap_allowed_path',
+];
+exports.ORIGINAL_DIMENSIONS = ORIGINAL_DIMENSIONS;
+/** Build deterministic model-evaluated alternatives without mutating the intended call.
+ *
+ * @param predicate   - the synthesized predicate
+ * @param permitCtx   - EvalContext for the intended (permitted) call
+ * @param dimensions  - optional whitelist of dimension names to emit; when omitted
+ *                     all known dimensions (including over-permissiveness mutations)
+ *                     are emitted. The synth pipeline passes ORIGINAL_DIMENSIONS so
+ *                     existing fixtures do not regress. */
+function generateCases(predicate, permitCtx, dimensions) {
     const facts = inspectPredicate(predicate);
     const denies = [];
     for (const comparison of facts.comparisons) {
@@ -147,6 +179,32 @@ function generateCases(predicate, permitCtx) {
         ctx.args[comparison.left.index] = differentVector(ctx.args[comparison.left.index]);
         denies.push({ dimension: 'soroswap_allowed_path', ctx });
     }
+    // --- argument_reorder: swap first two address args ---
+    // Skipped when dimensions filter is active so the synth pipeline can emit a policy;
+    // the over-permissiveness harness then tests this mutation as a FINDING.
+    const constrainedArgIndices = new Set();
+    for (const comparison of facts.comparisons) {
+        if (comparison.left.kind === 'call_arg')
+            constrainedArgIndices.add(comparison.left.index);
+    }
+    for (const membership of facts.memberships) {
+        if (membership.needle.kind === 'call_arg')
+            constrainedArgIndices.add(membership.needle.index);
+    }
+    const hasConstrainedArg = constrainedArgIndices.size > 0;
+    if ((!dimensions || dimensions.includes('argument_reorder')) &&
+        hasConstrainedArg &&
+        permitCtx.args.length >= 2 &&
+        permitCtx.args[0]?.type === 'address' &&
+        permitCtx.args[1]?.type === 'address') {
+        const ctx = cloneContext(permitCtx);
+        // Guard above guarantees args[0] and args[1] exist and are address-typed.
+        const a0 = ctx.args[0];
+        const a1 = ctx.args[1];
+        ctx.args[0] = a1;
+        ctx.args[1] = a0;
+        denies.push({ dimension: 'argument_reorder', ctx });
+    }
     // Version mismatch, malformed predicates, master authorization, and nonce replay are install-time checks and are intentionally omitted from model-evaluated cases.
     return { permit: cloneContext(permitCtx), denies };
 }

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

@@ -1,3 +1,4 @@
+export { isStellarAddress } from './address.ts';
 export { type ComposeOptions, type ComposeResult, composeFromRecording, } from './compose-from-recording.ts';
 export { type DenyCase, type GeneratedCases, generateCases, } from './deny-cases.ts';
 export { type EvalContext, type EvalResult, evaluate } from './evaluate.ts';

package/dist-cjs/synth/index.js

@@ -1,7 +1,12 @@
 "use strict";
 // src/synth/index.ts - re-export the synthesizer front-ends.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.synthesizeFromRecording = exports.synthesizeFromMandate = exports.scopeToContextRuleType = exports.decideScope = exports.minimize = exports.lower = exports.runHarness = exports.evaluate = exports.generateCases = exports.composeFromRecording = void 0;
+exports.synthesizeFromRecording = exports.synthesizeFromMandate = exports.scopeToContextRuleType = exports.decideScope = exports.minimize = exports.lower = exports.runHarness = exports.evaluate = exports.generateCases = exports.composeFromRecording = exports.isStellarAddress = void 0;
+// Exported because `swapRecipientAllowlist` is part of the public synthesis
+// input: a caller assembling one needs the same validator the schema applies,
+// and re-deriving it elsewhere means a second address check that can drift.
+var address_ts_1 = require("./address.js");
+Object.defineProperty(exports, "isStellarAddress", { enumerable: true, get: function () { return address_ts_1.isStellarAddress; } });
 var compose_from_recording_ts_1 = require("./compose-from-recording.js");
 Object.defineProperty(exports, "composeFromRecording", { enumerable: true, get: function () { return compose_from_recording_ts_1.composeFromRecording; } });
 var deny_cases_ts_1 = require("./deny-cases.js");

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

@@ -1,4 +1,4 @@
 import type { PredicateNode } from '../types.ts';
 import type { EvalContext } from './evaluate.ts';
 /** Remove top-level conjuncts only when the current and regenerated batteries still deny. */
-export declare function minimize(predicate: PredicateNode, permitCtx: EvalContext): PredicateNode;
+export declare function minimize(predicate: PredicateNode, permitCtx: EvalContext, dimensions?: string[]): PredicateNode;

package/dist-cjs/synth/minimize.js

@@ -4,17 +4,17 @@ 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) {
+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);
+        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);
+        const candidateCases = (0, deny_cases_ts_1.generateCases)(candidate, permitCtx, dimensions);
         const verificationCases = {
             permit: candidateCases.permit,
             denies: mergeDenyCases(currentCases.denies, candidateCases.denies),

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

@@ -130,6 +130,31 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             },
         };
     }
+    // 1a. Zero-invocation refusal (item 1). A recording with zero contract
+    //     invocations cleared the parseConfidence gate legitimately (the
+    //     `denom === 0` short-circuit pins overall to 1.0 for that case), but a
+    //     policy must scope to an authorized contract call. Refuse before any
+    //     lower/scope work so the failure is specific and actionable. The
+    //     recorder's silence is also made visible via `parseConfidence.noInvocations`
+    //     so consumers can pattern-match without inferring from `invocations: []`
+    //     next to `overall: 1.0`. The message does NOT ask for an ABI - the
+    //     failure mode is the recording shape, not decoding coverage.
+    const hasNoInvocations = tx.parseConfidence.noInvocations === true || tx.invocations.length === 0;
+    if (hasNoInvocations) {
+        return {
+            ok: false,
+            error: {
+                code: 'SYNTHESIS_ERROR',
+                message: 'Recording contains no contract invocation to scope a policy to. Re-record a transaction that invokes a Soroban contract function (e.g. an SAC/SEP-41 transfer, a Blend yield-claim, or a SoroSwap swap).',
+                severity: 'error',
+                retryable: false,
+                details: {
+                    invocations: tx.invocations.length,
+                    noInvocationsMarker: tx.parseConfidence.noInvocations === true,
+                },
+            },
+        };
+    }
     // Bound the recording size fail-closed (defense-in-depth for direct callers;
     // the MCP schema caps this too).
     if (tx.invocations.length > types_ts_1.SOROBAN_LIMITS.maxInvocations) {
@@ -321,8 +346,10 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             };
         }
         const permitCtx = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate);
-        const finalPredicate = startingPredicate.op === 'and' ? (0, minimize_ts_1.minimize)(startingPredicate, permitCtx) : startingPredicate;
-        const harnessCases = (0, deny_cases_ts_1.generateCases)(finalPredicate, permitCtx);
+        const finalPredicate = startingPredicate.op === 'and'
+            ? (0, minimize_ts_1.minimize)(startingPredicate, permitCtx, deny_cases_ts_1.ORIGINAL_DIMENSIONS)
+            : startingPredicate;
+        const harnessCases = (0, deny_cases_ts_1.generateCases)(finalPredicate, permitCtx, deny_cases_ts_1.ORIGINAL_DIMENSIONS);
         const harnessResult = (0, harness_ts_1.runHarness)(finalPredicate, harnessCases);
         if (!harnessResult.ok) {
             return {
@@ -423,12 +450,24 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
         ...compileRes.proposed.contextRule,
         policies: mergedRefs,
     };
+    // When nothing installable was synthesised (no interpreter doc AND no OZ
+    // policy refs), an empty `policies` array reads as "no restrictions" rather
+    // than "I synthesised nothing". Surface that explicitly so the empty result
+    // is never mistaken for a permissive policy - the context rule still exists,
+    // but it constrains nothing. (Kept as `{ok:true}` so the documented
+    // Path-A/Path-B demo behaviour is preserved - see F3.)
+    const zeroPolicyWarning = mergedRefs.length === 0 && !interpreterPolicyDocument
+        ? [
+            'No policy constraints were synthesised: the call to this contract is UNCONSTRAINED by this policy. Enable the interpreter (supply a smart account) to enforce the surfaced constraints.',
+        ]
+        : [];
     const proposed = {
         contextRule: mergedContextRule,
         policyDocuments: interpreterPolicyDocument ? [interpreterPolicyDocument] : [],
         policyRefs: mergedRefs,
         parseConfidence: { ...tx.parseConfidence },
         warnings: [
+            ...zeroPolicyWarning,
             ...ozUncovered.map((u) => `${UNCOVERED_PREFIX}${u}`),
             ...composed.warnings.map((w) => `${UNCOVERED_PREFIX}${w}`),
         ],
@@ -474,7 +513,7 @@ function validateOptions(opts) {
             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 synthesisError(`limitAmount must be a positive i128 decimal string within [1, ${I128_MAX}] (2^127-1), got: ${ur.limitAmount}`);
         }
     }
     if (opts.interpreter) {
@@ -524,15 +563,24 @@ function validateOptions(opts) {
  *  contract address derivable from the on-chain account, never a
  *  fixture/LLM-seam marker. */
 const PLACEHOLDER_SMART_ACCOUNT_PREFIX = /^(VERIFY-|PLACEHOLDER-|TODO-)/i;
+/** Maximum value a signed i128 can hold (2^127-1). A limitAmount above this
+ *  cannot be represented on-chain, so reject it at the synthesis boundary
+ *  (fail-closed) instead of passing it through as an over-broad spending_limit.
+ *  Mirrors the SOROBAN_LIMITS.u32Max bound the ledger-sequence fields enforce. */
+const I128_MAX = 2n ** 127n - 1n;
 function isPositiveInt(n) {
     return Number.isInteger(n) && n > 0;
 }
-/** True when `s` is a canonical positive decimal integer (i128-safe via BigInt). */
+/** True when `s` is a canonical positive decimal integer inside the signed-i128
+ *  range [1, 2^127-1]. A value above the i128 ceiling is rejected (fail-closed):
+ *  it cannot be installed on-chain, and accepting it would emit a spending_limit
+ *  with an effectively unbounded cap. */
 function isPositiveI128(s) {
     if (!/^[0-9]+$/.test(s))
         return false;
     try {
-        return BigInt(s) > 0n;
+        const v = BigInt(s);
+        return v > 0n && v <= I128_MAX;
     }
     catch {
         return false;

package/dist-cjs/types.d.ts

@@ -21,6 +21,17 @@ export type ScVal = {
 } | {
     type: 'bytes';
     value: string;
+}
+/** Map<Symbol, ScVal> carried forward for SAC/SEP-41 transfer event data,
+ *  which uses a Map shape (key "amount" -> I128) on Stellar mainnet. The
+ *  entry key is captured as its symbol/form string so readAmount can route
+ *  to the conventional field name without re-decoding the full XDR. */
+ | {
+    type: 'map';
+    value: Array<{
+        key: string;
+        val: ScVal;
+    }>;
 } | {
     type: 'other';
     value: string;
@@ -272,7 +283,15 @@ export interface AmbiguityPrompt {
 export type AmbiguityCode = 'DURATION_UNSPECIFIED' | 'AMOUNT_BOUND_MISSING' | 'RECIPIENT_ALLOWLIST_EMPTY' | 'FREQUENCY_BOUND_MISSING' | 'ORACLE_ASSET_UNKNOWN' | 'MULTIPLE_UNRELATED_TARGETS';
 /** Structured recording freshness. `overall` is the gate threshold (default 1.0); the
  *  breakdown is the diagnostic the user / agent sees when the gate fires. The
- *  computation rule is pinned: `overall = 1 - (unknownContracts + opaqueScVals) / total`. */
+ *  computation rule is pinned: `overall = 1 - (unknownContracts + opaqueScVals) / total`.
+ *
+ *  `noInvocations` (item 1) is a recorder-side marker set ONLY when the envelope
+ *  contained zero `invokeContract` host functions (e.g. a `createContract` or
+ *  `uploadContractWasm` op). The math is unchanged: that case still scores 1.0
+ *  via the `denom === 0` guard. The marker exists so a consumer does not have
+ *  to infer the situation from `invocations.length === 0` next to `overall: 1.0`
+ *  — a downstream synth refuses such recordings with a specific, actionable
+ *  error rather than silently producing a useless empty scope. */
 export interface ParseConfidence {
     overall: number;
     knownContracts: string[];
@@ -285,4 +304,8 @@ export interface ParseConfidence {
         type: string;
     }>;
     thresholdUsed: number;
+    /** True iff the recorder decoded zero contract invocations. Absent on
+     *  recordings that pre-date this field; consumers should treat `undefined`
+     *  as "no marker" and rely on `invocations.length` as the fallback. */
+    noInvocations?: true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",