happenstance-postgres 0.4.2

PostgreSQL event store and projection store adapters for happenstance.
Documentation
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
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
//! Postgres-backed [`SendProjectionStore`].
//!
//! # The `Batch` question, and the answer this adapter had to reach
//!
//! The port used to declare `type Batch<'a> where Self: 'a`, and the module
//! documentation on it justified the lifetime with *"a transaction cannot
//! outlive its connection"*. That is true of `rusqlite::Transaction<'a>`, which
//! borrows its `Connection`. It was **not** true here, and that was the finding
//! that fed PS-5: [`PgPool::begin`](sqlx::PgPool::begin) hands back a
//! `Transaction<'static, Postgres>`, taking the `PoolConnection` by value and
//! returning it to the pool on drop. A pooled, networked driver with every
//! opportunity to hand back a borrowed handle chose to hand back an owned one.
//!
//! PS-5 removed the parameter on that evidence, and the evidence stands. What
//! did not stand is the binding this file then carried:
//!
//! ```text
//! type Batch = sqlx::Transaction<'static, Postgres>;   // and five `todo!()`
//! ```
//!
//! **That binding could not be discharged under the port as it then stood, and
//! no compiler said so.** `todo!()` has type `!`, which coerces to everything,
//! so a skeleton type-checks against a signature nothing can implement — the
//! hazard the specification already names about skeletons in general, and that
//! this file demonstrated in particular. Three facts settled it at phase 10b:
//!
//! * [`begin`](happenstance_core::ProjectionStore::begin) was **total,
//!   synchronous and infallible**. There was no `Result`, no `await`, and no
//!   argument to fail on.
//! * `sqlx`'s only constructor for a transaction is `Transaction::begin`, which
//!   is `async` and fallible; `Transaction`'s fields are private, so the type
//!   cannot be assembled by hand. `Pool::try_acquire` is synchronous but yields
//!   a `PoolConnection`, and `BEGIN` is still a round trip.
//! * [`ProjectionProbe::probe_write`](happenstance_core::ProjectionProbe::probe_write)
//!   was synchronous and infallible too, so even given a live transaction there
//!   was no point at which this adapter could issue a statement into it.
//!
//! ADR-0060 recorded that finding as the reason the port stayed gated, and
//! ADR-0062 acted on it: `begin` and the probe seam are `async` and fallible
//! now, and the binding this file could not discharge is discharged one module
//! over, in [`live_projection_store`](crate::live_projection_store). That store
//! is the far end of PS-2's batch-shape axis and it passes the suite.
//!
//! **This store stays as it is.** The batch is [`PostgresProjectionBatch`]: an
//! owned, `Send`, `'static` list of parameterised statements, replayed inside
//! one transaction that `commit` and `reset` open for themselves — PS-4's
//! deferred write set, the same shape `happenstance-sqlite` reaches by a
//! different route. It is the store an application uses, because the typed
//! layer's `Projection::apply` is synchronous and can push into a buffer but
//! cannot issue a statement into a live transaction. The live store is an
//! instrument; this one is the product.
//!
//! # What that costs, stated rather than discovered
//!
//! [`READS_THROUGH_BATCH`](happenstance_core::ProjectionProbe::READS_THROUGH_BATCH)
//! is `false`. Nothing has been sent to Postgres while a batch is open, so there
//! is no pending server state to read through, and answering from *committed*
//! state is what PS-12 forbids by name — a projection doing `get` then `set`
//! inside one batch would read the value from before the batch began and lose
//! every increment after the first.
//!
//! **The consequence for a caller is real and is not hidden:** a projection whose
//! `apply` must read what it has already written in the same batch cannot be
//! written against this adapter. A shadow map inside the batch would buy a green
//! `batch_reads_reflect_pending_writes` about a second source of truth Postgres
//! never sees, and is rejected on the record for that reason.
//!
//! # What this settled about PS-2, and what settled it back
//!
//! PS-2 is `[FROZEN]` and names a live-transaction adapter as the far end of the
//! batch-shape axis, offering `rusqlite` or `sqlx` as the two candidates. Phase
//! 10b found both refuted under the port as it stood, each by its own mechanism:
//! `rusqlite`'s `Transaction<'_>` is `!Send`, so a live handle costs the
//! `SendProjectionStore` impl; `sqlx`'s transaction could not be produced by a
//! total synchronous `begin` at all. That result went to PS-2's owner, and the
//! owner's answer is ADR-0062: the `sqlx` refutation was a defect in the port's
//! signatures, not a property of the axis, and the signatures moved. The
//! `rusqlite` refutation stands — it is a property of that driver — which is
//! why the far end is a `sqlx` store and lives in this crate.
//!
//! # The invariant
//!
//! A read-model write and its checkpoint write must be one transaction, or a
//! restart either replays applied events or skips unapplied ones.
//! [`commit`](happenstance_core::ProjectionStore::commit) replays the caller's
//! statements and does the checkpoint upsert on the same [`Transaction`], then
//! commits once.
//!
//! # Schema
//!
//! `migrations/0002_projection_checkpoint.sql`, applied by
//! [`apply_projection`](crate::migration::apply_projection). Read-model tables
//! are the application's business; this adapter owns the checkpoint and the
//! transaction that carries it.

