@cratis/chronicle 6.48.0 → 6.50.0

package/testing/InProcessEventSequence.ts

@@ -17,7 +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 { hasNamedTags, 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';
@@ -215,7 +215,8 @@ export class InProcessEventSequence implements IEventSequence {
                     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))
+                    tags: prepared.tags.map(tag => new Tag(tag)),
+                    namedTags: []
                 }
             };
             const violations = this.validateConstraints([...this._history, ...(this._stagedSeeds ?? [])], [stored]);
@@ -254,10 +255,13 @@ export class InProcessEventSequence implements IEventSequence {
             for (const entry of entries) {
                 if (typeof sourceOrEvents === 'string') break;
                 if (!entry || typeof entry !== 'object' || Reflect.ownKeys(entry).some(key =>
-                    !['eventSourceId', 'event', 'eventSourceType', 'eventStreamType', 'eventStreamId', 'subject', 'occurred', 'tags'].includes(String(key)))) {
+                    !['eventSourceId', 'event', 'eventSourceType', 'eventStreamType', 'eventStreamId', 'subject', 'occurred', 'tags', 'namedTags'].includes(String(key)))) {
                     throw this.unsupported('appendMany.entry', this.id.value, 'Unrecognized per-entry metadata.');
                 }
                 const individual = entry as EventForEventSourceId;
+                if (hasNamedTags(individual.namedTags)) {
+                    throw this.unsupported('appendMany.namedTags', this.id.value, 'Named tags are not fixture-backed.');
+                }
                 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.');
@@ -271,7 +275,8 @@ export class InProcessEventSequence implements IEventSequence {
             try {
                 const batchOptions: AppendOptions | undefined = shared?.correlationId === undefined && this._correlationId
                     ? { correlationId: this._correlationId(), sourceType: shared?.sourceType, streamType: shared?.streamType,
-                        streamId: shared?.streamId, subject: shared?.subject, occurred: shared?.occurred, tags: shared?.tags }
+                        streamId: shared?.streamId, subject: shared?.subject, occurred: shared?.occurred, tags: shared?.tags,
+                        namedTags: shared?.namedTags }
                     : shared;
                 if (batchOptions?.correlationId !== undefined) this.validateGuid(batchOptions.correlationId, 'appendMany.correlationId');
                 prepared = typeof sourceOrEvents === 'string'
@@ -318,7 +323,8 @@ export class InProcessEventSequence implements IEventSequence {
                     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))
+                    tags: wire.Tags.map(tag => new Tag(tag)),
+                    namedTags: []
                 } };
                 return { stored, result: this.success(sequenceNumber, event.constructor.name) };
             });
@@ -411,7 +417,10 @@ export class InProcessEventSequence implements IEventSequence {
         if (!options || typeof options !== 'object' || Array.isArray(options)) {
             throw this.unsupported('appendMany.options', this.id.value, 'Append options must be an object.');
         }
-        const allowed = ['correlationId', 'sourceType', 'streamType', 'streamId', 'subject', 'occurred', 'tags'];
+        if (hasNamedTags(options.namedTags)) {
+            throw this.unsupported('appendMany.namedTags', this.id.value, 'Named tags are not fixture-backed.');
+        }
+        const allowed = ['correlationId', 'sourceType', 'streamType', 'streamId', 'subject', 'occurred', 'tags', 'namedTags'];
         if (Reflect.ownKeys(options).some(key => !allowed.includes(String(key))) ||
             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.');
@@ -492,7 +501,8 @@ export class InProcessEventSequence implements IEventSequence {
             context: { ...event.context, eventType, occurred: new Date(event.context.occurred),
                 causedBy: causedBy && new Identity(causedBy.subject, causedBy.name, causedBy.userName, causedBy.onBehalfOf),
                 causation: event.context.causation.map(item => ({ ...item, occurred: item.occurred && new Date(item.occurred), properties: { ...item.properties } })),
-                tags: event.context.tags.map(item => new Tag(item.value)) }
+                tags: event.context.tags.map(item => new Tag(item.value)),
+                namedTags: [...(event.context.namedTags ?? [])] }
         };
     }
 

