@kairos-es/read-postgres 0.0.0

package/src/internal/statements.ts

@@ -0,0 +1,144 @@
+/**
+ * The four runtime statement texts the Postgres `ProjectionStore` issues, and the
+ * TWO parameter lists that feed them.
+ *
+ * The texts and their binding live in ONE module deliberately. `$3` and `$4` of
+ * the guarded advance are `next` and `expected` — both a `Position`, so both a
+ * `bigint` — and the whole exactly-once property of the read side rests on which
+ * of them the `SET` writes and which the `WHERE` compares. While the texts sat
+ * beside the store's Effect wiring and the binding sat inside its closure, that
+ * correspondence was asserted in prose in one place and implemented 180 lines away
+ * in another, and prose is exactly what drifted: a comment claimed a `bind` helper
+ * made a transposed argument list inexpressible, while the call site spread two
+ * interchangeable `Position`s positionally. Here the claim is checkable by reading
+ * one file, and `test/guardParameters.test.ts` pins it without a database.
+ *
+ * Everything else follows `internal/ddl.ts`: identifiers are pre-quoted literal
+ * text (`quoteQualified` / `CHECKPOINT_COLUMNS`) embedded into `sql.unsafe`, and
+ * every VALUE is a bound `$n` parameter, never interpolated.
+ */
+import type { Position } from '@kairos-es/core'
+import type { CheckpointKey } from '@kairos-es/read'
+import {
+  CHECKPOINT_COLUMNS,
+  quoteQualified,
+  type ResolvedCheckpointNames,
+} from './ddl'
+
+/**
+ * The four statement texts a store issues, compiled ONCE per store from the
+ * resolved names — the same compile-once discipline as the event store's read
+ * plans, so a long-lived projection re-binds only its parameters rather than
+ * re-assembling SQL per batch.
+ *
+ * All four take their parameters in ONE positional order — `$1` projection,
+ * `$2` partition, `$3` next, `$4` expected — and no consumer writes that order
+ * out: `keyParams` binds the two the `select` and the `reset` take, and
+ * `advanceParams` binds all four for the two guard shapes, reading each from a
+ * NAMED field. That naming is the point rather than a nicety, because the type
+ * system cannot help here: `next` and `expected` are the same type, so a
+ * positional list makes `[..., expected, next]` typecheck, and a transposed guard
+ * would compare the stored cursor against the position it was about to write —
+ * inverting the compare-and-set that makes a projection exactly-once. Reading the
+ * fields by name does not make the mistake impossible, but it makes it
+ * unwritable without naming the wrong field, which review and a diff can see.
+ */
+export interface CheckpointStatements {
+  readonly select: string
+  readonly upsertFromOrigin: string
+  readonly advance: string
+  readonly reset: string
+}
+
+/**
+ * Build the statement texts for a resolved name set.
+ *
+ * **The two guard shapes, and why one cannot serve both.** The guarded advance is
+ * a compare-and-set on `last_position`, and its correct SQL depends on whether the
+ * expected value is `ORIGIN`:
+ *
+ * - `expected === ORIGIN` needs `upsertFromOrigin`. A never-committed key has NO
+ *   ROW (a key reads back as `ORIGIN` by absence, so "fresh" and "reset" are one
+ *   state), so a plain `UPDATE` would match zero rows and report
+ *   `CheckpointSuperseded` — a fresh read model could never make its FIRST commit.
+ *   The `ON CONFLICT … DO UPDATE … WHERE chk.last_position = $4` arm keeps the
+ *   upsert a real guard rather than a blind write: two racers both starting from
+ *   `ORIGIN` cannot both win, because the second one's arm blocks on the first's
+ *   uncommitted row, then re-reads it and finds a position that is no longer
+ *   `ORIGIN`, matching zero rows. That arm also makes "row present at `0`"
+ *   (an operator zeroing the column by hand instead of deleting the row) behave
+ *   identically to "row absent", so the two ways of expressing a reset are
+ *   indistinguishable to a first commit.
+ * - `expected > ORIGIN` needs `advance`, the plain `UPDATE`. The upsert would be
+ *   WRONG here: `ON CONFLICT` guards only the branch where the row exists, so an
+ *   absent row would be INSERTED unconditionally — a `resetCheckpoint` racing an
+ *   in-flight commit would be silently undone, the key resurrected at `next`, and
+ *   the entire backlog the reset existed to replay skipped with no error at all.
+ *   The `UPDATE`'s zero rows for an absent row is the CORRECT outcome: somebody
+ *   reset it, so this commit must lose and the runner must re-read.
+ *
+ * Both shapes `RETURNING` a column so the outcome is a ROW COUNT: zero rows means
+ * the guard lost. That mirrors the event store's append, where a conflict is the
+ * function's zero-row result and never a caught SQL error — no unique-violation
+ * or serialisation-failure path to classify, so a lost guard can never arrive
+ * mistagged as an infrastructure fault.
+ *
+ * The `AS chk` alias exists so the `DO UPDATE` guard can reference the EXISTING
+ * row unambiguously: the insert target is schema-qualified, and without an alias
+ * the guard would need a three-part column reference.
+ */
+export const compileStatements = (
+  names: ResolvedCheckpointNames,
+): CheckpointStatements => {
+  const table = quoteQualified(names.checkpointTable)
+  const columns = CHECKPOINT_COLUMNS
+  const byKey = `${columns.projection} = $1 AND ${columns.partition} = $2`
+
+  return {
+    select: `SELECT ${columns.lastPosition}
+             FROM ${table}
+             WHERE ${byKey}`,
+
+    upsertFromOrigin: `INSERT INTO ${table} AS chk (
+                         ${columns.projection},
+                         ${columns.partition},
+                         ${columns.lastPosition}
+                       ) VALUES ($1, $2, $3)
+                       ON CONFLICT (${columns.projection}, ${columns.partition})
+                       DO UPDATE SET ${columns.lastPosition} = $3
+                       WHERE chk.${columns.lastPosition} = $4
+                       RETURNING ${columns.lastPosition}`,
+
+    advance: `UPDATE ${table}
+              SET ${columns.lastPosition} = $3
+              WHERE ${byKey} AND ${columns.lastPosition} = $4
+              RETURNING ${columns.lastPosition}`,
+
+    reset: `DELETE FROM ${table} WHERE ${byKey}`,
+  }
+}
+
+/** The `$1`/`$2` key parameters the `select` and the `reset` take. */
+export const keyParams = (key: CheckpointKey): ReadonlyArray<unknown> => [
+  key.projection,
+  key.partition,
+]
+
+/**
+ * The `$1`-`$4` parameters both guard shapes take, read from named fields.
+ *
+ * The argument is an object rather than three positional parameters for the reason
+ * `CheckpointStatements` gives: `next` and `expected` are interchangeable to the
+ * type checker and catastrophic to swap, so the ONE place their order is written
+ * out reads each of them by name.
+ */
+export const advanceParams = (args: {
+  readonly key: CheckpointKey
+  readonly expected: Position
+  readonly next: Position
+}): ReadonlyArray<unknown> => [
+  args.key.projection,
+  args.key.partition,
+  args.next,
+  args.expected,
+]

