@kairos-es/read 0.0.0

package/dist/dts/ProjectionRunner.d.ts

@@ -0,0 +1,557 @@
+/**
+ * `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 { DcbEventStore, type DecodedEvent, type Query, type SequencedEvent } from '@kairos-es/core';
+import { Array as Arr, type Duration, Effect, type Fiber, Schema, type Scope, Stream } from 'effect';
+import { EventLogDurability } from './EventLogDurability.js';
+import type { CheckpointKey, Durability, KeyedProjectionStore } from './ProjectionStore.js';
+import { type MaterialisationWiring } from './projectionWiringFault.js';
+import { type ProjectionStalled, type ProjectionSupervisionOptions, type ResolvedSupervisionTuning } from './superviseOnProgress.js';
+/**
+ * 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 declare const BatchSize: Schema.brand<Schema.filter<typeof Schema.Int>, "BatchSize">;
+export type BatchSize = typeof BatchSize.Type;
+/**
+ * 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 declare const resolveProjection: (view: KeyedProjectionStore, options?: ProjectionRunnerOptions) => ResolvedProjection;
+declare const PipelineDied_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PipelineDied";
+} & Readonly<A>;
+/**
+ * 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 declare class PipelineDied extends PipelineDied_base<{
+    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`.
+     */
+    get message(): string;
+}
+/**
+ * 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 declare const prepareProjection: <T extends Record<string, SliceProjection>>(slices: T, materialisations: ReadonlyArray<MaterialisationWiring>, preamble: string) => Effect.Effect<PreparedProjection<T>, never, EventLogDurability>;
+/**
+ * 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 declare 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>;
+export {};
+//# sourceMappingURL=ProjectionRunner.d.ts.map

package/dist/dts/ProjectionRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectionRunner.d.ts","sourceRoot":"","sources":["../../src/ProjectionRunner.ts"],"names":[],"mappings":"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"}