@cratis/chronicle 6.49.0 → 6.51.0

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

package/transactions/for_UnitOfWork/when_committing_events_with_append_metadata/and_a_later_event_sequence_fails.spec.ts

@@ -0,0 +1,30 @@
+// 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, successfulAppendResult, type RecordedAppend } from '../given/a_unit_of_work_with_a_recording_store.js';
+import type { UnitOfWork } from '../../UnitOfWork.js';
+
+chai.should();
+
+describe('when committing events with append metadata and a later event sequence fails', () => {
+    let unitOfWork: UnitOfWork;
+    let appends: RecordedAppend[];
+    let error: unknown;
+
+    beforeEach(async () => {
+        const recording = a_unit_of_work_with_a_recording_store(async eventSequenceId => {
+            if (eventSequenceId === 'outbox') throw new Error('Kernel unavailable');
+            return [successfulAppendResult(0n)];
+        });
+        ({ unitOfWork, appends } = recording);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { subject: 'first' });
+        unitOfWork.addEvent(new EventSequenceId('outbox'), 'a-1', { order: 1 }, { subject: 'second' });
+        error = await unitOfWork.commit().catch(caught => caught);
+    });
+
+    it('should reject the commit', () => (error as Error).message.should.equal('Kernel unavailable'));
+    it('should have written the earlier event sequence, since appends to separate sequences are not atomic', () => appends[0].events[0].subject!.should.equal('first'));
+    it('should not mark the unit of work completed', () => unitOfWork.isCompleted.should.be.false);
+});

package/transactions/for_UnitOfWork/when_committing_events_with_append_metadata/and_events_span_event_sequences.spec.ts

@@ -0,0 +1,34 @@
+// 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 type { AppendResult } from '../../../eventSequences/AppendResult.js';
+import { a_unit_of_work_with_a_recording_store, successfulAppendResult, type RecordedAppend } from '../given/a_unit_of_work_with_a_recording_store.js';
+
+chai.should();
+
+describe('when committing events with append metadata and events span event sequences', () => {
+    const outbox = new EventSequenceId('outbox');
+    const scope = { sequenceNumber: 4n, eventSourceId: true };
+    let appends: RecordedAppend[];
+    let results: ReadonlyArray<AppendResult>;
+
+    beforeEach(async () => {
+        const recording = a_unit_of_work_with_a_recording_store(async (eventSequenceId, events) =>
+            events.map((_, index) => successfulAppendResult(BigInt(eventSequenceId === 'outbox' ? 100 + index : index))));
+        recording.unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { subject: 'log-subject', concurrencyScope: scope });
+        recording.unitOfWork.addEvent(outbox, 'a-1', { order: 1 }, { subject: 'outbox-subject' });
+        recording.unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 2 });
+        await recording.unitOfWork.commit();
+        appends = recording.appends;
+        results = recording.unitOfWork.getAppendResults();
+    });
+
+    it('should append once per event sequence', () => appends.map(_ => _.eventSequenceId).should.deep.equal([EventSequenceId.eventLog.value, 'outbox']));
+    it('should keep the subject in the event log append', () => appends[0].events[0].subject!.should.equal('log-subject'));
+    it('should keep the subject in the outbox append', () => appends[1].events[0].subject!.should.equal('outbox-subject'));
+    it('should pass the scope to the event log append', () => appends[0].options.concurrencyScopes!.should.deep.equal({ 'a-1': scope }));
+    it('should not pass the scope to the outbox append', () => appends[1].options.should.not.have.property('concurrencyScopes'));
+    it('should report results in input order', () => results.map(_ => _.sequenceNumber.value).should.deep.equal([0n, 100n, 1n]));
+});

package/transactions/for_UnitOfWork/when_committing_events_with_append_metadata/and_options_differ_per_event.spec.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 { beforeEach, chai, describe, it } from 'vitest';
+import { Tag } from '../../../events/Tag.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import type { EventForEventSourceId } from '../../../eventSequences/EventForEventSourceId.js';
+import { a_unit_of_work_with_a_recording_store } from '../given/a_unit_of_work_with_a_recording_store.js';
+
+const should = chai.should();
+
+describe('when committing events with append metadata and options differ per event', () => {
+    const occurred = new Date('2026-01-02T03:04:05.000Z');
+    const first = { name: 'first' };
+    const second = { name: 'second' };
+    const third = { name: 'third' };
+    let batch: EventForEventSourceId[];
+
+    beforeEach(async () => {
+        const { unitOfWork, appends } = a_unit_of_work_with_a_recording_store();
+        const tags = ['priority'];
+        const occurredInput = new Date(occurred.getTime());
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', first, {
+            eventStreamType: 'Orders', eventStreamId: 'order-1', eventSourceType: 'Customer',
+            subject: 'subject-1', occurred: occurredInput, tags
+        });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'b-1', second, { tags: [new Tag('audit')] });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', third);
+        tags.push('mutated-after-enrollment');
+        occurredInput.setUTCFullYear(1999);
+        await unitOfWork.commit();
+        batch = appends[0].events;
+    });
+
+    it('should append the events in input order', () => batch.map(_ => _.event).should.deep.equal([first, second, third]));
+    it('should keep the stream type of the first event', () => batch[0].eventStreamType!.should.equal('Orders'));
+    it('should keep the stream id of the first event', () => batch[0].eventStreamId!.should.equal('order-1'));
+    it('should keep the source type of the first event', () => batch[0].eventSourceType!.should.equal('Customer'));
+    it('should keep the subject of the first event', () => batch[0].subject!.should.equal('subject-1'));
+    it('should keep the occurrence time given at enrollment', () => batch[0].occurred!.toISOString().should.equal(occurred.toISOString()));
+    it('should keep the tags given at enrollment', () => batch[0].tags!.should.deep.equal(['priority']));
+    it('should keep the tags of the second event', () => batch[1].tags!.map(String).should.deep.equal(['audit']));
+    it('should not give the third event any metadata', () => Object.keys(batch[2]).sort().should.deep.equal(['event', 'eventSourceId']));
+    it('should not leak the subject of the first event to the second', () => should.not.exist(batch[1].subject));
+});

