@cratis/chronicle 6.47.0 → 6.49.0

package/for_ChronicleClient/when_reconnecting/with_waiting_read_model_watchers.spec.ts

@@ -0,0 +1,117 @@
+// 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 { ChronicleClient } from '../../ChronicleClient.js';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import { EventStore } from '../../EventStore.js';
+import type { IEventStore } from '../../IEventStore.js';
+import { IncompatibleChronicleServer } from '../../connection/IncompatibleChronicleServer.js';
+import { RejectedChronicleCredentials } from '../../connection/RejectedChronicleCredentials.js';
+import { projection } from '../../projections/declarative/projection.js';
+import type { IReadModelWatcher } from '../../readModels/IReadModelWatcher.js';
+import { a_kernel_stream } from '../../readModels/for_ReadModelWatcher/given/a_kernel_stream.js';
+
+chai.should();
+
+const transport = vi.hoisted(() => ({
+    resetChannel: vi.fn(), connect: vi.fn(), disconnect: vi.fn(), getVersionInfo: vi.fn(),
+    ensureEventStore: vi.fn(), watch: vi.fn(),
+    lost: undefined as ((reason: string, error: unknown) => void) | undefined
+}));
+vi.mock('../../connection/ChronicleConnection', () => ({
+    ChronicleConnection: class {
+        resetChannel = transport.resetChannel;
+        connect = transport.connect;
+        disconnect = transport.disconnect;
+        server = { getVersionInfo: transport.getVersionInfo };
+        eventStores = { ensureEventStore: transport.ensureEventStore };
+        readModels = { watch: transport.watch };
+    }
+}));
+vi.mock('../../connection/KernelKeepAlive', () => ({
+    KernelKeepAlive: class {
+        constructor(_connections: unknown, onLost: (reason: string, error: unknown) => void) { transport.lost = onLost; }
+        async start() {}
+    }
+}));
+
+class Model { id = ''; }
+class ModelProjection { define() {} }
+projection('model', Model)(ModelProjection);
+
+describe('when reconnecting with waiting read model watchers', () => {
+    let client: ChronicleClient;
+    let store: IEventStore;
+    let watcher: IReadModelWatcher<Model>;
+    let stream: a_kernel_stream;
+    let rejectReconnect: (error: Error) => void;
+
+    beforeEach(async () => {
+        vi.useFakeTimers();
+        vi.clearAllMocks();
+        // Registration is outside this connection-lifetime specification; retain the real store and watchers.
+        vi.spyOn(EventStore.prototype, 'registerArtifacts').mockResolvedValue(undefined);
+        transport.resetChannel.mockResolvedValue(undefined);
+        transport.connect.mockResolvedValue(undefined);
+        transport.getVersionInfo.mockResolvedValue({});
+        transport.ensureEventStore.mockResolvedValue({ IsSuccess: true, IsAuthorized: true });
+        stream = new a_kernel_stream();
+        transport.watch.mockImplementation((_request, options: { signal: AbortSignal }) => {
+            stream.signal = options.signal;
+            options.signal.addEventListener('abort', () => stream.end(), { once: true });
+            return stream;
+        });
+        client = new ChronicleClient(ChronicleOptions.fromConnectionString('chronicle://localhost:35000', {
+            discoveryPatterns: [],
+            clientArtifactsProvider: {
+                readModels: [Model], projections: [ModelProjection], eventTypes: [], reactors: [], reducers: [],
+                seeders: [], constraints: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+            }
+        }));
+        store = await client.getEventStore('store');
+        watcher = store.readModels.createWatcher(Model, { resume: true });
+        stream.send({ Subscribed: true });
+        await watcher.subscribed;
+        transport.connect.mockImplementation(() => new Promise<void>((_resolve, reject) => { rejectReconnect = reject; }));
+        transport.lost!('keep-alive-ended', { code: 14 });
+        await vi.advanceTimersByTimeAsync(0);
+        stream.signal.aborted.should.be.true;
+    });
+    afterEach(() => {
+        client.dispose();
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+
+    it.each([
+        ['incompatible server', IncompatibleChronicleServer],
+        ['rejected credentials', RejectedChronicleCredentials]
+    ] as const)('should reject readiness and iteration on terminal %s', async (_reason, Failure) => {
+        const failure = new Failure('Replacement connection rejected');
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher[Symbol.asyncIterator]().next().catch(error => error);
+        rejectReconnect(failure);
+        (await readiness).should.equal(failure);
+        (await next).should.equal(failure);
+        await vi.advanceTimersByTimeAsync(15000);
+        transport.watch.mock.calls.should.have.lengthOf(1);
+        transport.connect.mock.calls.should.have.lengthOf(2);
+        // A cached store cannot create a watcher that waits forever after the terminal verdict.
+        const later = store.readModels.createWatcher(Model);
+        (await later.subscribed.catch(error => error)).should.equal(failure);
+        (await later[Symbol.asyncIterator]().next().catch(error => error)).should.equal(failure);
+    });
+
+    it('should reject pending readiness but complete iteration cleanly if disposed during recovery', async () => {
+        const readiness = watcher.subscribed.catch(error => error);
+        const next = watcher[Symbol.asyncIterator]().next();
+        client.dispose();
+        (await readiness).name.should.equal('AbortError');
+        (await next).done!.should.be.true;
+        rejectReconnect(new IncompatibleChronicleServer('Late reconnect failure'));
+        await vi.advanceTimersByTimeAsync(15000);
+        (await watcher[Symbol.asyncIterator]().next()).done!.should.be.true;
+        transport.watch.mock.calls.should.have.lengthOf(1);
+    });
+});

package/for_EventStore/when_implementing_a_legacy_event_store.spec.ts

@@ -0,0 +1,19 @@
+// 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 type { IEventStore } from '../IEventStore.js';
+
+const should = chai.should();
+
+/** An implementation written before event sources existed: it has no `eventSources` member. */
+type LegacyEventStore = Omit<IEventStore, 'eventSources'>;
+
+describe('when implementing an event store written before event sources', () => {
+    it('should still satisfy the IEventStore contract', () => {
+        // Compile-time regression: assigning would fail type-checking if `eventSources` became required.
+        const legacy = {} as LegacyEventStore;
+        const store: IEventStore = legacy;
+        should.not.exist(store.eventSources);
+    });
+});

package/index.ts

@@ -3,6 +3,7 @@
 
 import * as events from './events/index.js';
 import * as eventSequences from './eventSequences/index.js';
+import * as eventSources from './eventSources/index.js';
 import * as reactors from './reactors/index.js';
 import * as reducers from './reducers/index.js';
 import * as seeding from './seeding/index.js';
@@ -48,6 +49,7 @@ export { DiagChronicleLogger } from './logging/DiagChronicleLogger.js';
 
 export * from './events/index.js';
 export * from './eventSequences/index.js';
+export * from './eventSources/index.js';
 export * from './reactors/index.js';
 export * from './reducers/index.js';
 export * from './seeding/index.js';
@@ -74,6 +76,7 @@ export * from './confidentiality/index.js';
 export {
     events,
     eventSequences,
+    eventSources,
     reactors,
     reducers,
     seeding,

package/jobs/for_Jobs/against_a_kernel/when_managing_a_replay_job.integration.spec.ts

@@ -3,12 +3,13 @@
 
 import { randomUUID } from 'node:crypto';
 import { afterAll, beforeAll, chai, describe, it } from 'vitest';
-import { JobStatus, JobStepStatus, type JobStepSummaryResponse, type JobSummaryResponse } from '@cratis/chronicle.contracts';
+import { JobStatus, JobStepStatus, ObserverRunningState, type JobStepSummaryResponse, type JobSummaryResponse } from '@cratis/chronicle.contracts';
 import { field, Guid } from '@cratis/fundamentals';
 import { ChronicleClient } from '../../../ChronicleClient.js';
 import { ChronicleOptions } from '../../../ChronicleOptions.js';
 import { fromContractsGuid } from '../../../connection/Guid.js';
 import type { IClientArtifactsProvider } from '../../../artifacts/index.js';
+import type { ChronicleConnection } from '../../../connection/index.js';
 import { eventType } from '../../../events/index.js';
 import type { IEventStore } from '../../../IEventStore.js';
 import { fromEvent } from '../../../projections/index.js';
@@ -55,8 +56,10 @@ async function eventually<T>(read: () => Promise<T>, accept: (value: T) => boole
 }
 
 describe.skipIf(!connectionString && !process.env.CI)('when managing a replay job against a kernel', () => {
+    const storeName = `Jobs${randomUUID().replaceAll('-', '').slice(0, 12)}`;
     let client: ChronicleClient;
     let store: IEventStore;
+    let connection: ChronicleConnection;
     let jobId: JobId;
     let listed: JobSummaryResponse[];
     let stopped: JobSummaryResponse | undefined;
@@ -65,19 +68,36 @@ describe.skipIf(!connectionString && !process.env.CI)('when managing a replay jo
     let stopUnknownJob: unknown;
     let deleteUnknownJob: unknown;
 
+    const waitForActiveObserver = (lastHandledSequenceNumber?: bigint) => eventually(
+        () => connection.observers.getObserverInformation({
+            EventStore: storeName,
+            Namespace: 'Default',
+            ObserverId: 'Item',
+            EventSequenceId: 'event-log'
+        }),
+        observer => observer.IsSubscribed && observer.RunningState === ObserverRunningState.Active &&
+            (lastHandledSequenceNumber === undefined || observer.LastHandledEventSequenceNumber === lastHandledSequenceNumber),
+        15_000);
+
+    // Readiness (30s) and the existing job-state waits (90s) leave 30s for RPC overhead.
     beforeAll(async () => {
         client = new ChronicleClient(ChronicleOptions.fromConnectionString(connectionString!, {
             discoveryPatterns: [],
             clientArtifactsProvider: artifacts
         }));
-        store = await client.getEventStore(`Jobs${randomUUID().replaceAll('-', '').slice(0, 12)}`);
+        store = await client.getEventStore(storeName);
+        connection = (store as unknown as { _connection: ChronicleConnection })._connection;
 
+        // Append only after initial catch-up completes, so it cannot race the explicit replay.
+        await waitForActiveObserver();
         // Enough events that the replay is still running when it is stopped; a stopped job stays until deleted,
         // where a completed one is removed and could not be listed reliably.
-        await store.eventLog.appendMany(Array.from({ length: 500 }, (_, index) => ({
+        const appended = await store.eventLog.appendMany(Array.from({ length: 500 }, (_, index) => ({
             eventSourceId: randomUUID(),
             event: Object.assign(new ItemAdded(), { name: `Item ${index}` })
         })));
+        // ReplayForModel uses Observer.Replay too; wait for acknowledged progress before requesting it.
+        await waitForActiveObserver(appended.at(-1)!.sequenceNumber.value);
 
         jobId = await store.projections.replayForModel(Item);
 
@@ -98,7 +118,7 @@ describe.skipIf(!connectionString && !process.env.CI)('when managing a replay jo
 
         stopUnknownJob = await store.jobs.stop(randomUUID()).catch((error: unknown) => error);
         deleteUnknownJob = await store.jobs.delete(randomUUID()).catch((error: unknown) => error);
-    });
+    }, 150_000);
 
     afterAll(() => client?.dispose());
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.47.0",
+    "version": "6.49.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -173,12 +173,12 @@
         "clean": "rm -rf dist",
         "test": "vitest run",
         "test:integration": "vitest run --config vitest.integration.config.ts",
-        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.standard.spec.ts events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts reactors/for_Reactors/against_a_kernel/when_filtering_source_and_stream_types.integration.spec.ts testing/for_observerScenarios/when_selecting_filters/with_source_and_stream_types.spec.ts",
+        "test:standard-types": "tsc --ignoreConfig --noEmit --target es2022 --module es2022 --moduleResolution bundler --lib es2022,esnext.decorators --types node --skipLibCheck --strict schemas/decorators.standard.spec.ts projections/declarative/addChildCompatibility.standard.spec.ts projections/declarative/for_CompositeKeyBuilder/when_typing_constant_parts.standard.spec.ts projections/modelBound/decorators.standard.spec.ts events/classDecorators.standard.spec.ts reactors/decorators.standard.spec.ts readModels/standardFallbacks.standard.spec.ts readModels/registration.standard.spec.ts for_ChronicleClient/when_registering_artifacts/with_standard_property_mappings.standard.spec.ts artifacts/validateArtifactSchemas.spec.ts testing/for_EventScenario/when_appending_concept_fields/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_scoped_constraints/with_standard_decorators.standard.spec.ts schemas/for_JsonSchemaGenerator/when_generating_children/with_standard_decorators.standard.spec.ts events/for_handles/when_decorating_a_method.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_arithmetic/with_standard_decorators.standard.spec.ts testing/for_ReadModelScenario/when_evaluating_joins/with_standard_decorators.standard.spec.ts testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all_events.standard.spec.ts events/for_observerFilters/when_registering/with_standard_decorators.standard.spec.ts reactors/for_Reactors/against_a_kernel/when_filtering_source_and_stream_types.integration.spec.ts testing/for_observerScenarios/when_selecting_filters/with_source_and_stream_types.spec.ts readModels/for_ReadModelWatcher/watchCompatibility.standard.spec.ts for_EventStore/when_implementing_a_legacy_event_store.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {
         "@bufbuild/protobuf": "^2.16.0",
-        "@cratis/chronicle.contracts": "19.26.2",
+        "@cratis/chronicle.contracts": "19.30.0",
         "@grpc/grpc-js": "^1.14.5",
         "@opentelemetry/api": "^1.9.1",
         "glob": "^13.0.6",

package/projections/eventContextPropertyExpression.ts

@@ -23,7 +23,8 @@ const contextProperties = {
     correlationId: true,
     causation: true,
     tags: true
-} satisfies Record<keyof EventContext, true>;
+    // eventSource is deliberately not projectable: its kernel resolution is not part of the supported expression set.
+} satisfies Record<Exclude<keyof EventContext, 'eventSource'>, true>;
 
 // Mirror the kernel's DerivedPropertyFunctions registry: Week() applies to dates only.
 const derivedFunctions: Record<string, string> = { week: 'Week' };

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