@kairos-es/codec 0.0.0

package/src/decode.ts

@@ -0,0 +1,256 @@
+/**
+ * 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 v3's `mapEffect` is
+ * order-PRESERVING even when concurrent — reordering needs the separate
+ * `unordered: true` option (verified against the installed
+ * `effect@3.22`'s `Stream.d.ts`, and probed at runtime) — 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 { Effect, type Schema, Stream } from 'effect'
+// Type-only, so the `decisionModel` <-> `decode` edge is erased at emit and
+// there is no runtime import cycle. `RequirementOf` deliberately stays with
+// `buildDecisionModel`, its original home and primary consumer.
+import type { RequirementOf } from './decisionModel'
+import { deserialiseThenDecode } from './deserialiseThenDecode'
+import { CodecError } from './errors'
+import type { SliceProjection } from './projection'
+import { Serializer } from './Serializer'
+
+/**
+ * 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 = <T extends Record<string, SliceProjection>>(
+  projections: T,
+): ReadonlyMap<string, Schema.Schema<unknown, unknown, RequirementOf<T>>> => {
+  const schemas = new Map<
+    string,
+    Schema.Schema<unknown, unknown, RequirementOf<T>>
+  >()
+  // 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<string, string>()
+  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 as Schema.Schema<unknown, unknown, RequirementOf<T>>,
+      )
+      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 =
+  <RS>(schemas: ReadonlyMap<string, Schema.Schema<unknown, unknown, RS>>) =>
+  <E, R>(
+    events: Stream.Stream<SequencedEvent, E, R>,
+  ): Stream.Stream<DecodedEvent, E | CodecError, R | RS | Serializer> =>
+    Stream.unwrap(
+      Effect.map(Serializer, (serializer) =>
+        events.pipe(
+          Stream.mapEffect((sequenced) => {
+            const schema = schemas.get(sequenced.event.type)
+            if (schema === undefined) {
+              return Effect.fail(
+                new CodecError({
+                  reason: `no schema for event type '${sequenced.event.type}'`,
+                }),
+              )
+            }
+            return deserialiseThenDecode(
+              serializer,
+              schema,
+              sequenced.event.data,
+            ).pipe(
+              Effect.map((payload): DecodedEvent => ({ 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.
+ */
+export 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
+>) => decodeEvents(mergeSliceSchemas(slices))

package/src/deserialiseThenDecode.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.decodeUnknown` 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.decodeUnknown` 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'
+import type { Serializer } from './Serializer'
+
+export const deserialiseThenDecode = <R>(
+  serializer: Context.Tag.Service<Serializer>,
+  schema: Schema.Schema<unknown, unknown, R>,
+  bytes: Uint8Array,
+): Effect.Effect<unknown, CodecError, R> =>
+  Effect.try({
+    try: () => serializer.deserialise(bytes),
+    catch: (cause) => new CodecError({ reason: 'deserialise', cause }),
+  }).pipe(
+    Effect.flatMap((raw) =>
+      Schema.decodeUnknown(schema)(raw).pipe(
+        Effect.mapError((cause) => new CodecError({ reason: 'decode', cause })),
+      ),
+    ),
+  )

package/src/errors.ts

