@kairos-es/codec 0.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Neverbland
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,46 @@
+# @kairos-es/codec
+
+Schema-first codec with an encryption seam for kairos-es (ADR-0004).
+
+The typed-payload to opaque-bytes seam: `event(type, fields, tagsFor)` defines a
+tagged `Schema` together with the mapper that derives an event's tags from its own
+payload (ADR-0006); `projection(init).on(def, fold)…build()` builds the slices a
+decision model or a read model folds through; `modelAtHead(slices)` reads, decodes
+through each def's `Schema`, and folds purely, returning `{ state, head }`;
+`buildDecisionModel(slices)` is that same read plus the `AppendCondition` a write
+needs; and `toEvent` produces a wire event (encode, serialise, tags derived, clock
+and uuid from services).
+
+`modelAtHead` is the read side's third materialisation KIND — checkpoint-free and
+read-time, no table, no runner, nothing maintained — and `head` is its consistency
+contract: it is current as of the position its own read returned, which a maintained
+view's checkpoint necessarily trails. So it is MORE current than any table of the
+same slices, and reaching for a maintained view is about the queries a single fold
+cannot serve, never about freshness. It lives here rather than in `@kairos-es/read`
+because it touches none of that package's machinery, and it is deliberately not what
+a decider calls: `runDecider` already folds to head through `buildDecisionModel`,
+under the condition that read produces.
+
+`decodeSlices(slices)` is the decode stage `modelAtHead` folds through, and so in turn
+the one `buildDecisionModel` gets by building on `modelAtHead` — exported so the read
+side's `ProjectionRunner` shares one implementation over a live `subscribe` stream
+rather than reimplementing it. `makeRegistry(defs)` is the minimal general
+path, decoding an arbitrary wire event by its runtime type string with an unknown
+type as a typed `UnknownEventType` (ADR-0005).
+
+`Decider` and `runDecider(decider, command)` close the write side's whole command
+cycle over that fold: build the decision model, decide, append under the read's
+own condition. `decider(projections, decide)` builds one with its slice record,
+its error union and its extra requirement all inferred — the command type, on the
+`projections` parameter, is the only annotation a caller writes. They live here,
+beside the `buildDecisionModel` they drive, rather
+than in `@kairos-es/testing` — nothing in them is test apparatus, and that
+package peers `@effect/vitest`, which a production command handler must not pull
+into its module graph. Wrap the call in `core`'s `retryOnConflict` to retry a
+conflict correctly (ADR-0008).
+
+Serialisation is a pluggable `Serializer`, JSON by default. Encryption is an
+**application**-authored `Schema` transform on a payload field: the codec owns no
+cipher and imports no `node:crypto`, it only propagates the transform's
+requirement and error channels. Platform-neutral; `@kairos-es/core` and `effect`
+are peer dependencies.

package/dist/cjs/Serializer.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SerializerDefault = exports.Serializer = void 0;
+var _effect = require("effect");
+/**
+ * The pluggable serialiser: the `Uint8Array` <-> value boundary applied
+ * *outside* `Schema`. Encode is `Schema.encode` then `serialise`; decode is
+ * `deserialise` then `Schema.decodeUnknown`. Both codec paths read the same
+ * `Serializer` from context, so encode and decode cannot mismatch; swapping
+ * JSON for msgpack is a different layer with no schema or call-site changes.
+ *
+ * `deserialise` may throw synchronously (corrupt bytes): wrapping it as a
+ * `CodecError` is the *caller's* concern — every decode site wraps it in
+ * `Effect.try`. Keeping the service interface plain (no Effect) lets a layer be
+ * a trivial `Layer.succeed`.
+ */
+
+class Serializer extends /*#__PURE__*/_effect.Context.Tag('@kairos-es/codec/Serializer')() {}
+exports.Serializer = Serializer;
+const encoder = /*#__PURE__*/new TextEncoder();
+const decoder = /*#__PURE__*/new TextDecoder();
+/**
+ * The shipped default: JSON over UTF-8. `serialise` = `JSON.stringify` then
+ * `TextEncoder`; `deserialise` = `TextDecoder` then `JSON.parse` (which throws
+ * synchronously on corrupt bytes, wrapped to `CodecError` at the call site).
+ */
+const SerializerDefault = exports.SerializerDefault = /*#__PURE__*/_effect.Layer.succeed(Serializer, {
+  serialise: v => encoder.encode(JSON.stringify(v)),
+  deserialise: b => JSON.parse(decoder.decode(b))
+});
+//# sourceMappingURL=Serializer.js.map

