@cratis/chronicle 6.47.0 → 6.49.0

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

package/eventSources/ResolvedEventRouting.ts

@@ -0,0 +1,78 @@
+// 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 { EventSourceDefinition } from './EventSourceDefinition.js';
+import type { EventStreamDefinition } from './EventStreamDefinition.js';
+import type { IEventSources } from './IEventSources.js';
+import { EventRoutingContradictsEventSource } from './EventRoutingContradictsEventSource.js';
+import { EventStreamDoesNotBelongToEventSource } from './EventStreamDoesNotBelongToEventSource.js';
+import { EventStreamRequiresEventSource } from './EventStreamRequiresEventSource.js';
+import { UnknownEventSource } from './UnknownEventSource.js';
+
+/** The explicit routing a caller supplied next to a definition. */
+export interface ExplicitRouting {
+    /** Explicit event source type, if any. */
+    sourceType?: string;
+
+    /** Explicit event stream type, if any. */
+    streamType?: string;
+}
+
+/** The routing of an append resolved through an event source definition. */
+export class ResolvedEventRouting {
+    private constructor(readonly definition: EventSourceDefinition, readonly stream?: EventStreamDefinition) {}
+
+    /** The registered event source name written on the event. */
+    get eventSource(): string { return this.definition.name; }
+
+    /** The event source type written on the event. */
+    get sourceType(): string { return this.definition.name; }
+
+    /** The event stream type to write, or undefined to let the Kernel choose. */
+    get streamType(): string | undefined { return this.stream?.name; }
+
+    /** The concurrency dimensions that apply: the stream's when it declares any, otherwise the source's. */
+    get dimensions(): ConcurrencyDimensionFlags {
+        return this.stream && this.stream.concurrency !== 0 ? this.stream.concurrency : this.definition.concurrency;
+    }
+
+    /**
+     * Resolves the routing of an append.
+     * @param eventSources - The event sources; undefined when the store has none.
+     * @param eventSource - The definition class or name; undefined for a legacy append.
+     * @param stream - The declared stream name, if any.
+     * @param explicit - Explicit routing that must not contradict the definition.
+     * @returns The routing, or undefined when no definition is involved.
+     * @throws UnknownEventSource, EventStreamDoesNotBelongToEventSource, EventRoutingContradictsEventSource, EventStreamRequiresEventSource.
+     */
+    static resolve(
+        eventSources: IEventSources | undefined,
+        eventSource: Constructor | string | undefined,
+        stream: string | undefined,
+        explicit: ExplicitRouting = {}
+    ): ResolvedEventRouting | undefined {
+        if (eventSource === undefined) {
+            if (stream !== undefined) throw new EventStreamRequiresEventSource(stream);
+            return undefined;
+        }
+        if (!eventSources) throw new UnknownEventSource(typeof eventSource === 'string' ? eventSource : eventSource.name);
+        const definition = eventSources.getFor(eventSource);
+
+        const isSet = (value: string | undefined, unspecified: string[]) => value !== undefined && value !== '' && !unspecified.includes(value);
+        if (isSet(explicit.sourceType, ['Default', 'Unspecified']) && explicit.sourceType !== definition.name) {
+            throw new EventRoutingContradictsEventSource(definition.name, 'event source type', definition.name, explicit.sourceType!);
+        }
+        const explicitStream = isSet(explicit.streamType, ['All']) ? explicit.streamType : undefined;
+        if (stream !== undefined && explicitStream !== undefined && stream !== explicitStream) {
+            throw new EventRoutingContradictsEventSource(definition.name, 'event stream type', stream, explicitStream);
+        }
+
+        const name = stream ?? explicitStream;
+        if (name === undefined) return new ResolvedEventRouting(definition);
+        const found = definition.streams.find(candidate => candidate.name === name);
+        if (!found) throw new EventStreamDoesNotBelongToEventSource(definition.name, name);
+        return new ResolvedEventRouting(definition, found);
+    }
+}

package/eventSources/UnknownEventSource.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 an event source that is not a discovered definition. */
+export class UnknownEventSource extends Error {
+    constructor(readonly eventSource: string) {
+        super(`The event source '${eventSource}' is not a discovered event source definition.`);
+        this.name = 'UnknownEventSource';
+    }
+}

package/eventSources/eventSource.ts

