@kairos-es/read-postgres 0.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Neverbland
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,238 @@
+# @kairos-es/read-postgres
+
+The Postgres `ProjectionStore` for kairos-es: a durable checkpoint table plus the
+guarded compare-and-set that commits a read model's view writes and its checkpoint
+advance in one transaction, and an idempotent `ensureCheckpointSchema` for the
+consumer's own migrator (ADR-0007).
+
+Peers `@effect/sql` and needs only the generic `SqlClient` — no `@effect/sql-pg`
+and no reserved connection, because the event store owns the LISTEN.
+
+A store is defined entirely by its `{ schema, tablePrefix }` pair — the same pair
+the event-store backend is configured with — so the checkpoint table cohabits per
+prefix and [ADR-0002](../../docs/adr)'s "each prefix is a complete, isolated
+store" keeps holding across the read side.
+
+## Installation
+
+`@kairos-es/core`, `@kairos-es/read`, `effect` and `@effect/sql` are peer
+dependencies (so the app owns the single shared Effect + `SqlClient` instance,
+per ADR-0003):
+
+```sh
+pnpm add @kairos-es/read-postgres@alpha @kairos-es/read@alpha @kairos-es/codec@alpha \
+  @kairos-es/core@alpha @effect/sql @effect/platform @effect/experimental effect
+```
+
+Three of those are on the line because something ELSE on it requires them, not
+because this package names them. `@kairos-es/codec` is a peer of
+`@kairos-es/read`, which imports from it; `@effect/platform` and
+`@effect/experimental` are peers of `@effect/sql`. Neither requirer marks any of
+them optional — an optional peer is one the REQUIRER lists in its own
+`peerDependenciesMeta`, and neither declares that field at all — so all three
+are required. This package re-declares none of them, so the unmet-peer warning
+you get without them names the requirer rather than anything here.
+
+A `SqlClient` **implementation** is deliberately not peered: this package needs
+only the generic `SqlClient` tag, so the driver (`@effect/sql-pg`, or whatever
+already provides that tag in your app) stays your choice.
+
+## Schema: `ensureCheckpointSchema` as a migration
+
+The package ships **no migrator**. `ensureCheckpointSchema(config)` is a single
+idempotent `Effect<void, SqlError, SqlClient>` that creates (or refreshes) the one
+object it owns: the checkpoint table. Every statement is `CREATE … IF NOT EXISTS`,
+so re-running it is a no-op. Migration **orchestration** is yours; the package
+only provides the idempotent **payload**.
+
+```ts
+import { Migrator } from '@effect/sql'
+import { ensureSchema } from '@kairos-es/store-postgres'
+import { ensureCheckpointSchema } from '@kairos-es/read-postgres'
+
+const config = { schema: 'public', tablePrefix: 'dcb_events' }
+
+const migrations = Migrator.fromRecord({
+  '0001_kairos_store_dcb_events': ensureSchema(config),
+  '0002_kairos_checkpoints': ensureCheckpointSchema(config),
+})
+```
+
+Because it requires the **generic** `SqlClient` tag, it slots into any migrator or
+boot sequence that already provides one. The table it creates:
+
+```sql
+CREATE TABLE IF NOT EXISTS <schema>.<prefix>_checkpoints (
+  "projection"    text NOT NULL,
+  "partition"     text NOT NULL,
+  "last_position" bigint NOT NULL,
+  PRIMARY KEY ("projection", "partition")
+);
+```
+
+The primary key is load-bearing twice over: it makes a checkpoint read an index
+lookup, and it is the arbiter index the first commit's `ON CONFLICT` names.
+
+## Wiring a read model
+
+`makeSqlProjectionStore(config?)` is an `Effect`, not a `Layer` — the view store
+is selected **per materialisation**, so it is a value handed to a read model rather
+than a context tag one store could claim process-wide. Per materialisation and not
+merely per read model: one read model may be materialised several times at once, a
+durable store from here beside an in-memory one, which is a shape a process-wide
+tag could not express at all. It closes over the `SqlClient` it acquires, so the
+returned store's `commit` adds no `SqlClient` to the read model's own requirements.
+
+```ts
+import {
+  checkpointKey,
+  DurableEventLog,
+  forKey,
+  ProjectionId,
+  projectionLayer,
+} from '@kairos-es/read'
+import { makeSqlProjectionStore } from '@kairos-es/read-postgres'
+import { Effect, Layer } from 'effect'
+
+const config = { schema: 'public', tablePrefix: 'dcb_events' }
+
+const key = checkpointKey(ProjectionId.make('course-subscriptions'))
+
+const courseView = Layer.unwrapEffect(
+  Effect.gen(function* () {
+    const store = yield* makeSqlProjectionStore(config)
+    return projectionLayer({
+      // The store is multi-key — one `SqlClient` serves every read model — so it
+      // is bound to this read model's checkpoint once, here. From then on `commit`
+      // takes no key at all.
+      store: forKey(store, key),
+      slices,
+      apply,
+    })
+  }),
+)
+
+// What the LOG is worth is declared ONCE, beside the layer that chose it — not on
+// each read model, because it is a fact about the log and N read models over one
+// log could otherwise hold N copies that disagree. `DcbEventStore` exposes no
+// durability, so the application is the only honest source, and this is R2's other
+// input: a durable view store (which this package's is) needs a durable log.
+const main = Layer.provide(
+  Layer.mergeAll(courseView, studentView),
+  Layer.mergeAll(eventStoreLayer, DurableEventLog, SerializerDefault),
+)
+```
+
+### A worked SQL `apply`
+
+`slices` and `apply` above are the consumer's. The one the library cannot write
+for you is `apply`, so there is a worked one — and it lives with the read model it
+materialises rather than here, because that is where a consumer reads worked code:
+[`examples/course-subscriptions/src/courseRosterSql.ts`](../../examples/course-subscriptions/src/courseRosterSql.ts)
+materialises that example's course roster into two real tables — its own
+idempotent DDL, its identifier quoting, a typed dispatch onto the domain's event
+defs, and ADR-0007's apply-throughput escape hatch in its hybrid shape — one fold
+over the batch, so the capacity row's whole batch coalesces into one upsert while
+each seat is its own row and its own insert, then those writes issued in order
+inside the one `commit`, sequentially because one transaction pins one connection
+and parallel writes are not on offer there. It needs nothing from this package: a
+read model owns its own view schema, and the only object this package owns is the
+checkpoint table.
+
+It imports the example's slices, `CheckpointKey` derivation and derived figures
+**verbatim**, which is what makes it a second **materialisation of one read model**
+rather than a second read model — the pattern `@kairos-es/read`'s `runProjections`
+names and wires, holding one `slices` value and one `ProjectionId` across N
+materialisations, each with its own store, `apply`, checkpoint and runner. The
+example runs the durable materialisation beside an in-memory one under a single
+such call in
+[`src/courseRosterMaterialisations.ts`](../../examples/course-subscriptions/src/courseRosterMaterialisations.ts).
+What lives in this package is the COMPARISON that needs a container:
+[`test/courseRosterGraduation.test.ts`](./test/courseRosterGraduation.test.ts)
+runs the same slice record into a `Ref` and into Postgres side by side over one
+durable log and asserts the two composed queries, the two checkpoint keys and the
+two rosters agree. The example's own base roster stays database-free, which is what
+keeps it runnable with no container anywhere.
+
+The one thing to copy carefully: **the store and your `apply` must share one
+`SqlClient`**. See "The atomic bracket" below.
+
+`EventLogDurability` is a **required** input of every projection layer, with no
+default, and one declaration satisfies all of them. Declaring `EphemeralEventLog`
+over this store is what R2 rejects at construction: the checkpoint table would
+survive a restart the log did not, and the view would sit frozen and permanently
+stale without ever erroring.
+
+The store performs **no DDL**: `ensureCheckpointSchema` must have run first, just
+as the event store's `layer` assumes `ensureSchema` has.
+
+## The atomic bracket
+
+`commit` is `sql.withTransaction(viewWrites *> guardedAdvance)`. Your own `sql`
+statements join that transaction because `@effect/sql` carries the transaction's
+connection in the Effect **context**, not in the client value; `withTransaction`
+is savepoint-aware, so a projection already inside a transaction composes without
+a second physical one. A write through an unrelated client (or to another
+database) is **not** bracketed.
+
+The guarded advance touches zero rows when the stored position no longer equals
+`expected`, which fails `CheckpointSuperseded` — and that failure aborts the
+transaction, rolling the view writes back with it. That abort is the exactly-once
+mechanism, so the shared `@kairos-es/projection-store-contract-tests` suite proves
+it against a known-broken store rather than assuming it.
+
+The advance has **two** SQL shapes, and neither can serve both cases:
+
+- from `ORIGIN`, an `INSERT … ON CONFLICT (projection, partition) DO UPDATE …
+  WHERE last_position = 0`, because a never-committed key has no row at all and a
+  plain `UPDATE` would report a lost guard forever;
+- from a non-origin position, a plain `UPDATE … WHERE last_position = expected`,
+  because an upsert would **insert** an absent row — silently undoing a
+  `resetCheckpoint` and skipping the whole backlog it existed to replay.
+
+Both `RETURNING` a column, so a lost guard is a **row count**, never a caught SQL
+error — the same doctrine as the event store's zero-row append conflict.
+
+## Infrastructure faults are channel values here
+
+A `SqlError` surfaces as `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 job is to
+tell "retry the subscription with backoff" from "give up and report a stalled
+projection", and a defect carries no such distinction.
+
+## Positions are strictly-increasing, not gapless
+
+`last_position` is a `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`. The stored position is the last
+processed event's position **as is** — never `expected + 1` — so a gap is normal
+and arithmetic on a position would be wrong.
+
+A key that has never been committed has **no row** and reads back as `ORIGIN`.
+`resetCheckpoint` deletes the row rather than zeroing it, so "never committed" and
+"reset" stay one state.
+
+## Configuration
+
+```ts
+interface ReadPostgresConfig {
+  readonly schema?: string // default 'public'
+  readonly tablePrefix?: string // default 'dcb_events'
+}
+```
+
+Validated at construction, so a malformed config fails loudly: an empty or dotted
+atom is rejected (a dot would re-partition the qualified name into the wrong
+schema), as is any pair whose derived table name would exceed Postgres's 63-byte
+identifier limit and be silently truncated — two prefixes sharing one checkpoint
+table is the failure that guard prevents.
+
+The config is deliberately **duplicated** from `@kairos-es/store-postgres` rather
+than imported: peering an event-store backend would couple the read side to one
+specific log implementation, and a durable view must be free to sit over any store
+satisfying `DcbEventStore`.
+
+## Licence
+
+BSD 3-Clause. See [`LICENSE`](./LICENSE). Copyright (c) 2026 Neverbland.

package/dist/cjs/config.js

@@ -0,0 +1,86 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.decodeReadPostgresConfig = exports.ReadPostgresConfig = void 0;
+var _effect = require("effect");
+var _ddl = require("./internal/ddl.js");
+/**
+ * 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.
+ */
+
+/**
+ * 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 = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_effect.Schema.nonEmptyString(), /*#__PURE__*/_effect.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.
+ */
+const ReadPostgresConfig = exports.ReadPostgresConfig = /*#__PURE__*/_effect.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: _effect.Schema.optionalWith(IdentifierAtom, {
+    exact: true
+  }),
+  tablePrefix: _effect.Schema.optionalWith(IdentifierAtom, {
+    exact: true
+  })
+}).pipe(/*#__PURE__*/
+// 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.
+_effect.Schema.filter(config => (0, _ddl.oversizedIdentifier)(config) ?? true));
+/**
+ * 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.
+ */
+const decodeReadPostgresConfig = exports.decodeReadPostgresConfig = /*#__PURE__*/_effect.Schema.decodeUnknownSync(ReadPostgresConfig);
+//# sourceMappingURL=config.js.map

package/dist/cjs/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":["_effect","require","_ddl","IdentifierAtom","Schema","String","pipe","nonEmptyString","pattern","identifier","description","ReadPostgresConfig","exports","Struct","schema","optionalWith","exact","tablePrefix","filter","config","oversizedIdentifier","decodeReadPostgresConfig","decodeUnknownSync"],"sources":["../../src/config.ts"],"sourcesContent":[null],"mappings":";;;;;;AAmCA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,IAAA,GAAAD,OAAA;AApCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA;;;;;;AAMA,MAAME,cAAc,gBAAGC,cAAM,CAACC,MAAM,CAACC,IAAI,cACvCF,cAAM,CAACG,cAAc,EAAE,eACvBH,cAAM,CAACI,OAAO,CAAC,SAAS,EAAE;EACxBC,UAAU,EAAE,wBAAwB;EACpCC,WAAW,EAAE;CACd,CAAC,CACH;AAED;;;;;;;;;;AAUO,MAAMC,kBAAkB,GAAAC,OAAA,CAAAD,kBAAA,gBAAGP,cAAM,CAACS,MAAM,CAAC;EAC9C;EACA;EACA;EACAC,MAAM,EAAEV,cAAM,CAACW,YAAY,CAACZ,cAAc,EAAE;IAAEa,KAAK,EAAE;EAAI,CAAE,CAAC;EAC5DC,WAAW,EAAEb,cAAM,CAACW,YAAY,CAACZ,cAAc,EAAE;IAAEa,KAAK,EAAE;EAAI,CAAE;CACjE,CAAC,CAACV,IAAI;AACL;AACA;AACA;AACAF,cAAM,CAACc,MAAM,CAAEC,MAAM,IAAK,IAAAC,wBAAmB,EAACD,MAAM,CAAC,IAAI,IAAI,CAAC,CAC/D;AAGD;;;;;AAKO,MAAME,wBAAwB,GAAAT,OAAA,CAAAS,wBAAA,gBACnCjB,cAAM,CAACkB,iBAAiB,CAACX,kBAAkB,CAAC","ignoreList":[]}

package/dist/cjs/ensureCheckpointSchema.js

@@ -0,0 +1,58 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ensureCheckpointSchema = void 0;
+var _sql = require("@effect/sql");
+var _effect = require("effect");
+var _config = require("./config.js");
+var _ddl = require("./internal/ddl.js");
+/**
+ * `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.
+ */
+
+/**
+ * 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.
+ */
+const ensureCheckpointSchema = config => _effect.Effect.gen(function* () {
+  const sql = yield* _sql.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 = (0, _ddl.resolveCheckpointNames)((0, _config.decodeReadPostgresConfig)(config));
+  // Sequentially, in dependency order (schema → table).
+  yield* _effect.Effect.all((0, _ddl.runCheckpointDdl)(sql, names), {
+    discard: true
+  });
+});
+exports.ensureCheckpointSchema = ensureCheckpointSchema;
+//# sourceMappingURL=ensureCheckpointSchema.js.map