package/src/projectionStore.ts

@@ -0,0 +1,300 @@
+/**
+ * The SQL `ProjectionStore`: a durable scalar checkpoint plus the guarded
+ * compare-and-set that brackets a read model's own view writes in ONE ordinary
+ * transaction (ADR-0007).
+ *
+ * This is the durable half of the parity pair. `@kairos-es/read`'s in-memory store
+ * is the oracle; this backend must produce identical OBSERVABLE behaviour, and the
+ * shared `projection-store-contract-tests` suite runs unchanged against both. The
+ * one place the two genuinely differ is HOW the abort is achieved:
+ *
+ * - in memory, the guard is checked FIRST and a loss means `viewWrites` never ran
+ *   (abort by omission — there is nothing to undo);
+ * - here, `viewWrites` runs first and a lost guard FAILS, so the transaction rolls
+ *   the view writes back with it (abort by undo).
+ *
+ * Both satisfy the port's promise that a lost guard leaves no observable view
+ * effect, which is why ordering inside the transaction is a performance choice
+ * rather than a correctness one: running the guard last keeps the checkpoint row
+ * lock held only for the advance instead of for the whole batch's worth of view
+ * writes.
+ *
+ * Two contract inversions worth naming, both deliberate:
+ *
+ * 1. A `SqlError` becomes a `ProjectionStoreError` on the ERROR CHANNEL — the
+ *    opposite of the event store, where an infrastructure fault is a DEFECT
+ *    (`Effect.die`, ADR-0002). The read side has a supervisor above it whose whole
+ *    job is telling "retry the subscription with backoff" from "give up and report
+ *    a stalled projection", and a defect carries no such distinction. On the event
+ *    store there is no supervisor: a caller cannot meaningfully retry a broken
+ *    connection, so dying is right there and wrong here.
+ * 2. A lost guard is a tagged failure (`CheckpointSuperseded`), never a returned
+ *    outcome value, and that failure is exactly what aborts the transaction. A
+ *    returned value would only roll back if the caller remembered to convert it
+ *    into a failure, and forgetting is silent double-application.
+ *
+ * The store closes over the `SqlClient` it acquired, so the returned
+ * `ProjectionStore.commit` adds NO `SqlClient` to the caller's `R` — a read model
+ * stays free of the view store's requirements, which is what lets one runner drive
+ * read models over different backends.
+ *
+ * What this module owns is the Effect wiring: the client, the transaction bracket,
+ * the error classification. The SQL itself and the parameter lists that feed it are
+ * `internal/statements.ts`, which owns the argument for why the two live together.
+ */
+import type { SqlError } from '@effect/sql'
+import { SqlClient } from '@effect/sql'
+import { ORIGIN, Position } from '@kairos-es/core'
+import {
+  type CheckpointKey,
+  CheckpointSuperseded,
+  type ProjectionStore,
+  ProjectionStoreError,
+} from '@kairos-es/read'
+import { Effect } from 'effect'
+import { decodeReadPostgresConfig, type ReadPostgresConfig } from './config'
+import { resolveCheckpointNames } from './internal/ddl'
+import {
+  advanceParams,
+  compileStatements,
+  keyParams,
+} from './internal/statements'
+
+/**
+ * A row of the checkpoint table's only interesting column.
+ *
+ * `last_position` is typed as a STRING because `bigint`/`int8` arrives from the
+ * driver as a decimal string: a 64-bit position exceeds JS `number` safety at
+ * 2^53, so it is reconstructed with `BigInt(...)` and never coerced through
+ * `number` — the same round-trip the event store performs for its `MAX(id)` head.
+ * The snake_case key is the column name verbatim; see `withoutTransforms()` below
+ * for why a consumer's result-name transform cannot rename it under us.
+ */
+type LastPositionRow = { readonly last_position: string }
+
+/** A statement returning no columns (a `DELETE` with no `RETURNING`). */
+type NoRows = Record<string, never>
+
+/**
+ * The caller's `viewWrites` failure, wrapped for the duration of the transaction.
+ *
+ * `sql.withTransaction` ADDS `SqlError` to whatever its body fails with, so the
+ * frame's own faults (BEGIN/SAVEPOINT/COMMIT) arrive in the same channel as the
+ * caller's `E` — and if a read model's view writes are themselves SQL, that `E`
+ * IS `SqlError`, making the two indistinguishable. Wrapping `E` before entering
+ * the transaction and unwrapping it after keeps them apart, so the port's promise
+ * that a projection's own `E` passes through `commit` UNTOUCHED holds exactly,
+ * while a genuine transaction-frame fault still becomes a `ProjectionStoreError`.
+ * A plain tagged object rather than a `Data.TaggedError` because it never escapes
+ * this module.
+ */
+interface ViewWriteFailed<E> {
+  readonly _tag: 'ViewWriteFailed'
+  readonly error: E
+}
+
+/** Every failure `sql.withTransaction` can hand back for a `commit` body. */
+type CommitFailure<E> =
+  | ViewWriteFailed<E>
+  | CheckpointSuperseded
+  | ProjectionStoreError
+  | SqlError.SqlError
+
+/**
+ * Turn a `ProjectionStoreError` out of a SQL fault, naming what was being
+ * attempted and for which key. `reason` is the human-readable line a supervisor
+ * logs, so it carries the key and the driver's message; `cause` carries the
+ * `SqlError` itself for anything that wants to inspect it.
+ */
+const storeError =
+  (attempt: string, key: CheckpointKey) =>
+  (cause: SqlError.SqlError): ProjectionStoreError =>
+    new ProjectionStoreError({
+      reason: `${attempt} for projection '${key.projection}' partition '${key.partition}' failed: ${cause.message}`,
+      cause,
+    })
+
+/**
+ * Restore the port's declared error channel after the transaction: unwrap the
+ * caller's `E`, and classify a transaction-frame `SqlError` as infrastructure.
+ * Both `CheckpointSuperseded` and an already-classified `ProjectionStoreError`
+ * pass through as they are.
+ */
+const unwrapCommitError = <E>(
+  key: CheckpointKey,
+  error: CommitFailure<E>,
+): E | CheckpointSuperseded | ProjectionStoreError => {
+  if (error._tag === 'ViewWriteFailed') {
+    return error.error
+  }
+  if (error._tag === 'SqlError') {
+    return storeError('the checkpoint commit transaction', key)(error)
+  }
+  return error
+}
+
+/**
+ * Build a durable `ProjectionStore` over the ambient `SqlClient`.
+ *
+ * A factory `Effect` rather than a `Layer`, matching the in-memory store: the view
+ * store is selected PER MATERIALISATION, so it is a value handed to a read model, not
+ * a context tag one store could claim process-wide. Per materialisation rather than
+ * per read model, because one read model may be materialised several times at once —
+ * a store from here beside an in-memory one, wired by `@kairos-es/read`'s
+ * `runProjections` — which is a shape a process-wide tag could not express at all. It
+ * acquires the client ONCE and closes over it, which is what keeps `commit`'s `R`
+ * down to the caller's own.
+ *
+ * **The atomic bracket covers writes issued through THIS client.** The caller's
+ * `viewWrites` join the transaction because `@effect/sql` carries the transaction's
+ * connection in the Effect CONTEXT, not in the client value — so any statement run
+ * through the same underlying client inside `commit` is in the same transaction,
+ * including through a differently-transformed copy of it. A write to a different
+ * database, or through an unrelated client, is NOT bracketed and the exactly-once
+ * property does not extend to it.
+ *
+ * `ensureCheckpointSchema(config)` must have run (in the caller's migrator or at
+ * boot) before the store is used; this factory performs no DDL, so it stays a pure
+ * runtime dependency on the client alone.
+ */
+export const makeSqlProjectionStore = (
+  config: ReadPostgresConfig = {},
+): Effect.Effect<ProjectionStore, never, SqlClient.SqlClient> =>
+  Effect.gen(function* () {
+    // `withoutTransforms()` because this package takes the CONSUMER's generic
+    // client, which may carry a result-name transform (`@effect/sql` will happily
+    // camel-case every returned key). Under one, `last_position` would arrive as
+    // `lastPosition`, `readCheckpoint` would see `undefined` and report `ORIGIN`,
+    // and a durable projection would silently replay its whole backlog on every
+    // boot. Stripping the transform for OUR statements is the fix; the caller's
+    // own view writes keep their client's transforms and still join the same
+    // transaction (the connection travels in the context, not the client).
+    const sql = (yield* SqlClient.SqlClient).withoutTransforms()
+
+    // Decode INSIDE the Effect so a malformed config (empty/dotted atom, an
+    // over-63-byte derived name) surfaces as a defect on the fibre building the
+    // store rather than as an exception thrown out of the factory call, matching
+    // `ensureCheckpointSchema`.
+    const names = resolveCheckpointNames(decodeReadPostgresConfig(config))
+    const statements = compileStatements(names)
+
+    const readCheckpoint = (
+      key: CheckpointKey,
+    ): Effect.Effect<Position, ProjectionStoreError> =>
+      sql.unsafe<LastPositionRow>(statements.select, keyParams(key)).pipe(
+        Effect.mapError(storeError('reading the checkpoint', key)),
+        Effect.map((rows) => {
+          const stored = rows[0]?.last_position
+          // No row means never committed (or reset), which the port defines as
+          // `ORIGIN` — so a fresh read model and a reset one both simply catch up
+          // from the start of the log.
+          return stored === undefined
+            ? ORIGIN
+            : // `Position.make` re-validates non-negativity, so a corrupted
+              // column becomes a loud defect here rather than a nonsensical
+              // cursor that silently reads nothing.
+              Position.make(BigInt(stored))
+        }),
+      )
+
+    /**
+     * The compare-and-set half of `commit`, run INSIDE the caller's transaction.
+     * Which shape is correct depends on `expected`; see `compileStatements` for
+     * why neither shape can serve both cases.
+     *
+     * Takes its three values as NAMED FIELDS, and `commit` hands it the very
+     * object the port handed `commit`, so `expected` and `next` are never lined up
+     * positionally anywhere between the port's boundary and the bound `$n`
+     * (`advanceParams` does the binding, also by name). They are both a `Position`,
+     * so nothing else would notice them swapping — and swapped, the guard would
+     * compare the stored cursor against the position it was about to write.
+     */
+    const guardedAdvance = (args: {
+      readonly key: CheckpointKey
+      readonly expected: Position
+      readonly next: Position
+    }): Effect.Effect<void, CheckpointSuperseded | ProjectionStoreError> => {
+      const { key, expected } = args
+      const [text, attempt] =
+        expected === ORIGIN
+          ? ([
+              statements.upsertFromOrigin,
+              'inserting the first checkpoint',
+            ] as const)
+          : ([statements.advance, 'advancing the checkpoint'] as const)
+      // `next` is bound AS IS — it is the last processed event's position, never
+      // `expected + 1`: positions are strictly increasing but not gapless, so a
+      // jump is normal and arithmetic would be wrong.
+      return sql.unsafe<LastPositionRow>(text, advanceParams(args)).pipe(
+        Effect.mapError(storeError(attempt, key)),
+        Effect.flatMap((rows) =>
+          // Zero rows = the guard lost. Failing (rather than returning an
+          // outcome) is what aborts the enclosing transaction and rolls the
+          // view writes back WITH it.
+          rows.length === 0
+            ? Effect.fail(new CheckpointSuperseded({ key, expected }))
+            : Effect.void,
+        ),
+      )
+    }
+
+    const commit = <E, R>(args: {
+      readonly key: CheckpointKey
+      readonly expected: Position
+      readonly next: Position
+      readonly viewWrites: Effect.Effect<void, E, R>
+    }): Effect.Effect<
+      void,
+      E | CheckpointSuperseded | ProjectionStoreError,
+      R
+    > =>
+      sql
+        .withTransaction(
+          args.viewWrites.pipe(
+            Effect.mapError(
+              (error): ViewWriteFailed<E> => ({
+                _tag: 'ViewWriteFailed',
+                error,
+              }),
+            ),
+            // View writes first, guard last. Ordering is a performance choice,
+            // not a correctness one: the transaction makes the pair atomic
+            // either way, and deferring the advance holds the checkpoint row
+            // lock only for the advance rather than across the whole batch. (The
+            // in-memory store has no such freedom — with nothing to roll back it
+            // MUST check first.) No `uninterruptible` wrapper either:
+            // `withTransaction` masks interruption around its own frame, so an
+            // interrupt landing mid-body rolls back exactly like a failure.
+            // `args` itself, not three values pulled out of it in an order: see
+            // `guardedAdvance`.
+            Effect.zipRight(guardedAdvance(args)),
+          ),
+        )
+        .pipe(Effect.mapError((error) => unwrapCommitError<E>(args.key, error)))
+
+    const resetCheckpoint = (
+      key: CheckpointKey,
+    ): Effect.Effect<void, ProjectionStoreError> =>
+      // DELETE rather than `SET last_position = 0`, so "never committed" and
+      // "reset" stay ONE state — which is exactly what the port promises the
+      // read-back is, and what the in-memory store's map delete does.
+      sql
+        .unsafe<NoRows>(statements.reset, keyParams(key))
+        .pipe(
+          Effect.mapError(storeError('resetting the checkpoint', key)),
+          Effect.asVoid,
+        )
+
+    // Annotated at the definition site rather than only through the exported
+    // signature, per the rule on `ProjectionStore` itself.
+    const store: ProjectionStore = {
+      // Outlives the process, which is the R2 input: a durable view is legal only
+      // over a durable log, and the runner dies at construction if it is wired
+      // over an ephemeral one.
+      durability: 'durable',
+      readCheckpoint,
+      commit,
+      resetCheckpoint,
+    }
+    return store
+  })