@cratis/chronicle 0.1.0 → 0.2.0

package/dist/webhooks/Webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Webhooks.js","sourceRoot":"","sources":["../../webhooks/Webhooks.ts"],"names":[],"mappings":"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"}

package/dist/webhooks/index.d.ts

@@ -0,0 +1,10 @@
+export { WebhookId } from './WebhookId';
+export { WebhookTargetUrl } from './WebhookTargetUrl';
+export { webhook, getWebhookMetadata, isWebhook } from './webhook';
+export type { WebhookMetadata } from './webhook';
+export type { IWebhook } from './IWebhook';
+export type { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
+export type { IWebhooks } from './IWebhooks';
+export { WebhookDefinitionBuilder } from './WebhookDefinitionBuilder';
+export { Webhooks } from './Webhooks';
+//# sourceMappingURL=index.d.ts.map

package/dist/webhooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../webhooks/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAC7E,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/webhooks/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+export { WebhookId } from './WebhookId';
+export { WebhookTargetUrl } from './WebhookTargetUrl';
+export { webhook, getWebhookMetadata, isWebhook } from './webhook';
+export { WebhookDefinitionBuilder } from './WebhookDefinitionBuilder';
+export { Webhooks } from './Webhooks';
+//# sourceMappingURL=index.js.map

package/dist/webhooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../webhooks/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAKnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/webhooks/webhook.d.ts

@@ -0,0 +1,41 @@
+import 'reflect-metadata';
+import { WebhookId } from './WebhookId';
+import { WebhookTargetUrl } from './WebhookTargetUrl';
+/**
+ * Metadata stored on a webhook class.
+ */
+export interface WebhookMetadata {
+    /** The webhook identifier. */
+    readonly id: WebhookId;
+    /** The webhook target URL. */
+    readonly targetUrl: WebhookTargetUrl;
+    /** Optional explicit event sequence id. */
+    readonly eventSequenceId: string | undefined;
+}
+/**
+ * TypeScript decorator that marks a class as a discoverable webhook.
+ * Overloads:
+ * - `@webhook(targetUrl)` -> class name is used as identifier.
+ * - `@webhook(id, targetUrl)` -> explicit identifier.
+ * - `@webhook(id, targetUrl, eventSequenceId)` -> explicit identifier and event sequence.
+ * @param idOrTargetUrl - The webhook identifier or target URL.
+ * @param targetUrlOrUndefined - The webhook target URL when id is provided.
+ * @param eventSequenceId - Optional event sequence identifier.
+ * @returns A class decorator.
+ */
+export declare function webhook(targetUrl: string): ClassDecorator;
+export declare function webhook(id: string, targetUrl: string): ClassDecorator;
+export declare function webhook(id: string, targetUrl: string, eventSequenceId: string): ClassDecorator;
+/**
+ * Gets webhook metadata from a webhook class.
+ * @param target - The class constructor.
+ * @returns The metadata, if any.
+ */
+export declare function getWebhookMetadata(target: Function): WebhookMetadata | undefined;
+/**
+ * Checks whether a class has webhook metadata.
+ * @param target - The class constructor.
+ * @returns True when decorated as webhook.
+ */
+export declare function isWebhook(target: Function): boolean;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhooks/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../webhooks/webhook.ts"],"names":[],"mappings":"AAGA,OAAO,kBAAkB,CAAC;AAG1B,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAKtD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IAEvB,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IAErC,2CAA2C;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC;AAC3D,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC;AACvE,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,cAAc,CAAC;AA2BhG;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAEnD"}

package/dist/webhooks/webhook.js

@@ -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 'reflect-metadata';
+import { DecoratorType, TypeDiscoverer } from '../types';
+import { WebhookId } from './WebhookId';
+import { WebhookTargetUrl } from './WebhookTargetUrl';
+/** Metadata key used to store webhook information on a class. */
+const WEBHOOK_METADATA_KEY = 'chronicle:webhook';
+export function webhook(idOrTargetUrl, targetUrlOrUndefined, eventSequenceId) {
+    return (target) => {
+        const hasExplicitId = targetUrlOrUndefined !== undefined;
+        const explicitId = hasExplicitId ? idOrTargetUrl : undefined;
+        const resolvedTargetUrl = hasExplicitId ? targetUrlOrUndefined : idOrTargetUrl;
+        if (!resolvedTargetUrl) {
+            throw new Error('A webhook targetUrl must be a non-empty string for @webhook.');
+        }
+        const constructor = target;
+        const webhookId = new WebhookId(explicitId ?? constructor.name);
+        const metadata = {
+            id: webhookId,
+            targetUrl: new WebhookTargetUrl(resolvedTargetUrl),
+            eventSequenceId
+        };
+        Reflect.defineMetadata(WEBHOOK_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(DecoratorType.Webhook, constructor, webhookId.value);
+    };
+}
+/**
+ * Gets webhook metadata from a webhook class.
+ * @param target - The class constructor.
+ * @returns The metadata, if any.
+ */
+export function getWebhookMetadata(target) {
+    return Reflect.getMetadata(WEBHOOK_METADATA_KEY, target);
+}
+/**
+ * Checks whether a class has webhook metadata.
+ * @param target - The class constructor.
+ * @returns True when decorated as webhook.
+ */
+export function isWebhook(target) {
+    return Reflect.hasMetadata(WEBHOOK_METADATA_KEY, target);
+}
+//# sourceMappingURL=webhook.js.map

package/dist/webhooks/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../webhooks/webhook.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qGAAqG;AAErG,OAAO,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,iEAAiE;AACjE,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AA8BjD,MAAM,UAAU,OAAO,CAAC,aAAqB,EAAE,oBAA6B,EAAE,eAAwB;IAClG,OAAO,CAAC,MAAc,EAAE,EAAE;QACtB,MAAM,aAAa,GAAG,oBAAoB,KAAK,SAAS,CAAC;QACzD,MAAM,UAAU,GAAG,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,MAAM,iBAAiB,GAAG,aAAa,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,aAAa,CAAC;QAE/E,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QACpF,CAAC;QAED,MAAM,WAAW,GAAG,MAAkB,CAAC;QACvC,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,UAAU,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,QAAQ,GAAoB;YAC9B,EAAE,EAAE,SAAS;YACb,SAAS,EAAE,IAAI,gBAAgB,CAAC,iBAAiB,CAAC;YAClD,eAAe;SAClB,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,oBAAoB,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC/D,cAAc,CAAC,OAAO,CAAC,QAAQ,CAC3B,aAAa,CAAC,OAAO,EACrB,WAA0B,EAC1B,SAAS,CAAC,KAAK,CAClB,CAAC;IACN,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAgB;IAC/C,OAAO,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAgB;IACtC,OAAO,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;AAC7D,CAAC"}

package/eventSequences/AppendOptions.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 { Guid } from '@cratis/fundamentals';
+import type { ConcurrencyScope } from './ConcurrencyScope';
+
+/**
+ * Options for appending an event to an event sequence.
+ */
+export interface AppendOptions {
+    /** Optional correlation identifier for tracking the append operation. */
+    correlationId?: string | Guid;
+
+    /** Optional explicit sequence number to use for the event. */
+    eventSourceId?: string;
+
+    /** Optional concurrency scope to use for append operations. */
+    concurrencyScope?: ConcurrencyScope;
+}

package/eventSequences/ConcurrencyScope.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { EventType } from '../events';
+
+/**
+ * Represents a concurrency scope for append operations.
+ */
+export interface ConcurrencyScope {
+    /** The expected sequence number used for concurrency validation. */
+    sequenceNumber: bigint;
+
+    /** Whether to include event source identifier as part of the scope. */
+    eventSourceId?: boolean;
+
+    /** Optional event stream type to scope to. */
+    eventStreamType?: string;
+
+    /** Optional event stream identifier to scope to. */
+    eventStreamId?: string;
+
+    /** Optional event source type to scope to. */
+    eventSourceType?: string;
+
+    /** Optional event types to scope to. */
+    eventTypes?: EventType[];
+}

package/eventSequences/EventForEventSourceId.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents an event paired with the event source identifier it belongs to.
+ */
+export interface EventForEventSourceId {
+    /** The event source identifier for the event. */
+    readonly eventSourceId: string;
+
+    /** The event payload to append. */
+    readonly event: object;
+}

package/eventSequences/EventLog.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.
+
+import { ChronicleConnection } from '../connection';
+import { EventSequence } from './EventSequence';
+import { EventSequenceId } from './EventSequenceId';
+import { IEventLog } from './IEventLog';
+import { IUnitOfWorkManager } from '../transactions/IUnitOfWorkManager';
+
+/**
+ * Implements {@link IEventLog} by extending the base {@link EventSequence}.
+ * The event log is the default event sequence used for all domain events.
+ */
+export class EventLog extends EventSequence implements IEventLog {
+    constructor(
+        eventStoreName: string,
+        namespace: string,
+        connection: ChronicleConnection,
+        unitOfWorkManager: IUnitOfWorkManager
+    ) {
+        super(EventSequenceId.eventLog, eventStoreName, namespace, connection, unitOfWorkManager);
+    }
+}

package/eventSequences/EventSequence.ts

@@ -0,0 +1,413 @@
+// 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 { SpanStatusCode } from '@opentelemetry/api';
+import { Guid } from '@cratis/fundamentals';
+import { getEventTypeFor } from '../events/eventTypeDecorator';
+import { AppendOptions } from './AppendOptions';
+import { AppendResult } from './AppendResult';
+import { ConstraintViolation } from './ConstraintViolation';
+import { EventForEventSourceId } from './EventForEventSourceId';
+import { IEventSequence } from './IEventSequence';
+import { ITransactionalEventSequence } from './ITransactionalEventSequence';
+import { EventSequenceId } from './EventSequenceId';
+import { EventSequenceNumber } from './EventSequenceNumber';
+import { TransactionalEventSequence } from './TransactionalEventSequence';
+import { ChronicleTracer } from '../Tracing';
+import { ChronicleMetrics } from '../Metrics';
+import { identityProvider, Identity } from '../identity';
+import { causationManager, CausationType } from '../auditing';
+import { correlationIdManager } from '../correlation';
+import { toContractsGuid } from '../connection/Guid';
+import type { ConcurrencyScope } from './ConcurrencyScope';
+import { IUnitOfWorkManager } from '../transactions/IUnitOfWorkManager';
+
+/**
+ * Implements {@link IEventSequence} by communicating with the Chronicle Kernel
+ * via gRPC using the {@link ChronicleConnection}.
+ */
+export class EventSequence implements IEventSequence {
+    readonly transactional: ITransactionalEventSequence;
+
+    constructor(
+        readonly id: EventSequenceId,
+        private readonly _eventStoreName: string,
+        private readonly _namespace: string,
+        private readonly _connection: ChronicleConnection,
+        private readonly _unitOfWorkManager: IUnitOfWorkManager
+    ) {
+        this.transactional = new TransactionalEventSequence(this, this._unitOfWorkManager);
+    }
+
+    /** @inheritdoc */
+    async append(eventSourceId: string, event: object, options?: AppendOptions): Promise<AppendResult> {
+        const eventType = getEventTypeFor(event.constructor as Function);
+        const correlationId = options?.correlationId === undefined
+            ? Guid.as(correlationIdManager.current.value)
+            : Guid.as(options.correlationId);
+        const content = JSON.stringify(event);
+
+        causationManager.add(CausationType.appendEvent, { eventType: eventType.id.value });
+        const causationChain = causationManager.getCurrentChain();
+        const identity = identityProvider.getCurrent();
+
+        const metricAttributes = {
+            'chronicle.event_store': this._eventStoreName,
+            'chronicle.namespace': this._namespace,
+            'chronicle.event_sequence_id': this.id.value,
+            'chronicle.event_type_id': eventType.id.value
+        };
+
+        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.append', async span => {
+            span.setAttribute('chronicle.event_store', this._eventStoreName);
+            span.setAttribute('chronicle.namespace', this._namespace);
+            span.setAttribute('chronicle.event_sequence_id', this.id.value);
+            span.setAttribute('chronicle.event_source_id', eventSourceId);
+            span.setAttribute('chronicle.event_type_id', eventType.id.value);
+            span.setAttribute('chronicle.event_type_generation', eventType.generation.value);
+            const startTime = Date.now();
+            try {
+                const response = await this._connection.eventSequences.append({
+                    EventStore: this._eventStoreName,
+                    Namespace: this._namespace,
+                    EventSequenceId: this.id.value,
+                    CorrelationId: toContractsGuid(correlationId),
+                    EventSourceType: 'Default',
+                    EventSourceId: eventSourceId,
+                    EventStreamType: 'Default',
+                    EventStreamId: eventSourceId,
+                    EventType: {
+                        Id: eventType.id.value,
+                        Generation: eventType.generation.value,
+                        Tombstone: eventType.tombstone
+                    },
+                    Content: content,
+                    Causation: causationChain.map(c => ({
+                        Occurred: { Value: c.occurred.toISOString() },
+                        Type: c.type.name,
+                        Properties: { ...c.properties }
+                    })),
+                    CausedBy: toContractsCausedBy(identity),
+                    ConcurrencyScope: this.toContractConcurrencyScope(options?.concurrencyScope),
+                    Tags: [],
+                    Occurred: undefined,
+                    Subject: eventSourceId
+                });
+
+                const duration = Date.now() - startTime;
+                const result = this.mapAppendResponse(
+                    response.SequenceNumber,
+                    response.ConstraintViolations ?? [],
+                    response.Errors ?? []
+                );
+                span.setAttribute('chronicle.sequence_number', result.sequenceNumber.value.toString());
+                span.setStatus({ code: SpanStatusCode.OK });
+
+                ChronicleMetrics.eventsAppended.add(1, metricAttributes);
+                ChronicleMetrics.appendDuration.record(duration, metricAttributes);
+                if (result.constraintViolations.length > 0) {
+                    ChronicleMetrics.constraintViolations.add(result.constraintViolations.length, {
+                        'chronicle.event_store': this._eventStoreName,
+                        'chronicle.namespace': this._namespace,
+                        'chronicle.event_sequence_id': this.id.value
+                    });
+                }
+                if (result.errors.length > 0) {
+                    ChronicleMetrics.appendErrors.add(result.errors.length, {
+                        'chronicle.event_store': this._eventStoreName,
+                        'chronicle.namespace': this._namespace,
+                        'chronicle.event_sequence_id': this.id.value
+                    });
+                }
+                return result;
+            } catch (error) {
+                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+                span.recordException(error as Error);
+                ChronicleMetrics.appendErrors.add(1, {
+                    'chronicle.event_store': this._eventStoreName,
+                    'chronicle.namespace': this._namespace,
+                    'chronicle.event_sequence_id': this.id.value
+                });
+                throw error;
+            } finally {
+                span.end();
+            }
+        });
+    }
+
+    /** @inheritdoc */
+    async appendMany(eventSourceId: string, events: object[], options?: AppendOptions): Promise<AppendResult[]>;
+    async appendMany(events: EventForEventSourceId[], options?: AppendOptions): Promise<AppendResult[]>;
+    async appendMany(
+        eventSourceIdOrEvents: string | EventForEventSourceId[],
+        eventsOrOptions?: object[] | AppendOptions,
+        options?: AppendOptions
+    ): Promise<AppendResult[]> {
+        if (typeof eventSourceIdOrEvents !== 'string' && !Array.isArray(eventSourceIdOrEvents)) {
+            throw new Error('Invalid arguments: first parameter must be an eventSourceId string or an array of { eventSourceId, event }.');
+        }
+        if (typeof eventSourceIdOrEvents === 'string' && !Array.isArray(eventsOrOptions)) {
+            throw new Error('Invalid arguments: use appendMany(eventSourceId, events, options?) where the second parameter is an array of events.');
+        }
+        if (typeof eventSourceIdOrEvents !== 'string' && Array.isArray(eventsOrOptions)) {
+            throw new Error('Invalid arguments: use appendMany(eventsForEventSourceId, options?) where the second parameter is append options.');
+        }
+
+        let eventsForEventSourceIds: EventForEventSourceId[];
+        if (typeof eventSourceIdOrEvents === 'string') {
+            const eventsArray = eventsOrOptions as object[];
+            eventsForEventSourceIds = eventsArray.map((event: object) => ({
+                eventSourceId: eventSourceIdOrEvents,
+                event
+            }));
+        } else {
+            eventsForEventSourceIds = eventSourceIdOrEvents;
+        }
+        const appendOptions = typeof eventSourceIdOrEvents === 'string'
+            ? options
+            : eventsOrOptions as AppendOptions | undefined;
+
+        const correlationId = appendOptions?.correlationId === undefined
+            ? Guid.as(correlationIdManager.current.value)
+            : Guid.as(appendOptions.correlationId);
+
+        causationManager.add(CausationType.appendManyEvents, { count: String(eventsForEventSourceIds.length) });
+        const batchCausationChain = causationManager.getCurrentChain();
+        const identity = identityProvider.getCurrent();
+        const concurrencyScope = this.toContractConcurrencyScope(appendOptions?.concurrencyScope);
+
+        const eventsToAppend = eventsForEventSourceIds.map(({ eventSourceId, event }) => {
+            const eventType = getEventTypeFor(event.constructor as Function);
+            return {
+                EventSourceType: 'Default',
+                EventSourceId: eventSourceId,
+                EventStreamType: 'Default',
+                EventStreamId: eventSourceId,
+                EventType: {
+                    Id: eventType.id.value,
+                    Generation: eventType.generation.value,
+                    Tombstone: eventType.tombstone
+                },
+                Content: JSON.stringify(event),
+                Causation: batchCausationChain.map(c => ({
+                    Occurred: { Value: c.occurred.toISOString() },
+                    Type: c.type.name,
+                    Properties: { ...c.properties }
+                })),
+                CausedBy: toContractsCausedBy(identity),
+                ConcurrencyScope: concurrencyScope,
+                Tags: [],
+                Occurred: undefined,
+                Subject: eventSourceId
+            };
+        });
+
+        const distinctEventSourceIds = [...new Set(eventsForEventSourceIds.map(_ => _.eventSourceId))];
+
+        const batchMetricAttributes = {
+            'chronicle.event_store': this._eventStoreName,
+            'chronicle.namespace': this._namespace,
+            'chronicle.event_sequence_id': this.id.value,
+            'chronicle.events_count': eventsForEventSourceIds.length
+        };
+
+        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.append_many', async span => {
+            span.setAttribute('chronicle.event_store', this._eventStoreName);
+            span.setAttribute('chronicle.namespace', this._namespace);
+            span.setAttribute('chronicle.event_sequence_id', this.id.value);
+            if (distinctEventSourceIds.length === 1) {
+                span.setAttribute('chronicle.event_source_id', distinctEventSourceIds[0]);
+            }
+            span.setAttribute('chronicle.events_count', eventsForEventSourceIds.length);
+            const startTime = Date.now();
+            try {
+                const response = await this._connection.eventSequences.appendMany({
+                    EventStore: this._eventStoreName,
+                    Namespace: this._namespace,
+                    EventSequenceId: this.id.value,
+                    CorrelationId: toContractsGuid(correlationId),
+                    Events: eventsToAppend,
+                    Causation: batchCausationChain.map(c => ({
+                        Occurred: { Value: c.occurred.toISOString() },
+                        Type: c.type.name,
+                        Properties: { ...c.properties }
+                    })),
+                    CausedBy: toContractsCausedBy(identity),
+                    ConcurrencyScopes: {
+                        ...Object.fromEntries(distinctEventSourceIds.map(eventSourceId => [eventSourceId, concurrencyScope]))
+                    }
+                });
+
+                const duration = Date.now() - startTime;
+                const result = (response.SequenceNumbers ?? []).map((sequenceNumber: bigint, index: number) =>
+                    this.mapAppendResponse(
+                        sequenceNumber,
+                        response.ConstraintViolations ?? [],
+                        (response.Errors ?? []).filter((_: string, errorIndex: number) => errorIndex === index)
+                    )
+                );
+                span.setStatus({ code: SpanStatusCode.OK });
+
+                ChronicleMetrics.batchAppendsPerformed.add(1, batchMetricAttributes);
+                ChronicleMetrics.eventsAppended.add(eventsForEventSourceIds.length, batchMetricAttributes);
+                ChronicleMetrics.appendManyDuration.record(duration, batchMetricAttributes);
+
+                const totalViolations = result.reduce((sum: number, appendResult: AppendResult) => sum + appendResult.constraintViolations.length, 0);
+                if (totalViolations > 0) {
+                    ChronicleMetrics.constraintViolations.add(totalViolations, {
+                        'chronicle.event_store': this._eventStoreName,
+                        'chronicle.namespace': this._namespace,
+                        'chronicle.event_sequence_id': this.id.value
+                    });
+                }
+                const totalErrors = result.reduce((sum: number, appendResult: AppendResult) => sum + appendResult.errors.length, 0);
+                if (totalErrors > 0) {
+                    ChronicleMetrics.appendErrors.add(totalErrors, {
+                        'chronicle.event_store': this._eventStoreName,
+                        'chronicle.namespace': this._namespace,
+                        'chronicle.event_sequence_id': this.id.value
+                    });
+                }
+                return result;
+            } catch (error) {
+                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+                span.recordException(error as Error);
+                ChronicleMetrics.appendErrors.add(1, {
+                    'chronicle.event_store': this._eventStoreName,
+                    'chronicle.namespace': this._namespace,
+                    'chronicle.event_sequence_id': this.id.value
+                });
+                throw error;
+            } finally {
+                span.end();
+            }
+        });
+    }
+
+    /** @inheritdoc */
+    async getTailSequenceNumber(eventSourceId?: string): Promise<EventSequenceNumber> {
+        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.get_tail_sequence_number', async span => {
+            span.setAttribute('chronicle.event_store', this._eventStoreName);
+            span.setAttribute('chronicle.namespace', this._namespace);
+            span.setAttribute('chronicle.event_sequence_id', this.id.value);
+            if (eventSourceId !== undefined) {
+                span.setAttribute('chronicle.event_source_id', eventSourceId);
+            }
+            try {
+                const response = await this._connection.eventSequences.getTailSequenceNumber({
+                    EventStore: this._eventStoreName,
+                    Namespace: this._namespace,
+                    EventSequenceId: this.id.value,
+                    EventSourceId: eventSourceId ?? '',
+                    EventTypes: [],
+                    EventSourceType: 'Default',
+                    EventStreamId: '',
+                    EventStreamType: 'Default'
+                });
+
+                const result = new EventSequenceNumber(response.SequenceNumber ?? 0n);
+                span.setAttribute('chronicle.sequence_number', result.value.toString());
+                span.setStatus({ code: SpanStatusCode.OK });
+                return result;
+            } catch (error) {
+                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+                span.recordException(error as Error);
+                throw error;
+            } finally {
+                span.end();
+            }
+        });
+    }
+
+    /** @inheritdoc */
+    async hasEventsFor(eventSourceId: string): Promise<boolean> {
+        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.has_events_for', async span => {
+            span.setAttribute('chronicle.event_store', this._eventStoreName);
+            span.setAttribute('chronicle.namespace', this._namespace);
+            span.setAttribute('chronicle.event_sequence_id', this.id.value);
+            span.setAttribute('chronicle.event_source_id', eventSourceId);
+            try {
+                const response = await this._connection.eventSequences.hasEventsForEventSourceId({
+                    EventStore: this._eventStoreName,
+                    Namespace: this._namespace,
+                    EventSequenceId: this.id.value,
+                    EventSourceId: eventSourceId
+                });
+
+                const result = response.HasEvents ?? false;
+                span.setAttribute('chronicle.has_events', result);
+                span.setStatus({ code: SpanStatusCode.OK });
+                return result;
+            } catch (error) {
+                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+                span.recordException(error as Error);
+                throw error;
+            } finally {
+                span.end();
+            }
+        });
+    }
+
+    private mapAppendResponse(
+        sequenceNumber: bigint,
+        constraintViolations: Array<{ ConstraintId?: string; Message?: string; Details?: Record<string, string> }>,
+        errors: string[]
+    ): AppendResult {
+        const mappedViolations: ConstraintViolation[] = constraintViolations.map(violation => ({
+            constraintId: violation.ConstraintId ?? '',
+            message: violation.Message ?? '',
+            details: violation.Details ?? {}
+        }));
+
+        const mappedErrors = errors.map(message => ({ message }));
+
+        const safeSequenceNumber = sequenceNumber === 18446744073709551615n ? 0n : sequenceNumber;
+
+        return {
+            sequenceNumber: new EventSequenceNumber(safeSequenceNumber),
+            constraintViolations: mappedViolations,
+            errors: mappedErrors,
+            isSuccess: mappedViolations.length === 0 && mappedErrors.length === 0
+        };
+    }
+
+    private toContractConcurrencyScope(scope?: ConcurrencyScope) {
+        return {
+            SequenceNumber: scope?.sequenceNumber ?? EventSequenceNumber.unset.value,
+            EventSourceId: scope?.eventSourceId ?? false,
+            EventStreamType: scope?.eventStreamType ?? '',
+            EventStreamId: scope?.eventStreamId ?? '',
+            EventSourceType: scope?.eventSourceType ?? '',
+            EventTypes: (scope?.eventTypes ?? []).map(eventType => ({
+                Id: eventType.id.value,
+                Generation: eventType.generation.value,
+                Tombstone: eventType.tombstone
+            }))
+        };
+    }
+}
+
+/**
+ * Converts a RFC 4122 Guid string into the protobuf Guid shape used by Chronicle contracts.
+ * @param guid - The Guid to convert.
+ * @returns The converted protobuf Guid with fixed64-safe hi/lo values.
+ */
+
+/**
+ * Converts an {@link Identity} into the CausedBy shape used by Chronicle contracts.
+ * @param identity - The identity to convert.
+ * @returns The contracts CausedBy object.
+ */
+function toContractsCausedBy(identity: Identity): object {
+    const result: Record<string, unknown> = {
+        Subject: identity.subject,
+        Name: identity.name,
+        UserName: identity.userName,
+        OnBehalfOf: undefined
+    };
+    if (identity.onBehalfOf !== undefined) {
+        result.OnBehalfOf = toContractsCausedBy(identity.onBehalfOf);
+    }
+    return result;
+}