@kairos-es/feed-postgres 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,138 @@
+/**
+ * The sync worker's lease on Postgres, in the two kinds `FeedSyncStore`'s doc
+ * describes, chosen in config to suit the infrastructure in front of the
+ * database.
+ *
+ * ## Why there are two
+ *
+ * A worker lease is what keeps a feed's sends to a sink in order: a sink has no
+ * transaction, so a rival worker's stale send lands before any compare-and-set can
+ * catch it (ADR-0019 §5). The two kinds trade the same two things against each
+ * other — what the connection must be, and how long a lapsed worker can go on
+ * sending — and neither wins on both.
+ *
+ * - **`leaseRow`, the default.** The holder and an expiry live on the sink's
+ *   cursor row, taken with a guarded upsert (only when free, expired, or held by
+ *   an advisory worker whose session is gone; see below) and renewed by a
+ *   heartbeat forked into the lease's scope. Every statement is an ordinary short
+ *   one, and the take one short transaction, so it works through a TRANSACTION
+ *   POOLER, which drops session state and so rules out a session lock, and it
+ *   needs no reserved connection. Its cost is a window. `ensureHeld` fails a
+ *   MARGIN before the stored expiry: once the last successful renewal is
+ *   `ttl - margin` old by the worker's own `Clock`, that renewal's expiry, which is
+ *   when a rival may take the row, is at most `margin` away. So a call to the sink
+ *   that `ensureHeld` let through, and that lands within `margin` of that check,
+ *   pauses included, lands before any rival can hold the lease, however its
+ *   renewals have been failing meanwhile, as long as the two workers' clocks
+ *   agree. A call that outlasts the margin, whether it is slow or its worker
+ *   pauses (a long GC pause, a network stall), can land after a rival took over:
+ *   ONE stale call, since the next `ensureHeld` fails; `FeedSyncStore.ts` owns what
+ *   that call costs. The margin is `ttl / 3` unless configured, and must leave the
+ *   heartbeat room under the lease (`heartbeat + margin < ttl`), or `ensureHeld`
+ *   would fail between two renewals that both landed at once. Each renewal is
+ *   bounded by the heartbeat and the next starts on the next tick, and the age
+ *   `ensureHeld` judges runs from when a renewal STARTED. So a renewal that lands
+ *   is at most `heartbeat` late, and the worst age `ensureHeld` meets is
+ *   `heartbeat` plus that latency with every renewal landing, and `2 * heartbeat`
+ *   plus it with one lost. A worker therefore goes on sending, without a single
+ *   failed `ensureHeld`, through renewals that are slow when
+ *   `2 * heartbeat + margin <= ttl`, and through one that fails or hangs when
+ *   `3 * heartbeat + margin <= ttl`. The defaults satisfy the second; the
+ *   construction check enforces only the first's zero-latency form, so a tighter
+ *   config is accepted and trades those guarantees for a shorter `ttl`.
+ * - **`advisoryLock`.** A session `pg_try_advisory_lock` on a connection RESERVED
+ *   from a client the consumer dedicates to it, keyed by a hash of the prefix, the
+ *   feed and the sink. The lock goes when the session goes, and `ensureHeld` asks
+ *   that same session, before every call that changes the sink, whether it still
+ *   holds the lock; any failure to answer is a lost lease. So a process pause
+ *   opens no stale window, since the lock survives it. What a check cannot see is
+ *   the session dying AFTER it: the call it let through is already under way and
+ *   runs to its end, so it can land as late as its whole duration after the session
+ *   died, and after a rival has taken the lock and sent. That is still ONE stale
+ *   call, since the next `ensureHeld` asks a session that is gone, but a sink call
+ *   can be long — a resync's `publish` most of all. The price is a connection per
+ *   running worker, and a connection that is genuinely a SESSION: a transaction
+ *   pooler would hand the lock's session to somebody else between statements. A
+ *   client this package can recognise as one is refused at construction; see
+ *   {@link pooledConnectionFault} for what it can and cannot recognise.
+ *
+ * ## Fencing is the same for both
+ *
+ * Both kinds record the holder on the cursor row, and the cursor compare-and-set
+ * requires it, so a worker whose lease has gone cannot move the cursor whichever
+ * kind it held. Mixing the two kinds on one feed and sink fails safe, because
+ * neither takes the row from a LIVE holder of the other. A lease-row worker takes
+ * over an advisory holder (one with no expiry to lapse) only while it holds that
+ * sink's advisory lock for its own transaction, which a live advisory session
+ * refuses; so a crashed advisory worker, whose scope never closed to clear the row,
+ * does not leave the sink unleasable by every lease-row worker after it. An
+ * advisory worker that wins the lock but finds a lease row unexpired on the row lets
+ * the lock go and fails `LeaseHeld`. Whichever took the row first keeps it while it
+ * lives. The advisory worker likewise takes over an ADVISORY holder recorded on the
+ * row, because holding the lock proves that session is gone; it records itself
+ * from the session that holds the lock, and only while it still does, so a session
+ * that died after its try-lock cannot overwrite the successor that took the lock
+ * from it.
+ */
+import { type FeedLease, type FeedSinkId, type FeedUnreadable, type FeedWriteFailed, LeaseHeld } from '@kairos-es/feed';
+import { Duration, Effect, type Scope } from 'effect';
+import type { SqlClient } from 'effect/sql';
+/** The lease kind, as config carries it. See the module doc. */
+export type FeedLeaseConfig = {
+    readonly _tag: 'LeaseRow';
+    /** How long a lease lasts without a renewal. */
+    readonly ttl: Duration.Input;
+    /** How often the holder renews it; shorter than `ttl`. */
+    readonly heartbeat: Duration.Input;
+    /**
+     * How long before the stored expiry `ensureHeld` starts failing: a sink call
+     * that takes less than this cannot land after a rival took the lease. See
+     * the module doc. `ttl / 3` when absent; `heartbeat + margin` must be under
+     * `ttl`.
+     */
+    readonly margin?: Duration.Input;
+} | {
+    readonly _tag: 'AdvisoryLock';
+    /**
+     * A client used for nothing but leases, each lease reserving one connection
+     * from it for its lifetime. Its lifecycle is the consumer's, exactly as the
+     * main client's is.
+     */
+    readonly connection: SqlClient.SqlClient;
+};
+/** The default lease length. */
+export declare const DEFAULT_LEASE_TTL: Duration.Duration;
+/**
+ * The default renewal interval: a fifth of the lease. With the default margin, a
+ * third, `3 * heartbeat + margin` is under the `ttl`, so a worker goes on sending,
+ * with no failed `ensureHeld`, through one renewal that fails or hangs. However
+ * many fail, it stops sending a margin before its lease could lapse. The module
+ * doc has the arithmetic.
+ */
+export declare const DEFAULT_LEASE_HEARTBEAT: Duration.Duration;
+/** A lease row, the default; see the module doc. */
+export declare const leaseRow: (options?: {
+    readonly ttl?: Duration.Input;
+    readonly heartbeat?: Duration.Input;
+    readonly margin?: Duration.Input;
+}) => FeedLeaseConfig;
+/** A session advisory lock on a dedicated connection; see the module doc. */
+export declare const advisoryLock: (options: {
+    readonly connection: SqlClient.SqlClient;
+}) => FeedLeaseConfig;
+/**
+ * Why `client` cannot carry a session lock, when this package can tell, or
+ * `undefined`.
+ *
+ * What it can tell is limited to what a client says about where it connects,
+ * which `@effect/sql-pg`'s client exposes as `config` and a generic `SqlClient`
+ * does not. It recognises the two pooler conventions that show in an address: a
+ * Neon pooled endpoint (a host containing `-pooler`), and PgBouncer's default
+ * port, 6432, or a `pgbouncer=true` URL parameter. A pooler on any other address,
+ * or behind a client that exposes nothing, passes; that is a wiring the consumer
+ * owns. The URL is read only to judge it and is never repeated in the message.
+ */
+export declare const pooledConnectionFault: (client: SqlClient.SqlClient) => string | undefined;
+/** How a sync store takes a lease. Package-internal. */
+export type AcquireLease = (id: FeedSinkId) => Effect.Effect<FeedLease, LeaseHeld | FeedUnreadable | FeedWriteFailed, Scope.Scope>;
+//# sourceMappingURL=lease.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../../src/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,EAGV,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAEL,QAAQ,EACR,MAAM,EAKN,KAAK,KAAK,EACX,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAG3C,gEAAgE;AAChE,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAA;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAA;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAA;CACjC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,SAAS,CAAA;CACzC,CAAA;AAEL,gCAAgC;AAChC,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,QAA+B,CAAA;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,QAA8B,CAAA;AAE7E,oDAAoD;AACpD,eAAO,MAAM,QAAQ,GACnB,UAAS;IACP,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAA;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAA;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAA;CAC5B,KACL,eAKD,CAAA;AAEF,6EAA6E;AAC7E,eAAO,MAAM,YAAY,GAAI,SAAS;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,SAAS,CAAA;CACzC,KAAG,eAGF,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,SAAS,CAAC,SAAS,KAC1B,MAAM,GAAG,SAwCX,CAAA;AAED,wDAAwD;AACxD,MAAM,MAAM,YAAY,GAAG,CACzB,EAAE,EAAE,UAAU,KACX,MAAM,CAAC,MAAM,CAChB,SAAS,EACT,SAAS,GAAG,cAAc,GAAG,eAAe,EAC5C,KAAK,CAAC,KAAK,CACZ,CAAA"}

