@kairos-es/feed-postgres 0.0.0-stage → 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

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @kairos-es/feed-postgres
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Postgres change feed for kairos-es: the feed tables and an idempotent `ensureFeedSchema` for your own migrator, the `FeedWriter` that writes inside a read model's own commit, the `FeedSource` a sync worker tails, the `FeedSyncStore` with its worker lease, and `withFeed`, the store decorator that moves the feed's generation on a reset (ADR-0019).
+
+A feed row exists if and only if the view write and the checkpoint advance that produced it landed. That is the whole reason to write the feed in Postgres beside the view: a search index or cache downstream then receives every change in commit order, with none lost to a crash between the view and the sink. A crash can make the worker send a batch twice, never skip one.
+
+## Installation
+
+`@kairos-es/core`, `@kairos-es/read`, `@kairos-es/feed` and `effect` are peer dependencies. `@kairos-es/codec` is on the line because `@kairos-es/read` peers it:
+
+```sh
+pnpm add @kairos-es/feed-postgres@alpha @kairos-es/feed@alpha @kairos-es/read@alpha \
+  @kairos-es/codec@alpha @kairos-es/core@alpha effect@^4.0.5
+```
+
+The package needs only the generic `SqlClient` from `effect/sql`, so the driver stays your choice. You will normally use it beside `@kairos-es/read-postgres`, whose `ProjectionStore` opens the transaction the feed writes join.
+
+## Schema
+
+`ensureFeedSchema(config)` is an idempotent `Effect<void, SqlError, SqlClient>`; every statement is `IF NOT EXISTS`. Register it in your migrator beside the event store's `ensureSchema` and the read side's `ensureCheckpointSchema`, with the same `{ schema, tablePrefix }` pair:
+
+```ts
+const migrations = Migrator.fromRecord({
+  '0001_kairos_store_dcb_events': ensureSchema(config),
+  '0002_kairos_checkpoints': ensureCheckpointSchema(config),
+  '0003_kairos_feed': ensureFeedSchema(config),
+})
+```
+
+It creates `<prefix>_feed_rows` (one row per feed and key, the newest document or a tombstone), the `<prefix>_feed_seq` sequence every feed in the prefix shares, `<prefix>_feed_generations`, `<prefix>_feed_cursors` (one cursor and lease per feed and sink) and `<prefix>_feed_parked`.
+
+## Wiring
+
+Build the projection store, the feed and `withFeed` under ONE `SqlClient`. The feed's writes, and `withFeed`'s reset, join the store's transaction only through the same client instance; a feed written through any other client is not rolled back with the view.
+
+```ts
+const config = { schema: 'public', tablePrefix: 'dcb_events' }
+const key = checkpointKey(ProjectionId.make('course-search'))
+
+const feed = yield* makePostgresFeed({
+  config,
+  feed: FeedName.make('course-search'),
+  doc: CourseDoc,
+})
+const store = yield* withFeed(yield* makeSqlProjectionStore(config), feed, key)
+
+// In the read model's apply, inside the commit:
+const apply = (batch) =>
+  feed.write(Arr.lastNonEmpty(batch).sequenced.position, (writer) =>
+    Effect.forEach(touchedCourses(batch), (course) =>
+      writer.upsert(FeedKey.make(course.id), toDoc(course)),
+    ),
+  )
+
+// Beside the projections, one worker per feed and sink:
+const syncStore = yield* makePostgresFeedSyncStore({ config })
+yield* Effect.forkScoped(runFeedSync({ source: feed.source, sink, store: syncStore }))
+```
+
+Things to know:
+
+- **One feed per materialisation.** A feed is bound to one checkpoint key the first time `withFeed` decorates a store for it, and that binding is stored in the database: decorating it for a second key dies at construction, in any process.
+- **A reset rebuilds the sinks, not your view.** `resetCheckpoint` on the decorated store deletes the checkpoint, deletes the feed's rows and moves its generation on, in one transaction. Every sink then resyncs from what the replay writes. Your view's own rows are not touched, exactly as a plain `resetCheckpoint` leaves them, so rebuilding a durable view means emptying it yourself before the replay. Otherwise a row the replay never writes again stays in the view, and an `apply` that reads the view back builds on the old rows and the feed sends that to every sink.
+- **Unchanged documents cost nothing.** An upsert of a document equal to the stored one (compared as `jsonb`, so key order does not matter) writes nothing, and the sink is not sent it.
+- **A document that fails to encode through its `Schema` is a defect**, not a sink rejection.
+- **The wake is optional.** The worker polls. `eventStoreWake(query)` gives it the event store's `subscribe` as a wake; it fires when an event is appended, before the projection has written the feed, so it shortens the wait and never replaces the poll.
+
+## The worker lease
+
+One sync worker per feed and sink holds a lease, because a sink has no transaction and two workers could send out of order. Choose the kind in `makePostgresFeedSyncStore({ config, lease })`:
+
+- **`leaseRow({ ttl, heartbeat, margin })`, the default** (30 seconds, renewed every 6, margin a third of `ttl`). Ordinary short statements, so it works through a transaction pooler and needs no reserved connection. The worker stops sending `margin` before its lease could lapse, so a call to the sink that finishes within `margin` of the check before it lands before any other worker can take the lease, even while its renewals are failing. A call that outlasts the margin, because it is slow or because its worker pauses (a long GC pause, a network stall), can land after another worker took over: one stale call, since the next check fails. In the steady state that is one batch; during a rebuild possibly the swap of its own rebuilt copy, which can put back an older copy than the new holder had already served, until those records change again or the next rebuild. So set `margin` above your longest sink call; `heartbeat + margin` must be under `ttl`, which is checked at construction. Each renewal is abandoned at the heartbeat. To keep sending, without a pause, through one renewal that fails or hangs, keep `3 × heartbeat + margin` within `ttl`, as the defaults do; a tighter setting is accepted, and then one lost renewal can stop the worker briefly and restart its session. Expiry is judged by each worker's clock, so keep your hosts' clocks within a small fraction of `ttl` of each other.
+- **`advisoryLock({ connection })`.** A session advisory lock on a connection reserved from a client you dedicate to it. The lock goes only when the session goes, and the worker asks that session before every call that changes the sink, so a long process pause cannot let a stale call through. What it cannot catch is the session dying after that check: the call it let through runs to its end, so it can land as late as its whole duration after the session died, after another worker has taken over and sent. That is still one stale call, but a sink call can be long, a rebuild's swap most of all. The client must be a DIRECT connection: a transaction pooler would hand the session to someone else between statements. A client this package can recognise as a pooler (a `-pooler` host, port 6432, or `pgbouncer=true`) is refused at construction; any other pooler is not detected, so do not give it one.
+
+Either way the cursor's compare-and-set checks the holder, so a worker that has lost its lease cannot move the cursor. The two kinds can meet on one sink, for example during a switch from one to the other, and neither takes it from a live holder of the other. An advisory worker that crashed without closing its scope leaves its name on the sink; a `leaseRow` worker takes the sink over once that worker's session, and so its lock, is gone.
+
+If your driver is `@effect/sql-pg` 4 behind a transaction-mode pooler, build the main client with `prepare: false`, as `@kairos-es/read-postgres`'s README explains.
+
+## Operating a feed
+
+`inspectFeed(feed.source, syncStore)` and `retryParked(syncStore, { feed, sink, key })` from `@kairos-es/feed` read and repair everything here without the sink's credentials: each sink's generation, cursor, when the cursor last moved (`lastAdvance`), lag, lease and parked records, and sending one parked record again.
+
+`lastAdvance` is stamped by the worker's own clock, not the database's, like the lease expiry. A sink whose `lastAdvance` stays still while the feed's head moves is a sink nothing runs, and it holds tombstone collection back for the whole feed: tombstones are kept until every sink with a cursor row has passed them.
+
+`removeSink(syncStore, { feed, sink })` retires such a sink: it deletes its cursor row and its parked records in one transaction, so collection can go on without it. It fails `LeaseHeld` and deletes nothing while a worker holds the sink's lease, of either kind: a lease row whose expiry has not passed, or an advisory lock held by a live session. Stop the worker first. A worker started for the sink later simply registers it again and resyncs.

