@kairos-es/core 0.0.0

package/dist/esm/SubscribeMachine.js

@@ -0,0 +1,227 @@
+/**
+ * The subscribe machine every engine's `subscribe` is built from — the in-memory
+ * store, `@kairos-es/store-postgres` and `@kairos-es/store-sqlite`: the wake queue,
+ * the wake-source drain, the paged catch-up reconcile, the `> boundary` de-dup (via
+ * the cursor's exclusive lower bound) and the poll loop that together turn a paged
+ * read into a live subscription.
+ *
+ * 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
+ * behaviour whole, exactly as it supplies mechanics to `makeContractStore` and
+ * inherits the contract policy whole. Two engines that each grew their own wake
+ * loop would be identical only by inspection, and `subscribe` is the verb where
+ * that is least affordable: a divergence there loses events rather than failing.
+ * 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
+ * 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
+ * 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
+ *
+ * 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
+ * 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
+ * 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
+ * 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
+ *
+ * `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.
+ *
+ * That is a memory characteristic and nothing more, which is why ONE chunk is
+ * enough here: downstream commit boundaries do not depend on the upstream chunking
+ * at all, because the read side's `Stream.groupedWithin` re-chunks the stream into
+ * bounded micro-batches whatever arrives (ADR-0007), so a projection's transactions
+ * 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.
+ */
+import { Chunk, Effect, Option, Queue, Schedule, Schema, Stream } from 'effect';
+import { ORIGIN, ReadLimit } from "./Event.js";
+/**
+ * A short catch-up page size default for the reconcile loop. Reads page by page
+ * until a short page signals the tail is drained, so a large backlog is streamed in
+ * bounded chunks rather than one unbounded read. Every engine takes its
+ * `catchUpPageSize` from here — each SQL engine as its config's default, the
+ * in-memory store as its options' — so backends cannot drift on tuning.
+ */
+export const DEFAULT_CATCH_UP_PAGE_SIZE = 512;
+/**
+ * The default upper bound a subscriber waits for a wake before re-reading from its
+ * cursor ANYWAY (milliseconds). Every engine takes its `pollInterval` from here —
+ * each SQL engine as its config's default, the in-memory store as its options' — so
+ * backends cannot drift on tuning.
+ *
+ * This periodic position-based poll — not the wake source — IS the correctness
+ * guarantee: every committed position is reconciled within this interval whether or
+ * not a wake for it was ever heard. That covers a wake fired before the source was
+ * fully established, a coalesced or dropped wake, and a wake source that died
+ * silently and never said so. A wake source only lowers delivery latency BELOW this
+ * interval; it never carries delivery, so no engine's wake mechanism can make the
+ * right figure here engine-specific. It trades worst-case delivery latency against
+ * idle read volume and nothing else. Upstream `postgres_tt.py` picks the same
+ * one-second fallback poll (`conn.wait(..., interval=1)`).
+ */
+export const DEFAULT_POLL_INTERVAL_MILLIS = 1000;
+/**
+ * The two subscribe-tuning config FIELDS, for an engine whose config is a `Schema`
+ * to spread into its own struct.
+ *
+ * These knobs are the machine's, not any engine's: they name what the loop above
+ * does, the figures they fall back to are the two constants declared beside them,
+ * and neither is derivable from a backend's own properties — which is why the
+ * defaults already live here. Shipping the FIELD rather than only the default is
+ * what closes the last gap in that arrangement. An engine that spreads these gets
+ * the key NAME, the VALIDATION and the DEFAULT from one place, so a caller who has
+ * tuned one engine's subscribe reads another's without translating, and the two
+ * cannot drift in what they ACCEPT any more than in what they assume. Two engines
+ * hand-authoring the identical `Schema.optionalWith(…)` twice were identical only
+ * by inspection.
+ *
+ * The bounds differ between the two because the quantities do. `pollInterval` is a
+ * duration, so a fraction of a millisecond is meaningful and only `positive` and
+ * `finite` matter: at zero or below the loop would spin without ever waiting for a
+ * wake, and at `Infinity` the periodic re-read — the half that carries delivery —
+ * would never come, which silently converts the wake source from an optimisation
+ * into the guarantee. `catchUpPageSize` is a COUNT, so it must be an integer
+ * (`Schema.Int` excludes `Infinity` with it): the reconcile loop compares a page's
+ * length against it to decide the tail is drained, and a page of zero would report
+ * "drained" forever without reading anything.
+ *
+ * `exact: true` on both keeps the decoded type at `key?: T` rather than
+ * `T | undefined`, matching the repo's `exactOptionalPropertyTypes` discipline — an
+ * absent key, never an explicit `undefined`.
+ */
+export const subscriptionTuningFields = {
+  pollInterval: /*#__PURE__*/Schema.optionalWith(/*#__PURE__*/Schema.Number.pipe(/*#__PURE__*/Schema.positive(), /*#__PURE__*/Schema.finite()), {
+    exact: true
+  }),
+  catchUpPageSize: /*#__PURE__*/Schema.optionalWith(/*#__PURE__*/Schema.Int.pipe(/*#__PURE__*/Schema.positive()), {
+    exact: true
+  })
+};
+/**
+ * Retry a TRANSIENT poll fault (an `E` from one reconcile read) on a capped
+ * exponential backoff rather than letting `Stream.orDie` kill a subscription that
+ * may have been alive for days over a single connection blip. A fault that PERSISTS
+ * past the cap propagates (the decorator dies it) — infrastructure stays off the
+ * contract channel while the stream survives ordinary transients.
+ */
+const POLL_RETRY_SCHEDULE = /*#__PURE__*/Schedule.exponential('100 millis', 2).pipe(/*#__PURE__*/Schedule.union(/*#__PURE__*/Schedule.spaced('2 seconds')), /*#__PURE__*/Schedule.intersect(/*#__PURE__*/Schedule.recurs(20)));
+/**
+ * Build the subscription `Stream`: catch up from `after`, then track the live tail.
+ * The cursor threads through the `unfoldChunkEffect` unfold state, starting at
+ * `after` and advancing to the last delivered position each batch; the stream never
+ * completes on its own (always `Option.some`), so the enclosing scope interrupts it
+ * on close. An `E` mid-stream stays on the channel; `makeContractStore` dies it
+ * (subscribe is `E = never` on the contract).
+ */
+export const subscribeStream = (deps, after) => Stream.unwrapScoped(Effect.gen(function* () {
+  // The wake primitive: a sliding(1) queue holding at most one pending
+  // signal. The wake source `offer`s an opaque wake on every notification;
+  // the poll loop `take`s (with a timeout). The lost-wakeup guard is
+  // STRUCTURAL — drain the queue BEFORE reading, so a wake that lands
+  // mid-read leaves a fresh signal that makes the next `take` return at once
+  // rather than sleeping through a real change.
+  const wake = yield* Queue.sliding(1);
+  // Tap every notification into the wake queue. If the wake source DOES
+  // surface an error, re-subscribe with capped-exponential backoff. Many wake
+  // sources do not error on a dropped connection at all — they simply go
+  // quiet — so this retry is NOT the reconnect guarantee: the poll fallback
+  // below is. The reconcile loop re-reads from the cursor on every poll, so a
+  // silently-dropped (and later re-established) wake source loses no
+  // positions. Absent a wake source entirely, `Stream.never` makes this a
+  // fibre that parks forever and delivery falls to the poll alone.
+  const listener = (deps.listen ?? Stream.never).pipe(Stream.tap(() => Queue.offer(wake, undefined)), Stream.retry(Schedule.exponential('50 millis').pipe(Schedule.union(Schedule.spaced('1 seconds')))));
+  // Drain the wake source into the wake queue on a background fibre; the
+  // scope releases it. We never read its elements directly — every
+  // notification is an opaque wake signal.
+  yield* listener.pipe(Stream.runDrain, Effect.forkScoped);
+  // Reconcile: page-read from `from` until a short page, advancing to the last
+  // delivered position. Retries a TRANSIENT poll fault on a capped schedule so
+  // a single connection blip does not kill a days-long subscription; a
+  // persistent fault propagates and dies.
+  const drainFrom = from => Effect.gen(function* () {
+    const collected = [];
+    let cursor = from;
+    // Loop pages until a short page signals the tail is drained.
+    while (true) {
+      const events = yield* deps.fetch(cursor, ReadLimit.make(deps.catchUpPageSize));
+      for (const event of events) {
+        collected.push(event);
+      }
+      const lastEvent = events.at(-1);
+      if (lastEvent === undefined || events.length < deps.catchUpPageSize) {
+        break;
+      }
+      cursor = lastEvent.position;
+    }
+    const last = collected.at(-1)?.position ?? from;
+    return {
+      events: collected,
+      last
+    };
+  }).pipe(Effect.retry(POLL_RETRY_SCHEDULE));
+  /**
+   * Produce the NEXT non-empty batch from a cursor position, together with
+   * the advanced cursor — a pure `Position → Effect<[Chunk, next]>`. The
+   * `> boundary` de-dup is enforced by `fetch`'s exclusive lower bound, so a
+   * live re-read after a wake never re-emits an already-delivered position.
+   *
+   * Drain the wake queue BEFORE reading (lost-wakeup guard), then drain from
+   * the cursor. If a drain yields nothing, wait for a wake but only up to the
+   * poll interval, then loop and re-read ANYWAY — the periodic position-based
+   * poll that makes delivery correct independently of any wake. This effect
+   * only completes by returning a non-empty chunk; the scope interrupts it on
+   * close.
+   */
+  const nextBatch = from => Effect.gen(function* () {
+    while (true) {
+      yield* Queue.takeAll(wake);
+      const {
+        events,
+        last
+      } = yield* drainFrom(from);
+      if (events.length > 0) {
+        return [Chunk.fromIterable(events), last];
+      }
+      // Nothing new: block on a wake, but only up to the poll interval — on
+      // timeout we fall through and the loop re-reads regardless.
+      yield* Effect.ignore(Effect.timeout(Queue.take(wake), deps.pollInterval));
+    }
+  });
+  return Stream.unfoldChunkEffect(after ?? ORIGIN, from => Effect.map(nextBatch(from), Option.some));
+}));
+//# sourceMappingURL=SubscribeMachine.js.map

