@kairos-es/testing 0.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,13 @@
+# @kairos-es/testing
+
+Given/When/Then decision-model testing surface for kairos-es.
+
+A `DeciderSpecification`-equivalent over the codec's `buildDecisionModel`, running
+the real read → decode → decide → append cycle against the in-memory store rather
+than a mock, on `@effect/vitest`. `@kairos-es/core`, `@kairos-es/codec`, `effect`
+and `@effect/vitest` are peer dependencies.
+
+The `Decider` a scenario exercises and the `runDecider` that runs it are
+production symbols and belong to [`@kairos-es/codec`](../codec); this package
+imports them and deliberately does not re-export them, so typing a command
+handler never means naming a package that peers a test framework.

package/dist/cjs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _specification = require("./specification.js");
+Object.keys(_specification).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _specification[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _specification[key];
+    }
+  });
+});
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_specification","require","Object","keys","forEach","key","exports","defineProperty","enumerable","get"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":";;;;;AA0BA,IAAAA,cAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,cAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAA,GAAA,IAAAC,OAAA,IAAAA,OAAA,CAAAD,GAAA,MAAAL,cAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAK,cAAA,CAAAD,OAAA,EAAAD,GAAA;IAAAG,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAT,cAAA,CAAAK,GAAA;IAAA;EAAA;AAAA","ignoreList":[]}

package/dist/cjs/specification.js

@@ -0,0 +1,159 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.specificationFor = exports.scenario = void 0;
+var _vitest = require("@effect/vitest");
+var _codec = require("@kairos-es/codec");
+var _core = require("@kairos-es/core");
+var _effect = require("effect");
+/**
+ * The Given/When/Then surface: a `DeciderSpecification`-equivalent over the real
+ * `@kairos-es/codec` `buildDecisionModel` fold and a `DcbEventStore` (the
+ * in-memory layer in practice). It is shaped so an Event Modeling
+ * `Specification` (given events, when a command, then events / thenError a tag)
+ * compiles onto it 1:1 — prior art: dcb-events `TestRunner` and Emmett's
+ * `DeciderSpecification`.
+ *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .then(...expectedNewEventProducers)   // success branch
+ *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .thenError('AppendConditionFailed')   // failure branch (domain error or conflict)
+ *
+ * Events are supplied *effectfully*: a given/expected event is the producer an
+ * application authors via `toEvent` — an `Effect<DcbEvent, CodecError,
+ * Serializer | Uuid | R>` — so both sides materialise (encode -> serialise)
+ * under the same layers the cycle runs against, and their `data` bytes match.
+ *
+ * Each terminal (`then` / `thenError`) returns an `Effect` requiring
+ * `DcbEventStore | Serializer | Uuid | R`, so a test provides the store,
+ * serialiser, and uuid layers (fresh store per case for isolation).
+ * `scenario(...)` wraps the whole thing in `@effect/vitest`'s `it.effect`
+ * against a fresh in-memory store plus `SerializerDefault` and `UuidTest`, so
+ * example specs read as one line.
+ *
+ * `then` compares the *appended* events (those written past the given seed) to
+ * the expected batch structurally — by `type`, `tags`, and `data` — ignoring
+ * the store-assigned `position` and the producer-supplied `uuid`/`occurredAt`,
+ * which are not part of the decision under test. JSON serialisation is
+ * deterministic, so equal payloads produce equal `data` bytes.
+ */
+
+const shapeOf = event => ({
+  type: event.type,
+  tags: event.tags,
+  data: event.data
+});
+/** Collect a stream of sequenced events into a plain array. */
+const collect = events => _effect.Stream.runCollect(events).pipe(_effect.Effect.map(_effect.Chunk.toReadonlyArray));
+/**
+ * Seed the given past-event producers into the store: materialise each producer
+ * (encode -> serialise), then one append each (log order). Returns the position
+ * the LAST seeded append was written at, or `ORIGIN` when nothing was seeded —
+ * this is the boundary `then` reads strictly after.
+ *
+ * We track the boundary by position rather than by count because positions are
+ * gappy on a real store (Postgres `bigserial` skips values on rollbacks and
+ * across concurrent writers), so "everything past N rows" is wrong; "everything
+ * strictly after this position" is exact regardless of gaps.
+ */
+const seed = producers => _effect.Effect.gen(function* () {
+  const store = yield* _core.DcbEventStore;
+  let last = _core.ORIGIN;
+  for (const producer of producers) {
+    const event = yield* producer;
+    // Unconditional appends never fail; a failure here would be a defect in
+    // the store, not a domain outcome, so turn it into one.
+    last = yield* store.append([event]).pipe(_effect.Effect.orDie);
+  }
+  return last;
+});
+/**
+ * The events appended past the seed boundary, so `then` can read back exactly
+ * the events the decider appended. We read all matching events strictly after
+ * `after` (the last seeded position), which is correct on a gappy store where
+ * dropping a fixed row count would not be — the in-memory store gives the
+ * identical result because its positions are gapless.
+ */
+const appendedAfter = after => _effect.Effect.gen(function* () {
+  const store = yield* _core.DcbEventStore;
+  const {
+    events
+  } = yield* store.read(_core.query.all(), {
+    after
+  });
+  return yield* collect(events);
+});
+/**
+ * Begin a specification for `decider`. The returned `given(...)` starts the
+ * Given/When/Then chain; the terminal step yields an `Effect` requiring
+ * `DcbEventStore | Serializer | Uuid | R | RequirementOf<P>`.
+ */
+const specificationFor = decider => ({
+  given: (...pastEvents) => ({
+    when: command => {
+      // Run the seed + decider cycle, exposing the outcome as an Exit so both
+      // branches (then / thenError) can inspect success or failure uniformly. The
+      // seed is inside the Exit too, so a decode failure while materialising a
+      // given producer is captured as a failure rather than escaping the channel.
+      // The success value pairs the seed boundary (the last seeded position) with
+      // the decider's outcome, so `then` reads strictly after that boundary
+      // rather than dropping a fixed row count (correct on a gappy store).
+      const runToExit = seed(pastEvents).pipe(_effect.Effect.zip((0, _codec.runDecider)(decider, command)), _effect.Effect.exit);
+      return {
+        // biome-ignore lint/suspicious/noThenProperty: deliberate Given/When/Then terminal name (see WhenSpec.then); never awaited as a thenable.
+        then: (...expected) => _effect.Effect.gen(function* () {
+          const exit = yield* runToExit;
+          if (_effect.Exit.isFailure(exit)) {
+            // Surface the real failure to the caller's error channel; a
+            // `.then` on a failing cycle is a test authoring mistake, so make
+            // it loud rather than silently passing.
+            return yield* _effect.Effect.failCause(exit.cause);
+          }
+          const [seedBoundary] = exit.value;
+          const appended = yield* appendedAfter(seedBoundary);
+          const expectedEvents = yield* _effect.Effect.all(expected);
+          (0, _vitest.expect)(appended.map(s => shapeOf(s.event))).toEqual(expectedEvents.map(shapeOf));
+        }),
+        thenError: tag => _effect.Effect.gen(function* () {
+          const exit = yield* runToExit;
+          (0, _vitest.expect)(_effect.Exit.isFailure(exit)).toBe(true);
+          if (_effect.Exit.isFailure(exit)) {
+            const failure = _effect.Cause.failureOption(exit.cause);
+            const error = failure._tag === 'Some' ? failure.value : undefined;
+            const actualTag = typeof error === 'object' && error !== null && '_tag' in error ? error._tag : undefined;
+            (0, _vitest.expect)(actualTag).toBe(tag);
+          }
+        })
+      };
+    }
+  })
+});
+/**
+ * `scenario(description, spec => spec.given(...).when(...).then(...))` — register
+ * an `@effect/vitest` `it.effect` case running `build` against a fresh in-memory
+ * `DcbEventStore` plus the default serialiser and a fresh deterministic uuid
+ * layer. The callback receives `specificationFor(decider)` so example suites
+ * read as a single Given/When/Then line per case.
+ *
+ * `scenario` provides exactly the store, serialiser, and uuid, so `build` must
+ * return an effect requiring only those three. For a plain decider (`R` and
+ * `RequirementOf<P>` both `never`) that is automatic; a decider carrying an
+ * encryption requirement provides its cipher layer inside `build` before
+ * returning.
+ */
+exports.specificationFor = specificationFor;
+const scenario = (description, decider, build) => {
+  _vitest.it.effect(description, () => build(specificationFor(decider)).pipe(
+  // A fresh store + uuid layer per case: both are stateful, so isolation is
+  // required (mirrors the contract suite's per-case layer thunk).
+  _effect.Effect.provide(_effect.Layer.mergeAll(_effect.Layer.fresh(_core.DcbEventStoreInMemory), _codec.SerializerDefault, _effect.Layer.fresh(_codec.UuidTest)))));
+};
+exports.scenario = scenario;
+//# sourceMappingURL=specification.js.map

