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

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

@@ -8,7 +8,7 @@
  * where transport code lives, and the two per-column type maps (`EventJson`,
  * `EventRow`) sit next to each other rather than in two files.
  *
- * The 5-column event contract stays single-sourced on `EventColumnName`
+ * The event column contract stays single-sourced on `EventColumnName`
  * (`internal/matchSql.ts`), the one column-NAME descriptor: both type maps here
  * are mapped types over it, so a column rename in `EVENT_COLUMNS` is a COMPILE
  * error in this module, never a silent transport drift the lax read boundary
@@ -19,20 +19,21 @@
  * (`toEventJson`) serialises `data` as base64 text and domain time as an ISO
  * string, both restored in SQL.
  */
-import type { DcbEvent, Query, SequencedEvent } from '@kairos-es/core';
+import type { DcbEvent, Metadata, Query, SequencedEvent } from '@kairos-es/core';
 import type { EventColumnName } from './matchSql.js';
 /**
  * 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 declare const jsonbText: (value: unknown) => string;
 /** The JSON shape of one query item: types OR-filter, tags AND-superset. */
@@ -45,9 +46,11 @@ export declare const toQueryItemsJson: (query: Query) => ReadonlyArray<QueryItem
 /**
  * The per-column TS types of the transport JSON shape — one entry per
  * `EVENT_COLUMNS` name. `data` is base64 TEXT and `occurred_at` an ISO string
- * (both restored in SQL: `decode(…, 'base64')` / `timestamptz`); the rest map
- * straight across. Kept as a plain map so `EventJson` below is a mapped type over
- * the ONE column descriptor rather than a hand-restated column list.
+ * (both restored in SQL: `decode(…, 'base64')` / `timestamptz`); `metadata`
+ * travels as a nested JSON object, which `jsonb_to_recordset` hands to the
+ * insert as `jsonb` untouched; the rest map straight across. Kept as a plain
+ * map so `EventJson` below is a mapped type over the ONE column descriptor
+ * rather than a hand-restated column list.
  */
 interface EventJsonColumns {
     readonly type: string;
@@ -55,6 +58,7 @@ interface EventJsonColumns {
     readonly tags: ReadonlyArray<string>;
     readonly uuid: string;
     readonly occurred_at: string;
+    readonly metadata: Metadata;
 }
 /**
  * The JSON shape of one event as sent to the append functions, as a mapped type
@@ -72,8 +76,12 @@ export type EventJson = {
 export declare 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[]`. `id`
+ * 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
  * and absent from the events recordset, so it sits outside the shared descriptor.
  */
@@ -83,23 +91,30 @@ interface EventRowColumns {
     readonly tags: ReadonlyArray<string>;
     readonly uuid: string;
     readonly occurred_at: Date;
+    readonly metadata: unknown;
 }
 /**
- * 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;
+    readonly id: bigint | string;
 } & {
     readonly [K in EventColumnName]: EventRowColumns[K];
 };
 /**
  * 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`.
+ * 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.
  *
  * The branded scalars (`type`, `tags`, `uuid`, `position`) are minted by trusted
  * `as`-cast, NOT by re-running `EventType.make` / `Tag.make` etc. This is

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

@@ -0,0 +1 @@
+{"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;AAGxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;GAaG;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,SAW5C,CAAA;AAEF;;;;;;;;;;GAUG;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;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG;IACxD,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-cjs/package.json

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

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

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

package/dist/dts-esm/clients.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The TWO store-owned Postgres clients — the "Neon trap" mitigation (ADR-0002).
+ *
+ * `@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 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`. 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` 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`.
+ *
+ * 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 { PgClient } from '@effect/sql-pg';
+import { Context, Layer } from 'effect';
+import type { SqlError } from 'effect/sql';
+declare const PgClientPooled_base: Context.ServiceClass<PgClientPooled, "@kairos-es/store-postgres/PgClientPooled", PgClient.PgClient>;
+/**
+ * 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` key.
+ */
+export declare class PgClientPooled extends PgClientPooled_base {
+}
+declare const PgClientDirect_base: Context.ServiceClass<PgClientDirect, "@kairos-es/store-postgres/PgClientDirect", PgClient.PgClient>;
+/**
+ * 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 declare class PgClientDirect extends PgClientDirect_base {
+}
+/**
+ * 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` key.
+ */
+export declare const pooledLayer: (config: PgClient.PgPoolConfig) => Layer.Layer<PgClientPooled, SqlError.SqlError>;
+/**
+ * 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 declare const directLayer: (config: PgClient.PgPoolConfig) => Layer.Layer<PgClientDirect, SqlError.SqlError>;
+export {};
+//# sourceMappingURL=clients.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"clients.d.ts","sourceRoot":"","sources":["../../src/clients.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACzC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAEvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;;AAE1C;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,mBAGW;CAAG;;AAElD;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,mBAGW;CAAG;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,QAAQ,CAAC,YAAY,KAC5B,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAG7C,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,QAAQ,CAAC,YAAY,KAC5B,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,QAAQ,CAAC,QAAQ,CAG7C,CAAA"}

package/dist/dts-esm/config.d.ts

@@ -0,0 +1,48 @@
+import { Schema } from 'effect';
+/**
+ * Configuration for a Postgres store instance.
+ *
+ * - `schema` — the Postgres schema that owns the store's objects (default
+ *   `public`). `ensureSchema` creates it defensively.
+ * - `tablePrefix` — the base name for the store's tables/indexes/functions
+ *   (default `dcb_events`). Two stores with different prefixes (or schemas)
+ *   cohabit one database without interference.
+ * - `lockTimeout` — seconds passed to `set_config('lock_timeout', …, true)`
+ *   inside every append, bounding how long a blocked writer waits on the
+ *   exclusive lock. `0` (the default) means wait indefinitely — parity with the
+ *   in-memory semaphore's unbounded wait, so the shared contract suite behaves
+ *   identically across engines. A non-zero timeout that fires (`55P03`) is a
+ *   Postgres-only outcome surfaced OFF the shared `append` contract (a defect),
+ *   never as `AppendConditionFailed` — the in-memory oracle cannot produce it.
+ * - `pollInterval` — MILLISECONDS a live `subscribe` waits for a NOTIFY wake
+ *   before re-reading from its cursor anyway, defaulting to core's
+ *   `DEFAULT_POLL_INTERVAL_MILLIS`. Because this engine HAS a wake source, the
+ *   value bounds worst-case live-tail latency rather than being it — only a
+ *   subscriber no NOTIFY reaches waits the whole interval; lower it (e.g. in tests)
+ *   to poll faster. See `packages/core/src/SubscribeMachine.ts` for what the poll
+ *   guarantees and what a wake source is for.
+ * - `catchUpPageSize` — the `subscribe` reconcile page size, defaulting to core's
+ *   `DEFAULT_CATCH_UP_PAGE_SIZE`: how many events a single catch-up/live read
+ *   fetches before looping.
+ */
+export declare const PostgresStoreConfig: Schema.Struct<{
+    readonly pollInterval: Schema.optionalKey<Schema.Number>;
+    readonly catchUpPageSize: Schema.optionalKey<Schema.Int>;
+    readonly schema: Schema.optionalKey<Schema.String>;
+    readonly tablePrefix: Schema.optionalKey<Schema.String>;
+    readonly lockTimeout: Schema.optionalKey<Schema.Number>;
+}>;
+export type PostgresStoreConfig = typeof PostgresStoreConfig.Type;
+/**
+ * Decode an unknown value into a validated `PostgresStoreConfig`, throwing a
+ * `SchemaError` on any violation. Used by `layer`/`ensureSchema` so a bad config
+ * fails at construction time.
+ */
+export declare const decodePostgresStoreConfig: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+    readonly lockTimeout?: number;
+    readonly pollInterval?: number;
+    readonly catchUpPageSize?: number;
+};
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAiB/B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,mBAAmB;;;;;;EAiB/B,CAAA;AACD,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;AAEjE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;CACS,CAAA"}

