@onchaindiligence/sdk 0.2.0 → 0.3.1

package/dist/commerce/executor.js

@@ -0,0 +1,19 @@
+/**
+ * executor.ts — the CommerceExecutor contract (D2.5, Section 3).
+ *
+ * OCD evaluates. The executor authorizes and submits. These are DELIBERATELY
+ * independent: an OCD ALLOW is a policy opinion, never a grant of wallet
+ * authority, and this interface exists precisely so a developer can swap
+ * wallets/providers without OCD code ever touching a private key or a
+ * payment authorization it didn't need to see.
+ *
+ * `prepare()` MUST NOT broadcast anything — it is the point where a durable
+ * execution/payment identity is created (and, in the commerce client's
+ * orchestration, persisted to the recovery store and registered with OCD's
+ * execution-bindings endpoint) BEFORE any state-changing network call.
+ * `submit()` is called AT MOST ONCE per prepared identity by the orchestrator
+ * — an executor must never invent a second identity/authorization on its
+ * own initiative. `resume()` must query/resume the SAME prepared identity,
+ * never fabricate a new payment.
+ */
+export {};

package/dist/commerce/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @onchaindiligence/sdk/commerce
+ * ------------------------------
+ * The online commerce client (D2.5): open/resume a durable OCD operation,
+ * evaluate preflight, execute through an independent executor, and
+ * observe/finalize into a signed Commerce Receipt — without hand-assembling
+ * onchaindiligence-mcp's D2.4 lifecycle machinery yourself.
+ *
+ *   import { createCommerceClient, MockCommerceExecutor } from '@onchaindiligence/sdk/commerce'
+ *
+ * Kept separate from the package's root export (the OFFLINE compliance-API
+ * client + zero-network attestation verifier) — this module makes network
+ * calls and requires a durable recovery store; the root export does not.
+ *
+ * BROWSER-SAFE by construction: everything here bundles for
+ * `--platform=browser` (no Node built-ins). `NodeFileRecoveryStore` is
+ * genuinely Node-only (it wraps `node:fs`) and lives at the separate
+ * `@onchaindiligence/sdk/commerce/node` subpath instead — importing THIS
+ * barrel from a browser bundle can never accidentally pull in `node:fs`.
+ */
+export * from './types.js';
+export * from './results.js';
+export * from './executor.js';
+export * from './recoveryStore.js';
+export * from './mockExecutor.js';
+export * from './x402Executor.js';
+export * from './client.js';
+export * from './policyTemplates.js';
+export * from './evidenceExport.js';

package/dist/commerce/index.js

@@ -0,0 +1,29 @@
+/**
+ * @onchaindiligence/sdk/commerce
+ * ------------------------------
+ * The online commerce client (D2.5): open/resume a durable OCD operation,
+ * evaluate preflight, execute through an independent executor, and
+ * observe/finalize into a signed Commerce Receipt — without hand-assembling
+ * onchaindiligence-mcp's D2.4 lifecycle machinery yourself.
+ *
+ *   import { createCommerceClient, MockCommerceExecutor } from '@onchaindiligence/sdk/commerce'
+ *
+ * Kept separate from the package's root export (the OFFLINE compliance-API
+ * client + zero-network attestation verifier) — this module makes network
+ * calls and requires a durable recovery store; the root export does not.
+ *
+ * BROWSER-SAFE by construction: everything here bundles for
+ * `--platform=browser` (no Node built-ins). `NodeFileRecoveryStore` is
+ * genuinely Node-only (it wraps `node:fs`) and lives at the separate
+ * `@onchaindiligence/sdk/commerce/node` subpath instead — importing THIS
+ * barrel from a browser bundle can never accidentally pull in `node:fs`.
+ */
+export * from './types.js';
+export * from './results.js';
+export * from './executor.js';
+export * from './recoveryStore.js';
+export * from './mockExecutor.js';
+export * from './x402Executor.js';
+export * from './client.js';
+export * from './policyTemplates.js';
+export * from './evidenceExport.js';

package/dist/commerce/mockExecutor.d.ts

