@kairos-es/store-postgres 0.0.0

package/src/config.ts

@@ -0,0 +1,92 @@
+/**
+ * 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.
+ */
+import { subscriptionTuningFields } from '@kairos-es/core'
+import { Schema } from 'effect'
+import { oversizedIdentifier } from './internal/ddl'
+
+/**
+ * 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 = Schema.String.pipe(
+  Schema.nonEmptyString(),
+  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.
+ */
+export const PostgresStoreConfig = 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: Schema.optionalWith(IdentifierAtom, { exact: true }),
+  tablePrefix: Schema.optionalWith(IdentifierAtom, { exact: true }),
+  lockTimeout: Schema.optionalWith(
+    Schema.Number.pipe(Schema.nonNegative(), Schema.finite()),
+    { exact: true },
+  ),
+  // The two subscribe knobs are core's field definitions, not this engine's: see
+  // `subscriptionTuningFields`.
+  ...subscriptionTuningFields,
+}).pipe(
+  // 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),
+)
+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
+ * fails at construction time.
+ */
+export const decodePostgresStoreConfig =
+  Schema.decodeUnknownSync(PostgresStoreConfig)

package/src/ensureSchema.ts

@@ -0,0 +1,46 @@
+/**
+ * `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.
+ */
+import { SqlClient, type SqlError } from '@effect/sql'
+import { Effect } from 'effect'
+import { decodePostgresStoreConfig, type PostgresStoreConfig } from './config'
+import { resolveNames, runDdl } from './internal/ddl'
+
+/**
+ * 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 const ensureSchema = (
+  config: PostgresStoreConfig,
+): Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient> =>
+  Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient
+    // Decode through the config schema (same guard as `layer`) so a malformed
+    // config fails at construction rather than mid-migration.
+    const names = resolveNames(decodePostgresStoreConfig(config))
+    // Sequentially, in dependency order (tables → indexes → FK → functions).
+    yield* Effect.all(runDdl(sql, names), { discard: true })
+  })

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @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 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.
+ */
+export {
+  directLayer,
+  PgClientDirect,
+  PgClientPooled,
+  pooledLayer,
+} from './clients'
+export type { PostgresStoreConfig } from './config'
+export { ensureSchema } from './ensureSchema'
+export { layer } from './store'