@kairos-es/read 0.0.0

package/dist/esm/testing.js

@@ -0,0 +1,133 @@
+import { Array as Arr, Effect, Option } from 'effect';
+import { runProjection } from "./runProjection.js";
+/**
+ * How often the waiting fibre re-reads the checkpoint. Small, because the wait
+ * ends on the FIRST read that has got there and a coarse interval would add its
+ * own latency to every case; not zero, because each read is a real store
+ * operation (a SQL round trip on a durable backend).
+ */
+const DEFAULT_POLL_INTERVAL = '2 millis';
+/**
+ * The ceiling on convergence. Deliberately far larger than any well-behaved case
+ * needs: it exists to turn a genuine hang into a FAILED assertion naming the
+ * position that was never reached, not to police how fast a runner is on a loaded
+ * machine. Backends whose live tail has its own poll interval — Postgres wakes on
+ * NOTIFY but GUARANTEES delivery by polling — should raise it to several of those
+ * intervals rather than lower it.
+ */
+const DEFAULT_TIMEOUT = '10 seconds';
+/**
+ * The stored checkpoint of a read model's bound view store, right now.
+ *
+ * `orDie` because a `ProjectionStoreError` means the test's own fixture cannot
+ * read its own checkpoint. The port puts that on the ERROR channel for the
+ * runner's supervisor, which has to tell retry-with-backoff from give-up
+ * (ADR-0007) — but a test has no supervisor and nothing to retry, so surfacing it
+ * as a defect keeps a broken fixture clearly distinct from the case's own
+ * assertion failing, and keeps every signature here `E = never` so a case never
+ * has to widen its own error channel to look at a view.
+ */
+export const storedCheckpoint = store => Effect.orDie(store.readCheckpoint);
+/**
+ * Wait until the stored checkpoint has reached `target`, then return it.
+ *
+ * The read side's answer to "has the projection caught up yet?", and the reason
+ * a read-model test needs no sleep: it polls the OBSERVABLE state, so it ends the
+ * instant the runner has actually got there and no sooner. Comparison is `>=`
+ * rather than `===` and that is load-bearing — positions are strictly increasing
+ * but NOT gapless, so a target derived from an append may be overshot by a batch
+ * that carried later events too, and an equality test would then wait for a
+ * position the log will never store.
+ *
+ * A KEYED store rather than a `(store, key)` pair, matching the shape the package
+ * settled on everywhere else: a read model's materialisation carries
+ * `forKey(store, key)` INSTEAD of a key field, so "one materialisation, one key" is
+ * structural rather than conventional, and the same argument applies to observing
+ * one. There is no key to transpose, the timeout message names `store.key` and
+ * therefore cannot name a key the poll did not use, and `readModel.store` is
+ * already exactly the right argument. A caller holding the multi-key port writes
+ * `forKey(store, key)`, which is the library's own one-line adapter and is
+ * `store.readCheckpoint(key)` with a `suspend` around it — so a suite deliberately
+ * observing through the RAW port (as `read-postgres`' live-log cases do, to keep
+ * "the façade wrote where the port reads" an observation rather than an assumption)
+ * loses nothing.
+ *
+ * A read model materialised N ways (`runProjections`) is N of these observations,
+ * one per store, and there is deliberately no plural helper for it. Under one
+ * `ProjectionId` and the default partition the N keys are IDENTICAL — a key names a
+ * cursor within a store — so the STORE is what distinguishes the materialisations,
+ * and each runner carries its own: `awaitCheckpoint(runners[i].store, target)` is
+ * already the per-entry observation, over the very binding the call made. So a plural
+ * helper would take nothing a caller does not already hold, and the N waits are one
+ * `Effect.all` over the runners it was handed — concurrently, since waiting on them
+ * in turn would prove only that each converges once the others have.
+ *
+ * Exceeding the timeout is a DEFECT, so this stays `E = never` and a case need
+ * not thread a timeout error it has no intention of handling. It is the right
+ * classification anyway: a projection that never converged is a broken test or a
+ * broken library, never an outcome to assert on.
+ */
+export const awaitCheckpoint = (store, target, options) => Effect.repeat(Effect.zipRight(Effect.sleep(options?.pollInterval ?? DEFAULT_POLL_INTERVAL), storedCheckpoint(store)), {
+  until: stored => stored >= target
+}).pipe(Effect.timeoutFail({
+  duration: options?.timeout ?? DEFAULT_TIMEOUT,
+  onTimeout: () => new Error(`awaitCheckpoint: the checkpoint for projection ` + `'${store.key.projection}' (partition '${store.key.partition}') ` + `never reached position ${target}`)
+}), Effect.orDie);
+/**
+ * Start the projection maintaining `readModel` and wait until its checkpoint has
+ * reached `target` — "run this until it has consumed the log", as one call.
+ *
+ * This is the surface the read side was missing. `runProjection` returns once the
+ * daemon is FORKED, which is the only honest thing it can do, so every read-model
+ * test is otherwise a two-step dance the author has to know to write; this pairs
+ * the two steps so that a case's next line can assert on the view.
+ *
+ * It returns the `ProjectionRunner` rather than swallowing it, because everything
+ * a case might do next needs the handle: `Fiber.poll` it (is the daemon still
+ * up?), `Fiber.interrupt` it early, or await it. The scope is still the teardown
+ * mechanism — this forks into the CALLER's `Scope`, exactly as `runProjection`
+ * does, so closing that scope interrupts the daemon and waits for it.
+ *
+ * ## What it deliberately is NOT
+ *
+ * A TEST helper, not a production freshness API. It reports nothing about lag, it
+ * cannot enumerate checkpoints, and no consumer should reach for it to make a
+ * request wait for its own write to be projected — a read model is eventually
+ * consistent by construction and a `waitUntilProcessed` on the hot path would be
+ * a way to pretend otherwise. That is why it lives behind `/testing` and not on
+ * the package's main entry. Where a request genuinely must see its own write, the
+ * honest answer is not to wait on a MAINTAINED materialisation at all: fold the log
+ * at query time with `modelAtHead` from `@kairos-es/codec`, which is consistent as
+ * of the `head` its read returned and therefore never behind a checkpoint.
+ *
+ * It also does not race the daemon's fibre against the wait. A projection that
+ * gives up fails `ProjectionStalled`, and it would be possible to surface that
+ * here instead of timing out — but the daemon's failure and the convergence
+ * ceiling are two independent clocks, and a helper whose diagnosis depended on
+ * which fired first is a worse instrument than one that always says the same
+ * thing. A case that wants the stall itself has the fibre returned above, and
+ * `onStalled` besides.
+ */
+export const runProjectionUntil = (readModel, target, options) => Effect.tap(runProjection(readModel, options), () =>
+// The read model's OWN bound store, so the cursor being waited on is
+// necessarily the cursor the runner advances. A `store` parameter here would
+// reintroduce exactly the pair `KeyedProjectionStore` exists to abolish.
+awaitCheckpoint(readModel.store, target, options));
+/**
+ * The LAST position of a sequence — the convergence target, derived from what
+ * `append` actually reported.
+ *
+ * The companion to the two waits above, and the reason it is a helper rather than
+ * `positions[positions.length - 1]`: a fixture that appended nothing would
+ * otherwise yield `undefined`, and a wait for `undefined` is either a type error
+ * at best or a vacuous assertion at worst. Failing loudly at the point the
+ * fixture is wrong is worth four lines.
+ *
+ * Targets are built this way — from the positions the log HANDED OUT — rather
+ * than from a literal `1n..Nn`, because positions are strictly increasing and NOT
+ * gapless: a rolled-back append burns an id, and a tag-narrowed subscription
+ * never delivers the positions it does not match. Nothing here does arithmetic on
+ * a position.
+ */
+export const lastPosition = positions => Option.getOrThrowWith(Arr.last(positions), () => new Error('test fixture: no events were appended'));
+//# sourceMappingURL=testing.js.map

