@kairos-es/feed-postgres 0.0.0-stage → 0.0.0

package/src/internal/ddl.ts

@@ -0,0 +1,233 @@
+/**
+ * Internal object naming and DDL for the Postgres change feed.
+ *
+ * The single source of truth for the FIVE objects this package owns — the feed
+ * rows, the sequence they share, the generations, the sync cursors and the parked
+ * list — and for the idempotent DDL that creates them. Every name is derived ONCE
+ * from `{ schema, tablePrefix }` and reused by `ensureFeedSchema` (the migration
+ * payload) and by every runtime statement in `statements.ts`, so a migration and a
+ * query can never disagree about what an object is called.
+ *
+ * The pair is the SAME one the event store and `@kairos-es/read-postgres` take, so
+ * the feed's tables land beside the log and the checkpoints they belong with, and
+ * one prefix keeps naming one complete, isolated world (ADR-0002).
+ *
+ * The identifier discipline is `@kairos-es/read-postgres`'s, duplicated rather
+ * than imported for the reason that package gives for duplicating the event
+ * store's: each package measures and quotes only the names IT materialises, and
+ * importing a sibling backend's internals would couple two packages that must
+ * stay independently publishable. Identifiers are pre-quoted here and embedded as
+ * literal text into `sql.unsafe`; values are always bound `$n` parameters. Names
+ * never pass through `sql(identifier)`, because the consumer's client may carry a
+ * query-name transform that would rewrite them.
+ */
+import type { SqlClient, Statement } from 'effect/sql'
+
+/** Every object a feed config owns, as qualified (unquoted) names. */
+export interface ResolvedFeedNames {
+  readonly schema: string
+  readonly tablePrefix: string
+  /** `<schema>.<prefix>_feed_rows`: one row per feed and key, the newest state. */
+  readonly rowsTable: string
+  /** `<prefix>_feed_rows_seq_idx`: the `(feed, seq)` index the tail reads by. */
+  readonly rowsSeqIndex: string
+  /** `<schema>.<prefix>_feed_seq`: the one sequence every feed in the prefix shares. */
+  readonly sequence: string
+  /** `<schema>.<prefix>_feed_generations`: each feed's generation and binding. */
+  readonly generationsTable: string
+  /** `<schema>.<prefix>_feed_cursors`: one cursor and lease per feed and sink. */
+  readonly cursorsTable: string
+  /** `<schema>.<prefix>_feed_parked`: the records a sink refused. */
+  readonly parkedTable: string
+}
+
+/** The default schema, identical to the event store's and the read side's. */
+export const DEFAULT_SCHEMA = 'public'
+/** The default table prefix, identical to the event store's and the read side's. */
+export const DEFAULT_TABLE_PREFIX = 'dcb_events'
+
+const MAX_IDENTIFIER_BYTES = 63
+
+const utf8ByteLength = (value: string): number =>
+  new TextEncoder().encode(value).length
+
+const suffixes = {
+  rows: '_feed_rows',
+  rowsSeqIndex: '_feed_rows_seq_idx',
+  sequence: '_feed_seq',
+  generations: '_feed_generations',
+  cursors: '_feed_cursors',
+  parked: '_feed_parked',
+} as const
+
+/**
+ * The single-atom identifiers Postgres materialises for a config. The index is
+ * measured, unlike a primary key's implicit one, because it is named explicitly
+ * and `CREATE INDEX IF NOT EXISTS` would skip a truncated name that collides with
+ * another prefix's index instead of reporting it.
+ */
+const derivedAtoms = (config: {
+  readonly schema?: string
+  readonly tablePrefix?: string
+}): ReadonlyArray<readonly [string, string]> => {
+  const schema = config.schema ?? DEFAULT_SCHEMA
+  const prefix = config.tablePrefix ?? DEFAULT_TABLE_PREFIX
+  return [
+    ['schema', schema],
+    ['feed rows table', `${prefix}${suffixes.rows}`],
+    ['feed rows index', `${prefix}${suffixes.rowsSeqIndex}`],
+    ['feed sequence', `${prefix}${suffixes.sequence}`],
+    ['feed generations table', `${prefix}${suffixes.generations}`],
+    ['feed cursors table', `${prefix}${suffixes.cursors}`],
+    ['feed parked table', `${prefix}${suffixes.parked}`],
+  ]
+}
+
+/**
+ * The first derived identifier over Postgres's 63-byte limit, as a message, or
+ * `undefined` when every name fits. Postgres truncates an over-long identifier
+ * with only a notice, so two prefixes sharing a 63-byte stem would silently share
+ * one feed table; refusing at the boundary beats that.
+ */
+export const oversizedIdentifier = (config: {
+  readonly schema?: string
+  readonly tablePrefix?: string
+}): string | undefined => {
+  for (const [label, atom] of derivedAtoms(config)) {
+    const bytes = utf8ByteLength(atom)
+    if (bytes > MAX_IDENTIFIER_BYTES) {
+      return `the ${label} identifier "${atom}" is ${bytes} bytes, over Postgres's ${MAX_IDENTIFIER_BYTES}-byte limit; it would be silently truncated, letting two prefixes share one feed object`
+    }
+  }
+  return undefined
+}
+
+/** Derive every name from the pair; throws on an over-long identifier. */
+export const resolveFeedNames = (config: {
+  readonly schema?: string
+  readonly tablePrefix?: string
+}): ResolvedFeedNames => {
+  const problem = oversizedIdentifier(config)
+  if (problem !== undefined) {
+    throw new Error(`resolveFeedNames: ${problem}`)
+  }
+  const schema = config.schema ?? DEFAULT_SCHEMA
+  const tablePrefix = config.tablePrefix ?? DEFAULT_TABLE_PREFIX
+  const qualified = (suffix: string) => `${schema}.${tablePrefix}${suffix}`
+  return {
+    schema,
+    tablePrefix,
+    rowsTable: qualified(suffixes.rows),
+    rowsSeqIndex: `${tablePrefix}${suffixes.rowsSeqIndex}`,
+    sequence: qualified(suffixes.sequence),
+    generationsTable: qualified(suffixes.generations),
+    cursorsTable: qualified(suffixes.cursors),
+    parkedTable: qualified(suffixes.parked),
+  }
+}
+
+/** Quote a possibly qualified identifier, atom by atom, for literal SQL text. */
+export const quoteQualified = (name: string): string =>
+  name
+    .split('.')
+    .map((atom) => quoteAtom(atom))
+    .join('.')
+
+/** Quote one identifier atom, doubling any embedded `"`. */
+export const quoteAtom = (name: string): string =>
+  `"${name.replace(/"/g, '""')}"`
+
+/**
+ * The quoted sequence name as a SQL string LITERAL, for `nextval('…')`. The
+ * literal is parsed as a `regclass`, which honours the double quotes inside it, so
+ * an awkward prefix resolves to exactly the object the DDL created; any `'` in it
+ * is doubled so the literal cannot be closed early.
+ */
+export const sequenceLiteral = (names: ResolvedFeedNames): string =>
+  `'${quoteQualified(names.sequence).replace(/'/g, "''")}'`
+
+/**
+ * The ordered, idempotent DDL. Every statement is `IF NOT EXISTS`, so a second
+ * run against existing objects is a no-op that keeps every row.
+ *
+ * Shapes that are load-bearing:
+ *
+ * - `_feed_rows` is keyed `(feed, key)`: one row per record, which is what
+ *   "coalesced, latest wins" means in storage, and the arbiter the writer's
+ *   `ON CONFLICT` names. `doc` is NULL for a tombstone; a document that encodes to
+ *   JSON `null` is the jsonb value `null`, which is not SQL NULL, so the two
+ *   cannot be confused.
+ * - The `(feed, seq)` index is what `changesAfter` pages by.
+ * - ONE sequence serves every feed in the prefix. A feed's `seq` values therefore
+ *   have gaps, which the cursor never minds: it compares, never counts.
+ * - `_feed_cursors` holds the cursor AND the lease, so the cursor's
+ *   compare-and-set can fence on the lease holder in the same row it moves. The
+ *   cursor is `(generation, seq)`, both NULL before a sink's first sync and never
+ *   one without the other, which the `CHECK` holds. `last_advance_at` is when
+ *   the cursor last moved, NULL until it first does; taking a lease leaves it
+ *   alone, so a sink registered and never run shows as one.
+ * - `_feed_generations` holds the checkpoint key a feed is bound to, so binding
+ *   one feed to two materialisations is refused across processes, not only within
+ *   one.
+ */
+export const feedDdlStatements = (
+  names: ResolvedFeedNames,
+): ReadonlyArray<string> => {
+  const rows = quoteQualified(names.rowsTable)
+  const generations = quoteQualified(names.generationsTable)
+  const cursors = quoteQualified(names.cursorsTable)
+  const parked = quoteQualified(names.parkedTable)
+  return [
+    `CREATE SCHEMA IF NOT EXISTS ${quoteAtom(names.schema)};`,
+
+    `CREATE SEQUENCE IF NOT EXISTS ${quoteQualified(names.sequence)};`,
+
+    `CREATE TABLE IF NOT EXISTS ${rows} (
+       "feed" text NOT NULL,
+       "key" text NOT NULL,
+       "doc" jsonb NULL,
+       "seq" bigint NOT NULL,
+       "event_position" bigint NOT NULL,
+       PRIMARY KEY ("feed", "key")
+     );`,
+
+    `CREATE INDEX IF NOT EXISTS ${quoteAtom(names.rowsSeqIndex)}
+       ON ${rows} ("feed", "seq");`,
+
+    `CREATE TABLE IF NOT EXISTS ${generations} (
+       "feed" text PRIMARY KEY,
+       "generation" bigint NOT NULL,
+       "checkpoint_projection" text NULL,
+       "checkpoint_partition" text NULL
+     );`,
+
+    `CREATE TABLE IF NOT EXISTS ${cursors} (
+       "feed" text NOT NULL,
+       "sink" text NOT NULL,
+       "generation" bigint NULL,
+       "seq" bigint NULL,
+       "lease_holder" text NULL,
+       "lease_expires_at" timestamptz NULL,
+       "last_advance_at" timestamptz NULL,
+       PRIMARY KEY ("feed", "sink"),
+       CHECK (("generation" IS NULL) = ("seq" IS NULL))
+     );`,
+
+    `CREATE TABLE IF NOT EXISTS ${parked} (
+       "feed" text NOT NULL,
+       "sink" text NOT NULL,
+       "key" text NOT NULL,
+       "seq" bigint NOT NULL,
+       "reason" text NOT NULL,
+       "parked_at" timestamptz NOT NULL,
+       PRIMARY KEY ("feed", "sink", "key")
+     );`,
+  ]
+}
+
+/** The DDL as statements on `sql`, one `sql.unsafe` each, in order. */
+export const runFeedDdl = (
+  sql: SqlClient.SqlClient,
+  names: ResolvedFeedNames,
+): ReadonlyArray<Statement.Statement<unknown>> =>
+  feedDdlStatements(names).map((statement) => sql.unsafe(statement))