package/dist/dts-esm/package.json

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

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

@@ -0,0 +1,57 @@
+/**
+ * The Postgres `FeedSyncStore`: every sink's cursor, its parked list and its
+ * worker lease, kept in the source database beside the feed rows (ADR-0019 §10).
+ *
+ * `@kairos-es/feed`'s `FeedSyncStore.ts` owns the contract, and the in-memory feed
+ * is the oracle this store is held to; what is here is how each atomic step the
+ * contract names becomes one transaction or one statement.
+ *
+ * - `casCursor` is ONE transaction: the guarded, holder-fenced cursor update,
+ *   stamped with its `lastAdvance` from this process's `Clock`, and the parked
+ *   list moved with it. A guard that loses fails `CursorSuperseded` inside the
+ *   transaction, which rolls back the parked changes with it, so a park can never
+ *   outlive a refused advance.
+ * - `retryParked` is one transaction that takes the feed lock exclusively before it
+ *   re-stamps the row, so its new `seq` cannot commit out of order with the
+ *   materialisation's own writes (`internal/statements.ts` owns that argument).
+ * - `collectTombstones` is one statement that reads every registered sink's cursor
+ *   and deletes below the lowest, or nothing while any of them has no cursor, so
+ *   no cursor can move between the two.
+ * - `removeSink` is one transaction that first takes the sink's advisory lock for
+ *   its own length, which an advisory worker's session lock refuses, then deletes
+ *   the cursor row only when no live lease row holds it, in the same statement as
+ *   that test, and the parks after it. Both tests are therefore made whichever
+ *   lease kind this store was built with: a sink can be leased by either kind
+ *   (`lease.ts` owns how the two coexist), and the row alone cannot say whether
+ *   an advisory holder's session is alive.
+ * - `describe` is three reads, each its own snapshot, so a figure in it can be a
+ *   batch older or newer than the next. It is a report for an operator, and no
+ *   decision is taken on it.
+ *
+ * One store serves every feed in its prefix: unlike the in-memory feed, whose
+ * store belongs to one feed, a SQL store's state is keyed by feed name in shared
+ * tables, so a single store value is what every worker over the prefix takes.
+ *
+ * Infrastructure faults are `FeedUnreadable` on a read and `FeedWriteFailed` on a
+ * write, never defects, so the driver's supervision backs off and tries again.
+ */
+import { type FeedSyncStore } from '@kairos-es/feed';
+import { Effect } from 'effect';
+import { SqlClient } from 'effect/sql';
+import type { FeedPostgresConfig } from './config.js';
+import { type FeedLeaseConfig } from './lease.js';
+/** Options for {@link makePostgresFeedSyncStore}. */
+export interface PostgresFeedSyncStoreOptions {
+    /** The `{ schema, tablePrefix }` pair the feeds were written under. */
+    readonly config?: FeedPostgresConfig;
+    /** The lease kind; `leaseRow()` with its defaults when absent. */
+    readonly lease?: FeedLeaseConfig;
+}
+/**
+ * Build the sync store over the ambient `SqlClient`. Dies at construction on a
+ * malformed config, a lease whose heartbeat is not shorter than its ttl or leaves
+ * no room for its margin, or an `advisoryLock` connection recognisably pooled.
+ * `ensureFeedSchema` must have run.
+ */
+export declare const makePostgresFeedSyncStore: (options?: PostgresFeedSyncStoreOptions) => Effect.Effect<FeedSyncStore, never, SqlClient.SqlClient>;
+//# sourceMappingURL=syncStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncStore.d.ts","sourceRoot":"","sources":["../../src/syncStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAML,KAAK,aAAa,EAOnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAmB,MAAM,EAAU,MAAM,QAAQ,CAAA;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAOlD,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,SAAS,CAAA;AAEhB,qDAAqD;AACrD,MAAM,WAAW,4BAA4B;IAC3C,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;IACpC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;CACjC;AA0DD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,UAAS,4BAAiC,KACzC,MAAM,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,CAwMtD,CAAA"}

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

