@cratis/chronicle 6.50.0 → 6.51.1

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

@@ -8,3 +8,4 @@ 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;
+}

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

@@ -0,0 +1,99 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { ReceivedWebhookRequest } from './ReceivedWebhookRequest.fixture.js';
+
+/**
+ * The host name the kernel container uses to reach this process. Docker Desktop resolves
+ * host.docker.internal natively; on Linux (CI) the kernel container maps it to the host gateway
+ * (--add-host=host.docker.internal:host-gateway, see .github/workflows/build.yml).
+ * Override with CHRONICLE_INTEGRATION_WEBHOOK_HOST when the kernel reaches this process differently.
+ */
+const receiverHost = process.env.CHRONICLE_INTEGRATION_WEBHOOK_HOST ?? 'host.docker.internal';
+
+/**
+ * A local HTTP endpoint the kernel delivers webhook requests to. It records every request and
+ * answers each with a fixed status code.
+ */
+export class WebhookReceiver {
+    private readonly _requests: ReceivedWebhookRequest[] = [];
+    private _server: Server | undefined;
+    private _port = 0;
+
+    /**
+     * Initializes a new instance of the {@link WebhookReceiver} class.
+     * @param _statusCode - The status code to answer every request with.
+     */
+    constructor(private readonly _statusCode: number) {}
+
+    /** Gets the requests received so far, in arrival order. */
+    get requests(): ReadonlyArray<ReceivedWebhookRequest> {
+        return this._requests;
+    }
+
+    /**
+     * Starts listening on all interfaces on a free port, so a kernel container can reach it.
+     */
+    async start(): Promise<void> {
+        const server = createServer((request, response) => {
+            const chunks: Buffer[] = [];
+            request.on('data', (chunk: Buffer) => chunks.push(chunk));
+            request.on('end', () => {
+                this._requests.push({
+                    method: request.method ?? '',
+                    path: request.url ?? '',
+                    headers: request.headers,
+                    body: Buffer.concat(chunks).toString('utf8')
+                });
+                response.statusCode = this._statusCode;
+                response.end();
+            });
+        });
+        await new Promise<void>((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(0, '0.0.0.0', () => resolve());
+        });
+        this._server = server;
+        this._port = (server.address() as AddressInfo).port;
+    }
+
+    /**
+     * Gets the URL the kernel should deliver to for the given path.
+     * @param path - The path, starting with a slash.
+     * @returns The URL as seen from the kernel.
+     */
+    urlFor(path: string): string {
+        return `http://${receiverHost}:${this._port}${path}`;
+    }
+
+    /**
+     * Waits until at least the given number of requests have arrived.
+     * @param count - The number of requests to wait for.
+     * @param timeoutMs - How long to wait before failing.
+     * @returns The requests received.
+     */
+    async waitForRequests(count: number, timeoutMs = 30_000): Promise<ReadonlyArray<ReceivedWebhookRequest>> {
+        const deadline = Date.now() + timeoutMs;
+        while (this._requests.length < count) {
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out waiting for ${count} webhook request(s); received ${this._requests.length}. ` +
+                    `Is ${receiverHost} reachable from the kernel?`);
+            }
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        return this._requests;
+    }
+
+    /**
+     * Stops listening.
+     */
+    async stop(): Promise<void> {
+        const server = this._server;
+        if (!server) return;
+        this._server = undefined;
+        server.closeAllConnections();
+        await new Promise<void>(resolve => server.close(() => resolve()));
+    }
+}