@kairos-es/store-postgres 0.0.0

package/dist/esm/internal/readPlan.js

@@ -0,0 +1,59 @@
+import { classifyServableQuery, ORIGIN } from '@kairos-es/core';
+import { taggedReadSql, typeOnlyReadSql, wildcardReadSql } from "./matchSql.js";
+import { jsonbText, toQueryItemsJson } from "./transport.js";
+/**
+ * Compile a servable query into a `FetchPlan`. The SQL comes from the shared
+ * `matchSql` builders (the tagged path composes the same emitted match chain as the
+ * conflict check, which binds its own placeholder tokens and wraps it differently),
+ * with the pre-quoted names embedded and the VALUES bound as `$n` parameters
+ * (never interpolated).
+ *
+ * The `switch` is exhaustive over core's `ServableQueryShape` with NO `default`
+ * and no trailing fall-through arm, and what that buys is a COMPILE error where
+ * there would otherwise be a silent mis-serve. Core owns that union and this
+ * module only consumes it, so a fourth member added there is a change this file
+ * cannot see coming: a cascade ending in an unguarded tagged branch would have
+ * SERVED that shape as tagged, and both `read` and the `subscribe` poll sharing
+ * its plan would have returned the wrong rows — no error raised, nothing failing
+ * to typecheck. Every arm returns instead, so the added member leaves this
+ * function with a reachable end and a return type that does not admit
+ * `undefined`, and the module stops compiling.
+ */
+export const compileFetchPlan = (tables, query) => {
+  const shape = classifyServableQuery(query);
+  switch (shape.kind) {
+    case 'wildcard':
+      return {
+        text: wildcardReadSql(tables.main),
+        bind: (after, limit) => [after, limit]
+      };
+    case 'typeOnly':
+      {
+        // node-postgres binds a JS array param as a Postgres array literal, so
+        // `type = ANY($2)` matches any of the item's types. The item's own list is
+        // bound as it stands: a branded `EventType` IS its string to the driver, so
+        // nothing here has to unwrap or copy it.
+        const types = shape.types;
+        return {
+          text: typeOnlyReadSql(tables.main),
+          bind: (after, limit) => [after, types, limit]
+        };
+      }
+    case 'tagged':
+      {
+        // `after` ($2) is applied at BOTH CTE stages; `limit` ($3) inside the
+        // ordered filtered_ids so it caps by position, not on the outer join.
+        const itemsJson = jsonbText(toQueryItemsJson(query));
+        return {
+          text: taggedReadSql(tables.main, tables.tag),
+          bind: (after, limit) => [itemsJson, after, limit]
+        };
+      }
+  }
+};
+/**
+ * Run a compiled plan for a given `after`/`limit`, honouring `after` (exclusive;
+ * absent → `0`) and `limit` (`NULL` = no limit), ordered by `id ASC`.
+ */
+export const runFetch = (sql, plan, after, limit) => sql.unsafe(plan.text, plan.bind(after ?? ORIGIN, limit ?? null));
+//# sourceMappingURL=readPlan.js.map

