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

package/README.md

@@ -5,7 +5,7 @@ guarded compare-and-set that commits a read model's view writes and its checkpoi
 advance in one transaction, and an idempotent `ensureCheckpointSchema` for the
 consumer's own migrator (ADR-0007).
 
-Peers `@effect/sql` and needs only the generic `SqlClient` — no `@effect/sql-pg`
+Needs only the generic `SqlClient` from `effect/sql` — no `@effect/sql-pg`
 and no reserved connection, because the event store owns the LISTEN.
 
 A store is defined entirely by its `{ schema, tablePrefix }` pair — the same pair
@@ -15,28 +15,33 @@ store" keeps holding across the read side.
 
 ## Installation
 
-`@kairos-es/core`, `@kairos-es/read`, `effect` and `@effect/sql` are peer
-dependencies (so the app owns the single shared Effect + `SqlClient` instance,
-per ADR-0003):
+`@kairos-es/core`, `@kairos-es/read` and `effect` are peer dependencies (so the
+app owns the single shared Effect + `SqlClient` instance, per ADR-0003); the
+generic SQL modules (`SqlClient`, `Migrator`, `SqlError`) ship inside `effect`
+itself, as `effect/sql`:
 
 ```sh
 pnpm add @kairos-es/read-postgres@alpha @kairos-es/read@alpha @kairos-es/codec@alpha \
-  @kairos-es/core@alpha @effect/sql@^0.52.0 @effect/platform@^0.97.0 @effect/experimental@^0.61.0 \
-  effect@^3.22.0
+  @kairos-es/core@alpha effect@^4.0.5
 ```
 
-Three of those are on the line because something ELSE on it requires them, not
-because this package names them. `@kairos-es/codec` is a peer of
-`@kairos-es/read`, which imports from it; `@effect/platform` and
-`@effect/experimental` are peers of `@effect/sql`. Neither requirer marks any of
-them optional — an optional peer is one the REQUIRER lists in its own
-`peerDependenciesMeta`, and neither declares that field at all — so all three
-are required. This package re-declares none of them, so the unmet-peer warning
-you get without them names the requirer rather than anything here.
+`@kairos-es/codec` is on the line because something ELSE on it requires it, not
+because this package names it: it is a peer of `@kairos-es/read`, which imports
+from it. That requirer does not mark it optional — an optional peer is one the
+REQUIRER lists in its own `peerDependenciesMeta`, and it declares no such field —
+so it is required. This package does not re-declare it, so a package manager that
+reports an unmet peer names the requirer rather than anything here.
 
 A `SqlClient` **implementation** is deliberately not peered: this package needs
-only the generic `SqlClient` tag, so the driver (`@effect/sql-pg`, or whatever
-already provides that tag in your app) stays your choice.
+only the generic `SqlClient` service, so the driver (`@effect/sql-pg`, or whatever
+already provides that service in your app) stays your choice.
+
+If that driver is `@effect/sql-pg` 4, it caches named prepared statements by
+default, its transaction's `BEGIN` and `COMMIT` included. Behind a
+transaction-mode pooler, such as the PgBouncer behind Neon's `-pooler` endpoint, a
+statement may run on a different server connection from the one that prepared
+it, so unless the pooler documents support for protocol-level prepared
+statements, build the client you hand this package with `prepare: false`.
 
 ## Schema: `ensureCheckpointSchema` as a migration
 
@@ -47,9 +52,9 @@ so re-running it is a no-op. Migration **orchestration** is yours; the package
 only provides the idempotent **payload**.
 
 ```ts
-import { Migrator } from '@effect/sql'
 import { ensureSchema } from '@kairos-es/store-postgres'
 import { ensureCheckpointSchema } from '@kairos-es/read-postgres'
+import { Migrator } from 'effect/sql'
 
 const config = { schema: 'public', tablePrefix: 'dcb_events' }
 
@@ -59,7 +64,7 @@ const migrations = Migrator.fromRecord({
 })
 ```
 
-Because it requires the **generic** `SqlClient` tag, it slots into any migrator or
+Because it requires the **generic** `SqlClient` service, it slots into any migrator or
 boot sequence that already provides one. The table it creates:
 
 ```sql
@@ -78,10 +83,10 @@ lookup, and it is the arbiter index the first commit's `ON CONFLICT` names.
 
 `makeSqlProjectionStore(config?)` is an `Effect`, not a `Layer` — the view store
 is selected **per materialisation**, so it is a value handed to a read model rather
-than a context tag one store could claim process-wide. Per materialisation and not
+than a context service one store could claim process-wide. Per materialisation and not
 merely per read model: one read model may be materialised several times at once, a
 durable store from here beside an in-memory one, which is a shape a process-wide
-tag could not express at all. It closes over the `SqlClient` it acquires, so the
+service could not express at all. It closes over the `SqlClient` it acquires, so the
 returned store's `commit` adds no `SqlClient` to the read model's own requirements.
 
 ```ts
