@kairos-es/codec 0.0.0

package/dist/esm/decode.js

@@ -0,0 +1,163 @@
+import { Effect, Stream } from 'effect';
+import { deserialiseThenDecode } from "./deserialiseThenDecode.js";
+import { CodecError } from "./errors.js";
+import { Serializer } from "./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 => 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 => ({
+    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 = slices => decodeEvents(mergeSliceSchemas(slices));
+//# sourceMappingURL=decode.js.map

package/dist/esm/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","names":["Effect","Stream","deserialiseThenDecode","CodecError","Serializer","mergeSliceSchemas","projections","schemas","Map","contributedBy","key","Object","keys","slice","type","schema","owner","get","undefined","Error","set","decodeEvents","events","unwrap","map","serializer","pipe","mapEffect","sequenced","event","fail","reason","data","payload","decodeSlices","slices"],"sources":["../../src/decode.ts"],"sourcesContent":[null],"mappings":"AAiDA,SAASA,MAAM,EAAeC,MAAM,QAAQ,QAAQ;AAKpD,SAASC,qBAAqB,QAAQ,4BAAyB;AAC/D,SAASC,UAAU,QAAQ,aAAU;AAErC,SAASC,UAAU,QAAQ,iBAAc;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,MAAMC,iBAAiB,GACrBC,WAAc,IAC4D;EAC1E,MAAMC,OAAO,GAAG,IAAIC,GAAG,EAGpB;EACH;EACA;EACA;EACA;EACA,MAAMC,aAAa,GAAG,IAAID,GAAG,EAAkB;EAC/C,KAAK,MAAME,GAAG,IAAIC,MAAM,CAACC,IAAI,CAACN,WAAW,CAAC,EAAE;IAC1C,MAAMO,KAAK,GAAGP,WAAW,CAACI,GAAG,CAAC;IAC9B,KAAK,MAAM,CAACI,IAAI,EAAEC,MAAM,CAAC,IAAIF,KAAK,CAACN,OAAO,EAAE;MAC1C,MAAMS,KAAK,GAAGP,aAAa,CAACQ,GAAG,CAACH,IAAI,CAAC;MACrC,IAAIE,KAAK,KAAKE,SAAS,IAAIX,OAAO,CAACU,GAAG,CAACH,IAAI,CAAC,KAAKC,MAAM,EAAE;QACvD,MAAM,IAAII,KAAK,CACb,yBAAyBL,IAAI,gBAAgBE,KAAK,UAAUN,GAAG,KAAK,GAClE,gEAAgE,GAChE,kEAAkE,GAClE,+BAA+B,CAClC;MACH;MACAH,OAAO,CAACa,GAAG,CACTN,IAAI,EACJC,MAA2D,CAC5D;MACDN,aAAa,CAACW,GAAG,CAACN,IAAI,EAAEJ,GAAG,CAAC;IAC9B;EACF;EACA,OAAOH,OAAO;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,MAAMc,YAAY,GACXd,OAAiE,IAEpEe,MAA2C,IAE3CrB,MAAM,CAACsB,MAAM,CACXvB,MAAM,CAACwB,GAAG,CAACpB,UAAU,EAAGqB,UAAU,IAChCH,MAAM,CAACI,IAAI,CACTzB,MAAM,CAAC0B,SAAS,CAAEC,SAAS,IAAI;EAC7B,MAAMb,MAAM,GAAGR,OAAO,CAACU,GAAG,CAACW,SAAS,CAACC,KAAK,CAACf,IAAI,CAAC;EAChD,IAAIC,MAAM,KAAKG,SAAS,EAAE;IACxB,OAAOlB,MAAM,CAAC8B,IAAI,CAChB,IAAI3B,UAAU,CAAC;MACb4B,MAAM,EAAE,6BAA6BH,SAAS,CAACC,KAAK,CAACf,IAAI;KAC1D,CAAC,CACH;EACH;EACA,OAAOZ,qBAAqB,CAC1BuB,UAAU,EACVV,MAAM,EACNa,SAAS,CAACC,KAAK,CAACG,IAAI,CACrB,CAACN,IAAI,CACJ1B,MAAM,CAACwB,GAAG,CAAES,OAAO,KAAoB;IAAEL,SAAS;IAAEK;EAAO,CAAE,CAAC,CAAC,CAChE;AACH,CAAC,CAAC,CACH,CACF,CACF;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,OAAO,MAAMC,YAAY,GACvBC,MAAS,IAOLd,YAAY,CAAChB,iBAAiB,CAAC8B,MAAM,CAAC,CAAC","ignoreList":[]}

