@cratis/chronicle 6.33.0 → 6.35.0

package/reactors/Reactors.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, ReactorMessage, ReplayState } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
@@ -13,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';
@@ -102,8 +104,9 @@ export class Reactors implements IReactors {
     /** 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/reactors' });
+    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>();
@@ -130,8 +133,9 @@ export class Reactors implements IReactors {
         private readonly _eventStore?: IEventStore,
         private readonly _artifactActivator?: ClientArtifactsActivator
     ) {
+        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();
@@ -140,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();
@@ -168,43 +173,50 @@ 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 {
-        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,
-            eventSequenceId,
-            handlerCount: eventTypes.length,
-            handlers: eventTypes.map(e => e.methodName)
+    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;
+
+            this._logger.info('Starting reactor observation', {
+                reactorId: id,
+                eventSequenceId,
+                handlerCount: eventTypes.length,
+                handlers: eventTypes.map(e => e.methodName)
+            });
+
+            void this.runObservation(id, reactorType, eventSequenceId, eventTypes, validateInstance);
         });
-
-        void this.runObservation(id, reactorType, eventSequenceId, eventTypes);
     }
 
     private async runObservation(
         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: String(error) });
+            this._logger.error('Reactor observation loop exited with error', { reactorId: id, error });
         }
 
-        this.scheduleReobserve(id, reactorType);
+        this.scheduleReobserve(id, reactorType, eventTypes, validateInstance);
     }
 
     /**
@@ -216,21 +228,21 @@ 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) {
             return;
         }
 
-        const handle = setTimeout(() => {
+        const handle = runInBackgroundContext(() => setTimeout(() => {
             if (!this._registered || this._disposed) {
                 return;
             }
 
             this._logger.info('Re-establishing reactor observation', { reactorId: id });
-            this.startObservation(id, reactorType);
-        }, Reactors._reobserveDelayMs);
+            this.startObservation(id, reactorType, eventTypes, validateInstance);
+        }, Reactors._reobserveDelayMs));
 
         handle.unref?.();
     }
@@ -239,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();
@@ -274,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
             };
@@ -286,7 +300,6 @@ export class Reactors implements IReactors {
 
                 this._logger.debug('Received events to observe', {
                     reactorId: id,
-                    partition: eventsToObserve.Partition,
                     count: eventsToObserve.Events.length,
                     replayState: eventsToObserve.ReplayState
                 });
@@ -299,14 +312,17 @@ 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._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);
                     }
                 } catch (err) {
-                    this._logger.error('Error notifying reactor of replay lifecycle transition', { reactorId: id, error: String(err) });
+                    this._logger.error('Error notifying reactor of replay lifecycle transition', { reactorId: id, error: err });
                     if (err instanceof ArtifactCompletionFailed && err.processingError !== undefined) {
                         exceptionMessages.push(String(err.processingError));
                     }
@@ -348,7 +364,6 @@ export class Reactors implements IReactors {
                             }
 
                             const content = JSON.parse(event.Content) as Record<string, unknown>;
-                            this._logger.debug('Event content', { reactorId: id, eventTypeId, contentKeys: Object.keys(content), rawContent: event.Content.substring(0, 200) });
                             const context = toClientEventContext(event.Context!);
 
                             this._logger.info('Invoking reactor handler', {
@@ -364,7 +379,7 @@ export class Reactors implements IReactors {
 
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                         } catch (err) {
-                            this._logger.error('Error handling event in reactor', { reactorId: id, error: String(err) });
+                            this._logger.error('Error handling event in reactor', { reactorId: id, error: err });
                             exceptionMessages.push(String(err));
                             exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
                             state = ObservationState.Failed;
@@ -386,9 +401,12 @@ 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._artifactActivator, artifact => {
+                            validateInstance(artifact.instance);
+                            return processEvents(artifact);
+                        }, this._connection.logger);
                     } catch (err) {
-                        this._logger.error('Error activating reactor', { reactorId: id, error: String(err) });
+                        this._logger.error('Error activating reactor', { reactorId: id, error: err });
                         exceptionMessages.push(String(err));
                         const completionStack = err instanceof Error ? (err.stack ?? '') : '';
                         exceptionStackTrace = err instanceof ArtifactCompletionFailed && exceptionStackTrace
@@ -419,7 +437,7 @@ export class Reactors implements IReactors {
             if (!this._queues.has(id)) {
                 this._logger.debug('Reactor observation stream closed cleanly', { reactorId: id });
             } else {
-                this._logger.error('Reactor observation stream ended unexpectedly', { reactorId: id, error: String(err) });
+                this._logger.error('Reactor observation stream ended unexpectedly', { reactorId: id, error: err });
             }
         } finally {
             // Only retire our own queue: a reconnect can already have replaced it,

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);

package/reactors/for_ReactorDispatcher/when_selecting_explicit_handlers.spec.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventObservationState } from '@cratis/chronicle.contracts';
+import { beforeEach, chai, describe, it } from 'vitest';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { handles, onceOnly, replay } from '../index.js';
+import { getReactorEventTypes, selectReactorHandler } from '../ReactorDispatcher.js';
+
+chai.should();
+
+@eventType('selected-handler')
+class AuthorRegistered {}
+
+function selected(type: new () => object, state: EventObservationState) {
+    return selectReactorHandler(getReactorEventTypes(type, [AuthorRegistered]), type, undefined, 'selected-handler', state)!;
+}
+
+describe('when selecting an explicit handler with a replay alternative', () => {
+    class Observer {
+        @handles(AuthorRegistered)
+        @onceOnly()
+        notify() {}
+
+        @replay(AuthorRegistered)
+        rebuild() {}
+    }
+    it('should select the explicit method for live events', () => {
+        selected(Observer, EventObservationState.Initial).methodName!.should.equal('notify');
+    });
+    it('should select the replay alternative even when the live method is onceOnly', () => {
+        selected(Observer, EventObservationState.Replay).should.deep.equal({ methodName: 'rebuild', isReplay: true, skipReplay: false });
+    });
+});
+
+describe('when selecting an explicit handler without a replay alternative', () => {
+    class Observer { @handles(AuthorRegistered) notify() {} }
+    let handler: ReturnType<typeof selected>;
+    beforeEach(() => { handler = selected(Observer, EventObservationState.Replay); });
+    it('should use the explicit method during replay too', () => {
+        handler.should.deep.equal({ methodName: 'notify', isReplay: true, skipReplay: false });
+    });
+});
+
+describe('when an explicit handler is onceOnly', () => {
+    class Observer { @onceOnly() @handles(AuthorRegistered) notify() {} }
+    it('should not skip live delivery', () => {
+        selected(Observer, EventObservationState.Initial).skipReplay.should.be.false;
+    });
+    it('should skip replay delivery', () => {
+        selected(Observer, EventObservationState.Replay).skipReplay.should.be.true;
+    });
+});
+
+describe('when a method declares both live and replay roles', () => {
+    class Observer { @handles(AuthorRegistered) @replay(AuthorRegistered) notify() {} }
+    it('should reject the ambiguous declaration during discovery', () => {
+        (() => getReactorEventTypes(Observer, [AuthorRegistered])).should.throw(/notify.*Observer.*cannot combine @handles and @replay/);
+    });
+    it('should reject replay above handles too', () => {
+        class Reversed { @replay(AuthorRegistered) @handles(AuthorRegistered) notify() {} }
+        (() => getReactorEventTypes(Reversed, [AuthorRegistered])).should.throw(/notify.*Reversed.*cannot combine @handles and @replay/);
+    });
+});

package/reactors/for_Reactors/when_activating_a_field_override.spec.ts

@@ -0,0 +1,62 @@
+// 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 ReactorMessage } 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 { IEventLog } from '../../eventSequences/IEventLog.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { handles, reactor, Reactors } from '../index.js';
+
+chai.should();
+
+@eventType('field-reactor-event')
+class AuthorRegistered {}
+const calls: string[] = [];
+class Base {
+    @handles(AuthorRegistered) notify() { calls.push('base'); }
+    beginReplay() { calls.push('replay'); }
+    endReplay() {}
+}
+@reactor('field-reactor')
+class Derived extends Base {
+    override notify = () => { calls.push('field'); };
+}
+
+for (const replayState of [ReplayState.REPLAY_STATE_None, ReplayState.BeginReplay]) {
+    describe(`when activating a reactor with a field override for replay state ${replayState}`, () => {
+        let result: ReactorMessage;
+        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<ReactorMessage>) {
+                const messages = queue[Symbol.asyncIterator]();
+                await messages.next();
+                yield { Events: [{ Content: '{}', Context: EventContext.fromPartial({
+                    EventType: EventType.fromPartial({ Id: 'field-reactor-event', Generation: 1 }), SequenceNumber: 1n
+                }) }], Partition: 'author', ReplayState: replayState, InitialState: '' };
+                result = (await messages.next()).value!;
+                await lifecycle.disconnected(error => { throw error; });
+                finish();
+            }
+            const reactors = new Reactors({ reactors: [Derived], eventTypes: [AuthorRegistered] } as unknown as IClientArtifactsProvider,
+                { reactors: { observe: stream } } as unknown as ChronicleConnection, 'store', 'tenant', lifecycle, {} as IEventLog,
+                undefined, { readModels: {} } as IEventStore, type => ({ instance: new type(), dispose: () => { disposed = true; } }));
+            try { await reactors.register(); await finished; } finally { reactors.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!.ExceptionMessages.join(' ').should.contain(
+                "Override 'notify' 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/reactors/for_Reactors/when_delivering/with_activation.spec.ts

@@ -4,7 +4,8 @@
 import { EventContext as WireContext, EventObservationState, EventType, ObservationState, type ReactorMessage } from '@cratis/chronicle.contracts';
 import { ReplayState } from '../../../index.js';
 import { chai, describe, it, vi } from 'vitest';
-import { diag, DiagLogLevel, type DiagLogger } from '@opentelemetry/api';
+import type { IChronicleLogger } from '../../../logging/IChronicleLogger.js';
+import type { ChronicleLogEntry } from '../../../logging/ChronicleLogEntry.js';
 import type { ChronicleConnection } from '../../../connection/index.js';
 import { ConnectionLifecycle } from '../../../connection/ConnectionLifecycle.js';
 import type { IClientArtifactsProvider } from '../../../artifacts/IClientArtifactsProvider.js';
@@ -98,7 +99,7 @@ function delivery(events: ReturnType<typeof event>[], replayState = ReplayState.
 }
 
 async function observe(type: Function, batches: ReturnType<typeof delivery>[], namespace = 'tenant-a',
-    activator?: ClientArtifactsActivator, appendResult = true, onAppendMany?: () => void) {
+    activator?: ClientArtifactsActivator, appendResult = true, onAppendMany?: () => void, logger?: IChronicleLogger) {
     const acknowledgements: NonNullable<ReactorMessage['Content']>['Value1'][] = [];
     const append = vi.fn().mockResolvedValue({ isSuccess: appendResult });
     const appendMany = vi.fn().mockImplementation(async () => {
@@ -122,7 +123,7 @@ async function observe(type: Function, batches: ReturnType<typeof delivery>[], n
         await lifecycle.disconnected(error => { throw error; });
         finished();
     }
-    const connection = { reactors: { observe: stream } } as unknown as ChronicleConnection;
+    const connection = { logger, reactors: { observe: stream } } as unknown as ChronicleConnection;
     const artifacts = { reactors: [type], eventTypes: [ActivationEvent] } as unknown as IClientArtifactsProvider;
     await new Reactors(artifacts, connection, 'store', namespace, lifecycle, eventLog, undefined, store, activator).register();
     await complete;
@@ -462,16 +463,15 @@ describe('when delivering reactor batches', () => {
     });
 
     it('should log disposal failure without changing successful acknowledgement', async () => {
-        const errors: string[] = [];
-        diag.setLogger({ error: (...values: unknown[]) => { errors.push(values.map(String).join(' ')); } } as DiagLogger, DiagLogLevel.ERROR);
-        try {
-            const activator: ClientArtifactsActivator = type => ({ instance: new type(), dispose: async () => { throw new Error('cleanup'); } });
-            const result = await observe(ActivationReactor, [delivery([event('live', 1n)])], 'tenant-a', activator);
-            result.acknowledgements[0]?.State.should.equal(ObservationState.Success);
-            result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(1n);
-            errors.some(value => value.includes('Error disposing activated artifact')).should.be.true;
-        } finally {
-            diag.disable();
-        }
+        const entries: ChronicleLogEntry[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(), dispose: async () => { throw new Error('private cleanup details'); } });
+        const result = await observe(ActivationReactor, [delivery([event('private payload', 1n)])], 'tenant-a', activator,
+            true, undefined, { log: entry => entries.push(entry) });
+        result.acknowledgements[0]?.State.should.equal(ObservationState.Success);
+        result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(1n);
+        entries.filter(entry => entry.attributes['exception.type'] === 'Error').should.have.lengthOf(1);
+        JSON.stringify(entries).should.not.contain('private cleanup details');
+        JSON.stringify(entries).should.not.contain('private payload');
+        JSON.stringify(entries).should.not.contain('book-1');
     });
 });

package/reactors/for_Reactors/when_delivering_to_instance_handlers.spec.ts

@@ -0,0 +1,108 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventContext, EventObservationState, EventType, ObservationState, ReplayState, type ReactorMessage } 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 { IEventLog } from '../../eventSequences/IEventLog.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { handles, reactor, Reactors, replay } from '../index.js';
+
+chai.should();
+
+@eventType('instance-reactor-event')
+class AuthorRegistered {}
+const calls: string[] = [];
+
+@reactor('bound-conventional-reactor')
+class BoundConventional {
+    readonly marker = 'bound conventional';
+    constructor() { this.authorRegistered = this.authorRegistered.bind(this); }
+    authorRegistered() { calls.push(this.marker); }
+}
+
+@reactor('bound-explicit-reactor')
+class BoundExplicit {
+    readonly marker = 'bound explicit';
+    constructor() { this.notify = this.notify.bind(this); }
+    @handles(AuthorRegistered)
+    notify() { calls.push(this.marker); }
+}
+
+class BoundExplicitBase {
+    readonly marker = 'twice bound explicit';
+    constructor() { this.notify = this.notify.bind(this); }
+    @handles(AuthorRegistered)
+    notify() { calls.push(this.marker); }
+}
+
+@reactor('twice-bound-explicit-reactor')
+class TwiceBoundExplicit extends BoundExplicitBase {
+    constructor() { super(); this.notify = this.notify.bind(this); }
+}
+
+class Conventional {
+    authorRegistered() { calls.push('base'); }
+}
+
+@reactor('field-conventional-reactor')
+class FieldConventional extends Conventional {
+    override authorRegistered = () => { calls.push('field conventional'); };
+}
+
+@reactor('bound-replay-reactor')
+class BoundReplay {
+    readonly marker = 'bound replay';
+    constructor() { this.restore = this.restore.bind(this); }
+    @replay(AuthorRegistered)
+    restore() { calls.push(this.marker); }
+}
+
+class Replay {
+    @replay(AuthorRegistered)
+    restore() { calls.push('base replay'); }
+}
+
+@reactor('field-replay-reactor')
+class FieldReplay extends Replay {
+    override restore = () => { calls.push('field replay'); };
+}
+
+for (const { type, expected, observationState } of [
+    { type: BoundConventional, expected: 'bound conventional', observationState: EventObservationState.Initial },
+    { type: BoundExplicit, expected: 'bound explicit', observationState: EventObservationState.Initial },
+    { type: TwiceBoundExplicit, expected: 'twice bound explicit', observationState: EventObservationState.Initial },
+    { type: FieldConventional, expected: 'field conventional', observationState: EventObservationState.Initial },
+    { type: BoundReplay, expected: 'bound replay', observationState: EventObservationState.Replay },
+    { type: FieldReplay, expected: 'field replay', observationState: EventObservationState.Replay }
+]) {
+    describe(`when delivering to the ${expected} reactor handler without an activator`, () => {
+        let result: ReactorMessage;
+        beforeEach(async () => {
+            calls.length = 0;
+            const lifecycle = new ConnectionLifecycle();
+            let finish!: () => void;
+            const finished = new Promise<void>(resolve => { finish = resolve; });
+            async function* stream(queue: AsyncIterable<ReactorMessage>) {
+                const messages = queue[Symbol.asyncIterator]();
+                await messages.next();
+                yield { Events: [{ Content: '{}', Context: EventContext.fromPartial({
+                    EventType: EventType.fromPartial({ Id: 'instance-reactor-event', Generation: 1 }), SequenceNumber: 1n,
+                    ObservationState: observationState
+                }) }], Partition: 'author', ReplayState: ReplayState.REPLAY_STATE_None, InitialState: '' };
+                result = (await messages.next()).value!;
+                await lifecycle.disconnected(error => { throw error; });
+                finish();
+            }
+            const reactors = new Reactors({ reactors: [type], eventTypes: [AuthorRegistered] } as unknown as IClientArtifactsProvider,
+                { reactors: { observe: stream } } as unknown as ChronicleConnection, 'store', 'tenant', lifecycle, {} as IEventLog,
+                undefined, { readModels: {} } as IEventStore);
+            try { await reactors.register(); await finished; } finally { reactors.dispose(); }
+        });
+        it('should invoke the instance handler', () => { calls.should.deep.equal([expected]); });
+        it('should complete delivery', () => { result.Content!.Value1!.State.should.equal(ObservationState.Success); });
+    });
+}

package/reactors/for_Reactors/when_observing_explicit_handlers.legacy.spec.ts

@@ -0,0 +1,77 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventContext, EventObservationState, EventType, type ReactorMessage } 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 { IEventLog } from '../../eventSequences/IEventLog.js';
+import { eventType } from '../../events/eventTypeDecorator.js';
+import { handles, onceOnly, reactor, Reactors, replay } from '../index.js';
+
+chai.should();
+
+@eventType('legacy-delivered-handler')
+class AuthorRegistered { constructor(readonly name = '') {} }
+
+const calls: string[] = [];
+@reactor('legacy-delivery')
+class AuthorReactor {
+    @handles(AuthorRegistered)
+    @onceOnly()
+    notify(event: AuthorRegistered) { calls.push(`live:${event.name}`); }
+}
+@reactor('legacy-delivery-with-replay')
+class ReplayAuthorReactor extends AuthorReactor {
+    @replay(AuthorRegistered)
+    rebuild(event: AuthorRegistered) { calls.push(`replay:${event.name}`); }
+}
+
+for (const [type, expected] of [
+    [AuthorReactor, ['live:Ada']],
+    [ReplayAuthorReactor, ['live:Ada', 'replay:Ada']]
+] as const) {
+    describe(`when observing live and replay events with explicit legacy handlers on ${type.name}`, () => {
+        let registration: ReactorMessage;
+        let result: ReactorMessage;
+        beforeEach(async () => {
+            calls.length = 0;
+            const lifecycle = new ConnectionLifecycle();
+            let finish!: () => void;
+            const finished = new Promise<void>(resolve => { finish = resolve; });
+            async function* stream(queue: AsyncIterable<ReactorMessage>) {
+                const messages = queue[Symbol.asyncIterator]();
+                registration = (await messages.next()).value!;
+                yield {
+                    Events: [EventObservationState.Initial, EventObservationState.Replay].map((state, index) => ({
+                        Context: EventContext.fromPartial({
+                            EventType: EventType.fromPartial({ Id: 'legacy-delivered-handler', Generation: 1 }),
+                            SequenceNumber: BigInt(index + 1), ObservationState: state
+                        }),
+                        Content: JSON.stringify({ name: 'Ada' })
+                    })),
+                    Partition: 'author', ReplayState: 0, InitialState: ''
+                };
+                result = (await messages.next()).value!;
+                await lifecycle.disconnected(error => { throw error; });
+                finish();
+            }
+            const connection = { reactors: { observe: stream } } as unknown as ChronicleConnection;
+            const artifacts = { reactors: [type], eventTypes: [AuthorRegistered] } as unknown as IClientArtifactsProvider;
+            const reactors = new Reactors(artifacts, connection, 'store', 'tenant', lifecycle, {} as IEventLog);
+            try {
+                await reactors.register();
+                await finished;
+            } finally { reactors.dispose(); }
+        });
+        it('should subscribe to the explicitly named event type', () => {
+            registration.Content!.Value0!.Reactor!.EventTypes.map(entry => entry.EventType!.Id)
+                .should.deep.equal(['legacy-delivered-handler']);
+        });
+        it('should invoke only the appropriate handlers', () => { calls.should.deep.equal(expected); });
+        it('should acknowledge both deliveries', () => {
+            result.Content!.Value1!.LastSuccessfulObservation.should.equal(2n);
+        });
+    });
+}