@cratis/chronicle 6.48.0 → 6.50.0

package/eventSequences/for_EventSequence/when_appending_named_tags/with_an_invalid_tag.spec.ts

@@ -0,0 +1,36 @@
+// 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 { InvalidNamedTag, type NamedTag } from '../../../events/index.js';
+import { a_sequence, NamedTagRecorded } from './given.fixture.js';
+
+chai.should();
+const blank = { name: '', value: 'x' } as NamedTag;
+
+describe('when appending a single event with an invalid named tag', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    let error: unknown;
+    beforeEach(async () => {
+        calls = a_sequence();
+        error = await calls.sequence.append('source', new NamedTagRecorded(), { namedTags: [blank] }).catch(caught => caught);
+    });
+    it('should fail with an invalid named tag error', () => (error as Error).should.be.instanceOf(InvalidNamedTag));
+    it('should not call the kernel', () =>
+        (calls.append.mock.calls.length + calls.appendWithNamedTags.mock.calls.length).should.equal(0));
+});
+
+describe('when appending a batch where one entry has an invalid named tag', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    let error: unknown;
+    beforeEach(async () => {
+        calls = a_sequence();
+        error = await calls.sequence.appendMany([
+            { eventSourceId: 'one', event: new NamedTagRecorded() },
+            { eventSourceId: 'two', event: new NamedTagRecorded(), namedTags: [null as unknown as NamedTag] }
+        ]).catch(caught => caught);
+    });
+    it('should fail with an invalid named tag error', () => (error as Error).should.be.instanceOf(InvalidNamedTag));
+    it('should not append any of the events', () =>
+        (calls.appendManyForEventSources.mock.calls.length + calls.appendManyForEventSourcesWithNamedTags.mock.calls.length).should.equal(0));
+});

package/eventSequences/for_EventSequence/when_appending_named_tags/with_registered_sources.spec.ts