use core::sync::atomic::{AtomicU64, Ordering};

use happenstance_core::{
    Authority, Checkpoint, CommitError, ProjectionId, ResetError, SendProjectionStore,
    SequencePosition,
};
use sqlx::{PgPool, Postgres, Transaction};

use crate::error::PostgresProjectionStoreError;

pub(crate) mod placeholder;

/// [`Authority::Live`] as it is stored.
///
/// Text rather than an integer or a `CREATE TYPE`. The value is read by a human
/// with a debugger far more often than by this module; a Postgres enum type is a
/// second schema object with no `IF NOT EXISTS` arm to make the migration
/// idempotent; and the `CHECK` in migration 2 is what keeps the column honest.
/// What matters is that the authority is **stored** rather than inferred.
pub(crate) const AUTHORITY_LIVE: &str = "live";

/// [`Authority::Rebuilding`] as it is stored.
pub(crate) const AUTHORITY_REBUILDING: &str = "rebuilding";

/// The conformance suite's own read model.
///
/// A constant here rather than a file in `migrations/`, and the placement is the
/// decision: a `.sql` file in that directory is, by construction, something a
/// DBA applies. A test read model inside an application's database is a defect
/// no test in this repository could catch, because every test enables the
/// feature that creates it.
#[cfg(feature = "conformance")]
pub const PROBE_TABLE: &str = "\
CREATE TABLE IF NOT EXISTS projection_probe (
    k text   NOT NULL PRIMARY KEY,
    v bigint NOT NULL
);";

/// Mints the identity one store instance stamps its batches with.
///
/// A **process-global** ordinal, taken once per store at construction. Both
/// properties are about what must not happen, and `happenstance-sqlite` records
/// the same two: it must not be derived from a pointer address, because an `Arc`
/// can be freed and a new allocation land where the old one was, giving two
/// stores one identity; and it must not be minted in `Clone`, because a clone is
/// the same store and must accept its origin's batches.
///
/// A counter held *per store* and incremented at
/// [`begin`](SendProjectionStore::begin) is the trap that looks equivalent: it
/// hands store A and store B the identical sequence 1, 2, 3…, and the
/// foreign-batch check never fires.
pub(crate) fn mint_stamp() -> u64 {
    static NEXT: AtomicU64 = AtomicU64::new(1);
    NEXT.fetch_add(1, Ordering::Relaxed)
}

/// One bound parameter, owned.
///
/// `sqlx` ships no owned dynamic bind value. `PgArguments` is written through the
/// `Arguments` trait's `add`, which is **fallible**, and
/// [`probe_write`](happenstance_core::ProjectionProbe::probe_write) is not — so
/// encoding at push would have to park an impossible failure in the batch and
/// report it at commit, adding a state and an error variant to represent
/// something that cannot happen for these types. Parameters are therefore kept
/// as values and bound at replay.
///
/// # Why every variant carries an `Option` rather than there being one `Null`
///
/// Postgres parameters are typed, and `sqlx` derives the type OID from the Rust
/// type at `bind`. A single untyped `Null` variant would force this module to
/// pick a concrete `None::<T>` at replay, and `None::<i64>` against a `text`
/// column is a server-side type error rather than a silent success. A null with
/// a type is Postgres' own model, so it is this enum's model too.
///
/// The name is `PgParam` and not `PgValue` because `sqlx::postgres::PgValue`
/// exists and is public — on the *decode* side. Nothing here would fail to
/// compile; a reader tracking down which `PgValue` a line meant would lose the
/// time this name saves.
#[derive(Debug, Clone, PartialEq)]
#[non_exhaustive]
pub enum PgParam {
    /// `text`.
    Text(Option<String>),
    /// `bigint`.
    Int8(Option<i64>),
    /// `integer`.
    Int4(Option<i32>),
    /// `boolean`.
    Bool(Option<bool>),
    /// `double precision`.
    Float8(Option<f64>),
    /// `bytea`.
    Bytea(Option<Vec<u8>>),
}

