@kairos-es/codec 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/dts-esm/decision.d.ts

@@ -0,0 +1,161 @@
+/**
+ * `Unchanged`: a decision's answer when there is nothing to do because the work
+ * is already done, and the two types that let a decision say so without costing
+ * any existing caller its `Position`.
+ *
+ * ## Why a decision needs a third answer
+ *
+ * A decision had two answers: a non-empty batch of events to append, or a
+ * failure. The idempotent case fitted neither. A webhook redelivered after its
+ * first delivery was recorded, or a recorder re-running after a conflict whose
+ * winning write already closed the item, has nothing to append — and nothing
+ * WRONG has happened, so a failure is the wrong channel: a caller would have to
+ * tell "already done" from a genuine refusal by matching a tag, and a retry
+ * policy keyed on the error channel would retry a success. An empty batch is not
+ * the answer either. `append` refuses one as a defect, and the `Decider`'s
+ * `NonEmptyReadonlyArray` bound is what makes that refusal unreachable from a
+ * decision, a guarantee `decider.ts` calls load-bearing. So "already done" gets a
+ * value of its own, and it is a SUCCESS: an idempotent skip is never retried.
+ *
+ * ## Why it is recognised by a type id, and never by `instanceof` or a `_tag`
+ *
+ * This package ships dual ESM/CJS, so one consumer's graph can hold two copies of
+ * this module and therefore two distinct `Unchanged` classes. Under `instanceof`,
+ * a value built by one copy fails the other's check, and the runner would treat
+ * "already done" as a batch and hand it to `append` — the same single point of
+ * silent failure `@kairos-es/core` argues against, in its contract store, for
+ * `AppendConditionFailed`. That error falls back on its `_tag`, and a tag is
+ * enough there because the error channel is the library's own. A DECISION's
+ * success channel is not: an application's own union may well carry a member
+ * tagged `'Unchanged'`, and a runner that skipped on the bare tag would swallow
+ * that value and append nothing, silently. `Symbol.for` gives an identity that is
+ * shared across both builds (the global symbol registry is per runtime, not per
+ * module copy) and that no application value carries by accident. `isUnchanged`
+ * is the one test, and every runner in this package uses it.
+ *
+ * ## Why the widening is a defaulted type parameter, not a second entry point
+ *
+ * `Decider` gains a fifth type parameter `O`, defaulting to the non-empty batch.
+ * A second entry point would have meant a second `Decider`, a second runner, a
+ * second `transact` and a second `decideOnly` — against a surface whose whole
+ * argument is that `runDecider` and `decideOnly` are ONE pair.
+ *
+ * ## Why `DecisionResult` is shaped as it is, and why `decider` is overloaded
+ *
+ * The promise is that a decider or body that cannot answer `Unchanged` keeps
+ * exactly the `Position` result it had. Two kinds of success make that harder
+ * than it looks, and both were measured against call shapes that compiled
+ * before the widening.
+ *
+ * - An UNTYPED success. `any` satisfies every question a conditional can ask of
+ *   it: `Unchanged extends any` holds, and `any extends Unchanged` takes BOTH
+ *   branches. So a decision nobody typed would read as one that can answer
+ *   `Unchanged`, and its caller's `(position: Position) => …` would stop
+ *   compiling. `DecisionResult` therefore checks for `any` FIRST, and answers
+ *   `Position`.
+ * - A GENERIC success. In a wrapper generic in the success type
+ *   (`<A extends NonEmptyReadonlyArray<DcbEvent>, …>`), a conditional over `A`
+ *   stays DEFERRED, and a deferred conditional is `Position` only if the checker
+ *   can see that it must be. It can for one shape and not for the other:
+ *   `Unchanged extends O ? …` is related through the union of its two branches,
+ *   which admits `Unchanged`; `O extends Unchanged ? …`, DISTRIBUTIVE over `O`,
+ *   is related through itself instantiated at `O`'s bound — and at a bound of
+ *   the non-empty batch that is `Position`. So `DecisionResult` is written the
+ *   second way, and `runDecider` and `transact` keep ONE signature each, which
+ *   is what lets `body.pipe(transact(p))` still infer its error and requirement
+ *   channels; an overloaded step would lose both to `unknown`.
+ *
+ * `decider(…)` cannot be served by a conditional at all. Its `O` is derived from
+ * the SUCCESS of an effect type variable, and `Effect.Success` of a type
+ * variable is itself deferred, so a wrapper that copies `decider`'s own generics
+ * would get a `Decider` whose `O` nothing can resolve, and a runner result that
+ * is not `Position`. So `decider` is declared TWICE, which asks the question by
+ * ASSIGNABILITY instead: FIRST for an effect whose success is the non-empty
+ * batch, returning a `Decider` with the default `O`, and only then for any
+ * `DecisionOutput`, returning one whose `O` is `DecisionOutput`. A type
+ * variable bounded by the batch fits the first, and so does `any`; a `decide`
+ * with a branch answering `Unchanged` does not, and falls through to the second.
+ * Keep that ORDER: the checker takes the first declaration that fits, so
+ * swapped, every decider would be widened.
+ *
+ * Neither reaches a type QUERY. `ReturnType<typeof runDecider>` reads `O` at its
+ * bound, which admits `Unchanged`, so its success is widened; instantiated
+ * (`typeof runDecider<P, Command, E, R>`), `O` takes its default and the answer
+ * is `Position` again. `ReturnType<typeof decider<…>>` reads the LAST
+ * declaration, so it is the widened `Decider` whatever effect type it is given;
+ * a decider VALUE is typed by the declaration that fitted it.
+ *
+ * `DecisionOutput` still refuses a possibly-empty array — a `DcbEvent[]` from a
+ * `filter`, say — at compile time, because a plain array is neither non-empty nor
+ * `Unchanged`. The widening adds an answer; it removes no guarantee.
+ */
+import type { DcbEvent, Position } from '@kairos-es/core';
+import { type Array as Arr } from 'effect';
+/**
+ * The type id `isUnchanged` recognises. `Symbol.for`, so both halves of the dual
+ * build — and any two copies of this package in one graph — agree on it.
+ */
+export declare const UnchangedTypeId: unique symbol;
+/** The type of `UnchangedTypeId`. */
+export type UnchangedTypeId = typeof UnchangedTypeId;
+declare const Unchanged_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]; }>) => Readonly<A> & {
+    readonly _tag: "Unchanged";
+} & import("effect/Pipeable").Pipeable;
+/**
+ * "Nothing to do: this work is already done." A runner that receives it appends
+ * nothing and returns it in place of a `Position`.
+ *
+ * `reason` is for a human reading a trace or a test failure, and nothing in the
+ * library reads it. A `Data.TaggedClass`, so two values with the same reason are
+ * `Equal` and a test can compare them structurally.
+ *
+ * ⚠ Test for it with `isUnchanged`, never with `instanceof` or `_tag` — the
+ * module documentation says why each of those is wrong.
+ */
+export declare class Unchanged extends Unchanged_base<{
+    readonly reason?: string;
+}> {
+    readonly [UnchangedTypeId]: UnchangedTypeId;
+}
+/**
+ * Whether `u` is an `Unchanged`, by its type id. Total over `unknown`, and
+ * realm-safe across the dual ESM/CJS build. An application value that merely
+ * carries `_tag: 'Unchanged'` answers `false`, deliberately.
+ */
+export declare const isUnchanged: (u: unknown) => u is Unchanged;
+/**
+ * The constructors a `decide` step reaches for. One member today; it is a
+ * namespace object rather than a bare function so the call site reads as what it
+ * is, `Decision.unchanged('already dispatched')`.
+ */
+export declare const Decision: {
+    readonly unchanged: (reason?: string) => Unchanged;
+};
+/**
+ * Everything a decision may succeed with: a non-empty batch of events to
+ * append, or `Unchanged`. A plain, possibly-empty array is NOT a member, which is
+ * what keeps an empty batch unreachable from a decision.
+ */
+export type DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent> | Unchanged;
+/**
+ * What a runner returns for a decision that succeeds with `O`: `Position` unless
+ * `O` admits `Unchanged`, and `Position | Unchanged` when it does.
+ *
+ * Asked of each member of `O` — DISTRIBUTIVE — so a union `O` answers
+ * `Position | Unchanged` exactly when one of its members is `Unchanged`, a batch
+ * answers `Position` with no `| never` residue, and an `O` that is a type
+ * variable bounded by the batch is seen to be `Position`, which is what a
+ * wrapper generic in its success type needs. `O` that can ONLY be `Unchanged`
+ * answers `Unchanged`, the precise result and assignable wherever
+ * `Position | Unchanged` is expected.
+ *
+ * Two members are checked BEFORE the distribution, and both answer `Position`,
+ * the result each had before `Unchanged` existed. `any`, because a distributive
+ * conditional over `any` takes both branches and would widen every untyped
+ * decision. And `never` — a body that only ever fails — because distributing
+ * over `never` answers `never`, which a variable once typed with a `Position`
+ * result would no longer accept. The module documentation owns the rest.
+ */
+export type DecisionResult<O> = 0 extends 1 & O ? Position : [O] extends [never] ? Position : O extends Unchanged ? Unchanged : Position;
+export {};
+//# sourceMappingURL=decision.d.ts.map