package/dist/esm/internal/readPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readPlan.js","names":["classifyServableQuery","ORIGIN","taggedReadSql","typeOnlyReadSql","wildcardReadSql","jsonbText","toQueryItemsJson","compileFetchPlan","tables","query","shape","kind","text","main","bind","after","limit","types","itemsJson","tag","runFetch","sql","plan","unsafe"],"sources":["../../../src/internal/readPlan.ts"],"sourcesContent":[null],"mappings":"AAyBA,SAASA,qBAAqB,EAAEC,MAAM,QAAoB,iBAAiB;AAE3E,SAASC,aAAa,EAAEC,eAAe,EAAEC,eAAe,QAAQ,eAAY;AAC5E,SAAwBC,SAAS,EAAEC,gBAAgB,QAAQ,gBAAa;AA0BxE;;;;;;;;;;;;;;;;;;AAkBA,OAAO,MAAMC,gBAAgB,GAAGA,CAC9BC,MAAkB,EAClBC,KAAY,KACC;EACb,MAAMC,KAAK,GAAGV,qBAAqB,CAACS,KAAK,CAAC;EAC1C,QAAQC,KAAK,CAACC,IAAI;IAChB,KAAK,UAAU;MACb,OAAO;QACLC,IAAI,EAAER,eAAe,CAACI,MAAM,CAACK,IAAI,CAAC;QAClCC,IAAI,EAAEA,CAACC,KAAK,EAAEC,KAAK,KAAK,CAACD,KAAK,EAAEC,KAAK;OACtC;IACH,KAAK,UAAU;MAAE;QACf;QACA;QACA;QACA;QACA,MAAMC,KAAK,GAAGP,KAAK,CAACO,KAAK;QACzB,OAAO;UACLL,IAAI,EAAET,eAAe,CAACK,MAAM,CAACK,IAAI,CAAC;UAClCC,IAAI,EAAEA,CAACC,KAAK,EAAEC,KAAK,KAAK,CAACD,KAAK,EAAEE,KAAK,EAAED,KAAK;SAC7C;MACH;IACA,KAAK,QAAQ;MAAE;QACb;QACA;QACA,MAAME,SAAS,GAAGb,SAAS,CAACC,gBAAgB,CAACG,KAAK,CAAC,CAAC;QACpD,OAAO;UACLG,IAAI,EAAEV,aAAa,CAACM,MAAM,CAACK,IAAI,EAAEL,MAAM,CAACW,GAAG,CAAC;UAC5CL,IAAI,EAAEA,CAACC,KAAK,EAAEC,KAAK,KAAK,CAACE,SAAS,EAAEH,KAAK,EAAEC,KAAK;SACjD;MACH;EACF;AACF,CAAC;AAED;;;;AAIA,OAAO,MAAMI,QAAQ,GAAGA,CACtBC,GAAwB,EACxBC,IAAe,EACfP,KAA2B,EAC3BC,KAA4B,KAE5BK,GAAG,CAACE,MAAM,CAAWD,IAAI,CAACV,IAAI,EAAEU,IAAI,CAACR,IAAI,CAACC,KAAK,IAAId,MAAM,EAAEe,KAAK,IAAI,IAAI,CAAC,CAAC","ignoreList":[]}

package/dist/esm/internal/subscribe.js

