@cratis/chronicle 6.50.0 → 6.51.1

package/testing/EventScenario.fixtures.spec.ts

@@ -59,7 +59,7 @@ const fixtures = readdirSync(directory).filter(name => name.endsWith('.json') &&
     !['batches.json', 'batch-omitted-routes.json', 'batch-rollback.json', 'builders.json', 'constraints.json', 'constraints-isolation.json', 'constraints-key-domain.json',
         'constraints-property-lifecycle.json', 'constraints-property-covered-removal.json', 'constraints-event-type-cycles.json',
         'constraints-event-type-siblings.json', 'constraints-composite.json',
-        'constraints-ignore-casing.json', 'constraints-scopes.json', 'constraints-field-types.json'].includes(name)).map(name => ({
+        'constraints-ignore-casing.json', 'constraints-scopes.json', 'constraints-field-types.json', 'constraints-event-sequences.json'].includes(name)).map(name => ({
     name, fixture: JSON.parse(readFileSync(new URL(name, directory), 'utf8')) as Fixture
 }));
 const artifacts = { eventTypes: [OracleEventRecorded, AlternateRecorded, BoundaryRecorded], constraints: [] };

package/testing/EventScenario.ts

@@ -85,9 +85,15 @@ export class EventScenario {
                         }
                     }
                 }