impl PgParam {
    /// A non-null `text`.
    pub fn text(value: impl Into<String>) -> Self {
        Self::Text(Some(value.into()))
    }

    /// A non-null `bigint`.
    pub const fn int8(value: i64) -> Self {
        Self::Int8(Some(value))
    }

    /// A non-null `bytea`.
    pub fn bytea(value: impl Into<Vec<u8>>) -> Self {
        Self::Bytea(Some(value.into()))
    }
}

/// One statement queued into a batch, with its parameters.
#[derive(Debug, Clone)]
struct PendingStatement {
    sql: Box<str>,
    params: Box<[PgParam]>,
}

/// A Postgres projection batch: an owned list of statements that has been sent
/// to the server exactly never.
///
/// It holds no connection, no transaction and no borrow, so it is `Send` and
/// `'static` — which is what lets the port's `type Batch;` carry no lifetime and
/// no `Send` bound while this adapter implements the `Send` flavour.
///
/// [`begin`](SendProjectionStore::begin) is the only way to obtain one, and that
/// is the whole of the foreign-batch defence: `stamped` is private, so a batch
/// always carries the identity of the store that began it.
#[derive(Debug, Clone)]
pub struct PostgresProjectionBatch {
    statements: Vec<PendingStatement>,
    /// The identity of the store that began this batch.
    stamp: u64,
}

impl PostgresProjectionBatch {
    /// An empty batch stamped with `stamp`.
    ///
    /// Private, deliberately. `begin` is the only caller.
    const fn stamped(stamp: u64) -> Self {
        Self {
            statements: Vec::new(),
            stamp,
        }
    }

    /// Queues a statement to run when the batch commits.
    ///
    /// # Security
    ///
    /// `sql` is `&'static str`, so it cannot be assembled at run time, and the
    /// values are **bound** rather than interpolated. A statement built out of
    /// decoded event data is a SQL injection whose source is the log — and it
    /// commits inside the same transaction that advances the checkpoint, so the
    /// projection never replays those events and nothing re-derives the rows it
    /// corrupted. [`push_raw_sql`](Self::push_raw_sql) is the escape hatch, and
    /// it is separately named so that reaching for it is a decision.
    ///
    /// A statement written in source compiles:
    ///
    /// ```
    /// use happenstance_postgres::projection_store::{PgParam, PostgresProjectionBatch};
    ///
    /// fn queue(batch: &mut PostgresProjectionBatch, account: &str) {
    ///     batch.push(
    ///         "DELETE FROM balance WHERE account = $1",
    ///         [PgParam::text(account)],
    ///     );
    /// }
    /// ```
    ///
    /// and the same statement with the value interpolated does not:
    ///
    /// ```compile_fail,E0308
    /// use happenstance_postgres::projection_store::{PgParam, PostgresProjectionBatch};
    ///
    /// fn queue(batch: &mut PostgresProjectionBatch, account: &str) {
    ///     batch.push(
    ///         format!("DELETE FROM balance WHERE account = '{account}'"),
    ///         core::iter::empty::<PgParam>(),
    ///     );
    /// }
    /// ```
    ///
    /// # Parameter count
    ///
    /// The values must match the highest `$n` that `sql` uses, one for one.
    /// Nothing counts them here. At `commit` (and `reset`) the batch counts them
    /// before binding, and refuses a mismatch in either direction as
    /// [`CommitError::Store`] (or [`ResetError::Store`]) carrying
    /// [`ParameterCount`](PostgresProjectionStoreError::ParameterCount). Neither
    /// the batch's statements nor the checkpoint move. The server alone would
    /// refuse only too few values (ADR-0084).
    pub fn push(&mut self, sql: &'static str, params: impl IntoIterator<Item = PgParam>) {
        self.statements.push(PendingStatement {
            sql: sql.into(),
            params: params.into_iter().collect(),
        });
    }

    /// Queues a statement whose **shape** is computed at run time.
    ///
    /// The honest case is an `IN (…)` list sized by the number of parameters.
    /// Everything [`push`](Self::push) says about binding still applies: values
    /// belong in `params`, never in `sql`.
    ///
    /// # Parameter count
    ///
    /// As for [`push`](Self::push). A computed `IN (…)` list is where a count
    /// goes wrong: build the placeholders and the values from the same
    /// collection.
    pub fn push_raw_sql(&mut self, sql: impl Into<Box<str>>, params: Vec<PgParam>) {
        self.statements.push(PendingStatement {
            sql: sql.into(),
            params: params.into_boxed_slice(),
        });
    }

