@cratis/chronicle 6.49.0 → 6.51.0

package/testing/for_EventScenario/when_appending_event_sequence_constraints/other_sequence_extended_key_behaviors.fixture.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it, type Assertion } from 'vitest';
+import type { Constructor } from '@cratis/fundamentals';
+import { EventScenario } from '../../index.js';
+
+chai.should();
+function should(value: unknown): Assertion { return (value as { should: Assertion }).should; }
+
+/**
+ * Proves a numeric unique constraint applicable to the event log is not rejected as non-isolated because another
+ * constraint is scoped only to a different event sequence.
+ * @param claimed - Event type constructor with a numeric key.
+ * @param other - Event type constructor used by the outbox-only constraint.
+ * @param constraints - The numeric event log constraint and the outbox-only constraint.
+ */
+export function otherSequenceExtendedKeyBehaviors(
+    claimed: new () => object,
+    other: new () => object,
+    constraints: Constructor[]
+): void {
+    describe('with a numeric key and a constraint scoped to another event sequence', () => {
+        const create = () => new EventScenario({ artifacts: { eventTypes: [claimed, other], constraints } });
+
+        it('should construct the scenario', () => {
+            should(create).not.throw();
+        });
+
+        it('should accept the first event', async () => {
+            should((await create().append('A', new claimed())).isSuccess).equal(true);
+        });
+
+        it('should enforce the numeric constraint on the event log', async () => {
+            const scenario = create();
+            await scenario.append('A', new claimed());
+            should((await scenario.append('B', new claimed())).isSuccess).equal(false);
+        });
+    });
+}

package/testing/for_EventScenario/when_appending_event_sequence_constraints/with_legacy_decorators.legacy.spec.ts

