@cratis/chronicle 6.40.0 → 6.41.0

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

package/testing/for_EventScenario/when_using_routed_builders/with_routing_options.spec.ts

@@ -0,0 +1,116 @@
+// 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, vi } from 'vitest';
+import type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import { Claim, createEvents, rejection, route, routing } from '../given/routed_scenario.fixture.js';
+
+chai.should();
+describe('when seeding with routed builders', () => {
+    it('should record each setup route through single append without action results', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A', route).events(new Claim('Alpha'), new Claim('Beta'));
+        scenario.appendedEvents.map(event => routing(event.context)).should.deep.equal([route, route]);
+        scenario.results.should.have.lengthOf(0);
+        (await scenario.append('B', new Claim('Alpha'), route)).isSuccess.should.be.true;
+        (await scenario.append('B', new Claim('Beta'), route)).isSuccess.should.be.false;
+    });
+
+    it('should roll back routed setup and preserve claims in other scopes', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        await scenario.given.forEventSource('A').events(new Claim('DefaultKey'));
+        const before = scenario.appendedEvents;
+        await scenario.given.forEventSource('B', route).events(new Claim('Temporary'), new Claim('Taken')).then(
+            () => { throw new Error('Expected failed setup'); }, error => (error as Error).message.should.include('EventScenario given setup failed'));
+        scenario.appendedEvents.should.deep.equal(before);
+        scenario.results.should.have.lengthOf(0);
+        (await scenario.when.forEventSource('C', route).event(new Claim('Temporary'))).sequenceNumber.value.should.equal(2n);
+        (await scenario.when.forEventSource('D').event(new Claim('DefaultKey'))).isSuccess.should.be.false;
+    });
+});
+
+describe('when acting with routed builders', () => {
+    it('should preserve append metadata identically to direct atomic batches', async () => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.setSystemTime(new Date('2026-01-02T03:04:05.000Z'));
+        try {
+            const scenario = createEvents();
+            const direct = createEvents();
+            const subject = 'CustomerSubject';
+            const correlationId = '11111111-2222-3333-4444-555555555555';
+            const occurred = new Date('2025-12-01T12:34:56.000Z');
+            const tags = ['Priority', 'Routed'];
+            await scenario.when.forEventSource('A', { ...route, subject, correlationId, occurred, tags }).events(new Claim('Alpha'), new Claim('Beta'));
+            await direct.appendMany('A', [new Claim('Alpha'), new Claim('Beta')], { ...route, subject, correlationId, occurred, tags });
+            scenario.appendedEvents.map(event => event.context).should.deep.equal(direct.appendedEvents.map(event => event.context));
+        } finally { vi.useRealTimers(); }
+    });
+
+    it('should use the route for single actions and atomic batches', async () => {
+        const scenario = createEvents();
+        (await scenario.when.forEventSource('A', route).event(new Claim('Alpha'))).isSuccess.should.be.true;
+        const results = await scenario.when.forEventSource('B', { ...route, streamId: 'East' }).events(new Claim('Alpha'), new Claim('Beta'));
+        results.every(result => result.isSuccess).should.be.true;
+        scenario.appendedEvents.map(event => routing(event.context)).should.deep.equal([route,
+            { ...route, streamId: 'East' }, { ...route, streamId: 'East' }]);
+        scenario.results.should.have.lengthOf(3);
+    });
+
+    it('should honor every scoped dimension and reject only the matching route', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        for (const dimension of ['sourceType', 'streamType', 'streamId'] as const) {
+            (await scenario.when.forEventSource(`B-${dimension}`, { ...route, [dimension]: 'Other' }).event(new Claim('Taken'))).isSuccess.should.be.true;
+        }
+        const before = scenario.appendedEvents;
+        const results = await scenario.when.forEventSource('C', route).events(new Claim('Temporary'), new Claim('Taken'));
+        results.every(result => !result.isSuccess).should.be.true;
+        scenario.appendedEvents.should.deep.equal(before);
+        (await scenario.when.forEventSource('D', route).event(new Claim('Temporary'))).sequenceNumber.value.should.equal(4n);
+    });
+
+    it('should retain omitted routing and resolve empty strings to exact defaults', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A').events(new Claim('Given'));
+        await scenario.given.forEventSource('B', { sourceType: '', streamType: '', streamId: '' }).events(new Claim('Empty'));
+        await scenario.when.forEventSource('C').event(new Claim('Single'));
+        await scenario.when.forEventSource('D', {}).events(new Claim('Batch'));
+        scenario.appendedEvents.map(event => routing(event.context)).should.deep.equal(Array(4).fill({ sourceType: 'Default', streamType: 'All', streamId: 'Default' }));
+        (await scenario.when.forEventSource('E', { streamId: '' }).event(new Claim('Given'))).isSuccess.should.be.false;
+    });
+});
+
+describe('when routed builders receive unsupported options', () => {
+    it('should reject identically to their append path without changing history, results or notifications', async () => {
+        const scenario = createEvents();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        const before = scenario.appendedEvents;
+        const notifications = scenario.eventLog.appendOperations[Symbol.asyncIterator]();
+        const pending = notifications.next();
+        try {
+            const invalid: unknown[] = [null, [], { concurrencyScopes: {} }, { arbitrary: true }];
+            for (const dimension of ['sourceType', 'streamType', 'streamId'] as const) {
+                for (const value of [' ', 'a|b', 'é', '*', 'a:b', 'a\u0000b', 1, null]) invalid.push({ [dimension]: value });
+            }
+            for (const value of invalid) {
+                const options = value as AppendOptions;
+                const single = await rejection(() => scenario.append('B', new Claim('Other'), options));
+                (await rejection(() => scenario.given.forEventSource('B', options).events(new Claim('Other')))).message.should.equal(single.message);
+                (await rejection(() => scenario.when.forEventSource('B', options).event(new Claim('Other')))).message.should.equal(single.message);
+                const batch = await rejection(() => scenario.appendMany('B', [new Claim('Other')], options));
+                (await rejection(() => scenario.when.forEventSource('B', options).events(new Claim('Other')))).message.should.equal(batch.message);
+            }
+            const metadata = { tags: [] };
+            const single = await rejection(() => scenario.append('B', new Claim('Other'), metadata));
+            (await rejection(() => scenario.given.forEventSource('B', metadata).events(new Claim('Other')))).message.should.equal(single.message);
+            (await rejection(() => scenario.when.forEventSource('B', metadata).event(new Claim('Other')))).message.should.equal(single.message);
+            scenario.appendedEvents.should.deep.equal(before);
+            scenario.results.should.have.lengthOf(0);
+            (await scenario.eventLog.getNextSequenceNumber()).value.should.equal(1n);
+            const rejected = await scenario.when.forEventSource('B', route).event(new Claim('Taken'));
+            rejected.isSuccess.should.be.false;
+            (await pending).value![0].result.should.equal(rejected);
+        } finally { await notifications.return?.(); }
+    });
+});