package/dist/cjs/config.js

@@ -0,0 +1,46 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.decodeFeedPostgresConfig = exports.FeedPostgresConfig = void 0;
+var _effect = require("effect");
+var _ddl = require("./internal/ddl.js");
+/**
+ * Public configuration for the Postgres change feed.
+ *
+ * A feed backend is defined by its `{ schema, tablePrefix }` naming pair alone:
+ * every object it owns is DERIVED from it (`internal/ddl.ts`), so one config
+ * value is one isolated set of feed tables, cohabiting per prefix beside the
+ * event store's objects and `@kairos-es/read-postgres`'s checkpoint table. Pass
+ * the same pair to all three and one prefix names one complete world: the log,
+ * the checkpoints, and the feeds the read models write.
+ *
+ * It is a `Schema` rather than a bare interface so that a malformed value fails
+ * LOUDLY at construction rather than obscurely at the first statement: an empty or
+ * dotted atom (a dot would break the qualified-name split), or a pair whose
+ * derived names would exceed Postgres's 63-byte identifier limit and be silently
+ * truncated. The shape and its checks are `@kairos-es/read-postgres`'s, written
+ * again here rather than imported, because each backend measures only the names it
+ * creates and a sibling backend's internals are not a public surface.
+ */
+
+/** A single identifier atom: non-empty and dot-free. */
+const IdentifierAtom = /*#__PURE__*/_effect.Schema.String.check(/*#__PURE__*/_effect.Schema.isNonEmpty(), /*#__PURE__*/_effect.Schema.isPattern(/^[^.]+$/, {
+  identifier: 'PostgresIdentifierAtom',
+  description: 'a non-empty identifier atom containing no "."'
+}));
+/**
+ * Configuration for the feed's tables.
+ *
+ * - `schema` — the Postgres schema that owns them (default `public`).
+ * - `tablePrefix` — the stem every name derives from (default `dcb_events`,
+ *   giving `dcb_events_feed_rows` and its siblings).
+ */
+const FeedPostgresConfig = exports.FeedPostgresConfig = /*#__PURE__*/_effect.Schema.Struct({
+  schema: _effect.Schema.optionalKey(IdentifierAtom),
+  tablePrefix: _effect.Schema.optionalKey(IdentifierAtom)
+}).check(/*#__PURE__*/_effect.Schema.makeFilter(config => (0, _ddl.oversizedIdentifier)(config)));
+/** Decode a config, throwing a `SchemaError` on any violation. */
+const decodeFeedPostgresConfig = exports.decodeFeedPostgresConfig = /*#__PURE__*/_effect.Schema.decodeUnknownSync(FeedPostgresConfig);
+//# sourceMappingURL=config.js.map