package/dist/cjs/Serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.js","names":["_effect","require","Serializer","Context","Tag","exports","encoder","TextEncoder","decoder","TextDecoder","SerializerDefault","Layer","succeed","serialise","v","encode","JSON","stringify","deserialise","b","parse","decode"],"sources":["../../src/Serializer.ts"],"sourcesContent":[null],"mappings":";;;;;;AAYA,IAAAA,OAAA,GAAAC,OAAA;AAZA;;;;;;;;;;;;;AAcM,MAAOC,UAAW,sBAAQC,eAAO,CAACC,GAAG,CAAC,6BAA6B,CAAC,EAMvE;AAAAC,OAAA,CAAAH,UAAA,GAAAA,UAAA;AAEH,MAAMI,OAAO,gBAAG,IAAIC,WAAW,EAAE;AACjC,MAAMC,OAAO,gBAAG,IAAIC,WAAW,EAAE;AAEjC;;;;;AAKO,MAAMC,iBAAiB,GAAAL,OAAA,CAAAK,iBAAA,gBAA4BC,aAAK,CAACC,OAAO,CACrEV,UAAU,EACV;EACEW,SAAS,EAAGC,CAAC,IAAKR,OAAO,CAACS,MAAM,CAACC,IAAI,CAACC,SAAS,CAACH,CAAC,CAAC,CAAC;EACnDI,WAAW,EAAGC,CAAC,IAAKH,IAAI,CAACI,KAAK,CAACZ,OAAO,CAACa,MAAM,CAACF,CAAC,CAAC;CACjD,CACF","ignoreList":[]}

package/dist/cjs/Uuid.js

@@ -0,0 +1,41 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.UuidTest = exports.UuidLive = exports.Uuid = void 0;
+var _testing = require("@kairos-es/core/testing");
+var _effect = require("effect");
+/**
+ * The uuid service: `toEvent` stamps each wire event's `uuid` from here, keeping
+ * `core` RNG-free (and letting suites make events comparable). Overridable per
+ * `toEvent` call via `options.uuid`.
+ *
+ * `UuidLive` uses WebCrypto (`globalThis.crypto.randomUUID`) so the codec stays
+ * platform-neutral with no `node:crypto`. `UuidTest` is a deterministic layer
+ * whose per-layer counter yields stable RFC-4122 v4-shaped uuids
+ * (`00000000-0000-4000-8000-<12 hex>`), so a suite that builds one `UuidTest`
+ * layer gets a repeatable sequence.
+ */
+
+class Uuid extends /*#__PURE__*/_effect.Context.Tag('@kairos-es/codec/Uuid')() {}
+/** Live uuid generation via WebCrypto (no `node:crypto`). */
+exports.Uuid = Uuid;
+const UuidLive = exports.UuidLive = /*#__PURE__*/_effect.Layer.succeed(Uuid, {
+  generate: /*#__PURE__*/_effect.Effect.sync(() => globalThis.crypto.randomUUID())
+});
+/**
+ * A deterministic uuid layer for suites, wrapping core's shared
+ * `makeSequentialUuid` (the single source of truth for the counter scheme).
+ * Each layer instance builds a fresh generator, so it owns its own counter and
+ * yields a stable v4-shaped sequence `00000000-0000-4000-8000-<12 hex>` starting
+ * at `...000000000000`. Generation is wrapped in `Effect.sync` because the
+ * generator advances its counter (a side effect on each call).
+ */
+const UuidTest = exports.UuidTest = /*#__PURE__*/_effect.Layer.sync(Uuid, () => {
+  const next = (0, _testing.makeSequentialUuid)();
+  return {
+    generate: _effect.Effect.sync(next)
+  };
+});
+//# sourceMappingURL=Uuid.js.map

