@kairos-es/read 0.0.0

package/dist/dts/index.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @kairos-es/read — the read side: a query-driven projection runner over the
+ * store's `subscribe` contract, and a scalar checkpoint committed atomically with
+ * the read model's own writes (ADR-0007).
+ *
+ * Platform-neutral by design: peers are `effect` plus `@kairos-es/core` and
+ * `@kairos-es/codec` only — the same peer shape as the codec — so the
+ * all-in-memory permutation, a property of one MATERIALISATION's (log, view)
+ * pairing and including client-side use, needs no database
+ * dependency. Every dependency-bearing backend is its own package, which is why
+ * the SQL `ProjectionStore` lives in `@kairos-es/read-postgres` rather than behind
+ * a sub-entry here: a sub-entry shares one dependency surface, whereas a separate
+ * package isolates a new one (`@effect/sql`).
+ *
+ * ## Where each rationale lives
+ *
+ * This module re-exports; it does not argue. Every argument the read side rests
+ * on is written ONCE, at the definition site a reader would reach for anyway,
+ * because a rationale kept in N places is a rationale a correction has to find N
+ * times. What follows is the index, R1 and R2 included: each of those two has a
+ * module that owns it, so each gets a pointer here like everything else. R3 is the
+ * one exception, and the last section says why.
+ *
+ * - **The log seam is `DcbEventStore.subscribe`, and it belongs entirely to the
+ *   event store.** `store-postgres` owns LISTEN/NOTIFY as a wake source over
+ *   `core`'s shared poll machine, `store-sqlite` owns no wake source and rides
+ *   that poll alone, and `core`'s in-memory layer owns its append `PubSub` as a
+ *   wake source over that same machine; all three sit behind the
+ *   identical `subscribe(query, after)` contract, so a projection never learns
+ *   which it is running against. Nothing in this package adds to that contract —
+ *   the one claim below that no other module is placed to make.
+ * - **The view seam is `ProjectionStore`** — one port rather than two, `commit`
+ *   taking the view writes as an ARGUMENT, `CheckpointSuperseded` as an error
+ *   rather than a returned outcome, and `ProjectionStoreError` inverting the store
+ *   contract's defect rule. `ProjectionStore.ts`'s module doc. The multi-key port
+ *   against the keyed façade a read model is handed is on `KeyedProjectionStore`
+ *   and on `forKey` in the same module; the single-atomic-effect requirement a
+ *   NON-TRANSACTIONAL store's caller must honour is on the `ProjectionStore`
+ *   interface itself, and `foldIntoRef.ts` is that shape.
+ * - **R1, atomicity** — a read model's checkpoint lives WITH its view, in a store
+ *   where the two can be committed atomically, which is what `commit` is. The
+ *   argument is on the `ProjectionStore` interface in `ProjectionStore.ts` (R1 is
+ *   what that interface IS), together with what a view offering no transaction at
+ *   all falls back to: at-least-once, with POSITION-KEYED idempotent writes, a
+ *   recommendation because the port cannot check it.
+ * - **R2, durability ordering** — checkpoint durability must not EXCEED event-log
+ *   durability, so a DURABLE view over an EPHEMERAL log is a defect rejected at
+ *   construction rather than a view that silently freezes. The view store declares
+ *   its half on the `ProjectionStore` it implements; the log's half, the silent
+ *   failure the rule prevents, and why the log's class is ONE context tag beside
+ *   the store layer rather than a field per read model are all in
+ *   `EventLogDurability.ts`.
+ * - **How these errors RENDER themselves** — why `ProjectionStoreError` derives its
+ *   `message` from `reason` and `CheckpointSuperseded` derives one from `expected`
+ *   (including the `bigint` argument that once kept the field empty and why it was a
+ *   category error), how far filling that field reaches (every reader of the error,
+ *   not one log line) and what it leaves untouched: the two classes in
+ *   `ProjectionStore.ts`. `PipelineDied` in `ProjectionRunner.ts` and
+ *   `ProjectionStalled` in `superviseOnProgress.ts` are the other two and point
+ *   there.
+ * - **Why the view store is a VALUE and not a `Context.Tag`**, and what a slice's
+ *   graduation from memory to Postgres does and does not change: `ReadModel.store`
+ *   in `runProjection.ts`. It is demonstrated rather than asserted, by
+ *   `examples/course-subscriptions`'s `src/courseRosterSql.ts` and by
+ *   `@kairos-es/read-postgres`'s `test/courseRosterGraduation.test.ts`.
+ * - **The in-memory implementation, and why it is not merely a test double:**
+ *   `inMemoryProjectionStore.ts`.
+ * - **The runner** — the pipeline stage by stage, and why supervision lives next
+ *   door: `ProjectionRunner.ts`, which holds the SUBSTRATE both entry points sit on
+ *   and no entry point of its own. Its two option sets are documented on
+ *   `ProjectionPipelineOptions` there and on `ProjectionSupervisionOptions` in
+ *   `superviseOnProgress.ts`; `ProjectionRunnerOptions` says why their union is
+ *   FLAT and why every figure is bounded rather than merely documented.
+ * - **ONE materialisation of one read model** — `runProjection` and the
+ *   `projectionLayer` over it: `runProjection.ts`, which also says why the singular
+ *   and the plural entry points are two modules over one substrate and why neither
+ *   calls the other.
+ * - **N MATERIALISATIONS of one read model** — one slice record and one
+ *   `ProjectionId` for the call, one view store and one runner each, which is what
+ *   `runProjections` is: `runProjections.ts`. It carries the guarantee at exactly
+ *   its strength (one query, one decode, N applies — never "they cannot drift",
+ *   since a SQL `apply` re-implements the fold and agreement between materialised
+ *   figures is empirical), why the guarantee is construction-scoped, why each entry
+ *   hands over an UNBOUND `ProjectionStore` while the identity is named once for the
+ *   call, why the tuning and the two supervision hooks are PER ENTRY, and why there
+ *   is no `projectionsLayer`. The wiring that is its OWN — two materialisations
+ *   sharing one store under one resolved `CheckpointKey` — is the set-level rung of
+ *   the construction gate below, with the two bounds it deliberately does not reach;
+ *   the gate's other four run in the same pass — two per entry, two once over the
+ *   shared query and slice record — so no refused call forks anything, whichever
+ *   rung and whichever entry it was.
+ * - **The supervisor** — retry while an externally observed signal moves, give up
+ *   when it stops; why a `CheckpointSuperseded` loser resynchronises instead of
+ *   tripping the breaker; why the two hooks are the primary observability channel
+ *   and the log lines a thin lossy default; why it holds no rendering of a
+ *   caller's `E` at all, the label being the fault's own `message`; and the
+ *   wall-clock arithmetic behind the no-progress budget: `superviseOnProgress.ts`.
+ *   `superviseOnProgress` ITSELF is package-internal and deliberately not exported
+ *   below — it is the projection runner's supervisor, not a general combinator, and
+ *   that module records both why and what generalising it would cost. Three
+ *   symbols from it are exported, each because the PUBLIC surface names it:
+ *   `ProjectionStalled` is `ProjectionRunner.fibre`'s error channel,
+ *   `ProjectionRunnerOptions` extends `ProjectionSupervisionOptions`, and tuning
+ *   the no-progress budget means calling `MaxNoProgressRestarts.make(n)`.
+ * - **One writer per MATERIALISATION, and why one read model's stream is never
+ *   sharded:** ADR-0007, with the partition dimension's own half on `PartitionId`.
+ *   Per materialisation rather than per read model, because a read model may have
+ *   several — N of them are N single writers, never shards of one stream.
+ *   Where apply THROUGHPUT rather than isolation is the constraint, ADR-0007 also
+ *   carries the escape hatch — coalesce a batch per target row inside the one
+ *   commit — and there is no library symbol for it, because it is a fold the read
+ *   model performs over its own batch.
+ * - **The tagless-slice rule** — every read-model slice carries at least one tag
+ *   (a `system:…` tag for a genuinely global slice), enforced at construction by
+ *   two checks that cannot stand in for each other, since a lone tagless slice
+ *   composes to a query the store WOULD serve: both are rungs of the wiring gate
+ *   `projectionWiringFault.ts`, which argues the rules and the order they are judged
+ *   in, and which is consulted from the one `prepareProjection` phase both runner
+ *   entry points run before either forks anything.
+ * - **Running a read model in a test** — the `@kairos-es/read/testing` subpath
+ *   (`testing.ts`), which also states its boundary against
+ *   `@kairos-es/projection-store-contract-tests`.
+ * - **The narrative version of all of it** is this package's `README.md`; the
+ *   decision it implements is ADR-0007.
+ *
+ * ## R3, the legal permutations, and several materialisations of one read model
+ *
+ * The one thing this file ARGUES rather than indexes. R1 and R2 each have a module
+ * that owns them, pointed at above; R3 has none, because it is a property of how
+ * read models are composed into a SUBSCRIPTION and no single module holds that.
+ *
+ * **R3, composition bound.** Read models sharing one subscription share one cursor
+ * and one checkpoint, hence by R1 one view store and one durability class. So
+ * per-read-model view selection means one runner per view-store GROUP, not one per
+ * read model — and rebuilding one member of a composed bundle means rebuilding the
+ * bundle (or running a transient dedicated runner from `ORIGIN`). Composing is
+ * still the default, because the NOTIFY channel is per store, not per query.
+ *
+ * **What R3 does NOT say.** It does not bound how many times ONE read model may be
+ * materialised. R3 is about sharing a SUBSCRIPTION, and several materialisations of
+ * one read model deliberately do not share one: they pay N subscriptions, N cursors
+ * and N checkpoints precisely BECAUSE R1 and R2 forbid the sharing — one atomic
+ * `commit` cannot span two stores, and one checkpoint cannot carry two durability
+ * classes. So per-read-model view-store selection is a FLOOR rather than a ceiling.
+ * One slice record may feed a durable Postgres materialisation and an ephemeral
+ * in-memory one AT ONCE, wired by `runProjections`, which holds one `slices` value
+ * and one `ProjectionId` across them so their query and their decode cannot diverge.
+ * What it does not hold is the FOLDS — each `apply` re-expresses the fold against
+ * its own store, and a SQL one writing rows is not `foldIntoRef` — so agreement
+ * between two materialised figures is EMPIRICAL, something a test demonstrates, and
+ * never something the wiring gives you. The runners do not contend either: each
+ * owns its own checkpoint in its own store, so the guarded compare-and-set
+ * arbitrates with no lease, no lock and no coordinator.
+ *
+ * That leaves exactly THREE legal (log, view) permutations: all-in-memory (tests,
+ * prototypes, client-side); a durable log with an in-memory view (dev, low-traffic
+ * and admin views, in-flux slices — rebuilt from `ORIGIN` each boot, which is
+ * affordable at the event counts that are its remit and a reason to graduate a
+ * slice once it bakes); and a durable log with a durable view, the production
+ * default. Each is a property of ONE MATERIALISATION's pairing. Mixing is a
+ * DEPLOYMENT property rather than a fourth permutation: one deployment can run the
+ * second and third side by side against the same log — for two different read
+ * models, which is the case R3 bounds when they try to share a subscription, or for
+ * two materialisations of ONE read model, which R3 never reaches because they never
+ * share one.
+ *
+ * **A third KIND of materialisation sits outside all of this.** A read-time
+ * materialisation — `modelAtHead`, in `@kairos-es/codec` — folds the log per query
+ * and has no table, no checkpoint, no runner and no view store, so no permutation,
+ * no rung of the construction gate and no durability rule applies to it, R2 being
+ * VACUOUS where there is no checkpoint whose durability could outlive a log. It is
+ * consistent as of the `head` its read returned, which trails nothing, so it is the
+ * MOST current view of a slice record and the maintained table beside it is the
+ * stale one. Where a read model is small enough to fold at query time, that is a
+ * reason not to maintain it at all.
+ */
+export { DurableEventLog, EphemeralEventLog, EventLogDurability, } from './EventLogDurability.js';
+export { foldIntoRef } from './foldIntoRef.js';
+export { makeInMemoryProjectionStore } from './inMemoryProjectionStore.js';
+export { BatchSize, PipelineDied, type ProjectionPipelineOptions, type ProjectionRunner, type ProjectionRunnerOptions, } from './ProjectionRunner.js';
+export { type CheckpointKey, CheckpointSuperseded, checkpointKey, DEFAULT_PARTITION, type Durability, forKey, type KeyedProjectionStore, PartitionId, ProjectionId, type ProjectionStore, ProjectionStoreError, } from './ProjectionStore.js';
+export { projectionLayer, type ReadModel, runProjection, } from './runProjection.js';
+export { type Materialisation, type MaterialisedProjection, runProjections, } from './runProjections.js';
+export { MaxNoProgressRestarts, ProjectionStalled, type ProjectionSupervisionOptions, } from './superviseOnProgress.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+KG;AACH,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAA;AACvE,OAAO,EACL,SAAS,EACT,YAAY,EACZ,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,KAAK,aAAa,EAClB,oBAAoB,EACpB,aAAa,EACb,iBAAiB,EACjB,KAAK,UAAU,EACf,MAAM,EACN,KAAK,oBAAoB,EACzB,WAAW,EACX,YAAY,EACZ,KAAK,eAAe,EACpB,oBAAoB,GACrB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,aAAa,GACd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,cAAc,GACf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,4BAA4B,GAClC,MAAM,uBAAuB,CAAA"}

