@cratis/chronicle 6.48.0 → 6.49.0

package/eventSources/for_EventSources/against_a_kernel/when_appending_through_registered_sources.integration.spec.ts

@@ -0,0 +1,106 @@
+// 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, ConcurrencyDimensions, eventSource, eventStream, eventType,
+    type IClientArtifactsProvider, type IEventStore } from '../../../index.js';
+
+const should = chai.should();
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class FundsDeposited { @field(Number) amount = 0; }
+
+@eventSource({ name: 'Account', description: 'A bank account', concurrency: ConcurrencyDimensions.eventSourceId })
+@eventStream('Transactions', { description: 'Money movements' })
+class AccountEventSource {}
+
+@eventSource({ name: 'Customer' })
+class CustomerEventSource {}
+
+@eventSource({ name: 'Ledger' })
+@eventStream('Monthly', { concurrency: ConcurrencyDimensions.eventSourceId | ConcurrencyDimensions.eventStreamId })
+class LedgerEventSource {}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [FundsDeposited], eventSources: [AccountEventSource, CustomerEventSource, LedgerEventSource], readModels: [], reactors: [], reducers: [],
+    seeders: [], constraints: [], projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+};
+
+const sequenceStart = EventSequenceNumber.first;
+const deposit = (amount: number) => Object.assign(new FundsDeposited(), { amount });
+
+describe.skipIf(!connectionString && !process.env.CI)('when appending through registered event sources against a kernel', () => {
+    const storeName = `Sources${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    let client: ChronicleClient;
+    let store: IEventStore;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, { discoveryPatterns: [], clientArtifactsProvider: artifacts }));
+        store = await client.getEventStore(storeName);
+    });
+    afterAll(() => client?.dispose());
+
+    // The sequence-number read does not narrow by route, so it also returns events routed through a definition.
+    const eventsFor = (id: string) => store.eventLog.getFromSequenceNumber(sequenceStart, id, [FundsDeposited]);
+
+    it('should register the definitions with the kernel', async () => {
+        const connection = (store as unknown as { _connection: { eventSources: { allEventSources(request: unknown): Promise<{ Data: Array<{ Name: string; Streams: Array<{ Name: string }> }> }> } } })._connection;
+        const response = await connection.eventSources.allEventSources({ EventStore: storeName });
+        const account = response.Data.find(_ => _.Name === 'Account');
+        should.exist(account);
+        account!.Streams.map(_ => _.Name).should.deep.equal(['Transactions']);
+        response.Data.some(_ => _.Name === 'Customer').should.equal(true);
+    });
+
+    it('should round-trip the event source and stream on appended events', async () => {
+        const id = randomUUID();
+        const result = await store.eventLog.append(id, deposit(10), { eventSource: AccountEventSource, eventStream: 'Transactions', streamId: 'tx-1' });
+        result.isSuccess.should.equal(true);
+        const [event] = await eventsFor(id);
+        event.context.eventSource!.should.equal('Account');
+        event.context.eventSourceType!.should.equal('Account');
+        event.context.eventStreamType!.should.equal('Transactions');
+    });
+
+    it('should leave the source unset for legacy appends', async () => {
+        const id = randomUUID();
+        await store.eventLog.append(id, deposit(1));
+        const [event] = await eventsFor(id);
+        should.equal(event.context.eventSource, undefined);
+    });
+
+    it('should reject a stale explicit scope on append-many and keep the batch atomic', async () => {
+        const id = randomUUID();
+        await store.eventLog.appendMany(id, [deposit(1), deposit(2)], { eventSource: 'Account' });
+        const stale = { sequenceNumber: 0n, eventSourceId: true };
+        const result = await store.eventLog.appendMany(id, [deposit(3)], { eventSource: 'Account', concurrencyScope: stale }).catch(error => error);
+        const events = await eventsFor(id);
+        events.should.have.length(2);
+        (result instanceof Error || result.some((appended: { isSuccess: boolean }) => !appended.isSuccess)).should.equal(true);
+    });
+
+    it('should route a mixed-source batch per event', async () => {
+        const account = randomUUID(); const customer = randomUUID();
+        await store.eventLog.appendMany([
+            { eventSourceId: account, event: deposit(1) },
+            { eventSourceId: customer, event: deposit(2), eventSource: CustomerEventSource }
+        ], { eventSource: AccountEventSource });
+        const [accountEvent] = await eventsFor(account);
+        const [customerEvent] = await eventsFor(customer);
+        accountEvent.context.eventSource!.should.equal('Account');
+        customerEvent.context.eventSource!.should.equal('Customer');
+    });
+
+    it('should guard a shared event source id once and reject differing guards without writing', async () => {
+        const id = randomUUID();
+        const ledger = (streamId: string) => ({ eventSourceId: id, event: deposit(1), eventSource: LedgerEventSource, eventStream: 'Monthly', eventStreamId: streamId });
+        const shared = await store.eventLog.appendMany([ledger('2026-01'), ledger('2026-01')]);
+        shared.every(_ => _.isSuccess).should.equal(true);
+        const error = await store.eventLog.appendMany([ledger('2026-01'), ledger('2026-02')]).catch(e => e as Error);
+        (error instanceof Error).should.equal(true);
+        (await eventsFor(id)).should.have.length(2);
+    });
+});

package/eventSources/for_EventSources/when_appending_through_a_definition.spec.ts

@@ -0,0 +1,190 @@
+// 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, vi } from 'vitest';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { EventSequence, EventSequenceId } from '../../eventSequences/index.js';
+import { eventType } from '../../events/index.js';
+import type { IUnitOfWorkManager } from '../../transactions/index.js';
+import {
+    ConcurrencyDimensions, eventSource, eventStream, EventSources,
+    EventRoutingContradictsEventSource, EventStreamDoesNotBelongToEventSource, EventStreamRequiresEventSource, UnknownEventSource
+} from '../index.js';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+
+const should = chai.should();
+class Deposited { constructor(readonly amount = 1) {} }
+eventType('DepositedToAccount')(Deposited);
+
+@eventSource({ concurrency: ConcurrencyDimensions.eventSourceId })
+@eventStream('Transactions', { concurrency: ConcurrencyDimensions.eventSourceId | ConcurrencyDimensions.eventStreamType })
+class AccountEventSource {}
+
+@eventSource({ name: 'Customer' })
+@eventStream('Profile')
+class CustomerEventSource {}
+
+@eventSource({ name: 'Plain' })
+class PlainEventSource {}
+
+async function create(tail = 7n) {
+    const append = vi.fn().mockResolvedValue({ Response: { SequenceNumber: 0n } });
+    const appendManyForEventSources = vi.fn().mockResolvedValue({ Response: { SequenceNumbers: [0n, 1n] } });
+    const tailSequenceNumber = vi.fn().mockResolvedValue({ Data: { SequenceNumber: tail } });
+    const connection = { eventSequences: { append, appendManyForEventSources, tailSequenceNumber } } as unknown as ChronicleConnection;
+    const sources = new EventSources('store', connection, { eventSources: [AccountEventSource, CustomerEventSource, PlainEventSource] } as unknown as IClientArtifactsProvider);
+    await sources.discover();
+    return { sequence: new EventSequence(EventSequenceId.eventLog, 'store', 'ns', connection, {} as IUnitOfWorkManager, undefined, undefined, sources), append, appendManyForEventSources, tailSequenceNumber };
+}
+
+describe('when appending through a definition and stream', () => {
+    let request: any; let tailRequest: any;
+    beforeEach(async () => {
+        const c = await create();
+        await c.sequence.append('acc-1', new Deposited(), { eventSource: AccountEventSource, eventStream: 'Transactions', streamId: 'tx-1' });
+        request = c.append.mock.calls[0][0];
+        tailRequest = c.tailSequenceNumber.mock.calls[0][0];
+    });
+    it('should set the wire event source key and routing', () => {
+        request.EventSource.should.equal('Account');
+        request.EventSourceType.should.equal('Account');
+        request.EventStreamType.should.equal('Transactions');
+        request.EventStreamId.should.equal('tx-1');
+    });
+    it('should derive the scope from the stream dimensions', () => {
+        request.ConcurrencyScope.SequenceNumber.should.equal(7n);
+        request.ConcurrencyScope.EventSourceId.should.equal(true);
+        request.ConcurrencyScope.EventStreamType.should.equal('Transactions');
+        request.ConcurrencyScope.EventSourceType.should.equal('');
+    });
+    it('should read the tail with exactly the scoped dimensions', () => {
+        tailRequest.EventSourceId.should.equal('acc-1');
+        tailRequest.EventStreamType.should.equal('Transactions');
+        tailRequest.EventSourceType.should.equal('');
+    });
+});
+
+describe('when appending through a definition by name without a stream', () => {
+    it('should use the source dimensions and leave the stream to the kernel', async () => {
+        const c = await create();
+        await c.sequence.append('acc-1', new Deposited(), { eventSource: 'Account' });
+        const request = c.append.mock.calls[0][0];
+        request.EventSource.should.equal('Account');
+        should.equal(request.EventStreamType, undefined);
+        request.ConcurrencyScope.EventSourceId.should.equal(true);
+        request.ConcurrencyScope.EventStreamType.should.equal('');
+    });
+    it('should expect no matching event when the scope is empty', async () => {
+        const c = await create(18446744073709551615n);
+        await c.sequence.append('acc-1', new Deposited(), { eventSource: 'Account' });
+        c.append.mock.calls[0][0].ConcurrencyScope.ExpectsNoMatchingEvent.should.equal(true);
+    });
+});
+
+describe('when an explicit concurrency scope is given', () => {
+    it('should win over the definition and not read the tail', async () => {
+        const c = await create();
+        await c.sequence.append('acc-1', new Deposited(), { eventSource: 'Account', concurrencyScope: { sequenceNumber: 3n } });
+        c.append.mock.calls[0][0].ConcurrencyScope.SequenceNumber.should.equal(3n);
+        c.tailSequenceNumber.mock.calls.length.should.equal(0);
+    });
+});
+
+describe('when the definition declares no concurrency', () => {
+    it('should not add a scope', async () => {
+        const c = await create();
+        await c.sequence.append('c-1', new Deposited(), { eventSource: 'Plain' });
+        const request = c.append.mock.calls[0][0];
+        request.EventSource.should.equal('Plain');
+        request.ConcurrencyScope.SequenceNumber.should.equal(18446744073709551615n);
+        c.tailSequenceNumber.mock.calls.length.should.equal(0);
+    });
+});
+
+describe('when appending without a definition', () => {
+    it('should keep legacy behavior and send no event source key', async () => {
+        const c = await create();
+        await c.sequence.append('acc-1', new Deposited(), { sourceType: 'Legacy' });
+        const request = c.append.mock.calls[0][0];
+        should.equal(request.EventSource, undefined);
+        request.EventSourceType.should.equal('Legacy');
+    });
+});
+
+describe('when routing is invalid', () => {
+    it('should reject an unknown source', async () => {
+        const c = await create();
+        let error: unknown; await c.sequence.append('a', new Deposited(), { eventSource: 'Ghost' }).catch(e => error = e);
+        (error as Error).should.be.instanceOf(UnknownEventSource);
+        c.append.mock.calls.length.should.equal(0);
+    });
+    it('should reject an undeclared stream', async () => {
+        const c = await create();
+        let error: unknown; await c.sequence.append('a', new Deposited(), { eventSource: 'Account', eventStream: 'Profile' }).catch(e => error = e);
+        (error as Error).should.be.instanceOf(EventStreamDoesNotBelongToEventSource);
+    });
+    it('should reject a stream without a source', async () => {
+        const c = await create();
+        let error: unknown; await c.sequence.append('a', new Deposited(), { eventStream: 'Transactions' }).catch(e => error = e);
+        (error as Error).should.be.instanceOf(EventStreamRequiresEventSource);
+    });
+    it('should reject a contradicting explicit source type or stream type', async () => {
+        const c = await create();
+        const errors: unknown[] = [];
+        await c.sequence.append('a', new Deposited(), { eventSource: 'Account', sourceType: 'Other' }).catch(e => errors.push(e));
+        await c.sequence.append('a', new Deposited(), { eventSource: 'Account', eventStream: 'Transactions', streamType: 'Other' }).catch(e => errors.push(e));
+        errors.every(e => e instanceof EventRoutingContradictsEventSource).should.equal(true);
+        errors.should.have.length(2);
+    });
+    it('should accept explicit values that agree', async () => {
+        const c = await create();
+        await c.sequence.append('a', new Deposited(), { eventSource: 'Account', eventStream: 'Transactions', sourceType: 'Account', streamType: 'Transactions' });
+        c.append.mock.calls.length.should.equal(1);
+    });
+});
+
+describe('when appending many through a definition', () => {
+    it('should route every event and derive one scope per event source id', async () => {
+        const c = await create();
+        await c.sequence.appendMany('acc-1', [new Deposited(), new Deposited()], { eventSource: 'Account', eventStream: 'Transactions' });
+        const request = c.appendManyForEventSources.mock.calls[0][0];
+        request.Events.map((e: any) => e.EventSource).should.deep.equal(['Account', 'Account']);
+        request.Events.map((e: any) => e.EventStreamType).should.deep.equal(['Transactions', 'Transactions']);
+        request.ConcurrencyScopes.should.have.length(1);
+        request.ConcurrencyScopes[0].EventSourceId.should.equal('acc-1');
+        request.ConcurrencyScopes[0].Scope.SequenceNumber.should.equal(7n);
+    });
+    it('should let per-event routing override shared options in a mixed batch without inheriting the stream', async () => {
+        const c = await create();
+        await c.sequence.appendMany([
+            { eventSourceId: 'acc-1', event: new Deposited() },
+            { eventSourceId: 'cust-1', event: new Deposited(), eventSource: CustomerEventSource },
+            { eventSourceId: 'cust-2', event: new Deposited(), eventSource: 'Customer', eventStream: 'Profile' },
+            { eventSourceId: 'old-1', event: new Deposited(), eventSource: 'Plain' }
+        ], { eventSource: 'Account', eventStream: 'Transactions' });
+        const events = c.appendManyForEventSources.mock.calls[0][0].Events;
+        events.map((e: any) => e.EventSource).should.deep.equal(['Account', 'Customer', 'Customer', 'Plain']);
+        events.map((e: any) => e.EventStreamType).should.deep.equal(['Transactions', undefined, 'Profile', undefined]);
+        events.map((e: any) => e.EventSourceType).should.deep.equal(['Account', 'Customer', 'Customer', 'Plain']);
+    });
+    it('should let an explicit per-id scope win and a shared scope win over derivation', async () => {
+        const c = await create();
+        await c.sequence.appendMany([
+            { eventSourceId: 'acc-1', event: new Deposited() },
+            { eventSourceId: 'acc-2', event: new Deposited() }
+        ], { eventSource: 'Account', concurrencyScopes: { 'acc-1': { sequenceNumber: 1n } } });
+        const scopes = c.appendManyForEventSources.mock.calls[0][0].ConcurrencyScopes;
+        scopes.find((s: any) => s.EventSourceId === 'acc-1').Scope.SequenceNumber.should.equal(1n);
+        scopes.find((s: any) => s.EventSourceId === 'acc-2').Scope.SequenceNumber.should.equal(7n);
+    });
+    it('should send nothing when any event routing is invalid (atomic)', async () => {
+        const c = await create();
+        let error: unknown;
+        await c.sequence.appendMany([
+            { eventSourceId: 'a', event: new Deposited() },
+            { eventSourceId: 'b', event: new Deposited(), eventSource: 'Ghost' }
+        ], { eventSource: 'Account' }).catch(e => error = e);
+        (error as Error).should.be.instanceOf(UnknownEventSource);
+        c.appendManyForEventSources.mock.calls.length.should.equal(0);
+    });
+});

package/eventSources/for_EventSources/when_batch_requires_differing_guards.spec.ts

@@ -0,0 +1,139 @@
+// 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 { chai, describe, it, vi } from 'vitest';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { EventSequence, EventSequenceId } from '../../eventSequences/index.js';
+import { eventType } from '../../events/index.js';
+import { UnitOfWork } from '../../transactions/UnitOfWork.js';
+import type { IUnitOfWorkManager } from '../../transactions/index.js';
+import { ConcurrencyDimensions, eventSource, eventStream, EventSources } from '../index.js';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+import type { IEventStore } from '../../IEventStore.js';
+
+chai.should();
+class Booked { constructor(readonly amount = 1) {} }
+eventType('BookedToLedger')(Booked);
+
+const sourceAndStreamId = ConcurrencyDimensions.eventSourceId | ConcurrencyDimensions.eventStreamType | ConcurrencyDimensions.eventStreamId;
+
+@eventSource({ name: 'Ledger' })
+@eventStream('Monthly', { concurrency: sourceAndStreamId })
+class LedgerEventSource {}
+
+@eventSource({ name: 'Archive', concurrency: ConcurrencyDimensions.eventSourceId })
+class ArchiveEventSource {}
+
+@eventSource({ name: 'Mirror' })
+@eventStream('Monthly', { concurrency: sourceAndStreamId })
+class MirrorEventSource {}
+
+@eventSource({ name: 'Open' })
+class OpenEventSource {}
+
+@eventSource({ name: 'Routed', concurrency: ConcurrencyDimensions.eventSourceId })
+class RoutedEventSource {}
+
+async function create() {
+    const appendManyForEventSources = vi.fn().mockResolvedValue({ Response: { SequenceNumbers: [0n, 1n] } });
+    const tailSequenceNumber = vi.fn().mockResolvedValue({ Data: { SequenceNumber: 5n } });
+    const connection = { eventSequences: { appendManyForEventSources, tailSequenceNumber } } as unknown as ChronicleConnection;
+    const sources = new EventSources('store', connection, {
+        eventSources: [LedgerEventSource, ArchiveEventSource, MirrorEventSource, OpenEventSource, RoutedEventSource]
+    } as unknown as IClientArtifactsProvider);
+    await sources.discover();
+    const sequence = new EventSequence(EventSequenceId.eventLog, 'store', 'ns', connection, {} as IUnitOfWorkManager, undefined, undefined, sources);
+    return { sequence, appendManyForEventSources, tailSequenceNumber, sources };
+}
+
+const ledger = (streamId: string, eventSourceId = 'a-1') =>
+    ({ eventSourceId, event: new Booked(), eventSource: LedgerEventSource, eventStream: 'Monthly', eventStreamId: streamId });
+
+describe('when a batch needs differing stream id guards for one event source id', () => {
+    it('should throw before any wire write', async () => {
+        const c = await create();
+        let error: Error | undefined;
+        try { await c.sequence.appendMany([ledger('2026-01'), ledger('2026-02')]); } catch (e) { error = e as Error; }
+        (error?.message ?? '').should.contain("'a-1'").and.contain('separate batches');
+        c.appendManyForEventSources.mock.calls.length.should.equal(0);
+        c.tailSequenceNumber.mock.calls.length.should.equal(0);
+    });
+});
+
+describe('when a batch has the same stream id guard repeated', () => {
+    it('should send one shared scope for the id', async () => {
+        const c = await create();
+        await c.sequence.appendMany([ledger('2026-01'), ledger('2026-01')]);
+        const scopes = c.appendManyForEventSources.mock.calls[0][0].ConcurrencyScopes;
+        scopes.length.should.equal(1);
+        scopes[0].Scope.EventStreamId.should.equal('2026-01');
+    });
+});
+
+describe('when a batch needs differing guards from different definitions for one id', () => {
+    it('should throw before any wire write', async () => {
+        const c = await create();
+        let error: Error | undefined;
+        try {
+            await c.sequence.appendMany([ledger('2026-01'), { eventSourceId: 'a-1', event: new Booked(), eventSource: ArchiveEventSource }]);
+        } catch (e) { error = e as Error; }
+        (error?.message ?? '').should.contain('differing concurrency guards');
+        c.appendManyForEventSources.mock.calls.length.should.equal(0);
+    });
+});
+
+describe('when equivalent guards differ only in values the dimensions do not select', () => {
+    it('should share one conservative scope', async () => {
+        const c = await create();
+        await c.sequence.appendMany([
+            { eventSourceId: 'a-1', event: new Booked(), eventSource: ArchiveEventSource, eventStreamId: 'x' },
+            { eventSourceId: 'a-1', event: new Booked(), eventSource: ArchiveEventSource, eventStreamId: 'y' }
+        ]);
+        const scopes = c.appendManyForEventSources.mock.calls[0][0].ConcurrencyScopes;
+        scopes.length.should.equal(1);
+        scopes[0].Scope.EventSourceId.should.equal(true);
+    });
+});
+
+describe('when an unguarded definition event precedes a guarded one for the same id', () => {
+    it('should still guard the id', async () => {
+        const c = await create();
+        await c.sequence.appendMany([
+            { eventSourceId: 'a-1', event: new Booked(), eventSource: OpenEventSource },
+            { eventSourceId: 'a-1', event: new Booked(), eventSource: ArchiveEventSource }
+        ]);
+        const scopes = c.appendManyForEventSources.mock.calls[0][0].ConcurrencyScopes;
+        scopes[0].Scope.EventSourceId.should.equal(true);
+        scopes[0].Scope.SequenceNumber.should.equal(5n);
+    });
+});
+
+describe('when an explicit broader scope exists for the id', () => {
+    it('should send it and not require agreement between the derived guards', async () => {
+        const c = await create();
+        await c.sequence.appendMany([ledger('2026-01'), ledger('2026-02')],
+            { concurrencyScopes: { 'a-1': { sequenceNumber: 3n, eventSourceId: true } } });
+        const scopes = c.appendManyForEventSources.mock.calls[0][0].ConcurrencyScopes;
+        scopes.length.should.equal(1);
+        scopes[0].Scope.SequenceNumber.should.equal(3n);
+        c.tailSequenceNumber.mock.calls.length.should.equal(0);
+    });
+});
+
+describe('when a unit of work holds a conflicting group after a valid group', () => {
+    it('should reject on commit before any group is written', async () => {
+        const c = await create();
+        const appendMany = vi.fn().mockResolvedValue([]);
+        const store = { eventSources: c.sources, getEventSequence: () => ({ appendMany }) } as unknown as IEventStore;
+        const unitOfWork = new UnitOfWork(Guid.create(), () => {}, store);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'ok-1', new Booked(), { eventSource: ArchiveEventSource });
+        const other = new EventSequenceId('other');
+        unitOfWork.addEvent(other, 'a-1', new Booked(), { eventSource: LedgerEventSource, eventStream: 'Monthly' });
+        unitOfWork.addEvent(other, 'a-1', new Booked(), { eventSource: ArchiveEventSource });
+        let error: Error | undefined;
+        try { await unitOfWork.commit(); } catch (e) { error = e as Error; }
+        (error?.message ?? '').should.contain('differing concurrency guards');
+        appendMany.mock.calls.length.should.equal(0);
+    });
+});

package/eventSources/for_EventSources/when_discovering_and_registering.spec.ts

@@ -0,0 +1,94 @@
+// 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, vi } from 'vitest';
+import type { Constructor } from '@cratis/fundamentals';
+import type { ChronicleConnection } from '../../connection/index.js';
+import { ConcurrencyDimensions, eventSource, eventStream, EventSources } from '../index.js';
+import { DuplicateEventSourceName } from '../DuplicateEventSourceName.js';
+import { DuplicateEventStreamName } from '../DuplicateEventStreamName.js';
+import { UnknownEventSource } from '../UnknownEventSource.js';
+import type { IClientArtifactsProvider } from '../../artifacts/index.js';
+
+const should = chai.should();
+
+@eventSource({ description: 'An account', concurrency: ConcurrencyDimensions.eventSourceId })
+@eventStream('Transactions', { description: 'Money moves', concurrency: ConcurrencyDimensions.eventSourceId | ConcurrencyDimensions.eventStreamType })
+@eventStream('Statements')
+class AccountEventSource {}
+
+@eventSource({ name: 'Same' }) class First {}
+@eventSource({ name: 'Same' }) class Second {}
+@eventSource({ name: 'Dup' })
+@eventStream('S') @eventStream('S')
+class DuplicateStreams {}
+
+function artifacts(...types: Constructor[]): IClientArtifactsProvider {
+    return { eventSources: types } as unknown as IClientArtifactsProvider;
+}
+
+function create(...types: Constructor[]) {
+    const registerEventSources = vi.fn().mockResolvedValue({ IsSuccess: true, ValidationResults: [], ExceptionMessages: [] });
+    const connection = { eventSources: { registerEventSources } } as unknown as ChronicleConnection;
+    return { sources: new EventSources('store', connection, artifacts(...types)), registerEventSources };
+}
+
+describe('when discovering a decorated event source', () => {
+    let sources: EventSources;
+    beforeEach(async () => {
+        ({ sources } = create(AccountEventSource));
+        await sources.discover();
+    });
+    it('should default the name by trimming the EventSource suffix', () => sources.all[0].name.should.equal('Account'));
+    it('should keep description and concurrency', () => {
+        sources.all[0].description.should.equal('An account');
+        sources.all[0].concurrency.should.equal(ConcurrencyDimensions.eventSourceId);
+    });
+    it('should keep streams in declaration order with their own dimensions', () => {
+        sources.all[0].streams.map(_ => _.name).should.deep.equal(['Transactions', 'Statements']);
+        sources.all[0].streams[0].concurrency.should.equal(5);
+        sources.all[0].streams[1].concurrency.should.equal(0);
+    });
+    it('should resolve by class and by name', () => {
+        sources.getFor(AccountEventSource).should.equal(sources.getFor('Account'));
+    });
+    it('should reject an unknown source', () => {
+        (() => sources.getFor('Nope')).should.throw(UnknownEventSource);
+    });
+});
+
+describe('when discovering duplicate names', () => {
+    it('should reject duplicate source names', async () => {
+        const { sources } = create(First, Second);
+        let error: unknown;
+        await sources.discover().catch(e => error = e);
+        (error as Error).should.be.instanceOf(DuplicateEventSourceName);
+    });
+    it('should reject duplicate stream names', async () => {
+        const { sources } = create(DuplicateStreams);
+        let error: unknown;
+        await sources.discover().catch(e => error = e);
+        (error as Error).should.be.instanceOf(DuplicateEventStreamName);
+    });
+});
+
+describe('when registering', () => {
+    it('should send the definitions with client ownership and wire dimension flags', async () => {
+        const { sources, registerEventSources } = create(AccountEventSource);
+        await sources.discover();
+        await sources.register();
+        const request = registerEventSources.mock.calls[0][0];
+        request.EventStore.should.equal('store');
+        request.Sources.should.have.length(1);
+        request.Sources[0].Name.should.equal('Account');
+        request.Sources[0].Owner.should.equal(1);
+        request.Sources[0].Concurrency.should.equal(1);
+        request.Sources[0].Streams[0].should.deep.equal({ Name: 'Transactions', Description: 'Money moves', Concurrency: 5 });
+    });
+    it('should not call the kernel when there are no definitions', async () => {
+        const { sources, registerEventSources } = create();
+        await sources.discover();
+        await sources.register();
+        should.equal(registerEventSources.mock.calls.length, 0);
+    });
+});

package/eventSources/index.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.
+
+export { ConcurrencyDimensions } from './ConcurrencyDimensions.js';
+export type { ConcurrencyDimensionFlags } from './ConcurrencyDimensions.js';
+export type { EventSourceDefinition } from './EventSourceDefinition.js';
+export type { EventStreamDefinition } from './EventStreamDefinition.js';
+export { eventSource, eventStream, getEventSourceMetadata, getEventStreamsFor } from './eventSource.js';
+export type { EventSourceOptions, EventStreamOptions, EventSourceMetadata, EventStreamMetadata } from './eventSource.js';
+export type { IEventSources } from './IEventSources.js';
+export { EventSources } from './EventSources.js';
+export { ResolvedEventRouting } from './ResolvedEventRouting.js';
+export type { ExplicitRouting } from './ResolvedEventRouting.js';
+export { UnknownEventSource } from './UnknownEventSource.js';
+export { DuplicateEventSourceName } from './DuplicateEventSourceName.js';
+export { DuplicateEventStreamName } from './DuplicateEventStreamName.js';
+export { EventStreamDoesNotBelongToEventSource } from './EventStreamDoesNotBelongToEventSource.js';
+export { EventRoutingContradictsEventSource } from './EventRoutingContradictsEventSource.js';
+export { EventStreamRequiresEventSource } from './EventStreamRequiresEventSource.js';

package/events/EventContext.ts

@@ -31,6 +31,12 @@ export interface EventContext {
     /** The stream identifier returned by the kernel. */
     readonly eventStreamId?: string;
 
+    /**
+     * The registered event source definition the event was appended through.
+     * Undefined for events appended without a definition, including events stored before event sources existed.
+     */
+    readonly eventSource?: string;
+
     /** The compliance subject returned by the kernel. */
     readonly subject?: string;
 

package/events/WireEventContext.ts

@@ -7,6 +7,8 @@ import type { AppendedEventResponse } from '@cratis/chronicle.contracts';
 export type WireEventContext = Omit<NonNullable<AppendedEventResponse['Context']>, 'ObservationState'> & {
     /** Numeric wire value shared by the generated observation-state enums. */
     ObservationState: number;
+    /** The registered event source name; empty or absent when the event was not appended through a definition. */
+    EventSource?: string;
     /** Store metadata is carried by observer deliveries, but not every read response. */
     EventStore?: string;
     /** Namespace metadata is carried by observer deliveries, but not every read response. */

package/events/for_EventContext/with_event_source.spec.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it, chai } from 'vitest';
+import { toClientEventContext } from '../toClientEventContext.js';
+import type { WireEventContext } from '../WireEventContext.js';
+
+const should = chai.should();
+const wire = (extra: Partial<WireEventContext>): WireEventContext => ({
+    EventSourceId: 's', SequenceNumber: 1n, ObservationState: 0, Tags: [], Causation: [],
+    EventType: { Id: 't', Generation: 1, Tombstone: false }, Occurred: { Value: '2025-01-01T00:00:00.000Z' }, ...extra
+} as unknown as WireEventContext);
+
+describe('when converting a kernel event context', () => {
+    it('should carry the registered event source', () => {
+        toClientEventContext(wire({ EventSource: 'Account' })).eventSource!.should.equal('Account');
+    });
+    it('should leave the source unset when the event was not appended through a definition', () => {
+        should.equal(toClientEventContext(wire({ EventSource: '' })).eventSource, undefined);
+        should.equal(toClientEventContext(wire({})).eventSource, undefined);
+    });
+});

package/events/toClientEventContext.ts

@@ -20,6 +20,7 @@ export function toClientEventContext(context: WireEventContext): EventContext {
         eventSourceType: context.EventSourceType,
         eventStreamType: context.EventStreamType,
         eventStreamId: context.EventStreamId,
+        eventSource: context.EventSource ? context.EventSource : undefined,
         subject: context.Subject,
         hash: context.Hash,
         observationState: context.ObservationState,

package/for_EventStore/when_implementing_a_legacy_event_store.spec.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.
+
+import { chai, describe, it } from 'vitest';
+import type { IEventStore } from '../IEventStore.js';
+
+const should = chai.should();
+
+/** An implementation written before event sources existed: it has no `eventSources` member. */
+type LegacyEventStore = Omit<IEventStore, 'eventSources'>;
+
+describe('when implementing an event store written before event sources', () => {
+    it('should still satisfy the IEventStore contract', () => {
+        // Compile-time regression: assigning would fail type-checking if `eventSources` became required.
+        const legacy = {} as LegacyEventStore;
+        const store: IEventStore = legacy;
+        should.not.exist(store.eventSources);
+    });
+});

package/index.ts

@@ -3,6 +3,7 @@
 
 import * as events from './events/index.js';
 import * as eventSequences from './eventSequences/index.js';
+import * as eventSources from './eventSources/index.js';
 import * as reactors from './reactors/index.js';
 import * as reducers from './reducers/index.js';
 import * as seeding from './seeding/index.js';
@@ -48,6 +49,7 @@ export { DiagChronicleLogger } from './logging/DiagChronicleLogger.js';
 
 export * from './events/index.js';
 export * from './eventSequences/index.js';
+export * from './eventSources/index.js';
 export * from './reactors/index.js';
 export * from './reducers/index.js';
 export * from './seeding/index.js';
@@ -74,6 +76,7 @@ export * from './confidentiality/index.js';
 export {
     events,
     eventSequences,
+    eventSources,
     reactors,
     reducers,
     seeding,