package/dist/esm/SubscribeMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubscribeMachine.js","names":["Chunk","Effect","Option","Queue","Schedule","Schema","Stream","ORIGIN","ReadLimit","DEFAULT_CATCH_UP_PAGE_SIZE","DEFAULT_POLL_INTERVAL_MILLIS","subscriptionTuningFields","pollInterval","optionalWith","Number","pipe","positive","finite","exact","catchUpPageSize","Int","POLL_RETRY_SCHEDULE","exponential","union","spaced","intersect","recurs","subscribeStream","deps","after","unwrapScoped","gen","wake","sliding","listener","listen","never","tap","offer","undefined","retry","runDrain","forkScoped","drainFrom","from","collected","cursor","events","fetch","make","event","push","lastEvent","at","length","position","last","nextBatch","takeAll","fromIterable","ignore","timeout","take","unfoldChunkEffect","map","some"],"sources":["../../src/SubscribeMachine.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsEA,SACEA,KAAK,EACLC,MAAM,EACNC,MAAM,EACNC,KAAK,EACLC,QAAQ,EACRC,MAAM,EAENC,MAAM,QACD,QAAQ;AAEf,SAASC,MAAM,EAAEC,SAAS,QAAQ,YAAS;AAE3C;;;;;;;AAOA,OAAO,MAAMC,0BAA0B,GAAG,GAAG;AAE7C;;;;;;;;;;;;;;;;AAgBA,OAAO,MAAMC,4BAA4B,GAAG,IAAI;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,MAAMC,wBAAwB,GAAG;EACtCC,YAAY,eAAEP,MAAM,CAACQ,YAAY,cAC/BR,MAAM,CAACS,MAAM,CAACC,IAAI,cAACV,MAAM,CAACW,QAAQ,EAAE,eAAEX,MAAM,CAACY,MAAM,EAAE,CAAC,EACtD;IAAEC,KAAK,EAAE;EAAI,CAAE,CAChB;EACDC,eAAe,eAAEd,MAAM,CAACQ,YAAY,cAACR,MAAM,CAACe,GAAG,CAACL,IAAI,cAACV,MAAM,CAACW,QAAQ,EAAE,CAAC,EAAE;IACvEE,KAAK,EAAE;GACR;CACO;AAEV;;;;;;;AAOA,MAAMG,mBAAmB,gBAAGjB,QAAQ,CAACkB,WAAW,CAAC,YAAY,EAAE,CAAC,CAAC,CAACP,IAAI,cACpEX,QAAQ,CAACmB,KAAK,cAACnB,QAAQ,CAACoB,MAAM,CAAC,WAAW,CAAC,CAAC,eAC5CpB,QAAQ,CAACqB,SAAS,cAACrB,QAAQ,CAACsB,MAAM,CAAC,EAAE,CAAC,CAAC,CACxC;AAwCD;;;;;;;;AAQA,OAAO,MAAMC,eAAe,GAAGA,CAC7BC,IAAyB,EACzBC,KAA2B,KAE3BvB,MAAM,CAACwB,YAAY,CACjB7B,MAAM,CAAC8B,GAAG,CAAC,aAAS;EAClB;EACA;EACA;EACA;EACA;EACA;EACA,MAAMC,IAAI,GAAG,OAAO7B,KAAK,CAAC8B,OAAO,CAAO,CAAC,CAAC;EAE1C;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMC,QAAQ,GAAG,CAACN,IAAI,CAACO,MAAM,IAAI7B,MAAM,CAAC8B,KAAK,EAAErB,IAAI,CACjDT,MAAM,CAAC+B,GAAG,CAAC,MAAMlC,KAAK,CAACmC,KAAK,CAACN,IAAI,EAAEO,SAAS,CAAC,CAAC,EAC9CjC,MAAM,CAACkC,KAAK,CACVpC,QAAQ,CAACkB,WAAW,CAAC,WAAW,CAAC,CAACP,IAAI,CACpCX,QAAQ,CAACmB,KAAK,CAACnB,QAAQ,CAACoB,MAAM,CAAC,WAAW,CAAC,CAAC,CAC7C,CACF,CACF;EACD;EACA;EACA;EACA,OAAOU,QAAQ,CAACnB,IAAI,CAACT,MAAM,CAACmC,QAAQ,EAAExC,MAAM,CAACyC,UAAU,CAAC;EAExD;EACA;EACA;EACA;EACA,MAAMC,SAAS,GACbC,IAAc,IAQd3C,MAAM,CAAC8B,GAAG,CAAC,aAAS;IAClB,MAAMc,SAAS,GAA0B,EAAE;IAC3C,IAAIC,MAAM,GAAGF,IAAI;IACjB;IACA,OAAO,IAAI,EAAE;MACX,MAAMG,MAAM,GAAG,OAAOnB,IAAI,CAACoB,KAAK,CAC9BF,MAAM,EACNtC,SAAS,CAACyC,IAAI,CAACrB,IAAI,CAACT,eAAe,CAAC,CACrC;MACD,KAAK,MAAM+B,KAAK,IAAIH,MAAM,EAAE;QAC1BF,SAAS,CAACM,IAAI,CAACD,KAAK,CAAC;MACvB;MACA,MAAME,SAAS,GAAGL,MAAM,CAACM,EAAE,CAAC,CAAC,CAAC,CAAC;MAC/B,IACED,SAAS,KAAKb,SAAS,IACvBQ,MAAM,CAACO,MAAM,GAAG1B,IAAI,CAACT,eAAe,EACpC;QACA;MACF;MACA2B,MAAM,GAAGM,SAAS,CAACG,QAAQ;IAC7B;IACA,MAAMC,IAAI,GAAGX,SAAS,CAACQ,EAAE,CAAC,CAAC,CAAC,CAAC,EAAEE,QAAQ,IAAIX,IAAI;IAC/C,OAAO;MAAEG,MAAM,EAAEF,SAAS;MAAEW;IAAI,CAAE;EACpC,CAAC,CAAC,CAACzC,IAAI,CAACd,MAAM,CAACuC,KAAK,CAACnB,mBAAmB,CAAC,CAAC;EAE5C;;;;;;;;;;;;;EAaA,MAAMoC,SAAS,GACbb,IAAc,IAEd3C,MAAM,CAAC8B,GAAG,CAAC,aAAS;IAClB,OAAO,IAAI,EAAE;MACX,OAAO5B,KAAK,CAACuD,OAAO,CAAC1B,IAAI,CAAC;MAC1B,MAAM;QAAEe,MAAM;QAAES;MAAI,CAAE,GAAG,OAAOb,SAAS,CAACC,IAAI,CAAC;MAC/C,IAAIG,MAAM,CAACO,MAAM,GAAG,CAAC,EAAE;QACrB,OAAO,CAACtD,KAAK,CAAC2D,YAAY,CAACZ,MAAM,CAAC,EAAES,IAAI,CAAU;MACpD;MACA;MACA;MACA,OAAOvD,MAAM,CAAC2D,MAAM,CAClB3D,MAAM,CAAC4D,OAAO,CAAC1D,KAAK,CAAC2D,IAAI,CAAC9B,IAAI,CAAC,EAAEJ,IAAI,CAAChB,YAAY,CAAC,CACpD;IACH;EACF,CAAC,CAAC;EAEJ,OAAON,MAAM,CAACyD,iBAAiB,CAAClC,KAAK,IAAItB,MAAM,EAAGqC,IAAI,IACpD3C,MAAM,CAAC+D,GAAG,CAACP,SAAS,CAACb,IAAI,CAAC,EAAE1C,MAAM,CAAC+D,IAAI,CAAC,CACzC;AACH,CAAC,CAAC,CACH","ignoreList":[]}