package/dist/dts-esm/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../src/decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,KAAK,KAAK,IAAI,GAAG,EAAmB,MAAM,QAAQ,CAAA;AAE3D;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,MAEpC,CAAA;AAED,qCAAqC;AACrC,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAA;;;;AAEpD;;;;;;;;;;GAUG;AACH,qBAAa,SAAU,SAAQ,eAA8B;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC;IACA,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,eAAe,CAAkB;CAC9D;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,SACH,CAAA;AAE3C;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,SAAS,CAAA;CAGnD,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAC3C,QAAQ,GACR,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACjB,QAAQ,GACR,CAAC,SAAS,SAAS,GACjB,SAAS,GACT,QAAQ,CAAA"}

package/dist/dts-esm/decisionModel.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Read-and-fold over a slice record: read the composed query, decode each event
+ * through the matching def's `Schema` in an effectful `Stream.mapEffect` stage,
+ * then fold *purely* through core's `composeProjections`.
+ *
+ * TWO exports sit over that ONE body, the second expressed over the first.
+ * `modelAtHead` stops where the fold does, at `{ state, head }` — a
+ * materialisation of the record with no table, no checkpoint and no runner.
+ * `buildDecisionModel` adds the only part that is genuinely decision-specific:
+ * the `AppendCondition` (the DCB optimistic-concurrency contract). It is core's
+ * old `buildDecisionModel(Record<string, AnyProjection>)` surface, moved here
+ * because decode needs `Schema` + the `Serializer`.
+ *
+ * BOTH exports also record into the ambient read ledger when one is in context,
+ * which is what makes a decision that walks a chain of identifiers guard on every
+ * hop rather than on its last. Recording is `modelAtHead`'s, so it happens
+ * whatever symbol performed the read; outside a bracket there is no ledger,
+ * nothing is recorded and no behaviour changes. `readLedger.ts` owns the whole
+ * argument, including why the recorder is this module rather than a
+ * layered-only entry point of its own.
+ *
+ * The fold stays pure and in core; only the decode stage is effectful, and that
+ * stage lives in `decode.ts` — `decodeSlices` — so the read side folds a live
+ * `subscribe` stream through the *same* decode this module folds a bounded
+ * `read` stream through.
+ *
+ * The result requirement is exactly `DcbEventStore | Serializer | R`, where `R`
+ * is the union of the record's slices' requirements — inferred with no cast,
+ * `R` being carried covariantly by each slice's `schemas` map value type.
+ * `Serializer` is not yielded here: `decodeSlices` reads it from context itself,
+ * so the requirement arrives through the decode stage rather than through a
+ * binding this module owns (see `decode.ts` for why).
+ */
+import { type AppendCondition, type CompositeState, DcbEventStore, type Position } from '@kairos-es/core';
+import { Effect } from 'effect';
+import type { CodecError } from './errors.js';
+import type { SliceProjection } from './projection.js';
+import { type TaglessSliceInLedger } from './readLedger.js';
+import type { Serializer } from './Serializer.js';
+/** The union of requirements `R` carried by a record of `SliceProjection`s. */
+export type RequirementOf<T extends Record<string, SliceProjection>> = T[keyof T] extends SliceProjection<infer _S, infer R> ? R : never;
+/**
+ * Read the events for the composed slices' query, decode each through its def's
+ * `Schema`, fold into per-key state, and return `{ state, head }`: one slice
+ * record materialised at read time, with no table, no checkpoint and no runner.
+ *
+ * ## Why `head` comes back, and not bare `state`
+ *
+ * `head` is the consistency statement, and without it the state is a figure with
+ * no as-of — which is why the as-of is in the name. The fold stops at the
+ * position the read returned and is maintained no further, so `head` is the
+ * whole of what a caller can say about this state's currency: it is what lets
+ * the write path turn it into an `AppendCondition` (see `buildDecisionModel`),
+ * and what lets a read-time caller report, cache or compare a state against a
+ * position rather than against a wall clock.
+ *
+ * It is also the inversion worth naming out loud, because intuition runs the
+ * other way. A MAINTAINED view is consistent as of its CHECKPOINT, which trails
+ * the log's head by however far behind its runner is; this fold is consistent as
+ * of the head itself. So of two materialisations of one slice record, the one
+ * with no table, no checkpoint and no runner is the MOST current, and the table
+ * beside it is the stale one. Reach for a maintained view for the queries a
+ * single fold cannot serve — across many identities, ordered, joined, paginated
+ * — and never because it is fresher, because it is not.
+ *
+ * ⚠ AND INSIDE A BRACKET IT IS NOT THE FLOOR THE APPEND WILL USE. Everything
+ * above is a statement about THIS read, and it stays true; what changes is that a
+ * bracket guards on the EARLIEST head across every hop it walked, which on any hop
+ * after the first is a strictly lower number than the one returned here. So a
+ * caller who reads `head` inside a bracket and reasons about what the append will
+ * refuse is reasoning from the wrong figure — the guard is wider than this head
+ * says. Nothing here is wrong; the trap is assuming the two are the same number,
+ * and it is named because it is exactly the assumption that holds outside a
+ * bracket and quietly stops holding inside one. `readLedger.ts` owns the floor.
+ *
+ * `head` is LOG-GLOBAL: it is the head the store's `read` returned, so it moves
+ * for an event no slice here selects. `test/decisionModel.test.ts` pins that
+ * behaviour EXPLICITLY, over four appended events one of which the composed query
+ * excludes by tag; `test/modelAtHead.test.ts` pins it incidentally, its own head
+ * assertion landing on that same excluded event's position. Two guards, one of them
+ * deliberate — reach for the explicit one when the property itself is what changes.
+ * Log-global neither tightens nor loosens the derived guard — there can be no
+ * event matching the query between the query's last match and the log head, so a
+ * query-filtered head would refuse exactly the same appends — which is precisely
+ * why the store's own figure is the one to carry: one fact about the log, not a
+ * per-query derivation, and the honest as-of for a state folded from everything
+ * the query selected up to it.
+ *
+ * ## Why this lives in the codec and not in `@kairos-es/read`
+ *
+ * In `@kairos-es/read` it would be the only export touching none of that
+ * package's machinery: no checkpoint, no `EventLogDurability` (R2 is vacuous
+ * where there is no checkpoint to outlive the log), no rung of that package's
+ * construction gate, and none of its test apparatus. The vocabulary is already
+ * this package's — ADR-0004 names the typed slice path's clients as "a decision
+ * model / materialisation / command" — and the body is `buildDecisionModel`'s,
+ * which is here for the reason the module doc gives.
+ */
+export declare const modelAtHead: <T extends Record<string, SliceProjection>>(projections: T) => Effect.Effect<{
+    readonly state: CompositeState<T>;
+    readonly head: Position;
+}, CodecError | TaglessSliceInLedger, DcbEventStore | Serializer | RequirementOf<T>>;
+/**
+ * The write side's decision model: `modelAtHead` plus the `AppendCondition` that
+ * reuses the read query as `failIfEventsMatch` and the read head as `after` (the
+ * DCB optimistic-concurrency contract).
+ *
+ * It is expressed OVER `modelAtHead` rather than beside it, and that is the point
+ * of the pair. Two functions reading, decoding and folding a slice record almost
+ * identically would need two sets of tests and would be free to drift on the
+ * decode stage, on the cast recovering `CompositeState<T>`, or on which record
+ * the query is composed from. Re-expressing makes this a decomposition instead
+ * of a near-duplicate: `modelAtHead` is the shared part, this function is the
+ * condition and nothing else, and each is shorter than the one function was.
+ *
+ * Outside a bracket `composeProjections` therefore runs twice for one command —
+ * once inside `modelAtHead` for the read, once here for `failIfEventsMatch` — and
+ * that is deliberate rather than waste. It is a pure derivation of the record, so
+ * the two queries cannot disagree however either call site changes. The
+ * alternative, returning the query from `modelAtHead`, would put a third field on
+ * a READ-TIME API that no read-time caller wants, to save one pure merge over a
+ * handful of slices; a surface paying for a body's convenience is the worse
+ * trade. Inside a bracket the second merge is not reached at all: the ledger's
+ * own derivation composes every recorded hop instead.
+ *
+ * ## How to attribute the read, the decode and the fold — the rule, stated once
+ *
+ * Because this function is expressed OVER `modelAtHead`, prose about the codec
+ * splits into two kinds and only one of them may name this symbol:
+ *
+ * - Naming this function as the ENTRY POINT a caller invokes, or as the path
+ *   something is reached THROUGH, is correct — "the `buildDecisionModel` fold", "the
+ *   write path reaches decode through `buildDecisionModel`". Transitive reach is real
+ *   reach, and this is the symbol a command actually calls.
+ * - Naming it as the function that CONTAINS the read, the decode or the fold is
+ *   FALSE. All three are `modelAtHead`'s; this body adds an `AppendCondition` and
+ *   nothing else.
+ *
+ * Worth writing down because the distinction is invisible from a call site and the
+ * mistake is systematic rather than careless: every such claim was TRUE before
+ * `modelAtHead` was extracted from here, so a doc written against the older shape
+ * reads perfectly and is wrong. The correction is to name `modelAtHead`, never to
+ * soften the sentence.
+ */
+export declare const buildDecisionModel: <T extends Record<string, SliceProjection>>(projections: T) => Effect.Effect<{
+    readonly state: CompositeState<T>;
+    readonly appendCondition: AppendCondition;
+}, CodecError | TaglessSliceInLedger, DcbEventStore | Serializer | RequirementOf<T>>;
+//# sourceMappingURL=decisionModel.d.ts.map

