@cratis/chronicle 2.1.1 → 3.1.0

package/externalServices/IExternalServiceBuilder.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines a fluent builder for configuring an external service.
+ */
+export interface IExternalServiceBuilder {
+    /**
+     * Configures the service as an HTTP endpoint.
+     * @param url - The base URL of the endpoint.
+     * @returns The builder for chaining.
+     */
+    http(url: string): IExternalServiceBuilder;
+
+    /**
+     * Configures basic authentication for an HTTP endpoint.
+     * @param username - The username.
+     * @param password - The password.
+     * @returns The builder for chaining.
+     */
+    withBasicAuth(username: string, password: string): IExternalServiceBuilder;
+
+    /**
+     * Configures bearer token authentication for an HTTP endpoint.
+     * @param token - The bearer token.
+     * @returns The builder for chaining.
+     */
+    withBearerToken(token: string): IExternalServiceBuilder;
+
+    /**
+     * Configures OAuth authentication for an HTTP endpoint.
+     * @param authority - The OAuth authority.
+     * @param clientId - The OAuth client id.
+     * @param clientSecret - The OAuth client secret.
+     * @returns The builder for chaining.
+     */
+    withOAuth(authority: string, clientId: string, clientSecret: string): IExternalServiceBuilder;
+
+    /**
+     * Adds a header to send with every HTTP request.
+     * @param key - The header key.
+     * @param value - The header value.
+     * @returns The builder for chaining.
+     */
+    withHeader(key: string, value: string): IExternalServiceBuilder;
+
+    /**
+     * Configures the service as a Microsoft SQL Server database endpoint.
+     * @param host - The database host.
+     * @param database - The database name.
+     * @param username - The username used to connect.
+     * @param password - The password used to connect.
+     * @param port - The database port. Leave as 0 to use the provider default.
+     * @returns The builder for chaining.
+     */
+    msSql(host: string, database: string, username: string, password: string, port?: number): IExternalServiceBuilder;
+
+    /**
+     * Configures the service as a PostgreSQL database endpoint.
+     * @param host - The database host.
+     * @param database - The database name.
+     * @param username - The username used to connect.
+     * @param password - The password used to connect.
+     * @param port - The database port. Leave as 0 to use the provider default.
+     * @returns The builder for chaining.
+     */
+    postgreSql(host: string, database: string, username: string, password: string, port?: number): IExternalServiceBuilder;
+
+    /**
+     * Adds a provider-specific option to a database endpoint's connection options.
+     * @param key - The option key.
+     * @param value - The option value.
+     * @returns The builder for chaining.
+     */
+    withOption(key: string, value: string): IExternalServiceBuilder;
+}

package/externalServices/IExternalServices.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IExternalServiceBuilder } from './IExternalServiceBuilder';
+
+/**
+ * Defines a system for working with external service registrations for the Kernel.
+ */
+export interface IExternalServices {
+    /**
+     * Registers an external service.
+     * @param name - The name of the external service. The name is also used as its identifier.
+     * @param configure - Callback for configuring the external service.
+     */
+    register(name: string, configure: (builder: IExternalServiceBuilder) => void): Promise<void>;
+}

package/externalServices/index.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export type { IExternalServiceBuilder } from './IExternalServiceBuilder';
+export { ExternalServiceBuilder } from './ExternalServiceBuilder';
+export type { IExternalServices } from './IExternalServices';
+export { ExternalServices } from './ExternalServices';