package/dist/cjs/Uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Uuid.js","names":["_testing","require","_effect","Uuid","Context","Tag","exports","UuidLive","Layer","succeed","generate","Effect","sync","globalThis","crypto","randomUUID","UuidTest","next","makeSequentialUuid"],"sources":["../../src/Uuid.ts"],"sourcesContent":[null],"mappings":";;;;;;AAWA,IAAAA,QAAA,GAAAC,OAAA;AACA,IAAAC,OAAA,GAAAD,OAAA;AAZA;;;;;;;;;;;;AAcM,MAAOE,IAAK,sBAAQC,eAAO,CAACC,GAAG,CAAC,uBAAuB,CAAC,EAG3D;AAEH;AAAAC,OAAA,CAAAH,IAAA,GAAAA,IAAA;AACO,MAAMI,QAAQ,GAAAD,OAAA,CAAAC,QAAA,gBAAsBC,aAAK,CAACC,OAAO,CAACN,IAAI,EAAE;EAC7DO,QAAQ,eAAEC,cAAM,CAACC,IAAI,CAAC,MAAMC,UAAU,CAACC,MAAM,CAACC,UAAU,EAAE;CAC3D,CAAC;AAEF;;;;;;;;AAQO,MAAMC,QAAQ,GAAAV,OAAA,CAAAU,QAAA,gBAAsBR,aAAK,CAACI,IAAI,CAACT,IAAI,EAAE,MAAK;EAC/D,MAAMc,IAAI,GAAG,IAAAC,2BAAkB,GAAE;EACjC,OAAO;IAAER,QAAQ,EAAEC,cAAM,CAACC,IAAI,CAACK,IAAI;EAAC,CAAE;AACxC,CAAC,CAAC","ignoreList":[]}

package/dist/cjs/decider.js