@@ -0,0 +1,41 @@
+/**
+ * mockExecutor.ts — a deterministic, no-network CommerceExecutor for the
+ * quickstart and tests. It never touches a chain and never moves money;
+ * every outcome is scripted so documentation and tests can demonstrate the
+ * FULL lifecycle without a live payment, per D2.5's own mandate ("Use a
+ * mocked/test executor for the normal quickstart so running documentation
+ * does not cost money").
+ */
+import type { CommerceExecutor, PrepareContext, PrepareResult, ExecutionResult, ExecutorRecoveryMode } from './executor.js';
+export type MockOutcomeScript = {
+    kind: 'success';
+    transactionHash?: string;
+} | {
+    kind: 'ambiguous-then-success';
+    transactionHash?: string;
+} | {
+    kind: 'manual-recovery';
+};
+export interface MockExecutorOptions {
+    recoveryMode?: ExecutorRecoveryMode;
+    /** What submit()/resume() should do. Defaults to an immediate success. */
+    script?: MockOutcomeScript;
+}
+/**
+ * A minimal, fully in-memory executor. `prepare()` just records the frozen
+ * action; `submit()` follows the configured script exactly once; `resume()`
+ * only ever returns what submit() already committed to (or manual recovery,
+ * for a 'manual' script) — it never invents a new outcome.
+ */
+export declare class MockCommerceExecutor implements CommerceExecutor {
+    readonly id = "mock-executor";
+    readonly version = "v1";
+    readonly recoveryMode: ExecutorRecoveryMode;
+    private readonly script;
+    private readonly submittedOnce;
+    private readonly outcomes;
+    constructor(options?: MockExecutorOptions);
+    prepare(context: PrepareContext): Promise<PrepareResult>;
+    submit(prepared: PrepareResult): Promise<ExecutionResult>;
+    resume(prepared: PrepareResult): Promise<ExecutionResult>;
+}

package/dist/commerce/mockExecutor.js

