@kairos-es/core 0.0.0

package/src/Query.ts

@@ -0,0 +1,237 @@
+/**
+ * The DCB selection language: `Query` is an OR of `QueryItem`s. Within an item,
+ * `types` is an OR-filter (empty means any type) and `tags` is an AND superset
+ * test (the event must carry all of the item's tags; extra event tags are
+ * fine). The empty query (`items: []`) matches every event.
+ *
+ * The match predicate is a single pure module function over plain data;
+ * `Query` values carry no methods. See `matchesQuery` / `matchesQueryItem`.
+ *
+ * Smart constructors enforce the indexed fast-path restriction at the
+ * constructor surface (not via a runtime throw): every query built through them
+ * is the wildcard (`query.all`), a single type-only item (`query.types`), or an
+ * OR of tagged items each carrying at least one tag (`query.item` + `query.or`,
+ * or `query.tags` for the single-item case). The `query.item` constructor
+ * requires a non-empty `tags` at the type level, so there is no public way to
+ * build an unrestricted item (empty types and empty tags). `QueryItem`/`Query`
+ * are plain data, so internal decision-model plumbing can still assemble any
+ * shape directly; the restriction binds the public surface, where consumers
+ * build their consistency boundaries.
+ *
+ * The grammar's DISPATCH lives here too, beside the grammar it dispatches over:
+ * `ServableQueryShape` / `classifyServableQuery` own the three shapes an engine
+ * serves and the routing of the degenerate empty item.
+ */
+import { Array as Arr, Schema } from 'effect'
+import { type DcbEvent, EventType, type SequencedEvent, Tag } from './Event'
+
+/**
+ * One clause of a query: a set of types (OR, empty = any) AND a set of tags
+ * (superset test, empty = no tag constraint).
+ */
+export const QueryItem = Schema.Struct({
+  types: Schema.Array(EventType),
+  tags: Schema.Array(Tag),
+})
+export type QueryItem = typeof QueryItem.Type
+
+/** A query: an OR of items. Empty `items` matches everything. */
+export const Query = Schema.Struct({
+  items: Schema.Array(QueryItem),
+})
+export type Query = typeof Query.Type
+
+/**
+ * True when `event` satisfies `item`: its type is in `item.types` (or the item
+ * has no type constraint) AND the event's tags are a superset of `item.tags`.
+ */
+export const matchesQueryItem = (event: DcbEvent, item: QueryItem): boolean => {
+  const typeOk = item.types.length === 0 || item.types.includes(event.type)
+  if (!typeOk) {
+    return false
+  }
+  const eventTags = new Set<string>(event.tags)
+  return item.tags.every((tag) => eventTags.has(tag))
+}
+
+/**
+ * The one true match predicate (ported from `popo.py:48-54`): an empty query is
+ * a wildcard; otherwise the event must match at least one item (OR across
+ * items).
+ */
+export const matchesQuery = (event: DcbEvent, query: Query): boolean => {
+  if (query.items.length === 0) {
+    return true
+  }
+  return query.items.some((item) => matchesQueryItem(event, item))
+}
+
+/** Convenience predicate over a `SequencedEvent`. */
+export const matchesSequenced = (
+  sequenced: SequencedEvent,
+  query: Query,
+): boolean => matchesQuery(sequenced.event, query)
+
+/**
+ * Assert `query` is *servable* by the indexed fast paths, throwing a plain
+ * `Error` describing the violation otherwise. This enforces at the store
+ * boundary the restriction the smart constructors enforce at the type level
+ * (`Query.ts` module docs) but which plain-data assembly — e.g. decision-model
+ * composition, `Projection.ts:31-36` — can still bypass.
+ *
+ * The servable grammar is exactly one of:
+ * - the wildcard (`items.length === 0`), which matches every event;
+ * - a *single* item (`items.length === 1`), any types/tags, including a
+ *   type-only item; or
+ * - a *multi*-item query (`items.length > 1`) in which every item carries at
+ *   least one tag.
+ *
+ * A multi-item query that mixes a tagless (type-only) item with tagged items is
+ * NOT servable: the by-type path and the by-tag path are indexed differently,
+ * so an OR spanning both cannot ride a single index. This is the previously
+ * un-enforced edge (`Projection.ts:31-36`).
+ *
+ * This function is pure (no clock, no RNG, no effect). Every engine applies it at
+ * its read/subscribe/append entry points, through the one shared
+ * `makeContractStore` decorator, so the rule is inherited rather than restated per
+ * backend; a throw inside a store `Effect` becomes a *defect* — a programming
+ * error, not an error-channel value — which is the intended "defect in every
+ * engine" behaviour.
+ */
+export const assertServableQuery = (query: Query): void => {
+  const { items } = query
+  // Wildcard and single-item queries are always servable.
+  if (items.length <= 1) {
+    return
+  }
+  // A multi-item query is servable only if every item is tagged; a tagless
+  // (type-only) item mixed with tagged items cannot ride a single index.
+  const hasTaglessItem = items.some((item) => item.tags.length === 0)
+  if (hasTaglessItem) {
+    throw new Error(
+      'assertServableQuery: a multi-item query must have every item carry at ' +
+        'least one tag; a type-only item mixed with tagged items is not servable',
+    )
+  }
+}
+
+/**
+ * The three shapes a servable query is SERVED by, and therefore the only three an
+ * engine's plan compiler dispatches over: the wildcard, a single type-only item,
+ * and an all-tagged query. `assertServableQuery` has already refused the mixed
+ * tagless-plus-tagged multi-item query, so these three are exhaustive over
+ * everything that reaches a store.
+ *
+ * `typeOnly` carries a NON-EMPTY list of types, and that is the whole guard
+ * against the degenerate empty item: see `classifyServableQuery`.
+ */
+export type ServableQueryShape =
+  | { readonly kind: 'wildcard' }
+  | {
+      readonly kind: 'typeOnly'
+      readonly types: Arr.NonEmptyReadonlyArray<EventType>
+    }
+  | { readonly kind: 'tagged' }
+
+/**
+ * Classify a servable `Query` into the shape that serves it.
+ *
+ * ## Why the dispatch lives beside the grammar
+ *
+ * The three shapes ARE the three bullets `assertServableQuery` above admits, so an
+ * engine that re-derives the dispatch is a second answer to "which shape is
+ * this?", and the shapes only stay in step while there is one answer. Core states
+ * the grammar, so stating the dispatch over it here is that one fact once rather
+ * than once per backend. It is pure — no clock, no RNG, no effect — and knows
+ * nothing of SQL: what a shape COMPILES to stays entirely the engine's.
+ *
+ * ## The degenerate empty item routes to the WILDCARD, structurally
+ *
+ * A single item with neither types nor tags — `{ items: [{ types: [], tags: [] }] }`
+ * — matches EVERY event: `matchesQueryItem` reads empty types as "any type" and
+ * empty tags as a vacuous superset test. It must therefore be served by the
+ * wildcard. Served by the type-only path it would compile to a value list with
+ * nothing in it, and a membership test against an empty list matches NOTHING — the
+ * exact inversion of what the query means. Nothing upstream stops it reaching an
+ * engine: `assertServableQuery` admits a SINGLE item of any shape, and the servable
+ * grammar forbids a tagless item only in a MULTI-item query, so this dispatch is
+ * the last place the divergence can be closed.
+ *
+ * It is closed by the SHAPE and not by a branch in front of it. `typeOnly` carries
+ * `NonEmptyReadonlyArray`, so there is no way to construct it from an empty list;
+ * the emptiness test IS the constructor, and deleting it does not silently restore
+ * the wrong routing, it stops compiling. A guard clause placed before the
+ * construction would have been deletable by anyone tidying what looks like a
+ * redundant check on a list that "obviously" has types in it.
+ */
+export const classifyServableQuery = (query: Query): ServableQueryShape => {
+  if (query.items.length === 0) {
+    return { kind: 'wildcard' }
+  }
+  const only = query.items.length === 1 ? query.items[0] : undefined
+  if (only !== undefined && only.tags.length === 0) {
+    return Arr.isNonEmptyReadonlyArray(only.types)
+      ? { kind: 'typeOnly', types: only.types }
+      : { kind: 'wildcard' }
+  }
+  return { kind: 'tagged' }
+}
+
+// --- Smart constructors (the fast-path-enforcing surface) -------------------
+
+/**
+ * A query item carrying at least one tag (superset test), optionally narrowed
+ * to `types`. The non-empty `tags` requirement is the fast-path restriction,
+ * enforced at the type level rather than as a runtime throw. Combine several
+ * items with `or`.
+ */
+const item = (fields: {
+  readonly tags: readonly [Tag, ...ReadonlyArray<Tag>]
+  readonly types?: ReadonlyArray<EventType>
+}): QueryItem => ({
+  types: fields.types ?? [],
+  tags: fields.tags,
+})
+
+/** The wildcard query: matches every event. */
+const all = (): Query => ({ items: [] })
+
+/**
+ * A single-item query matching events that carry all of `tags`, optionally also
+ * constrained to `types`. The common indexed fast-path shape.
+ */
+const tags = (
+  tags: readonly [Tag, ...ReadonlyArray<Tag>],
+  types?: ReadonlyArray<EventType>,
+): Query => ({
+  items: [item({ tags, ...(types === undefined ? {} : { types }) })],
+})
+
+/**
+ * A single type-only query (the other indexed fast path): one item constrained
+ * to `types` with no tag filter. This is the only tagless item shape the
+ * surface admits, and only as the whole query.
+ */
+const types = (
+  types: readonly [EventType, ...ReadonlyArray<EventType>],
+): Query => ({ items: [{ types, tags: [] }] })
+
+/**
+ * An OR of query items. Each item should be built with `item` (which requires
+ * at least one tag); combining bare type-only items is intentionally not
+ * offered (use `types` for the single type-only query).
+ */
+const or = (
+  items: readonly [QueryItem, ...ReadonlyArray<QueryItem>],
+): Query => ({
+  items,
+})
+
+/** Namespaced smart constructors for `Query`. */
+export const query = {
+  all,
+  item,
+  or,
+  tags,
+  types,
+} as const

