@cratis/chronicle 6.46.0 → 6.48.0

package/events/for_observerFilters/when_registering/with_legacy_decorators.legacy.spec.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { eventSourceType, eventStreamType, filterEventsByTag, tag } from '../../../index.js';
+import { filterRegistrationBehaviors } from './filter_registration_behaviors.fixture.js';
+
+class Unfiltered {}
+@eventSourceType('Customers')
+class SourceFiltered {}
+@eventStreamType('Orders')
+class StreamFiltered {}
+@eventSourceType('Customers')
+@eventStreamType('Orders')
+@filterEventsByTag('vip')
+@filterEventsByTag('priority')
+@tag('Analytics')
+class Combined {}
+class Inherited extends Combined {}
+@eventSourceType('')
+@eventStreamType('All')
+class Reset extends Combined {}
+
+filterRegistrationBehaviors([
+    { type: Unfiltered, source: '', stream: 'All', tags: [] },
+    { type: SourceFiltered, source: 'Customers', stream: 'All', tags: [] },
+    { type: StreamFiltered, source: '', stream: 'Orders', tags: [] },
+    { type: Combined, source: 'Customers', stream: 'Orders', tags: ['priority', 'vip'] },
+    { type: Inherited, source: 'Customers', stream: 'Orders', tags: ['priority', 'vip'] },
+    { type: Reset, source: '', stream: 'All', tags: ['priority', 'vip'] }
+]);

package/events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { eventSourceType, eventStreamType, filterEventsByTag, tag } from '../../../index.js';
+import { filterRegistrationBehaviors } from './filter_registration_behaviors.fixture.js';
+
+class Unfiltered {}
+@eventSourceType('Customers')
+class SourceFiltered {}
+@eventStreamType('Orders')
+class StreamFiltered {}
+@eventSourceType('Customers')
+@eventStreamType('Orders')
+@filterEventsByTag('vip')
+@filterEventsByTag('priority')
+@tag('Analytics')
+class Combined {}
+class Inherited extends Combined {}
+@eventSourceType('')
+@eventStreamType('All')
+class Reset extends Combined {}
+
+filterRegistrationBehaviors([
+    { type: Unfiltered, source: '', stream: 'All', tags: [] },
+    { type: SourceFiltered, source: 'Customers', stream: 'All', tags: [] },
+    { type: StreamFiltered, source: '', stream: 'Orders', tags: [] },
+    { type: Combined, source: 'Customers', stream: 'Orders', tags: ['priority', 'vip'] },
+    { type: Inherited, source: 'Customers', stream: 'Orders', tags: ['priority', 'vip'] },
+    { type: Reset, source: '', stream: 'All', tags: ['priority', 'vip'] }
+]);

package/events/index.ts

@@ -18,6 +18,8 @@ export { isRegisteredEvent } from './isRegisteredEvent.js';
 export { Tag } from './Tag.js';
 export { tag, tags, getTagsFor } from './tagDecorator.js';
 export { filterEventsByTag, getFilterTagsFor } from './filterEventsByTagDecorator.js';
+export { eventSourceType, getEventSourceTypeFor } from './eventSourceTypeDecorator.js';
+export { eventStreamType, getEventStreamTypeFor } from './eventStreamTypeDecorator.js';
 export { mergeTags } from './mergeTags.js';
 export * from './constraints/index.js';
 export * from './migrations/index.js';

package/for_ChronicleClient/when_reconnecting/with_waiting_read_model_watchers.spec.ts

