@kairos-es/read 0.0.0

package/dist/esm/ProjectionStore.js

@@ -0,0 +1,223 @@
+import { Data, Effect, Schema } from 'effect';
+/**
+ * The name of a read model, as a branded non-empty string.
+ *
+ * Branded rather than a bare `string` for the same reason every other kairos-es
+ * identifier is (`Position`, `Tag`, `EventType`): the projection name and the
+ * partition name are both non-empty strings with identical shape, so an
+ * unbranded pair is trivially transposable at a call site and the mistake would
+ * surface only as a projection silently reading somebody else's checkpoint.
+ * Construct with `ProjectionId.make(...)`.
+ */
+export const ProjectionId = /*#__PURE__*/Schema.String.pipe(/*#__PURE__*/Schema.nonEmptyString(), /*#__PURE__*/Schema.brand('ProjectionId'));
+/**
+ * The partition of a read model's checkpoint, as a branded non-empty string.
+ *
+ * `DEFAULT_PARTITION` is the single value the RUNNER uses, because stream
+ * sharding is deliberately not offered: DCB events carry a tag matrix, so two
+ * shards can own rows for the same tag while each holds its own checkpoint —
+ * both guarded compare-and-sets then succeed and the lost update goes undetected
+ * (the guard arbitrates cursor progress, not row ownership). Nothing on this port
+ * restricts the value, and a `ProjectionStore` must keep every distinct
+ * `(projection, partition)` pair independent — the shared contract suite commits
+ * to a second partition precisely to prove that. The dimension is in the KEY so
+ * that a restricted, opt-in sharding capability — for read models that provably
+ * need no cross-tag ordering and whose every row is owned by one partition value
+ * — could be added later with no migration of the checkpoint's shape or storage.
+ */
+export const PartitionId = /*#__PURE__*/Schema.String.pipe(/*#__PURE__*/Schema.nonEmptyString(), /*#__PURE__*/Schema.brand('PartitionId'));
+/** The partition value every runner uses while sharding is cut (ADR-0007). */
+export const DEFAULT_PARTITION = /*#__PURE__*/PartitionId.make('default');
+/**
+ * Build a `CheckpointKey`, defaulting the partition — the constructor nearly
+ * every call site wants, so that the sharding dimension stays in the key shape
+ * without appearing in ordinary wiring code.
+ */
+export const checkpointKey = (projection, partition = DEFAULT_PARTITION) => ({
+  projection,
+  partition
+});
+/**
+ * An infrastructure fault from a view store — a connection dropped, a statement
+ * failed, the checkpoint table is missing.
+ *
+ * This is a value on the ERROR channel rather than a defect, which inverts the
+ * store contract's rule (`DcbEventStore` dies on infrastructure faults, ADR-0002)
+ * and does so on purpose: the read side has a supervisor above it, and the
+ * supervisor's whole job is to tell "retry the subscription with backoff" from
+ * "give up and report a stalled projection". A defect carries no such
+ * distinction. `cause` is exact-optional — only set when there is one.
+ */
+export class ProjectionStoreError extends /*#__PURE__*/Data.TaggedError('ProjectionStoreError') {
+  /**
+   * `reason` again, as the `Error` field that says why — so the fault renders
+   * ITSELF.
+   *
+   * `Data.TaggedError` sets `name` to the tag and leaves `message` empty, so
+   * without this a `ProjectionStoreError` stringifies to `'ProjectionStoreError'`
+   * and the sentence explaining the fault reaches a log line only where something
+   * OUTSIDE the class knows to go and fetch `reason`. With it,
+   * `Error.prototype.toString` yields `'ProjectionStoreError: <reason>'`, and
+   * `String(fault)`, `Cause.pretty` (which reads `message` off anything `instanceof
+   * Error`) and the projection supervisor's `reason` annotation all take it from the
+   * one place it is declared. That matters most for exactly the audience this error
+   * exists for: the supervisor above the read side, whose log line is what an
+   * operator sees when a view store starts refusing to answer.
+   *
+   * ## What filling `message` reaches — and what it deliberately leaves alone
+   *
+   * Not the supervisor's two log lines: `message` is the field `Cause.pretty` reads
+   * off anything `instanceof Error`, so this changes how a `ProjectionStoreError`
+   * prints EVERYWHERE it is reported — a failed fibre's `cause` annotation on all
+   * three shipped loggers, `Effect.logError(message, cause)`, an unhandled
+   * failure's report, and any reporter or test runner that reads `.message`. That
+   * blast radius is the point of doing it on the class instead of at one call site:
+   * one declaration improves every reader at once, and none of them has to know
+   * this class's field names.
+   *
+   * What it does NOT change is the STRUCTURED shape. `Data.Error` overrides
+   * `YieldableError`'s `toJSON` with `{ ...plainArgs, ...this }` — own enumerables
+   * plus the constructor args, and a prototype accessor is neither — so
+   * `JSON.stringify(fault)` and an `Effect.logError(fault)` that JSON-encodes its
+   * object message emit exactly the `reason`/`_tag` they always did. The humane
+   * rendering gains a sentence; the machine-parsed one is untouched.
+   *
+   * A GETTER rather than a second field, so `reason` stays the single declaration
+   * and the two cannot disagree. Safe as a prototype accessor because
+   * `Data.TaggedError`'s constructor is `super(args?.message, …)` followed by
+   * `Object.assign(this, args)` (verified against `effect@3.22`'s `Data.ts`) and
+   * `message` is not among the fields above, so nothing shadows it with an own
+   * property.
+   *
+   * Both mechanics — that accessor safety and the `toJSON` shape above it — are
+   * argued HERE and nowhere else, for every read-side fault that fills the field:
+   * `CheckpointSuperseded` below, `PipelineDied` in `ProjectionRunner.ts` and
+   * `ProjectionStalled` in `superviseOnProgress.ts` each point back rather than
+   * re-derive, and none of the four declares a `message` field for that
+   * `Object.assign` to shadow its accessor with. One version pin to re-verify on an
+   * `effect` bump, not four.
+   */
+  get message() {
+    return this.reason;
+  }
+}
+/**
+ * The guarded compare-and-set lost: the stored checkpoint no longer equals
+ * `expected`, so somebody else advanced this key.
+ *
+ * A tagged ERROR, never a returned outcome value. A returned
+ * `Advanced | Superseded` only rolls the view writes back if the caller remembers
+ * to convert it into a failure, and forgetting is silent corruption — the view
+ * commits while the checkpoint stays put, and the next pass double-applies the
+ * batch. On the error channel the abort is automatic and cannot be ignored.
+ *
+ * It carries the key and the expectation but deliberately NOT the stored
+ * position, mirroring `AppendConditionFailed` (ADR-0002) for the same reason: the
+ * recovery path re-reads the checkpoint, so a carried position would already be
+ * stale by the time anything acted on it, and carrying one would invite exactly
+ * the resume-from-the-conflict-point bug that omitting it prevents.
+ *
+ * Like its sibling `ProjectionStoreError` it fills `message`, from the expectation
+ * it already carries. The getter below says what the field reaches, and also
+ * records the reasoning it REPLACED — this class once left `message` empty on a
+ * ground that could not be true, and that is worth being able to recognise again.
+ */
+export class CheckpointSuperseded extends /*#__PURE__*/Data.TaggedError('CheckpointSuperseded') {
+  /**
+   * The sentence this class's own first paragraph writes, plus the expectation the
+   * guard turned on — as the `Error` field that says why, so the fault renders
+   * ITSELF.
+   *
+   * `Data.TaggedError` sets `name` to the tag and leaves `message` empty, and
+   * `Cause.pretty` substitutes its own `'An error has occurred'` for an empty one,
+   * so unfilled this fault printed through a `Cause` reads
+   * `'CheckpointSuperseded: An error has occurred'` — a line naming neither a guard,
+   * nor a checkpoint, nor an expectation. Filled, `Error.prototype.toString` yields
+   * the tag followed by the sentence, everywhere the fault is reported. How far that
+   * reaches and what it deliberately leaves alone is set out on
+   * `ProjectionStoreError` above; the argument is identical for every fault that
+   * fills the field, so it is made once, on the one an operator meets most.
+   *
+   * ## Why this field was once left EMPTY, and why that reason was wrong
+   *
+   * Recorded rather than quietly deleted, because a rationale that cannot be true is
+   * worse than a missing one and the shape of this mistake is easy to repeat. The
+   * argument ran: `expected` is a `bigint`; a `bigint` is not JSON-serialisable, and
+   * `effect@3.22`'s `Logger.json` throws outright on one nested in an annotation
+   * value and loses the whole line with it; therefore filling `message` would push
+   * that value class into the field every renderer reaches for first.
+   *
+   * The measurement is true and stays load-bearing. The inference from it is a
+   * category error. `message` is typed `string`, and TEMPLATE INTERPOLATION of a
+   * `bigint` yields its decimal digits, so nothing downstream of this getter can see
+   * a `bigint` through it. The hazard is about the values handed to a LOGGER as
+   * ANNOTATIONS — which is exactly where the projection supervisor applies it, in
+   * `shouldRestart`, whose `position` annotation is `String(stored)` — and it says
+   * nothing whatever about a string rendered from one. Nor was the substitute the
+   * old argument offered a substitute: the supervisor's `position` annotation is the
+   * progress signal it RE-READ after the failure, not this expectation. Meanwhile
+   * the cost of the omission was real and was being paid on every `Cause.pretty` of
+   * a superseded commit.
+   *
+   * What the correction does NOT touch is the other ground this class states, which
+   * stands unchanged: no STORED position is carried, because the recovery path
+   * re-reads and a carried one would already be stale. That decision is about a
+   * RECOVERY INPUT — what a caller might wrongly resume from. This getter is a
+   * human-readable label over a field the class already carries, and `expected` is
+   * exactly as stale in the label as it is in the payload: a reader is being told
+   * what the guard expected, never what to resume from.
+   *
+   * A GETTER rather than a `message` field, so `expected` stays the single
+   * declaration. Why a prototype accessor is safe here, and why a structured log of
+   * this fault still emits the same `key`/`expected`/`_tag` it always did, are set
+   * out once for all four of these getters on `ProjectionStoreError` above.
+   */
+  get message() {
+    return `the stored checkpoint no longer equals the expectation (${this.expected})`;
+  }
+}
+/**
+ * Bind a `ProjectionStore` to one `CheckpointKey`, producing the surface a read
+ * model is actually given.
+ *
+ * A FREE FUNCTION rather than a method on `ProjectionStore`, decided that way for
+ * two reasons beyond the obvious one (a single implementation, which every present
+ * and future backend then gets for nothing rather than re-deriving — and could
+ * re-derive WRONGLY, since a `forKey` that closed over the wrong key would be
+ * invisible until two read models started trading cursors).
+ *
+ * The sharper reason is DECORATORS. Wrapping a store is an established move here —
+ * a test's never-committing view store, a durability override — and every one of
+ * them is written `{ ...inner, commit: … }`. Were `forKey` a method, that spread
+ * would copy the INNER store's own `forKey`, whose closure still points at the
+ * inner store, so `forKey(decorated, key)` would silently route straight past the
+ * decoration. As a free function it reads `store.commit` off the value it is
+ * handed, so a decorated store decorates.
+ *
+ * The second reason is the port's implementation burden: `ProjectionStore` stays
+ * three methods, which is what a backend has to get right, and no implementation
+ * can drift on a member that is pure derivation.
+ *
+ * `Effect.suspend` on the two no-argument members preserves the port's per-call
+ * construction timing exactly: an implementation is entitled to build its effect
+ * when its method is called (the SQL store binds parameters there), so suspending
+ * keeps `yield* view.readCheckpoint` indistinguishable from
+ * `yield* store.readCheckpoint(key)` rather than freezing one construction for the
+ * store's lifetime.
+ */
+export const forKey = (store, key) => ({
+  key,
+  durability: store.durability,
+  readCheckpoint: Effect.suspend(() => store.readCheckpoint(key)),
+  // Spelled out field by field rather than `{ key, ...args }`: the bound key is
+  // then the ONLY key in the call, which is the whole claim this façade makes, and
+  // no spread order or stray property can put a different one there.
+  commit: args => store.commit({
+    key,
+    expected: args.expected,
+    next: args.next,
+    viewWrites: args.viewWrites
+  }),
+  resetCheckpoint: Effect.suspend(() => store.resetCheckpoint(key))
+});
+//# sourceMappingURL=ProjectionStore.js.map

