@kairos-es/read 0.0.0

package/src/runProjection.ts

@@ -0,0 +1,270 @@
+/**
+ * `runProjection` — the read side's SINGULAR entry point: one read model, one view
+ * store, one supervised daemon forked into the caller's `Scope`; plus
+ * `projectionLayer`, the same call shaped as a `Layer` so an application's graph owns
+ * that daemon's lifetime.
+ *
+ * ## Two entry points, one substrate
+ *
+ * This module and `runProjections.ts` are the read side's TWO entry points, and they
+ * are deliberately symmetrical one arity apart: N = 1 here, N >= 1 there. Neither
+ * builds a pipeline of its own and neither carries a rule of its own. Both run the
+ * three phases in `ProjectionRunner.ts` — `resolveProjection`, `prepareProjection`
+ * (which is where the construction gate `projectionWiringFault.ts` is consulted, for
+ * both of them, before either forks anything) and `buildAndFork` — so what differs
+ * between them is the shape of their INPUT and nothing else.
+ *
+ * Neither calls the other, and that follows from those input shapes rather than being
+ * an omission: a `ReadModel` carries a BOUND `KeyedProjectionStore`, a
+ * `Materialisation` an UNBOUND `ProjectionStore` plus the one `ProjectionId` the call
+ * names, and `forKey` deliberately does not expose what it closed over — so there is
+ * no route back from the first shape to the second. `runProjections.ts` owns that
+ * argument in full; this is the pointer to it, not a second home for it.
+ *
+ * ## Why a module of its own rather than a section of the substrate
+ *
+ * Because a file declaring the `ProjectionRunner` handle, the two option sets, the
+ * three shared phases AND one of the two entry points reads as though that entry
+ * point were the privileged one. It is not: it is the N = 1 case, and a read model
+ * that grows a second materialisation moves to the sibling without changing anything
+ * about how it is run. Keeping the substrate under the name of the type it declares,
+ * and each entry point in a file named for the function it exports, is what makes
+ * that symmetry visible from the directory listing.
+ */
+import type {
+  RequirementOf,
+  Serializer,
+  SliceProjection,
+} from '@kairos-es/codec'
+import type { DcbEventStore, DecodedEvent } from '@kairos-es/core'
+import { type Array as Arr, Effect, Layer, type Scope } from 'effect'
+import type { EventLogDurability } from './EventLogDurability'
+import {
+  buildAndFork,
+  type ProjectionRunner,
+  type ProjectionRunnerOptions,
+  prepareProjection,
+  resolveProjection,
+} from './ProjectionRunner'
+import type { KeyedProjectionStore } from './ProjectionStore'
+
+/**
+ * One read model: where it materialises (under which key), which slices drive it,
+ * and how a batch is applied.
+ *
+ * The slices are load-bearing twice over: their composed query is the
+ * subscription's query (so the runner reads exactly the events the folds want,
+ * with no separate query to keep in step), and their merged `type -> Schema` map
+ * is the decode lookup. There is no way to declare one without the other.
+ *
+ * The other half of R2 — the EVENT LOG's durability — is deliberately NOT a field
+ * here: it is declared once beside the store layer as the `EventLogDurability`
+ * service and read from context. `EventLogDurability.ts` argues why, and states
+ * the rule both halves feed.
+ *
+ * By R3, read models sharing one subscription share one cursor and therefore one
+ * `CheckpointKey`, one view store and one durability class — which is why a
+ * composed bundle is expressed as ONE `ReadModel` over several slices rather than
+ * several `ReadModel`s over one subscription.
+ *
+ * That bound is about sharing one SUBSCRIPTION, and the boundary is worth stating
+ * because the sentence above otherwise reads as one materialisation per read model.
+ * It says nothing about materialising ONE read model more than once: several
+ * materialisations of one read model deliberately take N subscriptions, N cursors
+ * and N checkpoints, exactly because R1 and R2 forbid them to share any of the
+ * three. Wire that with `runProjections`, which holds one `slices` value and one
+ * `ProjectionId` across N materialisations so their query and their decode cannot
+ * diverge, while each keeps its own store, its own `apply`, its own checkpoint and
+ * its own supervision hooks. What it does NOT hold is the folds, so agreement
+ * between the figures two materialisations arrive at stays empirical.
+ */
+export interface ReadModel<
+  T extends Record<string, SliceProjection>,
+  E = never,
+  R = never,
+> {
+  /**
+   * The view store this read model materialises into, ALREADY BOUND to the
+   * checkpoint it advances (`forKey(store, key)`).
+   *
+   * A VALUE on the read model rather than a context tag, because the view store
+   * is selected per MATERIALISATION: one deployment can run an in-memory admin view
+   * and a durable production view against the same event log, and a slice can
+   * graduate from the first to the second with its `slices`, its composed query,
+   * its `CheckpointKey` and this runner untouched. What necessarily changes is
+   * this field and `apply` below — the two that name the view store — and nothing
+   * else.
+   *
+   * Graduation is SEQUENTIAL, memory and then Postgres, and it is not the only
+   * shape the selection permits: the same slice record can feed both AT ONCE, which
+   * is what `runProjections` wires. This field stays SINGULAR either way — one
+   * materialisation, one store, one key, one runner — and N materialisations are N
+   * of these values over one `slices` value, never one value holding a list. A list
+   * would imply one atomic `commit` across two stores, which R1 says is unsound;
+   * the demonstration of the simultaneous shape is
+   * `@kairos-es/read-postgres`'s `test/courseRosterGraduation.test.ts`, and the
+   * worked production wiring is `examples/course-subscriptions`'s
+   * `src/courseRosterMaterialisations.ts`.
+   *
+   * KEYED rather than a `(key, store)` pair, for the reason `KeyedProjectionStore`
+   * in `ProjectionStore.ts` argues — it owns why binding a key to a store turns
+   * "one materialisation, one key, one runner" from convention into structure. What
+   * is local to this field is that the key stays readable as `store.key`, which is
+   * where the runner's log annotations and failure payloads get it.
+   */
+  readonly store: KeyedProjectionStore
+
+  /** The slices whose composed query drives the subscription and whose schemas decode. */
+  readonly slices: T
+
+  /**
+   * The per-batch view writes, handed to `ProjectionStore.commit` so they land
+   * inside the same transaction as the checkpoint advance.
+   *
+   * The batch is non-empty by construction, so `apply` needs no empty case. If
+   * the store is NON-transactional this must be a SINGLE atomic effect (fold the
+   * batch purely, then one write — see `foldIntoRef`): the port cannot roll back
+   * a multi-write `apply` that fails part-way, and that requirement, not the
+   * store, is where the obligation sits.
+   */
+  readonly apply: (
+    batch: Arr.NonEmptyReadonlyArray<DecodedEvent>,
+  ) => Effect.Effect<void, E, R>
+}
+
+/**
+ * Start the daemon maintaining `readModel`, forked into the caller's `Scope`.
+ *
+ * The returned effect is INFALLIBLE (`E = never`): starting a projection cannot
+ * fail, because everything that can go wrong once it is running is the
+ * supervisor's business and lives on the fibre's error channel.
+ *
+ * ## What can go wrong BEFORE the fork is a programming error, and those are defects
+ *
+ * Which wirings are refused on the READ SIDE'S rules, why each one is a wiring
+ * nothing at runtime would ever notice, and the order they are judged in are all
+ * `projectionWiringFault`'s — one gate over five rules, whose only relation to this
+ * function is that it is the one place they can be applied before anything exists to
+ * be wrong. The gate judges a SET of materialisations, and this function supplies a
+ * SINGLETON: the two PER-ENTRY rungs judge that one wiring, the two that are
+ * functions of the shared query and slice record judge it once and would do so
+ * whatever N was, and the collision rung is a property of the set and is vacuous over
+ * one entry, having no sibling to be paired with. That is also why nothing here carries
+ * an entry index — the gate names one only where there is a set to index into.
+ * A further refusal is the CODEC's and fires just below the gate; `prepareProjection`
+ * owns that ordering for both entry points, and the gate's doc says why the rule
+ * stays in the codec. This function keeps the two claims that are its own.
+ *
+ * The verdict is a DEFECT rather than a value on the error channel, because no
+ * application can handle its own mis-wiring: the only repair is to change the
+ * wiring, and a channel value would ask every caller to write a handler for a
+ * mistake that has already been made by the time the program runs. `Effect.die`
+ * with an `Error` is the same classification the store gives a mis-built query
+ * through `assertServableQuery`, which is one of the rules.
+ *
+ * And it lands on THIS effect before the `forkScoped` at the foot of `buildAndFork`:
+ * the gate is consulted while the daemon is still being
+ * assembled, so a rejected wiring has read no checkpoint, opened no subscription
+ * and left no half-started fibre behind. That is what makes the defect safe to
+ * raise rather than merely early, and every construction case in this package
+ * asserts the stored checkpoint is still `ORIGIN` afterwards to keep it true.
+ *
+ * The preamble on the message is written HERE, once, naming the projection and the
+ * partition — the gate returns the sentence about the RULE, and this function knows
+ * WHO broke it. The single `Effect.die` that joins them is `prepareProjection`'s,
+ * which is why there is one for both entry points rather than one per rule.
+ */
+export const runProjection = <T extends Record<string, SliceProjection>, E, R>(
+  readModel: ReadModel<T, E, R>,
+  options?: ProjectionRunnerOptions,
+): Effect.Effect<
+  ProjectionRunner,
+  never,
+  | Scope.Scope
+  | DcbEventStore
+  | EventLogDurability
+  | Serializer
+  | RequirementOf<T>
+  | R
+> =>
+  Effect.gen(function* () {
+    // ## RESOLVE — every value the gate has to judge, and every figure that runs
+    //
+    // `resolveProjection` is a pure function shared with `runProjections`, so the
+    // defaults, the key and the view's durability are read in ONE place for both
+    // callers: the figure that was judged cannot differ from the figure that runs.
+    const view = readModel.store
+    const resolved = resolveProjection(view, options)
+
+    // ## PREPARE — the log's durability, the merged query, the gate, the decode
+    //
+    // The shared middle, and the same call `runProjections` makes: it reads
+    // `EventLogDurability` from context, composes the query, consults the gate and
+    // only then builds the decode stage — an order `prepareProjection` owns on behalf
+    // of both entry points, and whose reasons are on it rather than restated here.
+    //
+    // The entry list is a SINGLETON, over which the collision rung has no pair to
+    // find. Its `cursorIdentity` is what that rung compares by reference — the BOUND
+    // view here, which `runProjections` could not use and does not, since a lone
+    // entry can only ever be compared with itself and the choice is therefore free at
+    // this arity.
+    //
+    // The preamble is this function's own half of the defect message and the only
+    // half it writes: the gate returns the sentence about the RULE, and this names
+    // the projection and the partition whose wiring broke it. No entry index, because
+    // there is no set to index into.
+    const prepared = yield* prepareProjection(
+      readModel.slices,
+      [{ ...resolved, cursorIdentity: view }],
+      `runProjection: invalid wiring for projection ` +
+        `'${resolved.key.projection}' (partition ` +
+        `'${resolved.key.partition}')`,
+    )
+
+    // ## BUILD AND FORK — the pipeline, the read side's own rules now satisfied
+    return yield* buildAndFork(resolved, {
+      query: prepared.query,
+      decode: prepared.decode,
+      apply: readModel.apply,
+      options,
+    })
+  })
+
+/**
+ * `runProjection` as a `Layer` whose own scope owns the daemon.
+ *
+ * It provides NOTHING (`ROut = never`): a projection is a background process, not
+ * a service, and nothing should be able to depend on it as one — a read model is
+ * queried through its view store, never through the runner. What the `Layer` buys
+ * is lifecycle: dropped into an application's layer graph, the daemon starts when
+ * the graph is built and is interrupted when it is released, alongside the store
+ * layers it reads from, with no bespoke startup or shutdown code.
+ *
+ * Discarding the runner discards its fibre too, which is correct and has one
+ * consequence worth wiring for: under this `Layer` — the recommended shape — a
+ * `ProjectionStalled` has no fibre to be awaited on, so it reaches the outside
+ * world only through the supervisor's `Effect.logError` and through `onStalled`.
+ * That hook is the reason a stall need not be a log line somebody happens to grep
+ * for; pass one in `options` if a stalled projection should fail a health check,
+ * exit non-zero, or page.
+ *
+ * `Layer.scopedDiscard` discharges the `Scope` the fork needs; the store, its
+ * `EventLogDurability` declaration, the `Serializer`, the slices' requirements and
+ * the read model's own `R` stay on the layer's inputs, so they are satisfied the
+ * same way every other layer's are. `EventLogDurability` being an INPUT is what
+ * makes the wiring read correctly: the declaration is provided once, alongside the
+ * `DcbEventStore` layer it describes, and every projection layer in the graph is
+ * then satisfied from that one declaration.
+ */
+export const projectionLayer = <
+  T extends Record<string, SliceProjection>,
+  E,
+  R,
+>(
+  readModel: ReadModel<T, E, R>,
+  options?: ProjectionRunnerOptions,
+): Layer.Layer<
+  never,
+  never,
+  DcbEventStore | EventLogDurability | Serializer | RequirementOf<T> | R
+> => Layer.scopedDiscard(runProjection(readModel, options))