@kairos-es/read-postgres 0.0.0

package/dist/esm/projectionStore.js

@@ -0,0 +1,147 @@
+import { SqlClient } from '@effect/sql';
+import { ORIGIN, Position } from '@kairos-es/core';
+import { CheckpointSuperseded, ProjectionStoreError } from '@kairos-es/read';
+import { Effect } from 'effect';
+import { decodeReadPostgresConfig } from "./config.js";
+import { resolveCheckpointNames } from "./internal/ddl.js";
+import { advanceParams, compileStatements, keyParams } from "./internal/statements.js";
+/**
+ * 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, key) => cause => 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 = (key, error) => {
+  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 = {}) => 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 => sql.unsafe(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 => {
+    const {
+      key,
+      expected
+    } = args;
+    const [text, attempt] = expected === ORIGIN ? [statements.upsertFromOrigin, 'inserting the first checkpoint'] : [statements.advance, 'advancing the checkpoint'];
+    // `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(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 = args => sql.withTransaction(args.viewWrites.pipe(Effect.mapError(error => ({
+    _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(args.key, error)));
+  const resetCheckpoint = key =>
+  // 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(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 = {
+    // 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;
+});
+//# sourceMappingURL=projectionStore.js.map

package/dist/esm/projectionStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionStore.js","names":["SqlClient","ORIGIN","Position","CheckpointSuperseded","ProjectionStoreError","Effect","decodeReadPostgresConfig","resolveCheckpointNames","advanceParams","compileStatements","keyParams","storeError","attempt","key","cause","reason","projection","partition","message","unwrapCommitError","error","_tag","makeSqlProjectionStore","config","gen","sql","withoutTransforms","names","statements","readCheckpoint","unsafe","select","pipe","mapError","map","rows","stored","last_position","undefined","make","BigInt","guardedAdvance","args","expected","text","upsertFromOrigin","advance","flatMap","length","fail","void","commit","withTransaction","viewWrites","zipRight","resetCheckpoint","reset","asVoid","store","durability"],"sources":["../../src/projectionStore.ts"],"sourcesContent":[null],"mappings":"AA6CA,SAASA,SAAS,QAAQ,aAAa;AACvC,SAASC,MAAM,EAAEC,QAAQ,QAAQ,iBAAiB;AAClD,SAEEC,oBAAoB,EAEpBC,oBAAoB,QACf,iBAAiB;AACxB,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAASC,wBAAwB,QAAiC,aAAU;AAC5E,SAASC,sBAAsB,QAAQ,mBAAgB;AACvD,SACEC,aAAa,EACbC,iBAAiB,EACjBC,SAAS,QACJ,0BAAuB;AA0C9B;;;;;;AAMA,MAAMC,UAAU,GACdA,CAACC,OAAe,EAAEC,GAAkB,KACnCC,KAAwB,IACvB,IAAIV,oBAAoB,CAAC;EACvBW,MAAM,EAAE,GAAGH,OAAO,oBAAoBC,GAAG,CAACG,UAAU,gBAAgBH,GAAG,CAACI,SAAS,aAAaH,KAAK,CAACI,OAAO,EAAE;EAC7GJ;CACD,CAAC;AAEN;;;;;;AAMA,MAAMK,iBAAiB,GAAGA,CACxBN,GAAkB,EAClBO,KAAuB,KAC4B;EACnD,IAAIA,KAAK,CAACC,IAAI,KAAK,iBAAiB,EAAE;IACpC,OAAOD,KAAK,CAACA,KAAK;EACpB;EACA,IAAIA,KAAK,CAACC,IAAI,KAAK,UAAU,EAAE;IAC7B,OAAOV,UAAU,CAAC,mCAAmC,EAAEE,GAAG,CAAC,CAACO,KAAK,CAAC;EACpE;EACA,OAAOA,KAAK;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAME,sBAAsB,GAAGA,CACpCC,MAAA,GAA6B,EAAE,KAE/BlB,MAAM,CAACmB,GAAG,CAAC,aAAS;EAClB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMC,GAAG,GAAG,CAAC,OAAOzB,SAAS,CAACA,SAAS,EAAE0B,iBAAiB,EAAE;EAE5D;EACA;EACA;EACA;EACA,MAAMC,KAAK,GAAGpB,sBAAsB,CAACD,wBAAwB,CAACiB,MAAM,CAAC,CAAC;EACtE,MAAMK,UAAU,GAAGnB,iBAAiB,CAACkB,KAAK,CAAC;EAE3C,MAAME,cAAc,GAClBhB,GAAkB,IAElBY,GAAG,CAACK,MAAM,CAAkBF,UAAU,CAACG,MAAM,EAAErB,SAAS,CAACG,GAAG,CAAC,CAAC,CAACmB,IAAI,CACjE3B,MAAM,CAAC4B,QAAQ,CAACtB,UAAU,CAAC,wBAAwB,EAAEE,GAAG,CAAC,CAAC,EAC1DR,MAAM,CAAC6B,GAAG,CAAEC,IAAI,IAAI;IAClB,MAAMC,MAAM,GAAGD,IAAI,CAAC,CAAC,CAAC,EAAEE,aAAa;IACrC;IACA;IACA;IACA,OAAOD,MAAM,KAAKE,SAAS,GACvBrC,MAAM;IACN;IACA;IACA;IACAC,QAAQ,CAACqC,IAAI,CAACC,MAAM,CAACJ,MAAM,CAAC,CAAC;EACnC,CAAC,CAAC,CACH;EAEH;;;;;;;;;;;;EAYA,MAAMK,cAAc,GAAIC,IAIvB,IAAsE;IACrE,MAAM;MAAE7B,GAAG;MAAE8B;IAAQ,CAAE,GAAGD,IAAI;IAC9B,MAAM,CAACE,IAAI,EAAEhC,OAAO,CAAC,GACnB+B,QAAQ,KAAK1C,MAAM,GACd,CACC2B,UAAU,CAACiB,gBAAgB,EAC3B,gCAAgC,CACvB,GACV,CAACjB,UAAU,CAACkB,OAAO,EAAE,0BAA0B,CAAW;IACjE;IACA;IACA;IACA,OAAOrB,GAAG,CAACK,MAAM,CAAkBc,IAAI,EAAEpC,aAAa,CAACkC,IAAI,CAAC,CAAC,CAACV,IAAI,CAChE3B,MAAM,CAAC4B,QAAQ,CAACtB,UAAU,CAACC,OAAO,EAAEC,GAAG,CAAC,CAAC,EACzCR,MAAM,CAAC0C,OAAO,CAAEZ,IAAI;IAClB;IACA;IACA;IACAA,IAAI,CAACa,MAAM,KAAK,CAAC,GACb3C,MAAM,CAAC4C,IAAI,CAAC,IAAI9C,oBAAoB,CAAC;MAAEU,GAAG;MAAE8B;IAAQ,CAAE,CAAC,CAAC,GACxDtC,MAAM,CAAC6C,IAAI,CAChB,CACF;EACH,CAAC;EAED,MAAMC,MAAM,GAAUT,IAKrB,IAKCjB,GAAG,CACA2B,eAAe,CACdV,IAAI,CAACW,UAAU,CAACrB,IAAI,CAClB3B,MAAM,CAAC4B,QAAQ,CACZb,KAAK,KAA0B;IAC9BC,IAAI,EAAE,iBAAiB;IACvBD;GACD,CAAC,CACH;EACD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACAf,MAAM,CAACiD,QAAQ,CAACb,cAAc,CAACC,IAAI,CAAC,CAAC,CACtC,CACF,CACAV,IAAI,CAAC3B,MAAM,CAAC4B,QAAQ,CAAEb,KAAK,IAAKD,iBAAiB,CAAIuB,IAAI,CAAC7B,GAAG,EAAEO,KAAK,CAAC,CAAC,CAAC;EAE5E,MAAMmC,eAAe,GACnB1C,GAAkB;EAElB;EACA;EACA;EACAY,GAAG,CACAK,MAAM,CAASF,UAAU,CAAC4B,KAAK,EAAE9C,SAAS,CAACG,GAAG,CAAC,CAAC,CAChDmB,IAAI,CACH3B,MAAM,CAAC4B,QAAQ,CAACtB,UAAU,CAAC,0BAA0B,EAAEE,GAAG,CAAC,CAAC,EAC5DR,MAAM,CAACoD,MAAM,CACd;EAEL;EACA;EACA,MAAMC,KAAK,GAAoB;IAC7B;IACA;IACA;IACAC,UAAU,EAAE,SAAS;IACrB9B,cAAc;IACdsB,MAAM;IACNI;GACD;EACD,OAAOG,KAAK;AACd,CAAC,CAAC","ignoreList":[]}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@kairos-es/read-postgres",
+  "version": "0.0.0",
+  "description": "Postgres ProjectionStore backend and checkpoint DDL for kairos-es",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverbland/kairos-es.git",
+    "directory": "packages/read-postgres"
+  },
+  "sideEffects": [],
+  "homepage": "https://github.com/neverbland/kairos-es",
+  "peerDependencies": {
+    "@effect/sql": "^0.52.0",
+    "effect": "^3.22.0",
+    "@kairos-es/read": "^0.0.0",
+    "@kairos-es/core": "^0.0.0"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/dts/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {}
+  }
+}

package/src/config.ts

@@ -0,0 +1,83 @@
+/**
+ * Public configuration for the Postgres `ProjectionStore`.
+ *
+ * A read-side store is defined entirely by its `{ schema, tablePrefix }` naming
+ * pair: the checkpoint table name is DERIVED from it (see `internal/ddl.ts`), so
+ * one config value is one completely isolated checkpoint namespace, cohabiting
+ * per prefix exactly as the event store's objects do (ADR-0002).
+ *
+ * It is a `Schema`, not a bare interface, so malformed input fails LOUDLY at
+ * construction (`makeSqlProjectionStore`/`ensureCheckpointSchema` decode through
+ * it) rather than late and obscurely on the first commit — the same
+ * fail-at-the-boundary discipline core applies to `Tag`/`ReadLimit`. It rejects an
+ * empty or dotted `schema`/`tablePrefix` atom (a dot would break the
+ * qualified-name dot-split) and — via `oversizedIdentifier` — any pair whose
+ * derived table name would exceed Postgres's 63-byte identifier limit and be
+ * silently truncated.
+ *
+ * **WHY this config is DUPLICATED rather than imported from
+ * `@kairos-es/store-postgres`.** Importing it would mean peering that package,
+ * and peering an event-store BACKEND from the read side is precisely what the
+ * per-materialisation view-store design exists to avoid: a durable view must be
+ * free to sit over any log satisfying `DcbEventStore` — the in-memory oracle,
+ * Postgres, a future backend — so this package depends on the PORT
+ * (`@kairos-es/read`) and on `@effect/sql`, never on a sibling backend. The
+ * duplication also keeps the two guards honestly independent: each package
+ * measures only the identifiers IT materialises, so neither inherits a byte budget
+ * from names it never creates.
+ *
+ * The shape is intentionally the event store's MINUS everything read-side wiring
+ * has no business choosing: no `lockTimeout` (the checkpoint's guarded
+ * compare-and-set takes only ordinary row locks, and a blocked writer is a
+ * competing runner whose loss is a `CheckpointSuperseded` the supervisor already
+ * handles), no `pollInterval`/`catchUpPageSize` (those belong to `subscribe`, on
+ * the log side). What remains is naming, and only naming.
+ */
+import { Schema } from 'effect'
+import { oversizedIdentifier } from './internal/ddl'
+
+/**
+ * A single Postgres identifier atom: non-empty and dot-free. Dots are barred
+ * because `schema`/`tablePrefix` are composed into a qualified name that is
+ * dot-split when quoted, so an embedded dot would silently re-partition the name
+ * into the wrong schema/object.
+ */
+const IdentifierAtom = Schema.String.pipe(
+  Schema.nonEmptyString(),
+  Schema.pattern(/^[^.]+$/, {
+    identifier: 'PostgresIdentifierAtom',
+    description: 'a non-empty identifier atom containing no "."',
+  }),
+)
+
+/**
+ * Configuration for a read-side checkpoint store.
+ *
+ * - `schema` — the Postgres schema that owns the checkpoint table (default
+ *   `public`). `ensureCheckpointSchema` creates it defensively.
+ * - `tablePrefix` — the base name the checkpoint table derives from (default
+ *   `dcb_events`, giving `dcb_events_checkpoints`). Pass the SAME pair the event
+ *   store is configured with and the checkpoint table lands beside that store's
+ *   objects, one isolated store per prefix.
+ */
+export const ReadPostgresConfig = Schema.Struct({
+  // `exact: true` keeps the decoded type at `key?: T` (never `T | undefined`),
+  // matching the repo's `exactOptionalPropertyTypes` discipline — an absent key,
+  // not an explicit `undefined`.
+  schema: Schema.optionalWith(IdentifierAtom, { exact: true }),
+  tablePrefix: Schema.optionalWith(IdentifierAtom, { exact: true }),
+}).pipe(
+  // Cross-field guard: the derived table name must fit Postgres's 63-byte
+  // identifier limit. Returning the message string fails the decode with it;
+  // `undefined`/`true` passes.
+  Schema.filter((config) => oversizedIdentifier(config) ?? true),
+)
+export type ReadPostgresConfig = typeof ReadPostgresConfig.Type
+
+/**
+ * Decode an unknown value into a validated `ReadPostgresConfig`, throwing a
+ * `ParseError` on any violation. Used by `makeSqlProjectionStore` and
+ * `ensureCheckpointSchema` so a bad config fails at construction time.
+ */
+export const decodeReadPostgresConfig =
+  Schema.decodeUnknownSync(ReadPostgresConfig)

