@cratis/chronicle 6.46.0 → 6.48.0

package/readModels/for_ReadModelWatcher/against_a_kernel/when_watching_changes.integration.spec.ts

@@ -0,0 +1,104 @@
+// 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 { field } from '@cratis/fundamentals';
+import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { eventType } from '../../../events/index.js';
+import { fromEvent, removedWith } from '../../../projections/index.js';
+import type { IReadModelWatcher } from '../../IReadModelWatcher.js';
+import type { ReadModelChangeset } from '../../ReadModelChangeset.js';
+import { ReadModelChangeType } from '../../ReadModelChangeType.js';
+
+chai.should();
+const connectionString = process.env.CHRONICLE_INTEGRATION_CONNECTION_STRING;
+
+@eventType()
+class NameChanged {
+    @field(String) name = '';
+}
+
+@eventType()
+class EntryRemoved {
+    @field(String) reason = 'removed';
+}
+
+@fromEvent(NameChanged)
+@removedWith(EntryRemoved)
+class WatchedEntry {
+    @field(String) name = '';
+}
+
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [NameChanged, EntryRemoved], readModels: [WatchedEntry],
+    projections: [], reactors: [], reducers: [], seeders: [], constraints: [], webhooks: [],
+    eventTypeMigrations: [], globalForHandlers: []
+};
+
+describe.skipIf(!connectionString && !process.env.CI)('when awaiting readiness before appending against a kernel', () => {
+    const storeName = `Watcher${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    const source = randomUUID();
+    const correlationIds = [randomUUID(), randomUUID(), randomUUID()];
+    const occurred = new Date('2026-01-02T03:04:05.123Z');
+    const changes: ReadModelChangeset<WatchedEntry>[] = [];
+    const sequenceNumbers: bigint[] = [];
+    let client: ChronicleClient;
+    let watcher: IReadModelWatcher<WatchedEntry>;
+
+    beforeAll(async () => {
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
+            discoveryPatterns: [], clientArtifactsProvider: artifacts
+        }));
+        const store = await client.getEventStore(storeName);
+        watcher = store.readModels.createWatcher(WatchedEntry, { signal: AbortSignal.timeout(60_000) });
+        // No iteration, arbitrary sleep, or append before the server's readiness barrier.
+        await watcher.subscribed;
+        const iterator = watcher[Symbol.asyncIterator]();
+        const events = [Object.assign(new NameChanged(), { name: 'first' }),
+            Object.assign(new NameChanged(), { name: 'second' }), new EntryRemoved()];
+        for (const [index, event] of events.entries()) {
+            const result = await store.eventLog.append(source, event, { correlationId: correlationIds[index], occurred });
+            result.isSuccess.should.be.true;
+            sequenceNumbers.push(result.sequenceNumber.value);
+            const change = await iterator.next();
+            if (change.done) throw new Error('Watcher ended before the appended change arrived.');
+            changes.push(change.value);
+        }
+    });
+    afterAll(() => {
+        watcher?.dispose();
+        client?.dispose();
+    });
+
+    it('should observe creation, modification, and removal in order', () => {
+        changes.map(change => change.changeType).should.deep.equal([
+            ReadModelChangeType.Added, ReadModelChangeType.Modified, ReadModelChangeType.Removed
+        ]);
+    });
+    it('should preserve the existing model, key, namespace and removal fields', () => {
+        changes[0].readModel.should.be.instanceOf(WatchedEntry);
+        changes[0].readModel.name.should.equal('first');
+        changes[1].readModel.name.should.equal('second');
+        changes.map(change => change.key).should.deep.equal([source, source, source]);
+        changes.map(change => change.namespace).should.deep.equal(['Default', 'Default', 'Default']);
+        changes.map(change => change.removed).should.deep.equal([false, false, true]);
+    });
+    it('should preserve each triggering sequence number without numeric conversion', () => {
+        changes.map(change => change.changeContext!.sequenceNumber).should.deep.equal(sequenceNumbers);
+    });
+    it('should preserve each triggering correlation identifier', () => {
+        changes.map(change => change.changeContext!.correlationId).should.deep.equal(correlationIds);
+    });
+    it('should preserve each triggering timestamp', () => {
+        changes.map(change => change.changeContext!.occurred!.toISOString()).should.deep.equal([
+            occurred.toISOString(), occurred.toISOString(), occurred.toISOString()
+        ]);
+    });
+    it('should include the store and namespace in the triggering context', () => {
+        changes.every(change => change.changeContext!.eventStore === storeName &&
+            change.changeContext!.namespace === 'Default').should.be.true;
+    });
+});

package/readModels/for_ReadModelWatcher/given/a_kernel_stream.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReadModelChangeset } from '@cratis/chronicle.contracts';
+
+export class a_kernel_stream implements AsyncIterableIterator<ReadModelChangeset> {
+    private readonly _messages: IteratorResult<ReadModelChangeset>[] = [];
+    private _waiting?: {
+        resolve: (result: IteratorResult<ReadModelChangeset>) => void;
+        reject: (error: unknown) => void;
+    };
+    signal!: AbortSignal;
+    closed = false;
+    pulls = 0;
+
+    [Symbol.asyncIterator]() { return this; }
+
+    next(): Promise<IteratorResult<ReadModelChangeset>> {
+        this.pulls++;
+        const message = this._messages.shift();
+        if (message) return Promise.resolve(message);
+        if (this.closed) return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => { this._waiting = { resolve, reject }; });
+    }
+
+    async return(): Promise<IteratorResult<ReadModelChangeset>> {
+        this.end();
+        return { done: true, value: undefined };
+    }
+
+    send(change: Partial<ReadModelChangeset>): void {
+        const result = { done: false as const, value: ReadModelChangeset.fromPartial(change) };
+        if (this._waiting) {
+            this._waiting.resolve(result);
+            this._waiting = undefined;
+        } else this._messages.push(result);
+    }
+
+    end(): void {
+        this.closed = true;
+        this._waiting?.resolve({ done: true, value: undefined });
+        this._waiting = undefined;
+    }
+
+    fail(error: unknown): void {
+        if (!this._waiting) throw new Error('The stream must be reading before failing it.');
+        this._waiting.reject(error);
+        this._waiting = undefined;
+    }
+}

package/readModels/for_ReadModelWatcher/given/a_watched_read_model.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { vi } from 'vitest';
+import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import { ConnectionLifecycle } from '../../../connection/ConnectionLifecycle.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
+import { fromEvent } from '../../../projections/index.js';
+import { ReadModels } from '../../ReadModels.js';
+import { a_kernel_stream } from './a_kernel_stream.js';
+
+export class a_watched_read_model {
+    readonly model = class Model { id = ''; };
+    readonly lifecycle = new ConnectionLifecycle();
+    readonly streams: a_kernel_stream[] = [];
+    readonly watch = vi.fn((_request: unknown, options?: { signal: AbortSignal }) => {
+        const stream = new a_kernel_stream();
+        if (options) {
+            stream.signal = options.signal;
+            options.signal.addEventListener('abort', () => stream.end(), { once: true });
+        }
+        this.streams.push(stream);
+        return stream;
+    });
+    readonly readModels: ReadModels;
+
+    constructor() {
+        fromEvent(class Changed {})(this.model);
+        const artifacts = { readModels: [this.model], projections: [], reducers: [] } as unknown as IClientArtifactsProvider;
+        const connection = { readModels: { watch: this.watch } } as unknown as ChronicleConnection;
+        this.readModels = new ReadModels('store', 'tenant', connection, artifacts, 'sink', undefined, undefined, this.lifecycle);
+    }
+
+    async connect() { await this.lifecycle.connected(error => { throw error; }); }
+    async disconnect() { await this.lifecycle.disconnected(error => { throw error; }); }
+    async flush() { await new Promise<void>(resolve => setImmediate(resolve)); }
+}

package/readModels/for_ReadModelWatcher/watchCompatibility.standard.spec.ts

@@ -0,0 +1,29 @@
+// 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 { chai, describe, expectTypeOf, it } from 'vitest';
+import type { IReadModels } from '../IReadModels.js';
+import type { ReadModels } from '../ReadModels.js';
+import type { ReadModelChangeset } from '../ReadModelChangeset.js';
+
+chai.should();
+
+describe('when implementing the original watch contract', () => {
+    it('should keep exactly the signature exported on main', () => {
+        expectTypeOf<IReadModels['watch']>().toEqualTypeOf<
+            <TReadModel>(readModelType: Constructor<TReadModel>) => AsyncIterable<ReadModelChangeset<TReadModel>>
+        >();
+        expectTypeOf<ReadModels['watch']>().toEqualTypeOf<IReadModels['watch']>();
+    });
+
+    it('should accept an existing async generator implementation without watcher members', async () => {
+        const mock: Pick<IReadModels, 'watch'> = {
+            async *watch<TReadModel>(readModelType: Constructor<TReadModel>) {
+                yield { namespace: 'tenant', key: 'one', readModel: new readModelType(), removed: false };
+            }
+        };
+        const iterator = mock.watch(class Model {})[Symbol.asyncIterator]();
+        (await iterator.next()).value.key.should.equal('one');
+    });
+});

package/readModels/for_ReadModelWatcher/when_a_stream_cannot_recover.spec.ts

@@ -0,0 +1,86 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { ConnectionLifecycle } from '../../connection/ConnectionLifecycle.js';
+import { ReadModelWatcher } from '../ReadModelWatcher.js';
+import { a_kernel_stream } from './given/a_kernel_stream.js';
+import { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe('when a read model stream cannot recover', () => {
+    it.each([3, 7, 16])('should terminate on non-transport status %s', async code => {
+        const context = new a_watched_read_model();
+        await context.connect();
+        const watcher = context.readModels.createWatcher(context.model, { resume: true });
+        const failure = { code };
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher[Symbol.asyncIterator]().next().catch(error => error);
+        try {
+            context.streams[0].fail(failure);
+            (await readiness).should.equal(failure);
+            (await next).should.equal(failure);
+            await context.disconnect();
+            await context.connect();
+            context.streams.should.have.lengthOf(1);
+        } finally { watcher.dispose(); }
+    });
+
+    it('should not retry a transport-coded compliance or conversion failure', async () => {
+        const lifecycle = new ConnectionLifecycle();
+        await lifecycle.connected(error => { throw error; });
+        const stream = new a_kernel_stream();
+        const failure = { code: 14 };
+        let opened = 0;
+        const watcher = new ReadModelWatcher(() => { opened++; return stream; }, async () => { throw failure; }, new AbortController().signal, lifecycle, { resume: true });
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher.next().catch(error => error);
+        try {
+            stream.send({ ReadModel: '{}' });
+            (await readiness).should.equal(failure);
+            (await next).should.equal(failure);
+            await lifecycle.disconnected(error => { throw error; });
+            await lifecycle.connected(error => { throw error; });
+            opened.should.equal(1);
+        } finally { watcher.dispose(); }
+    });
+
+    it.each([false, true])('should retain completed standalone changes until consumed or disposed (disposed: %s)', async disposed => {
+        const stream = new a_kernel_stream();
+        const watcher = new ReadModelWatcher(() => stream, async change => ({
+            namespace: change.Namespace, key: change.ModelKey, readModel: {}, removed: false
+        }), new AbortController().signal);
+        try {
+            stream.send({ Subscribed: true });
+            stream.send({ ModelKey: 'first' });
+            stream.send({ ModelKey: 'second' });
+            stream.end();
+            await watcher.subscribed;
+            await new Promise<void>(resolve => setImmediate(resolve));
+            if (disposed) watcher.dispose();
+            else {
+                (await watcher.next()).value.key.should.equal('first');
+                (await watcher.next()).value.key.should.equal('second');
+            }
+            (await watcher.next()).done!.should.be.true;
+        } finally { watcher.dispose(); }
+    });
+
+    it.each([false, true])('should end a standalone stream cleanly (acknowledged: %s)', async acknowledged => {
+        const stream = new a_kernel_stream();
+        const watcher = new ReadModelWatcher(() => stream, async () => { throw new Error('Unexpected data'); }, new AbortController().signal);
+        try {
+            if (acknowledged) {
+                stream.send({ Subscribed: true });
+                await watcher.subscribed;
+            }
+            const readiness = watcher.subscribed.catch(error => error);
+            const next = watcher.next();
+            stream.end();
+            (await next).done!.should.be.true;
+            if (!acknowledged) (await readiness).message.should.contain('before subscription acknowledgment');
+            else await readiness;
+        } finally { watcher.dispose(); }
+    });
+});

package/readModels/for_ReadModelWatcher/when_applying_backpressure.spec.ts

@@ -0,0 +1,80 @@
+// 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 { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe('when applying read model watch backpressure', () => {
+    let context: a_watched_read_model;
+    beforeEach(async () => {
+        context = new a_watched_read_model();
+        await context.connect();
+    });
+    afterEach(() => context.readModels.dispose());
+
+    it('should pause a created watcher for a slow consumer and deliver more than the buffer limit without failure', async () => {
+        const iterator = context.readModels.createWatcher(context.model)[Symbol.asyncIterator]();
+        const stream = context.streams[0];
+        stream.send({ Subscribed: true });
+        for (let index = 0; index < 2050; index++) stream.send({ ModelKey: `${index}`, ReadModel: '{}' });
+        await context.flush();
+        stream.pulls.should.equal(1025); // One acknowledgment and 1,024 buffered changes.
+        stream.signal.aborted.should.be.false;
+        (await iterator.next()).value.key.should.equal('0');
+        await context.flush();
+        stream.pulls.should.equal(1026);
+        for (let index = 1; index < 2050; index++) {
+            (await iterator.next()).value.key.should.equal(`${index}`);
+        }
+        stream.end();
+        (await iterator.next()).done!.should.be.true;
+    });
+
+    it('should reach acknowledgment with a full pre-acknowledgment buffer then pause until consumption', async () => {
+        const watcher = context.readModels.createWatcher(context.model);
+        const stream = context.streams[0];
+        for (let index = 0; index < 1024; index++) stream.send({ ModelKey: `${index}`, ReadModel: '{}' });
+        stream.send({ Subscribed: true });
+        stream.send({ ModelKey: 'after', ReadModel: '{}' });
+        await watcher.subscribed;
+        await context.flush();
+        stream.pulls.should.equal(1025);
+        const iterator = watcher[Symbol.asyncIterator]();
+        for (let index = 0; index < 1024; index++) (await iterator.next()).value.key.should.equal(`${index}`);
+        (await iterator.next()).value.key.should.equal('after');
+    });
+
+    it('should cancel a paused read on disposal', async () => {
+        const watcher = context.readModels.createWatcher(context.model);
+        const stream = context.streams[0];
+        stream.send({ Subscribed: true });
+        for (let index = 0; index < 1024; index++) stream.send({ ReadModel: '{}' });
+        await context.flush();
+        watcher.dispose();
+        await context.flush();
+        stream.closed.should.be.true;
+        stream.signal.aborted.should.be.true;
+        stream.pulls.should.equal(1025);
+        (await watcher[Symbol.asyncIterator]().next()).done!.should.be.true;
+    });
+
+    it('should read eagerly again until each resumed stream acknowledges even with a full buffer', async () => {
+        const watcher = context.readModels.createWatcher(context.model, { resume: true });
+        context.streams[0].send({ Subscribed: true });
+        for (let index = 0; index < 1024; index++) context.streams[0].send({ ModelKey: `${index}`, ReadModel: '{}' });
+        await context.flush();
+        await context.disconnect();
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        context.streams[1].send({ ModelKey: 'resumed', ReadModel: '{}' });
+        await watcher.subscribed;
+        await context.flush();
+        context.streams[0].closed.should.be.true;
+        context.streams[1].pulls.should.equal(1);
+        const iterator = watcher[Symbol.asyncIterator]();
+        for (let index = 0; index < 1024; index++) (await iterator.next()).value.key.should.equal(`${index}`);
+        (await iterator.next()).value.key.should.equal('resumed');
+    });
+});

package/readModels/for_ReadModelWatcher/when_failing_with_buffered_changes.spec.ts

@@ -0,0 +1,39 @@
+// 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 { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe.each(['transport', 'stream', 'connection'] as const)('when a read model watcher has buffered changes before a terminal %s failure', kind => {
+    let context: a_watched_read_model;
+    beforeEach(async () => {
+        context = new a_watched_read_model();
+        await context.connect();
+    });
+    afterEach(() => context.readModels.dispose());
+
+    it.each([false, true])('should drain received changes before rejecting with the original error (acknowledged: %s)', async acknowledged => {
+        const watcher = context.readModels.createWatcher(context.model, { resume: kind !== 'transport' });
+        const readiness = watcher.subscribed.catch(error => error);
+        const stream = context.streams[0];
+        if (acknowledged) {
+            stream.send({ Subscribed: true });
+            await readiness;
+        }
+        stream.send({ ModelKey: 'first', ReadModel: '{"id":"first"}' });
+        stream.send({ ModelKey: 'second', ReadModel: '{"id":"second"}' });
+        await context.flush();
+        const failure = Object.assign(new Error('terminal failure'), { code: kind === 'transport' ? 14 : 7 });
+        if (kind === 'connection') await context.lifecycle.failed(failure, error => { throw error; });
+        else stream.fail(failure);
+        await context.flush();
+        if (!acknowledged) (await readiness).should.equal(failure);
+        stream.signal.aborted.should.be.true;
+        const iterator = watcher[Symbol.asyncIterator]();
+        (await iterator.next()).value.should.contain({ key: 'first' });
+        (await iterator.next()).value.should.contain({ key: 'second' });
+        (await iterator.next().catch(error => error)).should.equal(failure);
+    });
+});

package/readModels/for_ReadModelWatcher/when_not_opting_into_resume.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, vi } from 'vitest';
+import { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe.each(['watch', 'createWatcher'] as const)('when %s has not opted into resumption', method => {
+    let context: a_watched_read_model;
+    beforeEach(async () => {
+        vi.useFakeTimers();
+        context = new a_watched_read_model();
+        await context.connect();
+    });
+    afterEach(() => {
+        context.readModels.dispose();
+        vi.useRealTimers();
+    });
+
+    it.each([1, 4, 13, 14])('should reject iteration with the original transport error for status %s', async code => {
+        const iterator = context.readModels[method](context.model)[Symbol.asyncIterator]();
+        const next = iterator.next().catch(error => error);
+        context.streams[0].send({ Subscribed: true });
+        await vi.advanceTimersByTimeAsync(0);
+        const failure = Object.assign(new Error('transport failed'), { code });
+        // A keep-alive disconnect arriving first must not replace the watch stream error.
+        await context.disconnect();
+        context.streams[0].closed.should.be.false;
+        context.streams[0].fail(failure);
+        (await next).should.equal(failure);
+        await context.connect();
+        await vi.advanceTimersByTimeAsync(1000);
+        context.streams.should.have.lengthOf(1);
+    });
+
+    it('should complete iteration without restarting after stream completion', async () => {
+        const iterator = context.readModels[method](context.model)[Symbol.asyncIterator]();
+        const next = iterator.next();
+        context.streams[0].send({ Subscribed: true });
+        context.streams[0].send({ ModelKey: 'received', ReadModel: '{}' });
+        context.streams[0].end();
+        await vi.advanceTimersByTimeAsync(1000);
+        (await next).value.key.should.equal('received');
+        (await iterator.next()).done!.should.be.true;
+        context.streams.should.have.lengthOf(1);
+    });
+
+    it('should stop opting into resumption after the last callback is removed', async () => {
+        const watcher = context.readModels.createWatcher(context.model);
+        const unsubscribe = watcher.onResubscribed(() => {});
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        unsubscribe();
+        const failure = { code: 14 };
+        const next = watcher[Symbol.asyncIterator]().next().catch(error => error);
+        context.streams[0].fail(failure);
+        (await next).should.equal(failure);
+        await vi.advanceTimersByTimeAsync(1000);
+        context.streams.should.have.lengthOf(1);
+    });
+});

package/readModels/for_ReadModelWatcher/when_notifying_resubscription.spec.ts

@@ -0,0 +1,128 @@
+// 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();
+
+describe('when notifying read model resubscription', () => {
+    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(() => context.readModels.dispose());
+
+    it('should notify once per acknowledged resubscription and ignore duplicate markers', async () => {
+        const callback = vi.fn();
+        watcher.onResubscribed(callback);
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        for (let generation = 1; generation <= 2; generation++) {
+            await context.disconnect();
+            await context.connect();
+            callback.mock.calls.should.have.lengthOf(generation - 1);
+            context.streams[generation].send({ Subscribed: true });
+            context.streams[generation].send({ Subscribed: true });
+            await context.flush();
+            callback.mock.calls.should.have.lengthOf(generation);
+        }
+    });
+
+    it('should not notify for the first acknowledgment after an unacknowledged disconnect', async () => {
+        const callback = vi.fn();
+        watcher.onResubscribed(callback);
+        await context.disconnect();
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        await watcher.subscribed;
+        await context.flush();
+        callback.mock.calls.should.have.lengthOf(0);
+    });
+
+    it('should unregister callbacks idempotently without removing other callbacks', async () => {
+        const removed = vi.fn();
+        const remaining = vi.fn();
+        const unsubscribe = watcher.onResubscribed(removed);
+        watcher.onResubscribed(remaining);
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        unsubscribe();
+        unsubscribe();
+        await context.disconnect();
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        await context.flush();
+        removed.mock.calls.should.have.lengthOf(0);
+        remaining.mock.calls.should.have.lengthOf(1);
+    });
+
+    it('should await refresh callbacks in registration order before delivering resumed changes', async () => {
+        let finishRefresh!: () => void;
+        const refresh = new Promise<void>(resolve => { finishRefresh = resolve; });
+        const calls: string[] = [];
+        watcher.onResubscribed(async () => {
+            calls.push('refresh');
+            await refresh;
+        });
+        watcher.onResubscribed(() => { calls.push('refreshed'); });
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        const next = watcher[Symbol.asyncIterator]().next().then(change => {
+            calls.push('change');
+            return change;
+        });
+        await context.disconnect();
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        context.streams[1].send({ ModelKey: 'new', ReadModel: '{}' });
+        await context.flush();
+        calls.should.deep.equal(['refresh']);
+        finishRefresh();
+        (await next).value.key.should.equal('new');
+        calls.should.deep.equal(['refresh', 'refreshed', 'change']);
+    });
+
+    it.each([false, true])('should fail iteration on a callback failure even with a transport code (async: %s)', async asynchronous => {
+        const failure = { code: 14 };
+        watcher.onResubscribed(() => {
+            if (asynchronous) return Promise.reject(failure);
+            throw failure;
+        });
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        const next = watcher[Symbol.asyncIterator]().next().catch(error => error);
+        await context.disconnect();
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        (await next).should.equal(failure);
+        context.streams[1].signal.aborted.should.be.true;
+        await context.disconnect();
+        await context.connect();
+        context.streams.should.have.lengthOf(2);
+    });
+
+    it('should stop notifying callbacks when disposed during a refresh', async () => {
+        const remaining = vi.fn();
+        watcher.onResubscribed(() => watcher.dispose());
+        watcher.onResubscribed(remaining);
+        context.streams[0].send({ Subscribed: true });
+        await watcher.subscribed;
+        const next = watcher[Symbol.asyncIterator]().next();
+        await context.disconnect();
+        await context.connect();
+        context.streams[1].send({ Subscribed: true });
+        (await next).done!.should.be.true;
+        await context.flush();
+        remaining.mock.calls.should.have.lengthOf(0);
+        const unsubscribe = watcher.onResubscribed(remaining);
+        unsubscribe();
+        await context.disconnect();
+        await context.connect();
+        context.streams.should.have.lengthOf(2);
+    });
+});

package/readModels/for_ReadModelWatcher/when_opting_into_overflow.spec.ts

@@ -0,0 +1,39 @@
+// 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 { a_watched_read_model } from './given/a_watched_read_model.js';
+
+chai.should();
+
+describe('when opting into watch overflow failure', () => {
+    let context: a_watched_read_model;
+    beforeEach(async () => {
+        context = new a_watched_read_model();
+        await context.connect();
+    });
+    afterEach(() => context.readModels.dispose());
+
+    it.each([false, true])('should fail instead of dropping changes above the explicit limit (acknowledged: %s)', async acknowledged => {
+        const watcher = context.readModels.createWatcher(context.model, { maxBuffered: 2, resume: true });
+        const readiness = watcher.subscribed.catch(error => error);
+        if (acknowledged) {
+            context.streams[0].send({ Subscribed: true });
+            await readiness;
+        }
+        for (let index = 0; index < 3; index++) context.streams[0].send({ ReadModel: '{}' });
+        await context.flush();
+        const failure = await watcher[Symbol.asyncIterator]().next().catch(error => error);
+        failure.message.should.contain('buffer exceeded 2 changes');
+        if (!acknowledged) (await readiness).should.equal(failure);
+        context.streams[0].signal.aborted.should.be.true;
+        await context.disconnect();
+        await context.connect();
+        context.streams.should.have.lengthOf(1);
+    });
+
+    it.each([0, -1, 1.5, Infinity, NaN, Number.MAX_SAFE_INTEGER + 1])('should reject an invalid limit %s before opening a stream', maxBuffered => {
+        (() => context.readModels.createWatcher(context.model, { maxBuffered })).should.throw(RangeError);
+        context.streams.should.have.lengthOf(0);
+    });
+});