package/dist/esm/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Tagged errors for the store contract. Conflicts are values on the error
+ * channel, never defects.
+ */
+import { Data } from 'effect';
+/**
+ * Raised by `append` when the append condition's `failIfEventsMatch` query
+ * matches at least one event after `condition.after`. Carries only the
+ * offending condition: a correct retry re-reads the store to its new head and
+ * rebuilds its condition from there, so no conflicting position is carried (it
+ * would already be stale by the time it was acted on).
+ */
+export class AppendConditionFailed extends /*#__PURE__*/Data.TaggedError('AppendConditionFailed') {}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":["Data","AppendConditionFailed","TaggedError"],"sources":["../../src/errors.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;AAIA,SAASA,IAAI,QAAQ,QAAQ;AAG7B;;;;;;;AAOA,OAAM,MAAOC,qBAAsB,sBAAQD,IAAI,CAACE,WAAW,CACzD,uBAAuB,CAGvB","ignoreList":[]}

package/dist/esm/inMemory.js

@@ -0,0 +1,184 @@
+import { Effect, Layer, PubSub, Ref, Stream } from 'effect';
+import { makeContractStore } from "./ContractStore.js";
+import { DcbEventStore } from "./DcbEventStore.js";
+import { ORIGIN } from "./Event.js";
+import { AppendConditionFailed } from "./errors.js";
+import { matchesSequenced } from "./Query.js";
+import { DEFAULT_CATCH_UP_PAGE_SIZE, DEFAULT_POLL_INTERVAL_MILLIS, subscribeStream } from "./SubscribeMachine.js";
+/** Filter a snapshot by `query` and `after` (strict `position > after`). */
+const filterLog = (log, query, after) => log.filter(sequenced => (after === undefined || sequenced.position > after) && matchesSequenced(sequenced, query));
+/** The position of the last event in a slice, or `undefined` when empty. */
+const lastPosition = events => events.at(-1)?.position;
+/**
+ * Compute the read result over a snapshot: filter, apply the limit, and derive
+ * `head` per the contract (no limit => global last position or ORIGIN; limit =>
+ * last returned position or ORIGIN).
+ */
+const readSnapshot = (log, query, options) => {
+  const matched = filterLog(log, query, options?.after);
+  const limited = options?.limit === undefined ? matched : matched.slice(0, options.limit);
+  // No limit => head is the global last position (ignoring the filter). With a
+  // limit => head is the last returned event's position. Either way, ORIGIN
+  // when there is nothing to report.
+  const head = (options?.limit === undefined ? lastPosition(log) : lastPosition(limited)) ?? ORIGIN;
+  return {
+    events: Stream.fromIterable(limited),
+    head
+  };
+};
+/**
+ * The index of the first event strictly after `after`, by BINARY SEARCH.
+ *
+ * The log is append-only and ascending by position, so the cursor cut is a boundary
+ * in a sorted array and costs O(log n). That is what makes a live subscription's
+ * idle poll affordable at any log size: the poll re-reads from its cursor every
+ * interval whether or not anything arrived, so a linear cut would charge every open
+ * subscription O(n) per interval for as long as it stayed open.
+ */
+const firstIndexAfter = (log, after) => {
+  let low = 0;
+  let high = log.length;
+  while (low < high) {
+    // `>>> 1` rather than a divide: an integer midpoint with no rounding step.
+    const mid = low + high >>> 1;
+    if (log[mid].position > after) {
+      high = mid;
+    } else {
+      low = mid + 1;
+    }
+  }
+  return low;
+};
+/**
+ * `subscribeStream`'s `fetch` seam: up to `limit` events matching `query` strictly
+ * after `from`, ascending.
+ *
+ * The cursor cut comes FIRST and the query match second, so the predicate only ever
+ * sees candidates the cursor admits, and the scan stops the moment `limit` of them
+ * have matched rather than filtering a tail it would discard.
+ *
+ * Deliberately not expressed through `filterLog`, and the reason is COST rather than
+ * the answer: that form returns the same events and scans the whole log per page.
+ *
+ * What is not interchangeable is what the cap COUNTS. The machine's paging contract
+ * reads a SHORT page as "the tail is drained", so the cap has to count MATCHES and a
+ * short page has to mean the scan ran off the end of the log. A cap counting
+ * CANDIDATES — `limit` events taken by POSITION, with the predicate applied within
+ * them — reports a short page for a window that merely held few matches; and a window
+ * holding NONE reports a drained tail while advancing the cursor nowhere, so the
+ * subscription is WEDGED rather than delayed, with no later poll able to move it.
+ * `InMemoryStoreOptions.catchUpPageSize` is what puts a test at that boundary.
+ */
+const fetchPage = (log, query, from, limit) => {
+  const page = [];
+  for (let index = firstIndexAfter(log, from); index < log.length && page.length < limit; index += 1) {
+    const sequenced = log[index];
+    if (matchesSequenced(sequenced, query)) {
+      page.push(sequenced);
+    }
+  }
+  return page;
+};
+/**
+ * Build the in-memory store MECHANICS (a `RawDcbEventStore`), wiring the Ref,
+ * semaphore and hub. The contract-enforcement policy (`assertServableQuery`,
+ * `ReadLimit` decode, error-vs-defect classification) is NOT here — it is added
+ * uniformly by `makeContractStore`, so this engine is pure mechanics.
+ */
+const make = options => Effect.gen(function* () {
+  const beforeCommit = options?.beforeCommit ?? Effect.void;
+  const suppressWake = options?.suppressWake ?? false;
+  const catchUpPageSize = options?.catchUpPageSize ?? DEFAULT_CATCH_UP_PAGE_SIZE;
+  const pollInterval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL_MILLIS;
+  const log = yield* Ref.make([]);
+  const mutex = yield* Effect.makeSemaphore(1);
+  const hub = yield* PubSub.unbounded();
+  const nextPosition = yield* Ref.make(1n);
+  const read = (query, options) =>
+  // The lock keeps read consistent with concurrent appends; popo.py's RLock
+  // is reentrant, so append's inner read re-enters. Here append inlines the
+  // read logic instead, so a plain lock suffices.
+  mutex.withPermits(1)(Effect.map(Ref.get(log), snapshot => readSnapshot(snapshot, query, options)));
+  const append = (events, condition) =>
+  // Critical section: check + commit are atomic (the exactly-one-wins guarantee).
+  mutex.withPermits(1)(Effect.gen(function* () {
+    const snapshot = yield* Ref.get(log);
+    if (condition !== undefined) {
+      const conflicts = filterLog(snapshot, condition.failIfEventsMatch, condition.after);
+      // Detect by presence: any matching event after `condition.after`
+      // fails the append. The error carries only the condition (see
+      // `AppendConditionFailed`); a correct retry re-reads to the new head.
+      if (conflicts.length > 0) {
+        return yield* new AppendConditionFailed({
+          condition
+        });
+      }
+    }
+    // Optional test seam between the conflict-check and the commit (see
+    // `InMemoryStoreOptions.beforeCommit`). Defaults to `Effect.void`, a
+    // synchronous no-op, so the shipped critical section stays atomic by
+    // construction; the concurrency contract test injects `Effect.yieldNow()`
+    // here to make the exactly-one-wins guard genuinely depend on the mutex.
+    yield* beforeCommit;
+    const start = yield* Ref.get(nextPosition);
+    const appended = events.map((event, index) => ({
+      event,
+      position: start + BigInt(index)
+    }));
+    const end = start + BigInt(events.length);
+    yield* Ref.set(log, [...snapshot, ...appended]);
+    yield* Ref.set(nextPosition, end);
+    // The hub is a WAKE SOURCE and nothing else: the subscribe machine never
+    // reads what it carries, and its poll delivers with or without one. That
+    // is why suppressing the publish is a legitimate test seam rather than a
+    // broken store (see `InMemoryStoreOptions.suppressWake`).
+    if (!suppressWake) {
+      yield* PubSub.publishAll(hub, appended);
+    }
+    // `events` is non-empty, so the last new position is `end - 1`.
+    return end - 1n;
+  }));
+  const subscribe = (query, after) =>
+  // Take the hub seat HERE, before handing the machine its wake source, so the
+  // subscription is established no later than the machine's first `fetch`. That
+  // ordering is what keeps delivery independent of the poll's timer: an append
+  // either lands before that first read, and the read sees it, or after the seat
+  // exists, and its wake is queued. The machine drains a wake source on a forked
+  // fibre, so a seat taken inside that fibre would leave a window in which an
+  // append publishes to nobody — recoverable by the next poll, but only on a
+  // real clock, and much of this store's use is under `TestClock`.
+  //
+  // No mutex: `Ref.get` already reads one committed snapshot, and the machine's
+  // exclusive cursor is what makes the catch-up/live seam exactly-once, so there
+  // is nothing left here for a critical section to protect. `append` keeps its
+  // permit, which is the whole exactly-one-wins guarantee.
+  Stream.unwrapScoped(Effect.gen(function* () {
+    const wakes = yield* PubSub.subscribe(hub);
+    return subscribeStream({
+      fetch: (from, limit) => Effect.map(Ref.get(log), snapshot => fetchPage(snapshot, query, from, limit)),
+      listen: Stream.fromQueue(wakes),
+      pollInterval,
+      catchUpPageSize
+    }, after);
+  }));
+  return {
+    read,
+    append,
+    subscribe
+  };
+});
+/** The in-memory `DcbEventStore` layer (production; no test seam). */
+export const DcbEventStoreInMemory = /*#__PURE__*/Layer.effect(DcbEventStore, /*#__PURE__*/Effect.map(/*#__PURE__*/make(), makeContractStore));
+/**
+ * Test-only in-memory layer factory: the same store as `DcbEventStoreInMemory`, but
+ * with `InMemoryStoreOptions`' seams open. Kept off the package's public surface
+ * (deliberately not re-exported from `index.ts`); production code always uses
+ * `DcbEventStoreInMemory`. Every seam exists to make a claim about this store
+ * FALSIFIABLE rather than merely commented — the store contract suite forces the
+ * check/commit interleaving the exactly-one-wins case needs, one core test takes the
+ * wake away and shortens the poll so that what delivers can only be the poll, and
+ * another lowers the catch-up page to reach the second-page boundary the shipped page
+ * size puts out of reach.
+ */
+export const makeInMemoryTestLayer = options => Layer.effect(DcbEventStore, Effect.map(make(options), makeContractStore));
+//# sourceMappingURL=inMemory.js.map