package/dist/dts-esm/ensureSchema.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `ensureSchema` — the idempotent DDL migration building block (ADR-0002).
+ *
+ * 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` service — NOT `PgClientPooled` — precisely so a consumer can drop it
+ * straight into THEIR OWN migrator, e.g.:
+ *
+ * ```ts
+ * Migrator.fromRecord({
+ *   '0001_kairos_store_dcb_events': ensureSchema(config),
+ * })
+ * ```
+ *
+ * or simply run it once at boot. We ship no `FileSystem`/`Path`/`ChildProcess`
+ * dependency and no `PgMigrator`; migration ORCHESTRATION belongs to the
+ * consumer, this package only provides the idempotent PAYLOAD.
+ *
+ * Idempotence: every statement is `CREATE … IF NOT EXISTS` or `CREATE OR REPLACE
+ * FUNCTION`, so re-running it is safe. It is NOT a no-op across versions: a
+ * re-run replaces the append functions with this version's, and does NOT alter
+ * an existing table, so a column a newer version adds must be added by hand
+ * before the re-run (the release notes give the statement). A store whose
+ * table gained a column but whose functions were never replaced keeps writing
+ * through the old ones, which do not know the column. Names come from
+ * `sql(identifier)` (via the pre-quoted builder in `internal/ddl.ts`); the DDL
+ * bodies carry no bound values (pure schema), and the append functions keep
+ * their runtime VALUES as bound parameters, never interpolated.
+ */
+import { Effect } from 'effect';
+import { SqlClient, type SqlError } from 'effect/sql';
+import { type PostgresStoreConfig } from './config.js';
+/**
+ * Produce the migration payload for `config`. Resolves the object names once and
+ * runs the ordered idempotent DDL against whatever `SqlClient` the caller's
+ * migrator (or boot code) provides.
+ */
+export declare const ensureSchema: (config: PostgresStoreConfig) => Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient>;
+//# sourceMappingURL=ensureSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureSchema.d.ts","sourceRoot":"","sources":["../../src/ensureSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrD,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-esm/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @kairos-es/store-postgres — the Postgres `DcbEventStore` backend.
+ *
+ * A single store is one `{ schema, tablePrefix }` naming pair (`PostgresStoreConfig`);
+ * every object it owns is derived from that pair, so multiple isolated stores
+ * cohabit one database. The engine is the two-table B-tree + exclusive-lock
+ * conditional append of ADR-0002, with JSON transport and a two-client Layer to
+ * survive Neon's pooled LISTEN/NOTIFY drop.
+ *
+ * Wiring, end to end:
+ *
+ * ```ts
+ * import { PgClient } from '@effect/sql-pg'
+ * import {
+ *   ensureSchema,
+ *   layer,
+ *   pooledLayer,
+ *   directLayer,
+ * } from '@kairos-es/store-postgres'
+ *
+ * const config = { schema: 'public', tablePrefix: 'dcb_events' }
+ *
+ * // 1. Register `ensureSchema(config)` in YOUR migrator (or run it at boot).
+ * // 2. Provide the two clients (same URL off Neon; a direct endpoint for
+ * //    `directLayer` on Neon), then the store layer over them.
+ * const clients = Layer.merge(
+ *   pooledLayer({ url: Redacted.make(poolUrl) }),
+ *   directLayer({ url: Redacted.make(directUrl) }),
+ * )
+ * const store = layer(config).pipe(Layer.provide(clients))
+ * ```
+ *
+ * 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, PgClientDirect, PgClientPooled, pooledLayer, } from './clients.js';
+export type { PostgresStoreConfig } from './config.js';
+export { ensureSchema } from './ensureSchema.js';
+export { layer } from './store.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;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-esm/internal/ddl.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Internal DDL and object-naming for the Postgres `DcbEventStore` backend.
+ *
+ * This module is the single source of truth for every object name a store owns
+ * and for the plpgsql function bodies. It is deliberately factored apart from
+ * the public engine so that:
+ *
+ * 1. names are derived ONCE, from `{ schema, tablePrefix }`, and reused by both
+ *    `ensureSchema` (DDL) and the runtime (`append`/`read`/`subscribe`), so the
+ *    migration and the queries can never disagree about what a table is called;
+ * 2. the append-function body is assembled from COMPOSABLE parts — in
+ *    particular the `LOCK TABLE … IN EXCLUSIVE MODE` clause is an omittable
+ *    fragment — so a test can `CREATE OR REPLACE` a deliberately-LOCKLESS twin of
+ *    the append function to prove the shared contract suite actually detects a
+ *    non-serialising store. The production Layer never exposes a lockless option;
+ *    the seam lives here, in an internal module, reachable only from the test
+ *    graph.
+ *
+ * WHY names are never string-concatenated: every identifier flows through
+ * `sql(identifier)`, which quotes and dot-splits safely, so a hostile or merely
+ * awkward `schema`/`tablePrefix` cannot inject SQL or collide with a reserved
+ * word. The plpgsql *bodies*, which must embed the resolved names as literal
+ * text inside a `CREATE FUNCTION … $$ … $$` string, use the SAME quoting via a
+ * small `quoteQualified` helper so the body text matches what `sql(identifier)`
+ * would emit; VALUES stay bound parameters (`sql.unsafe` with `params`) and are
+ * never interpolated.
+ */
+import type { SqlClient, Statement } from 'effect/sql';
+/**
+ * A store is one physical `{ schema, tablePrefix }` pair. Every object it owns
+ * (both tables, both indexes, both functions, and the NOTIFY channel) is derived
+ * from this pair, so one prefix is one completely isolated store: its own
+ * bigserial sequence, its own exclusive-lock scope, its own wake channel.
+ */
+export interface ResolvedNames {
+    readonly schema: string;
+    readonly tablePrefix: string;
+    /** `<schema>.<prefix>` — the main event table. */
+    readonly mainTable: string;
+    /** `<schema>.<prefix>_tags` — the junction tag table. */
+    readonly tagTable: string;
+    /** `<prefix>_idx_id_type` — the covering unique index on the main table. */
+    readonly mainIndex: string;
+    /** `<prefix>_idx_tag_main_id` — the composite B-tree on the tag table. */
+    readonly tagIndex: string;
+    /** `<schema>.<prefix>_append` — the conditional (lock → check → insert → notify) function. */
+    readonly appendFn: string;
+    /**
+     * `<schema>.<prefix>_append_unconditional` — the check-free insert twin. It takes
+     * the SAME exclusive lock as the conditional one, which is what discharges the
+     * subscribe machine's ascending-commit-order precondition on this engine;
+     * `unconditionalAppendBody` owns why a lock-free twin would not.
+     */
+    readonly appendUnconditionalFn: string;
+    /**
+     * The `LISTEN`/`NOTIFY` channel: the fully-qualified events-table name with
+     * dots replaced by `_`. A channel is a single unqualified identifier, so the
+     * schema is folded into the name to keep two stores in different schemas but
+     * with the same prefix from sharing a channel.
+     */
+    readonly channel: string;
+}
+/** Default schema when the config omits one. */
+export declare const DEFAULT_SCHEMA = "public";
+/** Default table prefix when the config omits one. */
+export declare const DEFAULT_TABLE_PREFIX = "dcb_events";
+/**
+ * The first derived identifier that exceeds 63 bytes, as a human-readable
+ * message, or `undefined` when every name fits. Shared by `resolveNames` (which
+ * throws) and the `PostgresStoreConfig` schema filter (which fails validation),
+ * so the byte bound is enforced identically at both the name-derivation and the
+ * config-decode boundary.
+ */
+export declare const oversizedIdentifier: (config: {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+}) => string | undefined;
+/**
+ * Derive every owned object name from `{ schema, tablePrefix }`. The index and
+ * function *base* names are unqualified prefixes (`<prefix>_…`) because an index
+ * name is scoped to its table's schema and a function is created in `<schema>`;
+ * the tables and functions carry the schema explicitly so `sql(identifier)`
+ * dot-splits them.
+ *
+ * Throws at construction if any derived identifier would be silently truncated
+ * (see `oversizedIdentifier` / `MAX_IDENTIFIER_BYTES`) — a loud failure at the
+ * single choke point beats an invisible index-skip or channel collision later.
+ */
+export declare const resolveNames: (config: {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+}) => ResolvedNames;
+/**
+ * Quote a possibly-qualified identifier for embedding inside a plpgsql body as
+ * literal text. Splits on `.` and double-quotes each atom, mirroring what
+ * `sql(identifier)` emits, so the body's table references and the runtime's
+ * `sql(identifier)` references resolve to exactly the same object. Any embedded
+ * `"` is doubled per SQL identifier-quoting rules.
+ */
+export declare const quoteQualified: (name: string) => string;
+/**
+ * The named body-fragment seams, replacing positional boolean flags — the old
+ * `unconditionalAppendBody(names, true, false)` was boolean-blind. Both knobs
+ * default to the production configuration (locked + notifying); a test twin
+ * overrides one field BY NAME. This is the union of both knobs; each body `Pick`s
+ * only the ones it actually varies — the conditional body always notifies, so it
+ * never took `notify`.
+ *
+ * - `lock` — include the `LOCK TABLE … IN EXCLUSIVE MODE` clause (default true).
+ *   BOTH twins vary it: the test-only lockless twins pass `false` to prove the
+ *   lock is load-bearing (the conditional path's lockless meta-test and the
+ *   unconditional commit-order repro).
+ * - `notify` — include the `pg_notify` wake (default true). ONLY the unconditional
+ *   twin varies it: the poll-only delivery test passes `false` to prove the
+ *   periodic poll, not NOTIFY, is the delivery guarantee.
+ */
+export interface AppendBodyOptions {
+    readonly lock?: boolean;
+    readonly notify?: boolean;
+}
+/**
+ * Which append function to (re)create, plus the body-fragment seams. `kind`
+ * selects the conditional (guarded) or unconditional (check-free) twin — fixing
+ * the function NAME and SIGNATURE — and the seams default to the production
+ * configuration.
+ *
+ * A DISCRIMINATED union, not `extends AppendBodyOptions`, so the seams a `kind`
+ * cannot vary are un-expressible: the conditional twin exposes only `lock` (it
+ * always notifies), so `{ kind: 'conditional', notify: false }` is a compile error
+ * rather than a silently-ignored dead option.
+ */
+export type AppendFunctionOptions = ({
+    readonly kind: 'conditional';
+} & Pick<AppendBodyOptions, 'lock'>) | ({
+    readonly kind: 'unconditional';
+} & AppendBodyOptions);
+/**
+ * Build ONE complete `CREATE OR REPLACE FUNCTION … RETURNS SETOF bigint LANGUAGE
+ * plpgsql AS $kairos$…$kairos$` statement for an append function. This is the
+ * single source of the wrapper — its qualified name, argument SIGNATURE, and
+ * `$kairos$`-delimited body — consumed by `ddlStatements` (production, both twins)
+ * AND by the test installers that `CREATE OR REPLACE` a lockless / notify-
+ * suppressed twin over their own prefix.
+ *
+ * WHY one builder: `ddlStatements` plus three test twins previously hand-restated
+ * this wrapper, several with string-INTERPOLATED identifiers this module's own
+ * doctrine forbids (`"${schema}"."${prefix}_append"` rather than
+ * `quoteQualified(names.appendFn)`). A drift in the SIGNATURE across those copies
+ * is a silent footgun: `CREATE OR REPLACE` with a changed argument list creates a
+ * new OVERLOAD instead of replacing, leaving the original production function live
+ * under test. Single-sourcing name + signature makes a twin unable to diverge —
+ * a twin `CREATE OR REPLACE`s exactly the function `ddlStatements` created.
+ */
+export declare const appendFunctionStatement: (names: ResolvedNames, options: AppendFunctionOptions) => string;
+/**
+ * The full ordered list of idempotent DDL statements that create/refresh a
+ * store's objects. Each entry is a `sql.unsafe` statement string; VALUES are not
+ * involved (pure DDL), and every identifier is pre-quoted via `quoteQualified`
+ * to match the runtime's `sql(identifier)` resolution.
+ *
+ * Ordering matters: tables before their indexes and before the tag table's FK,
+ * functions last (they reference the tables). Everything is `IF NOT EXISTS` /
+ * `CREATE OR REPLACE`, so re-running is a no-op — the migration payload is safe
+ * to register in any migrator or to run directly.
+ */
+export declare const ddlStatements: (names: ResolvedNames) => ReadonlyArray<string>;
+/**
+ * Run the ordered DDL against the generic `SqlClient`. Kept here (not in the
+ * public `ensureSchema`) so the same builder feeds both the public migration
+ * payload and any internal test setup. Each statement is a separate `sql.unsafe`
+ * call so a driver that rejects multi-statement strings still works.
+ */
+export declare const runDdl: (sql: SqlClient.SqlClient, names: ResolvedNames) => ReadonlyArray<Statement.Statement<unknown>>;
+//# sourceMappingURL=ddl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../../src/internal/ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAWtD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,gDAAgD;AAChD,eAAO,MAAM,cAAc,WAAW,CAAA;AACtC,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,eAAe,CAAA;AAuChD;;;;;;GAMG;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;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,KAAG,aAkBH,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,MAIhC,CAAA;AA2Cd;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AAoOD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAC7B,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GACpE,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAAG,iBAAiB,CAAC,CAAA;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB,GAClC,OAAO,aAAa,EACpB,SAAS,qBAAqB,KAC7B,MAqBF,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,aAAa,KAAG,aAAa,CAAC,MAAM,CAmExE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GACjB,KAAK,SAAS,CAAC,SAAS,EACxB,OAAO,aAAa,KACnB,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CACmB,CAAA"}