package/dist/cjs/specification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specification.js","names":["_vitest","require","_codec","_core","_effect","shapeOf","event","type","tags","data","collect","events","Stream","runCollect","pipe","Effect","map","Chunk","toReadonlyArray","seed","producers","gen","store","DcbEventStore","last","ORIGIN","producer","append","orDie","appendedAfter","after","read","Q","all","specificationFor","decider","given","pastEvents","when","command","runToExit","zip","runDecider","exit","then","expected","Exit","isFailure","failCause","cause","seedBoundary","value","appended","expectedEvents","expect","s","toEqual","thenError","tag","toBe","failure","Cause","failureOption","error","_tag","undefined","actualTag","exports","scenario","description","build","it","effect","provide","Layer","mergeAll","fresh","DcbEventStoreInMemory","SerializerDefault","UuidTest"],"sources":["../../src/specification.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/dts/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @kairos-es/testing — the Given/When/Then decision-model testing surface.
+ *
+ * A `DeciderSpecification`-equivalent over the real `@kairos-es/codec`
+ * `buildDecisionModel` fold and a `DcbEventStore` (in practice the in-memory
+ * layer). Shaped so an Event Modeling `Specification` (given events / when a
+ * command / then events / thenError a tag) compiles onto it 1:1.
+ *
+ *   scenario('subscribe a student', subscribeDecider, (spec) =>
+ *     spec
+ *       .given(courseDefined('c1', 10))
+ *       .when({ studentId: 's1', courseId: 'c1' })
+ *       .then(studentSubscribed('s1', 'c1')),
+ *   )
+ *
+ * The unit it exercises — `Decider`, pairing the schema-backed projections a
+ * command reads with an effectful `decide` step producing events via `toEvent`,
+ * and `runDecider`, running the real read -> decode -> decide -> append cycle —
+ * belongs to `@kairos-es/codec` and is imported from there, so the surface
+ * exercises the genuine production cycle and not a test-only restatement of it.
+ * It is deliberately NOT re-exported here: this package peers `@effect/vitest`,
+ * and a re-export would let a production command handler reach a test framework
+ * through the type it names. Given/expected events are effectful producers
+ * (`toEvent`), materialised under the same serialiser + uuid layers `scenario`
+ * provides.
+ */
+export * from './specification.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;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,cAAc,iBAAiB,CAAA"}