@@ -0,0 +1,69 @@
+/**
+ * `withFeed` — a `ProjectionStore` decorated so that resetting the checkpoint a
+ * feed is bound to also empties the feed and moves its generation on, in ONE
+ * transaction.
+ *
+ * ## Why a decorator
+ *
+ * Nothing in the library rebuilds a read model; a rebuild is an application
+ * resetting a checkpoint and letting the runner replay. A feed has to know when
+ * that happens, because a sink holding the old copy must be rebuilt from the
+ * replay rather than patched by it: a record the replay never writes again would
+ * otherwise survive in the sink. The reset is the one moment both facts are true,
+ * so the generation bump rides it.
+ *
+ * What it adds is the FEED's half of a rebuild and nothing more. A rebuild resets
+ * the checkpoint, drops the view, and starts again from `ORIGIN`; this resets the
+ * checkpoint and the feed, and the view is still the consumer's to drop. So
+ * rebuilding a DURABLE view means emptying it yourself before the replay, exactly
+ * as the port's own `resetCheckpoint` leaves it. Skip that and a row the replay
+ * never writes again survives in the view, and a read model whose `apply` reads
+ * its view back (a running count, say) builds on the old rows, which the feed
+ * then mirrors to every sink.
+ *
+ * The decorator keeps the port's three methods and replaces only
+ * `resetCheckpoint`, so it works through `forKey` exactly as the store does, and
+ * nothing about the read side has to know a feed exists.
+ *
+ * ## One transaction, and the client it needs
+ *
+ * The reset bumps the generation, deletes the checkpoint row through the store's
+ * own `resetCheckpoint`, and deletes the feed's rows, all inside one
+ * `withTransaction` on the client this decorator was built over. The store's own
+ * statement joins that transaction only when the store was built from the SAME
+ * client instance (ADR-0018 §3), which `@kairos-es/read-postgres`'s
+ * `makeSqlProjectionStore` is when both are built under one `SqlClient`. Build
+ * them apart and the checkpoint delete commits on its own: the reset still
+ * happens, but not atomically with the bump.
+ *
+ * The generation is bumped FIRST. That takes the feed lock exclusively, so a
+ * materialisation commit in flight finishes before the reset proceeds, and one
+ * that starts after it waits; and it takes the locks in the same order a commit
+ * does (the feed, then the checkpoint), so the two cannot deadlock. A commit that
+ * was mid-flight with the old checkpoint then loses its guard and rolls its feed
+ * rows back with its view.
+ *
+ * ## The binding
+ *
+ * A feed serves ONE materialisation, because one writer is what keeps its `seq`
+ * ascending in commit order. The binding is recorded on the feed's generations
+ * row the first time the feed is decorated, and checked at every construction
+ * after that, so a feed bound to another checkpoint key is refused across
+ * processes, not only within one. A refusal is a defect, as the read side's
+ * construction gate's are.
+ *
+ * The decorated store must be DURABLE. This feed is, and the feed's rows are
+ * written inside the store's commit transaction: an ephemeral store opens no
+ * transaction for them to join.
+ */
+import type { FeedWriteFailed } from '@kairos-es/feed';
+import { type CheckpointKey, type ProjectionStore } from '@kairos-es/read';
+import { Effect } from 'effect';
+import { SqlClient } from 'effect/sql';
+import { type PostgresFeed } from './feed.js';
+/**
+ * `store`, with `resetCheckpoint` for `key` also emptying `feed` and moving its
+ * generation on; see the module doc. Every other key passes through untouched.
+ */
+export declare const withFeed: <D>(store: ProjectionStore, feed: PostgresFeed<D>, key: CheckpointKey) => Effect.Effect<ProjectionStore, FeedWriteFailed, SqlClient.SqlClient>;
+//# sourceMappingURL=withFeed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"withFeed.d.ts","sourceRoot":"","sources":["../../src/withFeed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACtD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAA;AAMrD;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EACxB,OAAO,eAAe,EACtB,MAAM,YAAY,CAAC,CAAC,CAAC,EACrB,KAAK,aAAa,KACjB,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,eAAe,EAAE,SAAS,CAAC,SAAS,CAmElE,CAAA"}

