@kairos-es/feed 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,110 @@
-# Temporary Holding Version
+# @kairos-es/feed
 
-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.
+A state-only change feed for kairos-es. A read model writes the newest state of each record it touches into a **feed**, inside the same commit as its view and its checkpoint. A **sync worker** copies the rows past its cursor to a **sink** (a search index, a cache, a mirror) and moves its cursor only once the sink confirms them. Use it for a target that has no transaction of its own and so cannot be a `ProjectionStore` (ADR-0019).
+
+The feed copies **state**: each record once per batch, at its newest version, however many events touched it, and a delete when the read model removes it. It never tells anyone each thing that happened; for that, use `@kairos-es/automation`.
+
+This package holds the ports, the driver and the in-memory implementations every other backend is held against:
+
+- `FeedWriter` / `BatchedFeedWriter` (what a read model writes) and `FeedSource` (what a worker reads);
+- `FeedSink`, with its optional `FeedResync` and `FeedReconcile` parts;
+- `FeedSyncStore`, the worker's cursor, parked list and lease;
+- `runFeedSync`, the worker, with `materialisationCaughtUp` for its `readiness`, and `reconcileFeed`, `inspectFeed`, `retryParked` and `removeSink`;
+- `makeInMemoryFeed` / `withInMemoryFeed` and `makeInMemorySink`.
+
+`@kairos-es/feed-postgres` is the durable feed, and `@kairos-es/feed-algolia` the first sink.
+
+## Installation
+
+`@kairos-es/core`, `@kairos-es/read` and `effect` are peer dependencies. `@kairos-es/codec` is on the line because `@kairos-es/read` peers it:
+
+```sh
+pnpm add @kairos-es/feed@alpha @kairos-es/read@alpha @kairos-es/codec@alpha \
+  @kairos-es/core@alpha effect@^4.0.5
+```
+
+## Writing the feed
+
+Make the feed's write the read model's own: in `apply`, call `feed.write(at, body)` with the batch's last position, and in the body `upsert(key, doc)` or `remove(key)` each record the batch changed. The feed keeps the last write per key within a batch, skips a document equal to the one it holds (compared on its encoded form, so key order does not matter), and lands the batch only if the body succeeds.
+
+```ts
+import { FeedKey, FeedName, makeInMemoryFeed, withInMemoryFeed } from '@kairos-es/feed'
+import { makeInMemoryProjectionStore } from '@kairos-es/read'
+
+const feed = yield* makeInMemoryFeed({ feed: FeedName.make('course-search'), doc: CourseDoc })
+const store = yield* withInMemoryFeed(yield* makeInMemoryProjectionStore, feed, key)
+
+const apply = (batch) =>
+  feed.write(Arr.lastNonEmpty(batch).sequenced.position, (writer) =>
+    Effect.forEach(touchedCourses(batch), (course) =>
+      course.listed
+        ? writer.upsert(FeedKey.make(course.id), toDoc(course))
+        : writer.remove(FeedKey.make(course.id)),
+    ),
+  )
+```
+
+Things to know:
+
+- **One feed per materialisation.** A feed's order is the order its one writer commits in, so a feed is bound to one checkpoint key, and binding it to a second is refused. Use a feed per read model, and a sink per feed.
+- **A reset rebuilds the sinks.** Reset the checkpoint through the store `withInMemoryFeed` (or `feed-postgres`'s `withFeed`) returns, and the feed is emptied and its generation moves on. Every sink then rebuilds from what the replay writes. A sink with `FeedResync` keeps serving its old copy until the new one is published; a sink without it is rebuilt in place, over the copy it is serving, so it serves a mixture of old and new from the first page on. Give the worker a `readiness` (below) so that a published copy is complete, and so that an in-place rebuild does not delete what the replay has not written yet.
+- **A remove is a tombstone.** It reaches every sink as a delete, and is collected once every sink registered on the feed has passed it, so a sink that is resyncing holds collection back until its resync is saved. So does a sink you stopped running: remove it (below) when you retire it.
+- **A document that fails to encode through its `Schema` is a defect** in the read model, not a sink's refusal.
+- **In memory, write the feed last in `apply`.** The in-memory store cannot roll back a view written before a step that failed; the in-memory feed lands its batch in one update and fails only by a defect. The in-memory feed is ephemeral, like the in-memory store: its generation is fresh on every boot, so a sink that outlives the process rebuilds rather than keeping a copy of a feed that no longer exists, and it refuses a durable store.
+
+## Running the sync
+
+Start one worker per feed and sink, in a scope beside your projections:
+
+```ts
+import { runFeedSync } from '@kairos-es/feed'
+
+yield* Effect.forkScoped(
+  runFeedSync({ source: feed.source, sink, store: feed.syncStore }),
+)
+```
+
+What it does:
+
+- **It holds a lease.** A sink has no transaction, so two workers could send out of order; a second worker for the same feed and sink waits as a standby until the first lets go. The cursor's compare-and-set also checks the holder, so a worker that has lost its lease cannot move the cursor.
+- **The cursor moves only after the sink confirms** the batch is applied and visible. A crash before that resends the batch, so a sink's writes must be idempotent.
+- **A record the sink refuses is parked**, with the sink's reason, and the rest of the batch moves on. It is sent again when its row next changes, or when you call `retryParked`. A later delete of a parked record is sent and clears it.
+- **A new generation is a resync.** With `FeedResync`, the worker loads every live row into a fresh target and publishes it over the live one in one step. Without it, the worker resyncs in place, sending every row over the live copy, and then reconciles away what the feed no longer holds. In place, a refusal leaves the old copy's record live: a refused upsert leaves the previous generation's document of that key in the sink, and an orphan whose delete is refused stays in it. Both are in the parked list with the sink's reason, and the closing reconcile's report goes to `onReconcile`.
+- **A rebuild waits for the replay when you give it `readiness`.** After a reset, the worker starts its resync at once, while the read model is still replaying the log into the feed. Without `readiness`, the worker finishes the rebuild when it reaches the end of the feed — publishing, or in place reconciling — so **search can serve a partial index** until the replay is done and the tail fills in the rest. With `readiness`, the worker keeps sending what the replay writes, and finishes only when the readiness says the read model has caught up. It checks the generation on every poll while it waits, so a second reset abandons the attempt and starts a fresh one. `materialisationCaughtUp(readModel)` is the usual readiness: the read model's checkpoint has reached the last event its query selected when the attempt started. Pass the read model whose `apply` writes this feed:
+
+  ```ts
+  import { materialisationCaughtUp, runFeedSync } from '@kairos-es/feed'
+
+  const readiness = yield* materialisationCaughtUp(readModel) // needs DcbEventStore
+  yield* Effect.forkScoped(
+    runFeedSync({ source: feed.source, sink, store: feed.syncStore, readiness }),
+  )
+  ```
+
+  Each rebuild attempt starts with one paged read of the read model's events, which is the backlog the replay reads anyway. Your own `FeedReadiness` is a function from the generation to a probe: the function is called once per attempt, and the probe it returns is asked on every poll until it answers `true`. For a sink without `resync`, the wait holds the final reconcile and the cursor save instead, so the reconcile does not delete records the replay has not reached yet; without `readiness`, it does delete them, and the tail sends each back as the replay writes it.
+
+  The wait has no time limit: publishing early is what it exists to prevent, so a readiness that never answers `true` holds the rebuild for good, with no error. You can see it two ways. `inspectFeed` reports the sink `resyncDue` for as long as the wait lasts, and the worker logs a warning, `feed sync rebuild held on readiness`, every 60 poll intervals it has waited (a minute at the default poll), with the feed, sink, generation, polls and `heldMillis`.
+- **Reconcile** deletes the records a sink holds that the feed no longer has. Set `reconcileEvery` to run it between batches, or call `reconcileFeed` (which takes the lease itself).
+- **It supervises itself.** A failure ends the session and the worker restarts with a jittered back-off (100 ms to 30 s by default, never sooner than a sink's `Retry-After`). It gives up with `FeedSyncStalled` only after `maxNoProgressRestarts` restarts in a row with no cursor advance. Every knob is in `tuning`.
+
+The worker polls on `pollInterval` (1 second by default); a source's optional `listen` stream only wakes it sooner.
+
+## Writing a sink
+
+Implement `FeedSink<D, Receipt>`:
+
+- `apply(batch)` sends a non-empty batch of `FeedChange`s, each an `Upsert` with the whole document or a `Delete`, and returns a receipt. Write whole records only: a partial update is not idempotent, and a batch may be sent twice.
+- `confirm(receipt)` resolves once that batch is applied **and visible**. Resolving early lets the cursor pass a batch a crash could still lose.
+- Fail with `SinkRetryable` (try again later, optionally with `retryAfter`), `SinkRejected` (these keys, with a reason each; the rest of the batch is resent) or `SinkHalted` (stop; supervision decides).
+- Give it `resync` (`begin`, `load`, `publish`, for a target with an atomic swap), `reconcile` (`listKeys`, a stream of every key the target holds), or both. `runFeedSync` refuses a sink with neither, because it could never rebuild.
+- A `resync` must keep each attempt's target its own. Every `begin` returns a name no earlier `begin` returned, even for the same generation; every `begin` drops every other target an earlier attempt left; and a target that has gone is never published: a `load` into it may fail, or may recreate it if your target springs into being on its first write, but either way its `publish` fails `SinkRetryable` and leaves the live copy alone. Without all three, a worker that has lost its lease without knowing it yet can publish the half-built target of the worker that holds the lease now, and the pages that worker had not loaded yet are lost from the live copy without any error. The hover docs on `FeedResync` and `ResyncTarget` state the full contract.
+
+`makeInMemorySink` is the reference sink, and the one to run your read model against in a test. The law suite this repository holds every sink to is not published for the alpha.
+
+## Operating a feed
+
+`inspectFeed(source, store)` reports, per sink, its generation, cursor, when the cursor last moved (`lastAdvance`), lag, lease and parked records with their reasons, and `retryParked(store, { feed, sink, key })` sends one parked record again.
+
+Every sink registered on a feed holds its tombstone collection back, a sink you no longer run included. A sink whose `lastAdvance` stays put while the feed's head moves is one nothing is running. Stop its worker, then call `removeSink(store, { feed, sink })`: it deletes the sink's cursor, lease record and parked records, and fails `LeaseHeld` without removing anything while a worker for the sink is still running. Starting a worker for that sink again later registers it afresh, and it resyncs.
+
+None of these needs the sink's client or credentials.

package/dist/cjs/Feed.js

@@ -0,0 +1,6 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+//# sourceMappingURL=Feed.js.map

package/dist/cjs/Feed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Feed.js","names":[],"sources":["../../src/Feed.ts"],"sourcesContent":[null],"mappings":"","ignoreList":[]}

package/dist/cjs/FeedSink.js

@@ -0,0 +1,54 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.changeOf = exports.FeedChange = void 0;
+var _effect = require("effect");
+/**
+ * The sink port: what a target a feed is copied to must offer the driver.
+ *
+ * ## Three parts, two of them optional
+ *
+ * - `apply` and `confirm` are the whole of the steady state. `apply` sends a
+ *   batch and returns a `Receipt`; `confirm` resolves once that batch is applied
+ *   AND VISIBLE in the target. The driver moves its cursor only after `confirm`
+ *   (ADR-0019 §6), so a crash between the two resends the batch — which is why
+ *   every sink must be IDEMPOTENT: the same batch applied twice leaves the target
+ *   as once. Full-record replace satisfies that; a partial operation such as an
+ *   increment does not, and a sink must never use one.
+ * - `resync` is how a sink rebuilds after the feed's generation moves: load every
+ *   row into a fresh target that is not yet serving — tombstones too, as deletes,
+ *   since the feed can delete a key the same resync has already loaded — then swap
+ *   it over the live one atomically, so search keeps serving the old copy until the new one is
+ *   complete and records deleted from the feed do not survive the rebuild.
+ * - `reconcile` lists the keys the target holds, so the driver can delete those
+ *   the feed no longer has. Deletes go through the ordinary `apply`.
+ *
+ * A sink with no atomic swap leaves out `resync`, and the driver then resyncs IN
+ * PLACE: it sends every row to the live target and reconciles away what the feed
+ * no longer holds. That needs `reconcile`, so `runFeedSync` refuses at
+ * construction a sink that has neither part: such a sink could never be rebuilt.
+ *
+ * ## Why `FeedChange` is not `FeedRow`
+ *
+ * A sink is handed the change to make, not the row it came from: an `Upsert` with
+ * the document or a `Delete`. The sequence and the event position are the
+ * driver's business, and a sink that could see them could be tempted to keep a
+ * cursor of its own, which would be a second record of progress.
+ */
+
+/** `FeedChange.Upsert({ key, doc })`, `FeedChange.Delete({ key })`, and matchers. */
+const FeedChange = exports.FeedChange = /*#__PURE__*/_effect.Data.taggedEnum();
+/** The change a row asks of a sink: its document as an upsert, a tombstone as a delete. */
+const changeOf = row => _effect.Option.match(row.doc, {
+  onNone: () => FeedChange.Delete({
+    key: row.key
+  }),
+  onSome: doc => FeedChange.Upsert({
+    key: row.key,
+    doc
+  })
+});
+exports.changeOf = changeOf;
+//# sourceMappingURL=FeedSink.js.map

package/dist/cjs/FeedSink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeedSink.js","names":["_effect","require","FeedChange","exports","Data","taggedEnum","changeOf","row","Option","match","doc","onNone","Delete","key","onSome","Upsert"],"sources":["../../src/FeedSink.ts"],"sourcesContent":[null],"mappings":";;;;;;AAiCA,IAAAA,OAAA,GAAAC,OAAA;AAjCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA;AACO,MAAMC,UAAU,GAAAC,OAAA,CAAAD,UAAA,gBAAGE,YAAI,CAACC,UAAU,EAAwB;AAEjE;AACO,MAAMC,QAAQ,GAAOC,GAAe,IACzCC,cAAM,CAACC,KAAK,CAACF,GAAG,CAACG,GAAG,EAAE;EACpBC,MAAM,EAAEA,CAAA,KAAMT,UAAU,CAACU,MAAM,CAAC;IAAEC,GAAG,EAAEN,GAAG,CAACM;EAAG,CAAE,CAAC;EACjDC,MAAM,EAAGJ,GAAG,IAAKR,UAAU,CAACa,MAAM,CAAC;IAAEF,GAAG,EAAEN,GAAG,CAACM,GAAG;IAAEH;EAAG,CAAE;CACzD,CAAC;AAAAP,OAAA,CAAAG,QAAA,GAAAA,QAAA","ignoreList":[]}

package/dist/cjs/FeedSyncStore.js

@@ -0,0 +1,10 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.sameCursor = void 0;
+/** Whether two optional cursors are the same cursor, as `casCursor` compares them. */
+const sameCursor = (left, right) => left._tag === 'None' ? right._tag === 'None' : right._tag === 'Some' && left.value.generation === right.value.generation && left.value.seq === right.value.seq;
+exports.sameCursor = sameCursor;
+//# sourceMappingURL=FeedSyncStore.js.map

package/dist/cjs/FeedSyncStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FeedSyncStore.js","names":["sameCursor","left","right","_tag","value","generation","seq","exports"],"sources":["../../src/FeedSyncStore.ts"],"sourcesContent":[null],"mappings":";;;;;;AA4NA;AACO,MAAMA,UAAU,GAAGA,CACxBC,IAA+B,EAC/BC,KAAgC,KAEhCD,IAAI,CAACE,IAAI,KAAK,MAAM,GAChBD,KAAK,CAACC,IAAI,KAAK,MAAM,GACrBD,KAAK,CAACC,IAAI,KAAK,MAAM,IACrBF,IAAI,CAACG,KAAK,CAACC,UAAU,KAAKH,KAAK,CAACE,KAAK,CAACC,UAAU,IAChDJ,IAAI,CAACG,KAAK,CAACE,GAAG,KAAKJ,KAAK,CAACE,KAAK,CAACE,GAAG;AAAAC,OAAA,CAAAP,UAAA,GAAAA,UAAA","ignoreList":[]}

package/dist/cjs/deliver.js

@@ -0,0 +1,86 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.deliver = exports.UNEXPLAINED_REFUSAL = void 0;
+var _effect = require("effect");
+var _errors = require("./errors.js");
+/**
+ * One batch to a sink, end to end: send, park what the sink refuses, send the rest
+ * again, then confirm. Package-internal, and the ONE place the driver talks to a
+ * sink's write path, so the steady state, a resync's load and a reconcile's
+ * deletes cannot each grow their own idea of what a refusal means.
+ *
+ * ## Why a refusal re-sends the rest rather than skipping the batch
+ *
+ * A sink that refuses one record of a batch has, by the port's contract, applied
+ * none of it — Algolia, the first sink, rejects a whole `batch` call for one
+ * oversized record. So the records it did NOT name must go again, without the
+ * refused ones, until the sink takes what is left or there is nothing left. Each
+ * round removes at least one key, so the loop ends. A sink that names no key of
+ * the batch would loop forever instead, and that is a sink bug the driver turns
+ * into `SinkHalted` rather than spin on.
+ *
+ * ## The lease, before every send
+ *
+ * `ensureHeld` runs before each `send`, not once per batch: a refusal round is a
+ * send like any other, and a worker that lost its lease between two rounds must
+ * not make the second.
+ */
+
+/** The reason recorded for a refused key the sink gave no reason for. */
+const UNEXPLAINED_REFUSAL = exports.UNEXPLAINED_REFUSAL = 'refused by the sink, with no reason given';
+/**
+ * Send `pending` through `send`, parking each refused key with the sink's reason,
+ * and confirm the receipt of whatever was finally taken. See the module doc.
+ *
+ * @internal
+ */
+const deliver = args => _effect.Effect.gen(function* () {
+  let remaining = args.pending;
+  const parked = [];
+  for (;;) {
+    if (!_effect.Array.isReadonlyArrayNonEmpty(remaining)) {
+      return {
+        sent: [],
+        parked
+      };
+    }
+    const batch = _effect.Array.map(remaining, p => p.change);
+    yield* args.lease.ensureHeld;
+    const sent = yield* args.send(batch).pipe(_effect.Effect.map(receipt => ({
+      _tag: 'Taken',
+      receipt
+    })), _effect.Effect.catchTag('SinkRejected', rejected => _effect.Effect.succeed({
+      _tag: 'Refused',
+      rejected
+    })));
+    if (sent._tag === 'Taken') {
+      yield* args.confirm(sent.receipt);
+      return {
+        sent: remaining.map(p => p.change.key),
+        parked
+      };
+    }
+    const refused = new Set(sent.rejected.keys);
+    const named = remaining.filter(p => refused.has(p.change.key));
+    if (named.length === 0) {
+      return yield* new _errors.SinkHalted({
+        reason: `the sink refused keys that are not in the batch (${sent.rejected.keys.join(', ')})`
+      });
+    }
+    const parkedAt = yield* _effect.DateTime.now;
+    for (const p of named) {
+      parked.push({
+        key: p.change.key,
+        seq: p.seq,
+        reason: sent.rejected.reasons.get(p.change.key) ?? UNEXPLAINED_REFUSAL,
+        parkedAt
+      });
+    }
+    remaining = remaining.filter(p => !refused.has(p.change.key));
+  }
+});
+exports.deliver = deliver;
+//# sourceMappingURL=deliver.js.map

package/dist/cjs/deliver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliver.js","names":["_effect","require","_errors","UNEXPLAINED_REFUSAL","exports","deliver","args","Effect","gen","remaining","pending","parked","Arr","isReadonlyArrayNonEmpty","sent","batch","map","p","change","lease","ensureHeld","send","pipe","receipt","_tag","catchTag","rejected","succeed","confirm","key","refused","Set","keys","named","filter","has","length","SinkHalted","reason","join","parkedAt","DateTime","now","push","seq","reasons","get"],"sources":["../../src/deliver.ts"],"sourcesContent":[null],"mappings":";;;;;;AAsBA,IAAAA,OAAA,GAAAC,OAAA;AAEA,IAAAC,OAAA,GAAAD,OAAA;AAxBA;;;;;;;;;;;;;;;;;;;;;;;AA+CA;AACO,MAAME,mBAAmB,GAAAC,OAAA,CAAAD,mBAAA,GAAG,2CAA2C;AAE9E;;;;;;AAMO,MAAME,OAAO,GAAgBC,IASnC,IAICC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,IAAIC,SAAS,GAA8BH,IAAI,CAACI,OAAO;EACvD,MAAMC,MAAM,GAAwB,EAAE;EACtC,SAAS;IACP,IAAI,CAACC,aAAG,CAACC,uBAAuB,CAACJ,SAAS,CAAC,EAAE;MAC3C,OAAO;QAAEK,IAAI,EAAE,EAAE;QAAEH;MAAM,CAAE;IAC7B;IACA,MAAMI,KAAK,GAAGH,aAAG,CAACI,GAAG,CAACP,SAAS,EAAGQ,CAAC,IAAKA,CAAC,CAACC,MAAM,CAAC;IACjD,OAAOZ,IAAI,CAACa,KAAK,CAACC,UAAU;IAC5B,MAAMN,IAAI,GAAG,OAAOR,IAAI,CAACe,IAAI,CAACN,KAAK,CAAC,CAACO,IAAI,CACvCf,cAAM,CAACS,GAAG,CAAEO,OAAO,KAAM;MAAEC,IAAI,EAAE,OAAgB;MAAED;IAAO,CAAE,CAAC,CAAC,EAC9DhB,cAAM,CAACkB,QAAQ,CAAC,cAAc,EAAGC,QAAQ,IACvCnB,cAAM,CAACoB,OAAO,CAAC;MAAEH,IAAI,EAAE,SAAkB;MAAEE;IAAQ,CAAE,CAAC,CACvD,CACF;IACD,IAAIZ,IAAI,CAACU,IAAI,KAAK,OAAO,EAAE;MACzB,OAAOlB,IAAI,CAACsB,OAAO,CAACd,IAAI,CAACS,OAAO,CAAC;MACjC,OAAO;QAAET,IAAI,EAAEL,SAAS,CAACO,GAAG,CAAEC,CAAC,IAAKA,CAAC,CAACC,MAAM,CAACW,GAAG,CAAC;QAAElB;MAAM,CAAE;IAC7D;IACA,MAAMmB,OAAO,GAAG,IAAIC,GAAG,CAAUjB,IAAI,CAACY,QAAQ,CAACM,IAAI,CAAC;IACpD,MAAMC,KAAK,GAAGxB,SAAS,CAACyB,MAAM,CAAEjB,CAAC,IAAKa,OAAO,CAACK,GAAG,CAAClB,CAAC,CAACC,MAAM,CAACW,GAAG,CAAC,CAAC;IAChE,IAAII,KAAK,CAACG,MAAM,KAAK,CAAC,EAAE;MACtB,OAAO,OAAO,IAAIC,kBAAU,CAAC;QAC3BC,MAAM,EAAE,oDAAoDxB,IAAI,CAACY,QAAQ,CAACM,IAAI,CAACO,IAAI,CAAC,IAAI,CAAC;OAC1F,CAAC;IACJ;IACA,MAAMC,QAAQ,GAAG,OAAOC,gBAAQ,CAACC,GAAG;IACpC,KAAK,MAAMzB,CAAC,IAAIgB,KAAK,EAAE;MACrBtB,MAAM,CAACgC,IAAI,CAAC;QACVd,GAAG,EAAEZ,CAAC,CAACC,MAAM,CAACW,GAAG;QACjBe,GAAG,EAAE3B,CAAC,CAAC2B,GAAG;QACVN,MAAM,EACJxB,IAAI,CAACY,QAAQ,CAACmB,OAAO,CAACC,GAAG,CAAC7B,CAAC,CAACC,MAAM,CAACW,GAAG,CAAC,IAAI1B,mBAAmB;QAChEqC;OACD,CAAC;IACJ;IACA/B,SAAS,GAAGA,SAAS,CAACyB,MAAM,CAAEjB,CAAC,IAAK,CAACa,OAAO,CAACK,GAAG,CAAClB,CAAC,CAACC,MAAM,CAACW,GAAG,CAAC,CAAC;EACjE;AACF,CAAC,CAAC;AAAAzB,OAAA,CAAAC,OAAA,GAAAA,OAAA","ignoreList":[]}

package/dist/cjs/errors.js

@@ -0,0 +1,114 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SinkRetryable = exports.SinkRejected = exports.SinkHalted = exports.LeaseLost = exports.LeaseHeld = exports.FeedWriteFailed = exports.FeedUnreadable = exports.FeedSyncStalled = exports.CursorSuperseded = void 0;
+var _effect = require("effect");
+/**
+ * The change feed's error vocabulary.
+ *
+ * ## The sink's three answers
+ *
+ * A sink classifies every failure into one of three, and the driver's whole
+ * behaviour on failure follows from which. The names borrow the meaning of
+ * `@kairos-es/automation`'s classification without depending on that package: a
+ * feed is not an automation (ADR-0019), and a dependency for three class names
+ * would make it look like one.
+ *
+ * - `SinkRetryable` — the sink could not take the batch NOW (a rate limit, a 5xx, a
+ *   timeout). The cursor stays where it is and the batch is sent again after a
+ *   back-off, never sooner than `retryAfter` when the sink names one.
+ * - `SinkRejected` — the sink will never take THESE records as they stand (too
+ *   large, invalid). The named keys are parked with the sink's reasons, the rest of
+ *   the batch is sent again without them, and the cursor moves past the whole page.
+ *   A parked record is retried when its row next changes.
+ * - `SinkHalted` — something is wrong that retrying will not mend (bad
+ *   credentials, a missing index). The worker stops, and supervision decides.
+ *
+ * ## The feed's own tables
+ *
+ * `FeedWriteFailed` and `FeedUnreadable` are infrastructure faults on the feed's
+ * own durable state, split by direction: a write that did not land, a read that
+ * could not be made. They are tagged errors rather than defects for the reason the
+ * `ProjectionStore` port gives for its own: the driver's supervision has to tell
+ * "back off and try again" from "give up", and only a value can carry that.
+ *
+ * ## The worker's lease and cursor
+ *
+ * `LeaseHeld`, `LeaseLost` and `CursorSuperseded` are the three ways the
+ * single-worker guarantee shows itself: another worker holds the lease, this
+ * worker's lease went while it ran, or the cursor it expected to advance is not
+ * the one stored (a rival moved it, or the lease changed hands).
+ */
+
+/** The sink cannot take the batch now: keep the cursor and back off. */
+class SinkRetryable extends /*#__PURE__*/_effect.Data.TaggedError('SinkRetryable') {
+  get message() {
+    return this.retryAfter === undefined ? this.reason : `${this.reason} (retry after ${_effect.Duration.format(this.retryAfter)})`;
+  }
+}
+/** The sink refuses these records as they stand: park them, send the rest. */
+exports.SinkRetryable = SinkRetryable;
+class SinkRejected extends /*#__PURE__*/_effect.Data.TaggedError('SinkRejected') {
+  get message() {
+    return `the sink refused ${this.keys.length} record(s): ${this.keys.join(', ')}`;
+  }
+}
+/** Something retrying will not mend: stop the worker. */
+exports.SinkRejected = SinkRejected;
+class SinkHalted extends /*#__PURE__*/_effect.Data.TaggedError('SinkHalted') {
+  get message() {
+    return this.reason;
+  }
+}
+/** A write to the feed's own tables did not land. */
+exports.SinkHalted = SinkHalted;
+class FeedWriteFailed extends /*#__PURE__*/_effect.Data.TaggedError('FeedWriteFailed') {
+  get message() {
+    return this.reason;
+  }
+}
+/** A read of the feed's own tables could not be made. */
+exports.FeedWriteFailed = FeedWriteFailed;
+class FeedUnreadable extends /*#__PURE__*/_effect.Data.TaggedError('FeedUnreadable') {
+  get message() {
+    return this.reason;
+  }
+}
+/** Another worker holds the lease for this feed and sink. */
+exports.FeedUnreadable = FeedUnreadable;
+class LeaseHeld extends /*#__PURE__*/_effect.Data.TaggedError('LeaseHeld') {
+  get message() {
+    return `another worker holds the lease for feed '${this.feed}' and sink '${this.sink}'`;
+  }
+}
+/** This worker's lease is no longer its own; it must stop sending at once. */
+exports.LeaseHeld = LeaseHeld;
+class LeaseLost extends /*#__PURE__*/_effect.Data.TaggedError('LeaseLost') {
+  get message() {
+    return `the lease for feed '${this.feed}' and sink '${this.sink}' was lost`;
+  }
+}
+/**
+ * The cursor compare-and-set lost: the stored cursor is not the one expected, or
+ * the lease is not held by the worker that asked. Nothing the call carried landed.
+ */
+exports.LeaseLost = LeaseLost;
+class CursorSuperseded extends /*#__PURE__*/_effect.Data.TaggedError('CursorSuperseded') {
+  get message() {
+    return `the cursor for feed '${this.feed}' and sink '${this.sink}' was superseded`;
+  }
+}
+/**
+ * The sync worker gave up: it restarted `restarts` times in a row without moving
+ * its cursor once. `reason` is the failure that ended the last attempt.
+ */
+exports.CursorSuperseded = CursorSuperseded;
+class FeedSyncStalled extends /*#__PURE__*/_effect.Data.TaggedError('FeedSyncStalled') {
+  get message() {
+    return `the sync of feed '${this.feed}' to sink '${this.sink}' made no progress in ${this.restarts} consecutive restarts`;
+  }
+}
+exports.FeedSyncStalled = FeedSyncStalled;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":["_effect","require","SinkRetryable","Data","TaggedError","message","retryAfter","undefined","reason","Duration","format","exports","SinkRejected","keys","length","join","SinkHalted","FeedWriteFailed","FeedUnreadable","LeaseHeld","feed","sink","LeaseLost","CursorSuperseded","FeedSyncStalled","restarts"],"sources":["../../src/errors.ts"],"sourcesContent":[null],"mappings":";;;;;;AAqCA,IAAAA,OAAA,GAAAC,OAAA;AArCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA;AACM,MAAOC,aAAc,sBAAQC,YAAI,CAACC,WAAW,CAAC,eAAe,CAIjE;EACA,IAAaC,OAAOA,CAAA;IAClB,OAAO,IAAI,CAACC,UAAU,KAAKC,SAAS,GAChC,IAAI,CAACC,MAAM,GACX,GAAG,IAAI,CAACA,MAAM,iBAAiBC,gBAAQ,CAACC,MAAM,CAAC,IAAI,CAACJ,UAAU,CAAC,GAAG;EACxE;;AAGF;AAAAK,OAAA,CAAAT,aAAA,GAAAA,aAAA;AACM,MAAOU,YAAa,sBAAQT,YAAI,CAACC,WAAW,CAAC,cAAc,CAI/D;EACA,IAAaC,OAAOA,CAAA;IAClB,OAAO,oBAAoB,IAAI,CAACQ,IAAI,CAACC,MAAM,eAAe,IAAI,CAACD,IAAI,CAACE,IAAI,CAAC,IAAI,CAAC,EAAE;EAClF;;AAGF;AAAAJ,OAAA,CAAAC,YAAA,GAAAA,YAAA;AACM,MAAOI,UAAW,sBAAQb,YAAI,CAACC,WAAW,CAAC,YAAY,CAE3D;EACA,IAAaC,OAAOA,CAAA;IAClB,OAAO,IAAI,CAACG,MAAM;EACpB;;AAGF;AAAAG,OAAA,CAAAK,UAAA,GAAAA,UAAA;AACM,MAAOC,eAAgB,sBAAQd,YAAI,CAACC,WAAW,CAAC,iBAAiB,CAGrE;EACA,IAAaC,OAAOA,CAAA;IAClB,OAAO,IAAI,CAACG,MAAM;EACpB;;AAGF;AAAAG,OAAA,CAAAM,eAAA,GAAAA,eAAA;AACM,MAAOC,cAAe,sBAAQf,YAAI,CAACC,WAAW,CAAC,gBAAgB,CAGnE;EACA,IAAaC,OAAOA,CAAA;IAClB,OAAO,IAAI,CAACG,MAAM;EACpB;;AAGF;AAAAG,OAAA,CAAAO,cAAA,GAAAA,cAAA;AACM,MAAOC,SAAU,sBAAQhB,YAAI,CAACC,WAAW,CAAC,WAAW,CAAa;EACtE,IAAaC,OAAOA,CAAA;IAClB,OAAO,4CAA4C,IAAI,CAACe,IAAI,eAAe,IAAI,CAACC,IAAI,GAAG;EACzF;;AAGF;AAAAV,OAAA,CAAAQ,SAAA,GAAAA,SAAA;AACM,MAAOG,SAAU,sBAAQnB,YAAI,CAACC,WAAW,CAAC,WAAW,CAAa;EACtE,IAAaC,OAAOA,CAAA;IAClB,OAAO,uBAAuB,IAAI,CAACe,IAAI,eAAe,IAAI,CAACC,IAAI,YAAY;EAC7E;;AAGF;;;;AAAAV,OAAA,CAAAW,SAAA,GAAAA,SAAA;AAIM,MAAOC,gBAAiB,sBAAQpB,YAAI,CAACC,WAAW,CACpD,kBAAkB,CACP;EACX,IAAaC,OAAOA,CAAA;IAClB,OAAO,wBAAwB,IAAI,CAACe,IAAI,eAAe,IAAI,CAACC,IAAI,kBAAkB;EACpF;;AAGF;;;;AAAAV,OAAA,CAAAY,gBAAA,GAAAA,gBAAA;AAIM,MAAOC,eAAgB,sBAAQrB,YAAI,CAACC,WAAW,CAAC,iBAAiB,CAKrE;EACA,IAAaC,OAAOA,CAAA;IAClB,OAAO,qBAAqB,IAAI,CAACe,IAAI,cAAc,IAAI,CAACC,IAAI,yBAAyB,IAAI,CAACI,QAAQ,uBAAuB;EAC3H","ignoreList":[]}

package/dist/cjs/identifiers.js

@@ -0,0 +1,63 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SinkName = exports.LeaseHolder = exports.Generation = exports.FeedSeq = exports.FeedName = exports.FeedKey = exports.FEED_ORIGIN = void 0;
+var _effect = require("effect");
+/**
+ * The change feed's branded identifiers.
+ *
+ * Every one of them is a branded `Schema`, as every domain identifier in this
+ * repository is, so a raw string or `bigint` cannot stand in for one by accident.
+ * Two of them are worth a word, because they look like things the read side
+ * already has and are deliberately not those things.
+ *
+ * - `FeedSeq` is NOT a `Position`. A `Position` is a place in the global event log,
+ *   and one event may fan out into many feed rows (a teacher renamed, fifty courses
+ *   touched). Give those fifty rows the event's position as their cursor and they
+ *   all share one value, so a page boundary that falls among them loses the rest of
+ *   them: the next page asks for rows strictly after a value the lost ones also
+ *   carry. A feed-local sequence gives every row a cursor value of its own. The
+ *   event position is still kept on each row, as `eventPosition`, for the one
+ *   question it answers — "is the sink at least as fresh as P?" — and is never a
+ *   cursor.
+ * - `Generation` is NOT a counter a caller reads meaning into. It is compared for
+ *   EQUALITY only: a sink whose cursor was saved at a generation other than the
+ *   feed's current one resyncs. That is what lets the in-memory feed draw a fresh
+ *   generation from `Random` on every boot while a durable feed counts upwards, and
+ *   both satisfy the one rule the driver needs.
+ */
+
+/**
+ * The name of one change feed. A feed is bound to ONE materialisation, because a
+ * feed sequence taken inside a commit is ascending in commit order only while one
+ * transaction at a time writes that feed — which the read side gives per
+ * materialisation and no wider.
+ */
+const FeedName = exports.FeedName = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_effect.Schema.check(/*#__PURE__*/_effect.Schema.isNonEmpty()), /*#__PURE__*/_effect.Schema.brand('FeedName'));
+/** A record's key within a feed, and the sink's object id for that record. */
+const FeedKey = exports.FeedKey = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_effect.Schema.check(/*#__PURE__*/_effect.Schema.isNonEmpty()), /*#__PURE__*/_effect.Schema.brand('FeedKey'));
+/**
+ * The feed-local cursor: unique, and ascending in commit order. Compared, never
+ * arithmetic'd, and never assumed contiguous — a sequence shared by several feeds
+ * leaves gaps in each, and a coalesced row gives up its old value when it moves.
+ */
+const FeedSeq = exports.FeedSeq = /*#__PURE__*/_effect.Schema.BigInt.pipe(/*#__PURE__*/_effect.Schema.check(/*#__PURE__*/_effect.Schema.isGreaterThanOrEqualToBigInt(0n)), /*#__PURE__*/_effect.Schema.brand('FeedSeq'));
+/** The sentinel feed sequence meaning "before the first row". */
+const FEED_ORIGIN = exports.FEED_ORIGIN = /*#__PURE__*/FeedSeq.make(0n);
+/**
+ * The feed's generation: it moves on every reset of the materialisation the feed
+ * is bound to, and on every boot of an ephemeral feed. Compared for equality only;
+ * see the module doc.
+ */
+const Generation = exports.Generation = /*#__PURE__*/_effect.Schema.BigInt.pipe(/*#__PURE__*/_effect.Schema.check(/*#__PURE__*/_effect.Schema.isGreaterThanOrEqualToBigInt(0n)), /*#__PURE__*/_effect.Schema.brand('Generation'));
+/** The name of one sink. A feed keeps one cursor per sink. */
+const SinkName = exports.SinkName = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_effect.Schema.check(/*#__PURE__*/_effect.Schema.isNonEmpty()), /*#__PURE__*/_effect.Schema.brand('SinkName'));
+/**
+ * Who holds a sync worker's lease. Issued by the `FeedSyncStore` when the lease is
+ * taken, and checked again by every cursor compare-and-set, so a worker that has
+ * lost its lease cannot move the cursor even if it is still running.
+ */
+const LeaseHolder = exports.LeaseHolder = /*#__PURE__*/_effect.Schema.String.pipe(/*#__PURE__*/_effect.Schema.check(/*#__PURE__*/_effect.Schema.isNonEmpty()), /*#__PURE__*/_effect.Schema.brand('LeaseHolder'));
+//# sourceMappingURL=identifiers.js.map

