@cratis/chronicle 6.12.0 → 6.14.0

package/reducers/ReducerEventDispatcher.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import type { EventContext } from '../events/EventContext.js';
+import type { ReducerEventHandler } from './ReducerEventHandler.js';
+
+/** Selects and invokes the same reducer handlers for kernel deliveries and in-process scenarios. */
+export class ReducerEventDispatcher {
+    readonly handlers: ReducerEventHandler[];
+
+    /** Discovers event methods from the artifact event types. */
+    constructor(reducerType: Constructor, eventTypes: readonly Constructor[]) {
+        const proto = reducerType.prototype as Record<string, unknown>;
+        this.handlers = [];
+        for (const eventTypeClass of eventTypes) {
+            const metadata = getEventTypeMetadata(eventTypeClass);
+            if (!metadata) continue;
+            const className = (eventTypeClass as Function).name;
+            const methodName = className.charAt(0).toLowerCase() + className.slice(1);
+            if (typeof proto[methodName] === 'function') {
+                this.handlers.push({
+                    id: metadata.eventType.id.value,
+                    generation: metadata.eventType.generation.value,
+                    methodName
+                });
+            }
+        }
+    }
+
+    /** Resolves a registered event type, or returns undefined for an unsubscribed event. */
+    handlerFor(eventTypeId: string): ReducerEventHandler | undefined {
+        return this.handlers.find(handler => handler.id === eventTypeId);
+    }
+
+    /** Calls the selected handler with the event, current state, and context. */
+    async invoke(
+        instance: Record<string, Function>,
+        handler: ReducerEventHandler,
+        event: unknown,
+        currentState: unknown,
+        context: EventContext
+    ): Promise<unknown> {
+        return await instance[handler.methodName](event, currentState, context) as unknown;
+    }
+}

package/reducers/ReducerEventHandler.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Event type and camel-case method selected for a reducer observation. */
+export interface ReducerEventHandler {
+    readonly id: string;
+    readonly generation: number;
+    readonly methodName: string;
+}

package/reducers/Reducers.ts

@@ -8,7 +8,6 @@ import { ObservationState, ReadModelObserverType, ReducerMessage } from '@cratis
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
 import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
-import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
 import { toClientEventContext } from '../events/toClientEventContext.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
@@ -16,6 +15,7 @@ import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
 import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle.js';
 import { IReducers } from './IReducers.js';
 import { getReducerMetadata } from './reducer.js';
+import { ReducerEventDispatcher } from './ReducerEventDispatcher.js';
 import { getReadModelMetadata } from '../readModels/index.js';
 import { getReadModelId } from '../readModels/readModel.js';
 import { buildReadModelDefinition } from '../readModels/buildReadModelDefinition.js';
@@ -28,12 +28,6 @@ const EVENT_SOURCE_ID_KEY = '$eventSourceId';
 /** Sentinel sequence number sent back when no event was successfully processed. */
 const SEQUENCE_NUMBER_UNAVAILABLE = 4294967295n;
 