@@ -99,7 +104,7 @@ const config = { schema: 'public', tablePrefix: 'dcb_events' }
 
 const key = checkpointKey(ProjectionId.make('course-subscriptions'))
 
-const courseView = Layer.unwrapEffect(
+const courseView = Layer.unwrap(
   Effect.gen(function* () {
     const store = yield* makeSqlProjectionStore(config)
     return projectionLayer({
@@ -169,12 +174,13 @@ as the event store's `layer` assumes `ensureSchema` has.
 
 ## The atomic bracket
 
-`commit` is `sql.withTransaction(viewWrites *> guardedAdvance)`. Your own `sql`
-statements join that transaction because `@effect/sql` carries the transaction's
-connection in the Effect **context**, not in the client value; `withTransaction`
-is savepoint-aware, so a projection already inside a transaction composes without
-a second physical one. A write through an unrelated client (or to another
-database) is **not** bracketed.
+`commit` is `sql.withTransaction(viewWrites *> guardedAdvance)`. Your view writes
+join `commit` only when issued through the **same `SqlClient`** the store was
+built from. A write through any other `SqlClient` instance — even one connected
+to the same database — or to another database is **not** bracketed, and is not
+rolled back on a lost guard. `withTransaction` is savepoint-aware, so a
+projection already inside a transaction on that client composes without a second
+physical one.
 
 The guarded advance touches zero rows when the stored position no longer equals
 `expected`, which fails `CheckpointSuperseded` — and that failure aborts the
@@ -205,8 +211,8 @@ projection", and a defect carries no such distinction.
 ## Positions are strictly-increasing, not gapless
 
 `last_position` is a `bigint` because a `Position` is 64-bit and exceeds JS
-`number` safety at 2^53; it is read back as a decimal string and reconstructed
-with `BigInt(…)`, never coerced through `number`. The stored position is the last
+`number` safety at 2^53; the driver reads it back as a `bigint`, and it is never
+coerced through `number`. The stored position is the last
 processed event's position **as is** — never `expected + 1` — so a gap is normal
 and arithmetic on a position would be wrong.
 

package/dist/cjs/config.js

@@ -29,7 +29,7 @@ var _ddl = require("./internal/ddl.js");
  * 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.
@@ -48,7 +48,7 @@ var _ddl = require("./internal/ddl.js");
  * dot-split when quoted, so an embedded dot would silently re-partition the name
  * into the wrong schema/object.
  */
-const IdentifierAtom = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_effect.Schema.nonEmptyString(), /*#__PURE__*/_effect.Schema.pattern(/^[^.]+$/, {
+const IdentifierAtom = /*#__PURE__*/_effect.Schema.String.check(/*#__PURE__*/_effect.Schema.isNonEmpty(), /*#__PURE__*/_effect.Schema.isPattern(/^[^.]+$/, {
   identifier: 'PostgresIdentifierAtom',
   description: 'a non-empty identifier atom containing no "."'
 }));
@@ -63,23 +63,19 @@ const IdentifierAtom = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_eff
  *   objects, one isolated store per prefix.
  */
 const ReadPostgresConfig = exports.ReadPostgresConfig = /*#__PURE__*/_effect.Schema.Struct({
-  // `exact: true` keeps the decoded type at `key?: T` (never `T | undefined`),
+  // `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: _effect.Schema.optionalWith(IdentifierAtom, {
-    exact: true
-  }),
-  tablePrefix: _effect.Schema.optionalWith(IdentifierAtom, {
-    exact: true
-  })
-}).pipe(/*#__PURE__*/
+  schema: _effect.Schema.optionalKey(IdentifierAtom),
+  tablePrefix: _effect.Schema.optionalKey(IdentifierAtom)
+}).check(/*#__PURE__*/
 // Cross-field guard: the derived table name must fit Postgres's 63-byte
 // identifier limit. Returning the message string fails the decode with it;
-// `undefined`/`true` passes.
-_effect.Schema.filter(config => (0, _ddl.oversizedIdentifier)(config) ?? true));
+// `undefined` passes.
+_effect.Schema.makeFilter(config => (0, _ddl.oversizedIdentifier)(config)));
 /**
  * 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.
  */
 const decodeReadPostgresConfig = exports.decodeReadPostgresConfig = /*#__PURE__*/_effect.Schema.decodeUnknownSync(ReadPostgresConfig);

package/dist/cjs/config.js.map

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

package/dist/cjs/ensureCheckpointSchema.js

@@ -4,8 +4,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.ensureCheckpointSchema = void 0;
-var _sql = require("@effect/sql");
 var _effect = require("effect");
+var _sql = require("effect/sql");
 var _config = require("./config.js");
 var _ddl = require("./internal/ddl.js");
 /**
@@ -14,7 +14,7 @@ var _ddl = require("./internal/ddl.js");
  *
  * 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

package/dist/cjs/ensureCheckpointSchema.js.map

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

package/dist/cjs/index.js.map

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

package/dist/cjs/internal/ddl.js

@@ -122,8 +122,8 @@ const CHECKPOINT_COLUMNS = exports.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/cjs/projectionStore.js

@@ -4,13 +4,58 @@ 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 _sql = require("effect/sql");
 var _config = require("./config.js");
 var _ddl = require("./internal/ddl.js");
 var _statements = require("./internal/statements.js");
+/**
+ * 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.
+ */
+
 /**
  * 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
@@ -41,20 +86,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
@@ -62,13 +110,15 @@ const unwrapCommitError = (key, error) => {
  */
 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
+  // 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* _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
@@ -131,7 +181,7 @@ const makeSqlProjectionStore = (config = {}) => _effect.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.Effect.zipRight(guardedAdvance(args)))).pipe(_effect.Effect.mapError(error => unwrapCommitError(args.key, error)));
+  _effect.Effect.andThen(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

package/dist/cjs/projectionStore.js.map

@@ -1 +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":[]}
+{"version":3,"file":"projectionStore.js","names":["_core","require","_read","_effect","_sql","_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","andThen","resetCheckpoint","reset","asVoid","store","durability","exports"],"sources":["../../src/projectionStore.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/{dts → dts-cjs}/config.d.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.
@@ -44,21 +44,17 @@ import { Schema } from 'effect';
  *   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 declare const ReadPostgresConfig: Schema.Struct<{
+    readonly schema: Schema.optionalKey<Schema.String>;
+    readonly tablePrefix: Schema.optionalKey<Schema.String>;
+}>;
 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 declare const decodeReadPostgresConfig: (u: unknown, overrideOptions?: import("effect/SchemaAST").ParseOptions) => {
+export declare const decodeReadPostgresConfig: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
     readonly schema?: string;
     readonly tablePrefix?: string;
 };

package/dist/{dts → dts-cjs}/config.d.ts.map

@@ -1 +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"}
+{"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;;;EAW9B,CAAA;AACD,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;CACS,CAAA"}

package/dist/{dts → dts-cjs}/ensureCheckpointSchema.d.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,8 @@
  * 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 { type ReadPostgresConfig } from './config.js';
 /**
  * Produce the checkpoint migration payload for `config`. Resolves the table name

package/dist/{dts → dts-cjs}/ensureCheckpointSchema.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"ensureCheckpointSchema.d.ts","sourceRoot":"","sources":["../../src/ensureCheckpointSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrD,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 → dts-cjs}/index.d.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.js';
 export { ensureCheckpointSchema } from './ensureCheckpointSchema.js';

package/dist/{dts → dts-cjs}/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;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 → dts-cjs}/internal/ddl.d.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
  * so the `{ schema, tablePrefix }` atoms stay available to error messages and so
@@ -111,8 +111,8 @@ export declare const CHECKPOINT_COLUMNS: {
     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`.
+     * JS `number` safety at 2^53. The driver reads it back as a `bigint`, and it
+     * is never coerced through `number`.
      */
     readonly lastPosition: string;
 };

package/dist/{dts → dts-cjs}/internal/ddl.d.ts.map

@@ -1 +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"}
+{"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,YAAY,CAAA;AAEtD;;;;;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"}

package/dist/dts-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/dts-cjs/projectionStore.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { type ProjectionStore } from '@kairos-es/read';
+import { Effect } from 'effect';
+import { SqlClient } from 'effect/sql';
+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 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 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 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
+ * 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-cjs/projectionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionStore.d.ts","sourceRoot":"","sources":["../../src/projectionStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAmF5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAQ,kBAAuB,KAC9B,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,CA4IxD,CAAA"}