@@ -0,0 +1,74 @@
+// 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 { ConcurrencyDimensions } from '../../../eventSources/index.js';
+import { NamedTag } from '../../../events/index.js';
+import { NamedTagsWithRegisteredEventSourceNotSupported, type AppendOptions, type EventForEventSourceId } from '../../index.js';
+import { Account, a_sequence, NamedTagRecorded, registered_sources } from './given.fixture.js';
+
+chai.should();
+const namedTags = [new NamedTag('batch', 'b-1')];
+const entry = (options: Partial<EventForEventSourceId> = {}): EventForEventSourceId =>
+    ({ eventSourceId: 'source', event: new NamedTagRecorded(), ...options });
+
+const batches: Array<{ description: string; events: EventForEventSourceId[]; options?: AppendOptions }> = [
+    { description: 'tags and a registered source on the same entry', events: [entry({ eventSource: Account, namedTags })] },
+    { description: 'a tagged entry before an untagged registered entry', events: [entry({ namedTags }), entry({ eventSource: 'Account' })] },
+    { description: 'an untagged registered entry before a tagged entry', events: [entry({ eventSource: 'Account' }), entry({ namedTags })] },
+    { description: 'shared tags and a registered entry', events: [entry({ eventSource: 'Account' })], options: { namedTags } },
+    { description: 'per-entry tags and a shared registered source', events: [entry({ namedTags })], options: { eventSource: Account } }
+];
+
+for (const batch of batches) {
+    describe(`when appending a batch with ${batch.description}`, () => {
+        let calls: ReturnType<typeof a_sequence>;
+        let error: unknown;
+        beforeEach(async () => {
+            calls = a_sequence(registered_sources(ConcurrencyDimensions.eventSourceId));
+            error = await calls.sequence.appendMany(batch.events, batch.options).catch(caught => caught);
+        });
+        it('should reject with the typed unsupported combination error', () =>
+            (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+        it('should explain the kernel limitation', () => (error as Error).message.should.contain('drops registered event source routing'));
+        it('should link to the kernel issue', () => (error as Error).message.should.contain('https://github.com/Cratis/Chronicle/issues/4603'));
+        it('should not send a plain batch', () => calls.appendManyForEventSources.mock.calls.should.have.lengthOf(0));
+        it('should not send a named-tag batch', () => calls.appendManyForEventSourcesWithNamedTags.mock.calls.should.have.lengthOf(0));
+        it('should not read a tail to derive a guard', () => calls.tailSequenceNumber.mock.calls.should.have.lengthOf(0));
+        it('should not fall back to single appends', () =>
+            [...calls.append.mock.calls, ...calls.appendWithNamedTags.mock.calls].should.have.lengthOf(0));
+    });
+}
+
+describe('when appending a same-source batch with shared named tags and registered routing', () => {
+    let error: unknown;
+    beforeEach(async () => {
+        const calls = a_sequence(registered_sources());
+        error = await calls.sequence.appendMany('source', [new NamedTagRecorded()], { eventSource: Account, namedTags }).catch(caught => caught);
+    });
+    it('should reject with the typed unsupported combination error', () =>
+        (error as Error).should.be.instanceOf(NamedTagsWithRegisteredEventSourceNotSupported));
+});
+
+describe('when appending a registered-source batch with empty named tags', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    beforeEach(async () => {
+        calls = a_sequence(registered_sources());
+        await calls.sequence.appendMany([entry({ eventSource: Account, namedTags: [] })], { namedTags: [] });
+    });
+    it('should retain registered routing on the plain batch call', () =>
+        calls.appendManyForEventSources.mock.calls[0][0].Events[0].EventSource.should.equal('Account'));
+    it('should not send a named-tag batch', () => calls.appendManyForEventSourcesWithNamedTags.mock.calls.should.have.lengthOf(0));
+});
+
+describe('when appending a single event with named tags and a registered source', () => {
+    let calls: ReturnType<typeof a_sequence>;
+    beforeEach(async () => {
+        calls = a_sequence(registered_sources());
+        await calls.sequence.append('source', new NamedTagRecorded(), { eventSource: Account, namedTags });
+    });
+    it('should retain registered routing on the dedicated single append call', () =>
+        calls.appendWithNamedTags.mock.calls[0][0].EventSource.should.equal('Account'));
+    it('should retain the named tags on the single append', () =>
+        calls.appendWithNamedTags.mock.calls[0][0].NamedTags.should.deep.equal([{ Name: 'batch', Value: 'b-1' }]));
+});

package/eventSequences/for_TransactionalEventSequence/when_appending_many_with_named_tags.spec.ts

@@ -0,0 +1,41 @@
+// 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 { InvalidNamedTag, NamedTag } from '../../events/index.js';
+import type { IUnitOfWorkManager } from '../../transactions/index.js';
+import { EventSequenceId } from '../EventSequenceId.js';
+import type { IEventSequence } from '../IEventSequence.js';
+import { TransactionalEventSequence } from '../TransactionalEventSequence.js';
+
+chai.should();
+
+function a_transactional_sequence() {
+    const addEvent = vi.fn();
+    const manager = { current: { addEvent } } as unknown as IUnitOfWorkManager;
+    return { sequence: new TransactionalEventSequence({ id: EventSequenceId.eventLog } as IEventSequence, manager), addEvent };
+}
+
+describe('when appending many events transactionally with shared named tags', () => {
+    let addEvent: ReturnType<typeof vi.fn>;
+    beforeEach(async () => {
+        const given = a_transactional_sequence();
+        addEvent = given.addEvent;
+        await given.sequence.appendMany('source', [{ one: 1 }, { two: 2 }], { eventSource: 'Account', namedTags: [new NamedTag('import', 'i-1')] });
+    });
+    it('should add every event with the shared named tags and routing', () =>
+        addEvent.mock.calls.map(call => [call[3].eventSource, call[3].namedTags.map((tag: NamedTag) => tag.value)])
+            .should.deep.equal([['Account', ['i-1']], ['Account', ['i-1']]]));
+});
+
+describe('when appending many events transactionally with an invalid named tag', () => {
+    let addEvent: ReturnType<typeof vi.fn>;
+    let error: unknown;
+    beforeEach(async () => {
+        const given = a_transactional_sequence();
+        addEvent = given.addEvent;
+        error = await given.sequence.appendMany('source', [{ one: 1 }], { namedTags: [{ name: '', value: '' } as NamedTag] }).catch(caught => caught);
+    });
+    it('should fail with an invalid named tag error', () => (error as Error).should.be.instanceOf(InvalidNamedTag));
+    it('should not add any event', () => addEvent.mock.calls.should.have.lengthOf(0));
+});

package/eventSequences/index.ts

@@ -10,6 +10,7 @@ export type { AppendResult } from './AppendResult.js';
 export type { AppendedEventWithResult } from './AppendedEventWithResult.js';
 export type { AppendOptions } from './AppendOptions.js';
 export { CompleteStreamError } from './CompleteStreamError.js';
+export { NamedTagsWithRegisteredEventSourceNotSupported } from './NamedTagsWithRegisteredEventSourceNotSupported.js';
 export type { CompleteStreamResult } from './CompleteStreamResult.js';
 export type { ConcurrencyScope } from './ConcurrencyScope.js';
 export type { EventForEventSourceId } from './EventForEventSourceId.js';

package/eventSequences/prepareBatchAppend.ts

@@ -7,6 +7,7 @@ import { correlationIdManager } from '../correlation/index.js';
 import { getEventTypeFor } from '../events/eventTypeDecorator.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { mergeTags } from '../events/mergeTags.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { identityProvider } from '../identity/index.js';
 import { resolveEventSubject } from '../compliance/resolveEventSubject.js';
 import type { AppendOptions } from './AppendOptions.js';
@@ -45,6 +46,8 @@ export function prepareBatchAppend(
     for (const { eventSourceId } of eventsForEventSourceIds) {
         if (!concurrencyScopes.has(eventSourceId)) concurrencyScopes.set(eventSourceId, appendOptions?.concurrencyScope);
     }
+    // Validate every event's named tags before anything is sent; the order of entries is preserved.
+    const namedTags = eventsForEventSourceIds.map(({ namedTags: instanceNamedTags }) => mergeNamedTags(instanceNamedTags, appendOptions?.namedTags));
     const eventsToAppend = eventsForEventSourceIds.map(({ eventSourceId, event, eventStreamType, eventStreamId, eventSourceType, subject, occurred, tags: instanceTags }) => {
         const eventType = getEventTypeFor(event.constructor as Function);
         const tags = mergeTags(getTagsFor(event.constructor as Function), instanceTags, appendOptions?.tags);
@@ -60,5 +63,5 @@ export function prepareBatchAppend(
             Subject: subject ?? appendOptions?.subject ?? resolveEventSubject(event) ?? eventSourceId
         };
     });
-    return { eventsForEventSourceIds, appendOptions, correlationId, batchCausationChain, identity, concurrencyScopes, eventsToAppend };
+    return { eventsForEventSourceIds, appendOptions, correlationId, batchCausationChain, identity, concurrencyScopes, eventsToAppend, namedTags };
 }

package/eventSequences/prepareSingleAppend.ts

@@ -5,6 +5,7 @@ import { Guid, JsonSerializer } from '@cratis/fundamentals';
 import { getEventTypeFor } from '../events/eventTypeDecorator.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { mergeTags } from '../events/mergeTags.js';
+import { mergeNamedTags } from '../events/mergeNamedTags.js';
 import { identityProvider } from '../identity/index.js';
 import { causationManager, CausationType } from '../auditing/index.js';
 import { correlationIdManager } from '../correlation/index.js';
@@ -20,8 +21,9 @@ export function prepareSingleAppend(event: object, options?: AppendOptions) {
     const subject = options?.subject ?? resolveEventSubject(event);
     const content = JsonSerializer.serialize(event);
     const tags = mergeTags(getTagsFor(event.constructor as Function), options?.tags);
+    const namedTags = mergeNamedTags(options?.namedTags);
     const causationChain = causationManager.run(CausationType.appendEvent, { eventType: eventType.id.value },
         () => causationManager.getCurrentChain());
     const identity = identityProvider.getCurrent();
-    return { eventType, correlationId, content, tags, causationChain, identity, subject };
+    return { eventType, correlationId, content, tags, namedTags, causationChain, identity, subject };
 }

package/eventSequences/resolveEventSourceRouting.ts

@@ -0,0 +1,125 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ConcurrencyDimensions } from '../eventSources/ConcurrencyDimensions.js';
+import { ResolvedEventRouting } from '../eventSources/ResolvedEventRouting.js';
+import type { IEventSources } from '../eventSources/IEventSources.js';
+import type { AppendOptions } from './AppendOptions.js';
+import type { ConcurrencyScope } from './ConcurrencyScope.js';
+import type { EventForEventSourceId } from './EventForEventSourceId.js';
+import { EventSequenceNumber } from './EventSequenceNumber.js';
+
+/** Resolves the definition routing of a single append, or undefined for a legacy append. */
+export function resolveSingleRouting(eventSources: IEventSources | undefined, options?: AppendOptions): ResolvedEventRouting | undefined {
+    return ResolvedEventRouting.resolve(eventSources, options?.eventSource, options?.eventStream,
+        { sourceType: options?.sourceType, streamType: options?.streamType });
+}
+
+/** Resolves the definition routing of one event of a batch; per-event values win over the shared options. */
+export function resolveBatchRouting(
+    eventSources: IEventSources | undefined,
+    event: EventForEventSourceId,
+    options?: AppendOptions
+): ResolvedEventRouting | undefined {
+    const ownSource = event.eventSource !== undefined;
+    const source = event.eventSource ?? options?.eventSource;
+    // A stream belongs to its event source: never inherit the shared stream into a different source.
+    const stream = event.eventStream ?? (ownSource ? undefined : options?.eventStream);
+    return ResolvedEventRouting.resolve(eventSources, source, stream, {
+        sourceType: event.eventSourceType ?? options?.sourceType,
+        streamType: event.eventStreamType ?? options?.streamType
+    });
+}
+
+/** A derived guard required by a registered-definition event of a batch. */
+export interface RequiredGuard {
+    /** The routing whose dimensions produce the guard. */
+    readonly routing: ResolvedEventRouting;
+    /** The stream id the guard's stream-id dimension (if any) applies to. */
+    readonly streamId: string | undefined;
+}
+
+/** The predicate a guard evaluates: only the values of the dimensions the routing selects. */
+function guardPredicate(routing: ResolvedEventRouting, eventSourceId: string, streamId: string | undefined): string | undefined {
+    const dimensions = routing.dimensions;
+    if (dimensions === ConcurrencyDimensions.none) return undefined;
+    const has = (flag: number) => (dimensions & flag) !== 0;
+    return JSON.stringify([
+        has(ConcurrencyDimensions.eventSourceId) ? eventSourceId : null,
+        has(ConcurrencyDimensions.eventSourceType) ? routing.sourceType : null,
+        has(ConcurrencyDimensions.eventStreamType) ? routing.streamType ?? null : null,
+        has(ConcurrencyDimensions.eventStreamId) ? streamId ?? null : null
+    ]);
+}
+
+/**
+ * Determines the single derived guard every event source id of a batch needs.
+ * The Kernel accepts one concurrency scope per event source id, so equivalent predicates share one
+ * scope (an unguarded event never suppresses a guarded one) and differing predicates are rejected
+ * before anything is written.
+ * @param routings - The resolved routing per event, aligned with {@link events}.
+ * @param events - The batch events.
+ * @param sharedStreamId - The shared stream id from the append options.
+ * @param explicitIds - Event source ids that carry an explicit scope; they are never derived.
+ * @returns The guard to derive per event source id.
+ * @throws Error when one event source id needs differing guards.
+ */
+export function planDerivedGuards(
+    routings: Array<ResolvedEventRouting | undefined>,
+    events: EventForEventSourceId[],
+    sharedStreamId: string | undefined,
+    explicitIds: ReadonlySet<string> = new Set()
+): Map<string, RequiredGuard> {
+    const guards = new Map<string, { guard: RequiredGuard; predicate: string }>();
+    routings.forEach((routing, index) => {
+        const { eventSourceId, eventStreamId } = events[index];
+        if (!routing || explicitIds.has(eventSourceId)) return;
+        const streamId = eventStreamId ?? sharedStreamId;
+        const predicate = guardPredicate(routing, eventSourceId, streamId);
+        if (predicate === undefined) return;
+        const existing = guards.get(eventSourceId);
+        if (!existing) {
+            guards.set(eventSourceId, { guard: { routing, streamId }, predicate });
+        } else if (existing.predicate !== predicate) {
+            throw new Error(
+                `Event source id '${eventSourceId}' needs differing concurrency guards within one batch ` +
+                `('${existing.guard.routing.eventSource}' and '${routing.eventSource}'), but Chronicle accepts one concurrency scope per event source id. ` +
+                'Pass an explicit shared concurrencyScopes entry for the id, or append the events in separate batches.');
+        }
+    });
+    return new Map([...guards].map(([id, { guard }]) => [id, guard]));
+}
+
+/** The tail reader a derived concurrency scope needs. */
+export type TailReader = (eventSourceId?: string, sourceType?: string, streamType?: string, streamId?: string) => Promise<EventSequenceNumber>;
+
+/**
+ * Derives an optimistic concurrency scope from the dimensions a definition declares.
+ * Only call this when no explicit scope exists; explicit scopes always win.
+ * @returns The scope, or undefined when the definition declares no dimensions.
+ */
+export async function deriveConcurrencyScope(
+    routing: ResolvedEventRouting,
+    eventSourceId: string,
+    streamId: string | undefined,
+    readTail: TailReader
+): Promise<ConcurrencyScope | undefined> {
+    const dimensions = routing.dimensions;
+    if (dimensions === ConcurrencyDimensions.none) return undefined;
+
+    const has = (flag: number) => (dimensions & flag) !== 0;
+    const scopedSource = has(ConcurrencyDimensions.eventSourceId) ? eventSourceId : undefined;
+    const scopedSourceType = has(ConcurrencyDimensions.eventSourceType) ? routing.sourceType : undefined;
+    const scopedStreamType = has(ConcurrencyDimensions.eventStreamType) ? routing.streamType : undefined;
+    const scopedStreamId = has(ConcurrencyDimensions.eventStreamId) ? streamId : undefined;
+
+    const tail = await readTail(scopedSource, scopedSourceType, scopedStreamType, scopedStreamId);
+    return {
+        // An empty scope is checked against "no matching event", like an explicit first append.
+        sequenceNumber: tail.value === EventSequenceNumber.unset.value ? EventSequenceNumber.beforeFirst.value : tail.value,
+        eventSourceId: scopedSource !== undefined,
+        eventSourceType: scopedSourceType,
+        eventStreamType: scopedStreamType,
+        eventStreamId: scopedStreamId
+    };
+}