    /// How many statements are queued.
    pub fn len(&self) -> usize {
        self.statements.len()
    }

    /// Whether nothing has been queued.
    ///
    /// An empty batch is still worth committing: the checkpoint write is the
    /// point, and a runner that skipped the commit because its events produced no
    /// read-model change would replay them forever.
    pub fn is_empty(&self) -> bool {
        self.statements.is_empty()
    }

    /// Every queued statement's value count against its text, in queue order.
    ///
    /// Run before the transaction opens, which is what makes "a refused batch
    /// moves nothing" structural: no statement reaches the server, so no
    /// wrong-arity statement is ever prepared and cached on a pooled connection.
    fn check_parameter_counts(&self) -> Result<(), PostgresProjectionStoreError> {
        self.statements
            .iter()
            .enumerate()
            .try_for_each(|(index, statement)| {
                placeholder::check_parameter_count(index, &statement.sql, statement.params.len())
            })
    }
}

/// A Postgres-backed projection store.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct PostgresProjectionStore {
    pool: PgPool,
    /// This instance's identity, compared against the one every
    /// [`PostgresProjectionBatch`] carries.
    ///
    /// Copied by `Clone` rather than re-minted, because a clone is the same store
    /// and must accept its origin's batches.
    stamp: u64,
}

impl PostgresProjectionStore {
    /// Wraps an existing pool.
    ///
    /// Sharing one pool with
    /// [`PostgresEventStore`](crate::event_store::PostgresEventStore) is the
    /// expected deployment, which is why neither type builds its own.
    pub fn new(pool: PgPool) -> Self {
        Self {
            pool,
            stamp: mint_stamp(),
        }
    }

    /// The pool this store writes through.
    pub fn pool(&self) -> &PgPool {
        &self.pool
    }
}

/// Binds `params` onto `query`, in order.
///
/// A free function rather than a method on [`PgParam`], because `bind` consumes
/// and returns the query by value, so the loop has to own it.
pub(crate) fn bind_all<'q>(
    mut query: sqlx::query::Query<'q, Postgres, sqlx::postgres::PgArguments>,
    params: &'q [PgParam],
) -> sqlx::query::Query<'q, Postgres, sqlx::postgres::PgArguments> {
    for param in params {
        query = match param {
            PgParam::Text(value) => query.bind(value.as_deref()),
            PgParam::Int8(value) => query.bind(*value),
            PgParam::Int4(value) => query.bind(*value),
            PgParam::Bool(value) => query.bind(*value),
            PgParam::Float8(value) => query.bind(*value),
            PgParam::Bytea(value) => query.bind(value.as_deref()),
        };
    }
    query
}

/// Replays `batch`'s statements, in order, inside `transaction`.
async fn replay(
    transaction: &mut Transaction<'static, Postgres>,
    batch: &PostgresProjectionBatch,
) -> Result<(), sqlx::Error> {
    for statement in &batch.statements {
        bind_all(sqlx::query(&statement.sql), &statement.params)
            .execute(&mut **transaction)
            .await?;
    }
    Ok(())
}

/// A stored `bigint` as a [`SequencePosition`].
///
/// Fallible rather than a cast, for the reason the event store's own converter
/// is: `bigint` is signed and admits zero, and `unsigned_abs()` would turn a
/// corrupt negative row into a plausible position.
pub(crate) fn position_from_row(
    stored: i64,
) -> Result<SequencePosition, PostgresProjectionStoreError> {
    u64::try_from(stored)
        .ok()
        .and_then(SequencePosition::new)
        .ok_or(PostgresProjectionStoreError::CheckpointOutOfRange { value: stored })
}

/// A [`SequencePosition`] as a `bigint`.
///
/// `SequencePosition` is a `NonZeroU64` and `bigint` is signed, so the top half
/// of the domain has no representation. It is refused rather than wrapped.
pub(crate) fn position_to_row(
    position: SequencePosition,
) -> Result<i64, PostgresProjectionStoreError> {
    i64::try_from(position.get()).map_err(|_| {
        PostgresProjectionStoreError::CheckpointOutOfRange {
            // Reported as the negative it would have become, which is the value a
            // reader would find in the table had this been written.
            value: position.get().cast_signed(),
        }
    })
}

