@cratis/chronicle 6.34.0 → 6.36.0

package/observation/createHandlerInstanceValidator.ts

@@ -0,0 +1,42 @@
+// 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 { getHandledEventType } from '../events/handles.js';
+import { getInstanceMethods } from './getInstanceMethods.js';
+
+/** Captures @handles prototype methods during preflight and rejects instance properties hiding them, except bound methods. */
+export function createHandlerInstanceValidator(type: Constructor, names: Iterable<string>, methods = getInstanceMethods(type)):
+    (instance: object) => void {
+    const handlers = [...new Set(names)].filter(name => getHandledEventType(methods.get(name)!) !== undefined).map(name => {
+        const method = methods.get(name)!;
+        let declaring = type.prototype;
+        while (declaring && Object.getOwnPropertyDescriptor(declaring, name)?.value !== method) {
+            declaring = Object.getPrototypeOf(declaring);
+        }
+        const eventType = getHandledEventType(method)!;
+        const declaration = `@handles(${(eventType as Function).name})`;
+        return { name, method, declaration, declaringType: declaring?.constructor.name ?? type.name };
+    });
+    return instance => {
+        for (const { name, method, declaration, declaringType } of handlers) {
+            let current: object | null = instance;
+            while (current && !Object.hasOwn(current, name)) current = Object.getPrototypeOf(current) as object | null;
+            const value: unknown = current ? Object.getOwnPropertyDescriptor(current, name)?.value : undefined;
+            if (current === instance && typeof value === 'function' && isBoundCopyOf(value, method)) continue;
+            if (current === instance || !current || value !== method) {
+                throw new Error(`Override '${name}' on '${type.name}' hides ${declaration} declared on '${declaringType}'; use a method with @handles instead of an instance field.`);
+            }
+        }
+    };
+}
+
+/**
+ * Checks whether a function is a (possibly repeatedly) Function.prototype.bind copy of a method.
+ * @param value - The function found on the instance.
+ * @param method - The declared method.
+ * @returns True when the function name is one or more `bound ` prefixes followed by the method name.
+ */
+function isBoundCopyOf(value: Function, method: Function): boolean {
+    return value.name.startsWith('bound ') && value.name.replace(/^(bound )+/, '') === method.name;
+}

package/observation/for_getEventHandlers/when_discovering_handlers.spec.ts