package/eventSources/ConcurrencyDimensions.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.
+
+/**
+ * Flags describing which dimensions of an append take part in a concurrency check.
+ * Values match the wire contract and can be combined with bitwise OR.
+ */
+export const ConcurrencyDimensions = {
+    /** No dimensions declared; the append keeps its existing concurrency behavior. */
+    none: 0,
+
+    /** The event source identifier. */
+    eventSourceId: 1,
+
+    /** The event source type. */
+    eventSourceType: 2,
+
+    /** The event stream type. */
+    eventStreamType: 4,
+
+    /** The event stream identifier. */
+    eventStreamId: 8
+} as const;
+
+/** A bitwise combination of {@link ConcurrencyDimensions} values. */
+export type ConcurrencyDimensionFlags = number;

package/eventSources/DuplicateEventSourceName.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Thrown when two discovered event source definitions share a name. */
+export class DuplicateEventSourceName extends Error {
+    constructor(readonly eventSource: string) {
+        super(`More than one event source definition is named '${eventSource}'.`);
+        this.name = 'DuplicateEventSourceName';
+    }
+}

package/eventSources/DuplicateEventStreamName.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Thrown when an event source definition declares the same stream name twice. */
+export class DuplicateEventStreamName extends Error {
+    constructor(readonly eventSource: string, readonly stream: string) {
+        super(`The event source '${eventSource}' declares the event stream '${stream}' more than once.`);
+        this.name = 'DuplicateEventStreamName';
+    }
+}