package/testing/ReactorScenario.ts

@@ -13,11 +13,13 @@ import type { AppendedEvent } from '../events/AppendedEvent.js';
 import type { EventContext } from '../events/EventContext.js';
 import { getEventTypeMetadata } from '../events/eventTypeDecorator.js';
 import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { getEventSourceTypeFor } from '../events/eventSourceTypeDecorator.js';
 import { getDeclaredEventStreamTypeFor, getEventStreamTypeFor } from '../events/eventStreamTypeDecorator.js';
 import type { IEventLog } from '../eventSequences/IEventLog.js';
 import type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
 import type { AppendOptions } from '../eventSequences/AppendOptions.js';
+import { ensureNamedTagBatchIsSupported } from '../eventSequences/ensureNamedTagBatchIsSupported.js';
 import { EventStoreName } from '../EventStoreName.js';
 import { EventStoreNamespaceName } from '../EventStoreNamespaceName.js';
 import type { IEventStore } from '../IEventStore.js';
@@ -297,6 +299,10 @@ export class ReactorScenario {
             throw new UnsupportedReactorOperation('handler.return', this._reactor.name,
                 'Only registered events and production EventForEventSourceId wrappers may be recorded; commands and unknown values are unsupported.');
         }
+        // Production validates named tags before appending, failing the delivery on an invalid tag; so does recording.
+        for (const target of events) mergeNamedTags(target.namedTags);
+        ensureNamedTagBatchIsSupported(events.some(event => mergeNamedTags(event.namedTags).length > 0),
+            events.some(event => event.eventSource !== undefined));
         for (const target of events) {
             this._effects.push(Object.freeze({ kind: 'event', value: target.event, target, triggeringContext: context,
                 handler, deliveryIndex }));

package/testing/for_EventScenario/when_appending_named_tags/with_named_tags.spec.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { NamedTag } from '../../../events/NamedTag.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+import { artifacts, Claim, createEvents, rejection } from '../given/routed_scenario.fixture.js';
+
+chai.should();
+const namedTags = [new NamedTag('batch', 'b-1')];
+
+describe('when appending a single event with named tags in an event scenario', () => {
+    let scenario: EventScenario;
+    let error: UnsupportedEventSequenceOperation;
+    beforeEach(async () => {
+        scenario = createEvents();
+        error = await rejection(() => scenario.append('source', new Claim('one'), { namedTags }));
+    });
+    it('should reject the named tags explicitly', () => error.message.should.contain('append.namedTags'));
+    it('should not append the event', () => scenario.appendedEvents.should.have.lengthOf(0));
+});
+
+describe('when appending a batch with shared named tags in an event scenario', () => {
+    let error: UnsupportedEventSequenceOperation;
+    beforeEach(async () => {
+        error = await rejection(() => createEvents().appendMany('source', [new Claim('one')], { namedTags }));
+    });
+    it('should reject the named tags explicitly', () => error.message.should.contain('appendMany.namedTags'));
+});
+
+describe('when appending a batch entry with named tags in an event scenario', () => {
+    let error: UnsupportedEventSequenceOperation;
+    beforeEach(async () => {
+        error = await rejection(() => createEvents().appendMany([{ eventSourceId: 'source', event: new Claim('one'), namedTags }]));
+    });
+    it('should reject the named tags explicitly', () => error.message.should.contain('appendMany.namedTags'));
+});
+
+describe('when appending with an empty named tag list in an event scenario', () => {
+    let scenario: EventScenario;
+    beforeEach(async () => {
+        scenario = new EventScenario({ artifacts });
+        await scenario.append('source', new Claim('one'), { namedTags: [] });
+    });
+    it('should append the event', () => scenario.appendedEvents.should.have.lengthOf(1));
+    it('should expose an empty named tag list on the stored context like a kernel delivery', () =>
+        scenario.appendedEvents[0].context.namedTags!.should.deep.equal([]));
+});

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

@@ -0,0 +1,119 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { InvalidNamedTag } from '../../../events/InvalidNamedTag.js';
+import { NamedTag } from '../../../events/NamedTag.js';
+import { NamedTagsWithRegisteredEventSourceNotSupported } from '../../../eventSequences/index.js';
+import type { EventContext } from '../../../events/EventContext.js';
+import { reactor } from '../../../reactors/reactor.js';
+import { ReactorScenario } from '../../ReactorScenario.js';
+
+chai.should();
+@eventType('scenario-named-tag-input')
+class NamedTagInput { @field(String) name = 'input'; }
+@eventType('scenario-named-tag-output')
+class NamedTagOutput { @field(String) name = 'output'; }
+
+const contexts: EventContext[] = [];
+@reactor('scenario-named-tag-reactor')
+class NamedTagReactor {
+    namedTagInput(_: NamedTagInput, context: EventContext) {
+        contexts.push(context);
+        return { eventSourceId: 'other', event: new NamedTagOutput(), namedTags: [new NamedTag('origin', context.eventSourceId)] };
+    }
+}
+@reactor('scenario-invalid-named-tag-reactor')
+class InvalidNamedTagReactor {
+    namedTagInput() {
+        return { eventSourceId: 'other', event: new NamedTagOutput(), namedTags: [{ name: ' ', value: 'x' }] };
+    }
+}
+@reactor('scenario-named-tags-registered-source-same-entry')
+class NamedTagRegisteredSourceReactor {
+    namedTagInput() {
+        return { eventSourceId: 'other', event: new NamedTagOutput(), eventSource: 'Account', namedTags: [new NamedTag('origin', 'trigger')] };
+    }
+}
+@reactor('scenario-named-tags-registered-source-cross-entry')
+class NamedTagCrossEntryReactor {
+    namedTagInput() {
+        return [
+            { eventSourceId: 'tagged', event: new NamedTagOutput(), namedTags: [new NamedTag('origin', 'trigger')] },
+            { eventSourceId: 'registered', event: new NamedTagOutput(), eventSource: 'Account' }
+        ];
+    }
+}
+@reactor('scenario-named-tags-registered-source-cross-entry-reversed')
+class NamedTagCrossEntryReversedReactor {
+    namedTagInput() {
+        return [
+            { eventSourceId: 'registered', event: new NamedTagOutput(), eventSource: 'Account' },
+            { eventSourceId: 'tagged', event: new NamedTagOutput(), namedTags: [new NamedTag('origin', 'trigger')] }
+        ];
+    }
+}
+@reactor('scenario-empty-named-tags-registered-source')
+class EmptyNamedTagsRegisteredSourceReactor {
+    namedTagInput() {
+        return { eventSourceId: 'other', event: new NamedTagOutput(), eventSource: 'Account', namedTags: [] };
+    }
+}
+const artifacts = { eventTypes: [NamedTagInput, NamedTagOutput] };
+
+describe('when recording a side effect with named tags', () => {
+    let scenario: ReactorScenario;
+    beforeEach(async () => {
+        contexts.length = 0;
+        scenario = new ReactorScenario(NamedTagReactor, { artifacts, constraints: 'disabled' });
+        await scenario.when.forEventSource('trigger').events(new NamedTagInput());
+    });
+    it('should record the named tags on the side-effect target', () =>
+        scenario.sideEffects[0].target.namedTags!.map(tag => `${tag.name}=${tag.value}`).should.deep.equal(['origin=trigger']));
+    it('should deliver an empty named tag list like a kernel delivery of an untagged event', () =>
+        contexts[0].namedTags!.should.deep.equal([]));
+});
+
+describe('when recording a side effect with an invalid named tag', () => {
+    let error: unknown;
+    beforeEach(async () => {
+        const scenario = new ReactorScenario(InvalidNamedTagReactor, { artifacts, constraints: 'disabled' });
+        error = await scenario.when.forEventSource('trigger').events(new NamedTagInput()).catch(caught => caught);
+    });
+    it('should fail the delivery with an invalid named tag error, as production append does', () =>
+        (error as Error).should.be.instanceOf(InvalidNamedTag));
+});
+
+for (const [description, reactorType] of [
+    ['the same entry', NamedTagRegisteredSourceReactor],
+    ['a tagged entry before a registered entry', NamedTagCrossEntryReactor],
+    ['a registered entry before a tagged entry', NamedTagCrossEntryReversedReactor]
+] as const) {
+    describe(`when recording named tags and a registered source in ${description}`, () => {
+        let scenario: ReactorScenario;
+        let error: unknown;
+        beforeEach(async () => {
+            scenario = new ReactorScenario(reactorType, { artifacts, constraints: 'disabled' });
+            error = await scenario.when.forEventSource('trigger').events(new NamedTagInput()).catch(caught => caught);
+        });
+        it('should reject with the production unsupported combination error', () =>
+            (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+        it('should record an unsuccessful delivery', () => scenario.results[0].completed.should.be.false);
+        it('should retain the rejection on the delivery result', () => scenario.results[0].error!.should.equal(error));
+        it('should not record any returned side effect', () => scenario.sideEffects.should.have.lengthOf(0));
+        it('should not report any produced event', () => scenario.produced.should.have.lengthOf(0));
+    });
+}
+
+describe('when recording a registered source with empty named tags', () => {
+    let scenario: ReactorScenario;
+    beforeEach(async () => {
+        scenario = new ReactorScenario(EmptyNamedTagsRegisteredSourceReactor, { artifacts, constraints: 'disabled' });
+        await scenario.when.forEventSource('trigger').events(new NamedTagInput());
+    });
+    it('should complete the delivery', () => scenario.results[0].completed.should.be.true);
+    it('should retain the registered source on the recorded effect', () => scenario.sideEffects[0].target.eventSource!.should.equal('Account'));
+    it('should retain the empty named tag array', () => scenario.sideEffects[0].target.namedTags!.should.deep.equal([]));
+});

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

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { NamedTag } from '../../../events/index.js';
+import { reducer } from '../../../reducers/reducer.js';
+import { ReadModelScenario, UnsupportedEventSequenceOperation } from '../../index.js';
+import { Claim, rejection } 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('NamedTagSetupCounter', undefined, Count)(Counter);
+const create = () => new ReadModelScenario(Count, { eventTypes: [Claim], reducers: [Counter], projections: [] });
+
+describe('when read-model setup receives non-empty named tags', () => {
+    let scenario: ReadModelScenario<Count>;
+    let error: Error;
+    beforeEach(async () => {
+        scenario = create();
+        error = await rejection(() => scenario.given.forEventSource('A', { namedTags: [new NamedTag('batch', 'b-1')] }).events(new Claim('Rejected')));
+    });
+    it('should reject with the typed unsupported operation error', () => error.should.be.instanceOf(UnsupportedEventSequenceOperation));
+    it('should identify the append named tags operation', () => error.message.should.contain('UnsupportedEventSequenceOperation: append.namedTags (Claim)'));
+    it('should not collect the rejected event', async () => ((await scenario.instance) === null).should.be.true);
+});
+
+describe('when read-model setup receives an empty named tag array', () => {
+    let scenario: ReadModelScenario<Count>;
+    beforeEach(() => {
+        scenario = create();
+        scenario.given.forEventSource('A', { namedTags: [] }).events(new Claim('Accepted'));
+    });
+    it('should accept and fold the event', async () => (await scenario.instance)!.claimed.should.equal(1));
+});

package/testing/projections/ProjectionReadModelProcessor.ts

@@ -138,7 +138,8 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
             if (!state) {
                 // SetInitialState: an event only a child subscribes to creates an uninitialized parent.
                 state = from ? this.initialState(key, event) : this.identityState(key, event, false);
-            } else if (state.__initialized === false) {
+            } else if (state.__initialized === false && from) {
+                // Chronicle 19.30.0 no longer initializes a parent on events only a child subscribes to.
                 for (const [name, value] of Object.entries(this.initialValues())) if (!(name in state)) state[name] = value;
                 state.__initialized = true;
             }

package/testing/singleAppendRoute.ts

@@ -4,6 +4,14 @@
 import type { AppendOptions } from '../eventSequences/AppendOptions.js';
 import { UnsupportedEventSequenceOperation } from './UnsupportedEventSequenceOperation.js';
 
+/**
+ * Whether a named-tag option asks for anything. An explicitly empty array carries no tags, exactly like an
+ * omitted option; anything else is reported, including malformed values the production client would reject.
+ */
+export function hasNamedTags(namedTags: unknown): boolean {
+    return namedTags !== undefined && !(Array.isArray(namedTags) && namedTags.length === 0);
+}
+
 /** 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),
@@ -12,8 +20,12 @@ export function singleAppendRoute(options: AppendOptions | undefined, artifact:
     if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
         throw unsupported('append.options', artifact, 'Append options must be an object.');
     }
+    if (options && hasNamedTags(options.namedTags)) {
+        throw unsupported('append.namedTags', artifact, 'Named tags are not fixture-backed.');
+    }
     const allowed = ['sourceType', 'streamType', 'streamId', ...(allowSubject ? ['subject'] : [])];
-    if (options && (Reflect.ownKeys(options).some(key => !allowed.includes(String(key))) ||
+    // An explicitly empty namedTags array is accepted (checked above) but not advertised as a supported option.
+    if (options && (Reflect.ownKeys(options).some(key => key !== 'namedTags' && !allowed.includes(String(key))) ||
         options.correlationId !== undefined || (!allowSubject && options.subject !== undefined) || options.occurred !== undefined ||
         options.eventSourceId !== undefined || options.concurrencyScope !== undefined || options.tags !== undefined ||
         options.concurrencyScopes !== undefined)) {

package/transactions/IUnitOfWork.ts

@@ -6,6 +6,7 @@ import { AppendError } from '../eventSequences/AppendError.js';
 import { ConcurrencyViolation } from '../eventSequences/ConcurrencyViolation.js';
 import { ConstraintViolation } from '../eventSequences/ConstraintViolation.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
 import { AppendResult } from '../eventSequences/AppendResult.js';
 
 /**
@@ -26,8 +27,10 @@ export interface IUnitOfWork {
      * @param eventSequenceId - The identifier of the event sequence to append to.
      * @param eventSourceId - The event source identifier.
      * @param event - The event payload.
+     * @param options - Optional registered event source / stream routing and named tags for this event.
+     * @throws {@link InvalidNamedTag} when a named tag is invalid; the event is not added.
      */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object): void;
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, options?: TransactionalAppendOptions): void;
 
     /**
      * Gets all events currently buffered in this unit of work.

package/transactions/TransactionalAppendOptions.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { NamedTag } from '../events/NamedTag.js';
+import type { TransactionalEventRouting } from './TransactionalEventRouting.js';
+
+/**
+ * Optional metadata for an event added to a unit of work: registered event source routing and
+ * structured named tags. Carried through to the append on commit.
+ */
+export interface TransactionalAppendOptions extends TransactionalEventRouting {
+    /**
+     * Structured named tags for the event. Validated when the event is added, so an invalid tag fails
+     * before anything is committed; the first occurrence of each exact name and value pair is kept.
+     */
+    readonly namedTags?: ReadonlyArray<NamedTag>;
+}

package/transactions/TransactionalEventRouting.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+
+/**
+ * Optional registered event source routing for an event added to a unit of work.
+ * Carried through to the append on commit, where it is validated like any other append.
+ */
+export interface TransactionalEventRouting {
+    /** Registered event source definition (class decorated with `@eventSource`, or its name). */
+    readonly eventSource?: Constructor | string;
+
+    /** Stream name declared by {@link eventSource}. */
+    readonly eventStream?: string;
+}

package/transactions/UnitOfWork.ts

@@ -8,7 +8,11 @@ import { ConcurrencyViolation } from '../eventSequences/ConcurrencyViolation.js'
 import { ConstraintViolation } from '../eventSequences/ConstraintViolation.js';
 import { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { planDerivedGuards, resolveBatchRouting } from '../eventSequences/resolveEventSourceRouting.js';
+import { ensureNamedTagBatchIsSupported } from '../eventSequences/ensureNamedTagBatchIsSupported.js';
 import { IEventStore } from '../IEventStore.js';
+import type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { IUnitOfWork } from './IUnitOfWork.js';
 
 interface EventForEventSourceIdWithSequenceNumber {
@@ -46,14 +50,18 @@ export class UnitOfWork implements IUnitOfWork {
     }
 
     /** @inheritdoc */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object): void {
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, options?: TransactionalAppendOptions): void {
         this.throwIfCompleted();
+        const namedTags = mergeNamedTags(options?.namedTags);
         this._events.push({
             sequenceNumber: this._events.length,
             eventSequenceId,
             eventForEventSourceId: {
                 eventSourceId,
-                event
+                event,
+                ...(options?.eventSource !== undefined ? { eventSource: options.eventSource } : {}),
+                ...(options?.eventStream !== undefined ? { eventStream: options.eventStream } : {}),
+                ...(namedTags.length > 0 ? { namedTags } : {})
             }
         });
     }
@@ -90,6 +98,11 @@ export class UnitOfWork implements IUnitOfWork {
         this.throwIfCompleted();
 
         if (this._events.length > 0) {
+            // Validate the entire commit before writing any sequence, including combinations in different groups.
+            ensureNamedTagBatchIsSupported(
+                this._events.some(entry => (entry.eventForEventSourceId.namedTags?.length ?? 0) > 0),
+                this._events.some(entry => entry.eventForEventSourceId.eventSource !== undefined)
+            );
             const resultsBySequenceNumber = new Map<number, AppendResult>();
             const eventsByEventSequence = new Map<string, EventForEventSourceIdWithSequenceNumber[]>();
 
@@ -100,6 +113,13 @@ export class UnitOfWork implements IUnitOfWork {
                 eventsByEventSequence.set(key, events);
             }
 
+            // Resolve routing and required guards for every group first: a rejection must not follow a written group.
+            const eventSources = this._eventStore.eventSources;
+            for (const eventsForSequence of eventSources ? eventsByEventSequence.values() : []) {
+                const events = eventsForSequence.map(_ => _.eventForEventSourceId);
+                planDerivedGuards(events.map(_ => resolveBatchRouting(eventSources, _)), events, undefined);
+            }
+
             for (const [eventSequenceId, eventsForSequence] of eventsByEventSequence) {
                 const sequence = this._eventStore.getEventSequence(new EventSequenceId(eventSequenceId));
                 const appendResults = await sequence.appendMany(

package/transactions/for_UnitOfWork/when_committing_events_with_event_source_routing.spec.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Guid } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import { EventSequenceId } from '../../eventSequences/index.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { UnitOfWork } from '../UnitOfWork.js';
+
+const should = chai.should();
+
+describe('when committing events with event source routing in a unit of work', () => {
+    let batch: any[];
+    beforeEach(async () => {
+        const appendMany = vi.fn().mockResolvedValue([{ isSuccess: true, constraintViolations: [], errors: [] }, { isSuccess: true, constraintViolations: [], errors: [] }]);
+        const store = { getEventSequence: () => ({ appendMany }) } as unknown as IEventStore;
+        const unitOfWork = new UnitOfWork(Guid.create(), () => {}, store);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { first: 1 }, { eventSource: 'Account', eventStream: 'Transactions' });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'c-1', { second: 2 }, { eventSource: 'Customer' });
+        await unitOfWork.commit();
+        batch = appendMany.mock.calls[0][0];
+    });
+    it('should keep the source and stream of the first event', () => {
+        batch[0].eventSource.should.equal('Account');
+        batch[0].eventStream.should.equal('Transactions');
+    });
+    it('should keep a different source on the second event without a stream', () => {
+        batch[1].eventSource.should.equal('Customer');
+        should.not.exist(batch[1].eventStream);
+    });
+});
+
+describe('when adding an event to a unit of work without routing', () => {
+    it('should not add routing keys to the buffered event', async () => {
+        const appendMany = vi.fn().mockResolvedValue([{ isSuccess: true, constraintViolations: [], errors: [] }]);
+        const unitOfWork = new UnitOfWork(Guid.create(), () => {}, { getEventSequence: () => ({ appendMany }) } as unknown as IEventStore);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', {});
+        await unitOfWork.commit();
+        Object.keys(appendMany.mock.calls[0][0][0]).sort().should.deep.equal(['event', 'eventSourceId']);
+    });
+});

package/transactions/for_UnitOfWork/when_committing_events_with_named_tags.spec.ts

@@ -0,0 +1,112 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Guid } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import { InvalidNamedTag, NamedTag } from '../../events/index.js';
+import { EventSequenceId, NamedTagsWithRegisteredEventSourceNotSupported, type EventForEventSourceId } from '../../eventSequences/index.js';
+import { ConcurrencyDimensions, type IEventSources } from '../../eventSources/index.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { UnitOfWork } from '../UnitOfWork.js';
+
+const should = chai.should();
+const success = { isSuccess: true, constraintViolations: [], errors: [] };
+
+class Account {}
+const eventSources = {
+    getFor: () => ({ type: Account, name: 'Account', description: '', concurrency: ConcurrencyDimensions.none, streams: [] })
+} as unknown as IEventSources;
+
+function a_unit_of_work() {
+    const appendMany = vi.fn().mockImplementation(async (events: EventForEventSourceId[]) => events.map(() => success));
+    const completed = vi.fn();
+    const unitOfWork = new UnitOfWork(Guid.create(), completed, { eventSources, getEventSequence: () => ({ appendMany }) } as unknown as IEventStore);
+    return { unitOfWork, appendMany, completed };
+}
+
+describe('when committing events with named tags in a unit of work', () => {
+    let batch: EventForEventSourceId[];
+    beforeEach(async () => {
+        const { unitOfWork, appendMany } = a_unit_of_work();
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { first: 1 },
+            { namedTags: [new NamedTag('batch', 'b-1'), new NamedTag('batch', 'b-1')] });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-2', { second: 2 }, { namedTags: [] });
+        await unitOfWork.commit();
+        batch = appendMany.mock.calls[0][0];
+    });
+    it('should carry the distinct named tags on the event they were added with', () =>
+        batch[0].namedTags!.map(tag => `${tag.name}=${tag.value}`).should.deep.equal(['batch=b-1']));
+    it('should not add named tags to an event added with none', () => should.not.exist(batch[1].namedTags));
+});
+
+describe('when adding an event with an invalid named tag to a unit of work', () => {
+    let error: unknown;
+    let unitOfWork: UnitOfWork;
+    beforeEach(() => {
+        ({ unitOfWork } = a_unit_of_work());
+        try {
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', {}, { namedTags: [{ name: ' ', value: 'x' } as NamedTag] });
+        } catch (caught) {
+            error = caught;
+        }
+    });
+    it('should fail with an invalid named tag error', () => (error as Error).should.be.instanceOf(InvalidNamedTag));
+    it('should not buffer the event', () => unitOfWork.getEvents().should.have.lengthOf(0));
+});
+
+for (const separateSequences of [false, true]) {
+    describe(`when committing named tags and a registered source in ${separateSequences ? 'different event sequences' : 'one batch'}`, () => {
+        let calls: ReturnType<typeof a_unit_of_work>;
+        let error: unknown;
+        beforeEach(async () => {
+            calls = a_unit_of_work();
+            // An otherwise valid group must not be written before a later unsupported combination is found.
+            calls.unitOfWork.addEvent(EventSequenceId.eventLog, 'plain', { first: 1 });
+            const sequenceId = separateSequences ? new EventSequenceId('other') : EventSequenceId.eventLog;
+            calls.unitOfWork.addEvent(sequenceId, 'tagged', { second: 2 }, { namedTags: [new NamedTag('batch', 'b-1')] });
+            calls.unitOfWork.addEvent(sequenceId, 'registered', { third: 3 }, { eventSource: Account });
+            error = await calls.unitOfWork.commit().catch(caught => caught);
+        });
+        it('should reject with the typed unsupported combination error', () =>
+            (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+        it('should not write any group', () => calls.appendMany.mock.calls.should.have.lengthOf(0));
+        it('should leave the unit of work uncompleted', () => calls.unitOfWork.isCompleted.should.be.false);
+        it('should not invoke completion callbacks', () => calls.completed.mock.calls.should.have.lengthOf(0));
+        it('should retain the buffered events for rollback', () => calls.unitOfWork.getEvents().should.have.lengthOf(3));
+    });
+}
+
+describe('when committing tags and registered sources on different event sequences', () => {
+    let calls: ReturnType<typeof a_unit_of_work>;
+    let error: unknown;
+    beforeEach(async () => {
+        calls = a_unit_of_work();
+        calls.unitOfWork.addEvent(EventSequenceId.eventLog, 'tagged', {}, { namedTags: [new NamedTag('batch', 'b-1')] });
+        calls.unitOfWork.addEvent(new EventSequenceId('other'), 'registered', {}, { eventSource: 'Account' });
+        error = await calls.unitOfWork.commit().catch(caught => caught);
+    });
+    it('should reject the entire commit', () => (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+    it('should not append the first event sequence', () => calls.appendMany.mock.calls.should.have.lengthOf(0));
+});
+
+describe('when committing a registered source and named tags on one event', () => {
+    let error: unknown;
+    beforeEach(async () => {
+        const { unitOfWork } = a_unit_of_work();
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'registered', {}, { eventSource: 'Account', namedTags: [new NamedTag('batch', 'b-1')] });
+        error = await unitOfWork.commit().catch(caught => caught);
+    });
+    it('should reject with the typed unsupported combination error', () =>
+        (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+});
+
+describe('when committing a registered source with an empty named tag array', () => {
+    let calls: ReturnType<typeof a_unit_of_work>;
+    beforeEach(async () => {
+        calls = a_unit_of_work();
+        calls.unitOfWork.addEvent(EventSequenceId.eventLog, 'registered', {}, { eventSource: 'Account', namedTags: [] });
+        await calls.unitOfWork.commit();
+    });
+    it('should append the registered source', () => calls.appendMany.mock.calls[0][0][0].eventSource.should.equal('Account'));
+    it('should complete the unit of work', () => calls.unitOfWork.isCompleted.should.be.true);
+});

package/transactions/index.ts

@@ -6,3 +6,5 @@ export type { IUnitOfWorkManager } from './IUnitOfWorkManager.js';
 export { NoUnitOfWorkHasBeenStarted } from './NoUnitOfWorkHasBeenStarted.js';
 export { UnitOfWork } from './UnitOfWork.js';
 export { UnitOfWorkManager } from './UnitOfWorkManager.js';
+export type { TransactionalEventRouting } from './TransactionalEventRouting.js';
+export type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';

package/types/DecoratorType.ts

@@ -33,5 +33,8 @@ export enum DecoratorType {
     EventTypeMigration = 'eventTypeMigration',
 
     /** Global read model variant handler artifacts discovered through the globalFor decorator. */
-    GlobalForHandler = 'globalForHandler'
+    GlobalForHandler = 'globalForHandler',
+
+    /** Event source definition artifacts discovered through the eventSource decorator. */
+    EventSource = 'eventSource'
 }