@@ -0,0 +1,116 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import type { Constructor } from '@cratis/fundamentals';
+import { DecoratorType, TypeDiscoverer } from '../types/index.js';
+import type { ChronicleClassDecorator } from '../types/standardDecoratorMetadata.js';
+import type { ConcurrencyDimensionFlags } from './ConcurrencyDimensions.js';
+
+const EVENT_SOURCE_METADATA_KEY = 'chronicle:eventSource';
+const EVENT_STREAMS_METADATA_KEY = 'chronicle:eventSource:streams';
+let registrationCounter = 0;
+
+/** Optional settings for {@link eventSource}. */
+export interface EventSourceOptions {
+    /** The stable name. Defaults to the class name without a trailing `EventSource`. */
+    name?: string;
+
+    /** The description of the event source. */
+    description?: string;
+
+    /** The default dimensions that take part in concurrency checks; combine {@link ConcurrencyDimensions} values with `|`. */
+    concurrency?: ConcurrencyDimensionFlags;
+}
+
+/** Optional settings for {@link eventStream}. */
+export interface EventStreamOptions {
+    /** The description of the stream. */
+    description?: string;
+
+    /** The dimensions that take part in concurrency checks for the stream. Falls back to the event source when omitted or none. */
+    concurrency?: ConcurrencyDimensionFlags;
+}
+
+/** Metadata recorded by {@link eventSource}. */
+export interface EventSourceMetadata {
+    readonly name: string;
+    readonly description: string;
+    readonly concurrency: ConcurrencyDimensionFlags;
+}
+
+/** Metadata recorded by {@link eventStream}. */
+export interface EventStreamMetadata {
+    readonly name: string;
+    readonly description: string;
+    readonly concurrency: ConcurrencyDimensionFlags;
+}
+
+/**
+ * Declares a class as an event source definition, discovered and registered with the Kernel at startup.
+ * The definition is not tied to event types; an append routes through it with `AppendOptions.eventSource`.
+ * Supports legacy and standard class decorators.
+ * @param options - Optional name (defaults to the class name without a trailing `EventSource`), description and concurrency.
+ * @returns A class decorator.
+ */
+export function eventSource(options?: EventSourceOptions): ChronicleClassDecorator {
+    return ((target: Function, context?: ClassDecoratorContext) => {
+        let constructor = target;
+        const metadata: EventSourceMetadata = {
+            name: options?.name ?? defaultNameFor(constructor),
+            description: options?.description ?? '',
+            concurrency: options?.concurrency ?? 0
+        };
+        Reflect.defineMetadata(EVENT_SOURCE_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(DecoratorType.EventSource, constructor as Constructor, `${metadata.name}#${registrationCounter++}`);
+        context?.addInitializer(function () {
+            if (this !== constructor) {
+                constructor = this as Function;
+                Reflect.defineMetadata(EVENT_SOURCE_METADATA_KEY, metadata, constructor);
+                Reflect.defineMetadata(EVENT_STREAMS_METADATA_KEY, Reflect.getOwnMetadata(EVENT_STREAMS_METADATA_KEY, target), constructor);
+                TypeDiscoverer.default.register(DecoratorType.EventSource, constructor as Constructor, `${metadata.name}#${registrationCounter++}`);
+            }
+        });
+    }) as ChronicleClassDecorator;
+}
+
+/**
+ * Declares a stream of an event source. Repeat the decorator for several streams.
+ * Only takes effect on a class that is also decorated with {@link eventSource}.
+ * @param name - The stable name of the stream, which is the event stream type of appended events.
+ * @param options - Optional description and concurrency dimensions.
+ * @returns A class decorator.
+ */
+export function eventStream(name: string, options?: EventStreamOptions): ChronicleClassDecorator {
+    return ((target: Function) => {
+        const existing = (Reflect.getOwnMetadata(EVENT_STREAMS_METADATA_KEY, target) as EventStreamMetadata[] | undefined) ?? [];
+        // Decorators evaluate bottom-up; unshift keeps declaration order.
+        Reflect.defineMetadata(EVENT_STREAMS_METADATA_KEY, [
+            { name, description: options?.description ?? '', concurrency: options?.concurrency ?? 0 },
+            ...existing
+        ], target);
+    }) as ChronicleClassDecorator;
+}
+
+/**
+ * Gets the event source metadata declared on a class.
+ * @param target - The class constructor.
+ * @returns The metadata, or undefined when the class is not an event source.
+ */
+export function getEventSourceMetadata(target: Function): EventSourceMetadata | undefined {
+    return Reflect.getOwnMetadata(EVENT_SOURCE_METADATA_KEY, target) as EventSourceMetadata | undefined;
+}
+
+/**
+ * Gets the streams declared on a class, in declaration order (duplicates are preserved so they can be rejected).
+ * @param target - The class constructor.
+ * @returns The declared streams.
+ */
+export function getEventStreamsFor(target: Function): ReadonlyArray<EventStreamMetadata> {
+    return (Reflect.getOwnMetadata(EVENT_STREAMS_METADATA_KEY, target) as EventStreamMetadata[] | undefined) ?? [];
+}
+
+function defaultNameFor(type: Function): string {
+    const suffix = 'EventSource';
+    return type.name.length > suffix.length && type.name.endsWith(suffix) ? type.name.slice(0, -suffix.length) : type.name;
+}