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

package/README.md

@@ -39,6 +39,10 @@ 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
 imports them and deliberately does not re-export them, so typing a command

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":";;;;;AA2BA,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

@@ -31,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`
@@ -97,7 +102,8 @@ const appendedAfter = after => _effect.Effect.gen(function* () {
 });
 /**
  * Begin a specification for ANY command cycle that returns the appended
- * `Position` — a bracket for one command as readily as a decider.
+ * `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
@@ -131,7 +137,8 @@ const specificationForCycle = run => ({
             // 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));
@@ -145,6 +152,16 @@ const specificationForCycle = run => ({
             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([]);
         })
       };
     }

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","specificationForCycle","run","given","pastEvents","when","command","runToExit","zip","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","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":[]}
+{"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

@@ -5,7 +5,9 @@
  * 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.
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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,7 +1,7 @@
-import type { CodecError, Decider, NoReadsRecorded, RequirementOf, SliceProjection, TaglessSliceInLedger } 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, type Position } from '@kairos-es/core';
-import { Effect } from 'effect';
+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>;
 /**
@@ -52,7 +52,7 @@ 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
@@ -61,6 +61,12 @@ export interface WhenSpec<E, R, PR> {
      * 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 | CycleError, DcbEventStore | Serializer | Uuid | R | PR>;
     /**
@@ -78,10 +84,23 @@ export interface WhenSpec<E, R, PR> {
      * 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.
+ * `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
@@ -94,7 +113,7 @@ export interface WhenSpec<E, R, PR> {
  * 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, E | CycleError, DcbEventStore | Serializer | Uuid | R | PR>) => Specification<Command, E, R, PR>;
+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
@@ -104,7 +123,7 @@ export declare const specificationForCycle: <Command, E, R, PR = never>(run: (co
  * 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
@@ -118,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 | CycleError, 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":"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"}
+{"version":3,"file":"specification.d.ts","sourceRoot":"","sources":["../../src/specification.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -5,7 +5,9 @@
  * 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.
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,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

@@ -21,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`
@@ -40,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 => ({
@@ -90,7 +95,8 @@ const appendedAfter = after => Effect.gen(function* () {
 });
 /**
  * Begin a specification for ANY command cycle that returns the appended
- * `Position` — a bracket for one command as readily as a decider.
+ * `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
@@ -124,7 +130,8 @@ export const specificationForCycle = run => ({
             // 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));
@@ -138,6 +145,16 @@ export const specificationForCycle = run => ({
             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([]);
         })
       };
     }

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","specificationForCycle","run","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","specificationFor","decider","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.1",
+  "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.1",
-    "@kairos-es/core": "^1.0.0-alpha.1"
+    "@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

@@ -5,7 +5,9 @@
  * 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.
+ * 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

@@ -21,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`
@@ -43,12 +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,
@@ -65,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<
@@ -192,7 +208,7 @@ 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
@@ -201,6 +217,12 @@ export interface WhenSpec<E, R, PR> {
    * 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>>
@@ -226,11 +248,28 @@ export interface WhenSpec<E, R, PR> {
   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.
+ * `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
@@ -247,7 +286,7 @@ export const specificationForCycle = <Command, E, R, PR = never>(
   run: (
     command: Command,
   ) => Effect.Effect<
-    Position,
+    Position | Unchanged,
     E | CycleError,
     DcbEventStore | Serializer | Uuid | R | PR
   >,
@@ -277,7 +316,8 @@ export const specificationForCycle = <Command, E, R, PR = never>(
               // 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(
@@ -298,6 +338,17 @@ export const specificationForCycle = <Command, E, R, PR = never>(
               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([])
+          }),
       }
     },
   }),
@@ -317,8 +368,9 @@ export const specificationFor = <
   Command,
   E,
   R,
+  O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>,
 >(
-  decider: Decider<P, Command, E, R>,
+  decider: Decider<P, Command, E, R, O>,
 ): Specification<Command, E, R, RequirementOf<P>> =>
   specificationForCycle<Command, E, R, RequirementOf<P>>((command) =>
     runDecider(decider, command),
@@ -337,9 +389,14 @@ 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 | CycleError, DcbEventStore | Serializer | Uuid>,