-                constraints = new InProcessConstraints(definitions, new Map(eventTypes.map(type =>
-                    [getEventTypeFor(type).id.value, getEventTypeMetadata(type)!.schema])));
-                for (const [name, capture] of definitions) {
+                // The scenario appends to the event log only. A definition scoped to other event sequences is neither
+                // validated nor indexed there by the kernel (constraints-event-sequences.json), so it takes no part.
+                const eventLog = EventSequenceId.eventLog.value;
+                const applicable = new Map([...definitions].filter(([, capture]) =>
+                    !capture.eventSequences?.length || capture.eventSequences.includes(eventLog)));
+                const inapplicable = new Set([...definitions.keys()].filter(name => !applicable.has(name)));
+                constraints = new InProcessConstraints(applicable, new Map(eventTypes.map(type =>
+                    [getEventTypeFor(type).id.value, getEventTypeMetadata(type)!.schema])), inapplicable);
+                for (const [name, capture] of applicable) {
                     const ids = capture.uniqueConstraint?.eventDefinitions.map(entry => entry.eventTypeId) ??
                         capture.uniqueEventType?.eventTypeIds ?? [capture.uniqueEventType?.eventTypeId];
                     const removedWith = [...(capture.uniqueConstraint?.removedWithEventTypeIds ?? []),
@@ -121,7 +127,7 @@ export class EventScenario {
                                 `Unique keys with schema ${schema?.type ?? 'missing'}/${schema?.format ?? 'unformatted'} are not fixture-backed; date, object and other numeric formats require a kernel-backed test.`);
                         }
                         const extendedKey = schemas.some(schema => schema?.type === 'number' || schema?.format === 'guid');
-                        if (extendedKey && (definitions.size !== 1 || capture.uniqueConstraint!.eventDefinitions.length !== 1 ||
+                        if (extendedKey && (applicable.size !== 1 || capture.uniqueConstraint!.eventDefinitions.length !== 1 ||
                             removedWith.some(id => id !== undefined))) {
                             throw new UnsupportedEventSequenceOperation('artifacts.constraints', name,
                                 'Guid and numeric keys require one isolated definition covering one event type without removers; shared definitions and removal combinations are not fixture-backed.');

package/testing/InProcessConstraints.ts

@@ -69,7 +69,8 @@ export class InProcessConstraints {
     private readonly _propertyRemovalTypes = new Set<string>();
 
     constructor(private readonly _definitions: ReadonlyMap<string, ConstraintCapture>,
-        private readonly _schemas: ReadonlyMap<string, JsonSchema> = new Map()) {
+        private readonly _schemas: ReadonlyMap<string, JsonSchema> = new Map(),
+        private readonly _inapplicable: ReadonlySet<string> = new Set()) {
         const coveredTypes = new Map<string, string>();
         const removalOwners = new Map<string, string>();
         for (const [name, capture] of _definitions) {
@@ -161,6 +162,9 @@ export class InProcessConstraints {
 
     hasRemovalType(eventTypeId: string): boolean { return this._removalTypes.has(eventTypeId); }
 
+    /** Whether a named definition is scoped to event sequences other than the scenario's, so it takes no part. */
+    isInapplicable(name: string): boolean { return this._inapplicable.has(name); }
+
     isConstrainedProperty(eventTypeId: string, property: string): boolean {
         return this._constrainedProperties.get(eventTypeId)?.has(property) ?? false;
     }

package/testing/InProcessEventSequence.ts

@@ -110,7 +110,8 @@ export class InProcessEventSequence implements IEventSequence {
             if (eventType.generation.value !== 1 || eventType.tombstone) {
                 throw this.unsupported('artifacts.eventTypes', type.name, 'Only generation 1, non-tombstone events are proven.');
             }
-            if (options.constraints !== 'disabled' && getRemovedConstraintNames(type).length &&
+            if (options.constraints !== 'disabled' &&
+                getRemovedConstraintNames(type).some(name => !this._constraints?.isInapplicable(name)) &&
                 !this._constraints?.hasRemovalType(eventType.id.value)) {
                 throw this.unsupported('artifacts.eventTypes.constraints', type.name, 'Constraint removal is not fixture-backed.');
             }

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

@@ -0,0 +1,101 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { chai, describe, it, vi, type Assertion } from 'vitest';
+import type { Constructor } from '@cratis/fundamentals';
+import { getEventTypeMetadata } from '../../../events/eventTypeDecorator.js';
+import { compileConstraints } from '../../../events/constraints/Constraints.js';
+import { EventScenario } from '../../index.js';
+import { InProcessConstraints } from '../../InProcessConstraints.js';
+
+chai.should();
+function should(value: unknown): Assertion { return (value as { should: Assertion }).should; }
+
+type Entry = { source: string; type: string; value: string };
+type Definition = { kind: string; name: string; events?: Array<{ type: string; properties: string[] }>; eventTypes?: string[];
+    ignoreCasing?: boolean; removedWithEventTypeIds: string[]; message: string; eventSequences: string[] };
+type History = { sequence: string; source: string; sourceType?: string; streamType?: string; streamId?: string;
+    type: string; content: Record<string, unknown>; hash?: string };
+type Outcome = { success: boolean; sequences: string[]; errors: string[];
+    wireViolations: Array<{ EventTypeId: string; SequenceNumber: string; ConstraintType: number; ConstraintName: string; Message: string; Details: Record<string, string> }>;
+    violations: Array<{ id: string; message: string; details: Record<string, string> }>; history: History[]; next: string };
+type SequenceCase = { name: string; kind: string; eventSchemas: Record<string, { eventTypeId: string; properties: Record<string, string> }>;
+    constraintDefinitions: Definition[]; isolatedConstraintOperations: Array<{ mode: string; events: Entry[] }> };
+type Fixture = { eventSequenceCases: SequenceCase[]; expected: { cases: Array<{ name: string; result: { outcomes: Outcome[] } }> } };
+
+/**
+ * Replays constraints-event-sequences.json: a definition applying to the event log behaves as unscoped, and one
+ * applying only to other event sequences is neither validated nor indexed on the scenario's event log.
+ * @param types - Event constructors by fixture alias.
+ * @param constraints - Selects the constraint classes for a case name.
+ */
+export function eventSequenceScenarioBehaviors(
+    types: Record<string, new (value: string) => object>,
+    constraints: (caseName: string) => Constructor[]
+): void {
+    const fixture = JSON.parse(readFileSync(new URL('../../fixtures/constraints-event-sequences.json', import.meta.url), 'utf8')) as Fixture;
+    const historyOf = (scenario: EventScenario): History[] => scenario.appendedEvents.map(event => ({
+        sequence: event.context.sequenceNumber.toString(), source: event.context.eventSourceId,
+        sourceType: event.context.eventSourceType, streamType: event.context.eventStreamType, streamId: event.context.eventStreamId,
+        type: event.eventType.id.value, content: event.content, hash: event.context.hash
+    }));
+    const aliases = Object.fromEntries(Object.entries(types).map(([alias, type]) => [getEventTypeMetadata(type)!.eventType.id.value, alias]));
+
+    it('should retain every event sequence case', () => {
+        should(fixture.eventSequenceCases.map(test => test.name)).deep.equal([
+            'property-event-log', 'property-event-log-and-outbox', 'property-outbox',
+            'cycle-event-log', 'cycle-outbox', 'once-event-log', 'once-outbox'
+        ]);
+        should(fixture.expected.cases.map(test => test.name)).deep.equal(fixture.eventSequenceCases.map(test => test.name));
+    });
+
+    for (const [caseIndex, test] of fixture.eventSequenceCases.entries()) {
+        describe(`with ${test.name}`, () => {
+            it('should match the installed definitions and kernel violations, history and next sequence', async () => {
+                const selected = Object.keys(test.eventSchemas).map(alias => types[alias]);
+                const selectedConstraints = constraints(test.name);
+                const compiled = compileConstraints({ eventTypes: selected, constraints: selectedConstraints });
+                should([...compiled].map(([name, capture]) => ({
+                    kind: capture.uniqueConstraint ? 'uniqueProperty' : 'uniqueEventType', name,
+                    ...(capture.uniqueConstraint ? {
+                        events: capture.uniqueConstraint.eventDefinitions.map(entry => ({ type: aliases[entry.eventTypeId], properties: entry.properties })),
+                        ignoreCasing: capture.uniqueConstraint.ignoreCasing
+                    } : { eventTypes: (capture.uniqueEventType!.eventTypeIds ?? [capture.uniqueEventType!.eventTypeId]).map(id => aliases[id]) }),
+                    removedWithEventTypeIds: (capture.uniqueConstraint?.removedWithEventTypeIds ?? capture.uniqueEventType?.removedWithEventTypeIds ?? []).map(id => aliases[id]),
+                    message: capture.uniqueConstraint?.message ?? capture.uniqueEventType?.message ?? '',
+                    eventSequences: capture.eventSequences ?? []
+                }))).deep.equal(test.constraintDefinitions);
+                const scenario = new EventScenario({ artifacts: { eventTypes: selected, constraints: selectedConstraints } });
+                const validate = vi.spyOn(InProcessConstraints.prototype, 'validate');
+                const expected = fixture.expected.cases[caseIndex].result.outcomes;
+                should(expected.length).equal(test.isolatedConstraintOperations.length);
+                try {
+                    for (const [index, operation] of test.isolatedConstraintOperations.entries()) {
+                        const before = historyOf(scenario);
+                        const entries = operation.events.map(entry => ({ eventSourceId: entry.source, event: new types[entry.type](entry.value) }));
+                        const results = operation.mode === 'single'
+                            ? [await scenario.append(entries[0].eventSourceId, entries[0].event)]
+                            : await scenario.appendMany(entries);
+                        const outcome = expected[index];
+                        const raw = validate.mock.results.at(-1)!.value as ReturnType<InProcessConstraints['validate']>;
+                        should(raw.map(({ SequenceNumber, ...violation }) => ({ ...violation, SequenceNumber: SequenceNumber.toString() })))
+                            .deep.equal(outcome.wireViolations);
+                        for (const [position, result] of results.entries()) {
+                            should(result.isSuccess).equal(outcome.success);
+                            should(result.sequenceNumber.value.toString()).equal(outcome.success ? outcome.sequences[position] : '0');
+                            should(result.constraintViolations.map(violation => ({ id: violation.constraintId, message: violation.message, details: violation.details })))
+                                .deep.equal(outcome.violations);
+                            should(result.errors.map(error => error.message)).deep.equal(outcome.errors);
+                        }
+                        if (!outcome.success) should(historyOf(scenario)).deep.equal(before);
+                        should(historyOf(scenario)).deep.equal(outcome.history);
+                        should((await scenario.eventLog.getNextSequenceNumber()).value.toString()).equal(outcome.next);
+                    }
+                } finally {
+                    validate.mockRestore();
+                }
+            });
+        });
+    }
+}

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

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { field } from '@cratis/fundamentals';
+import { describe } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { otherSequenceExtendedKeyBehaviors } from './other_sequence_extended_key_behaviors.fixture.js';
+
+@eventType('OracleOtherSequenceNumber')
+class NumberClaimed { @field(Number) key = 1; }
+@eventType('OracleOtherSequenceOutbox')
+class OutboxClaimed { @field(String) label = 'x'; }
+
+@constraint('OracleOtherSequenceNumberKey')
+class NumberKey {
+    define(builder: IConstraintBuilder) { builder.forEventLog().unique(key => key.on(NumberClaimed, event => event.key)); }
+}
+@constraint('OracleOtherSequenceOutboxKey')
+class OutboxKey {
+    define(builder: IConstraintBuilder) { builder.forEventSequences('outbox').unique(key => key.on(OutboxClaimed, event => event.label)); }
+}
+
+describe('when appending extended keys beside other event sequence constraints with  decorators', () => {
+    otherSequenceExtendedKeyBehaviors(NumberClaimed, OutboxClaimed, [NumberKey, OutboxKey]);
+});

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

@@ -0,0 +1,27 @@
+// 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 { describe } from 'vitest';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import { constraint } from '../../../events/constraints/constraint.js';
+import type { IConstraintBuilder } from '../../../events/constraints/IConstraintBuilder.js';
+import { otherSequenceExtendedKeyBehaviors } from './other_sequence_extended_key_behaviors.fixture.js';
+
+@eventType('OracleOtherSequenceNumber')
+class NumberClaimed { @field(Number) key = 1; }
+@eventType('OracleOtherSequenceOutbox')
+class OutboxClaimed { @field(String) label = 'x'; }
+
+@constraint('OracleOtherSequenceNumberKey')
+class NumberKey {
+    define(builder: IConstraintBuilder) { builder.forEventLog().unique(key => key.on(NumberClaimed, event => event.key)); }
+}
+@constraint('OracleOtherSequenceOutboxKey')
+class OutboxKey {
+    define(builder: IConstraintBuilder) { builder.forEventSequences('outbox').unique(key => key.on(OutboxClaimed, event => event.label)); }
+}
+
+describe('when appending extended keys beside other event sequence constraints with  decorators', () => {
+    otherSequenceExtendedKeyBehaviors(NumberClaimed, OutboxClaimed, [NumberKey, OutboxKey]);
+});

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/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

@@ -27,7 +27,8 @@ 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.
+     * @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, options?: TransactionalAppendOptions): void;

package/transactions/TransactionalAppendOptions.ts

@@ -2,13 +2,41 @@
 // 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 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.
+ * 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.

package/transactions/UnitOfWork.ts

@@ -12,7 +12,10 @@ import { planDerivedGuards, resolveBatchRouting } from '../eventSequences/resolv
 import { ensureNamedTagBatchIsSupported } from '../eventSequences/ensureNamedTagBatchIsSupported.js';
 import { IEventStore } from '../IEventStore.js';
 import type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
-import { mergeNamedTags } from '../events/mergeNamedTags.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 {
@@ -26,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;
@@ -52,17 +56,21 @@ export class UnitOfWork implements IUnitOfWork {
     /** @inheritdoc */
     addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, options?: TransactionalAppendOptions): void {
         this.throwIfCompleted();
-        const namedTags = mergeNamedTags(options?.namedTags);
+        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,
-                ...(options?.eventSource !== undefined ? { eventSource: options.eventSource } : {}),
-                ...(options?.eventStream !== undefined ? { eventStream: options.eventStream } : {}),
-                ...(namedTags.length > 0 ? { namedTags } : {})
-            }
+            eventForEventSourceId
         });
     }
 
@@ -115,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) => {
@@ -148,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);
+}