package/dist/cjs/identifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifiers.js","names":["_effect","require","FeedName","exports","Schema","String","pipe","check","isNonEmpty","brand","FeedKey","FeedSeq","BigInt","isGreaterThanOrEqualToBigInt","FEED_ORIGIN","make","Generation","SinkName","LeaseHolder"],"sources":["../../src/identifiers.ts"],"sourcesContent":[null],"mappings":";;;;;;AAuBA,IAAAA,OAAA,GAAAC,OAAA;AAvBA;;;;;;;;;;;;;;;;;;;;;;;;AAyBA;;;;;;AAMO,MAAMC,QAAQ,GAAAC,OAAA,CAAAD,QAAA,gBAAGE,cAAM,CAACC,MAAM,CAACC,IAAI,cACxCF,cAAM,CAACG,KAAK,cAACH,cAAM,CAACI,UAAU,EAAE,CAAC,eACjCJ,cAAM,CAACK,KAAK,CAAC,UAAU,CAAC,CACzB;AAGD;AACO,MAAMC,OAAO,GAAAP,OAAA,CAAAO,OAAA,gBAAGN,cAAM,CAACC,MAAM,CAACC,IAAI,cACvCF,cAAM,CAACG,KAAK,cAACH,cAAM,CAACI,UAAU,EAAE,CAAC,eACjCJ,cAAM,CAACK,KAAK,CAAC,SAAS,CAAC,CACxB;AAGD;;;;;AAKO,MAAME,OAAO,GAAAR,OAAA,CAAAQ,OAAA,gBAAGP,cAAM,CAACQ,MAAM,CAACN,IAAI,cACvCF,cAAM,CAACG,KAAK,cAACH,cAAM,CAACS,4BAA4B,CAAC,EAAE,CAAC,CAAC,eACrDT,cAAM,CAACK,KAAK,CAAC,SAAS,CAAC,CACxB;AAGD;AACO,MAAMK,WAAW,GAAAX,OAAA,CAAAW,WAAA,gBAAYH,OAAO,CAACI,IAAI,CAAC,EAAE,CAAC;AAEpD;;;;;AAKO,MAAMC,UAAU,GAAAb,OAAA,CAAAa,UAAA,gBAAGZ,cAAM,CAACQ,MAAM,CAACN,IAAI,cAC1CF,cAAM,CAACG,KAAK,cAACH,cAAM,CAACS,4BAA4B,CAAC,EAAE,CAAC,CAAC,eACrDT,cAAM,CAACK,KAAK,CAAC,YAAY,CAAC,CAC3B;AAGD;AACO,MAAMQ,QAAQ,GAAAd,OAAA,CAAAc,QAAA,gBAAGb,cAAM,CAACC,MAAM,CAACC,IAAI,cACxCF,cAAM,CAACG,KAAK,cAACH,cAAM,CAACI,UAAU,EAAE,CAAC,eACjCJ,cAAM,CAACK,KAAK,CAAC,UAAU,CAAC,CACzB;AAGD;;;;;AAKO,MAAMS,WAAW,GAAAf,OAAA,CAAAe,WAAA,gBAAGd,cAAM,CAACC,MAAM,CAACC,IAAI,cAC3CF,cAAM,CAACG,KAAK,cAACH,cAAM,CAACI,UAAU,EAAE,CAAC,eACjCJ,cAAM,CAACK,KAAK,CAAC,aAAa,CAAC,CAC5B","ignoreList":[]}