package/dist/esm/deserialiseThenDecode.js

@@ -0,0 +1,13 @@
+import { Effect, Schema } from 'effect';
+import { CodecError } from "./errors.js";
+export const deserialiseThenDecode = (serializer, schema, bytes) => 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
+})))));
+//# sourceMappingURL=deserialiseThenDecode.js.map

package/dist/esm/deserialiseThenDecode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deserialiseThenDecode.js","names":["Effect","Schema","CodecError","deserialiseThenDecode","serializer","schema","bytes","try","deserialise","catch","cause","reason","pipe","flatMap","raw","decodeUnknown","mapError"],"sources":["../../src/deserialiseThenDecode.ts"],"sourcesContent":[null],"mappings":"AAyDA,SAASA,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AACvC,SAASC,UAAU,QAAQ,aAAU;AAGrC,OAAO,MAAMC,qBAAqB,GAAGA,CACnCC,UAA2C,EAC3CC,MAA0C,EAC1CC,KAAiB,KAEjBN,MAAM,CAACO,GAAG,CAAC;EACTA,GAAG,EAAEA,CAAA,KAAMH,UAAU,CAACI,WAAW,CAACF,KAAK,CAAC;EACxCG,KAAK,EAAGC,KAAK,IAAK,IAAIR,UAAU,CAAC;IAAES,MAAM,EAAE,aAAa;IAAED;EAAK,CAAE;CAClE,CAAC,CAACE,IAAI,CACLZ,MAAM,CAACa,OAAO,CAAEC,GAAG,IACjBb,MAAM,CAACc,aAAa,CAACV,MAAM,CAAC,CAACS,GAAG,CAAC,CAACF,IAAI,CACpCZ,MAAM,CAACgB,QAAQ,CAAEN,KAAK,IAAK,IAAIR,UAAU,CAAC;EAAES,MAAM,EAAE,QAAQ;EAAED;AAAK,CAAE,CAAC,CAAC,CACxE,CACF,CACF","ignoreList":[]}

package/dist/esm/errors.js

