@cratis/chronicle 6.48.0 → 6.50.0

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

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