/// [`Authority`] as it is stored.
///
/// `Authority` is `#[non_exhaustive]`, so a variant this adapter has never seen
/// is possible. It is written as a value migration 2's `CHECK` refuses, rather
/// than silently stored as `live` — reporting a half-finished rebuild as a live
/// projection is the failure this arm exists to prevent, and a constraint
/// violation names it where it happened.
pub(crate) const fn authority_to_row(authority: Authority) -> &'static str {
    match authority {
        Authority::Live => AUTHORITY_LIVE,
        Authority::Rebuilding => AUTHORITY_REBUILDING,
        _ => "unknown",
    }
}

impl SendProjectionStore for PostgresProjectionStore {
    type Error = PostgresProjectionStoreError;

    /// An owned buffered write set. See the [module documentation](self) for why
    /// this is not `sqlx::Transaction<'static, Postgres>`, which is what this
    /// line said while every body below was `todo!()`.
    type Batch = PostgresProjectionBatch;

    /// Never awaits and never fails: minting an empty `Vec` and copying a `u64`
    /// touches no connection. The signature is `async` and fallible for the
    /// live store's sake, and this body is what PS-6's discipline looks like on
    /// a buffer.
    async fn begin(&self) -> Result<Self::Batch, Self::Error> {
        Ok(PostgresProjectionBatch::stamped(self.stamp))
    }

    /// Reads `id`'s checkpoint, or [`Checkpoint::NeverRun`] when it has no row.
    ///
    /// The absence of a row **is** the `NeverRun` state, which is why a
    /// successful [`reset`](Self::reset) deletes rather than writing a sentinel:
    /// a sentinel position would make a reset indistinguishable from a commit at
    /// the first position.
    ///
    /// # Errors
    ///
    /// * [`PostgresProjectionStoreError::Driver`] if the pool or the server
    ///   rejected the read;
    /// * [`CheckpointOutOfRange`](PostgresProjectionStoreError::CheckpointOutOfRange)
    ///   or [`InvalidAuthority`](PostgresProjectionStoreError::InvalidAuthority)
    ///   if the row is one this adapter could not have written.
    async fn checkpoint(&self, id: &ProjectionId) -> Result<Checkpoint, Self::Error> {
        let row: Option<(i64, String)> = sqlx::query_as(
            "SELECT position, authority FROM projection_checkpoint WHERE projection_id = $1",
        )
        .bind(id.as_str())
        .fetch_optional(&self.pool)
        .await?;

        let Some((stored_position, stored_authority)) = row else {
            return Ok(Checkpoint::NeverRun);
        };

        let through = position_from_row(stored_position)?;
        match stored_authority.as_str() {
            AUTHORITY_LIVE => Ok(Checkpoint::Live { through }),
            AUTHORITY_REBUILDING => Ok(Checkpoint::Rebuilding { through }),
            _ => Err(PostgresProjectionStoreError::InvalidAuthority(
                stored_authority,
            )),
        }
    }