-interface EventTypeEntry {
-    readonly id: string;
-    readonly generation: number;
-    readonly methodName: string;
-}
-
 /**
  * A push-based async queue that implements {@link AsyncIterable} for use with nice-grpc
  * bidirectional streaming. Values pushed via {@link send} are yielded in order to
@@ -229,29 +223,29 @@ export class Reducers implements IReducers {
         if (this._disposed) return;
         const metadata = getReducerMetadata(reducerType)!;
         const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
-        const eventTypes = this.getEventTypesFor(reducerType);
+        const dispatcher = new ReducerEventDispatcher(reducerType, this._clientArtifacts.eventTypes);
         const readModelName = this.getReducerReadModelIdentifier(reducerType);
 
         this._logger.info('Starting reducer observation', {
             reducerId: id,
             eventSequenceId,
             readModel: readModelName,
-            handlerCount: eventTypes.length,
-            handlers: eventTypes.map(e => e.methodName)
+            handlerCount: dispatcher.handlers.length,
+            handlers: dispatcher.handlers.map(e => e.methodName)
         });
 
-        void this.runObservation(id, reducerType, eventSequenceId, eventTypes, readModelName);
+        void this.runObservation(id, reducerType, eventSequenceId, readModelName, dispatcher);
     }
 
     private async runObservation(
         id: string,
         reducerType: Constructor,
         eventSequenceId: string,
-        eventTypes: EventTypeEntry[],
-        readModelName: string
+        readModelName: string,
+        dispatcher: ReducerEventDispatcher
     ): Promise<void> {
         try {
-            await this.observeReducer(id, reducerType, eventSequenceId, eventTypes, readModelName);
+            await this.observeReducer(id, reducerType, eventSequenceId, readModelName, dispatcher);
         } catch (error) {
             this._logger.error('Reducer observation loop exited with error', { reducerId: id, error: String(error) });
         }
@@ -301,8 +295,8 @@ export class Reducers implements IReducers {
         id: string,
         reducerType: Constructor,
         eventSequenceId: string,
-        eventTypes: EventTypeEntry[],
-        readModelName: string
+        readModelName: string,
+        dispatcher: ReducerEventDispatcher
     ): Promise<void> {
         const queue = new AsyncQueue<ReducerMessage>();
         const controller = new AbortController();
@@ -319,7 +313,7 @@ export class Reducers implements IReducers {
                     Reducer: {
                         ReducerId: id,
                         EventSequenceId: eventSequenceId,
-                        EventTypes: eventTypes.map(et => ({
+                        EventTypes: dispatcher.handlers.map(et => ({
                             EventType: { Id: et.id, Generation: et.generation, Tombstone: false },
                             Key: EVENT_SOURCE_ID_KEY
                         })),
@@ -377,7 +371,7 @@ export class Reducers implements IReducers {
                             continue;
                         }
 
-                        const entry = eventTypes.find(et => et.id === eventTypeId);
+                        const entry = dispatcher.handlerFor(eventTypeId);
                         if (!entry) {
                             this._logger.debug('No handler registered for event type — skipping', { reducerId: id, eventTypeId });
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
@@ -395,7 +389,7 @@ export class Reducers implements IReducers {
                             hasState: currentState !== undefined
                         });
 
-                        currentState = await reducerInstance[entry.methodName](content, currentState, context);
+                        currentState = await dispatcher.invoke(reducerInstance, entry, content, currentState, context);
                         lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                     } catch (err) {
                         this._logger.error('Error handling event in reducer', { reducerId: id, error: String(err) });
@@ -442,29 +436,6 @@ export class Reducers implements IReducers {
         }
     }
 
-    private getEventTypesFor(reducerType: Constructor): EventTypeEntry[] {
-        const proto = reducerType.prototype as Record<string, unknown>;
-        const entries: EventTypeEntry[] = [];
-
-        for (const eventTypeClass of this._clientArtifacts.eventTypes) {
-            const eventTypeMeta = getEventTypeMetadata(eventTypeClass);
-            if (!eventTypeMeta) continue;
-
-            const className = (eventTypeClass as Function).name;
-            const methodName = className.charAt(0).toLowerCase() + className.slice(1);
-
-            if (typeof proto[methodName] === 'function') {
-                entries.push({
-                    id: eventTypeMeta.eventType.id.value,
-                    generation: eventTypeMeta.eventType.generation.value,
-                    methodName
-                });
-            }
-        }
-
-        return entries;
-    }
-
     private disconnectAll(): void {
         for (const controller of this._observations.values()) controller.abort();
         for (const queue of this._queues.values()) queue.complete();

package/testing/ReadModelScenario.example.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { eventType } from '../events/eventTypeDecorator.js';
+import { reducer } from '../reducers/reducer.js';
+import { ReadModelScenario } from './index.js';
+
+class BookBorrowed {
+    constructor(readonly title: string) {}
+}
+eventType('book-borrowed')(BookBorrowed);
+
+class BookStatus {
+    title = '';
+}
+
+class BookStatusReducer {
+    bookBorrowed(event: BookBorrowed): BookStatus {
+        return { title: event.title };
+    }
+}
+reducer('book-status-reducer', undefined, BookStatus)(BookStatusReducer);
+
+/** An in-process read model example compiled with the SDK. */
+export async function readModelScenarioExample(): Promise<BookStatus | null> {
+    const scenario = new ReadModelScenario(BookStatus);
+    scenario.given.forEventSource('book-42').events(new BookBorrowed('Dune'));
+    return await scenario.instanceForEventSourceId('book-42');
+}