package/dist/esm/config.js

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+import { Schema } from 'effect';
+import { oversizedIdentifier } from "./internal/ddl.js";
+/** A single identifier atom: non-empty and dot-free. */
+const IdentifierAtom = /*#__PURE__*/Schema.String.check(/*#__PURE__*/Schema.isNonEmpty(), /*#__PURE__*/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).
+ */
+export const FeedPostgresConfig = /*#__PURE__*/Schema.Struct({
+  schema: Schema.optionalKey(IdentifierAtom),
+  tablePrefix: Schema.optionalKey(IdentifierAtom)
+}).check(/*#__PURE__*/Schema.makeFilter(config => oversizedIdentifier(config)));
+/** Decode a config, throwing a `SchemaError` on any violation. */
+export const decodeFeedPostgresConfig = /*#__PURE__*/Schema.decodeUnknownSync(FeedPostgresConfig);
+//# sourceMappingURL=config.js.map

package/dist/esm/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":["Schema","oversizedIdentifier","IdentifierAtom","String","check","isNonEmpty","isPattern","identifier","description","FeedPostgresConfig","Struct","schema","optionalKey","tablePrefix","makeFilter","config","decodeFeedPostgresConfig","decodeUnknownSync"],"sources":["../../src/config.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;AAkBA,SAASA,MAAM,QAAQ,QAAQ;AAC/B,SAASC,mBAAmB,QAAQ,mBAAgB;AAEpD;AACA,MAAMC,cAAc,gBAAGF,MAAM,CAACG,MAAM,CAACC,KAAK,cACxCJ,MAAM,CAACK,UAAU,EAAE,eACnBL,MAAM,CAACM,SAAS,CAAC,SAAS,EAAE;EAC1BC,UAAU,EAAE,wBAAwB;EACpCC,WAAW,EAAE;CACd,CAAC,CACH;AAED;;;;;;;AAOA,OAAO,MAAMC,kBAAkB,gBAAGT,MAAM,CAACU,MAAM,CAAC;EAC9CC,MAAM,EAAEX,MAAM,CAACY,WAAW,CAACV,cAAc,CAAC;EAC1CW,WAAW,EAAEb,MAAM,CAACY,WAAW,CAACV,cAAc;CAC/C,CAAC,CAACE,KAAK,cAACJ,MAAM,CAACc,UAAU,CAAEC,MAAM,IAAKd,mBAAmB,CAACc,MAAM,CAAC,CAAC,CAAC;AAGpE;AACA,OAAO,MAAMC,wBAAwB,gBACnChB,MAAM,CAACiB,iBAAiB,CAACR,kBAAkB,CAAC","ignoreList":[]}

package/dist/esm/ensureFeedSchema.js

@@ -0,0 +1,31 @@
+/**
+ * `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.
+ */
+import { Effect } from 'effect';
+import { SqlClient } from 'effect/sql';
+import { decodeFeedPostgresConfig } from "./config.js";
+import { resolveFeedNames, runFeedDdl } from "./internal/ddl.js";
+/** The feed tables' migration payload for `config`. */
+export const ensureFeedSchema = (config = {}) => Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+  const names = resolveFeedNames(decodeFeedPostgresConfig(config));
+  yield* Effect.all(runFeedDdl(sql, names), {
+    discard: true
+  });
+});
+//# sourceMappingURL=ensureFeedSchema.js.map

package/dist/esm/ensureFeedSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureFeedSchema.js","names":["Effect","SqlClient","decodeFeedPostgresConfig","resolveFeedNames","runFeedDdl","ensureFeedSchema","config","gen","sql","names","all","discard"],"sources":["../../src/ensureFeedSchema.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;AAkBA,SAASA,MAAM,QAAQ,QAAQ;AAC/B,SAASC,SAAS,QAAuB,YAAY;AACrD,SAASC,wBAAwB,QAAiC,aAAU;AAC5E,SAASC,gBAAgB,EAAEC,UAAU,QAAQ,mBAAgB;AAE7D;AACA,OAAO,MAAMC,gBAAgB,GAAGA,CAC9BC,MAAA,GAA6B,EAAE,KAE/BN,MAAM,CAACO,GAAG,CAAC,aAAS;EAClB,MAAMC,GAAG,GAAG,OAAOP,SAAS,CAACA,SAAS;EACtC,MAAMQ,KAAK,GAAGN,gBAAgB,CAACD,wBAAwB,CAACI,MAAM,CAAC,CAAC;EAChE,OAAON,MAAM,CAACU,GAAG,CAACN,UAAU,CAACI,GAAG,EAAEC,KAAK,CAAC,EAAE;IAAEE,OAAO,EAAE;EAAI,CAAE,CAAC;AAC9D,CAAC,CAAC","ignoreList":[]}

