[freeze][validation] Write a 2nd store adapter (postgres) to validate the contract before freeze

[joeldsouzax]

Tier 0/strategic — the single highest-leverage validation before freeze.

Why

The adapter-facing contract (RawEventStore, RawSubscription, SnapshotStore, wire, GlobalSeq) has only ever been exercised by one embedded adapter (fjall), so single-process/synchronous assumptions have leaked into the "generic" traits. Several freeze issues are all symptoms of "tested against fjall only":

• GlobalSeq <-> subscription mismatch ([freeze][T0] Resolve GlobalSeq <-> subscription contract mismatch #206-style)
• read_stream(from) inclusive vs subscribe(from) exclusive — undocumented on the trait
• trait docs describe fjall's batch_size/keyset pagination as if it were the contract

Action

Build a postgres (or sqlite) adapter — even a skeleton — before freezing the adapter traits. A second backend is the only thing that actually proves the boundary is drawn right, the same way the saga repo proved the kernel boundary. Findings feed back into #204–#210.

Relates to milestone "Phase 4: Cutting Edge & New Adapters". From the 2026-06-19 freeze-readiness audit (bottom-line recommendation).

[joeldsouzax]

Design decision: cross-stream ordering (GlobalSeq) on postgres

Research + discussion outcome (the hazard this card exists to surface).

The hazard

A subscriber tailing $all resumes with WHERE global_seq > :bookmark (our AllCatchup::next_pos = strict-after on GlobalSeq). On postgres, a BIGSERIAL/IDENTITY number is assigned at INSERT time but the row is visible only at COMMIT time, and commit order can differ from insert order. So a slower writer with a lower number can commit after a faster writer with a higher number — the reader advances its bookmark past the lower number while that row was still invisible, and never delivers it (silent event loss). This is not the gap problem (our contract already tolerates gaps); it's late-visibility. fjall never hit it because its single serialized write path makes insert-order == commit-order for free — i.e. GlobalSeq's monotonic-visibility property was an unstated fjall-ism. (Confirmed against PG docs: sequences are assigned at insert, not commit.)

Decision — close it on the READER (Way 2)

Keep insert-time BIGSERIAL (full write concurrency, postgres's whole point — we do not serialize writers to mimic fjall). Make the $all read refuse to advance past in-flight writes:

• tag each event row with its writing transaction id (xid8),
• the $all read only yields rows whose transaction is committed and older than the oldest still-in-flight write (pg_snapshot_xmin(pg_current_snapshot()) watermark),
• order/resume by (transaction_id, global_seq).

Prior art: Emmett / Oskar Dudycz, eugene-khyst/postgresql-event-sourcing.

Rejected alternatives: serialize writers via advisory lock (kills concurrency — defeats using postgres); a commit-time "sorter"/relay (extra always-on component); WAL/logical-decoding (bypasses the very read_all/WakeSource machinery this card validates, + heavy infra — deferred to #265).
Known caveat of Way 2: a single long-running transaction anywhere holds the watermark back and stalls $all consumers until it finishes.

Freeze finding (feeds #204–#210)

The $all cursor position is hardcoded to a single GlobalSeq (Catchup::Position = GlobalSeq). A correct concurrent-writer SQL adapter needs a richer, commit-ordered position (transaction, seq). So before freeze, either:

• widen the $all position to an opaque, adapter-defined type (the cleaner, more honest contract), or
• freeze an explicit GlobalSeq contract clause: "an adapter must expose GlobalSeq such that once a value is observable, no smaller value will later become observable — serialize appends if the backend's sequence is non-transactional."

Adapter approach (this card)

• sqlx targeting postgres (not sqlx::Any, not sqlite) — async fits our traits; PgListener (LISTEN/NOTIFY) backs WakeSource.
• Reuse the unchanged generic Subscription loop; MVP = RawEventStore + WakeSource + a concurrent-writer linearizability test green. Defer snapshot/export/import.
• Tests run via nixosTest as a separate integration-test flake attribute (à la Nix's own hydraJobs.tests), on Linux CI — not in the local nix flake check gate (keeps the dev gate fast/dockerless/Mac-friendly; matches the Linux-only-coverage precedent).

Future high-throughput WAL/CDC path: #265.