package/testing/ReadModelScenario.spec.ts

@@ -0,0 +1,191 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { ConceptAs, field } from '@cratis/fundamentals';
+import type { Constructor } from '@cratis/fundamentals';
+import { eventType } from '../events/eventTypeDecorator.js';
+import type { EventContext } from '../events/EventContext.js';
+import { fromEvent } from '../projections/modelBound/fromEvent.js';
+import { projection } from '../projections/declarative/projection.js';
+import { reducer } from '../reducers/reducer.js';
+import { ReadModelScenario, ReadModelScenarioGivenBuilder } from './index.js';
+import { readModelScenarioExample } from './ReadModelScenario.example.js';
+
+class ItemAdded {
+    constructor(readonly amount: number) {}
+}
+eventType('scenario-item-added')(ItemAdded);
+class ItemRemoved {}
+eventType('scenario-item-removed')(ItemRemoved);
+class UnrelatedEvent {}
+eventType('scenario-unrelated')(UnrelatedEvent);
+class BookTitle extends ConceptAs<string> {
+    static readonly valueType = String;
+}
+class BookNamed {
+    @field(BookTitle) title: BookTitle;
+    constructor(title: BookTitle) { this.title = title; }
+}
+eventType('scenario-book-named')(BookNamed);
+class BookState { title = ''; }
+class BookReducer {
+    bookNamed(event: { title: string }): BookState { return { title: event.title }; }
+}
+reducer('scenario-book-reducer', undefined, BookState)(BookReducer);
+
+const nullableStates: unknown[] = [];
+class NullableState { count = 0; }
+class NullableReducer {
+    itemAdded(_event: ItemAdded, current: NullableState | null | undefined): null {
+        nullableStates.push(current);
+        return null;
+    }
+}
+reducer('scenario-nullable-reducer', undefined, NullableState)(NullableReducer);
+
+const reducerFailure = new Error('broken handler');
+class FailingState {}
+class FailingReducer {
+    itemAdded(): never { throw reducerFailure; }
+}
+reducer('scenario-failing-reducer', undefined, FailingState)(FailingReducer);
+
+class ItemState {
+    count = 0;
+}
+const contexts: EventContext[] = [];
+const incomingStates: Array<ItemState | undefined> = [];
+class ItemReducer {
+    async itemAdded(event: ItemAdded, current: ItemState | undefined, context: EventContext): Promise<ItemState> {
+        contexts.push(context);
+        incomingStates.push(current);
+        await Promise.resolve();
+        return { count: (current?.count ?? 0) + event.amount };
+    }
+    itemRemoved(): undefined { return undefined; }
+}
+reducer('scenario-item-reducer', undefined, ItemState)(ItemReducer);
+
+const artifacts = {
+    reducers: [ItemReducer],
+    eventTypes: [ItemAdded, ItemRemoved, UnrelatedEvent],
+    projections: [] as Constructor[]
+};
+
+describe('ReadModelScenario', () => {
+    it('runs the compiled documentation example', async () => {
+        expect(await readModelScenarioExample()).toEqual({ title: 'Dune' });
+    });
+
+    it('exposes a named given builder for selecting an event source', () => {
+        const scenario = new ReadModelScenario(ItemState, artifacts);
+        expect(scenario.given).toBeInstanceOf(ReadModelScenarioGivenBuilder);
+    });
+
+    it('returns null without matching events and distinguishes that from deletion', async () => {
+        const scenario = new ReadModelScenario(ItemState, artifacts);
+        scenario.given.forEventSource('A').events(new UnrelatedEvent());
+        expect(await scenario.instance).toBeNull();
+        expect(await scenario.instanceForEventSourceId('A')).toBeNull();
+        expect(await scenario.wasDeletedForEventSourceId('A')).toBe(false);
+    });
+
+    it('passes each event, current state, and realistic ordered contexts to an async reducer', async () => {
+        contexts.length = 0;
+        incomingStates.length = 0;
+        const scenario = new ReadModelScenario(ItemState, artifacts);
+        scenario.given.forEventSource('A').events(new ItemAdded(2), new ItemAdded(3));
+        expect(await scenario.instance).toEqual({ count: 5 });
+        expect(incomingStates).toEqual([undefined, { count: 2 }]);
+        expect(contexts.map(context => context.sequenceNumber)).toEqual([0n, 1n]);
+        expect(contexts.map(context => context.eventSourceId)).toEqual(['A', 'A']);
+        expect(contexts.map(context => context.eventSourceType)).toEqual(['Default', 'Default']);
+        expect(contexts.map(context => context.eventStreamType)).toEqual(['All', 'All']);
+        expect(contexts.map(context => context.eventStreamId)).toEqual(['Default', 'Default']);
+        expect(contexts.map(context => context.eventStore)).toEqual(['[NotSet]', '[NotSet]']);
+        expect(contexts.map(context => context.namespace)).toEqual(['[NotSet]', '[NotSet]']);
+        expect(contexts.map(context => context.eventType.id.value)).toEqual(['scenario-item-added', 'scenario-item-added']);
+        expect(contexts.map(context => context.eventType.generation.value)).toEqual([1, 1]);
+        expect(contexts.every(context => context.occurred instanceof Date && !Number.isNaN(context.occurred.getTime()))).toBe(true);
+        expect(contexts.map(context => context.correlationId)).toEqual([
+            '00000000-0000-0000-0000-000000000000', '00000000-0000-0000-0000-000000000000'
+        ]);
+    });
+
+    it('keeps interleaved event sources separate and rejects an ambiguous single instance', async () => {
+        contexts.length = 0;
+        const scenario = new ReadModelScenario(ItemState, artifacts);
+        scenario.given.forEventSource('A').events(new ItemAdded(2));
+        scenario.given.forEventSource('B').events(new ItemAdded(7));
+        scenario.given.forEventSource('A').events(new ItemAdded(3));
+        expect(await scenario.instanceForEventSourceId('A')).toEqual({ count: 5 });
+        expect(await scenario.instanceForEventSourceId('B')).toEqual({ count: 7 });
+        expect(contexts.map(context => context.sequenceNumber)).toEqual([0n, 1n, 2n]);
+        expect(contexts.map(context => context.eventSourceId)).toEqual(['A', 'B', 'A']);
+        await expect(scenario.instance).rejects.toThrow('Multiple read model instances');
+    });
+
+    it('replays added events after an earlier result was read', async () => {
+        const scenario = new ReadModelScenario(ItemState, artifacts);
+        scenario.given.forEventSource('A').events(new ItemAdded(2));
+        expect(await scenario.instance).toEqual({ count: 2 });
+        scenario.given.forEventSource('A').events(new ItemAdded(3));
+        expect(await scenario.instance).toEqual({ count: 5 });
+    });
+
+    it('treats an undefined reducer result as deletion, not missing history', async () => {
+        incomingStates.length = 0;
+        const scenario = new ReadModelScenario(ItemState, artifacts);
+        scenario.given.forEventSource('A').events(new ItemAdded(2), new ItemRemoved());
+        expect(await scenario.instanceForEventSourceId('A')).toBeNull();
+        expect(await scenario.wasDeletedForEventSourceId('A')).toBe(true);
+        scenario.given.forEventSource('A').events(new ItemAdded(4));
+        expect(await scenario.instance).toEqual({ count: 4 });
+        expect(incomingStates.at(-1)).toBeUndefined();
+        expect(await scenario.wasDeletedForEventSourceId('A')).toBe(false);
+    });
+
+    it('serializes concept properties as primitives, like production append', async () => {
+        const scenario = new ReadModelScenario(BookState, {
+            reducers: [BookReducer], eventTypes: [BookNamed], projections: []
+        });
+        scenario.given.forEventSource('book-42').events(new BookNamed(new BookTitle('Dune')));
+        expect(await scenario.instance).toEqual({ title: 'Dune' });
+    });
+
+    it('preserves a null reducer result as null state rather than a deletion', async () => {
+        nullableStates.length = 0;
+        const scenario = new ReadModelScenario(NullableState, {
+            reducers: [NullableReducer], eventTypes: [ItemAdded], projections: []
+        });
+        scenario.given.forEventSource('A').events(new ItemAdded(1), new ItemAdded(2));
+        expect(await scenario.instanceForEventSourceId('A')).toBeNull();
+        expect(await scenario.wasDeletedForEventSourceId('A')).toBe(false);
+        expect(nullableStates).toEqual([undefined, null]);
+    });
+
+    it('wraps reducer failures with the read model and reducer names and preserves the cause', async () => {
+        const scenario = new ReadModelScenario(FailingState, {
+            reducers: [FailingReducer], eventTypes: [ItemAdded], projections: []
+        });
+        scenario.given.forEventSource('A').events(new ItemAdded(1));
+        await expect(scenario.instance).rejects.toMatchObject({
+            message: expect.stringContaining('FailingState'),
+            cause: reducerFailure
+        });
+        await expect(scenario.instance).rejects.toThrow('FailingReducer');
+    });
+
+    it('rejects model-bound and declarative projections rather than silently returning null', () => {
+        class ProjectedState {}
+        fromEvent(ItemAdded)(ProjectedState);
+        expect(() => new ReadModelScenario(ProjectedState, artifacts)).toThrow('not supported yet; use a kernel-backed test');
+
+        class FluentState {}
+        class FluentProjection {}
+        projection('scenario-fluent-projection', FluentState)(FluentProjection);
+        expect(() => new ReadModelScenario(FluentState, { ...artifacts, projections: [FluentProjection] }))
+            .toThrow('not supported yet; use a kernel-backed test');
+    });
+});