@@ -0,0 +1,152 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runDecider = exports.decider = void 0;
+var _core = require("@kairos-es/core");
+var _effect = require("effect");
+var _decisionModel = require("./decisionModel.js");
+/**
+ * A `Decider`: the write side's unit of decision. It pairs the projections a
+ * command handler reads (its decision model) with an effectful `decide` step
+ * that turns the folded state plus a command into the events to append.
+ *
+ * This is PRODUCTION code and it lives beside the `buildDecisionModel` it
+ * drives. It began in `@kairos-es/testing` because the Given/When/Then surface
+ * was its first consumer, but nothing in it is test apparatus: every import
+ * resolves to this package or to `@kairos-es/core`, and a test framework is
+ * never one of them. That home was a real hazard rather than a tidiness
+ * complaint — `@kairos-es/testing` peers `@effect/vitest`, so a command handler
+ * typed against `Decider` (as this repo's own worked example is, in `src/` and
+ * not `test/`) named a package whose sibling module imports `expect` and `it` at
+ * top level, and a handler that actually RAN a command would have
+ * runtime-imported `runDecider` from it, loading a test framework into a
+ * production module graph. `@kairos-es/read/testing` documents that same hazard
+ * as the reason a subpath may add no peer; the difference here is that this is
+ * not a testing surface at all, so the fix is a home rather than a rule.
+ *
+ * `@kairos-es/testing` now imports these two symbols like any other consumer,
+ * and NO compatibility re-export is left behind there: nothing is published yet,
+ * so a re-export would be permanent clutter bought for no consumer, and it would
+ * preserve in that package's public surface exactly the coupling the move
+ * exists to remove. That is the argument ADR-0008 made when `retryOnConflict`
+ * moved to the package that owns the error it matches, and it holds here for the
+ * same reason — a write-side consumer depending on the wrong package is
+ * backwards, whichever direction the dependency points.
+ *
+ * `projections` is a *function of the command* because a DCB decision model is
+ * parametrised by the command's own identifiers (e.g. narrow to
+ * `course:{command.courseId}`), which keeps the consistency boundary — and the
+ * `failIfEventsMatch` guard the read produces — as tight as the decision
+ * actually needs. This mirrors dcb-events, where the command handler calls
+ * `buildDecisionModel(store, { ...projections built from command.data })`.
+ *
+ * `runDecider` runs the DCB command cycle against whatever `DcbEventStore` is in
+ * context: build the decision model for the command (a real `read` + decode +
+ * fold via `buildDecisionModel`), decide, then `append` the new events under the
+ * append condition the read produced. That IS the optimistic-concurrency
+ * contract, in production and in a scenario alike — which is also why the
+ * Given/When/Then surface built on it exercises the real fold and the real store
+ * rather than a mock. It is a free function rather than a `Context.Tag` service,
+ * so it is still not the "production command-runner service method" a retrying
+ * `Layer` would need (ADR-0008): the correct retry remains
+ * `retryOnConflict(runDecider(...))`, wrapping the whole cycle so a fresh read
+ * re-derives the condition.
+ *
+ * The `decide` step produces its events effectfully (they are encoded via
+ * `toEvent`, so it requires `Serializer | Uuid | R`) and may fail on its own
+ * error channel (a domain rule violation, e.g. "course already exists"); the
+ * append may fail with `AppendConditionFailed` if a concurrent writer moved the
+ * boundary, and decode may fail with `CodecError`. All surface on the error
+ * channel, so a caller handles all three the same way — and
+ * `@kairos-es/testing`'s `.thenError(tag)` can assert any of them.
+ */
+
+/**
+ * Build a `Decider` with all four of its type arguments INFERRED: the slice
+ * record `P` from what `projections` returns, the error union `E` and the extra
+ * requirement `R` from what `decide` returns. The command type is the one thing
+ * a caller still writes, once, as the annotation on the `projections` parameter
+ * — `Command` occurs only in parameter positions, so nothing else could supply
+ * it, and it is domain information (the command this decision is parametrised
+ * by) rather than plumbing.
+ *
+ * It adds no capability: the interface stays directly inhabitable and this
+ * returns exactly the object literal a caller would have written. What it
+ * changes is what an author must SPELL. An object literal annotated
+ * `Decider<P, Command, E>` has to state the whole slice record — a
+ * `ReturnType<typeof someProjection>` per key, a slice's state type being
+ * inferred by `projection().on().build()` and so having no name to write — plus
+ * the union of every error its decide branches can fail with. Dropping the
+ * annotation instead is not open to the author: without it `decide`'s `state`
+ * and `command` parameters have no contextual type and are implicitly `any`. So
+ * the cost landed hardest on the worked example, where some thirty lines of type
+ * plumbing sat between the reader and the three decisions that file exists to
+ * teach.
+ *
+ * `Eff` captures decide's WHOLE return type as one type parameter instead of
+ * inferring `E` and `R` from an `Effect<…, E, Serializer | Uuid | R>` shaped
+ * target, and that is the part that had to be got right rather than merely
+ * written down. A real `decide` returns a UNION of effects — one `Effect.fail`
+ * per rule it enforces, plus the produce path — and TypeScript infers a type
+ * parameter from a union source by choosing one constituent's candidate, not by
+ * unioning them. Against the shaped target `E` therefore came out as whichever
+ * branch won, and every other branch was then rejected against it. Inference to
+ * a NAKED type variable takes the union whole, which is why `Eff` is the
+ * parameter and `Effect.Effect.Error` / `Effect.Effect.Context` recover the two
+ * channels afterwards: those do distribute across a union of effects.
+ *
+ * The constraint on `Eff` is load-bearing twice over. It is what still refuses a
+ * `decide` that could produce an EMPTY batch, the one guarantee the shaped
+ * target used to give and the one `append` relies on. It is also what
+ * contextually types the produce path's `(event) => [event]` as a one-element
+ * TUPLE; unconstrained, that widens to `DcbEvent[]`, which is not a
+ * `NonEmptyReadonlyArray` and would fail at the call site.
+ *
+ * The single `as` is narrow and unavoidable: the declared return is a
+ * conditional over an unresolved `Eff`, so while `Eff` is still a type variable
+ * the checker cannot relate `(…) => Eff` to `(…) => Effect<…,
+ * Effect.Error<Eff>, …>`. The value is the two functions it was handed, so
+ * there is nothing for the cast to be wrong about.
+ *
+ * `R` excludes `Serializer | Uuid` because that is what `R` MEANS on `Decider`:
+ * the interface writes decide's requirement as `Serializer | Uuid | R`, so `R`
+ * is what the produce side needs BEYOND the codec's own two services. Leaving
+ * them in would state the same requirement twice and make an ordinary decider
+ * read as though it carried an extra one, though the set `runDecider` ends up
+ * asking for is identical either way. The exclusion cannot swallow a caller's
+ * own service by accident: a `Context.Tag`'s requirement type carries its key as
+ * a literal `Id` field, so only a tag declared under `@kairos-es/codec/Uuid` or
+ * `@kairos-es/codec/Serializer` matches — and a tag under that key IS that
+ * service, context being keyed by the same string at runtime.
+ */
+const decider = (projections, decide) => ({
+  projections,
+  decide
+});
+/**
+ * Run the full DCB command cycle for a decider against the ambient
+ * `DcbEventStore`: build the decision model (real read + decode + fold), decide,
+ * and append under the read's append condition. Returns the last new position.
+ *
+ * The requirement is `DcbEventStore | Serializer | Uuid | R |
+ * RequirementOf<P>`: `Serializer` enters through both the decode
+ * (`buildDecisionModel`) and produce (`toEvent`) sides, `Uuid` through produce,
+ * the slices' `RequirementOf<P>` through decode, and `R` through produce. (For a
+ * def whose `Schema` carries a requirement, `RequirementOf<P>` and `R` are the
+ * same tag.) Any `decide` failure, a decode `CodecError`, or an
+ * `AppendConditionFailed` propagates on the error channel unchanged.
+ */
+exports.decider = decider;
+const runDecider = (decider, command) => _effect.Effect.gen(function* () {
+  const store = yield* _core.DcbEventStore;
+  const {
+    state,
+    appendCondition
+  } = yield* (0, _decisionModel.buildDecisionModel)(decider.projections(command));
+  const newEvents = yield* decider.decide(state, command);
+  return yield* store.append(newEvents, appendCondition);
+});
+exports.runDecider = runDecider;
+//# sourceMappingURL=decider.js.map

