@cratis/chronicle 6.33.0 → 6.35.0

package/reactors/for_Reactors/when_registering_explicit_handlers.spec.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { ConnectionLifecycle } from '../../connection/ConnectionLifecycle.js';
+import type { IEventLog } from '../../eventSequences/IEventLog.js';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { handles, reactor, Reactors } from '../index.js';
+
+chai.should();
+
+@eventType('registration-handled-event')
+class AuthorRegistered {}
+@eventType('unselected-handled-event')
+class Unregistered {}
+
+@reactor('valid-handlers')
+class Valid { @handles(AuthorRegistered) notify() {} }
+@reactor('missing-handler-event')
+class Missing { @handles(Unregistered) notify() {} }
+@reactor('duplicate-handlers')
+class Duplicate {
+    @handles(AuthorRegistered) notify() {}
+    authorRegistered() {}
+}
+
+for (const [type, message] of [
+    [Missing, /notify.*Missing.*Unregistered.*no registered event type/],
+    [Duplicate, /multiple handlers.*registration-handled-event.*notify.*authorRegistered/]
+] as const) {
+    describe(`when registering a reactor with invalid explicit handlers on ${type.name}`, () => {
+        const observe = vi.fn();
+        let error: unknown;
+        beforeEach(async () => {
+            observe.mockReset();
+            error = undefined;
+            const artifacts = { reactors: [Valid, type], eventTypes: [AuthorRegistered] } as unknown as IClientArtifactsProvider;
+            const connection = { reactors: { observe } } as unknown as ChronicleConnection;
+            const reactors = new Reactors(artifacts, connection, 'store', 'tenant', new ConnectionLifecycle(), {} as IEventLog);
+            try { await reactors.register(); } catch (caught) { error = caught; }
+            finally { reactors.dispose(); }
+        });
+        it('should reject registration with an actionable error', () => {
+            (error instanceof Error).should.be.true;
+            (error as Error).message.should.match(message);
+        });
+        it('should not start any observation before validating all reactors', () => {
+            observe.mock.calls.should.have.lengthOf(0);
+        });
+    });
+}

package/reactors/index.ts

@@ -3,6 +3,7 @@
 
 export { ReactorId } from './ReactorId.js';
 export { reactor, getReactorMetadata, isReactor } from './reactor.js';
+export { handles } from '../events/handles.js';
 export { onceOnly } from './onceOnly.js';
 export { replay } from './replay.js';
 export type { ReactorMetadata } from './reactor.js';

package/reducers/ReducerEventDispatcher.ts

@@ -2,31 +2,20 @@
 // 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 { createHandlerInstanceValidator } from '../observation/createHandlerInstanceValidator.js';
+import { getEventHandlers } from '../observation/getEventHandlers.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[];
+    readonly validateInstance: (instance: object) => void;
 
     /** 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
-                });
-            }
-        }
+        this.handlers = getEventHandlers(reducerType, eventTypes);
+        this.validateInstance = createHandlerInstanceValidator(reducerType, this.handlers.map(handler => handler.methodName));
     }
 
     /** Resolves a registered event type, or returns undefined for an unsubscribed event. */

package/reducers/ReducerEventHandler.ts

@@ -1,9 +1,7 @@
 // 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;
-}
+import type { EventHandler } from '../observation/EventHandler.js';
+
+/** Event type and method selected for a reducer observation. */
+export type ReducerEventHandler = EventHandler;

package/reducers/Reducers.ts

@@ -2,7 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
-import { diag } from '@opentelemetry/api';
+import { createLogger } from '../logging/createLogger.js';
+import { runInBackgroundContext } from '../telemetry/runInBackgroundContext.js';
 import { Constructor } from '@cratis/fundamentals';
 import { ObservationState, ReadModelObserverType, ReducerMessage, ReplayState } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
