Storage

The SQLite file at storage.receipts.path preserves these gateway records across restarts:

• receipts, the commerce event log, payment attempts and the transaction journal;
• since 2.6.0, AP2 mandate holds, ACP idempotency claims and A2A x402 tasks waiting for payment;
• a record of each deprecated store file it imported.

New database files use 0600; missing directories use 0700. The database runs in WAL mode. Run one gateway per database.

#Upgrade from 2.5

1. Back up

   Run agent-commerce backup from 2.6.0 before starting it. Backup reads schema v4 without migration, includes unimported legacy files and can run beside the 2.5 gateway.

2. Keep the deprecated keys

   Keep authorization.ap2.replay.path and protocols.acp.idempotency.path set, with their files in place. Version 2.6.0 accepts both keys with deprecation warnings.

3. Start 2.6.0 once

   agent-commerce start migrates the receipt database to schema v5 and imports the legacy files. Version 2.5 cannot open the migrated database.

4. Check, then remove the keys

   Remove a key once doctor confirms the import and no 2.5 gateway still uses the file. Version 3.0.0 is planned to remove both keys without an importer.

#Deprecated store files

agent-commerce start imports the files:

• Each source's rows and import marker commit together, and later starts skip that import. ACP schema-v1 rows are skipped as in 2.5; skipped claims not marked completed produce a warn count.
• start locks existing source files against writes until shutdown, so a 2.5 gateway cannot update them meanwhile.
• The first import needs a writable directory; otherwise startup fails with STORAGE_ERROR. Make it writable or copy the file to a writable location and update the key. After import, SQLITE_CANTOPEN produces a warning; other lock errors still stop startup.
• Import failure rolls back that source's rows and marker while preserving earlier imports. Startup fails with STORAGE_ERROR and retries on the next start.
• Changing a recorded source path is refused. A spent mandate stays spent: an import cannot unblock a reference already held in the receipt database.

Without an import marker or prior check, start looks for past use of each enabled feature: a receipt or transaction with authorization for AP2, or an ACP event. If found, an unset key or missing file causes STORAGE_ERROR. Restore the previous file, or point the key at an empty file to accept lost records. :memory: also accepts the loss because a 2.5 in-memory store retained nothing across restarts. A successful check without a file is recorded so later starts can omit the key; a file supplied later can still be imported.

#Backup

npx @devlab.group/agent-commerce backup --out ./backups/2026-11-01

backup reads sources without changing them and can run beside a live gateway. It writes receipts.sqlite plus eligible unimported AP2/ACP files, each as a separate VACUUM INTO snapshot at 0600, checked with PRAGMA integrity_check. It writes backup.json last, recording the package version, time and each copy's config key, schema version and SHA-256. Without that manifest, the backup is incomplete.

#Restore

1. Stop writers

   Stop the gateway and any reconcile or resolve run.

2. Verify the copies

   Check each file against its SHA-256 in backup.json.

3. Replace the receipt database

   Delete the receipt database and its -wal and -shm files: a leftover WAL file belongs to the old database. Copy receipts.sqlite to storage.receipts.path.

4. Restore deprecated files

   Restore ap2-replay.sqlite or acp-idempotency.sqlite, if included, to its configured path. Remove the old file and its -wal/-shm files first. Keep the key set for import on the next start.

5. Start and reconcile

   Start the gateway, then run agent-commerce reconcile.

Restoring a backup discards local records written after its snapshot:

• Later receipts, events, payment attempts, holds, idempotency claims and pending tasks are lost. Transfers remain on chain.
• Proofs spent since the snapshot reach the facilitator again. EVM verification rejects spent authorizations; Solana and NEAR rely on chain rejection of processed transactions or nonces. If verification passes, the authorization flow can run the backend before settlement fails and the response is withheld. Payment cannot repeat, but backend execution can.
• An AP2 mandate consumed after the backup can authorize another purchase until it expires. That purchase still requires payment.
• Retrying an ACP checkout under a key claimed after the backup reaches the merchant again with the same derived Idempotency-Key.

A transaction recorded as unresolved in the backup still needs reconcile or resolve. To roll back to 2.5, restore a backup made before the upgrade.

#Shutdown

The first SIGTERM or SIGINT stops new connections and waits for in-flight requests without a time limit. Adapters then stop, followed by authorization providers and the database. Successful shutdown exits 0; errors exit 1.

A second signal exits immediately with 1. An orchestrator may send SIGKILL after its grace period (Docker Compose defaults to 10 s). Either forced exit can leave reserved or settlement-uncertain attempts whose replays get 409 without a fresh challenge. Run reconcile after restarting; use resolve when evidence remains inconclusive.