@@ -0,0 +1,137 @@
+// 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 { handles } from '../../events/handles.js';
+import { getReactorEventTypes } from '../../reactors/ReactorDispatcher.js';
+import { ReducerEventDispatcher } from '../../reducers/ReducerEventDispatcher.js';
+
+chai.should();
+
+@eventType('explicit-author', 2)
+class AuthorRegistered {}
+@eventType('conventional-book')
+class BookBorrowed {}
+
+const registeredTypes = [AuthorRegistered, BookBorrowed];
+const discoverers = [
+    { name: 'reactor', discover: getReactorEventTypes },
+    { name: 'reducer', discover: (type: new () => object, types: readonly (new () => object)[]) => new ReducerEventDispatcher(type, types).handlers }
+];
+
+for (const { name, discover } of discoverers) {
+    describe(`when discovering explicit and conventional ${name} handlers`, () => {
+        class Observer {
+            @handles(AuthorRegistered)
+            notify() {}
+            bookBorrowed() {}
+            helper() {}
+            get unrelated() { throw new Error('A getter must not run during discovery'); }
+        }
+        let entries: ReturnType<typeof getReactorEventTypes>;
+        beforeEach(() => { entries = discover(Observer, registeredTypes); });
+        it('should include both event types without treating helpers as handlers', () => {
+            entries.should.deep.equal([
+                { id: 'explicit-author', generation: 2, methodName: 'notify' },
+                { id: 'conventional-book', generation: 1, methodName: 'bookBorrowed' }
+            ]);
+        });
+    });
+
+    describe(`when an explicit ${name} method has another event's conventional name`, () => {
+        class Observer { @handles(AuthorRegistered) bookBorrowed() {} }
+        it('should use only the explicit event type', () => {
+            discover(Observer, registeredTypes).should.deep.equal([{ id: 'explicit-author', generation: 2, methodName: 'bookBorrowed' }]);
+        });
+    });
+
+    describe(`when an explicit ${name} method has its own conventional name`, () => {
+        class Observer { @handles(AuthorRegistered) authorRegistered() {} }
+        it('should register it only once', () => {
+            discover(Observer, registeredTypes).should.have.lengthOf(1);
+        });
+    });
+
+    describe(`when inheriting an explicit ${name} handler`, () => {
+        class Base { @handles(AuthorRegistered) notify() {} }
+        class Inherited extends Base {}
+        class Overridden extends Base { notify() {} }
+        class Remapped extends Base { @handles(BookBorrowed) notify() {} }
+        it('should discover the inherited handler', () => {
+            discover(Inherited, registeredTypes)[0].methodName!.should.equal('notify');
+        });
+        it('should reject an override that hides the base declaration', () => {
+            (() => discover(Overridden, registeredTypes)).should.throw(
+                "Override 'notify' on 'Overridden' hides @handles(AuthorRegistered) declared on 'Base'; redecorate the override.");
+        });
+        it('should reject an inherited undecorated override across multiple levels', () => {
+            class Derived extends Overridden {}
+            (() => discover(Derived, registeredTypes)).should.throw(
+                "Override 'notify' on 'Overridden' hides @handles(AuthorRegistered) declared on 'Base'; redecorate the override.");
+        });
+        it('should allow an override explicitly keeping the same event type', () => {
+            class Reaffirmed extends Base { @handles(AuthorRegistered) notify() {} }
+            discover(Reaffirmed, registeredTypes).should.deep.equal([{ id: 'explicit-author', generation: 2, methodName: 'notify' }]);
+        });
+        it('should use the override event type instead of the base declaration', () => {
+            discover(Remapped, registeredTypes).should.deep.equal([{ id: 'conventional-book', generation: 1, methodName: 'notify' }]);
+        });
+    });
+
+    describe(`when explicit ${name} event classes share a name`, () => {
+        const OtherAuthorRegistered = class AuthorRegistered {};
+        eventType('another-author')(OtherAuthorRegistered);
+        class Observer {
+            @handles(AuthorRegistered) notify() {}
+            @handles(OtherAuthorRegistered) archive() {}
+        }
+        it('should resolve event constructors rather than class names', () => {
+            discover(Observer, [AuthorRegistered, OtherAuthorRegistered]).map(entry => entry.id)
+                .should.deep.equal(['explicit-author', 'another-author']);
+        });
+    });
+
+    describe(`when an explicit ${name} event type is not registered`, () => {
+        class Observer { @handles(AuthorRegistered) notify() {} }
+        it('should name the observer method and missing event constructor', () => {
+            (() => discover(Observer, [BookBorrowed])).should.throw(/notify.*Observer.*AuthorRegistered.*no registered event type/);
+        });
+        it('should not accept a different constructor with the same event id', () => {
+            @eventType('explicit-author', 2)
+            class OtherAuthor {}
+            (() => discover(Observer, [OtherAuthor])).should.throw(/notify.*no registered event type/);
+        });
+        it('should not accept a listed class without event metadata', () => {
+            class Unknown {}
+            class Invalid { @handles(Unknown) notify() {} }
+            (() => discover(Invalid, [Unknown])).should.throw(/notify.*Unknown.*no registered event type/);
+        });
+    });
+
+    describe(`when two ${name} methods handle one event type`, () => {
+        class Explicit {
+            @handles(AuthorRegistered) notify() {}
+            @handles(AuthorRegistered) archive() {}
+        }
+        class Mixed {
+            @handles(AuthorRegistered) notify() {}
+            authorRegistered() {}
+        }
+        class Base { @handles(AuthorRegistered) notify() {} }
+        class Inherited extends Base { @handles(AuthorRegistered) archive() {} }
+        class Conventional extends Base { authorRegistered() {} }
+        it('should reject two explicit handlers', () => {
+            (() => discover(Explicit, registeredTypes)).should.throw(/multiple handlers.*explicit-author.*notify.*archive/);
+        });
+        it('should reject an explicit handler and a conventional handler', () => {
+            (() => discover(Mixed, registeredTypes)).should.throw(/multiple handlers.*explicit-author.*notify.*authorRegistered/);
+        });
+        it('should include inherited methods in duplicate detection', () => {
+            (() => discover(Inherited, registeredTypes)).should.throw(/multiple handlers.*explicit-author.*archive.*notify/);
+        });
+        it('should reject a conventional handler duplicating an inherited explicit handler', () => {
+            (() => discover(Conventional, registeredTypes)).should.throw(/multiple handlers.*explicit-author.*notify.*authorRegistered/);
+        });
+    });
+}