package/dist/dts/specification.d.ts

@@ -0,0 +1,76 @@
+import type { CodecError, Decider, RequirementOf, SliceProjection } from '@kairos-es/codec';
+import { type Serializer, type Uuid } from '@kairos-es/codec';
+import { type AppendConditionFailed, type DcbEvent, DcbEventStore } from '@kairos-es/core';
+import { Effect } from 'effect';
+/** An effectful producer of a wire event (the `toEvent` result an app authors). */
+export type EventProducer<R> = Effect.Effect<DcbEvent, CodecError, Serializer | Uuid | R>;
+/**
+ * The entry point of the Given/When/Then chain: what `specificationFor` returns
+ * and what `scenario` hands its `build` callback. It is NAMED rather than
+ * written inline at those two sites because it was the one step of this chain
+ * with no name — the two statements of it were free to drift — and it is the
+ * step a caller most needs to name, since factoring a `build` callback out of a
+ * `scenario` call means writing its parameter's type. The sibling fluent
+ * builder in `@kairos-es/codec` names its own entry point (`ProjectionBuilder`)
+ * for the same reason.
+ *
+ * It introduces no type parameter of its own: all four are `GivenSpec`'s below,
+ * passed straight through, because seeding past events changes nothing about
+ * the command, the domain error, or either requirement — it only fixes the
+ * state the decision is folded from.
+ */
+export interface Specification<Command, E, R, PR> {
+    /**
+     * Seed the past events, in log order (one append each). They are effectful
+     * producers, materialised under the same layers the decision runs against.
+     */
+    readonly given: (...pastEvents: ReadonlyArray<EventProducer<R>>) => GivenSpec<Command, E, R, PR>;
+}
+/**
+ * A spec bound to a decider and a set of given events, awaiting `.when`. `PR` is
+ * the slices' decode requirement (`RequirementOf<P>`) that also flows through
+ * the terminals' requirement channel alongside the produce requirement `R`.
+ */
+export interface GivenSpec<Command, E, R, PR> {
+    /** Supply the command to decide. */
+    readonly when: (command: Command) => WhenSpec<E, R, PR>;
+}
+/** A spec that has a command and awaits a `then`/`thenError` assertion. */
+export interface WhenSpec<E, R, PR> {
+    /**
+     * Assert the success branch: the decider appended exactly these events
+     * (compared structurally by type/tags/data, in order). The expected events are
+     * effectful producers, materialised under the provided layers. The error
+     * channel keeps `E | CodecError | AppendConditionFailed` because a genuinely
+     * failing cycle re-raises its cause (a `.then` on a failing decision is a
+     * test-authoring mistake, made loud rather than silently green).
+     */
+    readonly then: (...expected: ReadonlyArray<EventProducer<R>>) => Effect.Effect<void, E | CodecError | AppendConditionFailed, DcbEventStore | Serializer | Uuid | R | PR>;
+    /**
+     * Assert the failure branch: the cycle failed with a tagged error whose
+     * `_tag` equals `tag` (a domain error from `decide`, a `CodecError` from
+     * decode, or `AppendConditionFailed` from a moved consistency boundary).
+     */
+    readonly thenError: (tag: string) => Effect.Effect<void, never, DcbEventStore | Serializer | Uuid | R | PR>;
+}
+/**
+ * Begin a specification for `decider`. The returned `given(...)` starts the
+ * Given/When/Then chain; the terminal step yields an `Effect` requiring
+ * `DcbEventStore | Serializer | Uuid | R | RequirementOf<P>`.
+ */
+export declare const specificationFor: <P extends Record<string, SliceProjection>, Command, E, R>(decider: Decider<P, Command, E, R>) => Specification<Command, E, R, RequirementOf<P>>;
+/**
+ * `scenario(description, spec => spec.given(...).when(...).then(...))` — register
+ * an `@effect/vitest` `it.effect` case running `build` against a fresh in-memory
+ * `DcbEventStore` plus the default serialiser and a fresh deterministic uuid
+ * layer. The callback receives `specificationFor(decider)` so example suites
+ * read as a single Given/When/Then line per case.
+ *
+ * `scenario` provides exactly the store, serialiser, and uuid, so `build` must
+ * return an effect requiring only those three. For a plain decider (`R` and
+ * `RequirementOf<P>` both `never`) that is automatic; a decider carrying an
+ * encryption requirement provides its cipher layer inside `build` before
+ * returning.
+ */
+export declare const scenario: <P extends Record<string, SliceProjection>, Command, E>(description: string, decider: Decider<P, Command, E>, build: (spec: Specification<Command, E, never, RequirementOf<P>>) => Effect.Effect<void, E | CodecError | AppendConditionFailed, DcbEventStore | Serializer | Uuid>) => void;
+//# sourceMappingURL=specification.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"specification.d.ts","sourceRoot":"","sources":["../../src/specification.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EACV,UAAU,EACV,OAAO,EACP,aAAa,EACb,eAAe,EAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,IAAI,EAEV,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,QAAQ,EACb,aAAa,EAMd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAgB,MAAM,EAAuB,MAAM,QAAQ,CAAA;AAElE,mFAAmF;AACnF,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,CAC1C,QAAQ,EACR,UAAU,EACV,UAAU,GAAG,IAAI,GAAG,CAAC,CACtB,CAAA;AA+DD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;IAC9C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,GAAG,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,KAC3C,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;IAC1C,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;CACxD;AAED,2EAA2E;AAC3E,MAAM,WAAW,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,CACb,GAAG,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,KACzC,MAAM,CAAC,MAAM,CAChB,IAAI,EACJ,CAAC,GAAG,UAAU,GAAG,qBAAqB,EACtC,aAAa,GAAG,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,CAC3C,CAAA;IACD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAClB,GAAG,EAAE,MAAM,KACR,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,aAAa,GAAG,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC,CAAA;CAC5E;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,OAAO,EACP,CAAC,EACD,CAAC,EAED,SAAS,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,KACjC,aAAa,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAkD9C,CAAA;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,OAAO,EAAE,CAAC,EAC5E,aAAa,MAAM,EACnB,SAAS,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,EAC/B,OAAO,CACL,IAAI,EAAE,aAAa,CAAC,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,KACrD,MAAM,CAAC,MAAM,CAChB,IAAI,EACJ,CAAC,GAAG,UAAU,GAAG,qBAAqB,EACtC,aAAa,GAAG,UAAU,GAAG,IAAI,CAClC,KACA,IAcF,CAAA"}