package/src/ensureCheckpointSchema.ts

@@ -0,0 +1,51 @@
+/**
+ * `ensureCheckpointSchema` — the idempotent checkpoint DDL, as a building block
+ * rather than a migrator (ADR-0007, mirroring the event store's `ensureSchema`).
+ *
+ * It is a single `Effect<void, SqlError, SqlClient>` that creates (or refreshes)
+ * the one object this package owns: the checkpoint table. It requires the GENERIC
+ * `SqlClient` tag — not a package-owned client tag — precisely so a consumer can
+ * drop it straight into THEIR OWN migrator, e.g.:
+ *
+ * ```ts
+ * Migrator.fromRecord({
+ *   '0002_kairos_checkpoints': ensureCheckpointSchema(config),
+ * })
+ * ```
+ *
+ * or simply run it once at boot, beside `ensureSchema` from the event-store
+ * backend. We ship no `FileSystem`/`Path`/`ChildProcess` dependency and no
+ * migrator: migration ORCHESTRATION belongs to the consumer, this package only
+ * provides the idempotent PAYLOAD. That is also why schema ownership never
+ * silently moves — a read model cannot conjure its own table at runtime.
+ *
+ * Idempotence: every statement is `CREATE … IF NOT EXISTS`, so re-running against
+ * an existing checkpoint table is a no-op. Names come pre-quoted from
+ * `internal/ddl.ts`; the DDL carries no bound values (pure schema).
+ *
+ * Unlike the runtime store, this path needs no `withoutTransforms()` guard: it
+ * reads no rows and passes no identifier through `sql(identifier)`, so a
+ * consumer's name transforms have nothing here to rewrite.
+ */
+import { SqlClient, type SqlError } from '@effect/sql'
+import { Effect } from 'effect'
+import { decodeReadPostgresConfig, type ReadPostgresConfig } from './config'
+import { resolveCheckpointNames, runCheckpointDdl } from './internal/ddl'
+
+/**
+ * Produce the checkpoint migration payload for `config`. Resolves the table name
+ * once and runs the ordered idempotent DDL against whatever `SqlClient` the
+ * caller's migrator (or boot code) provides.
+ */
+export const ensureCheckpointSchema = (
+  config: ReadPostgresConfig,
+): Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient> =>
+  Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient
+    // Decode through the config schema (the same guard `makeSqlProjectionStore`
+    // applies) so a malformed config fails at construction rather than
+    // mid-migration.
+    const names = resolveCheckpointNames(decodeReadPostgresConfig(config))
+    // Sequentially, in dependency order (schema → table).
+    yield* Effect.all(runCheckpointDdl(sql, names), { discard: true })
+  })

