docs(events): correct sequence semantics; test cursors across sequence gaps

ADR-0002 described the bigserial seq as gap-free. PostgreSQL sequences are
not: values consumed by rolled-back inserts are never reused. The code only
ever relied on monotonic order (seq > cursor), so this is a documentation
correction plus a regression test that burns sequence values and checks
paging, cursor resumption from inside a gap and stats.
This commit is contained in:
Andy Dixon
2026-07-10 23:45:47 +01:00
parent ee463329f1
commit ac2a1a447f
3 changed files with 63 additions and 2 deletions
+4
View File
@@ -385,6 +385,10 @@ func scan(row pgx.Row) (events.Event, error) {
}
// Cursor returns the last sequence consumed by consumer for a mind.
//
// seq is an ordering key, not a counter: bigserial values are skipped when a
// transaction rolls back, so consumers always ask for "seq > cursor" and
// never for "cursor + 1" (ADR-0002).
func (s *Store) Cursor(ctx context.Context, q storage.Querier, mind ids.ID, consumer string) (int64, error) {
var seq int64
err := q.QueryRow(ctx, `SELECT last_seq FROM mind_cursors WHERE mind_id=$1 AND consumer=$2`, mind, consumer).Scan(&seq)