@kairos-es/core 1.0.0-alpha.5 → 1.0.0-alpha.6

package/dist/cjs/SubscribeMachine.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.subscriptionTuningFields = exports.subscribeStream = exports.DEFAULT_POLL_INTERVAL_MILLIS = exports.DEFAULT_CATCH_UP_PAGE_SIZE = void 0;
+exports.subscriptionTuningFields = exports.subscribeStream = exports.subscribeItems = exports.DEFAULT_POLL_INTERVAL_MILLIS = exports.DEFAULT_CATCH_UP_PAGE_SIZE = void 0;
 var _effect = require("effect");
 var _Event = require("./Event.js");
 /**
@@ -13,6 +13,15 @@ var _Event = require("./Event.js");
  * the cursor's exclusive lower bound) and the poll loop that together turn a paged
  * read into a live subscription.
  *
+ * The algorithm is `subscribeItems`, generic over the item `A` it delivers and the
+ * cursor `C` it resumes from, because nothing in it is about an event: any source
+ * that can page-read strictly after a cursor and name the cursor of what it
+ * returned is subscribable by the same loop. `subscribeStream` is the event-store
+ * shape — `SequencedEvent` ordered by `Position` — over the same loop, and it is
+ * what every engine calls, unchanged by the generalisation. A second kind of
+ * source reuses the loop rather than growing a second one, for the reason the next
+ * paragraph gives.
+ *
  * It lives in core because delivery semantics are contract semantics. An engine
  * supplies TRANSPORT through two STUBBABLE seams — `fetch`, a paged read strictly
  * after a cursor, and `listen`, an optional wake source — and inherits the delivery
@@ -23,48 +32,52 @@ var _Event = require("./Event.js");
  * Both seams take plain in-memory values in a test, so the wake/poll/de-dup logic
  * is exercisable with no live backend at all.
  *
- * All THREE are the callers, and the count matters to a reader here: it means there
- * is exactly ONE delivery algorithm in this repo, and it is the code below. The
+ * All THREE engines are callers, and the count matters to a reader here: it means
+ * there is exactly ONE delivery algorithm in this repo, and it is the code below. The
  * in-memory store is a caller like the rest — it hands in a `fetch` over its log
  * `Ref` and its append `PubSub` as a wake source and keeps no delivery logic of its
  * own — which is what makes the shared contract suite's subscribe cases a comparison
  * of two BACKENDS rather than of two delivery algorithms.
  *
- * Correctness rests on the periodic position-based reconcile — a re-read from the
+ * Correctness rests on the periodic cursor-based reconcile — a re-read from the
  * cursor every poll interval — and NEVER on the wake source, which only lowers
  * delivery latency below that interval. A subscription with no wake source at all
  * is therefore complete and correct, merely slower, which is why `listen` is
  * optional in the TYPE rather than by the convention of passing `Stream.never`:
  * poll-only delivery is a supported shape, not a degraded one.
  *
- * ## The precondition every engine inherits: ASCENDING COMMIT ORDER
+ * ## The precondition every caller inherits: ASCENDING COMMIT ORDER
  *
- * A position that is committed and VISIBLE must never be below one already
- * delivered. Gaps are fine: the cursor is an ascending exclusive lower bound, so a
- * number that is allocated and never committed, or never allocated at all, is
- * simply a number the machine never sees. Out-of-order commits are not fine. If one
+ * It binds EVERY caller, over whatever cursor it chose — an engine's `Position`, or
+ * any other `C` handed to `subscribeItems` — and the example below is written in
+ * positions only because the engines are the callers it was first written for. A
+ * cursor that is committed and VISIBLE must never be below one already delivered.
+ * Gaps are fine: the cursor is an ascending exclusive lower bound, so a number
+ * that is allocated and never committed, or never allocated at all, is simply a
+ * number the machine never sees. Out-of-order commits are not fine. If one
  * writer allocates position 5 and another allocates 6, and 6 commits first, a poll
  * landing between the two commits delivers 6 and advances the cursor past it — and
  * 5 is then lost forever, because no later read looks below the cursor and nothing
- * anywhere notices the hole. An engine whose concurrent writers can commit out of
+ * anywhere notices the hole. A caller whose concurrent writers can commit out of
  * order MUST serialise them, or this machine will silently skip. An engine that
  * takes an exclusive lock on both of its append paths discharges the obligation
  * that way; an engine whose append is a single statement discharges it
  * structurally.
  *
  * The obligation is written down HERE, in the algorithm that depends on it, rather
- * than in whichever engine happens to satisfy it. It is a property of this delivery
- * loop and of nothing else, so an engine author reading only their own source has
+ * than in whichever caller happens to satisfy it. It is a property of this delivery
+ * loop and of nothing else, so an author reading only their own source has
  * no way to discover that anything downstream needs it — and the failure mode is
  * the worst kind there is: no error, no defect, no failing test, just an event that
  * a subscriber never receives. A single engine owning both its append path and its
  * own wake loop can leave the assumption implicit; a shared machine cannot.
  *
- * ## `catchUpPageSize` bounds the READ, not the emission
+ * ## `catchUpPageSize` bounds the READ, not the emission — unless `emit: 'page'`
  *
- * `drainFrom` below PAGES the catch-up read — `catchUpPageSize` bounds each
- * `fetch` — but it COLLECTS every page into one array, which is emitted as a SINGLE
- * chunk. So peak memory at subscription start is O(backlog) rather than O(page): a
+ * Under the default `emit: 'backlog'`, which is what `subscribeStream` and so every
+ * engine uses, `drainFrom` below PAGES the catch-up read — `catchUpPageSize` bounds
+ * each `fetch` — but it COLLECTS every page into one array, which is emitted as a
+ * SINGLE chunk. So peak memory at subscription start is O(backlog) rather than O(page): a
  * subscriber joining behind a large log materialises the whole backlog before its
  * consumer sees the first element.
  *
@@ -75,6 +88,19 @@ var _Event = require("./Event.js");
  * stay small even against a one-chunk catch-up. The cost therefore lands on backlog
  * memory alone, and it lands hardest on the durable-log-with-in-memory-view mode,
  * where an ephemeral view re-catches-up the entire log on every boot.
+ *
+ * `emit: 'page'` changes exactly that and nothing else. Each fetched page is
+ * emitted as its own chunk and the cursor advances past it before the next read, so
+ * peak memory is O(page) and the consumer sees the first item after ONE read rather
+ * than after the whole backlog. Delivery is unchanged: the same items in the same
+ * order, the same de-dup, the same wake and poll. What a caller gives up is the
+ * one-chunk catch-up, so it must not read meaning into chunk boundaries under
+ * either mode. It is for a consumer that does NOT re-chunk downstream and whose
+ * catch-up can be the whole of a large source — a full resync of a table, say —
+ * where holding the backlog would be the cost the paging was meant to avoid. The
+ * engines keep `'backlog'` because the read side's re-chunking already bounds what
+ * they commit, and changing their emission would move a behaviour nobody asked to
+ * move.
  */
 
 /**
@@ -102,6 +128,10 @@ const DEFAULT_CATCH_UP_PAGE_SIZE = exports.DEFAULT_CATCH_UP_PAGE_SIZE = 512;
  * one-second fallback poll (`conn.wait(..., interval=1)`).
  */
 const DEFAULT_POLL_INTERVAL_MILLIS = exports.DEFAULT_POLL_INTERVAL_MILLIS = 1000;
