@kairos-es/read 0.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Neverbland
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,538 @@
+# @kairos-es/read
+
+The kairos-es read side: a query-driven projection runner and the
+`ProjectionStore` checkpoint port with its in-memory implementation (ADR-0007).
+
+Platform-neutral — `effect`, `@kairos-es/core` and `@kairos-es/codec` are peer
+dependencies and nothing else, so the all-in-memory permutation — a property of one
+materialisation's (log, view) pairing — needs no database. The durable
+`ProjectionStore` lives in `@kairos-es/read-postgres`.
+
+Everything here is the read side and only the read side. `retryOnConflict`, the
+decider-level retry for `AppendConditionFailed` (ADR-0008), is a **write**-side
+combinator and lives in [`@kairos-es/core`](../core) beside the error it matches,
+so retrying your own appends never means depending on this package.
+
+## Wiring a read model
+
+A read model is a view store bound to the `CheckpointKey` it advances
+(`forKey(store, key)`), the codec slices whose union query drives its
+subscription, and a per-batch `apply`. `runProjection` forks the daemon into the
+enclosing `Scope`; `projectionLayer` is the same thing as a `Layer` whose scope
+owns it. Both also require an `EventLogDurability` declaration, provided **once**
+beside the `DcbEventStore` layer.
+
+```ts
+import { event, projection, SerializerDefault } from '@kairos-es/codec'
+import {
+  composeProjections,
+  DcbEventStoreInMemory,
+  tagIdentity,
+} from '@kairos-es/core'
+import {
+  checkpointKey,
+  EphemeralEventLog,
+  foldIntoRef,
+  forKey,
+  makeInMemoryProjectionStore,
+  ProjectionId,
+  projectionLayer,
+  runProjection,
+} from '@kairos-es/read'
+import { Effect, Layer, Ref, Schema } from 'effect'
+
+const CourseId = tagIdentity('course')
+
+const SeatTaken = event('SeatTaken', { courseId: Schema.String }, (payload) => [
+  CourseId.make(payload.courseId),
+])
+
+// Tag-narrowed, never type-only: every read-model slice carries at least one tag,
+// so the composed subscription's union query stays servable.
+const slices = {
+  seats: projection<number>(0)
+    .on(SeatTaken, (count) => count + 1)
+    .build({ tags: [CourseId.make('c1')] }),
+}
+
+// The read model, plus the view it materialises into. The view is returned
+// alongside it because a read model is queried through its VIEW, never through
+// the runner — `projectionLayer` deliberately provides nothing.
+const makeCourseSeats = Effect.gen(function* () {
+  const store = yield* makeInMemoryProjectionStore
+  const view = yield* Ref.make(composeProjections(slices).initialState)
+  return {
+    view,
+    readModel: {
+      // `ProjectionStore` is multi-key, because one store instance serves many
+      // read models. `forKey` binds it to this one's checkpoint, so `commit` has
+      // no key argument left to get wrong — and the read model carries the pair
+      // rather than two fields that could disagree.
+      store: forKey(store, checkpointKey(ProjectionId.make('course-seats'))),
+      slices,
+      // The folded-state shape: fold the batch purely, then ONE write. This is
+      // what a non-transactional view store's contract requires.
+      apply: foldIntoRef(slices, view),
+    },
+  }
+})
+
+// `EphemeralEventLog` sits BESIDE the store layer, because what it declares is a
+// fact about the LOG, not about any one read model: `DcbEventStore` exposes no
+// durability, so the application that chose the layer is the only honest source,
+// and one declaration here satisfies every runner in the graph. Swap it for
+// `DurableEventLog` when the log is.
+const inMemory = Layer.mergeAll(
+  DcbEventStoreInMemory,
+  EphemeralEventLog,
+  SerializerDefault,
+)
+
+// Either fork the daemon into a scope you own — catch-up starts at once, and
+// closing the scope interrupts it and waits for it...
+const program = Effect.scoped(
+  Effect.gen(function* () {
+    const { readModel, view } = yield* makeCourseSeats
+    yield* runProjection(readModel)
+    // ...append through `DcbEventStore` and let the runner catch up, then read
+    // the materialised view.
+    return yield* Ref.get(view)
+  }),
+).pipe(Effect.provide(inMemory))
+
+// ...or let a Layer own it, so the daemon starts when the application's layer
+// graph is built and is interrupted when the graph is released.
+//
+// `onStalled` is wired here rather than left out, because this shape DISCARDS the
+// runner: `projectionLayer` provides nothing, so there is no fibre to await and a
+// `ProjectionStalled` would otherwise reach you only as a log line. The restart is
+// the metric; the stall is the page.
+
+// Read by this process's readiness probe.
+const stalledProjections = new Set<string>()
+
+const courseSeats = Layer.unwrapEffect(
+  Effect.map(makeCourseSeats, ({ readModel }) =>
+    projectionLayer(readModel, {
+      // Whatever "a human must look at this" means in your deployment: fail a
+      // health check, exit non-zero, fire a pager. Infallible by signature, so it
+      // can neither fail the daemon nor widen its requirements.
+      onStalled: ({ key }) =>
+        Effect.sync(() => stalledProjections.add(key.projection)),
+    }),
+  ),
+)
+
+const main = Layer.launch(Layer.provide(courseSeats, inMemory))
+```
+
+## Testing a read model: `@kairos-es/read/testing`
+
+A projection is a **daemon**, so `runProjection` returns as soon as the fibre is
+forked — which is the only honest thing it can do, but it means every test of a
+read model needs one more step: *run this until it has consumed the log, then
+assert the view*. A published subpath ships that step, so nobody has to invent it
+(and nobody has to guess a `sleep`, which is wrong when it is short and expensive
+when it is long).
+
+```ts
+import { runProjectionUntil, storedCheckpoint } from '@kairos-es/read/testing'
+
+const { readModel, view } = yield* makeCourseSeats
+const positions = yield* appendSomeEvents
+
+// Fork the daemon, then wait until the stored checkpoint reaches that position.
+// Returns the `ProjectionRunner`, so `Fiber.poll`/`Fiber.interrupt` stay available.
+yield* runProjectionUntil(readModel, lastPosition(positions), {
+  // The runner's own tuning and the wait's, in ONE flat object.
+  batchSize: BatchSize.make(2),
+  batchWindow: '5 millis',
+  timeout: '20 seconds',
+})
+
+expect(yield* Ref.get(view)).toEqual(/* … */)
+expect(yield* storedCheckpoint(readModel.store)).toBe(lastPosition(positions))
+```
+
+`awaitCheckpoint(readModel.store, target, options?)` is the wait on its own, for a
+projection started some other way (`projectionLayer`, a scope you own). It POLLS
+the stored checkpoint rather than sleeping, so a slow machine takes longer instead
+of failing, and a genuine hang becomes a failed assertion naming the position that
+was never reached. `storedCheckpoint` reads it once, and `lastPosition` turns what
+`append` reported into a target, loudly, rather than yielding `undefined` from an
+empty fixture.
+
+`awaitCheckpoint` and `storedCheckpoint` take the **keyed** store a read model
+already carries (`readModel.store`) and `runProjectionUntil` takes the read model
+itself, so there is no key to pass and none to transpose; `lastPosition` is a pure
+function over what `append` returned, and takes no store at all. It adds no peer
+dependency — no test framework, no `expect`, just `Effect`s (and that one pure
+function) you run under whatever runner you already have — which is why it is a
+subpath of this package rather than a package of its own. It is deliberately a
+**testing** surface: there is no lag reporting and no production "wait until my
+write is projected" hook, because a read model is eventually consistent by
+construction.
+
+## One store, many read models — one read model, one key per store
+
+`ProjectionStore` is **multi-key**: `readCheckpoint(key)`, `resetCheckpoint(key)`
+and `commit({ key, … })`, because one store instance (one `SqlClient`, one pool)
+serves however many read models an application runs, and keeping their keys
+independent is contract behaviour the shared suite proves against every backend.
+
+A read model has exactly **one** key, so it is given `forKey(store, key)`: the
+same three operations with the key already supplied, so there is none to
+transpose, omit, or read from the wrong variable. `ReadModel` carries that bound
+store **instead of** a `key` field, which is what turns "one materialisation, one
+key, one runner" from a convention every wiring happened to follow into something a
+wiring cannot express otherwise. The key is still readable as `store.key` — the
+runner's log annotations and its `ProjectionStalled` payload name it.
+
+A key is unique **within one store**, which is a consequence of R1 rather than a
+policy: the checkpoint is co-located with its view so the pair commits atomically,
+so a key is only ever resolved against the store holding it and there is no global
+namespace to collide in. That is the direction this heading did not use to name.
+ONE read model materialised in several stores carries ONE `ProjectionId` across
+them — that shared id is what its single identity means, and it is what the
+graduation case asserts as its acceptance criterion. Distinctness is forced only
+where two materialisations of one read model cohabit a store, which is what
+`PartitionId` is for: two of them in one store under one key would trade cursors,
+each advancing the other's, and the wiring gate refuses that pairing at
+construction. That rung is the one only `runProjections` can reach, a single
+materialisation having no sibling to collide with.
+
+`forKey` is a **free function over the port**, not a method on it: one
+implementation every backend gets for nothing, a port that stays three methods,
+and — the sharp reason — a store **decorator** (`{ ...inner, commit: … }`) cannot
+copy a `forKey` that closed over the undecorated store and silently route past
+its own decoration.
+
+Every read-model slice must carry at least one tag (a `system:…` tag for a
+genuinely global slice), so a composed subscription's union query stays servable.
+The wiring gate **checks this at construction**, for either entry point, and the
+wiring is refused as a defect naming the convention — including for a lone tagless
+slice, which the store's own servable grammar would
+accept (a single type-only item is the indexed fast path) but which breaks the day
+a second, tagged slice is composed with it.
+
+The same wiring over a real domain, with the events coming from the write side's
+own deciders rather than from hand-assembled fixtures, is
+[`examples/course-subscriptions/src/courseRoster.ts`](../../examples/course-subscriptions/src/courseRoster.ts) —
+a course's capacity, roster and seats remaining, run and resumed from its
+checkpoint in
+[`test/courseRoster.spec.ts`](../../examples/course-subscriptions/test/courseRoster.spec.ts).
+
+## Graduating a slice from memory to Postgres
+
+Because the view store is a **value** selected per MATERIALISATION, a slice that
+started in an in-memory view graduates to a durable one with its **slices, its
+composed query, its `CheckpointKey` and its runner untouched**. Two things change
+and only two: the `store` it is handed, and the `apply` that writes through it —
+`foldIntoRef` becomes the view's own statements, which also widens the read
+model's `E` from `never` to whatever those writes can fail with. The runner is
+generic in that `E` and needs no retuning; a fault from `apply` travels through
+`commit` to the supervisor, which is what makes "retry with backoff" the response
+to a flaky view store.
+
+That is demonstrated rather than asserted, and it is the same roster both ways.
+[`examples/course-subscriptions/src/courseRosterSql.ts`](../../examples/course-subscriptions/src/courseRosterSql.ts)
+re-points that example's roster at Postgres — importing its slices, its key
+derivation and its pure `courseRosterOf` verbatim — and is the repo's worked SQL
+`apply`, hybrid on purpose: the capacity row's whole batch coalesces into one
+upsert, while each seat is its own row and its own insert.
+[`read-postgres/test/courseRosterGraduation.test.ts`](../read-postgres/test/courseRosterGraduation.test.ts)
+then runs that one slice record into a `Ref` and into Postgres **side by side over
+one durable log** — legal permutations 2 and 3 at once — and asserts the two
+composed queries are equal, the two checkpoint keys are equal, and the two rosters
+agree field for field.
+
+So that pair demonstrates two things rather than one. Graduation is the sequential
+reading — memory *then* Postgres, with the `store` and the `apply` the only things
+that change. Running both **at once** is the other, and it is the section below. The
+two wirings live in the example, which is where a consumer reads worked code and
+where `courseRoster.ts` still needs no database at all; what lives in
+`@kairos-es/read-postgres`'s test directory is the COMPARISON, because running that
+needs a container and a live Postgres log.
+
+## Several materialisations of one read model
+
+Per-read-model view-store selection is a **floor rather than a ceiling**. One slice
+record can feed a durable Postgres materialisation for the big queryable read model
+and an ephemeral in-memory one for hot in-process reads, at the same time, over one
+log.
+
+R1 and R2 fix the shape: one atomic `commit` cannot span two stores, and one
+checkpoint cannot carry two durability classes, so this is N checkpoints, N runners
+and N subscriptions. They do not contend — each owns its checkpoint in its own
+store, and the guarded compare-and-set arbitrates without any lease. Nor are they
+shards: no stream is divided and no work is shared, so the sharding of one read
+model that ADR-0007 refuses is not what this is.
+
+`runProjections({ slices, projection, materialisations })` wires it, holding one
+`slices` value and one `ProjectionId` for the whole call so the subscription query
+and the decode table cannot diverge across materialisations. Each entry — a
+`Materialisation` — keeps its own **unbound** `store`, its own `apply` and its own
+tuning and supervision hooks, and the call applies `forKey` per entry itself. The
+guarantee is exactly **one query, one decode, N applies**. What it does not hold is
+the folds: a SQL `apply` re-implements the fold rather than reusing `foldIntoRef`,
+so agreement between materialisations is something a test demonstrates rather than
+something the type system gives you.
+
+One consequence surprises, so it is worth stating plainly: keys are store-local, so
+under one `ProjectionId` and the default partition the N materialisations'
+`CheckpointKey`s are **identical**. That is the intended shape — a key names a
+cursor *within* a store — and the discriminator is the store. Each runner carries
+its own, so `runners[i].store` is entry *i*'s cursor and
+`awaitCheckpoint(runners[i].store, target)` observes how far that one materialisation
+has got, with no `forKey` for the caller to re-derive. What the store cannot reach is
+a **hook**: `onRestart`/`onStalled` are handed a payload rather than a handle, and
+`info.key` does not tell the entries apart, so which entry's hook fired is the
+discriminator there — which is why the tuning and the hooks are per entry rather than
+per call.
+
+Two materialisations that would share one store **under the same resolved
+`CheckpointKey`** are a **construction-time fault** — both conditions, since
+sharing a store is perfectly legal under distinct partitions and equal keys across
+DIFFERENT stores are the intended shape of a read model materialised twice. The fix
+is usually that they were never two materialisations: several views in one store
+want ONE MATERIALISATION whose single `apply` writes them all inside the one
+`commit`, under one checkpoint. Use a distinct partition only where two
+materialisations genuinely must cohabit a store.
+
+What the gate cannot see is the other side of the same mistake: two entries whose
+`apply`s write **the same view**. Different stores satisfy every rule it has, and
+the view is opaque inside `apply`, so nothing refuses it — and both runners then
+fold the whole stream into that one target under independent checkpoints, applying
+every event twice. **One materialisation owns one view target**, and that one is on
+you rather than on the gate. Every other rule the read side enforces runs in the
+**same pass** — two of them per entry, two once over the shared query and slice
+record — so a call refused for any reason at all has forked nothing, not even the
+entries that were sound.
+
+And if a read model is small enough to fold per query, consider not maintaining it
+at all. `modelAtHead` from `@kairos-es/codec` reads the log at query time and is
+consistent as of the `head` its read returned, which makes it MORE current than any
+maintained view of the same slices — a maintained view is consistent as of a
+checkpoint that trails that head. No table, no checkpoint, no runner, and no rung
+of the construction gate applies to it.
+
+All three over one course's roster:
+[`examples/course-subscriptions/src/courseRosterMaterialisations.ts`](../../examples/course-subscriptions/src/courseRosterMaterialisations.ts),
+whose
+[`test/courseRosterMaterialisations.spec.ts`](../../examples/course-subscriptions/test/courseRosterMaterialisations.spec.ts)
+is what establishes that the three folds agree — empirically, by comparing the
+materialised figures, because nothing structural gives it.
+
+## Supervision: retry while the checkpoint moves
+
+The runner's supervisor is a module of its own — `superviseOnProgress`, which is
+**package-internal and deliberately not exported**: it is this runner's supervisor,
+not a general combinator on offer, and its signature says so (a `CheckpointKey`, a
+`Position`, a `ProjectionStoreError`). What you tune is exported
+(`ProjectionSupervisionOptions`, `MaxNoProgressRestarts`) and what you catch is
+exported (`ProjectionStalled`); the mechanism between them is ours to change.
+
+What it does is **retry an effect while an externally observed progress signal keeps
+moving, and give up with `ProjectionStalled` when it stops.** For a projection the
+signal is the stored checkpoint, re-read through `readCheckpoint` after every
+failure. It is separate from the runner because supervision is the hardest thing
+here to test through the whole pipeline — it knows nothing of `subscribe`, decoding,
+batching or committing, so every subtle part of it is pinned against a stub progress
+signal instead of an event store, a rigged view store and a hand-driven clock loop.
+
+It splits two decisions that are usually conflated. The **schedule** decides how
+fast to restart — a capped, jittered exponential that resets after
+`restartResetAfter`, so a sustained outage sawtooths back to `restartMinDelay`
+rather than pinning at the ceiling. The **circuit-breaker** decides whether to
+keep restarting, by re-reading `progress` after every failure and counting only
+the *consecutive* restarts that moved it not at all.
+
+Keying on the signal rather than on a failure count is what makes a competing
+writer behave: two processes accidentally maintaining one read model both lose
+their guard on every batch, but the winner keeps advancing the shared checkpoint,
+so every one of the loser's restarts scores as progress, its counter resets, and
+it resynchronises at the schedule's bounded rate. Only a signal that is genuinely
+stuck — a poison event, a persistently broken view store — trips the breaker. The
+budget for that is sized in **wall clock**, roughly five minutes on the defaults,
+so a view store that is merely *unavailable* is back inside it.
+
+What that paragraph describes is one store under one key, and it is a **fault**: two
+*deliberate* materialisations of one read model never reach it, their checkpoints
+living in different stores with no shared cursor to contend for. That is why
+`runProjections` refuses the one-store pairing at construction rather than leaving
+this mechanism to absorb it — it would, indefinitely and silently, each
+materialisation holding an arbitrary subset of the events.
+
+Tuning is two documented option sets in **one flat object**.
+`ProjectionPipelineOptions` (`batchSize`, `batchWindow`) sizes a transaction and a
+latency ceiling; `ProjectionSupervisionOptions` (`restartMinDelay`,
+`restartMaxDelay`, `restartResetAfter`, `maxNoProgressRestarts`, `onRestart`,
+`onStalled`) sizes a recovery policy. `ProjectionRunnerOptions` is their union —
+flat, because the ubiquitous `{ ...OPTIONS, oneField }` override would silently
+drop its siblings under a nested shape. Every figure is bounded at construction:
+the two counts are branded (`BatchSize.make(…)`, `MaxNoProgressRestarts.make(…)`),
+and the four `Duration`s are rejected as defects before anything is forked —
+including under `runProjections`, where every entry's figures are judged before the
+first daemon exists. Retune `maxNoProgressRestarts` by the wall clock it buys, never
+by the count.
+
+## The restart is the metric, the stall is the page
+
+The supervisor has two outcomes and one hook each, and they are not equally
+important. `onRestart` fires on **every restart**, before the backoff sleep — the
+outcome that resolves itself, so it is a rate to graph and to alert on only if it
+climbs. `onStalled` fires **once**, at the give-up, immediately after the error is
+logged and immediately before `ProjectionStalled` is raised — a poison event or a
+view store broken rather than merely unavailable, both of which need a human.
+
+**Wire `onStalled` in production.** The recommended shape is `projectionLayer`,
+which provides nothing and therefore discards the daemon fibre — deliberately,
+because a projection is a background process and a read model is queried through
+its view — so there is nothing to `Fiber.await`, and a stall's only other route out
+of the process is a single `Effect.logError`. The hook is what turns that into a
+failed health check, a non-zero exit, or a page.
+
+Its payload is the `ProjectionStalled` about to be raised, field for field and
+value for value: `key`, `noProgressRestarts`, the stuck `position` (so the
+offending event is one query away) and the raw `reason` rather than the string the
+log line carries. Both hooks are `Effect<void>`, so neither can fail the daemon nor
+widen its requirements — and neither traps a **defect**, which takes the fibre down
+as any other bug would. The ordering is what makes that safe: the log line has
+already landed by the time your hook is called, so a broken pager cannot buy
+silence.
+
+**The hooks are the primary channel; the log lines are a thin lossy default.**
+Every annotation on the two supervision lines is a string or a number, on purpose
+— JSON-safe rather than uniformly stringy. Be precise about which `bigint` is the
+hazard, because the obvious reading is wrong: `effect@3.22`'s `Logger.json`
+special-cases a **top-level** annotation value, so a bare `bigint` renders fine. A
+`bigint` **nested inside** an annotation's object is the one that survives into the
+single `JSON.stringify` of the whole record, with nothing catching the throw, and
+raises `TypeError: Do not know how to serialize a BigInt` — losing the entire line
+and taking the daemon with it as a defect. A raw fault is exactly such an object:
+`CheckpointSuperseded` carries `expected: Position`. So the log line gets
+`String(fault)` and the hooks get the fault untouched: anything that needs to match
+on a tag, read a payload, or count by fault type takes `onRestart`/`onStalled`; the
+log line is for everyone else.
+
+**The label is the fault's, not the supervisor's.** `String(fault)` is the whole
+reduction — there is no table of tag-to-label anywhere, and nothing to hand the
+supervisor. `Error.prototype.toString` is `name: message`, and `Data.TaggedError`
+sets `name` to the tag, so a fault that fills `message` arrives as
+`ProjectionStoreError: connection reset` and one that does not arrives as its bare
+tag. The library's own faults all fill it from the field that says why —
+`ProjectionStoreError` and `CodecError` from `reason`, `PipelineDied` from its
+`defect`, `CheckpointSuperseded` from `expected`, and `ProjectionStalled` from the
+budget it spent and the position it is stuck at. A `bigint` field is no obstacle:
+`message` is typed `string`, so interpolating one yields digits, and the hazard
+above — which is about the annotation values a logger is handed — never arises
+through it. **Your read model's `E` gets the same treatment**, so put a `message` on
+any error you want to recognise in a log: it costs one getter over the field you
+already have, and it pays in `Cause.pretty` and every other reader of that error,
+not only here.
+
+## R2: one log, one declaration
+
+The three legal (event log, view store) pairings are all-in-memory, durable log
+with an in-memory view, and durable log with a durable view. A **durable view
+over an in-memory log is rejected at construction** (R2): its checkpoint would
+outlive the log, leaving the view frozen and permanently stale without ever
+erroring.
+
+Each pairing is a property of ONE materialisation, not of a read model: a read
+model materialised twice can have two of them in play at once over one log, which
+is a deployment property rather than a fourth permutation.
+
+The comparison's two inputs are declared in the two places that know them. The
+view store carries its own class on the `ProjectionStore` it implements. The log's
+is the **`EventLogDurability` service** — `DurableEventLog` or
+`EphemeralEventLog`, provided beside the `DcbEventStore` layer — because
+`DcbEventStore` deliberately exposes no durability and the application that chose
+the layer is the only honest source.
+
+A **context tag rather than a field on `ReadModel`**, because one log is *one*
+fact. Authored per read model, it would be stated N times at N sites, N copies
+could disagree over the identical store, and nothing anywhere could notice:
+`runProjection` only ever sees the pair it was handed. Since horizontal scale here
+is a runner per read model — and one read model materialised N ways is N runners
+too — N > 1 is the expected case.
+
+The cost is that `EventLogDurability` is a **required** input of `runProjection`,
+`projectionLayer` and `runProjections` alike, with no default — and it is costliest
+to forget at `runProjections`, where one missing layer refuses N materialisations at
+once. That is deliberate in both directions:
+defaulting to `'ephemeral'` would make the production wiring the one you have to
+remember, and defaulting to `'durable'` would turn an omission into the frozen
+view R2 exists to prevent. The store layers do not supply it either — the tag is a
+read-side concept and `@kairos-es/core` knows nothing of the read side, a backend
+declaring it would move the fact away from the only party that knows it, and two
+providers of one tag resolve by merge order rather than loudly.
+
+## More apply throughput in one runner: coalesce the batch per row
+
+ADR-0007's escape hatch for when apply **throughput** rather than isolation is the
+constraint (horizontal scale of one read model — sharding, competing consumers —
+is deliberately not offered). It is a technique, not a library symbol, because all
+of it is a **fold your read model performs over its own batch**: collapse each
+touched row's N events into the one write that row needs, then issue those writes
+inside the one `commit`. A batch of N events touching R rows costs R statements
+rather than N. There is still one writer, one transaction and one checkpoint
+advance.
+
+Why per **row** and not per event: one DCB event fans out to several rows, so no
+event-derived key can own a row — which is precisely what sank sharding, and the
+argument lives in ADR-0007 beside the alternative it rejects.
+
+Coalescing need not be total, and the **hybrid** is the shape worth seeing: one
+row's whole batch becomes an upsert while a row written per event stays N inserts.
+A plain sequential list is all the ordering that needs, since it preserves exactly
+the order the fold emitted — which is ascending position order, because the store
+delivers strictly ascending and `groupedWithin` keeps that.
+
+```ts
+const apply = (batch: Arr.NonEmptyReadonlyArray<DecodedEvent>) =>
+  // `Effect.suspend` so the fold runs when this effect RUNS — inside `commit`'s
+  // bracket, where a transaction can roll it back — and not when the runner calls
+  // `apply` to build the effect it hands to `commit`.
+  Effect.suspend(() =>
+    Effect.all(
+      // One write per row it can collapse, plus whatever cannot fold into that.
+      Arr.flatMap([...coalesceByRow(batch)], ([row, delta]) => [
+        upsertTotals(row, delta.applied),
+        appendAudit(row, delta.positions),
+      ]),
+      { discard: true },
+    ),
+  )
+```
+
+**On a transactional SQL view store these writes cannot run in parallel, and do
+not need to.** `sql.withTransaction` acquires one connection and pins it into the
+fibre context, and `pg` dispatches one statement at a time per connection, so the
+statements queue in the driver whatever a caller does. What coalescing buys there
+is far **fewer round trips** on that pinned connection, never parallel ones.
+
+On a **non-transactional** view store the port already requires a single atomic
+per-batch write, and `foldIntoRef` is coalescing taken to its limit: fold the whole
+batch, then write exactly once.
+
+## Where the checkpoint cannot travel with the view
+
+R1 says a read model's checkpoint lives with its view, committed atomically with
+it — which is what `ProjectionStore.commit` is. A view store offering **no
+transaction at all** (a search index, an object store, an HTTP API) cannot
+satisfy that: there is nothing to bundle the checkpoint into, so the mode is
+at-least-once and the projection's own writes must be **idempotent**.
+
+The recommended shape is a **position-keyed write that no-ops on replay** — in
+SQL terms an `INSERT … ON CONFLICT DO NOTHING` keyed by the event's position, and
+in a search index or an object store the equivalent: derive the document or
+object key from the position so re-applying the same event overwrites itself
+instead of accumulating. The runner's guarantee then degrades from exactly-once
+to "every event applied at least once, and applying it twice is
+indistinguishable from applying it once".
+
+This is documented rather than enforced because the library cannot force a read
+model's schema to be position-keyed: the key is a property of the reader's own
+rows, which the port has no knowledge of. No helper is shipped for it, and no
+such view store is implemented here.