package/fundamentalsPeerRange.spec.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+// The peer range's lower bound is a compatibility claim; the exact devDependency pin is the only version this
+// package is ever compiled and tested against. When they disagree the range claims support for versions nothing
+// verifies, and nothing fails until a consumer resolves one of them.
+//
+// That is not hypothetical: the range shipped as ^7 while ConceptAs - used here as a runtime value, compared by
+// class object in JsonSchemaGenerator - only exists from 7.14.0 onward, leaving 48 published versions that
+// satisfied the range and could not link. Tying the bound to the pin is what stops the two drifting again.
+const manifest = JSON.parse(
+    readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf-8')) as {
+        peerDependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+    };
+
+describe('fundamentals peer range', () => {
+    const peer = manifest.peerDependencies?.['@cratis/fundamentals'];
+    const pinned = manifest.devDependencies?.['@cratis/fundamentals'];
+
+    it('should declare fundamentals as a peer dependency', () => expect(peer).toBeDefined());
+
+    it('should pin one concrete version to build against', () => expect(pinned).toMatch(/^\d+\.\d+\.\d+$/));
+
+    it('should admit no version below the one it builds against', () => expect(peer).toBe(`^${pinned}`));
+});

package/identities/IIdentityManager.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.
+
+/**
+ * Defines a manager of identities in the system.
+ */
+export interface IIdentityManager {
+    /**
+     * Renames the name of an identity, identified by its subject.
+     * @param subject - The subject of the identity to rename.
+     * @param name - The new name to give the identity.
+     * @remarks
+     * The subject is the stable identifier of the identity - the name is the display name and
+     * can change over time, for instance when a person changes their name. Renaming an identity
+     * affects every event and read model that refers to the identity, as the name is resolved
+     * from the identity itself and not stored with what refers to it.
+     */
+    rename(subject: string, name: string): Promise<void>;
+}

package/identities/IdentityManager.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ChronicleConnection } from '../connection';
+import { IIdentityManager } from './IIdentityManager';
+
+/**
+ * Implements {@link IIdentityManager} by proxying to the Chronicle Kernel over the client connection.
+ */
+export class IdentityManager implements IIdentityManager {
+    /**
+     * Creates a new {@link IdentityManager} instance.
+     * @param _eventStore - Event store name.
+     * @param _namespace - Event store namespace.
+     * @param _connection - Chronicle connection.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _namespace: string,
+        private readonly _connection: ChronicleConnection
+    ) {}
+
+    /** @inheritdoc */
+    async rename(subject: string, name: string): Promise<void> {
+        await this._connection.identities.renameIdentity({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            Subject: subject,
+            Name: name
+        });
+    }
+}

package/identities/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export type { IIdentityManager } from './IIdentityManager';
+export { IdentityManager } from './IdentityManager';

package/index.ts

@@ -10,6 +10,8 @@ import * as readModels from './readModels';
 import * as projections from './projections';
 import * as jobs from './jobs';
 import * as webhooks from './webhooks';
+import * as externalServices from './externalServices';
+import * as identities from './identities';
 import * as observation from './observation';
 import * as sinks from './sinks';
 import * as schemas from './schemas';
@@ -42,6 +44,8 @@ export * from './readModels';
 export * from './projections';
 export * from './jobs';
 export * from './webhooks';
+export * from './externalServices';
+export * from './identities';
 export * from './observation';
 export * from './sinks';
 export * from './schemas';
@@ -64,6 +68,8 @@ export {
     projections,
     jobs,
     webhooks,
+    externalServices,
+    identities,
     observation,
     sinks,
     schemas,

package/observation/FailedPartition.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FailedPartitionAttempt } from './FailedPartitionAttempt';
+
+/**
+ * Represents a partition that has failed for an observer (Reactor, Reducer, ++).
+ */
+export interface FailedPartition {
+    /** The unique identifier of the failed partition registration. */
+    readonly id: string;
+
+    /** The identifier of the observer (Reactor, Reducer) the partition failed for. */
+    readonly observerId: string;
+
+    /** The partition that has failed. */
+    readonly partition: string;
+
+    /** The collection of attempts made at processing the partition. */
+    readonly attempts: ReadonlyArray<FailedPartitionAttempt>;
+}