@@ -0,0 +1,117 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it, vi } from 'vitest';
+import { ChronicleClient } from '../../ChronicleClient.js';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import { EventStore } from '../../EventStore.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { IncompatibleChronicleServer } from '../../connection/IncompatibleChronicleServer.js';
+import { RejectedChronicleCredentials } from '../../connection/RejectedChronicleCredentials.js';
+import { projection } from '../../projections/declarative/projection.js';
+import type { IReadModelWatcher } from '../../readModels/IReadModelWatcher.js';
+import { a_kernel_stream } from '../../readModels/for_ReadModelWatcher/given/a_kernel_stream.js';
+
+chai.should();
+
+const transport = vi.hoisted(() => ({
+    resetChannel: vi.fn(), connect: vi.fn(), disconnect: vi.fn(), getVersionInfo: vi.fn(),
+    ensureEventStore: vi.fn(), watch: vi.fn(),
+    lost: undefined as ((reason: string, error: unknown) => void) | undefined
+}));
+vi.mock('../../connection/ChronicleConnection', () => ({
+    ChronicleConnection: class {
+        resetChannel = transport.resetChannel;
+        connect = transport.connect;
+        disconnect = transport.disconnect;
+        server = { getVersionInfo: transport.getVersionInfo };
+        eventStores = { ensureEventStore: transport.ensureEventStore };
+        readModels = { watch: transport.watch };
+    }
+}));
+vi.mock('../../connection/KernelKeepAlive', () => ({
+    KernelKeepAlive: class {
+        constructor(_connections: unknown, onLost: (reason: string, error: unknown) => void) { transport.lost = onLost; }
+        async start() {}
+    }
+}));
+
+class Model { id = ''; }
+class ModelProjection { define() {} }
+projection('model', Model)(ModelProjection);
+
+describe('when reconnecting with waiting read model watchers', () => {
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let watcher: IReadModelWatcher<Model>;
+    let stream: a_kernel_stream;
+    let rejectReconnect: (error: Error) => void;
+
+    beforeEach(async () => {
+        vi.useFakeTimers();
+        vi.clearAllMocks();
+        // Registration is outside this connection-lifetime specification; retain the real store and watchers.
+        vi.spyOn(EventStore.prototype, 'registerArtifacts').mockResolvedValue(undefined);
+        transport.resetChannel.mockResolvedValue(undefined);
+        transport.connect.mockResolvedValue(undefined);
+        transport.getVersionInfo.mockResolvedValue({});
+        transport.ensureEventStore.mockResolvedValue({ IsSuccess: true, IsAuthorized: true });
+        stream = new a_kernel_stream();
+        transport.watch.mockImplementation((_request, options: { signal: AbortSignal }) => {
+            stream.signal = options.signal;
+            options.signal.addEventListener('abort', () => stream.end(), { once: true });
+            return stream;
+        });
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString('chronicle://localhost:35000', {
+            discoveryPatterns: [],
+            clientArtifactsProvider: {
+                readModels: [Model], projections: [ModelProjection], eventTypes: [], reactors: [], reducers: [],
+                seeders: [], constraints: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+            }
+        }));
+        store = await client.getEventStore('store');
+        watcher = store.readModels.createWatcher(Model, { resume: true });
+        stream.send({ Subscribed: true });
+        await watcher.subscribed;
+        transport.connect.mockImplementation(() => new Promise<void>((_resolve, reject) => { rejectReconnect = reject; }));
+        transport.lost!('keep-alive-ended', { code: 14 });
+        await vi.advanceTimersByTimeAsync(0);
+        stream.signal.aborted.should.be.true;
+    });
+    afterEach(() => {
+        client.dispose();
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+
+    it.each([
+        ['incompatible server', IncompatibleChronicleServer],
+        ['rejected credentials', RejectedChronicleCredentials]
+    ] as const)('should reject readiness and iteration on terminal %s', async (_reason, Failure) => {
+        const failure = new Failure('Replacement connection rejected');
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher[Symbol.asyncIterator]().next().catch(error => error);
+        rejectReconnect(failure);
+        (await readiness).should.equal(failure);
+        (await next).should.equal(failure);
+        await vi.advanceTimersByTimeAsync(15000);
+        transport.watch.mock.calls.should.have.lengthOf(1);
+        transport.connect.mock.calls.should.have.lengthOf(2);
+        // A cached store cannot create a watcher that waits forever after the terminal verdict.
+        const later = store.readModels.createWatcher(Model);
+        (await later.subscribed.catch(error => error)).should.equal(failure);
+        (await later[Symbol.asyncIterator]().next().catch(error => error)).should.equal(failure);
+    });
+
+    it('should reject pending readiness but complete iteration cleanly if disposed during recovery', async () => {
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher[Symbol.asyncIterator]().next();
+        client.dispose();
+        (await readiness).name.should.equal('AbortError');
+        (await next).done!.should.be.true;
+        rejectReconnect(new IncompatibleChronicleServer('Late reconnect failure'));
+        await vi.advanceTimersByTimeAsync(15000);
+        (await watcher[Symbol.asyncIterator]().next()).done!.should.be.true;
+        transport.watch.mock.calls.should.have.lengthOf(1);
+    });
+});

package/jobs/for_Jobs/against_a_kernel/when_managing_a_replay_job.integration.spec.ts

@@ -3,12 +3,13 @@
 
 import { randomUUID } from 'node:crypto';
 import { afterAll, beforeAll, chai, describe, it } from 'vitest';
-import { JobStatus, JobStepStatus, type JobStepSummaryResponse, type JobSummaryResponse } from '@cratis/chronicle.contracts';
+import { JobStatus, JobStepStatus, ObserverRunningState, type JobStepSummaryResponse, type JobSummaryResponse } from '@cratis/chronicle.contracts';
 import { field, Guid } from '@cratis/fundamentals';
 import { ChronicleClient } from '../../../ChronicleClient.js';
 import { ChronicleOptions } from '../../../ChronicleOptions.js';
 import { fromContractsGuid } from '../../../connection/Guid.js';
 import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
 import { eventType } from '../../../events/index.js';
 import type { IEventStore } from '../../../IEventStore.js';
 import { fromEvent } from '../../../projections/index.js';
@@ -55,8 +56,10 @@ async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boole
 }
 
 describe.skipIf(!connectionString && !process.env.CI)('when managing a replay job against a kernel', () => {
+    const storeName = `Jobs${randomUUID().replaceAll('-', '').slice(0, 12)}`;
     let client: ChronicleClient;
     let store: IEventStore;
+    let connection: ChronicleConnection;
     let jobId: JobId;
     let listed: JobSummaryResponse[];
     let stopped: JobSummaryResponse | undefined;
@@ -65,19 +68,36 @@ describe.skipIf(!connectionString && !process.env.CI)('when managing a replay jo
     let stopUnknownJob: unknown;
     let deleteUnknownJob: unknown;
 
+    const waitForActiveObserver = (lastHandledSequenceNumber?: bigint) => eventually(
+        () => connection.observers.getObserverInformation({
+            EventStore: storeName,
+            Namespace: 'Default',
+            ObserverId: 'Item',
+            EventSequenceId: 'event-log'
+        }),
+        observer => observer.IsSubscribed && observer.RunningState === ObserverRunningState.Active &&
+            (lastHandledSequenceNumber === undefined || observer.LastHandledEventSequenceNumber === lastHandledSequenceNumber),
+        15_000);
+
+    // Readiness (30s) and the existing job-state waits (90s) leave 30s for RPC overhead.
     beforeAll(async () => {
         client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
             discoveryPatterns: [],
             clientArtifactsProvider: artifacts
         }));
-        store = await client.getEventStore(`Jobs${randomUUID().replaceAll('-', '').slice(0, 12)}`);
+        store = await client.getEventStore(storeName);
+        connection = (store as unknown as { _connection: ChronicleConnection })._connection;
 
+        // Append only after initial catch-up completes, so it cannot race the explicit replay.
+        await waitForActiveObserver();
         // Enough events that the replay is still running when it is stopped; a stopped job stays until deleted,
         // where a completed one is removed and could not be listed reliably.
-        await store.eventLog.appendMany(Array.from({ length: 500 }, (_, index) => ({
+        const appended = await store.eventLog.appendMany(Array.from({ length: 500 }, (_, index) => ({
             eventSourceId: randomUUID(),
             event: Object.assign(new ItemAdded(), { name: `Item ${index}` })
         })));
+        // ReplayForModel uses Observer.Replay too; wait for acknowledged progress before requesting it.
+        await waitForActiveObserver(appended.at(-1)!.sequenceNumber.value);
 
         jobId = await store.projections.replayForModel(Item);
 
@@ -98,7 +118,7 @@ describe.skipIf(!connectionString && !process.env.CI)('when managing a replay jo
 
         stopUnknownJob = await store.jobs.stop(randomUUID()).catch((error: unknown) => error);
         deleteUnknownJob = await store.jobs.delete(randomUUID()).catch((error: unknown) => error);
-    });
+    }, 150_000);
 
     afterAll(() => client?.dispose());
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.46.0",
+    "version": "6.48.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",
@@ -173,7 +173,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/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.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 testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.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/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.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 testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.standard.spec.ts events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts reactors/for_Reactors/against_a_kernel/when_filtering_source_and_stream_types.integration.spec.ts testing/for_observerScenarios/when_selecting_filters/with_source_and_stream_types.spec.ts readModels/for_ReadModelWatcher/watchCompatibility.standard.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {

package/reactors/ReactorSideEffects.ts

@@ -2,6 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { hasEventType } from '../events/eventTypeDecorator.js';
+import { getEventSourceTypeFor } from '../events/eventSourceTypeDecorator.js';
+import { getDeclaredEventStreamTypeFor } from '../events/eventStreamTypeDecorator.js';
 import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
 import type { IEventLog } from '../eventSequences/IEventLog.js';
 import type { EventContext } from '../events/EventContext.js';
@@ -25,7 +27,8 @@ export async function dispatchReactorSideEffects(eventLog: IEventLog, result: un
     reactorType: Function, eventStore: string, namespace: string, handler?: ReactorResultHandler): Promise<void> {
     if (await handler?.(result, context, reactorType, eventStore, namespace)) return;
     const appended = await appendReactorSideEffects(eventLog, result, context.eventSourceId,
-        context.eventStreamType ?? 'Default', context.eventStreamId ?? context.eventSourceId);
+        context.eventStreamType ?? 'Default', context.eventStreamId ?? context.eventSourceId,
+        getEventSourceTypeFor(reactorType), getDeclaredEventStreamTypeFor(reactorType));
     if (!appended.isSuccess) throw new Error(`Reactor side effect failed to append: ${appended.errors.join('; ')}`);
 }
 
@@ -58,22 +61,27 @@ function isEventForEventSourceId(value: unknown): value is EventForEventSourceId
  * event returns.
  * @param triggeringEventStreamId - The event stream identifier of the triggering event, used for
  * bare event returns.
+ * @param reactorEventSourceType - Non-empty reactor source type metadata for bare event returns.
+ * @param reactorEventStreamType - Non-empty declared reactor stream type metadata for bare event returns,
+ * overriding the triggering stream type. Omitted metadata preserves the triggering stream type.
  * @returns The outcome of the append. Each {@link EventForEventSourceId} entry keeps its own
- * target (event source id, stream type/id, subject); bare events use the triggering event's.
+ * target metadata; bare events use the triggering target with the reactor's declared types.
  */
 export async function appendReactorSideEffects(
     eventLog: IEventLog,
     handlerResult: unknown,
     triggeringEventSourceId: string,
     triggeringEventStreamType: string,
-    triggeringEventStreamId: string
+    triggeringEventStreamId: string,
+    reactorEventSourceType?: string,
+    reactorEventStreamType?: string
 ): Promise<ReactorSideEffectResult> {
     if (handlerResult === undefined || handlerResult === null) {
         return noSideEffects;
     }
 
     const events = normalizeReactorSideEffects(handlerResult, triggeringEventSourceId,
-        triggeringEventStreamType, triggeringEventStreamId);
+        triggeringEventStreamType, triggeringEventStreamId, reactorEventSourceType, reactorEventStreamType);
     if (events.length === 0) {
         return noSideEffects;
     }
@@ -91,7 +99,8 @@ export async function appendReactorSideEffects(
 
 /** Production return-shape normalization; unknown values are ignored by production dispatch. */
 export function normalizeReactorSideEffects(handlerResult: unknown, triggeringEventSourceId: string,
-    triggeringEventStreamType: string, triggeringEventStreamId: string): EventForEventSourceId[] {
+    triggeringEventStreamType: string, triggeringEventStreamId: string,
+    reactorEventSourceType?: string, reactorEventStreamType?: string): EventForEventSourceId[] {
     const items = Array.isArray(handlerResult) ? handlerResult : [handlerResult];
     const events: EventForEventSourceId[] = [];
 
@@ -102,7 +111,8 @@ export function normalizeReactorSideEffects(handlerResult: unknown, triggeringEv
             events.push({
                 eventSourceId: triggeringEventSourceId,
                 event: item,
-                eventStreamType: triggeringEventStreamType,
+                eventStreamType: reactorEventStreamType || triggeringEventStreamType,
+                ...(reactorEventSourceType ? { eventSourceType: reactorEventSourceType } : {}),
                 eventStreamId: triggeringEventStreamId,
                 subject: triggeringEventSourceId
             });

package/reactors/Reactors.ts

@@ -12,6 +12,8 @@ import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
 import { toClientEventContext } from '../events/toClientEventContext.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
+import { getEventSourceTypeFor } from '../events/eventSourceTypeDecorator.js';
+import { getEventStreamTypeFor } from '../events/eventStreamTypeDecorator.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
 import type { IEventLog } from '../eventSequences/IEventLog.js';
 import { createHandlerInstanceValidator } from '../observation/createHandlerInstanceValidator.js';
@@ -277,8 +279,8 @@ export class Reactors implements IReactors {
                         Tags: getTagsFor(reactorType).map(t => t.value),
                         Filters: {
                             FilterTags: getFilterTagsFor(reactorType).map(t => t.value),
-                            EventSourceType: '',
-                            EventStreamType: 'All'
+                            EventSourceType: getEventSourceTypeFor(reactorType),
+                            EventStreamType: getEventStreamTypeFor(reactorType)
                         }
                     }
                 },

package/reactors/for_ReactorSideEffects/when_dispatching/with_reactor_source_and_stream_types.spec.ts

@@ -0,0 +1,75 @@
+// 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 { eventSourceType } from '../../../events/eventSourceTypeDecorator.js';
+import { eventStreamType } from '../../../events/eventStreamTypeDecorator.js';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import type { EventContext } from '../../../events/EventContext.js';
+import type { EventForEventSourceId } from '../../../eventSequences/EventForEventSourceId.js';
+import type { IEventLog } from '../../../eventSequences/IEventLog.js';
+import { dispatchReactorSideEffects } from '../../ReactorSideEffects.js';
+
+chai.should();
+@eventType('side-effect-with-reactor-types')
+class Outbound {}
+@eventSourceType('my-source')
+class SourceReactor {}
+@eventStreamType('my-stream')
+class StreamReactor extends SourceReactor {}
+class InheritedReactor extends StreamReactor {}
+@eventSourceType('')
+@eventStreamType('')
+class EmptyReactor extends StreamReactor {}
+@eventStreamType('All')
+class AllStreamsReactor {}
+const context = { eventSourceId: 'trigger', eventStreamType: 'trigger-stream', eventStreamId: 'trigger-stream-id' } as EventContext;
+
+for (const [reactorType, sourceType, streamType] of [
+    [SourceReactor, 'my-source', 'trigger-stream'],
+    [StreamReactor, 'my-source', 'my-stream'],
+    [InheritedReactor, 'my-source', 'my-stream'],
+    [EmptyReactor, undefined, 'trigger-stream'],
+    [AllStreamsReactor, undefined, 'All']
+] as const) {
+    describe(`when dispatching a bare returned event from ${reactorType.name}`, () => {
+        let appended: EventForEventSourceId[];
+        const outbound = new Outbound();
+        beforeEach(async () => {
+            const eventLog = { appendMany: vi.fn(async (events: EventForEventSourceId[]) => {
+                appended = events;
+                return [{ isSuccess: true, errors: [], constraintViolations: [] }];
+            }) } as unknown as IEventLog;
+            await dispatchReactorSideEffects(eventLog, outbound, context, reactorType, 'store', 'namespace');
+        });
+        it('should append the returned event with the reactor types and triggering target', () => {
+            appended.should.deep.equal([{ eventSourceId: 'trigger', event: outbound, eventStreamType: streamType,
+                ...(sourceType ? { eventSourceType: sourceType } : {}), eventStreamId: 'trigger-stream-id', subject: 'trigger' }]);
+        });
+    });
+}
+
+describe('when dispatching mixed bare and explicitly targeted returned events', () => {
+    let appended: EventForEventSourceId[];
+    const explicit = { eventSourceId: 'other', event: new Outbound(), eventSourceType: 'explicit-source',
+        eventStreamType: 'explicit-stream', eventStreamId: 'other-stream', subject: 'other-subject' };
+    const omitted = { eventSourceId: 'omitted', event: new Outbound() };
+    const empty = { eventSourceId: 'empty', event: new Outbound(), eventSourceType: '', eventStreamType: '' };
+    beforeEach(async () => {
+        const eventLog = { appendMany: vi.fn(async (events: EventForEventSourceId[]) => {
+            appended = events;
+            return [{ isSuccess: true, errors: [], constraintViolations: [] }];
+        }) } as unknown as IEventLog;
+        await dispatchReactorSideEffects(eventLog, [new Outbound(), explicit, omitted, empty], context, StreamReactor, 'store', 'namespace');
+    });
+    it('should apply reactor metadata to only the bare event', () => {
+        appended[0].eventSourceType!.should.equal('my-source');
+        appended[0].eventStreamType!.should.equal('my-stream');
+    });
+    it('should preserve explicit targets including omitted and empty type values', () => {
+        appended.slice(1).should.deep.equal([explicit, omitted, empty]);
+        appended[1].should.equal(explicit);
+        appended[2].should.equal(omitted);
+        appended[3].should.equal(empty);
+    });
+});

package/reactors/for_Reactors/against_a_kernel/when_filtering_source_and_stream_types.integration.spec.ts

@@ -0,0 +1,147 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { ObserverRunningState } from '@cratis/chronicle.contracts';
+import { ChronicleClient, ChronicleOptions, eventType, eventSourceType, eventStreamType, filterEventsByTag,
+    reactor, reducer, tag, type IEventStore, type IClientArtifactsProvider } from '../../../index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+
+chai.should();
+function should(value: unknown): ReturnType<typeof chai.expect> {
+    return (value as { should: ReturnType<typeof chai.expect> }).should;
+}
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class FilteredOrderPlaced {
+    @field(String) name = '';
+}
+
+const reactorCalls = new Map<string, string[]>();
+const reducerCalls = new Map<string, string[]>();
+class Totals { count = 0; lastName = ''; }
+class SourceTotals extends Totals {}
+class StreamTotals extends Totals {}
+class CombinedTotals extends Totals {}
+
+@reactor()
+class AllOrders {
+    filteredOrderPlaced(event: FilteredOrderPlaced) {
+        const name = this.constructor.name;
+        reactorCalls.set(name, [...reactorCalls.get(name) ?? [], event.name]);
+    }
+}
+@reactor()
+@eventSourceType('Customers')
+class CustomerOrders extends AllOrders {}
+@reactor()
+@eventStreamType('Orders')
+class OrdersStream extends AllOrders {}
+@reactor()
+@eventSourceType('Customers')
+@eventStreamType('Orders')
+@filterEventsByTag('vip')
+@filterEventsByTag('priority')
+@tag('Analytics')
+class PriorityCustomerOrders extends AllOrders {}
+
+@reducer('AllOrderTotals', undefined, Totals)
+class AllOrderTotals {
+    filteredOrderPlaced(event: FilteredOrderPlaced, current: Totals | undefined): Totals {
+        const name = this.constructor.name;
+        reducerCalls.set(name, [...reducerCalls.get(name) ?? [], event.name]);
+        return { count: (current?.count ?? 0) + 1, lastName: event.name };
+    }
+}
+@reducer('CustomerOrderTotals', undefined, SourceTotals)
+@eventSourceType('Customers')
+class CustomerOrderTotals extends AllOrderTotals {}
+@reducer('OrdersStreamTotals', undefined, StreamTotals)
+@eventStreamType('Orders')
+class OrdersStreamTotals extends AllOrderTotals {}
+@reducer('PriorityCustomerOrderTotals', undefined, CombinedTotals)
+@eventSourceType('Customers')
+@eventStreamType('Orders')
+@filterEventsByTag('vip')
+@filterEventsByTag('priority')
+@tag('Analytics')
+class PriorityCustomerOrderTotals extends AllOrderTotals {}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [FilteredOrderPlaced], reactors: [AllOrders, CustomerOrders, OrdersStream, PriorityCustomerOrders],
+    reducers: [AllOrderTotals, CustomerOrderTotals, OrdersStreamTotals, PriorityCustomerOrderTotals],
+    readModels: [Totals, SourceTotals, StreamTotals, CombinedTotals], seeders: [], constraints: [], projections: [],
+    webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+};
+
+async function eventually(accept: () => boolean | Promise<boolean>, timeoutMs = 30_000): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (!await accept()) {
+        if (Date.now() > deadline) throw new Error('Timed out waiting for filtered observers');
+        await new Promise(resolve => setTimeout(resolve, 250));
+    }
+}
+
+// A final matching event is an ordered barrier in every observer's shared source partition.
+// The unrestricted observers also prove all excluded input was actually committed and delivered.
+const expected = [
+    ['wrong-source', 'wrong-stream', 'wrong-tag', 'no-tag', 'priority', 'barrier'],
+    ['wrong-stream', 'wrong-tag', 'no-tag', 'priority', 'barrier'],
+    ['wrong-source', 'wrong-tag', 'no-tag', 'priority', 'barrier'],
+    ['priority', 'barrier']
+];
+
+describe.skipIf(!connectionString && !process.env.CI)('when filtering reactor and reducer delivery against a kernel', () => {
+    const storeName = `Filters${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    const sourceId = randomUUID();
+    let client: ChronicleClient;
+    let store: IEventStore;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [], clientArtifactsProvider: artifacts
+        }));
+        store = await client.getEventStore(storeName);
+        const connection = (store as unknown as { _connection: ChronicleConnection })._connection;
+        await eventually(async () => {
+            const observers = await Promise.all([...artifacts.reactors, ...artifacts.reducers].map(type =>
+                connection.observers.getObserverInformation({ EventStore: storeName, Namespace: 'Default',
+                    ObserverId: type.name, EventSequenceId: 'event-log' })));
+            return observers.every(observer => observer.IsSubscribed && observer.RunningState === ObserverRunningState.Active);
+        });
+        const input = [
+            { name: 'wrong-source', source: 'Other', stream: 'Orders', tags: ['vip'] },
+            { name: 'wrong-stream', source: 'Customers', stream: 'Other', tags: ['vip'] },
+            { name: 'wrong-tag', source: 'Customers', stream: 'Orders', tags: ['regular'] },
+            { name: 'no-tag', source: 'Customers', stream: 'Orders', tags: [] },
+            { name: 'priority', source: 'Customers', stream: 'Orders', tags: ['priority'] },
+            { name: 'barrier', source: 'Customers', stream: 'Orders', tags: ['vip'] }
+        ];
+        const results = await store.eventLog.appendMany(input.map(item => ({ eventSourceId: sourceId,
+            event: Object.assign(new FilteredOrderPlaced(), { name: item.name }), eventSourceType: item.source,
+            eventStreamType: item.stream, eventStreamId: 'Default', tags: item.tags })));
+        should(results).have.lengthOf(input.length);
+        should(results.every(result => result.isSuccess)).be.true;
+        await eventually(() => [...artifacts.reactors].every(type => reactorCalls.get(type.name)?.at(-1) === 'barrier') &&
+            [...artifacts.reducers].every(type => reducerCalls.get(type.name)?.at(-1) === 'barrier'));
+        await eventually(async () => {
+            const states = await Promise.all(artifacts.readModels.map(type => store.readModels.findInstanceById(type, sourceId)));
+            return states.every(state => (state as Totals | null)?.lastName === 'barrier');
+        });
+    });
+    afterAll(() => client?.dispose());
+
+    for (let index = 0; index < expected.length; index++) {
+        it(`should deliver only the selected events to reactor ${artifacts.reactors[index].name}`, () => {
+            should(reactorCalls.get(artifacts.reactors[index].name)).deep.equal(expected[index]);
+        });
+        it(`should deliver only the selected events to reducer ${artifacts.reducers[index].name}`, async () => {
+            should(reducerCalls.get(artifacts.reducers[index].name)).deep.equal(expected[index]);
+            const state = await store.readModels.getInstanceById(artifacts.readModels[index], sourceId) as Totals;
+            should(state.count).equal(expected[index].length);
+        });
+    }
+});