@kairos-es/store-postgres 0.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Neverbland
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,167 @@
+# @kairos-es/store-postgres
+
+The Postgres `DcbEventStore` backend for kairos-es: the two-table B-tree +
+exclusive-lock conditional append of [ADR-0002](../../docs/adr), behind the same
+`DcbEventStore` contract as the in-memory store. It passes the shared
+`@kairos-es/store-contract-tests` suite unchanged, with the in-memory store as
+the parity oracle.
+
+A store is defined entirely by its `{ schema, tablePrefix }` pair. Every object
+it owns (both tables, both indexes, both plpgsql functions, and the NOTIFY
+channel) is derived from that pair, so multiple isolated stores cohabit one
+database without interference.
+
+## Installation
+
+`@kairos-es/core`, `effect`, and the Effect SQL/Postgres stack are peer
+dependencies (so the app owns the single shared Effect + `SqlClient` instance,
+per ADR-0003):
+
+```sh
+pnpm add @kairos-es/store-postgres@alpha @kairos-es/core@alpha \
+  @effect/sql @effect/sql-pg @effect/platform @effect/experimental effect
+```
+
+`@effect/platform` and `@effect/experimental` are pulled in because
+`@effect/sql-pg` requires them (the pooled client's `Reactivity` service lives in
+`@effect/experimental`); declaring them here keeps the peer graph resolvable for
+consumers.
+
+## Schema: `ensureSchema` as a migration
+
+The package ships **no migrator**. `ensureSchema(config)` is a single idempotent
+`Effect<void, SqlError, SqlClient>` that creates (or refreshes) every object the
+store owns. Every statement is `CREATE … IF NOT EXISTS` or `CREATE OR REPLACE
+FUNCTION`, so re-running it is a no-op. Migration **orchestration** is yours; the
+package only provides the idempotent **payload**.
+
+Drop it straight into an `@effect/sql` migrator as a one-liner:
+
+```ts
+import { Migrator } from '@effect/sql'
+import { ensureSchema } from '@kairos-es/store-postgres'
+
+const config = { schema: 'public', tablePrefix: 'dcb_events' }
+
+const migrations = Migrator.fromRecord({
+  '0001_kairos_store_dcb_events': ensureSchema(config),
+})
+```
+
+Because `ensureSchema` requires the **generic** `SqlClient` tag (not the
+store-owned client tags), it slots into any migrator or boot sequence that
+already provides a `SqlClient`.
+
+Or run it directly once at boot, over whatever `SqlClient` you have wired:
+
+```ts
+import { SqlClient } from '@effect/sql'
+import { PgClient } from '@effect/sql-pg'
+import { ensureSchema } from '@kairos-es/store-postgres'
+import { Effect, Layer, Redacted } from 'effect'
+
+const config = { schema: 'public', tablePrefix: 'dcb_events' }
+
+const program = ensureSchema(config)
+
+const SqlLive = PgClient.layer({ url: Redacted.make(process.env.DATABASE_URL!) })
+
+await Effect.runPromise(program.pipe(Effect.provide(SqlLive)))
+```
+
+`ensureSchema` must have run before the store `layer` is used; the `layer` itself
+performs no DDL and depends only on the two client tags.
+
+## Two-endpoint wiring (Neon)
+
+`@effect/sql-pg` exposes a single `PgClient`/`SqlClient` tag, so this package
+defines **two distinct tags**, each holding a `PgClient` value:
+
+- `PgClientPooled` — reads, the append function, and `NOTIFY`. Point it at your
+  pooled endpoint.
+- `PgClientDirect` — used **only** by `subscribe`'s `LISTEN`. Point it at a
+  **direct** (non-pooler) endpoint.
+
+Why the split matters on Neon: the built-in `listen` constructs a standalone
+connection inheriting the pool's host. A Neon **pooled** endpoint
+(`…-pooler…`) lands that connection on the PgBouncer front door, which
+**silently drops `LISTEN`/`NOTIFY`** — the subscription would simply never wake.
+Pointing `PgClientDirect` at Neon's direct endpoint fixes it. `subscribe` is the
+only method that touches `PgClientDirect`.
+
+```ts
+import {
+  directLayer,
+  layer,
+  pooledLayer,
+} from '@kairos-es/store-postgres'
+import { Layer, Redacted } from 'effect'
+
+const config = { schema: 'public', tablePrefix: 'dcb_events' }
+
+const clients = Layer.merge(
+  // The -pooler endpoint: pooled reads/append/notify.
+  pooledLayer({ url: Redacted.make(process.env.NEON_POOLED_URL!) }),
+  // The direct (non-pooler) endpoint: LISTEN/NOTIFY survives here.
+  directLayer({ url: Redacted.make(process.env.NEON_DIRECT_URL!) }),
+)
+
+const store = layer(config).pipe(Layer.provide(clients))
+```
+
+On a plain (non-Neon) Postgres, point both tags at the **same** URL — the split
+costs nothing there:
+
+```ts
+const url = Redacted.make(process.env.DATABASE_URL!)
+const clients = Layer.merge(pooledLayer({ url }), directLayer({ url }))
+```
+
+## Positions are strictly-increasing, not gapless
+
+`id` is a `bigserial`, so positions are **strictly-increasing but NOT gapless**.
+A rolled-back or timed-out insert permanently consumes its id, leaving a gap.
+Ordering is by `id` alone; never assume positions are contiguous. `read`'s `head`
+is the actual last position, not a count — treat it as an opaque cursor, compare
+it, and never do arithmetic on it. (The shared contract suite is gap-tolerant for
+exactly this reason.)
+
+## `lockTimeout` defaults to `0`
+
+`lockTimeout` (seconds) is passed to `set_config('lock_timeout', …, true)` (the
+bound-parameter equivalent of `SET LOCAL`) inside every append, bounding how long
+a blocked writer waits on the exclusive lock. It **defaults to `0` — wait
+indefinitely**, matching the in-memory semaphore's unbounded wait so the shared
+contract suite behaves identically across engines.
+
+A non-zero timeout that fires raises SQLSTATE `55P03`. That is a Postgres-only
+outcome and is surfaced **off** the shared `append` contract as a **defect**
+(`Effect.die`), never as `AppendConditionFailed` — the in-memory oracle cannot
+produce it, and a lock-timeout is infrastructure, not a consistency conflict.
+
+## Configuration
+
+`PostgresStoreConfig` is a `Schema` (exported), so a malformed config fails
+loudly at construction (empty/dotted `schema`/`tablePrefix`, a
+negative/non-finite `lockTimeout`, or any `{ schema, tablePrefix }` whose derived
+identifiers would exceed Postgres's 63-byte limit and be silently truncated).
+
+```ts
+interface PostgresStoreConfig {
+  readonly schema?: string // default 'public'
+  readonly tablePrefix?: string // default 'dcb_events'
+  readonly lockTimeout?: number // seconds; default 0 (wait forever)
+  readonly pollInterval?: number // subscribe poll, ms; default 1000
+  readonly catchUpPageSize?: number // subscribe reconcile page; default 512
+}
+```
+
+`pollInterval` bounds worst-case live-tail latency for `subscribe`: the periodic
+position-based poll — not `NOTIFY` — is the delivery guarantee, so every
+committed position is reconciled within this interval whether or not its `NOTIFY`
+was heard. `catchUpPageSize` is how many events a single reconcile read fetches
+before looping.
+
+## Licence
+
+BSD 3-Clause. See [`LICENSE`](./LICENSE). Copyright (c) 2026 Neverbland.

package/dist/cjs/clients.js

@@ -0,0 +1,62 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.pooledLayer = exports.directLayer = exports.PgClientPooled = exports.PgClientDirect = void 0;
+var _experimental = require("@effect/experimental");
+var _sqlPg = require("@effect/sql-pg");
+var _effect = require("effect");
+/**
+ * The TWO store-owned Postgres clients — the "Neon trap" mitigation (ADR-0002).
+ *
+ * `@effect/sql-pg` exposes a single `PgClient` (and `SqlClient`) tag; 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:
+ *
+ * - `PgClientPooled` — the pooled client used for reads, the append function,
+ *   and `notify`. Backed by a `pg.Pool`; connections are recycled 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
+ *   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
+ * deployment-time wiring choice rather than a code change.
+ */
+
+/**
+ * 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.
+ */
+class PgClientPooled extends /*#__PURE__*/_effect.Context.Tag('@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.
+ */
+exports.PgClientPooled = PgClientPooled;
+class PgClientDirect extends /*#__PURE__*/_effect.Context.Tag('@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
+ * built-in `PgClient.layer` does internally, minus the collision-prone claim on
+ * the shared `PgClient` tag.
+ */
+exports.PgClientDirect = PgClientDirect;
+const pooledLayer = config => _effect.Layer.scoped(PgClientPooled, _sqlPg.PgClient.make(config)).pipe(_effect.Layer.provide(_experimental.Reactivity.layer));
+/**
+ * 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).
+ */
+exports.pooledLayer = pooledLayer;
+const directLayer = config => _effect.Layer.scoped(PgClientDirect, _sqlPg.PgClient.make(config)).pipe(_effect.Layer.provide(_experimental.Reactivity.layer));
+exports.directLayer = directLayer;
+//# sourceMappingURL=clients.js.map

package/dist/cjs/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","names":["_experimental","require","_sqlPg","_effect","PgClientPooled","Context","Tag","exports","PgClientDirect","pooledLayer","config","Layer","scoped","PgClient","make","pipe","provide","Reactivity","layer","directLayer"],"sources":["../../src/clients.ts"],"sourcesContent":[null],"mappings":";;;;;;AAsBA,IAAAA,aAAA,GAAAC,OAAA;AAEA,IAAAC,MAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AAzBA;;;;;;;;;;;;;;;;;;;;;;;AA2BA;;;;;AAKM,MAAOG,cAAe,sBAAQC,eAAO,CAACC,GAAG,CAC7C,0CAA0C,CAC3C,EAAqC;AAEtC;;;;AAAAC,OAAA,CAAAH,cAAA,GAAAA,cAAA;AAIM,MAAOI,cAAe,sBAAQH,eAAO,CAACC,GAAG,CAC7C,0CAA0C,CAC3C,EAAqC;AAEtC;;;;;;;AAAAC,OAAA,CAAAC,cAAA,GAAAA,cAAA;AAOO,MAAMC,WAAW,GACtBC,MAA+B,IAE/BC,aAAK,CAACC,MAAM,CAACR,cAAc,EAAES,eAAQ,CAACC,IAAI,CAACJ,MAAM,CAAC,CAAC,CAACK,IAAI,CACtDJ,aAAK,CAACK,OAAO,CAACC,wBAAU,CAACC,KAAK,CAAC,CAChC;AAEH;;;;;AAAAX,OAAA,CAAAE,WAAA,GAAAA,WAAA;AAKO,MAAMU,WAAW,GACtBT,MAA+B,IAE/BC,aAAK,CAACC,MAAM,CAACJ,cAAc,EAAEK,eAAQ,CAACC,IAAI,CAACJ,MAAM,CAAC,CAAC,CAACK,IAAI,CACtDJ,aAAK,CAACK,OAAO,CAACC,wBAAU,CAACC,KAAK,CAAC,CAChC;AAAAX,OAAA,CAAAY,WAAA,GAAAA,WAAA","ignoreList":[]}

package/dist/cjs/config.js

@@ -0,0 +1,94 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.decodePostgresStoreConfig = exports.PostgresStoreConfig = void 0;
+var _core = require("@kairos-es/core");
+var _effect = require("effect");
+var _ddl = require("./internal/ddl.js");
+/**
+ * Public configuration for a Postgres `DcbEventStore`.
+ *
+ * A store is defined entirely by its `{ schema, tablePrefix }` naming pair plus
+ * a `lockTimeout`. Everything else — table/index/function names, the NOTIFY
+ * channel, the lock scope — is DERIVED from these (see `internal/ddl.ts`), so
+ * one config value is one completely isolated store. There is deliberately NO
+ * lockless option here: the exclusive-lock serialisation is not negotiable on the
+ * production surface — the lockless variant is a test-fixture-only seam, living in
+ * an internal module reachable only from the test graph.
+ *
+ * The config is a `Schema`, not a bare interface, so that malformed input fails
+ * LOUDLY at construction (`layer`/`ensureSchema` decode through it) rather than
+ * late and obscurely on the first DDL or append — the same fail-at-the-boundary
+ * discipline core applies to `Tag`/`ReadLimit`. It rejects: an empty or dotted
+ * `schema`/`tablePrefix` atom (a dot would break the qualified-name dot-split),
+ * a negative/non-finite `lockTimeout`, and — via `oversizedIdentifier` — any
+ * `{ schema, tablePrefix }` whose derived names would exceed Postgres's 63-byte
+ * identifier limit and be silently truncated.
+ */
+
+/**
+ * A single Postgres identifier atom: non-empty and dot-free. Dots are barred
+ * because `schema`/`tablePrefix` are composed into qualified names that
+ * `sql(identifier)` dot-splits, 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(/^[^.]+$/, {
+  identifier: 'PostgresIdentifierAtom',
+  description: 'a non-empty identifier atom containing no "."'
+}));
+/**
+ * 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.
+ */
+const PostgresStoreConfig = exports.PostgresStoreConfig = /*#__PURE__*/_effect.Schema.Struct({
+  // `exact: true` 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
+  }),
+  lockTimeout: _effect.Schema.optionalWith(_effect.Schema.Number.pipe(_effect.Schema.nonNegative(), _effect.Schema.finite()), {
+    exact: true
+  }),
+  // The two subscribe knobs are core's field definitions, not this engine's: see
+  // `subscriptionTuningFields`.
+  ..._core.subscriptionTuningFields
+}).pipe(/*#__PURE__*/
+// 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.
+_effect.Schema.filter(config => (0, _ddl.oversizedIdentifier)(config) ?? true));
+/**
+ * Decode an unknown value into a validated `PostgresStoreConfig`, throwing a
+ * `ParseError` on any violation. Used by `layer`/`ensureSchema` so a bad config
+ * fails at construction time.
+ */
+const decodePostgresStoreConfig = exports.decodePostgresStoreConfig = /*#__PURE__*/_effect.Schema.decodeUnknownSync(PostgresStoreConfig);
+//# sourceMappingURL=config.js.map

package/dist/cjs/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":["_core","require","_effect","_ddl","IdentifierAtom","Schema","String","pipe","nonEmptyString","pattern","identifier","description","PostgresStoreConfig","exports","Struct","schema","optionalWith","exact","tablePrefix","lockTimeout","Number","nonNegative","finite","subscriptionTuningFields","filter","config","oversizedIdentifier","decodePostgresStoreConfig","decodeUnknownSync"],"sources":["../../src/config.ts"],"sourcesContent":[null],"mappings":";;;;;;AAoBA,IAAAA,KAAA,GAAAC,OAAA;AACA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,IAAA,GAAAF,OAAA;AAtBA;;;;;;;;;;;;;;;;;;;;;AAwBA;;;;;;AAMA,MAAMG,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;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BO,MAAMC,mBAAmB,GAAAC,OAAA,CAAAD,mBAAA,gBAAGP,cAAM,CAACS,MAAM,CAAC;EAC/C;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,CAAC;EACjEE,WAAW,EAAEd,cAAM,CAACW,YAAY,CAC9BX,cAAM,CAACe,MAAM,CAACb,IAAI,CAACF,cAAM,CAACgB,WAAW,EAAE,EAAEhB,cAAM,CAACiB,MAAM,EAAE,CAAC,EACzD;IAAEL,KAAK,EAAE;EAAI,CAAE,CAChB;EACD;EACA;EACA,GAAGM;CACJ,CAAC,CAAChB,IAAI;AACL;AACA;AACA;AACAF,cAAM,CAACmB,MAAM,CAAEC,MAAM,IAAK,IAAAC,wBAAmB,EAACD,MAAM,CAAC,IAAI,IAAI,CAAC,CAC/D;AAGD;;;;;AAKO,MAAME,yBAAyB,GAAAd,OAAA,CAAAc,yBAAA,gBACpCtB,cAAM,CAACuB,iBAAiB,CAAChB,mBAAmB,CAAC","ignoreList":[]}

package/dist/cjs/ensureSchema.js

@@ -0,0 +1,53 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ensureSchema = void 0;
+var _sql = require("@effect/sql");
+var _effect = require("effect");
+var _config = require("./config.js");
+var _ddl = require("./internal/ddl.js");
+/**
+ * `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` tag — 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 against an existing store is a no-op. 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.
+ */
+
+/**
+ * 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.
+ */
+const ensureSchema = config => _effect.Effect.gen(function* () {
+  const sql = yield* _sql.SqlClient.SqlClient;
+  // Decode through the config schema (same guard as `layer`) so a malformed
+  // config fails at construction rather than mid-migration.
+  const names = (0, _ddl.resolveNames)((0, _config.decodePostgresStoreConfig)(config));
+  // Sequentially, in dependency order (tables → indexes → FK → functions).
+  yield* _effect.Effect.all((0, _ddl.runDdl)(sql, names), {
+    discard: true
+  });
+});
+exports.ensureSchema = ensureSchema;
+//# sourceMappingURL=ensureSchema.js.map

package/dist/cjs/ensureSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureSchema.js","names":["_sql","require","_effect","_config","_ddl","ensureSchema","config","Effect","gen","sql","SqlClient","names","resolveNames","decodePostgresStoreConfig","all","runDdl","discard","exports"],"sources":["../../src/ensureSchema.ts"],"sourcesContent":[null],"mappings":";;;;;;AAyBA,IAAAA,IAAA,GAAAC,OAAA;AACA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AACA,IAAAG,IAAA,GAAAH,OAAA;AA5BA;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA;;;;;AAKO,MAAMI,YAAY,GACvBC,MAA2B,IAE3BC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,GAAG,GAAG,OAAOC,cAAS,CAACA,SAAS;EACtC;EACA;EACA,MAAMC,KAAK,GAAG,IAAAC,iBAAY,EAAC,IAAAC,iCAAyB,EAACP,MAAM,CAAC,CAAC;EAC7D;EACA,OAAOC,cAAM,CAACO,GAAG,CAAC,IAAAC,WAAM,EAACN,GAAG,EAAEE,KAAK,CAAC,EAAE;IAAEK,OAAO,EAAE;EAAI,CAAE,CAAC;AAC1D,CAAC,CAAC;AAAAC,OAAA,CAAAZ,YAAA,GAAAA,YAAA","ignoreList":[]}

package/dist/cjs/index.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "PgClientDirect", {
+  enumerable: true,
+  get: function () {
+    return _clients.PgClientDirect;
+  }
+});
+Object.defineProperty(exports, "PgClientPooled", {
+  enumerable: true,
+  get: function () {
+    return _clients.PgClientPooled;
+  }
+});
+Object.defineProperty(exports, "directLayer", {
+  enumerable: true,
+  get: function () {
+    return _clients.directLayer;
+  }
+});
+Object.defineProperty(exports, "ensureSchema", {
+  enumerable: true,
+  get: function () {
+    return _ensureSchema.ensureSchema;
+  }
+});
+Object.defineProperty(exports, "layer", {
+  enumerable: true,
+  get: function () {
+    return _store.layer;
+  }
+});
+Object.defineProperty(exports, "pooledLayer", {
+  enumerable: true,
+  get: function () {
+    return _clients.pooledLayer;
+  }
+});
+var _clients = require("./clients.js");
+var _ensureSchema = require("./ensureSchema.js");
+var _store = require("./store.js");
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_clients","require","_ensureSchema","_store"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAAA,QAAA,GAAAC,OAAA;AAOA,IAAAC,aAAA,GAAAD,OAAA;AACA,IAAAE,MAAA,GAAAF,OAAA","ignoreList":[]}