@kairos-es/read 0.0.0

package/src/runProjections.ts

@@ -0,0 +1,623 @@
+/**
+ * `runProjections` — one read model materialised N WAYS: one slice record and one
+ * `ProjectionId` for the whole call, one `Materialisation` per view store, and one
+ * `ProjectionRunner` forked for each.
+ *
+ * ## What it is for
+ *
+ * `ReadModel.store` records what a slice's GRADUATION from an in-memory view to
+ * Postgres does and does not change, and owns that claim. Per-read-model view-store
+ * selection is a FLOOR rather than a ceiling, though, and nothing in that claim says
+ * the two variants must be alternatives in TIME. A deployment can legitimately want
+ * both at once: a durable table somebody queries with SQL, beside an in-process view
+ * of the same slices holding one aggregate's hot figures with no round trip to reach
+ * them. Written as two `runProjection` calls that is two hand-built read models with
+ * the slice record named at both, and nothing placed to notice when the two copies
+ * drift apart.
+ *
+ * A hand-written pair also cannot get the REFUSAL the shape needs, and that is the
+ * half worth stating beside the sharing. Two materialisations bound to one store
+ * under one key would trade cursors, each advancing the other's; the gate's collision
+ * rung is what says so, and it is vacuous over the singleton each `runProjection`
+ * call hands it, having no sibling there to compare against. So the pairing is
+ * refused when the entries arrive together and unrefused when they are written
+ * separately, which is a property of the CALL rather than of any rule this module
+ * owns.
+ *
+ * ## The guarantee, at exactly its strength
+ *
+ * ONE QUERY, ONE DECODE, N APPLIES. The `slices` value is stated once for the call,
+ * and the two derivations from it are built ONCE for it — in `prepareProjection`,
+ * the phase `runProjection` shares — and handed to every entry: one
+ * `Query` object across the N subscriptions, one merged `type -> Schema` table across
+ * the N decode stages. There is no second place for either to be written
+ * differently, because there is no second place they are written at all — and now
+ * literally no second OBJECT either.
+ *
+ * It is NOT "N materialisations cannot drift", and nothing in this package should be
+ * worded that way. The FOLDS drift freely: a SQL `apply` that writes rows
+ * re-implements the fold rather than reusing `foldIntoRef`, so two materialisations
+ * of one slice record can disagree about what they made of the very same events.
+ * What is shared VERBATIM is the slices — the query and the decode schemas — and
+ * never the FOLD. Agreement between N materialised figures is therefore
+ * EMPIRICAL, something a test demonstrates by comparing the figures; it is not
+ * structural, and this function does not make it so.
+ *
+ * ## The guarantee is CONSTRUCTION-SCOPED, and that is enough
+ *
+ * This holds sharing at the moment of the CALL. Nothing afterwards carries it: each
+ * runner is an ordinary supervised pipeline from the fork onwards, and none of them
+ * can see its siblings. That is the same move `forKey` makes one level down — bind
+ * the pairing into the value every later operation flows through, so the incoherent
+ * thing is unwritable rather than merely unwritten — and it is sufficient here for a
+ * structural reason. The subscription's query and the decode table are both built
+ * FROM the slices at construction, in the one PREPARE phase, and are never rebuilt: a
+ * restart re-subscribes with the query it already holds. So there is no later moment at
+ * which one materialisation could come to hold a different query from its siblings,
+ * and no ongoing agreement for anything to police.
+ *
+ * ## Why a module of its own
+ *
+ * It composes the runner's three phases — `resolveProjection`, `prepareProjection`
+ * (which is where the construction gate is consulted) and `buildAndFork` — with
+ * `forKey`, and adds nothing to any of them: no pipeline
+ * stage, no supervision, no store operation, and no rule of its own at all, the
+ * collision being a rung of the one gate both entry points consult.
+ * The precedent for taking a whole job out of `ProjectionRunner.ts` is that module's
+ * own history, three times over: `superviseOnProgress.ts` and
+ * `projectionWiringFault.ts` were both extracted from it and each became testable on
+ * its own terms by being, and `runProjection.ts` — the SINGULAR entry point, this
+ * module's opposite number — was split off it in turn, leaving that file the shared
+ * pipeline substrate both entry points sit on. No count of lines is quoted here on
+ * purpose: the argument is that the file accretes JOBS, which is true of it at any
+ * length.
+ *
+ * ## Why there is no `projectionsLayer`
+ *
+ * `projectionLayer` is `Layer.scopedDiscard(runProjection(readModel, options))` and
+ * nothing else, so the layer shape for N materialisations is
+ * `Layer.scopedDiscard(runProjections(spec))` — which discards the N runners exactly
+ * as `projectionLayer` discards the one, and for the same reason (a projection is a
+ * background process, not a service). A second one-line wrapper would be a second
+ * home for one line, and the argument `projectionLayer`'s doc makes — that a `Layer`
+ * is how an application's graph owns a daemon's lifetime, with no bespoke startup or
+ * shutdown code — is already written down once. The one consequence worth carrying
+ * across is `projectionLayer`'s too: a discarded runner has no fibre to await, so a
+ * stall reaches the outside world only through the supervisor's `logError` and
+ * through `onStalled`, which under this function is a hook per materialisation.
+ */
+import type {
+  RequirementOf,
+  Serializer,
+  SliceProjection,
+} from '@kairos-es/codec'
+import type { DcbEventStore, DecodedEvent } from '@kairos-es/core'
+import { Array as Arr, Effect, type Scope } from 'effect'
+import type { EventLogDurability } from './EventLogDurability'
+import {
+  buildAndFork,
+  type ProjectionRunner,
+  type ProjectionRunnerOptions,
+  prepareProjection,
+  resolveProjection,
+} from './ProjectionRunner'
+import {
+  checkpointKey,
+  forKey,
+  type PartitionId,
+  type ProjectionId,
+  type ProjectionStore,
+} from './ProjectionStore'
+
+/**
+ * ONE way a read model is materialised: where its view lives, how a batch is
+ * written into it, and how its own runner is tuned.
+ *
+ * It is a `ReadModel` minus the two things `runProjections` supplies for the whole
+ * call — the slices, and the `forKey` binding — which is why the store here is the
+ * UNBOUND multi-key port rather than a `KeyedProjectionStore`.
+ *
+ * ## Why BOTH parameters survived the tuple fix, `E` included
+ *
+ * `E` was considered for removal and deliberately KEPT, so a reader meeting it here
+ * is not meeting an oversight. The case for dropping it was that one `E` shared
+ * across N entries fails to reconcile — but that was the SAME defect as `R`'s, and
+ * `MaterialisedProjection`'s tuple parameter fixes it for both by one mechanism:
+ * two entries with two distinct error classes now infer `ErrA | ErrB`. Removing the
+ * parameter would therefore delete a working, CHECKED type to route around a bug
+ * that is already fixed.
+ *
+ * Two things would have gone with it. The `ReadModel` correspondence this doc opens
+ * with: `ReadModel<T, E, R>` keeps its `E`, and typing an `apply`'s error as
+ * `unknown` here would mean the two were no longer the same shape — which
+ * `examples/course-subscriptions/src/courseRosterSql.ts` would be the first to
+ * notice, one value there serving as both. And a check a caller gets for free:
+ * `Materialisation<never>` states that an `apply` CANNOT fail and is verified,
+ * `Materialisation<SqlError>` that this one fails only that way. Under `unknown`
+ * both become unwritable and every `apply` typechecks, including one whose author
+ * got the error type wrong.
+ *
+ * The narrower version of that insight is real and IS taken, one level up:
+ * `MaterialisationAny` bounds BOTH positions with `unknown`, and loses nothing by
+ * it, because a CONSTRAINT is not a type anything declares a value at. Wherever a
+ * caller DOES declare one — a value typed `Materialisation<SqlError>`, or a domain
+ * interface of its own parameterised by that error, which is the shape
+ * `examples/course-subscriptions` takes — the check above is still theirs. The bound
+ * only has to admit the result.
+ */
+export interface Materialisation<E = never, R = never> {
+  /**
+   * The multi-key view store this materialisation writes into, UNBOUND.
+   *
+   * Unbound because `runProjections` does the binding, from the one `ProjectionId`
+   * the call names and this entry's own `partition`. `MaterialisedProjection`'s own
+   * doc argues why that direction is load-bearing rather than merely convenient.
+   */
+  readonly store: ProjectionStore
+
+  /**
+   * THIS materialisation's per-batch view writes, handed to its own
+   * `ProjectionStore.commit` so they land inside the same transaction as its own
+   * checkpoint advance.
+   *
+   * Every obligation `ReadModel.apply` carries applies here unchanged and per
+   * entry: the batch is non-empty by construction, and a NON-TRANSACTIONAL store's
+   * `apply` must be a SINGLE atomic effect (fold the batch purely, then one write —
+   * `foldIntoRef`), because the port cannot roll back a multi-write `apply` that
+   * fails part-way. N materialisations means N independent answers to that: an
+   * in-memory entry beside a SQL one owes the requirement, and the SQL one does not
+   * discharge it on its behalf.
+   *
+   * ## ONE MATERIALISATION OWNS ONE VIEW TARGET, and the gate cannot check it
+   *
+   * Two entries whose `apply`s write the SAME view — the same `Ref`, the same row,
+   * the same table — are a defect, and one nothing here refuses. It is the exact
+   * mirror of the collision the gate DOES catch: that one is two entries sharing a
+   * CURSOR, this one is two entries sharing a TARGET. Both end with the view wrong
+   * indefinitely and nothing on any error channel.
+   *
+   * It is undetectable rather than merely unchecked, and the reason is structural:
+   * the view lives INSIDE this closure, so the library sees an opaque effect and has
+   * nothing to compare. Where the collision rung has two store references and two
+   * resolved keys to hold up against each other, here it has two functions.
+   *
+   * The failure is worth recognising because it looks nothing like a race. Both
+   * runners are sound single writers of their OWN cursors, each committing exactly
+   * once per batch; they simply both apply every event to one target, so the figures
+   * come out doubled (or last-write-wins, for a `set` rather than an increment)
+   * while both checkpoints advance cleanly to head. A caller reaching for a second
+   * materialisation almost always wants a second VIEW to go with the second store —
+   * and if the two views really are meant to be one, that is ONE materialisation
+   * with one `apply`, which is the same answer the collision rung's message gives.
+   */
+  readonly apply: (
+    batch: Arr.NonEmptyReadonlyArray<DecodedEvent>,
+  ) => Effect.Effect<void, E, R>
+
+  /**
+   * This materialisation's checkpoint PARTITION. Defaults to `DEFAULT_PARTITION`,
+   * which is what nearly every call wants.
+   *
+   * Present for the one shape that needs it: two materialisations that genuinely
+   * must COHABIT one `ProjectionStore`. Under one `ProjectionId` and the default
+   * partition their `CheckpointKey`s would be identical, so they would be two
+   * runners over ONE cursor, racing the same guarded advance on every batch — which
+   * `materialisationCollisionFault` refuses at construction, and whose sentence
+   * names this field as the escape hatch. A distinct `PartitionId` is a distinct
+   * `CheckpointKey` and therefore a cursor of its own.
+   *
+   * It is NOT sharding: nothing here splits one materialisation's stream, which
+   * ADR-0007 rules out and `PartitionId`'s own doc explains. Each partition still
+   * has exactly one runner over the whole composed query.
+   */
+  readonly partition?: PartitionId
+
+  /**
+   * This materialisation's own pipeline tuning and supervision hooks — the same
+   * object `runProjection` takes, per entry.
+   *
+   * ## Why PER ENTRY, and why there is no call-level options object
+   *
+   * The figures are genuinely per materialisation: a SQL `apply` and a `Ref` update
+   * want different batch sizes and different latency ceilings, and there is nothing
+   * about "one read model" that makes one transaction size right for both.
+   *
+   * The observability halves settle it. Each materialisation's checkpoint IS its
+   * progress signal, so `onRestart` and `onStalled` are about ONE of them: a restart
+   * is a rate to graph and a stall needs a human, and an operator has to be able to
+   * attribute either — collapsing N signals into one pair of hooks would report that
+   * something restarted while saying nothing about WHAT. There is a sharp
+   * consequence worth stating because it surprises: under one `ProjectionId` and the
+   * default partition the N `CheckpointKey`s are IDENTICAL — the intended shape, a
+   * key naming a cursor WITHIN a store — so `info.key` on the hooks does not
+   * discriminate the materialisations. For SUPERVISION the discriminator is WHICH
+   * ENTRY'S HOOK FIRED, which is exactly what a per-entry options object gives and a
+   * call-level one would take away.
+   *
+   * That argument is about the hooks specifically and does not generalise to every
+   * observer. A hook is handed a payload rather than a handle, so the discriminator
+   * a RETURNED runner has — `runners[i].store`, the bound cursor it maintains — is
+   * not in reach from inside one. An operator attributing a stall therefore closes
+   * over the entry, while a caller reading how far each materialisation has got asks
+   * its runner.
+   *
+   * A call-level object would also be a second home for every figure in
+   * `ProjectionRunnerOptions`, free to disagree with the per-entry one, with a merge
+   * order to document and get wrong. Sharing a tuning across entries is a `const`
+   * the caller writes once and names twice, which needs no library support.
+   */
+  readonly options?: ProjectionRunnerOptions
+}
+
+/**
+ * Any materialisation at all, whatever its `apply` fails with and whatever it
+ * needs — the CONSTRAINT on the tuple below, and not a type anything declares a
+ * value at.
+ *
+ * Both positions are `unknown` — the widest bound that is not `any`, so the tuple
+ * admits every materialisation while erasing nothing a reader could mistake for a
+ * check. The `R` half of that is what makes the body's ONE assertion MANDATORY: a
+ * wildcard bound would make it optional, and an optional assertion is one nobody
+ * writes.
+ *
+ * Under this bound an element of `Ms` is known only to be a
+ * `Materialisation<unknown, unknown>`, so the requirement `Effect.forEach` would
+ * infer from `entry.apply` is `unknown`, which satisfies no declared requirement:
+ * the module does not compile until the one `buildAndFork` call says what the
+ * entries actually need. It says it once and narrowly — on `entry.apply` alone, to
+ * exactly `MaterialisationContext<Ms>`, the alias the return type already names —
+ * and everything downstream is then inferred from that alias rather than from a
+ * wildcard, so the WHOLE requirement channel of the declared return type is CHECKED.
+ * Deleting `Serializer`, `DcbEventStore` or `MaterialisationContext<Ms>` itself from
+ * that union is a compile error, as is deleting the assertion; verified by mutation
+ * rather than reasoned about, all four.
+ *
+ * `any` in the `R` position also compiles, and compiles with no assertion at all,
+ * which is what makes it the tempting shape. It is the wrong trade and not a small
+ * one: `X | any` normalises to `any`, so the body's requirement erases ENTIRELY and
+ * every member of that union could be deleted — or a service the body never needs
+ * added — with the module still green. An `as` on one line is the narrow, visible
+ * form of the trade `@kairos-es/codec`'s `makeRegistry` makes with its single cast;
+ * a wildcard bound is the wide, silent form of the same thing, and the absence of an
+ * `as` is not the absence of an assertion.
+ *
+ * The `E` position is `unknown` for a duller reason and needs no assertion of its
+ * own: `E` never reaches this function's return type, `runProjections` being
+ * infallible, so no error an entry declares has anywhere to go but its supervisor.
+ */
+type MaterialisationAny = Materialisation<unknown, unknown>
+
+/**
+ * The union of requirements `R` carried by a TUPLE of materialisations — what makes
+ * two entries needing two different services compile with nothing annotated.
+ *
+ * ## Why a tuple parameter, and what the shape it replaced could not do
+ *
+ * The obvious signature is one `Materialisation<E, R>` for every entry, and it is
+ * WRONG in a way that only shows up on the very shape this function exists for.
+ * With one `R` shared across N entries, TypeScript collects a candidate from each
+ * element and then checks the rest against the first, so two entries needing two
+ * different services do not union — the second is reported as not assignable to the
+ * first, and the caller's only recourse is to compute the union by hand and annotate
+ * it. Heterogeneous view stores is the whole point of this function, and under that
+ * signature the heterogeneous case was the one that did not work.
+ *
+ * A tuple parameter has no single `R` to reconcile. `Ms` is inferred PER ELEMENT, so
+ * no candidate has to lose, and this alias then reads the union back off the
+ * inferred tuple, and is also the body's one assertion target, for the reason
+ * `MaterialisationAny` gives. It is the mechanism `Effect.all` uses for exactly this
+ * problem —
+ * `All.ReturnTuple` indexes its tuple with `T[number]` and infers through the
+ * variance struct, and `effect`'s own dtslint suite pins the result
+ * (`Effect.all([string, number])` is
+ * `Effect<[string, number], "err-1" | "err-2", "dep-1" | "dep-2">`).
+ *
+ * ## Why the brackets, when they do nothing here
+ *
+ * They are the idiom `Effect.Context` is written in and the form that stays correct
+ * under the one edit a later reader is most likely to make. They are NOT what
+ * produces the union, and this doc says so plainly because the alternative is a
+ * reader concluding they are magic and preserving them while "simplifying" the tuple
+ * parameter away — which is the change that actually breaks it.
+ *
+ * Distribution happens only when the checked type is a NAKED type parameter, and
+ * `Ms[number]` is an indexed access, so the conditional here does not distribute and
+ * the brackets suppress nothing. Both forms were compiled side by side over a
+ * two-entry tuple, an array of a union and the empty tuple, and agreed on all three.
+ * Should the checked type ever become a bare parameter, the brackets are what keeps
+ * the answer the same.
+ *
+ * `R` is COVARIANT in Effect v3 (`Effect<out A, out E, out R>`, and `_R:
+ * Covariant<R>` on the variance struct), which is why inferring across the elements
+ * yields a UNION and not an intersection.
+ */
+type MaterialisationContext<
+  Ms extends Arr.NonEmptyReadonlyArray<MaterialisationAny>,
+> = [Ms[number]] extends [Materialisation<infer _E, infer R>] ? R : never
+
+/**
+ * One read model — its slices and its identity — plus the N ways it is materialised:
+ * the whole input of `runProjections`.
+ *
+ * ## Why the UNBOUND store per entry plus ONE `ProjectionId` for the call
+ *
+ * The alternative shape is N pre-bound `KeyedProjectionStore`s, and it was rejected
+ * for three reasons that are each load-bearing.
+ *
+ * It makes the PRIMARY GUARANTEE structural. One `slices` field cannot become two,
+ * so "one query, one decode" is a property of the type rather than of a caller's
+ * discipline — which is the whole point of the function, and would be given away by
+ * a shape that took N read models.
+ *
+ * It makes the KEY POLICY structural too. One `ProjectionId` for the call is what
+ * "one read model, N materialisations, ONE identity" MEANS, and it is the honest
+ * reading of a `CheckpointKey`: the key is a lookup identifier WITHIN one store, so
+ * N stores holding the same key are N materialisations of one read model, not a
+ * collision. N pre-bound stores would leave every caller free to fragment one read
+ * model's identity across N ids — nothing would break, and nothing would ever say
+ * so, until somebody went looking for one projection's cursors and found three
+ * names.
+ *
+ * And it is the only shape in which the collision check is POSSIBLE at all. `forKey`
+ * returns a fresh object literal that deliberately does not expose the store it
+ * closed over (so that a `{ ...inner, commit: … }` decorator decorates), so nothing
+ * downstream of a binding can compare two bound stores for store IDENTITY. The
+ * unbound port is the last point at which "these two entries are the same store" is
+ * a question anything can ask.
+ *
+ * All three are the same move as `forKey` itself, one level up: bind the pairing
+ * into the value every later operation flows through, so a wiring cannot express the
+ * incoherent thing.
+ *
+ * ## Why the materialisations are a NON-EMPTY array
+ *
+ * An empty list is a projection nobody maintains, forked silently — no runner, no
+ * checkpoint, no view, and no error either. The type refuses it a stack frame from
+ * where it was written, which is both earlier and cheaper than a rung of the
+ * construction gate. It is also why the return type is non-empty: the runners come
+ * back one per entry, in entry order.
+ *
+ * ## Why the materialisations are a TUPLE parameter and not `Arr.NonEmptyReadonlyArray<Materialisation<E, R>>`
+ *
+ * So that N entries needing N different services compile with nothing annotated.
+ * `MaterialisationContext` above owns that argument in full; what it means HERE is
+ * that the second parameter is the entries' own inferred tuple rather than a shared
+ * `E`/`R` pair, and that `Ms` is normally inferred and never written. Its default is
+ * what keeps the one-argument spelling — `MaterialisedProjection<Slices>` — reading
+ * as it always did, for the callers that only ever name the slices.
+ *
+ * ## What the tuple parameter COSTS: one assertion, on one line, at one call site
+ *
+ * It is stronger for CALLERS and costs the body exactly one `as`. Under the shape it
+ * replaced, the body's requirement came straight off `entry.apply`, which was
+ * `Effect<void, E, R>`. Under a tuple parameter an element is known only by its
+ * CONSTRAINT, so `entry.apply` reads as `Effect<void, unknown, unknown>` inside the
+ * body and the assembled effect satisfies no declared requirement until the
+ * `buildAndFork` call names one. `MaterialisationAny`'s doc owns that mechanic and
+ * the reason the bound is `unknown` rather than a wildcard; what it means HERE is
+ * the ONE thing the compiler is asked to take on trust.
+ *
+ * That one thing is narrow and worth stating exactly: an entry's `apply` requires no
+ * more than the union `MaterialisationContext<Ms>` reads back off the very tuple the
+ * entry came from. It is true by construction — the alias IS that union and the
+ * entry IS an element of that tuple — but TypeScript cannot verify it for an
+ * unresolved generic `Ms`, the alias being a deferred conditional over `Ms[number]`.
+ * Assert something wider there and callers would be asked for services no entry
+ * needs; assert `never` and they would be asked for nothing, and a genuinely missing
+ * service would surface as a runtime defect instead of a type error. Which is why
+ * the alias is written in exactly two places, the assertion and the return type, and
+ * they are the same expression.
+ *
+ * Everything downstream of that line is CHECKED, which is the whole return on
+ * keeping it narrow: the declared requirement channel is verified member by member,
+ * and the assertion itself cannot be quietly deleted by a later reader who finds it
+ * decorative. `MaterialisationAny` names the mutations that demonstrate both. The
+ * value channel is checked too — the runners come back one per entry and the
+ * non-emptiness is real.
+ *
+ * ## Why the runners come back as an ARRAY and not as a mapped TUPLE
+ *
+ * `{ readonly [K in keyof Ms]: ProjectionRunner }` compiles, and it makes a
+ * two-entry call hand back a `readonly [ProjectionRunner, ProjectionRunner]`. It was
+ * measured and declined. `Arr.With` — the type both `Arr.map` and `Effect.forEach`
+ * map their input through, `S extends NonEmptyReadonlyArray<any> ? NonEmptyArray<A>
+ * : Array<A>` in Effect v3 — has dropped the ARITY by the first of those two steps
+ * and nothing recovers it, so the mapped tuple needs a SECOND assertion, on the
+ * `Effect.forEach` result, and that one converts the value channel above from
+ * checked into asserted.
+ *
+ * What it buys back is arity and only arity. Every element is a `ProjectionRunner`,
+ * so it cannot express the pairing `runners[i]` ↔ `materialisations[i]` that the
+ * entry ORDER carries and that this module's prose states; and with
+ * `noUncheckedIndexedAccess` off, as it is across this repo, no call site reads
+ * differently either way. Trading a check for an assertion to type something no
+ * caller can use is the wrong direction.
+ */
+export interface MaterialisedProjection<
+  T extends Record<string, SliceProjection>,
+  Ms extends
+    Arr.NonEmptyReadonlyArray<MaterialisationAny> = Arr.NonEmptyReadonlyArray<Materialisation>,
+> {
+  /**
+   * The slices every materialisation shares: their composed query is the ONE
+   * subscription query and their merged schema table is the ONE decode lookup.
+   *
+   * Stated once for the call, which is the guarantee — see the module doc for what
+   * that guarantee does and does not extend to.
+   */
+  readonly slices: T
+
+  /**
+   * The read model's identity, shared by every materialisation.
+   *
+   * One name for one read model however many ways it is materialised, because a
+   * `CheckpointKey` identifies a cursor WITHIN a store: equal keys across two
+   * different stores are the intended shape of a graduated slice, not a clash.
+   */
+  readonly projection: ProjectionId
+
+  /** The N ways it is materialised, at least one. */
+  readonly materialisations: Ms
+}
+
+/**
+ * Start one daemon per materialisation, all forked into the caller's `Scope`.
+ *
+ * The returned effect is INFALLIBLE for the reason `runProjection`'s is: starting a
+ * projection cannot fail, because everything that can go wrong once one is running
+ * belongs to its own supervisor and lives on its own fibre's error channel. The
+ * runners come back in ENTRY ORDER, so `runners[i]` is `materialisations[i]`'s.
+ *
+ * Each runner carries the store THIS call bound for its entry, so `runners[i].store`
+ * is that materialisation's cursor and a caller observing one re-derives no binding
+ * it never wrote. It is also what tells the N handles apart: under one `ProjectionId`
+ * the keys are equal wherever no entry named a partition, so a runner carrying only a
+ * key could not name which of the N views it maintains.
+ *
+ * ## N = 1 is legal and carries nothing inert
+ *
+ * One entry is `runProjection` with the `forKey` binding done for you, and every
+ * field means the same thing it means at N = 3. The two run the identical phases —
+ * one `resolveProjection`, one `prepareProjection`, one `buildAndFork` — rather than
+ * merely offering the same surface, so there is no threshold at which a caller should
+ * switch functions: a read model that grows a second materialisation adds an entry.
+ *
+ * ## Every rule is judged before ANY entry is forked
+ *
+ * The construction gate takes the whole call — the shared log, query and slice
+ * record, plus the N resolved wirings — and this call reaches it ONCE, through
+ * `prepareProjection`, above the `Effect.forEach` below. So a call refused for ANY
+ * reason has forked NOTHING,
+ * not even the entries that were sound: not the collision, which is a property of
+ * the set, and not a degenerate `batchWindow` or an R2 violation on the last entry
+ * either. Half a call running is a worse state than none of it, and the pairing of N
+ * materialisations is one wiring decision.
+ *
+ * Two consequences of the gate judging a SET are worth stating rather than leaving
+ * to be met.
+ *
+ * A per-entry rung names its ENTRY. The gate prefixes its verdict with
+ * `materialisations[i]` where there is more than one entry, in the vocabulary the
+ * collision sentence already uses; this function's preamble names the PROJECTION and
+ * no partition, because under one `ProjectionId` the N keys are equal wherever no
+ * entry named a partition, so a partition never discriminated them.
+ *
+ * And the order is over RULES, not over entries. Where two entries break two
+ * DIFFERENT rules the earlier RULE wins whatever entry it is in — entry 0's
+ * degenerate `batchWindow` beside entry 1's illegal durability pairing reports entry
+ * 1's R2 fault, because R2 is the wider mistake wherever it sits. The gate's module
+ * doc argues that, and it is why the rules are judged rule-major rather than by
+ * walking the entries.
+ */
+export const runProjections = <
+  T extends Record<string, SliceProjection>,
+  Ms extends Arr.NonEmptyReadonlyArray<MaterialisationAny>,
+>(
+  spec: MaterialisedProjection<T, Ms>,
+): Effect.Effect<
+  Arr.NonEmptyReadonlyArray<ProjectionRunner>,
+  never,
+  | Scope.Scope
+  | DcbEventStore
+  | EventLogDurability
+  | Serializer
+  | RequirementOf<T>
+  | MaterialisationContext<Ms>
+> =>
+  Effect.gen(function* () {
+    // ## RESOLVE — everything the gate has to judge, and every figure that runs
+    //
+    // Each entry's key and its five defaulted figures, through the same pure
+    // `resolveProjection` a single wiring goes through. Resolved here and carried,
+    // rather than derived twice: the gate below judges these values and the pipelines
+    // further down run from these same values, so what was checked cannot differ from
+    // what runs.
+    //
+    // Built as an EXPLICIT literal rather than by spreading the `Materialisation`,
+    // so every field on an entry has exactly one meaning and nothing dead rides
+    // along. A spread would carry the caller's `store` and `partition` into a record
+    // that already holds the BOUND view (from the resolve step) and the UNBOUND port
+    // under `cursorIdentity` — two names for one reference, one name for a different
+    // one, and a `partition` nothing downstream reads because `key` has absorbed it.
+    // That is a near-miss of the very hazard `cursorIdentity` was renamed to close.
+    //
+    // `cursorIdentity` is the UNBOUND port here, which is the last surface at which
+    // sameness is askable — `forKey` returns a fresh literal per call and does not
+    // expose what it closed over, so two bound views are never equal even over one
+    // store. `runProjection` passes its bound view instead, which is free at an arity
+    // where the rung cannot fire. `MaterialisationWiring`'s doc owns that argument.
+    const entries = Arr.map(spec.materialisations, (materialisation) => {
+      const key = checkpointKey(spec.projection, materialisation.partition)
+      return {
+        ...resolveProjection(
+          forKey(materialisation.store, key),
+          materialisation.options,
+        ),
+        cursorIdentity: materialisation.store,
+        apply: materialisation.apply,
+        options: materialisation.options,
+      }
+    })
+
+    // ## PREPARE — the log's durability, the merged query, the gate, the decode
+    //
+    // The shared middle, and the same call `runProjection` makes with a singleton.
+    // It reads the LOG's half of R2 from context — once for the call, because it IS
+    // one fact about one log — composes the ONE query the N subscriptions share,
+    // judges all five rungs over the whole entry list, and only then builds the ONE
+    // decode stage the N pipelines share. All of it above the `Effect.forEach` below,
+    // so a refused call has forked nothing.
+    //
+    // The order of the last two steps is `prepareProjection`'s to own, and it is why
+    // `decodeSlices` is not simply hoisted beside the composition: a record wrong in
+    // the codec's way AND in one of the gate's must meet the gate's sentence.
+    //
+    // The preamble is this function's own half of the defect message: the PROJECTION
+    // and no partition, because under one `ProjectionId` the N keys are equal wherever
+    // no entry named one, so a partition never discriminated them. The gate prefixes
+    // the entry index itself, where there is a set to index into.
+    const prepared = yield* prepareProjection(
+      spec.slices,
+      entries,
+      `runProjections: invalid wiring for projection '${spec.projection}'`,
+    )
+
+    // ## FORK — one runner per entry, SEQUENTIALLY
+    //
+    // No `concurrency` option, deliberately. `buildAndFork` returns as soon as its
+    // daemon is forked into this scope, so it does no waiting for a concurrent pass
+    // to overlap: concurrency would buy nothing and would cost the returned ORDER,
+    // which is what lets a caller pair a runner with the entry it maintains. The
+    // daemons themselves run concurrently regardless — that is what forking them is.
+    //
+    // A runner naming its own bound cursor does not make that order redundant. The
+    // entry hands over an UNBOUND port and `forKey` deliberately does not expose what
+    // it closed over, so nothing a caller still holds can be compared against
+    // `runners[i].store` to recover which entry it came from. The order is the only
+    // statement of that pairing, and it is why this fold stays sequential.
+    //
+    // Each entry reaches the SAME build step a single wiring reaches, with the same
+    // shared query and the same shared decode stage, so the N pipelines differ in
+    // nothing but their store, their `apply` and their tuning.
+    return yield* Effect.forEach(entries, (entry) =>
+      buildAndFork(entry, {
+        query: prepared.query,
+        decode: prepared.decode,
+        // THE one assertion in this function, and the reason the requirement
+        // channel declared above is checked rather than wished for. Inside the
+        // body an entry is known only by its constraint, so this `apply` reads as
+        // `Effect<void, unknown, unknown>`; naming the alias the return type
+        // already names is what carries the entries' real requirement through
+        // `buildAndFork`, where a wildcard bound would instead absorb the lot and
+        // leave every member of that union unverified. It is narrow on purpose —
+        // `entry.apply` alone, to one expression written in one other place —
+        // and it cannot be dropped: without it the module does not compile.
+        // `MaterialisationAny` owns the mechanic, `MaterialisedProjection` what
+        // the compiler is being asked to take on trust.
+        apply: entry.apply as (
+          batch: Arr.NonEmptyReadonlyArray<DecodedEvent>,
+        ) => Effect.Effect<void, unknown, MaterialisationContext<Ms>>,
+        options: entry.options,
+      }),
+    )
+  })