    /// Applies `batch` and advances `id`'s checkpoint to `position`, as one unit.
    ///
    /// # How the regression guard is built, and why not the obvious way
    ///
    /// The upsert carries its own guard — `ON CONFLICT … DO UPDATE … WHERE
    /// projection_checkpoint.position <= excluded.position` — so two runners
    /// racing on one `ProjectionId` are serialised by the row lock `ON CONFLICT
    /// DO UPDATE` takes, without this adapter holding a lock of its own.
    /// `happenstance-sqlite` reads the recorded position first and relies on a
    /// global write lock; Postgres has no such lock, which is the point of this
    /// crate.
    ///
    /// A guarded upsert reports a regression as **zero rows** and cannot say what
    /// the recorded position was: `RETURNING` on a `DO UPDATE` yields the new
    /// row, and Postgres exposes no `OLD` there. So the recorded value is re-read
    /// inside the same transaction before the error is built —
    /// [`CommitError::CheckpointRegression`] carries both values so a caller can
    /// log the gap rather than spend a second round trip on it.
    ///
    /// **The transaction is rolled back on that path**, and that is not
    /// bookkeeping: the caller's statements are already in it, and a refused
    /// commit that left the read model written would be a partial application
    /// with no checkpoint to record it.
    ///
    /// # Errors
    ///
    /// * [`CommitError::ForeignBatch`] if `batch` was begun on a different store
    ///   instance, decided before any statement is prepared;
    /// * [`CommitError::CheckpointRegression`] if `position` is below the one
    ///   recorded — equal is accepted, because a batch that wrote nothing new
    ///   still records that its events were considered;
    /// * [`CommitError::Store`] carrying
    ///   [`ParameterCount`](PostgresProjectionStoreError::ParameterCount) if a
    ///   statement's values do not match the highest `$n` its text uses,
    ///   decided before the transaction opens;
    /// * [`CommitError::Store`] if the driver or the server failed.
    async fn commit(
        &self,
        batch: Self::Batch,
        id: &ProjectionId,
        position: SequencePosition,
        authority: Authority,
    ) -> Result<(), CommitError<Self::Error>> {
        if batch.stamp != self.stamp {
            // Before any SQL, which is what makes "neither store moved"
            // structural rather than something to remember.
            return Err(CommitError::ForeignBatch);
        }

        batch.check_parameter_counts().map_err(CommitError::Store)?;

        let stored_position = position_to_row(position).map_err(CommitError::Store)?;

        let mut transaction = self
            .pool
            .begin()
            .await
            .map_err(|error| CommitError::Store(PostgresProjectionStoreError::Driver(error)))?;

        replay(&mut transaction, &batch)
            .await
            .map_err(|error| CommitError::Store(PostgresProjectionStoreError::Driver(error)))?;

        let advanced: Option<(i64,)> = sqlx::query_as(
            "INSERT INTO projection_checkpoint (projection_id, position, authority) \
             VALUES ($1, $2, $3) \
             ON CONFLICT (projection_id) DO UPDATE \
             SET position = excluded.position, authority = excluded.authority \
             WHERE projection_checkpoint.position <= excluded.position \
             RETURNING position",
        )
        .bind(id.as_str())
        .bind(stored_position)
        .bind(authority_to_row(authority))
        .fetch_optional(&mut *transaction)
        .await
        .map_err(|error| CommitError::Store(PostgresProjectionStoreError::Driver(error)))?;

        if advanced.is_some() {
            return transaction
                .commit()
                .await
                .map_err(|error| CommitError::Store(PostgresProjectionStoreError::Driver(error)));
        }

        // Zero rows: the guard refused. Read what it refused against, still
        // inside the transaction, so the pair reported is the pair the guard saw.
        let current: (i64,) =
            sqlx::query_as("SELECT position FROM projection_checkpoint WHERE projection_id = $1")
                .bind(id.as_str())
                .fetch_one(&mut *transaction)
                .await
                .map_err(|error| CommitError::Store(PostgresProjectionStoreError::Driver(error)))?;

        let current = position_from_row(current.0).map_err(CommitError::Store)?;

        // The caller's statements are in this transaction. Discarding it is what
        // makes the refusal leave the read model untouched.
        drop(transaction);

        Err(CommitError::CheckpointRegression {
            current,
            attempted: position,
        })
    }

    /// Applies `batch` and returns `id` to [`Checkpoint::NeverRun`], as one unit.
    ///
    /// `commit`'s dual. It deletes nothing this adapter chose: the read model is
    /// the caller's, and an adapter that truncated a table of its own naming
    /// would be scoped to something the port deliberately never told it.
    ///
    /// # Errors
    ///
    /// * [`ResetError::ForeignBatch`] if `batch` was begun on a different store
    ///   instance;
    /// * [`ResetError::Store`] carrying
    ///   [`ParameterCount`](PostgresProjectionStoreError::ParameterCount) if a
    ///   statement's values do not match the highest `$n` its text uses,
    ///   decided before the transaction opens;
    /// * [`ResetError::Store`] if the driver or the server failed.
    ///
    /// [`ResetError::Refused`] is never returned: this store holds no protection
    /// policy, which is PS-18's mechanism left unexercised by a store with
    /// nothing to protect.
    async fn reset(
        &self,
        batch: Self::Batch,
        id: &ProjectionId,
    ) -> Result<(), ResetError<Self::Error>> {
        if batch.stamp != self.stamp {
            return Err(ResetError::ForeignBatch);
        }

        batch.check_parameter_counts().map_err(ResetError::Store)?;

        let mut transaction = self
            .pool
            .begin()
            .await
            .map_err(|error| ResetError::Store(PostgresProjectionStoreError::Driver(error)))?;

        replay(&mut transaction, &batch)
            .await
            .map_err(|error| ResetError::Store(PostgresProjectionStoreError::Driver(error)))?;

        sqlx::query("DELETE FROM projection_checkpoint WHERE projection_id = $1")
            .bind(id.as_str())
            .execute(&mut *transaction)
            .await
            .map_err(|error| ResetError::Store(PostgresProjectionStoreError::Driver(error)))?;

        transaction
            .commit()
            .await
            .map_err(|error| ResetError::Store(PostgresProjectionStoreError::Driver(error)))
    }