package/dist/esm/ProjectionStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectionStore.js","names":["Data","Effect","Schema","ProjectionId","String","pipe","nonEmptyString","brand","PartitionId","DEFAULT_PARTITION","make","checkpointKey","projection","partition","ProjectionStoreError","TaggedError","message","reason","CheckpointSuperseded","expected","forKey","store","key","durability","readCheckpoint","suspend","commit","args","next","viewWrites","resetCheckpoint"],"sources":["../../src/ProjectionStore.ts"],"sourcesContent":[null],"mappings":"AAsCA,SAASA,IAAI,EAAEC,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AAE7C;;;;;;;;;;AAUA,OAAO,MAAMC,YAAY,gBAAGD,MAAM,CAACE,MAAM,CAACC,IAAI,cAC5CH,MAAM,CAACI,cAAc,EAAE,eACvBJ,MAAM,CAACK,KAAK,CAAC,cAAc,CAAC,CAC7B;AAGD;;;;;;;;;;;;;;;AAeA,OAAO,MAAMC,WAAW,gBAAGN,MAAM,CAACE,MAAM,CAACC,IAAI,cAC3CH,MAAM,CAACI,cAAc,EAAE,eACvBJ,MAAM,CAACK,KAAK,CAAC,aAAa,CAAC,CAC5B;AAGD;AACA,OAAO,MAAME,iBAAiB,gBAAgBD,WAAW,CAACE,IAAI,CAAC,SAAS,CAAC;AA8BzE;;;;;AAKA,OAAO,MAAMC,aAAa,GAAGA,CAC3BC,UAAwB,EACxBC,SAAA,GAAyBJ,iBAAiB,MACvB;EAAEG,UAAU;EAAEC;AAAS,CAAE,CAAC;AAc/C;;;;;;;;;;;AAWA,OAAM,MAAOC,oBAAqB,sBAAQd,IAAI,CAACe,WAAW,CACxD,sBAAsB,CAItB;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgDA,IAAaC,OAAOA,CAAA;IAClB,OAAO,IAAI,CAACC,MAAM;EACpB;;AAGF;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAM,MAAOC,oBAAqB,sBAAQlB,IAAI,CAACe,WAAW,CACxD,sBAAsB,CAItB;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDA,IAAaC,OAAOA,CAAA;IAClB,OAAO,2DAA2D,IAAI,CAACG,QAAQ,GAAG;EACpF;;AAsMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,MAAMC,MAAM,GAAGA,CACpBC,KAAsB,EACtBC,GAAkB,MACQ;EAC1BA,GAAG;EACHC,UAAU,EAAEF,KAAK,CAACE,UAAU;EAC5BC,cAAc,EAAEvB,MAAM,CAACwB,OAAO,CAAC,MAAMJ,KAAK,CAACG,cAAc,CAACF,GAAG,CAAC,CAAC;EAC/D;EACA;EACA;EACAI,MAAM,EAASC,IAId,IACCN,KAAK,CAACK,MAAM,CAAC;IACXJ,GAAG;IACHH,QAAQ,EAAEQ,IAAI,CAACR,QAAQ;IACvBS,IAAI,EAAED,IAAI,CAACC,IAAI;IACfC,UAAU,EAAEF,IAAI,CAACE;GAClB,CAAC;EACJC,eAAe,EAAE7B,MAAM,CAACwB,OAAO,CAAC,MAAMJ,KAAK,CAACS,eAAe,CAACR,GAAG,CAAC;CACjE,CAAC","ignoreList":[]}

