@kairos-es/read 0.0.0

package/src/projectionWiringFault.ts

@@ -0,0 +1,694 @@
+/**
+ * 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 { assertServableQuery, type Query } from '@kairos-es/core'
+import { Duration, Either, Option } from 'effect'
+import { durabilityOrderingFault } from './EventLogDurability'
+import type { CheckpointKey, Durability } from './ProjectionStore'
+
+/**
+ * One `Duration.DurationInput` option, decoded and bounded: the `Duration` if it
+ * is positive and finite, otherwise the sentence explaining what it is and what
+ * that would do.
+ *
+ * FILE-PRIVATE, and applied four times, all of them by `tuningFault` below. It owns
+ * the BOUND and the shape of the sentence; each call site owns `role`, the clause
+ * saying what THIS option does and therefore what breaks at each degenerate end,
+ * because a generic "must be positive and finite" tells an author the rule but not
+ * the consequence, and the consequence is what makes the fix obvious. So the four
+ * call sites differ by exactly the thing that differs between them, and one bound is
+ * not stated four ways — the module doc's division, nested one level down.
+ *
+ * Three things about the checks are worth knowing rather than rediscovering:
+ *
+ * - **`Duration.decodeUnknown`, not `Duration.decode`.** The latter THROWS
+ *   `Error('Invalid DurationInput')` on an unparseable string, which inside
+ *   `Effect.gen` would already become a defect — but one whose message names
+ *   neither the option nor the value. The `Option`-returning form (`decodeUnknown`
+ *   is `Option.liftThrowable(decode)`) lets the fault carry both.
+ * - **`Duration.isZero` covers NEGATIVES too.** Every `Duration` constructor routes
+ *   through one internal `make` that maps a non-positive `number` or `bigint` to the
+ *   zero value, and the `[seconds, nanos]` form maps a `-Infinity` component to zero
+ *   outright (verified against `effect@3.22`'s `Duration.ts`), so `-5`,
+ *   `'-5 millis'` and `0` are indistinguishable by the time they are a `Duration`.
+ *   There is therefore no separate "negative" case to test for — and the zero
+ *   message has to SAY that, because a reader told "restartMinDelay is zero" while
+ *   looking at `'-5 millis'` in their own wiring would otherwise conclude the check
+ *   was reading the wrong field.
+ * - **Infinity is rejected everywhere, including `restartResetAfter`.** An infinite
+ *   figure in any of these positions stops a TIMING mechanism from being one, and
+ *   every claim the runner's docs make — a latency ceiling, a bounded backoff, a
+ *   five-minute budget — stops being true. "Effectively never" remains expressible
+ *   as a large finite figure, so a uniform rule costs a caller nothing and is one
+ *   predicate rather than four. It needs its own check: `Duration.isZero` answers
+ *   `false` for the infinite `Duration`, so the two bounds are independent.
+ *
+ * `String(input)`, never `JSON.stringify`, for the same reason `superviseOnProgress`
+ * reduces its log annotations with `String`: `DurationInput` admits a `bigint` of
+ * nanoseconds, and `JSON.stringify` THROWS on one — inside the very code path whose
+ * job is to explain a mistake clearly.
+ */
+const positiveFiniteDuration = (
+  name: string,
+  input: Duration.DurationInput,
+  role: string,
+): Either.Either<Duration.Duration, string> => {
+  const decoded = Duration.decodeUnknown(input)
+  if (Option.isNone(decoded)) {
+    return Either.left(
+      `${name} is not a Duration.DurationInput (got ${String(input)}). Pass a ` +
+        "string like '50 millis', a Duration, a number of milliseconds, a " +
+        'bigint of nanoseconds, or a [seconds, nanos] tuple.',
+    )
+  }
+  if (!Duration.isFinite(decoded.value)) {
+    return Either.left(`${name} is infinite (got ${String(input)}). ${role}`)
+  }
+  if (Duration.isZero(decoded.value)) {
+    return Either.left(
+      `${name} is zero (got ${String(input)}; Duration clamps any negative ` +
+        `input to zero, so a negative arrives here as zero too). ${role}`,
+    )
+  }
+  return Either.right(decoded.value)
+}
+
+/**
+ * The runner's four `Duration`s, decoded and bounded: `undefined` when the tuning
+ * is sound, otherwise the sentence naming the FIRST violation.
+ *
+ * ## WHY these are checked at all when both integer options are branded
+ *
+ * `Duration.DurationInput` is a UNION — a `Duration`, millis as a `number`, nanos
+ * as a `bigint`, a `[seconds, nanos]` tuple, or a `'50 millis'` string — so there
+ * is no single primitive for `Schema.Int`-plus-`Schema.brand` to refine, and
+ * validity is only knowable after `Duration.decode` runs. Branding one anyway would
+ * mean one of two losses: a constructor every call site must thread a raw input
+ * through, or a field narrowed to `Duration` alone, which makes
+ * `batchWindow: '50 millis'` — the ergonomic point of `DurationInput`, and what
+ * every test and example in this repo writes — unwritable. So the check happens at
+ * CONSTRUCTION instead, where the caller turns it into a defect. Same discipline as
+ * `BatchSize` and `MaxNoProgressRestarts` (fail at the boundary, report where the
+ * author can act), different mechanism, because the type is a different shape.
+ *
+ * ## Why all four together, when they tune two different machines
+ *
+ * `batchWindow` paces the PIPELINE and the three restart figures pace the
+ * SUPERVISOR, and those two modules deliberately know nothing of each other. But
+ * the mistake is one mistake — a degenerate figure whose failure mode is a hot loop
+ * or a permanently frozen view with nothing on any error channel — and an author
+ * who wrote `restartMinDelay: 0` beside `batchWindow: 0` should not have to fix one
+ * and re-run to be told about the other by a differently-worded message from a
+ * different module. `Either.all` short-circuits on the first violation, so one
+ * degenerate figure is one sentence naming one option; what the single home buys is
+ * that the sentence is built the same way whichever field it is about.
+ *
+ * ## The one CROSS-FIELD rule, and the one deliberately absent
+ *
+ * `restartMinDelay <= restartMaxDelay` is checked, in the spirit of
+ * `ReadPostgresConfig`'s own cross-field filter: the names assert an ordering, and
+ * inverting it is silently absorbed rather than rejected. `Schedule.union` takes the
+ * SHORTER of its two arms, so a min above the max deletes the exponential
+ * entirely — every restart sleeps exactly `restartMaxDelay`, the documented sawtooth
+ * never happens, and the no-progress budget is off by however far apart the two
+ * figures are. Equality is allowed: min == max is a deliberate flat pacing, not a
+ * contradiction.
+ *
+ * `restartResetAfter` is deliberately NOT cross-checked against the delays,
+ * although a reset threshold below `restartMinDelay` does flatten the backoff (the
+ * schedule resets before it can grow). The difference is that no ordering is implied
+ * there — the two figures measure different things, elapsed retrying time against
+ * one sleep — so a short reset is a tuning choice expressible another way
+ * (min == max), whereas min above max is a statement that contradicts itself.
+ * Rejecting the former would be inventing a policy rather than enforcing a rule.
+ *
+ * The words `invalid tuning` are this sentence's own, not the caller's preamble's:
+ * the preamble says which projection is mis-WIRED, and this says the wiring fault is
+ * a mis-set figure rather than a bad pair of layers or a mis-built slice. They are a
+ * CONSTANT rather than a literal at each of the two return sites below, so the phrase
+ * an operator greps for is written once even though the rule is one function.
+ */
+const MIS_TUNED = 'invalid tuning —'
+
+const tuningFault = (tuning: {
+  readonly batchWindow: Duration.DurationInput
+  readonly restartMinDelay: Duration.DurationInput
+  readonly restartMaxDelay: Duration.DurationInput
+  readonly restartResetAfter: Duration.DurationInput
+}): string | undefined => {
+  const checked = Either.all({
+    batchWindow: positiveFiniteDuration(
+      'batchWindow',
+      tuning.batchWindow,
+      'batchWindow is how long a PARTIAL batch waits before committing anyway: ' +
+        'at zero Stream.groupedWithin spins, emitting empty chunks without ever ' +
+        'pulling the subscription; infinite means a partial batch never flushes, ' +
+        'so a lone live event waits for batchSize-1 more events that may never ' +
+        'come.',
+    ),
+    restartMinDelay: positiveFiniteDuration(
+      'restartMinDelay',
+      tuning.restartMinDelay,
+      'restartMinDelay is the BASE Schedule.exponential multiplies: at zero ' +
+        'every delay in the series is zero and the supervisor restarts in a hot ' +
+        'loop; infinite means the first restart never arrives.',
+    ),
+    restartMaxDelay: positiveFiniteDuration(
+      'restartMaxDelay',
+      tuning.restartMaxDelay,
+      'restartMaxDelay is the backoff CEILING, unioned with the exponential: ' +
+        'Schedule.union takes the shorter arm, so at zero it caps every sleep to ' +
+        'nothing and the supervisor restarts in a hot loop; infinite removes the ' +
+        'cap and lets the exponential grow without bound.',
+    ),
+    restartResetAfter: positiveFiniteDuration(
+      'restartResetAfter',
+      tuning.restartResetAfter,
+      'restartResetAfter is the elapsed-retrying threshold at which the backoff ' +
+        'starts over: at zero it resets on every decision so the backoff never ' +
+        'grows, and infinite means it never resets — either way the sawtooth is ' +
+        "gone, and the no-progress budget's default is sized in WALL CLOCK " +
+        'against that sawtooth, so it would no longer buy the minutes it ' +
+        'documents.',
+    ),
+  })
+
+  if (Either.isLeft(checked)) {
+    return `${MIS_TUNED} ${checked.left}`
+  }
+
+  if (
+    Duration.greaterThan(
+      checked.right.restartMinDelay,
+      checked.right.restartMaxDelay,
+    )
+  ) {
+    return (
+      `${MIS_TUNED} restartMinDelay ` +
+      `(${Duration.format(checked.right.restartMinDelay)}) is greater than ` +
+      `restartMaxDelay (${Duration.format(checked.right.restartMaxDelay)}). ` +
+      'Schedule.union takes the SHORTER of its two arms, so an inverted pair ' +
+      'silences the exponential entirely: every restart would sleep exactly ' +
+      'restartMaxDelay, the documented sawtooth would not happen, and the ' +
+      'no-progress budget would be wrong by however far apart the two figures ' +
+      'are. Swap them, or raise the ceiling.'
+    )
+  }
+
+  return undefined
+}
+
+/**
+ * The composed subscription query against the STORE's servable grammar:
+ * `undefined` when the store would serve it, otherwise `core`'s own sentence about
+ * why it would not.
+ *
+ * ## Why `core`'s `assertServableQuery` and not a predicate of our own
+ *
+ * It is the very function every engine applies inside `read`/`subscribe`/`append`,
+ * so calling it is what makes ONE grammar rather than two that agree until one is
+ * edited. A local re-implementation would be a second definition of servability
+ * living in a package that does not own the concept, free to drift in either
+ * direction: too strict and it refuses a query the store would happily serve, too
+ * lax and the violation resurfaces at the first stream pull, inside the forked
+ * fibre, as a `PipelineDied` that only becomes visible as a `ProjectionStalled`
+ * once the breaker trips on a checkpoint that never moved — several backoff sleeps
+ * later, describing a stall rather than the mis-built slice that caused it.
+ *
+ * ## Why the THROW is converted rather than propagated
+ *
+ * `assertServableQuery` throws, because its own callers are store methods where a
+ * throw inside an `Effect` is already the defect it should be. Here it is one of
+ * five rules whose results compose, so letting it throw would give this gate two
+ * exit routes — a returned sentence for four rules and an exception for the
+ * fifth — and every caller would then need both a `??` chain and a `try`. Catching
+ * it keeps ONE exit route, and the caller keeps one `Effect.die`.
+ *
+ * The message is passed through VERBATIM, which is the point of the conversion
+ * rather than a detail of it: the violation goes on being reported in the store's
+ * vocabulary, in the same words the same rule produces when a store rejects the
+ * same query, so an author who meets it twice meets it once. The `instanceof`
+ * fallback is for the shape of the contract rather than for anything observed —
+ * `throw` admits any value, and `String(error)` is the honest reading of one this
+ * module cannot inspect.
+ */
+const servableQueryFault = (wiring: {
+  readonly query: Query
+}): string | undefined => {
+  try {
+    assertServableQuery(wiring.query)
+    return undefined
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+}
+
+/**
+ * The read side's OWN per-slice rule: `undefined` when every slice carries at least
+ * one tag, otherwise the sentence naming the first slice that does not.
+ *
+ * Checked slice by slice because the composed grammar above cannot see it: a SINGLE
+ * tagless slice composes to one type-only item, which IS servable, so the store
+ * would run that subscription happily. It is still a programming error, for two
+ * reasons. It does not COMPOSE — adding a second, tagged slice later turns today's
+ * accepted query into a tagless-plus-tagged union the store rejects, so the mistake
+ * would surface as a break in an unrelated change rather than at the slice that
+ * caused it. And a read model that genuinely is global should SAY so with an
+ * explicit `system:…` tag, which is the convention every other boundary in the repo
+ * already follows (CONTEXT); saying it by omission reads as a forgotten tag.
+ *
+ * The sentence names the offending SLICE, the rule and the fix, and deliberately
+ * not the projection: the caller's preamble carries that, for every rule at once,
+ * together with the partition where the caller has one worth naming.
+ */
+const taglessSliceFault = (wiring: {
+  readonly slices: Record<string, { readonly query: Query }>
+}): string | undefined => {
+  for (const [name, slice] of Object.entries(wiring.slices)) {
+    const untagged =
+      slice.query.items.length === 0 ||
+      slice.query.items.some((item) => item.tags.length === 0)
+    if (untagged) {
+      return (
+        `read-model slice '${name}' carries NO tags. Every read-model slice ` +
+        'must carry at least one tag: build it with .build({ tags: [...] }), ' +
+        'and give a genuinely GLOBAL slice an explicit system tag ' +
+        "(tagIdentity('system').make('…')) rather than no tag at all. A " +
+        'tagless slice is servable on its own — it is the single type-only fast ' +
+        'path — which is exactly why it is rejected here rather than by the ' +
+        'store: composing it with any tagged slice later would produce an ' +
+        'unservable tagless-plus-tagged union query, so the mistake would ' +
+        'surface far from its cause.'
+      )
+    }
+  }
+  return undefined
+}
+
+/**
+ * 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
+}
+
+/**
+ * Apply a PER-ENTRY rule to every entry in turn, returning the first sentence one of
+ * them yields — prefixed with the offending index where, and only where, there is
+ * more than one entry to index into.
+ *
+ * The condition is what keeps a single wiring's message byte-identical to what it
+ * was before the two callers shared this chain, and it keeps the module internally
+ * consistent: an index appears exactly where there is a set. The collision rung
+ * needs no such condition because it cannot fire below N = 2, so its indices are
+ * always meaningful.
+ *
+ * The prefix copies the collision rung's own vocabulary — `materialisations[i]` —
+ * rather than inventing a second way to name an entry, so an author who meets both
+ * meets one.
+ */
+const perEntry = <A>(
+  entries: ReadonlyArray<A>,
+  rule: (entry: A) => string | undefined,
+): string | undefined => {
+  for (let index = 0; index < entries.length; index += 1) {
+    const fault = rule(entries[index])
+    if (fault !== undefined) {
+      return entries.length > 1
+        ? `materialisations[${index}] — ${fault}`
+        : fault
+    }
+  }
+  return undefined
+}
+
+/**
+ * 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 const projectionWiringFault = (wiring: {
+  readonly eventLogDurability: Durability
+  readonly query: Query
+  readonly slices: Record<string, { readonly query: Query }>
+  readonly materialisations: ReadonlyArray<MaterialisationWiring>
+}): string | undefined =>
+  materialisationCollisionFault(wiring) ??
+  perEntry(wiring.materialisations, (entry) =>
+    durabilityOrderingFault({
+      eventLogDurability: wiring.eventLogDurability,
+      viewDurability: entry.viewDurability,
+    }),
+  ) ??
+  perEntry(wiring.materialisations, tuningFault) ??
+  servableQueryFault(wiring) ??
+  taglessSliceFault(wiring)
+
+/**
+ * The SET-LEVEL rung: `undefined` when no two materialisations of one read model
+ * would fight over one cursor, otherwise the sentence naming the offending pair and
+ * the fix.
+ *
+ * It is the FIRST rung in the declared order despite being the last symbol in this
+ * file, which is layout rather than precedence: the four per-wiring predicates sit
+ * above the chain that composes them, and this one — the newest and by far the
+ * longest — sits below it rather than pushing them apart. The module doc argues the
+ * order.
+ *
+ * FILE-PRIVATE, like every other rung: the chain is the only entry point, so a
+ * caller cannot reach one rule without the four that are declared to precede or
+ * follow it. It keeps its NAME because ADR-0007 cites the predicate by name.
+ *
+ * ## The rule
+ *
+ * A fault when two entries share the SAME store REFERENCE — compared by identity,
+ * never called, which is why the field is typed `object` — and their resolved
+ * `CheckpointKey`s are equal in both halves. Both conditions are needed and
+ * neither is sufficient, which is the whole content of the rule and the reason it
+ * takes resolved keys rather than a caller's raw options.
+ *
+ * Why the pairing is a defect: a `CheckpointKey` addresses ONE cursor within ONE
+ * store, so two runners over that pair are two writers over one scalar guarded
+ * compare-and-set. Every batch races it; one wins, the loser's `commit` fails
+ * `CheckpointSuperseded` and its own view writes are aborted with it; the loser then
+ * resynchronises from the winner's position and does it again. Nothing errors out to
+ * an operator — the supervisor's breaker deliberately does NOT trip, because the
+ * shared signal keeps moving, which is exactly the competing-writer case
+ * `superviseOnProgress` is built to absorb — so the observable result is two views
+ * each holding an arbitrary subset of the events, indefinitely, at the schedule's
+ * rate. It is the "one MATERIALISATION, one runner" invariant of ADR-0007 — which
+ * that record's own amendment is careful to word that way rather than per READ
+ * MODEL, a read model being materialisable N ways on purpose — broken in the one way
+ * a single `runProjection` call cannot break it.
+ *
+ * ## PAIRWISE, deliberately
+ *
+ * Two nested loops over N, where N is the number of ways one read model is
+ * materialised — two or three in every shape this exists for, and bounded by how many
+ * view stores an application has. A map keyed on the store plus the flattened key
+ * would be asymptotically better and worse in every way that matters here: it would
+ * need a key flattening (with the separator-injection question `mapKey` in
+ * `inMemoryProjectionStore.ts` had to settle) and a composite map key that cannot
+ * hold an object identity, to save microseconds on a list of three at construction
+ * time. Pairwise says the rule in the shape the rule is written in.
+ *
+ * ## The two bounds, which are DECISIONS and not oversights
+ *
+ * It does not reject equal keys across DIFFERENT stores. That is the sound and
+ * intended shape, and the reason this rung needs the store identity at all: one read
+ * model realised N ways shares ONE `ProjectionId`, because a `CheckpointKey` is a
+ * lookup identifier within one store rather than a global name. Two stores holding
+ * the same key are two materialisations of one read model, each with its own cursor,
+ * which is precisely what `runProjections` is for —
+ * `packages/read-postgres/test/courseRosterGraduation.test.ts` asserts that key
+ * equality across an in-memory and a SQL store as its acceptance criterion.
+ *
+ * And it cannot detect two SEPARATELY CONSTRUCTED stores pointed at one physical
+ * namespace — two `makeSqlProjectionStore` calls on the same schema and table
+ * prefix, say. Reference equality is blind to that by construction, and the
+ * same class of limit is already recorded for the SQL backend's own schema isolation
+ * in `packages/read-postgres/src/internal/ddl.ts`, which can reject an identifier it
+ * would truncate but cannot know what another config points at. What reference
+ * equality does catch is the realistic mistake: ONE store value passed twice, which
+ * is what the ergonomic shape of the call invites — a caller who has one store to
+ * hand writes it into both entries.
+ *
+ * The sentence names the two entries by INDEX and the partition they share, states
+ * what the pairing would do, and gives both fixes — the one that is almost always
+ * wanted (one materialisation whose single `apply` writes both views inside the one
+ * `commit`) and the escape hatch that makes genuine cohabitation legal (a distinct
+ * `partition`). It names no projection: the caller's preamble carries that, for every
+ * rule at once.
+ */
+const materialisationCollisionFault = (wiring: {
+  readonly materialisations: ReadonlyArray<{
+    readonly cursorIdentity: object
+    readonly key: CheckpointKey
+  }>
+}): string | undefined => {
+  const { materialisations } = wiring
+  for (let left = 0; left < materialisations.length; left += 1) {
+    for (let right = left + 1; right < materialisations.length; right += 1) {
+      const one = materialisations[left]
+      const other = materialisations[right]
+      if (
+        one.cursorIdentity === other.cursorIdentity &&
+        one.key.projection === other.key.projection &&
+        one.key.partition === other.key.partition
+      ) {
+        return (
+          `colliding materialisations — materialisations[${left}] and ` +
+          `materialisations[${right}] share ONE ProjectionStore under the SAME ` +
+          `CheckpointKey (partition '${one.key.partition}'), so they would be two ` +
+          'runners over one cursor. Every batch would race the same guarded ' +
+          "advance: one wins, the loser's commit fails CheckpointSuperseded and " +
+          'its own view writes are aborted with it, and because the shared ' +
+          'checkpoint keeps moving the supervisor never gives up — so the two ' +
+          'views would each hold an arbitrary subset of the events, ' +
+          'indefinitely, with nothing on any error channel. SEVERAL VIEWS IN ONE ' +
+          'STORE is a supported shape and this is not how to reach it: it wants ' +
+          'ONE materialisation whose single apply writes both views inside the ' +
+          'one commit, under one checkpoint. Where two materialisations genuinely ' +
+          'must cohabit one store, give one of them its own partition — a ' +
+          'distinct PartitionId is a distinct CheckpointKey and therefore a ' +
+          'cursor of its own.'
+        )
+      }
+    }
+  }
+  return undefined
+}