@kairos-es/testing 1.0.0-alpha.0 → 1.0.0-alpha.2

package/README.md

@@ -17,10 +17,31 @@ a peer for you.
 Its other peers, `@kairos-es/core`, `@kairos-es/codec` and `effect`, are the ones
 an application using the library already has.
 
-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.
+A `DeciderSpecification`-equivalent running the real read → decode → decide →
+append cycle against the in-memory store rather than a mock, on
+`@effect/vitest`. Over the codec's `buildDecisionModel` for a single-hop
+decision, and over `modelAtHead` and the read ledger for a layered one.
+`@kairos-es/core`, `@kairos-es/codec`, `effect` and `@effect/vitest` are peer
+dependencies.
+
+`specificationFor(decider)` is the ordinary entry point.
+`specificationForCycle(run)` is the general one it is a one-line specialisation
+of: it takes any `(command) => Effect<Position, …>`, so a `transact` bracket slots
+into the same chain a decider does. Its `run` states its errors as `E | CycleError`
+— the chain adds that union itself, so a naive `Effect<Position, E, R>`
+double-counts it and will not unify.
+
+⚠ `.thenError(tag)` is weaker on a bracket than on a decider, in three ways worth
+knowing before you rely on it. Two different denials from one guard usually share
+one tag, so a spec can pass on a refusal its author did not mean. An
+`AppendConditionFailed` now also fires for an EARLIER hop, so the tag no longer says
+which boundary moved. And `NoReadsRecorded` reads like a domain assertion while
+being a statement about wiring. A layered or permission suite should assert more
+than the tag.
+
+`.thenUnchanged()` asserts the "already done" branch: the cycle succeeded with
+the codec's `Unchanged` AND appended nothing. `.then()` and `.thenError(tag)` both
+fail on an `Unchanged` cycle, so the three terminals cannot pass for one another.
 
 The `Decider` a scenario exercises and the `runDecider` that runs it are
 production symbols and belong to [`@kairos-es/codec`](../codec); this package

package/dist/cjs/index.js.map

