@kairos-es/codec 0.0.0

package/dist/dts/index.d.ts

@@ -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 { type Decider, decider, runDecider } from './decider.js';
+export { buildDecisionModel, modelAtHead, type RequirementOf, } from './decisionModel.js';
+export { decodeSlices } from './decode.js';
+export { CodecError, UnknownEventType } from './errors.js';
+export { type EventDef, type EventDefAny, event, type TagsFor } from './event.js';
+export { type ProjectionBuilder, projection, type SliceProjection, } from './projection.js';
+export { makeRegistry, type Registry } from './registry.js';
+export { Serializer, SerializerDefault } from './Serializer.js';
+export { toEvent } from './toEvent.js';
+export { Uuid, UuidLive, UuidTest } from './Uuid.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAC9E,OAAO,EACL,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA"}

package/dist/dts/projection.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { type AnyProjection, type Tag } from '@kairos-es/core';
+import type { Schema } from 'effect';
+import type { EventDef } from './event.js';
+/**
+ * A schema-backed, directly-composable projection: an `AnyProjection<S>` plus
+ * the `type -> Schema` map for decode. The map's value type carries the union
+ * `R` of its defs' requirements covariantly, so `RequirementOf` recovers `R`
+ * (and the `out R` annotation keeps union-widening sound) with no phantom marker.
+ */
+export interface SliceProjection<out S = unknown, out R = unknown> extends AnyProjection<S> {
+    readonly schemas: ReadonlyMap<string, Schema.Schema<unknown, unknown, R>>;
+}
+/** The fluent builder: accumulate `.on(def, fold)` steps, then `.build()`. */
+export interface ProjectionBuilder<S, R = never> {
+    /**
+     * Fold events of `def`'s type: `fold` receives the decoded, typed `payload`.
+     * Adds `def`'s requirement `R2` to the accumulated `R`.
+     *
+     * Throws if this chain has already `.on`-ed that event type — see the guard in
+     * `projection` for why a repeat is always a mistake here, where across two
+     * slices it need not be.
+     */
+    on<A, I, R2>(def: EventDef<A, I, R2>, fold: (state: S, payload: A) => S): ProjectionBuilder<S, R | R2>;
+    /**
+     * Materialise the slice. The query is a single item over the `.on`-ed defs'
+     * types (branded via `EventType.make`) and `options.tags` (default none).
+     */
+    build(options?: {
+        readonly tags?: ReadonlyArray<Tag>;
+    }): SliceProjection<S, R>;
+}
+/**
+ * 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 declare const projection: <S>(initialState: S) => ProjectionBuilder<S, never>;
+//# sourceMappingURL=projection.d.ts.map

package/dist/dts/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,KAAK,aAAa,EAIlB,KAAK,GAAG,EACT,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,GAAG,OAAO,CAC/D,SAAQ,aAAa,CAAC,CAAC,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAA;CAC1E;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK;IAC7C;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EACT,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EACvB,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,GAChC,iBAAiB,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAA;IAC/B;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC,CAAA;KAAE,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;CAC/E;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,cAAc,CAAC,KAAG,iBAAiB,CAAC,CAAC,EAAE,KAAK,CAiGzE,CAAA"}

package/dist/dts/registry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The general (registry) path (minimal): decode an arbitrary wire event by its
+ * runtime type string. This is the one place a type outside the known set
+ * surfaces as a typed `UnknownEventType` — the home of ADR-0005 decode-totality.
+ *
+ * `makeRegistry(defs)` builds a `type -> Schema` map with a construction-time
+ * uniqueness guard (a duplicate type throws at wiring, not at runtime). Its
+ * requirement `R` is the union of the defs' requirements. `decode` looks the
+ * type up, then runs `deserialiseThenDecode` over the bytes, yielding
+ * `{ type, payload: unknown }`. That `unknown` is the point of the path rather
+ * than a gap in it: the type is discovered at RUNTIME off the wire event, so the
+ * caller has named no def and the return is deliberately NOT a discriminated
+ * union over `Defs`. What this path owes its caller is decode TOTALITY — every
+ * known type decodes, an unknown one fails as `UnknownEventType` — and not typed
+ * access. A caller who wants a typed payload names the def it expects and takes
+ * the typed slice path (`projection(init).on(def, fold)`), where each fold
+ * receives its payload already decoded and narrowed.
+ *
+ * What is this path's OWN and what it merely shares. The lookup is its own: a
+ * miss here is `UnknownEventType`, where the same miss on the typed path is a
+ * `CodecError` about a schema the caller did not supply — the asymmetry ADR-0005
+ * exists for. Everything after the lookup is the two-step both paths perform, so
+ * it is `deserialiseThenDecode` that owns it and fixes the `deserialise` /
+ * `decode` `reason` strings; this module holding a second copy is exactly how one
+ * of them would come to be reworded on one path only.
+ */
+import type { DcbEvent } from '@kairos-es/core';
+import { Effect } from 'effect';
+import { type CodecError, UnknownEventType } from './errors.js';
+import type { EventDef, EventDefAny } from './event.js';
+import { Serializer } from './Serializer.js';
+/** A registry decoding arbitrary wire events; `R` is the union of def requirements. */
+export interface Registry<R> {
+    readonly decode: (event: DcbEvent) => Effect.Effect<{
+        readonly type: string;
+        readonly payload: unknown;
+    }, UnknownEventType | CodecError, Serializer | R>;
+}
+/**
+ * Build a `Registry` from a def barrel. Throws at construction on a duplicate
+ * type; `R` is the union of the defs' requirements.
+ */
+type RequirementOfDefs<Defs extends ReadonlyArray<EventDefAny>> = Defs[number] extends EventDef<any, any, infer R> ? R : never;
+export declare const makeRegistry: <Defs extends ReadonlyArray<EventDefAny>>(defs: Defs) => Registry<RequirementOfDefs<Defs>>;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/dts/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,MAAM,EAAe,MAAM,QAAQ,CAAA;AAE5C,OAAO,EAAE,KAAK,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAEzC,uFAAuF;AACvF,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,QAAQ,KACZ,MAAM,CAAC,MAAM,CAChB;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,EACpD,gBAAgB,GAAG,UAAU,EAC7B,UAAU,GAAG,CAAC,CACf,CAAA;CACF;AAED;;;GAGG;AACH,KAAK,iBAAiB,CAAC,IAAI,SAAS,aAAa,CAAC,WAAW,CAAC,IAE5D,IAAI,CAAC,MAAM,CAAC,SAAS,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAE9D,eAAO,MAAM,YAAY,GAAI,IAAI,SAAS,aAAa,CAAC,WAAW,CAAC,EAClE,MAAM,IAAI,KACT,QAAQ,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAgClC,CAAA"}