@@ -0,0 +1,113 @@
+import { ORIGIN, ReadLimit } from '@kairos-es/core';
+import { Chunk, Effect, Option, Queue, Schedule, Stream } from 'effect';
+/**
+ * A short catch-up page size default for the reconcile loop. Reads page by page
+ * until a short page signals the tail is drained, so a large backlog is streamed
+ * in bounded chunks rather than one huge SELECT. Overridable via
+ * `config.catchUpPageSize`.
+ */
+export const DEFAULT_CATCH_UP_PAGE = 512;
+/**
+ * The default upper bound a live subscriber waits for a wake before re-reading
+ * from its cursor ANYWAY (milliseconds; overridable via `config.pollInterval`).
+ * This periodic position-based poll — not `NOTIFY` — is the correctness
+ * guarantee: every committed position is reconciled within this interval
+ * regardless of whether its `NOTIFY` was heard, which covers a `NOTIFY` fired
+ * before `LISTEN` was fully established, a coalesced/lost `NOTIFY`, and a listen
+ * connection that dropped SILENTLY (the `@effect/sql-pg` listen client swallows
+ * connection errors and does not auto-reconnect). `NOTIFY` only lowers delivery
+ * latency below this interval. Upstream `postgres_tt.py` uses the same 1-second
+ * fallback poll (`conn.wait(..., interval=1)`).
+ */
+export const DEFAULT_POLL_INTERVAL_MILLIS = 1000;
+/**
+ * Retry a TRANSIENT poll fault (a `SqlError` from one reconcile read) on a capped
+ * exponential backoff rather than letting `Stream.orDie` kill a subscription that
+ * may have been alive for days over a single connection blip. A fault that
+ * PERSISTS past the cap propagates (the decorator dies it) — infrastructure stays
+ * off the contract channel while the stream survives ordinary transients.
+ */
+const POLL_RETRY_SCHEDULE = /*#__PURE__*/Schedule.exponential('100 millis', 2).pipe(/*#__PURE__*/Schedule.union(/*#__PURE__*/Schedule.spaced('2 seconds')), /*#__PURE__*/Schedule.intersect(/*#__PURE__*/Schedule.recurs(20)));
+/**
+ * Build the subscription `Stream`: catch up from `after`, then track the live
+ * tail. The cursor threads through the `unfoldChunkEffect` unfold state, starting
+ * at `after` and advancing to the last delivered position each batch; the stream
+ * never completes on its own (always `Option.some`), so the enclosing scope
+ * interrupts it on close. A `SqlError` mid-stream stays on the channel;
+ * `makeContractStore` dies it (subscribe is `E = never` on the contract).
+ */
+export const subscribeStream = (deps, after) => Stream.unwrapScoped(Effect.gen(function* () {
+  // The wake primitive: a sliding(1) queue holding at most one pending
+  // signal. The listener `offer`s an opaque wake on every NOTIFY; the poll
+  // loop `take`s (with a timeout). The lost-wakeup guard is STRUCTURAL —
+  // drain the queue BEFORE reading, so a NOTIFY that lands mid-read leaves
+  // a fresh signal that makes the next `take` return at once rather than
+  // sleeping through a real change.
+  const wake = yield* Queue.sliding(1);
+  // Tap every notification into the wake queue. If the listen stream DOES
+  // surface an error, re-subscribe with capped-exponential backoff. In
+  // practice the @effect/sql-pg listen client usually swallows a dropped
+  // connection SILENTLY rather than erroring, so this retry rarely fires —
+  // the poll fallback below, not this retry, is the real reconnect guarantee:
+  // the reconcile loop re-reads from the cursor on every poll, so a silently-
+  // dropped (and later re-established) listener loses no positions.
+  const listener = deps.listen.pipe(Stream.tap(() => Queue.offer(wake, undefined)), Stream.retry(Schedule.exponential('50 millis').pipe(Schedule.union(Schedule.spaced('1 seconds')))));
+  // Drain the listener into the wake queue on a background fibre; the scope
+  // releases it. We never read its elements directly — every notification is
+  // an opaque wake signal.
+  yield* listener.pipe(Stream.runDrain, Effect.forkScoped);
+  // Reconcile: page-read from `from` until a short page, advancing to the last
+  // delivered position. Retries a TRANSIENT poll fault on a capped schedule so
+  // a single connection blip does not kill a days-long subscription; a
+  // persistent fault propagates and dies.
+  const drainFrom = from => Effect.gen(function* () {
+    const collected = [];
+    let cursor = from;
+    // Loop pages until a short page signals the tail is drained.
+    while (true) {
+      const events = yield* deps.fetch(cursor, ReadLimit.make(deps.catchUpPage));
+      for (const event of events) {
+        collected.push(event);
+      }
+      const lastEvent = events.at(-1);
+      if (lastEvent === undefined || events.length < deps.catchUpPage) {
+        break;
+      }
+      cursor = lastEvent.position;
+    }
+    const last = collected.at(-1)?.position ?? from;
+    return {
+      events: collected,
+      last
+    };
+  }).pipe(Effect.retry(POLL_RETRY_SCHEDULE));
+  /**
+   * Produce the NEXT non-empty batch from a cursor position, together with
+   * the advanced cursor — a pure `Position → Effect<[Chunk, next]>`. The
+   * `> boundary` de-dup is enforced by `fetch`'s exclusive lower bound, so a
+   * live re-read after a wake never re-emits an already-delivered position.
+   *
+   * Drain the wake queue BEFORE reading (lost-wakeup guard), then drain from
+   * the cursor. If a drain yields nothing, wait for a wake but only up to the
+   * poll interval, then loop and re-read ANYWAY — the periodic position-based
+   * poll that makes delivery correct independently of NOTIFY. This effect only
+   * completes by returning a non-empty chunk; the scope interrupts it on close.
+   */
+  const nextBatch = from => Effect.gen(function* () {
+    while (true) {
+      yield* Queue.takeAll(wake);
+      const {
+        events,
+        last
+      } = yield* drainFrom(from);
+      if (events.length > 0) {
+        return [Chunk.fromIterable(events), last];
+      }
+      // Nothing new: block on a wake, but only up to the poll interval — on
+      // timeout we fall through and the loop re-reads regardless.
+      yield* Effect.ignore(Effect.timeout(Queue.take(wake), deps.pollInterval));
+    }
+  });
+  return Stream.unfoldChunkEffect(after ?? ORIGIN, from => Effect.map(nextBatch(from), Option.some));
+}));
+//# sourceMappingURL=subscribe.js.map

