@kairos-es/read 0.0.0

package/dist/dts/runProjections.d.ts

@@ -0,0 +1,480 @@
+/**
+ * `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.js';
+import { type ProjectionRunner, type ProjectionRunnerOptions } from './ProjectionRunner.js';
+import { type PartitionId, type ProjectionId, type ProjectionStore } from './ProjectionStore.js';
+/**
+ * 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 declare 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>>;
+export {};
+//# sourceMappingURL=runProjections.d.ts.map

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

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