package/observation/FailedPartitionAttempt.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber';
+
+/**
+ * Represents a single failed attempt at processing a partition.
+ */
+export interface FailedPartitionAttempt {
+    /** When the attempt occurred. */
+    readonly occurred: Date;
+
+    /** The event sequence number the attempt occurred at. */
+    readonly sequenceNumber: EventSequenceNumber;
+
+    /** The messages associated with the failure. */
+    readonly messages: ReadonlyArray<string>;
+
+    /** The associated stack trace, if any. */
+    readonly stackTrace: string;
+}

package/observation/FailedPartitions.spec.ts

@@ -0,0 +1,75 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it, vi } from 'vitest';
+import type { ChronicleConnection } from '../connection';
+import { FailedPartitions } from './FailedPartitions';
+
+function wireFailedPartition() {
+    return {
+        Id: { lo: 1n, hi: 0n },
+        ObserverId: 'some-observer',
+        Partition: 'some-partition',
+        Attempts: [
+            {
+                Occurred: { Value: '2024-01-15T12:30:00.0000000+00:00' },
+                SequenceNumber: 7n,
+                Messages: ['Something went wrong'],
+                StackTrace: 'at Foo.Bar()'
+            }
+        ]
+    };
+}
+
+function createFailedPartitions(getFailedPartitionsResult?: unknown) {
+    const getFailedPartitions = vi.fn().mockResolvedValue(getFailedPartitionsResult ?? { items: [] });
+    const connection = { failedPartitions: { getFailedPartitions } } as unknown as ChronicleConnection;
+    const failedPartitions = new FailedPartitions('my-event-store', 'my-namespace', connection);
+    return { failedPartitions, getFailedPartitions };
+}
+
+describe('FailedPartitions', () => {
+    describe('when getting all failed partitions', () => {
+        const { failedPartitions, getFailedPartitions } = createFailedPartitions({ items: [wireFailedPartition()] });
+
+        it('should call the RPC with an empty observer id and map the response', async () => {
+            const result = await failedPartitions.getAllFailedPartitions();
+
+            expect(getFailedPartitions).toHaveBeenCalledTimes(1);
+            const request = getFailedPartitions.mock.calls[0][0];
+            expect(request.EventStore).toEqual('my-event-store');
+            expect(request.Namespace).toEqual('my-namespace');
+            expect(request.ObserverId).toEqual('');
+
+            expect(result).toHaveLength(1);
+            expect(result[0].observerId).toEqual('some-observer');
+            expect(result[0].partition).toEqual('some-partition');
+            expect(result[0].attempts).toHaveLength(1);
+            expect(result[0].attempts[0].sequenceNumber.value).toEqual(7n);
+            expect(result[0].attempts[0].messages).toEqual(['Something went wrong']);
+            expect(result[0].attempts[0].stackTrace).toEqual('at Foo.Bar()');
+        });
+    });
+
+    describe('when getting failed partitions for a specific observer', () => {
+        const { failedPartitions, getFailedPartitions } = createFailedPartitions({ items: [wireFailedPartition()] });
+
+        it('should call the RPC with the given observer id', async () => {
+            await failedPartitions.getFailedPartitionsFor('some-observer');
+
+            expect(getFailedPartitions).toHaveBeenCalledTimes(1);
+            const request = getFailedPartitions.mock.calls[0][0];
+            expect(request.ObserverId).toEqual('some-observer');
+        });
+    });
+
+    describe('when there are no failed partitions', () => {
+        const { failedPartitions } = createFailedPartitions({ items: [] });
+
+        it('should return an empty array', async () => {
+            const result = await failedPartitions.getAllFailedPartitions();
+
+            expect(result).toEqual([]);
+        });
+    });
+});