package/observation/for_getEventHandlers/when_reobserving_explicit_handlers.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 type { ReactorMessage, ReducerMessage } from '@cratis/chronicle.contracts';
+import { afterEach, 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 } from '../../events/handles.js';
+import { onceOnly, reactor, Reactors } from '../../reactors/index.js';
+import { reducer, Reducers } from '../../reducers/index.js';
+
+chai.should();
+
+@eventType('reobserved-event')
+class AuthorRegistered {}
+
+@onceOnly()
+@reactor('reobserved-reactor')
+class AuthorReactor { @handles(AuthorRegistered) notify() {} }
+
+@reducer('reobserved-reducer')
+class AuthorReducer { @handles(AuthorRegistered) update() {} }
+
+for (const kind of ['reactor', 'reducer'] as const) {
+    describe(`when reobserving an explicit ${kind} handler`, () => {
+        const registrations: (ReactorMessage | ReducerMessage)[] = [];
+        let observations: Reactors | Reducers;
+        beforeEach(async () => {
+            vi.useFakeTimers();
+            registrations.length = 0;
+            const lifecycle = new ConnectionLifecycle();
+            async function* stream(queue: AsyncIterable<ReactorMessage | ReducerMessage>) {
+                registrations.push((await queue[Symbol.asyncIterator]().next()).value!);
+                yield { Events: [], Partition: 'author', ReplayState: 0, InitialState: '' };
+            }
+            const connection = {
+                reactors: { observe: stream }, reducers: { observe: stream },
+                readModels: { registerMany: async () => ({}) }
+            } as unknown as ChronicleConnection;
+            const artifacts = {
+                reactors: [AuthorReactor], reducers: [AuthorReducer], eventTypes: [AuthorRegistered], readModels: []
+            } as unknown as IClientArtifactsProvider;
+            observations = kind === 'reactor'
+                ? new Reactors(artifacts, connection, 'store', 'tenant', lifecycle, {} as IEventLog)
+                : new Reducers(artifacts, connection, 'store', 'tenant', lifecycle, 'sink');
+            await observations.register();
+            await vi.advanceTimersByTimeAsync(0);
+            // Changing the catalog must not invalidate an already validated observation on its timer callback.
+            artifacts.eventTypes.splice(0);
+            await vi.advanceTimersByTimeAsync(2000);
+        });
+        afterEach(() => {
+            observations.dispose();
+            vi.clearAllTimers();
+            vi.useRealTimers();
+        });
+        it('should reuse the registered handler mapping when the stream ends', () => {
+            registrations.should.have.lengthOf(2);
+            registrations[1].should.deep.equal(registrations[0]);
+            const registration = registrations[1].Content!.Value0!;
+            const observer = 'Reactor' in registration ? registration.Reactor : registration.Reducer;
+            observer!.EventTypes.map(entry => entry.EventType!.Id).should.deep.equal(['reobserved-event']);
+        });
+        if (kind === 'reactor') {
+            it('should register a class-level onceOnly reactor with an explicit handler as non-replayable', () => {
+                (registrations[0] as ReactorMessage).Content!.Value0!.Reactor!.IsReplayable.should.be.false;
+            });
+        }
+    });
+}

package/observation/getEventHandlers.ts

