@cratis/chronicle 6.46.0 → 6.48.0

package/readModels/for_ReadModelWatcher/when_receiving_changes.spec.ts

@@ -0,0 +1,69 @@
+// 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 { ReadModelChangeType as ContractChangeType } from '@cratis/chronicle.contracts';
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import { toContractsGuid } from '../../connection/Guid.js';
+import type { IReadModelWatcher } from '../IReadModelWatcher.js';
+import { ReadModelChangeType } from '../ReadModelChangeType.js';
+import { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe('when receiving 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);
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+    });
+    afterEach(() => watcher.dispose());
+
+    for (const [contractKind, kind] of [
+        [ContractChangeType.Added, ReadModelChangeType.Added],
+        [ContractChangeType.Modified, ReadModelChangeType.Modified],
+        [ContractChangeType.Removed, ReadModelChangeType.Removed],
+        [ContractChangeType.UNRECOGNIZED, ReadModelChangeType.Modified]
+    ]) {
+        it(`should preserve ${ContractChangeType[contractKind]} changes and their triggering context`, async () => {
+            const removed = contractKind === ContractChangeType.Removed;
+            const occurred = '2026-06-07T08:09:10.123Z';
+            const correlationId = '12345678-1234-5678-9abc-123456789abc';
+            context.streams[0].send({ Namespace: 'tenant', ModelKey: 'one', ReadModel: removed ? '' : '{"id":"one"}',
+                Removed: removed, ChangeType: contractKind, EventSequenceNumber: 9007199254740997n,
+                CorrelationId: toContractsGuid(Guid.as(correlationId)), Occurred: { Value: occurred } });
+            const change = (await watcher[Symbol.asyncIterator]().next()).value;
+            change.namespace.should.equal('tenant');
+            change.key.should.equal('one');
+            change.removed.should.equal(removed);
+            change.readModel.should.be.instanceOf(context.model);
+            change.changeType.should.equal(kind);
+            change.changeContext.should.deep.equal({ eventStore: 'store', namespace: 'tenant',
+                sequenceNumber: 9007199254740997n, correlationId, occurred: new Date(occurred) });
+        });
+    }
+
+    it('should leave absent timestamp and correlation metadata absent', async () => {
+        context.streams[0].send({ ReadModel: '{}' });
+        const change = (await watcher[Symbol.asyncIterator]().next()).value;
+        (change.changeContext.occurred === undefined).should.be.true;
+        (change.changeContext.correlationId === undefined).should.be.true;
+    });
+
+    it.each(['', 'not a timestamp'])('should leave an empty or invalid timestamp (%s) absent', async value => {
+        context.streams[0].send({ ReadModel: '{}', Occurred: { Value: value } });
+        const change = (await watcher[Symbol.asyncIterator]().next()).value;
+        (change.changeContext.occurred === undefined).should.be.true;
+    });
+
+    it('should surface a deserialization failure and stop the stream', async () => {
+        const next = watcher[Symbol.asyncIterator]().next().catch(error => error);
+        context.streams[0].send({ ReadModel: 'not json' });
+        (await next).should.be.instanceOf(SyntaxError);
+        context.streams[0].signal.aborted.should.be.true;
+    });
+});

package/readModels/for_ReadModelWatcher/when_reconnecting.spec.ts

@@ -0,0 +1,99 @@
+// 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 reconnecting a read model watcher', () => {
+    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, { resume: true });
+    });
+    afterEach(() => context.readModels.dispose());
+
+    it('should replace resolved readiness at disconnect and continue the same iterator after a fresh acknowledgment', async () => {
+        context.streams[0].send({ Subscribed: true });
+        const firstReadiness = watcher.subscribed;
+        await firstReadiness;
+        const iterator = watcher[Symbol.asyncIterator]();
+        const next = iterator.next();
+        await context.disconnect();
+        context.streams[0].signal.aborted.should.be.true;
+        watcher.subscribed.should.not.equal(firstReadiness);
+        let ready = false;
+        void watcher.subscribed.then(() => { ready = true; });
+        await context.connect();
+        await context.flush();
+        ready.should.be.false;
+        context.streams[1].send({ Subscribed: true });
+        await watcher.subscribed;
+        ready.should.be.true;
+        context.streams[1].send({ ModelKey: 'new', ReadModel: '{"id":"new"}' });
+        (await next).value.key.should.equal('new');
+    });
+
+    it('should preserve still pending readiness across a disconnect before acknowledgment', async () => {
+        const pending = watcher.subscribed;
+        await context.disconnect();
+        watcher.subscribed.should.equal(pending);
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        await pending;
+    });
+
+    it('should deliver buffered changes from the previous connection before new changes', async () => {
+        context.streams[0].send({ Subscribed: true });
+        context.streams[0].send({ ModelKey: 'old', ReadModel: '{"id":"old"}' });
+        await watcher.subscribed;
+        await context.flush();
+        await context.disconnect();
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        context.streams[1].send({ ModelKey: 'new', ReadModel: '{"id":"new"}' });
+        const iterator = watcher[Symbol.asyncIterator]();
+        (await iterator.next()).value.key.should.equal('old');
+        (await iterator.next()).value.key.should.equal('new');
+    });
+
+    it('should acknowledge a new subscription before consuming its buffered changes', async () => {
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        const iterator = watcher[Symbol.asyncIterator]();
+        await context.disconnect();
+        const readiness = watcher.subscribed;
+        await context.connect();
+        context.streams[1].send({ ModelKey: 'new', ReadModel: '{"id":"new"}' });
+        context.streams[1].send({ Subscribed: true });
+        await readiness;
+        (await iterator.next()).value.key.should.equal('new');
+    });
+
+    it('should not create duplicate streams for repeated connected notifications', async () => {
+        await context.connect();
+        context.streams.should.have.lengthOf(1);
+    });
+
+    it('should not restart a disposed watcher', async () => {
+        watcher.dispose();
+        await context.disconnect();
+        await context.connect();
+        context.streams.should.have.lengthOf(1);
+    });
+
+    it('should defer opening a watcher created while disconnected', async () => {
+        watcher.dispose();
+        await context.disconnect();
+        watcher = context.readModels.createWatcher(context.model);
+        context.streams.should.have.lengthOf(1);
+        await context.connect();
+        context.streams.should.have.lengthOf(2);
+        context.streams[1].send({ Subscribed: true });
+        await watcher.subscribed;
+    });
+});

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/reducers/Reducers.ts

@@ -12,6 +12,8 @@ import { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
 import { toClientEventContext } from '../events/toClientEventContext.js';
 import { getTagsFor } from '../events/tagDecorator.js';
 import { getFilterTagsFor } from '../events/filterEventsByTagDecorator.js';
+import { getEventSourceTypeFor } from '../events/eventSourceTypeDecorator.js';
+import { getEventStreamTypeFor } from '../events/eventStreamTypeDecorator.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
 import { notifyReplayLifecycle } from '../observation/notifyReplayLifecycle.js';
 import { IReducers } from './IReducers.js';
@@ -347,8 +349,8 @@ export class Reducers implements IReducers {
                         Tags: getTagsFor(reducerType).map(t => t.value),
                         Filters: {
                             FilterTags: getFilterTagsFor(reducerType).map(t => t.value),
-                            EventSourceType: '',
-                            EventStreamType: 'All'
+                            EventSourceType: getEventSourceTypeFor(reducerType),
+                            EventStreamType: getEventStreamTypeFor(reducerType)
                         }
                     }
                 },

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')