package/dist/cjs/decider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decider.js","names":["_core","require","_effect","_decisionModel","decider","projections","decide","exports","runDecider","command","Effect","gen","store","DcbEventStore","state","appendCondition","buildDecisionModel","newEvents","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":";;;;;;AA8DA,IAAAA,KAAA,GAAAC,OAAA;AAEA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,cAAA,GAAAF,OAAA;AAjEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DO,MAAMG,OAAO,GAAGA,CASrBC,WAAoC,EACpCC,MAA2D,MAO1D;EAAED,WAAW;EAAEC;AAAM,CAAE,CAKvB;AAEH;;;;;;;;;;;;;AAAAC,OAAA,CAAAH,OAAA,GAAAA,OAAA;AAaO,MAAMI,UAAU,GAAGA,CAMxBJ,OAAkC,EAClCK,OAAgB,KAMhBC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOC,mBAAa;EAClC,MAAM;IAAEC,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAO,IAAAC,iCAAkB,EAC1DZ,OAAO,CAACC,WAAW,CAACI,OAAO,CAAC,CAC7B;EACD,MAAMQ,SAAS,GAAG,OAAOb,OAAO,CAACE,MAAM,CAACQ,KAAK,EAAEL,OAAO,CAAC;EACvD,OAAO,OAAOG,KAAK,CAACM,MAAM,CAACD,SAAS,EAAEF,eAAe,CAAC;AACxD,CAAC,CAAC;AAAAR,OAAA,CAAAC,UAAA,GAAAA,UAAA","ignoreList":[]}

package/dist/cjs/decisionModel.js