@@ -0,0 +1,43 @@
+// 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 { getHandledEventType } from '../events/handles.js';
+import type { EventHandler } from './EventHandler.js';
+import { getInstanceMethods } from './getInstanceMethods.js';
+
+/** Resolves explicit event constructors first, with camelCase discovery for undecorated methods. */
+export function getEventHandlers(type: Constructor, registeredTypes: readonly Constructor[], methods = getInstanceMethods(type)): EventHandler[] {
+    const eventTypes = new Map(registeredTypes.flatMap(eventType => {
+        const metadata = getEventTypeMetadata(eventType);
+        return metadata ? [[eventType, metadata.eventType] as const] : [];
+    }));
+    const handlers = new Map<string, EventHandler>();
+    const addHandler = (eventType: Constructor, methodName: string) => {
+        const metadata = eventTypes.get(eventType)!;
+        const id = metadata.id.value;
+        const previous = handlers.get(id);
+        if (previous && previous.methodName !== methodName) {
+            throw new Error(`'${(type as Function).name}' has multiple handlers for event type '${id}': '${previous.methodName}' and '${methodName}'.`);
+        }
+        handlers.set(id, { id, generation: metadata.generation.value, methodName });
+    };
+
+    for (const [name, method] of methods) {
+        const eventType = getHandledEventType(method);
+        if (eventType === undefined) continue;
+        if (!eventTypes.has(eventType)) {
+            throw new Error(`Handler '${name}' on '${(type as Function).name}' names event type '${(eventType as Function).name}', which has no registered event type. Register that event constructor with the event store.`);
+        }
+        addHandler(eventType, name);
+    }
+
+    for (const eventType of eventTypes.keys()) {
+        const className = (eventType as Function).name;
+        const name = className.charAt(0).toLowerCase() + className.slice(1);
+        const method = methods.get(name);
+        if (method && getHandledEventType(method) === undefined) addHandler(eventType, name);
+    }
+    return [...handlers.values()];
+}

