x402: define a durable MerchantOfferStore path

[longfin]

Context

PR #207 introduces MerchantOfferStore with an in-memory implementation for single-process deployments. Multi-replica hosts need a durable implementation with an atomic one-shot execution claim.

The bridge already has a Postgres-backed precursor, while the gateway is separately tracking a shared durable consistency domain in planetarium/foundry-x402-gateway#12.

Scope

• Decide where a standard durable implementation belongs without leaking database dependencies into the root @a2x/sdk entry.
• Implement or publish a reference Postgres-compatible MerchantOfferStore for:
  • atomic publishing with rollback;
  • frozen MerchantOffer reads;
  • compare-and-set claim;
  • expiry and delete;
  • multi-replica correctness.
• Evaluate a read-only claimed-state fast path so known replays can avoid a facilitator verify round trip, while retaining the post-verify atomic claim as the arbiter.
• Add concurrency, expiry, rollback, and restart tests.
• Document schema migration and operational cleanup.

Constraints

• Preserve host-owned connection and transaction management.
• Do not make a database driver a root SDK runtime dependency.

Dependencies

• x402: extract a shared merchant-policy module (gate + pricing + metering) consumed by foundry-x402-gateway and vicoop-bridge #206
• feat: add shared merchant policy to x402 #207
• planetarium/foundry-x402-gateway#12

[longfin]

Storage-adapter boundary survey

I surveyed comparable SDKs after prototyping the PostgreSQL implementation in #214. The dominant pattern for optional infrastructure is core contract + in-memory reference + separately published backend adapter:

• Express Session defines the store contract and ships MemoryStore, explicitly warns that it is not suitable for production, and leaves Redis/PostgreSQL implementations to separate packages such as connect-redis and connect-pg-simple.
• LangGraph keeps the checkpoint abstraction separate and publishes PostgreSQL support as @langchain/langgraph-checkpoint-postgres. The adapter package owns its pg dependency, SQL, and migrations rather than putting them in the core graph package.
• Keyv keeps the adapter interface and default in-memory Map in core, while official backends are separate packages such as @keyv/postgres and @keyv/redis. It also uses a shared adapter test suite to keep backend behavior consistent.
• The closest same-package precedent is x402 itself: RedisChannelStorage is exported from an @x402/evm subpath, accepts a minimal Redis client interface, and does not add the Redis driver to that package. This is workable for a small mechanism-specific adapter, but it still couples backend semantics to the mechanism package.

The PostgreSQL prototype was substantially more operational than the Redis precedent: it owned a table and index, migration SQL, JSONB encoding, transaction/advisory-lock behavior, expiry cleanup, and PostgreSQL-specific compatibility. Avoiding a pg dependency through a generic query() interface did not remove that coupling; it only moved transaction integration work to every host. It also increased the @a2x/sdk/x402 artifact materially.

Recommended boundary for a2x

Keep in @a2x/sdk/x402:

• MerchantOfferStore and lifecycle-store contracts;
• the in-memory implementations;
• replay, claim, terminal-state, and indeterminate-settlement semantics;
• precise atomicity/CAS requirements for multi-replica implementations.

If we publish an official PostgreSQL implementation, put it in a separate workspace package such as @a2x/x402-postgres in this monorepo. That package should own:

• PostgresMerchantOfferStore and any combined lifecycle-store implementation;
• schema and migrations;
• PostgreSQL cleanup/reconciliation operations;
• integration tests against a real PostgreSQL instance;
• the pg integration, preferably accepting a host-provided Pool so the host retains connection ownership while the adapter owns its transactional invariants.

This is not the kind of arbitrary API categorization that motivated removing SDK subpaths in #157. The package boundary isolates an optional infrastructure dependency, operational schema, and independently evolving compatibility surface. A same-package @a2x/sdk/x402/postgres subpath would isolate imports, but not the npm artifact, release surface, or maintenance ownership.

Accordingly, the PostgreSQL implementation and migration have been removed from #214. That PR now covers #211's backend-neutral lifecycle/replay semantics only, while this issue remains open for the adapter package decision and implementation.