package/dist/esm/foldIntoRef.js

@@ -0,0 +1,29 @@
+import { composeProjections } from '@kairos-es/core';
+import { Ref } from 'effect';
+/**
+ * Build the per-batch `apply` for a read model whose whole view is `view`.
+ *
+ * `slices` must be the SAME record the read model's subscription query is derived
+ * from, so the events the runner delivers are exactly the events these folds
+ * expect; `composeProjections` gates each slice on its own query before
+ * dispatching, so a slice never sees an event it did not ask for.
+ *
+ * The returned effect is infallible (`E = never`) and requirement-free
+ * (`R = never`), which is the whole point: handed to `ProjectionStore.commit` as
+ * `viewWrites`, it adds nothing to the commit's error or requirement channels, so
+ * the ONLY way that commit can fail is the checkpoint guard.
+ */
+export const foldIntoRef = (slices, view) => {
+  // Composed ONCE, at wiring time, not per batch: the composition is pure and
+  // derives the merged query and the dispatch table, so rebuilding it on every
+  // batch would only burn allocations.
+  const composite = composeProjections(slices);
+  return batch =>
+  // One `Ref.update`, folding the whole batch inside the update function. Not a
+  // fold of `Ref.update`s: N updates are N observable states, so an interrupt or
+  // a concurrent reader could see the view half-way through a batch, and on a
+  // lost checkpoint guard a partly-applied batch would already be visible. One
+  // update makes the batch atomic in the same sense the checkpoint advance is.
+  Ref.update(view, state => batch.reduce((acc, decoded) => composite.evolve(acc, decoded), state));
+};
+//# sourceMappingURL=foldIntoRef.js.map

