@kairos-es/codec 0.0.0

package/src/Serializer.ts

@@ -0,0 +1,37 @@
+/**
+ * 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`.
+ */
+import { Context, Layer } from 'effect'
+
+export class Serializer extends Context.Tag('@kairos-es/codec/Serializer')<
+  Serializer,
+  {
+    readonly serialise: (v: unknown) => Uint8Array
+    readonly deserialise: (b: Uint8Array) => unknown
+  }
+>() {}
+
+const encoder = new TextEncoder()
+const decoder = 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).
+ */
+export const SerializerDefault: Layer.Layer<Serializer> = Layer.succeed(
+  Serializer,
+  {
+    serialise: (v) => encoder.encode(JSON.stringify(v)),
+    deserialise: (b) => JSON.parse(decoder.decode(b)),
+  },
+)

package/src/Uuid.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+import { makeSequentialUuid } from '@kairos-es/core/testing'
+import { Context, Effect, Layer } from 'effect'
+
+export class Uuid extends Context.Tag('@kairos-es/codec/Uuid')<
+  Uuid,
+  { readonly generate: Effect.Effect<string> }
+>() {}
+
+/** Live uuid generation via WebCrypto (no `node:crypto`). */
+export const UuidLive: Layer.Layer<Uuid> = Layer.succeed(Uuid, {
+  generate: 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).
+ */
+export const UuidTest: Layer.Layer<Uuid> = Layer.sync(Uuid, () => {
+  const next = makeSequentialUuid()
+  return { generate: Effect.sync(next) }
+})

package/src/decider.ts

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ */
+
+import type {
+  AppendConditionFailed,
+  CompositeState,
+  DcbEvent,
+  Position,
+} from '@kairos-es/core'
+import { DcbEventStore } from '@kairos-es/core'
+import type { Array as Arr } from 'effect'
+import { Effect } from 'effect'
+import { buildDecisionModel, type RequirementOf } from './decisionModel'
+import type { CodecError } from './errors'
+import type { SliceProjection } from './projection'
+import type { Serializer } from './Serializer'
+import type { Uuid } from './Uuid'
+
+/**
+ * A decision unit: the projections whose folded state a command is decided
+ * against, and the `decide` step producing the events to append.
+ *
+ * `decide` may fail with a domain error `E` (a tagged error is idiomatic, so
+ * `@kairos-es/testing`'s `.thenError` can match its `_tag`). It receives the
+ * composed decision-model `state` and the `command`, and returns the non-empty
+ * batch of new events — effectfully, because each event is produced via
+ * `toEvent` (encode -> serialise), which requires `Serializer | Uuid | R`.
+ *
+ * The projection record is bounded by this package's `SliceProjection` (the
+ * schema-backed, state-erased bound for a heterogeneous record); the
+ * precise per-key state is recovered by core's shared `CompositeState`. The
+ * requirement `R` is the union carried by the record's slices' schemas.
+ */
+export interface Decider<
+  P extends Record<string, SliceProjection>,
+  Command,
+  E = never,
+  R = never,
+> {
+  readonly projections: (command: Command) => P
+  readonly decide: (
+    state: CompositeState<P>,
+    command: Command,
+  ) => Effect.Effect<
+    Arr.NonEmptyReadonlyArray<DcbEvent>,
+    E,
+    Serializer | Uuid | R
+  >
+}
+
+/**
+ * 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.
+ */
+export const decider = <
+  P extends Record<string, SliceProjection>,
+  Command,
+  Eff extends Effect.Effect<
+    Arr.NonEmptyReadonlyArray<DcbEvent>,
+    unknown,
+    unknown
+  >,
+>(
+  projections: (command: Command) => P,
+  decide: (state: CompositeState<P>, command: Command) => Eff,
+): Decider<
+  P,
+  Command,
+  Effect.Effect.Error<Eff>,
+  Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>
+> =>
+  ({ projections, decide }) as Decider<
+    P,
+    Command,
+    Effect.Effect.Error<Eff>,
+    Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>
+  >
+
+/**
+ * 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.
+ */
+export const runDecider = <
+  P extends Record<string, SliceProjection>,
+  Command,
+  E,
+  R,
+>(
+  decider: Decider<P, Command, E, R>,
+  command: Command,
+): Effect.Effect<
+  Position,
+  E | CodecError | AppendConditionFailed,
+  DcbEventStore | Serializer | Uuid | R | RequirementOf<P>
+> =>
+  Effect.gen(function* () {
+    const store = yield* DcbEventStore
+    const { state, appendCondition } = yield* buildDecisionModel(
+      decider.projections(command),
+    )
+    const newEvents = yield* decider.decide(state, command)
+    return yield* store.append(newEvents, appendCondition)
+  })

package/src/decisionModel.ts

@@ -0,0 +1,182 @@
+/**
+ * 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).
+ */
+import {
+  type AnyProjection,
+  type AppendCondition,
+  type CompositeState,
+  composeProjections,
+  DcbEventStore,
+  type Position,
+} from '@kairos-es/core'
+import { Effect, Stream } from 'effect'
+import { decodeSlices } from './decode'
+import type { CodecError } from './errors'
+import type { SliceProjection } from './projection'
+import type { Serializer } from './Serializer'
+
+/** 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.
+ *
+ * `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 const modelAtHead = <T extends Record<string, SliceProjection>>(
+  projections: T,
+): Effect.Effect<
+  { readonly state: CompositeState<T>; readonly head: Position },
+  CodecError,
+  DcbEventStore | Serializer | RequirementOf<T>
+> =>
+  Effect.gen(function* () {
+    const store = yield* 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 = decodeSlices(projections)
+
+    // The pure fold: core composes the record (slices are AnyProjections).
+    const composite = composeProjections(
+      projections as Record<string, AnyProjection>,
+    )
+    const { events, head } = yield* store.read(composite.query)
+
+    const decoded = decode(events)
+
+    const state = (yield* Stream.runFold(
+      decoded,
+      composite.initialState,
+      (acc, event) => composite.evolve(acc, event),
+    )) as CompositeState<T>
+
+    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.
+ */
+export const buildDecisionModel = <T extends Record<string, SliceProjection>>(
+  projections: T,
+): Effect.Effect<
+  {
+    readonly state: CompositeState<T>
+    readonly appendCondition: AppendCondition
+  },
+  CodecError,
+  DcbEventStore | Serializer | RequirementOf<T>
+> =>
+  Effect.map(modelAtHead(projections), ({ state, head }) => ({
+    state,
+    appendCondition: {
+      failIfEventsMatch: composeProjections(
+        projections as Record<string, AnyProjection>,
+      ).query,
+      after: head,
+    },
+  }))