@@ -0,0 +1,55 @@
+// 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, type Constructor } from '@cratis/fundamentals';
+import { describe } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import { removeConstraint } from '../../../events/constraints/removeConstraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { eventSequenceScenarioBehaviors } from './event_sequence_scenario_behaviors.fixture.js';
+
+@eventType('OracleDomainText')
+class Text { @field(String) key: string; constructor(key: string) { this.key = key; } }
+@eventType('OracleDomainRemoved')
+class Removed { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleFirst')
+class First { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleSibling')
+class Sibling { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleRemoved')
+@removeConstraint('OracleSequencedCycle')
+class CycleRemoved { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleExpired')
+@removeConstraint('OracleSequencedCycle')
+class CycleExpired { @field(String) label: string; constructor(label: string) { this.label = label; } }
+
+const outbox = new EventSequenceId('outbox');
+
+function constraints(caseName: string): Constructor[] {
+    function select(builder: IConstraintBuilder): IConstraintBuilder {
+        if (caseName.endsWith('-event-log-and-outbox')) return builder.forEventSequences('outbox', EventSequenceId.eventLog);
+        return caseName.endsWith('-event-log') ? builder.forEventLog() : builder.forEventSequences(outbox);
+    }
+    @constraint('OracleSequencedKey')
+    class Key {
+        define(builder: IConstraintBuilder) {
+            select(builder).unique(key => key.on(Text, event => event.key).removedWith(Removed).withMessage('Taken: {PropertyValue}'));
+        }
+    }
+    @constraint('OracleSequencedFirst')
+    class FirstCycle { define(builder: IConstraintBuilder) { select(builder).uniqueFor(First, 'Cycle occupied', 'OracleSequencedCycle'); } }
+    @constraint('OracleSequencedSibling')
+    class SiblingCycle { define(builder: IConstraintBuilder) { select(builder).uniqueFor(Sibling, 'Cycle occupied', 'OracleSequencedCycle'); } }
+    @constraint('OracleSequencedOnceConstraint')
+    class Once { define(builder: IConstraintBuilder) { select(builder).uniqueFor(First, 'Already recorded', 'OracleSequencedOnce'); } }
+    const kind = caseName.split('-')[0];
+    return kind === 'property' ? [Key] : kind === 'once' ? [Once] : [FirstCycle, SiblingCycle];
+}
+
+describe('when appending event sequence constraints with legacy decorators', () => {
+    eventSequenceScenarioBehaviors({ string: Text, removed: Removed, first: First, sibling: Sibling,
+        cycleRemoved: CycleRemoved, cycleExpired: CycleExpired }, constraints);
+});

package/testing/for_EventScenario/when_appending_event_sequence_constraints/with_standard_decorators.standard.spec.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field, type Constructor } from '@cratis/fundamentals';
+import { describe } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import { removeConstraint } from '../../../events/constraints/removeConstraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { eventSequenceScenarioBehaviors } from './event_sequence_scenario_behaviors.fixture.js';
+
+@eventType('OracleDomainText')
+class Text { @field(String) key: string; constructor(key: string) { this.key = key; } }
+@eventType('OracleDomainRemoved')
+class Removed { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleFirst')
+class First { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleSibling')
+class Sibling { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleRemoved')
+@removeConstraint('OracleSequencedCycle')
+class CycleRemoved { @field(String) label: string; constructor(label: string) { this.label = label; } }
+@eventType('OracleCycleExpired')
+@removeConstraint('OracleSequencedCycle')
+class CycleExpired { @field(String) label: string; constructor(label: string) { this.label = label; } }
+
+const outbox = new EventSequenceId('outbox');
+
+function constraints(caseName: string): Constructor[] {
+    function select(builder: IConstraintBuilder): IConstraintBuilder {
+        if (caseName.endsWith('-event-log-and-outbox')) return builder.forEventSequences('outbox', EventSequenceId.eventLog);
+        return caseName.endsWith('-event-log') ? builder.forEventLog() : builder.forEventSequences(outbox);
+    }
+    @constraint('OracleSequencedKey')
+    class Key {
+        define(builder: IConstraintBuilder) {
+            select(builder).unique(key => key.on(Text, event => event.key).removedWith(Removed).withMessage('Taken: {PropertyValue}'));
+        }
+    }
+    @constraint('OracleSequencedFirst')
+    class FirstCycle { define(builder: IConstraintBuilder) { select(builder).uniqueFor(First, 'Cycle occupied', 'OracleSequencedCycle'); } }
+    @constraint('OracleSequencedSibling')
+    class SiblingCycle { define(builder: IConstraintBuilder) { select(builder).uniqueFor(Sibling, 'Cycle occupied', 'OracleSequencedCycle'); } }
+    @constraint('OracleSequencedOnceConstraint')
+    class Once { define(builder: IConstraintBuilder) { select(builder).uniqueFor(First, 'Already recorded', 'OracleSequencedOnce'); } }
+    const kind = caseName.split('-')[0];
+    return kind === 'property' ? [Key] : kind === 'once' ? [Once] : [FirstCycle, SiblingCycle];
+}
+
+describe('when appending event sequence constraints with standard decorators', () => {
+    eventSequenceScenarioBehaviors({ string: Text, removed: Removed, first: First, sibling: Sibling,
+        cycleRemoved: CycleRemoved, cycleExpired: CycleExpired }, constraints);
+});

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/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/ConflictingConcurrencyScopesInUnitOfWork.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Error thrown when a unit of work is given a concurrency scope for an event source identifier that already has a different
+ * scope in the same event sequence. Chronicle validates one scope per event source identifier in an append, so the unit of work
+ * cannot commit both.
+ */
+export class ConflictingConcurrencyScopesInUnitOfWork extends Error {
+    /**
+     * Initializes a new instance of the {@link ConflictingConcurrencyScopesInUnitOfWork} class.
+     * @param eventSequenceId - The identifier of the event sequence the events are added to.
+     */
+    constructor(readonly eventSequenceId: string) {
+        super(
+            `An event source in event sequence '${eventSequenceId}' already has a different concurrency scope in this unit of work. ` +
+            'Use the same scope for every event of the event source, or commit the events in separate units of work.');
+    }
+}

package/transactions/IUnitOfWork.ts

@@ -6,7 +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 { TransactionalEventRouting } from './TransactionalEventRouting.js';
+import type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
 import { AppendResult } from '../eventSequences/AppendResult.js';
 
 /**
@@ -27,9 +27,11 @@ 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 routing - Optional registered event source / stream routing for this event.
+     * @param options - Optional append metadata for this event: registered event source / stream routing, stream and source
+     * types, stream identifier, subject, occurrence time, tags, named tags and concurrency scope. Kept with the event until commit.
+     * @throws {@link InvalidNamedTag} when a named tag is invalid; the event is not added.
      */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, routing?: TransactionalEventRouting): 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,45 @@
+// 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 { Tag } from '../events/Tag.js';
+import type { ConcurrencyScope } from '../eventSequences/ConcurrencyScope.js';
+import type { TransactionalEventRouting } from './TransactionalEventRouting.js';
+
+/**
+ * Optional append metadata for an event added to a unit of work.
+ * Every value is kept with the event and carried to the append when the unit of work commits,
+ * where it is validated like any other append.
+ */
+export interface TransactionalAppendOptions extends TransactionalEventRouting {
+    /** Optional stream type. When omitted or empty, the kernel selects the route. */
+    readonly eventStreamType?: string;
+
+    /** Optional stream identifier. When omitted or empty, the kernel selects the route. */
+    readonly eventStreamId?: string;
+
+    /** Optional source type. When omitted or empty, the kernel selects the route. */
+    readonly eventSourceType?: string;
+
+    /** Optional occurrence time. When omitted, the kernel supplies the timestamp. */
+    readonly occurred?: Date;
+
+    /** Optional compliance subject. Overrides the event's @subject() value; otherwise defaults to the event source identifier. */
+    readonly subject?: string;
+
+    /** Optional tags, combined with any static tags declared on the event type via `@tag()`/`@tags()`. */
+    readonly tags?: ReadonlyArray<string | Tag>;
+
+    /**
+     * Optional concurrency scope for the event source identifier, validated when the unit of work commits.
+     * Chronicle accepts one scope per event source identifier in an append, so every event a unit of work holds
+     * for the same event source identifier in the same event sequence must use an equal scope or none.
+     */
+    readonly concurrencyScope?: ConcurrencyScope;
+
+    /**
+     * 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/UnitOfWork.ts

@@ -9,8 +9,13 @@ 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 { TransactionalEventRouting } from './TransactionalEventRouting.js';
+import type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
+import type { ConcurrencyScope } from '../eventSequences/ConcurrencyScope.js';
+import { ConflictingConcurrencyScopesInUnitOfWork } from './ConflictingConcurrencyScopesInUnitOfWork.js';
+import { concurrencyScopesAreEqual } from './concurrencyScopesAreEqual.js';
+import { toEventForEventSourceId } from './toEventForEventSourceId.js';
 import { IUnitOfWork } from './IUnitOfWork.js';
 
 interface EventForEventSourceIdWithSequenceNumber {
@@ -24,6 +29,7 @@ interface EventForEventSourceIdWithSequenceNumber {
  */
 export class UnitOfWork implements IUnitOfWork {
     private _events: EventForEventSourceIdWithSequenceNumber[] = [];
+    private _concurrencyScopes = new Map<string, Map<string, ConcurrencyScope>>();
     private _appendResults: AppendResult[] = [];
     private _isCommitted = false;
     private _isRolledBack = false;
@@ -48,17 +54,23 @@ export class UnitOfWork implements IUnitOfWork {
     }
 
     /** @inheritdoc */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, routing?: TransactionalEventRouting): void {
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, options?: TransactionalAppendOptions): void {
         this.throwIfCompleted();
+        const eventForEventSourceId = toEventForEventSourceId(eventSourceId, event, options);
+        const scope = options?.concurrencyScope;
+        const scopesForSequence = this._concurrencyScopes.get(eventSequenceId.value) ?? new Map<string, ConcurrencyScope>();
+        if (scope !== undefined) {
+            const enrolled = scopesForSequence.get(eventSourceId);
+            if (enrolled !== undefined && !concurrencyScopesAreEqual(enrolled, scope)) {
+                throw new ConflictingConcurrencyScopesInUnitOfWork(eventSequenceId.value);
+            }
+            scopesForSequence.set(eventSourceId, { ...scope, ...(scope.eventTypes ? { eventTypes: [...scope.eventTypes] } : {}) });
+            this._concurrencyScopes.set(eventSequenceId.value, scopesForSequence);
+        }
         this._events.push({
             sequenceNumber: this._events.length,
             eventSequenceId,
-            eventForEventSourceId: {
-                eventSourceId,
-                event,
-                ...(routing?.eventSource !== undefined ? { eventSource: routing.eventSource } : {}),
-                ...(routing?.eventStream !== undefined ? { eventStream: routing.eventStream } : {})
-            }
+            eventForEventSourceId
         });
     }
 
@@ -94,6 +106,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[]>();
 
@@ -106,16 +123,23 @@ export class UnitOfWork implements IUnitOfWork {
 
             // 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);
+            if (eventSources) {
+                for (const [eventSequenceId, eventsForSequence] of eventsByEventSequence) {
+                    const events = eventsForSequence.map(_ => _.eventForEventSourceId);
+                    const explicitIds = new Set(this._concurrencyScopes.get(eventSequenceId)?.keys() ?? []);
+                    planDerivedGuards(events.map(_ => resolveBatchRouting(eventSources, _)), events, undefined, explicitIds);
+                }
             }
 
             for (const [eventSequenceId, eventsForSequence] of eventsByEventSequence) {
                 const sequence = this._eventStore.getEventSequence(new EventSequenceId(eventSequenceId));
+                const scopes = this._concurrencyScopes.get(eventSequenceId);
                 const appendResults = await sequence.appendMany(
                     eventsForSequence.map(_ => _.eventForEventSourceId),
-                    { correlationId: this.correlationId }
+                    {
+                        correlationId: this.correlationId,
+                        ...(scopes && scopes.size > 0 ? { concurrencyScopes: Object.fromEntries(scopes) } : {})
+                    }
                 );
 
                 appendResults.forEach((appendResult, index) => {
@@ -139,6 +163,7 @@ export class UnitOfWork implements IUnitOfWork {
         this.throwIfCompleted();
         this._isRolledBack = true;
         this._events = [];
+        this._concurrencyScopes = new Map();
         this._appendResults = [];
         this._onCompleted(this);
     }

package/transactions/concurrencyScopesAreEqual.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ConcurrencyScope } from '../eventSequences/ConcurrencyScope.js';
+
+/**
+ * Compares two concurrency scopes by value.
+ * @param first - The first scope.
+ * @param second - The second scope.
+ * @returns True when both scopes validate the same expectation.
+ */
+export function concurrencyScopesAreEqual(first: ConcurrencyScope, second: ConcurrencyScope): boolean {
+    // Event type filters are sets of id + generation: omitted equals empty, duplicates and order do not matter.
+    const eventTypeKeys = (scope: ConcurrencyScope) =>
+        [...new Set((scope.eventTypes ?? []).map(_ => `${_.id.value}+${_.generation.value}`))].sort().join(',');
+
+    return first.sequenceNumber === second.sequenceNumber
+        && (first.eventSourceId ?? false) === (second.eventSourceId ?? false)
+        && first.eventStreamType === second.eventStreamType
+        && first.eventStreamId === second.eventStreamId
+        && first.eventSourceType === second.eventSourceType
+        && eventTypeKeys(first) === eventTypeKeys(second);
+}