package/dist/esm/foldIntoRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foldIntoRef.js","names":["composeProjections","Ref","foldIntoRef","slices","view","composite","batch","update","state","reduce","acc","decoded","evolve"],"sources":["../../src/foldIntoRef.ts"],"sourcesContent":[null],"mappings":"AAqBA,SAEEA,kBAAkB,QAEb,iBAAiB;AAExB,SAAsBC,GAAG,QAAQ,QAAQ;AAEzC;;;;;;;;;;;;;AAaA,OAAO,MAAMC,WAAW,GAAGA,CACzBC,MAAS,EACTC,IAAgC,KAGN;EAC1B;EACA;EACA;EACA,MAAMC,SAAS,GAAGL,kBAAkB,CAACG,MAAM,CAAC;EAE5C,OAAQG,KAAK;EACX;EACA;EACA;EACA;EACA;EACAL,GAAG,CAACM,MAAM,CAACH,IAAI,EAAGI,KAAK,IACrBF,KAAK,CAACG,MAAM,CAAC,CAACC,GAAG,EAAEC,OAAO,KAAKN,SAAS,CAACO,MAAM,CAACF,GAAG,EAAEC,OAAO,CAAC,EAAEH,KAAK,CAAC,CACtE;AACL,CAAC","ignoreList":[]}