@@ -102,8 +103,9 @@ export class Reducers implements IReducers {
     /** How long to wait before re-establishing an observation whose stream ended. */
     private static readonly _reobserveDelayMs = 2000;
 
-    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/reducers' });
+    private readonly _logger: ReturnType<typeof createLogger>;
     private readonly _lifecycle: ConnectionLifecycle;
+    private readonly _unsubscribeDisconnected: () => void;
     private readonly _reducers = new Map<string, Constructor>();
     private readonly _queues = new Map<string, AsyncQueue<ReducerMessage>>();
     private readonly _observations = new Map<string, AbortController>();
@@ -133,8 +135,9 @@ export class Reducers implements IReducers {
         private readonly _artifactActivator?: ClientArtifactsActivator,
         private readonly _readModelNamingPolicy?: ReadModelNamingPolicy
     ) {
+        this._logger = createLogger('@cratis/chronicle/reducers', _connection.logger);
         this._lifecycle = lifecycle;
-        lifecycle.onDisconnected(async () => {
+        this._unsubscribeDisconnected = lifecycle.onDisconnected(async () => {
             this._logger.info('Disconnected — stopping all reducer observations');
             this._registered = false;
             this.disconnectAll();
@@ -143,6 +146,7 @@ export class Reducers implements IReducers {
 
     /** Stops observations permanently when the owning client is disposed. */
     dispose(): void {
+        this._unsubscribeDisconnected();
         this._disposed = true;
         this._registered = false;
         this.disconnectAll();
@@ -170,13 +174,16 @@ export class Reducers implements IReducers {
             await this.discover();
         }
 
+        const registrations = [...this._reducers].map(([id, type]) => ({
+            id, type, dispatcher: new ReducerEventDispatcher(type, this._clientArtifacts.eventTypes)
+        }));
         assertUniqueReadModelIds(this._clientArtifacts.readModels);
         await this.registerReadModels();
 
         if (this._disposed) return;
         this._logger.info('Registering reducers', { count: this._reducers.size });
-        for (const [id, reducerType] of this._reducers) {
-            this.startObservation(id, reducerType);
+        for (const { id, type, dispatcher } of registrations) {
+            this.startObservation(id, type, dispatcher);
         }
 
         this._registered = true;
@@ -234,22 +241,24 @@ export class Reducers implements IReducers {
         return JSON.stringify(minimalSchema);
     }
 
-    private startObservation(id: string, reducerType: Constructor): void {
-        if (this._disposed) return;
-        const metadata = getReducerMetadata(reducerType)!;
-        const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
-        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: dispatcher.handlers.length,
-            handlers: dispatcher.handlers.map(e => e.methodName)
-        });
+    private startObservation(id: string, reducerType: Constructor,
+        dispatcher: ReducerEventDispatcher): void {
+        runInBackgroundContext(() => {
+            if (this._disposed) return;
+            const metadata = getReducerMetadata(reducerType)!;
+            const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
+            const readModelName = this.getReducerReadModelIdentifier(reducerType);
 
-        void this.runObservation(id, reducerType, eventSequenceId, readModelName, dispatcher);
+            this._logger.info('Starting reducer observation', {
+                reducerId: id,
+                eventSequenceId,
+                readModel: readModelName,
+                handlerCount: dispatcher.handlers.length,
+                handlers: dispatcher.handlers.map(e => e.methodName)
+            });
+
+            void this.runObservation(id, reducerType, eventSequenceId, readModelName, dispatcher);
+        });
     }
 
     private async runObservation(
@@ -262,10 +271,10 @@ export class Reducers implements IReducers {
         try {
             await this.observeReducer(id, reducerType, eventSequenceId, readModelName, dispatcher);
         } catch (error) {
-            this._logger.error('Reducer observation loop exited with error', { reducerId: id, error: String(error) });
+            this._logger.error('Reducer observation loop exited with error', { reducerId: id, error });
         }
 
-        this.scheduleReobserve(id, reducerType);
+        this.scheduleReobserve(id, reducerType, dispatcher);
     }
 
     /**
@@ -278,21 +287,21 @@ export class Reducers implements IReducers {
      * retried, and the delay keeps a stream that keeps ending from becoming a hot
      * loop.
      */
-    private scheduleReobserve(id: string, reducerType: Constructor): void {
+    private scheduleReobserve(id: string, reducerType: Constructor, dispatcher: ReducerEventDispatcher): void {
         // A disconnect clears the registration; the reconnect re-registers every
         // reducer from scratch, so retrying here as well would double up.
         if (!this._registered || this._disposed) {
             return;
         }
 
-        const handle = setTimeout(() => {
+        const handle = runInBackgroundContext(() => setTimeout(() => {
             if (!this._registered || this._disposed) {
                 return;
             }
 
             this._logger.info('Re-establishing reducer observation', { reducerId: id });
-            this.startObservation(id, reducerType);
-        }, Reducers._reobserveDelayMs);
+            this.startObservation(id, reducerType, dispatcher);
+        }, Reducers._reobserveDelayMs));
 
         handle.unref?.();
     }
@@ -349,6 +358,7 @@ export class Reducers implements IReducers {
 
         try {
             const reducerInstance = this._artifactActivator ? undefined : new (reducerType as new () => Record<string, Function>)();
+            if (reducerInstance) dispatcher.validateInstance(reducerInstance);
 
             for await (const operation of this._connection.reducers.observe(queue, { signal: controller.signal })) {
                 let lastSuccessfullyObservedEvent = SEQUENCE_NUMBER_UNAVAILABLE;
@@ -359,7 +369,6 @@ export class Reducers implements IReducers {
 
                 this._logger.debug('Received reduce operation', {
                     reducerId: id,
-                    partition: operation.Partition,
                     count: operation.Events.length,
                     hasInitialState: operation.InitialState !== '',
                     replayState: operation.ReplayState
@@ -373,14 +382,17 @@ export class Reducers implements IReducers {
                             readModels: this._eventStore.readModels, eventSequenceId, partition: operation.Partition,
                             signal: controller.signal, delivery: ArtifactDelivery.ReplayNotification,
                             replayState: operation.ReplayState
-                        }, this._artifactActivator, artifact => runActivated(artifact, () =>
-                            notifyReplayLifecycle(artifact.instance, operation.ReplayState, operation.Partition),
-                            { delivery: ArtifactDelivery.ReplayNotification, replayState: operation.ReplayState }));
+                        }, this._artifactActivator, artifact => {
+                            dispatcher.validateInstance(artifact.instance);
+                            return runActivated(artifact, () =>
+                                notifyReplayLifecycle(artifact.instance, operation.ReplayState, operation.Partition),
+                                { delivery: ArtifactDelivery.ReplayNotification, replayState: operation.ReplayState });
+                        }, this._connection.logger);
                     } else if (reducerInstance) {
                         await notifyReplayLifecycle(reducerInstance, operation.ReplayState, operation.Partition);
                     }
                 } catch (err) {
-                    this._logger.error('Error notifying reducer of replay lifecycle transition', { reducerId: id, error: String(err) });
+                    this._logger.error('Error notifying reducer of replay lifecycle transition', { reducerId: id, error: err });
                     if (err instanceof ArtifactCompletionFailed && err.processingError !== undefined) {
                         exceptionMessages.push(String(err.processingError));
                     }
@@ -424,7 +436,7 @@ export class Reducers implements IReducers {
                                 { delivery: ArtifactDelivery.Events, eventContext: context, methodName: entry.methodName });
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                         } catch (err) {
-                            this._logger.error('Error handling event in reducer', { reducerId: id, error: String(err) });
+                            this._logger.error('Error handling event in reducer', { reducerId: id, error: err });
                             exceptionMessages.push(String(err));
                             exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
                             state = ObservationState.Failed;
@@ -445,9 +457,12 @@ export class Reducers implements IReducers {
                             readModels: this._eventStore.readModels, eventSequenceId, partition: operation.Partition,
                             signal: controller.signal, delivery: ArtifactDelivery.Events,
                             eventContext: toClientEventContext(firstInvocableEvent.Context!)
-                        }, this._artifactActivator, processEvents);
+                        }, this._artifactActivator, artifact => {
+                            dispatcher.validateInstance(artifact.instance);
+                            return processEvents(artifact);
+                        }, this._connection.logger);
                     } catch (err) {
-                        this._logger.error('Error activating reducer', { reducerId: id, error: String(err) });
+                        this._logger.error('Error activating reducer', { reducerId: id, error: err });
                         exceptionMessages.push(String(err));
                         const completionStack = err instanceof Error ? (err.stack ?? '') : '';
                         exceptionStackTrace = err instanceof ArtifactCompletionFailed && exceptionStackTrace
@@ -483,7 +498,7 @@ export class Reducers implements IReducers {
             if (!this._queues.has(id)) {
                 this._logger.debug('Reducer observation stream closed cleanly', { reducerId: id });
             } else {
-                this._logger.error('Reducer observation stream ended unexpectedly', { reducerId: id, error: String(err) });
+                this._logger.error('Reducer observation stream ended unexpectedly', { reducerId: id, error: err });
             }
         } finally {
             // Only retire our own queue: a reconnect can already have replaced it,

package/reducers/for_ReducerEventDispatcher/when_invoking_an_explicit_handler.spec.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { EventType } from '../../events/EventType.js';
+import type { EventContext } from '../../events/EventContext.js';
+import { handles } from '../index.js';
+import { ReducerEventDispatcher } from '../ReducerEventDispatcher.js';
+
+chai.should();
+
+@eventType('explicit-reducer-delivery')
+class AuthorRegistered { constructor(readonly name: string) {} }
+
+class AuthorReducer {
+    @handles(AuthorRegistered)
+    update(event: AuthorRegistered, state: { names: string[] } | undefined, context: EventContext) {
+        return { names: [...(state?.names ?? []), event.name], id: context.eventSourceId };
+    }
+}
+
+class FieldReducer extends AuthorReducer {
+    override update = () => ({ names: [], id: 'hidden' });
+}
+
+describe('when an instance field hides an inherited reducer handler', () => {
+    it('should reject the field against the preflight method', () => {
+        const dispatcher = new ReducerEventDispatcher(FieldReducer, [AuthorRegistered]);
+        (() => dispatcher.validateInstance(new FieldReducer())).should.throw(
+            "Override 'update' on 'FieldReducer' hides @handles(AuthorRegistered) declared on 'AuthorReducer'; use a method with @handles instead of an instance field.");
+    });
+});
+
+describe('when invoking an explicit reducer handler', () => {
+    let result: unknown;
+    beforeEach(async () => {
+        const dispatcher = new ReducerEventDispatcher(AuthorReducer, [AuthorRegistered]);
+        const instance = new AuthorReducer() as unknown as Record<string, Function>;
+        const context: EventContext = {
+            sequenceNumber: 1n, eventSourceId: 'author', eventType: EventType.parse('explicit-reducer-delivery'),
+            occurred: new Date(), correlationId: '', causation: [], tags: []
+        };
+        const handler = dispatcher.handlerFor('explicit-reducer-delivery')!;
+        const initial = await dispatcher.invoke(instance, handler, new AuthorRegistered('Ada'), undefined, context);
+        result = await dispatcher.invoke(instance, handler, new AuthorRegistered('Grace'), initial, context);
+    });
+    it('should pass the event state and context to the named method', () => {
+        (result as object).should.deep.equal({ names: ['Ada', 'Grace'], id: 'author' });
+    });
+});

package/reducers/for_ReducerEventDispatcher/when_invoking_instance_handlers.spec.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { EventType } from '../../events/EventType.js';
+import type { EventContext } from '../../events/EventContext.js';
+import { handles } from '../index.js';
+import { ReducerEventDispatcher } from '../ReducerEventDispatcher.js';
+
+chai.should();
+
+@eventType('instance-reducer-event')
+class AuthorRegistered { constructor(readonly name: string) {} }
+
+class BoundConventional {
+    readonly prefix = 'conventional';
+    constructor() { this.authorRegistered = this.authorRegistered.bind(this); }
+    authorRegistered(event: AuthorRegistered, state: string[] | undefined, context: EventContext) {
+        return [...(state ?? []), `${this.prefix}:${event.name}:${context.eventSourceId}`];
+    }
+}
+
+class BoundExplicit {
+    readonly prefix = 'explicit';
+    constructor() { this.update = this.update.bind(this); }
+    @handles(AuthorRegistered)
+    update(event: AuthorRegistered, state: string[] | undefined, context: EventContext) {
+        return [...(state ?? []), `${this.prefix}:${event.name}:${context.eventSourceId}`];
+    }
+}
+
+class Conventional {
+    authorRegistered(event: AuthorRegistered, state: string[] | undefined, context: EventContext) {
+        return [...(state ?? []), `base:${event.name}:${context.eventSourceId}`];
+    }
+}
+
+class FieldConventional extends Conventional {
+    override authorRegistered = (event: AuthorRegistered, state: string[] | undefined, context: EventContext) =>
+        [...(state ?? []), `field:${event.name}:${context.eventSourceId}`];
+}
+
+for (const { type, prefix } of [
+    { type: BoundConventional, prefix: 'conventional' },
+    { type: BoundExplicit, prefix: 'explicit' },
+    { type: FieldConventional, prefix: 'field' }
+]) {
+    describe(`when invoking the ${prefix} reducer instance handler`, () => {
+        let result: unknown;
+        beforeEach(async () => {
+            const dispatcher = new ReducerEventDispatcher(type, [AuthorRegistered]);
+            const instance = new type();
+            dispatcher.validateInstance(instance);
+            const context: EventContext = {
+                sequenceNumber: 1n, eventSourceId: 'author', eventType: EventType.parse('instance-reducer-event'),
+                occurred: new Date(), correlationId: '', causation: [], tags: []
+            };
+            const handler = dispatcher.handlerFor('instance-reducer-event')!;
+            const initial = await dispatcher.invoke(instance as unknown as Record<string, Function>, handler,
+                new AuthorRegistered('Ada'), undefined, context);
+            result = await dispatcher.invoke(instance as unknown as Record<string, Function>, handler,
+                new AuthorRegistered('Grace'), initial, context);
+        });
+        it('should invoke the instance handler with the event state and context', () => {
+            (result as string[]).should.deep.equal([`${prefix}:Ada:author`, `${prefix}:Grace:author`]);
+        });
+    });
+}

package/reducers/for_Reducers/when_activating_a_field_override.spec.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventContext, EventType, ObservationState, ReplayState, type ReducerMessage } from '@cratis/chronicle.contracts';
+import { beforeEach, chai, describe, it } from 'vitest';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { ConnectionLifecycle } from '../../connection/ConnectionLifecycle.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { handles, reducer, Reducers } from '../index.js';
+
+chai.should();
+
+@eventType('field-reducer-event')
+class AuthorRegistered {}
+const calls: string[] = [];
+class Base {
+    @handles(AuthorRegistered) update() { calls.push('base'); return {}; }
+    beginReplay() { calls.push('replay'); }
+    endReplay() {}
+}
+@reducer('field-reducer')
+class Derived extends Base {
+    override update = () => { calls.push('field'); return {}; };
+}
+
+for (const replayState of [ReplayState.REPLAY_STATE_None, ReplayState.BeginReplay]) {
+    describe(`when activating a reducer with a field override for replay state ${replayState}`, () => {
+        let result: ReducerMessage;
+        let disposed: boolean;
+        beforeEach(async () => {
+            calls.length = 0;
+            disposed = false;
+            const lifecycle = new ConnectionLifecycle();
+            let finish!: () => void;
+            const finished = new Promise<void>(resolve => { finish = resolve; });
+            async function* stream(queue: AsyncIterable<ReducerMessage>) {
+                const messages = queue[Symbol.asyncIterator]();
+                await messages.next();
+                yield { Events: [{ Content: '{}', Context: EventContext.fromPartial({
+                    EventType: EventType.fromPartial({ Id: 'field-reducer-event', Generation: 1 }), SequenceNumber: 1n
+                }) }], Partition: 'author', ReplayState: replayState, InitialState: '' };
+                result = (await messages.next()).value!;
+                await lifecycle.disconnected(error => { throw error; });
+                finish();
+            }
+            const reducers = new Reducers({ reducers: [Derived], eventTypes: [AuthorRegistered], readModels: [] } as unknown as IClientArtifactsProvider,
+                { reducers: { observe: stream }, readModels: { registerMany: async () => ({}) } } as unknown as ChronicleConnection,
+                'store', 'tenant', lifecycle, 'sink', { readModels: {} } as IEventStore,
+                type => ({ instance: new type(), dispose: () => { disposed = true; } }));
+            try { await reducers.register(); await finished; } finally { reducers.dispose(); }
+        });
+        it('should fail delivery without invoking the field or replay notification', () => {
+            calls.should.have.lengthOf(0);
+            result.Content!.Value1!.State.should.equal(ObservationState.Failed);
+            result.Content!.Value1!.ReadModelState.should.equal('');
+            result.Content!.Value1!.ExceptionMessages.join(' ').should.contain(
+                "Override 'update' on 'Derived' hides @handles(AuthorRegistered) declared on 'Base'; use a method with @handles instead of an instance field.");
+        });
+        it('should release the rejected activation lease', () => { disposed.should.be.true; });
+    });
+}

package/reducers/for_Reducers/when_observing_explicit_handlers.legacy.spec.ts

@@ -0,0 +1,73 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventContext, EventType, ObservationState, type ReducerMessage } from '@cratis/chronicle.contracts';
+import { beforeEach, chai, describe, it } from 'vitest';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { ConnectionLifecycle } from '../../connection/ConnectionLifecycle.js';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import type { EventContext as ClientEventContext } from '../../events/EventContext.js';
+import { handles, reducer, Reducers } from '../index.js';
+
+chai.should();
+
+@eventType('legacy-reduced-handler')
+class AuthorRegistered { constructor(readonly name = '') {} }
+
+@reducer('legacy-reduction')
+class AuthorReducer {
+    @handles(AuthorRegistered)
+    update(event: AuthorRegistered, state: { names: string[] } | undefined, context: ClientEventContext) {
+        return { names: [...(state?.names ?? []), event.name], id: context.eventSourceId };
+    }
+}
+
+describe('when observing explicit legacy reducer handlers', () => {
+    let registration: ReducerMessage;
+    let result: ReducerMessage;
+    beforeEach(async () => {
+        const lifecycle = new ConnectionLifecycle();
+        let finish!: () => void;
+        const finished = new Promise<void>(resolve => { finish = resolve; });
+        async function* stream(queue: AsyncIterable<ReducerMessage>) {
+            const messages = queue[Symbol.asyncIterator]();
+            registration = (await messages.next()).value!;
+            yield {
+                Events: ['Ada', 'Grace'].map((name, index) => ({
+                    Context: EventContext.fromPartial({
+                        EventType: EventType.fromPartial({ Id: 'legacy-reduced-handler', Generation: 1 }),
+                        EventSourceId: 'author', SequenceNumber: BigInt(index + 1)
+                    }),
+                    Content: JSON.stringify({ name })
+                })),
+                Partition: 'author', ReplayState: 0, InitialState: ''
+            };
+            result = (await messages.next()).value!;
+            await lifecycle.disconnected(error => { throw error; });
+            finish();
+        }
+        const connection = {
+            reducers: { observe: stream }, readModels: { registerMany: async () => ({}) }
+        } as unknown as ChronicleConnection;
+        const artifacts = {
+            reducers: [AuthorReducer], eventTypes: [AuthorRegistered], readModels: []
+        } as unknown as IClientArtifactsProvider;
+        const reducers = new Reducers(artifacts, connection, 'store', 'tenant', lifecycle, 'sink');
+        try {
+            await reducers.register();
+            await finished;
+        } finally { reducers.dispose(); }
+    });
+    it('should subscribe to the explicitly named event type', () => {
+        registration.Content!.Value0!.Reducer!.EventTypes.map(entry => entry.EventType!.Id)
+            .should.deep.equal(['legacy-reduced-handler']);
+    });
+    it('should pass the event state and context through the named method', () => {
+        JSON.parse(result.Content!.Value1!.ReadModelState).should.deep.equal({ names: ['Ada', 'Grace'], id: 'author' });
+    });
+    it('should acknowledge both deliveries successfully', () => {
+        result.Content!.Value1!.State.should.equal(ObservationState.Success);
+        result.Content!.Value1!.LastSuccessfulObservation.should.equal(2n);
+    });
+});

package/reducers/for_Reducers/when_registering_explicit_handlers.spec.ts

@@ -0,0 +1,57 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { ConnectionLifecycle } from '../../connection/ConnectionLifecycle.js';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { handles, reducer, Reducers } from '../index.js';
+
+chai.should();
+
+@eventType('reducer-handled-event')
+class AuthorRegistered {}
+@eventType('unselected-reducer-event')
+class Unregistered {}
+
+@reducer('valid-handlers')
+class Valid { @handles(AuthorRegistered) update() {} }
+@reducer('missing-handler-event')
+class Missing { @handles(Unregistered) update() {} }
+@reducer('duplicate-handlers')
+class Duplicate {
+    @handles(AuthorRegistered) update() {}
+    authorRegistered() {}
+}
+
+for (const [type, message] of [
+    [Missing, /update.*Missing.*Unregistered.*no registered event type/],
+    [Duplicate, /multiple handlers.*reducer-handled-event.*update.*authorRegistered/]
+] as const) {
+    describe(`when registering a reducer with invalid explicit handlers on ${type.name}`, () => {
+        const observe = vi.fn();
+        const registerMany = vi.fn();
+        let error: unknown;
+        beforeEach(async () => {
+            observe.mockReset();
+            registerMany.mockReset();
+            error = undefined;
+            const artifacts = { reducers: [Valid, type], eventTypes: [AuthorRegistered], readModels: [] } as unknown as IClientArtifactsProvider;
+            const connection = { reducers: { observe }, readModels: { registerMany } } as unknown as ChronicleConnection;
+            const reducers = new Reducers(artifacts, connection, 'store', 'tenant', new ConnectionLifecycle(), 'sink');
+            try { await reducers.register(); } catch (caught) { error = caught; }
+            finally { reducers.dispose(); }
+        });
+        it('should reject registration with an actionable error', () => {
+            (error instanceof Error).should.be.true;
+            (error as Error).message.should.match(message);
+        });
+        it('should not register read models before validating all handlers', () => {
+            registerMany.mock.calls.should.have.lengthOf(0);
+        });
+        it('should not start an observation before validating all reducers', () => {
+            observe.mock.calls.should.have.lengthOf(0);
+        });
+    });
+}

package/reducers/index.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+export { handles } from '../events/handles.js';
 export { ReducerId } from './ReducerId.js';
 export { reducer, getReducerMetadata, isReducer } from './reducer.js';
 export type { ReducerMetadata } from './reducer.js';