@kairos-es/read 0.0.0

package/dist/cjs/EventLogDurability.js

@@ -0,0 +1,184 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.durabilityOrderingFault = exports.EventLogDurability = exports.EphemeralEventLog = exports.DurableEventLog = void 0;
+var _effect = require("effect");
+/**
+ * `EventLogDurability` — the R2 input the EVENT LOG contributes: how far the log a
+ * projection subscribes to survives a restart, declared by the application that
+ * chose the store's `Layer` and read from context in ONE place — the
+ * `prepareProjection` phase both runner entry points share, which is also the gate's
+ * only caller.
+ *
+ * ## The rule: R2, durability ordering
+ *
+ * This is R2's home, and every other mention in the read side points here rather
+ * than restating it.
+ *
+ * Checkpoint durability must not EXCEED event-log durability. The comparison has
+ * two halves, each declared where it is known: the VIEW store carries its own
+ * class on the `ProjectionStore` it implements, and the LOG's class is this tag. A
+ * DURABLE view over an EPHEMERAL log is the one illegal pairing of the four.
+ *
+ * It is illegal because the failure is SILENT. The checkpoint survives a restart
+ * the log does not, so on the next boot `subscribe(query, checkpoint)` returns
+ * nothing against a re-emptied log: no fibre dies, no error reaches any channel,
+ * no log line appears, and the view simply sits frozen and permanently stale while
+ * continuing to serve reads. Nothing at runtime is placed to notice it, which is
+ * why the two declarations are compared BEFORE anything is forked.
+ *
+ * `durabilityOrderingFault` at the foot of this module is that comparison — the
+ * CHECK beside the argument for it, so a reader who comes here for the rule finds
+ * the code that enforces it and the sentence an author meets when they break it,
+ * rather than a restatement of the rule four hundred lines away in the pipeline
+ * module. It is the first PER-ENTRY rung of the five rules `projectionWiringFault`
+ * chains, behind only the set-level collision rung, and is judged for every
+ * materialisation in the call; that module owns the argument for the whole order.
+ *
+ * The asymmetry is deliberate: getting the declaration wrong in the SAFE direction
+ * — saying `'ephemeral'` over a genuinely durable log — costs nothing but a durable
+ * view, so nothing checks it. Only the unsafe direction is rejected.
+ *
+ * ## Why it is DECLARED at all
+ *
+ * `DcbEventStore` deliberately exposes no durability, and that opacity is a
+ * feature rather than an omission: a runner never learns which engine it is
+ * running against, which is exactly what lets one projection sit over the
+ * in-memory log in a test and over Postgres in production with nothing in between
+ * changing. The store contract is untouched by the read side. But R2 has to know
+ * the log's class, so the only honest source is the application that picked the
+ * layer.
+ *
+ * ## Why a `Context.Tag` rather than a field on `ReadModel`
+ *
+ * ONE log, ONE declaration. The fact being declared is a property of the EVENT
+ * LOG, and every read model in a deployment reads the same log, so authoring it
+ * per read model states one fact N times at N sites — and N copies can DISAGREE.
+ * One read model declaring `'durable'` beside a neighbour declaring `'ephemeral'`
+ * over the identical `DcbEventStore` is not a type error, and nothing anywhere
+ * could notice: `runProjection` only ever sees the one pair it was handed, so
+ * there is no vantage point from which the contradiction is even visible. The read
+ * side's own scaling story is one runner per materialisation — horizontal scale by
+ * functional decomposition, never by sharding one read model's stream (ADR-0007) —
+ * so N > 1 is the EXPECTED case, and the unsafe direction is then reachable by a
+ * copy-paste that gets one of N wrong. N materialisations of ONE read model
+ * (`runProjections`) only sharpen that: their whole point is that the view stores
+ * differ, so their R2 verdicts differ too and each is judged separately against this
+ * one declaration — which is precisely why the LOG's half must not be authored
+ * alongside them.
+ *
+ * Provided beside the store layer, the declaration sits with the choice it
+ * describes: `Layer.merge(DcbEventStoreInMemory, EphemeralEventLog)` names the log
+ * and its durability class in one expression, and there is exactly one of it
+ * however many runners the graph goes on to carry.
+ *
+ * The cost is real and taken deliberately: this is a REQUIRED service in the `R` of
+ * `runProjection`, `projectionLayer` and `runProjections` alike, which every consumer
+ * must provide — and most costly to forget at `runProjections`, where one missing
+ * layer refuses N materialisations at once. Defaulting it would
+ * defeat the point in both directions — defaulting to `'ephemeral'` would make the
+ * PRODUCTION wiring the one you have to remember, and defaulting to `'durable'`
+ * would turn a forgotten declaration into the silently frozen view R2 exists to
+ * prevent.
+ *
+ * ## Why the store layers do not provide it themselves
+ *
+ * `DcbEventStoreInMemory` could plausibly provide `'ephemeral'` on its own and make
+ * the all-in-memory case correct by default. It deliberately does not, for three
+ * reasons that outweigh the ergonomics.
+ *
+ * This is a READ-SIDE tag, and `@kairos-es/core` knows nothing of the read side —
+ * `read` peers `core`, not the other way round — so core would have to DEFINE the
+ * tag for its layer to provide it. That puts a read-side rule inside the store
+ * contract's own package, which is precisely the coupling the contract's
+ * durability-opacity exists to avoid.
+ *
+ * It would also move the declaration from the APPLICATION to the BACKEND. Then a
+ * backend that got its own class wrong (a log that persists only on a flag, say)
+ * would be wrong for every read model at once with no wiring site left to correct
+ * it, and the whole reason R2 keys on a declaration rather than on the store is
+ * that only the application knows.
+ *
+ * And two providers of one tag is not an error in a layer graph — it is resolved
+ * by merge order. An application that declared `DurableEventLog` beside a store
+ * layer declaring `'ephemeral'` would get whichever merge happened to win, silently,
+ * which is a worse failure than the one being fixed. The single token
+ * `EphemeralEventLog` costs is not worth any of that.
+ */
+
+/**
+ * The event log's durability class, as the application declares it.
+ *
+ * The service value is the bare `Durability` rather than a record wrapping it:
+ * the tag's name says exactly what it holds, so `yield* EventLogDurability` is the
+ * whole read, and `Layer.succeed(EventLogDurability, 'durable')` is the whole
+ * declaration for anyone not reaching for the two layers below.
+ */
+class EventLogDurability extends /*#__PURE__*/_effect.Context.Tag('@kairos-es/read/EventLogDurability')() {}
+/**
+ * Declare that the event log OUTLIVES the process — the production wiring, beside
+ * a durable `DcbEventStore` layer such as `@kairos-es/store-postgres`'s.
+ *
+ * Shipped as a `Layer` rather than left to `Layer.succeed` at each wiring site for
+ * the same reason `SerializerDefault` is: it names the declaration, so the two
+ * legal values cannot be typo'd, and it composes into a store layer's own merge
+ * without a second import from `effect`.
+ */
+exports.EventLogDurability = EventLogDurability;
+const DurableEventLog = exports.DurableEventLog = /*#__PURE__*/_effect.Layer.succeed(EventLogDurability, 'durable');
+/**
+ * Declare that the event log DIES WITH THE PROCESS — `core`'s
+ * `DcbEventStoreInMemory`, and any other log whose contents do not survive a
+ * restart.
+ *
+ * Under this declaration a DURABLE `ProjectionStore` is rejected by R2, because
+ * its checkpoint would outlive the log it points into. It is also the honest
+ * conservative choice over a log whose durability is genuinely unknown: it forgoes
+ * a durable view and nothing else.
+ */
+const EphemeralEventLog = exports.EphemeralEventLog = /*#__PURE__*/_effect.Layer.succeed(EventLogDurability, 'ephemeral');
+/**
+ * R2 itself: `undefined` when the two declarations are legally ordered, otherwise
+ * the sentence an author meets when they are not.
+ *
+ * The one illegal pairing of the four is a DURABLE view over an EPHEMERAL log. The
+ * asymmetry is deliberate and the module doc argues it: declaring `'ephemeral'`
+ * over a genuinely durable log costs nothing but a durable view, so only the unsafe
+ * direction is rejected.
+ *
+ * ## Why NAMED FIELDS rather than two positional arguments
+ *
+ * The two operands are the same unbranded `Durability` union, so a positional pair
+ * would typecheck transposed — and a transposed R2 check is not a broken check, it
+ * is an INVERTED one: it would accept the one pairing that silently freezes a view
+ * and reject the three that are fine, which is worse than having no check at all.
+ * Named fields make that transposition unwritable without visibly naming the wrong
+ * field, which is as much as a call-site convention can be asked to carry.
+ *
+ * It is as much as is WANTED here, too. Branding the two halves so the type system
+ * separated them was considered and rejected: `Durability` is a two-value union
+ * read straight off a `Layer` and a `ProjectionStore`, both of them public surfaces
+ * a caller writes by hand, so branding it would put a constructor between an
+ * application and `Layer.succeed(EventLogDurability, 'durable')` for a mistake the
+ * R2 case and its non-vacuity control already catch — that control provides
+ * `DurableEventLog` over the SAME durable view store and asserts the runner starts,
+ * which no mis-comparison in here can satisfy while still failing the rejection
+ * half.
+ *
+ * The sentence begins with `R2 violated` and states the rule, the silent failure it
+ * prevents, and BOTH fixes, because it is written for whoever meets it in a log with
+ * no file open. It names `EventLogDurability` in particular: the log's half of the
+ * comparison is this service, provided beside the `DcbEventStore` layer, so that is
+ * where the reader has to go — a read model carries no field to correct. It does not
+ * name the projection; the caller's preamble carries that, for every rule at once.
+ * Whether it also names a PARTITION is the caller's to decide: `runProjection` writes
+ * one, and `runProjections` deliberately writes none — not because its entries share a
+ * partition (each resolves its own, and a distinct one is the escape hatch for two
+ * materialisations cohabiting a store) but because a fault there is already attributed
+ * by entry INDEX, which discriminates where a partition may not.
+ */
+const durabilityOrderingFault = declarations => declarations.eventLogDurability === 'ephemeral' && declarations.viewDurability === 'durable' ? 'R2 violated — a DURABLE ProjectionStore over an EPHEMERAL event log. ' + 'The checkpoint would survive a restart the log does not, so on the next ' + 'boot subscribe(query, checkpoint) would return nothing against a ' + 're-emptied log and the view would sit FROZEN and permanently stale ' + 'without ever erroring. Pair an ephemeral log with an ephemeral view ' + "store, or make the log durable. The log's half of this comparison is " + 'the EventLogDurability service provided beside your DcbEventStore layer ' + '(EphemeralEventLog here); the view store declares the other half itself.' : undefined;
+exports.durabilityOrderingFault = durabilityOrderingFault;
+//# sourceMappingURL=EventLogDurability.js.map

