@cratis/chronicle 6.46.0 → 6.48.0

package/reactors/for_Reactors/against_a_kernel/when_replaying_reactors_with_once_only_handlers.integration.spec.ts

@@ -3,6 +3,7 @@
 
 import { randomUUID } from 'node:crypto';
 import { afterAll, beforeAll, chai, describe, it } from 'vitest';
+import { ObserverRunningState } from '@cratis/chronicle.contracts';
 import { field } from '@cratis/fundamentals';
 import { ChronicleClient } from '../../../ChronicleClient.js';
 import { ChronicleOptions } from '../../../ChronicleOptions.js';
@@ -65,12 +66,11 @@ const artifacts: IClientArtifactsProvider = {
     globalForHandlers: []
 };
 
-// 30s was occasionally too tight for this reactor's initial catch-up under concurrent
-// kernel load in CI (observed timing out at 31.2s on a run that passed cleanly on retry
-// with no code change); 45s keeps the polling assertion honest while tolerating that jitter.
-async function eventually(accept: () => boolean, timeoutMs = 45_000): Promise<void> {
+// Keep the existing 45s replay polling budget for concurrent kernel load in CI.
+// Initial observation is gated separately by the bounded readiness waits below.
+async function eventually(accept: () => boolean | Promise<boolean>, timeoutMs = 45_000): Promise<void> {
     const deadline = Date.now() + timeoutMs;
-    while (!accept()) {
+    while (!await accept()) {
         if (Date.now() > deadline) throw new Error('Timed out waiting for the kernel');
         await new Promise(resolve => setTimeout(resolve, 250));
     }
@@ -86,6 +86,17 @@ describe.skipIf(!connectionString && !process.env.CI)('when replaying a reactor
     let jobId: string | undefined;
     let invocationsBeforeReplay: string[];
 
+    const waitForActiveObserver = (lastHandledSequenceNumber?: bigint, timeoutMs = 15_000) => eventually(async () => {
+        const observer = await connection.observers.getObserverInformation({
+            EventStore: storeName,
+            Namespace: 'Default',
+            ObserverId: 'MixedOnceOnlyReactor',
+            EventSequenceId: 'event-log'
+        });
+        return observer.IsSubscribed && observer.RunningState === ObserverRunningState.Active &&
+            (lastHandledSequenceNumber === undefined || observer.LastHandledEventSequenceNumber === lastHandledSequenceNumber);
+    }, timeoutMs);
+
     beforeAll(async () => {
         client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
             discoveryPatterns: [],
@@ -94,10 +105,18 @@ describe.skipIf(!connectionString && !process.env.CI)('when replaying a reactor
         store = await client.getEventStore(storeName);
         connection = (store as unknown as { _connection: ChronicleConnection })._connection;
 
+        // Registration starts observation in the background. Append only after the subscription
+        // is active, so initial catch-up cannot race the explicit replay's state transition.
+        // Initial registration and subscription took over 30s under concurrent CI kernel load before.
+        await waitForActiveObserver(undefined, 30_000);
         (await store.eventLog.append(randomUUID(), Object.assign(new MethodOnceOnlyHappened(), { name: 'a' }))).isSuccess.should.be.true;
         (await store.eventLog.append(randomUUID(), Object.assign(new MethodReplayableHappened(), { name: 'b' }))).isSuccess.should.be.true;
-        (await store.eventLog.append(randomUUID(), Object.assign(new MethodReplayOnceOnlyHappened(), { name: 'c' }))).isSuccess.should.be.true;
-        await eventually(() => invocations.length === 3);
+        const appended = await store.eventLog.append(randomUUID(), Object.assign(new MethodReplayOnceOnlyHappened(), { name: 'c' }));
+        appended.isSuccess.should.be.true;
+        // Worst case 30s + 30s + 15s + 45s + 3s stays inside the explicit 150s hook timeout below.
+        await eventually(() => invocations.length === 3, 30_000);
+        // The handlers update their sink before the kernel acknowledges delivery and records progress.
+        await waitForActiveObserver(appended.sequenceNumber.value);
         invocationsBeforeReplay = [...invocations];
 
         jobId = (await connection.observers.replay({
@@ -108,7 +127,7 @@ describe.skipIf(!connectionString && !process.env.CI)('when replaying a reactor
         })).JobId;
         await eventually(() => invocations.includes('replayable:b') && invocations.filter(_ => _ === 'replayable:b').length === 2);
         await new Promise(resolve => setTimeout(resolve, 3_000));
-    });
+    }, 150_000);
 
     afterAll(() => client?.dispose());
 

package/readModels/IReadModelWatcher.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ReadModelChangeset } from './ReadModelChangeset.js';
+
+/**
+ * A single-consumer stream of read model changes, started when createWatcher() is called.
+ * Terminal stream or connection failures retain buffered changes: iteration drains them
+ * before rejecting with the original error. Overflow and disposal discard buffered changes.
+ */
+export interface IReadModelWatcher<TReadModel> extends AsyncIterable<ReadModelChangeset<TReadModel>> {
+    /**
+     * Resolves on the kernel's subscription acknowledgment, without requiring iteration.
+     * When resumption is opted into, read this property again after disconnect for the next subscription.
+     * An already pending promise carries across lifecycle reconnects; a previously resolved
+     * promise cannot be revoked. Rejects if the watcher stops before acknowledgment.
+     */
+    readonly subscribed: Promise<void>;
+
+    /**
+     * Registers a callback after each subscription acknowledgment following the first.
+     * Having at least one registered callback opts into resumption on transport failures and
+     * completion. Without callbacks or the resume option, transport errors reject iteration.
+     * Refresh your query here: changes during an outage are not replayed. Register before
+     * awaiting subscribed; callbacks are not replayed for late registrations.
+     * Callbacks run in registration order and are awaited before reading more changes on
+     * the resumed stream. Do not wait for iteration inside a callback. A thrown error or
+     * rejected promise fails iteration. Reconnects retain already received changes.
+     * @returns An idempotent function that unregisters the callback. Disposal also unregisters it.
+     */
+    onResubscribed(callback: () => void | Promise<void>): () => void;
+
+    /** Stops the stream and completes pending iteration. Safe to call more than once. */
+    dispose(): void;
+}

package/readModels/IReadModels.ts

@@ -3,7 +3,9 @@
 
 import type { Constructor } from '@cratis/fundamentals';
 import type { IMaterializedReadModels } from './IMaterializedReadModels.js';
+import type { IReadModelWatcher } from './IReadModelWatcher.js';
 import type { ReadModelChangeset } from './ReadModelChangeset.js';
+import type { ReadModelWatchOptions } from './ReadModelWatchOptions.js';
 import type { ReadModelSnapshot } from './ReadModelSnapshot.js';
 
 /**
@@ -65,12 +67,25 @@ export interface IReadModels {
     getSnapshotsById<TReadModel>(readModelType: Constructor<TReadModel>, key: string): Promise<ReadModelSnapshot<TReadModel>[]>;
 
     /**
-     * Watches changes for a specific read model type.
+     * Watches changes for a specific read model type, opening the stream on the first next().
+     * Pulls changes only as the consumer requests them, without a client-side buffer or overflow limit.
      * @param readModelType - The read model type to observe.
-     * @returns An async iterable of read model changes.
+     * @returns An async iterable of read model changes. Transport failures reject iteration.
+     * @remarks Keeps its original return type so existing watch implementations and mocks can
+     * return plain async iterables. Use createWatcher for readiness and lifetime controls.
      */
     watch<TReadModel>(readModelType: Constructor<TReadModel>): AsyncIterable<ReadModelChangeset<TReadModel>>;
 
+    /**
+     * Starts a single-consumer watcher immediately, without requiring iteration for readiness.
+     * @param readModelType - The read model type to observe.
+     * @param options - Cancellation, opt-in resumption, and an optional overflow-failure limit.
+     * @returns A watcher with subscription readiness, resubscription callbacks, and explicit disposal.
+     * Transport failures reject iteration unless resume is true or an onResubscribed callback
+     * is registered. Resumed watches retain received changes but do not replay outage gaps.
+     */
+    createWatcher<TReadModel>(readModelType: Constructor<TReadModel>, options?: ReadModelWatchOptions): IReadModelWatcher<TReadModel>;
+
     /**
      * Dehydrates a read model session.
      * @param sessionId - The session identifier to dehydrate.

package/readModels/ReadModelChangeContext.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The triggering event metadata available on the kernel's read model change stream. */
+export interface ReadModelChangeContext {
+    readonly eventStore: string;
+    readonly namespace: string;
+    readonly sequenceNumber: bigint;
+    readonly correlationId?: string;
+    readonly occurred?: Date;
+}

package/readModels/ReadModelChangeType.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The kind of change to a read model instance. */
+export enum ReadModelChangeType {
+    Added = 0,
+    Modified = 1,
+    Removed = 2
+}

package/readModels/ReadModelChangeset.ts

@@ -1,6 +1,9 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import type { ReadModelChangeType } from './ReadModelChangeType.js';
+import type { ReadModelChangeContext } from './ReadModelChangeContext.js';
+
 /**
  * Represents a change observed for a read model.
  */
@@ -16,4 +19,10 @@ export interface ReadModelChangeset<TReadModel> {
 
     /** Whether the read model was removed. */
     readonly removed: boolean;
+
+    /** The kind of change. Optional for compatibility with user-created changesets. */
+    readonly changeType?: ReadModelChangeType;
+
+    /** Triggering event metadata supplied by the kernel, not a complete event context. */
+    readonly changeContext?: ReadModelChangeContext;
 }

package/readModels/ReadModelWatchOptions.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Options for creating a read model watcher. */
+export interface ReadModelWatchOptions {
+    /** Aborting completes iteration and rejects pending readiness. */
+    readonly signal?: AbortSignal;
+
+    /**
+     * Resume after transport failure or completion. Defaults to false; registering an
+     * onResubscribed callback also opts in while at least one callback is registered.
+     * Changes missed during an outage are not replayed; refresh your query after resubscription.
+     */
+    readonly resume?: boolean;
+
+    /**
+     * Opt into failing on overflow instead of applying backpressure. Must be a positive safe integer.
+     * By default, pause reads at 1,024 buffered changes after subscription acknowledgment.
+     * Before each acknowledgment, keep reading to reach the marker; exceeding 1,024 changes
+     * (or this explicit limit) fails iteration and pending readiness rather than dropping changes.
+     */
+    readonly maxBuffered?: number;
+}

package/readModels/ReadModelWatcher.ts

@@ -0,0 +1,271 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ReadModelChangeset as ContractChangeset } from '@cratis/chronicle.contracts';
+import type { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
+import type { IReadModelWatcher } from './IReadModelWatcher.js';
+import type { ReadModelChangeset } from './ReadModelChangeset.js';
+import type { ReadModelWatchOptions } from './ReadModelWatchOptions.js';
+
+/** @internal Owns one cancellable stream per connection generation. */
+export class ReadModelWatcher<TReadModel> implements IReadModelWatcher<TReadModel>, AsyncIterableIterator<ReadModelChangeset<TReadModel>> {
+    private static readonly _restartDelayMs = 1000;
+    private readonly _bufferLimit: number;
+    private readonly _failOnOverflow: boolean;
+    private readonly _resume: boolean;
+    private _resumeReading?: () => void;
+
+    private _subscribed!: Promise<void>;
+    private _resolveSubscribed!: () => void;
+    private _rejectSubscribed!: (error: unknown) => void;
+    private _acknowledged = false;
+    private _hasSubscribed = false;
+    private _delivery = Promise.resolve();
+    private readonly _onResubscribed = new Set<() => void | Promise<void>>();
+    private _controller?: AbortController;
+    private _stopped = false;
+    private _failed = false;
+    private _failure?: unknown;
+    private readonly _buffered: ReadModelChangeset<TReadModel>[] = [];
+    private _restartTimer?: ReturnType<typeof setTimeout>;
+    private readonly _waiting: {
+        resolve: (result: IteratorResult<ReadModelChangeset<TReadModel>>) => void;
+        reject: (error: unknown) => void;
+    }[] = [];
+    private readonly _unsubscribe: (() => void)[] = [];
+
+    constructor(
+        private readonly _open: (signal: AbortSignal) => AsyncIterable<ContractChangeset>,
+        private readonly _convert: (change: ContractChangeset) => Promise<ReadModelChangeset<TReadModel>>,
+        signal: AbortSignal,
+        private readonly _lifecycle?: ConnectionLifecycle,
+        options: ReadModelWatchOptions = {}
+    ) {
+        if (options.maxBuffered !== undefined && (!Number.isSafeInteger(options.maxBuffered) || options.maxBuffered < 1)) {
+            throw new RangeError('maxBuffered must be a positive safe integer.');
+        }
+        this._bufferLimit = options.maxBuffered ?? 1024;
+        this._failOnOverflow = options.maxBuffered !== undefined;
+        this._resume = options.resume === true;
+        this.resetReadiness();
+        const abort = () => this.finish(signal.reason, false);
+        signal.addEventListener('abort', abort, { once: true });
+        this._unsubscribe.push(() => signal.removeEventListener('abort', abort));
+        if (_lifecycle) {
+            // Without opt-in, let the watch stream propagate its original transport error.
+            this._unsubscribe.push(_lifecycle.onDisconnected(async () => {
+                if (this.shouldResume()) this.disconnect();
+            }));
+            this._unsubscribe.push(_lifecycle.onConnected(async () => this.start()));
+            this._unsubscribe.push(_lifecycle.onFailed(async error => this.finish(error, true, true)));
+        }
+        if (signal.aborted) {
+            abort();
+        } else if (_lifecycle?.failure) {
+            this.finish(_lifecycle.failure, true, true);
+        } else if (!_lifecycle || _lifecycle.isConnected) {
+            this.start();
+        }
+    }
+
+    get subscribed(): Promise<void> {
+        return this._subscribed;
+    }
+
+    onResubscribed(callback: () => void | Promise<void>): () => void {
+        if (this._stopped) return () => {};
+        this._onResubscribed.add(callback);
+        return () => { this._onResubscribed.delete(callback); };
+    }
+
+    [Symbol.asyncIterator](): AsyncIterableIterator<ReadModelChangeset<TReadModel>> {
+        return this;
+    }
+
+    next(): Promise<IteratorResult<ReadModelChangeset<TReadModel>>> {
+        const value = this._buffered.shift();
+        if (value) {
+            this.resumeReading();
+            return Promise.resolve({ done: false, value });
+        }
+        if (this._failed) return Promise.reject(this._failure);
+        if (this._stopped) return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => this._waiting.push({ resolve, reject }));
+    }
+
+    async return(): Promise<IteratorResult<ReadModelChangeset<TReadModel>>> {
+        this.dispose();
+        return { done: true, value: undefined };
+    }
+
+    dispose(): void {
+        this._buffered.length = 0;
+        this.finish(new DOMException('Read model watcher disposed.', 'AbortError'), false);
+    }
+
+    private resetReadiness(): void {
+        this._acknowledged = false;
+        this._subscribed = new Promise<void>((resolve, reject) => {
+            this._resolveSubscribed = resolve;
+            this._rejectSubscribed = reject;
+        });
+        // Legacy consumers only iterate. They still receive stream failures from next();
+        // not observing the optional readiness promise must not cause an unhandled rejection.
+        this._subscribed.catch(() => {});
+    }
+
+    private start(): void {
+        if (this._stopped || this._controller) return;
+        this.clearRestartTimer();
+        const controller = new AbortController();
+        this._controller = controller;
+        void this.read(controller);
+    }
+
+    private disconnect(): void {
+        if (this._stopped) return;
+        this.clearRestartTimer();
+        this.cancelStream();
+        // Received changes are not replayed by the kernel. Keep them across reconnects.
+        if (this._acknowledged) this.resetReadiness();
+    }
+
+    private shouldResume(): boolean {
+        return this._resume || this._onResubscribed.size > 0;
+    }
+
+    private restart(): void {
+        this.disconnect();
+        if (this._stopped || (this._lifecycle && !this._lifecycle.isConnected)) return;
+        // The watch and keep-alive share a transport, but can fail in either order.
+        // Also recover a watch-only failure if no disconnected notification follows.
+        this._restartTimer = setTimeout(() => {
+            this._restartTimer = undefined;
+            if (!this._lifecycle || this._lifecycle.isConnected) this.start();
+        }, ReadModelWatcher._restartDelayMs);
+        this._restartTimer.unref?.();
+    }
+
+    private clearRestartTimer(): void {
+        clearTimeout(this._restartTimer);
+        this._restartTimer = undefined;
+    }
+
+    private cancelStream(): void {
+        const controller = this._controller;
+        this._controller = undefined;
+        controller?.abort();
+        this.resumeReading();
+    }
+
+    private resumeReading(): void {
+        this._resumeReading?.();
+        this._resumeReading = undefined;
+    }
+
+    private waitForCapacity(controller: AbortController): Promise<void> | undefined {
+        if (this._controller === controller && this._acknowledged && !this._failOnOverflow &&
+            this._buffered.length >= this._bufferLimit) {
+            return new Promise<void>(resolve => { this._resumeReading = resolve; })
+                .then(() => this.waitForCapacity(controller));
+        }
+        return undefined;
+    }
+
+    private async read(controller: AbortController): Promise<void> {
+        try {
+            for await (const change of this._open(controller.signal)) {
+                if (this._controller !== controller) return;
+                if (change.Subscribed) {
+                    if (this._acknowledged) continue;
+                    this._acknowledged = true;
+                    this._resolveSubscribed();
+                    const resubscribed = this._hasSubscribed;
+                    this._hasSubscribed = true;
+                    if (resubscribed) {
+                        const callbacks = [...this._onResubscribed];
+                        this._delivery = this._delivery.then(() => this.notifyResubscribed(callbacks));
+                        await this._delivery;
+                    }
+                    const capacity = this.waitForCapacity(controller);
+                    if (capacity) await capacity;
+                    if (this._controller !== controller) return;
+                    continue;
+                }
+                // Finish converting changes already received, even if their stream disconnects.
+                // A new stream queues behind them so conversion cannot reorder delivery.
+                this._delivery = this._delivery.then(() => this.deliver(change));
+                await this._delivery;
+                const capacity = this.waitForCapacity(controller);
+                if (capacity) await capacity;
+                if (this._controller !== controller) return;
+            }
+            if (this._controller === controller) {
+                if (this.shouldResume()) this.restart();
+                else this.finish(new Error('Read model watch ended before subscription acknowledgment.'), false, true);
+            }
+        } catch (error) {
+            if (this._controller !== controller) return;
+            const code = (error as { code?: number })?.code;
+            if (this.shouldResume() && code !== undefined && [1, 4, 13, 14].includes(code)) this.restart();
+            // Let the consumer drain received changes before observing the terminal stream error.
+            else this.finish(error, true, true);
+        }
+    }
+
+    private async deliver(change: ContractChangeset): Promise<void> {
+        if (this._stopped) return;
+        let converted: ReadModelChangeset<TReadModel>;
+        try {
+            converted = await this._convert(change);
+        } catch (error) {
+            // Conversion includes compliance RPCs: even transport-coded errors here
+            // are terminal, not permission to skip an unreleased change.
+            this.finish(error, true);
+            return;
+        }
+        if (this._stopped) return;
+        const waiting = this._waiting.shift();
+        if (waiting) {
+            waiting.resolve({ done: false, value: converted });
+        } else {
+            // Before Subscribed we must keep reading to reach the readiness marker.
+            // Afterward the default pauses reads; only an explicit limit opts into failure.
+            if (this._buffered.length >= this._bufferLimit) {
+                this.finish(new Error(`Read model watcher buffer exceeded ${this._bufferLimit} changes. Consume changes faster or refresh the read model and create a new watcher.`), true);
+                return;
+            }
+            this._buffered.push(converted);
+        }
+    }
+
+    private async notifyResubscribed(callbacks: (() => void | Promise<void>)[]): Promise<void> {
+        try {
+            for (const callback of callbacks) {
+                if (this._stopped) return;
+                if (this._onResubscribed.has(callback)) await callback();
+            }
+        } catch (error) {
+            // A failed refresh is not a recovered watch, even for transport-coded errors.
+            this.finish(error, true);
+        }
+    }
+
+    private finish(reason: unknown, failed: boolean, preserveBuffered = false): void {
+        if (this._stopped) return;
+        this._stopped = true;
+        this._failed = failed;
+        this._failure = reason;
+        this._rejectSubscribed(reason);
+        this.clearRestartTimer();
+        this.cancelStream();
+        if (!preserveBuffered) this._buffered.length = 0;
+        for (const unsubscribe of this._unsubscribe) unsubscribe();
+        this._unsubscribe.length = 0;
+        this._onResubscribed.clear();
+        for (const waiting of this._waiting.splice(0)) {
+            if (failed) waiting.reject(reason);
+            else waiting.resolve({ done: true, value: undefined });
+        }
+    }
+}

package/readModels/ReadModels.ts

@@ -3,15 +3,19 @@
 
 import type {
     AppendedEvent,
+    ReadModelChangeset as ContractReadModelChangeset,
     ReadModelObserverType
 } from '@cratis/chronicle.contracts';
 import {
-    ReadModelObserverType as ContractReadModelObserverType
+    ReadModelObserverType as ContractReadModelObserverType,
+    ReadModelChangeType as ContractReadModelChangeType
 } from '@cratis/chronicle.contracts';
 import type { Constructor } from '@cratis/fundamentals';
 import { JsonSerializer } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
+import type { ConnectionLifecycle } from '../connection/ConnectionLifecycle.js';
+import { fromContractsGuid } from '../connection/Guid.js';
 import { ensureQuerySuccess } from '../connection/callResults.js';
 import { EventSequenceId } from '../eventSequences/EventSequenceId.js';
 import { getProjectionMetadata } from '../projections/declarative/projection.js';
@@ -31,7 +35,11 @@ import { ReadModelSubjectResolver } from './ReadModelSubjectResolver.js';
 import { deserializeReadModel } from './deserializeReadModel.js';
 import type { ReadModelNamingPolicy } from './ReadModelNamingPolicy.js';
 import type { IReadModels } from './IReadModels.js';
+import type { IReadModelWatcher } from './IReadModelWatcher.js';
+import { ReadModelWatcher } from './ReadModelWatcher.js';
 import type { ReadModelChangeset } from './ReadModelChangeset.js';
+import type { ReadModelWatchOptions } from './ReadModelWatchOptions.js';
+import { ReadModelChangeType } from './ReadModelChangeType.js';
 import type { ReadModelSnapshot } from './ReadModelSnapshot.js';
 
 const unlimitedEventCount = BigInt('18446744073709551615');
@@ -52,6 +60,7 @@ interface ResolvedReadModel {
  */
 export class ReadModels implements IReadModels {
     readonly materialized: IMaterializedReadModels;
+    private readonly _watchCancellation = new AbortController();
 
     constructor(
         private readonly _eventStore: string,
@@ -60,7 +69,8 @@ export class ReadModels implements IReadModels {
         private readonly _clientArtifacts: IClientArtifactsProvider,
         private readonly _defaultSinkTypeId: string,
         private readonly _isModelBoundProjectionRegistered?: (readModelType: Constructor) => boolean,
-        private readonly _readModelNamingPolicy?: ReadModelNamingPolicy
+        private readonly _readModelNamingPolicy?: ReadModelNamingPolicy,
+        private readonly _lifecycle?: ConnectionLifecycle
     ) {
         this.materialized = new MaterializedReadModels(_eventStore, _namespace, _connection);
     }
@@ -185,18 +195,35 @@ export class ReadModels implements IReadModels {
                 continue;
             }
 
-            const instance = this.deserializeReadModel(readModelType, changeset.ReadModel);
-            const requiresRelease = !changeset.Removed && readModel.observerType === ContractReadModelObserverType.Reducer &&
-                this.schemaHasComplianceMetadata(readModel.schema);
-            yield {
-                namespace: changeset.Namespace,
-                key: changeset.ModelKey,
-                readModel: requiresRelease ? await this.release(readModelType, instance) : instance,
-                removed: changeset.Removed
-            };
+            yield await this.toChangeset(readModelType, readModel, changeset);
         }
     }
 
+    /** @inheritdoc */
+    createWatcher<TReadModel>(readModelType: Constructor<TReadModel>, options?: ReadModelWatchOptions): IReadModelWatcher<TReadModel> {
+        const readModel = this.resolveReadModel(readModelType);
+        const signal = AbortSignal.any(options?.signal
+            ? [options.signal, this._watchCancellation.signal]
+            : [this._watchCancellation.signal]);
+        return new ReadModelWatcher(
+            streamSignal => this._connection.readModels.watch({
+                EventStore: this._eventStore,
+                Namespace: this._namespace,
+                ReadModelIdentifier: readModel.identifier,
+                EventSequenceId: readModel.eventSequenceId
+            }, { signal: streamSignal }),
+            changeset => this.toChangeset(readModelType, readModel, changeset),
+            signal,
+            this._lifecycle,
+            options
+        );
+    }
+
+    /** Stops all watchers created through createWatcher for this event store. */
+    dispose(): void {
+        this._watchCancellation.abort();
+    }
+
     /** @inheritdoc */
     async dehydrateSession<TReadModel>(sessionId: string, readModelType: Constructor<TReadModel>, key: string): Promise<void> {
         const readModel = this.resolveReadModel(readModelType);
@@ -355,6 +382,28 @@ export class ReadModels implements IReadModels {
         return typeof value === 'string' && value.length > 0;
     }
 
+    private async toChangeset<TReadModel>(readModelType: Constructor<TReadModel>, readModel: ResolvedReadModel, changeset: ContractReadModelChangeset): Promise<ReadModelChangeset<TReadModel>> {
+        const instance = this.deserializeReadModel(readModelType, changeset.ReadModel);
+        const occurred = changeset.Occurred?.Value ? new Date(changeset.Occurred.Value) : undefined;
+        const requiresRelease = !changeset.Removed && readModel.observerType === ContractReadModelObserverType.Reducer &&
+            this.schemaHasComplianceMetadata(readModel.schema);
+        return {
+            namespace: changeset.Namespace,
+            key: changeset.ModelKey,
+            readModel: requiresRelease ? await this.release(readModelType, instance) : instance,
+            removed: changeset.Removed,
+            changeType: changeset.ChangeType === ContractReadModelChangeType.Added ? ReadModelChangeType.Added :
+                changeset.ChangeType === ContractReadModelChangeType.Removed ? ReadModelChangeType.Removed : ReadModelChangeType.Modified,
+            changeContext: {
+                eventStore: this._eventStore,
+                namespace: changeset.Namespace,
+                sequenceNumber: changeset.EventSequenceNumber,
+                correlationId: changeset.CorrelationId ? fromContractsGuid(changeset.CorrelationId).toString() : undefined,
+                occurred: occurred && !Number.isNaN(occurred.getTime()) ? occurred : undefined
+            }
+        };
+    }
+
     private async releaseSnapshotInstances<TReadModel>(readModelType: Constructor<TReadModel>, snapshots: ReadModelSnapshot<TReadModel>[]): Promise<ReadModelSnapshot<TReadModel>[]> {
         return Promise.all(
             snapshots.map(async snapshot => ({