@@ -1 +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":[]}
+{"version":3,"file":"index.js","names":["_specification","require","Object","keys","forEach","key","exports","defineProperty","enumerable","get"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":";;;;;AA6BA,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

@@ -3,15 +3,20 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.specificationFor = exports.scenario = void 0;
+exports.specificationForCycle = 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
+ * The Given/When/Then surface: a `DeciderSpecification`-equivalent over a real
+ * fold and a `DcbEventStore` (the in-memory layer in practice) —
+ * `@kairos-es/codec`'s `buildDecisionModel` for a single-hop decision, and
+ * `modelAtHead` plus the read ledger for a layered one. `specificationForCycle`
+ * is the general entry point over either, named for the command CYCLE it takes
+ * rather than for the layered bracket that was its first caller — the shape it
+ * accepts is `(command) => Effect<Position, …>` and a decider is one instance of
+ * it. 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`.
@@ -26,12 +31,17 @@ var _effect = require("effect");
  *     .when(command)
  *     .thenError('AppendConditionFailed')   // failure branch (domain error or conflict)
  *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .thenUnchanged()                      // "already done" branch: nothing appended
+ *
  * 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
+ * Each terminal (`then` / `thenError` / `thenUnchanged`) 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`
@@ -91,21 +101,32 @@ const appendedAfter = after => _effect.Effect.gen(function* () {
   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>`.
+ * Begin a specification for ANY command cycle that returns the appended
+ * `Position` — a bracket for one command as readily as a decider — or
+ * `Unchanged`, for a cycle that can answer "already done".
+ *
+ * This is the general form and `specificationFor` below is a one-line
+ * specialisation of it, which is the result worth stating rather than the
+ * mechanism: a `Decider` is one particular `(command) => Effect<Position, …>`,
+ * and `runDecider` is the function that says so. Nothing downstream of `when`
+ * moves — the same seed boundary, the same read-back, the same shape comparison
+ * — because both cycles already agree on what they return.
+ *
+ * ⚠ `run`'s error channel is written `E | CycleError` and must be: the chain adds
+ * that union itself, so a naive `Effect<Position, E, R>` double-counts it and
+ * fails to unify. `CycleError` exists to be written here.
  */
-const specificationFor = decider => ({
+const specificationForCycle = run => ({
   given: (...pastEvents) => ({
     when: command => {
-      // Run the seed + decider cycle, exposing the outcome as an Exit so both
+      // Run the seed + 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
+      // the cycle'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);
+      const runToExit = seed(pastEvents).pipe(_effect.Effect.zip(run(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* () {
@@ -116,7 +137,8 @@ const specificationFor = decider => ({
             // it loud rather than silently passing.
             return yield* _effect.Effect.failCause(exit.cause);
           }
-          const [seedBoundary] = exit.value;
+          const [seedBoundary, result] = exit.value;
+          (0, _vitest.expect)((0, _codec.isUnchanged)(result)).toBe(false);
           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));
@@ -130,11 +152,32 @@ const specificationFor = decider => ({
             const actualTag = typeof error === 'object' && error !== null && '_tag' in error ? error._tag : undefined;
             (0, _vitest.expect)(actualTag).toBe(tag);
           }
+        }),
+        thenUnchanged: () => _effect.Effect.gen(function* () {
+          const exit = yield* runToExit;
+          if (_effect.Exit.isFailure(exit)) {
+            return yield* _effect.Effect.failCause(exit.cause);
+          }
+          const [seedBoundary, result] = exit.value;
+          (0, _vitest.expect)((0, _codec.isUnchanged)(result)).toBe(true);
+          const appended = yield* appendedAfter(seedBoundary);
+          (0, _vitest.expect)(appended.map(s => shapeOf(s.event))).toEqual([]);
         })
       };
     }
   })
 });
+/**
+ * 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>`.
+ *
+ * One line over the layered sibling above, and deliberately not a twin of it:
+ * a duplicated body would be two sets of tests and two things free to drift on
+ * the seed boundary, the read-back or the shape comparison.
+ */
+exports.specificationForCycle = specificationForCycle;
+const specificationFor = decider => specificationForCycle(command => (0, _codec.runDecider)(decider, command));
 /**
  * `scenario(description, spec => spec.given(...).when(...).then(...))` — register
  * an `@effect/vitest` `it.effect` case running `build` against a fresh in-memory

package/dist/cjs/specification.js.map

@@ -1 +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":[]}
+{"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","specificationForCycle","run","given","pastEvents","when","command","runToExit","zip","exit","then","expected","Exit","isFailure","failCause","cause","seedBoundary","result","value","expect","isUnchanged","toBe","appended","expectedEvents","s","toEqual","thenError","tag","failure","Cause","failureOption","error","_tag","undefined","actualTag","thenUnchanged","exports","specificationFor","decider","runDecider","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

@@ -1,10 +1,13 @@
 /**
  * @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.
+ * A `DeciderSpecification`-equivalent over a real fold and a `DcbEventStore` (in
+ * practice the in-memory layer): `@kairos-es/codec`'s `buildDecisionModel` for
+ * a single-hop decision, and `modelAtHead` plus the read ledger for a layered
+ * one. Shaped so an Event Modeling `Specification` (given events / when a
+ * command / then events / thenError a tag) compiles onto it 1:1, plus
+ * `thenUnchanged` for a decision that answers "already done" and appends
+ * nothing.
  *
  *   scenario('subscribe a student', subscribeDecider, (spec) =>
  *     spec

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,cAAc,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,cAAc,iBAAiB,CAAA"}

package/dist/dts/specification.d.ts

@@ -1,9 +1,26 @@
-import type { CodecError, Decider, RequirementOf, SliceProjection } from '@kairos-es/codec';
+import type { CodecError, Decider, DecisionOutput, NoReadsRecorded, RequirementOf, SliceProjection, TaglessSliceInLedger, Unchanged } 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';
+import { type AppendConditionFailed, type DcbEvent, DcbEventStore, type Position } from '@kairos-es/core';
+import { type Array as Arr, 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 errors a command CYCLE contributes, beyond whatever `E` the decision
+ * itself fails with.
+ *
+ * Named once and exported because it is what makes the layered entry point below
+ * UNIFY. `WhenSpec.then` adds this union itself, so a `run` written as a naive
+ * `Effect<Position, E, R>` double-counts every member of it and fails to
+ * typecheck against a chain that has already added them — a trap with an
+ * unhelpful error message, met once and closed here by giving the union a name a
+ * caller can write.
+ *
+ * `NoReadsRecorded` is reachable only on the layered path and `TaglessSliceInLedger`
+ * only where a bracket is open, but both are members here rather than in a second
+ * union, because the two paths share every step downstream of `when` and a second
+ * union would be a second thing to keep in step for no caller's benefit.
+ */
+export type CycleError = CodecError | AppendConditionFailed | TaglessSliceInLedger | NoReadsRecorded;
 /**
  * The entry point of the Given/When/Then chain: what `specificationFor` returns
  * and what `scenario` hands its `build` callback. It is NAMED rather than
@@ -35,30 +52,78 @@ 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. */
+/** A spec that has a command and awaits a `then`/`thenError`/`thenUnchanged` 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).
+     * channel keeps `E | CycleError` 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).
+     *
+     * A cycle that answered `Unchanged` FAILS this assertion, even with no
+     * expected events. `.then()` with an empty list and `.thenUnchanged()` both
+     * see nothing appended, but they claim different things — *decided an empty
+     * change* is not a decision this library can make, while *already done* is —
+     * so the one that does not match the cycle's answer must not pass.
      */
-    readonly then: (...expected: ReadonlyArray<EventProducer<R>>) => Effect.Effect<void, E | CodecError | AppendConditionFailed, DcbEventStore | Serializer | Uuid | R | PR>;
+    readonly then: (...expected: ReadonlyArray<EventProducer<R>>) => Effect.Effect<void, E | CycleError, 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).
+     *
+     * ⚠ THREE WAYS THIS PASSES FOR THE WRONG REASON, and a layered or permission
+     * suite must assert more than the tag. An opaque refusal is correct on the wire
+     * and is exactly what blinds this assertion — two different denials share one
+     * tag, so a spec can pass on a refusal its author did not mean. An
+     * `AppendConditionFailed` now also fires for an EARLIER hop, so the tag no
+     * longer says which boundary moved. And `NoReadsRecorded` is a reachable spec
+     * whose shape does not mark it as structural: it reads like a domain assertion
+     * and is a statement about wiring.
      */
     readonly thenError: (tag: string) => Effect.Effect<void, never, DcbEventStore | Serializer | Uuid | R | PR>;
+    /**
+     * Assert the "already done" branch: the cycle SUCCEEDED with `Unchanged`
+     * (recognised by `isUnchanged`, never by its tag) and appended nothing past
+     * the seed. A cycle that appended — even an empty-looking one — or that
+     * returned a `Position` fails it, and a failing cycle re-raises its cause, for
+     * the reason `then` gives.
+     *
+     * Both halves are asserted, not just the result, because they are different
+     * claims: a runner that returned `Unchanged` AND appended would be exactly the
+     * defect this step exists to catch, and the result alone would not see it.
+     */
+    readonly thenUnchanged: () => Effect.Effect<void, E | CycleError, DcbEventStore | Serializer | Uuid | R | PR>;
 }
+/**
+ * Begin a specification for ANY command cycle that returns the appended
+ * `Position` — a bracket for one command as readily as a decider — or
+ * `Unchanged`, for a cycle that can answer "already done".
+ *
+ * This is the general form and `specificationFor` below is a one-line
+ * specialisation of it, which is the result worth stating rather than the
+ * mechanism: a `Decider` is one particular `(command) => Effect<Position, …>`,
+ * and `runDecider` is the function that says so. Nothing downstream of `when`
+ * moves — the same seed boundary, the same read-back, the same shape comparison
+ * — because both cycles already agree on what they return.
+ *
+ * ⚠ `run`'s error channel is written `E | CycleError` and must be: the chain adds
+ * that union itself, so a naive `Effect<Position, E, R>` double-counts it and
+ * fails to unify. `CycleError` exists to be written here.
+ */
+export declare const specificationForCycle: <Command, E, R, PR = never>(run: (command: Command) => Effect.Effect<Position | Unchanged, E | CycleError, DcbEventStore | Serializer | Uuid | R | PR>) => Specification<Command, E, 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>`.
+ *
+ * One line over the layered sibling above, and deliberately not a twin of it:
+ * a duplicated body would be two sets of tests and two things free to drift on
+ * the seed boundary, the read-back or the shape comparison.
  */
-export declare const specificationFor: <P extends Record<string, SliceProjection>, Command, E, R>(decider: Decider<P, Command, E, R>) => Specification<Command, E, R, RequirementOf<P>>;
+export declare const specificationFor: <P extends Record<string, SliceProjection>, Command, E, R, O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>>(decider: Decider<P, Command, E, R, O>) => 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
@@ -72,5 +137,5 @@ export declare const specificationFor: <P extends Record<string, SliceProjection
  * 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;
+export declare const scenario: <P extends Record<string, SliceProjection>, Command, E, O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>>(description: string, decider: Decider<P, Command, E, never, O>, build: (spec: Specification<Command, E, never, RequirementOf<P>>) => Effect.Effect<void, E | CycleError, DcbEventStore | Serializer | Uuid>) => void;
 //# sourceMappingURL=specification.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"specification.d.ts","sourceRoot":"","sources":["../../src/specification.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -1,10 +1,13 @@
 /**
  * @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.
+ * A `DeciderSpecification`-equivalent over a real fold and a `DcbEventStore` (in
+ * practice the in-memory layer): `@kairos-es/codec`'s `buildDecisionModel` for
+ * a single-hop decision, and `modelAtHead` plus the read ledger for a layered
+ * one. Shaped so an Event Modeling `Specification` (given events / when a
+ * command / then events / thenError a tag) compiles onto it 1:1, plus
+ * `thenUnchanged` for a decision that answers "already done" and appends
+ * nothing.
  *
  *   scenario('subscribe a student', subscribeDecider, (spec) =>
  *     spec

package/dist/esm/index.js.map

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

package/dist/esm/specification.js

@@ -1,7 +1,12 @@
 /**
- * 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
+ * The Given/When/Then surface: a `DeciderSpecification`-equivalent over a real
+ * fold and a `DcbEventStore` (the in-memory layer in practice) —
+ * `@kairos-es/codec`'s `buildDecisionModel` for a single-hop decision, and
+ * `modelAtHead` plus the read ledger for a layered one. `specificationForCycle`
+ * is the general entry point over either, named for the command CYCLE it takes
+ * rather than for the layered bracket that was its first caller — the shape it
+ * accepts is `(command) => Effect<Position, …>` and a decider is one instance of
+ * it. 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`.
@@ -16,12 +21,17 @@
  *     .when(command)
  *     .thenError('AppendConditionFailed')   // failure branch (domain error or conflict)
  *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .thenUnchanged()                      // "already done" branch: nothing appended
+ *
  * 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
+ * Each terminal (`then` / `thenError` / `thenUnchanged`) 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`
@@ -35,7 +45,7 @@
  * deterministic, so equal payloads produce equal `data` bytes.
  */
 import { expect, it } from '@effect/vitest';
-import { runDecider, SerializerDefault, UuidTest } from '@kairos-es/codec';
+import { isUnchanged, 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 => ({
@@ -84,21 +94,32 @@ const appendedAfter = after => Effect.gen(function* () {
   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>`.
+ * Begin a specification for ANY command cycle that returns the appended
+ * `Position` — a bracket for one command as readily as a decider — or
+ * `Unchanged`, for a cycle that can answer "already done".
+ *
+ * This is the general form and `specificationFor` below is a one-line
+ * specialisation of it, which is the result worth stating rather than the
+ * mechanism: a `Decider` is one particular `(command) => Effect<Position, …>`,
+ * and `runDecider` is the function that says so. Nothing downstream of `when`
+ * moves — the same seed boundary, the same read-back, the same shape comparison
+ * — because both cycles already agree on what they return.
+ *
+ * ⚠ `run`'s error channel is written `E | CycleError` and must be: the chain adds
+ * that union itself, so a naive `Effect<Position, E, R>` double-counts it and
+ * fails to unify. `CycleError` exists to be written here.
  */
-export const specificationFor = decider => ({
+export const specificationForCycle = run => ({
   given: (...pastEvents) => ({
     when: command => {
-      // Run the seed + decider cycle, exposing the outcome as an Exit so both
+      // Run the seed + 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
+      // the cycle'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);
+      const runToExit = seed(pastEvents).pipe(Effect.zip(run(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* () {
@@ -109,7 +130,8 @@ export const specificationFor = decider => ({
             // it loud rather than silently passing.
             return yield* Effect.failCause(exit.cause);
           }
-          const [seedBoundary] = exit.value;
+          const [seedBoundary, result] = exit.value;
+          expect(isUnchanged(result)).toBe(false);
           const appended = yield* appendedAfter(seedBoundary);
           const expectedEvents = yield* Effect.all(expected);
           expect(appended.map(s => shapeOf(s.event))).toEqual(expectedEvents.map(shapeOf));
@@ -123,11 +145,31 @@ export const specificationFor = decider => ({
             const actualTag = typeof error === 'object' && error !== null && '_tag' in error ? error._tag : undefined;
             expect(actualTag).toBe(tag);
           }
+        }),
+        thenUnchanged: () => Effect.gen(function* () {
+          const exit = yield* runToExit;
+          if (Exit.isFailure(exit)) {
+            return yield* Effect.failCause(exit.cause);
+          }
+          const [seedBoundary, result] = exit.value;
+          expect(isUnchanged(result)).toBe(true);
+          const appended = yield* appendedAfter(seedBoundary);
+          expect(appended.map(s => shapeOf(s.event))).toEqual([]);
         })
       };
     }
   })
 });
+/**
+ * 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>`.
+ *
+ * One line over the layered sibling above, and deliberately not a twin of it:
+ * a duplicated body would be two sets of tests and two things free to drift on
+ * the seed boundary, the read-back or the shape comparison.
+ */
+export const specificationFor = decider => specificationForCycle(command => runDecider(decider, command));
 /**
  * `scenario(description, spec => spec.given(...).when(...).then(...))` — register
  * an `@effect/vitest` `it.effect` case running `build` against a fresh in-memory

package/dist/esm/specification.js.map

@@ -1 +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":[]}
+{"version":3,"file":"specification.js","names":["expect","it","isUnchanged","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","specificationForCycle","run","given","pastEvents","when","command","runToExit","zip","exit","then","expected","isFailure","failCause","cause","seedBoundary","result","value","toBe","appended","expectedEvents","s","toEqual","thenError","tag","failure","failureOption","error","_tag","undefined","actualTag","thenUnchanged","specificationFor","decider","scenario","description","build","effect","provide","mergeAll","fresh"],"sources":["../../src/specification.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairos-es/testing",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "Given/When/Then decision-model testing surface for kairos-es",
   "license": "BSD-3-Clause",
   "repository": {
@@ -13,8 +13,8 @@
   "peerDependencies": {
     "@effect/vitest": "^0.30.0",
     "effect": "^3.22.0",
-    "@kairos-es/codec": "^1.0.0-alpha.0",
-    "@kairos-es/core": "^1.0.0-alpha.0"
+    "@kairos-es/codec": "^1.0.0-alpha.2",
+    "@kairos-es/core": "^1.0.0-alpha.2"
   },
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",

package/src/index.ts

@@ -1,10 +1,13 @@
 /**
  * @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.
+ * A `DeciderSpecification`-equivalent over a real fold and a `DcbEventStore` (in
+ * practice the in-memory layer): `@kairos-es/codec`'s `buildDecisionModel` for
+ * a single-hop decision, and `modelAtHead` plus the read ledger for a layered
+ * one. Shaped so an Event Modeling `Specification` (given events / when a
+ * command / then events / thenError a tag) compiles onto it 1:1, plus
+ * `thenUnchanged` for a decision that answers "already done" and appends
+ * nothing.
  *
  *   scenario('subscribe a student', subscribeDecider, (spec) =>
  *     spec

package/src/specification.ts

@@ -1,7 +1,12 @@
 /**
- * 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
+ * The Given/When/Then surface: a `DeciderSpecification`-equivalent over a real
+ * fold and a `DcbEventStore` (the in-memory layer in practice) —
+ * `@kairos-es/codec`'s `buildDecisionModel` for a single-hop decision, and
+ * `modelAtHead` plus the read ledger for a layered one. `specificationForCycle`
+ * is the general entry point over either, named for the command CYCLE it takes
+ * rather than for the layered bracket that was its first caller — the shape it
+ * accepts is `(command) => Effect<Position, …>` and a decider is one instance of
+ * it. 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`.
@@ -16,12 +21,17 @@
  *     .when(command)
  *     .thenError('AppendConditionFailed')   // failure branch (domain error or conflict)
  *
+ *   specificationFor(decider)
+ *     .given(...pastEventProducers)
+ *     .when(command)
+ *     .thenUnchanged()                      // "already done" branch: nothing appended
+ *
  * 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
+ * Each terminal (`then` / `thenError` / `thenUnchanged`) 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`
@@ -38,10 +48,15 @@ import { expect, it } from '@effect/vitest'
 import type {
   CodecError,
   Decider,
+  DecisionOutput,
+  NoReadsRecorded,
   RequirementOf,
   SliceProjection,
+  TaglessSliceInLedger,
+  Unchanged,
 } from '@kairos-es/codec'
 import {
+  isUnchanged,
   runDecider,
   type Serializer,
   SerializerDefault,
@@ -58,7 +73,15 @@ import {
   query as Q,
   type SequencedEvent,
 } from '@kairos-es/core'
-import { Cause, Chunk, Effect, Exit, Layer, Stream } from 'effect'
+import {
+  type Array as Arr,
+  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<
@@ -128,6 +151,28 @@ const appendedAfter = (
     return yield* collect(events)
   })
 
+/**
+ * The errors a command CYCLE contributes, beyond whatever `E` the decision
+ * itself fails with.
+ *
+ * Named once and exported because it is what makes the layered entry point below
+ * UNIFY. `WhenSpec.then` adds this union itself, so a `run` written as a naive
+ * `Effect<Position, E, R>` double-counts every member of it and fails to
+ * typecheck against a chain that has already added them — a trap with an
+ * unhelpful error message, met once and closed here by giving the union a name a
+ * caller can write.
+ *
+ * `NoReadsRecorded` is reachable only on the layered path and `TaglessSliceInLedger`
+ * only where a bracket is open, but both are members here rather than in a second
+ * union, because the two paths share every step downstream of `when` and a second
+ * union would be a second thing to keep in step for no caller's benefit.
+ */
+export type CycleError =
+  | CodecError
+  | AppendConditionFailed
+  | TaglessSliceInLedger
+  | NoReadsRecorded
+
 /**
  * The entry point of the Given/When/Then chain: what `specificationFor` returns
  * and what `scenario` hands its `build` callback. It is NAMED rather than
@@ -163,57 +208,100 @@ export interface GivenSpec<Command, E, R, PR> {
   readonly when: (command: Command) => WhenSpec<E, R, PR>
 }
 
-/** A spec that has a command and awaits a `then`/`thenError` assertion. */
+/** A spec that has a command and awaits a `then`/`thenError`/`thenUnchanged` 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).
+   * channel keeps `E | CycleError` 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).
+   *
+   * A cycle that answered `Unchanged` FAILS this assertion, even with no
+   * expected events. `.then()` with an empty list and `.thenUnchanged()` both
+   * see nothing appended, but they claim different things — *decided an empty
+   * change* is not a decision this library can make, while *already done* is —
+   * so the one that does not match the cycle's answer must not pass.
    */
   readonly then: (
     ...expected: ReadonlyArray<EventProducer<R>>
   ) => Effect.Effect<
     void,
-    E | CodecError | AppendConditionFailed,
+    E | CycleError,
     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).
+   *
+   * ⚠ THREE WAYS THIS PASSES FOR THE WRONG REASON, and a layered or permission
+   * suite must assert more than the tag. An opaque refusal is correct on the wire
+   * and is exactly what blinds this assertion — two different denials share one
+   * tag, so a spec can pass on a refusal its author did not mean. An
+   * `AppendConditionFailed` now also fires for an EARLIER hop, so the tag no
+   * longer says which boundary moved. And `NoReadsRecorded` is a reachable spec
+   * whose shape does not mark it as structural: it reads like a domain assertion
+   * and is a statement about wiring.
    */
   readonly thenError: (
     tag: string,
   ) => Effect.Effect<void, never, DcbEventStore | Serializer | Uuid | R | PR>
+  /**
+   * Assert the "already done" branch: the cycle SUCCEEDED with `Unchanged`
+   * (recognised by `isUnchanged`, never by its tag) and appended nothing past
+   * the seed. A cycle that appended — even an empty-looking one — or that
+   * returned a `Position` fails it, and a failing cycle re-raises its cause, for
+   * the reason `then` gives.
+   *
+   * Both halves are asserted, not just the result, because they are different
+   * claims: a runner that returned `Unchanged` AND appended would be exactly the
+   * defect this step exists to catch, and the result alone would not see it.
+   */
+  readonly thenUnchanged: () => Effect.Effect<
+    void,
+    E | CycleError,
+    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>`.
+ * Begin a specification for ANY command cycle that returns the appended
+ * `Position` — a bracket for one command as readily as a decider — or
+ * `Unchanged`, for a cycle that can answer "already done".
+ *
+ * This is the general form and `specificationFor` below is a one-line
+ * specialisation of it, which is the result worth stating rather than the
+ * mechanism: a `Decider` is one particular `(command) => Effect<Position, …>`,
+ * and `runDecider` is the function that says so. Nothing downstream of `when`
+ * moves — the same seed boundary, the same read-back, the same shape comparison
+ * — because both cycles already agree on what they return.
+ *
+ * ⚠ `run`'s error channel is written `E | CycleError` and must be: the chain adds
+ * that union itself, so a naive `Effect<Position, E, R>` double-counts it and
+ * fails to unify. `CycleError` exists to be written here.
  */
-export const specificationFor = <
-  P extends Record<string, SliceProjection>,
-  Command,
-  E,
-  R,
->(
-  decider: Decider<P, Command, E, R>,
-): Specification<Command, E, R, RequirementOf<P>> => ({
+export const specificationForCycle = <Command, E, R, PR = never>(
+  run: (
+    command: Command,
+  ) => Effect.Effect<
+    Position | Unchanged,
+    E | CycleError,
+    DcbEventStore | Serializer | Uuid | R | PR
+  >,
+): Specification<Command, E, R, PR> => ({
   given: (...pastEvents) => ({
     when: (command) => {
-      // Run the seed + decider cycle, exposing the outcome as an Exit so both
+      // Run the seed + 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
+      // the cycle'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.zip(run(command)),
         Effect.exit,
       )
 
@@ -228,7 +316,8 @@ export const specificationFor = <
               // it loud rather than silently passing.
               return yield* Effect.failCause(exit.cause)
             }
-            const [seedBoundary] = exit.value
+            const [seedBoundary, result] = exit.value
+            expect(isUnchanged(result)).toBe(false)
             const appended = yield* appendedAfter(seedBoundary)
             const expectedEvents = yield* Effect.all(expected)
             expect(appended.map((s) => shapeOf(s.event))).toEqual(
@@ -249,11 +338,44 @@ export const specificationFor = <
               expect(actualTag).toBe(tag)
             }
           }),
+        thenUnchanged: () =>
+          Effect.gen(function* () {
+            const exit = yield* runToExit
+            if (Exit.isFailure(exit)) {
+              return yield* Effect.failCause(exit.cause)
+            }
+            const [seedBoundary, result] = exit.value
+            expect(isUnchanged(result)).toBe(true)
+            const appended = yield* appendedAfter(seedBoundary)
+            expect(appended.map((s) => shapeOf(s.event))).toEqual([])
+          }),
       }
     },
   }),
 })
 
+/**
+ * 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>`.
+ *
+ * One line over the layered sibling above, and deliberately not a twin of it:
+ * a duplicated body would be two sets of tests and two things free to drift on
+ * the seed boundary, the read-back or the shape comparison.
+ */
+export const specificationFor = <
+  P extends Record<string, SliceProjection>,
+  Command,
+  E,
+  R,
+  O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>,
+>(
+  decider: Decider<P, Command, E, R, O>,
+): Specification<Command, E, R, RequirementOf<P>> =>
+  specificationForCycle<Command, E, R, RequirementOf<P>>((command) =>
+    runDecider(decider, command),
+  )
+
 /**
  * `scenario(description, spec => spec.given(...).when(...).then(...))` — register
  * an `@effect/vitest` `it.effect` case running `build` against a fresh in-memory
@@ -267,16 +389,17 @@ export const specificationFor = <
  * encryption requirement provides its cipher layer inside `build` before
  * returning.
  */
-export const scenario = <P extends Record<string, SliceProjection>, Command, E>(
+export const scenario = <
+  P extends Record<string, SliceProjection>,
+  Command,
+  E,
+  O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>,
+>(
   description: string,
-  decider: Decider<P, Command, E>,
+  decider: Decider<P, Command, E, never, O>,
   build: (
     spec: Specification<Command, E, never, RequirementOf<P>>,
-  ) => Effect.Effect<
-    void,
-    E | CodecError | AppendConditionFailed,
-    DcbEventStore | Serializer | Uuid
-  >,
+  ) => Effect.Effect<void, E | CycleError, DcbEventStore | Serializer | Uuid>,
 ): void => {
   it.effect(description, () =>
     build(specificationFor(decider)).pipe(