package/dist/esm/internal/subscribe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe.js","names":["ORIGIN","ReadLimit","Chunk","Effect","Option","Queue","Schedule","Stream","DEFAULT_CATCH_UP_PAGE","DEFAULT_POLL_INTERVAL_MILLIS","POLL_RETRY_SCHEDULE","exponential","pipe","union","spaced","intersect","recurs","subscribeStream","deps","after","unwrapScoped","gen","wake","sliding","listener","listen","tap","offer","undefined","retry","runDrain","forkScoped","drainFrom","from","collected","cursor","events","fetch","make","catchUpPage","event","push","lastEvent","at","length","position","last","nextBatch","takeAll","fromIterable","ignore","timeout","take","pollInterval","unfoldChunkEffect","map","some"],"sources":["../../../src/internal/subscribe.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/esm/internal/transport.js

@@ -0,0 +1,56 @@
+import { DateTime, Encoding } from 'effect';
+/**
+ * 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.
+ */
+export const jsonbText = value => JSON.stringify(value);
+/** Serialise a `Query`'s items into their transport JSON shape. */
+export const toQueryItemsJson = query => query.items.map(item => ({
+  types: [...item.types],
+  tags: [...item.tags]
+}));
+/** Serialise one core `DcbEvent` into its transport JSON shape. */
+export const toEventJson = event => ({
+  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),
+  tags: [...event.tags],
+  uuid: event.uuid,
+  occurred_at: DateTime.formatIso(event.occurredAt)
+});
+/**
+ * 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`.
+ *
+ * The branded scalars (`type`, `tags`, `uuid`, `position`) are minted by trusted
+ * `as`-cast, NOT by re-running `EventType.make` / `Tag.make` etc. This is
+ * deliberate: these bytes were validated at write time, and the store schema is
+ * intentionally LAX on read (ADR-0006 store-laxness — hand-assembled or pre-ADR
+ * events must remain readable), so re-validating here could REJECT a legitimately
+ * stored value and break that contract. It mirrors the in-memory oracle, which
+ * likewise mints branded positions by cast at its trusted allocation boundary
+ * (`inMemory.ts`). The read boundary is the analogous trusted deserialisation
+ * point.
+ */
+export const rowToSequenced = row => ({
+  event: {
+    type: row.type,
+    data: row.data ?? new Uint8Array(0),
+    tags: row.tags,
+    uuid: row.uuid,
+    occurredAt: DateTime.unsafeFromDate(row.occurred_at)
+  },
+  position: BigInt(row.id)
+});
+//# sourceMappingURL=transport.js.map