package/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * @kairos-es/read-postgres — the SQL `ProjectionStore`: a durable checkpoint
+ * table plus the guarded compare-and-set that brackets a read model's own view
+ * writes in one ordinary transaction (ADR-0007).
+ *
+ * Peers `@effect/sql` and needs only the GENERIC `SqlClient`, deliberately not
+ * `@effect/sql-pg` and deliberately no reserved connection: the event store owns
+ * the LISTEN, so the read side needs no dedicated connection of its own, and
+ * requiring the generic client is what lets `ensureCheckpointSchema` drop into a
+ * consumer's existing migrator instead of shipping a migrator here.
+ *
+ * A store is one `{ schema, tablePrefix }` naming pair (`ReadPostgresConfig`) —
+ * the same pair the event store is configured with — so the checkpoint table
+ * cohabits PER PREFIX and ADR-0002's "each prefix is a complete, isolated store"
+ * keeps holding across the read side.
+ *
+ * Wiring, end to end:
+ *
+ * ```ts
+ * import {
+ *   checkpointKey,
+ *   DurableEventLog,
+ *   forKey,
+ *   ProjectionId,
+ *   projectionLayer,
+ * } from '@kairos-es/read'
+ * import {
+ *   ensureCheckpointSchema,
+ *   makeSqlProjectionStore,
+ * } from '@kairos-es/read-postgres'
+ *
+ * const config = { schema: 'public', tablePrefix: 'dcb_events' }
+ *
+ * // 1. Register `ensureCheckpointSchema(config)` in YOUR migrator (or run it at
+ * //    boot), beside the event-store backend's own `ensureSchema(config)`.
+ * // 2. Build the store where the read model is wired, so `commit` closes over the
+ * //    acquired client and the read model itself stays free of `SqlClient`.
+ * const courseView = Layer.unwrapEffect(
+ *   Effect.gen(function* () {
+ *     const store = yield* makeSqlProjectionStore(config)
+ *     return projectionLayer({
+ *       // One store, many read models: `forKey` binds it to THIS one's checkpoint,
+ *       // and from there no operation takes a key to get wrong.
+ *       store: forKey(store, checkpointKey(ProjectionId.make('course-subs'))),
+ *       slices,
+ *       apply,
+ *     })
+ *   }),
+ * )
+ *
+ * // 3. Declare what the LOG is worth ONCE, beside the layer that chose it —
+ * //    `DcbEventStore` exposes no durability, so the application is the only
+ * //    honest source, and R2 (a durable view needs a durable log) is checked
+ * //    against this. It is a required input of every projection layer, and one
+ * //    declaration satisfies every one of them.
+ * const main = Layer.provide(
+ *   Layer.mergeAll(courseView, studentView),
+ *   Layer.mergeAll(eventStoreLayer, DurableEventLog, SerializerDefault),
+ * )
+ * ```
+ *
+ * The resulting layer requires the `SqlClient` the checkpoint (and typically the
+ * view) is written through, the `EventLogDurability` declaration above, plus
+ * whatever the read model's own `apply` needs. The checkpoint table is assumed to
+ * already exist, exactly as the event store's `layer` assumes its objects do: this
+ * package performs no DDL at runtime.
+ *
+ * `commit` is `sql.withTransaction(viewWrites *> guardedAdvance)`. The author's own
+ * `sql` statements join that transaction through the same client, and
+ * `withTransaction` is savepoint-aware, so a projection already inside a
+ * transaction composes without a second physical one. A guarded advance touching
+ * zero rows raises `CheckpointSuperseded`, whose FAILURE aborts the transaction and
+ * rolls the view writes back with it — the abort that makes the projection
+ * exactly-once. An infrastructure fault surfaces as `ProjectionStoreError` on the
+ * ERROR CHANNEL rather than as a defect, inverting the event store's rule
+ * (ADR-0002) because the read side has a supervisor above it that must distinguish
+ * retry-with-backoff from give-up.
+ *
+ * The config and the identifier guards are duplicated here rather than imported
+ * from `@kairos-es/store-postgres`, and that duplication is deliberate: peering
+ * the event-store backend would couple the read side to one specific event-store
+ * implementation, which is precisely what per-materialisation view-store selection
+ * exists to avoid. A durable view must be free to sit over any log satisfying
+ * `DcbEventStore`, so this package depends on the port (`@kairos-es/read`) and
+ * on `@effect/sql`, never on a sibling backend.
+ */
+export type { ReadPostgresConfig } from './config'
+export { ensureCheckpointSchema } from './ensureCheckpointSchema'
+export { makeSqlProjectionStore } from './projectionStore'

