@kairos-es/read-postgres 0.0.0

package/dist/cjs/internal/statements.js

@@ -0,0 +1,83 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.keyParams = exports.compileStatements = exports.advanceParams = void 0;
+var _ddl = require("./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.
+ */
+const compileStatements = names => {
+  const table = (0, _ddl.quoteQualified)(names.checkpointTable);
+  const columns = _ddl.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. */
+exports.compileStatements = compileStatements;
+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.
+ */
+exports.keyParams = keyParams;
+const advanceParams = args => [args.key.projection, args.key.partition, args.next, args.expected];
+exports.advanceParams = advanceParams;
+//# sourceMappingURL=statements.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","names":["_ddl","require","compileStatements","names","table","quoteQualified","checkpointTable","columns","CHECKPOINT_COLUMNS","byKey","projection","partition","select","lastPosition","upsertFromOrigin","advance","reset","exports","keyParams","key","advanceParams","args","next","expected"],"sources":["../../../src/internal/statements.ts"],"sourcesContent":[null],"mappings":";;;;;;AAqBA,IAAAA,IAAA,GAAAC,OAAA;AA+BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCO,MAAMC,iBAAiB,GAC5BC,KAA8B,IACN;EACxB,MAAMC,KAAK,GAAG,IAAAC,mBAAc,EAACF,KAAK,CAACG,eAAe,CAAC;EACnD,MAAMC,OAAO,GAAGC,uBAAkB;EAClC,MAAMC,KAAK,GAAG,GAAGF,OAAO,CAACG,UAAU,aAAaH,OAAO,CAACI,SAAS,OAAO;EAExE,OAAO;IACLC,MAAM,EAAE,UAAUL,OAAO,CAACM,YAAY;oBACtBT,KAAK;qBACJK,KAAK,EAAE;IAExBK,gBAAgB,EAAE,eAAeV,KAAK;2BACfG,OAAO,CAACG,UAAU;2BAClBH,OAAO,CAACI,SAAS;2BACjBJ,OAAO,CAACM,YAAY;;sCAETN,OAAO,CAACG,UAAU,KAAKH,OAAO,CAACI,SAAS;uCACvCJ,OAAO,CAACM,YAAY;mCACxBN,OAAO,CAACM,YAAY;mCACpBN,OAAO,CAACM,YAAY,EAAE;IAErDE,OAAO,EAAE,UAAUX,KAAK;oBACRG,OAAO,CAACM,YAAY;sBAClBJ,KAAK,QAAQF,OAAO,CAACM,YAAY;0BAC7BN,OAAO,CAACM,YAAY,EAAE;IAE5CG,KAAK,EAAE,eAAeZ,KAAK,UAAUK,KAAK;GAC3C;AACH,CAAC;AAED;AAAAQ,OAAA,CAAAf,iBAAA,GAAAA,iBAAA;AACO,MAAMgB,SAAS,GAAIC,GAAkB,IAA6B,CACvEA,GAAG,CAACT,UAAU,EACdS,GAAG,CAACR,SAAS,CACd;AAED;;;;;;;;AAAAM,OAAA,CAAAC,SAAA,GAAAA,SAAA;AAQO,MAAME,aAAa,GAAIC,IAI7B,IAA6B,CAC5BA,IAAI,CAACF,GAAG,CAACT,UAAU,EACnBW,IAAI,CAACF,GAAG,CAACR,SAAS,EAClBU,IAAI,CAACC,IAAI,EACTD,IAAI,CAACE,QAAQ,CACd;AAAAN,OAAA,CAAAG,aAAA,GAAAA,aAAA","ignoreList":[]}

package/dist/cjs/projectionStore.js

@@ -0,0 +1,154 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.makeSqlProjectionStore = void 0;
+var _sql = require("@effect/sql");
+var _core = require("@kairos-es/core");
+var _read = require("@kairos-es/read");
+var _effect = require("effect");
+var _config = require("./config.js");
+var _ddl = require("./internal/ddl.js");
+var _statements = require("./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 _read.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.
+ */
+const makeSqlProjectionStore = (config = {}) => _effect.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* _sql.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 = (0, _ddl.resolveCheckpointNames)((0, _config.decodeReadPostgresConfig)(config));
+  const statements = (0, _statements.compileStatements)(names);
+  const readCheckpoint = key => sql.unsafe(statements.select, (0, _statements.keyParams)(key)).pipe(_effect.Effect.mapError(storeError('reading the checkpoint', key)), _effect.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 ? _core.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.
+    _core.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 === _core.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, (0, _statements.advanceParams)(args)).pipe(_effect.Effect.mapError(storeError(attempt, key)), _effect.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.Effect.fail(new _read.CheckpointSuperseded({
+      key,
+      expected
+    })) : _effect.Effect.void));
+  };
+  const commit = args => sql.withTransaction(args.viewWrites.pipe(_effect.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.Effect.zipRight(guardedAdvance(args)))).pipe(_effect.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, (0, _statements.keyParams)(key)).pipe(_effect.Effect.mapError(storeError('resetting the checkpoint', key)), _effect.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;
+});
+exports.makeSqlProjectionStore = makeSqlProjectionStore;
+//# sourceMappingURL=projectionStore.js.map