package/eventSources/EventRoutingContradictsEventSource.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Thrown when explicit routing values contradict the event source definition. */
+export class EventRoutingContradictsEventSource extends Error {
+    constructor(readonly eventSource: string, readonly dimension: string, readonly expected: string, readonly actual: string) {
+        super(`The explicit ${dimension} '${actual}' contradicts the event source '${eventSource}', which requires '${expected}'.`);
+        this.name = 'EventRoutingContradictsEventSource';
+    }
+}

package/eventSources/EventSourceDefinition.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+import type { ConcurrencyDimensionFlags } from './ConcurrencyDimensions.js';
+import type { EventStreamDefinition } from './EventStreamDefinition.js';
+
+/**
+ * Describes a registered event source: a stable name, its default concurrency dimensions and its streams.
+ * Routing belongs to the append, not to event types.
+ */
+export interface EventSourceDefinition {
+    /** The class carrying the definition. */
+    readonly type: Constructor;
+
+    /** The stable name of the event source; this is the event source type of appended events. */
+    readonly name: string;
+
+    /** The description of the event source. */
+    readonly description: string;
+
+    /** The default dimensions that take part in concurrency checks. */
+    readonly concurrency: ConcurrencyDimensionFlags;
+
+    /** The streams declared by the event source. */
+    readonly streams: ReadonlyArray<EventStreamDefinition>;
+}