package/dist/cjs/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":["_effect","require","_ddl","IdentifierAtom","Schema","String","check","isNonEmpty","isPattern","identifier","description","FeedPostgresConfig","exports","Struct","schema","optionalKey","tablePrefix","makeFilter","config","oversizedIdentifier","decodeFeedPostgresConfig","decodeUnknownSync"],"sources":["../../src/config.ts"],"sourcesContent":[null],"mappings":";;;;;;AAkBA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,IAAA,GAAAD,OAAA;AAnBA;;;;;;;;;;;;;;;;;;;AAqBA;AACA,MAAME,cAAc,gBAAGC,cAAM,CAACC,MAAM,CAACC,KAAK,cACxCF,cAAM,CAACG,UAAU,EAAE,eACnBH,cAAM,CAACI,SAAS,CAAC,SAAS,EAAE;EAC1BC,UAAU,EAAE,wBAAwB;EACpCC,WAAW,EAAE;CACd,CAAC,CACH;AAED;;;;;;;AAOO,MAAMC,kBAAkB,GAAAC,OAAA,CAAAD,kBAAA,gBAAGP,cAAM,CAACS,MAAM,CAAC;EAC9CC,MAAM,EAAEV,cAAM,CAACW,WAAW,CAACZ,cAAc,CAAC;EAC1Ca,WAAW,EAAEZ,cAAM,CAACW,WAAW,CAACZ,cAAc;CAC/C,CAAC,CAACG,KAAK,cAACF,cAAM,CAACa,UAAU,CAAEC,MAAM,IAAK,IAAAC,wBAAmB,EAACD,MAAM,CAAC,CAAC,CAAC;AAGpE;AACO,MAAME,wBAAwB,GAAAR,OAAA,CAAAQ,wBAAA,gBACnChB,cAAM,CAACiB,iBAAiB,CAACV,kBAAkB,CAAC","ignoreList":[]}

