@kairos-es/read 0.0.0

package/src/ProjectionStore.ts

@@ -0,0 +1,528 @@
+/**
+ * `ProjectionStore` — the read side's single port: a scalar checkpoint plus the
+ * atomic bracket a read model's own view writes are committed INSIDE (ADR-0007).
+ *
+ * It is deliberately one port rather than two (a checkpoint store and a view
+ * store), because the whole exactly-once property of a projection is that the
+ * view write and the checkpoint advance land together or not at all. Splitting
+ * them would put the bracket in the caller's hands, and a forgotten bracket is
+ * silent: the view would commit without the checkpoint advancing and the next
+ * pass would apply the same batch again. So `commit` takes `viewWrites` as an
+ * ARGUMENT — the caller hands its writes in, the port owns the transaction — and
+ * there is no operation on this interface that advances a checkpoint outside it.
+ *
+ * The checkpoint is a SCALAR `Position`, not a set of processed positions and not
+ * a high-water mark with gap tracking. That is licensed by the store's
+ * exclusive-lock append (ADR-0002): id-allocation order equals commit order, so
+ * once a position is visible every lower position is either already visible or
+ * permanently absent. A reader may therefore process strictly ascending and
+ * treat an absent position as absent forever. Positions are compared, never
+ * arithmetic'd, and never assumed contiguous.
+ *
+ * The port is MULTI-KEY — every operation takes a `CheckpointKey` — because one
+ * `SqlClient` legitimately serves many read models, and a store must keep every
+ * key independent. One MATERIALISATION of a read model, however, has exactly ONE
+ * key, so it is handed the `KeyedProjectionStore` façade at the bottom of this
+ * module rather than the port itself: `forKey` binds a store to a key once, and from
+ * there no operation has a key to get wrong. Both surfaces are real and neither
+ * replaces the other. A read model may have SEVERAL materialisations, one per store;
+ * the `CheckpointKey` doc below says what that does and does not do to key
+ * uniqueness.
+ *
+ * This module is dependency-free by design — branded ids, two tagged errors, two
+ * interfaces and the one-line façade that relates them. `@kairos-es/read` ships the
+ * in-memory implementation (the rule being that the package defining a port ships
+ * that port's dependency-free implementation, as `core` does for the in-memory
+ * event store); every dependency-bearing backend is its own package.
+ */
+import type { Position } from '@kairos-es/core'
+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 = Schema.String.pipe(
+  Schema.nonEmptyString(),
+  Schema.brand('ProjectionId'),
+)
+export type ProjectionId = typeof ProjectionId.Type
+
+/**
+ * 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 = Schema.String.pipe(
+  Schema.nonEmptyString(),
+  Schema.brand('PartitionId'),
+)
+export type PartitionId = typeof PartitionId.Type
+
+/** The partition value every runner uses while sharding is cut (ADR-0007). */
+export const DEFAULT_PARTITION: PartitionId = PartitionId.make('default')
+
+/**
+ * What a checkpoint is stored under: the read model plus its partition.
+ *
+ * **A key is unique WITHIN ONE STORE**, and stating the scope is load-bearing
+ * rather than pedantic: without it, the uniqueness rule below points a reader at the
+ * opposite of the right answer for a read model materialised more than once. The
+ * scope is a consequence of R1 rather than a policy — the checkpoint is co-located
+ * with its view so the pair commits atomically, so a key is only ever resolved
+ * against the store holding it, and there is no global namespace to collide in.
+ *
+ * Two DIFFERENT read models never share a key in one store, and by R3 read models
+ * that share one subscription share one cursor and therefore ONE key — a composed
+ * bundle checkpoints as a unit and rebuilds as a unit. But ONE read model
+ * materialised in several stores SHARES one `ProjectionId` across them, which is
+ * what its single identity means, and which
+ * `@kairos-es/read-postgres`'s `test/courseRosterGraduation.test.ts` asserts as its
+ * acceptance criterion. Distinctness is forced only where two materialisations of
+ * one read model COHABIT a store, which is what `PartitionId` is for: two of them
+ * in one store under one key would be two runners over one cursor, each advancing
+ * the other's, and the read side's construction gate refuses that pairing rather
+ * than leaving it to be discovered — a rung only a multi-materialisation call can
+ * reach, a lone materialisation having no sibling to collide with.
+ */
+export interface CheckpointKey {
+  readonly projection: ProjectionId
+  readonly partition: PartitionId
+}
+
+/**
+ * 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: ProjectionId,
+  partition: PartitionId = DEFAULT_PARTITION,
+): CheckpointKey => ({ projection, partition })
+
+/**
+ * How far a store's state survives: `'ephemeral'` dies with the process,
+ * `'durable'` outlives it.
+ *
+ * Declared rather than inferred so that R2 — checkpoint durability must not
+ * EXCEED event-log durability — is checkable at construction instead of
+ * invisible at runtime. This type is the VIEW's half of that comparison;
+ * `EventLogDurability` is the log's, and `EventLogDurability.ts` is where R2's
+ * argument and the silent failure it prevents are written.
+ */
+export type Durability = 'ephemeral' | 'durable'
+
+/**
+ * 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 Data.TaggedError(
+  'ProjectionStoreError',
+)<{
+  readonly reason: string
+  readonly cause?: unknown
+}> {
+  /**
+   * `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.
+   */
+  override get message(): string {
+    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 Data.TaggedError(
+  'CheckpointSuperseded',
+)<{
+  readonly key: CheckpointKey
+  readonly expected: Position
+}> {
+  /**
+   * 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.
+   */
+  override get message(): string {
+    return `the stored checkpoint no longer equals the expectation (${this.expected})`
+  }
+}
+
+/**
+ * Where read models materialise: a checkpoint and the view it tracks, in one store
+ * so each pair can be committed atomically.
+ *
+ * Each such pair is ONE MATERIALISATION of a read model, and a read model may have
+ * several across several stores — which is why the `CheckpointKey` doc above scopes
+ * uniqueness to one store rather than globally, and why R1 is what forces that
+ * scope.
+ *
+ * **Multi-key on purpose, and NOT the surface a read model is given.** Every
+ * operation takes a `CheckpointKey`, because one store instance — one `SqlClient`,
+ * one connection pool — serves however many read models an application runs, and
+ * keeping their keys independent is a contract obligation the shared suite proves.
+ * One materialisation has exactly one key, though, so it is handed
+ * `forKey(store, key)` instead: see `KeyedProjectionStore` below for why the
+ * difference is structural rather than stylistic. Implement THIS interface; hand out
+ * THAT one.
+ *
+ * **Annotate an implementation at its DEFINITION site** — `const store:
+ * ProjectionStore = { … }`, rather than leaning on the factory's return type alone
+ * — so a drift from this interface is a compile error THERE, on the offending
+ * member, instead of an opaque mismatch at the export. Both shipped
+ * implementations do it and say so in one line; a new backend should too.
+ *
+ * **The contract a NON-TRANSACTIONAL implementation must honour.** A SQL store
+ * runs `commit` in a transaction, so a `viewWrites` that fails PART-WAY is rolled
+ * back whole. An in-memory store has no transaction and cannot undo the writes
+ * that already landed before the failure. That single divergence is discharged by
+ * a requirement on the CALLER of a non-transactional store rather than by
+ * capability tiers in the shared contract suite: the per-batch view write MUST be
+ * a single atomic effect — fold the batch purely, then perform ONE write (see
+ * `foldIntoRef`, which is exactly that shape). Under that requirement a part-way
+ * failure is unreachable, every implementation's observable behaviour is
+ * identical, and one suite tests them all with no per-backend exemptions. State
+ * it loudly at any site that hands a multi-write `apply` to an in-memory store:
+ * that, not the store, is the bug.
+ *
+ * R1 (atomicity) is what this interface IS. The atomic unit is the VIEW's own
+ * transaction and never the event log's, so a view in a DIFFERENT database from the
+ * log is still exactly-once: the checkpoint travels with the view, and re-reading
+ * the log from a position needs no transaction at all, being deterministic and
+ * side-effect-free.
+ *
+ * A view store offering no transaction at all — a search index, an object store, an
+ * HTTP API — cannot implement this interface honestly: there is nothing for the
+ * checkpoint advance to ride along inside, so such a view is at-least-once and its
+ * writes must be IDEMPOTENT. That is a different design and not this port, but it
+ * has a recommended shape, so it is written down rather than left to be
+ * rediscovered: make every write POSITION-KEYED so re-applying an event no-ops —
+ * in SQL terms an `INSERT … ON CONFLICT DO NOTHING` keyed by the event's position,
+ * and in a search index or an object store the same idea, the document or object
+ * key derived from the position so a replay overwrites itself instead of
+ * accumulating. The guarantee then degrades from exactly-once to "at least once,
+ * and twice is indistinguishable from once".
+ *
+ * It is RECOMMENDED rather than mandated (and no helper is shipped for it)
+ * because the library cannot force it: the position-keying lives in the read
+ * model's own rows, whose shape this port knows nothing about. Nothing here can
+ * check it, so the honest move is to document the pattern and say plainly that
+ * the obligation is the reader's.
+ */
+export interface ProjectionStore {
+  /**
+   * How far this store's state survives — the R2 input. Checked against the
+   * event log's durability at runner construction.
+   */
+  readonly durability: Durability
+
+  /**
+   * The stored position for `key`. A key that has never been committed reads
+   * back as `ORIGIN` (`0n`), so a fresh read model and a reset read model are
+   * indistinguishable and both simply catch up from the start of the log.
+   */
+  readonly readCheckpoint: (
+    key: CheckpointKey,
+  ) => Effect.Effect<Position, ProjectionStoreError>
+
+  /**
+   * Apply `viewWrites` and advance the checkpoint from `expected` to `next`
+   * ATOMICALLY: both land or neither does.
+   *
+   * The view writes are passed IN rather than the caller opening its own
+   * transaction, so the bracket cannot be forgotten and no path exists to a
+   * checkpoint advance outside it. `viewWrites` is an arbitrary `Effect`, so
+   * nothing that belongs in the same transaction is excluded — the caller's own
+   * statements join it through the same client — and its `E`/`R` pass straight
+   * through this signature untouched, so a projection keeps its own error and
+   * requirement types.
+   *
+   * Fails `CheckpointSuperseded` when the stored position no longer equals
+   * `expected`, and that failure ABORTS the whole commit: the view writes must
+   * have no observable effect afterwards. That abort is the exactly-once
+   * mechanism, so it is the one behaviour the shared contract suite proves
+   * against a known-broken store rather than assuming.
+   *
+   * `next` is used AS IS. It is the last processed event's position, never
+   * `expected + 1` or any other arithmetic: positions are strictly increasing but
+   * not gapless, so a jump is normal and an increment would be wrong.
+   */
+  readonly commit: <E, R>(args: {
+    readonly key: CheckpointKey
+    readonly expected: Position
+    readonly next: Position
+    readonly viewWrites: Effect.Effect<void, E, R>
+  }) => Effect.Effect<void, E | CheckpointSuperseded | ProjectionStoreError, R>
+
+  /**
+   * Return `key` to `ORIGIN`, so the next run catches up from the start of the
+   * log — the rebuild path.
+   *
+   * It resets the CHECKPOINT only, never the view: what a rebuild must do with
+   * existing rows (truncate them, or write into a fresh table and swap) is the
+   * read model's business, and the port has no idea what its rows are.
+   */
+  readonly resetCheckpoint: (
+    key: CheckpointKey,
+  ) => Effect.Effect<void, ProjectionStoreError>
+}
+
+/**
+ * A `ProjectionStore` BOUND to one `CheckpointKey`: the same three operations,
+ * with no key to pass and therefore none to get wrong.
+ *
+ * **Why this exists: an invariant that was convention is now structure.** "One
+ * materialisation, one key, one runner" (ADR-0007) was true of every wiring in this
+ * repo and of every wiring a reader would write, but nothing enforced it. A
+ * `ReadModel` carrying `key` and `store` as INDEPENDENT fields admits two DIFFERENT
+ * read models authored against the same key in one store, or one read model whose
+ * `apply` reads a neighbour's checkpoint, and neither is a type error — the mistake
+ * would surface as one projection silently advancing another's cursor, which is
+ * exactly the failure mode `ProjectionId` is branded to prevent at the level below.
+ * Binding the key to the store ONCE, at the wiring site, makes the pairing the only
+ * thing there is: `commit` no longer has a key argument, so there is no key to
+ * transpose, omit, or refresh from the wrong variable.
+ *
+ * **`runProjections` is the same move one level up, and the collision gate is what
+ * binding alone cannot reach.** Where this façade binds a key to a store, that
+ * function binds ONE slice record and ONE `ProjectionId` across N materialisations
+ * and does the `forKey` call per entry itself, so "one read model, N
+ * materialisations, one identity" stops being a convention too. What binding cannot
+ * catch is the one incoherence that is invisible AFTER it: two entries bound to the
+ * same store under equal keys are each a perfectly well-formed
+ * `KeyedProjectionStore`, and `forKey` deliberately does not expose the store it
+ * closed over, so nothing downstream can ask whether two of them are the same. That
+ * question is only answerable at the UNBOUND port, which is where
+ * the read side's construction gate asks it.
+ *
+ * It is a FAÇADE and not a replacement. The multi-key port underneath is a real
+ * requirement — one client serves many read models, and per-key independence is
+ * contract behaviour the shared suite proves against every backend — so `forKey`
+ * narrows a store for one consumer rather than narrowing the port for everyone.
+ *
+ * `readCheckpoint` and `resetCheckpoint` are Effect VALUES rather than
+ * zero-argument functions. An `Effect` is a lazy description, so a value is
+ * re-runnable and a no-argument call has nothing left to express; `yield*
+ * view.readCheckpoint` is then the whole operation, with no vestigial `()` to
+ * suggest an argument might one day return.
+ */
+export interface KeyedProjectionStore {
+  /**
+   * The key this store is bound to.
+   *
+   * Carried rather than dropped because the RUNNER still needs it: its log
+   * annotations and its `PipelineDied`/`ProjectionStalled` payloads name BOTH halves —
+   * an operator greps on `projection` and `partition` together — and its
+   * construction-time defect messages name at least the projection. That is the whole
+   * reason the pair travels as one value: an operator's first question about a stalled
+   * projection is which one, and in a store where two materialisations cohabit the
+   * partition is the half that answers it. It
+   * is exposed for READING; nothing here takes it as an argument, which is the
+   * point.
+   */
+  readonly key: CheckpointKey
+
+  /** The underlying store's durability — the R2 input, passed straight through. */
+  readonly durability: Durability
+
+  /** The stored position for this store's key. `ORIGIN` when never committed. */
+  readonly readCheckpoint: Effect.Effect<Position, ProjectionStoreError>
+
+  /**
+   * Apply `viewWrites` and advance this key's checkpoint from `expected` to
+   * `next` atomically — `ProjectionStore.commit` with the one argument a caller
+   * could get wrong already supplied.
+   */
+  readonly commit: <E, R>(args: {
+    readonly expected: Position
+    readonly next: Position
+    readonly viewWrites: Effect.Effect<void, E, R>
+  }) => Effect.Effect<void, E | CheckpointSuperseded | ProjectionStoreError, R>
+
+  /** Return this key to `ORIGIN` — the rebuild path, checkpoint only. */
+  readonly resetCheckpoint: Effect.Effect<void, ProjectionStoreError>
+}
+
+/**
+ * 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: ProjectionStore,
+  key: CheckpointKey,
+): KeyedProjectionStore => ({
+  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: <E, R>(args: {
+    readonly expected: Position
+    readonly next: Position
+    readonly viewWrites: Effect.Effect<void, E, R>
+  }): Effect.Effect<void, E | CheckpointSuperseded | ProjectionStoreError, R> =>
+    store.commit({
+      key,
+      expected: args.expected,
+      next: args.next,
+      viewWrites: args.viewWrites,
+    }),
+  resetCheckpoint: Effect.suspend(() => store.resetCheckpoint(key)),
+})

package/src/foldIntoRef.ts

@@ -0,0 +1,63 @@
+/**
+ * `foldIntoRef` — the folded-state read model's `apply`: fold a batch PURELY
+ * through `composeProjections`, then perform exactly ONE write.
+ *
+ * This is the shape the `ProjectionStore` port's single-atomic-effect requirement
+ * asks for, and it is why that requirement costs nothing. A non-transactional view
+ * store cannot roll back a `viewWrites` that fails part-way; a fold followed by a
+ * single `Ref.update` has no part-way to fail at — the fold is pure (it cannot
+ * fail, and it touches nothing observable) and the write is a single atomic step.
+ * So the one divergence between a transactional and a non-transactional
+ * `ProjectionStore` is unreachable for a read model written this way, which is
+ * what keeps the shared contract suite free of capability tiers.
+ *
+ * It is deliberately a thin helper over primitives that already exist rather than
+ * a new fold abstraction: the composition is `core`'s `composeProjections`, the
+ * slices are the codec's `projection().on().build()`, and this module only wires
+ * the two to a `Ref`. Nothing here is required — a read model with its own
+ * multi-statement SQL `apply` ignores it entirely and relies on the transaction
+ * instead. It is the RECOMMENDED `apply` for an in-memory view specifically.
+ */
+import type { SliceProjection } from '@kairos-es/codec'
+import {
+  type CompositeState,
+  composeProjections,
+  type DecodedEvent,
+} from '@kairos-es/core'
+import type { Array as Arr } from 'effect'
+import { type Effect, 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 = <T extends Record<string, SliceProjection>>(
+  slices: T,
+  view: Ref.Ref<CompositeState<T>>,
+): ((
+  batch: Arr.NonEmptyReadonlyArray<DecodedEvent>,
+) => Effect.Effect<void>) => {
+  // 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),
+    )
+}