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

package/src/clients.ts

@@ -1,69 +1,81 @@
 /**
  * The TWO store-owned Postgres clients — the "Neon trap" mitigation (ADR-0002).
  *
- * `@effect/sql-pg` exposes a single `PgClient` (and `SqlClient`) tag; a
+ * `@effect/sql-pg` exposes a single `PgClient` (and `SqlClient`) service; a
  * `PgClient.layer` claims BOTH. If we built two `PgClient.layer`s they would
- * collide on that one tag — the second would shadow the first. So instead we
- * define two DISTINCT `Context.Tag`s, each HOLDING a `PgClient` value:
+ * collide on that one key — the second would shadow the first. So instead we
+ * define two DISTINCT `Context.Service`s, each HOLDING a `PgClient` value:
  *
  * - `PgClientPooled` — the pooled client used for reads, the append function,
- *   and `notify`. Backed by a `pg.Pool`; connections are recycled per query.
+ *   and `notify`. Its statements borrow a connection from the client's pool per
+ *   query.
  * - `PgClientDirect` — a client used ONLY by `subscribe`'s `listen`. Its
- *   built-in `listen` constructs a STANDALONE `pg.Client` from the pool's
- *   `options`, inheriting the pool's host. On a Neon POOLED endpoint
- *   (`…-pooler…`) that standalone connection lands on the PgBouncer front door,
- *   which SILENTLY DROPS `LISTEN`/`NOTIFY` — the subscription would simply never
+ *   built-in `listen` RESERVES a connection from that client's own pool and
+ *   holds it for the life of the subscription, so the listening session lives
+ *   on whatever host the client was configured with. On a Neon POOLED endpoint
+ *   (`…-pooler…`) that session is a PgBouncer front-door connection, which
+ *   SILENTLY DROPS `LISTEN`/`NOTIFY` — the subscription would simply never
  *   wake. Pointing `PgClientDirect` at Neon's DIRECT (non-pooler) endpoint fixes
  *   it. `subscribe` is the ONLY method that touches `PgClientDirect`.
  *
- * For a plain (non-Neon) Postgres both tags point at the same URL; the split
- * costs nothing there. The two-tag design is what makes the Neon fix a
+ * Because each live subscription holds one of `PgClientDirect`'s pooled
+ * connections until it closes, that client's `maxConnections` is also the number
+ * of subscriptions that can be listening at once. A subscription past it waits
+ * for a connection on its wake fibre only — delivery still proceeds at the poll
+ * rate meanwhile (see `store.ts`) — so size the direct client for the expected
+ * subscriber count rather than for query throughput.
+ *
+ * For a plain (non-Neon) Postgres both services point at the same URL; the split
+ * costs nothing there. The two-service design is what makes the Neon fix a
  * deployment-time wiring choice rather than a code change.
  */
-import { Reactivity } from '@effect/experimental'
-import type { SqlError } from '@effect/sql'
 import { PgClient } from '@effect/sql-pg'
 import { Context, Layer } from 'effect'
+import { Reactivity } from 'effect/reactivity'
+import type { SqlError } from 'effect/sql'
 
 /**
- * The pooled client tag: reads, the append function, and `notify`. Holds a
+ * The pooled client service: reads, the append function, and `notify`. Holds a
  * `PgClient` value rather than being a `PgClient.layer`, so it never collides
- * with the direct client on the shared `PgClient`/`SqlClient` tag.
+ * with the direct client on the shared `PgClient`/`SqlClient` key.
  */
-export class PgClientPooled extends Context.Tag(
-  '@kairos-es/store-postgres/PgClientPooled',
-)<PgClientPooled, PgClient.PgClient>() {}
+export class PgClientPooled extends Context.Service<
+  PgClientPooled,
+  PgClient.PgClient
+>()('@kairos-es/store-postgres/PgClientPooled') {}
 
 /**
- * The direct (non-pooler) client tag: the `subscribe` listener ONLY. Point this
- * at a direct endpoint on Neon so `LISTEN`/`NOTIFY` is not dropped by the pooler.
+ * The direct (non-pooler) client service: the `subscribe` listener ONLY. Point
+ * this at a direct endpoint on Neon so `LISTEN`/`NOTIFY` is not dropped by the
+ * pooler.
  */
