@cratis/chronicle 6.40.0 → 6.41.1

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';
@@ -36,6 +37,11 @@ import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOpe
 // JS trim() omits U+0085, which the kernel trims. Reject unproven non-ASCII whitespace and controls.
 const unprovenFilterCharacters = /[\u007f-\u009f]|(?=[^\x00-\x7f])\p{White_Space}/u;
 
+function resolveStoredSubject(subject: string | undefined, eventSourceId: string): string {
+    // Match the kernel's string.IsNullOrWhiteSpace, including U+0085 but not U+FEFF.
+    return subject && !/^\p{White_Space}*$/u.test(subject) ? subject : eventSourceId;
+}
+
 function matchesConstrainedValue(value: unknown, content: unknown): boolean {
     // Use production serialization for concepts, not their wrapper object's runtime type.
     // Keep rejecting other unproven conversions, such as a Date assigned to a string field.
@@ -129,7 +135,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 +144,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,13 +173,13 @@ 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), true);
             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>;
             let content: Record<string, unknown>;
             try {
-                prepared = prepareSingleAppend(event, this._correlationId ? { correlationId: this._correlationId() } : undefined);
+                prepared = prepareSingleAppend(event, { subject: options?.subject, correlationId: this._correlationId?.() });
                 content = this.checkedContent(event, prepared.content, 'append.content',
                     'Content differs from the event schema; null, missing and extra values are not proven.');
             } catch (error) {
@@ -206,7 +212,7 @@ export class InProcessEventSequence implements IEventSequence {
                     eventStore: this._store, namespace: this._namespace,
                     sequenceNumber: sequenceNumber.value, eventSourceId,
                     eventSourceType: route.sourceType, eventStreamType: route.streamType, eventStreamId: route.streamId,
-                    subject: eventSourceId, hash, causedBy: prepared.identity, observationState: EventObservationState.Initial,
+                    subject: resolveStoredSubject(prepared.subject, eventSourceId), hash, causedBy: prepared.identity, observationState: EventObservationState.Initial,
                     eventType: prepared.eventType, occurred, correlationId: prepared.correlationId.toString(),
                     causation: prepared.causationChain.map(item => ({ type: item.type.name, occurred: item.occurred, properties: { ...item.properties } })),
                     tags: prepared.tags.map(tag => new Tag(tag))
@@ -253,6 +259,9 @@ export class InProcessEventSequence implements IEventSequence {
                 }
                 const individual = entry as EventForEventSourceId;
                 if (individual.occurred !== undefined) this.checkedDate(individual.occurred, 'appendMany.occurred');
+                if (individual.subject !== undefined && individual.subject !== null && typeof individual.subject !== 'string') {
+                    throw this.unsupported('appendMany.subject', this.id.value, 'Subject must be a string.');
+                }
                 const tags = individual.tags;
                 if (tags && (!Array.isArray(tags) || tags.some(tag => typeof tag !== 'string'))) {
                     throw this.unsupported('appendMany.tags', this.id.value, 'Only plain string tags are fixture-backed.');
@@ -287,8 +296,8 @@ export class InProcessEventSequence implements IEventSequence {
                 this.validateSource(eventSourceId, 'appendMany.source');
                 const wire = eventsToAppend[index];
                 for (const [name, value] of Object.entries({ sourceType: wire.EventSourceType, streamType: wire.EventStreamType,
-                    streamId: wire.EventStreamId, subject: wire.Subject })) {
-                    const identifiers = name === 'subject' ? /^[A-Za-z0-9_-]+$/ : /^[A-Za-z0-9_-]*$/;
+                    streamId: wire.EventStreamId })) {
+                    const identifiers = /^[A-Za-z0-9_-]*$/;
                     if (value !== undefined && (typeof value !== 'string' || !identifiers.test(value))) {
                         throw this.unsupported(`appendMany.${name}`, String(value), 'Only simple metadata identifiers are fixture-backed.');
                     }
@@ -306,7 +315,7 @@ export class InProcessEventSequence implements IEventSequence {
                 const stored: AppendedEvent = { eventType, content, context: {
                     eventStore: this._store, namespace: this._namespace, sequenceNumber: sequenceNumber.value, eventSourceId,
                     eventSourceType: wire.EventSourceType || 'Default', eventStreamType: wire.EventStreamType || 'All',
-                    eventStreamId: wire.EventStreamId || 'Default', subject: wire.Subject, hash, causedBy: identity,
+                    eventStreamId: wire.EventStreamId || 'Default', subject: resolveStoredSubject(wire.Subject, eventSourceId), hash, causedBy: identity,
                     observationState: EventObservationState.Initial, eventType, occurred, correlationId: correlationId.toString(),
                     causation: batchCausationChain.map(item => ({ type: item.type.name, occurred: item.occurred, properties: { ...item.properties } })),
                     tags: wire.Tags.map(tag => new Tag(tag))
@@ -397,26 +406,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)) {
@@ -427,6 +416,9 @@ export class InProcessEventSequence implements IEventSequence {
             options.concurrencyScope !== undefined || options.concurrencyScopes !== undefined || options.eventSourceId !== undefined) {
             throw this.unsupported('appendMany.options', this.id.value, 'Concurrency and unrecognized metadata are not fixture-backed.');
         }
+        if (options.subject !== undefined && options.subject !== null && typeof options.subject !== 'string') {
+            throw this.unsupported('appendMany.subject', this.id.value, 'Subject must be a string.');
+        }
         if (options.tags && (!Array.isArray(options.tags) || options.tags.some(tag => typeof tag !== 'string'))) {
             throw this.unsupported('appendMany.tags', this.id.value, 'Only plain string tags are fixture-backed.');
         }

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.spec.ts

@@ -5,6 +5,7 @@ import { describe, expect, it } from 'vitest';
 import { ConceptAs, field, Guid } from '@cratis/fundamentals';
 import type { Constructor } from '@cratis/fundamentals';
 import { pii } from '../compliance/pii.js';
+import { subject } from '../compliance/subject.js';
 import { eventType } from '../events/eventTypeDecorator.js';
 import type { EventContext } from '../events/EventContext.js';
 import { fromEvent } from '../projections/modelBound/fromEvent.js';
@@ -219,6 +220,36 @@ describe('ReadModelScenario', () => {
         expect(await scenario.instance).toMatchObject({ subject: 'source-a' });
     });
 
+    it('maps a seeded event subject annotation to the projection Subject context', async () => {
+        class PersonalData {
+            @field(String) personId = 'person-a';
+        }
+        subject()(PersonalData.prototype, 'personId');
+        eventType('scenario-personal-data')(PersonalData);
+        class SubjectState { @field(String) id = ''; @field(String) subject = ''; }
+        fromEvent(PersonalData)(SubjectState);
+        setFromContext(PersonalData, 'subject')(SubjectState.prototype, 'subject');
+        const scenario = new ReadModelScenario(SubjectState, { ...artifacts, eventTypes: [PersonalData] });
+        scenario.given.forEventSource('source-a').events(new PersonalData());
+        expect(await scenario.instance).toMatchObject({ subject: 'person-a' });
+    });
+
+    it.each([undefined, null, '', ' \t\n', '\u0085\u2003'])('defaults an annotated subject %j to the event source', async value => {
+        class PersonalData {
+            // Keep null out of serialized content while exercising subject resolution.
+            get personId(): string | null | undefined { return value; }
+        }
+        field(String)(PersonalData.prototype, 'personId');
+        subject()(PersonalData.prototype, 'personId');
+        eventType('scenario-empty-subject')(PersonalData);
+        class SubjectState { @field(String) id = ''; @field(String) subject = ''; }
+        fromEvent(PersonalData)(SubjectState);
+        setFromContext(PersonalData, 'subject')(SubjectState.prototype, 'subject');
+        const scenario = new ReadModelScenario(SubjectState, { ...artifacts, eventTypes: [PersonalData] });
+        scenario.given.forEventSource('source-a').events(new PersonalData());
+        expect(await scenario.instance).toMatchObject({ subject: 'source-a' });
+    });
+
     it('defaults a projection Hash and CausedBy mapping to kernel sentinels when the seed omits them', async () => {
         class ContextDefaults { @field(String) id = ''; @field(String) hash = ''; @field(String) causedByName = ''; }
         setFromContext(ItemAdded, 'hash')(ContextDefaults.prototype, 'hash');

package/testing/ReadModelScenario.ts

@@ -7,6 +7,7 @@ import type { Constructor } from '@cratis/fundamentals';
 import { DefaultClientArtifactsProvider } from '../artifacts/DefaultClientArtifactsProvider.js';
 import type { IClientArtifactsProvider } from '../artifacts/IClientArtifactsProvider.js';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
+import { resolveEventSubject } from '../compliance/resolveEventSubject.js';
 import { getFromEventMetadata } from '../projections/modelBound/fromEvent.js';
 import { getRemovedWithClassMetadata } from '../projections/modelBound/removedWith.js';
 import { getRemovedWithJoinClassMetadata } from '../projections/modelBound/removedWithJoin.js';
@@ -24,6 +25,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,18 +127,26 @@ 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.`);
             // The kernel delivers JSON objects, not instances of decorated event classes.
             const content: unknown = JSON.parse(JsonSerializer.serialize(event));
+            const subject = resolveEventSubject(event);
             this._events.push({
                 sourceId: id,
                 content,
                 context: {
                     eventSourceId: id,
+                    // Match the kernel's string.IsNullOrWhiteSpace, including U+0085 but not U+FEFF.
+                    subject: subject && !/^\p{White_Space}*$/u.test(subject) ? subject : id,
                     eventSourceType: 'Default',
                     eventStreamType: 'All',
                     eventStreamId: 'Default',

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_appending_scoped_constraints/with_unproven_operations.spec.ts

@@ -83,7 +83,7 @@ describe('when a scoped append uses unsupported routes or metadata', () => {
                     await unsupported(() => scenario.appendMany('B', [new Claim('Beta')], options), `appendMany.${dimension}`);
                 }
             }
-            for (const options of [{ tags: [] }, { subject: '' }, { occurred: new Date() }, { correlationId: '00000000-0000-0000-0000-000000000001' },
+            for (const options of [{ tags: [] }, { occurred: new Date() }, { correlationId: '00000000-0000-0000-0000-000000000001' },
                 { concurrencyScopes: {} }, { eventSourceId: 'other' }, { arbitrary: true }]) {
                 await unsupported(() => scenario.append('B', new Claim('Beta'), options as AppendOptions), 'append.options');
             }

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,52 @@
+// 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 }, 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 list only supported seed options without collecting unsupported input', async () => {
+        const scenario = create();
+        for (const value of [{ tags: [] }, { arbitrary: true }, { subject: 'person-a' }]) {
+            const options = value as AppendOptions;
+            (await rejection(() => scenario.given.forEventSource('A', options).events(new Claim('Other')))).message.should.equal(
+                'UnsupportedEventSequenceOperation: append.options (Claim): Only sourceType, streamType, streamId options are supported for single append. Use a kernel-backed test.');
+        }
+        ((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);
+    });
+});