package/dist/esm/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","names":["Array","Arr","Effect","Option","runProjection","DEFAULT_POLL_INTERVAL","DEFAULT_TIMEOUT","storedCheckpoint","store","orDie","readCheckpoint","awaitCheckpoint","target","options","repeat","zipRight","sleep","pollInterval","until","stored","pipe","timeoutFail","duration","timeout","onTimeout","Error","key","projection","partition","runProjectionUntil","readModel","tap","lastPosition","positions","getOrThrowWith","last"],"sources":["../../src/testing.ts"],"sourcesContent":[null],"mappings":"AAuEA,SAASA,KAAK,IAAIC,GAAG,EAAiBC,MAAM,EAAEC,MAAM,QAAoB,QAAQ;AAOhF,SAAyBC,aAAa,QAAQ,oBAAiB;AAE/D;;;;;;AAMA,MAAMC,qBAAqB,GAA2B,UAAU;AAEhE;;;;;;;;AAQA,MAAMC,eAAe,GAA2B,YAAY;AAsB5D;;;;;;;;;;;AAWA,OAAO,MAAMC,gBAAgB,GAC3BC,KAA2B,IACCN,MAAM,CAACO,KAAK,CAACD,KAAK,CAACE,cAAc,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,OAAO,MAAMC,eAAe,GAAGA,CAC7BH,KAA2B,EAC3BI,MAAgB,EAChBC,OAAgC,KAEhCX,MAAM,CAACY,MAAM,CACXZ,MAAM,CAACa,QAAQ,CACbb,MAAM,CAACc,KAAK,CAACH,OAAO,EAAEI,YAAY,IAAIZ,qBAAqB,CAAC,EAC5DE,gBAAgB,CAACC,KAAK,CAAC,CACxB,EACD;EAAEU,KAAK,EAAGC,MAAM,IAAKA,MAAM,IAAIP;AAAM,CAAE,CACxC,CAACQ,IAAI,CACJlB,MAAM,CAACmB,WAAW,CAAC;EACjBC,QAAQ,EAAET,OAAO,EAAEU,OAAO,IAAIjB,eAAe;EAC7CkB,SAAS,EAAEA,CAAA,KACT,IAAIC,KAAK,CACP,iDAAiD,GAC/C,IAAIjB,KAAK,CAACkB,GAAG,CAACC,UAAU,iBAAiBnB,KAAK,CAACkB,GAAG,CAACE,SAAS,KAAK,GACjE,0BAA0BhB,MAAM,EAAE;CAEzC,CAAC,EACFV,MAAM,CAACO,KAAK,CACb;AAeH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,OAAO,MAAMoB,kBAAkB,GAAGA,CAKhCC,SAA6B,EAC7BlB,MAAgB,EAChBC,OAAmC,KAWnCX,MAAM,CAAC6B,GAAG,CAAC3B,aAAa,CAAC0B,SAAS,EAAEjB,OAAO,CAAC,EAAE;AAC5C;AACA;AACA;AACAF,eAAe,CAACmB,SAAS,CAACtB,KAAK,EAAEI,MAAM,EAAEC,OAAO,CAAC,CAClD;AAEH;;;;;;;;;;;;;;;;AAgBA,OAAO,MAAMmB,YAAY,GAAIC,SAAkC,IAC7D9B,MAAM,CAAC+B,cAAc,CACnBjC,GAAG,CAACkC,IAAI,CAACF,SAAS,CAAC,EACnB,MAAM,IAAIR,KAAK,CAAC,uCAAuC,CAAC,CACzD","ignoreList":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@kairos-es/read",
+  "version": "0.0.0",
+  "description": "Query-driven projection runner and checkpoint port for kairos-es",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverbland/kairos-es.git",
+    "directory": "packages/read"
+  },
+  "sideEffects": [],
+  "homepage": "https://github.com/neverbland/kairos-es",
+  "peerDependencies": {
+    "effect": "^3.22.0",
+    "@kairos-es/codec": "^0.0.0",
+    "@kairos-es/core": "^0.0.0"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/dts/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./testing": {
+      "types": "./dist/dts/testing.d.ts",
+      "import": "./dist/esm/testing.js",
+      "default": "./dist/cjs/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "testing": [
+        "./dist/dts/testing.d.ts"
+      ]
+    }
+  }
+}

package/src/EventLogDurability.ts

@@ -0,0 +1,201 @@
+/**
+ * `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.
+ */
+import { Context, Layer } from 'effect'
+import type { Durability } from './ProjectionStore'
+
+/**
+ * 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.
+ */
+export class EventLogDurability extends Context.Tag(
+  '@kairos-es/read/EventLogDurability',
+)<EventLogDurability, Durability>() {}
+
+/**
+ * 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`.
+ */
+export const DurableEventLog: Layer.Layer<EventLogDurability> = 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.
+ */
+export const EphemeralEventLog: Layer.Layer<EventLogDurability> = 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.
+ */
+export const durabilityOrderingFault = (declarations: {
+  readonly eventLogDurability: Durability
+  readonly viewDurability: Durability
+}): string | undefined =>
+  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