+/** A usable `pollInterval`: see `subscriptionTuningFields` for the bounds' argument. */
+const PollIntervalMillis = /*#__PURE__*/_effect.Schema.Number.check(/*#__PURE__*/_effect.Schema.isGreaterThan(0), /*#__PURE__*/_effect.Schema.isFinite());
+/** A usable `catchUpPageSize`: see `subscriptionTuningFields` for the bounds' argument. */
+const CatchUpPageSize = /*#__PURE__*/_effect.Schema.Int.check(/*#__PURE__*/_effect.Schema.isGreaterThan(0));
 /**
  * The two subscribe-tuning config FIELDS, for an engine whose config is a `Schema`
  * to spread into its own struct.
@@ -132,8 +162,24 @@ const DEFAULT_POLL_INTERVAL_MILLIS = exports.DEFAULT_POLL_INTERVAL_MILLIS = 1000
  * absent key, never an explicit `undefined`.
  */
 const subscriptionTuningFields = exports.subscriptionTuningFields = {
-  pollInterval: /*#__PURE__*/_effect.Schema.optionalKey(/*#__PURE__*/_effect.Schema.Number.check(/*#__PURE__*/_effect.Schema.isGreaterThan(0), /*#__PURE__*/_effect.Schema.isFinite())),
-  catchUpPageSize: /*#__PURE__*/_effect.Schema.optionalKey(/*#__PURE__*/_effect.Schema.Int.check(/*#__PURE__*/_effect.Schema.isGreaterThan(0)))
+  pollInterval: /*#__PURE__*/_effect.Schema.optionalKey(PollIntervalMillis),
+  catchUpPageSize: /*#__PURE__*/_effect.Schema.optionalKey(CatchUpPageSize)
+};
+/**
+ * Why a caller-supplied tuning knob is unusable, naming the field and the value, or
+ * `undefined` when both are usable or absent. It judges with the SAME two schemas
+ * the config fields are built from, so `subscribeItems`, whose caller may have no
+ * config to decode, accepts exactly what an engine's config accepts and the bounds
+ * have one home.
+ */
+const tuningFault = deps => {
+  if (deps.pollInterval !== undefined && !_effect.Schema.is(PollIntervalMillis)(deps.pollInterval)) {
+    return `subscribeItems: pollInterval must be a finite number of milliseconds greater than 0, got ${deps.pollInterval}`;
+  }
+  if (deps.catchUpPageSize !== undefined && !_effect.Schema.is(CatchUpPageSize)(deps.catchUpPageSize)) {
+    return `subscribeItems: catchUpPageSize must be an integer greater than 0, got ${deps.catchUpPageSize}`;
+  }
+  return undefined;
 };
 /**
  * Retry a TRANSIENT poll fault (an `E` from one reconcile read) on a capped
@@ -144,14 +190,40 @@ const subscriptionTuningFields = exports.subscriptionTuningFields = {
  */
 const POLL_RETRY_SCHEDULE = /*#__PURE__*/_effect.Schedule.max([/*#__PURE__*/_effect.Schedule.min([/*#__PURE__*/_effect.Schedule.exponential('100 millis', 2), /*#__PURE__*/_effect.Schedule.spaced('2 seconds')]), /*#__PURE__*/_effect.Schedule.recurs(20)]);
 /**
- * Build the subscription `Stream`: catch up from `after`, then track the live tail.
- * The cursor threads through the `Stream.paginate` state, starting at `after` and
- * advancing to the last delivered position each batch; the stream never completes
- * on its own (the next state is always `Option.some`), so the enclosing scope
- * interrupts it on close. An `E` mid-stream stays on the channel; `makeContractStore` dies it
- * (subscribe is `E = never` on the contract).
+ * Build a subscription `Stream` over any ascending-cursor source: catch up from
+ * `initial`, then track the live tail. The cursor threads through the
+ * `Stream.paginate` state, starting at `initial` and advancing to the cursor of the
+ * last delivered item each batch; the stream never completes on its own (the next
+ * state is always `Option.some`), so the enclosing scope interrupts it on close. An
+ * `E` mid-stream stays on the channel, for the caller to die or to supervise.
+ *
+ * This is THE delivery algorithm, and `subscribeStream` runs the same machine. Under
+ * `emit: 'backlog'` a batch is everything a drain to the tail returned; under
+ * `'page'` it is one fetched page, so the paginate step and the page coincide and a
+ * full page is followed at once by the next read rather than by a wait.
+ *
+ * A `pollInterval` or `catchUpPageSize` the config fields would refuse is a DEFECT
+ * here, raised by the stream before it reads or forks anything, with a message
+ * naming the field. This caller may have no config whose decode would have caught
+ * it, and unchecked the two failures are silent or late: a page size of 0 gives a
+ * stream that never emits and never fails, and 1.5 dies only at the first read,
+ * inside `ReadLimit`, in words that name neither knob.
  */