package/dist/esm/index.js

@@ -0,0 +1,28 @@
+/**
+ * @kairos-es/testing — the Given/When/Then decision-model testing surface.
+ *
+ * A `DeciderSpecification`-equivalent over the real `@kairos-es/codec`
+ * `buildDecisionModel` fold and a `DcbEventStore` (in practice the in-memory
+ * layer). Shaped so an Event Modeling `Specification` (given events / when a
+ * command / then events / thenError a tag) compiles onto it 1:1.
+ *
+ *   scenario('subscribe a student', subscribeDecider, (spec) =>
+ *     spec
+ *       .given(courseDefined('c1', 10))
+ *       .when({ studentId: 's1', courseId: 'c1' })
+ *       .then(studentSubscribed('s1', 'c1')),
+ *   )
+ *
+ * The unit it exercises — `Decider`, pairing the schema-backed projections a
+ * command reads with an effectful `decide` step producing events via `toEvent`,
+ * and `runDecider`, running the real read -> decode -> decide -> append cycle —
+ * belongs to `@kairos-es/codec` and is imported from there, so the surface
+ * exercises the genuine production cycle and not a test-only restatement of it.
+ * It is deliberately NOT re-exported here: this package peers `@effect/vitest`,
+ * and a re-export would let a production command handler reach a test framework
+ * through the type it names. Given/expected events are effectful producers
+ * (`toEvent`), materialised under the same serialiser + uuid layers `scenario`
+ * provides.
+ */
+export * from "./specification.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,cAAc,oBAAiB","ignoreList":[]}

package/dist/esm/package.json

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

package/dist/esm/specification.js

