@kairos-es/read-postgres 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/esm/internal/ddl.js

@@ -113,8 +113,8 @@ export const CHECKPOINT_COLUMNS = {
   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`.
+   * JS `number` safety at 2^53. The driver reads it back as a `bigint`, and it
+   * is never coerced through `number`.
    */
   lastPosition: /*#__PURE__*/quoteAtom('last_position')
 };

package/dist/esm/projectionStore.js

@@ -1,7 +1,51 @@
-import { SqlClient } from '@effect/sql';
+/**
+ * The SQL `ProjectionStore`: a durable scalar checkpoint plus the guarded
+ * compare-and-set that brackets a read model's own view writes in ONE ordinary
+ * transaction (ADR-0007).
+ *
+ * This is the durable half of the parity pair. `@kairos-es/read`'s in-memory store
+ * is the oracle; this backend must produce identical OBSERVABLE behaviour, and the
+ * shared `projection-store-contract-tests` suite runs unchanged against both. The
+ * one place the two genuinely differ is HOW the abort is achieved:
+ *
+ * - in memory, the guard is checked FIRST and a loss means `viewWrites` never ran
+ *   (abort by omission — there is nothing to undo);
+ * - here, `viewWrites` runs first and a lost guard FAILS, so the transaction rolls
+ *   the view writes back with it (abort by undo).
+ *
+ * Both satisfy the port's promise that a lost guard leaves no observable view
+ * effect, which is why ordering inside the transaction is a performance choice
+ * rather than a correctness one: running the guard last keeps the checkpoint row
+ * lock held only for the advance instead of for the whole batch's worth of view
+ * writes.
+ *
+ * Two contract inversions worth naming, both deliberate:
+ *
+ * 1. A `SqlError` becomes a `ProjectionStoreError` on the ERROR CHANNEL — the
+ *    opposite of the event store, where an infrastructure fault is a DEFECT
+ *    (`Effect.die`, ADR-0002). The read side has a supervisor above it whose whole
+ *    job is telling "retry the subscription with backoff" from "give up and report
+ *    a stalled projection", and a defect carries no such distinction. On the event
+ *    store there is no supervisor: a caller cannot meaningfully retry a broken
+ *    connection, so dying is right there and wrong here.
+ * 2. A lost guard is a tagged failure (`CheckpointSuperseded`), never a returned
+ *    outcome value, and that failure is exactly what aborts the transaction. A
+ *    returned value would only roll back if the caller remembered to convert it
+ *    into a failure, and forgetting is silent double-application.
+ *
+ * The store closes over the `SqlClient` it acquired, so the returned
+ * `ProjectionStore.commit` adds NO `SqlClient` to the caller's `R` — a read model
+ * stays free of the view store's requirements, which is what lets one runner drive
+ * read models over different backends.
+ *
+ * What this module owns is the Effect wiring: the client, the transaction bracket,
+ * the error classification. The SQL itself and the parameter lists that feed it are
+ * `internal/statements.ts`, which owns the argument for why the two live together.
+ */
 import { ORIGIN, Position } from '@kairos-es/core';
 import { CheckpointSuperseded, ProjectionStoreError } from '@kairos-es/read';
 import { Effect } from 'effect';
+import { SqlClient } from 'effect/sql';
 import { decodeReadPostgresConfig } from "./config.js";
 import { resolveCheckpointNames } from "./internal/ddl.js";
 import { advanceParams, compileStatements, keyParams } from "./internal/statements.js";
@@ -35,20 +79,23 @@ const unwrapCommitError = (key, error) => {
  *
  * 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
+ * a context service 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
+ * `runProjections` — which is a shape a process-wide service 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.
+ * `viewWrites` join the transaction only when they are issued through the same
+ * `SqlClient` the store was built from: `effect/sql` carries the transaction's
+ * connection in the Effect CONTEXT under a key that belongs to that one client
+ * instance, so a statement run inside `commit` finds the open transaction only if
+ * its client owns that key. The store's own `withoutTransforms()` copy shares the
+ * key, which is why the guarded advance and the caller's view writes land in one
+ * transaction; a write through any OTHER `SqlClient` instance — even one over the
+ * same database — or to a different database is NOT bracketed, is not rolled back
+ * on a lost guard, 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
@@ -56,13 +103,15 @@ const unwrapCommitError = (key, error) => {
  */
 export const makeSqlProjectionStore = (config = {}) => Effect.gen(function* () {
   // `withoutTransforms()` because this package takes the CONSUMER's generic
-  // client, which may carry a result-name transform (`@effect/sql` will happily
+  // 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).
+  // transaction, because the transform-free copy carries the original client's
+  // transaction key and so finds the connection that client's transaction put
+  // in the context.
   const sql = (yield* SqlClient.SqlClient).withoutTransforms();
   // Decode INSIDE the Effect so a malformed config (empty/dotted atom, an
   // over-63-byte derived name) surfaces as a defect on the fibre building the
@@ -125,7 +174,7 @@ export const makeSqlProjectionStore = (config = {}) => Effect.gen(function* () {
   // interrupt landing mid-body rolls back exactly like a failure.
   // `args` itself, not three values pulled out of it in an order: see
   // `guardedAdvance`.
-  Effect.zipRight(guardedAdvance(args)))).pipe(Effect.mapError(error => unwrapCommitError(args.key, error)));
+  Effect.andThen(guardedAdvance(args)))).pipe(Effect.mapError(error => unwrapCommitError(args.key, error)));
   const resetCheckpoint = key =>
   // DELETE rather than `SET last_position = 0`, so "never committed" and
   // "reset" stay ONE state — which is exactly what the port promises the

package/dist/esm/projectionStore.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairos-es/read-postgres",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.5",
   "description": "Postgres ProjectionStore backend and checkpoint DDL for kairos-es",
   "license": "BSD-3-Clause",
   "repository": {
@@ -11,19 +11,23 @@
   "sideEffects": [],
   "homepage": "https://github.com/neverbland/kairos-es",
   "peerDependencies": {
-    "@effect/sql": "^0.52.0",
-    "effect": "^3.22.0",
-    "@kairos-es/core": "^1.0.0-alpha.4",
-    "@kairos-es/read": "^1.0.0-alpha.4"
+    "effect": "^4.0.5",
+    "@kairos-es/core": "^1.0.0-alpha.5",
+    "@kairos-es/read": "^1.0.0-alpha.5"
   },
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
-  "types": "./dist/dts/index.d.ts",
+  "types": "./dist/dts-cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/dts/index.d.ts",
-      "import": "./dist/esm/index.js",
-      "default": "./dist/cjs/index.js"
+      "import": {
+        "types": "./dist/dts-esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/dts-cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     },
     "./package.json": "./package.json"
   },

package/src/config.ts

@@ -21,7 +21,7 @@
  * 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
+ * (`@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.
@@ -42,9 +42,9 @@ import { oversizedIdentifier } from './internal/ddl'
  * dot-split when quoted, so an embedded dot would silently re-partition the name
  * into the wrong schema/object.
  */
-const IdentifierAtom = Schema.String.pipe(
-  Schema.nonEmptyString(),
-  Schema.pattern(/^[^.]+$/, {
+const IdentifierAtom = Schema.String.check(
+  Schema.isNonEmpty(),
+  Schema.isPattern(/^[^.]+$/, {
     identifier: 'PostgresIdentifierAtom',
     description: 'a non-empty identifier atom containing no "."',
   }),
@@ -61,22 +61,22 @@ const IdentifierAtom = Schema.String.pipe(
  *   objects, one isolated store per prefix.
  */
 export const ReadPostgresConfig = Schema.Struct({
-  // `exact: true` keeps the decoded type at `key?: T` (never `T | undefined`),
+  // `optionalKey` 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(
+  schema: Schema.optionalKey(IdentifierAtom),
+  tablePrefix: Schema.optionalKey(IdentifierAtom),
+}).check(
   // 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),
+  // `undefined` passes.
+  Schema.makeFilter((config) => oversizedIdentifier(config)),
 )
 export type ReadPostgresConfig = typeof ReadPostgresConfig.Type
 
 /**
  * Decode an unknown value into a validated `ReadPostgresConfig`, throwing a
- * `ParseError` on any violation. Used by `makeSqlProjectionStore` and
+ * `SchemaError` on any violation. Used by `makeSqlProjectionStore` and
  * `ensureCheckpointSchema` so a bad config fails at construction time.
  */
 export const decodeReadPostgresConfig =

package/src/ensureCheckpointSchema.ts

@@ -4,7 +4,7 @@
  *
  * 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
+ * `SqlClient` service — not a package-owned client service — precisely so a consumer can
  * drop it straight into THEIR OWN migrator, e.g.:
  *
  * ```ts
@@ -27,8 +27,9 @@
  * 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 { SqlClient, type SqlError } from 'effect/sql'
 import { decodeReadPostgresConfig, type ReadPostgresConfig } from './config'
 import { resolveCheckpointNames, runCheckpointDdl } from './internal/ddl'
 

package/src/index.ts

@@ -3,7 +3,7 @@
  * 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
+ * Needs only the GENERIC `SqlClient` from `effect/sql`, 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
@@ -66,8 +66,10 @@
  * 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
+ * view writes join that transaction only when issued through the SAME `SqlClient`
+ * the store was built from; a write through any other `SqlClient` instance is NOT
+ * bracketed and is not rolled back on a lost guard. `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
@@ -82,7 +84,7 @@
  * 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.
+ * on `effect/sql`, never on a sibling backend.
  */
 export type { ReadPostgresConfig } from './config'
 export { ensureCheckpointSchema } from './ensureCheckpointSchema'

package/src/internal/ddl.ts

@@ -25,13 +25,13 @@
  *
  * 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
+ * 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'
+import type { SqlClient, Statement } from 'effect/sql'
 
 /**
  * The one object a read-side config owns. An interface rather than a bare string
@@ -187,8 +187,8 @@ export const CHECKPOINT_COLUMNS = {
   partition: quoteAtom('partition'),
   /**
    * The scalar checkpoint: `bigint`, because a `Position` is 64-bit and exceeds
-   * JS `number` safety at 2^53. It is read back as a decimal STRING and
-   * reconstructed with `BigInt(...)`, never coerced through `number`.
+   * JS `number` safety at 2^53. The driver reads it back as a `bigint`, and it
+   * is never coerced through `number`.
    */
   lastPosition: quoteAtom('last_position'),
 } as const

package/src/projectionStore.ts

@@ -42,8 +42,7 @@
  * the error classification. The SQL itself and the parameter lists that feed it are
  * `internal/statements.ts`, which owns the argument for why the two live together.
  */
-import type { SqlError } from '@effect/sql'
-import { SqlClient } from '@effect/sql'
+
 import { ORIGIN, Position } from '@kairos-es/core'
 import {
   type CheckpointKey,
@@ -52,6 +51,8 @@ import {
   ProjectionStoreError,
 } from '@kairos-es/read'
 import { Effect } from 'effect'
+import type { SqlError } from 'effect/sql'
+import { SqlClient } from 'effect/sql'
 import { decodeReadPostgresConfig, type ReadPostgresConfig } from './config'
 import { resolveCheckpointNames } from './internal/ddl'
 import {
@@ -63,14 +64,16 @@ import {
 /**
  * A row of the checkpoint table's only interesting column.
  *
- * `last_position` is typed as a STRING because `bigint`/`int8` arrives from the
- * driver as a decimal string: a 64-bit position exceeds JS `number` safety at
- * 2^53, so it is reconstructed with `BigInt(...)` and never coerced through
- * `number` — the same round-trip the event store performs for its `MAX(id)` head.
- * The snake_case key is the column name verbatim; see `withoutTransforms()` below
- * for why a consumer's result-name transform cannot rename it under us.
+ * `last_position` is an `int8`, which `@effect/sql-pg` decodes straight to a
+ * `bigint`. It is typed `bigint | string` and normalised with `BigInt(...)` — the
+ * identity on a `bigint`, and exact on the decimal string an `int8` arrived as
+ * under the driver this package ran on before — and it is never coerced through
+ * `number`, since a 64-bit position exceeds JS `number` safety at 2^53. The event
+ * store's `MAX(id)` head takes the same shape. The snake_case key is the column
+ * name verbatim; see `withoutTransforms()` below for why a consumer's result-name
+ * transform cannot rename it under us.
  */
-type LastPositionRow = { readonly last_position: string }
+type LastPositionRow = { readonly last_position: bigint | string }
 
 /** A statement returning no columns (a `DELETE` with no `RETURNING`). */
 type NoRows = Record<string, never>
@@ -138,20 +141,23 @@ const unwrapCommitError = <E>(
  *
  * 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
+ * a context service 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
+ * `runProjections` — which is a shape a process-wide service 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.
+ * `viewWrites` join the transaction only when they are issued through the same
+ * `SqlClient` the store was built from: `effect/sql` carries the transaction's
+ * connection in the Effect CONTEXT under a key that belongs to that one client
+ * instance, so a statement run inside `commit` finds the open transaction only if
+ * its client owns that key. The store's own `withoutTransforms()` copy shares the
+ * key, which is why the guarded advance and the caller's view writes land in one
+ * transaction; a write through any OTHER `SqlClient` instance — even one over the
+ * same database — or to a different database is NOT bracketed, is not rolled back
+ * on a lost guard, 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
@@ -162,13 +168,15 @@ export const makeSqlProjectionStore = (
 ): Effect.Effect<ProjectionStore, never, SqlClient.SqlClient> =>
   Effect.gen(function* () {
     // `withoutTransforms()` because this package takes the CONSUMER's generic
-    // client, which may carry a result-name transform (`@effect/sql` will happily
+    // 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).
+    // transaction, because the transform-free copy carries the original client's
+    // transaction key and so finds the connection that client's transaction put
+    // in the context.
     const sql = (yield* SqlClient.SqlClient).withoutTransforms()
 
     // Decode INSIDE the Effect so a malformed config (empty/dotted atom, an
@@ -267,7 +275,7 @@ export const makeSqlProjectionStore = (
             // interrupt landing mid-body rolls back exactly like a failure.
             // `args` itself, not three values pulled out of it in an order: see
             // `guardedAdvance`.
-            Effect.zipRight(guardedAdvance(args)),
+            Effect.andThen(guardedAdvance(args)),
           ),
         )
         .pipe(Effect.mapError((error) => unwrapCommitError<E>(args.key, error)))

package/dist/dts/projectionStore.d.ts

@@ -1,30 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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"}