@cratis/chronicle 6.45.0 → 6.47.0

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

package/reducers/Reducers.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 { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle.js';
 import { IReducers } from './IReducers.js';
@@ -347,8 +349,8 @@ export class Reducers implements IReducers {
                         Tags: getTagsFor(reducerType).map(t => t.value),
                         Filters: {
                             FilterTags: getFilterTagsFor(reducerType).map(t => t.value),
-                            EventSourceType: '',
-                            EventStreamType: 'All'
+                            EventSourceType: getEventSourceTypeFor(reducerType),
+                            EventStreamType: getEventStreamTypeFor(reducerType)
                         }
                     }
                 },

package/testing/ReactorScenario.ts

@@ -13,6 +13,8 @@ import type { AppendedEvent } from '../events/AppendedEvent.js';
 import type { EventContext } from '../events/EventContext.js';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
 import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
+import { getEventSourceTypeFor } from '../events/eventSourceTypeDecorator.js';
+import { getDeclaredEventStreamTypeFor, getEventStreamTypeFor } from '../events/eventStreamTypeDecorator.js';
 import type { IEventLog } from '../eventSequences/IEventLog.js';
 import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
 import type { AppendOptions } from '../eventSequences/AppendOptions.js';
@@ -63,6 +65,12 @@ export class ReactorScenario {
         if (getFilterTagsFor(_reactor).length) {
             throw new UnsupportedReactorOperation('reactor.filterEventsByTag', _reactor.name, 'Tag-filtered delivery is not fixture-backed.');
         }
+        if (getEventSourceTypeFor(_reactor) !== '') {
+            throw new UnsupportedReactorOperation('reactor.eventSourceType', _reactor.name, 'Source-type-filtered delivery is not fixture-backed.');
+        }
+        if (getEventStreamTypeFor(_reactor) !== 'All') {
+            throw new UnsupportedReactorOperation('reactor.eventStreamType', _reactor.name, 'Stream-type-filtered delivery is not fixture-backed.');
+        }
         if (_options.commandTypes?.length) {
             throw new UnsupportedReactorOperation('options.commandTypes', _reactor.name, 'Command classification belongs to the explicit-composition increment.');
         }
@@ -282,7 +290,8 @@ export class ReactorScenario {
         if (result == null) return;
         const items = Array.isArray(result) ? result : [result];
         const events = normalizeReactorSideEffects(result, context.eventSourceId,
-            context.eventStreamType ?? 'Default', context.eventStreamId ?? context.eventSourceId);
+            context.eventStreamType ?? 'Default', context.eventStreamId ?? context.eventSourceId,
+            getEventSourceTypeFor(this._reactor), getDeclaredEventStreamTypeFor(this._reactor));
         if (items.length !== events.length || events.some(entry => !this._eventTypes.includes(entry.event.constructor as Constructor))) {
             throw new UnsupportedReactorOperation('handler.return', this._reactor.name,
                 'Only registered events and production EventForEventSourceId wrappers may be recorded; commands and unknown values are unsupported.');

package/testing/ReducerReadModelProcessor.ts

@@ -3,6 +3,10 @@
 
 import type { Constructor } from '@cratis/fundamentals';
 import { ReducerEventDispatcher } from '../reducers/ReducerEventDispatcher.js';
+import { getEventSourceTypeFor } from '../events/eventSourceTypeDecorator.js';
+import { getEventStreamTypeFor } from '../events/eventStreamTypeDecorator.js';
+import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
+import { UnsupportedReducerOperation } from './UnsupportedReducerOperation.js';
 import type { IReadModelProcessor } from './IReadModelProcessor.js';
 import type { ReadModelState } from './ReadModelState.js';
 import type { ScenarioEvent } from './ScenarioEvent.js';
@@ -12,6 +16,15 @@ export class ReducerReadModelProcessor<TReadModel extends object> implements IRe
     private readonly _dispatcher: ReducerEventDispatcher;
 
     constructor(private readonly _readModelType: Constructor<TReadModel>, private readonly _reducerType: Constructor, eventTypes: Constructor[]) {
+        if (getFilterTagsFor(_reducerType).length) {
+            throw new UnsupportedReducerOperation('reducer.filterEventsByTag', _reducerType.name, 'Tag-filtered delivery is not fixture-backed.');
+        }
+        if (getEventSourceTypeFor(_reducerType) !== '') {
+            throw new UnsupportedReducerOperation('reducer.eventSourceType', _reducerType.name, 'Source-type-filtered delivery is not fixture-backed.');
+        }
+        if (getEventStreamTypeFor(_reducerType) !== 'All') {
+            throw new UnsupportedReducerOperation('reducer.eventStreamType', _reducerType.name, 'Stream-type-filtered delivery is not fixture-backed.');
+        }
         this._dispatcher = new ReducerEventDispatcher(_reducerType, eventTypes);
     }
 

package/testing/UnsupportedReducerOperation.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** An operation whose kernel/observer semantics have not been established for this scenario. */
+export class UnsupportedReducerOperation extends Error {
+    constructor(readonly operation: string, readonly artifact: string, reason: string) {
+        super(`Unsupported reducer operation '${operation}' for '${artifact}': ${reason} Use a kernel-backed test.`);
+        this.name = 'UnsupportedReducerOperation';
+    }
+}

package/testing/for_ReactorScenario/when_recording_side_effects/with_declared_stream_type.spec.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { eventStreamType } from '../../../events/eventStreamTypeDecorator.js';
+import type { EventForEventSourceId } from '../../../eventSequences/EventForEventSourceId.js';
+import type { IEventLog } from '../../../eventSequences/IEventLog.js';
+import { reactor } from '../../../reactors/reactor.js';
+import { dispatchReactorSideEffects } from '../../../reactors/ReactorSideEffects.js';
+import { ReactorScenario } from '../../ReactorScenario.js';
+
+chai.should();
+@eventType('scenario-type-side-effect-input')
+class Input { @field(String) name = 'input'; }
+@eventType('scenario-type-side-effect-output')
+class Outbound { @field(String) name = 'output'; }
+const bare = new Outbound();
+const explicit = { eventSourceId: 'other', event: new Outbound(), eventSourceType: 'explicit-source', eventStreamType: 'explicit-stream' };
+const omitted = { eventSourceId: 'omitted', event: new Outbound() };
+
+@reactor('scenario-type-side-effects')
+@eventStreamType('All')
+class AllStreamsReactor { input() { return [bare, explicit, omitted]; } }
+
+// Non-default filters still require kernel-backed delivery. An explicit unrestricted stream
+// decorator exercises declared side-effect metadata without pretending to implement filtering.
+describe('when recording side effects with an explicit unrestricted stream decorator', () => {
+    let scenario: ReactorScenario;
+    let appended: EventForEventSourceId[];
+    beforeEach(async () => {
+        scenario = new ReactorScenario(AllStreamsReactor, { artifacts: { eventTypes: [Input, Outbound] }, constraints: 'disabled' });
+        await scenario.when.forEventSource('trigger').events(new Input());
+        const eventLog = { appendMany: vi.fn(async (events: EventForEventSourceId[]) => {
+            appended = events;
+            return [{ isSuccess: true, errors: [], constraintViolations: [] }];
+        }) } as unknown as IEventLog;
+        await dispatchReactorSideEffects(eventLog, [bare, explicit, omitted], scenario.sideEffects[0].triggeringContext,
+            AllStreamsReactor, 'store', 'namespace');
+    });
+    it('should record the same target metadata as production dispatch', () => {
+        scenario.sideEffects.map(effect => effect.target).should.deep.equal(appended);
+        scenario.sideEffects[0].target.eventStreamType!.should.equal('All');
+    });
+    it('should preserve explicitly targeted events instead of inheriting reactor metadata', () => {
+        scenario.sideEffects[1].target.should.equal(explicit);
+        scenario.sideEffects[2].target.should.equal(omitted);
+    });
+});

package/testing/for_observerScenarios/when_selecting_filters/with_reducer_tag_filters.spec.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { filterEventsByTag, reducer, tag } from '../../../index.js';
+import { ReadModelScenario, UnsupportedReducerOperation } from '../../index.js';
+
+chai.should();
+class State { count = 0; }
+let created = false;
+@reducer('tag-filtered-scenario', undefined, State)
+@filterEventsByTag('vip')
+class TagFiltered {
+    constructor() { created = true; }
+}
+class InheritedTagFiltered extends TagFiltered {}
+@reducer('label-only-scenario', undefined, State)
+@tag('vip')
+class Labeled {}
+@reducer('empty-tag-filter-scenario', undefined, State)
+@filterEventsByTag('')
+class EmptyFilter {}
+
+for (const type of [TagFiltered, InheritedTagFiltered]) {
+    describe(`when creating a reducer scenario for ${type.name}`, () => {
+        it('should reject tag-filtered delivery before activating the reducer', () => {
+            created = false;
+            try {
+                new ReadModelScenario(State, { reducers: [type], eventTypes: [], projections: [] });
+                throw new Error('Expected unsupported reducer operation');
+            } catch (error) {
+                (error instanceof UnsupportedReducerOperation).should.be.true;
+                const unsupported = error as UnsupportedReducerOperation;
+                unsupported.operation.should.equal('reducer.filterEventsByTag');
+                unsupported.artifact.should.equal(type.name);
+                unsupported.message.should.contain('Tag-filtered delivery is not fixture-backed.');
+                unsupported.message.should.contain('Use a kernel-backed test.');
+            }
+            created.should.be.false;
+        });
+    });
+}
+
+for (const type of [Labeled, EmptyFilter]) {
+    describe(`when creating a reducer scenario for ${type.name}`, () => {
+        it('should allow metadata that does not restrict delivery', () => {
+            (() => new ReadModelScenario(State, { reducers: [type], eventTypes: [], projections: [] })).should.not.throw();
+        });
+    });
+}

package/testing/for_observerScenarios/when_selecting_filters/with_source_and_stream_types.spec.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { eventSourceType, eventStreamType, reactor, reducer } from '../../../index.js';
+import { ReactorScenario, ReadModelScenario, UnsupportedReactorOperation, UnsupportedReducerOperation } from '../../index.js';
+
+chai.should();
+function should(value: unknown): ReturnType<typeof chai.expect> {
+    return (value as { should: ReturnType<typeof chai.expect> }).should;
+}
+
+class State { count = 0; }
+@reactor('source-filtered-scenario')
+@reducer('source-filtered-scenario', undefined, State)
+@eventSourceType('Customers')
+class SourceFiltered {}
+@reactor('stream-filtered-scenario')
+@reducer('stream-filtered-scenario', undefined, State)
+@eventStreamType('Orders')
+class StreamFiltered {}
+@reactor('default-filtered-scenario')
+@reducer('default-filtered-scenario', undefined, State)
+@eventSourceType('')
+@eventStreamType('All')
+class DefaultFiltered {}
+class InheritedSourceFiltered extends SourceFiltered {}
+
+for (const type of [SourceFiltered, StreamFiltered, InheritedSourceFiltered]) {
+    describe(`when creating observer scenarios for ${type.name}`, () => {
+        it('should reject unproven reactor filter semantics before delivering events', () => {
+            should(() => new ReactorScenario(type)).throw(UnsupportedReactorOperation, 'Use a kernel-backed test.');
+        });
+        it('should reject unproven reducer filter semantics before folding events', () => {
+            should(() => new ReadModelScenario(State, { reducers: [type], eventTypes: [], projections: [] }))
+                .throw(UnsupportedReducerOperation, 'Use a kernel-backed test.');
+        });
+    });
+}
+
+describe('when creating observer scenarios with explicit default filters', () => {
+    it('should allow the existing unrestricted reactor scenario', () => {
+        should(() => new ReactorScenario(DefaultFiltered, { artifacts: { eventTypes: [] } })).not.throw();
+    });
+    it('should allow the existing unrestricted reducer scenario', () => {
+        should(() => new ReadModelScenario(State, { reducers: [DefaultFiltered], eventTypes: [], projections: [] })).not.throw();
+    });
+});

package/testing/index.ts

@@ -7,6 +7,7 @@ export type { ReactorScenarioOptions } from './ReactorScenarioOptions.js';
 export type { ReactorDeliveryResult } from './ReactorDeliveryResult.js';
 export type { RecordedReactorSideEffect } from './RecordedReactorSideEffect.js';
 export { UnsupportedReactorOperation } from './UnsupportedReactorOperation.js';
+export { UnsupportedReducerOperation } from './UnsupportedReducerOperation.js';
 export type { EventScenarioOptions } from './EventScenarioOptions.js';
 export { EventScenarioGivenBuilder } from './EventScenarioGivenBuilder.js';
 export { EventScenarioGiven } from './EventScenarioGiven.js';

package/testing/projections/ProjectionReadModelProcessor.fixtures.spec.ts

@@ -38,6 +38,11 @@ const allFixtures = readdirSync(directory).filter(name => name.endsWith('.json')
     .map(name => ({ name, fixture: JSON.parse(readFileSync(new URL(name, directory), 'utf8')) as Fixture }));
 const fixtures = allFixtures.filter(({ fixture }) => fixture.kind === 'kernelSemantics');
 const guardErrors: Record<string, { type: string; message: string }> = {
+    'composite-parent-key-without-constant.json': { type: 'UnsupportedProjectionOperation', message: 'only a lowercase id with a fixture-backed string, GUID, or number/double schema' },
+    'composite-child-join-key-expression-parts.json': { type: 'UnsupportedProjectionOperation', message: 'only a lowercase id with a fixture-backed string, GUID, or number/double schema' },
+    'composite-key-expression-parts.json': { type: 'UnsupportedProjectionOperation', message: 'only a lowercase id with a fixture-backed string, GUID, or number/double schema' },
+    'composite-parent-key-expression-parts.json': { type: 'UnsupportedProjectionOperation', message: 'only a lowercase id with a fixture-backed string, GUID, or number/double schema' },
+    'composite-join-key-expression-parts.json': { type: 'UnsupportedProjectionOperation', message: 'join keys other than $eventSourceId' },
     'from-all-only.json': { type: 'UnsupportedProjectionOperation', message: 'subscribe-to-all projections require a kernel-backed test' },
     'from-all-mixed.json': { type: 'UnsupportedProjectionOperation', message: 'subscribe-to-all projections require a kernel-backed test' },
     'from-all-exclude-children.json': { type: 'UnsupportedProjectionOperation', message: 'subscribe-to-all projections require a kernel-backed test' },

package/testing/projections/for_ProjectionCapabilities/when_rejecting_composite_expression_parts.spec.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { chai, describe, it } from 'vitest';
+import type { ICompositeKeyBuilder } from '../../../projections/declarative/ICompositeKeyBuilder.js';
+import { ProjectionCapabilities } from '../ProjectionCapabilities.js';
+import { UnsupportedProjectionOperation } from '../UnsupportedProjectionOperation.js';
+import { Changed } from './given/Changed.js';
+import { Removed } from './given/Removed.js';
+import { compileDeclarative } from './given/compile.js';
+
+chai.should();
+
+for (const source of ['event property', 'context', 'source id', 'constant'] as const) {
+    for (const kind of ['root', 'parent', 'join'] as const) {
+        describe(`when validating a ${kind} composite key with a ${source} part before replay`, () => {
+            it('should reject the composite key rather than evaluate unproven semantics', () => {
+                const configure = <TEvent>(key: ICompositeKeyBuilder<{ part: string }, TEvent>) => {
+                    const part = key.set(target => target.part);
+                    if (source === 'context') return part.toEventContextProperty('subject');
+                    if (source === 'source id') return part.toEventSourceId();
+                    if (source === 'constant') return part.toValue('fixed');
+                    return part.to(event => (event as { name: string }).name);
+                };
+                const { compiled, definition } = compileDeclarative(builder => {
+                    if (kind === 'root') builder.from(Changed, from => from.usingCompositeKey(configure));
+                    if (kind === 'parent') builder.from(Changed, from => from.usingParentCompositeKey(configure));
+                    if (kind === 'join') builder
+                        .from(Changed, from => from.set(model => model.state).to(event => event.name))
+                        .join(Removed, join => join.on(model => model.state).usingCompositeKey(configure));
+                });
+                const section = kind === 'join' ? 'Join[capability-removed:1].Key'
+                    : kind === 'parent' ? 'From[capability-changed:1].ParentKey' : 'From[capability-changed:1].Key';
+                (() => ProjectionCapabilities.validate(compiled, definition)).should.throw(UnsupportedProjectionOperation)
+                    .with.property('message').that.includes(section);
+            });
+        });
+    }
+}