package/dist/cjs/ensureCheckpointSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureCheckpointSchema.js","names":["_sql","require","_effect","_config","_ddl","ensureCheckpointSchema","config","Effect","gen","sql","SqlClient","names","resolveCheckpointNames","decodeReadPostgresConfig","all","runCheckpointDdl","discard","exports"],"sources":["../../src/ensureCheckpointSchema.ts"],"sourcesContent":[null],"mappings":";;;;;;AA6BA,IAAAA,IAAA,GAAAC,OAAA;AACA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AACA,IAAAG,IAAA,GAAAH,OAAA;AAhCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA;;;;;AAKO,MAAMI,sBAAsB,GACjCC,MAA0B,IAE1BC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,GAAG,GAAG,OAAOC,cAAS,CAACA,SAAS;EACtC;EACA;EACA;EACA,MAAMC,KAAK,GAAG,IAAAC,2BAAsB,EAAC,IAAAC,gCAAwB,EAACP,MAAM,CAAC,CAAC;EACtE;EACA,OAAOC,cAAM,CAACO,GAAG,CAAC,IAAAC,qBAAgB,EAACN,GAAG,EAAEE,KAAK,CAAC,EAAE;IAAEK,OAAO,EAAE;EAAI,CAAE,CAAC;AACpE,CAAC,CAAC;AAAAC,OAAA,CAAAZ,sBAAA,GAAAA,sBAAA","ignoreList":[]}