package/observation/FailedPartitions.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ChronicleConnection } from '../connection';
+import { FailedPartition } from './FailedPartition';
+import { IFailedPartitions } from './IFailedPartitions';
+import { toClientFailedPartition } from './toClientFailedPartition';
+
+/**
+ * Implements {@link IFailedPartitions} by proxying to the Chronicle Kernel over the client connection.
+ */
+export class FailedPartitions implements IFailedPartitions {
+    /**
+     * Creates a new {@link FailedPartitions} instance.
+     * @param _eventStore - Event store name.
+     * @param _namespace - Event store namespace.
+     * @param _connection - Chronicle connection.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _namespace: string,
+        private readonly _connection: ChronicleConnection
+    ) {}
+
+    /** @inheritdoc */
+    async getAllFailedPartitions(): Promise<FailedPartition[]> {
+        return this.getFailedPartitions('');
+    }
+
+    /** @inheritdoc */
+    async getFailedPartitionsFor(observerId: string): Promise<FailedPartition[]> {
+        return this.getFailedPartitions(observerId);
+    }
+
+    private async getFailedPartitions(observerId: string): Promise<FailedPartition[]> {
+        const response = await this._connection.failedPartitions.getFailedPartitions({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            ObserverId: observerId
+        });
+
+        return (response.items ?? []).map(failedPartition => toClientFailedPartition(failedPartition));
+    }
+}

package/observation/ICanBeNotifiedWhenPartitionReplayed.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines an optional contract a `@reactor`/`@reducer`-decorated class instance can implement to
+ * receive notifications when replay of a specific partition begins and ends.
+ */
+export interface ICanBeNotifiedWhenPartitionReplayed {
+    /**
+     * Called when replay of a partition begins.
+     * @param partition - The partition being replayed.
+     * @returns A promise that resolves when the callback has completed.
+     */
+    beginReplayPartition(partition: string): Promise<void>;
+
+    /**
+     * Called when replay of a partition ends.
+     * @param partition - The partition that was replayed.
+     * @returns A promise that resolves when the callback has completed.
+     */
+    endReplayPartition(partition: string): Promise<void>;
+}

package/observation/ICanBeNotifiedWhenReplay.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines an optional contract a `@reactor`/`@reducer`-decorated class instance can implement to
+ * receive notifications when a full replay of its observation begins and ends.
+ */
+export interface ICanBeNotifiedWhenReplay {
+    /**
+     * Called when a replay begins.
+     * @returns A promise that resolves when the callback has completed.
+     */
+    beginReplay(): Promise<void>;
+
+    /**
+     * Called when a replay ends.
+     * @returns A promise that resolves when the callback has completed.
+     */
+    endReplay(): Promise<void>;
+}

package/observation/IFailedPartitions.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FailedPartition } from './FailedPartition';
+
+/**
+ * Defines a system that can work with failed partitions.
+ */
+export interface IFailedPartitions {
+    /**
+     * Gets any failed partitions for any observer (Reactor, Reducer, ++).
+     * @returns A collection of {@link FailedPartition}.
+     */
+    getAllFailedPartitions(): Promise<FailedPartition[]>;
+
+    /**
+     * Gets any failed partitions for a specific observer (Reactor, Reducer, ++).
+     * @param observerId - The identifier of the observer to get for.
+     * @returns A collection of {@link FailedPartition}.
+     */
+    getFailedPartitionsFor(observerId: string): Promise<FailedPartition[]>;
+}

package/observation/index.ts

@@ -3,3 +3,9 @@
 
 export { ObserverId } from './ObserverId';
 export { ObserverRunningState } from './ObserverRunningState';
+export type { FailedPartition } from './FailedPartition';
+export type { FailedPartitionAttempt } from './FailedPartitionAttempt';
+export type { IFailedPartitions } from './IFailedPartitions';
+export { FailedPartitions } from './FailedPartitions';
+export type { ICanBeNotifiedWhenReplay } from './ICanBeNotifiedWhenReplay';
+export type { ICanBeNotifiedWhenPartitionReplayed } from './ICanBeNotifiedWhenPartitionReplayed';

package/observation/notifyReplayLifecycle.spec.ts