package/dist/esm/inMemoryProjectionStore.js

@@ -0,0 +1,131 @@
+/**
+ * The in-memory `ProjectionStore`: a `Ref` of checkpoints plus the exclusive
+ * critical section that makes the guarded advance atomic.
+ *
+ * This is NOT merely a test double. It is load-bearing for the in-process
+ * supervision restart, where the subscription dies (the event store's poll retry
+ * exhausted) but the process and its in-memory view survive: the restart must
+ * resume from the checkpoint rather than replay from `ORIGIN` into an
+ * already-populated view, and an ephemeral checkpoint stored beside an ephemeral
+ * view is exactly what makes that resume correct. It is also the whole
+ * all-in-memory permutation — tests, prototypes, client-side use — and the
+ * durable-log-with-in-memory-view mode's view store (dev, admin and in-flux
+ * slices, rebuilt from `ORIGIN` each boot).
+ *
+ * A factory `Effect`, deliberately not a `Layer`: the view store is selected PER
+ * MATERIALISATION — so a slice may start in memory and GRADUATE to Postgres, which
+ * `ReadModel.store` owns the claim about — and it is therefore a value handed to a
+ * read model, not a context tag that one store could claim process-wide.
+ *
+ * That selection is a FLOOR rather than a ceiling, and this store is on the common
+ * side of it: the two variants above are also available AT ONCE, an in-memory
+ * materialisation of a slice record beside a durable one from the SAME record —
+ * a Postgres table somebody queries with SQL, and an in-process view of the same
+ * slices holding one aggregate's hot figures with no round trip to reach them. That
+ * is `runProjections`, and every call of this factory is an independent store, so
+ * two materialisations wired that way share nothing but their slices. What they do
+ * not share is their FOLDS: each `apply` re-expresses one, so agreement between
+ * their figures is something a test demonstrates rather than something the wiring
+ * gives.
+ *
+ * The critical-section design mirrors `core`'s in-memory event store: one
+ * `Effect.makeSemaphore(1)` serialises the guarded advance, exactly as that store
+ * serialises check-then-append, and for the same reason — the check and the write
+ * must not be separable, and that atomicity IS the concurrency guarantee.
+ */
+import { ORIGIN } from '@kairos-es/core';
+import { Effect, Ref } from 'effect';
+import { CheckpointSuperseded } from "./ProjectionStore.js";
+/**
+ * Flatten a `CheckpointKey` into a map key.
+ *
+ * The separator is NUL. A `ProjectionId`/`PartitionId` is any non-empty string,
+ * so a printable separator (`:`, `/`, `|`) could be forged inside either half and
+ * two distinct keys would collide onto one checkpoint — one read model silently
+ * reading and advancing another's cursor. NUL cannot appear in a name any human
+ * or config file produces, so the flattening stays injective in practice without
+ * narrowing the id grammar.
+ *
+ * The other route to that same failure is a WIRING rather than a forged id: two
+ * materialisations handed this one store under equal keys, which would be two
+ * runners over one cursor. That one is caught before anything is forked, by the
+ * set-level collision rung of the construction gate in `projectionWiringFault.ts`,
+ * and its sentence names the two fixes. Nothing here can catch it — a store sees
+ * keys, never who is holding it.
+ */
+const mapKey = key => `${key.projection}\u0000${key.partition}`;
+/**
+ * Build an in-memory `ProjectionStore`.
+ *
+ * Every call is an independent store with its own checkpoints and its own
+ * semaphore, so two read models wired to two calls of this factory cannot
+ * interfere — and a test needing a fresh store just calls it again.
+ */
+export const makeInMemoryProjectionStore = /*#__PURE__*/Effect.gen(function* () {
+  const checkpoints = yield* Ref.make(new Map());
+  const mutex = yield* Effect.makeSemaphore(1);
+  /** The stored position, or `ORIGIN` for a key never committed. */
+  const positionOf = (stored, key) => stored.get(mapKey(key)) ?? ORIGIN;
+  const readCheckpoint = key =>
+  // No lock needed: `Ref.get` is a single atomic read, and the guard that
+  // actually protects a commit is re-checked INSIDE the critical section
+  // below — a value read here is only ever an expectation to be guarded on,
+  // never a licence to write.
+  Effect.map(Ref.get(checkpoints), stored => positionOf(stored, key));
+  const commit = args =>
+  // The permit is acquired INTERRUPTIBLY (a fibre waiting its turn can still
+  // be torn down), and only the section itself is uninterruptible.
+  mutex.withPermits(1)(Effect.uninterruptible(Effect.gen(function* () {
+    const stored = positionOf(yield* Ref.get(checkpoints), args.key);
+    // The guard is checked FIRST, before the view writes run. There is no
+    // transaction here to roll anything back, so the ONLY way a lost
+    // guard can leave the view untouched is to lose before touching it.
+    // Check-then-act is safe despite `viewWrites` suspending in between,
+    // because the section is exclusive: no other fibre can observe or
+    // advance this checkpoint until the permit is released, so the value
+    // read here cannot go stale within the section.
+    //
+    // On a lost guard `viewWrites` was NEVER RUN, which is observably
+    // identical to the SQL store's rollback — the port's abort contract
+    // is met by omission rather than by undo. (The one case omission
+    // cannot cover is a `viewWrites` that fails part-way, which is why
+    // the port requires a non-transactional store's per-batch write to be
+    // a single atomic effect; see `ProjectionStore` and `foldIntoRef`.)
+    if (stored !== args.expected) {
+      return yield* new CheckpointSuperseded({
+        key: args.key,
+        expected: args.expected
+      });
+    }
+    yield* args.viewWrites;
+    // Uninterruptibility earns its keep here: an interrupt landing
+    // between the view writes and this advance would commit the batch's
+    // effects with the cursor left behind, and the next run would apply
+    // the same batch a second time. Copy-on-write so a concurrent reader
+    // holding the previous map sees a consistent snapshot.
+    yield* Ref.update(checkpoints, current => new Map(current).set(mapKey(args.key), args.next));
+  })));
+  const resetCheckpoint = key =>
+  // Under the same permit as `commit`, so a reset can never interleave with a
+  // guarded advance and leave the map half-updated relative to the view.
+  // Deleting rather than storing `ORIGIN` keeps "never committed" and "reset"
+  // one state, which is what the port promises the read-back is.
+  mutex.withPermits(1)(Ref.update(checkpoints, current => {
+    const next = new Map(current);
+    next.delete(mapKey(key));
+    return next;
+  }));
+  // Annotated at the definition site rather than only through the exported
+  // signature, per the rule on `ProjectionStore` itself.
+  const store = {
+    // Dies with the process, which is the R2 input: an ephemeral view is legal
+    // over either an ephemeral or a durable log (it just re-catches-up), so
+    // this value never trips the durability-ordering check.
+    durability: 'ephemeral',
+    readCheckpoint,
+    commit,
+    resetCheckpoint
+  };
+  return store;
+});
+//# sourceMappingURL=inMemoryProjectionStore.js.map