package/dist/cjs/EventLogDurability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventLogDurability.js","names":["_effect","require","EventLogDurability","Context","Tag","exports","DurableEventLog","Layer","succeed","EphemeralEventLog","durabilityOrderingFault","declarations","eventLogDurability","viewDurability","undefined"],"sources":["../../src/EventLogDurability.ts"],"sourcesContent":[null],"mappings":";;;;;;AAsGA,IAAAA,OAAA,GAAAC,OAAA;AAtGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyGA;;;;;;;;AAQM,MAAOC,kBAAmB,sBAAQC,eAAO,CAACC,GAAG,CACjD,oCAAoC,CACrC,EAAkC;AAEnC;;;;;;;;;AAAAC,OAAA,CAAAH,kBAAA,GAAAA,kBAAA;AASO,MAAMI,eAAe,GAAAD,OAAA,CAAAC,eAAA,gBAAoCC,aAAK,CAACC,OAAO,CAC3EN,kBAAkB,EAClB,SAAS,CACV;AAED;;;;;;;;;;AAUO,MAAMO,iBAAiB,GAAAJ,OAAA,CAAAI,iBAAA,gBAAoCF,aAAK,CAACC,OAAO,CAC7EN,kBAAkB,EAClB,WAAW,CACZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCO,MAAMQ,uBAAuB,GAAIC,YAGvC,IACCA,YAAY,CAACC,kBAAkB,KAAK,WAAW,IAC/CD,YAAY,CAACE,cAAc,KAAK,SAAS,GACrC,uEAAuE,GACvE,0EAA0E,GAC1E,mEAAmE,GACnE,qEAAqE,GACrE,sEAAsE,GACtE,uEAAuE,GACvE,0EAA0E,GAC1E,0EAA0E,GAC1EC,SAAS;AAAAT,OAAA,CAAAK,uBAAA,GAAAA,uBAAA","ignoreList":[]}