@cratis/chronicle 6.47.0 → 6.49.0

package/readModels/for_ReadModelWatcher/when_reconnecting_during_conversion.spec.ts

@@ -0,0 +1,84 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import { ReadModelWatcher } from '../ReadModelWatcher.js';
+import { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe('when reconnecting during read model conversion', () => {
+    let context: a_watched_read_model;
+    let watcher: ReadModelWatcher<object>;
+    let finishConversion: () => void;
+    let failConversion: (error: unknown) => void;
+    const converted: string[] = [];
+    beforeEach(async () => {
+        converted.length = 0;
+        context = new a_watched_read_model();
+        await context.connect();
+        const conversion = new Promise<void>((resolve, reject) => {
+            finishConversion = resolve;
+            failConversion = reject;
+        });
+        watcher = new ReadModelWatcher(signal => context.watch(undefined, { signal }), async change => {
+            converted.push(change.ModelKey);
+            if (change.ModelKey === 'received') await conversion;
+            return { namespace: change.Namespace, key: change.ModelKey, readModel: {}, removed: false };
+        }, new AbortController().signal, context.lifecycle, { resume: true });
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        context.streams[0].send({ ModelKey: 'received' });
+        await context.flush();
+        await context.disconnect();
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        context.streams[1].send({ ModelKey: 'resumed' });
+        await watcher.subscribed;
+    });
+    afterEach(() => {
+        finishConversion();
+        watcher.dispose();
+        context.readModels.dispose();
+    });
+
+    it('should finish received conversion and preserve order across connections', async () => {
+        await context.flush();
+        converted.should.deep.equal(['received']);
+        finishConversion();
+        (await watcher.next()).value.key.should.equal('received');
+        (await watcher.next()).value.key.should.equal('resumed');
+        converted.should.deep.equal(['received', 'resumed']);
+    });
+
+    it('should not replay an acknowledgment to a callback registered while earlier conversion finishes', async () => {
+        let notifications = 0;
+        watcher.onResubscribed(() => { notifications++; });
+        finishConversion();
+        await context.flush();
+        notifications.should.equal(0);
+        await context.disconnect();
+        await context.connect();
+        context.streams[2].send({ Subscribed: true });
+        await context.flush();
+        notifications.should.equal(1);
+    });
+
+    it('should still fail on a received change that cannot be released after reconnect', async () => {
+        const failure = { code: 14 };
+        const next = watcher.next().catch(error => error);
+        failConversion(failure);
+        (await next).should.equal(failure);
+        context.streams[1].signal.aborted.should.be.true;
+        converted.should.deep.equal(['received']);
+    });
+
+    it('should not deliver an in-flight conversion after disposal', async () => {
+        const next = watcher.next();
+        watcher.dispose();
+        finishConversion();
+        (await next).done!.should.be.true;
+        await context.flush();
+        (await watcher.next()).done!.should.be.true;
+    });
+});

package/readModels/for_ReadModelWatcher/when_recovering_a_stream.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 { afterEach, beforeEach, chai, describe, it, vi } from 'vitest';
+import type { IReadModelWatcher } from '../IReadModelWatcher.js';
+import { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+const recoveries = [1, 4, 13, 14, undefined].flatMap(code => ['option', 'callback'].map(optIn => ({ code, optIn })));
+
+describe.each(recoveries)('when resumption uses $optIn after stream status $code', ({ code, optIn }) => {
+    let context: a_watched_read_model;
+    let watcher: IReadModelWatcher<{ id: string }>;
+    const endStream = () => {
+        if (code === undefined) context.streams[0].end();
+        else context.streams[0].fail({ code });
+    };
+    beforeEach(async () => {
+        vi.useFakeTimers();
+        context = new a_watched_read_model();
+        await context.connect();
+        watcher = context.readModels.createWatcher(context.model, { resume: optIn === 'option' });
+        if (optIn === 'callback') watcher.onResubscribed(() => {});
+    });
+    afterEach(() => {
+        context.readModels.dispose();
+        vi.useRealTimers();
+    });
+
+    it('should renew readiness and deliver the next connection change to the same pending iterator', async () => {
+        context.streams[0].send({ Subscribed: true });
+        const acknowledged = watcher.subscribed;
+        await acknowledged;
+        const iterator = watcher[Symbol.asyncIterator]();
+        const next = iterator.next();
+        endStream();
+        await vi.advanceTimersByTimeAsync(0);
+        watcher.subscribed.should.not.equal(acknowledged);
+        const readiness = watcher.subscribed;
+        await context.disconnect();
+        watcher.subscribed.should.equal(readiness);
+        await vi.advanceTimersByTimeAsync(1000);
+        context.streams.should.have.lengthOf(1);
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        await readiness;
+        context.streams[1].send({ ModelKey: 'next', ReadModel: '{}' });
+        (await next).value.key.should.equal('next');
+        await vi.advanceTimersByTimeAsync(1000);
+        context.streams.should.have.lengthOf(2);
+    });
+
+    it('should preserve pending readiness and retry if the lifecycle never disconnects', async () => {
+        const readiness = watcher.subscribed;
+        endStream();
+        await vi.advanceTimersByTimeAsync(0);
+        watcher.subscribed.should.equal(readiness);
+        context.streams.should.have.lengthOf(1);
+        await vi.advanceTimersByTimeAsync(1000);
+        context.streams.should.have.lengthOf(2);
+        context.streams[1].send({ Subscribed: true });
+        await readiness;
+    });
+
+    it('should notify resubscription only after recovery acknowledgment and continue iteration', async () => {
+        const resubscribed = vi.fn();
+        watcher.onResubscribed(resubscribed);
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        resubscribed.mock.calls.should.have.lengthOf(0);
+        const next = watcher[Symbol.asyncIterator]().next();
+        endStream();
+        await vi.advanceTimersByTimeAsync(1000);
+        resubscribed.mock.calls.should.have.lengthOf(0);
+        context.streams[1].send({ Subscribed: true });
+        context.streams[1].send({ ModelKey: 'resumed', ReadModel: '{}' });
+        (await next).value.key.should.equal('resumed');
+        resubscribed.mock.calls.should.have.lengthOf(1);
+    });
+
+    it('should keep received buffered changes after a transport failure or completion', async () => {
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        context.streams[0].send({ ModelKey: 'received', ReadModel: '{}' });
+        await vi.advanceTimersByTimeAsync(0);
+        endStream();
+        await vi.advanceTimersByTimeAsync(1000);
+        context.streams[1].send({ Subscribed: true });
+        context.streams[1].send({ ModelKey: 'resumed', ReadModel: '{}' });
+        await watcher.subscribed;
+        const iterator = watcher[Symbol.asyncIterator]();
+        (await iterator.next()).value.key.should.equal('received');
+        (await iterator.next()).value.key.should.equal('resumed');
+    });
+
+    it('should cancel a scheduled restart when disposed', async () => {
+        const readiness = watcher.subscribed.catch(error => error);
+        endStream();
+        await vi.advanceTimersByTimeAsync(0);
+        watcher.dispose();
+        await vi.advanceTimersByTimeAsync(1000);
+        (await readiness).name.should.equal('AbortError');
+        context.streams.should.have.lengthOf(1);
+    });
+});

package/readModels/for_ReadModelWatcher/when_stopping.spec.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import type { IReadModelWatcher } from '../IReadModelWatcher.js';
+import { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe('when stopping a read model watcher', () => {
+    let context: a_watched_read_model;
+    let watcher: IReadModelWatcher<{ id: string }>;
+    let cancellation: AbortController;
+    beforeEach(async () => {
+        context = new a_watched_read_model();
+        await context.connect();
+        cancellation = new AbortController();
+        watcher = context.readModels.createWatcher(context.model, { signal: cancellation.signal });
+    });
+    afterEach(() => context.readModels.dispose());
+
+    it('should cancel the transport and settle pending iteration and readiness on disposal', async () => {
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher[Symbol.asyncIterator]().next();
+        watcher.dispose();
+        watcher.dispose();
+        context.streams[0].signal.aborted.should.be.true;
+        (await readiness).name.should.equal('AbortError');
+        (await next).done!.should.be.true;
+    });
+
+    it('should complete iteration when the caller aborts', async () => {
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher[Symbol.asyncIterator]().next();
+        const reason = new Error('caller cancelled');
+        cancellation.abort(reason);
+        (await readiness).should.equal(reason);
+        (await next).done!.should.be.true;
+        context.streams[0].signal.aborted.should.be.true;
+    });
+
+    it('should not open a stream with an already aborted signal', async () => {
+        watcher.dispose();
+        cancellation.abort();
+        watcher = context.readModels.createWatcher(context.model, { signal: cancellation.signal });
+        const failure = await watcher.subscribed.catch(error => error);
+        failure.name.should.equal('AbortError');
+        context.streams.should.have.lengthOf(1);
+    });
+
+    it('should cancel on an early for await break', async () => {
+        context.streams[0].send({ Subscribed: true });
+        context.streams[0].send({ ReadModel: '{"id":"one"}' });
+        for await (const change of watcher) {
+            change.readModel.id.should.equal('one');
+            break;
+        }
+        context.streams[0].signal.aborted.should.be.true;
+    });
+
+    it('should cancel watchers when their owner is disposed', async () => {
+        const readiness = watcher.subscribed.catch(error => error);
+        context.readModels.dispose();
+        (await readiness).name.should.equal('AbortError');
+        context.streams[0].signal.aborted.should.be.true;
+    });
+
+    it('should surface a stream failure to readiness and iteration', async () => {
+        const failure = new Error('transport failed');
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher[Symbol.asyncIterator]().next().catch(error => error);
+        context.streams[0].fail(failure);
+        (await readiness).should.equal(failure);
+        (await next).should.equal(failure);
+    });
+
+    it('should surface a later stream failure without changing an already resolved promise', async () => {
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        const next = watcher[Symbol.asyncIterator]().next().catch(error => error);
+        context.streams[0].fail(new Error('later failure'));
+        (await next).message.should.equal('later failure');
+        await watcher.subscribed;
+    });
+});

package/readModels/for_ReadModelWatcher/when_subscribing.spec.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import type { IReadModelWatcher } from '../IReadModelWatcher.js';
+import { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe('when subscribing to read model changes', () => {
+    let context: a_watched_read_model;
+    let watcher: IReadModelWatcher<{ id: string }>;
+    beforeEach(async () => {
+        context = new a_watched_read_model();
+        await context.connect();
+        watcher = context.readModels.createWatcher(context.model);
+    });
+    afterEach(() => watcher.dispose());
+
+    it('should start the stream without iteration and await the actual acknowledgment', async () => {
+        let ready = false;
+        void watcher.subscribed.then(() => { ready = true; });
+        await context.flush();
+        ready.should.be.false;
+        context.watch.mock.calls[0][0].should.deep.equal({
+            EventStore: 'store', Namespace: 'tenant', ReadModelIdentifier: 'Model', EventSequenceId: 'event-log'
+        });
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        ready.should.be.true;
+    });
+
+    it('should not yield subscription markers or lose a change before iteration begins', async () => {
+        context.streams[0].send({ Subscribed: true });
+        context.streams[0].send({ Namespace: 'tenant', ModelKey: 'one', ReadModel: '{"id":"one"}' });
+        await watcher.subscribed;
+        await context.flush();
+        const result = await watcher[Symbol.asyncIterator]().next();
+        result.done!.should.be.false;
+        result.value.key.should.equal('one');
+    });
+
+    it('should acknowledge without iteration even when changes arrive before the marker', async () => {
+        context.streams[0].send({ ModelKey: 'one', ReadModel: '{"id":"one"}' });
+        context.streams[0].send({ ModelKey: 'two', ReadModel: '{"id":"two"}' });
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        const iterator = watcher[Symbol.asyncIterator]();
+        (await iterator.next()).value.key.should.equal('one');
+        (await iterator.next()).value.key.should.equal('two');
+    });
+
+    it('should fail explicitly on pre-acknowledgment overflow instead of hanging or silently dropping changes', async () => {
+        const failure = watcher.subscribed.catch(error => error);
+        for (let index = 0; index <= 1024; index++) context.streams[0].send({ ReadModel: '{}' });
+        context.streams[0].send({ Subscribed: true });
+        (await failure).message.should.contain('buffer exceeded 1024 changes');
+        const iterationFailure = await watcher[Symbol.asyncIterator]().next().catch(error => error);
+        iterationFailure.should.equal(await failure);
+        context.streams[0].signal.aborted.should.be.true;
+    });
+});

package/readModels/for_ReadModels/when_watching.spec.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReadModelChangeType as ContractChangeType } from '@cratis/chronicle.contracts';
+import { Guid } from '@cratis/fundamentals';
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import { toContractsGuid } from '../../connection/Guid.js';
+import { ReadModelChangeType } from '../ReadModelChangeType.js';
+import { a_watched_read_model } from '../for_ReadModelWatcher/given/a_watched_read_model.js';
+
+chai.should();
+
+describe('when watching with the original pull-based API', () => {
+    let context: a_watched_read_model;
+    beforeEach(async () => {
+        context = new a_watched_read_model();
+        await context.connect();
+    });
+    afterEach(() => context.readModels.dispose());
+
+    it('should not open or read the stream until the first next call', async () => {
+        const changes = context.readModels.watch(context.model);
+        await context.flush();
+        context.watch.mock.calls.should.have.lengthOf(0);
+        const iterator = changes[Symbol.asyncIterator]();
+        await context.flush();
+        context.watch.mock.calls.should.have.lengthOf(0);
+        const next = iterator.next();
+        context.watch.mock.calls.should.have.lengthOf(1);
+        context.streams[0].pulls.should.equal(1);
+        context.streams[0].send({ ModelKey: 'first', ReadModel: '{}' });
+        (await next).value.key.should.equal('first');
+        await iterator.return!();
+        context.streams[0].closed.should.be.true;
+    });
+
+    it('should defer model resolution failures until iteration starts', async () => {
+        const changes = context.readModels.watch(class Unknown {});
+        context.watch.mock.calls.should.have.lengthOf(0);
+        const failure = await changes[Symbol.asyncIterator]().next().catch(error => error);
+        failure.message.should.contain("Unknown read model 'Unknown'");
+    });
+
+    it.each([0, 2050, undefined])('should pull more than the watcher buffer limit without read-ahead or overflow (acknowledgment after %s changes)', async acknowledgeAfter => {
+        const iterator = context.readModels.watch(context.model)[Symbol.asyncIterator]();
+        const first = iterator.next();
+        const stream = context.streams[0];
+        if (acknowledgeAfter === 0) stream.send({ Subscribed: true });
+        for (let index = 0; index < 2050; index++) {
+            stream.send({ ModelKey: `${index}`, ReadModel: '{}' });
+        }
+        if (acknowledgeAfter === 2050) stream.send({ Subscribed: true });
+        stream.end();
+        try {
+            for (let index = 0; index < 2050; index++) {
+                const result = await (index === 0 ? first : iterator.next());
+                result.done!.should.be.false;
+                result.value.key.should.equal(`${index}`);
+                if (index === 0 || index === 1024 || index === 2049) {
+                    // Simulate a slow consumer: no next() means no further transport pulls.
+                    await context.flush();
+                    stream.pulls.should.equal(index + 1 + (acknowledgeAfter === 0 ? 1 : 0));
+                }
+            }
+            (await iterator.next()).done!.should.be.true;
+        } finally {
+            await iterator.return!();
+        }
+    });
+
+    it('should retain optional change kind and context on pull-based changes', async () => {
+        const iterator = context.readModels.watch(context.model)[Symbol.asyncIterator]();
+        const next = iterator.next();
+        const correlationId = '12345678-1234-5678-9abc-123456789abc';
+        const occurred = '2026-06-07T08:09:10.123Z';
+        context.streams[0].send({ Namespace: 'tenant', ModelKey: 'one', ReadModel: '{"id":"one"}',
+            ChangeType: ContractChangeType.Added, EventSequenceNumber: 9007199254740997n,
+            CorrelationId: toContractsGuid(Guid.as(correlationId)), Occurred: { Value: occurred } });
+        const change = (await next).value;
+        change.changeType.should.equal(ReadModelChangeType.Added);
+        change.changeContext.should.deep.equal({ eventStore: 'store', namespace: 'tenant',
+            sequenceNumber: 9007199254740997n, correlationId, occurred: new Date(occurred) });
+        await iterator.return!();
+    });
+});

package/readModels/index.ts

@@ -9,6 +9,10 @@ export { ReadModels } from './ReadModels.js';
 export { MaterializedReadModels } from './MaterializedReadModels.js';
 export { ReadModelSubjectResolver } from './ReadModelSubjectResolver.js';
 export type { ReadModelChangeset } from './ReadModelChangeset.js';
+export type { IReadModelWatcher } from './IReadModelWatcher.js';
+export type { ReadModelWatchOptions } from './ReadModelWatchOptions.js';
+export type { ReadModelChangeContext } from './ReadModelChangeContext.js';
+export { ReadModelChangeType } from './ReadModelChangeType.js';
 export type { ReadModelSnapshot } from './ReadModelSnapshot.js';
 export type { ReadModelNamingPolicy } from './ReadModelNamingPolicy.js';
 export { readModel, getReadModelMetadata, isReadModel } from './readModel.js';

package/testing/EventScenario.event-sources.spec.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { chai, describe, it } from 'vitest';
+import { field } from '@cratis/fundamentals';
+import { eventType } from '../events/eventTypeDecorator.js';
+import { EventScenario, UnsupportedEventSequenceOperation } from './index.js';
+
+chai.should();
+class ScenarioSourceEvent { @field(String) name: string; constructor(name: string) { this.name = name; } }
+eventType('ScenarioSourceEvent')(ScenarioSourceEvent);
+
+const rejects = async (action: () => Promise<unknown>) => {
+    let caught: unknown;
+    try { await action(); } catch (error) { caught = error; }
+    (caught instanceof UnsupportedEventSequenceOperation).should.be.true;
+};
+const create = () => new EventScenario({ artifacts: { eventTypes: [ScenarioSourceEvent] } });
+
+describe('when appending with registered event sources in an in-process scenario', () => {
+    it('should reject the eventSource option on append instead of dropping it', async () => {
+        await rejects(() => create().append('A', new ScenarioSourceEvent('x'), { eventSource: 'Account' }));
+    });
+    it('should reject the eventSource option on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x') }], { eventSource: 'Account' }));
+    });
+    it('should reject a per-event eventSource on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x'), eventSource: 'Account' }]));
+    });
+    it('should reject a per-event eventStream on appendMany instead of dropping it', async () => {
+        await rejects(() => create().appendMany([{ eventSourceId: 'A', event: new ScenarioSourceEvent('x'), eventStream: 'Transactions' }]));
+    });
+});

