@kairos-es/read 0.0.0

package/dist/cjs/projectionWiringFault.js

@@ -0,0 +1,532 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.projectionWiringFault = void 0;
+var _core = require("@kairos-es/core");
+var _effect = require("effect");
+var _EventLogDurability = require("./EventLogDurability.js");
+/**
+ * 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.
+ */
+
+/**
+ * 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, input, role) => {
+  const decoded = _effect.Duration.decodeUnknown(input);
+  if (_effect.Option.isNone(decoded)) {
+    return _effect.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 (!_effect.Duration.isFinite(decoded.value)) {
+    return _effect.Either.left(`${name} is infinite (got ${String(input)}). ${role}`);
+  }
+  if (_effect.Duration.isZero(decoded.value)) {
+    return _effect.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 _effect.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 => {
+  const checked = _effect.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 (_effect.Either.isLeft(checked)) {
+    return `${MIS_TUNED} ${checked.left}`;
+  }
+  if (_effect.Duration.greaterThan(checked.right.restartMinDelay, checked.right.restartMaxDelay)) {
+    return `${MIS_TUNED} restartMinDelay ` + `(${_effect.Duration.format(checked.right.restartMinDelay)}) is greater than ` + `restartMaxDelay (${_effect.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 => {
+  try {
+    (0, _core.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 => {
+  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;
+};
+/**
+ * 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 = (entries, rule) => {
+  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).
+ */
+const projectionWiringFault = wiring => materialisationCollisionFault(wiring) ?? perEntry(wiring.materialisations, entry => (0, _EventLogDurability.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.
+ */
+exports.projectionWiringFault = projectionWiringFault;
+const materialisationCollisionFault = wiring => {
+  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;
+};
+//# sourceMappingURL=projectionWiringFault.js.map

package/dist/cjs/projectionWiringFault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionWiringFault.js","names":["_core","require","_effect","_EventLogDurability","positiveFiniteDuration","name","input","role","decoded","Duration","decodeUnknown","Option","isNone","Either","left","String","isFinite","value","isZero","right","MIS_TUNED","tuningFault","tuning","checked","all","batchWindow","restartMinDelay","restartMaxDelay","restartResetAfter","isLeft","greaterThan","format","undefined","servableQueryFault","wiring","assertServableQuery","query","error","Error","message","taglessSliceFault","slice","Object","entries","slices","untagged","items","length","some","item","tags","perEntry","rule","index","fault","projectionWiringFault","materialisationCollisionFault","materialisations","entry","durabilityOrderingFault","eventLogDurability","viewDurability","exports","one","other","cursorIdentity","key","projection","partition"],"sources":["../../src/projectionWiringFault.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}