package/src/internal/statements.ts

@@ -0,0 +1,387 @@
+/**
+ * Every runtime statement text the Postgres change feed issues, compiled once per
+ * name set, and the conventions their parameters follow.
+ *
+ * One module, so what the feed sends to the database is auditable in one file.
+ * The Effect wiring that issues them lives in `feed.ts`, `syncStore.ts`, `lease.ts`
+ * and `withFeed.ts`; none of those writes SQL of its own.
+ *
+ * ## Parameter conventions
+ *
+ * - Every 64-bit value (`seq`, `generation`, `event_position`) is bound as a
+ *   decimal STRING and cast (`$n::bigint`), and read back as text and turned into
+ *   a `bigint`, so no value ever passes through a JS `number` and no driver's
+ *   integer handling can round one.
+ * - A batch of rows is bound as ONE `jsonb` parameter and unpacked server-side
+ *   (`jsonb_to_recordset`, `jsonb_array_elements_text`), so a batch is one
+ *   statement whatever its size and no array-binding support is asked of the
+ *   driver.
+ * - A timestamp is bound as epoch MILLISECONDS from Effect's `Clock`, and read back
+ *   the same way. Lease expiry is judged against the worker's Clock rather than the
+ *   database's `now()`, so a `TestClock` governs it in tests as it governs every
+ *   other time in this repository; the cost is that workers on several hosts must
+ *   keep their clocks within a small fraction of the lease length of each other.
+ * - A document is read back as `doc::text` and parsed here, so a consumer's JSON
+ *   parsing or name transforms cannot reshape it on the way.
+ * - A column read back as text is ALIASED to its own name, so every `ORDER BY`
+ *   qualifies the column with its table alias: an unqualified name in `ORDER BY`
+ *   resolves to the output column first, and `seq` would then sort as text, with
+ *   `10` before `4`.
+ *
+ * ## The feed lock
+ *
+ * The generations row of a feed doubles as its WRITE LOCK. A feed's `seq` is
+ * ascending in commit order only while one transaction at a time takes `seq`
+ * values for that feed, and the subscribe machine silently loses a row whose `seq`
+ * commits below one already read (ADR-0009). The materialisation is one writer, but
+ * two other things take `seq` values for a feed outside its commit: `retryParked`
+ * re-stamps a row, and a reset empties the feed. So the writer takes the row
+ * `FOR SHARE` before it takes any `seq`, `retryParked` takes it `FOR UPDATE`, and
+ * the reset UPDATEs it; each waits for the others to commit, and `seq` order is
+ * commit order for all three.
+ */
+import { quoteQualified, type ResolvedFeedNames, sequenceLiteral } from './ddl'
+
+/** Every statement text, compiled for one name set. */
+export interface FeedStatements {
+  // --- the writer ---
+  /** `$1` feed. Creates the generations row at generation 0 if absent. */
+  readonly ensureGeneration: string
+  /** `$1` feed. The writer's share of the feed lock. */
+  readonly lockFeedShared: string
+  /** `$1` feed, `$2` event position, `$3` jsonb `[{ key, doc }]`. */
+  readonly upsertRows: string
+  /** `$1` feed, `$2` event position, `$3` jsonb `[key]`. */
+  readonly tombstoneRows: string
+  // --- the source ---
+  /** `$1` feed. */
+  readonly selectGeneration: string
+  /** `$1` feed, `$2` after seq, `$3` limit. */
+  readonly changesAfter: string
+  // --- the sync store ---
+  /** `$1` feed, `$2` sink. */
+  readonly selectCursor: string
+  /**
+   * `$1` feed, `$2` sink, `$3` holder, `$4` next generation, `$5` next seq,
+   * `$6` expected generation (NULL for none), `$7` expected seq (NULL for none),
+   * `$8` now ms, recorded as the sink's last advance.
+   */
+  readonly casCursor: string
+  /** `$1` feed, `$2` sink. */
+  readonly clearParked: string
+  /** `$1` feed, `$2` sink, `$3` jsonb `[key]`. */
+  readonly unparkKeys: string
+  /** `$1` feed, `$2` sink, `$3` jsonb `[{ key, seq, reason, parked_at_ms }]`. */
+  readonly parkKeys: string
+  /** `$1` feed, `$2` sink. */
+  readonly selectParked: string
+  /** `$1` feed. The feed lock, exclusively, for `retryParked`. */
+  readonly lockFeedExclusive: string
+  /** `$1` feed, `$2` sink, `$3` key. */
+  readonly unparkOne: string
+  /** `$1` feed, `$2` key. */
+  readonly restampRow: string
+  /** `$1` feed. */
+  readonly collectTombstones: string
+  // --- removing a sink ---
+  /** `$1` lock name. The advisory lock, held until the transaction ends. */
+  readonly tryAdvisoryXactLock: string
+  /** `$1` feed, `$2` sink, `$3` now ms. Deletes the cursor row unless a live lease row holds it. */
+  readonly deleteCursorUnlessLeased: string
+  /** `$1` feed, `$2` sink. Whether a cursor row is still there. */
+  readonly cursorExists: string
+  /** `$1` feed, `$2` sink. Every park of the sink, one row back per park. */
+  readonly deleteSinkParked: string
+  /** `$1` feed. */
+  readonly selectHead: string
+  /** `$1` feed. */
+  readonly describeSinks: string
+  /** `$1` feed. */
+  readonly describeParked: string
+  // --- the lease ---
+  /**
+   * `$1` feed, `$2` sink, `$3` holder, `$4` expiry ms, `$5` now ms, `$6` whether
+   * the caller holds the sink's advisory lock for its transaction.
+   */
+  readonly takeLeaseRow: string
+  /** `$1` feed, `$2` sink, `$3` holder, `$4` expiry ms. */
+  readonly renewLeaseRow: string
+  /** `$1` feed, `$2` sink, `$3` holder. */
+  readonly releaseLease: string
+  /**
+   * `$1` feed, `$2` sink, `$3` holder, `$4` now ms, `$5` lock name. On the
+   * dedicated connection. Records an advisory holder unless a live lease row
+   * holds the row or this session no longer holds the lock; zero rows means one
+   * of the two.
+   */
+  readonly claimAdvisoryHolder: string
+  /** `$1` lock name. On the dedicated connection. */
+  readonly tryAdvisoryLock: string
+  /** `$1` lock name. On the dedicated connection. */
+  readonly holdsAdvisoryLock: string
+  /** `$1` lock name. On the dedicated connection. */
+  readonly advisoryUnlock: string
+  // --- the decorated store ---
+  /** `$1` feed, `$2` projection, `$3` partition. */
+  readonly bindFeed: string
+  /** `$1` feed. */
+  readonly bumpGeneration: string
+  /** `$1` feed. */
+  readonly deleteFeedRows: string
+}
+
+/** Compile every statement for `names`. */
+export const compileFeedStatements = (
+  names: ResolvedFeedNames,
+): FeedStatements => {
+  const rows = quoteQualified(names.rowsTable)
+  const generations = quoteQualified(names.generationsTable)
+  const cursors = quoteQualified(names.cursorsTable)
+  const parked = quoteQualified(names.parkedTable)
+  const nextSeq = `nextval(${sequenceLiteral(names)})`
+  const msToTimestamp = (param: string) =>
+    `to_timestamp(${param}::double precision / 1000)`
+  const timestampToMs = (column: string) =>
+    `round(extract(epoch from ${column}) * 1000)::bigint::text`
+  const advisoryKeyOf = (param: string) => `hashtextextended(${param}, 0)`
+  const advisoryKey = advisoryKeyOf('$1')
+  // Whether THIS session holds the advisory lock named by `param`. A bigint
+  // advisory key is stored in `pg_locks` split into two 32-bit halves, `classid`
+  // the high and `objid` the low, with `objsubid` 1.
+  const sessionHoldsLock = (param: string) => `EXISTS (
+                          SELECT 1 FROM pg_locks l
+                          WHERE l.locktype = 'advisory'
+                            AND l.pid = pg_backend_pid()
+                            AND l.granted
+                            AND l.objsubid = 1
+                            AND l.classid = ((${advisoryKeyOf(param)} >> 32) & 4294967295)::oid
+                            AND l.objid = (${advisoryKeyOf(param)} & 4294967295)::oid
+                        )`
+
+  return {
+    ensureGeneration: `INSERT INTO ${generations} ("feed", "generation")
+                       VALUES ($1, 0)
+                       ON CONFLICT ("feed") DO NOTHING`,
+
+    lockFeedShared: `SELECT 1 AS locked FROM ${generations}
+                     WHERE "feed" = $1 FOR SHARE`,
+
+    // One `nextval` per INSERTED candidate, kept by the update arm through
+    // `excluded.seq`, so an unchanged document burns a value and writes nothing:
+    // the `WHERE … IS DISTINCT FROM` arm compares the normalised jsonb, so key
+    // order is no change.
+    upsertRows: `INSERT INTO ${rows} AS r ("feed", "key", "doc", "seq", "event_position")
+                 SELECT $1, t."key", t."doc", ${nextSeq}, $2::bigint
+                 FROM jsonb_to_recordset($3::jsonb) AS t("key" text, "doc" jsonb)
+                 ON CONFLICT ("feed", "key") DO UPDATE
+                 SET "doc" = excluded."doc",
+                     "seq" = excluded."seq",
+                     "event_position" = excluded."event_position"
+                 WHERE r."doc" IS DISTINCT FROM excluded."doc"`,
+
+    // An UPDATE, never an insert: a remove of an absent key writes nothing, and
+    // neither does a remove of a key that is already a tombstone.
+    tombstoneRows: `UPDATE ${rows} AS r
+                    SET "doc" = NULL, "seq" = ${nextSeq}, "event_position" = $2::bigint
+                    FROM jsonb_array_elements_text($3::jsonb) AS t("key")
+                    WHERE r."feed" = $1 AND r."key" = t."key" AND r."doc" IS NOT NULL`,
+
+    selectGeneration: `SELECT "generation"::text AS generation
+                       FROM ${generations} WHERE "feed" = $1`,
+
+    changesAfter: `SELECT "key" AS key, "doc"::text AS doc, "seq"::text AS seq,
+                          "event_position"::text AS event_position
+                   FROM ${rows} AS r
+                   WHERE r."feed" = $1 AND r."seq" > $2::bigint
+                   ORDER BY r."seq"
+                   LIMIT $3`,
+
+    selectCursor: `SELECT "generation"::text AS generation, "seq"::text AS seq
+                   FROM ${cursors} WHERE "feed" = $1 AND "sink" = $2`,
+
+    // Guarded like a checkpoint AND fenced on the holder: zero rows means the
+    // stored cursor was not the expected one, or the lease is somebody else's.
+    casCursor: `UPDATE ${cursors}
+                SET "generation" = $4::bigint, "seq" = $5::bigint,
+                    "last_advance_at" = ${msToTimestamp('$8')}
+                WHERE "feed" = $1 AND "sink" = $2 AND "lease_holder" = $3
+                  AND "generation" IS NOT DISTINCT FROM $6::bigint
+                  AND "seq" IS NOT DISTINCT FROM $7::bigint
+                RETURNING 1 AS landed`,
+
+    clearParked: `DELETE FROM ${parked} WHERE "feed" = $1 AND "sink" = $2`,
+
+    unparkKeys: `DELETE FROM ${parked}
+                 WHERE "feed" = $1 AND "sink" = $2
+                   AND "key" IN (SELECT jsonb_array_elements_text($3::jsonb))`,
+
+    parkKeys: `INSERT INTO ${parked} ("feed", "sink", "key", "seq", "reason", "parked_at")
+               SELECT $1, $2, t."key", t."seq"::bigint, t."reason", ${msToTimestamp('t."parked_at_ms"')}
+               FROM jsonb_to_recordset($3::jsonb)
+                 AS t("key" text, "seq" text, "reason" text, "parked_at_ms" text)
+               ON CONFLICT ("feed", "sink", "key") DO UPDATE
+               SET "seq" = excluded."seq", "reason" = excluded."reason",
+                   "parked_at" = excluded."parked_at"`,
+
+    selectParked: `SELECT "key" AS key, "seq"::text AS seq, "reason" AS reason,
+                          ${timestampToMs('"parked_at"')} AS parked_at_ms
+                   FROM ${parked} AS p
+                   WHERE p."feed" = $1 AND p."sink" = $2
+                   ORDER BY p."seq", p."key"`,
+
+    lockFeedExclusive: `SELECT 1 AS locked FROM ${generations}
+                        WHERE "feed" = $1 FOR UPDATE`,
+
+    unparkOne: `DELETE FROM ${parked}
+                WHERE "feed" = $1 AND "sink" = $2 AND "key" = $3
+                RETURNING 1 AS unparked`,
+
+    restampRow: `UPDATE ${rows} SET "seq" = ${nextSeq}
+                 WHERE "feed" = $1 AND "key" = $2`,
+
+    // Every sink REGISTERED on the feed counts — every cursor row, whatever
+    // generation its cursor was saved at — and the lowest of their cursors bounds
+    // what goes. A cursor at an older generation needs no arm of its own:
+    // `FeedSyncStore.ts`'s tombstone section owns why the minimum already holds it
+    // below every row, and this store keeps that section's premise, since a reset
+    // (`withFeed.ts`) moves the generation and empties the feed in one
+    // transaction and the one sequence never goes back. A sink with no cursor is
+    // resyncing from the origin and blocks collection outright, which `bool_or`
+    // says. No cursor row at all leaves both aggregates NULL, so the guard is NULL
+    // and nothing goes. The cursors are read in the delete's own statement
+    // snapshot, so a cursor saved after it can only be one that blocked here
+    // (nothing deleted) or one that moved up. A sink whose cursor row is CREATED
+    // after the snapshot is not counted, and need not be: that row is made when
+    // the sink takes its lease, before it reads the feed, and a feed holds one row
+    // per key, so a tombstone this collects had replaced its key's live row before
+    // such a sink could read anything.
+    collectTombstones: `WITH "low" AS (
+                          SELECT min(c."seq") AS "seq",
+                                 bool_or(c."seq" IS NULL) AS "blocked"
+                          FROM ${cursors} c
+                          WHERE c."feed" = $1
+                        )
+                        DELETE FROM ${rows} r USING "low"
+                        WHERE r."feed" = $1 AND r."doc" IS NULL
+                          AND NOT "low"."blocked" AND r."seq" <= "low"."seq"
+                        RETURNING 1 AS collected`,
+
+    // The transaction-scoped twin of `tryAdvisoryLock`, on the same key, so it
+    // conflicts with a session lock any advisory worker holds and is let go at
+    // commit or rollback without an unlock of its own.
+    tryAdvisoryXactLock: `SELECT pg_try_advisory_xact_lock(${advisoryKey}) AS taken`,
+
+    // A row whose expiry is later than the caller's now is a live lease row and
+    // stays. A holder with no expiry is an advisory one, and is deleted only
+    // because the caller holds the advisory lock, which proves its session gone.
+    // The test is in the delete itself, so a lease row taken after an earlier
+    // read is still refused here rather than deleted from under its worker.
+    deleteCursorUnlessLeased: `DELETE FROM ${cursors}
+                               WHERE "feed" = $1 AND "sink" = $2
+                                 AND ("lease_expires_at" IS NULL
+                                      OR "lease_expires_at" <= ${msToTimestamp('$3')})
+                               RETURNING 1 AS removed`,
+
+    cursorExists: `SELECT 1 AS present FROM ${cursors}
+                   WHERE "feed" = $1 AND "sink" = $2`,
+
+    deleteSinkParked: `DELETE FROM ${parked} WHERE "feed" = $1 AND "sink" = $2
+                       RETURNING 1 AS removed`,
+
+    selectHead: `SELECT COALESCE(max("seq"), 0)::text AS head
+                 FROM ${rows} WHERE "feed" = $1`,
+
+    describeSinks: `SELECT c."sink" AS sink,
+                           c."generation"::text AS generation,
+                           c."seq"::text AS seq,
+                           c."lease_holder" AS lease_holder,
+                           ${timestampToMs('c."lease_expires_at"')} AS lease_expires_at_ms,
+                           ${timestampToMs('c."last_advance_at"')} AS last_advance_at_ms,
+                           (SELECT count(*) FROM ${rows} r
+                            WHERE r."feed" = c."feed"
+                              AND CASE WHEN c."seq" IS NULL THEN r."doc" IS NOT NULL
+                                       ELSE r."seq" > c."seq" END)::text AS pending
+                    FROM ${cursors} c
+                    WHERE c."feed" = $1
+                    ORDER BY c."sink"`,
+
+    describeParked: `SELECT "sink" AS sink, "key" AS key, "seq"::text AS seq,
+                            "reason" AS reason,
+                            ${timestampToMs('"parked_at"')} AS parked_at_ms
+                     FROM ${parked} AS p
+                     WHERE p."feed" = $1
+                     ORDER BY p."sink", p."seq", p."key"`,
+
+    // Taken when nobody holds it, when the holder's expiry has passed, or when the
+    // holder has no expiry — an ADVISORY holder — and the caller holds that
+    // sink's advisory lock for its own transaction (`$6`), which an advisory
+    // worker's live session would have refused, so the session that recorded the
+    // holder is gone. The caller holds that lock until this statement commits, so
+    // no advisory worker can take the lock and record itself in between.
+    takeLeaseRow: `INSERT INTO ${cursors} AS c ("feed", "sink", "lease_holder", "lease_expires_at")
+                   VALUES ($1, $2, $3, ${msToTimestamp('$4')})
+                   ON CONFLICT ("feed", "sink") DO UPDATE
+                   SET "lease_holder" = excluded."lease_holder",
+                       "lease_expires_at" = excluded."lease_expires_at"
+                   WHERE c."lease_holder" IS NULL
+                      OR (c."lease_expires_at" IS NOT NULL
+                          AND c."lease_expires_at" <= ${msToTimestamp('$5')})
+                      OR (c."lease_expires_at" IS NULL AND $6::boolean)
+                   RETURNING 1 AS taken`,
+
+    // Never moves the expiry back: a renewal the worker abandoned at its timeout
+    // can still land after a later one, if its cancel came too late, and must not
+    // shorten the lease the later one recorded, which the worker's `ensureHeld`
+    // already counts on.
+    renewLeaseRow: `UPDATE ${cursors}
+                    SET "lease_expires_at" = GREATEST("lease_expires_at", ${msToTimestamp('$4')})
+                    WHERE "feed" = $1 AND "sink" = $2 AND "lease_holder" = $3
+                    RETURNING 1 AS renewed`,
+
+    releaseLease: `UPDATE ${cursors}
+                   SET "lease_holder" = NULL, "lease_expires_at" = NULL
+                   WHERE "feed" = $1 AND "sink" = $2 AND "lease_holder" = $3`,
+
+    // Run on the SESSION that took the advisory lock, and proposes its row only
+    // while that session still holds the lock, so a claim from a session that has
+    // died — or let the lock go — since its try-lock records nothing, and cannot
+    // overwrite a successor that took the lock in between. Holding the lock proves
+    // that any ADVISORY holder recorded here (one with no expiry) is a dead
+    // session's, so that one is taken over. A lease-row holder whose expiry has not
+    // passed is live and is never taken over, as `takeLeaseRow` takes over an
+    // advisory holder only once its lock is free: whichever kind took the row
+    // first keeps it while it lives.
+    claimAdvisoryHolder: `INSERT INTO ${cursors} AS c ("feed", "sink", "lease_holder", "lease_expires_at")
+                          SELECT $1::text, $2::text, $3::text, NULL::timestamptz
+                          WHERE ${sessionHoldsLock('$5')}
+                          ON CONFLICT ("feed", "sink") DO UPDATE
+                          SET "lease_holder" = excluded."lease_holder",
+                              "lease_expires_at" = NULL
+                          WHERE c."lease_holder" IS NULL
+                             OR c."lease_expires_at" IS NULL
+                             OR c."lease_expires_at" <= ${msToTimestamp('$4')}
+                          RETURNING 1 AS claimed`,
+
+    tryAdvisoryLock: `SELECT pg_try_advisory_lock(${advisoryKey}) AS taken`,
+
+    holdsAdvisoryLock: `SELECT ${sessionHoldsLock('$1')} AS held`,
+
+    advisoryUnlock: `SELECT pg_advisory_unlock(${advisoryKey}) AS released`,
+
+    bindFeed: `INSERT INTO ${generations} AS g
+                 ("feed", "generation", "checkpoint_projection", "checkpoint_partition")
+               VALUES ($1, 0, $2, $3)
+               ON CONFLICT ("feed") DO UPDATE
+               SET "checkpoint_projection" = COALESCE(g."checkpoint_projection", excluded."checkpoint_projection"),
+                   "checkpoint_partition" = COALESCE(g."checkpoint_partition", excluded."checkpoint_partition")
+               RETURNING "checkpoint_projection" AS projection,
+                         "checkpoint_partition" AS partition`,
+
+    bumpGeneration: `INSERT INTO ${generations} AS g ("feed", "generation")
+                     VALUES ($1, 1)
+                     ON CONFLICT ("feed") DO UPDATE
+                     SET "generation" = g."generation" + 1`,
+
+    deleteFeedRows: `DELETE FROM ${rows} WHERE "feed" = $1`,
+  }
+}