package/dist/dts/toEvent.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Event production (codec edge-helper): turn a typed payload into a wire
+ * `DcbEvent`. Encode is `Schema.encode(def.schema)` (a `ParseError` becomes a
+ * `CodecError`; any encryption transform runs here, *before* serialisation)
+ * then `serialiser.serialise`. The wire `tags` are derived from the def's
+ * required `tagsFor` mapper (ADR-0006) — they are never hand-passed, so two
+ * command sites emitting the same event type cannot tag it differently. A mapper
+ * that throws (e.g. an ill-formed `key:value` rejected by `Tag.make`) is
+ * surfaced on the `CodecError` channel, not as a defect. `uuid`
+ * comes from `options.uuid` or the `Uuid` service; `occurredAt` from
+ * `options.occurredAt` or the Effect clock (`DateTime.now`), keeping `core`
+ * clock- and RNG-free while staying overridable for backdated imports.
+ */
+import type { DcbEvent } from '@kairos-es/core';
+import { DateTime, Effect } from 'effect';
+import { CodecError } from './errors.js';
+import type { EventDef } from './event.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 declare const toEvent: <A, I, R>(def: EventDef<A, I, R>, payload: A, options?: {
+    readonly uuid?: string;
+    readonly occurredAt?: DateTime.Utc;
+}) => Effect.Effect<DcbEvent, CodecError, Serializer | Uuid | R>;
+//# sourceMappingURL=toEvent.d.ts.map

package/dist/dts/toEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toEvent.d.ts","sourceRoot":"","sources":["../../src/toEvent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAA;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAE7B;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAC7B,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACtB,SAAS,CAAC,EACV,UAAU;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAA;CACnC,KACA,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,CAAC,CAyBxD,CAAA"}

package/dist/esm/Serializer.js

@@ -0,0 +1,26 @@
+/**
+ * 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 /*#__PURE__*/Context.Tag('@kairos-es/codec/Serializer')() {}
+const encoder = /*#__PURE__*/new TextEncoder();
+const decoder = /*#__PURE__*/new TextDecoder();
+/**
+ * The shipped default: JSON over UTF-8. `serialise` = `JSON.stringify` then
+ * `TextEncoder`; `deserialise` = `TextDecoder` then `JSON.parse` (which throws
+ * synchronously on corrupt bytes, wrapped to `CodecError` at the call site).
+ */
+export const SerializerDefault = /*#__PURE__*/Layer.succeed(Serializer, {
+  serialise: v => encoder.encode(JSON.stringify(v)),
+  deserialise: b => JSON.parse(decoder.decode(b))
+});
+//# sourceMappingURL=Serializer.js.map