package/dist/dts-esm/decisionModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisionModel.d.ts","sourceRoot":"","sources":["../../src/decisionModel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,cAAc,EAEnB,aAAa,EACb,KAAK,QAAQ,EACd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,MAAM,EAAkB,MAAM,QAAQ,CAAA;AAE/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,+EAA+E;AAC/E,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,IACjE,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,eAAe,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACnE,aAAa,CAAC,KACb,MAAM,CAAC,MAAM,CACd;IAAE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,EAC9D,UAAU,GAAG,oBAAoB,EACjC,aAAa,GAAG,UAAU,GAAG,aAAa,CAAC,CAAC,CAAC,CA6C3C,CAAA;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAC1E,aAAa,CAAC,KACb,MAAM,CAAC,MAAM,CACd;IACE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,CAAA;IACjC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;CAC1C,EACD,UAAU,GAAG,oBAAoB,EACjC,aAAa,GAAG,UAAU,GAAG,aAAa,CAAC,CAAC,CAAC,CA6B3C,CAAA"}

package/dist/dts-esm/decode.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The shared decode stage: the wire-bytes -> typed-payload half of the codec
+ * seam, lifted out of `buildDecisionModel` into a `Stream` combinator so every
+ * consumer of a slice record decodes through *one* implementation.
+ *
+ * Two consumers, one stage. `modelAtHead` folds a bounded `read` stream into
+ * decision state, which is how `buildDecisionModel` gets one; the read side folds
+ * an unbounded `subscribe` stream into a materialised view. They differ in
+ * everything *downstream* of decode (bounded vs live, a pure fold vs a
+ * transactional commit) and in nothing upstream of it — same slice record, same `type -> Schema` lookup, same
+ * `Serializer`, same failure taxonomy — so decode is exactly where the seam
+ * belongs. Duplicating it would let the two paths drift: a read side with its
+ * own copy could silently accept an event the decision path rejects, or reword
+ * a `CodecError` reason, and nothing would catch it.
+ *
+ * Why a `Stream` combinator rather than an `Effect` over a materialised array:
+ * decode must stay back-pressured. `Stream.mapEffect` with no `concurrency`
+ * option decodes one event at a time, pulling only as fast as the consumer
+ * folds, and that is what lets a projection catch up over a backlog far larger
+ * than memory.
+ *
+ * Be precise about what adding `concurrency` here would and would not cost,
+ * because the obvious reason is the wrong one. Effect's `mapEffect` is
+ * order-PRESERVING even when concurrent — reordering needs the separate
+ * `unordered: true` option (verified against `effect@4`'s `Channel.mapEffect`,
+ * which takes the ordered path unless that option is set) — so a bare
+ * `concurrency` would NOT hand the fold its events out of position order. What
+ * it would actually cost is the back-pressure above, and it would run
+ * application-authored `Schema` transforms (an ADR-0004 decryption hook, say)
+ * concurrently, which their authors have no reason to expect. `unordered: true`
+ * is the option that would be an outright correctness bug against an
+ * order-sensitive fold. Sequential is the right default for both reasons; the
+ * order argument alone does not carry it.
+ *
+ * Why these failures are values and not defects: corrupt bytes, an absent
+ * schema and a `Schema` mismatch are *data* problems an application can
+ * legitimately handle (quarantine the event, fail the command, alert), so they
+ * belong on the error channel as `CodecError` — see `errors.ts`. The three
+ * `reason` strings are observable surface; treat them as fixed, not cosmetic.
+ *
+ * Two of those three are no longer this module's to reword. `deserialise` and
+ * `decode` are fixed in `deserialiseThenDecode`, the two-step this stage shares
+ * with the general (registry) path, precisely so that a claim about surface has
+ * ONE implementation behind it rather than a copy per path. The absent-schema
+ * reason stays here, because the two paths deliberately disagree about what a
+ * lookup miss means — `UnknownEventType` there, ADR-0005 — and that helper's doc
+ * carries the argument.
+ */
+import type { DecodedEvent, SequencedEvent } from '@kairos-es/core';
+import { Stream } from 'effect';
+import type { RequirementOf } from './decisionModel.js';
+import { CodecError } from './errors.js';
+import type { SliceProjection } from './projection.js';
+import { Serializer } from './Serializer.js';
+/**
+ * The public decode stage: give it the slice record, get back a `Stream`
+ * combinator that decodes every event those slices can handle.
+ *
+ * **Why one call rather than two.** The lookup and the stage were briefly two
+ * public symbols — merge the record, then hand the map to the stage — and every
+ * consumer in the repo composed them in exactly that order and did nothing else
+ * with the intermediate map. A two-step protocol with one legal composition is
+ * not flexibility, it is a way to get it wrong: a caller can merge the wrong
+ * record, or a record that is not the one its `Query` was composed from, and
+ * that second mistake is silent. In the read side it would decode a live
+ * subscription against schemas the subscription never selects — every event
+ * arriving would fail `no schema for event type`, framed as a data problem when
+ * it is a wiring one. Taking the slices directly removes the intermediate value
+ * a caller could substitute, so the schemas provably come from the same record
+ * the query does.
+ *
+ * **Still curried, deliberately.** The merge is a pure derivation of the slice
+ * record, so both consumers build the stage ONCE — per decision model, per read
+ * model — and reuse it across every stream they drive. Rebuilding the table per
+ * stream (let alone per restart) would only burn allocations, and the currying
+ * is what makes "built once" the natural way to call this rather than a
+ * discipline.
+ *
+ * **It can REFUSE the record**, and does so the moment it is called rather than
+ * once events are flowing: a type reachable from two slices under two DIFFERENT
+ * `Schema`s throws, in the same words `makeRegistry` uses. See
+ * `mergeSliceSchemas` for the rule, why reference equality is its discriminator
+ * and why a throw is the right mechanism. Both in-repo consumers call this
+ * before there is a stream to fail, so inside their `Effect.gen`s the refusal is
+ * a defect at construction.
+ *
+ * `RequirementOf<T>` surfaces in the result's `R`, so a slice whose `Schema`
+ * carries a requirement (an application-authored decryption transform, ADR-0004)
+ * propagates it to the caller with no cast at the call site.
+ */
+export declare const decodeSlices: <T extends Record<string, SliceProjection>>(slices: T) => (<E, R>(events: Stream.Stream<SequencedEvent, E, R>) => Stream.Stream<DecodedEvent, E | CodecError, R | RequirementOf<T> | Serializer>);
+//# sourceMappingURL=decode.d.ts.map