@@ -0,0 +1,155 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.modelAtHead = exports.buildDecisionModel = void 0;
+var _core = require("@kairos-es/core");
+var _effect = require("effect");
+var _decode = require("./decode.js");
+/**
+ * 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` derived from the same query and that same head (the DCB
+ * optimistic-concurrency contract). It is core's old
+ * `buildDecisionModel(Record<string, AnyProjection>)` surface, moved here
+ * because decode needs `Schema` + the `Serializer`.
+ *
+ * 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).
+ */
+
+/**
+ * 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.
+ *
+ * `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.
+ */
+const modelAtHead = projections => _effect.Effect.gen(function* () {
+  const store = yield* _core.DcbEventStore;
+  // The shared, back-pressured decode stage, built from the SAME record the
+  // query below is composed from — which is the whole reason `decodeSlices`
+  // takes the slices rather than a pre-merged schema table.
+  const decode = (0, _decode.decodeSlices)(projections);
+  // The pure fold: core composes the record (slices are AnyProjections).
+  const composite = (0, _core.composeProjections)(projections);
+  const {
+    events,
+    head
+  } = yield* store.read(composite.query);
+  const decoded = decode(events);
+  const state = yield* _effect.Stream.runFold(decoded, composite.initialState, (acc, event) => composite.evolve(acc, event));
+  return {
+    state,
+    head
+  };
+});
+/**
+ * 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.
+ *
+ * `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.
+ *
+ * ## How to attribute the read, the decode and the fold — the rule, stated once
+ *
+ * Because this function is `Effect.map` 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.
+ */
+exports.modelAtHead = modelAtHead;
+const buildDecisionModel = projections => _effect.Effect.map(modelAtHead(projections), ({
+  state,
+  head
+}) => ({
+  state,
+  appendCondition: {
+    failIfEventsMatch: (0, _core.composeProjections)(projections).query,
+    after: head
+  }
+}));
+exports.buildDecisionModel = buildDecisionModel;
+//# sourceMappingURL=decisionModel.js.map

package/dist/cjs/decisionModel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisionModel.js","names":["_core","require","_effect","_decode","modelAtHead","projections","Effect","gen","store","DcbEventStore","decode","decodeSlices","composite","composeProjections","events","head","read","query","decoded","state","Stream","runFold","initialState","acc","event","evolve","exports","buildDecisionModel","map","appendCondition","failIfEventsMatch","after"],"sources":["../../src/decisionModel.ts"],"sourcesContent":[null],"mappings":";;;;;;AA0BA,IAAAA,KAAA,GAAAC,OAAA;AAQA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AAnCA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CO,MAAMG,WAAW,GACtBC,WAAc,IAMdC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOC,mBAAa;EAElC;EACA;EACA;EACA,MAAMC,MAAM,GAAG,IAAAC,oBAAY,EAACN,WAAW,CAAC;EAExC;EACA,MAAMO,SAAS,GAAG,IAAAC,wBAAkB,EAClCR,WAA4C,CAC7C;EACD,MAAM;IAAES,MAAM;IAAEC;EAAI,CAAE,GAAG,OAAOP,KAAK,CAACQ,IAAI,CAACJ,SAAS,CAACK,KAAK,CAAC;EAE3D,MAAMC,OAAO,GAAGR,MAAM,CAACI,MAAM,CAAC;EAE9B,MAAMK,KAAK,GAAI,OAAOC,cAAM,CAACC,OAAO,CAClCH,OAAO,EACPN,SAAS,CAACU,YAAY,EACtB,CAACC,GAAG,EAAEC,KAAK,KAAKZ,SAAS,CAACa,MAAM,CAACF,GAAG,EAAEC,KAAK,CAAC,CACvB;EAEvB,OAAO;IAAEL,KAAK;IAAEJ;EAAI,CAAE;AACxB,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAAW,OAAA,CAAAtB,WAAA,GAAAA,WAAA;AAwCO,MAAMuB,kBAAkB,GAC7BtB,WAAc,IASdC,cAAM,CAACsB,GAAG,CAACxB,WAAW,CAACC,WAAW,CAAC,EAAE,CAAC;EAAEc,KAAK;EAAEJ;AAAI,CAAE,MAAM;EACzDI,KAAK;EACLU,eAAe,EAAE;IACfC,iBAAiB,EAAE,IAAAjB,wBAAkB,EACnCR,WAA4C,CAC7C,CAACY,KAAK;IACPc,KAAK,EAAEhB;;CAEV,CAAC,CAAC;AAAAW,OAAA,CAAAC,kBAAA,GAAAA,kBAAA","ignoreList":[]}