    /// Discards the batch without committing.
    ///
    /// Nothing was ever sent to Postgres, so this is a drop — which is also the
    /// evidence PS-7 asks for: for a buffering adapter, "dropping a batch must
    /// roll back" is free, and the store is usable afterwards because no
    /// connection was ever checked out to return.
    ///
    /// # Errors
    ///
    /// [`PostgresProjectionStoreError::ForeignBatch`] if `batch` was begun on a
    /// different store instance. The batch is consumed either way; the refusal is
    /// how a caller learns it was holding the wrong one, on the call that was
    /// meant to be the cleanup.
    async fn rollback(&self, batch: Self::Batch) -> Result<(), Self::Error> {
        if batch.stamp != self.stamp {
            return Err(PostgresProjectionStoreError::ForeignBatch);
        }
        drop(batch);
        Ok(())
    }
}

/// The conformance suite's write and read seam.
///
/// It lives here, in `src/`, and not in `tests/projection.rs`: that is a
/// different crate, where neither [`ProjectionProbe`] nor
/// [`PostgresProjectionStore`] is local and the orphan rule answers
/// `error[E0117]`.
///
/// [`ProjectionProbe`]: happenstance_core::ProjectionProbe
#[cfg(feature = "conformance")]
impl happenstance_core::ProjectionProbe for PostgresProjectionStore {
    /// `false`, and it is the honest answer rather than a gap.
    ///
    /// A [`PostgresProjectionBatch`] is a list of statements that has been sent
    /// to Postgres exactly never, so there is no open transaction to read
    /// through — and answering from *committed* state is what PS-12 forbids by
    /// name. The two rules that would have used it are emitted as reported skips
    /// rather than omitted.
    const READS_THROUGH_BATCH: bool = false;

    /// Queues one probe row. Never awaits and never fails, because queueing a
    /// statement into a buffer the caller owns cannot fail.
    async fn probe_write(
        &self,
        batch: &mut Self::Batch,
        key: &str,
        value: u64,
    ) -> Result<(), Self::Error> {
        batch.push(
            "INSERT INTO projection_probe (k, v) VALUES ($1, $2) \
             ON CONFLICT (k) DO UPDATE SET v = excluded.v",
            [
                PgParam::text(key),
                // `cast_signed` rather than a fallible conversion: `bigint` is
                // signed, the bit pattern round-trips every `u64` exactly, and a
                // saturating conversion would map two values to one.
                PgParam::int8(value.cast_signed()),
            ],
        );
        Ok(())
    }

    /// Queues removal of every probe row, so that
    /// [`reset`](happenstance_core::ProjectionStore::reset) can be checked
    /// without the suite knowing what a read model is.
    async fn probe_delete_all(&self, batch: &mut Self::Batch) -> Result<(), Self::Error> {
        batch.push("DELETE FROM projection_probe", core::iter::empty());
        Ok(())
    }

    /// Reads one probe row from **committed** state.
    ///
    /// # Errors
    ///
    /// [`PostgresProjectionStoreError::Driver`] if the pool or the server
    /// rejected the read.
    async fn probe_read(&self, key: &str) -> Result<Option<u64>, Self::Error> {
        let row: Option<(i64,)> = sqlx::query_as("SELECT v FROM projection_probe WHERE k = $1")
            .bind(key)
            .fetch_optional(&self.pool)
            .await?;
        Ok(row.map(|(stored,)| stored.cast_unsigned()))
    }

    /// Never called, because
    /// [`READS_THROUGH_BATCH`](happenstance_core::ProjectionProbe::READS_THROUGH_BATCH)
    /// is `false`.
    ///
    /// # Panics
    ///
    /// Always. The specification permits exactly this for an adapter whose batch
    /// has no read path, and the panic is the honest answer: any value returned
    /// here would be a claim about pending writes Postgres has never been told
    /// about.
    async fn probe_read_through(
        &self,
        _batch: &mut Self::Batch,
        _key: &str,
    ) -> Result<Option<u64>, Self::Error> {
        unimplemented!(
            "PostgresProjectionBatch buffers its statements, so `READS_THROUGH_BATCH` \
             is `false` and this is never called: there is no open transaction to \
             read through, and answering from committed state is what PS-12 forbids"
        )
    }
}

#[cfg(test)]
mod tests {
    use super::{PgParam, PostgresProjectionBatch, PostgresProjectionStore, mint_stamp};
    use crate::error::PostgresProjectionStoreError;
    use happenstance_core::ProjectionStore;

