@cratis/chronicle 6.39.0 → 6.41.0

package/telemetry/for_ChronicleTelemetry/when_naming_spans/with_per_client_modes.spec.ts

@@ -0,0 +1,138 @@
+// 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 } from 'vitest';
+import { SpanKind } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { ChronicleClient } from '../../../ChronicleClient.js';
+import type { IEventSequence } from '../../../eventSequences/IEventSequence.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { EventSequenceNumber } from '../../../eventSequences/EventSequenceNumber.js';
+import { clientVersion } from '../../../connection/clientVersion.js';
+import { client } from '../given/a_client.fixture.js';
+import { Recorded } from '../given/an_event_sequence.fixture.js';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { legacySpans, conventionSpans } from '../given/a_span_name_registry.fixture.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+const sequenceNumber = new EventSequenceNumber(42n);
+const operations = {
+    append: (sequence: IEventSequence) => sequence.append('source', new Recorded()),
+    appendMany: (sequence: IEventSequence) => sequence.appendMany('source', [new Recorded(), new Recorded()]),
+    getTailSequenceNumber: (sequence: IEventSequence) => sequence.getTailSequenceNumber(),
+    hasEventsFor: (sequence: IEventSequence) => sequence.hasEventsFor('source'),
+    getForEventSourceIdAndEventTypes: (sequence: IEventSequence) => sequence.getForEventSourceIdAndEventTypes('source', [Recorded]),
+    getFromSequenceNumber: (sequence: IEventSequence) => sequence.getFromSequenceNumber(sequenceNumber),
+    redact: (sequence: IEventSequence) => sequence.redact(sequenceNumber, 'reason'),
+    redactForEventSource: (sequence: IEventSequence) => sequence.redactForEventSource('source', 'reason'),
+    completeStream: (sequence: IEventSequence) => sequence.completeStream('stream-type', 'stream-id')
+};
+
+for (const spanNames of [undefined, 'legacy', 'convention'] as const) {
+    const expected = spanNames === 'convention' ? conventionSpans : legacySpans;
+    for (const sequenceId of [EventSequenceId.eventLog, new EventSequenceId('dynamic')]) {
+        for (const operation of Object.keys(operations) as (keyof typeof operations)[]) {
+            describe(`when naming ${operation} on ${sequenceId.value} with ${spanNames ?? 'default'} names`, () => {
+                let instance: ChronicleClient;
+                let span: ReadableSpan;
+                beforeEach(async () => {
+                    instance = client(spanNames === undefined ? undefined : { spanNames });
+                    const store = await instance.getEventStore('store', 'namespace');
+                    const sequence = sequenceId === EventSequenceId.eventLog ? store.eventLog : store.getEventSequence(sequenceId);
+                    telemetry.spans.reset();
+                    await operations[operation](sequence);
+                    span = telemetry.spans.getFinishedSpans()[0];
+                });
+                afterEach(() => instance.dispose());
+                it('should emit exactly one client span with the selected name', () => {
+                    telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
+                    span.name.should.equal(expected[operation]);
+                    span.kind.should.equal(SpanKind.CLIENT);
+                });
+                it('should retain the versioned shared instrumentation scope', () => {
+                    span.instrumentationScope.name.should.equal('Cratis.Chronicle.Client');
+                    should.equal(span.instrumentationScope.version, clientVersion);
+                });
+                it('should retain both attribute families', () => {
+                    span.attributes.should.include({
+                        'chronicle.event_store': 'store', 'cratis.event_store.name': 'store',
+                        'chronicle.namespace': 'namespace', 'cratis.event_store.namespace': 'namespace',
+                        'chronicle.event_sequence_id': sequenceId.value, 'cratis.event_sequence.id': sequenceId.value
+                    });
+                });
+            });
+        }
+    }
+
+    for (const operation of ['getEventStore', 'getEventStores', 'getNamespaces'] as const) {
+        describe(`when naming ${operation} with ${spanNames ?? 'default'} names`, () => {
+            let instance: ChronicleClient;
+            let span: ReadableSpan;
+            beforeEach(async () => {
+                instance = client(spanNames === undefined ? undefined : { spanNames });
+                if (operation === 'getNamespaces') {
+                    const store = await instance.getEventStore('store', 'namespace');
+                    telemetry.spans.reset();
+                    await store.getNamespaces();
+                } else if (operation === 'getEventStore') {
+                    await instance.getEventStore('store', 'namespace');
+                } else {
+                    await instance.getEventStores();
+                }
+                span = telemetry.spans.getFinishedSpans()[0];
+            });
+            afterEach(() => instance.dispose());
+            it('should emit exactly one client span with the selected name and shared scope', () => {
+                telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
+                span.name.should.equal(expected[operation]);
+                span.kind.should.equal(SpanKind.CLIENT);
+                span.instrumentationScope.name.should.equal('Cratis.Chronicle.Client');
+                should.equal(span.instrumentationScope.version, clientVersion);
+            });
+            if (operation !== 'getEventStores') {
+                it('should retain both event store attributes', () => {
+                    span.attributes.should.include({ 'chronicle.event_store': 'store', 'cratis.event_store.name': 'store' });
+                });
+            }
+        });
+    }
+}
+
+describe('when interleaving two clients with different span naming modes', () => {
+    let legacy: ChronicleClient;
+    let convention: ChronicleClient;
+    let spans: ReadableSpan[];
+    beforeEach(async () => {
+        legacy = client({ spanNames: 'legacy' });
+        convention = client({ spanNames: 'convention' });
+        const [legacyStore, conventionStore] = await Promise.all([
+            legacy.getEventStore('legacy-store'), convention.getEventStore('convention-store')
+        ]);
+        await Promise.all([convention.getEventStores(), legacy.getEventStores()]);
+        await Promise.all([legacyStore.getNamespaces(), conventionStore.getNamespaces()]);
+        await conventionStore.eventLog.append('source', new Recorded());
+        await legacyStore.eventLog.append('source', new Recorded());
+        const id = new EventSequenceId('dynamic');
+        await legacyStore.getEventSequence(id).append('source', new Recorded());
+        await conventionStore.getEventSequence(id).append('source', new Recorded());
+        await legacy.getEventStore('legacy-store');
+        await convention.getEventStore('convention-store');
+        spans = telemetry.spans.getFinishedSpans();
+    });
+    afterEach(() => { legacy.dispose(); convention.dispose(); });
+    it('should keep each client and its cached stores in its own mode', () => {
+        spans.should.have.lengthOf(12);
+        spans.filter(span => span.attributes['cratis.event_store.name'] === 'legacy-store').map(span => span.name).should.deep.equal([
+            legacySpans.getEventStore, legacySpans.getNamespaces, legacySpans.append, legacySpans.append, legacySpans.getEventStore
+        ]);
+        spans.filter(span => span.attributes['cratis.event_store.name'] === 'convention-store').map(span => span.name).should.deep.equal([
+            conventionSpans.getEventStore, conventionSpans.getNamespaces, conventionSpans.append, conventionSpans.append, conventionSpans.getEventStore
+        ]);
+        spans.map(span => span.name).should.include(legacySpans.getEventStores).and.include(conventionSpans.getEventStores);
+    });
+    it('should use the same tracer scope in both modes', () => {
+        new Set(spans.map(span => `${span.instrumentationScope.name}/${span.instrumentationScope.version}`)).should.deep.equal(
+            new Set([`Cratis.Chronicle.Client/${clientVersion}`]));
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_product_attributes/with_both_naming_modes.spec.ts

@@ -0,0 +1,52 @@
+// 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 } from 'vitest';
+import type { Attributes } from '@opentelemetry/api';
+import type { ChronicleClient } from '../../../ChronicleClient.js';
+import { client } from '../given/a_client.fixture.js';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+
+chai.should();
+const telemetry = telemetrySession();
+
+for (const spanNames of ['legacy', 'convention'] as const) {
+    for (const hasEvents of [true, false]) {
+        describe(`when recording event presence ${hasEvents} with ${spanNames} span names`, () => {
+            let instance: ChronicleClient;
+            let attributes: Attributes;
+            beforeEach(async () => {
+                instance = client({ spanNames });
+                const store = await instance.getEventStore('store');
+                telemetry.spans.reset();
+                await store.eventLog.hasEventsFor(hasEvents ? 'source' : 'empty');
+                attributes = telemetry.spans.getFinishedSpans()[0].attributes;
+            });
+            afterEach(() => instance.dispose());
+            it('should record the boolean under both the legacy and product-only names', () => {
+                attributes.should.include({
+                    'chronicle.has_events': hasEvents,
+                    'cratis.chronicle.event_sequence.has_events': hasEvents
+                });
+            });
+        });
+    }
+    describe(`when completing a stream with ${spanNames} span names`, () => {
+        let instance: ChronicleClient;
+        let attributes: Attributes;
+        beforeEach(async () => {
+            instance = client({ spanNames });
+            const store = await instance.getEventStore('store');
+            telemetry.spans.reset();
+            await store.eventLog.completeStream('orders', 'stream-1');
+            attributes = telemetry.spans.getFinishedSpans()[0].attributes;
+        });
+        afterEach(() => instance.dispose());
+        it('should record the stream type under both names', () => {
+            attributes.should.include({ 'chronicle.event_stream_type': 'orders', 'cratis.chronicle.event_stream.type': 'orders' });
+        });
+        it('should record the stream identifier under both names', () => {
+            attributes.should.include({ 'chronicle.event_stream_id': 'stream-1', 'cratis.chronicle.event_stream.id': 'stream-1' });
+        });
+    });
+}

package/telemetry/observeOperation.ts

@@ -6,9 +6,17 @@ import { ChronicleTracer } from '../Tracing.js';
 import { correlationIdManager } from '../correlation/index.js';
 import { CorrelationId } from '../correlation/CorrelationId.js';
 import { WellKnownTelemetryNames } from '../WellKnownTelemetryNames.js';
+import type { ChronicleTelemetryOptions } from './ChronicleTelemetryOptions.js';
 
 /** Opens one client span, scoping the resolved business correlation without generating a new one. */
-export function observeOperation<T>(name: string, action: (span: Span) => Promise<T>, correlationId?: { toString(): string }): Promise<T> {
+export function observeOperation<T>(
+    operation: keyof typeof WellKnownTelemetryNames.conventionSpans,
+    telemetry: ChronicleTelemetryOptions | undefined,
+    action: (span: Span) => Promise<T>,
+    correlationId?: { toString(): string }
+): Promise<T> {
+    const names = telemetry?.spanNames === 'convention' ? WellKnownTelemetryNames.conventionSpans : WellKnownTelemetryNames.spans;
+    const name = names[operation];
     const resolved = correlationId ? new CorrelationId(correlationId.toString()) : correlationIdManager.scoped;
     const run = () => {
         const active = context.active();

package/testing/EventScenario.ts

@@ -149,7 +149,7 @@ export class EventScenario {
         }
         const sequence = new InProcessEventSequence(options, eventTypes, constraints);
         this.eventSequence = sequence;
-        registerScenarioSeed(this, (source, events) => sequence.seed(source, events));
+        registerScenarioSeed(this, (source, events, options) => sequence.seed(source, events, options));
         this.given = new EventScenarioGivenBuilder(this);
         this.when = new EventScenarioWhenBuilder(this);
     }

package/testing/EventScenarioGiven.ts

@@ -1,13 +1,14 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { EventScenario } from './EventScenario.js';
 import { seedScenario } from './EventScenarioSeed.js';
 
 /** Seeds events in order through individual single appends, as in the .NET given builder. */
 export class EventScenarioGiven {
-    constructor(private readonly _scenario: EventScenario, private readonly _id: string) {}
+    constructor(private readonly _scenario: EventScenario, private readonly _id: string, private readonly _options?: AppendOptions) {}
     async events(...events: object[]): Promise<void> {
-        await seedScenario(this._scenario, this._id, events);
+        await seedScenario(this._scenario, this._id, events, this._options);
     }
 }

package/testing/EventScenarioGivenBuilder.ts

@@ -1,11 +1,12 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { EventScenario } from './EventScenario.js';
 import { EventScenarioGiven } from './EventScenarioGiven.js';
 
 /** Selects the source for setup events. */
 export class EventScenarioGivenBuilder {
     constructor(private readonly _scenario: EventScenario) {}
-    forEventSource(id: string): EventScenarioGiven { return new EventScenarioGiven(this._scenario, id); }
+    forEventSource(id: string, options?: AppendOptions): EventScenarioGiven { return new EventScenarioGiven(this._scenario, id, options); }
 }

package/testing/EventScenarioSeed.ts

@@ -1,17 +1,18 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { EventScenario } from './EventScenario.js';
 
-const seeders = new WeakMap<EventScenario, (source: string, events: object[]) => Promise<void>>();
+const seeders = new WeakMap<EventScenario, (source: string, events: object[], options?: AppendOptions) => Promise<void>>();
 
 /** Internal builder wiring; not exported by the testing package. */
-export function registerScenarioSeed(scenario: EventScenario, seed: (source: string, events: object[]) => Promise<void>): void {
+export function registerScenarioSeed(scenario: EventScenario, seed: (source: string, events: object[], options?: AppendOptions) => Promise<void>): void {
     seeders.set(scenario, seed);
 }
 
-export function seedScenario(scenario: EventScenario, source: string, events: object[]): Promise<void> {
+export function seedScenario(scenario: EventScenario, source: string, events: object[], options?: AppendOptions): Promise<void> {
     const seed = seeders.get(scenario);
     if (!seed) throw new Error('EventScenario setup requires a constructed scenario.');
-    return seed(source, events);
+    return seed(source, events, options);
 }

package/testing/EventScenarioWhen.ts

@@ -1,14 +1,15 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { AppendResult } from '../eventSequences/AppendResult.js';
 import type { EventScenario } from './EventScenario.js';
 
 /** A single act-phase append; the plural form is reserved for atomic batches. */
 export class EventScenarioWhen {
-    constructor(private readonly _scenario: EventScenario, private readonly _id: string) {}
-    async event(event: object): Promise<AppendResult> { return this._scenario.append(this._id, event); }
+    constructor(private readonly _scenario: EventScenario, private readonly _id: string, private readonly _options?: AppendOptions) {}
+    async event(event: object): Promise<AppendResult> { return this._scenario.append(this._id, event, this._options); }
     async events(...events: object[]): Promise<readonly AppendResult[]> {
-        return this._scenario.appendMany(this._id, events);
+        return this._scenario.appendMany(this._id, events, this._options);
     }
 }

package/testing/EventScenarioWhenBuilder.ts

@@ -1,11 +1,12 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { EventScenario } from './EventScenario.js';
 import { EventScenarioWhen } from './EventScenarioWhen.js';
 
 /** Selects the source for an act-phase append. */
 export class EventScenarioWhenBuilder {
     constructor(private readonly _scenario: EventScenario) {}
-    forEventSource(id: string): EventScenarioWhen { return new EventScenarioWhen(this._scenario, id); }
+    forEventSource(id: string, options?: AppendOptions): EventScenarioWhen { return new EventScenarioWhen(this._scenario, id, options); }
 }

package/testing/InProcessEventSequence.ts

@@ -17,6 +17,7 @@ import { EventTypeId } from '../events/EventTypeId.js';
 import { EventTypeGeneration } from '../events/EventTypeGeneration.js';
 import { Identity } from '../identity/Identity.js';
 import type { AppendOptions } from '../eventSequences/AppendOptions.js';
+import { singleAppendRoute } from './singleAppendRoute.js';
 import type { AppendResult } from '../eventSequences/AppendResult.js';
 import type { AppendedEventWithResult } from '../eventSequences/AppendedEventWithResult.js';
 import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
@@ -129,7 +130,7 @@ export class InProcessEventSequence implements IEventSequence {
     get appendedEvents(): readonly AppendedEvent[] { return Object.freeze(this._history.map(event => this.snapshot(event))); }
 
     /** Validate and stage all setup appends, then commit and notify in single-append order. */
-    async seed(source: string, events: object[]): Promise<void> {
+    async seed(source: string, events: object[], options?: AppendOptions): Promise<void> {
         if (this._setup || this._busy) throw this.unsupported('given.events', this.id.value, 'Overlapping setup calls are not fixture-backed.');
         this._setup = true;
         this._stagedSeeds = [];
@@ -138,7 +139,7 @@ export class InProcessEventSequence implements IEventSequence {
             for (const event of events) {
                 this._allowSeedAppend = true;
                 let pending: Promise<AppendResult>;
-                try { pending = this.append(source, event); }
+                try { pending = this.append(source, event, options); }
                 finally { this._allowSeedAppend = false; }
                 const result = await pending;
                 if (!result.isSuccess) throw new Error(`EventScenario given setup failed: ${JSON.stringify(result, (_, value) =>
@@ -167,7 +168,7 @@ export class InProcessEventSequence implements IEventSequence {
         try {
             if (!event || typeof event !== 'object') throw this.unsupported('append.event', this.id.value, 'Only registered event instances are supported.');
             if (!/^[A-Za-z0-9_-]+$/.test(eventSourceId)) throw this.unsupported('append.source', eventSourceId, 'Only simple source identifiers are fixture-backed.');
-            const route = this.singleAppendRoute(options, event.constructor.name);
+            const route = singleAppendRoute(options, event.constructor.name, (operation, artifact, reason) => this.unsupported(operation, artifact, reason));
             const metadata = this._catalog.get(event.constructor);
             if (!metadata) throw this.unsupported('append.event', event.constructor.name, 'Event is not in the selected, validated catalog.');
             let prepared: ReturnType<typeof prepareSingleAppend>;
@@ -397,26 +398,6 @@ export class InProcessEventSequence implements IEventSequence {
         }
     }
 
-    private singleAppendRoute(options: AppendOptions | undefined, artifact: string): { sourceType: string; streamType: string; streamId: string } {
-        if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
-            throw this.unsupported('append.options', artifact, 'Append options must be an object.');
-        }
-        if (options && (Reflect.ownKeys(options).some(key => !['sourceType', 'streamType', 'streamId'].includes(String(key))) ||
-            options.correlationId !== undefined || options.subject !== undefined || options.occurred !== undefined ||
-            options.eventSourceId !== undefined || options.concurrencyScope !== undefined || options.tags !== undefined ||
-            options.concurrencyScopes !== undefined)) {
-            throw this.unsupported('append.options', artifact, 'Only sourceType, streamType and streamId routing options are fixture-backed for single append.');
-        }
-        const route = { sourceType: options?.sourceType, streamType: options?.streamType, streamId: options?.streamId };
-        for (const [name, value] of Object.entries(route)) {
-            if (value !== undefined && (typeof value !== 'string' || !/^[A-Za-z0-9_-]*$/.test(value))) {
-                throw this.unsupported(`append.${name}`, String(value), 'Only simple routing identifiers or empty defaults are fixture-backed.');
-            }
-        }
-        // ts-proto omits empty strings; the append pipeline resolves omissions to these exact values.
-        return { sourceType: route.sourceType || 'Default', streamType: route.streamType || 'All', streamId: route.streamId || 'Default' };
-    }
-
     private validateBatchOptions(options?: AppendOptions): void {
         if (options === undefined) return;
         if (!options || typeof options !== 'object' || Array.isArray(options)) {

package/testing/ReactorScenario.ts

@@ -35,8 +35,8 @@ import { UnsupportedReactorOperation } from './UnsupportedReactorOperation.js';
 
 /** Live, ordered reactor deliveries over the fixture-proven EventScenario event boundary. */
 export class ReactorScenario {
-    readonly given: { forEventSource(id: string): { events(...events: object[]): Promise<void> } };
-    readonly when: { forEventSource(id: string): { events(...events: object[]): Promise<void> } };
+    readonly given: { forEventSource(id: string, options?: AppendOptions): { events(...events: object[]): Promise<void> } };
+    readonly when: { forEventSource(id: string, options?: AppendOptions): { events(...events: object[]): Promise<void> } };
     private readonly _events: EventScenario;
     private readonly _entries: ReturnType<typeof getReactorEventTypes>;
     private readonly _eventTypes: readonly Constructor[];
@@ -85,8 +85,8 @@ export class ReactorScenario {
         this._instance = _options.artifactActivator ? undefined : new (_reactor as new () => Record<string, Function>)();
         if (this._instance) this._validateInstance(this._instance);
         this._store = _options.servicesEventStore ?? this.scenarioStore();
-        this.given = { forEventSource: id => ({ events: (...events) => this.deliver(id, events, true) }) };
-        this.when = { forEventSource: id => ({ events: (...events) => this.deliver(id, events, false) }) };
+        this.given = { forEventSource: (id, options) => ({ events: (...events) => this.deliver(id, events, true, options) }) };
+        this.when = { forEventSource: (id, options) => ({ events: (...events) => this.deliver(id, events, false, options) }) };
     }
 
     private scenarioStore(): IEventStore {
@@ -171,7 +171,7 @@ export class ReactorScenario {
         throw new UnsupportedReactorOperation('redeliver', this._reactor.name, 'Retry and checkpoint semantics are not supported.');
     }
 
-    private async deliver(sourceId: string, input: object[], setup: boolean): Promise<void> {
+    private async deliver(sourceId: string, input: object[], setup: boolean, options?: AppendOptions): Promise<void> {
         if (this._failed) throw new UnsupportedReactorOperation('delivery.afterFailure', this._reactor.name,
             'A previous delivery failed; failed-partition retries are not supported.');
         if (this._busy) throw new UnsupportedReactorOperation('delivery.overlap', this._reactor.name, 'Concurrent deliveries have unproven ordering.');
@@ -182,9 +182,9 @@ export class ReactorScenario {
             }
             const before = this._events.appendedEvents.length;
             if (setup) {
-                await this._events.given.forEventSource(sourceId).events(...input);
+                await this._events.given.forEventSource(sourceId, options).events(...input);
             } else {
-                const results = await this._events.when.forEventSource(sourceId).events(...input);
+                const results = await this._events.when.forEventSource(sourceId, options).events(...input);
                 const failures = results.filter(result => !result.isSuccess);
                 if (failures.length) throw new Error(`ReactorScenario action append failed: ${JSON.stringify(failures, (_, value) =>
                     typeof value === 'bigint' ? value.toString() : value)}`);

package/testing/ReadModelScenario.ts

@@ -24,6 +24,8 @@ import type { ReadModelState } from './ReadModelState.js';
 import { ReducerReadModelProcessor } from './ReducerReadModelProcessor.js';
 import type { ScenarioEvent } from './ScenarioEvent.js';
 import type { EventScenario } from './EventScenario.js';
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
+import { singleAppendRoute } from './singleAppendRoute.js';
 import type { ReactorScenario } from './ReactorScenario.js';
 import { ProjectionReadModelProcessor } from './projections/ProjectionReadModelProcessor.js';
 import { UnsupportedProjectionOperation } from './projections/UnsupportedProjectionOperation.js';
@@ -124,8 +126,13 @@ export class ReadModelScenario<TReadModel extends object> {
     }
 
     /** Collects events for a source; subsequent reads replay the complete seeded history. */
-    collectEventsFor(id: string, events: readonly object[]): void {
+    collectEventsFor(id: string, events: readonly object[], options?: AppendOptions): void {
         if (this._observed) throw this.mixedHistory();
+        const route = singleAppendRoute(options, events[0]?.constructor.name ?? this._modelName);
+        if (route.sourceType !== 'Default' || route.streamType !== 'All' || route.streamId !== 'Default') {
+            throw new UnsupportedProjectionOperation(this._modelName, 'given.events', `${route.sourceType}/${route.streamType}/${route.streamId}`,
+                'seeded events must use the default event source type and stream; routed events require a kernel-backed test');
+        }
         for (const event of events) {
             const metadata = getEventTypeMetadata(event.constructor);
             if (!metadata) throw new Error(`Event '${event.constructor.name}' has no @eventType metadata.`);

package/testing/ReadModelScenarioGiven.ts

@@ -1,16 +1,18 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { ReadModelScenario } from './ReadModelScenario.js';
 
 /** Seeds events belonging to one event source, in the order provided. */
 export class ReadModelScenarioGiven<TReadModel extends object> {
     /** Creates a builder for the selected event source. */
-    constructor(private readonly _scenario: ReadModelScenario<TReadModel>, private readonly _eventSourceId: string) {}
+    constructor(private readonly _scenario: ReadModelScenario<TReadModel>, private readonly _eventSourceId: string,
+        private readonly _options?: AppendOptions) {}
 
     /** Adds events to the scenario without connecting to a Chronicle kernel. */
     events(...events: object[]): ReadModelScenario<TReadModel> {
-        this._scenario.collectEventsFor(this._eventSourceId, events);
+        this._scenario.collectEventsFor(this._eventSourceId, events, this._options);
         return this._scenario;
     }
 }

package/testing/ReadModelScenarioGivenBuilder.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import type { ReadModelScenario } from './ReadModelScenario.js';
 import { ReadModelScenarioGiven } from './ReadModelScenarioGiven.js';
 
@@ -9,7 +10,7 @@ export class ReadModelScenarioGivenBuilder<TReadModel extends object> {
     constructor(private readonly _scenario: ReadModelScenario<TReadModel>) {}
 
     /** Creates a builder for the selected event source. */
-    forEventSource(id: string): ReadModelScenarioGiven<TReadModel> {
-        return new ReadModelScenarioGiven(this._scenario, id);
+    forEventSource(id: string, options?: AppendOptions): ReadModelScenarioGiven<TReadModel> {
+        return new ReadModelScenarioGiven(this._scenario, id, options);
     }
 }

package/testing/for_EventScenario/given/routed_scenario.fixture.ts

@@ -0,0 +1,39 @@
+// 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 { field } from '@cratis/fundamentals';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import type { EventContext } from '../../../events/EventContext.js';
+import { reactor } from '../../../reactors/reactor.js';
+import { EventScenario, ReactorScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+
+@eventType('BuilderRouteClaim')
+export class Claim { @field(String) key: string; constructor(key: string) { this.key = key; } }
+@eventType('BuilderRouteEffect')
+export class Effect { @field(String) key: string; constructor(key: string) { this.key = key; } }
+@constraint('BuilderRouteKey')
+class ScopedKey {
+    define(builder: IConstraintBuilder) {
+        builder.perEventSourceType().perEventStreamType().perEventStreamId().unique(key => key.on(Claim, event => event.key));
+    }
+}
+@reactor('BuilderRouteReactor')
+export class RoutedReactor {
+    claim(event: Claim, context: EventContext) {
+        return new Effect(`${event.key}:${context.eventSourceType}/${context.eventStreamType}/${context.eventStreamId}`);
+    }
+}
+export const route = { sourceType: 'Customer', streamType: 'Orders', streamId: 'West' };
+export const artifacts = { eventTypes: [Claim, Effect], constraints: [ScopedKey] };
+export const createEvents = () => new EventScenario({ artifacts });
+export const createReactor = () => new ReactorScenario(RoutedReactor, { artifacts });
+export const routing = (context: EventContext) => ({ sourceType: context.eventSourceType, streamType: context.eventStreamType, streamId: context.eventStreamId });
+export async function rejection(action: () => unknown): Promise<UnsupportedEventSequenceOperation> {
+    return Promise.resolve().then(action).then(() => { throw new Error('Expected unsupported operation'); }, error => {
+        if (!(error instanceof UnsupportedEventSequenceOperation)) throw error;
+        return error;
+    });
+}