@@ -0,0 +1,150 @@
+/**
+ * The Given/When/Then surface: a `DeciderSpecification`-equivalent over the real
+ * `@kairos-es/codec` `buildDecisionModel` fold and a `DcbEventStore` (the
+ * in-memory layer in practice). It is shaped so an Event Modeling
+ * `Specification` (given events, when a command, then events / thenError a tag)
+ * compiles onto it 1:1 — prior art: dcb-events `TestRunner` and Emmett's
+ * `DeciderSpecification`.
+ *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .then(...expectedNewEventProducers)   // success branch
+ *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .thenError('AppendConditionFailed')   // failure branch (domain error or conflict)
+ *
+ * Events are supplied *effectfully*: a given/expected event is the producer an
+ * application authors via `toEvent` — an `Effect<DcbEvent, CodecError,
+ * Serializer | Uuid | R>` — so both sides materialise (encode -> serialise)
+ * under the same layers the cycle runs against, and their `data` bytes match.
+ *
+ * Each terminal (`then` / `thenError`) returns an `Effect` requiring
+ * `DcbEventStore | Serializer | Uuid | R`, so a test provides the store,
+ * serialiser, and uuid layers (fresh store per case for isolation).
+ * `scenario(...)` wraps the whole thing in `@effect/vitest`'s `it.effect`
+ * against a fresh in-memory store plus `SerializerDefault` and `UuidTest`, so
+ * example specs read as one line.
+ *
+ * `then` compares the *appended* events (those written past the given seed) to
+ * the expected batch structurally — by `type`, `tags`, and `data` — ignoring
+ * the store-assigned `position` and the producer-supplied `uuid`/`occurredAt`,
+ * which are not part of the decision under test. JSON serialisation is
+ * deterministic, so equal payloads produce equal `data` bytes.
+ */
+import { expect, it } from '@effect/vitest';
+import { runDecider, SerializerDefault, UuidTest } from '@kairos-es/codec';
+import { DcbEventStore, DcbEventStoreInMemory, ORIGIN, query as Q } from '@kairos-es/core';
+import { Cause, Chunk, Effect, Exit, Layer, Stream } from 'effect';
+const shapeOf = event => ({
+  type: event.type,
+  tags: event.tags,
+  data: event.data
+});
+/** Collect a stream of sequenced events into a plain array. */
+const collect = events => Stream.runCollect(events).pipe(Effect.map(Chunk.toReadonlyArray));
+/**
+ * Seed the given past-event producers into the store: materialise each producer
+ * (encode -> serialise), then one append each (log order). Returns the position
+ * the LAST seeded append was written at, or `ORIGIN` when nothing was seeded —
+ * this is the boundary `then` reads strictly after.
+ *
+ * We track the boundary by position rather than by count because positions are
+ * gappy on a real store (Postgres `bigserial` skips values on rollbacks and
+ * across concurrent writers), so "everything past N rows" is wrong; "everything
+ * strictly after this position" is exact regardless of gaps.
+ */
+const seed = producers => Effect.gen(function* () {
+  const store = yield* DcbEventStore;
+  let last = ORIGIN;
+  for (const producer of producers) {
+    const event = yield* producer;
+    // Unconditional appends never fail; a failure here would be a defect in
+    // the store, not a domain outcome, so turn it into one.
+    last = yield* store.append([event]).pipe(Effect.orDie);
+  }
+  return last;
+});
+/**
+ * The events appended past the seed boundary, so `then` can read back exactly
+ * the events the decider appended. We read all matching events strictly after
+ * `after` (the last seeded position), which is correct on a gappy store where
+ * dropping a fixed row count would not be — the in-memory store gives the
+ * identical result because its positions are gapless.
+ */
+const appendedAfter = after => Effect.gen(function* () {
+  const store = yield* DcbEventStore;
+  const {
+    events
+  } = yield* store.read(Q.all(), {
+    after
+  });
+  return yield* collect(events);
+});
+/**
+ * Begin a specification for `decider`. The returned `given(...)` starts the
+ * Given/When/Then chain; the terminal step yields an `Effect` requiring
+ * `DcbEventStore | Serializer | Uuid | R | RequirementOf<P>`.
+ */
+export const specificationFor = decider => ({
+  given: (...pastEvents) => ({
+    when: command => {
+      // Run the seed + decider cycle, exposing the outcome as an Exit so both
+      // branches (then / thenError) can inspect success or failure uniformly. The
+      // seed is inside the Exit too, so a decode failure while materialising a
+      // given producer is captured as a failure rather than escaping the channel.
+      // The success value pairs the seed boundary (the last seeded position) with
+      // the decider's outcome, so `then` reads strictly after that boundary
+      // rather than dropping a fixed row count (correct on a gappy store).
+      const runToExit = seed(pastEvents).pipe(Effect.zip(runDecider(decider, command)), Effect.exit);
+      return {
+        // biome-ignore lint/suspicious/noThenProperty: deliberate Given/When/Then terminal name (see WhenSpec.then); never awaited as a thenable.
+        then: (...expected) => Effect.gen(function* () {
+          const exit = yield* runToExit;
+          if (Exit.isFailure(exit)) {
+            // Surface the real failure to the caller's error channel; a
+            // `.then` on a failing cycle is a test authoring mistake, so make
+            // it loud rather than silently passing.
+            return yield* Effect.failCause(exit.cause);
+          }
+          const [seedBoundary] = exit.value;
+          const appended = yield* appendedAfter(seedBoundary);
+          const expectedEvents = yield* Effect.all(expected);
+          expect(appended.map(s => shapeOf(s.event))).toEqual(expectedEvents.map(shapeOf));
+        }),
+        thenError: tag => Effect.gen(function* () {
+          const exit = yield* runToExit;
+          expect(Exit.isFailure(exit)).toBe(true);
+          if (Exit.isFailure(exit)) {
+            const failure = Cause.failureOption(exit.cause);
+            const error = failure._tag === 'Some' ? failure.value : undefined;
+            const actualTag = typeof error === 'object' && error !== null && '_tag' in error ? error._tag : undefined;
+            expect(actualTag).toBe(tag);
+          }
+        })
+      };
+    }
+  })
+});
+/**
+ * `scenario(description, spec => spec.given(...).when(...).then(...))` — register
+ * an `@effect/vitest` `it.effect` case running `build` against a fresh in-memory
+ * `DcbEventStore` plus the default serialiser and a fresh deterministic uuid
+ * layer. The callback receives `specificationFor(decider)` so example suites
+ * read as a single Given/When/Then line per case.
+ *
+ * `scenario` provides exactly the store, serialiser, and uuid, so `build` must
+ * return an effect requiring only those three. For a plain decider (`R` and
+ * `RequirementOf<P>` both `never`) that is automatic; a decider carrying an
+ * encryption requirement provides its cipher layer inside `build` before
+ * returning.
+ */
+export const scenario = (description, decider, build) => {
+  it.effect(description, () => build(specificationFor(decider)).pipe(
+  // A fresh store + uuid layer per case: both are stateful, so isolation is
+  // required (mirrors the contract suite's per-case layer thunk).
+  Effect.provide(Layer.mergeAll(Layer.fresh(DcbEventStoreInMemory), SerializerDefault, Layer.fresh(UuidTest)))));
+};
+//# sourceMappingURL=specification.js.map