package/dist/esm/internal/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","names":["DateTime","Encoding","jsonbText","value","JSON","stringify","toQueryItemsJson","query","items","map","item","types","tags","toEventJson","event","type","data","encodeBase64","uuid","occurred_at","formatIso","occurredAt","rowToSequenced","row","Uint8Array","unsafeFromDate","position","BigInt","id"],"sources":["../../../src/internal/transport.ts"],"sourcesContent":[null],"mappings":"AAsBA,SAASA,QAAQ,EAAEC,QAAQ,QAAQ,QAAQ;AAG3C;;;;;;;;;;;;;AAaA,OAAO,MAAMC,SAAS,GAAIC,KAAc,IAAaC,IAAI,CAACC,SAAS,CAACF,KAAK,CAAC;AAQ1E;AACA,OAAO,MAAMG,gBAAgB,GAAIC,KAAY,IAC3CA,KAAK,CAACC,KAAK,CAACC,GAAG,CAAEC,IAAI,KAAM;EACzBC,KAAK,EAAE,CAAC,GAAGD,IAAI,CAACC,KAAK,CAAC;EACtBC,IAAI,EAAE,CAAC,GAAGF,IAAI,CAACE,IAAI;CACpB,CAAC,CAAC;AA4BL;AACA,OAAO,MAAMC,WAAW,GAAIC,KAAe,KAAiB;EAC1DC,IAAI,EAAED,KAAK,CAACC,IAAI;EAChB;EACA;EACAC,IAAI,EAAEf,QAAQ,CAACgB,YAAY,CAACH,KAAK,CAACE,IAAI,CAAC;EACvCJ,IAAI,EAAE,CAAC,GAAGE,KAAK,CAACF,IAAI,CAAC;EACrBM,IAAI,EAAEJ,KAAK,CAACI,IAAI;EAChBC,WAAW,EAAEnB,QAAQ,CAACoB,SAAS,CAACN,KAAK,CAACO,UAAU;CACjD,CAAC;AA4BF;;;;;;;;;;;;;;;AAeA,OAAO,MAAMC,cAAc,GAAIC,GAAa,KAAsB;EAChET,KAAK,EAAE;IACLC,IAAI,EAAEQ,GAAG,CAACR,IAAwB;IAClCC,IAAI,EAAEO,GAAG,CAACP,IAAI,IAAI,IAAIQ,UAAU,CAAC,CAAC,CAAC;IACnCZ,IAAI,EAAEW,GAAG,CAACX,IAAmC;IAC7CM,IAAI,EAAEK,GAAG,CAACL,IAAwB;IAClCG,UAAU,EAAErB,QAAQ,CAACyB,cAAc,CAACF,GAAG,CAACJ,WAAW;GACpD;EACDO,QAAQ,EAAEC,MAAM,CAACJ,GAAG,CAACK,EAAE;CACxB,CAAC","ignoreList":[]}

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": []
+}

package/dist/esm/store.js