package/dist/esm/feed.js

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+import { DcbEventStore, Position } from '@kairos-es/core';
+import { FeedKey, FeedSeq, Generation } from '@kairos-es/feed';
+import { Effect, Option, Schema, Stream } from 'effect';
+import { SqlClient } from 'effect/sql';
+import { bigintOf, feedContext, unreadable, writeFailed } from "./internal/context.js";
+/** The context a feed was built over, for `withFeed`. */
+const contexts = /*#__PURE__*/new WeakMap();
+/** @internal */
+export 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.
+ */
+export const makePostgresFeed = options => Effect.gen(function* () {
+  const context = feedContext(options.config ?? {});
+  const {
+    statements
+  } = context;
+  const feed = options.feed;
+  const sql = (yield* SqlClient.SqlClient).withoutTransforms();
+  const encode = Schema.encodeEffect(options.doc);
+  const decode = Schema.decodeUnknownEffect(options.doc);
+  yield* sql.unsafe(statements.ensureGeneration, [feed]).pipe(Effect.mapError(writeFailed(`creating the generation of feed '${feed}'`)));
+  const write = (at, body) => Effect.gen(function* () {
+    const buffer = new Map();
+    const set = (key, doc) => Effect.sync(() => {
+      buffer.delete(key);
+      buffer.set(key, doc);
+    });
+    const result = yield* body({
+      upsert: (key, doc) => set(key, Option.some(doc)),
+      remove: key => set(key, Option.none())
+    });
+    if (buffer.size === 0) {
+      return result;
+    }
+    const upserts = [];
+    const removes = [];
+    for (const [key, doc] of buffer) {
+      if (Option.isSome(doc)) {
+        upserts.push({
+          key,
+          doc: yield* Effect.orDie(encode(doc.value))
+        });
+      } else {
+        removes.push(key);
+      }
+    }
+    const upsertJson = upserts.length === 0 ? undefined : yield* Effect.try({
+      try: () => JSON.stringify(upserts),
+      catch: cause => new Error(`feed '${feed}': an encoded document is not JSON-serialisable`, {
+        cause
+      })
+    }).pipe(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* SqlClient.SqlClient).withoutTransforms();
+    const position = at.toString();
+    yield* client.withTransaction(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.mapError(writeFailed(`writing feed '${feed}'`)));
+    return result;
+  });
+  const decodeRow = row => Effect.gen(function* () {
+    // Bound to a `const` so the `null` check narrows inside the `try` below.
+    const stored = row.doc;
+    const doc = stored === null ? Option.none() : Option.some(yield* Effect.orDie(Effect.flatMap(Effect.try({
+      try: () => JSON.parse(stored),
+      catch: cause => new Error(`feed '${feed}': a stored document is not JSON`, {
+        cause
+      })
+    }), json => decode(json))));
+    return {
+      key: FeedKey.make(row.key),
+      doc,
+      seq: FeedSeq.make(bigintOf(row.seq)),
+      eventPosition: Position.make(bigintOf(row.event_position))
+    };
+  });
+  const source = {
+    feed,
+    generation: sql.unsafe(statements.selectGeneration, [feed]).pipe(Effect.mapError(unreadable(`reading the generation of feed '${feed}'`)), Effect.map(rows => {
+      const stored = rows[0]?.generation;
+      return Generation.make(stored === undefined ? 0n : bigintOf(stored));
+    })),
+    changesAfter: (after, limit) => sql.unsafe(statements.changesAfter, [feed, after.toString(), limit]).pipe(Effect.mapError(unreadable(`reading feed '${feed}'`)), Effect.flatMap(rows => 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.
+ */
+export const eventStoreWake = query => Effect.gen(function* () {
+  const store = yield* DcbEventStore;
+  const wake = Stream.unwrap(Effect.map(store.read(query), response => store.subscribe(query, response.head))).pipe(Stream.scoped, Stream.as(undefined));
+  return wake;
+});
+//# sourceMappingURL=feed.js.map

package/dist/esm/feed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.js","names":["DcbEventStore","Position","FeedKey","FeedSeq","Generation","Effect","Option","Schema","Stream","SqlClient","bigintOf","feedContext","unreadable","writeFailed","contexts","WeakMap","contextOf","feed","get","makePostgresFeed","options","gen","context","config","statements","sql","withoutTransforms","encode","encodeEffect","doc","decode","decodeUnknownEffect","unsafe","ensureGeneration","pipe","mapError","write","at","body","buffer","Map","set","key","sync","delete","result","upsert","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","make","seq","eventPosition","event_position","source","generation","selectGeneration","map","rows","changesAfter","after","limit","forEach","listen","eventStoreWake","query","store","wake","unwrap","read","response","subscribe","head","scoped","as"],"sources":["../../src/feed.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,SACEA,aAAa,EACbC,QAAQ,QAGH,iBAAiB;AACxB,SAEEC,OAAO,EAGPC,OAAO,EAKPC,UAAU,QACL,iBAAiB;AACxB,SAASC,MAAM,EAAEC,MAAM,EAAEC,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AACvD,SAASC,SAAS,QAAQ,YAAY;AAEtC,SACEC,QAAQ,EAERC,WAAW,EACXC,UAAU,EACVC,WAAW,QACN,uBAAoB;AAmB3B;AACA,MAAMC,QAAQ,gBAAG,IAAIC,OAAO,EAAuB;AAEnD;AACA,OAAO,MAAMC,SAAS,GACpBC,IAA2B,IACCH,QAAQ,CAACI,GAAG,CAACD,IAAI,CAAC;AAShD;;;;;AAKA,OAAO,MAAME,gBAAgB,GAC3BC,OAAkC,IAElCf,MAAM,CAACgB,GAAG,CAAC,aAAS;EAClB,MAAMC,OAAO,GAAGX,WAAW,CAACS,OAAO,CAACG,MAAM,IAAI,EAAE,CAAC;EACjD,MAAM;IAAEC;EAAU,CAAE,GAAGF,OAAO;EAC9B,MAAML,IAAI,GAAGG,OAAO,CAACH,IAAI;EACzB,MAAMQ,GAAG,GAAG,CAAC,OAAOhB,SAAS,CAACA,SAAS,EAAEiB,iBAAiB,EAAE;EAC5D,MAAMC,MAAM,GAAGpB,MAAM,CAACqB,YAAY,CAACR,OAAO,CAACS,GAAG,CAAC;EAC/C,MAAMC,MAAM,GAAGvB,MAAM,CAACwB,mBAAmB,CAACX,OAAO,CAACS,GAAG,CAAC;EAEtD,OAAOJ,GAAG,CACPO,MAAM,CAACR,UAAU,CAACS,gBAAgB,EAAE,CAAChB,IAAI,CAAC,CAAC,CAC3CiB,IAAI,CACH7B,MAAM,CAAC8B,QAAQ,CACbtB,WAAW,CAAC,oCAAoCI,IAAI,GAAG,CAAC,CACzD,CACF;EAEH,MAAMmB,KAAK,GAAGA,CACZC,EAAY,EACZC,IAAuD,KAEvDjC,MAAM,CAACgB,GAAG,CAAC,aAAS;IAClB,MAAMkB,MAAM,GAAG,IAAIC,GAAG,EAA6B;IACnD,MAAMC,GAAG,GAAGA,CAACC,GAAY,EAAEb,GAAqB,KAC9CxB,MAAM,CAACsC,IAAI,CAAC,MAAK;MACfJ,MAAM,CAACK,MAAM,CAACF,GAAG,CAAC;MAClBH,MAAM,CAACE,GAAG,CAACC,GAAG,EAAEb,GAAG,CAAC;IACtB,CAAC,CAAC;IACJ,MAAMgB,MAAM,GAAG,OAAOP,IAAI,CAAC;MACzBQ,MAAM,EAAEA,CAACJ,GAAG,EAAEb,GAAG,KAAKY,GAAG,CAACC,GAAG,EAAEpC,MAAM,CAACyC,IAAI,CAAClB,GAAG,CAAC,CAAC;MAChDmB,MAAM,EAAGN,GAAG,IAAKD,GAAG,CAACC,GAAG,EAAEpC,MAAM,CAAC2C,IAAI,EAAE;KACxC,CAAC;IACF,IAAIV,MAAM,CAACW,IAAI,KAAK,CAAC,EAAE;MACrB,OAAOL,MAAM;IACf;IACA,MAAMM,OAAO,GAAsD,EAAE;IACrE,MAAMC,OAAO,GAAmB,EAAE;IAClC,KAAK,MAAM,CAACV,GAAG,EAAEb,GAAG,CAAC,IAAIU,MAAM,EAAE;MAC/B,IAAIjC,MAAM,CAAC+C,MAAM,CAACxB,GAAG,CAAC,EAAE;QACtBsB,OAAO,CAACG,IAAI,CAAC;UAAEZ,GAAG;UAAEb,GAAG,EAAE,OAAOxB,MAAM,CAACkD,KAAK,CAAC5B,MAAM,CAACE,GAAG,CAAC2B,KAAK,CAAC;QAAC,CAAE,CAAC;MACpE,CAAC,MAAM;QACLJ,OAAO,CAACE,IAAI,CAACZ,GAAG,CAAC;MACnB;IACF;IACA,MAAMe,UAAU,GACdN,OAAO,CAACO,MAAM,KAAK,CAAC,GAChBC,SAAS,GACT,OAAOtD,MAAM,CAACuD,GAAG,CAAC;MAChBA,GAAG,EAAEA,CAAA,KAAMC,IAAI,CAACC,SAAS,CAACX,OAAO,CAAC;MAClCY,KAAK,EAAGC,KAAK,IACX,IAAIC,KAAK,CACP,SAAShD,IAAI,iDAAiD,EAC9D;QAAE+C;MAAK,CAAE;KAEd,CAAC,CAAC9B,IAAI,CAAC7B,MAAM,CAACkD,KAAK,CAAC;IAC3B;IACA;IACA;IACA,MAAMW,MAAM,GAAG,CAAC,OAAOzD,SAAS,CAACA,SAAS,EAAEiB,iBAAiB,EAAE;IAC/D,MAAMyC,QAAQ,GAAG9B,EAAE,CAAC+B,QAAQ,EAAE;IAC9B,OAAOF,MAAM,CACVG,eAAe,CACdhE,MAAM,CAACgB,GAAG,CAAC,aAAS;MAClB,OAAO6C,MAAM,CAAClC,MAAM,CAACR,UAAU,CAAC8C,cAAc,EAAE,CAACrD,IAAI,CAAC,CAAC;MACvD,IAAIwC,UAAU,KAAKE,SAAS,EAAE;QAC5B,OAAOO,MAAM,CAAClC,MAAM,CAACR,UAAU,CAAC+C,UAAU,EAAE,CAC1CtD,IAAI,EACJkD,QAAQ,EACRV,UAAU,CACX,CAAC;MACJ;MACA,IAAIL,OAAO,CAACM,MAAM,GAAG,CAAC,EAAE;QACtB,OAAOQ,MAAM,CAAClC,MAAM,CAACR,UAAU,CAACgD,aAAa,EAAE,CAC7CvD,IAAI,EACJkD,QAAQ,EACRN,IAAI,CAACC,SAAS,CAACV,OAAO,CAAC,CACxB,CAAC;MACJ;IACF,CAAC,CAAC,CACH,CACAlB,IAAI,CAAC7B,MAAM,CAAC8B,QAAQ,CAACtB,WAAW,CAAC,iBAAiBI,IAAI,GAAG,CAAC,CAAC,CAAC;IAC/D,OAAO4B,MAAM;EACf,CAAC,CAAC;EAEJ,MAAM4B,SAAS,GAAIC,GAAc,IAC/BrE,MAAM,CAACgB,GAAG,CAAC,aAAS;IAClB;IACA,MAAMsD,MAAM,GAAGD,GAAG,CAAC7C,GAAG;IACtB,MAAMA,GAAG,GACP8C,MAAM,KAAK,IAAI,GACXrE,MAAM,CAAC2C,IAAI,EAAK,GAChB3C,MAAM,CAACyC,IAAI,CACT,OAAO1C,MAAM,CAACkD,KAAK,CACjBlD,MAAM,CAACuE,OAAO,CACZvE,MAAM,CAACuD,GAAG,CAAC;MACTA,GAAG,EAAEA,CAAA,KAAMC,IAAI,CAACgB,KAAK,CAACF,MAAM,CAAY;MACxCZ,KAAK,EAAGC,KAAK,IACX,IAAIC,KAAK,CACP,SAAShD,IAAI,kCAAkC,EAC/C;QACE+C;OACD;KAEN,CAAC,EACDc,IAAI,IAAKhD,MAAM,CAACgD,IAAI,CAAC,CACvB,CACF,CACF;IACP,OAAO;MACLpC,GAAG,EAAExC,OAAO,CAAC6E,IAAI,CAACL,GAAG,CAAChC,GAAG,CAAC;MAC1Bb,GAAG;MACHmD,GAAG,EAAE7E,OAAO,CAAC4E,IAAI,CAACrE,QAAQ,CAACgE,GAAG,CAACM,GAAG,CAAC,CAAC;MACpCC,aAAa,EAAEhF,QAAQ,CAAC8E,IAAI,CAACrE,QAAQ,CAACgE,GAAG,CAACQ,cAAc,CAAC;KAC1D;EACH,CAAC,CAAC;EAEJ,MAAMC,MAAM,GAAkB;IAC5BlE,IAAI;IACJmE,UAAU,EAAE3D,GAAG,CACZO,MAAM,CAAkCR,UAAU,CAAC6D,gBAAgB,EAAE,CACpEpE,IAAI,CACL,CAAC,CACDiB,IAAI,CACH7B,MAAM,CAAC8B,QAAQ,CACbvB,UAAU,CAAC,mCAAmCK,IAAI,GAAG,CAAC,CACvD,EACDZ,MAAM,CAACiF,GAAG,CAAEC,IAAI,IAAI;MAClB,MAAMZ,MAAM,GAAGY,IAAI,CAAC,CAAC,CAAC,EAAEH,UAAU;MAClC,OAAOhF,UAAU,CAAC2E,IAAI,CAACJ,MAAM,KAAKhB,SAAS,GAAG,EAAE,GAAGjD,QAAQ,CAACiE,MAAM,CAAC,CAAC;IACtE,CAAC,CAAC,CACH;IACHa,YAAY,EAAEA,CAACC,KAAc,EAAEC,KAAgB,KAC7CjE,GAAG,CACAO,MAAM,CAAYR,UAAU,CAACgE,YAAY,EAAE,CAC1CvE,IAAI,EACJwE,KAAK,CAACrB,QAAQ,EAAE,EAChBsB,KAAK,CACN,CAAC,CACDxD,IAAI,CACH7B,MAAM,CAAC8B,QAAQ,CAACvB,UAAU,CAAC,iBAAiBK,IAAI,GAAG,CAAC,CAAC,EACrDZ,MAAM,CAACuE,OAAO,CAAEW,IAAI,IAAKlF,MAAM,CAACsF,OAAO,CAACJ,IAAI,EAAEd,SAAS,CAAC,CAAC,CAC1D;IACL,IAAIrD,OAAO,CAACwE,MAAM,KAAKjC,SAAS,GAAG,EAAE,GAAG;MAAEiC,MAAM,EAAExE,OAAO,CAACwE;IAAM,CAAE;GACnE;EAED,MAAM/C,MAAM,GAAoB;IAAE5B,IAAI;IAAEmB,KAAK;IAAE+C;EAAM,CAAE;EACvDrE,QAAQ,CAAC2B,GAAG,CAACI,MAAM,EAAEvB,OAAO,CAAC;EAC7B,OAAOuB,MAAM;AACf,CAAC,CAAC;AAEJ;;;;;;;AAOA,OAAO,MAAMgD,cAAc,GACzBC,KAAY,IAEZzF,MAAM,CAACgB,GAAG,CAAC,aAAS;EAClB,MAAM0E,KAAK,GAAG,OAAO/F,aAAa;EAClC,MAAMgG,IAAI,GAA2BxF,MAAM,CAACyF,MAAM,CAChD5F,MAAM,CAACiF,GAAG,CAACS,KAAK,CAACG,IAAI,CAACJ,KAAK,CAAC,EAAGK,QAAQ,IACrCJ,KAAK,CAACK,SAAS,CAACN,KAAK,EAAEK,QAAQ,CAACE,IAAI,CAAC,CACtC,CACF,CAACnE,IAAI,CAAC1B,MAAM,CAAC8F,MAAM,EAAE9F,MAAM,CAAC+F,EAAE,CAAC5C,SAAS,CAAC,CAAC;EAC3C,OAAOqC,IAAI;AACb,CAAC,CAAC","ignoreList":[]}

package/dist/esm/index.js

@@ -0,0 +1,50 @@
+/**
+ * @kairos-es/feed-postgres — the Postgres change feed: the feed tables and their
+ * idempotent DDL, the `FeedWriter` that rides a read model's own `SqlClient`
+ * inside its commit, the `FeedSource`, the `FeedSyncStore` with its worker lease,
+ * and the store decorator that moves the feed's generation on a reset
+ * (ADR-0019).
+ *
+ * A package of its own rather than part of `@kairos-es/read-postgres`, so that a
+ * read model with no feed gains no `@kairos-es/feed` peer (ADR-0003). It needs
+ * only the GENERIC `SqlClient`, and takes no reserved connection unless the
+ * consumer chooses the advisory-lock lease and dedicates one to it.
+ *
+ * Where each part's argument lives:
+ *
+ * - `config.ts` and `internal/ddl.ts` — the `{ schema, tablePrefix }` pair and the
+ *   five objects derived from it; `ensureFeedSchema.ts` — the migration payload.
+ * - `internal/statements.ts` — every statement the package sends, and the feed
+ *   lock that keeps `seq` ascending in commit order.
+ * - `feed.ts` — the writer, the source and the wake.
+ * - `syncStore.ts` — the cursor, the parked list and their atomic steps.
+ * - `lease.ts` — the two lease kinds, and what each costs.
+ * - `withFeed.ts` — the reset, the generation and the binding.
+ *
+ * Wiring, end to end:
+ *
+ * ```ts
+ * const config = { schema: 'public', tablePrefix: 'dcb_events' }
+ * const key = checkpointKey(ProjectionId.make('course-search'))
+ *
+ * // 1. In YOUR migrator, beside `ensureSchema` and `ensureCheckpointSchema`:
+ * //    ensureFeedSchema(config)
+ *
+ * // 2. Where the read model is wired, under ONE SqlClient:
+ * const feed = yield* makePostgresFeed({ config, feed: FeedName.make('course-search'), doc: CourseDoc })
+ * const store = yield* withFeed(yield* makeSqlProjectionStore(config), feed, key)
+ * // …and in the read model's `apply`, inside `commit`:
+ * //    feed.write(lastPosition, (writer) => writer.upsert(FeedKey.make(id), toDoc(course)))
+ *
+ * // 3. Beside the projections, one worker per feed and sink:
+ * const syncStore = yield* makePostgresFeedSyncStore({ config })
+ * yield* Effect.forkScoped(runFeedSync({ source: feed.source, sink, store: syncStore }))
+ * ```
+ */
+export { decodeFeedPostgresConfig, FeedPostgresConfig } from "./config.js";
+export { ensureFeedSchema } from "./ensureFeedSchema.js";
+export { eventStoreWake, makePostgresFeed } from "./feed.js";
+export { advisoryLock, DEFAULT_LEASE_HEARTBEAT, DEFAULT_LEASE_TTL, leaseRow, pooledConnectionFault } from "./lease.js";
+export { makePostgresFeedSyncStore } from "./syncStore.js";
+export { withFeed } from "./withFeed.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["decodeFeedPostgresConfig","FeedPostgresConfig","ensureFeedSchema","eventStoreWake","makePostgresFeed","advisoryLock","DEFAULT_LEASE_HEARTBEAT","DEFAULT_LEASE_TTL","leaseRow","pooledConnectionFault","makePostgresFeedSyncStore","withFeed"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,SACEA,wBAAwB,EACxBC,kBAAkB,QACb,aAAU;AACjB,SAASC,gBAAgB,QAAQ,uBAAoB;AACrD,SACEC,cAAc,EACdC,gBAAgB,QAGX,WAAQ;AACf,SACEC,YAAY,EACZC,uBAAuB,EACvBC,iBAAiB,EAEjBC,QAAQ,EACRC,qBAAqB,QAChB,YAAS;AAChB,SACEC,yBAAyB,QAEpB,gBAAa;AACpB,SAASC,QAAQ,QAAQ,eAAY","ignoreList":[]}

package/dist/esm/internal/context.js

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+import { FeedUnreadable, FeedWriteFailed } from '@kairos-es/feed';
+import { decodeFeedPostgresConfig } from "../config.js";
+import { resolveFeedNames } from "./ddl.js";
+import { compileFeedStatements } from "./statements.js";
+/** Decode `config` and compile its statements; throws on a malformed config. */
+export const feedContext = config => {
+  const names = resolveFeedNames(decodeFeedPostgresConfig(config));
+  return {
+    names,
+    statements: compileFeedStatements(names)
+  };
+};
+/** A read that failed, named for what was being read. */
+export const unreadable = attempt => cause => new FeedUnreadable({
+  reason: `${attempt} failed: ${cause.message}`,
+  cause
+});
+/** A write that failed, named for what was being written. */
+export const writeFailed = attempt => cause => new FeedWriteFailed({
+  reason: `${attempt} failed: ${cause.message}`,
+  cause
+});
+/** A 64-bit column read back as text, as a `bigint`; see `statements.ts`. */
+export const bigintOf = text => BigInt(text);
+//# sourceMappingURL=context.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","names":["FeedUnreadable","FeedWriteFailed","decodeFeedPostgresConfig","resolveFeedNames","compileFeedStatements","feedContext","config","names","statements","unreadable","attempt","cause","reason","message","writeFailed","bigintOf","text","BigInt"],"sources":["../../../src/internal/context.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;AASA,SAASA,cAAc,EAAEC,eAAe,QAAQ,iBAAiB;AAEjE,SAASC,wBAAwB,QAAiC,cAAW;AAC7E,SAAiCC,gBAAgB,QAAQ,UAAO;AAChE,SAASC,qBAAqB,QAA6B,iBAAc;AAQzE;AACA,OAAO,MAAMC,WAAW,GAAIC,MAA0B,IAAiB;EACrE,MAAMC,KAAK,GAAGJ,gBAAgB,CAACD,wBAAwB,CAACI,MAAM,CAAC,CAAC;EAChE,OAAO;IAAEC,KAAK;IAAEC,UAAU,EAAEJ,qBAAqB,CAACG,KAAK;EAAC,CAAE;AAC5D,CAAC;AAED;AACA,OAAO,MAAME,UAAU,GACpBC,OAAe,IACfC,KAAwB,IACvB,IAAIX,cAAc,CAAC;EAAEY,MAAM,EAAE,GAAGF,OAAO,YAAYC,KAAK,CAACE,OAAO,EAAE;EAAEF;AAAK,CAAE,CAAC;AAEhF;AACA,OAAO,MAAMG,WAAW,GACrBJ,OAAe,IACfC,KAAwB,IACvB,IAAIV,eAAe,CAAC;EAClBW,MAAM,EAAE,GAAGF,OAAO,YAAYC,KAAK,CAACE,OAAO,EAAE;EAC7CF;CACD,CAAC;AAEN;AACA,OAAO,MAAMI,QAAQ,GAAIC,IAA8B,IAAaC,MAAM,CAACD,IAAI,CAAC","ignoreList":[]}