@@ -0,0 +1,74 @@
+/** Universal (Node + browser) random hex via Web Crypto -- this file must stay bundle-safe for a browser operator, unlike nodeFileRecoveryStore.ts. */
+function fakeTransactionHash() {
+    const bytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(bytes);
+    return '0x' + Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * A minimal, fully in-memory executor. `prepare()` just records the frozen
+ * action; `submit()` follows the configured script exactly once; `resume()`
+ * only ever returns what submit() already committed to (or manual recovery,
+ * for a 'manual' script) — it never invents a new outcome.
+ */
+export class MockCommerceExecutor {
+    id = 'mock-executor';
+    version = 'v1';
+    recoveryMode;
+    script;
+    submittedOnce = new Set();
+    outcomes = new Map();
+    constructor(options = {}) {
+        this.recoveryMode = options.recoveryMode ?? 'stable-payment-identity';
+        this.script = options.script ?? { kind: 'success' };
+    }
+    async prepare(context) {
+        return { clientSubmissionKey: context.clientSubmissionKey, reference: { action: context.action }, preparedAt: new Date().toISOString() };
+    }
+    async submit(prepared) {
+        const key = prepared.clientSubmissionKey;
+        if (this.submittedOnce.has(key)) {
+            // An orchestrator bug would be the only way to reach this twice for
+            // the same key -- report it as ambiguous rather than silently
+            // fabricating a second transaction, exactly what a real executor must do.
+            return { clientSubmissionKey: key, status: 'submission-ambiguous', reason: 'submit() called twice for the same clientSubmissionKey' };
+        }
+        this.submittedOnce.add(key);
+        if (this.script.kind === 'manual-recovery') {
+            const outcome = { clientSubmissionKey: key, status: 'manual-recovery-required', reason: 'mock script: no safe recovery identity' };
+            this.outcomes.set(key, outcome);
+            return outcome;
+        }
+        if (this.script.kind === 'ambiguous-then-success') {
+            const outcome = { clientSubmissionKey: key, status: 'submission-ambiguous', reason: 'mock script: simulated lost response after submission' };
+            this.outcomes.set(key, outcome);
+            return outcome;
+        }
+        const outcome = {
+            clientSubmissionKey: key,
+            status: 'transaction-known',
+            transactionHash: this.script.transactionHash ?? fakeTransactionHash(),
+            providerReference: this.id,
+        };
+        this.outcomes.set(key, outcome);
+        return outcome;
+    }
+    async resume(prepared) {
+        const key = prepared.clientSubmissionKey;
+        const prior = this.outcomes.get(key);
+        if (prior?.status === 'submission-ambiguous' && this.script.kind === 'ambiguous-then-success') {
+            // The scripted "resolves on resume" case -- mirrors a real executor
+            // that can now confirm what actually happened, e.g. a chain lookup.
+            const resolved = {
+                clientSubmissionKey: key,
+                status: 'transaction-known',
+                transactionHash: this.script.transactionHash ?? fakeTransactionHash(),
+                providerReference: this.id,
+            };
+            this.outcomes.set(key, resolved);
+            return resolved;
+        }
+        if (prior)
+            return prior;
+        return { clientSubmissionKey: key, status: 'manual-recovery-required', reason: 'resume() called before submit() ever ran for this identity' };
+    }
+}

package/dist/commerce/nodeFileRecoveryStore.d.ts

@@ -0,0 +1,17 @@
+import { type CommerceRecoveryStore, type CommerceRecoveryRecord } from './recoveryStore.js';
+export declare class NodeFileRecoveryStore implements CommerceRecoveryStore {
+    private readonly directory;
+    private queue;
+    constructor(directory: string);
+    private pathFor;
+    /** Serializes all reads+writes for this store instance so create/update's read-then-write is never interleaved with another call in the same process. */
+    private locked;
+    private readRaw;
+    private writeRaw;
+    create(record: Omit<CommerceRecoveryRecord, 'version' | 'createdAt' | 'updatedAt'>): Promise<CommerceRecoveryRecord>;
+    load(operationId: string): Promise<CommerceRecoveryRecord | null>;
+    update(operationId: string, patch: Partial<Omit<CommerceRecoveryRecord, 'operationId' | 'version'>>, expectedVersion: number): Promise<CommerceRecoveryRecord>;
+    findByClientSubmissionKey(clientSubmissionKey: string): Promise<CommerceRecoveryRecord | null>;
+    /** Test/example convenience: not part of the interface. */
+    _deleteForTests(operationId: string): Promise<void>;
+}

package/dist/commerce/nodeFileRecoveryStore.js

@@ -0,0 +1,126 @@
+/**
+ * nodeFileRecoveryStore.ts — a real, restart-surviving CommerceRecoveryStore
+ * for Node (single-process apps, the operator UI, examples, tests).
+ *
+ * Storage: one JSON file per operation under `directory`, named
+ * `<operationId>.json`. Writes are atomic (write to a temp file, then
+ * rename) so a crash mid-write can never leave a half-written, corrupt
+ * record — the rename either lands or it doesn't.
+ *
+ * Concurrency: compare-and-swap is enforced at the application level (the
+ * version field is checked before every write) and writes within one
+ * process are serialized per-operation by an in-memory lock queue, so two
+ * concurrent calls in the SAME process can't race past each other between
+ * the read and the write. This is NOT a multi-process/multi-machine lock —
+ * if your deployment runs more than one instance against the same
+ * directory, implement CommerceRecoveryStore against a real database with
+ * native CAS (e.g. a WHERE version = $n UPDATE) instead.
+ *
+ * Secrets (recoveryCredential, finalizationCapability) are stored in this
+ * file in plaintext. This is appropriate for local, single-user, file-
+ * system-permission-protected use (examples, the local operator) — a real
+ * multi-user production deployment should encrypt at rest or use a secrets
+ * manager, which is exactly why this is one INTERCHANGEABLE implementation
+ * of the interface, not the interface itself.
+ */
+import { mkdir, readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { RecoveryRecordExistsError, RecoveryRecordNotFoundError, VersionConflictError, } from './recoveryStore.js';
+function isValidOperationId(operationId) {
+    // Matches the shape onchaindiligence-mcp's operation.ts generates
+    // (OCD-OP- + base64url); rejected characters could otherwise be used to
+    // escape `directory` via a crafted operationId.
+    return /^[A-Za-z0-9_-]{1,128}$/.test(operationId);
+}
+export class NodeFileRecoveryStore {
+    directory;
+    queue = Promise.resolve();
+    constructor(directory) {
+        this.directory = directory;
+    }
+    pathFor(operationId) {
+        if (!isValidOperationId(operationId))
+            throw new TypeError(`invalid operationId for file storage: ${operationId}`);
+        return join(this.directory, `${operationId}.json`);
+    }
+    /** Serializes all reads+writes for this store instance so create/update's read-then-write is never interleaved with another call in the same process. */
+    locked(fn) {
+        const run = this.queue.then(fn, fn);
+        this.queue = run.catch(() => { });
+        return run;
+    }
+    async readRaw(operationId) {
+        try {
+            const text = await readFile(this.pathFor(operationId), 'utf8');
+            return JSON.parse(text);
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async writeRaw(operationId, record) {
+        await mkdir(this.directory, { recursive: true });
+        const finalPath = this.pathFor(operationId);
+        const tempPath = join(this.directory, `.${operationId}.${randomBytes(4).toString('hex')}.tmp`);
+        await writeFile(tempPath, JSON.stringify(record, null, 2), 'utf8');
+        await rename(tempPath, finalPath); // atomic on the same filesystem
+    }
+    async create(record) {
+        return this.locked(async () => {
+            const existing = await this.readRaw(record.operationId);
+            if (existing)
+                throw new RecoveryRecordExistsError(record.operationId);
+            const now = new Date().toISOString();
+            const full = { ...record, version: 1, createdAt: now, updatedAt: now };
+            await this.writeRaw(record.operationId, full);
+            return full;
+        });
+    }
+    async load(operationId) {
+        return this.locked(() => this.readRaw(operationId));
+    }
+    async update(operationId, patch, expectedVersion) {
+        return this.locked(async () => {
+            const existing = await this.readRaw(operationId);
+            if (!existing)
+                throw new RecoveryRecordNotFoundError(operationId);
+            if (existing.version !== expectedVersion)
+                throw new VersionConflictError(operationId, expectedVersion, existing.version);
+            const updated = { ...existing, ...patch, version: existing.version + 1, updatedAt: new Date().toISOString() };
+            await this.writeRaw(operationId, updated);
+            return updated;
+        });
+    }
+    async findByClientSubmissionKey(clientSubmissionKey) {
+        // No index -- a real production store backed by a database should add
+        // one. Scoped to Node's readdir, acceptable for the small, local,
+        // single-operator-at-a-time use this implementation targets.
+        return this.locked(async () => {
+            const { readdir } = await import('node:fs/promises');
+            let files;
+            try {
+                files = await readdir(this.directory);
+            }
+            catch (err) {
+                if (err?.code === 'ENOENT')
+                    return null;
+                throw err;
+            }
+            for (const file of files) {
+                if (!file.endsWith('.json') || file.startsWith('.'))
+                    continue;
+                const record = await this.readRaw(file.slice(0, -'.json'.length));
+                if (record?.clientSubmissionKey === clientSubmissionKey)
+                    return record;
+            }
+            return null;
+        });
+    }
+    /** Test/example convenience: not part of the interface. */
+    async _deleteForTests(operationId) {
+        await unlink(this.pathFor(operationId)).catch(() => { });
+    }
+}

package/dist/commerce/policyTemplates.d.ts

@@ -0,0 +1,48 @@
+/**
+ * policyTemplates.ts — a SMALL set of versioned starter policy templates
+ * (D2.5, Section 9). These are convenience functions that produce ordinary
+ * strict CommercePolicy objects — they introduce NO new policy semantics,
+ * NO natural-language interpretation, and NO authorization authority. Every
+ * `policy` object returned here is exactly what a developer could have
+ * hand-written against onchaindiligence-mcp's own strict, closed-schema
+ * policy parser (which rejects any unrecognized field outright) — so the
+ * version is returned ALONGSIDE the policy, never embedded inside it; a
+ * template_version field inside `policy` itself would be rejected as an
+ * unrecognized field by the server.
+ */
+import type { CommercePolicy } from './types.js';
+export declare const POLICY_TEMPLATE_VERSION = "onchaindiligence.policy-template.v1";
+export interface PolicyTemplateResult {
+    policy: CommercePolicy;
+    templateVersion: typeof POLICY_TEMPLATE_VERSION;
+    templateName: string;
+}
+/** A. Bounded API purchase: caps amount, network, and asset; no recipient/origin restriction. */
+export declare function apiPurchasePolicy(params: {
+    maxAmount: string;
+    allowedNetwork: string;
+    allowedAsset: string;
+}): PolicyTemplateResult;
+/**
+ * B. Approval required above threshold: this template alone cannot express
+ * "ALLOW below X, REQUIRE_APPROVAL above X" as a single policy object — OCD
+ * policy evaluation is FAIL-closed on max_amount (exceeding it is BLOCK, not
+ * REQUIRE_APPROVAL; see onchaindiligence-mcp's evaluatePreflightPolicy). This
+ * helper instead returns the policy to use for the "approval" tier: no
+ * amount cap at all (acknowledged explicitly), so amount-based judgment is
+ * left entirely to whatever separate human/approval process the developer's
+ * own application wires up above OCD -- OCD's role stays what it always is
+ * (policy evaluation), never a stand-in for that approval step.
+ */
+export declare function approvalAboveThresholdPolicy(params: {
+    allowedNetwork: string;
+    allowedAsset: string;
+    expectedRecipient?: string | null;
+}): PolicyTemplateResult;
+/** C. Fixed-recipient bounded payment: caps amount AND pins the exact recipient — the tightest of the three templates. */
+export declare function fixedRecipientPolicy(params: {
+    maxAmount: string;
+    allowedNetwork: string;
+    allowedAsset: string;
+    expectedRecipient: string;
+}): PolicyTemplateResult;

package/dist/commerce/policyTemplates.js

@@ -0,0 +1,54 @@
+export const POLICY_TEMPLATE_VERSION = 'onchaindiligence.policy-template.v1';
+/** A. Bounded API purchase: caps amount, network, and asset; no recipient/origin restriction. */
+export function apiPurchasePolicy(params) {
+    return {
+        policy: {
+            max_amount: params.maxAmount,
+            allowed_networks: [params.allowedNetwork],
+            allowed_assets: [params.allowedAsset],
+            expected_recipient: null,
+            allowed_resource_origins: null,
+        },
+        templateVersion: POLICY_TEMPLATE_VERSION,
+        templateName: 'bounded-api-purchase',
+    };
+}
+/**
+ * B. Approval required above threshold: this template alone cannot express
+ * "ALLOW below X, REQUIRE_APPROVAL above X" as a single policy object — OCD
+ * policy evaluation is FAIL-closed on max_amount (exceeding it is BLOCK, not
+ * REQUIRE_APPROVAL; see onchaindiligence-mcp's evaluatePreflightPolicy). This
+ * helper instead returns the policy to use for the "approval" tier: no
+ * amount cap at all (acknowledged explicitly), so amount-based judgment is
+ * left entirely to whatever separate human/approval process the developer's
+ * own application wires up above OCD -- OCD's role stays what it always is
+ * (policy evaluation), never a stand-in for that approval step.
+ */
+export function approvalAboveThresholdPolicy(params) {
+    return {
+        policy: {
+            max_amount: null,
+            allowed_networks: [params.allowedNetwork],
+            allowed_assets: [params.allowedAsset],
+            expected_recipient: params.expectedRecipient ?? null,
+            allowed_resource_origins: null,
+            acknowledge_unconstrained: true,
+        },
+        templateVersion: POLICY_TEMPLATE_VERSION,
+        templateName: 'approval-above-threshold',
+    };
+}
+/** C. Fixed-recipient bounded payment: caps amount AND pins the exact recipient — the tightest of the three templates. */
+export function fixedRecipientPolicy(params) {
+    return {
+        policy: {
+            max_amount: params.maxAmount,
+            allowed_networks: [params.allowedNetwork],
+            allowed_assets: [params.allowedAsset],
+            expected_recipient: params.expectedRecipient,
+            allowed_resource_origins: null,
+        },
+        templateVersion: POLICY_TEMPLATE_VERSION,
+        templateName: 'fixed-recipient-bounded-payment',
+    };
+}

package/dist/commerce/recoveryStore.d.ts

@@ -0,0 +1,73 @@
+/**
+ * recoveryStore.ts — durable recovery abstraction for the commerce client.
+ *
+ * This is the ONE thing standing between "lost my HTTP response" and "paid
+ * twice" or "sent a duplicate merchant payment" on the CLIENT side — the
+ * mirror image of what onchaindiligence-mcp's own lifecycle_steps /
+ * execution_bindings tables do server-side (D2.4). A developer's application
+ * MUST persist a record here BEFORE calling anything that could move money
+ * (preflight, executor.prepare, executor.submit) so a crash between "we
+ * asked" and "we got an answer" has something durable to resume from.
+ *
+ * `create`/`update` use explicit optimistic concurrency (a version counter)
+ * rather than silent last-write-wins, so two concurrent processes touching
+ * the same operation can never silently clobber each other's state — one of
+ * them gets a VersionConflictError and must reload and retry.
+ *
+ * The in-memory implementation exists ONLY for tests and throwaway scripts.
+ * It is explicitly NOT advertised as production-safe (it does not survive a
+ * process restart, which defeats the entire point of this interface) — see
+ * NodeFileRecoveryStore for a real, restart-surviving option, and implement
+ * this interface against your own database for a multi-instance deployment.
+ */
+export interface CommerceRecoveryRecord {
+    operationId: string;
+    /** The OCD-issued recovery credential — required to call GET /operations/:id, POST .../execution-bindings, POST .../finalize. Never log this. */
+    recoveryCredential: string;
+    /** Optimistic-concurrency version. Starts at 1; every update() must supply the version it read and gets back the new one. */
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    preflightReceiptId: string | null;
+    /** The one-time finalization capability token, when known. Never log this. */
+    finalizationCapability: string | null;
+    finalizationCapabilityExpiresAt: string | null;
+    executionRequestId: string | null;
+    /** Caller-chosen idempotency key for the executor's submission attempt — see executor.ts. */
+    clientSubmissionKey: string | null;
+    /** The `id` of the CommerceExecutor used for the current/last execution attempt — used only to label the finalize call's execution_provider field. */
+    executorId: string | null;
+    transactionHash: string | null;
+    /** Free-form local phase label for the developer's own UI/logging — never trusted as the source of truth (the server's /operations/:id status is). */
+    localPhase: string;
+}
+export declare class RecoveryRecordExistsError extends Error {
+    constructor(operationId: string);
+}
+export declare class RecoveryRecordNotFoundError extends Error {
+    constructor(operationId: string);
+}
+export declare class VersionConflictError extends Error {
+    constructor(operationId: string, expected: number, actual: number);
+}
+export interface CommerceRecoveryStore {
+    /** Atomic create. Throws RecoveryRecordExistsError if the operationId is already present. */
+    create(record: Omit<CommerceRecoveryRecord, 'version' | 'createdAt' | 'updatedAt'>): Promise<CommerceRecoveryRecord>;
+    load(operationId: string): Promise<CommerceRecoveryRecord | null>;
+    /** Compare-and-swap update: `expectedVersion` must match the currently-stored version, or this throws VersionConflictError without applying the patch. */
+    update(operationId: string, patch: Partial<Omit<CommerceRecoveryRecord, 'operationId' | 'version'>>, expectedVersion: number): Promise<CommerceRecoveryRecord>;
+    /** Convenience lookup used by resume-after-restart flows that only know the executor's own idempotency key, not the operation id. Optional: stores that can't index this may return null always. */
+    findByClientSubmissionKey(clientSubmissionKey: string): Promise<CommerceRecoveryRecord | null>;
+}
+/**
+ * Volatile, single-process, TEST/EXAMPLE-ONLY implementation. Does not
+ * survive a restart -- using this in production silently defeats every
+ * "resume after crash/restart" guarantee this interface exists to provide.
+ */
+export declare class InMemoryRecoveryStore implements CommerceRecoveryStore {
+    private readonly records;
+    create(record: Omit<CommerceRecoveryRecord, 'version' | 'createdAt' | 'updatedAt'>): Promise<CommerceRecoveryRecord>;
+    load(operationId: string): Promise<CommerceRecoveryRecord | null>;
+    update(operationId: string, patch: Partial<Omit<CommerceRecoveryRecord, 'operationId' | 'version'>>, expectedVersion: number): Promise<CommerceRecoveryRecord>;
+    findByClientSubmissionKey(clientSubmissionKey: string): Promise<CommerceRecoveryRecord | null>;
+}

package/dist/commerce/recoveryStore.js

@@ -0,0 +1,77 @@
+/**
+ * recoveryStore.ts — durable recovery abstraction for the commerce client.
+ *
+ * This is the ONE thing standing between "lost my HTTP response" and "paid
+ * twice" or "sent a duplicate merchant payment" on the CLIENT side — the
+ * mirror image of what onchaindiligence-mcp's own lifecycle_steps /
+ * execution_bindings tables do server-side (D2.4). A developer's application
+ * MUST persist a record here BEFORE calling anything that could move money
+ * (preflight, executor.prepare, executor.submit) so a crash between "we
+ * asked" and "we got an answer" has something durable to resume from.
+ *
+ * `create`/`update` use explicit optimistic concurrency (a version counter)
+ * rather than silent last-write-wins, so two concurrent processes touching
+ * the same operation can never silently clobber each other's state — one of
+ * them gets a VersionConflictError and must reload and retry.
+ *
+ * The in-memory implementation exists ONLY for tests and throwaway scripts.
+ * It is explicitly NOT advertised as production-safe (it does not survive a
+ * process restart, which defeats the entire point of this interface) — see
+ * NodeFileRecoveryStore for a real, restart-surviving option, and implement
+ * this interface against your own database for a multi-instance deployment.
+ */
+export class RecoveryRecordExistsError extends Error {
+    constructor(operationId) {
+        super(`a recovery record for operation ${operationId} already exists`);
+        this.name = 'RecoveryRecordExistsError';
+    }
+}
+export class RecoveryRecordNotFoundError extends Error {
+    constructor(operationId) {
+        super(`no recovery record found for operation ${operationId}`);
+        this.name = 'RecoveryRecordNotFoundError';
+    }
+}
+export class VersionConflictError extends Error {
+    constructor(operationId, expected, actual) {
+        super(`recovery record for ${operationId} was updated concurrently (expected version ${expected}, found ${actual}) -- reload and retry`);
+        this.name = 'VersionConflictError';
+    }
+}
+/**
+ * Volatile, single-process, TEST/EXAMPLE-ONLY implementation. Does not
+ * survive a restart -- using this in production silently defeats every
+ * "resume after crash/restart" guarantee this interface exists to provide.
+ */
+export class InMemoryRecoveryStore {
+    records = new Map();
+    async create(record) {
+        if (this.records.has(record.operationId))
+            throw new RecoveryRecordExistsError(record.operationId);
+        const now = new Date().toISOString();
+        const full = { ...record, version: 1, createdAt: now, updatedAt: now };
+        this.records.set(record.operationId, full);
+        return { ...full };
+    }
+    async load(operationId) {
+        const found = this.records.get(operationId);
+        return found ? { ...found } : null;
+    }
+    async update(operationId, patch, expectedVersion) {
+        const existing = this.records.get(operationId);
+        if (!existing)
+            throw new RecoveryRecordNotFoundError(operationId);
+        if (existing.version !== expectedVersion)
+            throw new VersionConflictError(operationId, expectedVersion, existing.version);
+        const updated = { ...existing, ...patch, version: existing.version + 1, updatedAt: new Date().toISOString() };
+        this.records.set(operationId, updated);
+        return { ...updated };
+    }
+    async findByClientSubmissionKey(clientSubmissionKey) {
+        for (const record of this.records.values()) {
+            if (record.clientSubmissionKey === clientSubmissionKey)
+                return { ...record };
+        }
+        return null;
+    }
+}