@kairos-es/read-postgres 0.0.0

package/dist/dts/internal/statements.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 { type ResolvedCheckpointNames } from './ddl.js';
+/**
+ * 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 declare const compileStatements: (names: ResolvedCheckpointNames) => CheckpointStatements;
+/** The `$1`/`$2` key parameters the `select` and the `reset` take. */
+export declare const keyParams: (key: CheckpointKey) => ReadonlyArray<unknown>;
+/**
+ * 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 declare const advanceParams: (args: {
+    readonly key: CheckpointKey;
+    readonly expected: Position;
+    readonly next: Position;
+}) => ReadonlyArray<unknown>;
+//# sourceMappingURL=statements.d.ts.map

package/dist/dts/internal/statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.d.ts","sourceRoot":"","sources":["../../../src/internal/statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,OAAO,CAAA;AAEd;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,uBAAuB,KAC7B,oBA2BF,CAAA;AAED,sEAAsE;AACtE,eAAO,MAAM,SAAS,GAAI,KAAK,aAAa,KAAG,aAAa,CAAC,OAAO,CAGnE,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM;IAClC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CACxB,KAAG,aAAa,CAAC,OAAO,CAKxB,CAAA"}

package/dist/dts/projectionStore.d.ts

@@ -0,0 +1,30 @@
+import { SqlClient } from '@effect/sql';
+import { type ProjectionStore } from '@kairos-es/read';
+import { Effect } from 'effect';
+import { type ReadPostgresConfig } from './config.js';
+/**
+ * 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 declare const makeSqlProjectionStore: (config?: ReadPostgresConfig) => Effect.Effect<ProjectionStore, never, SqlClient.SqlClient>;
+//# sourceMappingURL=projectionStore.d.ts.map

package/dist/dts/projectionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionStore.d.ts","sourceRoot":"","sources":["../../src/projectionStore.ts"],"names":[],"mappings":"AA6CA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvC,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAiF5E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAQ,kBAAuB,KAC9B,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,CA0IxD,CAAA"}

package/dist/esm/config.js

@@ -0,0 +1,79 @@
+/**
+ * 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.js";
+/**
+ * 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__*/Schema.String.pipe(/*#__PURE__*/Schema.nonEmptyString(), /*#__PURE__*/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 = /*#__PURE__*/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(/*#__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.
+Schema.filter(config => 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.
+ */
+export const decodeReadPostgresConfig = /*#__PURE__*/Schema.decodeUnknownSync(ReadPostgresConfig);
+//# sourceMappingURL=config.js.map

package/dist/esm/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":["Schema","oversizedIdentifier","IdentifierAtom","String","pipe","nonEmptyString","pattern","identifier","description","ReadPostgresConfig","Struct","schema","optionalWith","exact","tablePrefix","filter","config","decodeReadPostgresConfig","decodeUnknownSync"],"sources":["../../src/config.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAASA,MAAM,QAAQ,QAAQ;AAC/B,SAASC,mBAAmB,QAAQ,mBAAgB;AAEpD;;;;;;AAMA,MAAMC,cAAc,gBAAGF,MAAM,CAACG,MAAM,CAACC,IAAI,cACvCJ,MAAM,CAACK,cAAc,EAAE,eACvBL,MAAM,CAACM,OAAO,CAAC,SAAS,EAAE;EACxBC,UAAU,EAAE,wBAAwB;EACpCC,WAAW,EAAE;CACd,CAAC,CACH;AAED;;;;;;;;;;AAUA,OAAO,MAAMC,kBAAkB,gBAAGT,MAAM,CAACU,MAAM,CAAC;EAC9C;EACA;EACA;EACAC,MAAM,EAAEX,MAAM,CAACY,YAAY,CAACV,cAAc,EAAE;IAAEW,KAAK,EAAE;EAAI,CAAE,CAAC;EAC5DC,WAAW,EAAEd,MAAM,CAACY,YAAY,CAACV,cAAc,EAAE;IAAEW,KAAK,EAAE;EAAI,CAAE;CACjE,CAAC,CAACT,IAAI;AACL;AACA;AACA;AACAJ,MAAM,CAACe,MAAM,CAAEC,MAAM,IAAKf,mBAAmB,CAACe,MAAM,CAAC,IAAI,IAAI,CAAC,CAC/D;AAGD;;;;;AAKA,OAAO,MAAMC,wBAAwB,gBACnCjB,MAAM,CAACkB,iBAAiB,CAACT,kBAAkB,CAAC","ignoreList":[]}

package/dist/esm/ensureCheckpointSchema.js

@@ -0,0 +1,50 @@
+/**
+ * `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 } from '@effect/sql';
+import { Effect } from 'effect';
+import { decodeReadPostgresConfig } from "./config.js";
+import { resolveCheckpointNames, runCheckpointDdl } from "./internal/ddl.js";
+/**
+ * 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 => 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
+  });
+});
+//# sourceMappingURL=ensureCheckpointSchema.js.map

package/dist/esm/ensureCheckpointSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureCheckpointSchema.js","names":["SqlClient","Effect","decodeReadPostgresConfig","resolveCheckpointNames","runCheckpointDdl","ensureCheckpointSchema","config","gen","sql","names","all","discard"],"sources":["../../src/ensureCheckpointSchema.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAASA,SAAS,QAAuB,aAAa;AACtD,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAASC,wBAAwB,QAAiC,aAAU;AAC5E,SAASC,sBAAsB,EAAEC,gBAAgB,QAAQ,mBAAgB;AAEzE;;;;;AAKA,OAAO,MAAMC,sBAAsB,GACjCC,MAA0B,IAE1BL,MAAM,CAACM,GAAG,CAAC,aAAS;EAClB,MAAMC,GAAG,GAAG,OAAOR,SAAS,CAACA,SAAS;EACtC;EACA;EACA;EACA,MAAMS,KAAK,GAAGN,sBAAsB,CAACD,wBAAwB,CAACI,MAAM,CAAC,CAAC;EACtE;EACA,OAAOL,MAAM,CAACS,GAAG,CAACN,gBAAgB,CAACI,GAAG,EAAEC,KAAK,CAAC,EAAE;IAAEE,OAAO,EAAE;EAAI,CAAE,CAAC;AACpE,CAAC,CAAC","ignoreList":[]}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { ensureCheckpointSchema } from "./ensureCheckpointSchema.js";
+export { makeSqlProjectionStore } from "./projectionStore.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["ensureCheckpointSchema","makeSqlProjectionStore"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAuFA,SAASA,sBAAsB,QAAQ,6BAA0B;AACjE,SAASC,sBAAsB,QAAQ,sBAAmB","ignoreList":[]}

package/dist/esm/internal/ddl.js

@@ -0,0 +1,161 @@
+/**
+ * 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 => 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.
+ */
+export 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.
+ */
+export 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.)
+ */
+export 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.
+ */
+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.
+ */
+export const 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.
+ */
+export 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.
+ */
+export const runCheckpointDdl = (sql, names) => checkpointDdlStatements(names).map(statement => sql.unsafe(statement));
+//# sourceMappingURL=ddl.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.js","names":["DEFAULT_SCHEMA","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":[]}

package/dist/esm/internal/statements.js

@@ -0,0 +1,74 @@
+import { CHECKPOINT_COLUMNS, quoteQualified } from "./ddl.js";
+/**
+ * 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 => {
+  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 => [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 => [args.key.projection, args.key.partition, args.next, args.expected];
+//# sourceMappingURL=statements.js.map

package/dist/esm/internal/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","names":["CHECKPOINT_COLUMNS","quoteQualified","compileStatements","names","table","checkpointTable","columns","byKey","projection","partition","select","lastPosition","upsertFromOrigin","advance","reset","keyParams","key","advanceParams","args","next","expected"],"sources":["../../../src/internal/statements.ts"],"sourcesContent":[null],"mappings":"AAqBA,SACEA,kBAAkB,EAClBC,cAAc,QAET,UAAO;AA2Bd;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,OAAO,MAAMC,iBAAiB,GAC5BC,KAA8B,IACN;EACxB,MAAMC,KAAK,GAAGH,cAAc,CAACE,KAAK,CAACE,eAAe,CAAC;EACnD,MAAMC,OAAO,GAAGN,kBAAkB;EAClC,MAAMO,KAAK,GAAG,GAAGD,OAAO,CAACE,UAAU,aAAaF,OAAO,CAACG,SAAS,OAAO;EAExE,OAAO;IACLC,MAAM,EAAE,UAAUJ,OAAO,CAACK,YAAY;oBACtBP,KAAK;qBACJG,KAAK,EAAE;IAExBK,gBAAgB,EAAE,eAAeR,KAAK;2BACfE,OAAO,CAACE,UAAU;2BAClBF,OAAO,CAACG,SAAS;2BACjBH,OAAO,CAACK,YAAY;;sCAETL,OAAO,CAACE,UAAU,KAAKF,OAAO,CAACG,SAAS;uCACvCH,OAAO,CAACK,YAAY;mCACxBL,OAAO,CAACK,YAAY;mCACpBL,OAAO,CAACK,YAAY,EAAE;IAErDE,OAAO,EAAE,UAAUT,KAAK;oBACRE,OAAO,CAACK,YAAY;sBAClBJ,KAAK,QAAQD,OAAO,CAACK,YAAY;0BAC7BL,OAAO,CAACK,YAAY,EAAE;IAE5CG,KAAK,EAAE,eAAeV,KAAK,UAAUG,KAAK;GAC3C;AACH,CAAC;AAED;AACA,OAAO,MAAMQ,SAAS,GAAIC,GAAkB,IAA6B,CACvEA,GAAG,CAACR,UAAU,EACdQ,GAAG,CAACP,SAAS,CACd;AAED;;;;;;;;AAQA,OAAO,MAAMQ,aAAa,GAAIC,IAI7B,IAA6B,CAC5BA,IAAI,CAACF,GAAG,CAACR,UAAU,EACnBU,IAAI,CAACF,GAAG,CAACP,SAAS,EAClBS,IAAI,CAACC,IAAI,EACTD,IAAI,CAACE,QAAQ,CACd","ignoreList":[]}

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": []
+}