package/transactions/for_UnitOfWork/when_committing_events_with_append_metadata/and_the_append_is_rejected.spec.ts

@@ -0,0 +1,26 @@
+// 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 { EventSequenceNumber } from '../../../eventSequences/EventSequenceNumber.js';
+import { a_unit_of_work_with_a_recording_store, successfulAppendResult } from '../given/a_unit_of_work_with_a_recording_store.js';
+import type { UnitOfWork } from '../../UnitOfWork.js';
+
+chai.should();
+
+describe('when committing events with append metadata and the append is rejected', () => {
+    const violation = { eventSourceId: 'a-1', expectedSequenceNumber: new EventSequenceNumber(1n), actualSequenceNumber: new EventSequenceNumber(5n) };
+    let unitOfWork: UnitOfWork;
+
+    beforeEach(async () => {
+        ({ unitOfWork } = a_unit_of_work_with_a_recording_store(async () => [
+            { ...successfulAppendResult(0n), isSuccess: false, concurrencyViolation: violation }
+        ]));
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { concurrencyScope: { sequenceNumber: 1n } });
+        await unitOfWork.commit();
+    });
+
+    it('should not report success', () => unitOfWork.isSuccess.should.be.false);
+    it('should surface the concurrency violation', () => unitOfWork.getConcurrencyViolations().should.deep.equal([violation]));
+});

package/transactions/for_UnitOfWork/when_committing_events_with_named_tags.spec.ts

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

package/transactions/for_UnitOfWork/when_rolling_back_events_with_append_metadata.spec.ts

@@ -0,0 +1,24 @@
+// 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, type Mock } from 'vitest';
+import { EventSequenceId } from '../../eventSequences/EventSequenceId.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 rolling back events with append metadata', () => {
+    let unitOfWork: UnitOfWork;
+    let record: Mock;
+
+    beforeEach(async () => {
+        ({ unitOfWork, record } = a_unit_of_work_with_a_recording_store());
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { order: 0 }, { subject: 'subject-1', concurrencyScope: { sequenceNumber: 1n } });
+        await unitOfWork.rollback();
+    });
+
+    it('should drop the buffered events', () => unitOfWork.getEvents().should.be.empty);
+    it('should not append anything', () => record.mock.calls.should.be.empty);
+    it('should reject a later commit', async () => (await unitOfWork.commit().catch(caught => caught)).should.be.instanceOf(Error));
+});

package/transactions/index.ts

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

package/transactions/toEventForEventSourceId.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 type { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
+import type { TransactionalAppendOptions } from './TransactionalAppendOptions.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
+
+/**
+ * Captures an event and its transactional append metadata as the batch entry appended on commit.
+ * Only supplied values become keys, and tags and occurrence time are copied so later caller mutations do not leak in.
+ * The concurrency scope is not part of the entry; the unit of work passes it per event source identifier.
+ * @param eventSourceId - The event source identifier.
+ * @param event - The event payload.
+ * @param options - Optional transactional append metadata.
+ * @returns The batch entry.
+ */
+export function toEventForEventSourceId(eventSourceId: string, event: object, options?: TransactionalAppendOptions): EventForEventSourceId {
+    const namedTags = mergeNamedTags(options?.namedTags);
+    return {
+        eventSourceId,
+        event,
+        ...(options?.eventSource !== undefined ? { eventSource: options.eventSource } : {}),
+        ...(options?.eventStream !== undefined ? { eventStream: options.eventStream } : {}),
+        ...(options?.eventStreamType !== undefined ? { eventStreamType: options.eventStreamType } : {}),
+        ...(options?.eventStreamId !== undefined ? { eventStreamId: options.eventStreamId } : {}),
+        ...(options?.eventSourceType !== undefined ? { eventSourceType: options.eventSourceType } : {}),
+        ...(options?.occurred !== undefined ? { occurred: new Date(options.occurred.getTime()) } : {}),
+        ...(options?.subject !== undefined ? { subject: options.subject } : {}),
+        ...(options?.tags !== undefined ? { tags: [...options.tags] } : {}),
+        ...(namedTags.length > 0 ? { namedTags } : {})
+    };
+}

package/vitest.integration.config.ts

@@ -7,6 +7,8 @@ import baseConfig from './vitest.config.js';
 // Kernel-backed specifications. They need a running Chronicle kernel and are skipped unless
 // CHRONICLE_INTEGRATION_CONNECTION_STRING points at one, for example
 // chronicle://chronicle-dev-client:chronicle-dev-secret@localhost:35000
+// The webhook delivery specifications also need the kernel to reach this process over HTTP, as
+// host.docker.internal by default; set CHRONICLE_INTEGRATION_WEBHOOK_HOST when it reaches it differently.
 export default defineConfig({
     ...baseConfig,
     test: {

package/webhooks/for_Webhooks/against_a_kernel/given/ReceivedWebhookRequest.fixture.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { IncomingHttpHeaders } from 'node:http';
+
+/**
+ * A request the kernel delivered to a {@link WebhookReceiver}.
+ */
+export interface ReceivedWebhookRequest {
+    /** The HTTP method. */
+    readonly method: string;
+
+    /** The request path, including any query string. */
+    readonly path: string;
+
+    /** The request headers, with lowercase names. */
+    readonly headers: IncomingHttpHeaders;
+
+    /** The raw request body. */
+    readonly body: string;
+}