package/dist/dts/projectionWiringFault.d.ts

@@ -0,0 +1,260 @@
+/**
+ * The read side's CONSTRUCTION GATE: every wiring the read side refuses ON ITS OWN
+ * RULES, judged in one place, in one declared order, each verdict one
+ * `string | undefined`.
+ *
+ * ## ONE entry point over five rules, at three arities
+ *
+ * `projectionWiringFault` judges ONE CALL: the log the whole graph subscribes to,
+ * the one composed query and the one slice record every materialisation shares, and
+ * a LIST of the resolved per-entry wirings. `runProjection` hands it a singleton and
+ * `runProjections` hands it N, and both do so before either forks anything.
+ *
+ * The rules divide by what they are a function of, not by who called:
+ *
+ * - the COLLISION rung is a function of the whole list, pairwise;
+ * - R2 and the tuning figures are functions of ONE entry, judged for every entry in
+ *   turn;
+ * - the servable grammar and the per-slice tag rule are functions of the SHARED
+ *   query and the SHARED slice record, so they are judged once for the call.
+ *
+ * One record with the shared fields stated once and the entries as a list is what
+ * lets all three arities compose in one `??` chain. What the gate is stays what it
+ * was: one home, one return type, one declared order (below), and a caller that
+ * classifies the verdict under a preamble it was handed.
+ *
+ * ## The ONE refusal that is deliberately not here
+ *
+ * Naming it is what keeps "one place" honest. A slice record holding two DISTINCT
+ * `Schema`s under one event type is refused by `@kairos-es/codec`'s
+ * `decodeSlices`, which `prepareProjection` calls a few lines BELOW this gate on
+ * behalf of both entry points — so a rejected record still dies as a defect with
+ * nothing forked, exactly as a rejected wiring does, but the sentence a reader
+ * meets is the codec's. That rule
+ * belongs to the codec because BOTH of its consumers need it and only one is on
+ * the read side: the write path reaches the same merge through
+ * `buildDecisionModel` and never comes near this module, so a rung here
+ * would be a second home for one rule, covering half the hazard. `decode.ts` owns
+ * the argument; this is a pointer, not a restatement.
+ *
+ * Which of the two a record wrong in BOTH ways meets FIRST is not this module's to
+ * state either, and it has exactly one home: `prepareProjection` in
+ * `ProjectionRunner.ts`, the single body in which the gate call sits above the
+ * `decodeSlices` call, for both entry points at once. It was a claim two function
+ * bodies each made in prose until that phase was extracted, and pinned for only one
+ * of them.
+ *
+ * ## Why this is a module and not a paragraph of `runProjection`
+ *
+ * `runProjection` was doing two unrelated jobs. One is to refuse a wiring that can
+ * only ever be wrong — five rules, none of which mentions a stream, a scope or a
+ * fibre, and only one of which so much as compares two stores for identity. The
+ * other is to build and fork a pipeline. The refusals had
+ * grown to roughly two fifths of that function's body and most of its doc, and
+ * three of them wrote their own `Effect.die` with their own copy of the preamble
+ * naming the projection.
+ *
+ * The precedent is this package's own: `superviseOnProgress` was a deep module
+ * trapped inside the same function, and pulling it out is what made a supervision
+ * quantity pinnable against a stub instead of through the whole pipeline. This is
+ * the other half of that function, and it is deeper still by the measure that
+ * matters here — its interface is a record in and a sentence out, while everything
+ * behind it is five unrelated rules over four vocabularies (a layer graph, a
+ * tuning literal, a query grammar, a set of view stores).
+ *
+ * The fifth rule arriving from a DIFFERENT caller is what the module having been
+ * extracted bought. `runProjections` needed a construction-time refusal of its own,
+ * and there was already a place for it — with a settled return type, a settled
+ * division of labour with its caller, and a suite that states a rule against a
+ * record literal. Inline, it would have been a sixth thing inside a second pipeline
+ * function, in a second style, with a second preamble. It landed as a RUNG of the
+ * one chain rather than as a second entry point, which is what keeps the declared
+ * order below a property of this file rather than of which caller a reader opened.
+ *
+ * ## Why `string | undefined`, and why the shared record takes no `CheckpointKey`
+ *
+ * `undefined` for a sound wiring, otherwise the SPECIFIC sentence: what is wrong,
+ * what it would do, and how to fix it. It does not throw, does not call `Effect.die`
+ * and does not return an `Either` — ONE exit route and one return type, which is
+ * what lets five rules over four vocabularies compose with `??` and be read as five
+ * lines.
+ *
+ * The shared half of the record names no projection and no partition. The per-entry
+ * list does carry a resolved `CheckpointKey` each, but for the collision rung to
+ * COMPARE rather than for anything to report: no rule interpolates a `key` into its
+ * sentence except the collision rung, which names the partition the two offenders
+ * share.
+ *
+ * ATTRIBUTION and CLASSIFICATION both sit outside. This gate's ONE caller,
+ * `prepareProjection`, owns the single `Effect.die`; the PREAMBLE naming the
+ * projection (and, where there is one to name, the partition) comes from one level
+ * further out still, from whichever entry point was called. So the preamble is
+ * written once per ENTRY POINT rather than once per rule — which is exactly what
+ * collapsed three `Effect.die` sites to one. The gate
+ * writes the third party to that sentence: where there is more than one entry, the
+ * per-entry rungs prefix their verdict with the offending INDEX, in the same
+ * `materialisations[i]` vocabulary the collision rung already uses. Over a singleton
+ * there is no index to name and none is written, so a single wiring's message is
+ * what it always was. The same arrangement repeats one level DOWN, inside this file:
+ * `positiveFiniteDuration` owns the `Duration` bound and each of the four tuning
+ * call sites supplies the `role` clause, because the predicate knows the rule and
+ * its caller knows what breaks.
+ *
+ * The classification half of that is worth spelling out. That a mis-wiring is a
+ * DEFECT rather
+ * than a channel value is a claim about `runProjection`'s and `runProjections`'
+ * signatures — both error channels are `never` because everything that can go wrong
+ * once a projection is RUNNING belongs to the supervisor — and a gate returning a
+ * string makes no such claim, so it can be called from a plain function, a test, or
+ * an `Effect.gen` without three different failure conventions.
+ *
+ * ## The ORDER is a decision, and this is the only place it is stated
+ *
+ * The rules run OUTWARD-IN, from the widest wiring decision to the narrowest.
+ *
+ * The order is over RULES and not over ENTRIES. Entry 1's layer-graph mistake is
+ * still wider than entry 0's options-literal mistake, so rung 2 is judged for every
+ * entry before rung 3 is judged for any. An entry-major loop would instead let ARRAY
+ * POSITION decide which fault an author sees, and position carries no meaning here:
+ * the entries are a set, and are a tuple only because inference needs one.
+ *
+ * 1. **The collision rung**, once over the whole SET. Two materialisations sharing
+ *    one store under one key is a property of the WHOLE CALL rather than of any one
+ *    wiring in it, so it is judged before any single wiring is looked at — the same
+ *    outward-in principle, one level up. And a colliding pair is worth hearing about
+ *    BEFORE a mis-tuned figure in one of them, because fixing the tuning would leave
+ *    the two runners racing one cursor. It cannot fire below N = 2, so it is vacuous
+ *    for the singleton `runProjection` passes.
+ * 2. **R2, durability ordering**, PER ENTRY in entry order. A property of the LAYER
+ *    GRAPH — which log, which view store — decided before any read model existed. If
+ *    that pairing is illegal then nothing else about the runner matters, because the
+ *    view it maintains cannot be true however well tuned the daemon is.
+ * 3. **The tuning figures**, PER ENTRY in entry order. What the caller wrote in the
+ *    options literal, a smaller and more local mistake than picking the wrong pair
+ *    of layers.
+ * 4. **The store's own servable grammar**, once over the SHARED composed query,
+ *    reported in the STORE's vocabulary by `core`'s own `assertServableQuery`.
+ * 5. **The read side's stricter per-slice tag rule**, once over the SHARED slice
+ *    record, and it MUST stay after (4): it catches only what that grammar admits,
+ *    since a lone type-only item is servable. Were it first, a tagless-plus-tagged
+ *    union — a violation of the shared grammar — would be reported as a read-side
+ *    slice convention instead of in the vocabulary every other caller of that
+ *    grammar meets it in.
+ *
+ * Hoisting the two SHARED rungs ahead of the two per-entry ones, which the
+ * shared-versus-per-entry axis would suggest, was considered and rejected: it
+ * changes the message a single wiring wrong in two ways gets, which is a fixed
+ * constraint. (2)-(3) ahead of (4)-(5) also restores the relative order that held
+ * before the supervisor was extracted, when its three restart durations were checked
+ * with `batchWindow` rather than a module away. But the point of writing the order
+ * down is not the restoration: it is that the order is now FIVE LINES a reader can
+ * read, rather than an emergent property of which of two modules happens to look at
+ * a field first.
+ *
+ * ## Why the input is a record of ALREADY-RESOLVED values
+ *
+ * Every field is a value, not an option: the caller has already applied its
+ * defaults — through `resolveProjection`, the one resolution site both callers
+ * share — so the gate judges exactly the figures that will run and cannot be handed
+ * one default while the pipeline uses another. That also holds the defaults
+ * themselves to the rules they document, for one decode per runner. The keys are
+ * RESOLVED `CheckpointKey`s for the same reason and one more: a partition a caller
+ * omitted is `DEFAULT_PARTITION`, so a rung judging the raw options would miss the
+ * commonest form of the collision, which is two entries that name no partition at
+ * all.
+ *
+ * The two INTEGER options are absent from the record on purpose. `BatchSize` and
+ * `MaxNoProgressRestarts` are branded, so their boundary is the caller's own
+ * `.make(...)` — a bad value is refused a stack frame away from where it was
+ * written and never reaches here at all.
+ *
+ * `slices` is a SHARED field and is typed as narrowly as the check needs — a query
+ * per slice, nothing else — which keeps this module free of a `@kairos-es/codec`
+ * import for a rule that has no opinion about schemas, payloads or folds.
+ * `Record<string, SliceProjection>` satisfies it structurally, so the record an entry
+ * point was handed reaches this rung unconverted.
+ *
+ * An entry's `cursorIdentity` is typed `object` and never called: it is an identity
+ * token the collision rung compares by REFERENCE. `object` rather than `ProjectionStore`
+ * because a `KeyedProjectionStore` is not structurally one (`readCheckpoint` is an
+ * `Effect` on the façade and a function on the port), so a caller holding only a
+ * bound view could not fill the field; and because `object` forbids `undefined`,
+ * which would otherwise make two unidentified entries compare equal.
+ *
+ * It is INTERNAL: nothing here is re-exported from the package index. The gate is
+ * how the two runner entry points refuse a wiring, not a capability the library
+ * offers — a caller with a wiring to validate has `runProjection` or
+ * `runProjections` itself. BOTH judge all five rules before either forks anything.
+ */
+import { type Query } from '@kairos-es/core';
+import { Duration } from 'effect';
+import type { CheckpointKey, Durability } from './ProjectionStore.js';
+/**
+ * ONE materialisation as the gate sees it: an identity token, its resolved key, its
+ * half of R2 and the four `Duration`s that tune it.
+ *
+ * `ResolvedProjection` in `ProjectionRunner.ts` satisfies all of it but
+ * `cursorIdentity`, which is why both entry points can build an entry by spreading a
+ * resolved wiring beside the identity they hold.
+ *
+ * Exported to the PACKAGE and no further, which is one more symbol than the gate
+ * used to offer and still nothing a consumer can reach: `prepareProjection` — the
+ * phase that calls this gate on behalf of both entry points — names the entry LIST
+ * in its own signature, and a structural re-declaration there would be a second
+ * statement of what the gate judges, free to drift from this one.
+ *
+ * The field is NOT called `store`, and that is the point rather than taste. The two
+ * entry points put DIFFERENT objects in it — `runProjections` the UNBOUND port, which is
+ * the last surface at which sameness is askable since `forKey` deliberately does not
+ * expose what it closed over; `runProjection` the BOUND view it was handed, where a
+ * singleton makes the rung vacuous anyway — and each is right for its own arity.
+ * Under the name `store` those two meanings sat behind one word in a record built by
+ * SPREADING a `Materialisation`, whose own `store` field means only the first of
+ * them. Nothing would have complained if a future field on either side shadowed the
+ * other, the type being `object`. What the rung needs is not "a store" but "the value
+ * whose IDENTITY separates one cursor from another", which is what this name says.
+ *
+ * Typed `object` because the rung COMPARES it and never calls it (a
+ * `KeyedProjectionStore` is not structurally a `ProjectionStore`), and because
+ * `object` also refuses `undefined` — which would otherwise make two unidentified
+ * entries compare equal and manufacture a collision out of nothing.
+ *
+ * `batchSize` is deliberately absent along with `maxNoProgressRestarts`: both are
+ * branded, so both were bounded at the caller's own `.make(...)`.
+ */
+export type MaterialisationWiring = {
+    readonly cursorIdentity: object;
+    readonly key: CheckpointKey;
+    readonly viewDurability: Durability;
+    readonly batchWindow: Duration.DurationInput;
+    readonly restartMinDelay: Duration.DurationInput;
+    readonly restartMaxDelay: Duration.DurationInput;
+    readonly restartResetAfter: Duration.DurationInput;
+};
+/**
+ * Judge ONE CALL's whole wiring: `undefined` when it is sound, otherwise the
+ * sentence describing the FIRST rule it breaks.
+ *
+ * Five rules, `??`-chained in the outward-in order the module doc argues for and
+ * fixes. `??` rather than an array of predicates or a collected list of every
+ * violation, for two reasons: the first fault is the one to fix — the later rules
+ * judge a wiring whose wider decisions are already known to be wrong, so their
+ * verdicts would be noise — and a chain of five named calls is the whole
+ * implementation, which is what makes the declared order checkable against the code
+ * rather than merely asserted about it.
+ *
+ * The two PER-ENTRY rungs go through `perEntry`, which is what keeps the chain
+ * rule-major: every entry is judged by rung 2 before any entry is judged by rung 3.
+ *
+ * Every field is a RESOLVED value: see the module doc for why (and for why the two
+ * integer options are not here at all).
+ */
+export declare const projectionWiringFault: (wiring: {
+    readonly eventLogDurability: Durability;
+    readonly query: Query;
+    readonly slices: Record<string, {
+        readonly query: Query;
+    }>;
+    readonly materialisations: ReadonlyArray<MaterialisationWiring>;
+}) => string | undefined;
+//# sourceMappingURL=projectionWiringFault.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projectionWiringFault.d.ts","sourceRoot":"","sources":["../../src/projectionWiringFault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2LG;AACH,OAAO,EAAuB,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,EAAE,QAAQ,EAAkB,MAAM,QAAQ,CAAA;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAyRlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;IAC3B,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAA;IACnC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,aAAa,CAAA;IAC5C,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,aAAa,CAAA;IAChD,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,aAAa,CAAA;IAChD,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,aAAa,CAAA;CACnD,CAAA;AAgCD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,GAAI,QAAQ;IAC5C,QAAQ,CAAC,kBAAkB,EAAE,UAAU,CAAA;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IAC1D,QAAQ,CAAC,gBAAgB,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAA;CAChE,KAAG,MAAM,GAAG,SAUc,CAAA"}