@@ -0,0 +1,91 @@
+/**
+ * Tagged errors for the codec. Decode failures are values on the error channel,
+ * never defects.
+ *
+ * `CodecError` covers every serialisation/`Schema` failure on the codec path
+ * (deserialise threw, `Schema.decode`/`encode` produced a `ParseError`, a
+ * wrong/absent encryption key surfaced through a `Schema` transform, or a
+ * `tagsFor` mapper threw while deriving an event's tags). It carries a
+ * human-readable `reason` and the underlying `cause` (exact-optional).
+ * `UnknownEventType` is raised only on the general (registry) path, when a wire
+ * event's runtime type string is outside the registered set — the home of
+ * ADR-0005 decode-totality.
+ */
+import { Data } from 'effect'
+
+/** A serialisation or `Schema` decode/encode failure on the codec path. */
+export class CodecError extends Data.TaggedError('CodecError')<{
+  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 `Object.assign(this, args)` (verified
+   * against `effect@3.22`'s `Data.ts`): the args above carry no `message`, so
+   * nothing shadows this prototype accessor with an own property.
+   */
+  override get message(): string {
+    return this.reason
+  }
+}
+
+/** A wire event whose runtime type string is outside the registry's known set. */
+export class UnknownEventType extends Data.TaggedError('UnknownEventType')<{
+  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.
+   */
+  override get message(): string {
+    return `event type '${this.type}' is not in the registry`
+  }
+}

package/src/event.ts

@@ -0,0 +1,90 @@
+/**
+ * Event definitions: a tagged `Schema` built through `event(type, fields,
+ * tagsFor)`. Each def is a `Schema<Payload, Wire, R>` plus its branded versioned
+ * `type` (ADR-0005) captured *beside* the payload, and a required `tagsFor`
+ * mapper deriving the event's tags from its decoded payload (ADR-0006).
+ *
+ * The single `EventType` brand is applied once, here, so no consumer ever casts
+ * a type string: `def.type` is already assignable to core's `EventType`. The
+ * payload `A`, wire encoding `I`, and requirement `R` are inferred from the
+ * `Schema.Struct` of `fields` — including any requirement a field's `Schema`
+ * transform carries (e.g. an application `Encrypted(...)` field contributes its
+ * `CipherKey` to `R`).
+ *
+ * `tagsFor` is the only way to tag an event: `toEvent` derives the wire tags by
+ * calling it, and there is no `tags` option to override them. Its
+ * `NonEmptyReadonlyArray<Tag>` return makes "every event carries at least one
+ * tag" a compile-time guarantee (returning `[]` is a type error at the def
+ * site), and its input being only this event's payload guarantees `tag ⊆ event
+ * data` structurally. An event with no natural business identity returns an
+ * explicit app-defined `system:<name>` tag, never an empty array.
+ *
+ * A mapper must be a *pure* function of its payload and key off fields in their
+ * schema-canonical form (normalising in the mapper to match a field's schema),
+ * so the tag it derives is stable under the schema round-trip: a later retag
+ * re-derives tags from decoded history, and `tagsFor(decode(encode(p)))` must
+ * equal `tagsFor(p)` for that to be sound. Plain scalar fields satisfy this
+ * trivially; a field whose schema canonicalises on decode (trim, lowercase,
+ * normalise) needs the mapper to apply the same normalisation (ADR-0006).
+ */
+import type { EventType, Tag } from '@kairos-es/core'
+import type { Array as Arr } from 'effect'
+import { Schema } from 'effect'
+
+/**
+ * A tag mapper: derives an event's tags from its decoded payload, returning at
+ * least one `Tag`. Named so a standalone mapper can be typed and shared (e.g.
+ * across two versioned defs of one logical event) and so the signature is
+ * written once, not per use site.
+ */
+export type TagsFor<A> = (payload: A) => Arr.NonEmptyReadonlyArray<Tag>
+
+/**
+ * An event definition: its branded `type`, the `Schema` mapping its typed
+ * payload `A` to its wire encoding `I` (requiring `R`), and the `tagsFor` mapper
+ * that derives the event's tags from a decoded payload. `Schema` is invariant in
+ * `A`/`I`, so `EventDef` cannot be `out A`/`out I`.
+ */
+export interface EventDef<A = unknown, I = unknown, R = never> {
+  readonly type: EventType
+  readonly schema: Schema.Schema<A, I, R>
+  readonly tagsFor: TagsFor<A>
+}
+
+/**
+ * The heterogeneous bound (mirrors `Schema.Schema.Any`) for arrays/records of
+ * mixed defs, where the precise `A`/`I` differ per element. `tagsFor` erases to
+ * `(a: any) => …`, which is harmless: only the write path (`toEvent`) calls it,
+ * and the registry/decode path never does (stored events already carry tags).
+ */
+// biome-ignore lint/suspicious/noExplicitAny: the sanctioned heterogeneous bound (mirrors Schema.Schema.Any); A/I differ per element, so any is the only sound erasure.
+export type EventDefAny = EventDef<any, any, unknown>
+
+/**
+ * Define an event from a versioned `type` literal, its payload `fields`, and its
+ * required `tagsFor` mapper. Builds `Schema.Struct(fields)` and brands the type
+ * literal *once* (the single sanctioned cast). The returned def is typed so
+ * `def.type` is a branded literal assignable to core's `EventType` with no
+ * consumer cast, `A`/`I`/`R` are inferred from the struct, and `tagsFor`
+ * receives the def's decoded payload type.
+ */
+export const event = <
+  const Type extends string,
+  Fields extends Schema.Struct.Fields,
+>(
+  type: Type,
+  fields: Fields,
+  tagsFor: TagsFor<Schema.Struct.Type<Fields>>,
+): {
+  readonly type: Type & EventType
+  readonly schema: Schema.Struct<Fields>
+  readonly tagsFor: TagsFor<Schema.Struct.Type<Fields>>
+} => {
+  const schema = Schema.Struct(fields)
+  return {
+    // The single EventType brand, applied once inside event(); no consumer casts.
+    type: type as Type & EventType,
+    schema,
+    tagsFor,
+  }
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * @kairos-es/codec — the schema-first codec seam, mapping typed domain events
+ * to and from the store's opaque wire bytes, with an application-owned
+ * encryption seam (ADR-0004).
+ *
+ * Two entry points:
+ * - The *typed slice path* (primary): `event(type, fields, tagsFor)` defines a
+ *   tagged `Schema` plus a required mapper deriving the event's tags from its
+ *   payload (ADR-0006); `projection(init).on(def, fold)...build()` composes the
+ *   specific defs a decision model consumes, inferring its state and requirement
+ *   `R`; `modelAtHead(slices)` reads, decodes through each def's `Schema`, and folds
+ *   purely, and `buildDecisionModel(slices)` adds the `AppendCondition` to it. A handler for an un-imported event is a compile error, and
+ *   a mistyped type cannot silently match nothing.
+ * - The *general path* (minimal): `makeRegistry(defs)` decodes an arbitrary wire
+ *   event by its runtime type string; an unknown type is a typed
+ *   `UnknownEventType` (ADR-0005 decode-totality). The payload stays `unknown`
+ *   on this path: the type is discovered at runtime, so no def was named to
+ *   narrow it (see `registry.ts`).
+ *
+ * `toEvent(def, payload, { uuid?, occurredAt? })` produces a wire event (encode
+ * -> serialise, tags derived from `def.tagsFor`, clock + uuid from services).
+ * Serialisation is a pluggable `Serializer` (JSON
+ * default). Encryption, when needed, is an *application*-authored `Schema`
+ * transform on a payload field; the codec only propagates its requirement and
+ * error channels — it owns no cipher and imports no `node:crypto`.
+ *
+ * `Decider` + `runDecider(decider, command)` close that path into the write
+ * side's whole command cycle: build the decision model, decide, append under the
+ * read's own condition. They live HERE, beside the `buildDecisionModel` they
+ * drive, rather than in `@kairos-es/testing` where they began — that package
+ * peers `@effect/vitest`, and a production command handler must not name it (see
+ * `decider.ts` for the full argument). `decider(projections, decide)` builds one
+ * with all four type arguments inferred, so a command's slice record and its
+ * error union are written once, in the two function bodies, rather than restated
+ * as an annotation above them.
+ *
+ * `modelAtHead(slices)` is that same read-decode-fold WITHOUT the
+ * `AppendCondition`: `{ state, head }`, one slice record materialised at read
+ * time with no table, no checkpoint and no runner, current as of the `head` its
+ * read returned — which is a stronger currency claim than a maintained view's
+ * checkpoint can make. `buildDecisionModel` is expressed over it, so the write
+ * path's decision model and a read-time materialisation share one body rather
+ * than two that could drift (see `decisionModel.ts` for both arguments).
+ *
+ * `decodeSlices(slices)` is the decode stage `modelAtHead` folds through,
+ * exported because the read side needs the *same* decode over a live
+ * `subscribe` stream. Exposing it keeps that single implementation shared
+ * rather than reimplemented downstream. It is deliberately ONE symbol taking
+ * the slice record, not a merge-then-decode pair: the pair had exactly one
+ * legal composition, and its only degree of freedom was to decode against a
+ * record other than the one the query came from (see `decode.ts`).
+ */
+
+export { type Decider, decider, runDecider } from './decider'
+export {
+  buildDecisionModel,
+  modelAtHead,
+  type RequirementOf,
+} from './decisionModel'
+export { decodeSlices } from './decode'
+export { CodecError, UnknownEventType } from './errors'
+export { type EventDef, type EventDefAny, event, type TagsFor } from './event'
+export {
+  type ProjectionBuilder,
+  projection,
+  type SliceProjection,
+} from './projection'
+export { makeRegistry, type Registry } from './registry'
+export { Serializer, SerializerDefault } from './Serializer'
+export { toEvent } from './toEvent'
+export { Uuid, UuidLive, UuidTest } from './Uuid'