    /// The bare flavour must come free from the `Send` one, at this concrete
    /// store rather than in the abstract.
    #[test]
    fn send_flavour_satisfies_the_bare_bound() {
        fn assert_projection_store<P: ProjectionStore>() {}
        assert_projection_store::<PostgresProjectionStore>();
    }

    /// The batch does not borrow the store, written in argument position.
    ///
    /// Against the old GAT this had to be written this way because
    /// `assert_static::<Batch<'_>>()` proved nothing — `'_` in a turbofish is
    /// merely *inferred* and the compiler picked `'static`, so the assertion
    /// passed against `type Batch<'a> = Transaction<'a, Postgres>`, the exact
    /// shape it existed to reject. It was written that way first. Argument
    /// position was the fix, because `'_` there elides to a fresh
    /// universally-quantified lifetime rather than to whatever inference finds
    /// convenient.
    ///
    /// The port no longer has a lifetime to elide, so that hazard cannot recur —
    /// and the test is not therefore vacuous. `type Batch;` is still bindable to
    /// a borrowing type by a store carrying a lifetime of its own, and rebinding
    /// this associated type to anything but the owned batch makes this function
    /// `error[E0308]`.
    fn the_batch_does_not_borrow_the_store(
        batch: <PostgresProjectionStore as ProjectionStore>::Batch,
    ) -> PostgresProjectionBatch {
        batch
    }

    #[test]
    fn the_batch_is_owned() {
        fn assert_static<T: 'static>() {}
        fn assert_send<T: Send>() {}

        assert_static::<<PostgresProjectionStore as ProjectionStore>::Batch>();
        assert_send::<<PostgresProjectionStore as ProjectionStore>::Batch>();
        let _ = the_batch_does_not_borrow_the_store;
    }

    /// Two stores must not share an identity, or the foreign-batch check never
    /// fires.
    ///
    /// This is the test that rejects a per-store counter incremented at `begin`,
    /// which hands every store the sequence 1, 2, 3… and reports every foreign
    /// batch as its own.
    #[test]
    fn each_store_mints_a_distinct_stamp() {
        let first = mint_stamp();
        let second = mint_stamp();
        assert_ne!(first, second);
    }

    /// A batch begun on one store carries that store's identity, and a batch
    /// begun on another does not match it.
    ///
    /// Written against the stamps rather than against a live pool, because
    /// building a `PgPool` is a round trip and this proposition is not about the
    /// server.
    #[test]
    fn a_batch_carries_the_stamp_of_the_store_that_began_it() {
        let first = PostgresProjectionBatch::stamped(mint_stamp());
        let second = PostgresProjectionBatch::stamped(mint_stamp());
        assert_ne!(first.stamp, second.stamp);
    }

    /// An empty batch is still a batch worth committing.
    #[test]
    fn a_fresh_batch_is_empty_and_grows() {
        let mut batch = PostgresProjectionBatch::stamped(1);
        assert!(batch.is_empty());
        assert_eq!(batch.len(), 0);

        batch.push("SELECT $1", [PgParam::text("x")]);
        assert!(!batch.is_empty());
        assert_eq!(batch.len(), 1);
    }

    /// The first statement whose value count is wrong is the one reported, by
    /// its position in queue order — whichever direction it is wrong in.
    #[test]
    fn a_batch_reports_the_first_statement_whose_count_is_wrong() {
        let mut batch = PostgresProjectionBatch::stamped(1);
        assert!(matches!(batch.check_parameter_counts(), Ok(())));

        batch.push("DELETE FROM t WHERE k = $1", [PgParam::text("kept")]);
        batch.push(
            "DELETE FROM t WHERE k = $1",
            [PgParam::text("k"), PgParam::text("unused")],
        );
        batch.push("DELETE FROM t WHERE k = $1 OR k = $2", [PgParam::text("k")]);

        assert!(matches!(
            batch.check_parameter_counts(),
            Err(PostgresProjectionStoreError::ParameterCount {
                statement: 1,
                declared: 1,
                supplied: 2,
            })
        ));
    }

    /// A null carries a type, because Postgres parameters are typed.
    ///
    /// The variant that would fail is a single untyped `Null`: bound as
    /// `None::<&str>` against a `bigint` column it is a server-side type error,
    /// and there is no correct choice to make at the bind site.
    #[test]
    fn a_null_parameter_carries_its_type() {
        assert_eq!(PgParam::Int8(None), PgParam::Int8(None));
        assert_ne!(PgParam::Int8(None), PgParam::Text(None));
    }
}