package/dist/cjs/ensureFeedSchema.js

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ensureFeedSchema = void 0;
+var _effect = require("effect");
+var _sql = require("effect/sql");
+var _config = require("./config.js");
+var _ddl = require("./internal/ddl.js");
+/**
+ * `ensureFeedSchema` — the feed's idempotent DDL, as a payload for the consumer's
+ * migrator rather than a migrator of its own, exactly as `ensureCheckpointSchema`
+ * is for the read side and `ensureSchema` for the event store.
+ *
+ * It requires the GENERIC `SqlClient`, so it drops into an existing migrator:
+ *
+ * ```ts
+ * Migrator.fromRecord({
+ *   '0003_kairos_feed': ensureFeedSchema(config),
+ * })
+ * ```
+ *
+ * or runs once at boot. Every statement is `IF NOT EXISTS`, so running it again
+ * against existing tables keeps every row. Nothing in this package performs DDL at
+ * runtime: a feed cannot conjure its own tables, so schema ownership stays with
+ * whoever owns the migrations.
+ */
+
+/** The feed tables' migration payload for `config`. */
+const ensureFeedSchema = (config = {}) => _effect.Effect.gen(function* () {
+  const sql = yield* _sql.SqlClient.SqlClient;
+  const names = (0, _ddl.resolveFeedNames)((0, _config.decodeFeedPostgresConfig)(config));
+  yield* _effect.Effect.all((0, _ddl.runFeedDdl)(sql, names), {
+    discard: true
+  });
+});
+exports.ensureFeedSchema = ensureFeedSchema;
+//# sourceMappingURL=ensureFeedSchema.js.map

package/dist/cjs/ensureFeedSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureFeedSchema.js","names":["_effect","require","_sql","_config","_ddl","ensureFeedSchema","config","Effect","gen","sql","SqlClient","names","resolveFeedNames","decodeFeedPostgresConfig","all","runFeedDdl","discard","exports"],"sources":["../../src/ensureFeedSchema.ts"],"sourcesContent":[null],"mappings":";;;;;;AAkBA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,IAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AACA,IAAAG,IAAA,GAAAH,OAAA;AArBA;;;;;;;;;;;;;;;;;;;AAuBA;AACO,MAAMI,gBAAgB,GAAGA,CAC9BC,MAAA,GAA6B,EAAE,KAE/BC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,GAAG,GAAG,OAAOC,cAAS,CAACA,SAAS;EACtC,MAAMC,KAAK,GAAG,IAAAC,qBAAgB,EAAC,IAAAC,gCAAwB,EAACP,MAAM,CAAC,CAAC;EAChE,OAAOC,cAAM,CAACO,GAAG,CAAC,IAAAC,eAAU,EAACN,GAAG,EAAEE,KAAK,CAAC,EAAE;IAAEK,OAAO,EAAE;EAAI,CAAE,CAAC;AAC9D,CAAC,CAAC;AAAAC,OAAA,CAAAZ,gBAAA,GAAAA,gBAAA","ignoreList":[]}

package/dist/cjs/feed.js