package/dist/esm/inMemoryProjectionStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryProjectionStore.js","names":["ORIGIN","Effect","Ref","CheckpointSuperseded","mapKey","key","projection","partition","makeInMemoryProjectionStore","gen","checkpoints","make","Map","mutex","makeSemaphore","positionOf","stored","get","readCheckpoint","map","commit","args","withPermits","uninterruptible","expected","viewWrites","update","current","set","next","resetCheckpoint","delete","store","durability"],"sources":["../../src/inMemoryProjectionStore.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAASA,MAAM,QAAuB,iBAAiB;AACvD,SAASC,MAAM,EAAEC,GAAG,QAAQ,QAAQ;AAEpC,SAASC,oBAAoB,QAAQ,sBAAmB;AAExD;;;;;;;;;;;;;;;;;AAiBA,MAAMC,MAAM,GAAIC,GAAkB,IAChC,GAAGA,GAAG,CAACC,UAAU,SAASD,GAAG,CAACE,SAAS,EAAE;AAE3C;;;;;;;AAOA,OAAO,MAAMC,2BAA2B,gBACtCP,MAAM,CAACQ,GAAG,CAAC,aAAS;EAClB,MAAMC,WAAW,GAAG,OAAOR,GAAG,CAACS,IAAI,CACjC,IAAIC,GAAG,EAAE,CACV;EACD,MAAMC,KAAK,GAAG,OAAOZ,MAAM,CAACa,aAAa,CAAC,CAAC,CAAC;EAE5C;EACA,MAAMC,UAAU,GAAGA,CACjBC,MAAqC,EACrCX,GAAkB,KACLW,MAAM,CAACC,GAAG,CAACb,MAAM,CAACC,GAAG,CAAC,CAAC,IAAIL,MAAM;EAEhD,MAAMkB,cAAc,GAClBb,GAAkB;EAElB;EACA;EACA;EACA;EACAJ,MAAM,CAACkB,GAAG,CAACjB,GAAG,CAACe,GAAG,CAACP,WAAW,CAAC,EAAGM,MAAM,IAAKD,UAAU,CAACC,MAAM,EAAEX,GAAG,CAAC,CAAC;EAEvE,MAAMe,MAAM,GAAUC,IAKrB;EACC;EACA;EACAR,KAAK,CAACS,WAAW,CAAC,CAAC,CAAC,CAClBrB,MAAM,CAACsB,eAAe,CACpBtB,MAAM,CAACQ,GAAG,CAAC,aAAS;IAClB,MAAMO,MAAM,GAAGD,UAAU,CAAC,OAAOb,GAAG,CAACe,GAAG,CAACP,WAAW,CAAC,EAAEW,IAAI,CAAChB,GAAG,CAAC;IAEhE;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA,IAAIW,MAAM,KAAKK,IAAI,CAACG,QAAQ,EAAE;MAC5B,OAAO,OAAO,IAAIrB,oBAAoB,CAAC;QACrCE,GAAG,EAAEgB,IAAI,CAAChB,GAAG;QACbmB,QAAQ,EAAEH,IAAI,CAACG;OAChB,CAAC;IACJ;IAEA,OAAOH,IAAI,CAACI,UAAU;IAEtB;IACA;IACA;IACA;IACA;IACA,OAAOvB,GAAG,CAACwB,MAAM,CAAChB,WAAW,EAAGiB,OAAO,IACrC,IAAIf,GAAG,CAACe,OAAO,CAAC,CAACC,GAAG,CAACxB,MAAM,CAACiB,IAAI,CAAChB,GAAG,CAAC,EAAEgB,IAAI,CAACQ,IAAI,CAAC,CAClD;EACH,CAAC,CAAC,CACH,CACF;EAEH,MAAMC,eAAe,GAAIzB,GAAkB;EACzC;EACA;EACA;EACA;EACAQ,KAAK,CAACS,WAAW,CAAC,CAAC,CAAC,CAClBpB,GAAG,CAACwB,MAAM,CAAChB,WAAW,EAAGiB,OAAO,IAAI;IAClC,MAAME,IAAI,GAAG,IAAIjB,GAAG,CAACe,OAAO,CAAC;IAC7BE,IAAI,CAACE,MAAM,CAAC3B,MAAM,CAACC,GAAG,CAAC,CAAC;IACxB,OAAOwB,IAAI;EACb,CAAC,CAAC,CACH;EAEH;EACA;EACA,MAAMG,KAAK,GAAoB;IAC7B;IACA;IACA;IACAC,UAAU,EAAE,WAAW;IACvBf,cAAc;IACdE,MAAM;IACNU;GACD;EACD,OAAOE,KAAK;AACd,CAAC,CAAC","ignoreList":[]}