package/dist/cjs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ensureCheckpointSchema", {
+  enumerable: true,
+  get: function () {
+    return _ensureCheckpointSchema.ensureCheckpointSchema;
+  }
+});
+Object.defineProperty(exports, "makeSqlProjectionStore", {
+  enumerable: true,
+  get: function () {
+    return _projectionStore.makeSqlProjectionStore;
+  }
+});
+var _ensureCheckpointSchema = require("./ensureCheckpointSchema.js");
+var _projectionStore = require("./projectionStore.js");
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_ensureCheckpointSchema","require","_projectionStore"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":";;;;;;;;;;;;;;;;;AAuFA,IAAAA,uBAAA,GAAAC,OAAA;AACA,IAAAC,gBAAA,GAAAD,OAAA","ignoreList":[]}

package/dist/cjs/internal/ddl.js

@@ -0,0 +1,172 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runCheckpointDdl = exports.resolveCheckpointNames = exports.quoteQualified = exports.oversizedIdentifier = exports.checkpointDdlStatements = exports.DEFAULT_TABLE_PREFIX = exports.DEFAULT_SCHEMA = exports.CHECKPOINT_COLUMNS = void 0;
+/**
+ * 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.
+ */
+const DEFAULT_SCHEMA = exports.DEFAULT_SCHEMA = 'public';
+/** Default table prefix when the config omits one — again the event store's. */
+const DEFAULT_TABLE_PREFIX = exports.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 => 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 => {
+  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.
+ */
+const oversizedIdentifier = config => {
+  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.
+ */
+exports.oversizedIdentifier = oversizedIdentifier;
+const resolveCheckpointNames = config => {
+  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.)
+ */
+exports.resolveCheckpointNames = resolveCheckpointNames;
+const quoteQualified = name => 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.
+ */
+exports.quoteQualified = quoteQualified;
+const quoteAtom = name => `"${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.
+ */
+const CHECKPOINT_COLUMNS = exports.CHECKPOINT_COLUMNS = {
+  /** The read model's `ProjectionId`. */
+  projection: /*#__PURE__*/quoteAtom('projection'),
+  /** The read model's `PartitionId` (`default` while sharding is cut). */
+  partition: /*#__PURE__*/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: /*#__PURE__*/quoteAtom('last_position')
+};
+/**
+ * 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.
+ */
+const checkpointDdlStatements = names => {
+  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.
+ */
+exports.checkpointDdlStatements = checkpointDdlStatements;
+const runCheckpointDdl = (sql, names) => checkpointDdlStatements(names).map(statement => sql.unsafe(statement));
+exports.runCheckpointDdl = runCheckpointDdl;
+//# sourceMappingURL=ddl.js.map

package/dist/cjs/internal/ddl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.js","names":["DEFAULT_SCHEMA","exports","DEFAULT_TABLE_PREFIX","CHECKPOINT_SUFFIX","MAX_IDENTIFIER_BYTES","utf8ByteLength","value","TextEncoder","encode","length","derivedAtoms","config","schema","tablePrefix","oversizedIdentifier","label","atom","bytes","undefined","resolveCheckpointNames","problem","Error","checkpointTable","quoteQualified","name","split","map","replace","join","quoteAtom","CHECKPOINT_COLUMNS","projection","partition","lastPosition","checkpointDdlStatements","names","table","columns","runCheckpointDdl","sql","statement","unsafe"],"sources":["../../../src/internal/ddl.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}