package/dist/esm/inMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemory.js","names":["Effect","Layer","PubSub","Ref","Stream","makeContractStore","DcbEventStore","ORIGIN","AppendConditionFailed","matchesSequenced","DEFAULT_CATCH_UP_PAGE_SIZE","DEFAULT_POLL_INTERVAL_MILLIS","subscribeStream","filterLog","log","query","after","filter","sequenced","undefined","position","lastPosition","events","at","readSnapshot","options","matched","limited","limit","slice","head","fromIterable","firstIndexAfter","low","high","length","mid","fetchPage","from","page","index","push","make","gen","beforeCommit","void","suppressWake","catchUpPageSize","pollInterval","mutex","makeSemaphore","hub","unbounded","nextPosition","read","withPermits","map","get","snapshot","append","condition","conflicts","failIfEventsMatch","start","appended","event","BigInt","end","set","publishAll","subscribe","unwrapScoped","wakes","fetch","listen","fromQueue","DcbEventStoreInMemory","effect","makeInMemoryTestLayer"],"sources":["../../src/inMemory.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/esm/index.js

@@ -0,0 +1,38 @@
+/**
+ * @kairos-es/core: DCB-first event-sourcing contract and in-memory store for
+ * Effect v3.
+ *
+ * Exposes the domain types (`DcbEvent`, `SequencedEvent`, `Position`, `Tag`,
+ * `EventType`), the selection language (`Query`, `QueryItem`, the pure match
+ * predicate + smart constructors, and the servable-shape dispatch every engine
+ * compiles its plans through), the `AppendCondition`, tagged errors, the
+ * `DcbEventStore` contract, the in-memory layer, the shared subscribe machine
+ * every engine's `subscribe` is built from (`SubscribeMachine.ts`), the pure
+ * projection primitives (`Projection`, `DecodedEvent`, `composeProjections`), and
+ * `retryOnConflict`.
+ *
+ * Core keeps only the *pure* fold: projections fold an already-`DecodedEvent`
+ * (decoding needs `Schema` + a `Serializer`, which core must not depend on).
+ * The event-def builder and the decode-aware `buildDecisionModel` live in
+ * `@kairos-es/codec`.
+ *
+ * `retryOnConflict` is here because it is the recovery half of the append
+ * condition — the only consistency mechanism there is. It matches the
+ * `AppendConditionFailed` core defines and needs nothing beyond `effect`'s
+ * `Schedule`, which core already peers, so homing it downstream only made a
+ * write-only consumer depend on a package it uses nothing else of (ADR-0008).
+ */
+export * from "./AppendCondition.js";
+export * from "./ContractStore.js";
+export * from "./DcbEventStore.js";
+export * from "./Event.js";
+export * from "./errors.js";
+// Named re-export (not `export *`): `DcbEventStoreInMemory` is the whole public
+// in-memory surface. `makeInMemoryTestLayer` / `InMemoryStoreOptions` are a
+// test-only seam and are deliberately kept off the package's public exports.
+export { DcbEventStoreInMemory } from "./inMemory.js";
+export * from "./Projection.js";
+export * from "./Query.js";
+export * from "./retryOnConflict.js";
+export * from "./SubscribeMachine.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["DcbEventStoreInMemory"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,cAAc,sBAAmB;AACjC,cAAc,oBAAiB;AAC/B,cAAc,oBAAiB;AAC/B,cAAc,YAAS;AACvB,cAAc,aAAU;AACxB;AACA;AACA;AACA,SAASA,qBAAqB,QAAQ,eAAY;AAClD,cAAc,iBAAc;AAC5B,cAAc,YAAS;AACvB,cAAc,sBAAmB;AACjC,cAAc,uBAAoB","ignoreList":[]}