package/dist/esm/Serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.js","names":["Context","Layer","Serializer","Tag","encoder","TextEncoder","decoder","TextDecoder","SerializerDefault","succeed","serialise","v","encode","JSON","stringify","deserialise","b","parse","decode"],"sources":["../../src/Serializer.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;AAYA,SAASA,OAAO,EAAEC,KAAK,QAAQ,QAAQ;AAEvC,OAAM,MAAOC,UAAW,sBAAQF,OAAO,CAACG,GAAG,CAAC,6BAA6B,CAAC,EAMvE;AAEH,MAAMC,OAAO,gBAAG,IAAIC,WAAW,EAAE;AACjC,MAAMC,OAAO,gBAAG,IAAIC,WAAW,EAAE;AAEjC;;;;;AAKA,OAAO,MAAMC,iBAAiB,gBAA4BP,KAAK,CAACQ,OAAO,CACrEP,UAAU,EACV;EACEQ,SAAS,EAAGC,CAAC,IAAKP,OAAO,CAACQ,MAAM,CAACC,IAAI,CAACC,SAAS,CAACH,CAAC,CAAC,CAAC;EACnDI,WAAW,EAAGC,CAAC,IAAKH,IAAI,CAACI,KAAK,CAACX,OAAO,CAACY,MAAM,CAACF,CAAC,CAAC;CACjD,CACF","ignoreList":[]}

package/dist/esm/Uuid.js

@@ -0,0 +1,33 @@
+/**
+ * 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 /*#__PURE__*/Context.Tag('@kairos-es/codec/Uuid')() {}
+/** Live uuid generation via WebCrypto (no `node:crypto`). */
+export const UuidLive = /*#__PURE__*/Layer.succeed(Uuid, {
+  generate: /*#__PURE__*/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 = /*#__PURE__*/Layer.sync(Uuid, () => {
+  const next = makeSequentialUuid();
+  return {
+    generate: Effect.sync(next)
+  };
+});
+//# sourceMappingURL=Uuid.js.map

package/dist/esm/Uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Uuid.js","names":["makeSequentialUuid","Context","Effect","Layer","Uuid","Tag","UuidLive","succeed","generate","sync","globalThis","crypto","randomUUID","UuidTest","next"],"sources":["../../src/Uuid.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;AAWA,SAASA,kBAAkB,QAAQ,yBAAyB;AAC5D,SAASC,OAAO,EAAEC,MAAM,EAAEC,KAAK,QAAQ,QAAQ;AAE/C,OAAM,MAAOC,IAAK,sBAAQH,OAAO,CAACI,GAAG,CAAC,uBAAuB,CAAC,EAG3D;AAEH;AACA,OAAO,MAAMC,QAAQ,gBAAsBH,KAAK,CAACI,OAAO,CAACH,IAAI,EAAE;EAC7DI,QAAQ,eAAEN,MAAM,CAACO,IAAI,CAAC,MAAMC,UAAU,CAACC,MAAM,CAACC,UAAU,EAAE;CAC3D,CAAC;AAEF;;;;;;;;AAQA,OAAO,MAAMC,QAAQ,gBAAsBV,KAAK,CAACM,IAAI,CAACL,IAAI,EAAE,MAAK;EAC/D,MAAMU,IAAI,GAAGd,kBAAkB,EAAE;EACjC,OAAO;IAAEQ,QAAQ,EAAEN,MAAM,CAACO,IAAI,CAACK,IAAI;EAAC,CAAE;AACxC,CAAC,CAAC","ignoreList":[]}

package/dist/esm/decider.js

@@ -0,0 +1,143 @@
+/**
+ * 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 { DcbEventStore } from '@kairos-es/core';
+import { Effect } from 'effect';
+import { buildDecisionModel } from "./decisionModel.js";
+/**
+ * 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 = (projections, decide) => ({
+  projections,
+  decide
+});
+/**
+ * Run the full DCB command cycle for a decider against the ambient
+ * `DcbEventStore`: build the decision model (real read + decode + fold), decide,
+ * and append under the read's append condition. Returns the last new position.
+ *
+ * The requirement is `DcbEventStore | Serializer | Uuid | R |
+ * RequirementOf<P>`: `Serializer` enters through both the decode
+ * (`buildDecisionModel`) and produce (`toEvent`) sides, `Uuid` through produce,
+ * the slices' `RequirementOf<P>` through decode, and `R` through produce. (For a
+ * def whose `Schema` carries a requirement, `RequirementOf<P>` and `R` are the
+ * same tag.) Any `decide` failure, a decode `CodecError`, or an
+ * `AppendConditionFailed` propagates on the error channel unchanged.
+ */
+export const runDecider = (decider, command) => 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);
+});
+//# sourceMappingURL=decider.js.map