package/eventSources/EventSources.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+import type { IClientArtifactsProvider } from '../artifacts/index.js';
+import type { ChronicleConnection } from '../connection/index.js';
+import { EventSourceOwner } from '@cratis/chronicle.contracts';
+import { ensureCommandSuccess } from '../connection/callResults.js';
+import type { EventSourceDefinition } from './EventSourceDefinition.js';
+import { getEventSourceMetadata, getEventStreamsFor } from './eventSource.js';
+import { DuplicateEventSourceName } from './DuplicateEventSourceName.js';
+import { DuplicateEventStreamName } from './DuplicateEventStreamName.js';
+import { UnknownEventSource } from './UnknownEventSource.js';
+import type { IEventSources } from './IEventSources.js';
+
+/**
+ * Implements {@link IEventSources}, discovering `@eventSource` classes and registering them with the Kernel.
+ */
+export class EventSources implements IEventSources {
+    private _byType = new Map<Constructor, EventSourceDefinition>();
+    private _byName = new Map<string, EventSourceDefinition>();
+
+    /**
+     * Creates a new {@link EventSources}.
+     * @param _eventStore - The name of the event store the definitions belong to.
+     * @param _connection - The connection used to communicate with the Kernel.
+     * @param _clientArtifacts - Provider for discovered client artifact types.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _connection: ChronicleConnection,
+        private readonly _clientArtifacts: IClientArtifactsProvider
+    ) {}
+
+    /** @inheritdoc */
+    get all(): ReadonlyArray<EventSourceDefinition> {
+        return [...this._byType.values()];
+    }
+
+    /** @inheritdoc */
+    async discover(): Promise<void> {
+        const byType = new Map<Constructor, EventSourceDefinition>();
+        const byName = new Map<string, EventSourceDefinition>();
+        for (const type of this._clientArtifacts.eventSources ?? []) {
+            const metadata = getEventSourceMetadata(type);
+            if (!metadata) continue;
+            if (byName.has(metadata.name)) throw new DuplicateEventSourceName(metadata.name);
+            const streams = getEventStreamsFor(type);
+            const seen = new Set<string>();
+            for (const stream of streams) {
+                if (seen.has(stream.name)) throw new DuplicateEventStreamName(metadata.name, stream.name);
+                seen.add(stream.name);
+            }
+            const definition: EventSourceDefinition = {
+                type,
+                name: metadata.name,
+                description: metadata.description,
+                concurrency: metadata.concurrency,
+                streams: streams.map(stream => ({ ...stream }))
+            };
+            byType.set(type, definition);
+            byName.set(definition.name, definition);
+        }
+        this._byType = byType;
+        this._byName = byName;
+    }
+
+    /** @inheritdoc */
+    async register(): Promise<void> {
+        if (this._byType.size === 0) return;
+        ensureCommandSuccess('register event sources', await this._connection.eventSources.registerEventSources({
+            EventStore: this._eventStore,
+            Sources: this.all.map(definition => ({
+                Name: definition.name,
+                Description: definition.description,
+                Owner: EventSourceOwner.Client,
+                Concurrency: definition.concurrency,
+                Streams: definition.streams.map(stream => ({
+                    Name: stream.name,
+                    Description: stream.description,
+                    Concurrency: stream.concurrency
+                }))
+            }))
+        }));
+    }
+
+    /** @inheritdoc */
+    getFor(eventSource: Constructor | string): EventSourceDefinition {
+        const definition = typeof eventSource === 'string' ? this._byName.get(eventSource) : this._byType.get(eventSource);
+        if (!definition) throw new UnknownEventSource(typeof eventSource === 'string' ? eventSource : eventSource.name);
+        return definition;
+    }
+}