package/dist/esm/package.json

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

package/dist/esm/retryOnConflict.js

@@ -0,0 +1,87 @@
+/**
+ * `retryOnConflict` — the decider-level retry for `AppendConditionFailed`
+ * (ADR-0008).
+ *
+ * `append` surfaces a conflict as a SIGNAL only: a tagged `AppendConditionFailed`
+ * flattened to the tripped condition, carrying no conflicting position,
+ * deliberately so that a retry cannot resume from a stale conflict point. A
+ * correct DCB retry must therefore re-derive its append-condition lower bound
+ * from a FRESH READ to the current head — which means re-running the whole
+ * read-decide-append cycle, not re-submitting the same events.
+ *
+ * That is why this is a combinator over a command and NOT a `Layer` decorating
+ * `DcbEventStore.append`. A decorator sees only the events and the condition; it
+ * cannot re-read the log and it cannot re-decide, so it is STRUCTURALLY incapable
+ * of a correct DCB retry — the only thing it could do is re-submit against a
+ * condition that is already known to be stale, which either fails again forever
+ * or, worse, succeeds against a boundary the decision was never made under. No
+ * retrying `Layer` is shipped, and if a production command-runner service ever
+ * emerges, a `Layer` over THAT (a whole cycle) is the shape to add.
+ *
+ * It lives HERE, in `@kairos-es/core`, because conflict retry is a WRITE-side
+ * concern and core is where the write side is defined: core declares the `append`
+ * contract, defines the `AppendConditionFailed` this combinator matches, and
+ * already peers `effect` for `Schedule`, so the move costs nothing and adds no
+ * dependency in either direction. It shipped from `@kairos-es/read` first on the
+ * argument that it added no peer surface there either — true, but an argument for
+ * where it MAY live, not where it SHOULD. What that home actually cost was a
+ * write-only consumer having to depend on the READ package to retry its own
+ * appends, for a combinator that touches no projection, no checkpoint and no view
+ * (ADR-0008, homing amended).
+ *
+ * Core stays pure with it here. `Schedule`'s driver reads the time through
+ * `Clock.currentTimeMillis` and sleeps through `Clock.sleep`, both resolved from
+ * the fibre's default services, so `TestClock` still governs every delay; the
+ * jitter draws from `Random.next`, a default service on the same footing as the
+ * clock rather than a host `Math.random`. No `node:*`, no wall-clock reading, no
+ * ungoverned RNG.
+ *
+ * Effect v3 caveat: the `Schedule` API below is the THREE-type-parameter
+ * `Schedule<Out, In, R>` that `effect@3` exports, with `Schedule.intersect`. The
+ * currently-published docs show a newer four-type-parameter `Schedule` without
+ * `intersect` — do not copy them; this file is written against the installed
+ * `effect@3` type definitions.
+ */
+import { Effect, Predicate, Schedule } from 'effect';
+/**
+ * The default conflict backoff: exponential from 20ms, jittered, capped at five
+ * retries.
+ *
+ * `Schedule.intersect` continues only while BOTH schedules continue, so the
+ * `recurs(5)` arm is what bounds the attempts and the exponential arm is what
+ * spaces them. Jitter matters more here than in a typical backoff: contending
+ * deciders conflict precisely because they read the same boundary at the same
+ * time, so an unjittered backoff would re-synchronise them into the same conflict
+ * on every round. The figures are the conventional starting point (Emmett,
+ * Kurrent and Dudycz all land in this neighbourhood) and are a DEFAULT — a
+ * command with a tighter latency budget, or one contending harder, should pass its
+ * own schedule.
+ */
+const conflictBackoff = /*#__PURE__*/Schedule.intersect(/*#__PURE__*/Schedule.jittered(/*#__PURE__*/Schedule.exponential('20 millis', 2)), /*#__PURE__*/Schedule.recurs(5));
+/**
+ * Retry `command` while — and only while — it fails `AppendConditionFailed`.
+ *
+ * `command` must be the WHOLE read-decide-append cycle (read a decision model to
+ * the current head, decide, append under that read's condition), because each
+ * retry's correctness comes from the re-read: the fresh read re-derives the
+ * append condition's `after` from the new head, so the retried append is judged
+ * against the boundary the retried decision was actually made under. Wrapping only
+ * the `append` re-submits a stale condition and is wrong.
+ *
+ * A non-conflict `E` is preserved on the error channel and escapes IMMEDIATELY
+ * with zero retries: the `while` predicate is false for it, so a domain rejection
+ * ("course is full") never pays a backoff and never retries into a decision the
+ * log has already refused. `A`, the non-conflict `E`, and `R` all pass through
+ * untouched.
+ *
+ * The predicate matches on the `_tag` rather than `instanceof`. The tag is the
+ * error's identity across module realms, and a published package ships dual
+ * ESM/CJS, so an `instanceof` check can see two distinct classes for the same
+ * error when a consumer's graph loads both builds — a conflict would then escape
+ * unretried and silently.
+ */
+export const retryOnConflict = (command, schedule = conflictBackoff) => Effect.retry(command, {
+  schedule,
+  while: Predicate.isTagged('AppendConditionFailed')
+});
+//# sourceMappingURL=retryOnConflict.js.map