package/src/SubscribeMachine.ts

@@ -0,0 +1,316 @@
+/**
+ * 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,
+  type Scope,
+  Stream,
+} from 'effect'
+import type { Position, SequencedEvent } from './Event'
+import { ORIGIN, ReadLimit } from './Event'
+
+/**
+ * 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: Schema.optionalWith(
+    Schema.Number.pipe(Schema.positive(), Schema.finite()),
+    { exact: true },
+  ),
+  catchUpPageSize: Schema.optionalWith(Schema.Int.pipe(Schema.positive()), {
+    exact: true,
+  }),
+} as const
+
+/**
+ * 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 = Schedule.exponential('100 millis', 2).pipe(
+  Schedule.union(Schedule.spaced('2 seconds')),
+  Schedule.intersect(Schedule.recurs(20)),
+)
+
+/**
+ * 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.
+ *
+ * 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>`
+ * that is assignable here under Effect v3's covariant error channel. A second
+ * parameter would buy nothing and would have to be spelled at every call site. Nor
+ * is there an `R`: neither seam contributes a requirement, and unused generality is
+ * not free.
+ */
+export interface SubscriptionDeps<E> {
+  /**
+   * Page-read the events strictly after `from`, up to `limit`, ascending by
+   * position. Returning FEWER than `limit` signals the tail is drained.
+   */
+  readonly fetch: (
+    from: Position,
+    limit: ReadLimit,
+  ) => Effect.Effect<ReadonlyArray<SequencedEvent>, E>
+  /**
+   * The raw wake source: each element is an OPAQUE wake signal. The machine taps it
+   * into its own wake queue and drains it on a background fibre; it never reads the
+   * elements, so anything an engine can push on a change will do.
+   *
+   * OPTIONAL, and omitting it defaults to `Stream.never` at the point of use — an
+   * engine with no wake mechanism gets poll-only delivery, which the poll loop
+   * already makes correct. Under `exactOptionalPropertyTypes` that means omitting
+   * the key entirely rather than passing `undefined`.
+   */
+  readonly listen?: Stream.Stream<unknown, E>
+  /** The poll interval in milliseconds (see `DEFAULT_POLL_INTERVAL_MILLIS`). */
+  readonly pollInterval: number
+  /** The catch-up page size (see `DEFAULT_CATCH_UP_PAGE_SIZE`). */
+  readonly catchUpPageSize: number
+}
+
+/**
+ * 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 = <E>(
+  deps: SubscriptionDeps<E>,
+  after: Position | undefined,
+): Stream.Stream<SequencedEvent, E, Scope.Scope> =>
+  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<void>(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: Position,
+      ): Effect.Effect<
+        {
+          readonly events: ReadonlyArray<SequencedEvent>
+          readonly last: Position
+        },
+        E
+      > =>
+        Effect.gen(function* () {
+          const collected: Array<SequencedEvent> = []
+          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: Position,
+      ): Effect.Effect<readonly [Chunk.Chunk<SequencedEvent>, Position], E> =>
+        Effect.gen(function* () {
+          while (true) {
+            yield* Queue.takeAll(wake)
+            const { events, last } = yield* drainFrom(from)
+            if (events.length > 0) {
+              return [Chunk.fromIterable(events), last] as const
+            }
+            // 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),
+      )
+    }),
+  )

package/src/errors.ts

@@ -0,0 +1,19 @@
+/**
+ * Tagged errors for the store contract. Conflicts are values on the error
+ * channel, never defects.
+ */
+import { Data } from 'effect'
+import type { AppendCondition } from './AppendCondition'
+
+/**
+ * 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 Data.TaggedError(
+  'AppendConditionFailed',
+)<{
+  readonly condition: AppendCondition
+}> {}