@@ -0,0 +1,176 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.makePostgresFeed = exports.eventStoreWake = exports.contextOf = void 0;
+var _core = require("@kairos-es/core");
+var _feed = require("@kairos-es/feed");
+var _effect = require("effect");
+var _sql = require("effect/sql");
+var _context = require("./internal/context.js");
+/**
+ * The Postgres feed's two faces: the `BatchedFeedWriter` a read model's `apply`
+ * writes through, and the `FeedSource` a sync worker tails.
+ *
+ * ## The writer rides the read model's own client
+ *
+ * A feed row must exist if and only if the view write and the checkpoint advance
+ * that produced it landed (ADR-0019 §2). `@kairos-es/read-postgres`'s `commit` is
+ * one transaction over the client the store was built from, and `effect/sql`
+ * carries that transaction in the Effect CONTEXT under a key that belongs to that
+ * one client instance (ADR-0018 §3). So the writer does not capture a client: it
+ * reads `SqlClient` from the context AT WRITE TIME, which inside `commit`'s
+ * `viewWrites` is the read model's own, and its statements join the open
+ * transaction and roll back with it on a lost guard. That is why `SqlClient` sits
+ * in the writer's `RW` and not in the factory's requirements alone. A write
+ * through any OTHER client instance is not bracketed, and the exactly-once
+ * property does not extend to it.
+ *
+ * ## What one `write` sends
+ *
+ * The body's upserts and removes are buffered, last write per key winning, and
+ * land as at most three statements whatever the batch size: the feed lock (see
+ * `internal/statements.ts` for why the writer takes it), one upsert of every
+ * changed document and one tombstone of every removed key. The upsert writes
+ * nothing for a document equal to the stored one, compared as `jsonb`, so key
+ * order is no change; the tombstone writes nothing for a key that is absent or
+ * already a tombstone.
+ *
+ * Each document is encoded through its `Schema` before anything is sent. A
+ * document that fails to encode is a DEFECT in the read model, not a fault of the
+ * feed and not something a sink should ever be asked to refuse.
+ *
+ * ## The source
+ *
+ * `changesAfter` pages the feed's rows by `seq`, tombstones included, and decodes
+ * each document through the same `Schema`. A stored document that no longer
+ * decodes is a defect too: it means the schema changed without the feed being
+ * rebuilt, which retrying cannot mend.
+ *
+ * `listen` is optional and is a WAKE only. This package takes no reserved
+ * connection for a `LISTEN` of its own, as `@kairos-es/read-postgres` takes none,
+ * so the poll is the guarantee. {@link eventStoreWake} offers the event store's
+ * `subscribe` as a wake: it fires when an event is appended, which is BEFORE the
+ * projection has applied it and written the feed, so a woken read may find nothing
+ * new and the poll picks the row up. It shortens the wait; it never decides
+ * correctness.
+ */
+
+/** The context a feed was built over, for `withFeed`. */
+const contexts = /*#__PURE__*/new WeakMap();
+/** @internal */
+const contextOf = feed => contexts.get(feed);
+/**
+ * Build a feed over the ambient `SqlClient`. Creates the feed's generations row
+ * if it is absent, at generation 0, so the writer's feed lock always has a row to
+ * take; that is the only write it makes. `ensureFeedSchema` must have run first.
+ */
+exports.contextOf = contextOf;
+const makePostgresFeed = options => _effect.Effect.gen(function* () {
+  const context = (0, _context.feedContext)(options.config ?? {});
+  const {
+    statements
+  } = context;
+  const feed = options.feed;
+  const sql = (yield* _sql.SqlClient.SqlClient).withoutTransforms();
+  const encode = _effect.Schema.encodeEffect(options.doc);
+  const decode = _effect.Schema.decodeUnknownEffect(options.doc);
+  yield* sql.unsafe(statements.ensureGeneration, [feed]).pipe(_effect.Effect.mapError((0, _context.writeFailed)(`creating the generation of feed '${feed}'`)));
+  const write = (at, body) => _effect.Effect.gen(function* () {
+    const buffer = new Map();
+    const set = (key, doc) => _effect.Effect.sync(() => {
+      buffer.delete(key);
+      buffer.set(key, doc);
+    });
+    const result = yield* body({
+      upsert: (key, doc) => set(key, _effect.Option.some(doc)),
+      remove: key => set(key, _effect.Option.none())
+    });
+    if (buffer.size === 0) {
+      return result;
+    }
+    const upserts = [];
+    const removes = [];
+    for (const [key, doc] of buffer) {
+      if (_effect.Option.isSome(doc)) {
+        upserts.push({
+          key,
+          doc: yield* _effect.Effect.orDie(encode(doc.value))
+        });
+      } else {
+        removes.push(key);
+      }
+    }
+    const upsertJson = upserts.length === 0 ? undefined : yield* _effect.Effect.try({
+      try: () => JSON.stringify(upserts),
+      catch: cause => new Error(`feed '${feed}': an encoded document is not JSON-serialisable`, {
+        cause
+      })
+    }).pipe(_effect.Effect.orDie);
+    // The read model's own client, from the context at write time; see the
+    // module doc. Transform-free, for the same reason the read side's store
+    // is: the copy keeps the original's transaction key.
+    const client = (yield* _sql.SqlClient.SqlClient).withoutTransforms();
+    const position = at.toString();
+    yield* client.withTransaction(_effect.Effect.gen(function* () {
+      yield* client.unsafe(statements.lockFeedShared, [feed]);
+      if (upsertJson !== undefined) {
+        yield* client.unsafe(statements.upsertRows, [feed, position, upsertJson]);
+      }
+      if (removes.length > 0) {
+        yield* client.unsafe(statements.tombstoneRows, [feed, position, JSON.stringify(removes)]);
+      }
+    })).pipe(_effect.Effect.mapError((0, _context.writeFailed)(`writing feed '${feed}'`)));
+    return result;
+  });
+  const decodeRow = row => _effect.Effect.gen(function* () {
+    // Bound to a `const` so the `null` check narrows inside the `try` below.
+    const stored = row.doc;
+    const doc = stored === null ? _effect.Option.none() : _effect.Option.some(yield* _effect.Effect.orDie(_effect.Effect.flatMap(_effect.Effect.try({
+      try: () => JSON.parse(stored),
+      catch: cause => new Error(`feed '${feed}': a stored document is not JSON`, {
+        cause
+      })
+    }), json => decode(json))));
+    return {
+      key: _feed.FeedKey.make(row.key),
+      doc,
+      seq: _feed.FeedSeq.make((0, _context.bigintOf)(row.seq)),
+      eventPosition: _core.Position.make((0, _context.bigintOf)(row.event_position))
+    };
+  });
+  const source = {
+    feed,
+    generation: sql.unsafe(statements.selectGeneration, [feed]).pipe(_effect.Effect.mapError((0, _context.unreadable)(`reading the generation of feed '${feed}'`)), _effect.Effect.map(rows => {
+      const stored = rows[0]?.generation;
+      return _feed.Generation.make(stored === undefined ? 0n : (0, _context.bigintOf)(stored));
+    })),
+    changesAfter: (after, limit) => sql.unsafe(statements.changesAfter, [feed, after.toString(), limit]).pipe(_effect.Effect.mapError((0, _context.unreadable)(`reading feed '${feed}'`)), _effect.Effect.flatMap(rows => _effect.Effect.forEach(rows, decodeRow))),
+    ...(options.listen === undefined ? {} : {
+      listen: options.listen
+    })
+  };
+  const result = {
+    feed,
+    write,
+    source
+  };
+  contexts.set(result, context);
+  return result;
+});
+/**
+ * A wake from the event store: one element per event matching `query` appended
+ * after the moment the stream is subscribed, and nothing else. Pass it as
+ * `listen`. Early by the projection's own lag, as the module doc says, so the
+ * worker's poll still bounds the latency; `query` should be the read model's own,
+ * so events it never applies wake nothing.
+ */
+exports.makePostgresFeed = makePostgresFeed;
+const eventStoreWake = query => _effect.Effect.gen(function* () {
+  const store = yield* _core.DcbEventStore;
+  const wake = _effect.Stream.unwrap(_effect.Effect.map(store.read(query), response => store.subscribe(query, response.head))).pipe(_effect.Stream.scoped, _effect.Stream.as(undefined));
+  return wake;
+});
+exports.eventStoreWake = eventStoreWake;
+//# sourceMappingURL=feed.js.map

