@cratis/chronicle 6.50.0 → 6.51.0

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

package/transactions/for_UnitOfWork/against_a_kernel/when_committing_with_append_metadata.integration.spec.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { ChronicleClient, ChronicleOptions, EventSequenceNumber, eventType, type AppendedEvent,
+    type IClientArtifactsProvider, type IEventStore } from '../../../index.js';
+
+chai.should();
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class ItemAdded { @field(Number) order = 0; }
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [ItemAdded], eventSources: [], readModels: [], reactors: [], reducers: [],
+    seeders: [], constraints: [], projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+};
+
+const item = (order: number) => Object.assign(new ItemAdded(), { order });
+
+describe.skipIf(!connectionString && !process.env.CI)('when committing a unit of work with append metadata against a kernel', () => {
+    const storeName = `UnitOfWork${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    const occurred = new Date('2026-03-04T05:06:07.000Z');
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let id: string;
+    let events: AppendedEvent[];
+    let committed: boolean;
+    let staleSucceeded: boolean;
+    let eventsAfterStale: number;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, { discoveryPatterns: [], clientArtifactsProvider: artifacts }));
+        store = await client.getEventStore(storeName);
+        id = randomUUID();
+        const seeded = await store.eventLog.append(id, item(-1));
+        const tail = { sequenceNumber: seeded.sequenceNumber.value, eventSourceId: true };
+
+        const unitOfWork = store.unitOfWorkManager.begin();
+        await store.eventLog.transactional.append(id, item(0), {
+            eventStreamType: 'Orders', eventStreamId: 'order-1', eventSourceType: 'Customer',
+            subject: 'subject-1', occurred, tags: ['priority'], concurrencyScope: tail
+        });
+        await store.eventLog.transactional.append(id, item(1));
+        await unitOfWork.commit();
+        committed = unitOfWork.isSuccess;
+        events = (await store.eventLog.getFromSequenceNumber(EventSequenceNumber.first, id, [ItemAdded])).slice(1);
+
+        const stale = store.unitOfWorkManager.begin();
+        await store.eventLog.transactional.append(id, item(2), { concurrencyScope: tail });
+        await stale.commit();
+        staleSucceeded = stale.isSuccess;
+        eventsAfterStale = (await store.eventLog.getFromSequenceNumber(EventSequenceNumber.first, id, [ItemAdded])).length;
+    });
+    afterAll(() => client?.dispose());
+
+    it('should accept a current concurrency scope', () => committed.should.be.true);
+    it('should append both events in input order', () => events.map(_ => (_.content as { order: number }).order).should.deep.equal([0, 1]));
+    it('should keep the stream type', () => events[0].context.eventStreamType!.should.equal('Orders'));
+    it('should keep the stream id', () => events[0].context.eventStreamId!.should.equal('order-1'));
+    it('should keep the source type', () => events[0].context.eventSourceType!.should.equal('Customer'));
+    it('should keep the subject', () => events[0].context.subject!.should.equal('subject-1'));
+    it('should keep the occurrence time', () => events[0].context.occurred.toISOString().should.equal(occurred.toISOString()));
+    it('should keep the tags', () => events[0].context.tags.map(String).should.contain('priority'));
+    it('should default the subject of the event without options to its event source id', () => events[1].context.subject!.should.equal(id));
+    it('should reject a stale concurrency scope', () => staleSucceeded.should.be.false);
+    it('should not write the event rejected by the stale scope', () => eventsAfterStale.should.equal(3));
+});

package/transactions/for_UnitOfWork/given/a_unit_of_work_with_a_recording_store.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 { Guid } from '@cratis/fundamentals';
+import { vi, type Mock } from 'vitest';
+import type { AppendOptions } from '../../../eventSequences/AppendOptions.js';
+import type { AppendResult } from '../../../eventSequences/AppendResult.js';
+import type { EventForEventSourceId } from '../../../eventSequences/EventForEventSourceId.js';
+import { EventSequenceNumber } from '../../../eventSequences/EventSequenceNumber.js';
+import type { IEventStore } from '../../../IEventStore.js';
+import { UnitOfWork } from '../../UnitOfWork.js';
+
+/** One recorded appendMany call. */
+export interface RecordedAppend {
+    readonly eventSequenceId: string;
+    readonly events: EventForEventSourceId[];
+    readonly options: AppendOptions;
+}
+
+/** Creates a successful append result with a given sequence number. */
+export function successfulAppendResult(sequenceNumber: bigint): AppendResult {
+    return { sequenceNumber: new EventSequenceNumber(sequenceNumber), constraintViolations: [], errors: [], isSuccess: true, waitForCompletion: vi.fn() };
+}
+
+/** The unit of work and what its store recorded. */
+export interface RecordingUnitOfWork {
+    readonly unitOfWork: UnitOfWork;
+    readonly appends: RecordedAppend[];
+    readonly record: Mock;
+    readonly completed: Mock;
+}
+
+/**
+ * Creates a unit of work over a store whose event sequences record every appendMany call.
+ * @param appendMany - Optional replacement for the recording appendMany; receives the sequence id first.
+ */
+export function a_unit_of_work_with_a_recording_store(
+    appendMany?: (eventSequenceId: string, events: EventForEventSourceId[], options: AppendOptions) => Promise<AppendResult[]>
+): RecordingUnitOfWork {
+    const appends: RecordedAppend[] = [];
+    let next = 0n;
+    const record: Mock = vi.fn(async (eventSequenceId: string, events: EventForEventSourceId[], options: AppendOptions) => {
+        appends.push({ eventSequenceId, events, options });
+        return appendMany ? appendMany(eventSequenceId, events, options) : events.map(() => successfulAppendResult(next++));
+    });
+    const store = {
+        getEventSequence: (id: { value: string }) => ({
+            appendMany: (events: EventForEventSourceId[], options: AppendOptions) => record(id.value, events, options)
+        })
+    } as unknown as IEventStore;
+    const completed = vi.fn();
+    const unitOfWork = new UnitOfWork(Guid.create(), completed, store);
+    return { unitOfWork, appends, record, completed };
+}

package/transactions/for_UnitOfWork/when_adding_events_with_concurrency_scopes/and_the_event_type_filters_are_equivalent.spec.ts

@@ -0,0 +1,32 @@
+// 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 { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { EventType } from '../../../events/EventType.js';
+import { a_unit_of_work_with_a_recording_store, type RecordedAppend } from '../given/a_unit_of_work_with_a_recording_store.js';
+
+chai.should();
+
+describe('when adding events with concurrency scopes and the event type filters are equivalent', () => {
+    let appends: RecordedAppend[];
+
+    beforeEach(async () => {
+        const recording = a_unit_of_work_with_a_recording_store();
+        const orderPlaced = EventType.parse('OrderPlaced+1');
+        const orderShipped = EventType.parse('OrderShipped+2');
+        const add = (eventSourceId: string, order: number, concurrencyScope: object) =>
+            recording.unitOfWork.addEvent(EventSequenceId.eventLog, eventSourceId, { order }, { concurrencyScope });
+
+        add('omitted', 0, { sequenceNumber: 1n });
+        add('omitted', 1, { sequenceNumber: 1n, eventTypes: [] });
+        add('duplicates', 2, { sequenceNumber: 1n, eventTypes: [orderPlaced] });
+        add('duplicates', 3, { sequenceNumber: 1n, eventTypes: [orderPlaced, EventType.parse('OrderPlaced+1')] });
+        add('order', 4, { sequenceNumber: 1n, eventTypes: [orderPlaced, orderShipped] });
+        add('order', 5, { sequenceNumber: 1n, eventTypes: [orderShipped, orderPlaced] });
+        await recording.unitOfWork.commit();
+        appends = recording.appends;
+    });
+
+    it('should append every event', () => appends[0].events.should.have.lengthOf(6));
+});

package/transactions/for_UnitOfWork/when_adding_events_with_concurrency_scopes/and_the_event_type_filters_differ.spec.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 { beforeEach, chai, describe, it } from 'vitest';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { EventType } from '../../../events/EventType.js';
+import { ConflictingConcurrencyScopesInUnitOfWork } from '../../ConflictingConcurrencyScopesInUnitOfWork.js';
+import { a_unit_of_work_with_a_recording_store } from '../given/a_unit_of_work_with_a_recording_store.js';
+import type { UnitOfWork } from '../../UnitOfWork.js';
+
+chai.should();
+
+describe('when adding events with concurrency scopes and the event type filters differ', () => {
+    let unitOfWork: UnitOfWork;
+    let errors: unknown[];
+
+    const tryAdd = (eventSourceId: string, eventTypes: EventType[]) => {
+        try {
+            unitOfWork.addEvent(EventSequenceId.eventLog, eventSourceId, { eventSourceId }, { concurrencyScope: { sequenceNumber: 1n, eventTypes } });
+        } catch (caught) {
+            errors.push(caught);
+        }
+    };
+
+    beforeEach(() => {
+        ({ unitOfWork } = a_unit_of_work_with_a_recording_store());
+        errors = [];
+        tryAdd('different-type', [EventType.parse('OrderPlaced+1')]);
+        tryAdd('different-type', [EventType.parse('OrderShipped+1')]);
+        tryAdd('different-generation', [EventType.parse('OrderPlaced+1')]);
+        tryAdd('different-generation', [EventType.parse('OrderPlaced+2')]);
+        tryAdd('empty-versus-filled', []);
+        tryAdd('empty-versus-filled', [EventType.parse('OrderPlaced+1')]);
+    });
+
+    it('should reject each conflicting event', () => {
+        errors.should.have.lengthOf(3);
+        errors.every(_ => _ instanceof ConflictingConcurrencyScopesInUnitOfWork).should.be.true;
+    });
+});

package/transactions/for_UnitOfWork/when_adding_events_with_concurrency_scopes/and_the_scopes_are_equal_or_omitted.spec.ts

@@ -0,0 +1,29 @@
+// 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 { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { a_unit_of_work_with_a_recording_store, type RecordedAppend } from '../given/a_unit_of_work_with_a_recording_store.js';
+
+chai.should();
+
+describe('when adding events with concurrency scopes and the scopes are equal or omitted', () => {
+    let appends: RecordedAppend[];
+
+    beforeEach(async () => {
+        const recording = a_unit_of_work_with_a_recording_store();
+        recording.unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { concurrencyScope: { sequenceNumber: 3n, eventStreamType: 'Orders' } });
+        recording.unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 1 });
+        recording.unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 2 }, { concurrencyScope: { eventStreamType: 'Orders', sequenceNumber: 3n } });
+        recording.unitOfWork.addEvent(EventSequenceId.eventLog, 'b-1', { order: 3 }, { concurrencyScope: { sequenceNumber: 9n } });
+        await recording.unitOfWork.commit();
+        appends = recording.appends;
+    });
+
+    it('should append every event', () => appends[0].events.should.have.lengthOf(4));
+    it('should pass one scope per event source', () => appends[0].options.concurrencyScopes!.should.deep.equal({
+        'a-1': { sequenceNumber: 3n, eventStreamType: 'Orders' },
+        'b-1': { sequenceNumber: 9n }
+    }));
+    it('should keep the correlation of the unit of work', () => appends[0].options.should.have.property('correlationId'));
+});

package/transactions/for_UnitOfWork/when_adding_events_with_concurrency_scopes/and_the_scopes_differ_for_one_event_source.spec.ts

@@ -0,0 +1,29 @@
+// 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 { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { ConflictingConcurrencyScopesInUnitOfWork } from '../../ConflictingConcurrencyScopesInUnitOfWork.js';
+import { a_unit_of_work_with_a_recording_store } from '../given/a_unit_of_work_with_a_recording_store.js';
+import type { UnitOfWork } from '../../UnitOfWork.js';
+
+chai.should();
+
+describe('when adding events with concurrency scopes and the scopes differ for one event source', () => {
+    let unitOfWork: UnitOfWork;
+    let error: unknown;
+
+    beforeEach(() => {
+        ({ unitOfWork } = a_unit_of_work_with_a_recording_store());
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { concurrencyScope: { sequenceNumber: 1n } });
+        try {
+            unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 1 }, { concurrencyScope: { sequenceNumber: 2n } });
+        } catch (caught) {
+            error = caught;
+        }
+    });
+
+    it('should reject the conflicting event', () => error!.should.be.instanceOf(ConflictingConcurrencyScopesInUnitOfWork));
+    it('should not name the event source in the message', () => (error as Error).message.should.not.contain('a-1'));
+    it('should keep only the first event', () => unitOfWork.getEvents().should.deep.equal([{ order: 0 }]));
+});