@kairos-es/read 0.0.0

package/src/ProjectionRunner.ts

@@ -0,0 +1,923 @@
+/**
+ * `ProjectionRunner` — the read side's daemon: ONE `subscribe(query, checkpoint)`
+ * stream per `ReadModel`, decoded through the codec's shared decode stage,
+ * micro-batched, committed atomically with its checkpoint, and supervised
+ * (ADR-0007).
+ *
+ * ## The pipeline, and why every stage is the stage it is
+ *
+ * `subscribe -> decode -> groupedWithin -> mapEffect(commit, concurrency 1) ->
+ * runDrain`. Each arrow is a back-pressure boundary, and that is the point: a
+ * projection must be able to catch up over a backlog far larger than memory, so
+ * nothing in the chain may buffer without bound and nothing may run ahead of the
+ * committer.
+ *
+ * - **`subscribe`, not `read`.** The store's `subscribe` is catch-up-then-live
+ *   behind one contract, so the runner has no catch-up mode and no live mode and
+ *   therefore no transition between them to get wrong. It also means the runner
+ *   never learns which engine it is running against (`store-postgres`'s
+ *   LISTEN/NOTIFY wake over `core`'s shared poll machine, `store-sqlite`'s
+ *   unwoken ride on that same poll, or the in-memory layer's `PubSub` wake over
+ *   the same machine again).
+ * - **The codec's `decodeSlices`, not a local copy.** The read side needs exactly
+ *   the decode stage the write side's own fold needs, so it shares that one
+ *   implementation; a read-side copy could silently accept an event the decision
+ *   path rejects. Decode is deliberately sequential (`Stream.mapEffect` with no
+ *   `concurrency`), because a fold is order-sensitive and decode order must stay
+ *   position order.
+ * - **`groupedWithin`, not per-event commit.** One transaction per event would
+ *   pay a round-trip per event on catch-up; one transaction per *window* amortises
+ *   it while keeping the transaction small. The window is a latency ceiling too:
+ *   a lone live event waits at most `batchWindow` rather than for a full batch.
+ * - **`mapEffect` at concurrency 1.** The single writer. The checkpoint is a
+ *   scalar guarded compare-and-set, so two batches in flight would race their own
+ *   read model's cursor — one would lose its guard and the pipeline would restart
+ *   for nothing. Concurrency 1 also gives the natural back-pressure: the stream
+ *   pulls the next window only when the previous commit has landed.
+ *
+ * ## Supervision lives NEXT DOOR, and that is the point
+ *
+ * `DcbEventStore.subscribe` is `E = never` — a store that cannot serve the live
+ * tail *dies*. So the runner's boundary converts DEATH into a typed
+ * `PipelineDied` and hands it to a supervisor, because the checkpoint is the
+ * recovery mechanism for infrastructure death, not merely crash-restart hygiene:
+ * a restart re-reads the stored checkpoint and re-subscribes from it, which is the
+ * same code path a cold boot takes.
+ *
+ * The supervisor itself is `superviseOnProgress`, a module of its own — but this
+ * package's own, not a general combinator on offer to anybody (its module doc says
+ * why, and records what generalising it would cost). Its whole input from here is
+ * the checkpoint key, `readCheckpoint` as a progress signal, the RESOLVED restart
+ * tuning and its two hooks (`onRestart` on every restart, `onStalled` once at the
+ * give-up); it knows nothing of `subscribe`, decoding, batching, committing or
+ * slices, which is what lets it be stated, documented and TESTED on its own terms:
+ * retry while an externally observed signal moves, give up when it stops. What that
+ * buys the runner is that everything below is one attempt, `runOnce`, with no
+ * supervision state threaded through it; what it buys the supervisor is that its
+ * subtle parts (the `ORIGIN` seeding, the breaker being consulted before the sleep,
+ * the interruption trap on the re-read, the counter resetting on progress, the
+ * five-minute default budget) are pinned against a stub rather than through this
+ * whole pipeline. Its module doc carries the reasoning, including why a
+ * `CheckpointSuperseded` loser resynchronises instead of tripping the breaker.
+ *
+ * ## The two entry points live NEXT DOOR
+ *
+ * What this module holds is the SUBSTRATE: the `ProjectionRunner` handle, the two
+ * option sets a caller tunes it with, and the three phases every projection call runs
+ * — `resolveProjection`, `prepareProjection` (where the construction gate is
+ * consulted) and `buildAndFork`. It exports no entry point of its own.
+ * `runProjection.ts` is the N = 1 one and `runProjections.ts` the N >= 1 one; both
+ * import from here and nothing here imports from either, which is what lets the
+ * substrate be read without either caller in view. `runProjection.ts`'s module doc
+ * owns the argument for that arrangement.
+ *
+ * ## Platform-neutral
+ *
+ * No `node:*`, no `Date`, no host RNG: the batch window and the backoff are
+ * Effect `Duration`s scheduled through the `Clock`, and the jitter is Effect's
+ * `Random` service, so a test can drive both deterministically.
+ */
+import type {
+  CodecError,
+  RequirementOf,
+  Serializer,
+  SliceProjection,
+} from '@kairos-es/codec'
+import { decodeSlices } from '@kairos-es/codec'
+import {
+  type AnyProjection,
+  composeProjections,
+  DcbEventStore,
+  type DecodedEvent,
+  type Query,
+  type SequencedEvent,
+} from '@kairos-es/core'
+import {
+  Array as Arr,
+  Chunk,
+  Data,
+  type Duration,
+  Effect,
+  type Fiber,
+  Ref,
+  Schema,
+  type Scope,
+  Stream,
+} from 'effect'
+import { EventLogDurability } from './EventLogDurability'
+import type {
+  CheckpointKey,
+  CheckpointSuperseded,
+  Durability,
+  KeyedProjectionStore,
+  ProjectionStoreError,
+} from './ProjectionStore'
+import {
+  type MaterialisationWiring,
+  projectionWiringFault,
+} from './projectionWiringFault'
+import {
+  DEFAULT_RESTART_MAX_DELAY,
+  DEFAULT_RESTART_MIN_DELAY,
+  DEFAULT_RESTART_RESET_AFTER,
+  type ProjectionStalled,
+  type ProjectionSupervisionOptions,
+  type ResolvedSupervisionTuning,
+  superviseOnProgress,
+} from './superviseOnProgress'
+
+/**
+ * Maximum events per commit: a branded POSITIVE integer.
+ *
+ * Branded because `batchSize` is the tuning figure whose invalid values are
+ * absorbed most quietly. `Stream.groupedWithin(0, window)` does not throw and
+ * does not merely under-batch: it emits EMPTY chunks in a tight loop without
+ * ever pulling the subscription, so a projection wired with `batchSize: 0`
+ * spins a CPU for ever, commits nothing, stays at `ORIGIN`, never fails, never
+ * restarts and logs nothing — the exact silent-stall class the supervisor below
+ * exists to make loud, arriving by a route the supervisor cannot see (the
+ * breaker only counts RESTARTS, and a spinning stream never ends a run). A
+ * fractional or `NaN` size is the same mistake by a different route.
+ *
+ * The SHAPE mirrors core's `ReadLimit` — `Schema.Int`, a bound, a brand, the
+ * same fail-at-the-boundary discipline — but deliberately NOT `ReadLimit`
+ * itself, which is `>= 0`. Zero is the whole difference between the two: a
+ * `read` capped at zero events is a meaningful (if useless) request, whereas a
+ * COMMIT of zero events is not a request at all. Reusing `ReadLimit` here would
+ * import the one value that has to be rejected.
+ *
+ * A distinct brand from `MaxNoProgressRestarts` despite the identical
+ * refinement, because the two are still writable side by side in one flat
+ * options literal, are both bare integers, and differ by an order of magnitude
+ * in meaning — nominality is what makes a transposition fail to typecheck rather
+ * than silently retune the runner. That the two now tune different mechanisms
+ * (this one the pipeline, that one the supervisor) is a second reason for the
+ * distinction, not a replacement for the first.
+ *
+ * Construct with `BatchSize.make(n)`, which throws a `ParseError` at the call
+ * site rather than deferring the mistake to the first stream pull.
+ */
+export const BatchSize = Schema.Int.pipe(
+  Schema.positive(),
+  Schema.brand('BatchSize'),
+)
+export type BatchSize = typeof BatchSize.Type
+
+/**
+ * Half the store's `catchUpPageSize` default (512), so a commit transaction stays
+ * comfortably smaller than one catch-up page while still amortising the
+ * round-trip across a couple of hundred events.
+ */
+const DEFAULT_BATCH_SIZE: BatchSize = BatchSize.make(256)
+
+/**
+ * An order of magnitude under the store's 1-second `pollInterval` — the live
+ * tail's own latency floor — so the batching window never dominates end-to-end
+ * lag.
+ */
+const DEFAULT_BATCH_WINDOW: Duration.DurationInput = '50 millis'
+
+/**
+ * How the PIPELINE is tuned: how much a commit carries, and how long a partial
+ * batch waits for company.
+ *
+ * Separate from `ProjectionSupervisionOptions` because these are dials on a
+ * different machine. These two size a TRANSACTION and a latency ceiling, in
+ * milliseconds and events, and their consequences are visible within one batch;
+ * the supervision figures size a RECOVERY POLICY measured in minutes of outage,
+ * and nothing about them is observable until something has already failed.
+ * Reading them as one undifferentiated bag is how `maxNoProgressRestarts` gets
+ * retuned as though it were a throughput knob.
+ *
+ * Every figure is a build-time DEFAULT, not a contract: the mechanisms are fixed
+ * by ADR-0007, the numbers are judgement calls sized against
+ * `@kairos-es/store-postgres`'s own defaults and are meant to be overridden by a
+ * deployment that knows its own latency budget (and by tests, which want tiny
+ * windows).
+ *
+ * A judgement call is still not a free choice: zero, negative, fractional and
+ * infinite figures are not "aggressive tuning", they are wirings whose failure
+ * mode is a hot loop or a permanently frozen view with nothing on any error
+ * channel. So this surface fails at its boundary, exactly as `Tag`, `ReadLimit`
+ * and `ReadPostgresConfig` do — `BatchSize` is BRANDED, so a bad value is
+ * rejected at the caller's own `.make(...)` and a plain integer literal does not
+ * compile at all, while `batchWindow` is judged by the read side's construction
+ * gate before anything is forked, because `Duration.DurationInput` is a union with
+ * no primitive to refine. `projectionWiringFault` carries that reasoning, and
+ * judges the supervisor's three restart durations in the same pass under the same
+ * rule — one home for the bound, whichever machine the figure tunes.
+ */
+export interface ProjectionPipelineOptions {
+  /**
+   * Maximum events per commit. Default `256` — half the store's `catchUpPageSize`
+   * default, so one transaction stays small while still amortising round-trips
+   * across a catch-up. Raise it for throughput, lower it to shrink the
+   * transaction (and the amount of work a lost checkpoint guard discards).
+   *
+   * A branded positive integer: write `BatchSize.make(512)`, not `512`.
+   */
+  readonly batchSize?: BatchSize
+
+  /**
+   * How long a partial batch waits before committing anyway. Default
+   * `'50 millis'` — an order of magnitude under the store's 1-second
+   * `pollInterval`, so batching never dominates end-to-end lag. This is a latency
+   * ceiling, not a delay: a full `batchSize` commits immediately.
+   *
+   * Positive and finite, checked at construction.
+   */
+  readonly batchWindow?: Duration.DurationInput
+}
+
+/**
+ * Everything `runProjection` can be tuned with: the pipeline's two figures plus
+ * the supervisor's four and its two hooks.
+ *
+ * ## Why FLAT, when the two halves are deliberately distinct types
+ *
+ * A nested `{ pipeline, supervision }` would state the split at every call site,
+ * and it was rejected for a reason worth recording. Overriding one figure of a
+ * shared tuning constant is the dominant idiom here — `{ ...RUNNER_OPTIONS,
+ * batchSize: ONE_PER_BATCH }` appears throughout this repo's tests and examples
+ * — and under a nested shape the obvious spelling of that,
+ * `{ ...OPTIONS, supervision: { onRestart } }`, SILENTLY DROPS every other
+ * supervision figure, because a spread is shallow. That is precisely the class of
+ * quiet mis-tuning the branding and the construction-time checks exist to
+ * prevent, and a shape that invites it would be paying in silent bugs for a
+ * distinction that types can carry for free.
+ *
+ * So the distinction lives in the TYPES: two documented interfaces a reader (or
+ * an IDE) can see the boundary in, one flat object a caller writes. The two are
+ * disjoint by construction, and `buildAndFork` splits them by forwarding each half
+ * to the machine that reads it — the pipeline's two figures into the stream, and the
+ * supervision half into `superviseOnProgress` as one spread of whatever the caller
+ * wrote plus the three RESOLVED durations named after it. That second split is
+ * carried by types too (`UnresolvedSupervisionOptions` and
+ * `ResolvedSupervisionTuning`); the call site says how.
+ */
+export interface ProjectionRunnerOptions
+  extends ProjectionPipelineOptions,
+    ProjectionSupervisionOptions {}
+
+/**
+ * ONE materialisation's wiring with every default already applied: the bound view,
+ * the key and durability read off it, and the five figures that will actually run.
+ *
+ * This is the RESOLVE phase's whole output, and every field of it is either judged
+ * by the construction gate or used by the pipeline below — usually both, which is
+ * the point. `batchSize` is the one exception in the other direction: it is BRANDED,
+ * so the gate has nothing left to judge, but it is resolved here anyway because a
+ * default the pipeline applied for itself would be a figure resolved in a second
+ * place.
+ *
+ * The three restart figures are not restated here: this interface EXTENDS
+ * `ResolvedSupervisionTuning`, which is the type `superviseOnProgress` requires and
+ * the type `UnresolvedSupervisionOptions` is the complement of. One declaration
+ * therefore serves both ends — the resolve step cannot produce a set of figures the
+ * supervisor does not require, and `buildAndFork` cannot forward a set missing one.
+ * It stays FLAT despite the `extends`, and deliberately: `MaterialisationWiring`
+ * reads those fields flat, so a nested `supervision` sub-object would ripple into
+ * the construction gate and its pure suite for no gain.
+ *
+ * PACKAGE-INTERNAL and deliberately not re-exported: it is the seam between the two
+ * runner entry points, not a shape a caller ever writes. Nothing on it mentions the
+ * read model's `E` or its `R`, which is what lets one monomorphic record be shared
+ * by a single wiring and by a LIST of them — see `runProjections.ts` for why a type
+ * parameterised by one `Materialisation` in this position would not work.
+ */
+export interface ResolvedProjection extends ResolvedSupervisionTuning {
+  /** The view store this materialisation writes into, bound to its key. */
+  readonly view: KeyedProjectionStore
+
+  /**
+   * The key the commits will use, read OFF the bound view rather than beside it:
+   * the read model cannot name a key its store is not bound to, so annotations,
+   * defect messages and failure payloads all report the key that actually runs.
+   */
+  readonly key: CheckpointKey
+
+  /** The VIEW's half of R2, passed straight through from the bound store. */
+  readonly viewDurability: Durability
+
+  readonly batchSize: BatchSize
+  readonly batchWindow: Duration.DurationInput
+}
+
+/**
+ * RESOLVE: apply every default and read both call-independent facts off the bound
+ * view, so the gate can judge exactly the figures the pipeline will run.
+ *
+ * A PURE function — no `Effect`, no context, no clock — which is what lets BOTH
+ * runner entry points share one resolution site. That is the whole reason it exists
+ * as a function rather than as a paragraph of `runProjection`'s body: the gate is
+ * only as good as the argument it is handed, and two resolution sites are free to
+ * drift into approving a figure the pipeline does not use. One site, and the figure
+ * that was judged cannot differ from the figure that runs, for one wiring and for N
+ * of them alike.
+ *
+ * The five `??` defaults are resolved HERE and ONCE. `batchSize` and `batchWindow`
+ * go into the pipeline, the three restart durations into the supervision options,
+ * where `superviseOnProgress` requires all three for exactly that reason.
+ *
+ * `maxNoProgressRestarts` is deliberately absent, as it is from the gate: it is
+ * BRANDED, so its boundary was the caller's own `.make(...)`, nothing here has to
+ * resolve it, and its default stays where its wall-clock arithmetic is documented.
+ *
+ * It takes the BOUND view rather than the unbound port because `key` and
+ * `viewDurability` are its two reads and both are on the bound façade. The UNBOUND
+ * store is still the only thing that can answer "are these two entries the same
+ * store?" — `forKey` deliberately does not expose what it closed over — so the gate
+ * takes that identity as a field of its own, from whichever caller holds one.
+ */
+export const resolveProjection = (
+  view: KeyedProjectionStore,
+  options?: ProjectionRunnerOptions,
+): ResolvedProjection => ({
+  view,
+  key: view.key,
+  viewDurability: view.durability,
+  batchSize: options?.batchSize ?? DEFAULT_BATCH_SIZE,
+  batchWindow: options?.batchWindow ?? DEFAULT_BATCH_WINDOW,
+  restartMinDelay: options?.restartMinDelay ?? DEFAULT_RESTART_MIN_DELAY,
+  restartMaxDelay: options?.restartMaxDelay ?? DEFAULT_RESTART_MAX_DELAY,
+  restartResetAfter: options?.restartResetAfter ?? DEFAULT_RESTART_RESET_AFTER,
+})
+
+/**
+ * A defect surfaced from the drain, converted into a value the supervisor can act
+ * on.
+ *
+ * **Why the conversion exists.** `DcbEventStore.subscribe` is `E = never` by
+ * contract (ADR-0002: infrastructure faults are defects, not channel values), so a
+ * store whose live tail fails beyond its own retry budget DIES rather than failing.
+ * Converting that death into a typed error at the runner's boundary is what makes
+ * it actionable: a defect can only be caught, whereas a value can be counted,
+ * logged, matched on, and fed to a supervisor that decides between backoff and
+ * give-up.
+ *
+ * **Why the boundary is DRAIN-WIDE**, which is what the name reports. The
+ * conversion sits outside the whole `runDrain`, so what arrives is a defect from
+ * any stage of it: the subscription's own death, the codec's decode, the read
+ * model's `apply`, or a `ProjectionStore` implementation that dies where the port
+ * says it should fail. They all end the run identically, and the progress-keyed
+ * breaker is the right arbiter for all of them, since it restarts while the
+ * checkpoint moves and gives up with a logged `ProjectionStalled` when it does
+ * not. Narrowing the conversion to the subscription stage would instead let an
+ * `apply` defect escape `Effect.retry` — which sees failures, never defects — and
+ * kill the daemon fibre outright: no restart, no `ProjectionStalled`, no logged
+ * give-up, and since `runProjection` is infallible, no route to an operator at
+ * all. The boundary must equally not WIDEN to `catchAllCause`; the comment at the
+ * conversion site sets out why.
+ *
+ * `defect` is `unknown` because it is somebody else's defect and the runner must
+ * not pretend to know its shape.
+ */
+export class PipelineDied extends Data.TaggedError('PipelineDied')<{
+  readonly key: CheckpointKey
+  readonly defect: unknown
+}> {
+  /**
+   * Why this class fills `message` at all: so the fault renders ITSELF.
+   *
+   * `Data.TaggedError` sets `name` to the tag and leaves `message` empty, so an
+   * unfilled tagged error stringifies to its bare tag — "the pipeline died", with
+   * no hint of what killed it, and `PipelineDied: ECONNRESET` is not the same log
+   * line. Filled, `Error.prototype.toString` yields `name: message`, so
+   * `String(fault)`, `Cause.pretty` (which reads `message` off anything
+   * `instanceof Error`) and every log line built from either report the field that
+   * says WHY — and no table of tag-to-label outside the class has to be kept in
+   * step with the fields inside it.
+   *
+   * `String(this.defect)` rather than anything cleverer, for exactly the reason
+   * `defect` is `unknown` above: plucking a `.message`, sniffing a `_tag` or
+   * `JSON.stringify`-ing it would each be the runner pretending to know the shape
+   * of somebody else's defect, and the last of them THROWS on a `bigint`.
+   *
+   * A GETTER rather than a `message` field, which keeps `defect` the single
+   * declaration of the fact. Why a prototype accessor is safe here, how far filling
+   * the field reaches and the structured `toJSON` shape it deliberately leaves
+   * untouched are set out once for all four of these getters on
+   * `ProjectionStoreError` in `ProjectionStore.ts`.
+   */
+  override get message(): string {
+    return String(this.defect)
+  }
+}
+
+/**
+ * Everything one run of the pipeline can fail with: the runner's own four faults
+ * plus the read model's `E`, which passes through `apply` and `commit` untouched.
+ *
+ * Internal, because it is the supervisor's INPUT rather than anything a caller
+ * sees: the supervisor collapses all of it into `ProjectionStalled` (or into
+ * another restart), so the only failure on the daemon's error channel is that.
+ */
+type RunnerFault<E> =
+  | CheckpointSuperseded
+  | CodecError
+  | ProjectionStoreError
+  | PipelineDied
+  | E
+
+/**
+ * A running projection: the bound view store it maintains, the key it maintains it
+ * under, and the daemon fibre doing the maintaining.
+ *
+ * The fibre is exposed rather than hidden so a caller can `Fiber.poll` it (is this
+ * projection still up?), `Fiber.await` it, or `Fiber.interrupt` it early — the
+ * last being the documented answer to "give up immediately", which
+ * `MaxNoProgressRestarts` deliberately does not offer as a supervision policy. It
+ * is NOT the teardown mechanism: the fibre is forked into the enclosing `Scope`,
+ * so closing that scope interrupts it deterministically and waits for it, which is
+ * what makes a shutdown graceful — the in-flight commit either completes or was
+ * never started, and either way the checkpoint matches the view.
+ *
+ * A full `RuntimeFiber` rather than something `Fiber.await`-shaped (an
+ * `Effect<never, ProjectionStalled>`, which would leave awaiting the terminal
+ * failure as the only thing a caller could do), for two reasons that arrived
+ * together. Awaiting is no longer how a stall is noticed — `onStalled` is, and it
+ * works under `projectionLayer` too, where there IS no handle because the daemon
+ * is discarded on purpose — so narrowing this type would be narrowing towards the
+ * weaker of the two routes. And the two capabilities it would remove, polling and
+ * interrupting, are the ones with no equivalent on an awaitable: "is it still
+ * running?" cannot be asked of an effect that only completes when it is not, and
+ * the early stop is guidance this repo gives elsewhere in prose.
+ *
+ * ## Why the BOUND STORE is carried, and why here rather than beside the handle
+ *
+ * Because it is what tells N runners of ONE read model apart wherever their keys do
+ * not — which is the ordinary case, a distinct `PartitionId` being the escape hatch
+ * for two materialisations COHABITING one store rather than the normal shape. Under
+ * one `ProjectionId`, wherever no entry named a partition, the N `CheckpointKey`s are
+ * EQUAL — which is the intended shape, a key naming a cursor WITHIN a store, so equal
+ * keys across two stores are one read model materialised twice rather than a clash —
+ * and a handle carrying only that key therefore cannot name which cursor it advances.
+ * `runProjections` did the `forKey` binding for the caller, so without this field
+ * every observer of a multi-materialisation call had to re-derive a binding the
+ * library had already made, from a key and a store it had to pair up again by hand.
+ *
+ * Carried ON the runner rather than returned beside it (`{ runner, store }` per
+ * entry) because of where the two entry points get their store from. `runProjection`
+ * is HANDED the bound store by its caller, so a pair would hand back what that caller
+ * already holds; `runProjections` is the one place the caller does not hold it. One
+ * field on the handle covers both, and it keeps "one materialisation, one key, one
+ * runner" readable off a single value.
+ *
+ * What it does NOT do is pair a runner back with the entry that asked for it. An
+ * entry hands `runProjections` an UNBOUND port and `forKey` deliberately does not
+ * expose what it closed over, so this field can be OBSERVED but not matched against a
+ * store the caller still holds; the returned ENTRY ORDER is what states that pairing,
+ * and `runProjections` says so where it fixes the order.
+ */
+export interface ProjectionRunner {
+  /**
+   * The key this projection advances — `store.key`, so it names the cursor the
+   * commits actually use rather than one stated beside it.
+   *
+   * Kept as a field of its own although the store carries it, because it is what
+   * almost every reader wants (log lines, a `ProjectionStalled` payload, an
+   * operator's "which projection?") and reaching it through the store would be a
+   * hop for nothing.
+   */
+  readonly key: CheckpointKey
+
+  /**
+   * The view store this daemon commits through, bound to `key` — the runner's own
+   * cursor, and the discriminator among N materialisations of one read model.
+   *
+   * Exposed for OBSERVING: `readCheckpoint` (how far has THIS materialisation got?),
+   * `durability` and `key`. `commit` and `resetCheckpoint` are on it because
+   * `KeyedProjectionStore` is one interface, and neither should be called while this
+   * runner is up — the daemon is this cursor's SINGLE WRITER (ADR-0007), so a write
+   * from anywhere else races the guarded advance it owns and costs the loser a
+   * restart. A rebuild takes the runner down first (close the enclosing `Scope`) and
+   * resets the cursor after.
+   */
+  readonly store: KeyedProjectionStore
+
+  /** The daemon fibre. Interrupted when the enclosing `Scope` closes. */
+  readonly fibre: Fiber.RuntimeFiber<void, ProjectionStalled>
+}
+
+/**
+ * The decode stage a build step is handed: `decodeSlices`' return type, named.
+ *
+ * It stays GENERIC in the input stream's own error and requirement, exactly as
+ * `decodeSlices` is, so one stage built for a call can be applied to every
+ * subscription in it. Naming the type is what makes passing the stage as an
+ * ARGUMENT possible without instantiating it at the first call site — which is what
+ * `runProjections` needs, since it builds one stage and hands it to N pipelines.
+ *
+ * `RSlices` is the slice record's OWN requirement, which rides out in the decoded
+ * stream's `R`. It is the REQUIREMENT rather than the record it came from because
+ * `RequirementOf<T>` is a conditional type: nothing could recover `T` from a stage
+ * handed over as a value, so a record parameter would be uninferable here.
+ *
+ * TWO references to this alias are LOAD-BEARING: `PreparedProjection.decode`, the
+ * SOURCE, where the stage is handed over, and `buildAndFork`'s own `decode`
+ * parameter, the TARGET, where it is taken. With source and target both written
+ * through the alias, TypeScript infers straight from its type ARGUMENT
+ * and never has to unify two generic signatures' return unions, which it cannot do
+ * here (`SR` and `RSlices` are both naked variables in one union, so it gives up and
+ * infers `unknown`). Widen EITHER and the failure is loud in both entry points at
+ * once — `RSlices` collapses to `unknown` and neither declared requirement is
+ * satisfiable — which is measured rather than asserted.
+ *
+ * `prepareProjection`'s own local is annotated through the alias too, and that one is
+ * DOCUMENTARY rather than load-bearing — it restates `decodeSlices`' declared return
+ * type, so dropping it compiles clean. Worth saying, because the field and the local
+ * look like one precaution written twice and only one of them is holding anything up.
+ */
+export type DecodeStage<RSlices> = <SE, SR>(
+  events: Stream.Stream<SequencedEvent, SE, SR>,
+) => Stream.Stream<DecodedEvent, SE | CodecError, SR | RSlices | Serializer>
+
+/**
+ * PREPARE's whole output: the ONE composed query every subscription in a call
+ * subscribes with, and the ONE decode stage every pipeline in it runs.
+ *
+ * Both are pure derivations of a single `slices` value and both are handed straight
+ * to `buildAndFork`, which holds no slice record of its own — so there is no second
+ * record either could have been derived differently from. PACKAGE-INTERNAL, like
+ * `ResolvedProjection` beside it: it is a seam between the phases, not a shape a
+ * caller ever writes.
+ */
+export interface PreparedProjection<T extends Record<string, SliceProjection>> {
+  /** `composeProjections`' merged query, shared by the call's N subscriptions. */
+  readonly query: Query
+
+  /** `decodeSlices`' stage, shared by the call's N pipelines. */
+  readonly decode: DecodeStage<RequirementOf<T>>
+}
+
+/**
+ * PREPARE: the whole middle of a projection call — the log's durability, the merged
+ * query, the construction gate's verdict and the decode stage — between the
+ * per-entry RESOLVE above and the per-entry BUILD below.
+ *
+ * ## Why it is a phase of its own
+ *
+ * Everything in it is a function of the CALL rather than of any one materialisation,
+ * and both entry points ran these same five steps in this same order before it
+ * existed. `runProjection` is the N = 1 case: it hands over a singleton entry list
+ * and its own preamble and gets back the pair `runProjections` gets back for N.
+ *
+ * ## What the ONE body is FOR: the gate is consulted before the codec
+ *
+ * This is worth more than the duplication it removes. `decodeSlices` refuses a slice
+ * record carrying two DISTINCT `Schema`s under one event type, and refuses it by
+ * THROWING — which inside this `Effect.gen` is a defect, exactly as the gate's
+ * verdict is. A record wrong in BOTH ways therefore has two sentences available and
+ * nothing but the ORDER of two statements decides which one its author reads. The
+ * gate's is the right one: it is the read side's own rule about the wiring in front
+ * of that author, where the codec's is about a merge the write path shares and
+ * `decode.ts` owns.
+ *
+ * That order is now a property of ONE body — the gate call above, the `decodeSlices`
+ * call below — for both entry points at once. It used to be a claim two function
+ * bodies each made in prose, free to drift, and pinned for only one of them. It is
+ * pinned for both now: `test/runProjections.test.ts`'s "the GATE is consulted before
+ * the codec" case and `test/runner.construction.test.ts`'s sibling each drive a
+ * record breaking both rules and assert which sentence comes back. Neither RULE is
+ * under test in either — `packages/codec`'s decode suite and
+ * `projectionWiringFault.test.ts` own those.
+ *
+ * ## What the caller keeps
+ *
+ * The PREAMBLE, and only the preamble: `runProjection` names the projection and its
+ * partition, `runProjections` the projection alone, and this function joins whichever
+ * it was to the gate's sentence about the RULE with one `': '`. That is the division
+ * `projectionWiringFault`'s doc fixes — the gate knows the rule, the entry point
+ * knows whose wiring it is — and moving the single `Effect.die` here changes only
+ * WHERE the two halves meet, never which half writes which. It is built eagerly, one
+ * interpolation per construction, rather than as a thunk: a call that is about to
+ * subscribe to an event log does not need that deferred, and a thunk reads worse at
+ * both call sites.
+ *
+ * ## Why both derivations happen HERE
+ *
+ * The runner needs only the merged QUERY from the composition — the fold is the read
+ * model's own `apply` — but it must be the SAME merge a fold would use, so it comes
+ * from `core`'s `composeProjections` rather than a local query union that could drift
+ * from it. It is also the gate's input, and the gate can only judge it at
+ * construction because the union is a pure function of the slices.
+ *
+ * Both derivations run ONCE per call rather than once per entry or once per restart,
+ * so N subscriptions share a single `Query` object and N pipelines a single merged
+ * `type -> Schema` table. Sharing the decode stage is safe because the `Serializer`
+ * is read from context INSIDE it, per stream, so one stage does not freeze one
+ * serialiser across entries. `DecodeStage`'s own doc says which references to that
+ * alias hold the inference up, and which do not.
+ *
+ * The cast erases each slice's own state and event types down to `AnyProjection`. It
+ * is sound because `composeProjections` only ever folds a slice through its OWN
+ * `evolve`, never across two, so the per-slice pairing the erasure hides is the one
+ * thing it cannot violate — and `T`'s precise shape is recovered on the way out, in
+ * `CompositeState<T>`. It is unavoidable rather than merely convenient: a slice
+ * record is keyed by a caller's literal union, and no signature in `core` is generic
+ * over that union AND over each member's state, so the variance has to be discharged
+ * somewhere. Once, now, rather than at each entry point.
+ *
+ * ## Why `EventLogDurability` is read from CONTEXT here
+ *
+ * Because it is R2's log half, and one log is ONE fact —
+ * `EventLogDurability.ts` argues why it is a service declared beside the store layer
+ * rather than a field per read model. Reading it once for the CALL is what that
+ * argument already wanted, and it is deliberately not part of `resolveProjection`,
+ * which is per ENTRY and pure. It is this function's only requirement, and through it
+ * the reason both entry points declare one.
+ */
+export const prepareProjection = <T extends Record<string, SliceProjection>>(
+  slices: T,
+  materialisations: ReadonlyArray<MaterialisationWiring>,
+  preamble: string,
+): Effect.Effect<PreparedProjection<T>, never, EventLogDurability> =>
+  Effect.gen(function* () {
+    // The LOG's half of R2, from CONTEXT rather than from any read model. Each
+    // entry's VIEW half already rode in on the resolved wiring.
+    const eventLogDurability = yield* EventLogDurability
+
+    const composite = composeProjections(
+      slices as Record<string, AnyProjection>,
+    )
+
+    // ## ASSERT — one gate, one verdict, one `Effect.die`
+    //
+    // Five rules over four vocabularies, in the order `projectionWiringFault`
+    // declares and argues; this function supplies the values and classifies the
+    // verdict, and its caller supplied the preamble that says WHOSE wiring is wrong.
+    // Both entry points reach this before they fork anything, so a rejected wiring
+    // has read no checkpoint and opened no subscription.
+    const fault = projectionWiringFault({
+      eventLogDurability,
+      query: composite.query,
+      slices,
+      materialisations,
+    })
+    if (fault !== undefined) {
+      return yield* Effect.die(new Error(`${preamble}: ${fault}`))
+    }
+
+    // BELOW the gate, and that is the ordering this phase exists to own.
+    // `decodeSlices` carries the CODEC's own construction refusal — two DISTINCT
+    // `Schema`s under one event type — and it THROWS, which here is a second defect;
+    // a record wrong in both ways must meet the gate's sentence first. Moving this
+    // call above the gate would still die with nothing forked, only with the wrong
+    // sentence, which is why the doc above names the two suites that pin it.
+    //
+    // It takes the RECORD rather than a pre-merged schema table for the same reason
+    // the query is composed here: the decode lookup and the subscription query
+    // cannot then come from different records.
+    const decode: DecodeStage<RequirementOf<T>> = decodeSlices(slices)
+
+    return { query: composite.query, decode }
+  })
+
+/**
+ * BUILD and FORK: one resolved wiring plus the three shared derivations in, one
+ * supervised daemon out.
+ *
+ * This is everything the two runner entry points have in common from the gate's
+ * verdict onwards — the subscription, the decode, the micro-batching, the guarded
+ * commit, the supervisor and the `forkScoped`. It is package-internal and takes no
+ * `ReadModel`, so `runProjections` reaches it directly rather than by re-entering
+ * `runProjection` per entry, which is what lets one call resolve, judge and derive
+ * ONCE and still run N identical pipelines. `read-postgres`'s
+ * `test/courseRosterGraduation.test.ts` rests on the two callers running literally
+ * the same pipeline, so this function staying the only build step is load-bearing.
+ *
+ * It requires no `EventLogDurability`. That service is read by `prepareProjection`
+ * above — the one place it is read at all — for the gate, and has no part in what
+ * runs; the two public entry points DECLARE it only because they run that phase.
+ *
+ * `query` and `decode` arrive as ARGUMENTS rather than being derived here from a
+ * slice record, which is a structural gain rather than a cost: the build step holds
+ * no slice record at all, so there is no second record it could derive a different
+ * query or a different decode table from. It is the same move `decodeSlices` itself
+ * made when it collapsed a two-step protocol into one call.
+ */
+export const buildAndFork = <RSlices, E, R>(
+  resolved: ResolvedProjection,
+  build: {
+    readonly query: Query
+    readonly decode: DecodeStage<RSlices>
+    readonly apply: (
+      batch: Arr.NonEmptyReadonlyArray<DecodedEvent>,
+    ) => Effect.Effect<void, E, R>
+    readonly options: ProjectionRunnerOptions | undefined
+  },
+): Effect.Effect<
+  ProjectionRunner,
+  never,
+  Scope.Scope | DcbEventStore | Serializer | RSlices | R
+> =>
+  Effect.gen(function* () {
+    const {
+      view,
+      key,
+      batchSize,
+      batchWindow,
+      restartMinDelay,
+      restartMaxDelay,
+      restartResetAfter,
+    } = resolved
+    const store = yield* DcbEventStore
+
+    /**
+     * One run of the pipeline: resolve the resume point, subscribe from it, and
+     * drain until the stream ends, is interrupted, or dies.
+     *
+     * `Effect.scoped` per RUN, not per runner, so a restart releases the previous
+     * subscription's resources (the store's listener, its poll fibre) before the
+     * next one acquires them — otherwise every restart would leak a subscription
+     * into the runner's outer scope.
+     */
+    const runOnce: Effect.Effect<
+      void,
+      RunnerFault<E>,
+      Serializer | RSlices | R
+    > = Effect.gen(function* () {
+      // Re-read on EVERY attempt. This is the resynchronisation: after a lost
+      // checkpoint guard the stored position is whatever the winner advanced it
+      // to, and the restart picks that up instead of resuming from a stale
+      // expectation.
+      const stored = yield* view.readCheckpoint
+
+      // The expectation for the next guarded advance, threaded through the run.
+      // A `Ref` rather than a fold accumulator because the batch committer is a
+      // `Stream.mapEffect` callback; correctness rests on the single-writer
+      // property (concurrency 1), so there is exactly one fibre reading and
+      // writing this.
+      const expected = yield* Ref.make(stored)
+
+      const commitBatch = (
+        batch: Chunk.Chunk<DecodedEvent>,
+      ): Effect.Effect<
+        void,
+        E | CheckpointSuperseded | ProjectionStoreError,
+        R
+      > =>
+        Effect.gen(function* () {
+          const events = Chunk.toReadonlyArray(batch)
+
+          // Total on the empty chunk. `groupedWithin` is `aggregateWithin` over a
+          // `collectAllN` sink on a `spaced` schedule, so a window that elapses
+          // with nothing buffered has an empty collection to emit; even if a
+          // given version suppressed that, resting the runner's correctness on an
+          // undocumented internal would be a bug waiting for an upgrade. There is
+          // nothing to apply and no last position, and committing `expected` onto
+          // itself would be a pointless write that could lose its guard to a
+          // legitimate winner and restart the pipeline for nothing.
+          if (!Arr.isNonEmptyReadonlyArray(events)) {
+            return
+          }
+
+          // The last event's position, AS IS. Never `expected + 1` and never any
+          // other arithmetic: positions are strictly increasing but NOT gapless
+          // (a rolled-back append burns ids), so the gap between two delivered
+          // events is normal and an increment would invent a position that either
+          // never existed or belongs to an event this query does not match.
+          const next = Arr.lastNonEmpty(events).sequenced.position
+          const from = yield* Ref.get(expected)
+
+          // The port owns the bracket: the view writes go IN, so the checkpoint
+          // advance cannot happen outside the transaction that carries them. A
+          // lost guard fails here, which aborts the whole commit and restarts the
+          // run — `expected` is deliberately NOT advanced on a failure. There is
+          // no `key` argument: the store is bound to one, so the batch cannot be
+          // committed against a cursor other than the one it was read from.
+          yield* view.commit({
+            expected: from,
+            next,
+            viewWrites: build.apply(events),
+          })
+
+          yield* Ref.set(expected, next)
+        })
+
+      yield* store.subscribe(build.query, stored).pipe(
+        build.decode,
+        Stream.groupedWithin(batchSize, batchWindow),
+        Stream.mapEffect(commitBatch, { concurrency: 1 }),
+        Stream.runDrain,
+        // `catchAllDefect`, NOT `catchAllCause`. The subscription's failure mode
+        // is a DEFECT (`subscribe` is `E = never`) and that is what the
+        // supervisor needs as a value — but the OTHER way this drain ends is
+        // INTERRUPTION, when the enclosing `Scope` closes at shutdown.
+        // `catchAllCause` would swallow that too, turning a graceful teardown
+        // into a `PipelineDied` that the supervisor would dutifully retry —
+        // restarting a subscription inside a scope that is being torn down.
+        // `catchAllDefect` re-fails any cause carrying no defect, so interruption
+        // propagates untouched and the fibre dies when it is told to.
+        //
+        // Placed outside the WHOLE drain, so it converts a defect from any stage
+        // — decode, `apply`, a store implementation that dies — and not only the
+        // subscription's own death; the fault says PIPELINE for that reason.
+        // `PipelineDied`'s doc carries the reasoning (in short: they all end the
+        // run identically, and a narrower conversion would let an `apply` defect
+        // bypass the supervisor entirely).
+        Effect.catchAllDefect((defect) => new PipelineDied({ key, defect })),
+      )
+    }).pipe(Effect.scoped)
+
+    // ## SUPERVISE — one attempt in, a supervised daemon out
+    //
+    // What goes with it is the whole of what supervision knows about this runner:
+    // the key it reports under, the bound store's `readCheckpoint` as the progress
+    // signal, whatever the caller wrote in the UNRESOLVED half of its supervision
+    // options, and the three restart durations RESOLVED above.
+    //
+    // What DOES the work is that those three were resolved ONCE, in
+    // `resolveProjection`, so the supervisor receives exactly the figures the gate
+    // judged — the argument is on `SuperviseOnProgressOptions` in
+    // `superviseOnProgress.ts`, which requires all three for exactly that reason.
+    //
+    // WHICH FIELDS travel is carried by the TYPES, not by an enumeration of the
+    // forwardable ones. `UnresolvedSupervisionOptions` — the type
+    // `SuperviseOnProgressOptions` is built from — is `ProjectionSupervisionOptions`
+    // MINUS the resolved three, so a new OPTIONAL supervision field lands in it and
+    // travels through this call with no edit here, while a new RESOLVED figure lands
+    // in `ResolvedSupervisionTuning` instead and leaves the literal below missing a
+    // required property. Neither direction rests on a comment or on a test
+    // remembering to be extended, which is what the enumeration this replaced could
+    // not say.
+    //
+    // The REST-DESTRUCTURE is the other half, and it is about the OBJECT rather than
+    // its type. `build.options` is the caller's own FLAT record, so a raw
+    // `restartMinDelay` it wrote is copied by a spread whatever the spread's static
+    // type says it holds; discarded here, it is not in the object to be copied at
+    // all. Without it the resolved figure would stay on top only while it was written
+    // LAST in the literal, and a transposition of two adjacent lines would typecheck
+    // and then run the unjudged figure — a rule that has to be remembered is one an
+    // edit reading as pure tidying can break.
+    //
+    // The three discards are the one place a resolved field is named twice, and they
+    // cannot silently fall out of step: a fourth resolved figure stops the literal
+    // below compiling until it is named there, and its author is then one line from
+    // this destructure.
+    //
+    // The caller's two PIPELINE figures ride along in the copy and are inert: the
+    // supervisor reads its options by name and has no field either could reach.
+    // Excluding them would be two more discards for nothing.
+    //
+    // What is destructured is the OPTIONS and not `resolved`: that record is flat and
+    // also carries `view`, `viewDurability`, `batchSize` and `batchWindow`, so
+    // spreading it wholesale would ride four dead fields into a supervisor's options
+    // object — the hazard `runProjections.ts` names where it builds its entry literal
+    // explicitly.
+    //
+    // `?? {}` rather than the conditional spreads this replaced.
+    // `exactOptionalPropertyTypes` bars setting an optional key to an explicit
+    // `undefined`, and this sets none: spreading an object contributes only the keys
+    // it has, and an absent whole options object contributes none at all.
+    //
+    // The progress signal goes in as a VALUE, so nothing has been read from the
+    // view store yet: a runner rejected above still has not touched it.
+    //
+    // Nothing is handed in for RENDERING the runner's faults on the supervisor's
+    // log lines. All four set `message`, so `String(fault)` is
+    // `Error.prototype.toString` — `'ProjectionStoreError: ECONNRESET'` — and each
+    // fault labels itself wherever it is reported, from the field that says why.
+    // `CheckpointSuperseded`'s is the interesting one and its own doc carries the
+    // argument: its `expected` is a `bigint`, but a `bigint` interpolated into a
+    // `string` is digits, so the value class the log reduction below keeps away from
+    // a serialiser never reaches one through `message`.
+    //
+    // The residual error is `ProjectionStalled` and nothing else: the schedule
+    // never terminates on its own, so the only way out with a failure is the
+    // breaker giving up. `superviseOnProgress` carries that reasoning.
+    const {
+      restartMinDelay: _rawMinDelay,
+      restartMaxDelay: _rawMaxDelay,
+      restartResetAfter: _rawResetAfter,
+      ...supervisionOverrides
+    }: ProjectionRunnerOptions = build.options ?? {}
+
+    const daemon: Effect.Effect<
+      void,
+      ProjectionStalled,
+      Serializer | RSlices | R
+    > = superviseOnProgress(runOnce, {
+      key,
+      progress: view.readCheckpoint,
+      ...supervisionOverrides,
+      restartMinDelay,
+      restartMaxDelay,
+      restartResetAfter,
+    })
+
+    // ## FORK
+    //
+    // `forkScoped`, so the daemon's lifetime IS the caller's scope: no manual
+    // shutdown handle to forget, and scope close interrupts and awaits the fibre
+    // deterministically. A plain `Effect.fork` would tie it to the calling
+    // fibre's lifetime, which for a wiring effect that returns immediately would
+    // kill the daemon on the spot.
+    const fibre = yield* Effect.forkScoped(daemon)
+
+    // The BOUND view goes back with the fibre, which is what lets a returned handle
+    // name its own cursor. It is the same object the pipeline above commits through,
+    // not a re-binding: `runProjections` resolved it from a store its caller never
+    // bound, and equal keys across N entries leave it as the only discriminator.
+    return { key, store: view, fibre }
+  })