-const subscribeStream = (deps, after) => _effect.Stream.unwrap(_effect.Effect.gen(function* () {
+const subscribeItems = deps => {
+  const fault = tuningFault(deps);
+  return fault === undefined ? machine(deps) : _effect.Stream.die(new Error(fault));
+};
+/**
+ * The machine itself, with no check of its tuning. `subscribeStream` runs it
+ * directly, and deliberately: the event path stays exactly as it was, with no
+ * second check of figures each SQL engine has already decoded from its config
+ * through the same bounds, and the in-memory store's are a test's own options.
+ */
+exports.subscribeItems = subscribeItems;
+const machine = deps => _effect.Stream.unwrap(_effect.Effect.gen(function* () {
+  const pageSize = deps.catchUpPageSize ?? DEFAULT_CATCH_UP_PAGE_SIZE;
+  const pollInterval = deps.pollInterval ?? DEFAULT_POLL_INTERVAL_MILLIS;
+  const limit = _Event.ReadLimit.make(pageSize);
   // The wake primitive: a sliding(1) queue holding at most one pending
   // signal. The wake source `offer`s an opaque wake on every notification;
   // the poll loop `take`s (with a timeout). The lost-wakeup guard is
@@ -172,62 +244,83 @@ const subscribeStream = (deps, after) => _effect.Stream.unwrap(_effect.Effect.ge
   // scope releases it. We never read its elements directly — every
   // notification is an opaque wake signal.
   yield* listener.pipe(_effect.Stream.runDrain, _effect.Effect.forkScoped);
+  // One page strictly after `from`: the step `drainFrom` loops, and the whole
+  // of a `'page'` read.
+  const fetchPage = from => deps.fetch(from, limit);
   // Reconcile: page-read from `from` until a short page, advancing to the last
-  // delivered position. Retries a TRANSIENT poll fault on a capped schedule so
+  // delivered cursor. Retries a TRANSIENT poll fault on a capped schedule so
   // a single connection blip does not kill a days-long subscription; a
-  // persistent fault propagates and dies.
+  // persistent fault propagates. The retry wraps the WHOLE drain, so a fault on
+  // page three re-reads pages one and two: nothing has been emitted yet, so
+  // that costs reads and never a duplicate.
   const drainFrom = from => _effect.Effect.gen(function* () {
     const collected = [];
     let cursor = from;
     // Loop pages until a short page signals the tail is drained.
     while (true) {
-      const events = yield* deps.fetch(cursor, _Event.ReadLimit.make(deps.catchUpPageSize));
-      for (const event of events) {
-        collected.push(event);
+      const items = yield* fetchPage(cursor);
+      for (const item of items) {
+        collected.push(item);
       }
-      const lastEvent = events.at(-1);
-      if (lastEvent === undefined || events.length < deps.catchUpPageSize) {
+      const lastItem = items.at(-1);
+      if (lastItem === undefined || items.length < pageSize) {
         break;
       }
-      cursor = lastEvent.position;
+      cursor = deps.cursorOf(lastItem);
     }
-    const last = collected.at(-1)?.position ?? from;
-    return {
-      events: collected,
-      last
-    };
+    return collected;
   }).pipe(_effect.Effect.retry(POLL_RETRY_SCHEDULE));
+  // The read one paginate step performs, by emission mode. Under `'page'` the
+  // retry wraps the single page, which is the whole of what is unemitted.
+  const read = (deps.emit ?? 'backlog') === 'page' ? from => fetchPage(from).pipe(_effect.Effect.retry(POLL_RETRY_SCHEDULE)) : drainFrom;
   /**
-   * Produce the NEXT non-empty batch from a cursor position, together with
-   * the advanced cursor — a pure `Position → Effect<[events, next]>`. The
-   * `> boundary` de-dup is enforced by `fetch`'s exclusive lower bound, so a
-   * live re-read after a wake never re-emits an already-delivered position.
+   * Produce the NEXT non-empty batch from a cursor, together with the advanced
+   * cursor — a pure `C → Effect<[items, next]>`. The `> boundary` de-dup is
+   * enforced by `fetch`'s exclusive lower bound, so a live re-read after a wake
+   * never re-emits an already-delivered item.
    *
-   * Drain the wake queue BEFORE reading (lost-wakeup guard), then drain from
-   * the cursor. If a drain yields nothing, wait for a wake but only up to the
-   * poll interval, then loop and re-read ANYWAY — the periodic position-based
-   * poll that makes delivery correct independently of any wake. This effect
-   * only completes by returning a non-empty batch; the scope interrupts it on
-   * close.
+   * Drain the wake queue BEFORE reading (lost-wakeup guard), then read from the
+   * cursor. If a read yields nothing, wait for a wake but only up to the poll
+   * interval, then loop and re-read ANYWAY — the periodic cursor-based poll that
+   * makes delivery correct independently of any wake. This effect only
+   * completes by returning a non-empty batch; the scope interrupts it on close.
    */
   const nextBatch = from => _effect.Effect.gen(function* () {
     while (true) {
       // `Queue.clear` and not `Queue.takeAll`: the drain must NOT wait, and
       // `takeAll` suspends until at least one signal is present.
       yield* _effect.Queue.clear(wake);
-      const {
-        events,
-        last
-      } = yield* drainFrom(from);
-      if (events.length > 0) {
-        return [events, last];
+      const items = yield* read(from);
+      const last = items.at(-1);
+      if (last !== undefined) {
+        return [items, deps.cursorOf(last)];
       }
       // Nothing new: block on a wake, but only up to the poll interval — on
       // timeout we fall through and the loop re-reads regardless.
-      yield* _effect.Effect.ignore(_effect.Effect.timeout(_effect.Queue.take(wake), deps.pollInterval));
+      yield* _effect.Effect.ignore(_effect.Effect.timeout(_effect.Queue.take(wake), pollInterval));
     }
   });
-  return _effect.Stream.paginate(after ?? _Event.ORIGIN, from => _effect.Effect.map(nextBatch(from), ([events, last]) => [events, _effect.Option.some(last)]));
+  return _effect.Stream.paginate(deps.initial, from => _effect.Effect.map(nextBatch(from), ([items, next]) => [items, _effect.Option.some(next)]));
 }));
+/**
+ * Build the event subscription `Stream`: catch up from `after`, then track the live
+ * tail. A THIN wrapper over the machine `subscribeItems` runs, fixing the item to
+ * `SequencedEvent`, the cursor to its `position`, the start to `ORIGIN` when `after`
+ * is absent, and the emission to the default `'backlog'` — so every engine's call
+ * site, and every figure it delivers, is what it was before the machine became
+ * generic. It skips `subscribeItems`' tuning check, for the reason on `machine`. An `E`
+ * mid-stream stays on the channel; `makeContractStore` dies it (subscribe is
+ * `E = never` on the contract).
+ */
+const subscribeStream = (deps, after) => machine({
+  fetch: deps.fetch,
+  cursorOf: event => event.position,
+  initial: after ?? _Event.ORIGIN,
+  ...(deps.listen === undefined ? {} : {
+    listen: deps.listen
+  }),
+  pollInterval: deps.pollInterval,
+  catchUpPageSize: deps.catchUpPageSize
+});
 exports.subscribeStream = subscribeStream;
 //# sourceMappingURL=SubscribeMachine.js.map

package/dist/cjs/SubscribeMachine.js.map

@@ -1 +1 @@
-{"version":3,"file":"SubscribeMachine.js","names":["_effect","require","_Event","DEFAULT_CATCH_UP_PAGE_SIZE","exports","DEFAULT_POLL_INTERVAL_MILLIS","subscriptionTuningFields","pollInterval","Schema","optionalKey","Number","check","isGreaterThan","isFinite","catchUpPageSize","Int","POLL_RETRY_SCHEDULE","Schedule","max","min","exponential","spaced","recurs","subscribeStream","deps","after","Stream","unwrap","Effect","gen","wake","Queue","sliding","listener","listen","never","pipe","tap","offer","undefined","retry","runDrain","forkScoped","drainFrom","from","collected","cursor","events","fetch","ReadLimit","make","event","push","lastEvent","at","length","position","last","nextBatch","clear","ignore","timeout","take","paginate","ORIGIN","map","Option","some"],"sources":["../../src/SubscribeMachine.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"SubscribeMachine.js","names":["_effect","require","_Event","DEFAULT_CATCH_UP_PAGE_SIZE","exports","DEFAULT_POLL_INTERVAL_MILLIS","PollIntervalMillis","Schema","Number","check","isGreaterThan","isFinite","CatchUpPageSize","Int","subscriptionTuningFields","pollInterval","optionalKey","catchUpPageSize","tuningFault","deps","undefined","is","POLL_RETRY_SCHEDULE","Schedule","max","min","exponential","spaced","recurs","subscribeItems","fault","machine","Stream","die","Error","unwrap","Effect","gen","pageSize","limit","ReadLimit","make","wake","Queue","sliding","listener","listen","never","pipe","tap","offer","retry","runDrain","forkScoped","fetchPage","from","fetch","drainFrom","collected","cursor","items","item","push","lastItem","at","length","cursorOf","read","emit","nextBatch","clear","last","ignore","timeout","take","paginate","initial","map","next","Option","some","subscribeStream","after","event","position","ORIGIN"],"sources":["../../src/SubscribeMachine.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/dts-cjs/SubscribeMachine.d.ts

@@ -5,6 +5,15 @@
  * the cursor's exclusive lower bound) and the poll loop that together turn a paged
  * read into a live subscription.
  *
+ * The algorithm is `subscribeItems`, generic over the item `A` it delivers and the
+ * cursor `C` it resumes from, because nothing in it is about an event: any source
+ * that can page-read strictly after a cursor and name the cursor of what it
+ * returned is subscribable by the same loop. `subscribeStream` is the event-store
+ * shape — `SequencedEvent` ordered by `Position` — over the same loop, and it is
+ * what every engine calls, unchanged by the generalisation. A second kind of
+ * source reuses the loop rather than growing a second one, for the reason the next
+ * paragraph gives.
+ *
  * It lives in core because delivery semantics are contract semantics. An engine
  * supplies TRANSPORT through two STUBBABLE seams — `fetch`, a paged read strictly
  * after a cursor, and `listen`, an optional wake source — and inherits the delivery
@@ -15,48 +24,52 @@
  * Both seams take plain in-memory values in a test, so the wake/poll/de-dup logic
  * is exercisable with no live backend at all.
  *
- * All THREE are the callers, and the count matters to a reader here: it means there
- * is exactly ONE delivery algorithm in this repo, and it is the code below. The
+ * All THREE engines are callers, and the count matters to a reader here: it means
+ * there is exactly ONE delivery algorithm in this repo, and it is the code below. The
  * in-memory store is a caller like the rest — it hands in a `fetch` over its log
  * `Ref` and its append `PubSub` as a wake source and keeps no delivery logic of its
  * own — which is what makes the shared contract suite's subscribe cases a comparison
  * of two BACKENDS rather than of two delivery algorithms.
  *
- * Correctness rests on the periodic position-based reconcile — a re-read from the
+ * Correctness rests on the periodic cursor-based reconcile — a re-read from the
  * cursor every poll interval — and NEVER on the wake source, which only lowers
  * delivery latency below that interval. A subscription with no wake source at all
  * is therefore complete and correct, merely slower, which is why `listen` is
  * optional in the TYPE rather than by the convention of passing `Stream.never`:
  * poll-only delivery is a supported shape, not a degraded one.
  *
- * ## The precondition every engine inherits: ASCENDING COMMIT ORDER
+ * ## The precondition every caller inherits: ASCENDING COMMIT ORDER
  *
- * A position that is committed and VISIBLE must never be below one already
- * delivered. Gaps are fine: the cursor is an ascending exclusive lower bound, so a
- * number that is allocated and never committed, or never allocated at all, is
- * simply a number the machine never sees. Out-of-order commits are not fine. If one
+ * It binds EVERY caller, over whatever cursor it chose — an engine's `Position`, or
+ * any other `C` handed to `subscribeItems` — and the example below is written in
+ * positions only because the engines are the callers it was first written for. A
+ * cursor that is committed and VISIBLE must never be below one already delivered.
+ * Gaps are fine: the cursor is an ascending exclusive lower bound, so a number
+ * that is allocated and never committed, or never allocated at all, is simply a
+ * number the machine never sees. Out-of-order commits are not fine. If one
  * writer allocates position 5 and another allocates 6, and 6 commits first, a poll
  * landing between the two commits delivers 6 and advances the cursor past it — and
  * 5 is then lost forever, because no later read looks below the cursor and nothing
- * anywhere notices the hole. An engine whose concurrent writers can commit out of
+ * anywhere notices the hole. A caller whose concurrent writers can commit out of
  * order MUST serialise them, or this machine will silently skip. An engine that
  * takes an exclusive lock on both of its append paths discharges the obligation
  * that way; an engine whose append is a single statement discharges it
  * structurally.
  *
  * The obligation is written down HERE, in the algorithm that depends on it, rather
- * than in whichever engine happens to satisfy it. It is a property of this delivery
- * loop and of nothing else, so an engine author reading only their own source has
+ * than in whichever caller happens to satisfy it. It is a property of this delivery
+ * loop and of nothing else, so an author reading only their own source has
  * no way to discover that anything downstream needs it — and the failure mode is
  * the worst kind there is: no error, no defect, no failing test, just an event that
  * a subscriber never receives. A single engine owning both its append path and its
  * own wake loop can leave the assumption implicit; a shared machine cannot.
  *
- * ## `catchUpPageSize` bounds the READ, not the emission
+ * ## `catchUpPageSize` bounds the READ, not the emission — unless `emit: 'page'`
  *
- * `drainFrom` below PAGES the catch-up read — `catchUpPageSize` bounds each
- * `fetch` — but it COLLECTS every page into one array, which is emitted as a SINGLE
- * chunk. So peak memory at subscription start is O(backlog) rather than O(page): a
+ * Under the default `emit: 'backlog'`, which is what `subscribeStream` and so every
+ * engine uses, `drainFrom` below PAGES the catch-up read — `catchUpPageSize` bounds
+ * each `fetch` — but it COLLECTS every page into one array, which is emitted as a
+ * SINGLE chunk. So peak memory at subscription start is O(backlog) rather than O(page): a
  * subscriber joining behind a large log materialises the whole backlog before its
  * consumer sees the first element.
  *
@@ -67,6 +80,19 @@
  * stay small even against a one-chunk catch-up. The cost therefore lands on backlog
  * memory alone, and it lands hardest on the durable-log-with-in-memory-view mode,
  * where an ephemeral view re-catches-up the entire log on every boot.
+ *
+ * `emit: 'page'` changes exactly that and nothing else. Each fetched page is
+ * emitted as its own chunk and the cursor advances past it before the next read, so
+ * peak memory is O(page) and the consumer sees the first item after ONE read rather
+ * than after the whole backlog. Delivery is unchanged: the same items in the same
+ * order, the same de-dup, the same wake and poll. What a caller gives up is the
+ * one-chunk catch-up, so it must not read meaning into chunk boundaries under
+ * either mode. It is for a consumer that does NOT re-chunk downstream and whose
+ * catch-up can be the whole of a large source — a full resync of a table, say —
+ * where holding the backlog would be the cost the paging was meant to avoid. The
+ * engines keep `'backlog'` because the read side's re-chunking already bounds what
+ * they commit, and changing their emission would move a behaviour nobody asked to
+ * move.
  */
 import { Effect, Schema, type Scope, Stream } from 'effect';
 import type { Position, SequencedEvent } from './Event.js';
@@ -130,9 +156,74 @@ export declare const subscriptionTuningFields: {
     readonly catchUpPageSize: Schema.optionalKey<Schema.Int>;
 };
 /**
- * The two seams the subscribe machine runs over, plus the two tuning knobs. `E` is
- * the engine's own infrastructure error — whatever its reads fail with — and it
- * stays on the channel through to `makeContractStore`, which dies it.
+ * How a subscription hands its catch-up to the consumer: the whole backlog as ONE
+ * chunk (`'backlog'`), or each fetched page as a chunk of its own (`'page'`). The
+ * module doc's "`catchUpPageSize` bounds the READ" section owns what each costs.
+ *
+ * A closed union of two words rather than a boolean, so a call site says WHICH
+ * behaviour it chose instead of what it turned off, and a third shape, should one
+ * ever be argued for, is added beside these rather than encoded in a second flag.
+ */
+export type SubscriptionEmission = 'backlog' | 'page';
+/**
+ * The machine's inputs over ANY item `A` with an ascending cursor `C`: the two seams,
+ * where the cursor comes from and starts, and the tuning.
+ *
+ * Generic in the item and the cursor because nothing in the algorithm is about an
+ * EVENT. The wake queue, the poll, the paged reconcile and the exclusive-lower-bound
+ * de-dup need only three things of what they deliver: a page-read strictly after a
+ * cursor, a way to read the cursor OFF a delivered item, and a starting cursor. A
+ * log of `SequencedEvent`s ordered by `Position` is one such source; a feed of rows
+ * ordered by a feed-local sequence is another, and a second copy of this loop for it
+ * would be exactly the divergence the module doc argues against.
+ *
+ * The machine never COMPARES two cursors. `fetch` is the only thing that interprets
+ * one — its exclusive lower bound is what does the de-dup — so `C` needs no ordering
+ * instance here, and the ascending-commit-order obligation in the module doc is the
+ * caller's, stated over whatever `C` it chose.
+ *
+ * `initial` is REQUIRED, unlike `subscribeStream`'s `after`. Only a cursor type the
+ * machine knows can have a default — `ORIGIN` for `Position` — and for any other the
+ * caller is the only party that knows what "before everything" is.
+ *
+ * `pollInterval` and `catchUpPageSize` are optional here and fall back to
+ * `DEFAULT_POLL_INTERVAL_MILLIS` and `DEFAULT_CATCH_UP_PAGE_SIZE`: a caller with no
+ * config of its own takes the same figures every engine does, from the same place.
+ * The event-store shape, `SubscriptionDeps`, keeps them required, because every
+ * engine already resolves them from its config and that type is unchanged.
+ */
+export interface ItemSubscriptionDeps<A, C, E> {
+    /**
+     * Page-read the items strictly after `after`, up to `limit`, ascending by cursor.
+     * Returning FEWER than `limit` signals the tail is drained. The exclusive lower
+     * bound IS the de-dup: a re-read from the cursor never returns what was delivered.
+     */
+    readonly fetch: (after: C, limit: ReadLimit) => Effect.Effect<ReadonlyArray<A>, E>;
+    /** The cursor of a delivered item: the next `fetch` starts strictly after it. */
+    readonly cursorOf: (item: A) => C;
+    /** The cursor to start from, exclusive: the first `fetch` reads strictly after it. */
+    readonly initial: C;
+    /** The raw wake source — see `SubscriptionDeps.listen`, whose rules it shares. */
+    readonly listen?: Stream.Stream<unknown, E>;
+    /**
+     * The poll interval in milliseconds (default `DEFAULT_POLL_INTERVAL_MILLIS`):
+     * finite and greater than 0, or `subscribeItems` dies.
+     */
+    readonly pollInterval?: number;
+    /**
+     * The catch-up page size (default `DEFAULT_CATCH_UP_PAGE_SIZE`): an integer
+     * greater than 0, or `subscribeItems` dies.
+     */
+    readonly catchUpPageSize?: number;
+    /** The catch-up's chunking (default `'backlog'`); see `SubscriptionEmission`. */
+    readonly emit?: SubscriptionEmission;
+}
+/**
+ * The two seams the event-store subscribe machine runs over, plus the two tuning
+ * knobs: `ItemSubscriptionDeps` fixed to `SequencedEvent` and `Position`, the shape
+ * every engine's `subscribe` already hands to `subscribeStream`. `E` is the engine's
+ * own infrastructure error — whatever its reads fail with — and it stays on the
+ * channel through to `makeContractStore`, which dies it.
  *
  * ONE type parameter and not two, deliberately: a wake source with an error type of
  * its own is `Stream.orDie`d by the caller, yielding a `Stream<unknown, never>`
@@ -164,12 +255,35 @@ export interface SubscriptionDeps<E> {
     readonly catchUpPageSize: number;
 }
 /**
- * Build the subscription `Stream`: catch up from `after`, then track the live tail.
- * The cursor threads through the `Stream.paginate` state, starting at `after` and
- * advancing to the last delivered position each batch; the stream never completes
- * on its own (the next state is always `Option.some`), so the enclosing scope
- * interrupts it on close. An `E` mid-stream stays on the channel; `makeContractStore` dies it
- * (subscribe is `E = never` on the contract).
+ * Build a subscription `Stream` over any ascending-cursor source: catch up from
+ * `initial`, then track the live tail. The cursor threads through the
+ * `Stream.paginate` state, starting at `initial` and advancing to the cursor of the
+ * last delivered item each batch; the stream never completes on its own (the next
+ * state is always `Option.some`), so the enclosing scope interrupts it on close. An
+ * `E` mid-stream stays on the channel, for the caller to die or to supervise.
+ *
+ * This is THE delivery algorithm, and `subscribeStream` runs the same machine. Under
+ * `emit: 'backlog'` a batch is everything a drain to the tail returned; under
+ * `'page'` it is one fetched page, so the paginate step and the page coincide and a
+ * full page is followed at once by the next read rather than by a wait.
+ *
+ * A `pollInterval` or `catchUpPageSize` the config fields would refuse is a DEFECT
+ * here, raised by the stream before it reads or forks anything, with a message
+ * naming the field. This caller may have no config whose decode would have caught
+ * it, and unchecked the two failures are silent or late: a page size of 0 gives a
+ * stream that never emits and never fails, and 1.5 dies only at the first read,
+ * inside `ReadLimit`, in words that name neither knob.
+ */
+export declare const subscribeItems: <A, C, E>(deps: ItemSubscriptionDeps<A, C, E>) => Stream.Stream<A, E, Scope.Scope>;
+/**
+ * Build the event subscription `Stream`: catch up from `after`, then track the live
+ * tail. A THIN wrapper over the machine `subscribeItems` runs, fixing the item to
+ * `SequencedEvent`, the cursor to its `position`, the start to `ORIGIN` when `after`
+ * is absent, and the emission to the default `'backlog'` — so every engine's call
+ * site, and every figure it delivers, is what it was before the machine became
+ * generic. It skips `subscribeItems`' tuning check, for the reason on `machine`. An `E`
+ * mid-stream stays on the channel; `makeContractStore` dies it (subscribe is
+ * `E = never` on the contract).
  */
 export declare const subscribeStream: <E>(deps: SubscriptionDeps<E>, after: Position | undefined) => Stream.Stream<SequencedEvent, E, Scope.Scope>;
 //# sourceMappingURL=SubscribeMachine.d.ts.map

package/dist/dts-cjs/SubscribeMachine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SubscribeMachine.d.ts","sourceRoot":"","sources":["../../src/SubscribeMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,EACL,MAAM,EAIN,MAAM,EACN,KAAK,KAAK,EACV,MAAM,EACP,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,EAAU,SAAS,EAAE,MAAM,SAAS,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAA;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,wBAAwB;;;CAO3B,CAAA;AAiBV;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,SAAS,KACb,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAA;IACpD;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3C,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,MAAM,gBAAgB,CAAC,CAAC,CAAC,EACzB,OAAO,QAAQ,GAAG,SAAS,KAC1B,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CA+G5C,CAAA"}
+{"version":3,"file":"SubscribeMachine.d.ts","sourceRoot":"","sources":["../../src/SubscribeMachine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+FG;AACH,OAAO,EACL,MAAM,EAIN,MAAM,EACN,KAAK,KAAK,EACV,MAAM,EACP,MAAM,QAAQ,CAAA;AACf,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,EAAU,SAAS,EAAE,MAAM,SAAS,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,MAAM,CAAA;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAA;AAWhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,wBAAwB;;;CAG3B,CAAA;AA2CV;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,MAAM,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,KAAK,EAAE,CAAC,EACR,KAAK,EAAE,SAAS,KACb,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACvC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAA;IACjC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,oBAAoB,CAAA;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,SAAS,KACb,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAA;IACpD;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC3C,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EACpC,MAAM,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAClC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAGjC,CAAA;AA4HD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,MAAM,gBAAgB,CAAC,CAAC,CAAC,EACzB,OAAO,QAAQ,GAAG,SAAS,KAC1B,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,EAAE,KAAK,CAAC,KAAK,CAQ3C,CAAA"}