-export class PgClientDirect extends Context.Tag(
-  '@kairos-es/store-postgres/PgClientDirect',
-)<PgClientDirect, PgClient.PgClient>() {}
+export class PgClientDirect extends Context.Service<
+  PgClientDirect,
+  PgClient.PgClient
+>()('@kairos-es/store-postgres/PgClientDirect') {}
 
 /**
- * Build a `PgClientPooled` layer from a `PgClient` config. We construct the
- * client via `PgClient.make` (scoped) and place it in our OWN tag, then provide
- * `Reactivity.layer` (which `PgClient.make` requires) — exactly what the
+ * Build a `PgClientPooled` layer from a `PgClient` pool config. We construct the
+ * client via `PgClient.make` (scoped) and place it in our OWN service, then
+ * provide `Reactivity.layer` (which `PgClient.make` requires) — exactly what the
  * built-in `PgClient.layer` does internally, minus the collision-prone claim on
- * the shared `PgClient` tag.
+ * the shared `PgClient` key.
  */
 export const pooledLayer = (
-  config: PgClient.PgClientConfig,
+  config: PgClient.PgPoolConfig,
 ): Layer.Layer<PgClientPooled, SqlError.SqlError> =>
-  Layer.scoped(PgClientPooled, PgClient.make(config)).pipe(
+  Layer.effect(PgClientPooled, PgClient.make(config)).pipe(
     Layer.provide(Reactivity.layer),
   )
 
 /**
- * Build a `PgClientDirect` layer from a `PgClient` config. Same construction as
+ * Build a `PgClientDirect` layer from a `PgClient` pool config. Same construction as
  * `pooledLayer`; the two differ only in which endpoint the caller points them
  * at (and that only matters on Neon).
  */
 export const directLayer = (
-  config: PgClient.PgClientConfig,
+  config: PgClient.PgPoolConfig,
 ): Layer.Layer<PgClientDirect, SqlError.SqlError> =>
-  Layer.scoped(PgClientDirect, PgClient.make(config)).pipe(
+  Layer.effect(PgClientDirect, PgClient.make(config)).pipe(
     Layer.provide(Reactivity.layer),
   )

package/src/config.ts

@@ -28,9 +28,9 @@ import { oversizedIdentifier } from './internal/ddl'
  * `sql(identifier)` dot-splits, 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 "."',
   }),
@@ -63,29 +63,28 @@ const IdentifierAtom = Schema.String.pipe(
  *   fetches before looping.
  */
 export const PostgresStoreConfig = 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 }),
-  lockTimeout: Schema.optionalWith(
-    Schema.Number.pipe(Schema.nonNegative(), Schema.finite()),
-    { exact: true },
+  schema: Schema.optionalKey(IdentifierAtom),
+  tablePrefix: Schema.optionalKey(IdentifierAtom),
+  lockTimeout: Schema.optionalKey(
+    Schema.Number.check(Schema.isGreaterThanOrEqualTo(0), Schema.isFinite()),
   ),
   // The two subscribe knobs are core's field definitions, not this engine's: see
   // `subscriptionTuningFields`.
   ...subscriptionTuningFields,
-}).pipe(
+}).check(
   // Cross-field guard: the derived table/index/function/channel names must all
   // 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),
+  // the decode with it; `undefined` passes.
+  Schema.makeFilter((config) => oversizedIdentifier(config)),
 )
 export type PostgresStoreConfig = typeof PostgresStoreConfig.Type
 
 /**
  * Decode an unknown value into a validated `PostgresStoreConfig`, throwing a
- * `ParseError` on any violation. Used by `layer`/`ensureSchema` so a bad config
+ * `SchemaError` on any violation. Used by `layer`/`ensureSchema` so a bad config
  * fails at construction time.
  */
 export const decodePostgresStoreConfig =

package/src/ensureSchema.ts

@@ -4,7 +4,7 @@
  * This is deliberately NOT a migrator. It is a single `Effect<void, SqlError,
  * SqlClient>` that creates (or refreshes) every object a store owns: both
  * tables, both indexes, and both plpgsql functions. It requires the GENERIC