package/src/internal/ddl.ts

@@ -0,0 +1,246 @@
+/**
+ * Internal object-naming and DDL for the Postgres `ProjectionStore`.
+ *
+ * This module is the single source of truth for the ONE object this package owns
+ * — the checkpoint table — and for the idempotent DDL that creates it. It is
+ * factored apart from the public surface for the same reason the event store's
+ * `internal/ddl.ts` is: the name is derived ONCE, from `{ schema, tablePrefix }`,
+ * and reused by both `ensureCheckpointSchema` (the migration payload) and the
+ * runtime statements in `projectionStore.ts`, so a migration and a query can
+ * never disagree about what the table is called.
+ *
+ * The checkpoint table derives from the SAME `{ schema, tablePrefix }` pair the
+ * event store uses, so a checkpoint table cohabits PER PREFIX: two prefixes are
+ * two complete, isolated stores (ADR-0002) with two independent checkpoint
+ * namespaces, and that isolation keeps holding once the read side is added rather
+ * than being punctured by one shared checkpoint table.
+ *
+ * WHY names are never string-concatenated into a query: every identifier is
+ * pre-quoted here (`quoteQualified` for the dotted table, `quoteAtom` for a bare
+ * atom) and embedded as literal text into a `sql.unsafe(text, params)` statement,
+ * exactly as the event store's read plans are; VALUES are always bound `$n`
+ * parameters and never interpolated. A hostile or merely awkward
+ * `schema`/`tablePrefix` therefore cannot inject SQL or collide with a reserved
+ * word.
+ *
+ * The runtime deliberately does NOT route these names through `sql(identifier)`.
+ * This package takes the CONSUMER's generic `SqlClient`, which may carry a
+ * query-name transform (`@effect/sql` applies it to every `sql(identifier)`), so
+ * a camel-casing consumer would silently rewrite `last_position` to
+ * `lastPosition` and address a column that does not exist. Pre-quoted text inside
+ * `sql.unsafe` is transform-proof; the result side is handled by
+ * `withoutTransforms()` in `projectionStore.ts`.
+ */
+import type { SqlClient, Statement } from '@effect/sql'
+
+/**
+ * The one object a read-side config owns. An interface rather than a bare string
+ * so the `{ schema, tablePrefix }` atoms stay available to error messages and so
+ * a second derived object (should one ever be needed) is an additive change here
+ * rather than a new parameter at every call site.
+ */
+export interface ResolvedCheckpointNames {
+  readonly schema: string
+  readonly tablePrefix: string
+  /** `<schema>.<prefix>_checkpoints` — the scalar checkpoint table. */
+  readonly checkpointTable: string
+}
+
+/**
+ * Default schema when the config omits one. Identical to the event store's
+ * default, on purpose: the common wiring is one `{ schema, tablePrefix }` pair
+ * used for both sides, so both defaults must agree or a caller omitting the
+ * config would silently split the log and its checkpoints across two schemas.
+ */
+export const DEFAULT_SCHEMA = 'public'
+/** Default table prefix when the config omits one — again the event store's. */
+export const DEFAULT_TABLE_PREFIX = 'dcb_events'
+
+/** The suffix appended to the prefix to name the checkpoint table. */
+const CHECKPOINT_SUFFIX = '_checkpoints'
+
+/**
+ * Postgres truncates any identifier to 63 bytes (`NAMEDATALEN - 1`) with only a
+ * notice. Two configs whose derived checkpoint-table names share a 63-byte
+ * prefix would truncate onto ONE table, and `CREATE TABLE IF NOT EXISTS` would
+ * then see a name-match and SKIP creating the second: two supposedly isolated
+ * stores would silently share one checkpoint namespace, so a rebuild
+ * (`resetCheckpoint`) of one read model could delete the other's cursor. Loud
+ * rejection at the boundary beats that.
+ */
+const MAX_IDENTIFIER_BYTES = 63
+
+/** UTF-8 byte length (identifiers are bytes, not chars, to Postgres). */
+const utf8ByteLength = (value: string): number =>
+  new TextEncoder().encode(value).length
+
+/**
+ * The single-atom identifiers Postgres actually materialises for a config. A
+ * `schema.table` qualified name is TWO atoms to Postgres, so each is measured
+ * separately rather than the dotted whole.
+ *
+ * The primary key's implicit index (`<table>_pkey`) is deliberately not measured:
+ * Postgres derives and de-duplicates that name itself (appending a digit when it
+ * is taken), so it cannot collide silently the way an explicitly-named
+ * `CREATE INDEX IF NOT EXISTS` can.
+ */
+const derivedAtoms = (config: {
+  readonly schema?: string
+  readonly tablePrefix?: string
+}): ReadonlyArray<readonly [string, string]> => {
+  const schema = config.schema ?? DEFAULT_SCHEMA
+  const tablePrefix = config.tablePrefix ?? DEFAULT_TABLE_PREFIX
+  return [
+    ['schema', schema],
+    ['checkpoint table', `${tablePrefix}${CHECKPOINT_SUFFIX}`],
+  ]
+}
+
+/**
+ * The first derived identifier that exceeds 63 bytes, as a human-readable
+ * message, or `undefined` when every name fits. Shared by
+ * `resolveCheckpointNames` (which throws) and the `ReadPostgresConfig` schema
+ * filter (which fails validation), so the byte bound is enforced identically at
+ * both the name-derivation and the config-decode boundary.
+ *
+ * The bound is checked INDEPENDENTLY of the event store's: this package measures
+ * only the names IT materialises, so a prefix accepted there may be rejected here
+ * (and vice versa). Each package guards its own names, which is what lets the
+ * read side stay uncoupled from any particular event-store backend.
+ */
+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 checkpoint table`
+    }
+  }
+  return undefined
+}
+
+/**
+ * Derive the checkpoint table name from `{ schema, tablePrefix }`. The table
+ * carries its schema explicitly so `quoteQualified` dot-splits it into the two
+ * atoms Postgres expects.
+ *
+ * Throws at construction if a derived identifier would be silently truncated (see
+ * `oversizedIdentifier`) — a loud failure at the single choke point beats an
+ * invisible cross-prefix checkpoint collision later.
+ */
+export const resolveCheckpointNames = (config: {
+  readonly schema?: string
+  readonly tablePrefix?: string
+}): ResolvedCheckpointNames => {
+  const problem = oversizedIdentifier(config)
+  if (problem !== undefined) {
+    throw new Error(`resolveCheckpointNames: ${problem}`)
+  }
+  const schema = config.schema ?? DEFAULT_SCHEMA
+  const tablePrefix = config.tablePrefix ?? DEFAULT_TABLE_PREFIX
+  return {
+    schema,
+    tablePrefix,
+    checkpointTable: `${schema}.${tablePrefix}${CHECKPOINT_SUFFIX}`,
+  }
+}
+
+/**
+ * Quote a possibly-qualified identifier for embedding as literal SQL text.
+ * Splits on `.` and double-quotes each atom, mirroring what `sql(identifier)`
+ * emits, so a pre-quoted name and an `sql(identifier)` reference resolve to
+ * exactly the same object. Any embedded `"` is doubled per SQL
+ * identifier-quoting rules. (The dot-split is why `ReadPostgresConfig` bars a dot
+ * inside either atom: an embedded dot would silently re-partition the name into
+ * the wrong schema.)
+ */
+export const quoteQualified = (name: string): string =>
+  name
+    .split('.')
+    .map((atom) => `"${atom.replace(/"/g, '""')}"`)
+    .join('.')
+
+/**
+ * A quoted single-atom identifier (no dot-splitting) — used where a bare name is
+ * required, e.g. the schema in `CREATE SCHEMA` and the column names below.
+ */
+const quoteAtom = (name: string): string => `"${name.replace(/"/g, '""')}"`
+
+/**
+ * The checkpoint table's columns, PRE-QUOTED, as one shared descriptor.
+ *
+ * Shared by the DDL here and by every runtime statement in `projectionStore.ts`,
+ * so a column rename cannot half-land: the table it creates and the statements
+ * that address it read the same constant. Pre-quoted because `partition` is
+ * Postgres's own partitioning vocabulary — it parses unquoted today, but quoting
+ * removes the question, and quoting all three keeps the emitted SQL uniform.
+ *
+ * These names are FIXED and owned by this package (never config-derived), which
+ * is why they are plain constants rather than something the caller can influence.
+ */
+export const CHECKPOINT_COLUMNS = {
+  /** The read model's `ProjectionId`. */
+  projection: quoteAtom('projection'),
+  /** The read model's `PartitionId` (`default` while sharding is cut). */
+  partition: quoteAtom('partition'),
+  /**
+   * The scalar checkpoint: `bigint`, because a `Position` is 64-bit and exceeds
+   * JS `number` safety at 2^53. It is read back as a decimal STRING and
+   * reconstructed with `BigInt(...)`, never coerced through `number`.
+   */
+  lastPosition: quoteAtom('last_position'),
+} as const
+
+/**
+ * The ordered, idempotent DDL that creates (or refreshes) the checkpoint table.
+ * Each entry is a `sql.unsafe` statement string; no VALUES are involved (pure
+ * DDL), and every identifier is pre-quoted to match the runtime's resolution.
+ *
+ * Notes on the shape, both load-bearing:
+ *
+ * - `PRIMARY KEY (projection, partition)` is what makes `readCheckpoint` an index
+ *   lookup AND supplies the arbiter index the first-commit upsert's
+ *   `ON CONFLICT (projection, partition)` names. Without it that upsert would not
+ *   compile, so the key is not merely hygiene.
+ * - `last_position bigint NOT NULL` with NO row for a never-committed key: a key
+ *   reads back as `ORIGIN` by ABSENCE, so "never committed" and "reset" are one
+ *   state (`resetCheckpoint` deletes the row rather than zeroing it), exactly as
+ *   the in-memory store's map deletes its entry.
+ * - No autovacuum storage parameters, unlike the event store's tables. Those are
+ *   tuned for an append-heavy, effectively-immutable log; this table is a handful
+ *   of hot-UPDATEd rows, where the stock thresholds already fire aggressively.
+ */
+export const checkpointDdlStatements = (
+  names: ResolvedCheckpointNames,
+): ReadonlyArray<string> => {
+  const table = quoteQualified(names.checkpointTable)
+  const schema = quoteAtom(names.schema)
+  const columns = CHECKPOINT_COLUMNS
+
+  return [
+    // The schema may already exist (e.g. `public`); create it defensively so a
+    // custom schema does not require a separate provisioning step.
+    `CREATE SCHEMA IF NOT EXISTS ${schema};`,
+
+    `CREATE TABLE IF NOT EXISTS ${table} (
+       ${columns.projection} text NOT NULL,
+       ${columns.partition} text NOT NULL,
+       ${columns.lastPosition} bigint NOT NULL,
+       PRIMARY KEY (${columns.projection}, ${columns.partition})
+     );`,
+  ]
+}
+
+/**
+ * Run the ordered DDL against the generic `SqlClient`. Kept here (not in the
+ * public `ensureCheckpointSchema`) so the same builder feeds both the public
+ * migration payload and any internal test setup. Each statement is a separate
+ * `sql.unsafe` call so a driver that rejects multi-statement strings still works.
+ */
+export const runCheckpointDdl = (
+  sql: SqlClient.SqlClient,
+  names: ResolvedCheckpointNames,
+): ReadonlyArray<Statement.Statement<unknown>> =>
+  checkpointDdlStatements(names).map((statement) => sql.unsafe(statement))