package/dist/cjs/projectionStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionStore.js","names":["_sql","require","_core","_read","_effect","_config","_ddl","_statements","storeError","attempt","key","cause","ProjectionStoreError","reason","projection","partition","message","unwrapCommitError","error","_tag","makeSqlProjectionStore","config","Effect","gen","sql","SqlClient","withoutTransforms","names","resolveCheckpointNames","decodeReadPostgresConfig","statements","compileStatements","readCheckpoint","unsafe","select","keyParams","pipe","mapError","map","rows","stored","last_position","undefined","ORIGIN","Position","make","BigInt","guardedAdvance","args","expected","text","upsertFromOrigin","advance","advanceParams","flatMap","length","fail","CheckpointSuperseded","void","commit","withTransaction","viewWrites","zipRight","resetCheckpoint","reset","asVoid","store","durability","exports"],"sources":["../../src/projectionStore.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/dts/config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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';
+/**
+ * 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 declare const ReadPostgresConfig: Schema.filter<Schema.Struct<{
+    schema: Schema.optionalWith<Schema.filter<Schema.filter<typeof Schema.String>>, {
+        exact: true;
+    }>;
+    tablePrefix: Schema.optionalWith<Schema.filter<Schema.filter<typeof Schema.String>>, {
+        exact: 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 declare const decodeReadPostgresConfig: (u: unknown, overrideOptions?: import("effect/SchemaAST").ParseOptions) => {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+};
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAiB/B;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;;;;;;;GAW9B,CAAA;AACD,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;CACS,CAAA"}

package/dist/dts/ensureCheckpointSchema.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `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 { type ReadPostgresConfig } from './config.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 declare const ensureCheckpointSchema: (config: ReadPostgresConfig) => Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient>;
+//# sourceMappingURL=ensureCheckpointSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureCheckpointSchema.d.ts","sourceRoot":"","sources":["../../src/ensureCheckpointSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAG5E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,kBAAkB,KACzB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,CASzD,CAAA"}

package/dist/dts/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @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.js';
+export { ensureCheckpointSchema } from './ensureCheckpointSchema.js';
+export { makeSqlProjectionStore } from './projectionStore.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA"}

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

@@ -0,0 +1,146 @@
+/**
+ * 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 declare const DEFAULT_SCHEMA = "public";
+/** Default table prefix when the config omits one — again the event store's. */
+export declare const DEFAULT_TABLE_PREFIX = "dcb_events";
+/**
+ * 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 declare const oversizedIdentifier: (config: {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+}) => string | 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 declare const resolveCheckpointNames: (config: {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+}) => ResolvedCheckpointNames;
+/**
+ * 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 declare const quoteQualified: (name: string) => string;
+/**
+ * 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 declare const CHECKPOINT_COLUMNS: {
+    /** The read model's `ProjectionId`. */
+    readonly projection: string;
+    /** The read model's `PartitionId` (`default` while sharding is cut). */
+    readonly partition: string;
+    /**
+     * 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`.
+     */
+    readonly lastPosition: string;
+};
+/**
+ * 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 declare const checkpointDdlStatements: (names: ResolvedCheckpointNames) => ReadonlyArray<string>;
+/**
+ * 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 declare const runCheckpointDdl: (sql: SqlClient.SqlClient, names: ResolvedCheckpointNames) => ReadonlyArray<Statement.Statement<unknown>>;
+//# sourceMappingURL=ddl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../../src/internal/ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA;AACtC,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,eAAe,CAAA;AA0ChD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,KAAG,MAAM,GAAG,SAQZ,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,KAAG,uBAYH,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,MAIhC,CAAA;AAQd;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;IAC7B,uCAAuC;;IAEvC,wEAAwE;;IAExE;;;;OAIG;;CAEK,CAAA;AAEV;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,uBAAuB,GAClC,OAAO,uBAAuB,KAC7B,aAAa,CAAC,MAAM,CAiBtB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,SAAS,CAAC,SAAS,EACxB,OAAO,uBAAuB,KAC7B,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CAC6B,CAAA"}