package/dist/dts/runProjection.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"runProjection.d.ts","sourceRoot":"","sources":["../../src/runProjection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,eAAe,EAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAClE,OAAO,EAAE,KAAK,KAAK,IAAI,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,QAAQ,CAAA;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAG7B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,SAAS,CACxB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,CAAC,GAAG,KAAK,EACT,CAAC,GAAG,KAAK;IAET;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;IAEpC,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;IAElB;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,KAAK,EAAE,GAAG,CAAC,qBAAqB,CAAC,YAAY,CAAC,KAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC,EAC3E,WAAW,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7B,UAAU,uBAAuB,KAChC,MAAM,CAAC,MAAM,CACd,gBAAgB,EAChB,KAAK,EACH,KAAK,CAAC,KAAK,GACX,aAAa,GACb,kBAAkB,GAClB,UAAU,GACV,aAAa,CAAC,CAAC,CAAC,GAChB,CAAC,CA2CD,CAAA;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,eAAe,GAC1B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,CAAC,EACD,CAAC,EAED,WAAW,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAC7B,UAAU,uBAAuB,KAChC,KAAK,CAAC,KAAK,CACZ,KAAK,EACL,KAAK,EACL,aAAa,GAAG,kBAAkB,GAAG,UAAU,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CACb,CAAA"}