@kairos-es/read 0.0.0

package/dist/dts/ProjectionStore.d.ts

@@ -0,0 +1,475 @@
+/**
+ * `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 { 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 declare const ProjectionId: Schema.brand<Schema.filter<typeof Schema.String>, "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 declare const PartitionId: Schema.brand<Schema.filter<typeof Schema.String>, "PartitionId">;
+export type PartitionId = typeof PartitionId.Type;
+/** The partition value every runner uses while sharding is cut (ADR-0007). */
+export declare const DEFAULT_PARTITION: PartitionId;
+/**
+ * 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 declare const checkpointKey: (projection: ProjectionId, partition?: PartitionId) => CheckpointKey;
+/**
+ * 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';
+declare const ProjectionStoreError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ProjectionStoreError";
+} & Readonly<A>;
+/**
+ * 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 declare class ProjectionStoreError extends ProjectionStoreError_base<{
+    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.
+     */
+    get message(): string;
+}
+declare const CheckpointSuperseded_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CheckpointSuperseded";
+} & Readonly<A>;
+/**
+ * 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 declare class CheckpointSuperseded extends CheckpointSuperseded_base<{
+    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.
+     */
+    get message(): string;
+}
+/**
+ * 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 declare const forKey: (store: ProjectionStore, key: CheckpointKey) => KeyedProjectionStore;
+export {};
+//# sourceMappingURL=ProjectionStore.d.ts.map

package/dist/dts/ProjectionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProjectionStore.d.ts","sourceRoot":"","sources":["../../src/ProjectionStore.ts"],"names":[],"mappings":"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"}

package/dist/dts/foldIntoRef.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `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, 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 declare const foldIntoRef: <T extends Record<string, SliceProjection>>(slices: T, view: Ref.Ref<CompositeState<T>>) => ((batch: Arr.NonEmptyReadonlyArray<DecodedEvent>) => Effect.Effect<void>);
+//# sourceMappingURL=foldIntoRef.d.ts.map

package/dist/dts/foldIntoRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foldIntoRef.d.ts","sourceRoot":"","sources":["../../src/foldIntoRef.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,KAAK,MAAM,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAA;AAEzC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACnE,QAAQ,CAAC,EACT,MAAM,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,KAC/B,CAAC,CACF,KAAK,EAAE,GAAG,CAAC,qBAAqB,CAAC,YAAY,CAAC,KAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAevB,CAAA"}

package/dist/dts/inMemoryProjectionStore.d.ts

@@ -0,0 +1,11 @@
+import { Effect } from 'effect';
+import type { ProjectionStore } from './ProjectionStore.js';
+/**
+ * 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 declare const makeInMemoryProjectionStore: Effect.Effect<ProjectionStore>;
+//# sourceMappingURL=inMemoryProjectionStore.d.ts.map

package/dist/dts/inMemoryProjectionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inMemoryProjectionStore.d.ts","sourceRoot":"","sources":["../../src/inMemoryProjectionStore.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,MAAM,EAAO,MAAM,QAAQ,CAAA;AACpC,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAuBvE;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,CAAC,eAAe,CA+FnE,CAAA"}