package/dist/esm/index.js

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

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["DurableEventLog","EphemeralEventLog","EventLogDurability","foldIntoRef","makeInMemoryProjectionStore","BatchSize","PipelineDied","CheckpointSuperseded","checkpointKey","DEFAULT_PARTITION","forKey","PartitionId","ProjectionId","ProjectionStoreError","projectionLayer","runProjection","runProjections","MaxNoProgressRestarts","ProjectionStalled"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgLA,SACEA,eAAe,EACfC,iBAAiB,EACjBC,kBAAkB,QACb,yBAAsB;AAC7B,SAASC,WAAW,QAAQ,kBAAe;AAC3C,SAASC,2BAA2B,QAAQ,8BAA2B;AACvE,SACEC,SAAS,EACTC,YAAY,QAIP,uBAAoB;AAC3B,SAEEC,oBAAoB,EACpBC,aAAa,EACbC,iBAAiB,EAEjBC,MAAM,EAENC,WAAW,EACXC,YAAY,EAEZC,oBAAoB,QACf,sBAAmB;AAC1B,SACEC,eAAe,EAEfC,aAAa,QACR,oBAAiB;AACxB,SAGEC,cAAc,QACT,qBAAkB;AACzB,SACEC,qBAAqB,EACrBC,iBAAiB,QAEZ,0BAAuB","ignoreList":[]}

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": []
+}