@cratis/chronicle 6.38.0 → 6.40.0

package/eventSequences/EventSequence.ts

@@ -80,7 +80,7 @@ export class EventSequence implements IEventSequence {
             'chronicle.event_type_id': eventType.id.value
         };
 
-        return observeOperation(names.spans.append, async span => {
+        return observeOperation('append', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             setTelemetryAttribute(span, 'eventTypeId', eventType.id.value);
@@ -183,7 +183,7 @@ export class EventSequence implements IEventSequence {
             'chronicle.events_count': eventsForEventSourceIds.length
         };
 
-        return observeOperation(names.spans.appendMany, async span => {
+        return observeOperation('appendMany', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             if (distinctEventSourceIds.length === 1) {
                 setEventSourceId(span, distinctEventSourceIds[0], this._telemetry);
@@ -299,7 +299,7 @@ export class EventSequence implements IEventSequence {
         eventStreamId?: string,
         filterEventTypes?: Constructor[]
     ): Promise<EventSequenceNumber> {
-        return observeOperation(names.spans.getTailSequenceNumber, async span => {
+        return observeOperation('getTailSequenceNumber', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             try {
@@ -339,7 +339,7 @@ export class EventSequence implements IEventSequence {
 
     /** @inheritdoc */
     async hasEventsFor(eventSourceId: string): Promise<boolean> {
-        return observeOperation(names.spans.hasEventsFor, async span => {
+        return observeOperation('hasEventsFor', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             try {
@@ -371,7 +371,7 @@ export class EventSequence implements IEventSequence {
         eventStreamId?: string,
         eventSourceType?: string
     ): Promise<AppendedEvent[]> {
-        return observeOperation(names.spans.getForEventSourceIdAndEventTypes, async span => {
+        return observeOperation('getForEventSourceIdAndEventTypes', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             try {
@@ -406,7 +406,7 @@ export class EventSequence implements IEventSequence {
         eventSourceId?: string,
         filterEventTypes?: Constructor[]
     ): Promise<AppendedEvent[]> {
-        return observeOperation(names.spans.getFromSequenceNumber, async span => {
+        return observeOperation('getFromSequenceNumber', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             setSequenceNumber(span, sequenceNumber.value);
             setEventSourceId(span, eventSourceId, this._telemetry);
@@ -438,7 +438,7 @@ export class EventSequence implements IEventSequence {
         const causationChain = causationManager.getCurrentChain();
         const identity = identityProvider.getCurrent();
 
-        return observeOperation(names.spans.redact, async span => {
+        return observeOperation('redact', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             setSequenceNumber(span, sequenceNumber.value);
             try {
@@ -472,7 +472,7 @@ export class EventSequence implements IEventSequence {
         const identity = identityProvider.getCurrent();
         const wireEventTypeIds = (eventTypes ?? []).map(constructor => getEventTypeFor(constructor as unknown as Function).id.value);
 
-        return observeOperation(names.spans.redactForEventSource, async span => {
+        return observeOperation('redactForEventSource', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             try {
@@ -518,7 +518,7 @@ export class EventSequence implements IEventSequence {
 
     /** @inheritdoc */
     async completeStream(eventStreamType: string, eventStreamId: string): Promise<CompleteStreamResult> {
-        return observeOperation(names.spans.completeStream, async span => {
+        return observeOperation('completeStream', this._telemetry, async span => {
             this.setSequenceAttributes(span);
             setTelemetryAttribute(span, 'eventStreamType', eventStreamType);
             setTelemetryAttribute(span, 'eventStreamId', eventStreamId);

package/events/migrations/for_EventTypeMigrators/against_a_kernel/when_replaying_an_older_generation.integration.spec.ts

@@ -102,6 +102,7 @@ describe.skipIf(!connectionString && !process.env.CI)('when replaying an older g
     const eventStoreName = `Migration${randomUUID().replaceAll('-', '').slice(0, 12)}`;
     const eventSourceId = randomUUID();
     let firstGenerationClient: ChronicleClient;
+    let migrationClient: ChronicleClient;
     let secondGenerationClient: ChronicleClient;
     let appendedSequenceNumber: bigint;
     let event: AppendedEvent;
@@ -113,11 +114,33 @@ describe.skipIf(!connectionString && !process.env.CI)('when replaying an older g
         // An application that only knows the first generation appends the event.
         firstGenerationClient = clientWith(artifactsWith({ eventTypes: [AuthorRegisteredV1] }));
         const firstGenerationStore = await firstGenerationClient.getEventStore(eventStoreName);
+        // Keep a backlog so replay can overtake the asynchronous migration if the readiness barrier is removed.
+        await firstGenerationStore.eventLog.appendMany(Array.from({ length: 500 }, () => ({
+            eventSourceId: randomUUID(),
+            event: Object.assign(new AuthorRegisteredV1(), { name: 'Earlier Author' })
+        })));
         const appended = await firstGenerationStore.eventLog.append(eventSourceId, Object.assign(new AuthorRegisteredV1(), { name: 'Jane Doe' }));
         appendedSequenceNumber = appended.sequenceNumber.value;
+        // The backlog is the regression setup; without it the race this spec guards against cannot occur.
+        if (appendedSequenceNumber < 500n) throw new Error(`Expected the 500-event backlog before the target event, but it was appended at ${appendedSequenceNumber}.`);
         firstGenerationClient.dispose();
 
-        // A later version registers the second generation with a migration, a projection and a reactor that replay the history.
+        // Registration starts a background migration job; it does not mean stored history has been migrated.
+        // Wait for the target's second-generation content before any observer can replay the old payload.
+        migrationClient = clientWith(artifactsWith({
+            eventTypes: [AuthorRegisteredV1, AuthorRegistered],
+            eventTypeMigrations: [AuthorRegisteredMigration]
+        }));
+        const migrationStore = await migrationClient.getEventStore(eventStoreName);
+        event = await eventually(
+            async () => (await migrationStore.eventLog.getForEventSourceIdAndEventTypes(eventSourceId, [AuthorRegistered]))[0],
+            _ => {
+                const content = _?.content as AuthorRegistered | undefined;
+                return content?.firstName === 'Jane' && content.lastName === 'Doe';
+            });
+        migrationClient.dispose();
+
+        // A later application replays the migrated history through a projection and a reactor.
         secondGenerationClient = clientWith(artifactsWith({
             eventTypes: [AuthorRegisteredV1, AuthorRegistered],
             eventTypeMigrations: [AuthorRegisteredMigration],
@@ -126,10 +149,7 @@ describe.skipIf(!connectionString && !process.env.CI)('when replaying an older g
         }));
         const store: IEventStore = await secondGenerationClient.getEventStore(eventStoreName);
 
-        event = await eventually(
-            async () => (await store.eventLog.getForEventSourceIdAndEventTypes(eventSourceId, [AuthorRegistered]))[0],
-            _ => (_?.content as AuthorRegistered | undefined)?.firstName === 'Jane');
-        author = await eventually(() => store.readModels.findInstanceById(Author, eventSourceId), _ => _ !== null && _.firstName !== '');
+        author = await eventually(() => store.readModels.findInstanceById(Author, eventSourceId), _ => _ !== null);
         observation = await eventually(async () => observed.find(_ => _.context.eventSourceId === eventSourceId)!, _ => _ !== undefined);
 
         // Registering a second generation without a migration from the first is rejected.
@@ -140,6 +160,7 @@ describe.skipIf(!connectionString && !process.env.CI)('when replaying an older g
 
     afterAll(() => {
         firstGenerationClient?.dispose();
+        migrationClient?.dispose();
         secondGenerationClient?.dispose();
     });
 
@@ -147,10 +168,10 @@ describe.skipIf(!connectionString && !process.env.CI)('when replaying an older g
     it('should read the last name split from the first generation', () => (event.content as AuthorRegistered).lastName.should.equal('Doe'));
     it('should keep the event source of the appended event', () => event.context.eventSourceId.should.equal(eventSourceId));
     it('should keep the sequence number of the appended event', () => event.context.sequenceNumber.should.equal(appendedSequenceNumber));
-    it('should project the migrated first name', () => author!.firstName.should.equal('Jane'));
-    it('should project the migrated last name', () => author!.lastName.should.equal('Doe'));
-    it('should replay the migrated first name to the reactor', () => observation.event.firstName.should.equal('Jane'));
-    it('should replay the migrated last name to the reactor', () => observation.event.lastName.should.equal('Doe'));
+    it('should project the migrated first name', () => author!.should.have.property('firstName', 'Jane'));
+    it('should project the migrated last name', () => author!.should.have.property('lastName', 'Doe'));
+    it('should replay the migrated first name to the reactor', () => observation.event.should.have.property('firstName', 'Jane'));
+    it('should replay the migrated last name to the reactor', () => observation.event.should.have.property('lastName', 'Doe'));
     it('should replay the event source to the reactor', () => observation.context.eventSourceId.should.equal(eventSourceId));
     it('should reject a second generation that has no migration', () => missingMigrationError.should.be.instanceOf(Error));
 });

package/for_ChronicleOptions/when_configuring_telemetry/with_span_names.spec.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 { chai, describe, it } from 'vitest';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import type { ChronicleTelemetryOptions } from '../../telemetry/ChronicleTelemetryOptions.js';
+
+chai.should();
+
+for (const spanNames of ['unknown', '', null, false, 0, {}, [], ['legacy']]) {
+    describe(`when configuring unsupported span names ${JSON.stringify(spanNames)}`, () => {
+        const telemetry = { spanNames } as unknown as ChronicleTelemetryOptions;
+        it('should reject the development options at construction', () => {
+            (() => ChronicleOptions.development({ telemetry })).should.throw(TypeError, 'telemetry.spanNames must be legacy or convention.');
+        });
+        it('should reject the connection string options at construction', () => {
+            (() => ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { telemetry })).should.throw(TypeError, 'telemetry.spanNames must be legacy or convention.');
+        });
+    });
+}
+
+for (const spanNames of [undefined, 'legacy', 'convention'] as const) {
+    describe(`when configuring supported span names ${spanNames ?? 'by default'}`, () => {
+        it('should preserve the choice with the event source identifier policy', () => {
+            const telemetry = { spanNames, eventSourceId: { mode: 'raw' as const } };
+            const development = ChronicleOptions.development({ telemetry });
+            const connection = ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { telemetry });
+            development.telemetry!.should.deep.equal(telemetry);
+            connection.telemetry!.should.deep.equal(telemetry);
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.38.0",
+    "version": "6.40.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,7 +173,7 @@
         "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/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",
+        "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/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",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {

package/telemetry/ChronicleTelemetryOptions.ts

@@ -1,8 +1,11 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-/** Per-client privacy settings; instrumentation itself is always available. */
+/** Per-client naming and privacy settings; instrumentation itself is always available. */
 export interface ChronicleTelemetryOptions {
+    /** Span naming convention. Defaults to legacy; both modes use the same scope and attribute families. */
+    spanNames?: 'legacy' | 'convention';
+
     /** Absent means no event source identifiers. HMAC uses SHA-256 and a deployment-owned key. */
     eventSourceId?: { mode: 'raw' } | { mode: 'hmac'; key: Uint8Array };
 }

package/telemetry/for_ChronicleTelemetry/given/a_client.fixture.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { vi } from 'vitest';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../../artifacts/IClientArtifactsProvider.js';
+import type { ChronicleTelemetryOptions } from '../../ChronicleTelemetryOptions.js';
+
+vi.mock('../../../connection/ChronicleConnection.js', () => ({
+    ChronicleConnection: class {
+        async resetChannel() {}
+        async connect() {}
+        disconnect() {}
+        server = { getVersionInfo: async () => ({}) };
+        eventStores = {
+            ensureEventStore: async () => ({}),
+            allEventStores: async () => ({ IsAuthorized: true, Data: [{ Name: 'store' }] })
+        };
+        namespaces = { allNamespaces: async () => ({ IsAuthorized: true, Data: [{ Name: 'namespace' }] }) };
+        readModels = { registerMany: async () => ({}) };
+        eventSequences = {
+            append: async () => ({ Response: { SequenceNumber: 42n } }),
+            appendManyForEventSources: async () => ({ Response: { SequenceNumbers: [42n, 43n] } }),
+            tailSequenceNumber: async () => ({ IsAuthorized: true, Data: { SequenceNumber: 42n } }),
+            hasEventsForEventSourceId: async (request: { EventSourceId: string }) => ({ IsAuthorized: true, Data: { HasEvents: request.EventSourceId !== 'empty' } }),
+            forEventSourceIdAndEventTypes: async () => ({ IsAuthorized: true, Data: [] }),
+            fromSequenceNumber: async () => ({ IsAuthorized: true, Data: [] }),
+            redact: async () => ({}),
+            redactForEventSource: async () => ({}),
+            completeStream: async () => ({ Response: { IsSuccess: true, SequenceNumber: 42n } })
+        };
+    }
+}));
+vi.mock('../../../connection/KernelKeepAlive.js', () => ({
+    KernelKeepAlive: class { async start() {} }
+}));
+
+export function client(telemetry?: ChronicleTelemetryOptions) {
+    const artifacts: IClientArtifactsProvider = {
+        eventTypes: [], readModels: [], reactors: [], reducers: [], seeders: [], constraints: [],
+        projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+    };
+    return new ChronicleClient(ChronicleOptions.development({
+        discoveryPatterns: [], clientArtifactsProvider: artifacts, telemetry
+    }));
+}

package/telemetry/for_ChronicleTelemetry/given/a_span_name_registry.fixture.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Literal compatibility contract, independent of the production name selection. */
+export const legacySpans = {
+    append: 'chronicle.event_sequences.append',
+    appendMany: 'chronicle.event_sequences.append_many',
+    getTailSequenceNumber: 'chronicle.event_sequences.get_tail_sequence_number',
+    hasEventsFor: 'chronicle.event_sequences.has_events_for',
+    getForEventSourceIdAndEventTypes: 'chronicle.event_sequences.get_for_event_source_id_and_event_types',
+    getFromSequenceNumber: 'chronicle.event_sequences.get_from_sequence_number',
+    redact: 'chronicle.event_sequences.redact',
+    redactForEventSource: 'chronicle.event_sequences.redact_for_event_source',
+    completeStream: 'chronicle.event_sequences.complete_stream',
+    getEventStore: 'chronicle.client.get_event_store',
+    getEventStores: 'chronicle.client.get_event_stores',
+    getNamespaces: 'chronicle.event_store.get_namespaces'
+};
+
+export const conventionSpans = {
+    append: 'cratis.chronicle.client.event_sequence.append',
+    appendMany: 'cratis.chronicle.client.event_sequence.append_many',
+    getTailSequenceNumber: 'cratis.chronicle.client.event_sequence.get_tail_sequence_number',
+    hasEventsFor: 'cratis.chronicle.client.event_sequence.has_events_for',
+    getForEventSourceIdAndEventTypes: 'cratis.chronicle.client.event_sequence.get_for_event_source_id_and_event_types',
+    getFromSequenceNumber: 'cratis.chronicle.client.event_sequence.get_from_sequence_number',
+    redact: 'cratis.chronicle.client.event_sequence.redact',
+    redactForEventSource: 'cratis.chronicle.client.event_sequence.redact_for_event_source',
+    completeStream: 'cratis.chronicle.client.event_sequence.complete_stream',
+    getEventStore: 'cratis.chronicle.client.event_store.get',
+    getEventStores: 'cratis.chronicle.client.event_store.list',
+    getNamespaces: 'cratis.chronicle.client.event_store.get_namespaces'
+};

package/telemetry/for_ChronicleTelemetry/when_exposing_names/with_legacy_compatibility.spec.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 { chai, describe, it } from 'vitest';
+import { WellKnownTelemetryNames as names } from '../../../WellKnownTelemetryNames.js';
+import { legacySpans, conventionSpans } from '../given/a_span_name_registry.fixture.js';
+
+chai.should();
+describe('when exposing names during the migration overlap', () => {
+    it('should preserve every legacy span constant', () => {
+        names.spans.should.deep.equal(legacySpans);
+    });
+    it('should expose a matching convention span for every operation', () => {
+        names.conventionSpans.should.deep.equal(conventionSpans);
+        Object.keys(names.conventionSpans).should.deep.equal(Object.keys(names.spans));
+    });
+    it('should preserve the current and historical scopes', () => {
+        names.scope.should.equal('Cratis.Chronicle.Client');
+        names.legacyScope.should.equal('@cratis/chronicle');
+    });
+    it('should preserve every legacy attribute constant', () => {
+        names.legacyAttributes.should.deep.equal({
+            eventStore: 'chronicle.event_store', namespace: 'chronicle.namespace',
+            eventSequenceId: 'chronicle.event_sequence_id', sequenceNumber: 'chronicle.sequence_number',
+            eventTypeId: 'chronicle.event_type_id', eventTypeGeneration: 'chronicle.event_type_generation',
+            eventSourceId: 'chronicle.event_source_id', eventCount: 'chronicle.events_count',
+            hasEvents: 'chronicle.has_events', eventStreamType: 'chronicle.event_stream_type', eventStreamId: 'chronicle.event_stream_id'
+        });
+    });
+    it('should preserve every legacy metric constant', () => {
+        names.legacyMetrics.should.deep.equal({
+            eventsAppended: 'chronicle.events.appended', batchAppendsPerformed: 'chronicle.events.batch_appends',
+            eventStoreRetrievals: 'chronicle.client.event_store_retrievals', appendDuration: 'chronicle.events.append_duration',
+            appendManyDuration: 'chronicle.events.append_many_duration', constraintViolations: 'chronicle.events.constraint_violations',
+            appendErrors: 'chronicle.events.append_errors'
+        });
+    });
+    it('should expose the product-only attributes alongside the shared registry', () => {
+        names.attributes.should.include({
+            hasEvents: 'cratis.chronicle.event_sequence.has_events',
+            eventStreamType: 'cratis.chronicle.event_stream.type', eventStreamId: 'cratis.chronicle.event_stream.id'
+        });
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_naming_spans/with_per_client_modes.spec.ts

@@ -0,0 +1,138 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import { SpanKind } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { ChronicleClient } from '../../../ChronicleClient.js';
+import type { IEventSequence } from '../../../eventSequences/IEventSequence.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { EventSequenceNumber } from '../../../eventSequences/EventSequenceNumber.js';
+import { clientVersion } from '../../../connection/clientVersion.js';
+import { client } from '../given/a_client.fixture.js';
+import { Recorded } from '../given/an_event_sequence.fixture.js';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { legacySpans, conventionSpans } from '../given/a_span_name_registry.fixture.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+const sequenceNumber = new EventSequenceNumber(42n);
+const operations = {
+    append: (sequence: IEventSequence) => sequence.append('source', new Recorded()),
+    appendMany: (sequence: IEventSequence) => sequence.appendMany('source', [new Recorded(), new Recorded()]),
+    getTailSequenceNumber: (sequence: IEventSequence) => sequence.getTailSequenceNumber(),
+    hasEventsFor: (sequence: IEventSequence) => sequence.hasEventsFor('source'),
+    getForEventSourceIdAndEventTypes: (sequence: IEventSequence) => sequence.getForEventSourceIdAndEventTypes('source', [Recorded]),
+    getFromSequenceNumber: (sequence: IEventSequence) => sequence.getFromSequenceNumber(sequenceNumber),
+    redact: (sequence: IEventSequence) => sequence.redact(sequenceNumber, 'reason'),
+    redactForEventSource: (sequence: IEventSequence) => sequence.redactForEventSource('source', 'reason'),
+    completeStream: (sequence: IEventSequence) => sequence.completeStream('stream-type', 'stream-id')
+};
+
+for (const spanNames of [undefined, 'legacy', 'convention'] as const) {
+    const expected = spanNames === 'convention' ? conventionSpans : legacySpans;
+    for (const sequenceId of [EventSequenceId.eventLog, new EventSequenceId('dynamic')]) {
+        for (const operation of Object.keys(operations) as (keyof typeof operations)[]) {
+            describe(`when naming ${operation} on ${sequenceId.value} with ${spanNames ?? 'default'} names`, () => {
+                let instance: ChronicleClient;
+                let span: ReadableSpan;
+                beforeEach(async () => {
+                    instance = client(spanNames === undefined ? undefined : { spanNames });
+                    const store = await instance.getEventStore('store', 'namespace');
+                    const sequence = sequenceId === EventSequenceId.eventLog ? store.eventLog : store.getEventSequence(sequenceId);
+                    telemetry.spans.reset();
+                    await operations[operation](sequence);
+                    span = telemetry.spans.getFinishedSpans()[0];
+                });
+                afterEach(() => instance.dispose());
+                it('should emit exactly one client span with the selected name', () => {
+                    telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
+                    span.name.should.equal(expected[operation]);
+                    span.kind.should.equal(SpanKind.CLIENT);
+                });
+                it('should retain the versioned shared instrumentation scope', () => {
+                    span.instrumentationScope.name.should.equal('Cratis.Chronicle.Client');
+                    should.equal(span.instrumentationScope.version, clientVersion);
+                });
+                it('should retain both attribute families', () => {
+                    span.attributes.should.include({
+                        'chronicle.event_store': 'store', 'cratis.event_store.name': 'store',
+                        'chronicle.namespace': 'namespace', 'cratis.event_store.namespace': 'namespace',
+                        'chronicle.event_sequence_id': sequenceId.value, 'cratis.event_sequence.id': sequenceId.value
+                    });
+                });
+            });
+        }
+    }
+
+    for (const operation of ['getEventStore', 'getEventStores', 'getNamespaces'] as const) {
+        describe(`when naming ${operation} with ${spanNames ?? 'default'} names`, () => {
+            let instance: ChronicleClient;
+            let span: ReadableSpan;
+            beforeEach(async () => {
+                instance = client(spanNames === undefined ? undefined : { spanNames });
+                if (operation === 'getNamespaces') {
+                    const store = await instance.getEventStore('store', 'namespace');
+                    telemetry.spans.reset();
+                    await store.getNamespaces();
+                } else if (operation === 'getEventStore') {
+                    await instance.getEventStore('store', 'namespace');
+                } else {
+                    await instance.getEventStores();
+                }
+                span = telemetry.spans.getFinishedSpans()[0];
+            });
+            afterEach(() => instance.dispose());
+            it('should emit exactly one client span with the selected name and shared scope', () => {
+                telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
+                span.name.should.equal(expected[operation]);
+                span.kind.should.equal(SpanKind.CLIENT);
+                span.instrumentationScope.name.should.equal('Cratis.Chronicle.Client');
+                should.equal(span.instrumentationScope.version, clientVersion);
+            });
+            if (operation !== 'getEventStores') {
+                it('should retain both event store attributes', () => {
+                    span.attributes.should.include({ 'chronicle.event_store': 'store', 'cratis.event_store.name': 'store' });
+                });
+            }
+        });
+    }
+}
+
+describe('when interleaving two clients with different span naming modes', () => {
+    let legacy: ChronicleClient;
+    let convention: ChronicleClient;
+    let spans: ReadableSpan[];
+    beforeEach(async () => {
+        legacy = client({ spanNames: 'legacy' });
+        convention = client({ spanNames: 'convention' });
+        const [legacyStore, conventionStore] = await Promise.all([
+            legacy.getEventStore('legacy-store'), convention.getEventStore('convention-store')
+        ]);
+        await Promise.all([convention.getEventStores(), legacy.getEventStores()]);
+        await Promise.all([legacyStore.getNamespaces(), conventionStore.getNamespaces()]);
+        await conventionStore.eventLog.append('source', new Recorded());
+        await legacyStore.eventLog.append('source', new Recorded());
+        const id = new EventSequenceId('dynamic');
+        await legacyStore.getEventSequence(id).append('source', new Recorded());
+        await conventionStore.getEventSequence(id).append('source', new Recorded());
+        await legacy.getEventStore('legacy-store');
+        await convention.getEventStore('convention-store');
+        spans = telemetry.spans.getFinishedSpans();
+    });
+    afterEach(() => { legacy.dispose(); convention.dispose(); });
+    it('should keep each client and its cached stores in its own mode', () => {
+        spans.should.have.lengthOf(12);
+        spans.filter(span => span.attributes['cratis.event_store.name'] === 'legacy-store').map(span => span.name).should.deep.equal([
+            legacySpans.getEventStore, legacySpans.getNamespaces, legacySpans.append, legacySpans.append, legacySpans.getEventStore
+        ]);
+        spans.filter(span => span.attributes['cratis.event_store.name'] === 'convention-store').map(span => span.name).should.deep.equal([
+            conventionSpans.getEventStore, conventionSpans.getNamespaces, conventionSpans.append, conventionSpans.append, conventionSpans.getEventStore
+        ]);
+        spans.map(span => span.name).should.include(legacySpans.getEventStores).and.include(conventionSpans.getEventStores);
+    });
+    it('should use the same tracer scope in both modes', () => {
+        new Set(spans.map(span => `${span.instrumentationScope.name}/${span.instrumentationScope.version}`)).should.deep.equal(
+            new Set([`Cratis.Chronicle.Client/${clientVersion}`]));
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_product_attributes/with_both_naming_modes.spec.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import type { Attributes } from '@opentelemetry/api';
+import type { ChronicleClient } from '../../../ChronicleClient.js';
+import { client } from '../given/a_client.fixture.js';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+
+chai.should();
+const telemetry = telemetrySession();
+
+for (const spanNames of ['legacy', 'convention'] as const) {
+    for (const hasEvents of [true, false]) {
+        describe(`when recording event presence ${hasEvents} with ${spanNames} span names`, () => {
+            let instance: ChronicleClient;
+            let attributes: Attributes;
+            beforeEach(async () => {
+                instance = client({ spanNames });
+                const store = await instance.getEventStore('store');
+                telemetry.spans.reset();
+                await store.eventLog.hasEventsFor(hasEvents ? 'source' : 'empty');
+                attributes = telemetry.spans.getFinishedSpans()[0].attributes;
+            });
+            afterEach(() => instance.dispose());
+            it('should record the boolean under both the legacy and product-only names', () => {
+                attributes.should.include({
+                    'chronicle.has_events': hasEvents,
+                    'cratis.chronicle.event_sequence.has_events': hasEvents
+                });
+            });
+        });
+    }
+    describe(`when completing a stream with ${spanNames} span names`, () => {
+        let instance: ChronicleClient;
+        let attributes: Attributes;
+        beforeEach(async () => {
+            instance = client({ spanNames });
+            const store = await instance.getEventStore('store');
+            telemetry.spans.reset();
+            await store.eventLog.completeStream('orders', 'stream-1');
+            attributes = telemetry.spans.getFinishedSpans()[0].attributes;
+        });
+        afterEach(() => instance.dispose());
+        it('should record the stream type under both names', () => {
+            attributes.should.include({ 'chronicle.event_stream_type': 'orders', 'cratis.chronicle.event_stream.type': 'orders' });
+        });
+        it('should record the stream identifier under both names', () => {
+            attributes.should.include({ 'chronicle.event_stream_id': 'stream-1', 'cratis.chronicle.event_stream.id': 'stream-1' });
+        });
+    });
+}

package/telemetry/observeOperation.ts

@@ -6,9 +6,17 @@ import { ChronicleTracer } from '../Tracing.js';
 import { correlationIdManager } from '../correlation/index.js';
 import { CorrelationId } from '../correlation/CorrelationId.js';
 import { WellKnownTelemetryNames } from '../WellKnownTelemetryNames.js';
+import type { ChronicleTelemetryOptions } from './ChronicleTelemetryOptions.js';
 
 /** Opens one client span, scoping the resolved business correlation without generating a new one. */
-export function observeOperation<T>(name: string, action: (span: Span) => Promise<T>, correlationId?: { toString(): string }): Promise<T> {
+export function observeOperation<T>(
+    operation: keyof typeof WellKnownTelemetryNames.conventionSpans,
+    telemetry: ChronicleTelemetryOptions | undefined,
+    action: (span: Span) => Promise<T>,
+    correlationId?: { toString(): string }
+): Promise<T> {
+    const names = telemetry?.spanNames === 'convention' ? WellKnownTelemetryNames.conventionSpans : WellKnownTelemetryNames.spans;
+    const name = names[operation];
     const resolved = correlationId ? new CorrelationId(correlationId.toString()) : correlationIdManager.scoped;
     const run = () => {
         const active = context.active();

package/testing/EventFieldSchema.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { JsonSchema } from '../schemas/JsonSchema.js';
+
+const integerRanges = new Map<string, readonly [number, number]>([
+    ['int8', [-128, 127]], ['uint8', [0, 255]],
+    ['int16', [-32768, 32767]], ['uint16', [0, 65535]],
+    ['int32', [-2147483648, 2147483647]], ['uint32', [0, 4294967295]],
+    // JSON numbers cannot reliably represent the entire 64-bit domain. Fail closed outside safe integers.
+    ['int64', [Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]], ['uint64', [0, Number.MAX_SAFE_INTEGER]]
+]);
+const numberLimits = new Map<string, number>([
+    ['double', Number.MAX_VALUE], ['float', 3.4028234663852886e38], ['decimal', 7.922816251426433e28]
+]);
+
+/** Payload support is independent of the narrower, fixture-backed unique-key domain. */
+export function supportsEventField(schema: JsonSchema): boolean {
+    if (schema.compliance?.length || schema.security?.length || schema.enum !== undefined || schema.items !== undefined) return false;
+    if (schema.type === 'object') {
+        return schema.format === undefined &&
+            (typeof schema.additionalProperties !== 'object' || supportsEventField(schema.additionalProperties)) &&
+            Object.values(schema.properties ?? {}).every(supportsEventField);
+    }
+    if (schema.properties !== undefined || schema.additionalProperties !== undefined) return false;
+    if (schema.type === 'string') return schema.format === undefined || ['guid', 'uuid', 'date', 'date-time'].includes(schema.format);
+    if (schema.type === 'number' || schema.type === 'integer') {
+        return schema.format === undefined || integerRanges.has(schema.format) ||
+            (schema.type === 'number' && numberLimits.has(schema.format));
+    }
+    return schema.type === 'boolean' && schema.format === undefined;
+}
+
+/** Validate serialized JSON, never the wrapper objects production serialization has already removed. */
+export function matchesEventField(value: unknown, schema: JsonSchema): boolean {
+    if (schema.type === 'object') {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+        const content = value as Record<string, unknown>;
+        return (schema.required ?? []).every(key => Object.hasOwn(content, key)) &&
+            Object.entries(content).every(([key, entry]) => {
+                const property = schema.properties?.[key];
+                if (property) return matchesEventField(entry, property);
+                if (schema.additionalProperties === false) return false;
+                return typeof schema.additionalProperties !== 'object' || matchesEventField(entry, schema.additionalProperties);
+            });
+    }
+    if (schema.type === 'integer' || schema.type === 'number') {
+        if (typeof value !== 'number' || !Number.isFinite(value)) return false;
+        const range = integerRanges.get(schema.format ?? '');
+        if (schema.type === 'integer' || range) {
+            return Number.isSafeInteger(value) && (!range || (value >= range[0] && value <= range[1]));
+        }
+        return Math.abs(value) <= (numberLimits.get(schema.format ?? '') ?? Number.MAX_VALUE);
+    }
+    if (schema.type === 'string') {
+        if (typeof value !== 'string') return false;
+        if (schema.format === 'guid' || schema.format === 'uuid') return /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(value);
+        if (schema.format === 'date' || schema.format === 'date-time') return matchesDate(value, schema.format);
+    }
+    return typeof value === schema.type;
+}
+
+function matchesDate(value: string, format: string): boolean {
+    const dateOnly = format === 'date';
+    const pattern = dateOnly ? /^\d{4}-\d{2}-\d{2}$/ : /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+    if (!pattern.test(value) || +value.slice(0, 4) < 1) return false;
+    const instant = dateOnly ? `${value}T00:00:00.000Z` : value;
+    if (!Number.isFinite(Date.parse(instant))) return false;
+    // Date.parse rolls invalid calendar dates and 24:00 into another day; do not accept that coercion.
+    return new Date(instant).toISOString().slice(0, dateOnly ? 10 : 19) === value.slice(0, dateOnly ? 10 : 19);
+}