package/testing/ReactorScenario.spec.ts

@@ -175,18 +175,35 @@ describe('ReactorScenario live delivery', () => {
                 try {
                     for await (const _change of services.readModels.watch(Registered)) { /* Unsupported. */ }
                 } catch (error) { errors.push(error); }
+                try {
+                    await services.readModels.createWatcher(Registered).subscribed;
+                } catch (error) { errors.push(error); }
             }
         }
         const scenario = new ReactorScenario(ServiceRejection, options);
         let failure: unknown;
         await scenario.when.forEventSource('A').events(new Registered('first')).catch(error => { failure = error; });
-        errors.length.should.equal(10);
+        errors.length.should.equal(11);
         errors.every(error => error instanceof UnsupportedReactorOperation && String(error).includes('Use a kernel-backed test.')).should.be.true;
         // Swallowed rejections still fail the delivery with the first unsupported operation.
         (failure === errors[0]).should.be.true;
         scenario.results[0].completed.should.be.false;
     });
 
+    it('should complete delivery if a reactor creates a watch without iterating it', async () => {
+        @reactor('uniterated-watch-reactor')
+        class UniteratedWatch {
+            registered(_event: Registered, _context: EventContext, services: ReactorServices) {
+                services.readModels.watch(Registered);
+                return new Skipped('produced');
+            }
+        }
+        const scenario = new ReactorScenario(UniteratedWatch, options);
+        await scenario.when.forEventSource('A').events(new Registered('first'));
+        scenario.results[0].completed.should.be.true;
+        scenario.shouldHaveProduced(Skipped, event => event.label === 'produced');
+    });
+
     it('rejects behavior pattern queries through the default event store', async () => {
         let error: unknown;
         @reactor('pattern-rejection-reactor')

package/testing/ReactorScenario.ts

@@ -105,6 +105,7 @@ export class ReactorScenario {
             'getSnapshotsById', 'dehydrateSession', 'release', 'releaseMany']);
         const readModels = new Proxy({}, { get: (_, key) => {
             if (key === 'watch') return async function* () { unsupported('readModels.watch'); };
+            if (key === 'createWatcher') return () => unsupported('readModels.createWatcher');
             if (key === 'materialized') return unsupported('readModels.materialized');
             if (typeof key !== 'string' || !readModelMethods.has(key)) return undefined;
             return async () => unsupported(`readModels.${key}`);

package/testing/projections/ProjectionReadModelProcessor.ts

@@ -138,7 +138,8 @@ export class ProjectionReadModelProcessor<TReadModel extends object> implements
             if (!state) {
                 // SetInitialState: an event only a child subscribes to creates an uninitialized parent.
                 state = from ? this.initialState(key, event) : this.identityState(key, event, false);
-            } else if (state.__initialized === false) {
+            } else if (state.__initialized === false && from) {
+                // Chronicle 19.30.0 no longer initializes a parent on events only a child subscribes to.
                 for (const [name, value] of Object.entries(this.initialValues())) if (!(name in state)) state[name] = value;
                 state.__initialized = true;
             }

package/transactions/IUnitOfWork.ts

@@ -6,6 +6,7 @@ import { AppendError } from '../eventSequences/AppendError.js';
 import { ConcurrencyViolation } from '../eventSequences/ConcurrencyViolation.js';
 import { ConstraintViolation } from '../eventSequences/ConstraintViolation.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { TransactionalEventRouting } from './TransactionalEventRouting.js';
 import { AppendResult } from '../eventSequences/AppendResult.js';
 
 /**
@@ -26,8 +27,9 @@ export interface IUnitOfWork {
      * @param eventSequenceId - The identifier of the event sequence to append to.
      * @param eventSourceId - The event source identifier.
      * @param event - The event payload.
+     * @param routing - Optional registered event source / stream routing for this event.
      */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object): void;
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, routing?: TransactionalEventRouting): void;
 
     /**
      * Gets all events currently buffered in this unit of work.

package/transactions/TransactionalEventRouting.ts

@@ -0,0 +1,16 @@
+// 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';
+
+/**
+ * Optional registered event source routing for an event added to a unit of work.
+ * Carried through to the append on commit, where it is validated like any other append.
+ */
+export interface TransactionalEventRouting {
+    /** Registered event source definition (class decorated with `@eventSource`, or its name). */
+    readonly eventSource?: Constructor | string;
+
+    /** Stream name declared by {@link eventSource}. */
+    readonly eventStream?: string;
+}

package/transactions/UnitOfWork.ts

@@ -8,7 +8,9 @@ import { ConcurrencyViolation } from '../eventSequences/ConcurrencyViolation.js'
 import { ConstraintViolation } from '../eventSequences/ConstraintViolation.js';
 import { EventForEventSourceId } from '../eventSequences/EventForEventSourceId.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
+import { planDerivedGuards, resolveBatchRouting } from '../eventSequences/resolveEventSourceRouting.js';
 import { IEventStore } from '../IEventStore.js';
+import { TransactionalEventRouting } from './TransactionalEventRouting.js';
 import { IUnitOfWork } from './IUnitOfWork.js';
 
 interface EventForEventSourceIdWithSequenceNumber {
@@ -46,14 +48,16 @@ export class UnitOfWork implements IUnitOfWork {
     }
 
     /** @inheritdoc */
-    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object): void {
+    addEvent(eventSequenceId: EventSequenceId, eventSourceId: string, event: object, routing?: TransactionalEventRouting): void {
         this.throwIfCompleted();
         this._events.push({
             sequenceNumber: this._events.length,
             eventSequenceId,
             eventForEventSourceId: {
                 eventSourceId,
-                event
+                event,
+                ...(routing?.eventSource !== undefined ? { eventSource: routing.eventSource } : {}),
+                ...(routing?.eventStream !== undefined ? { eventStream: routing.eventStream } : {})
             }
         });
     }
@@ -100,6 +104,13 @@ export class UnitOfWork implements IUnitOfWork {
                 eventsByEventSequence.set(key, events);
             }
 
+            // Resolve routing and required guards for every group first: a rejection must not follow a written group.
+            const eventSources = this._eventStore.eventSources;
+            for (const eventsForSequence of eventSources ? eventsByEventSequence.values() : []) {
+                const events = eventsForSequence.map(_ => _.eventForEventSourceId);
+                planDerivedGuards(events.map(_ => resolveBatchRouting(eventSources, _)), events, undefined);
+            }
+
             for (const [eventSequenceId, eventsForSequence] of eventsByEventSequence) {
                 const sequence = this._eventStore.getEventSequence(new EventSequenceId(eventSequenceId));
                 const appendResults = await sequence.appendMany(

package/transactions/for_UnitOfWork/when_committing_events_with_event_source_routing.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 { Guid } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it, vi } from 'vitest';
+import { EventSequenceId } from '../../eventSequences/index.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { UnitOfWork } from '../UnitOfWork.js';
+
+const should = chai.should();
+
+describe('when committing events with event source routing in a unit of work', () => {
+    let batch: any[];
+    beforeEach(async () => {
+        const appendMany = vi.fn().mockResolvedValue([{ isSuccess: true, constraintViolations: [], errors: [] }, { isSuccess: true, constraintViolations: [], errors: [] }]);
+        const store = { getEventSequence: () => ({ appendMany }) } as unknown as IEventStore;
+        const unitOfWork = new UnitOfWork(Guid.create(), () => {}, store);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', { first: 1 }, { eventSource: 'Account', eventStream: 'Transactions' });
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'c-1', { second: 2 }, { eventSource: 'Customer' });
+        await unitOfWork.commit();
+        batch = appendMany.mock.calls[0][0];
+    });
+    it('should keep the source and stream of the first event', () => {
+        batch[0].eventSource.should.equal('Account');
+        batch[0].eventStream.should.equal('Transactions');
+    });
+    it('should keep a different source on the second event without a stream', () => {
+        batch[1].eventSource.should.equal('Customer');
+        should.not.exist(batch[1].eventStream);
+    });
+});
+
+describe('when adding an event to a unit of work without routing', () => {
+    it('should not add routing keys to the buffered event', async () => {
+        const appendMany = vi.fn().mockResolvedValue([{ isSuccess: true, constraintViolations: [], errors: [] }]);
+        const unitOfWork = new UnitOfWork(Guid.create(), () => {}, { getEventSequence: () => ({ appendMany }) } as unknown as IEventStore);
+        unitOfWork.addEvent(EventSequenceId.eventLog, 'a-1', {});
+        await unitOfWork.commit();
+        Object.keys(appendMany.mock.calls[0][0][0]).sort().should.deep.equal(['event', 'eventSourceId']);
+    });
+});

package/transactions/index.ts

@@ -6,3 +6,4 @@ export type { IUnitOfWorkManager } from './IUnitOfWorkManager.js';
 export { NoUnitOfWorkHasBeenStarted } from './NoUnitOfWorkHasBeenStarted.js';
 export { UnitOfWork } from './UnitOfWork.js';
 export { UnitOfWorkManager } from './UnitOfWorkManager.js';
+export type { TransactionalEventRouting } from './TransactionalEventRouting.js';