1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
//! Postgres adapters for happenstance: an event store and a projection store.
//!
//! # Status
//!
//! The **event store is implemented**, and run rather than asserted: 107 of 107
//! gated tests pass against a live PostgreSQL 17.10, including the concurrency
//! family at `CONTENDERS = 64`. That is the first time an adapter in this
//! workspace has cleared that family against a store whose writers are **not**
//! serialised, which is the whole reason the crate is in the tree.
//!
//! **The projection store beside it is implemented too**, and the crate carries
//! no `todo!()` and no `#![allow(clippy::todo)]` any more — the allow left with
//! the last stub, which is the contract it was written under.
//!
//! It carries **two** projection stores, and they are not two ways of doing the
//! same thing. [`projection_store`]'s batch is an owned statement list replayed
//! at commit — the shape an application uses, because the typed layer's
//! `Projection::apply` is synchronous and can push into a buffer. The skeleton
//! had declared `sqlx::Transaction<'static, Postgres>` instead, and that binding
//! could not be discharged while `begin` was total, synchronous and infallible;
//! a skeleton did not report it because `todo!()` has type `!` and coerces to
//! anything. ADR-0062 moved `begin` and the probe seam, and
//! [`live_projection_store`] is that binding discharged: a batch that **is** a
//! live transaction, standing at the far end of PS-2's batch-shape axis and
//! passing the suite there — an instrument for the freeze rather than a product.
//!
//! **The crate ships in `0.2.0`.** The release set was five, decided, and the
//! owner re-opened it on this crate's evidence at `e597c34`; the manifest carries
//! no `publish` key. This paragraph said the opposite until the release pass,
//! which would have told a docs.rs reader that the crate they were reading was
//! unpublished.
//!
//! **What a dropped `append` future does here is answered in
//! [`event_store`]'s `# Cancellation` section**, which ES-23 obliges this
//! adapter to carry. The short version, because a caller should not have to
//! click to learn it: the future cannot be cancelled and the batch may already
//! have committed.
//!
//! # Why this crate exists
//!
//! It is an instrument first and a target second. Every other adapter in the
//! workspace — `MemoryEventStore`, a `RefCell` store, rusqlite, a Durable
//! Object — assigns positions under a lock it holds until commit, so all four
//! satisfy the specification's ES-10 (*position order is visibility order*) for
//! free, and none of them votes for it. Postgres is the one shape on the roadmap
//! that can violate ES-10 **by construction**: `nextval()` allocates outside the
//! transaction, so a writer that took position 99 can commit after a writer that
//! took position 100, and a reader that has already seen 100 then watches 99
//! appear beneath it. `AppendCondition::after(100)` evaluates `99 <= 100` and
//! reports no violation, so the consistency boundary silently stops enforcing.
//!
//! This crate buys the invariant back rather than avoiding the shape, and the
//! next section is what that costs the caller.
//!
//! # What this store costs a caller
//!
//! Read this before choosing the adapter. Everything below is a **capability
//! limit** — a thing the store does not do — and not a defect to report, not a
//! setting, and not something an operator can tune down.
//!
//! ES-10 is bought with `xid8` + `pg_snapshot_xmin`. Every row stamps the
//! transaction that wrote it, and every read admits only rows beneath
//! `pg_snapshot_xmin(pg_current_snapshot())` — the transaction id below which
//! nothing can still be in flight. Writers are never serialised in the sense that
//! matters: this store takes no lock that makes disjoint boundaries queue behind
//! one another, which is the property it exists to have.
//!
//! **Most of the bill is paid on the read side, and there is a fourth item that
//! is not.** The read-side costs are the three below. The write-side one is this:
//! an *unconditional* append runs at the pool's default `READ COMMITTED` and pays
//! nothing extra, but a *conditional* append runs `SERIALIZABLE`, so two
//! conditional appends whose predicates overlap are adjudicated at commit and one
//! is aborted with `40001`. This adapter re-runs the loser up to
//! `SERIALISATION_ATTEMPTS` times with exponential, capped, fully-jittered
//! backoff — so a writer already losing a serialisation fight can pay several
//! round trips and a fraction of a second of waiting before it gets its answer.
//! That is retry inside the adapter and is invisible to the caller as anything
//! but latency. The constant's own doc block records that its value was adopted
//! from the Neon lane rather than measured here, and that a re-measurement is
//! owed.
//!
//! Three read-side things follow, and the crate does not soften them.
//!
//! **`head()` reports a visibility frontier, not `max(position)`, and the
//! frontier trails the maximum.** A head is a promise that nothing at or below
//! it will appear later; `max(position)` cannot make that promise here, because
//! it can name a row whose predecessors are still uncommitted. So `head()`
//! returns the highest position beneath the frontier, which legitimately sits
//! below the highest position this store has already assigned. The conformance
//! rule for a head asserts a *bound* rather than an equality for exactly this
//! reason.
//!
//! **Read-your-own-writes does not hold, and is not claimed.** `append`
//! returning `Ok(P)` does **not** promise that the next `head()` is at or above
//! *P*, and a read issued immediately after a successful append may not contain
//! the event that append just wrote. Nothing is lost — the row is committed and
//! will become visible — but a workflow that writes and then reads back through
//! this store to confirm the write is not one this adapter serves.
//!
//! **Staleness is bounded by the longest open write transaction anywhere on the
//! cluster.** Not on this table and not in this database: any write transaction
//! held open by anything connected to the same server holds the frontier where
//! it is. A migration, a batch job, an idle-in-transaction connection or an
//! unrelated tenant is enough, and it is a bound a consumer of this crate
//! neither controls nor can necessarily observe.
//!
//! **What to budget for.** Sub-millisecond when nothing else is holding a write
//! transaction open, and **the whole remaining duration of the longest one that
//! is** otherwise. The remainder of the holder, not a fraction of it.
//!
//! Measured against this adapter, nine samples per cell: a median of 0.593 ms
//! with no holder, and 4,799 ms behind a five-second held write transaction
//! writing to its own unrelated table — while the same adapter with the
//! visibility predicate removed is unaffected by the identical hold, at
//! 0.595 ms. Same server, same hold, same load; only the predicate differs. So
//! the figure to plan for is whatever your cluster's longest write transaction
//! is, and if you cannot bound that, you cannot bound this.
//!
//! ```no_run
//! use happenstance_core::{Event, SendEventStore};
//! use happenstance_postgres::event_store::PostgresEventStore;
//!
//! # async fn confirm(
//! # store: &PostgresEventStore,
//! # events: &[Event],
//! # ) -> Result<(), Box<dyn std::error::Error>> {
//! let written = store.append(events, None).await?;
//!
//! // `written` is where the event landed. It is not a position `head()`
//! // promises to have reached, so this is a bound and never an equality —
//! // `head() == Some(written)` is the assertion a caller must not write.
//! assert!(store.head().await? <= Some(written));
//! # Ok(())
//! # }
//! ```
//!
//! Three other mechanisms were measured and lost, and naming them once is
//! cheaper than having them re-proposed: a serialised sequence table (0.062 of
//! baseline throughput at 64 writers) and a constant advisory lock (0.033) are
//! both correct and both buy ES-10 by deleting the reason to reach for Postgres,
//! while a tag-keyed advisory lock is nearly free (0.935) and lost on the
//! **invariant** rather than on cost — it buys a per-boundary property where
//! ES-10 states a global one. `references/adr/0024-position-visibility-mechanism.md`
//! in this crate's repository carries the argument and the measurements.
//!
//! # Still open
//!
//! * **TLS.** Deliberately not selected, and the reason is measured rather than
//! assumed. `sqlx`'s `tls-rustls` fails the workspace's `cargo deny` licence
//! allowlist — not on `ring`, which is `Apache-2.0 AND ISC` and passes, but on
//! `webpki-roots`, the Mozilla CA root bundle, which is `CDLA-Permissive-2.0`.
//! A crate that connects to nothing does not need a TLS backend; a crate that
//! connects to RDS or Neon does, and that is the point at which the allowlist
//! has to either grow a data licence or the adapter has to take its roots from
//! the platform trust store.
//!
//! # Not the Neon adapter
//!
//! Neon's serverless driver speaks one-shot HTTP to a `/sql` endpoint: no
//! connection, no interactive transaction, no cursor. Everything below — a
//! pool, a server-side `DECLARE CURSOR`, a `Transaction` held across awaits —
//! is unavailable there. That is `happenstance-neon`, a separate crate
//! implementing the bare [`EventStore`](happenstance_core::EventStore), not a
//! feature of this one.
// `--cfg docsrs` is set by this crate's `[package.metadata.docs.rs]`, and it is
// what makes the `doc(cfg(...))` badges below render a feature gate rather than
// nothing. The manifest asserted that was happening while neither the feature
// nor a single attribute existed, so every gated item rendered as ordinary API.
// Both roles' schemas live here, each item gated on its own feature. The module
// is reachable from either, because a `projection-store`-only build needs
// `apply_projection` and has no event log at all — and a module gated on
// `event-store` would have hidden it, which is the defect this line exists to
// avoid rather than a preference about layout.
/// Re-exported so callers can build a pool without pinning their own `sqlx`
/// version against this crate's.
pub use sqlx;
/// Re-exported for ADR-0044's reason, and the trigger it named has arrived.
///
/// That decision states its own trigger as *"the moment `xtask/src/package.rs`'s
/// `reconcile` check would otherwise let the crate onto the registry without
/// it"*, and `0.2.0` is that moment. The contract is in this crate's public
/// signatures rather than merely behind them: `impl SendEventStore for
/// PostgresEventStore` names `Query`, `ReadOptions`, `SequencedEvent`, `Event`,
/// `AppendCondition` and `AppendError`, so a caller cannot use the store without
/// naming types it does not otherwise depend on. The dependency is
/// unconditional, so this needs no `cfg`.
pub use happenstance_core;