package/observation/getInstanceMethods.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 type { Constructor } from '@cratis/fundamentals';
+import { getHandledEventType } from '../events/handles.js';
+
+/** Finds prototype methods without invoking getters; explicit handlers require explicitly decorated overrides. */
+export function getInstanceMethods(type: Constructor): Map<string, Function> {
+    const methods = new Map<string, Function>();
+    const declaringTypes = new Map<string, string>();
+    for (let current = type.prototype; current && current !== Object.prototype; current = Object.getPrototypeOf(current)) {
+        for (const name of Object.getOwnPropertyNames(current)) {
+            if (name === 'constructor') continue;
+            const method = Object.getOwnPropertyDescriptor(current, name)?.value;
+            const declaringType = declaringTypes.get(name);
+            if (declaringType !== undefined) {
+                const eventType = typeof method === 'function' ? getHandledEventType(method) : undefined;
+                const override = methods.get(name);
+                if (eventType && (!override || getHandledEventType(override) === undefined)) {
+                    throw new Error(`Override '${name}' on '${declaringType}' hides @handles(${(eventType as Function).name}) declared on '${current.constructor.name}'; redecorate the override.`);
+                }
+                continue;
+            }
+            declaringTypes.set(name, current.constructor.name);
+            if (typeof method === 'function') methods.set(name, method);
+        }
+    }
+    return methods;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.34.0",
+    "version": "6.36.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -168,7 +168,7 @@
         "clean": "rm -rf dist",
         "test": "vitest run",
         "test:integration": "vitest run --config vitest.integration.config.ts",
-        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts",
+        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {

package/reactors/ReactorDispatcher.ts

@@ -8,6 +8,9 @@ import { ArtifactDelivery } from '../artifacts/ArtifactDelivery.js';
 import { runActivated } from '../artifacts/withActivatedArtifact.js';
 import type { EventContext } from '../events/EventContext.js';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { getHandledEventType } from '../events/handles.js';
+import { getEventHandlers } from '../observation/getEventHandlers.js';
+import { getInstanceMethods } from '../observation/getInstanceMethods.js';
 import { isOnceOnly } from './onceOnly.js';
 import { getReplayEventType } from './replay.js';
 import type { ReactorServices } from './ReactorServices.js';
@@ -21,8 +24,7 @@ export interface ReactorEventTypeEntry {
 }
 
 export function getReactorEventTypes(reactorType: Constructor, registeredTypes: readonly Constructor[]): ReactorEventTypeEntry[] {
-    const proto = reactorType.prototype as Record<string, unknown>;
-    const entries: ReactorEventTypeEntry[] = [];
+    const methods = getInstanceMethods(reactorType);
     const replayHandlers = new Map<string, string>();
     const eventTypes = new Map<string, { eventTypeClass: Function; id: string; generation: number }>();
 
@@ -37,40 +39,34 @@ export function getReactorEventTypes(reactorType: Constructor, registeredTypes:
         }
     }
 
-    // A derived method shadows a base method of the same name, even if it is not marked for replay.
-    const seenMethods = new Set<string>();
-    for (let current = proto; current && current !== Object.prototype; current = Object.getPrototypeOf(current) as Record<string, unknown>) {
-        for (const name of Object.getOwnPropertyNames(current)) {
-            if (seenMethods.has(name)) continue;
-            seenMethods.add(name);
-            const method = current[name];
-            if (typeof method !== 'function') continue;
-            const replayEventType = getReplayEventType(method);
-            if (replayEventType === undefined) continue;
-
-            const eventType = replayEventType === true
-                ? eventTypes.get(name.startsWith('replay') ? name.slice('replay'.length) : '')
-                : [...eventTypes.values()].find(candidate => candidate.eventTypeClass === replayEventType);
-            if (!eventType) {
-                throw new Error(`Replay handler '${name}' on reactor '${(reactorType as Function).name}' has no registered event type.`);
-            }
-            if (replayHandlers.has(eventType.id)) {
-                throw new Error(`Reactor '${(reactorType as Function).name}' has multiple replay handlers for event type '${eventType.id}': '${replayHandlers.get(eventType.id)}' and '${name}'.`);
-            }
-            replayHandlers.set(eventType.id, name);
+    for (const [name, method] of methods) {
+        const replayEventType = getReplayEventType(method);
+        if (replayEventType === undefined) continue;
+        if (getHandledEventType(method) !== undefined) {
+            throw new Error(`Handler '${name}' on reactor '${(reactorType as Function).name}' cannot combine @handles and @replay. Use separate live and replay methods.`);
+        }
+        const eventType = replayEventType === true
+            ? eventTypes.get(name.startsWith('replay') ? name.slice('replay'.length) : '')
+            : [...eventTypes.values()].find(candidate => candidate.eventTypeClass === replayEventType);
+        if (!eventType) {
+            throw new Error(`Replay handler '${name}' on reactor '${(reactorType as Function).name}' has no registered event type.`);
+        }
+        if (replayHandlers.has(eventType.id)) {
+            throw new Error(`Reactor '${(reactorType as Function).name}' has multiple replay handlers for event type '${eventType.id}': '${replayHandlers.get(eventType.id)}' and '${name}'.`);
         }
+        replayHandlers.set(eventType.id, name);
+        methods.delete(name);
     }
 
-    for (const [className, eventType] of eventTypes) {
-        const methodName = className.charAt(0).toLowerCase() + className.slice(1);
-        const liveMethod = proto[methodName];
-        const liveMethodName = typeof liveMethod === 'function' && getReplayEventType(liveMethod) === undefined ? methodName : undefined;
+    const entries = new Map<string, ReactorEventTypeEntry>(getEventHandlers(reactorType, registeredTypes, methods)
+        .map(handler => [handler.id, handler]));
+    for (const eventType of eventTypes.values()) {
         const replayMethodName = replayHandlers.get(eventType.id);
-        if (liveMethodName || replayMethodName) {
-            entries.push({ id: eventType.id, generation: eventType.generation, methodName: liveMethodName, replayMethodName });
+        if (replayMethodName) {
+            entries.set(eventType.id, { id: eventType.id, generation: eventType.generation, ...entries.get(eventType.id), replayMethodName });
         }
     }
-    return entries;
+    return [...entries.values()];
 }
 
 export function selectReactorHandler(entries: readonly ReactorEventTypeEntry[], reactorType: Constructor,

package/reactors/Reactors.ts

@@ -14,6 +14,7 @@ import { getTagsFor } from '../events/tagDecorator.js';
 import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
 import type { IEventLog } from '../eventSequences/IEventLog.js';
+import { createHandlerInstanceValidator } from '../observation/createHandlerInstanceValidator.js';
 import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle.js';
 import { IReactors } from './IReactors.js';
 import { dispatchReactorSideEffects } from './ReactorSideEffects.js';
@@ -105,6 +106,7 @@ export class Reactors implements IReactors {
 
     private readonly _logger: ReturnType<typeof createLogger>;
     private readonly _lifecycle: ConnectionLifecycle;
+    private readonly _unsubscribeDisconnected: () => void;
     private readonly _reactors = new Map<string, Constructor>();
     private readonly _queues = new Map<string, AsyncQueue<ReactorMessage>>();
     private readonly _observations = new Map<string, AbortController>();
@@ -133,7 +135,7 @@ export class Reactors implements IReactors {
     ) {
         this._logger = createLogger('@cratis/chronicle/reactors', _connection.logger);
         this._lifecycle = lifecycle;
-        lifecycle.onDisconnected(async () => {
+        this._unsubscribeDisconnected = lifecycle.onDisconnected(async () => {
             this._logger.info('Disconnected — stopping all reactor observations');
             this._registered = false;
             this.disconnectAll();
@@ -142,6 +144,7 @@ export class Reactors implements IReactors {
 
     /** Stops observations permanently when the owning client is disposed. */
     dispose(): void {
+        this._unsubscribeDisconnected();
         this._disposed = true;
         this._registered = false;
         this.disconnectAll();
@@ -170,20 +173,24 @@ export class Reactors implements IReactors {
         }
 
         if (this._disposed) return;
+        const registrations = [...this._reactors].map(([id, type]) => ({
+            id, type, eventTypes: getReactorEventTypes(type, this._clientArtifacts.eventTypes)
+        })).map(registration => ({ ...registration, validateInstance: createHandlerInstanceValidator(registration.type,
+            registration.eventTypes.flatMap(entry => [entry.methodName, entry.replayMethodName].filter((name): name is string => !!name))) }));
         this._logger.info('Registering reactors', { count: this._reactors.size });
-        for (const [id, reactorType] of this._reactors) {
-            this.startObservation(id, reactorType);
+        for (const { id, type, eventTypes, validateInstance } of registrations) {
+            this.startObservation(id, type, eventTypes, validateInstance);
         }
 
         this._registered = true;
     }
 
-    private startObservation(id: string, reactorType: Constructor): void {
+    private startObservation(id: string, reactorType: Constructor,
+        eventTypes: ReactorEventTypeEntry[], validateInstance: (instance: object) => void): void {
         runInBackgroundContext(() => {
             if (this._disposed) return;
             const metadata = getReactorMetadata(reactorType)!;
             const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
-            const eventTypes = getReactorEventTypes(reactorType, this._clientArtifacts.eventTypes);
 
             this._logger.info('Starting reactor observation', {
                 reactorId: id,
@@ -192,7 +199,7 @@ export class Reactors implements IReactors {
                 handlers: eventTypes.map(e => e.methodName)
             });
 
-            void this.runObservation(id, reactorType, eventSequenceId, eventTypes);
+            void this.runObservation(id, reactorType, eventSequenceId, eventTypes, validateInstance);
         });
     }
 
@@ -200,15 +207,16 @@ export class Reactors implements IReactors {
         id: string,
         reactorType: Constructor,
         eventSequenceId: string,
-        eventTypes: ReactorEventTypeEntry[]
+        eventTypes: ReactorEventTypeEntry[],
+        validateInstance: (instance: object) => void
     ): Promise<void> {
         try {
-            await this.observeReactor(id, reactorType, eventSequenceId, eventTypes);
+            await this.observeReactor(id, reactorType, eventSequenceId, eventTypes, validateInstance);
         } catch (error) {
             this._logger.error('Reactor observation loop exited with error', { reactorId: id, error });
         }
 
-        this.scheduleReobserve(id, reactorType);
+        this.scheduleReobserve(id, reactorType, eventTypes, validateInstance);
     }
 
     /**
@@ -220,7 +228,7 @@ export class Reactors implements IReactors {
      * the whole client reconnects. Both endings are therefore retried, and the delay
      * keeps a stream that keeps ending from becoming a hot loop.
      */
-    private scheduleReobserve(id: string, reactorType: Constructor): void {
+    private scheduleReobserve(id: string, reactorType: Constructor, eventTypes: ReactorEventTypeEntry[], validateInstance: (instance: object) => void): void {
         // A disconnect clears the registration; the reconnect re-registers every
         // reactor from scratch, so retrying here as well would double up.
         if (!this._registered || this._disposed) {
@@ -233,7 +241,7 @@ export class Reactors implements IReactors {
             }
 
             this._logger.info('Re-establishing reactor observation', { reactorId: id });
-            this.startObservation(id, reactorType);
+            this.startObservation(id, reactorType, eventTypes, validateInstance);
         }, Reactors._reobserveDelayMs));
 
         handle.unref?.();
@@ -243,7 +251,8 @@ export class Reactors implements IReactors {
         id: string,
         reactorType: Constructor,
         eventSequenceId: string,
-        eventTypes: ReactorEventTypeEntry[]
+        eventTypes: ReactorEventTypeEntry[],
+        validateInstance: (instance: object) => void
     ): Promise<void> {
         const queue = new AsyncQueue<ReactorMessage>();
         const controller = new AbortController();
@@ -278,6 +287,7 @@ export class Reactors implements IReactors {
 
         try {
             const reactorInstance = this._artifactActivator ? undefined : new (reactorType as new () => Record<string, Function>)();
+            if (reactorInstance) validateInstance(reactorInstance);
             const services: ReactorServices | undefined = this._eventStore && {
                 eventStore: this._eventStore, readModels: this._eventStore.readModels, signal: controller.signal
             };
@@ -302,9 +312,12 @@ export class Reactors implements IReactors {
                             readModels: services.readModels, eventSequenceId, partition: eventsToObserve.Partition,
                             signal: controller.signal, delivery: ArtifactDelivery.ReplayNotification,
                             replayState: eventsToObserve.ReplayState
-                        }, this._artifactActivator, artifact => runActivated(artifact, () =>
-                            notifyReplayLifecycle(artifact.instance, eventsToObserve.ReplayState, eventsToObserve.Partition),
-                            { delivery: ArtifactDelivery.ReplayNotification, replayState: eventsToObserve.ReplayState }), this._connection.logger);
+                        }, this._artifactActivator, artifact => {
+                            validateInstance(artifact.instance);
+                            return runActivated(artifact, () =>
+                                notifyReplayLifecycle(artifact.instance, eventsToObserve.ReplayState, eventsToObserve.Partition),
+                                { delivery: ArtifactDelivery.ReplayNotification, replayState: eventsToObserve.ReplayState });
+                        }, this._connection.logger);
                     } else if (reactorInstance) {
                         await notifyReplayLifecycle(reactorInstance, eventsToObserve.ReplayState, eventsToObserve.Partition);
                     }
@@ -388,7 +401,10 @@ export class Reactors implements IReactors {
                             readModels: services.readModels, eventSequenceId, partition: eventsToObserve.Partition,
                             signal: controller.signal, delivery: ArtifactDelivery.Events,
                             eventContext: toClientEventContext(firstInvocableEvent.Context!)
-                        }, this._artifactActivator, processEvents, this._connection.logger);
+                        }, this._artifactActivator, artifact => {
+                            validateInstance(artifact.instance);
+                            return processEvents(artifact);
+                        }, this._connection.logger);
                     } catch (err) {
                         this._logger.error('Error activating reactor', { reactorId: id, error: err });
                         exceptionMessages.push(String(err));

package/reactors/decorators.standard.spec.ts

@@ -4,11 +4,17 @@
 import { describe, expect, it } from 'vitest';
 import { onceOnly, isOnceOnly } from './onceOnly.js';
 import { replay, getReplayEventType } from './replay.js';
+import { handles } from '../index.js';
+import { getHandledEventType } from '../events/handles.js';
 
 class EventForReplay {}
 
 @onceOnly()
 class StandardReactor {
+    @handles(EventForReplay)
+    @onceOnly()
+    notify() {}
+
     @onceOnly()
     eventForReplay() {}
 
@@ -31,6 +37,8 @@ describe('standard reactor policy decorators', () => {
     });
 
     it('marks methods without modifying the class or other methods', () => {
+        expect(getHandledEventType(StandardReactor.prototype.notify)).toBe(EventForReplay);
+        expect(isOnceOnly(StandardReactor.prototype.notify)).toBe(true);
         expect(isOnceOnly(StandardReactor.prototype.eventForReplay)).toBe(true);
         expect(isOnceOnly(StandardReactor.prototype.replayEventForReplay)).toBe(false);
         expect(getReplayEventType(StandardReactor.prototype.replayEventForReplay)).toBe(true);