package/dist/cjs/feed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.js","names":["_core","require","_feed","_effect","_sql","_context","contexts","WeakMap","contextOf","feed","get","exports","makePostgresFeed","options","Effect","gen","context","feedContext","config","statements","sql","SqlClient","withoutTransforms","encode","Schema","encodeEffect","doc","decode","decodeUnknownEffect","unsafe","ensureGeneration","pipe","mapError","writeFailed","write","at","body","buffer","Map","set","key","sync","delete","result","upsert","Option","some","remove","none","size","upserts","removes","isSome","push","orDie","value","upsertJson","length","undefined","try","JSON","stringify","catch","cause","Error","client","position","toString","withTransaction","lockFeedShared","upsertRows","tombstoneRows","decodeRow","row","stored","flatMap","parse","json","FeedKey","make","seq","FeedSeq","bigintOf","eventPosition","Position","event_position","source","generation","selectGeneration","unreadable","map","rows","Generation","changesAfter","after","limit","forEach","listen","eventStoreWake","query","store","DcbEventStore","wake","Stream","unwrap","read","response","subscribe","head","scoped","as"],"sources":["../../src/feed.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/cjs/index.js

@@ -0,0 +1,84 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "DEFAULT_LEASE_HEARTBEAT", {
+  enumerable: true,
+  get: function () {
+    return _lease.DEFAULT_LEASE_HEARTBEAT;
+  }
+});
+Object.defineProperty(exports, "DEFAULT_LEASE_TTL", {
+  enumerable: true,
+  get: function () {
+    return _lease.DEFAULT_LEASE_TTL;
+  }
+});
+Object.defineProperty(exports, "FeedPostgresConfig", {
+  enumerable: true,
+  get: function () {
+    return _config.FeedPostgresConfig;
+  }
+});
+Object.defineProperty(exports, "advisoryLock", {
+  enumerable: true,
+  get: function () {
+    return _lease.advisoryLock;
+  }
+});
+Object.defineProperty(exports, "decodeFeedPostgresConfig", {
+  enumerable: true,
+  get: function () {
+    return _config.decodeFeedPostgresConfig;
+  }
+});
+Object.defineProperty(exports, "ensureFeedSchema", {
+  enumerable: true,
+  get: function () {
+    return _ensureFeedSchema.ensureFeedSchema;
+  }
+});
+Object.defineProperty(exports, "eventStoreWake", {
+  enumerable: true,
+  get: function () {
+    return _feed.eventStoreWake;
+  }
+});
+Object.defineProperty(exports, "leaseRow", {
+  enumerable: true,
+  get: function () {
+    return _lease.leaseRow;
+  }
+});
+Object.defineProperty(exports, "makePostgresFeed", {
+  enumerable: true,
+  get: function () {
+    return _feed.makePostgresFeed;
+  }
+});
+Object.defineProperty(exports, "makePostgresFeedSyncStore", {
+  enumerable: true,
+  get: function () {
+    return _syncStore.makePostgresFeedSyncStore;
+  }
+});
+Object.defineProperty(exports, "pooledConnectionFault", {
+  enumerable: true,
+  get: function () {
+    return _lease.pooledConnectionFault;
+  }
+});
+Object.defineProperty(exports, "withFeed", {
+  enumerable: true,
+  get: function () {
+    return _withFeed.withFeed;
+  }
+});
+var _config = require("./config.js");
+var _ensureFeedSchema = require("./ensureFeedSchema.js");
+var _feed = require("./feed.js");
+var _lease = require("./lease.js");
+var _syncStore = require("./syncStore.js");
+var _withFeed = require("./withFeed.js");
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_config","require","_ensureFeedSchema","_feed","_lease","_syncStore","_withFeed"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,IAAAA,OAAA,GAAAC,OAAA;AAIA,IAAAC,iBAAA,GAAAD,OAAA;AACA,IAAAE,KAAA,GAAAF,OAAA;AAMA,IAAAG,MAAA,GAAAH,OAAA;AAQA,IAAAI,UAAA,GAAAJ,OAAA;AAIA,IAAAK,SAAA,GAAAL,OAAA","ignoreList":[]}

