@crediolabs/policy-synth 0.1.5 → 0.1.7

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

@@ -11,8 +11,38 @@ const ADJACENT_ASSETS = [
     'CAS3J7GYLGXMF6TDJ5WQ2PEN4GRVNXJUIQ2TZU3ZB3OQ2V4DRCWI7WPF',
     'CCWCLTASNDT57N3BCHOSVB5QWMV5URK4BXLDDF6ZZQYMBQ4OKZA3ZB2N',
 ];
-/** Build deterministic model-evaluated alternatives without mutating the intended call. */
-export 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'];
+// 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',
+];
+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 function generateCases(predicate, permitCtx, dimensions) {
     const facts = inspectPredicate(predicate);
     const denies = [];
     for (const comparison of facts.comparisons) {
@@ -144,6 +174,32 @@ export 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/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/synth/index.js

@@ -1,4 +1,8 @@
 // src/synth/index.ts - re-export the synthesizer front-ends.
+// 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.
+export { isStellarAddress } from "./address.js";
 export { composeFromRecording, } from "./compose-from-recording.js";
 export { generateCases, } from "./deny-cases.js";
 export { evaluate } from "./evaluate.js";

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

@@ -1,17 +1,17 @@
 import { generateCases } from "./deny-cases.js";
 import { runHarness } from "./harness.js";
 /** Remove top-level conjuncts only when the current and regenerated batteries still deny. */
-export function minimize(predicate, permitCtx) {
+export 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 = generateCases(current, permitCtx);
+        const currentCases = generateCases(current, permitCtx, dimensions);
         const candidateChildren = children.filter((_, childIndex) => childIndex !== index);
         const candidate = { op: 'and', children: candidateChildren };
-        const candidateCases = generateCases(candidate, permitCtx);
+        const candidateCases = generateCases(candidate, permitCtx, dimensions);
         const verificationCases = {
             permit: candidateCases.permit,
             denies: mergeDenyCases(currentCases.denies, candidateCases.denies),

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

@@ -35,7 +35,7 @@ import { createOzAdapter } from "../adapters/oz/adapter.js";
 import { encodePredicate } from "../predicate/encode.js";
 import { MAX_SCVAL_CLONE_DEPTH, OZ_LIMITS, SOROBAN_LIMITS, } from "../types.js";
 import { composeFromRecording, } from "./compose-from-recording.js";
-import { generateCases } from "./deny-cases.js";
+import { generateCases, ORIGINAL_DIMENSIONS } from "./deny-cases.js";
 import { evaluate } from "./evaluate.js";
 import { runHarness } from "./harness.js";
 import { lower } from "./lower.js";
@@ -126,6 +126,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 > SOROBAN_LIMITS.maxInvocations) {
@@ -317,8 +342,10 @@ function synthesizeFromRecordingInner(tx, opts, ozConfig) {
             };
         }
         const permitCtx = buildPermitContext(tx, scope, topLevel, opts.userResponses, startingPredicate);
-        const finalPredicate = startingPredicate.op === 'and' ? minimize(startingPredicate, permitCtx) : startingPredicate;
-        const harnessCases = generateCases(finalPredicate, permitCtx);
+        const finalPredicate = startingPredicate.op === 'and'
+            ? minimize(startingPredicate, permitCtx, ORIGINAL_DIMENSIONS)
+            : startingPredicate;
+        const harnessCases = generateCases(finalPredicate, permitCtx, ORIGINAL_DIMENSIONS);
         const harnessResult = runHarness(finalPredicate, harnessCases);
         if (!harnessResult.ok) {
             return {
@@ -419,12 +446,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}`),
         ],
@@ -473,7 +512,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) {
@@ -523,15 +562,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/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/dist-cjs/record/decode.js

@@ -283,6 +283,26 @@ function scValToSubset(val, path, opaqueScVals, depth = 0) {
                 value: arr.map((v, i) => scValToSubset(v, `${path}[${i}]`, opaqueScVals, depth + 1)),
             };
         }
+        case 'scvMap': {
+            if (depth >= types_ts_1.MAX_SCVAL_DEPTH) {
+                opaqueScVals.push({ path, type: 'depth-exceeded' });
+                return { type: 'other', value: 'depth-exceeded' };
+            }
+            // Map<Symbol, ScVal> is the canonical data shape for SAC/SEP-41
+            // transfer/mint/burn events on Stellar mainnet (verified empirically
+            // against txs 112d2392..., eb39f493..., 50d36f5c...). The entry key is
+            // carried forward so readAmount can route to the conventional field
+            // name without re-decoding the full XDR. Non-symbol / non-string keys
+            // are stringified via the same key-to-string rule used for topics.
+            const entries = (val.map() ?? []);
+            return {
+                type: 'map',
+                value: entries.map((entry, i) => ({
+                    key: mapKeyToString(entry.key(), `${path}.key[${i}]`, opaqueScVals),
+                    val: scValToSubset(entry.val(), `${path}.val[${i}]`, opaqueScVals, depth + 1),
+                })),
+            };
+        }
         case 'scvBytes': {
             return { type: 'bytes', value: Buffer.from(val.bytes()).toString('hex') };
         }
@@ -360,6 +380,29 @@ function scValToTopicString(val) {
         return Buffer.from(val.bytes()).toString('hex');
     return `<${kind}>`;
 }
+/** Convert a Map<Symbol, ...> key ScVal to the string used in the normalised
+ *  ScVal map representation. Uses the same string-form rule as
+ *  `scValToTopicString` so SAC/SEP-41 event Map keys ("amount", "to_muxed_id")
+ *  resolve to the same string in both the topic path and the map-entry path.
+ *  Non-symbol / non-string keys record an opaque diagnostic and return a
+ *  placeholder so the Map entry is still carried forward. */
+function mapKeyToString(val, path, opaqueScVals) {
+    const kind = val.switch().name;
+    if (kind === 'scvSymbol')
+        return val.sym().toString();
+    if (kind === 'scvString')
+        return val.str().toString();
+    if (kind === 'scvU64')
+        return u64PartsToBigInt(val.u64()).toString();
+    if (kind === 'scvU32')
+        return val.u32().toString();
+    if (kind === 'scvI128')
+        return i128PartsToBigInt(val.i128()).toString();
+    if (kind === 'scvBytes')
+        return Buffer.from(val.bytes()).toString('hex');
+    opaqueScVals.push({ path, type: `unsupported-map-key:${kind}` });
+    return `<${kind}>`;
+}
 /** Build the OnChainEvent[] view from raw contract events. Diagnostic-only:
  *  captures the topics + data + emitter contract for the downstream
  *  validator. */

package/dist-cjs/record/freshness.d.ts

@@ -13,5 +13,18 @@ export declare function computeParseConfidence(input: FreshnessInput): ParseConf
  *  ToolError with the ParseConfidence payload attached as `details`. */
 export declare function isBelowThreshold(c: ParseConfidence): boolean;
 /** Convenience: build the user-facing remediation question for an
- *  under-confidence recording. */
+ *  under-confidence recording.
+ *
+ *  The remediation text branches on which diagnostic bucket is non-empty:
+ *    - unknownContracts only -> user MUST supply an ABI (or re-capture
+ *      against a known protocol version). The contract is real, the
+ *      recorder just cannot decode it.
+ *    - opaqueScVals only -> the recorder encountered a value shape it
+ *      should support but did not decode. The user cannot supply an ABI
+ *      to fix a decoder bug; the guidance explicitly says so and points at
+ *      re-running after a tool upgrade / reporting the path.
+ *    - both -> list both diagnostics AND chain the right remediation for
+ *      each (the user supplies an ABI AND reports the decoder gap).
+ *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
+ *      text; the user did not actually hit a code-level barrier. */
 export declare function buildLowConfidenceQuestion(c: ParseConfidence): string;

package/dist-cjs/record/freshness.js

@@ -41,8 +41,23 @@ function isBelowThreshold(c) {
     return c.overall < c.thresholdUsed;
 }
 /** Convenience: build the user-facing remediation question for an
- *  under-confidence recording. */
+ *  under-confidence recording.
+ *
+ *  The remediation text branches on which diagnostic bucket is non-empty:
+ *    - unknownContracts only -> user MUST supply an ABI (or re-capture
+ *      against a known protocol version). The contract is real, the
+ *      recorder just cannot decode it.
+ *    - opaqueScVals only -> the recorder encountered a value shape it
+ *      should support but did not decode. The user cannot supply an ABI
+ *      to fix a decoder bug; the guidance explicitly says so and points at
+ *      re-running after a tool upgrade / reporting the path.
+ *    - both -> list both diagnostics AND chain the right remediation for
+ *      each (the user supplies an ABI AND reports the decoder gap).
+ *    - neither (the "denom === 0" path) -> unchanged from the pre-fix
+ *      text; the user did not actually hit a code-level barrier. */
 function buildLowConfidenceQuestion(c) {
+    const hasUnknown = c.unknownContracts.length > 0;
+    const hasOpaque = c.opaqueScVals.length > 0;
     const reasons = [];
     for (const u of c.unknownContracts) {
         reasons.push(`unknown contract ${u.contract} (${u.reason})`);
@@ -51,5 +66,20 @@ function buildLowConfidenceQuestion(c) {
         reasons.push(`opaque ScVal at ${o.path} (${o.type})`);
     }
     const why = reasons.length === 0 ? 'no diagnostic reason available' : reasons.join('; ');
-    return `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}. Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+    const header = `Recording refused: parseConfidence ${c.overall.toFixed(3)} is below the threshold ${c.thresholdUsed.toFixed(3)}. Diagnostic: ${why}.`;
+    // The two remediation branches are explicit so the user (or the agent)
+    // can dispatch on the verb. The "unknown contract" branch is the only
+    // one that asks for an ABI; the "opaque ScVal" branch asks the user to
+    // report the path and re-run after a tool upgrade.
+    if (hasUnknown && hasOpaque) {
+        return (`${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version; ` +
+            `also file the opaque ScVal path against the recorder (decoder limitation) and re-run record_transaction after a tool upgrade.`);
+    }
+    if (hasUnknown) {
+        return `${header} Supply an ABI for the unknown contract(s) or re-capture the transaction against a known protocol version, then re-run record_transaction.`;
+    }
+    if (hasOpaque) {
+        return `${header} This is a recorder decoder limitation (the value shape is supported in principle but not yet decoded) - the agent cannot fix it by supplying an ABI. Report the opaque ScVal path above against the recorder and re-run record_transaction after a tool upgrade.`;
+    }
+    return `${header} No actionable diagnostic was recorded; re-run record_transaction against a fresh fetch and inspect the events.`;
 }

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

@@ -5,6 +5,9 @@ import { type RpcFetcher } from './rpc.ts';
  *    - exactly one of `hash` / `xdr`
  *    - `network` for hash mode (selects the public RPC)
  *    - optional injected `fetcher` for tests + custom RPC endpoints
+ *    - optional `crossNetworkFetcher` (item 2) for tests + offline use;
+ *      production builds the cross-network probe from `createRpcServer` when
+ *      this field is absent
  *    - optional `confidenceOverride` to relax the gate (default 1.0)
  *
  *  In xdr mode `network` is still required so the caller documents intent
@@ -15,6 +18,14 @@ export interface RecordInput {
     xdr?: string;
     network: Network;
     fetcher?: RpcFetcher;
+    /** Test-only seam + explicit production override for the cross-network
+     *  probe (item 2). When the primary fetcher returns null on hash mode,
+     *  the recorder also tries this fetcher against the OTHER network. If it
+     *  finds the hash there, the recorder returns a specific actionable
+     *  error mentioning the actual network. When unset, the recorder builds
+     *  this fetcher from `createRpcServer(otherNetwork)` so the help fires
+     *  automatically; tests can pass a deterministic stub. */
+    crossNetworkFetcher?: RpcFetcher;
     confidenceOverride?: number;
 }
 export type RecordResult = ToolResponse<RecordedTransaction>;

package/dist-cjs/record/index.js

@@ -53,6 +53,21 @@ async function recordTransaction(input) {
             return err('RECORDING_FAILED', 'hash required for on-chain mode', false);
         const fetched = await fetcher(hash);
         if (!fetched) {
+            // Item 2: cross-network sanity check. The default NOT_FOUND message
+            // ("transaction X not found on <network>") is not actionable when the
+            // user just used the wrong --network. Probe the OTHER network's
+            // fetcher before giving up: if the hash actually exists there, the
+            // user almost certainly passed the wrong network flag. Trade-off:
+            // one extra RPC round-trip ONLY on the NOT_FOUND path (the happy
+            // path is unchanged; NOT_FOUND is rare). The probe is auto-built
+            // from createRpcServer(otherNetwork) when the caller did not inject
+            // one; tests pass an explicit stub for offline determinism.
+            const otherNetwork = input.network === 'mainnet' ? 'testnet' : 'mainnet';
+            const crossFetcher = input.crossNetworkFetcher ?? (0, rpc_ts_1.createRpcServer)(otherNetwork);
+            const crossFetched = await crossFetcher(hash);
+            if (crossFetched) {
+                return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}; it exists on ${otherNetwork}. Re-run with --network ${otherNetwork} (or the corresponding MCP / API field).`, true);
+            }
             return err('RECORDING_FAILED', `transaction ${hash} not found on ${input.network}`, true);
         }
         const events = combineEvents(fetched.events);
@@ -128,6 +143,16 @@ function finish(network, decoded, confidenceOverride) {
         unknownContracts: decoded.unknownContracts,
         opaqueScVals: decoded.opaqueScVals,
     });
+    // Item 1: surface the "zero contract invocations decoded" case explicitly.
+    // The math already pins overall = 1.0 via the `denom === 0` guard; the
+    // marker just makes the silence visible so a downstream synth can refuse
+    // the recording (a policy must scope to an authorized contract call)
+    // without inferring the situation from `invocations: []` next to a
+    // confidence of 1.0. Only set when zero invocations were actually decoded
+    // - the marker is a positive signal, not a default.
+    if (decoded.invocations.length === 0) {
+        confidence = { ...confidence, noInvocations: true };
+    }
     if (typeof confidenceOverride === 'number') {
         confidence = { ...confidence, thresholdUsed: confidenceOverride };
     }

package/dist-cjs/record/movements.d.ts

@@ -9,9 +9,21 @@ export declare function extractTokenMovements(events: OnChainEvent[], opaqueScVa
 }>): TokenMovement[];
 /** Read an I128 amount from an event data ScVal. Supports:
  *    - data is I128 directly
- *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128
- *    - data is a Vec whose [0] is a Map { 'amount': I128 }
- *    - data is U64 (fallback for amount fields encoded as u64) */
+ *    - data is U64 (fallback for amount fields encoded as u64)
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128 / U64
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 | U64 }
+ *    - data is a Map whose entry with key "amount" is I128 / U64
+ *
+ *  The Map shapes are the canonical data layout for SAC/SEP-41 `transfer`,
+ *  `mint`, and `burn` events on Stellar mainnet, e.g. the USDC SAC and every
+ *  Stellar Asset Contract. The key `amount` is the SEP-41-defined field name
+ *  (verified empirically against txs 112d2392..., eb39f493..., 50d36f5c...
+ *  where the data is `Map { amount: I128, to_muxed_id: ... }`). The other
+ *  Map entries we observe in the wild (to_muxed_id, from_muxed_id) are
+ *  muxed-address adjuncts that the recorder does not support as topic
+ *  addresses; they are ignored here on purpose. A Map without an `amount`
+ *  entry, or with an `amount` entry that is not I128/U64, returns null
+ *  (fail-closed). */
 export declare function readAmount(data: OnChainEvent['data']): string | null;
 /** Re-decode a single ContractEvent body into a TokenMovement-shaped tuple,
  *  given the raw xdr.ScVal form (NOT the OnChainEvent subset). Used by the

package/dist-cjs/record/movements.js

@@ -86,25 +86,60 @@ function parseSingleEvent(evt) {
 }
 /** Read an I128 amount from an event data ScVal. Supports:
  *    - data is I128 directly
- *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128
- *    - data is a Vec whose [0] is a Map { 'amount': I128 }
- *    - data is U64 (fallback for amount fields encoded as u64) */
+ *    - data is U64 (fallback for amount fields encoded as u64)
+ *    - data is a Vec whose [0] (or [1] for SAC transfer) is I128 / U64
+ *    - data is a Vec whose [0] is a Map { 'amount': I128 | U64 }
+ *    - data is a Map whose entry with key "amount" is I128 / U64
+ *
+ *  The Map shapes are the canonical data layout for SAC/SEP-41 `transfer`,
+ *  `mint`, and `burn` events on Stellar mainnet, e.g. the USDC SAC and every
+ *  Stellar Asset Contract. The key `amount` is the SEP-41-defined field name
+ *  (verified empirically against txs 112d2392..., eb39f493..., 50d36f5c...
+ *  where the data is `Map { amount: I128, to_muxed_id: ... }`). The other
+ *  Map entries we observe in the wild (to_muxed_id, from_muxed_id) are
+ *  muxed-address adjuncts that the recorder does not support as topic
+ *  addresses; they are ignored here on purpose. A Map without an `amount`
+ *  entry, or with an `amount` entry that is not I128/U64, returns null
+ *  (fail-closed). */
 function readAmount(data) {
     if (data.type === 'i128')
         return data.value;
     if (data.type === 'u64')
         return data.value;
+    if (data.type === 'map')
+        return readAmountFromMap(data.value);
     if (data.type !== 'vec')
         return null;
-    const v = data.value;
-    // SAC transfer event data shape (some clients): Vec<Address, I128>
-    for (const item of v) {
+    // Vec shape: walk the elements and accept the first I128/U64 OR a Map whose
+    // 'amount' entry is I128/U64. SAC transfer event data is sometimes
+    // Vec<Address, I128> and sometimes Vec<Map{amount: I128}, ...>; both reach
+    // the same code path below.
+    for (const item of data.value) {
         if (item.type === 'i128')
             return item.value;
         if (item.type === 'u64')
             return item.value;
+        if (item.type === 'map') {
+            const fromMap = readAmountFromMap(item.value);
+            if (fromMap !== null)
+                return fromMap;
+        }
+    }
+    return null;
+}
+/** Try to extract an I128/U64 amount from a Map's `amount` entry. Returns
+ *  null when the Map lacks an `amount` key or the entry is not a numeric
+ *  ScVal kind this recorder understands. */
+function readAmountFromMap(entries) {
+    for (const entry of entries) {
+        if (entry.key !== 'amount')
+            continue;
+        if (entry.val.type === 'i128')
+            return entry.val.value;
+        if (entry.val.type === 'u64')
+            return entry.val.value;
+        return null;
     }
-    // Some flavours wrap in a Map. We expose Map entries as other; bail.
     return null;
 }
 /** Extract a single address from an event data ScVal at the given vec index. */

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

@@ -1,4 +1,4 @@
-import { type ProposedPolicy, type RecordedTransaction, type ToolResponse } from '../index.ts';
+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';
@@ -29,3 +29,15 @@ export declare function runRecordTransaction(raw: unknown): Promise<ToolResponse
  *  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;