package/dist/esm/specification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specification.js","names":["expect","it","runDecider","SerializerDefault","UuidTest","DcbEventStore","DcbEventStoreInMemory","ORIGIN","query","Q","Cause","Chunk","Effect","Exit","Layer","Stream","shapeOf","event","type","tags","data","collect","events","runCollect","pipe","map","toReadonlyArray","seed","producers","gen","store","last","producer","append","orDie","appendedAfter","after","read","all","specificationFor","decider","given","pastEvents","when","command","runToExit","zip","exit","then","expected","isFailure","failCause","cause","seedBoundary","value","appended","expectedEvents","s","toEqual","thenError","tag","toBe","failure","failureOption","error","_tag","undefined","actualTag","scenario","description","build","effect","provide","mergeAll","fresh"],"sources":["../../src/specification.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@kairos-es/testing",
+  "version": "0.0.0",
+  "description": "Given/When/Then decision-model testing surface for kairos-es",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverbland/kairos-es.git",
+    "directory": "packages/testing"
+  },
+  "sideEffects": [],
+  "homepage": "https://github.com/neverbland/kairos-es",
+  "peerDependencies": {
+    "@effect/vitest": "^0.30.0",
+    "effect": "^3.22.0",
+    "@kairos-es/codec": "^0.0.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": {
+    "*": {}
+  }
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @kairos-es/testing — the Given/When/Then decision-model testing surface.
+ *
+ * A `DeciderSpecification`-equivalent over the real `@kairos-es/codec`
+ * `buildDecisionModel` fold and a `DcbEventStore` (in practice the in-memory
+ * layer). Shaped so an Event Modeling `Specification` (given events / when a
+ * command / then events / thenError a tag) compiles onto it 1:1.
+ *
+ *   scenario('subscribe a student', subscribeDecider, (spec) =>
+ *     spec
+ *       .given(courseDefined('c1', 10))
+ *       .when({ studentId: 's1', courseId: 'c1' })
+ *       .then(studentSubscribed('s1', 'c1')),
+ *   )
+ *
+ * The unit it exercises — `Decider`, pairing the schema-backed projections a
+ * command reads with an effectful `decide` step producing events via `toEvent`,
+ * and `runDecider`, running the real read -> decode -> decide -> append cycle —
+ * belongs to `@kairos-es/codec` and is imported from there, so the surface
+ * exercises the genuine production cycle and not a test-only restatement of it.
+ * It is deliberately NOT re-exported here: this package peers `@effect/vitest`,
+ * and a re-export would let a production command handler reach a test framework
+ * through the type it names. Given/expected events are effectful producers
+ * (`toEvent`), materialised under the same serialiser + uuid layers `scenario`
+ * provides.
+ */
+export * from './specification'

package/src/specification.ts

@@ -0,0 +1,294 @@
+/**
+ * The Given/When/Then surface: a `DeciderSpecification`-equivalent over the real
+ * `@kairos-es/codec` `buildDecisionModel` fold and a `DcbEventStore` (the
+ * in-memory layer in practice). It is shaped so an Event Modeling
+ * `Specification` (given events, when a command, then events / thenError a tag)
+ * compiles onto it 1:1 — prior art: dcb-events `TestRunner` and Emmett's
+ * `DeciderSpecification`.
+ *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .then(...expectedNewEventProducers)   // success branch
+ *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .thenError('AppendConditionFailed')   // failure branch (domain error or conflict)
+ *
+ * Events are supplied *effectfully*: a given/expected event is the producer an
+ * application authors via `toEvent` — an `Effect<DcbEvent, CodecError,
+ * Serializer | Uuid | R>` — so both sides materialise (encode -> serialise)
+ * under the same layers the cycle runs against, and their `data` bytes match.
+ *
+ * Each terminal (`then` / `thenError`) returns an `Effect` requiring
+ * `DcbEventStore | Serializer | Uuid | R`, so a test provides the store,
+ * serialiser, and uuid layers (fresh store per case for isolation).
+ * `scenario(...)` wraps the whole thing in `@effect/vitest`'s `it.effect`
+ * against a fresh in-memory store plus `SerializerDefault` and `UuidTest`, so
+ * example specs read as one line.
+ *
+ * `then` compares the *appended* events (those written past the given seed) to
+ * the expected batch structurally — by `type`, `tags`, and `data` — ignoring
+ * the store-assigned `position` and the producer-supplied `uuid`/`occurredAt`,
+ * which are not part of the decision under test. JSON serialisation is
+ * deterministic, so equal payloads produce equal `data` bytes.
+ */
+import { expect, it } from '@effect/vitest'
+import type {
+  CodecError,
+  Decider,
+  RequirementOf,
+  SliceProjection,
+} from '@kairos-es/codec'
+import {
+  runDecider,
+  type Serializer,
+  SerializerDefault,
+  type Uuid,
+  UuidTest,
+} from '@kairos-es/codec'
+import {
+  type AppendConditionFailed,
+  type DcbEvent,
+  DcbEventStore,
+  DcbEventStoreInMemory,
+  ORIGIN,
+  type Position,
+  query as Q,
+  type SequencedEvent,
+} from '@kairos-es/core'
+import { Cause, Chunk, Effect, Exit, Layer, Stream } from 'effect'
+
+/** An effectful producer of a wire event (the `toEvent` result an app authors). */
+export type EventProducer<R> = Effect.Effect<
+  DcbEvent,
+  CodecError,
+  Serializer | Uuid | R
+>
+
+/** The structural shape `then` compares on (position/uuid/occurredAt excluded). */
+interface EventShape {
+  readonly type: string
+  readonly tags: ReadonlyArray<string>
+  readonly data: Uint8Array
+}
+
+const shapeOf = (event: DcbEvent): EventShape => ({
+  type: event.type,
+  tags: event.tags,
+  data: event.data,
+})
+
+/** Collect a stream of sequenced events into a plain array. */
+const collect = (
+  events: Stream.Stream<SequencedEvent>,
+): Effect.Effect<ReadonlyArray<SequencedEvent>> =>
+  Stream.runCollect(events).pipe(Effect.map(Chunk.toReadonlyArray))
+
+/**
+ * Seed the given past-event producers into the store: materialise each producer
+ * (encode -> serialise), then one append each (log order). Returns the position
+ * the LAST seeded append was written at, or `ORIGIN` when nothing was seeded —
+ * this is the boundary `then` reads strictly after.
+ *
+ * We track the boundary by position rather than by count because positions are
+ * gappy on a real store (Postgres `bigserial` skips values on rollbacks and
+ * across concurrent writers), so "everything past N rows" is wrong; "everything
+ * strictly after this position" is exact regardless of gaps.
+ */
+const seed = <R>(
+  producers: ReadonlyArray<EventProducer<R>>,
+): Effect.Effect<Position, CodecError, DcbEventStore | Serializer | Uuid | R> =>
+  Effect.gen(function* () {
+    const store = yield* DcbEventStore
+    let last: Position = ORIGIN
+    for (const producer of producers) {
+      const event = yield* producer
+      // Unconditional appends never fail; a failure here would be a defect in
+      // the store, not a domain outcome, so turn it into one.
+      last = yield* store.append([event]).pipe(Effect.orDie)
+    }
+    return last
+  })
+
+/**
+ * The events appended past the seed boundary, so `then` can read back exactly
+ * the events the decider appended. We read all matching events strictly after
+ * `after` (the last seeded position), which is correct on a gappy store where
+ * dropping a fixed row count would not be — the in-memory store gives the
+ * identical result because its positions are gapless.
+ */
+const appendedAfter = (
+  after: Position,
+): Effect.Effect<ReadonlyArray<SequencedEvent>, never, DcbEventStore> =>
+  Effect.gen(function* () {
+    const store = yield* DcbEventStore
+    const { events } = yield* store.read(Q.all(), { after })
+    return yield* collect(events)
+  })
+
+/**
+ * The entry point of the Given/When/Then chain: what `specificationFor` returns
+ * and what `scenario` hands its `build` callback. It is NAMED rather than
+ * written inline at those two sites because it was the one step of this chain
+ * with no name — the two statements of it were free to drift — and it is the
+ * step a caller most needs to name, since factoring a `build` callback out of a
+ * `scenario` call means writing its parameter's type. The sibling fluent
+ * builder in `@kairos-es/codec` names its own entry point (`ProjectionBuilder`)
+ * for the same reason.
+ *
+ * It introduces no type parameter of its own: all four are `GivenSpec`'s below,
+ * passed straight through, because seeding past events changes nothing about
+ * the command, the domain error, or either requirement — it only fixes the
+ * state the decision is folded from.
+ */
+export interface Specification<Command, E, R, PR> {
+  /**
+   * Seed the past events, in log order (one append each). They are effectful
+   * producers, materialised under the same layers the decision runs against.
+   */
+  readonly given: (
+    ...pastEvents: ReadonlyArray<EventProducer<R>>
+  ) => GivenSpec<Command, E, R, PR>
+}
+
+/**
+ * A spec bound to a decider and a set of given events, awaiting `.when`. `PR` is
+ * the slices' decode requirement (`RequirementOf<P>`) that also flows through
+ * the terminals' requirement channel alongside the produce requirement `R`.
+ */
+export interface GivenSpec<Command, E, R, PR> {
+  /** Supply the command to decide. */
+  readonly when: (command: Command) => WhenSpec<E, R, PR>
+}
+
+/** A spec that has a command and awaits a `then`/`thenError` assertion. */
+export interface WhenSpec<E, R, PR> {
+  /**
+   * Assert the success branch: the decider appended exactly these events
+   * (compared structurally by type/tags/data, in order). The expected events are
+   * effectful producers, materialised under the provided layers. The error
+   * channel keeps `E | CodecError | AppendConditionFailed` because a genuinely
+   * failing cycle re-raises its cause (a `.then` on a failing decision is a
+   * test-authoring mistake, made loud rather than silently green).
+   */
+  readonly then: (
+    ...expected: ReadonlyArray<EventProducer<R>>
+  ) => Effect.Effect<
+    void,
+    E | CodecError | AppendConditionFailed,
+    DcbEventStore | Serializer | Uuid | R | PR
+  >
+  /**
+   * Assert the failure branch: the cycle failed with a tagged error whose
+   * `_tag` equals `tag` (a domain error from `decide`, a `CodecError` from
+   * decode, or `AppendConditionFailed` from a moved consistency boundary).
+   */
+  readonly thenError: (
+    tag: string,
+  ) => Effect.Effect<void, never, DcbEventStore | Serializer | Uuid | R | PR>
+}
+
+/**
+ * Begin a specification for `decider`. The returned `given(...)` starts the
+ * Given/When/Then chain; the terminal step yields an `Effect` requiring
+ * `DcbEventStore | Serializer | Uuid | R | RequirementOf<P>`.
+ */
+export const specificationFor = <
+  P extends Record<string, SliceProjection>,
+  Command,
+  E,
+  R,
+>(
+  decider: Decider<P, Command, E, R>,
+): Specification<Command, E, R, RequirementOf<P>> => ({
+  given: (...pastEvents) => ({
+    when: (command) => {
+      // Run the seed + decider cycle, exposing the outcome as an Exit so both
+      // branches (then / thenError) can inspect success or failure uniformly. The
+      // seed is inside the Exit too, so a decode failure while materialising a
+      // given producer is captured as a failure rather than escaping the channel.
+      // The success value pairs the seed boundary (the last seeded position) with
+      // the decider's outcome, so `then` reads strictly after that boundary
+      // rather than dropping a fixed row count (correct on a gappy store).
+      const runToExit = seed(pastEvents).pipe(
+        Effect.zip(runDecider(decider, command)),
+        Effect.exit,
+      )
+
+      return {
+        // biome-ignore lint/suspicious/noThenProperty: deliberate Given/When/Then terminal name (see WhenSpec.then); never awaited as a thenable.
+        then: (...expected) =>
+          Effect.gen(function* () {
+            const exit = yield* runToExit
+            if (Exit.isFailure(exit)) {
+              // Surface the real failure to the caller's error channel; a
+              // `.then` on a failing cycle is a test authoring mistake, so make
+              // it loud rather than silently passing.
+              return yield* Effect.failCause(exit.cause)
+            }
+            const [seedBoundary] = exit.value
+            const appended = yield* appendedAfter(seedBoundary)
+            const expectedEvents = yield* Effect.all(expected)
+            expect(appended.map((s) => shapeOf(s.event))).toEqual(
+              expectedEvents.map(shapeOf),
+            )
+          }),
+        thenError: (tag) =>
+          Effect.gen(function* () {
+            const exit = yield* runToExit
+            expect(Exit.isFailure(exit)).toBe(true)
+            if (Exit.isFailure(exit)) {
+              const failure = Cause.failureOption(exit.cause)
+              const error = failure._tag === 'Some' ? failure.value : undefined
+              const actualTag =
+                typeof error === 'object' && error !== null && '_tag' in error
+                  ? (error as { readonly _tag: unknown })._tag
+                  : undefined
+              expect(actualTag).toBe(tag)
+            }
+          }),
+      }
+    },
+  }),
+})
+
+/**
+ * `scenario(description, spec => spec.given(...).when(...).then(...))` — register
+ * an `@effect/vitest` `it.effect` case running `build` against a fresh in-memory
+ * `DcbEventStore` plus the default serialiser and a fresh deterministic uuid
+ * layer. The callback receives `specificationFor(decider)` so example suites
+ * read as a single Given/When/Then line per case.
+ *
+ * `scenario` provides exactly the store, serialiser, and uuid, so `build` must
+ * return an effect requiring only those three. For a plain decider (`R` and
+ * `RequirementOf<P>` both `never`) that is automatic; a decider carrying an
+ * encryption requirement provides its cipher layer inside `build` before
+ * returning.
+ */
+export const scenario = <P extends Record<string, SliceProjection>, Command, E>(
+  description: string,
+  decider: Decider<P, Command, E>,
+  build: (
+    spec: Specification<Command, E, never, RequirementOf<P>>,
+  ) => Effect.Effect<
+    void,
+    E | CodecError | AppendConditionFailed,
+    DcbEventStore | Serializer | Uuid
+  >,
+): void => {
+  it.effect(description, () =>
+    build(specificationFor(decider)).pipe(
+      // A fresh store + uuid layer per case: both are stateful, so isolation is
+      // required (mirrors the contract suite's per-case layer thunk).
+      Effect.provide(
+        Layer.mergeAll(
+          Layer.fresh(DcbEventStoreInMemory),
+          SerializerDefault,
+          Layer.fresh(UuidTest),
+        ),
+      ),
+    ),
+  )
+}