package/dist/cjs/internal/context.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.writeFailed = exports.unreadable = exports.feedContext = exports.bigintOf = void 0;
+var _feed = require("@kairos-es/feed");
+var _config = require("../config.js");
+var _ddl = require("./ddl.js");
+var _statements = require("./statements.js");
+/**
+ * What every part of this package shares about one config: the resolved names,
+ * the compiled statements, and the error mapping from `SqlError` to the feed's own
+ * two infrastructure errors.
+ *
+ * A `PostgresFeed` carries its context privately, in a `WeakMap` keyed by the
+ * feed value, so `withFeed` can reach the feed's names and statements without the
+ * public type growing a field no consumer should touch.
+ */
+
+/** Decode `config` and compile its statements; throws on a malformed config. */
+const feedContext = config => {
+  const names = (0, _ddl.resolveFeedNames)((0, _config.decodeFeedPostgresConfig)(config));
+  return {
+    names,
+    statements: (0, _statements.compileFeedStatements)(names)
+  };
+};
+/** A read that failed, named for what was being read. */
+exports.feedContext = feedContext;
+const unreadable = attempt => cause => new _feed.FeedUnreadable({
+  reason: `${attempt} failed: ${cause.message}`,
+  cause
+});
+/** A write that failed, named for what was being written. */
+exports.unreadable = unreadable;
+const writeFailed = attempt => cause => new _feed.FeedWriteFailed({
+  reason: `${attempt} failed: ${cause.message}`,
+  cause
+});
+/** A 64-bit column read back as text, as a `bigint`; see `statements.ts`. */
+exports.writeFailed = writeFailed;
+const bigintOf = text => BigInt(text);
+exports.bigintOf = bigintOf;
+//# sourceMappingURL=context.js.map