package/testing/for_ReactorScenario/when_using_routed_builders/with_routing_options.spec.ts

@@ -0,0 +1,88 @@
+// 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 type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import { Claim, Effect, createEvents, createReactor, rejection, route, routing } from '../../for_EventScenario/given/routed_scenario.fixture.js';
+
+chai.should();
+describe('when delivering routed setup and action events', () => {
+    it('should preserve append metadata in handled and triggering contexts', async () => {
+        const scenario = createReactor();
+        const subject = 'CustomerSubject';
+        const correlationId = '11111111-2222-3333-4444-555555555555';
+        const occurred = new Date('2025-12-01T12:34:56.000Z');
+        const tags = ['Priority', 'Routed'];
+        await scenario.when.forEventSource('A', { ...route, subject, correlationId, occurred, tags }).events(new Claim('Alpha'), new Claim('Beta'));
+        const contexts = [...scenario.results.flatMap(result => result.handled), ...scenario.sideEffects.map(effect => effect.triggeringContext)];
+        contexts.map(context => ({ subject: context.subject, correlationId: context.correlationId, occurred: context.occurred,
+            tags: context.tags.map(tag => tag.value) })).should.deep.equal(Array(4).fill({ subject, correlationId, occurred, tags }));
+    });
+
+    it('should expose the recorded route in handled and triggering contexts', async () => {
+        const scenario = createReactor();
+        await scenario.given.forEventSource('A', route).events(new Claim('Given'));
+        await scenario.when.forEventSource('B', { ...route, streamId: 'East' }).events(new Claim('First'), new Claim('Second'));
+        const expected = [route, { ...route, streamId: 'East' }, { ...route, streamId: 'East' }];
+        scenario.appendedEvents.map(event => routing(event.context)).should.deep.equal(expected);
+        scenario.results.flatMap(result => result.handled.map(routing)).should.deep.equal(expected);
+        scenario.sideEffects.map(effect => routing(effect.triggeringContext)).should.deep.equal(expected);
+        scenario.sideEffects.map(effect => effect.triggeringContext).should.deep.equal(scenario.appendedEvents.map(event => event.context));
+        scenario.sideEffects.map(effect => effect.target.eventStreamId).should.deep.equal(['West', 'East', 'East']);
+        scenario.produced.map(effect => (effect as Effect).key).should.deep.equal([
+            'Given:Customer/Orders/West', 'First:Customer/Orders/East', 'Second:Customer/Orders/East']);
+    });
+
+    it('should enforce scoped constraints before delivering any rejected action batch', async () => {
+        const scenario = createReactor();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        await scenario.when.forEventSource('B', { ...route, streamId: 'East' }).events(new Claim('Taken'));
+        const before = scenario.appendedEvents;
+        await scenario.when.forEventSource('C', route).events(new Claim('Temporary'), new Claim('Taken')).then(
+            () => { throw new Error('Expected constraint rejection'); }, error => (error as Error).message.should.include('ReactorScenario action append failed'));
+        scenario.appendedEvents.should.deep.equal(before);
+        scenario.produced.should.have.lengthOf(2);
+        scenario.results.should.have.lengthOf(2);
+        await scenario.when.forEventSource('D', route).events(new Claim('Temporary'));
+        scenario.appendedEvents[2].context.sequenceNumber.should.equal(2n);
+    });
+
+    it('should roll back rejected routed setup before recording effects or delivery outcomes', async () => {
+        const scenario = createReactor();
+        await scenario.given.forEventSource('A', route).events(new Claim('Taken'));
+        await scenario.given.forEventSource('B', route).events(new Claim('Temporary'), new Claim('Taken')).then(
+            () => { throw new Error('Expected failed setup'); }, error => (error as Error).message.should.include('EventScenario given setup failed'));
+        scenario.appendedEvents.should.have.lengthOf(1);
+        scenario.produced.should.have.lengthOf(1);
+        scenario.results.should.have.lengthOf(1);
+        await scenario.when.forEventSource('C', route).events(new Claim('Temporary'));
+        scenario.appendedEvents[1].context.sequenceNumber.should.equal(1n);
+    });
+
+    it('should keep default routing for omitted and empty route options', async () => {
+        const scenario = createReactor();
+        await scenario.given.forEventSource('A').events(new Claim('Given'));
+        await scenario.when.forEventSource('B', { sourceType: '', streamType: '', streamId: '' }).events(new Claim('Action'));
+        scenario.results.flatMap(result => result.handled.map(routing)).should.deep.equal(Array(2).fill({ sourceType: 'Default', streamType: 'All', streamId: 'Default' }));
+    });
+});
+
+describe('when reactor builders receive unsupported routing', () => {
+    it('should reject through append validation without delivering or poisoning the next action', async () => {
+        const scenario = createReactor();
+        const direct = createEvents();
+        for (const value of [null, [], { sourceType: 1 }, { streamType: 'a|b' }, { streamId: ' ' }, { arbitrary: true }]) {
+            const options = value as AppendOptions;
+            const single = await rejection(() => direct.append('A', new Claim('Other'), options));
+            (await rejection(() => scenario.given.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(single.message);
+            const batch = await rejection(() => direct.appendMany('A', [new Claim('Other')], options));
+            (await rejection(() => scenario.when.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(batch.message);
+        }
+        scenario.appendedEvents.should.have.lengthOf(0);
+        scenario.results.should.have.lengthOf(0);
+        scenario.sideEffects.should.have.lengthOf(0);
+        await scenario.when.forEventSource('A', route).events(new Claim('Accepted'));
+        scenario.appendedEvents[0].context.sequenceNumber.should.equal(0n);
+        scenario.results[0].completed.should.be.true;
+    });
+});

package/testing/for_ReadModelScenario/when_seeding_with_options/with_route_validation.spec.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import { reducer } from '../../../reducers/reducer.js';
+import { ReadModelScenario, UnsupportedProjectionOperation } from '../../index.js';
+import { Claim, createEvents, rejection, route } from '../../for_EventScenario/given/routed_scenario.fixture.js';
+
+chai.should();
+class Count { claimed = 0; }
+class Counter { claim(_event: Claim, current: Count | undefined): Count { return { claimed: (current?.claimed ?? 0) + 1 }; } }
+reducer('BuilderRouteCounter', undefined, Count)(Counter);
+const create = () => new ReadModelScenario(Count, { eventTypes: [Claim], reducers: [Counter], projections: [] });
+
+describe('when read-model setup receives route options', () => {
+    it('should preserve default setup with omitted, explicit or empty defaults', async () => {
+        const scenario = create();
+        scenario.given.forEventSource('A').events(new Claim('First'));
+        scenario.given.forEventSource('A', { sourceType: '', streamType: '', streamId: '' }).events(new Claim('Second'));
+        scenario.given.forEventSource('A', { sourceType: 'Default', streamType: 'All', streamId: 'Default' }).events(new Claim('Third'));
+        (await scenario.instance)!.claimed.should.equal(3);
+    });
+
+    it('should reuse single-append rejection messages without collecting unsupported input', async () => {
+        const scenario = create();
+        const events = createEvents();
+        for (const value of [{ sourceType: ' ' }, { streamType: null }, { streamId: 1 }, { tags: [] }, { arbitrary: true }, null, []]) {
+            const options = value as AppendOptions;
+            const error = await rejection(() => events.append('A', new Claim('Other'), options));
+            (await rejection(() => scenario.given.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(error.message);
+        }
+        ((await scenario.instance) === null).should.be.true;
+    });
+
+    it('should retain the unproven routed read-model boundary instead of simulating projection routing', async () => {
+        const scenario = create();
+        (() => scenario.given.forEventSource('A', route).events(new Claim('Other'))).should.throw(UnsupportedProjectionOperation, 'routed events');
+        scenario.given.forEventSource('A').events(new Claim('Accepted'));
+        (await scenario.instance)!.claimed.should.equal(1);
+    });
+});

package/testing/singleAppendRoute.ts

@@ -0,0 +1,28 @@
+// 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 { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
+
+/** The fixture-proven single-append route boundary, shared with read-model setup. */
+export function singleAppendRoute(options: AppendOptions | undefined, artifact: string,
+    unsupported = (operation: string, artifact: string, reason: string) => new UnsupportedEventSequenceOperation(operation, artifact, reason)
+): { sourceType: string; streamType: string; streamId: string } {
+    if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+        throw 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 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 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' };
+}