package/eventSources/EventStreamDefinition.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ConcurrencyDimensionFlags } from './ConcurrencyDimensions.js';
+
+/**
+ * Describes an event stream declared by an event source definition.
+ */
+export interface EventStreamDefinition {
+    /** The stable name of the stream; this is the event stream type of appended events. */
+    readonly name: string;
+
+    /** The description of the stream. */
+    readonly description: string;
+
+    /** The dimensions that take part in concurrency checks for the stream. Falls back to the event source when none. */
+    readonly concurrency: ConcurrencyDimensionFlags;
+}

package/eventSources/EventStreamDoesNotBelongToEventSource.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Thrown when an append names a stream the event source does not declare. */
+export class EventStreamDoesNotBelongToEventSource extends Error {
+    constructor(readonly eventSource: string, readonly stream: string) {
+        super(`The event stream '${stream}' is not declared by the event source '${eventSource}'.`);
+        this.name = 'EventStreamDoesNotBelongToEventSource';
+    }
+}

package/eventSources/EventStreamRequiresEventSource.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Thrown when an append names a stream without naming the event source that declares it. */
+export class EventStreamRequiresEventSource extends Error {
+    constructor(readonly stream: string) {
+        super(`The event stream '${stream}' can only be used together with an event source.`);
+        this.name = 'EventStreamRequiresEventSource';
+    }
+}

package/eventSources/IEventSources.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Constructor } from '@cratis/fundamentals';
+import type { EventSourceDefinition } from './EventSourceDefinition.js';
+
+/**
+ * Defines the discovery and registration of event source definitions.
+ */
+export interface IEventSources {
+    /** Gets all discovered event source definitions. */
+    readonly all: ReadonlyArray<EventSourceDefinition>;
+
+    /**
+     * Discovers the event source definitions from the client artifacts.
+     * @throws DuplicateEventSourceName when two definitions share a name.
+     * @throws DuplicateEventStreamName when a definition declares the same stream twice.
+     */
+    discover(): Promise<void>;
+
+    /**
+     * Registers the discovered definitions with the Kernel. Registration is an upsert; the Kernel retains
+     * historical definitions that are no longer registered. Does nothing when there are no definitions.
+     */
+    register(): Promise<void>;
+
+    /**
+     * Gets the definition by class or name.
+     * @param eventSource - The class decorated with `@eventSource`, or the definition name.
+     * @throws UnknownEventSource when there is no such definition.
+     */
+    getFor(eventSource: Constructor | string): EventSourceDefinition;
+}