package/dist/cjs/internal/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","names":["_feed","require","_config","_ddl","_statements","feedContext","config","names","resolveFeedNames","decodeFeedPostgresConfig","statements","compileFeedStatements","exports","unreadable","attempt","cause","FeedUnreadable","reason","message","writeFailed","FeedWriteFailed","bigintOf","text","BigInt"],"sources":["../../../src/internal/context.ts"],"sourcesContent":[null],"mappings":";;;;;;AASA,IAAAA,KAAA,GAAAC,OAAA;AAEA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,IAAA,GAAAF,OAAA;AACA,IAAAG,WAAA,GAAAH,OAAA;AAbA;;;;;;;;;;AAqBA;AACO,MAAMI,WAAW,GAAIC,MAA0B,IAAiB;EACrE,MAAMC,KAAK,GAAG,IAAAC,qBAAgB,EAAC,IAAAC,gCAAwB,EAACH,MAAM,CAAC,CAAC;EAChE,OAAO;IAAEC,KAAK;IAAEG,UAAU,EAAE,IAAAC,iCAAqB,EAACJ,KAAK;EAAC,CAAE;AAC5D,CAAC;AAED;AAAAK,OAAA,CAAAP,WAAA,GAAAA,WAAA;AACO,MAAMQ,UAAU,GACpBC,OAAe,IACfC,KAAwB,IACvB,IAAIC,oBAAc,CAAC;EAAEC,MAAM,EAAE,GAAGH,OAAO,YAAYC,KAAK,CAACG,OAAO,EAAE;EAAEH;AAAK,CAAE,CAAC;AAEhF;AAAAH,OAAA,CAAAC,UAAA,GAAAA,UAAA;AACO,MAAMM,WAAW,GACrBL,OAAe,IACfC,KAAwB,IACvB,IAAIK,qBAAe,CAAC;EAClBH,MAAM,EAAE,GAAGH,OAAO,YAAYC,KAAK,CAACG,OAAO,EAAE;EAC7CH;CACD,CAAC;AAEN;AAAAH,OAAA,CAAAO,WAAA,GAAAA,WAAA;AACO,MAAME,QAAQ,GAAIC,IAA8B,IAAaC,MAAM,CAACD,IAAI,CAAC;AAAAV,OAAA,CAAAS,QAAA,GAAAA,QAAA","ignoreList":[]}