package/dist/esm/decider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decider.js","names":["DcbEventStore","Effect","buildDecisionModel","decider","projections","decide","runDecider","command","gen","store","state","appendCondition","newEvents","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAASA,aAAa,QAAQ,iBAAiB;AAE/C,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAASC,kBAAkB,QAA4B,oBAAiB;AAsCxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,OAAO,MAAMC,OAAO,GAAGA,CASrBC,WAAoC,EACpCC,MAA2D,MAO1D;EAAED,WAAW;EAAEC;AAAM,CAAE,CAKvB;AAEH;;;;;;;;;;;;;AAaA,OAAO,MAAMC,UAAU,GAAGA,CAMxBH,OAAkC,EAClCI,OAAgB,KAMhBN,MAAM,CAACO,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOT,aAAa;EAClC,MAAM;IAAEU,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAOT,kBAAkB,CAC1DC,OAAO,CAACC,WAAW,CAACG,OAAO,CAAC,CAC7B;EACD,MAAMK,SAAS,GAAG,OAAOT,OAAO,CAACE,MAAM,CAACK,KAAK,EAAEH,OAAO,CAAC;EACvD,OAAO,OAAOE,KAAK,CAACI,MAAM,CAACD,SAAS,EAAED,eAAe,CAAC;AACxD,CAAC,CAAC","ignoreList":[]}

package/dist/esm/decisionModel.js

@@ -0,0 +1,146 @@
+/**
+ * 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 { composeProjections, DcbEventStore } from '@kairos-es/core';
+import { Effect, Stream } from 'effect';
+import { decodeSlices } from "./decode.js";
+/**
+ * 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 = projections => 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);
+  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));
+  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 = projections => Effect.map(modelAtHead(projections), ({
+  state,
+  head
+}) => ({
+  state,
+  appendCondition: {
+    failIfEventsMatch: composeProjections(projections).query,
+    after: head
+  }
+}));
+//# sourceMappingURL=decisionModel.js.map

package/dist/esm/decisionModel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisionModel.js","names":["composeProjections","DcbEventStore","Effect","Stream","decodeSlices","modelAtHead","projections","gen","store","decode","composite","events","head","read","query","decoded","state","runFold","initialState","acc","event","evolve","buildDecisionModel","map","appendCondition","failIfEventsMatch","after"],"sources":["../../src/decisionModel.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAIEA,kBAAkB,EAClBC,aAAa,QAER,iBAAiB;AACxB,SAASC,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AACvC,SAASC,YAAY,QAAQ,aAAU;AASvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,OAAO,MAAMC,WAAW,GACtBC,WAAc,IAMdJ,MAAM,CAACK,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOP,aAAa;EAElC;EACA;EACA;EACA,MAAMQ,MAAM,GAAGL,YAAY,CAACE,WAAW,CAAC;EAExC;EACA,MAAMI,SAAS,GAAGV,kBAAkB,CAClCM,WAA4C,CAC7C;EACD,MAAM;IAAEK,MAAM;IAAEC;EAAI,CAAE,GAAG,OAAOJ,KAAK,CAACK,IAAI,CAACH,SAAS,CAACI,KAAK,CAAC;EAE3D,MAAMC,OAAO,GAAGN,MAAM,CAACE,MAAM,CAAC;EAE9B,MAAMK,KAAK,GAAI,OAAOb,MAAM,CAACc,OAAO,CAClCF,OAAO,EACPL,SAAS,CAACQ,YAAY,EACtB,CAACC,GAAG,EAAEC,KAAK,KAAKV,SAAS,CAACW,MAAM,CAACF,GAAG,EAAEC,KAAK,CAAC,CACvB;EAEvB,OAAO;IAAEJ,KAAK;IAAEJ;EAAI,CAAE;AACxB,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,OAAO,MAAMU,kBAAkB,GAC7BhB,WAAc,IASdJ,MAAM,CAACqB,GAAG,CAAClB,WAAW,CAACC,WAAW,CAAC,EAAE,CAAC;EAAEU,KAAK;EAAEJ;AAAI,CAAE,MAAM;EACzDI,KAAK;EACLQ,eAAe,EAAE;IACfC,iBAAiB,EAAEzB,kBAAkB,CACnCM,WAA4C,CAC7C,CAACQ,KAAK;IACPY,KAAK,EAAEd;;CAEV,CAAC,CAAC","ignoreList":[]}