package/dist/esm/retryOnConflict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryOnConflict.js","names":["Effect","Predicate","Schedule","conflictBackoff","intersect","jittered","exponential","recurs","retryOnConflict","command","schedule","retry","while","isTagged"],"sources":["../../src/retryOnConflict.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAASA,MAAM,EAAEC,SAAS,EAAEC,QAAQ,QAAQ,QAAQ;AAGpD;;;;;;;;;;;;;;AAcA,MAAMC,eAAe,gBAAGD,QAAQ,CAACE,SAAS,cACxCF,QAAQ,CAACG,QAAQ,cAACH,QAAQ,CAACI,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,eACvDJ,QAAQ,CAACK,MAAM,CAAC,CAAC,CAAC,CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMC,eAAe,GAAGA,CAC7BC,OAAuD,EACvDC,QAAA,GAIIP,eAAe,KAEnBH,MAAM,CAACW,KAAK,CAACF,OAAO,EAAE;EACpBC,QAAQ;EACRE,KAAK,EAAEX,SAAS,CAACY,QAAQ,CAAC,uBAAuB;CAClD,CAAC","ignoreList":[]}

package/dist/esm/testing.js

@@ -0,0 +1,46 @@
+/**
+ * Deterministic test-support utilities, shared across every kairos-es suite via
+ * the published `@kairos-es/core/testing` subpath.
+ *
+ * WHY a published subpath rather than a test-only package: three suites (core's
+ * own tests, the store contract suite, and the codec's `UuidTest` layer) each
+ * carried a byte-identical copy of the same counter-based uuid scheme and the
+ * `EPOCH` domain time. Copies drift. The one place every consumer already
+ * depends on is `@kairos-es/core`, so the single source of truth lives here as a
+ * *published* subpath — never a runtime dependency from a published package onto
+ * an unpublished/test-only one, which would create a packaging cycle.
+ *
+ * Everything here is PURE and DETERMINISTIC: no RNG, no wall-clock. That is the
+ * whole point — suites must produce the same bytes and positions on every run,
+ * so `data`/`uuid`/`occurredAt` never introduce nondeterminism into assertions.
+ */
+import { DateTime } from 'effect';
+/**
+ * A fixed domain time (`DateTime` at the Unix epoch) for test events.
+ *
+ * Ordering in the log is by `position` alone, so an event's `occurredAt` is
+ * informational; pinning it to the epoch keeps serialised bytes and comparisons
+ * stable across runs. Built via `DateTime.unsafeMake(0)` (the value is a
+ * compile-time constant, not read from the host clock).
+ */
+export const EPOCH = /*#__PURE__*/DateTime.unsafeMake(0);
+/**
+ * Build a fresh, deterministic uuid generator: a zero-based counter producing
+ * RFC-4122 v4-shaped ids `00000000-0000-4000-8000-<counter as 12 hex digits>`,
+ * starting at `...000000000000` and incrementing on each call.
+ *
+ * A *factory* (not a shared singleton) so each layer/suite instance owns its own
+ * counter and the sequence is repeatable in isolation — two independent suites
+ * do not interfere, yet each is stable on its own. No RNG: the ids are
+ * comparable and predictable, which is what assertions need, while still being
+ * distinct enough to tell events apart.
+ */
+export const makeSequentialUuid = () => {
+  let counter = 0;
+  return () => {
+    const suffix = counter.toString(16).padStart(12, '0');
+    counter += 1;
+    return `00000000-0000-4000-8000-${suffix}`;
+  };
+};
+//# sourceMappingURL=testing.js.map

package/dist/esm/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","names":["DateTime","EPOCH","unsafeMake","makeSequentialUuid","counter","suffix","toString","padStart"],"sources":["../../src/testing.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;AAgBA,SAASA,QAAQ,QAAQ,QAAQ;AAEjC;;;;;;;;AAQA,OAAO,MAAMC,KAAK,gBAAGD,QAAQ,CAACE,UAAU,CAAC,CAAC,CAAC;AAE3C;;;;;;;;;;;AAWA,OAAO,MAAMC,kBAAkB,GAAGA,CAAA,KAAqB;EACrD,IAAIC,OAAO,GAAG,CAAC;EACf,OAAO,MAAK;IACV,MAAMC,MAAM,GAAGD,OAAO,CAACE,QAAQ,CAAC,EAAE,CAAC,CAACC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IACrDH,OAAO,IAAI,CAAC;IACZ,OAAO,2BAA2BC,MAAM,EAAE;EAC5C,CAAC;AACH,CAAC","ignoreList":[]}