@@ -0,0 +1,98 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it, vi } from 'vitest';
+import { ReplayState } from '@cratis/chronicle.contracts';
+import { notifyReplayLifecycle } from './notifyReplayLifecycle';
+
+describe('notifyReplayLifecycle', () => {
+    describe('when the replay state is None', () => {
+        it('should not call any hook even when the instance implements both contracts', async () => {
+            const beginReplay = vi.fn();
+            const endReplay = vi.fn();
+            const beginReplayPartition = vi.fn();
+            const endReplayPartition = vi.fn();
+
+            await notifyReplayLifecycle(
+                { beginReplay, endReplay, beginReplayPartition, endReplayPartition },
+                ReplayState.REPLAY_STATE_None,
+                'some-partition');
+
+            expect(beginReplay).not.toHaveBeenCalled();
+            expect(endReplay).not.toHaveBeenCalled();
+            expect(beginReplayPartition).not.toHaveBeenCalled();
+            expect(endReplayPartition).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when the replay state is BeginReplay and the instance implements ICanBeNotifiedWhenReplay', () => {
+        it('should call beginReplay', async () => {
+            const beginReplay = vi.fn();
+            const endReplay = vi.fn();
+
+            await notifyReplayLifecycle({ beginReplay, endReplay }, ReplayState.BeginReplay, '');
+
+            expect(beginReplay).toHaveBeenCalledTimes(1);
+            expect(endReplay).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when the replay state is EndReplay and the instance implements ICanBeNotifiedWhenReplay', () => {
+        it('should call endReplay', async () => {
+            const beginReplay = vi.fn();
+            const endReplay = vi.fn();
+
+            await notifyReplayLifecycle({ beginReplay, endReplay }, ReplayState.EndReplay, '');
+
+            expect(endReplay).toHaveBeenCalledTimes(1);
+            expect(beginReplay).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when the replay state is BeginReplayPartition and the instance implements ICanBeNotifiedWhenPartitionReplayed', () => {
+        it('should call beginReplayPartition with the partition', async () => {
+            const beginReplayPartition = vi.fn();
+            const endReplayPartition = vi.fn();
+
+            await notifyReplayLifecycle({ beginReplayPartition, endReplayPartition }, ReplayState.BeginReplayPartition, 'partition-1');
+
+            expect(beginReplayPartition).toHaveBeenCalledWith('partition-1');
+            expect(endReplayPartition).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when the replay state is EndReplayPartition and the instance implements ICanBeNotifiedWhenPartitionReplayed', () => {
+        it('should call endReplayPartition with the partition', async () => {
+            const beginReplayPartition = vi.fn();
+            const endReplayPartition = vi.fn();
+
+            await notifyReplayLifecycle({ beginReplayPartition, endReplayPartition }, ReplayState.EndReplayPartition, 'partition-1');
+
+            expect(endReplayPartition).toHaveBeenCalledWith('partition-1');
+            expect(beginReplayPartition).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when the instance does not implement either contract', () => {
+        it('should not throw for any replay state', async () => {
+            const instance = {};
+
+            await expect(notifyReplayLifecycle(instance, ReplayState.BeginReplay, '')).resolves.toBeUndefined();
+            await expect(notifyReplayLifecycle(instance, ReplayState.EndReplay, '')).resolves.toBeUndefined();
+            await expect(notifyReplayLifecycle(instance, ReplayState.BeginReplayPartition, 'p')).resolves.toBeUndefined();
+            await expect(notifyReplayLifecycle(instance, ReplayState.EndReplayPartition, 'p')).resolves.toBeUndefined();
+        });
+    });
+
+    describe('when the instance only implements ICanBeNotifiedWhenReplay but the state is partition-scoped', () => {
+        it('should not call anything', async () => {
+            const beginReplay = vi.fn();
+            const endReplay = vi.fn();
+
+            await notifyReplayLifecycle({ beginReplay, endReplay }, ReplayState.BeginReplayPartition, 'partition-1');
+
+            expect(beginReplay).not.toHaveBeenCalled();
+            expect(endReplay).not.toHaveBeenCalled();
+        });
+    });
+});

package/observation/notifyReplayLifecycle.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReplayState } from '@cratis/chronicle.contracts';
+import { ICanBeNotifiedWhenPartitionReplayed } from './ICanBeNotifiedWhenPartitionReplayed';
+import { ICanBeNotifiedWhenReplay } from './ICanBeNotifiedWhenReplay';
+
+function hasReplayLifecycleHooks(instance: unknown): instance is ICanBeNotifiedWhenReplay {
+    if (typeof instance !== 'object' || instance === null) {
+        return false;
+    }
+
+    const candidate = instance as Record<string, unknown>;
+    return typeof candidate.beginReplay === 'function' && typeof candidate.endReplay === 'function';
+}
+
+function hasPartitionReplayLifecycleHooks(instance: unknown): instance is ICanBeNotifiedWhenPartitionReplayed {
+    if (typeof instance !== 'object' || instance === null) {
+        return false;
+    }
+
+    const candidate = instance as Record<string, unknown>;
+    return typeof candidate.beginReplayPartition === 'function' && typeof candidate.endReplayPartition === 'function';
+}
+
+/**
+ * Notifies a reactor/reducer instance of a replay-state transition signaled by the Chronicle Kernel,
+ * when the instance optionally implements {@link ICanBeNotifiedWhenReplay} and/or
+ * {@link ICanBeNotifiedWhenPartitionReplayed}. A no-op for {@link ReplayState.REPLAY_STATE_None} or
+ * when the instance implements neither contract.
+ * @param instance - The reactor/reducer instance to notify.
+ * @param replayState - The replay-state transition signaled for the current batch.
+ * @param partition - The partition the transition applies to, for the partition-scoped states.
+ * @returns A promise that resolves when the relevant callback (if any) has completed.
+ */
+export async function notifyReplayLifecycle(instance: unknown, replayState: ReplayState, partition: string): Promise<void> {
+    switch (replayState) {
+        case ReplayState.BeginReplay:
+            if (hasReplayLifecycleHooks(instance)) {
+                await instance.beginReplay();
+            }
+            break;
+        case ReplayState.EndReplay:
+            if (hasReplayLifecycleHooks(instance)) {
+                await instance.endReplay();
+            }
+            break;
+        case ReplayState.BeginReplayPartition:
+            if (hasPartitionReplayLifecycleHooks(instance)) {
+                await instance.beginReplayPartition(partition);
+            }
+            break;
+        case ReplayState.EndReplayPartition:
+            if (hasPartitionReplayLifecycleHooks(instance)) {
+                await instance.endReplayPartition(partition);
+            }
+            break;
+        default:
+            break;
+    }
+}

package/observation/toClientFailedPartition.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { FailedPartition as ContractsFailedPartition } from '@cratis/chronicle.contracts';
+import { fromContractsGuid } from '../connection/Guid';
+import { EventSequenceNumber } from '../eventSequences/EventSequenceNumber';
+import { FailedPartition } from './FailedPartition';
+
+/**
+ * Converts a wire {@link ContractsFailedPartition} into the client {@link FailedPartition} shape.
+ * @param failedPartition - The wire failed partition to convert.
+ * @returns The converted client failed partition.
+ */
+export function toClientFailedPartition(failedPartition: ContractsFailedPartition): FailedPartition {
+    return {
+        id: fromContractsGuid(failedPartition.Id).toString(),
+        observerId: failedPartition.ObserverId,
+        partition: failedPartition.Partition,
+        attempts: (failedPartition.Attempts ?? []).map(attempt => ({
+            occurred: new Date(attempt.Occurred?.Value ?? ''),
+            sequenceNumber: new EventSequenceNumber(attempt.SequenceNumber ?? 0n),
+            messages: attempt.Messages ?? [],
+            stackTrace: attempt.StackTrace ?? ''
+        }))
+    };
+}