package/dist/dts-esm/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AACnE,OAAO,EAAuB,MAAM,EAAE,MAAM,QAAQ,CAAA;AAIpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAoJzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACpE,QAAQ,CAAC,KACR,CAAC,CAAC,CAAC,EAAE,CAAC,EACP,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,EAAE,CAAC,CAAC,KACxC,MAAM,CAAC,MAAM,CAChB,YAAY,EACZ,CAAC,GAAG,UAAU,EACd,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAClC,CAA4C,CAAA"}

package/dist/dts-esm/deserialiseThenDecode.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The two-step every decode in this package performs, in one implementation:
+ * deserialise the wire bytes through the `Serializer` its caller already holds,
+ * then `Schema.decodeUnknownEffect` the result, each half's failure wrapped as the
+ * `CodecError` whose `reason` says WHICH half failed.
+ *
+ * **What it is the single home of.** The two `reason` strings `'deserialise'`
+ * and `'decode'`, and their ORDER. Why those strings are observable surface —
+ * fixed rather than cosmetic, because an application quarantines an event,
+ * alerts or fails a command off them — is argued in `decode.ts`'s module doc and
+ * is not restated here. What this module adds is that the argument had TWO
+ * implementations standing behind it: the slice stage (`decodeEvents`) and the
+ * general/registry path (`makeRegistry`'s `decode`) each wrote the pair out, in
+ * one package, and only the slice copy was pinned by a test. A reworded `reason`
+ * on the registry path would have been caught by nothing. Sharing the step
+ * DELETES that drift channel rather than alarming it, which is why this exists
+ * as a function and not as a second test.
+ *
+ * **The order is contract, not accident.** Deserialise has to run first because
+ * `Schema.decodeUnknownEffect` has nothing to read until it has, and the observable
+ * consequence is that the two reasons PARTITION the causes an operator acts on:
+ * rotten bytes are always `'deserialise'` and never `'decode'`, so a storage or
+ * producer problem never arrives dressed as schema drift. Swapping the labels
+ * would not break a decode; it would send every incident to the wrong team.
+ *
+ * **Why a `Serializer` VALUE rather than reading the tag here.** The two callers
+ * acquire it at deliberately different moments and this step must not flatten
+ * that. `decodeEvents` reads it ONCE when the stream starts (`Stream.unwrap`), so
+ * a backlog of a million events does not re-read context per event; the
+ * registry's `decode` is a per-event `Effect` and yields it inside its own
+ * `Effect.gen`. Taking the resolved service preserves both, and keeps
+ * `Serializer` off this signature's `R`, so the requirement stays declared where
+ * the acquisition actually happens — which is where a reader goes looking for it.
+ *
+ * **Why the LOOKUP is not folded in**, though both callers do one immediately
+ * before calling this: the two paths disagree about what a miss MEANS, and the
+ * disagreement is deliberate. The slice path fails `CodecError` with
+ * `no schema for event type '<type>'` — a caller named the type and the record it
+ * supplied has no entry for it, so the wiring is wrong. The registry path fails
+ * `UnknownEventType` — the type arrived off the WIRE and the registry does not
+ * know it, which is ADR-0005 decode-totality and the one fault a rolling
+ * deployment is EXPECTED to meet. `errors.ts` argues why those two sentences stay
+ * greppable apart. Folding the lookup in would mean a per-caller miss
+ * constructor: a second seam, bought to share the one thing the two paths
+ * genuinely do not have in common.
+ *
+ * `R` is the SCHEMA's requirement, propagated untouched — an ADR-0004 decryption
+ * transform reaches the caller's `R` through here with no cast. The three
+ * parameters are positional because their types are mutually unassignable, so a
+ * transposed call is a compile error rather than a silent inversion.
+ *
+ * PACKAGE-INTERNAL: exported to its two callers and no further, deliberately
+ * absent from `index.ts`. It is a shared step, not a capability on offer — a
+ * consumer holding bytes and a `Schema` wants `decodeSlices` or a `Registry`,
+ * both of which do the lookup this one refuses to.
+ */
+import type { Context } from 'effect';
+import { Effect, Schema } from 'effect';
+import { CodecError } from './errors.js';
+import type { Serializer } from './Serializer.js';
+export declare const deserialiseThenDecode: <R>(serializer: Context.Service.Shape<typeof Serializer>, schema: Schema.Decoder<unknown, R>, bytes: Uint8Array) => Effect.Effect<unknown, CodecError, R>;
+//# sourceMappingURL=deserialiseThenDecode.d.ts.map

package/dist/dts-esm/deserialiseThenDecode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialiseThenDecode.d.ts","sourceRoot":"","sources":["../../src/deserialiseThenDecode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,eAAO,MAAM,qBAAqB,GAAI,CAAC,EACrC,YAAY,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,EACpD,QAAQ,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAClC,OAAO,UAAU,KAChB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,CAUpC,CAAA"}

package/dist/dts-esm/errors.d.ts

@@ -0,0 +1,80 @@
+declare const CodecError_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: "CodecError";
+} & Readonly<A>;
+/** A serialisation or `Schema` decode/encode failure on the codec path. */
+export declare class CodecError extends CodecError_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 `CodecError` stringifies to `'CodecError'`, and the sentence
+     * naming the schema, the event type or the missing key that failed reaches a log
+     * line only where the code doing the logging knows to reach in for `reason`.
+     * Filled, `Error.prototype.toString` yields `'CodecError: <reason>'`, which is
+     * what `Cause.pretty` (it reads `message` off anything `instanceof Error`) and the
+     * read side's projection supervisor both report — neither of them holding a table
+     * of this class's fields to keep in step with it.
+     *
+     * This class is on the package's PUBLISHED surface, so be exact about what the
+     * field moves. Everything that renders the error for a HUMAN: `String(err)`,
+     * `Cause.pretty` and therefore a failed fibre's `cause` annotation on every
+     * shipped logger, and an unhandled failure's report. Nothing that renders it for
+     * a MACHINE: `Data.Error` overrides `YieldableError`'s `toJSON` with
+     * `{ ...plainArgs, ...this }` — own enumerables plus the constructor args, and a
+     * prototype accessor is neither — so `JSON.stringify(err)` still emits the same
+     * `reason`/`_tag` and a structured log of a raw `CodecError` keeps its shape.
+     *
+     * A GETTER rather than a second field, so `reason` stays the single declaration.
+     * It is visible because `Data.TaggedError`'s constructor is
+     * `super(args?.message, …)` followed by copying the args' own enumerable keys
+     * onto the instance (verified against `effect@4`'s `internal/core.ts`): the
+     * args above carry no `message`, so nothing shadows this prototype accessor
+     * with an own property.
+     */
+    get message(): string;
+}
+declare const UnknownEventType_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: "UnknownEventType";
+} & Readonly<A>;
+/** A wire event whose runtime type string is outside the registry's known set. */
+export declare class UnknownEventType extends UnknownEventType_base<{
+    readonly type: string;
+}> {
+    /**
+     * The offending type, in a sentence saying what the registry did with it — so the
+     * fault renders ITSELF, exactly as `CodecError` above does.
+     *
+     * `Data.TaggedError` sets `name` to the tag and leaves `message` empty, so without
+     * this a decode that met an unregistered type stringifies to `'UnknownEventType'`
+     * — the one datum that makes the failure actionable, the type string itself,
+     * reaching a log line only where the logging code knows to reach in for `type`.
+     * Filled, `Error.prototype.toString` yields the tag followed by
+     * `event type 'nope.v1' is not in the registry`, which is what `Cause.pretty`
+     * prints and what an operator greps for. It matters here in particular because
+     * this class is the home of ADR-0005 decode-totality: a wire event outside the
+     * registered set is the expected consequence of a deployment reading a log a newer
+     * writer has extended, and the first question is always WHICH type — which the tag
+     * alone cannot answer.
+     *
+     * The wording deliberately differs from `CodecError`'s. That one says there is no
+     * schema for a type, and is raised on the TYPED path, where a caller named the
+     * type and the schema map it supplied has no entry for it. This one is the general
+     * (registry) path, where the type arrived off the WIRE and the registry is what
+     * does not know it. Distinct sentences keep the two greppable apart, which a
+     * shared phrasing would cost for nothing.
+     *
+     * A GETTER rather than a second field, so `type` stays the single declaration.
+     * What filling this field reaches, what it deliberately leaves untouched, and why
+     * a prototype accessor is visible at all are argued once on `CodecError` above and
+     * not restated here — it is the same package, the same published surface and the
+     * same mechanism, and two copies of that paragraph would be two things to keep in
+     * step. The read side's four getters point at one home for the identical reason.
+     */
+    get message(): string;
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/dts-esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAgBA,2EAA2E;AAC3E,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;;;;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,sBAAqC;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB,CAAC;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF"}