package/testing/ReadModelScenario.ts

@@ -0,0 +1,151 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { JsonSerializer } from '@cratis/fundamentals';
+import type { Constructor } from '@cratis/fundamentals';
+import type { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
+import type { EventContext } from '../events/EventContext.js';
+import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { getFromEventMetadata } from '../projections/modelBound/fromEvent.js';
+import { getRemovedWithClassMetadata } from '../projections/modelBound/removedWith.js';
+import { getRemovedWithJoinClassMetadata } from '../projections/modelBound/removedWithJoin.js';
+import { getClearWithClassMetadata } from '../projections/modelBound/clearWith.js';
+import { getVariantOfMetadata } from '../projections/modelBound/variantOf.js';
+import { getEntersOnMetadata } from '../projections/modelBound/entersOn.js';
+import { getProjectionMetadata } from '../projections/declarative/projection.js';
+import { getReducerMetadata } from '../reducers/reducer.js';
+import { ReducerEventDispatcher } from '../reducers/ReducerEventDispatcher.js';
+import { DecoratorType } from '../types/DecoratorType.js';
+import { hasModelBoundProperties, TypeDiscoverer } from '../types/TypeDiscoverer.js';
+import { ReadModelScenarioGivenBuilder } from './ReadModelScenarioGivenBuilder.js';
+
+type ScenarioArtifacts = Pick<IClientArtifactsProvider, 'reducers' | 'eventTypes' | 'projections'>;
+
+type SeededEvent = { sourceId: string; content: unknown; context: EventContext };
+type ReducedState<T> = { instance: T | null; deleted: boolean };
+
+/**
+ * Folds seeded events through a reducer in-process, without a Chronicle kernel.
+ * Projections, observer scheduling, storage, migrations, and compliance are not simulated.
+ * Supply an artifact catalog to isolate a scenario from process-wide decorator discovery.
+ */
+export class ReadModelScenario<TReadModel extends object> {
+    private readonly _readModelType: Constructor<TReadModel>;
+    private readonly _reducerType: Constructor;
+    private readonly _dispatcher: ReducerEventDispatcher;
+    private readonly _events: SeededEvent[] = [];
+    private _results: Promise<Map<string, ReducedState<TReadModel>>> | undefined;
+
+    /** Selects the reducer associated with the read model type. */
+    constructor(readModelType: Constructor<TReadModel>, artifacts?: ScenarioArtifacts) {
+        this._readModelType = readModelType;
+        const registered = artifacts ?? {
+            reducers: TypeDiscoverer.default.getTypesByDecoratorType(DecoratorType.Reducer),
+            eventTypes: TypeDiscoverer.default.getTypesByDecoratorType(DecoratorType.EventType),
+            projections: TypeDiscoverer.default.getTypesByDecoratorType(DecoratorType.Projection)
+        };
+        const reducerTypes = registered.reducers.filter(type => getReducerMetadata(type)?.readModel === readModelType);
+        if (reducerTypes.length > 1) {
+            throw new Error(`Multiple reducers found for read model '${readModelType.name}'.`);
+        }
+        if (reducerTypes.length === 0) {
+            const projected = getFromEventMetadata(readModelType).length > 0 || hasModelBoundProperties(readModelType) ||
+                getRemovedWithClassMetadata(readModelType).length > 0 || getRemovedWithJoinClassMetadata(readModelType).length > 0 ||
+                getClearWithClassMetadata(readModelType).length > 0 || getVariantOfMetadata(readModelType) !== undefined ||
+                getEntersOnMetadata(readModelType).length > 0 ||
+                registered.projections.some(type => getProjectionMetadata(type)?.readModelType === readModelType);
+            if (projected) {
+                throw new Error(`Projection-backed read model '${readModelType.name}' is not supported yet; use a kernel-backed test.`);
+            }
+            throw new Error(`No reducer found for read model '${readModelType.name}'. Pass the read model type to @reducer; projections are not supported yet (use a kernel-backed test).`);
+        }
+        this._reducerType = reducerTypes[0];
+        this._dispatcher = new ReducerEventDispatcher(this._reducerType, registered.eventTypes);
+    }
+
+    /** Fluent entry point for event history. */
+    get given(): ReadModelScenarioGivenBuilder<TReadModel> {
+        return new ReadModelScenarioGivenBuilder(this);
+    }
+
+    /** Returns the sole materialized model, or null when no model exists. */
+    get instance(): Promise<TReadModel | null> {
+        return this.process().then(results => {
+            const materialized = [...results.values()].filter(result => result.instance !== null);
+            if (materialized.length > 1) {
+                throw new Error('Multiple read model instances materialized; use instanceForEventSourceId(id).');
+            }
+            return materialized[0]?.instance ?? null;
+        });
+    }
+
+    /** Returns the model for one source, or null if no handler created it or it was deleted. */
+    async instanceForEventSourceId(id: string): Promise<TReadModel | null> {
+        return (await this.process()).get(id)?.instance ?? null;
+    }
+
+    /** Distinguishes a model removed by a reducer from one never created. */
+    async wasDeletedForEventSourceId(id: string): Promise<boolean> {
+        return (await this.process()).get(id)?.deleted ?? false;
+    }
+
+    /** Collects events for a source; subsequent reads replay the complete seeded history. */
+    collectEventsFor(id: string, events: readonly object[]): void {
+        for (const event of events) {
+            const metadata = getEventTypeMetadata(event.constructor);
+            if (!metadata) throw new Error(`Event '${event.constructor.name}' has no @eventType metadata.`);
+            // The kernel delivers JSON objects, not instances of decorated event classes.
+            const content: unknown = JSON.parse(JsonSerializer.serialize(event));
+            this._events.push({
+                sourceId: id,
+                content,
+                context: {
+                    eventSourceId: id,
+                    eventSourceType: 'Default',
+                    eventStreamType: 'All',
+                    eventStreamId: 'Default',
+                    eventStore: '[NotSet]',
+                    namespace: '[NotSet]',
+                    sequenceNumber: BigInt(this._events.length),
+                    eventType: metadata.eventType,
+                    occurred: new Date(),
+                    correlationId: '00000000-0000-0000-0000-000000000000',
+                    causation: [],
+                    tags: []
+                }
+            });
+        }
+        this._results = undefined;
+    }
+
+    private process(): Promise<Map<string, ReducedState<TReadModel>>> {
+        if (!this._results) {
+            const events = [...this._events];
+            this._results = this.reduce(events);
+        }
+        return this._results;
+    }
+
+    private async reduce(events: readonly SeededEvent[]): Promise<Map<string, ReducedState<TReadModel>>> {
+        const results = new Map<string, ReducedState<TReadModel>>();
+        const reducer = new (this._reducerType as new () => Record<string, Function>)();
+        for (const event of events) {
+            const handler = this._dispatcher.handlerFor(event.context.eventType.id.value);
+            if (!handler) continue;
+            const prior = results.get(event.sourceId);
+            const previous = prior?.deleted ? undefined : prior?.instance;
+            let next: unknown;
+            try {
+                next = await this._dispatcher.invoke(reducer, handler, event.content, previous, event.context);
+            } catch (cause) {
+                throw new Error(`Reducer '${this._reducerType.name}' for read model '${this._readModelType.name}' failed`, { cause });
+            }
+            results.set(event.sourceId, {
+                instance: next === undefined ? null : next as TReadModel | null,
+                deleted: next === undefined
+            });
+        }
+        return results;
+    }
+}

package/testing/ReadModelScenarioGiven.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ReadModelScenario } from './ReadModelScenario.js';
+
+/** Seeds events belonging to one event source, in the order provided. */
+export class ReadModelScenarioGiven<TReadModel extends object> {
+    /** Creates a builder for the selected event source. */
+    constructor(private readonly _scenario: ReadModelScenario<TReadModel>, private readonly _eventSourceId: string) {}
+
+    /** Adds events to the scenario without connecting to a Chronicle kernel. */
+    events(...events: object[]): ReadModelScenario<TReadModel> {
+        this._scenario.collectEventsFor(this._eventSourceId, events);
+        return this._scenario;
+    }
+}

package/testing/ReadModelScenarioGivenBuilder.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ReadModelScenario } from './ReadModelScenario.js';
+import { ReadModelScenarioGiven } from './ReadModelScenarioGiven.js';
+
+/** Selects the event source for events seeded into a read model scenario. */
+export class ReadModelScenarioGivenBuilder<TReadModel extends object> {
+    constructor(private readonly _scenario: ReadModelScenario<TReadModel>) {}
+
+    /** Creates a builder for the selected event source. */
+    forEventSource(id: string): ReadModelScenarioGiven<TReadModel> {
+        return new ReadModelScenarioGiven(this._scenario, id);
+    }
+}

package/testing/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { ReadModelScenario } from './ReadModelScenario.js';
+export { ReadModelScenarioGiven } from './ReadModelScenarioGiven.js';
+export { ReadModelScenarioGivenBuilder } from './ReadModelScenarioGivenBuilder.js';