- * `SqlClient` tag — NOT `PgClientPooled` — precisely so a consumer can drop it
+ * `SqlClient` service — NOT `PgClientPooled` — precisely so a consumer can drop it
  * straight into THEIR OWN migrator, e.g.:
  *
  * ```ts
@@ -28,8 +28,8 @@
  * bodies carry no bound values (pure schema), and the append functions keep
  * their runtime VALUES as bound parameters, never interpolated.
  */
-import { SqlClient, type SqlError } from '@effect/sql'
 import { Effect } from 'effect'
+import { SqlClient, type SqlError } from 'effect/sql'
 import { decodePostgresStoreConfig, type PostgresStoreConfig } from './config'
 import { resolveNames, runDdl } from './internal/ddl'
 

package/src/index.ts

@@ -30,9 +30,10 @@
  * const store = layer(config).pipe(Layer.provide(clients))
  * ```
  *
- * The store `layer` performs NO DDL: it depends only on the two client tags and
- * assumes `ensureSchema` has run. `ensureSchema` requires the generic `SqlClient`
- * tag so it slots into any migrator; the runtime uses the store-owned tags.
+ * The store `layer` performs NO DDL: it depends only on the two client services
+ * and assumes `ensureSchema` has run. `ensureSchema` requires the generic
+ * `SqlClient` service so it slots into any migrator; the runtime uses the
+ * store-owned services.
  */
 export {
   directLayer,

package/src/internal/ddl.ts

@@ -25,7 +25,7 @@
  * would emit; VALUES stay bound parameters (`sql.unsafe` with `params`) and are
  * never interpolated.
  */
-import type { SqlClient, Statement } from '@effect/sql'
+import type { SqlClient, Statement } from 'effect/sql'
 import {
   allowedTypesPredicate,
   eventColumnList,

package/src/internal/matchSql.ts

@@ -88,9 +88,20 @@ export const RECORDSET_ALIAS = 'ne'
  * Typed as a `Record` over `EventColumnName` so that adding a column to
  * `EVENT_COLUMNS` without saying where its value comes from is a COMPILE error,
  * rather than a column the insert silently leaves at its default. Every column but
- * `data` passes through as the recordset already types it — `text[]` tags,
- * `timestamptz`, `jsonb` metadata — because `jsonb_to_recordset` did the casting;
- * `data` crosses as base64 TEXT and is restored to `bytea` here, its one decode.
+ * `data` and `metadata` passes through as the recordset already types it — `text[]`
+ * tags, `timestamptz` — because `jsonb_to_recordset` did the casting; `data`
+ * crosses as base64 TEXT and is restored to `bytea` here, its one decode.
+ *
+ * `metadata` is wrapped in `COALESCE(…, '{}'::jsonb)`, for a caller this package's
+ * own client never is. `ensureSchema` replaces each append function with
+ * `CREATE OR REPLACE`, which keeps its argument signature, so a client from before
+ * the column existed (`1.0.0-alpha.3` and earlier) goes on calling the current body
+ * with events JSON that has no `metadata` key. `jsonb_to_recordset` reads an absent
+ * key as `NULL`, and an insert that names the column inserts that `NULL` rather than
+ * the column's `DEFAULT`, so `NOT NULL` would refuse every such append. The
+ * `COALESCE` gives that row the empty bag the `DEFAULT` would have, which is what
+ * makes "migrate, then deploy" a safe order from those versions. An event sent WITH
+ * a bag passes through unchanged, so what is stored for it does not move.
  */
 const EVENT_COLUMN_SOURCE: Record<EventColumnName, string> = {
   type: `${RECORDSET_ALIAS}.type`,
@@ -98,7 +109,7 @@ const EVENT_COLUMN_SOURCE: Record<EventColumnName, string> = {
   tags: `${RECORDSET_ALIAS}.tags`,
   uuid: `${RECORDSET_ALIAS}.uuid`,
   occurred_at: `${RECORDSET_ALIAS}.occurred_at`,
-  metadata: `${RECORDSET_ALIAS}.metadata`,
+  metadata: `COALESCE(${RECORDSET_ALIAS}.metadata, '{}'::jsonb)`,
 }
 
 /**

package/src/internal/readPlan.ts

@@ -21,10 +21,11 @@
  * plpgsql body, where no compiler follows, and `ddl.ts` owns what that rests on
  * instead.
  */
-import type { SqlClient, SqlError } from '@effect/sql'
+
 import type { Position, ReadLimit } from '@kairos-es/core'
 import { classifyServableQuery, ORIGIN, type Query } from '@kairos-es/core'
 import type { Effect } from 'effect'
+import type { SqlClient, SqlError } from 'effect/sql'
 import { taggedReadSql, typeOnlyReadSql, wildcardReadSql } from './matchSql'
 import { type EventRow, jsonbText, toQueryItemsJson } from './transport'
 
@@ -82,7 +83,7 @@ export const compileFetchPlan = (
         bind: (after, limit) => [after, limit],
       }
     case 'typeOnly': {
-      // node-postgres binds a JS array param as a Postgres array literal, so
+      // `@effect/sql-pg` binds a JS array of strings as a `text[]` param, so
       // `type = ANY($2)` matches any of the item's types. A branded `EventType` IS
       // its string to the driver, so nothing has to be unwrapped — but the list is
       // COPIED here, at compile time. The driver serialises the array afresh on

package/src/internal/transport.ts

@@ -26,21 +26,23 @@ import type {
   Query,
   SequencedEvent,
 } from '@kairos-es/core'
-import { DateTime, Encoding } from 'effect'
+import { DateTime } from 'effect'
+import { Base64 } from 'effect/encoding'
 import type { EventColumnName } from './matchSql'
 
 /**
  * Serialise a value to a JSON STRING for transport as a `::jsonb`-cast bound
  * parameter.
  *
- * WHY not `sql.json(value)`: `@effect/sql-pg`'s `json` helper binds the RAW
- * value, and node-postgres serialises a JS *array* bound param as a Postgres
- * ARRAY literal (`{…}`), not JSON — so `sql.json([...])::jsonb` fails with a
- * `22P02` invalid-JSON error (an array literal is not valid JSON). Passing a
- * pre-stringified JSON string and casting `::jsonb` sends plain text that
- * Postgres parses as JSON, which round-trips reliably for both objects and
- * arrays. Kept as a named helper so every JSON-transport call site is consistent
- * and the reasoning lives in one place.
+ * WHY a string and not `sql.json(value)`: the read plan runs through
+ * `sql.unsafe(text, params)` with POSITIONAL parameters, and a positional
+ * parameter must be a plain scalar or a flat array of scalars — `@effect/sql-pg`
+ * cannot infer a Postgres type for an object or an array of objects, and a
+ * `sql.json` fragment is not a value that list can carry. A pre-stringified
+ * JSON string binds untyped and the `::jsonb` cast has Postgres parse it, which
+ * round-trips reliably for both objects and arrays on the positional path and
+ * the tagged-template path alike. Kept as a named helper so every
+ * JSON-transport call site is consistent and the reasoning lives in one place.
  */
 export const jsonbText = (value: unknown): string => JSON.stringify(value)
 
@@ -89,9 +91,11 @@ export type EventJson = { readonly [K in EventColumnName]: EventJsonColumns[K] }
 /** Serialise one core `DcbEvent` into its transport JSON shape. */
 export const toEventJson = (event: DcbEvent): EventJson => ({
   type: event.type,
-  // `Encoding.encodeBase64` (from `effect`) keeps this dependency-free and pure
-  // — no `Buffer`, so no `@types/node` and no browser/runtime coupling.
-  data: Encoding.encodeBase64(event.data),
+  // `Base64.encode` (from `effect/encoding`) keeps this dependency-free and pure
+  // — no `Buffer`, so no `@types/node` and no browser/runtime coupling. It emits
+  // the standard RFC 4648 alphabet with `=` padding, which is what plpgsql's
+  // `decode(…, 'base64')` reads.
+  data: Base64.encode(event.data),
   tags: [...event.tags],
   uuid: event.uuid,
   occurred_at: DateTime.formatIso(event.occurredAt),
@@ -100,9 +104,10 @@ export const toEventJson = (event: DcbEvent): EventJson => ({
 
 /**
  * The per-column TS types of a raw driver row — one entry per `EVENT_COLUMNS`
- * name. These are node-postgres's decoded JS types: `data` a `Buffer` (or null
- * for a payload-less event), `occurred_at` a JS `Date`, `tags` a `string[]`,
- * `metadata` whatever node-postgres parses a `jsonb` value into — declared
+ * name. These are the JS types `@effect/sql-pg`'s default binary codecs decode
+ * to: `data` a `Uint8Array` (or null for a payload-less event), `occurred_at` a
+ * JS `Date`, `tags` a `string[]`, `metadata` whatever the driver parses a
+ * `jsonb` value into — declared
  * `unknown`, because `jsonb` is the one column here whose SQL type does not
  * fix its JS shape, and `metadataFrom` below is where it is checked. `id`
  * (the `bigserial` position) is NOT here — it is prepended by the read projection
@@ -118,13 +123,16 @@ interface EventRowColumns {
 }
 
 /**
- * A raw row from the main table as node-postgres returns it, as `id` plus a
+ * A raw row from the main table as the driver returns it, as `id` plus a
  * mapped type over the shared `EventColumnName` descriptor. `id` is `int8`, which
- * the driver hands back as a decimal STRING (JS `number` is unsafe past 2^53).
+ * the driver's default codec hands back as a `bigint` (JS `number` is unsafe past
+ * 2^53). `rowToSequenced` still passes it through `BigInt(…)`, so a client
+ * configured with its own `int8` codec that yields the decimal string instead
+ * still mints a real `bigint` position.
  * The payload columns cannot drift from the read projection: a rename in
  * `EVENT_COLUMNS` breaks this mapped type.
  */
-export type EventRow = { readonly id: string } & {
+export type EventRow = { readonly id: bigint | string } & {
   readonly [K in EventColumnName]: EventRowColumns[K]
 }
 
@@ -152,7 +160,7 @@ const metadataFrom = (value: unknown): Metadata => {
 /**
  * Map a raw main-table row to a core `SequencedEvent`. `data` NULL → empty bytes
  * (a payload-less event round-trips to a zero-length `Uint8Array`); `occurred_at`
- * Date → `DateTime.Utc`; `id` string → branded `Position`; `metadata` through
+ * Date → `DateTime.Utc`; `id` → branded `Position`; `metadata` through
  * `metadataFrom`. The column is `NOT NULL DEFAULT '{}'`, so there is no absent
  * case to reconcile: an event appended with an empty bag reads back as `{}` on
  * this engine exactly as on the in-memory oracle.
@@ -173,7 +181,7 @@ export const rowToSequenced = (row: EventRow): SequencedEvent => ({
     data: row.data ?? new Uint8Array(0),
     tags: row.tags as unknown as DcbEvent['tags'],
     uuid: row.uuid as DcbEvent['uuid'],
-    occurredAt: DateTime.unsafeFromDate(row.occurred_at),
+    occurredAt: DateTime.fromDateUnsafe(row.occurred_at),
     metadata: metadataFrom(row.metadata),
   },
   position: BigInt(row.id) as Position,

package/src/store.ts

@@ -40,7 +40,6 @@
  * (`packages/core/src/SubscribeMachine.ts`), shared by every engine, and this
  * module only hands it a `fetch` and a `listen` built from the two clients.
  */
-import type { SqlClient, SqlError } from '@effect/sql'
 import type {
   DcbEvent,
   Position,
@@ -61,6 +60,7 @@ import {
   subscribeStream,
 } from '@kairos-es/core'
 import { type Array as Arr, Effect, Layer, type Scope, Stream } from 'effect'
+import type { SqlClient, SqlError } from 'effect/sql'
 import { PgClientDirect, PgClientPooled } from './clients'
 import { decodePostgresStoreConfig, type PostgresStoreConfig } from './config'
 import {
@@ -138,15 +138,19 @@ const make = (
      * Nor would such a parameter be load-bearing for the REPEATABLE READ
      * transaction this runs inside, which is the trap worth naming, since a
      * closed-over client LOOKS like it must escape to its own snapshot.
-     * `@effect/sql` resolves a statement's connection when the statement RUNS,
-     * from the FIBRE CONTEXT rather than from the client value: `withTransaction`
-     * acquires one connection and `Effect.locally`s it into
-     * `FiberRef.currentContext` under its `TransactionConnection` tag, and every
-     * statement a client builds resolves through a `getConnection` that reads
-     * that tag first, falling back to the pool acquirer only when it is absent
-     * (`@effect/sql@0.52` `src/internal/client.ts`). A statement therefore joins
-     * a transaction by being RUN inside it, and passing the client along the call
-     * chain neither adds to that nor is required by it. `read-postgres`'s
+     * `effect/sql` resolves a statement's connection when the statement RUNS,
+     * from the FIBRE CONTEXT: `withTransaction` acquires one connection and
+     * provides it under that client's OWN `TransactionConnection` key — one key
+     * per `SqlClient` instance — and every statement that client builds resolves
+     * through a `getConnection` that reads that key first, falling back to the
+     * pool only when it is absent (`effect/sql`'s `SqlClient.make`). So a
+     * statement joins a transaction by being RUN inside it AND by being built from
+     * the SAME client value that opened it; a statement from any other client,
+     * even one over the same database, runs on its own pooled connection outside
+     * the transaction. Here every statement in the frame — the isolation `SET`,
+     * the row fetch and this `MAX(id)` — comes from `pooled`, the client that
+     * opened it, so all three share its connection and its snapshot, and passing
+     * the client along the call chain would add nothing. `read-postgres`'s
      * `pinnedConnection` test observes the same fact from the SERVER: two
      * statements issued inside one transaction report one `pg_backend_pid()`.
      *
@@ -154,7 +158,7 @@ const make = (
      * supports: it carries no mutable state and recompiles on every execution.
      */
     const globalHead: Effect.Effect<Position, SqlError.SqlError> = pooled<{
-      readonly max: string | null
+      readonly max: bigint | string | null
     }>`
       SELECT MAX(id) AS max FROM ${pooled(names.mainTable)}
     `.pipe(
@@ -251,7 +255,7 @@ const make = (
      * One row of an append function's result: the new head (`MAX(id)`), or NULL /
      * zero rows for the empty/conflict cases the callers interpret.
      */
-    type AppendHeadRow = { readonly max: string | null }
+    type AppendHeadRow = { readonly max: bigint | string | null }
 
     /**
      * The ONE transaction frame every append rides: open a transaction, apply the
@@ -266,7 +270,7 @@ const make = (
       select: Effect.Effect<ReadonlyArray<AppendHeadRow>, SqlError.SqlError>,
     ): Effect.Effect<ReadonlyArray<AppendHeadRow>, SqlError.SqlError> =>
       pooled.withTransaction(
-        setLocalLockTimeout(pooled, lockTimeout).pipe(Effect.zipRight(select)),
+        setLocalLockTimeout(pooled, lockTimeout).pipe(Effect.andThen(select)),
       )
 
     const append = (
@@ -344,22 +348,23 @@ const make = (
     /**
      * Wire core's subscribe machine to the live clients: `fetch` is the
      * per-subscription compiled read plan run against the pooled client and mapped
-     * to `SequencedEvent`s; `listen` is the direct client's ref-counted, non-pooled
-     * LISTEN on this store's channel (the Neon-safe path — `clients.ts` owns why
-     * there are two clients at all). The plan is compiled ONCE here so the poll
-     * loop re-binds only the cursor.
+     * to `SequencedEvent`s; `listen` is the direct client's LISTEN on this store's
+     * channel (the Neon-safe path — `clients.ts` owns why there are two clients at
+     * all), which reserves one of that client's connections for as long as the
+     * subscription's wake fibre runs and drains its notification queue as a
+     * stream. The plan is compiled ONCE here so the poll loop re-binds only the
+     * cursor.
      *
      * The wake source is `NOTIFY`, and it is a LATENCY optimisation only: the
-     * machine's periodic position-based poll is what makes delivery correct, which
-     * matters more here than the general argument for it suggests. The
-     * `@effect/sql-pg` listen client SWALLOWS connection errors and does not
-     * auto-reconnect, so a dropped LISTEN typically goes quiet rather than
-     * erroring — the machine's listen-side retry then never fires, and the poll is
-     * the ONLY thing that recovers the subscription. The same silence is what a
-     * Neon pooled endpoint produces if `PgClientDirect` is misconfigured: the
-     * pooler drops `LISTEN`/`NOTIFY` without complaint and delivery degrades to
-     * poll-rate rather than failing, which is why that trap is a deployment-time
-     * wiring choice and not a runtime error.
+     * machine's periodic position-based poll is what makes delivery correct. A
+     * listening connection that DROPS fails its queue with the `SqlError` it died
+     * of, so the machine's listen-side retry re-subscribes on a fresh connection
+     * — but the notifications sent while it was down are gone, and only the poll
+     * recovers the events they announced. And some failures are silent: a Neon
+     * pooled endpoint, if `PgClientDirect` is misconfigured, accepts `LISTEN` and
+     * then never delivers a `NOTIFY`, so delivery degrades to poll-rate rather
+     * than failing, which is why that trap is a deployment-time wiring choice and
+     * not a runtime error.
      *
      * `E` is `SqlError.SqlError` — both seams fail with it, so the machine's single
      * error parameter carries it straight through to `makeContractStore`.
@@ -375,7 +380,9 @@ const make = (
             runFetch(pooled, plan, from, limit).pipe(
               Effect.map((rows) => rows.map(rowToSequenced)),
             ),
-          listen: direct.listen(names.channel),
+          listen: Stream.unwrap(
+            Effect.map(direct.listen(names.channel), Stream.fromQueue),
+          ),
           pollInterval,
           catchUpPageSize,
         },

package/dist/dts/clients.d.ts

@@ -1,34 +0,0 @@
-import type { SqlError } from '@effect/sql';
-import { PgClient } from '@effect/sql-pg';
-import { Context, Layer } from 'effect';
-declare const PgClientPooled_base: Context.TagClass<PgClientPooled, "@kairos-es/store-postgres/PgClientPooled", PgClient.PgClient>;
-/**
- * The pooled client tag: reads, the append function, and `notify`. Holds a
- * `PgClient` value rather than being a `PgClient.layer`, so it never collides
- * with the direct client on the shared `PgClient`/`SqlClient` tag.
- */
-export declare class PgClientPooled extends PgClientPooled_base {
-}
-declare const PgClientDirect_base: Context.TagClass<PgClientDirect, "@kairos-es/store-postgres/PgClientDirect", PgClient.PgClient>;
-/**
- * The direct (non-pooler) client tag: the `subscribe` listener ONLY. Point this
- * at a direct endpoint on Neon so `LISTEN`/`NOTIFY` is not dropped by the pooler.
- */
-export declare class PgClientDirect extends PgClientDirect_base {
-}
-/**
- * Build a `PgClientPooled` layer from a `PgClient` config. We construct the
- * client via `PgClient.make` (scoped) and place it in our OWN tag, then provide
- * `Reactivity.layer` (which `PgClient.make` requires) — exactly what the
- * built-in `PgClient.layer` does internally, minus the collision-prone claim on
- * the shared `PgClient` tag.
- */
-export declare const pooledLayer: (config: PgClient.PgClientConfig) => Layer.Layer<PgClientPooled, SqlError.SqlError>;
-/**
- * Build a `PgClientDirect` layer from a `PgClient` config. Same construction as
- * `pooledLayer`; the two differ only in which endpoint the caller points them
- * at (and that only matters on Neon).
- */
-export declare const directLayer: (config: PgClient.PgClientConfig) => Layer.Layer<PgClientDirect, SqlError.SqlError>;
-export {};
-//# sourceMappingURL=clients.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"clients.d.ts","sourceRoot":"","sources":["../../src/clients.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;;AAEvC;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,mBAEE;CAAG;;AAEzC;;;GAGG;AACH,qBAAa,cAAe,SAAQ,mBAEE;CAAG;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,QAAQ,CAAC,cAAc,KAC9B,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAG7C,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,QAAQ,CAAC,cAAc,KAC9B,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAG7C,CAAA"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"ensureSchema.d.ts","sourceRoot":"","sources":["../../src/ensureSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAG9E;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,mBAAmB,KAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,CAQzD,CAAA"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EACL,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,GACZ,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/internal/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,QAAQ,EAER,KAAK,EACL,cAAc,EACf,MAAM,iBAAiB,CAAA;AAExB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MAA+B,CAAA;AAE1E,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACrC;AAED,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,GAAI,OAAO,KAAK,KAAG,aAAa,CAAC,aAAa,CAItE,CAAA;AAEL;;;;;;;;GAQG;AACH,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAC5B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,eAAe,GAAG,gBAAgB,CAAC,CAAC,CAAC;CAAE,CAAA;AAEhF,mEAAmE;AACnE,eAAO,MAAM,WAAW,GAAI,OAAO,QAAQ,KAAG,SAS5C,CAAA;AAEF;;;;;;;;;GASG;AACH,UAAU,eAAe;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG;IAC/C,QAAQ,EAAE,CAAC,IAAI,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC;CACpD,CAAA;AAuBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,QAAQ,KAAG,cAU7C,CAAA"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AAkDA,OAAO,EAGL,aAAa,EAQd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAA6B,KAAK,EAAsB,MAAM,QAAQ,CAAA;AAC7E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAoU9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAChB,SAAQ,mBAAwB,KAC/B,KAAK,CAAC,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,cAAc,GAAG,cAAc,CASnE,CAAA"}