@@ -0,0 +1,249 @@
+import { AppendConditionFailed, DcbEventStore, DEFAULT_CATCH_UP_PAGE_SIZE, DEFAULT_POLL_INTERVAL_MILLIS, makeContractStore, ORIGIN, subscribeStream } from '@kairos-es/core';
+import { Effect, Layer, Stream } from 'effect';
+import { PgClientDirect, PgClientPooled } from "./clients.js";
+import { decodePostgresStoreConfig } from "./config.js";
+import { quoteQualified, resolveNames } from "./internal/ddl.js";
+import { compileFetchPlan, runFetch } from "./internal/readPlan.js";
+import { jsonbText, rowToSequenced, toEventJson, toQueryItemsJson } from "./internal/transport.js";
+/**
+ * Set `lock_timeout` for the current transaction via a BOUND parameter.
+ *
+ * `SET LOCAL` cannot take a bound parameter, but `set_config(setting, value,
+ * is_local)` is its exact bound-parameter equivalent (`is_local = true` ≡ `SET
+ * LOCAL`) — so the timeout value is a parameter, never interpolated into SQL
+ * text. The value is `'<seconds>s'` (Postgres parses the `s` unit); `'0s'` = no
+ * timeout. Runs inside the append transaction so it scopes to that call only.
+ */
+const setLocalLockTimeout = (sql, lockTimeout) => sql`SELECT set_config('lock_timeout', ${`${lockTimeout}s`}, true)`;
+/**
+ * Build the engine MECHANICS (a `RawDcbEventStore`) over the two clients and a
+ * resolved name set. Contract policy (`assertServableQuery`, `ReadLimit` decode,
+ * error-vs-defect classification) is NOT here — `makeContractStore` adds it
+ * uniformly, so this engine surfaces raw `SqlError`s and the contract conflict.
+ */
+const make = (config, names) => Effect.gen(function* () {
+  const pooled = yield* PgClientPooled;
+  const direct = yield* PgClientDirect;
+  const lockTimeout = config.lockTimeout ?? 0;
+  const pollInterval = config.pollInterval ?? DEFAULT_POLL_INTERVAL_MILLIS;
+  const catchUpPageSize = config.catchUpPageSize ?? DEFAULT_CATCH_UP_PAGE_SIZE;
+  // The pre-quoted table names every read plan embeds (resolved once).
+  const tables = {
+    main: quoteQualified(names.mainTable),
+    tag: quoteQualified(names.tagTable)
+  };
+  // --- read -------------------------------------------------------------
+  /**
+   * The global last position ignoring any filter — the head of a no-limit
+   * read. Empty store → ORIGIN.
+   *
+   * A VALUE over the resolved `pooled`, and deliberately NOT a function of a
+   * client — do not re-introduce the parameter. There is only one client it
+   * could take: `direct` exists solely for `subscribe`'s `listen` (see
+   * `clients.ts`), so a client parameter would advertise a selection seam the
+   * engine does not have.
+   *
+   * 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
+   * `pinnedConnection` test observes the same fact from the SERVER: two
+   * statements issued inside one transaction report one `pg_backend_pid()`.
+   *
+   * Built once at layer construction and re-run per read, which a statement
+   * supports: it carries no mutable state and recompiles on every execution.
+   */
+  const globalHead = pooled`
+      SELECT MAX(id) AS max FROM ${pooled(names.mainTable)}
+    `.pipe(Effect.map(rows => {
+    const max = rows[0]?.max;
+    return max === null || max === undefined ? ORIGIN : BigInt(max);
+  }));
+  /**
+   * The read MECHANICS: the rows a query selects, plus the head a decision
+   * model may then append under. `read` below only shapes the pair into a
+   * `ReadResponse`, so the two snapshot regimes argued for here stay in one
+   * place.
+   *
+   * Named for what it returns rather than for what it reads through: it closes
+   * over `pooled`, and takes no client, for the reason given on `globalHead`.
+   */
+  const readRowsAndHead = (query, options) => Effect.gen(function* () {
+    // No validation here — the query and limit were validated once at the
+    // `makeContractStore` boundary, so the per-read re-validation is gone.
+    const plan = compileFetchPlan(tables, query);
+    // Limited read: `head` is the last RETURNED position, taken from the
+    // SAME single statement, so rows and head are already one consistent
+    // snapshot (or ORIGIN when nothing is returned). No transaction needed —
+    // a single statement sees a single snapshot.
+    if (options?.limit !== undefined) {
+      const rows = yield* runFetch(pooled, plan, options.after, options.limit);
+      const lastRow = rows.at(-1);
+      const head = lastRow === undefined ? ORIGIN : BigInt(lastRow.id);
+      return {
+        rows,
+        head
+      };
+    }
+    // No-limit read: `head` is the GLOBAL last position (ignoring the query
+    // filter), which needs a SEPARATE `MAX(id)` statement. Rows and head
+    // MUST share one MVCC snapshot: under the default READ COMMITTED each
+    // statement snapshots independently, so a concurrent append committing
+    // between the row fetch and the `MAX(id)` would push `head` PAST an
+    // event absent from `events` — and a decision model appending under
+    // `{ after: head }` would then silently miss that event as a conflict,
+    // breaking optimistic concurrency. A REPEATABLE READ, READ ONLY
+    // transaction gives both statements a single snapshot, matching the
+    // in-memory oracle's atomic (mutex-guarded) read. Readers take only
+    // ACCESS SHARE, so this never contends with the exclusive-lock append.
+    return yield* pooled.withTransaction(Effect.gen(function* () {
+      yield* pooled.unsafe('SET TRANSACTION ISOLATION LEVEL REPEATABLE READ, READ ONLY');
+      const rows = yield* runFetch(pooled, plan, options?.after, undefined);
+      const head = yield* globalHead;
+      return {
+        rows,
+        head
+      };
+    }));
+  });
+  const read = (query, options) => readRowsAndHead(query, options).pipe(Effect.map(({
+    rows,
+    head
+  }) => ({
+    events: Stream.fromIterable(rows.map(rowToSequenced)),
+    head
+  })));
+  /**
+   * The ONE transaction frame every append rides: open a transaction, apply the
+   * per-call `set_config('lock_timeout', …, true)`, then run the caller's
+   * `SELECT <fn>(…)`. Both the conditional and unconditional paths go through
+   * here, so the lock-timeout frame can never diverge between them — the
+   * function's LOCK/check/insert and the timeout are one atomic unit, and the
+   * conflict (zero rows) vs head (`MAX(id)`) is read from the returned rows by
+   * the caller, never from a caught error.
+   */
+  const callAppendFn = select => pooled.withTransaction(setLocalLockTimeout(pooled, lockTimeout).pipe(Effect.zipRight(select)));
+  const append = (events, condition) => {
+    const eventsJson = events.map(toEventJson);
+    // Raw mechanics: a CONFLICT is `AppendConditionFailed`; a `SqlError` (incl.
+    // a `55P03` lock-timeout abort) rides the channel too. `makeContractStore`
+    // classifies — conflict stays, everything else becomes a defect.
+    return Effect.gen(function* () {
+      if (condition === undefined) {
+        // No guard, but the unconditional twin STILL takes the exclusive lock
+        // (see `unconditionalAppendBody`). That lock on BOTH append paths is how
+        // this engine discharges the subscribe machine's ascending-commit-order
+        // precondition (`SubscribeMachine.ts` argues it): without it two
+        // concurrent unconditional writers can commit bigserial ids out of
+        // order, letting `subscribe` skip the later-committing lower id and
+        // `head` overtake an in-flight position. Sharing `callAppendFn` with the
+        // conditional path guarantees the lock is scoped to the call and the
+        // configured timeout applies identically to both append paths.
+        const rows = yield* callAppendFn(pooled`
+              SELECT ${pooled(names.appendUnconditionalFn)}(
+                ${jsonbText(eventsJson)}::jsonb
+              ) AS max
+            `);
+        return headFromRows(rows);
+      }
+      const queryItems = toQueryItemsJson(condition.failIfEventsMatch);
+      const afterId = condition.after === undefined ? null : condition.after;
+      // The function returns MAX(id) on success, ZERO rows on conflict — the
+      // conflict is the row count, never a caught error.
+      const rows = yield* callAppendFn(pooled`
+            SELECT ${pooled(names.appendFn)}(
+              ${jsonbText(queryItems)}::jsonb,
+              ${afterId},
+              ${jsonbText(eventsJson)}::jsonb
+            ) AS max
+          `);
+      // Empty result set = conflict.
+      if (rows.length === 0) {
+        return yield* new AppendConditionFailed({
+          condition
+        });
+      }
+      return headFromRows(rows);
+    });
+  };
+  /**
+   * Extract the new head `Position` from the function's single result row. The
+   * function returns exactly one row (`MAX(id)`) on a successful insert; that
+   * value is the last new position (read-your-writes).
+   */
+  const headFromRows = rows => {
+    const max = rows[0]?.max;
+    if (max === null || max === undefined) {
+      // Defensive: a successful unconditional/`NOT conflict` insert always
+      // yields a non-null MAX. A null here means nothing was inserted, which
+      // for an append (always ≥1 event) is a broken invariant → die.
+      throw new Error('kairos-es/store-postgres: append returned no head position');
+    }
+    return BigInt(max);
+  };
+  // --- subscribe --------------------------------------------------------
+  /**
+   * 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.
+   *
+   * 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.
+   *
+   * `E` is `SqlError.SqlError` — both seams fail with it, so the machine's single
+   * error parameter carries it straight through to `makeContractStore`.
+   */
+  const subscribe = (query, after) => {
+    const plan = compileFetchPlan(tables, query);
+    return subscribeStream({
+      fetch: (from, limit) => runFetch(pooled, plan, from, limit).pipe(Effect.map(rows => rows.map(rowToSequenced))),
+      listen: direct.listen(names.channel),
+      pollInterval,
+      catchUpPageSize
+    }, after);
+  };
+  return {
+    read,
+    append,
+    subscribe
+  };
+});
+/**
+ * The Postgres `DcbEventStore` layer factory. Builds the engine over
+ * `PgClientPooled` (reads/append/notify) and `PgClientDirect` (the subscribe
+ * listener). The caller wires those two client layers — pointing `PgClientDirect`
+ * at a direct (non-pooler) endpoint on Neon, or at the same URL as `PgClientPooled`
+ * everywhere else.
+ *
+ * `ensureSchema(config)` must have been run (by the caller's migrator or at
+ * boot) before the layer is used; the layer itself performs no DDL, so it stays
+ * a pure runtime dependency requiring only the two clients.
+ */
+export const layer = (config = {}) => {
+  // Decode through the config schema so a malformed config (empty/dotted atom,
+  // negative/non-finite timeout, over-63-byte derived name) fails LOUDLY at
+  // construction rather than late on the first append.
+  const decoded = decodePostgresStoreConfig(config);
+  return Layer.effect(DcbEventStore, Effect.map(make(decoded, resolveNames(decoded)), makeContractStore));
+};
+//# sourceMappingURL=store.js.map

