@envarai/envarpay 0.1.0-alpha.3 → 0.2.0-alpha.10

package/README.md

@@ -1,159 +1,71 @@
-# @envarai/envarpay
+# EnvarPay TypeScript
 
-A TypeScript client for an existing **authenticated EnvarPay wallet MCP service**.
-The client does not install Python, run a signer, hold wallet keys, or change wallet
-policy. Use the Python CLI or a separately operated service for those responsibilities.
+Independent service commerce for user-operated Agents. Public communication uses
+A2A 1.0; payments use native x402 v2 exact USDC or MPP Stripe charge. Prices and
+scope are versioned configuration, enforced before dispatch, not instructions in
+a prompt. Envar is an optional directory and management UI.
 
-This client uses the alpha release channel. See
-[installation channels](https://github.com/EnvarAI/EnvarPay/blob/main/docs/packages.md)
-for the current registry status and available distributions.
+The 0.2 source line replaces the previous npm wallet-only MCP client. Build from
+this checkout while the release is undergoing acceptance; a source version is
+not evidence that its npm/OCI artifact is published.
 
-## Install and start a wallet
+## Runtime and entry points
 
-Install the npm alpha client:
+For Hermes onboarding, see [guided Skill setup](../../docs/hermes-skill-setup.md). The `setup --file ...` command reads the owner's local model configuration and creates a private seller with an empty catalog, ready for the first service to be configured in Envar.
 
-```sh
-npm install @envarai/envarpay@next
-```
+Node.js 22.14+ (Node 24 recommended). SQLite is single-instance. Contracts can be
+read without loading the seller or buyer runtime; Bun validation covers the
+contracts entry, not the SQLite server.
 
-If your project uses a custom package registry, route this scope to the public
-registry in its `.npmrc`: `@envarai:registry=https://registry.npmjs.org/`.
-
-Node.js >=22.14 and Bun are supported. Import this package from an ESM application.
-The npm library is a client; the wallet runs as a separate service:
+| Entry | Purpose |
+|---|---|
+| `@envarai/envarpay` | Config types/validation, integer pricing, quotes and A2A Cards |
+| `/server` | Durable seller A2A handler, exact x402 gate and native upstream executor |
+| `/client` | Buyer policy, atomic budgets, original-operation recovery and private management |
+| `/mpp` | Opt-in native MPP seller and read-only Stripe reconciliation |
+| `/envar` | Optional bounded config pull/ack and durable observation reports |
 
 ```sh
-uv tool install --python 3.13 envarpay==0.1.0a10
-envarpay init --agent mcp --role buyer --directory ./buyer \
-  --peer-url https://seller.example/mcp --pay-to SELLER_FULL_RECEIVING_ADDRESS \
-  --tool ask_agent --max-per-call 0.01 --budget 0.05
-envarpay keygen --output ./buyer/buyer.key
+npm ci --ignore-scripts
+npm run build
+node dist/commerce/cli.js init --directory ./private
+node dist/commerce/cli.js validate --config ./private/seller.json
 ```
 
-The generated policy uses Base Sepolia test USDC and payments off. Fund the
-dedicated test wallet, review the recipient/tool/limits and enable payments only
-for your intended purchases. The agent never receives the wallet key.
-
-Create the wallet-access credential in your private operator environment. This
-command never prints it and refuses to overwrite an existing file:
+Initialization writes examples and a vault key; it never creates a purchase or
+funds a wallet. Replace example addresses/hosts and review service limits before
+starting. Keep Agent model credentials in the Agent, and signer keys in a separate
+private wallet boundary.
 
 ```sh
-python3 - <<'PY'
-import os, secrets
-with os.fdopen(os.open('buyer/wallet-service.token', os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), 'w') as f:
-    f.write(secrets.token_urlsafe(32))
-PY
-```
-
-Add this table to the existing `buyer.toml`:
-
-```toml
-[wallet_server]
-host = "127.0.0.1"
-port = 4021
-allowed_hosts = ["127.0.0.1:*", "localhost:*"]
-bearer_token_file = "./wallet-service.token"
-```
-
-```sh
-envarpay doctor --config ./buyer/buyer.toml
-envarpay wallet-serve --config ./buyer/buyer.toml
-```
-
-For local development, connect to `http://127.0.0.1:4021/mcp`. For a separate wallet
-permission boundary, run it under another OS identity/container or on a private
-service with HTTPS; only the wallet receives its key, policy and ledger. Keep the
-wallet service private. Give the client its wallet-access token, not a seller's
-token or an Envar machine credential.
-
-## Discover tools and make a purchase
-
-```ts
-import { WalletClient, OperationUnknownError } from '@envarai/envarpay';
-
-const wallet = await WalletClient.connect({
-  url: 'https://wallet.example/mcp',
-  token: process.env.ENVARPAY_WALLET_TOKEN!,
-});
-try {
-  const tools = await wallet.listPaidTools('seller');
-  console.log(tools.tools.map(tool => tool.name));
-  // This may pay within the wallet operator's existing allowlist and budget.
-  const result = await wallet.callPaidTool({
-    peer: 'seller', tool: 'ask_agent',
-    arguments: { question: 'Review my API design' }, requestId: 'review-001',
-  });
-  console.log(result.result.content);
-} catch (error) {
-  if (error instanceof OperationUnknownError) {
-    console.log(await wallet.paymentStatus(error.requestId));
-    // When the operator-approved seller supports recovery:
-    // await wallet.recoverPayment(error.requestId);
-  } else throw error;
-} finally {
-  await wallet.close();
-}
+node dist/commerce/cli.js serve --config seller.json \
+  --credentials private/seller-auth.json --state private/seller.sqlite3 \
+  --origin https://seller.example --port 4020
+node dist/commerce/cli.js buyer-serve --config buyer-policy.json \
+  --credentials private/buyer-auth.json --state private/buyer.sqlite3 \
+  --origin https://buyer-management.example --port 4021
 ```
 
-The example uses the `seller` alias generated by the quickstart. If you changed it,
-use the alias actually configured in `buyer.toml`.
-`listPaidTools` does not pay. `callPaidTool` may spend within the existing wallet
-policy; `paymentStatus` and `recoverPayment` retain the original purchase.
-
-## Envar discovery and transaction pages
-
-With the optional `[connection]` in the wallet, these additional methods read
-Envar's public catalog:
-
-```ts
-const candidates = await wallet.discoverAgents('research');
-console.log(candidates.payment_authorized); // always false
-const profile = await wallet.getAgent('THE_PUBLISHED_AGENT_HANDLE');
-```
-
-The operator still approves and configures a peer before purchasing from it.
-The Python wallet handles optional durable Envar reports; the npm client does not
-duplicate signing, settlement or the platform's payment verification.
-[Complete Envar setup](https://github.com/EnvarAI/EnvarPay/blob/main/docs/envar.md).
-
-## Receiving and asynchronous tasks
-
-For **receiving**, put the Python `envarpay` payment gate in front of your existing
-private JS/TS MCP tool and expose only the gate through HTTPS. No buyer-wallet
-client is needed to receive payments; the seller does not need a signing key.
-[Seller quickstart](https://github.com/EnvarAI/EnvarPay/blob/main/docs/selling.md).
-
-For **asynchronous escrow/acceptance/refunds**, use Python `envarpay[task]` and
-`envarpay task wallet` with your host's standard MCP client. The task mode is an
-experimental Base Sepolia-only flow, separate from this upfront wallet API.
-[Task guide](https://github.com/EnvarAI/EnvarPay/blob/main/docs/tasks/README.md).
-
-## Errors and recovery
-
-Persist the request ID in your application before calling. Never replace it after
-an uncertain result. The client does not retry paid calls; the wallet retains the
-original authorization and ledger. A `WalletToolError` preserves an explicit
-wallet refusal/execution error. An `OperationUnknownError` means the result is
-uncertain, including transport failures and timeouts; it does not mean no payment occurred.
-
-HTTPS is required except for loopback HTTP. Redirects are rejected, including
-redirects to another wallet URL. The bearer token belongs to the wallet service,
-not to a seller or public directory; keep it in the application's private config.
-
-Targets Node.js >=22.14 and Bun. Local tests use the actual Python wallet MCP
-adapter with a fake service and transfer no funds; they are not real payment evidence.
-This client has no task-escrow API or framework-native plugin manifest.
-
-## Reviewed purchases from Envar
-
-Use the published Python EnvarPay 0.1.0a10 service with this client. `walletPolicy()` reads limits
-and already-approved peers. `callAgent()` selects only a peer bound to the reviewed
-Agent and endpoint IDs; it never adds a directory candidate to wallet policy. Supply
-`expectedNetwork`, `expectedPayTo` and `expectedAmountAtomic` from the terms you
-reviewed. A different live price is refused before signing. Keep `requestId` across
-uncertain outcomes and use the original status/recovery methods.
-
-The website can use the same authenticated wallet through its owner-only entry.
-For task creation, result verification and acceptance/refunds, connect the private
-`envarpay task wallet-serve` using a standard MCP client. The task signer and
-contract verification stay in Python; the task mode remains experimental/testnet.
+The management service is private and owner-authenticated. A website may request a
+quote and confirm an already-reviewed purchase; it cannot change peers, recipient
+allowlists, budgets or signing keys. Unknown outcomes retain the original request,
+signature/SPT and reserved budget. Never create a replacement purchase after a
+timeout.
+
+[Seller and wire behavior](../../docs/a2a-commerce.md) ·
+[Buyer management](../../docs/a2a-buyer.md) ·
+[Continuation and recovery](../../docs/a2a-runtime-recovery.md) ·
+[Envar configuration integration](../../docs/a2a-envar.md)
+
+## Payment guarantees
+
+Payment confirmation, task completion and acceptance are separate facts. The MVP
+charges upfront for a new task; reads and permitted clarification use that same
+purchase. It does not provide escrow, automatic refunds, subscriptions or billing
+for arbitrary internal tools. A2A compatibility alone does not give an Agent a
+wallet or authorize payment.
+
+MPP requires an eligible Stripe merchant, a permitted buyer token-creation flow,
+explicit test/live mode and any required customer authentication. Simulator tests
+are not card charges. Provider and chain acceptance must be recorded separately
+from SDK tests and build results.

package/dist/commerce/alerts.d.ts

@@ -0,0 +1,37 @@
+type SignalName = 'ledger_read' | 'payment_unknown' | 'execution_unknown' | 'recorded_provider_failure' | 'budget_near_limit' | 'budget_exhausted' | 'report_backlog' | 'report_failure';
+type Signal = {
+    name: SignalName;
+    status: 'clear' | 'alert' | 'unavailable' | 'not_applicable';
+    severity: 'info' | 'warning' | 'critical';
+    count: number | null;
+};
+type Budget = {
+    unit: string;
+    maxTotal: string;
+    reserved: string;
+    spent: string;
+    remaining: string;
+    state: 'available' | 'near_limit' | 'exhausted';
+};
+export interface LocalAlertOptions {
+    policyPath?: string;
+    integrationPath?: string;
+    integrationDisabled?: boolean;
+}
+/** Owner-local aggregate evidence only. Never opens a runtime store, signer, vault or network. */
+export declare function inspectLocalAlerts(path: string, options?: LocalAlertOptions): {
+    role: "unavailable" | "buyer" | "seller";
+    view: "alerts";
+    observation: "local_persisted_state_only";
+    status: string;
+    signals: Signal[];
+    budgets: Budget[];
+    alertCount: number;
+    unavailableCount: number;
+    providerHealth: "unavailable_not_probed";
+    recommendedExitCode: number;
+    paymentPerformed: boolean;
+    refundPerformed: boolean;
+    networkRequests: number;
+};
+export {};

package/dist/commerce/alerts.js

@@ -0,0 +1,127 @@
+import { DatabaseSync } from 'node:sqlite';
+import { lstatSync, readFileSync } from 'node:fs';
+import { loadBuyerPolicy } from './config.js';
+const CURRENCIES = {
+    usd: 'usd_cents',
+    'eip155:8453/erc20:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': 'base_usdc_atomic',
+    'eip155:84532/erc20:0x036cbd53842c5426634e7929541ec2318f3dcf7e': 'base_sepolia_usdc_atomic',
+};
+function privateFile(path, limit) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid()) || (limit !== undefined && stat.size > limit))
+        throw new Error('private_source_unavailable');
+}
+function database(path) {
+    privateFile(path);
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+        db.exec('PRAGMA query_only=ON; PRAGMA busy_timeout=1000; BEGIN');
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+const count = (db, sql) => Number(db.prepare(sql).get().n);
+const signal = (name, value, severity = 'warning') => ({ name, status: value ? 'alert' : 'clear', severity: value ? severity : 'info', count: value });
+const missing = (name) => ({ name, status: 'unavailable', severity: 'warning', count: null });
+const irrelevant = (name) => ({ name, status: 'not_applicable', severity: 'info', count: null });
+/** Owner-local aggregate evidence only. Never opens a runtime store, signer, vault or network. */
+export function inspectLocalAlerts(path, options = {}) {
+    const signals = [], budgets = [];
+    let role = 'unavailable', db;
+    try {
+        db = database(path);
+        const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(row => row.name));
+        if (tables.has('buyer_purchases') === tables.has('commerce_orders'))
+            throw new Error('unknown_ledger');
+        role = tables.has('buyer_purchases') ? 'buyer' : 'seller';
+        if (db.prepare(`SELECT version FROM ${role === 'buyer' ? 'buyer_meta' : 'commerce_meta'}`).get()?.version !== (role === 'buyer' ? 1 : 2))
+            throw new Error('unknown_version');
+        const unknownPayments = count(db, role === 'buyer' ? "SELECT COUNT(*) n FROM buyer_purchases WHERE json_extract(record_json,'$.paymentState')='unknown'" : "SELECT COUNT(*) n FROM commerce_orders WHERE payment_state='unknown'");
+        const unknownExecution = count(db, role === 'buyer' ? "SELECT COUNT(*) n FROM buyer_purchases WHERE json_extract(record_json,'$.executionState')='unknown'" : "SELECT COUNT(*) n FROM commerce_orders WHERE execution_state='unknown'");
+        // Only concrete persisted provider errors count. Generic unknown is not proof of provider failure.
+        const providerFailures = count(db, role === 'buyer'
+            ? "SELECT COUNT(*) n FROM buyer_purchases WHERE json_extract(record_json,'$.paymentState')!='confirmed' AND json_extract(record_json,'$.errorCode') IN ('stripe_transport_unknown','stripe_request_failed','stripe_rate_limit','stripe_response','stripe_response_size')"
+            : "SELECT COUNT(*) n FROM commerce_payment_attempts WHERE state!='confirmed' AND json_extract(receipt_json,'$.success')=0 AND length(json_extract(receipt_json,'$.errorReason'))>0");
+        signals.push(signal('ledger_read', 0), signal('payment_unknown', unknownPayments), signal('execution_unknown', unknownExecution), signal('recorded_provider_failure', providerFailures));
+        if (role === 'seller')
+            signals.push(irrelevant('budget_near_limit'), irrelevant('budget_exhausted'));
+        else {
+            try {
+                if (!options.policyPath)
+                    throw new Error('policy_required');
+                privateFile(options.policyPath, 1024 * 1024);
+                const policy = loadBuyerPolicy(JSON.parse(readFileSync(options.policyPath, 'utf8')));
+                const usage = new Map();
+                for (const b of policy.budgets)
+                    usage.set(b.currency, { reserved: 0n, spent: 0n });
+                for (const row of db.prepare("SELECT currency,amount,budget_state FROM buyer_purchases WHERE budget_state!='none'").iterate()) {
+                    const currency = String(row.currency), amount = String(row.amount), state = row.budget_state;
+                    const target = usage.get(currency);
+                    if (!target || !/^[1-9][0-9]{0,77}$/.test(amount) || !['spent', 'reserved'].includes(String(state)))
+                        throw new Error('budget_binding');
+                    target[state === 'spent' ? 'spent' : 'reserved'] += BigInt(amount);
+                }
+                const checked = policy.budgets.map(b => {
+                    const u = usage.get(b.currency), cap = BigInt(b.maxTotal), used = u.reserved + u.spent;
+                    const state = used >= cap ? 'exhausted' : used * 10n >= cap * 9n ? 'near_limit' : 'available';
+                    return { unit: CURRENCIES[b.currency], maxTotal: cap.toString(), reserved: u.reserved.toString(), spent: u.spent.toString(), remaining: (used < cap ? cap - used : 0n).toString(), state };
+                });
+                budgets.push(...checked);
+                signals.push(signal('budget_near_limit', checked.filter(b => b.state === 'near_limit').length), signal('budget_exhausted', checked.filter(b => b.state === 'exhausted').length, 'critical'));
+            }
+            catch {
+                signals.push(missing('budget_near_limit'), missing('budget_exhausted'));
+            }
+        }
+    }
+    catch {
+        role = 'unavailable';
+        signals.length = 0;
+        budgets.length = 0;
+        signals.push(...['ledger_read', 'payment_unknown', 'execution_unknown', 'recorded_provider_failure', 'budget_near_limit', 'budget_exhausted'].map(missing));
+    }
+    finally {
+        db?.close();
+    }
+    let integration;
+    try {
+        if (options.integrationDisabled && !options.integrationPath) {
+            signals.push(irrelevant('report_backlog'), irrelevant('report_failure'));
+        }
+        else {
+            if (options.integrationDisabled)
+                throw new Error('ambiguous_integration');
+            if (!options.integrationPath)
+                throw new Error('integration_not_supplied');
+            integration = database(options.integrationPath);
+            const binding = integration.prepare("SELECT value FROM meta WHERE key='binding'").get();
+            const source = integration.prepare("SELECT value FROM meta WHERE key='source_instance'").get();
+            if (!binding || !source || typeof binding.value !== 'string' || typeof source.value !== 'string')
+                throw new Error('integration_schema');
+            const parsed = JSON.parse(binding.value);
+            if (!parsed || typeof parsed.platformOrigin !== 'string' || typeof parsed.agentId !== 'string' || typeof parsed.runtimeAgentId !== 'string')
+                throw new Error('integration_schema');
+            const pending = count(integration, "SELECT COUNT(*) n FROM outbox WHERE state='pending'");
+            const failed = count(integration, "SELECT COUNT(*) n FROM outbox WHERE state='pending' AND attempts>0 AND last_error<>''");
+            signals.push(signal('report_backlog', pending), signal('report_failure', failed));
+        }
+    }
+    catch {
+        signals.push(missing('report_backlog'), missing('report_failure'));
+    }
+    finally {
+        integration?.close();
+    }
+    const alertCount = signals.filter(s => s.status === 'alert').length, unavailableCount = signals.filter(s => s.status === 'unavailable').length;
+    return {
+        role, view: 'alerts', observation: 'local_persisted_state_only',
+        status: role === 'unavailable' ? 'unavailable' : unavailableCount ? 'partial' : 'available',
+        signals, budgets, alertCount, unavailableCount,
+        providerHealth: 'unavailable_not_probed',
+        recommendedExitCode: unavailableCount ? 3 : alertCount ? 2 : 0,
+        paymentPerformed: false, refundPerformed: false, networkRequests: 0,
+    };
+}

package/dist/commerce/buyer-store.d.ts

@@ -0,0 +1,101 @@
+import type { PaymentRequired, PaymentRequirements, SettleResponse } from '@x402/core/types';
+import type { Challenge } from 'mppx';
+import type { MppReceipt } from './mpp-client.js';
+import { type BuyerPolicy, type Input } from './types.js';
+export interface BuyerQuote {
+    messageId: string;
+    payer: string;
+    amount: string;
+    currency: string | null;
+    recipient: string | null;
+    expiresAt: string;
+    serviceId: string;
+    serviceRevision: number;
+    offerId: string;
+    inputDigest: string;
+    termsDigest: string;
+    quoteId: string;
+    /** Absent for the original seller-advertised EnvarPay contract. */
+    termsSource?: 'local-policy';
+}
+export interface BuyerRecord {
+    id: string;
+    caller: string;
+    peerId: string;
+    cardUrl: string;
+    endpoint: string;
+    messageId: string;
+    fingerprint: string;
+    body: string;
+    quoteToken: string;
+    quote: BuyerQuote;
+    input: Input;
+    inputSchema: Record<string, unknown>;
+    peerMode?: 'standard-a2a';
+    standardBinding?: {
+        policyDigest: string;
+        bodyDigest: string;
+        challengeDigest: string;
+    };
+    continuations?: {
+        messageId: string;
+        input: Input;
+        body?: string;
+        state: 'pending' | 'unknown' | 'resolved';
+        beforeDigest: string;
+    }[];
+    protocol?: 'x402' | 'mpp' | 'free';
+    mppChallenge?: Challenge.Challenge;
+    tokenOperationId?: string;
+    tokenRef?: string;
+    mppMode?: 'test' | 'live';
+    mppPaymentMethod?: string;
+    required?: PaymentRequired;
+    requirements?: PaymentRequirements;
+    createdAt: string;
+    updatedAt: string;
+    state: 'previewed' | 'signing' | 'submitted' | 'unknown' | 'completed' | 'failed';
+    paymentState: 'quoted' | 'reserved' | 'unknown' | 'confirmed' | 'rejected' | 'not_required';
+    executionState: string;
+    credentialRef?: string;
+    nonce?: string;
+    fromBlock?: string;
+    receipt?: SettleResponse | MppReceipt;
+    task?: Record<string, unknown>;
+    result?: unknown;
+    errorCode?: string;
+    rejectionEvidence?: {
+        kind: 'finalized_expired_unused';
+        checkedAt: string;
+        nonce: string;
+    };
+}
+/** One wallet ledger, one process. Unknown authorizations retain cumulative budget. */
+export declare class BuyerStore {
+    private readonly db;
+    private readonly owner?;
+    constructor(path: string);
+    close(): void;
+    private transaction;
+    get(id: string, caller: string): BuyerRecord | undefined;
+    assertMessageOwner(caller: string, messageId: string): void;
+    find(caller: string, messageId: string): BuyerRecord | undefined;
+    insert(value: Omit<BuyerRecord, 'id' | 'createdAt' | 'updatedAt' | 'state' | 'paymentState' | 'executionState'>): BuyerRecord;
+    update(id: string, patch: Partial<Pick<BuyerRecord, 'state' | 'paymentState' | 'executionState' | 'credentialRef' | 'nonce' | 'fromBlock' | 'receipt' | 'task' | 'result' | 'errorCode' | 'continuations' | 'tokenOperationId' | 'tokenRef' | 'rejectionEvidence'>>): BuyerRecord;
+    pendingTasks(): BuyerRecord[];
+    usage(currency: string): {
+        reserved: string;
+        spent: string;
+    };
+    reserve(id: string, caller: string, policy: BuyerPolicy): {
+        record: BuyerRecord;
+        fresh: boolean;
+    };
+    beginFree(id: string, caller: string): {
+        record: BuyerRecord;
+        fresh: boolean;
+    };
+    rejectBeforeSigning(id: string, caller: string, errorCode: string): BuyerRecord;
+    rejectExpiredAuthorization(id: string, caller: string): BuyerRecord;
+    confirmed(id: string, receipt: SettleResponse | MppReceipt): BuyerRecord;
+}

package/dist/commerce/buyer-store.js

@@ -0,0 +1,168 @@
+import { DatabaseSync } from 'node:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { atomic } from './config.js';
+import { CommerceError } from './types.js';
+/** One wallet ledger, one process. Unknown authorizations retain cumulative budget. */
+export class BuyerStore {
+    db;
+    owner;
+    constructor(path) {
+        if (path !== ':memory:') {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            this.owner = new DatabaseSync(path + '.owner.sqlite3');
+            chmodSync(path + '.owner.sqlite3', 0o600);
+            try {
+                this.owner.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE');
+            }
+            catch {
+                this.owner.close();
+                throw new CommerceError('store_locked', 'Buyer ledger already has an active process');
+            }
+        }
+        try {
+            this.db = new DatabaseSync(path);
+            if (path !== ':memory:')
+                chmodSync(path, 0o600);
+            this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA busy_timeout=5000;
+        CREATE TABLE IF NOT EXISTS buyer_meta(version INTEGER NOT NULL);
+        INSERT INTO buyer_meta SELECT 1 WHERE NOT EXISTS(SELECT 1 FROM buyer_meta);
+        CREATE TABLE IF NOT EXISTS buyer_purchases(
+          id TEXT PRIMARY KEY, caller TEXT NOT NULL, message_id TEXT NOT NULL,
+          currency TEXT NOT NULL, amount TEXT NOT NULL, budget_state TEXT NOT NULL,
+          record_json TEXT NOT NULL, UNIQUE(caller,message_id), UNIQUE(message_id)
+        );`);
+            if (this.db.prepare('SELECT version FROM buyer_meta').get()?.version !== 1)
+                throw new CommerceError('store_version', 'Unsupported buyer ledger version');
+            // Never resume signing after a crash: no second nonce may be created.
+            for (const row of this.db.prepare('SELECT record_json FROM buyer_purchases').all()) {
+                const record = JSON.parse(String(row.record_json));
+                if (record.state === 'signing' || record.state === 'submitted')
+                    this.update(record.id, { state: 'unknown', paymentState: ['confirmed', 'not_required'].includes(record.paymentState) ? record.paymentState : 'unknown', errorCode: 'interrupted_purchase' });
+            }
+        }
+        catch (error) {
+            this.owner?.close();
+            throw error;
+        }
+    }
+    close() { this.db.close(); if (this.owner) {
+        this.owner.exec('ROLLBACK');
+        this.owner.close();
+    } }
+    transaction(fn) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = fn();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    get(id, caller) {
+        const row = this.db.prepare('SELECT record_json FROM buyer_purchases WHERE id=? AND caller=?').get(id, caller);
+        return row ? JSON.parse(String(row.record_json)) : undefined;
+    }
+    assertMessageOwner(caller, messageId) {
+        const row = this.db.prepare('SELECT caller FROM buyer_purchases WHERE message_id=?').get(messageId);
+        if (row && row.caller !== caller)
+            throw new CommerceError('purchase_conflict', 'Message ID is already reserved to another caller');
+    }
+    find(caller, messageId) {
+        const row = this.db.prepare('SELECT record_json FROM buyer_purchases WHERE caller=? AND message_id=?').get(caller, messageId);
+        return row ? JSON.parse(String(row.record_json)) : undefined;
+    }
+    insert(value) {
+        return this.transaction(() => {
+            this.assertMessageOwner(value.caller, value.messageId);
+            const prior = this.find(value.caller, value.messageId);
+            if (prior) {
+                if (prior.fingerprint !== value.fingerprint)
+                    throw new CommerceError('purchase_conflict', 'Message ID already identifies another purchase');
+                return prior;
+            }
+            const now = new Date().toISOString();
+            const record = { ...value, id: randomUUID(), createdAt: now, updatedAt: now, state: 'previewed', paymentState: 'quoted', executionState: 'not_started' };
+            this.db.prepare('INSERT INTO buyer_purchases VALUES(?,?,?,?,?,?,?)').run(record.id, record.caller, record.messageId, record.quote.currency ?? '', record.quote.amount, 'none', JSON.stringify(record));
+            return record;
+        });
+    }
+    update(id, patch) {
+        const row = this.db.prepare('SELECT record_json FROM buyer_purchases WHERE id=?').get(id);
+        if (!row)
+            throw new CommerceError('purchase_not_found', 'Purchase not found');
+        const record = { ...JSON.parse(String(row.record_json)), ...patch, updatedAt: new Date().toISOString() };
+        this.db.prepare('UPDATE buyer_purchases SET record_json=? WHERE id=?').run(JSON.stringify(record), id);
+        return record;
+    }
+    pendingTasks() {
+        return this.db.prepare('SELECT record_json FROM buyer_purchases').all()
+            .map(row => JSON.parse(String(row.record_json)))
+            .filter(record => record.task?.id && ['working', 'unknown'].includes(record.executionState));
+    }
+    usage(currency) {
+        let reserved = 0n, spent = 0n;
+        for (const row of this.db.prepare("SELECT amount,budget_state FROM buyer_purchases WHERE currency=? AND budget_state!='none'").all(currency)) {
+            if (row.budget_state === 'spent')
+                spent += BigInt(String(row.amount));
+            else
+                reserved += BigInt(String(row.amount));
+        }
+        return { reserved: reserved.toString(), spent: spent.toString() };
+    }
+    reserve(id, caller, policy) {
+        return this.transaction(() => {
+            const record = this.get(id, caller);
+            if (!record)
+                throw new CommerceError('purchase_not_found', 'Purchase not found');
+            if (record.state !== 'previewed')
+                return { record, fresh: false };
+            const limit = policy.budgets.find(b => b.currency === record.quote.currency);
+            const usage = this.usage(record.quote.currency ?? '');
+            if (!limit || BigInt(usage.reserved) + BigInt(usage.spent) + atomic(record.quote.amount) > atomic(limit.maxTotal))
+                throw new CommerceError('budget_exceeded', 'Cumulative wallet budget is exhausted or reserved');
+            this.db.prepare("UPDATE buyer_purchases SET budget_state='reserved' WHERE id=?").run(id);
+            return { record: this.update(id, { state: 'signing', paymentState: 'reserved' }), fresh: true };
+        });
+    }
+    beginFree(id, caller) {
+        return this.transaction(() => {
+            const record = this.get(id, caller);
+            if (!record || record.protocol !== 'free' || record.quote.amount !== '0' || record.quote.currency !== null || record.quote.recipient !== null)
+                throw new CommerceError('free_purchase_binding', 'Invalid original free purchase');
+            if (record.state !== 'previewed')
+                return { record, fresh: false };
+            return { record: this.update(id, { state: 'submitted', paymentState: 'not_required' }), fresh: true };
+        });
+    }
+    rejectBeforeSigning(id, caller, errorCode) {
+        return this.transaction(() => {
+            const record = this.get(id, caller);
+            if (!record || record.state !== 'signing' || record.credentialRef || record.nonce)
+                throw new CommerceError('authorization_may_exist', 'Cannot release an existing or ambiguous authorization');
+            this.db.prepare("UPDATE buyer_purchases SET budget_state='none' WHERE id=? AND budget_state='reserved'").run(id);
+            return this.update(id, { state: 'failed', paymentState: 'rejected', executionState: 'not_started', errorCode });
+        });
+    }
+    rejectExpiredAuthorization(id, caller) {
+        return this.transaction(() => {
+            const record = this.get(id, caller);
+            if (!record || record.protocol === 'mpp' || record.protocol === 'free' || !record.credentialRef || !record.nonce)
+                throw new CommerceError('authorization_recovery_required', 'Original x402 authorization is required');
+            if (record.paymentState === 'confirmed')
+                return record;
+            this.db.prepare("UPDATE buyer_purchases SET budget_state='none' WHERE id=? AND budget_state='reserved'").run(id);
+            return this.update(id, { state: 'failed', paymentState: 'rejected', errorCode: 'authorization_expired_unused', rejectionEvidence: { kind: 'finalized_expired_unused', checkedAt: new Date().toISOString(), nonce: record.nonce } });
+        });
+    }
+    confirmed(id, receipt) {
+        return this.transaction(() => {
+            this.db.prepare("UPDATE buyer_purchases SET budget_state='spent' WHERE id=? AND budget_state IN ('reserved','spent')").run(id);
+            return this.update(id, { paymentState: 'confirmed', receipt });
+        });
+    }
+}