@@ -0,0 +1,85 @@
+/**
+ * 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 /*#__PURE__*/Data.TaggedError('CodecError') {
+  /**
+   * `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.
+   */
+  get message() {
+    return this.reason;
+  }
+}
+/** A wire event whose runtime type string is outside the registry's known set. */
+export class UnknownEventType extends /*#__PURE__*/Data.TaggedError('UnknownEventType') {
+  /**
+   * The offending type, in a sentence saying what the registry did with it — so the
+   * fault renders ITSELF, exactly as `CodecError` above does.
+   *
+   * `Data.TaggedError` sets `name` to the tag and leaves `message` empty, so without
+   * this a decode that met an unregistered type stringifies to `'UnknownEventType'`
+   * — the one datum that makes the failure actionable, the type string itself,
+   * reaching a log line only where the logging code knows to reach in for `type`.
+   * Filled, `Error.prototype.toString` yields the tag followed by
+   * `event type 'nope.v1' is not in the registry`, which is what `Cause.pretty`
+   * prints and what an operator greps for. It matters here in particular because
+   * this class is the home of ADR-0005 decode-totality: a wire event outside the
+   * registered set is the expected consequence of a deployment reading a log a newer
+   * writer has extended, and the first question is always WHICH type — which the tag
+   * alone cannot answer.
+   *
+   * The wording deliberately differs from `CodecError`'s. That one says there is no
+   * schema for a type, and is raised on the TYPED path, where a caller named the
+   * type and the schema map it supplied has no entry for it. This one is the general
+   * (registry) path, where the type arrived off the WIRE and the registry is what
+   * does not know it. Distinct sentences keep the two greppable apart, which a
+   * shared phrasing would cost for nothing.
+   *
+   * A GETTER rather than a second field, so `type` stays the single declaration.
+   * What filling this field reaches, what it deliberately leaves untouched, and why
+   * a prototype accessor is visible at all are argued once on `CodecError` above and
+   * not restated here — it is the same package, the same published surface and the
+   * same mechanism, and two copies of that paragraph would be two things to keep in
+   * step. The read side's four getters point at one home for the identical reason.
+   */
+  get message() {
+    return `event type '${this.type}' is not in the registry`;
+  }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":["Data","CodecError","TaggedError","message","reason","UnknownEventType","type"],"sources":["../../src/errors.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;AAaA,SAASA,IAAI,QAAQ,QAAQ;AAE7B;AACA,OAAM,MAAOC,UAAW,sBAAQD,IAAI,CAACE,WAAW,CAAC,YAAY,CAG3D;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BA,IAAaC,OAAOA,CAAA;IAClB,OAAO,IAAI,CAACC,MAAM;EACpB;;AAGF;AACA,OAAM,MAAOC,gBAAiB,sBAAQL,IAAI,CAACE,WAAW,CAAC,kBAAkB,CAEvE;EACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8BA,IAAaC,OAAOA,CAAA;IAClB,OAAO,eAAe,IAAI,CAACG,IAAI,0BAA0B;EAC3D","ignoreList":[]}

package/dist/esm/event.js

@@ -0,0 +1,19 @@
+import { Schema } from 'effect';
+/**
+ * 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 = (type, fields, tagsFor) => {
+  const schema = Schema.Struct(fields);
+  return {
+    // The single EventType brand, applied once inside event(); no consumer casts.
+    type: type,
+    schema,
+    tagsFor
+  };
+};
+//# sourceMappingURL=event.js.map

package/dist/esm/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","names":["Schema","event","type","fields","tagsFor","schema","Struct"],"sources":["../../src/event.ts"],"sourcesContent":[null],"mappings":"AA+BA,SAASA,MAAM,QAAQ,QAAQ;AA+B/B;;;;;;;;AAQA,OAAO,MAAMC,KAAK,GAAGA,CAInBC,IAAU,EACVC,MAAc,EACdC,OAA4C,KAK1C;EACF,MAAMC,MAAM,GAAGL,MAAM,CAACM,MAAM,CAACH,MAAM,CAAC;EACpC,OAAO;IACL;IACAD,IAAI,EAAEA,IAAwB;IAC9BG,MAAM;IACND;GACD;AACH,CAAC","ignoreList":[]}

package/dist/esm/index.js

@@ -0,0 +1,63 @@
+/**
+ * @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 { decider, runDecider } from "./decider.js";
+export { buildDecisionModel, modelAtHead } from "./decisionModel.js";
+export { decodeSlices } from "./decode.js";
+export { CodecError, UnknownEventType } from "./errors.js";
+export { event } from "./event.js";
+export { projection } from "./projection.js";
+export { makeRegistry } from "./registry.js";
+export { Serializer, SerializerDefault } from "./Serializer.js";
+export { toEvent } from "./toEvent.js";
+export { Uuid, UuidLive, UuidTest } from "./Uuid.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["decider","runDecider","buildDecisionModel","modelAtHead","decodeSlices","CodecError","UnknownEventType","event","projection","makeRegistry","Serializer","SerializerDefault","toEvent","Uuid","UuidLive","UuidTest"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAuBA,OAAO,EAAEC,UAAU,QAAQ,cAAW;AAC7D,SACEC,kBAAkB,EAClBC,WAAW,QAEN,oBAAiB;AACxB,SAASC,YAAY,QAAQ,aAAU;AACvC,SAASC,UAAU,EAAEC,gBAAgB,QAAQ,aAAU;AACvD,SAA0CC,KAAK,QAAsB,YAAS;AAC9E,SAEEC,UAAU,QAEL,iBAAc;AACrB,SAASC,YAAY,QAAuB,eAAY;AACxD,SAASC,UAAU,EAAEC,iBAAiB,QAAQ,iBAAc;AAC5D,SAASC,OAAO,QAAQ,cAAW;AACnC,SAASC,IAAI,EAAEC,QAAQ,EAAEC,QAAQ,QAAQ,WAAQ","ignoreList":[]}

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": []
+}

package/dist/esm/projection.js

@@ -0,0 +1,110 @@
+/**
+ * The typed slice path (primary): a schema-backed projection and the fluent
+ * builder that produces it.
+ *
+ * A `SliceProjection<S, R>` is a core `AnyProjection<S>` (directly composable —
+ * its `evolve` folds a `DecodedEvent`) enriched with the `type -> Schema` map
+ * `decodeSlices` merges and decodes through. That map's value type carries `R`
+ * covariantly (`Schema<unknown, unknown, R>`), so the union of the defs'
+ * requirements flows to the decision model with no cast (and no phantom marker).
+ * Because `evolve` is already erased, a built slice drops straight into
+ * `composeProjections` — no `AnyProjection.of` ceremony.
+ *
+ * `projection(initialState).on(def, fold)...build()` infers the state `S` and
+ * the union `R` of the `.on`-ed defs' requirements, derives the read `Query`'s
+ * event-types from the defs' branded type literals (no `as EventType`), and
+ * hands each `fold` its decoded, typed payload. A handler for an un-imported
+ * event is therefore a compile error, and a mistyped type cannot silently match
+ * nothing.
+ */
+import { EventType } from '@kairos-es/core';
+/**
+ * Start a slice for `initialState`. Returns a builder with no defs yet
+ * (`R = never`); each `.on(def, fold)` widens `R` by the def's requirement.
+ */
+export const projection = initialState => {
+  // Persistent builder: `make` closes over the accumulated maps, and each
+  // `.on` copies them into a fresh builder rather than mutating in place, so
+  // no two derived builders ever share mutable state (reusing an intermediate
+  // builder can't cross-contaminate slices).
+  //
+  // `make` is generic in the accumulated requirement `R` — the parameter the
+  // builder is *about*. Pinning it to `never` and casting the result back would
+  // make the recursion typecheck by discarding the very thing each `.on` adds;
+  // threading `R` means the implementation states the same widening the
+  // `ProjectionBuilder` interface promises, and `on` returns without a cast.
+  const make = (schemas, folds) => ({
+    on: (def, fold) => {
+      // A repeated type WITHIN one chain is unambiguously a mistake, so this is
+      // a plain `has` rather than the reference-equality rule `mergeSliceSchemas`
+      // applies ACROSS slices. There, two entries for one type are the intended
+      // way to feed one event into two views, and the schemas being one object is
+      // what makes the collision harmless. Here there is only ever one fold per
+      // type — `evolve` dispatches by type into a single map — so a second `.on`
+      // cannot mean "as well as", only "instead of", and it silently discards
+      // the author's first fold along with its schema. The asymmetry is the
+      // point: the same `has` up there would outlaw the legitimate case.
+      if (schemas.has(def.type)) {
+        throw new Error(`duplicate event type '${def.type}' in slice: .on was called twice ` + 'for it, and the second fold would silently replace the first. ' + 'Handle both cases in one fold.');
+      }
+      // The entry type is annotated `R | R2` rather than inferred, and that
+      // annotation is what carries the requirement forward — `build` reads `R`
+      // straight off this map, so `RequirementOf` ultimately reads it from here.
+      // Widening the copied `R` entries into it costs nothing: `Schema` is
+      // declared `<in out A, in out I, out R>` upstream, hence covariant in its
+      // requirement.
+      const nextSchemas = new Map(schemas);
+      // Erasing `A`/`I` is the one unavoidable cast, and `as unknown as` is what
+      // it takes: `Schema` is INVARIANT in both, so `Schema<A, I, R2>` and
+      // `Schema<unknown, unknown, R2>` are unrelated in either direction. It is
+      // sound because the payload is only ever read back through `evolve`, which
+      // re-narrows by event type via the matching `fold`. The target names `R2`
+      // and not `never` because `R2` is what the def actually requires — an
+      // `Encrypted` field's `CipherKey` is not nothing — so the cast erases only
+      // what it has to and states the rest truthfully.
+      nextSchemas.set(def.type, def.schema);
+      const nextFolds = new Map(folds);
+      // Contravariance in the payload parameter, so this one is a cast too: the
+      // map holds folds over `unknown`, and `evolve` supplies the payload the
+      // matching def decoded, which is the `A` this fold was written against.
+      nextFolds.set(def.type, fold);
+      return make(nextSchemas, nextFolds);
+    },
+    build: options => {
+      // Internal-layer Query assembly from plain data (see core's Projection.ts
+      // note): a type-only-plus-optional-tags item the public surface withholds.
+      const types = [...schemas.keys()].map(t => EventType.make(t));
+      const query = {
+        items: [{
+          types,
+          tags: options?.tags ?? []
+        }]
+      };
+      return {
+        initialState,
+        query,
+        // Defensive copy: hand out a fresh Map, not the builder's own. `schemas`
+        // is typed `ReadonlyMap`, but that is a compile-time guard only — a
+        // caller who casts it back to `Map` could otherwise mutate the slice's
+        // live decode table after `build`, desyncing it from `query` (whose
+        // event-types were snapshotted from these keys just above). The copy is
+        // cheap (a handful of keys) and makes the slice genuinely immutable.
+        schemas: new Map(schemas),
+        // Erased evolve: dispatch by the sequenced event's type to the matching
+        // fold over the decoded payload. Per the `AnyProjection.evolve` contract
+        // (core), a projection is only ever handed events matching its `query` —
+        // `composeProjections` gates each sub before dispatch — so this needs no
+        // second `matchesSequenced` check; the `fold === undefined` fallback is
+        // the honest total-function guard (evolve is typed over any DecodedEvent).
+        evolve: (state, decoded) => {
+          const fold = folds.get(decoded.sequenced.event.type);
+          return fold === undefined ? state : fold(state, decoded.payload);
+        }
+      };
+    }
+  });
+  // Explicit `never`: an empty `Map` literal gives inference nothing to read the
+  // requirement off, and "no defs yet" is exactly `never`, not `unknown`.
+  return make(new Map(), new Map());
+};
+//# sourceMappingURL=projection.js.map

package/dist/esm/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","names":["EventType","projection","initialState","make","schemas","folds","on","def","fold","has","type","Error","nextSchemas","Map","set","schema","nextFolds","build","options","types","keys","map","t","query","items","tags","evolve","state","decoded","get","sequenced","event","undefined","payload"],"sources":["../../src/projection.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;AAmBA,SAGEA,SAAS,QAGJ,iBAAiB;AAoCxB;;;;AAIA,OAAO,MAAMC,UAAU,GAAOC,YAAe,IAAiC;EAC5E;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMC,IAAI,GAAGA,CACXC,OAAgE,EAChEC,KAA6D,MAChC;IAC7BC,EAAE,EAAEA,CACFC,GAAuB,EACvBC,IAAiC,KACD;MAChC;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACA,IAAIJ,OAAO,CAACK,GAAG,CAACF,GAAG,CAACG,IAAI,CAAC,EAAE;QACzB,MAAM,IAAIC,KAAK,CACb,yBAAyBJ,GAAG,CAACG,IAAI,mCAAmC,GAClE,gEAAgE,GAChE,gCAAgC,CACnC;MACH;MACA;MACA;MACA;MACA;MACA;MACA;MACA,MAAME,WAAW,GAAG,IAAIC,GAAG,CAGzBT,OAAO,CAAC;MACV;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MACAQ,WAAW,CAACE,GAAG,CACbP,GAAG,CAACG,IAAI,EACRH,GAAG,CAACQ,MAAwD,CAC7D;MACD,MAAMC,SAAS,GAAG,IAAIH,GAAG,CAACR,KAAK,CAAC;MAChC;MACA;MACA;MACAW,SAAS,CAACF,GAAG,CAACP,GAAG,CAACG,IAAI,EAAEF,IAAyC,CAAC;MAClE,OAAOL,IAAI,CAASS,WAAW,EAAEI,SAAS,CAAC;IAC7C,CAAC;IACDC,KAAK,EAAGC,OAAO,IAAI;MACjB;MACA;MACA,MAAMC,KAAK,GAAG,CAAC,GAAGf,OAAO,CAACgB,IAAI,EAAE,CAAC,CAACC,GAAG,CAAEC,CAAC,IAAKtB,SAAS,CAACG,IAAI,CAACmB,CAAC,CAAC,CAAC;MAC/D,MAAMC,KAAK,GAAU;QACnBC,KAAK,EAAE,CAAC;UAAEL,KAAK;UAAEM,IAAI,EAAEP,OAAO,EAAEO,IAAI,IAAI;QAAE,CAAE;OAC7C;MACD,OAAO;QACLvB,YAAY;QACZqB,KAAK;QACL;QACA;QACA;QACA;QACA;QACA;QACAnB,OAAO,EAAE,IAAIS,GAAG,CAACT,OAAO,CAAC;QACzB;QACA;QACA;QACA;QACA;QACA;QACAsB,MAAM,EAAEA,CAACC,KAAK,EAAEC,OAAqB,KAAI;UACvC,MAAMpB,IAAI,GAAGH,KAAK,CAACwB,GAAG,CAACD,OAAO,CAACE,SAAS,CAACC,KAAK,CAACrB,IAAI,CAAC;UACpD,OAAOF,IAAI,KAAKwB,SAAS,GAAGL,KAAK,GAAGnB,IAAI,CAACmB,KAAU,EAAEC,OAAO,CAACK,OAAO,CAAC;QACvE;OACD;IACH;GACD,CAAC;EACF;EACA;EACA,OAAO9B,IAAI,CAAQ,IAAIU,GAAG,EAAE,EAAE,IAAIA,GAAG,EAAE,CAAC;AAC1C,CAAC","ignoreList":[]}

package/dist/esm/registry.js

@@ -0,0 +1,34 @@
+import { Effect } from 'effect';
+import { deserialiseThenDecode } from "./deserialiseThenDecode.js";
+import { UnknownEventType } from "./errors.js";
+import { Serializer } from "./Serializer.js";
+export const makeRegistry = defs => {
+  const map = new Map();
+  for (const def of defs) {
+    if (map.has(def.type)) {
+      throw new Error(`duplicate event type '${def.type}' in registry`);
+    }
+    map.set(def.type, def.schema);
+  }
+  return {
+    decode: event => Effect.gen(function* () {
+      const schema = map.get(event.type);
+      if (schema === undefined) {
+        return yield* Effect.fail(new UnknownEventType({
+          type: event.type
+        }));
+      }
+      const serializer = yield* Serializer;
+      const payload = yield* deserialiseThenDecode(serializer, schema, event.data);
+      return {
+        type: event.type,
+        payload
+      };
+      // The schema map erases `R` to `unknown`; the declared `R` is recovered
+      // from `Defs` at the type level, so the gen block's inferred requirement
+      // (`unknown`) is re-stated as `Serializer | R` here, which is this
+      // module's only cast.
+    })
+  };
+};
+//# sourceMappingURL=registry.js.map

package/dist/esm/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","names":["Effect","deserialiseThenDecode","UnknownEventType","Serializer","makeRegistry","defs","map","Map","def","has","type","Error","set","schema","decode","event","gen","get","undefined","fail","serializer","payload","data"],"sources":["../../src/registry.ts"],"sourcesContent":[null],"mappings":"AA2BA,SAASA,MAAM,QAAqB,QAAQ;AAC5C,SAASC,qBAAqB,QAAQ,4BAAyB;AAC/D,SAA0BC,gBAAgB,QAAQ,aAAU;AAE5D,SAASC,UAAU,QAAQ,iBAAc;AAqBzC,OAAO,MAAMC,YAAY,GACvBC,IAAU,IAC2B;EACrC,MAAMC,GAAG,GAAG,IAAIC,GAAG,EAAoD;EACvE,KAAK,MAAMC,GAAG,IAAIH,IAAI,EAAE;IACtB,IAAIC,GAAG,CAACG,GAAG,CAACD,GAAG,CAACE,IAAI,CAAC,EAAE;MACrB,MAAM,IAAIC,KAAK,CAAC,yBAAyBH,GAAG,CAACE,IAAI,eAAe,CAAC;IACnE;IACAJ,GAAG,CAACM,GAAG,CAACJ,GAAG,CAACE,IAAI,EAAEF,GAAG,CAACK,MAAM,CAAC;EAC/B;EACA,OAAO;IACLC,MAAM,EAAGC,KAAK,IACZf,MAAM,CAACgB,GAAG,CAAC,aAAS;MAClB,MAAMH,MAAM,GAAGP,GAAG,CAACW,GAAG,CAACF,KAAK,CAACL,IAAI,CAAC;MAClC,IAAIG,MAAM,KAAKK,SAAS,EAAE;QACxB,OAAO,OAAOlB,MAAM,CAACmB,IAAI,CAAC,IAAIjB,gBAAgB,CAAC;UAAEQ,IAAI,EAAEK,KAAK,CAACL;QAAI,CAAE,CAAC,CAAC;MACvE;MACA,MAAMU,UAAU,GAAG,OAAOjB,UAAU;MACpC,MAAMkB,OAAO,GAAG,OAAOpB,qBAAqB,CAC1CmB,UAAU,EACVP,MAAM,EACNE,KAAK,CAACO,IAAI,CACX;MACD,OAAO;QAAEZ,IAAI,EAAEK,KAAK,CAACL,IAAI;QAAEW;MAAO,CAAE;MACpC;MACA;MACA;MACA;IACF,CAAC;GAKJ;AACH,CAAC","ignoreList":[]}

package/dist/esm/toEvent.js

@@ -0,0 +1,44 @@
+import { DateTime, Effect, Schema } from 'effect';
+import { CodecError } from "./errors.js";
+import { Serializer } from "./Serializer.js";
+import { Uuid } from "./Uuid.js";
+/**
+ * Encode `payload` under `def` and stamp it into a wire `DcbEvent`, deriving its
+ * `tags` from `def.tagsFor(payload)` (a throwing mapper surfaces as a
+ * `CodecError`, not a defect). The tags are stamped exactly as the mapper
+ * returns them — no dedup or reordering. `type` and `tags` are cleartext
+ * wire-envelope fields (the query surface), so a `tagsFor` mapper may only key
+ * off cleartext payload fields (ADR-0006). `uuid` / `occurredAt` are
+ * exact-optional overrides; absent, they come from the `Uuid` service and the
+ * Effect clock.
+ */
+export const toEvent = (def, payload, options) => Effect.gen(function* () {
+  // Derive tags first. A mapper is app code that can throw (e.g. `Tag.make`
+  // rejects an ill-formed `key:value`), and the codec's contract is that such
+  // failures are values on the `CodecError` channel, never defects (errors.ts).
+  // Deriving before the uuid/clock effects also means a bad tag fails without
+  // consuming the `Uuid` sequence.
+  const tags = yield* Effect.try({
+    try: () => def.tagsFor(payload),
+    catch: cause => new CodecError({
+      reason: 'tags',
+      cause
+    })
+  });
+  const serializer = yield* Serializer;
+  const encoded = yield* Schema.encode(def.schema)(payload).pipe(Effect.mapError(cause => new CodecError({
+    reason: 'encode',
+    cause
+  })));
+  const data = serializer.serialise(encoded);
+  const uuid = options?.uuid ?? (yield* (yield* Uuid).generate);
+  const occurredAt = options?.occurredAt ?? (yield* DateTime.now);
+  return {
+    type: def.type,
+    data,
+    tags,
+    uuid,
+    occurredAt
+  };
+});
+//# sourceMappingURL=toEvent.js.map

package/dist/esm/toEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toEvent.js","names":["DateTime","Effect","Schema","CodecError","Serializer","Uuid","toEvent","def","payload","options","gen","tags","try","tagsFor","catch","cause","reason","serializer","encoded","encode","schema","pipe","mapError","data","serialise","uuid","generate","occurredAt","now","type"],"sources":["../../src/toEvent.ts"],"sourcesContent":[null],"mappings":"AAcA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AACjD,SAASC,UAAU,QAAQ,aAAU;AAErC,SAASC,UAAU,QAAQ,iBAAc;AACzC,SAASC,IAAI,QAAQ,WAAQ;AAE7B;;;;;;;;;;AAUA,OAAO,MAAMC,OAAO,GAAGA,CACrBC,GAAsB,EACtBC,OAAU,EACVC,OAGC,KAEDR,MAAM,CAACS,GAAG,CAAC,aAAS;EAClB;EACA;EACA;EACA;EACA;EACA,MAAMC,IAAI,GAAG,OAAOV,MAAM,CAACW,GAAG,CAAC;IAC7BA,GAAG,EAAEA,CAAA,KAAML,GAAG,CAACM,OAAO,CAACL,OAAO,CAAC;IAC/BM,KAAK,EAAGC,KAAK,IAAK,IAAIZ,UAAU,CAAC;MAAEa,MAAM,EAAE,MAAM;MAAED;IAAK,CAAE;GAC3D,CAAC;EACF,MAAME,UAAU,GAAG,OAAOb,UAAU;EACpC,MAAMc,OAAO,GAAG,OAAOhB,MAAM,CAACiB,MAAM,CAACZ,GAAG,CAACa,MAAM,CAAC,CAACZ,OAAO,CAAC,CAACa,IAAI,CAC5DpB,MAAM,CAACqB,QAAQ,CAAEP,KAAK,IAAK,IAAIZ,UAAU,CAAC;IAAEa,MAAM,EAAE,QAAQ;IAAED;EAAK,CAAE,CAAC,CAAC,CACxE;EACD,MAAMQ,IAAI,GAAGN,UAAU,CAACO,SAAS,CAACN,OAAO,CAAC;EAC1C,MAAMO,IAAI,GAAGhB,OAAO,EAAEgB,IAAI,KAAK,OAAO,CAAC,OAAOpB,IAAI,EAAEqB,QAAQ,CAAC;EAC7D,MAAMC,UAAU,GAAGlB,OAAO,EAAEkB,UAAU,KAAK,OAAO3B,QAAQ,CAAC4B,GAAG,CAAC;EAC/D,OAAO;IACLC,IAAI,EAAEtB,GAAG,CAACsB,IAAI;IACdN,IAAI;IACJZ,IAAI;IACJc,IAAI;IACJE;GACD;AACH,CAAC,CAAC","ignoreList":[]}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@kairos-es/codec",
+  "version": "0.0.0",
+  "description": "Schema-first codec with encryption seam for kairos-es",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverbland/kairos-es.git",
+    "directory": "packages/codec"
+  },
+  "sideEffects": [],
+  "homepage": "https://github.com/neverbland/kairos-es",
+  "peerDependencies": {
+    "effect": "^3.22.0",
+    "@kairos-es/core": "^0.0.0"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/dts/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "default": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {}
+  }
+}