package/dist/esm/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","names":["AppendConditionFailed","DcbEventStore","DEFAULT_CATCH_UP_PAGE_SIZE","DEFAULT_POLL_INTERVAL_MILLIS","makeContractStore","ORIGIN","subscribeStream","Effect","Layer","Stream","PgClientDirect","PgClientPooled","decodePostgresStoreConfig","quoteQualified","resolveNames","compileFetchPlan","runFetch","jsonbText","rowToSequenced","toEventJson","toQueryItemsJson","setLocalLockTimeout","sql","lockTimeout","make","config","names","gen","pooled","direct","pollInterval","catchUpPageSize","tables","main","mainTable","tag","tagTable","globalHead","pipe","map","rows","max","undefined","BigInt","readRowsAndHead","query","options","plan","limit","after","lastRow","at","head","id","withTransaction","unsafe","read","events","fromIterable","callAppendFn","select","zipRight","append","condition","eventsJson","appendUnconditionalFn","headFromRows","queryItems","failIfEventsMatch","afterId","appendFn","length","Error","subscribe","fetch","from","listen","channel","layer","decoded","effect"],"sources":["../../src/store.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kairos-es/store-postgres",
+  "version": "0.0.0",
+  "description": "Postgres DcbEventStore backend for kairos-es",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverbland/kairos-es.git",
+    "directory": "packages/store-postgres"
+  },
+  "sideEffects": [],
+  "homepage": "https://github.com/neverbland/kairos-es",
+  "peerDependencies": {
+    "@effect/experimental": "^0.61.0",
+    "@effect/platform": "^0.97.0",
+    "@effect/sql": "^0.52.0",
+    "@effect/sql-pg": "^0.53.0",
+    "effect": "^3.22.0",
+    "@kairos-es/core": "^0.0.0"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/dts/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {}
+  }
+}

package/src/clients.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+import { Reactivity } from '@effect/experimental'
+import type { SqlError } from '@effect/sql'
+import { PgClient } from '@effect/sql-pg'
+import { Context, Layer } from 'effect'
+
+/**
+ * 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 class PgClientPooled extends Context.Tag(
+  '@kairos-es/store-postgres/PgClientPooled',
+)<PgClientPooled, 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 class PgClientDirect extends Context.Tag(
+  '@kairos-es/store-postgres/PgClientDirect',
+)<PgClientDirect, PgClient.PgClient>() {}
+
+/**
+ * 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 const pooledLayer = (
+  config: PgClient.PgClientConfig,
+): Layer.Layer<PgClientPooled, SqlError.SqlError> =>
+  Layer.scoped(PgClientPooled, PgClient.make(config)).pipe(
+    Layer.provide(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).
+ */
+export const directLayer = (
+  config: PgClient.PgClientConfig,
+): Layer.Layer<PgClientDirect, SqlError.SqlError> =>
+  Layer.scoped(PgClientDirect, PgClient.make(config)).pipe(
+    Layer.provide(Reactivity.layer),
+  )