package/dist/cjs/decode.js

@@ -0,0 +1,170 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.decodeSlices = void 0;
+var _effect = require("effect");
+var _deserialiseThenDecode = require("./deserialiseThenDecode.js");
+var _errors = require("./errors.js");
+var _Serializer = require("./Serializer.js");
+/**
+ * Merge every slice's `type -> Schema` map into one decode lookup.
+ *
+ * A record of slices is the unit an application composes, but decode is keyed
+ * by the wire event's runtime `type` string, so the per-slice maps have to
+ * collapse into one flat table first. A type reachable from two slices is
+ * therefore a collision the merge has to rule on, and it rules by REFERENCE
+ * EQUALITY: the same `Schema` arriving twice is absorbed, two *different*
+ * `Schema`s under one type string are refused with a throw.
+ *
+ * **Why reference equality is the discriminator.** The legitimate case — the one
+ * the old last-writer-wins was written for — is two slices that `.on` the same
+ * `EventDef`, which is how one event feeds two views. `event()` builds its
+ * `Schema.Struct` once and every def hands out that one object, so those two
+ * slices hold the identical reference and whichever entry survives the merge
+ * decodes identically; `decode.test.ts` asserts that under both key orderings
+ * rather than leaving it as a claim. Nothing weaker is sound and nothing
+ * stronger is needed: two distinct defs can be structurally identical today and
+ * diverge on the next commit, so structural comparison would license exactly the
+ * pairing that is about to go wrong.
+ *
+ * **Why the other case cannot stay last-writer-wins.** Two distinct defs can
+ * share a `type` string — a copied def, or two versions accidentally given one
+ * name — and then the surviving schema is whichever slice `Object.keys` visits
+ * last, an ordering the record does not express and its author never chose.
+ * Every event of that type is then decoded against the wrong def for one of the
+ * slices, and where the two shapes overlap that failure is SILENT rather than a
+ * `CodecError`: `Schema.decodeUnknown` defaults `onExcessProperty` to `'ignore'`
+ * (`effect@3.22`'s `ParseResult.ts` runs its excess-key loop only under
+ * `'error'` or `'preserve'`), so a field the other def declared is dropped, not
+ * reported, and the fold downstream is handed a payload quietly missing it.
+ *
+ * **Why a throw, and why here rather than at the read side's wiring gate.**
+ * `makeRegistry` already treats a duplicated type as a construction-time defect
+ * and throws (ADR-0005, `totality.test.ts`); this is the same mistake reached
+ * through the slice path, so it gets the same mechanism and the same opening
+ * words rather than a second convention for one rule. It belongs to the codec
+ * because BOTH consumers need it and only one of them is on the read side: the
+ * write path reaches this through `buildDecisionModel` and never goes near the read
+ * side's wiring gate. Neither consumer can be mid-stream when it fires —
+ * the write path merges before its first `store.read`, and the read side
+ * merges after that gate and before it forks the pipeline — and inside
+ * their `Effect.gen`s a throw becomes a DEFECT rather than an escaping exception
+ * (`effect@3.22`'s `fiberRuntime.ts` run loop converts a thrown value with
+ * `core.die`), which is the classification a mis-wiring already has on both
+ * sides of the library.
+ *
+ * The sentence names BOTH slices. The two halves of this mistake are in
+ * different entries of the record, and a message naming only the one that
+ * happened to be visited second sends its author to look in the wrong place.
+ *
+ * The cast re-attaches `R`. Indexing `T` by a plain `string` key erases each
+ * slice to the `SliceProjection` *constraint*, whose requirement parameter
+ * defaults to `unknown`, so the concrete per-slice `R` is not recoverable from
+ * the value side. `RequirementOf<T>` recovers it from the *type* side, and the
+ * assertion is sound because a slice's own requirement is always a member of
+ * that union. Doing it once here is why no call site needs a cast.
+ *
+ * Module-private, and deliberately so: see `decodeSlices` for why the merge is
+ * not a step a caller is trusted to take.
+ */
+const mergeSliceSchemas = projections => {
+  const schemas = new Map();
+  // Which slice contributed each entry, kept in lockstep with `schemas` purely
+  // so the refusal can name both sides of a collision. Its presence is also what
+  // the check below reads, rather than a second `schemas.has`, so the narrowing
+  // that makes the earlier key a `string` falls out of the check itself.
+  const contributedBy = new Map();
+  for (const key of Object.keys(projections)) {
+    const slice = projections[key];
+    for (const [type, schema] of slice.schemas) {
+      const owner = contributedBy.get(type);
+      if (owner !== undefined && schemas.get(type) !== schema) {
+        throw new Error(`duplicate event type '${type}' in slices '${owner}' and '${key}': ` + 'they hold different Schemas for one type, so decode would use ' + 'whichever slice merged last. Two slices may share an event type ' + 'only by sharing one EventDef.');
+      }
+      schemas.set(type, schema);
+      contributedBy.set(type, key);
+    }
+  }
+  return schemas;
+};
+/**
+ * The decode stage: look the event's `type` up in `schemas`, run the shared
+ * `deserialiseThenDecode` over the wire bytes, and emit a `DecodedEvent` (the
+ * sequenced envelope plus its typed payload) for the pure fold downstream. The
+ * lookup and the envelope are what this stage adds; the two-step in the middle,
+ * and the two `reason` strings it fails with, belong to that helper.
+ *
+ * Curried on `schemas` so a caller builds the lookup once — per decision model,
+ * per read model — and reuses the stage across every stream it drives.
+ *
+ * `Serializer` is read from context *inside* the stage (once, when the stream
+ * starts, via `Stream.unwrap`) rather than being pre-yielded and closed over by
+ * the caller. That keeps the serialisation dependency wholly inside this
+ * module: a consumer cannot hand in a different serialiser than the one its
+ * layer provides, so encode (`toEvent`) and decode provably read the same
+ * `Serializer` — the invariant `Serializer.ts` rests on. The obligation is
+ * still visible, because `Serializer` surfaces in the returned stream's `R`;
+ * it just is not satisfiable by hand.
+ *
+ * The stage is transparent to the input stream's own `E` and `R`: a bounded
+ * `read` stream (`never`, `never`) and a live `subscribe` stream (`never`,
+ * `Scope`) both flow through unchanged, gaining only `CodecError` and
+ * `Serializer`.
+ *
+ * Module-private: `decodeSlices` is the public shape. Keeping the schema-map
+ * form here rather than inlining it into `decodeSlices` is what makes the
+ * "build the lookup once, reuse the stage" property explicit in the types.
+ */
+const decodeEvents = schemas => events => _effect.Stream.unwrap(_effect.Effect.map(_Serializer.Serializer, serializer => events.pipe(_effect.Stream.mapEffect(sequenced => {
+  const schema = schemas.get(sequenced.event.type);
+  if (schema === undefined) {
+    return _effect.Effect.fail(new _errors.CodecError({
+      reason: `no schema for event type '${sequenced.event.type}'`
+    }));
+  }
+  return (0, _deserialiseThenDecode.deserialiseThenDecode)(serializer, schema, sequenced.event.data).pipe(_effect.Effect.map(payload => ({
+    sequenced,
+    payload
+  })));
+}))));
+/**
+ * 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.
+ */
+const decodeSlices = slices => decodeEvents(mergeSliceSchemas(slices));
+exports.decodeSlices = decodeSlices;
+//# sourceMappingURL=decode.js.map