@cratis/chronicle 6.42.2 → 6.43.0

package/eventSequences/EventSequence.ts

@@ -41,7 +41,7 @@ import { observeOperation } from '../telemetry/observeOperation.js';
 import { setTelemetryAttribute, setEventSourceId, setSequenceNumber, recordSafeException } from '../telemetry/spanAttributes.js';
 import type { ChronicleTelemetryOptions } from '../telemetry/ChronicleTelemetryOptions.js';
 import { WellKnownTelemetryNames as names } from '../WellKnownTelemetryNames.js';
-import { ChronicleMetrics } from '../Metrics.js';
+import { ChronicleConventionMetrics } from '../Metrics.js';
 import { identityProvider, Identity } from '../identity/index.js';
 import { causationManager, CausationType } from '../auditing/index.js';
 import { toContractsGuid } from '../connection/Guid.js';
@@ -73,14 +73,14 @@ export class EventSequence implements IEventSequence {
     async append(eventSourceId: string, event: object, options?: AppendOptions): Promise<AppendResult> {
         const { eventType, correlationId, content, tags, causationChain, identity, subject } = prepareSingleAppend(event, options);
 
-        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
+        const sequenceMetricAttributes = {
+            [names.attributes.eventStore]: this._eventStoreName,
+            [names.attributes.namespace]: this._namespace,
+            [names.attributes.eventSequenceId]: this.id.value
         };
+        const metricAttributes = { ...sequenceMetricAttributes, [names.attributes.eventTypeId]: eventType.id.value };
 
-        return observeOperation('append', this._telemetry, async span => {
+        return observeOperation('append', async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             setTelemetryAttribute(span, 'eventTypeId', eventType.id.value);
@@ -116,7 +116,7 @@ export class EventSequence implements IEventSequence {
                 });
 
                 const appendResponse = ensureCommandResponse('append event', response);
-                const duration = performance.now() - startTime;
+                const durationInSeconds = (performance.now() - startTime) / 1000;
                 const result = this.mapAppendResponse(
                     appendResponse.SequenceNumber,
                     appendResponse.ConstraintViolations ?? [],
@@ -126,21 +126,13 @@ export class EventSequence implements IEventSequence {
                 setSequenceNumber(span, result.sequenceNumber.value);
                 span.setStatus({ code: SpanStatusCode.OK });
 
-                ChronicleMetrics.eventsAppended.add(1, metricAttributes);
-                ChronicleMetrics.appendDuration.record(duration, metricAttributes);
+                ChronicleConventionMetrics.eventsAppended.add(1, metricAttributes);
+                ChronicleConventionMetrics.appendDuration.record(durationInSeconds, 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
-                    });
+                    ChronicleConventionMetrics.constraintViolations.add(result.constraintViolations.length, sequenceMetricAttributes);
                 }
                 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
-                    });
+                    ChronicleConventionMetrics.appendErrors.add(result.errors.length, sequenceMetricAttributes);
                 }
 
                 if (this.appendOperations.hasSubscribers) {
@@ -151,11 +143,7 @@ export class EventSequence implements IEventSequence {
                 return result;
             } catch (error) {
                 recordSafeException(span, error);
-                ChronicleMetrics.appendErrors.add(1, {
-                    'chronicle.event_store': this._eventStoreName,
-                    'chronicle.namespace': this._namespace,
-                    'chronicle.event_sequence_id': this.id.value
-                });
+                ChronicleConventionMetrics.appendErrors.add(1, sequenceMetricAttributes);
                 throw error;
             } finally {
                 span.end();
@@ -177,13 +165,12 @@ export class EventSequence implements IEventSequence {
         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
+            [names.attributes.eventStore]: this._eventStoreName,
+            [names.attributes.namespace]: this._namespace,
+            [names.attributes.eventSequenceId]: this.id.value
         };
 
-        return observeOperation('appendMany', this._telemetry, async span => {
+        return observeOperation('appendMany', async span => {
             this.setSequenceAttributes(span);
             if (distinctEventSourceIds.length === 1) {
                 setEventSourceId(span, distinctEventSourceIds[0], this._telemetry);
@@ -210,7 +197,7 @@ export class EventSequence implements IEventSequence {
                 });
 
                 const appendManyResponse = ensureCommandResponse('append many events', response);
-                const duration = performance.now() - startTime;
+                const durationInSeconds = (performance.now() - startTime) / 1000;
                 // Mirrors the C# client: every per-event AppendResult in a batch carries all
                 // constraint violations and the first concurrency violation of the whole batch —
                 // the wire response doesn't correlate either back to a specific event index.
@@ -236,25 +223,17 @@ export class EventSequence implements IEventSequence {
                     );
                 span.setStatus({ code: SpanStatusCode.OK });
 
-                ChronicleMetrics.batchAppendsPerformed.add(1, batchMetricAttributes);
-                ChronicleMetrics.eventsAppended.add(eventsForEventSourceIds.length, batchMetricAttributes);
-                ChronicleMetrics.appendManyDuration.record(duration, batchMetricAttributes);
+                ChronicleConventionMetrics.batchAppendsPerformed.add(1, batchMetricAttributes);
+                ChronicleConventionMetrics.eventsAppended.add(eventsForEventSourceIds.length, batchMetricAttributes);
+                ChronicleConventionMetrics.appendManyDuration.record(durationInSeconds, 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
-                    });
+                    ChronicleConventionMetrics.constraintViolations.add(totalViolations, batchMetricAttributes);
                 }
                 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
-                    });
+                    ChronicleConventionMetrics.appendErrors.add(totalErrors, batchMetricAttributes);
                 }
 
                 if (this.appendOperations.hasSubscribers && result.length > 0) {
@@ -270,11 +249,7 @@ export class EventSequence implements IEventSequence {
                 return result;
             } catch (error) {
                 recordSafeException(span, error);
-                ChronicleMetrics.appendErrors.add(1, {
-                    'chronicle.event_store': this._eventStoreName,
-                    'chronicle.namespace': this._namespace,
-                    'chronicle.event_sequence_id': this.id.value
-                });
+                ChronicleConventionMetrics.appendErrors.add(1, batchMetricAttributes);
                 throw error;
             } finally {
                 span.end();
@@ -299,7 +274,7 @@ export class EventSequence implements IEventSequence {
         eventStreamId?: string,
         filterEventTypes?: Constructor[]
     ): Promise<EventSequenceNumber> {
-        return observeOperation('getTailSequenceNumber', this._telemetry, async span => {
+        return observeOperation('getTailSequenceNumber', async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             try {
@@ -339,7 +314,7 @@ export class EventSequence implements IEventSequence {
 
     /** @inheritdoc */
     async hasEventsFor(eventSourceId: string): Promise<boolean> {
-        return observeOperation('hasEventsFor', this._telemetry, async span => {
+        return observeOperation('hasEventsFor', async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             try {
@@ -371,7 +346,7 @@ export class EventSequence implements IEventSequence {
         eventStreamId?: string,
         eventSourceType?: string
     ): Promise<AppendedEvent[]> {
-        return observeOperation('getForEventSourceIdAndEventTypes', this._telemetry, async span => {
+        return observeOperation('getForEventSourceIdAndEventTypes', async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             try {
@@ -406,7 +381,7 @@ export class EventSequence implements IEventSequence {
         eventSourceId?: string,
         filterEventTypes?: Constructor[]
     ): Promise<AppendedEvent[]> {
-        return observeOperation('getFromSequenceNumber', this._telemetry, async span => {
+        return observeOperation('getFromSequenceNumber', async span => {
             this.setSequenceAttributes(span);
             setSequenceNumber(span, sequenceNumber.value);
             setEventSourceId(span, eventSourceId, this._telemetry);
@@ -438,7 +413,7 @@ export class EventSequence implements IEventSequence {
         const causationChain = causationManager.getCurrentChain();
         const identity = identityProvider.getCurrent();
 
-        return observeOperation('redact', this._telemetry, async span => {
+        return observeOperation('redact', async span => {
             this.setSequenceAttributes(span);
             setSequenceNumber(span, sequenceNumber.value);
             try {
@@ -472,7 +447,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('redactForEventSource', this._telemetry, async span => {
+        return observeOperation('redactForEventSource', async span => {
             this.setSequenceAttributes(span);
             setEventSourceId(span, eventSourceId, this._telemetry);
             try {
@@ -518,7 +493,7 @@ export class EventSequence implements IEventSequence {
 
     /** @inheritdoc */
     async completeStream(eventStreamType: string, eventStreamId: string): Promise<CompleteStreamResult> {
-        return observeOperation('completeStream', this._telemetry, async span => {
+        return observeOperation('completeStream', async span => {
             this.setSequenceAttributes(span);
             setTelemetryAttribute(span, 'eventStreamType', eventStreamType);
             setTelemetryAttribute(span, 'eventStreamId', eventStreamId);

package/for_ChronicleOptions/when_configuring_telemetry/with_span_names.spec.ts

@@ -6,27 +6,27 @@ 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);
+const factories = {
+    development: (telemetry: ChronicleTelemetryOptions) => ChronicleOptions.development({ telemetry }),
+    connectionString: (telemetry: ChronicleTelemetryOptions) => ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { telemetry })
+};
+for (const [name, factory] of Object.entries(factories)) {
+    describe(`when configuring compatibility span names through ${name}`, () => {
+        for (const spanNames of ['legacy', 'convention'] as const) {
+            it(`should accept ${spanNames} without throwing or changing privacy`, () => {
+                factory({ spanNames, eventSourceId: { mode: 'raw' } }).telemetry!.should.deep.equal({
+                    spanNames, eventSourceId: { mode: 'raw' }
+                });
+            });
+        }
+        it('should accept privacy settings without a span name option', () => {
+            factory({ eventSourceId: { mode: 'raw' } }).telemetry!.eventSourceId!.should.deep.equal({ mode: 'raw' });
         });
+        for (const spanNames of ['invalid', '', null, 42, {}]) {
+            it(`should reject the invalid JavaScript selector ${JSON.stringify(spanNames)}`, () => {
+                const telemetry = { spanNames } as unknown as ChronicleTelemetryOptions;
+                (() => factory(telemetry)).should.throw(TypeError, 'telemetry.spanNames must be legacy or convention.');
+            });
+        }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.42.2",
+    "version": "6.43.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 testing/for_EventScenario/when_appending_field_types/with_standard_decorators.standard.spec.ts eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts",
+        "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 eventSequences/for_EventSequence/when_appending/with_subject_annotations.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_from_all.standard.spec.ts projections/for_ProjectionDefinitionCompiler/when_compiling_tags/with_standard_decorators.standard.spec.ts telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts",
         "test:native": "node ./scripts/check-native-esm.mjs"
     },
     "dependencies": {

package/telemetry/ChronicleTelemetryOptions.ts

@@ -1,12 +1,13 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-/** Per-client naming and privacy settings; instrumentation itself is always available. */
+/** Per-client privacy and compatibility settings; instrumentation itself is always available. */
 export interface ChronicleTelemetryOptions {
     /**
-     * Span naming convention. Defaults to legacy; both modes use the same scope and attribute families.
-     * Replacing the earlier "next major" plan, built-in legacy span emission ends in an upcoming
-     * minor after ADR 0001's one-minor overlap. Both values will remain accepted as no-ops, without a removal deadline.
+     * Retained naming selector. Both 'legacy' and 'convention' are accepted as no-ops;
+     * built-in instrumentation always uses conventionSpans, including when this option is absent.
+     * @deprecated No longer needed; built-in spans always use convention names. This option has no removal deadline.
+     * The minor-release naming cutoff replaces the earlier "next major" plan after ADR 0001's one-minor overlap.
      * See https://github.com/Cratis/Chronicle.TypeScript/issues/171.
      */
     spanNames?: 'legacy' | 'convention';

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

@@ -15,7 +15,7 @@ export const legacySpans = {
     getEventStore: 'chronicle.client.get_event_store',
     getEventStores: 'chronicle.client.get_event_stores',
     getNamespaces: 'chronicle.event_store.get_namespaces'
-};
+} as const;
 
 export const conventionSpans = {
     append: 'cratis.chronicle.client.event_sequence.append',
@@ -30,4 +30,4 @@ export const conventionSpans = {
     getEventStore: 'cratis.chronicle.client.event_store.get',
     getEventStores: 'cratis.chronicle.client.event_store.list',
     getNamespaces: 'cratis.chronicle.client.event_store.get_namespaces'
-};
+} as const;

package/telemetry/for_ChronicleTelemetry/when_appending/{with_shared_and_legacy_attributes.spec.ts → with_canonical_attributes.spec.ts}

@@ -26,24 +26,23 @@ describe('when appending with a business correlation override', () => {
         await correlationIdManager.run(new CorrelationId('outer'), () => sequence.append('sensitive-id', new Recorded(), { correlationId: correlation }));
         span = telemetry.spans.getFinishedSpans()[0];
     });
-    it('should produce one client span with the unchanged operation name', () => {
+    it('should produce one client span with the convention operation name', () => {
         telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
         span.kind.should.equal(SpanKind.CLIENT);
-        span.name.should.equal('chronicle.event_sequences.append');
+        span.name.should.equal('cratis.chronicle.client.event_sequence.append');
     });
     it('should use the versioned shared instrumentation scope', () => {
         span.instrumentationScope.name.should.equal('Cratis.Chronicle.Client');
         should.equal(span.instrumentationScope.version, clientVersion);
     });
-    it('should emit both registries on the same span', () => {
+    it('should emit canonical attributes with the exact-string sequence number exception', () => {
         span.attributes.should.include({
-            'cratis.event_store.name': 'store', 'chronicle.event_store': 'store',
-            'cratis.event_store.namespace': 'namespace', 'chronicle.namespace': 'namespace',
-            'cratis.event_sequence.id': 'event-log', 'chronicle.event_sequence_id': 'event-log',
-            'cratis.event_type.id': 'telemetry-recorded', 'chronicle.event_type_id': 'telemetry-recorded',
-            'cratis.event_type.generation': 1, 'chronicle.event_type_generation': 1,
-            'cratis.event_sequence.number': 42, 'chronicle.sequence_number': '42'
+            'cratis.event_store.name': 'store', 'cratis.event_store.namespace': 'namespace',
+            'cratis.event_sequence.id': 'event-log', 'cratis.event_type.id': 'telemetry-recorded',
+            'cratis.event_type.generation': 1, 'cratis.event_sequence.number': 42
         });
+        Object.keys(span.attributes).filter(key => key.startsWith('chronicle.')).should.deep.equal(['chronicle.sequence_number']);
+        span.attributes.should.have.property('chronicle.sequence_number', '42');
     });
     it('should scope the resolved correlation consistently for propagation', () => {
         should.equal(span.attributes['cratis.correlation_id'], correlation);

package/telemetry/for_ChronicleTelemetry/when_exposing_names/with_convention_names.spec.ts

@@ -0,0 +1,65 @@
+// 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, expectTypeOf, it } from 'vitest';
+import { ChronicleOptions, ChronicleMetrics, ChronicleConventionMetrics, WellKnownTelemetryNames as names } from '../../../index.js';
+import type { ChronicleTelemetryOptions } from '../../../index.js';
+import { legacySpans, conventionSpans } from '../given/a_span_name_registry.fixture.js';
+
+const legacyAttributes = {
+    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'
+} as const;
+const legacyMetrics = {
+    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'
+} as const;
+
+chai.should();
+describe('when exposing canonical names alongside retained compatibility APIs', () => {
+    it('should preserve every legacy span value and literal type', () => {
+        names.spans.should.deep.equal(legacySpans);
+        expectTypeOf(names.spans).toEqualTypeOf<typeof legacySpans>();
+    });
+    it('should expose a matching canonical span for every operation', () => {
+        names.conventionSpans.should.deep.equal(conventionSpans);
+        expectTypeOf(names.conventionSpans).toEqualTypeOf<typeof 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');
+        expectTypeOf(names.legacyScope).toEqualTypeOf<'@cratis/chronicle'>();
+    });
+    it('should preserve every legacy attribute value and literal type', () => {
+        names.legacyAttributes.should.deep.equal(legacyAttributes);
+        expectTypeOf(names.legacyAttributes).toEqualTypeOf<typeof legacyAttributes>();
+    });
+    it('should preserve every legacy metric value and literal type', () => {
+        names.legacyMetrics.should.deep.equal(legacyMetrics);
+        expectTypeOf(names.legacyMetrics).toEqualTypeOf<typeof legacyMetrics>();
+    });
+    it('should retain both typed selector values through the public factories', () => {
+        expectTypeOf<ChronicleTelemetryOptions['spanNames']>().toEqualTypeOf<'legacy' | 'convention' | undefined>();
+        for (const spanNames of ['legacy', 'convention'] as const) {
+            ChronicleOptions.development({ telemetry: { spanNames } }).telemetry!.spanNames!.should.equal(spanNames);
+            ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { telemetry: { spanNames } })
+                .telemetry!.spanNames!.should.equal(spanNames);
+        }
+    });
+    it('should retain the public metric recording signatures', () => {
+        expectTypeOf(ChronicleMetrics).toEqualTypeOf<typeof ChronicleConventionMetrics>();
+        Object.keys(ChronicleMetrics).should.have.members(Object.keys(names.legacyMetrics));
+    });
+    it('should retain 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 → with_convention_names.spec.ts}

@@ -6,6 +6,7 @@ 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 type { ChronicleTelemetryOptions } from '../../ChronicleTelemetryOptions.js';
 import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
 import { EventSequenceNumber } from '../../../eventSequences/EventSequenceNumber.js';
 import { clientVersion } from '../../../connection/clientVersion.js';
@@ -30,14 +31,14 @@ const operations = {
 };
 
 for (const spanNames of [undefined, 'legacy', 'convention'] as const) {
-    const expected = spanNames === 'convention' ? conventionSpans : legacySpans;
+    const options: ChronicleTelemetryOptions | undefined = spanNames === undefined ? undefined : { spanNames };
     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`, () => {
+            describe(`when naming ${operation} on ${sequenceId.value} with ${spanNames ?? 'default'} configuration`, () => {
                 let instance: ChronicleClient;
                 let span: ReadableSpan;
                 beforeEach(async () => {
-                    instance = client(spanNames === undefined ? undefined : { spanNames });
+                    instance = client(options);
                     const store = await instance.getEventStore('store', 'namespace');
                     const sequence = sequenceId === EventSequenceId.eventLog ? store.eventLog : store.getEventSequence(sequenceId);
                     telemetry.spans.reset();
@@ -45,32 +46,35 @@ for (const spanNames of [undefined, 'legacy', 'convention'] as const) {
                     span = telemetry.spans.getFinishedSpans()[0];
                 });
                 afterEach(() => instance.dispose());
-                it('should emit exactly one client span with the selected name', () => {
+                it('should emit exactly one convention client span and no legacy span', () => {
                     telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
-                    span.name.should.equal(expected[operation]);
+                    span.name.should.equal(conventionSpans[operation]).and.not.equal(legacySpans[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', () => {
+                it('should emit canonical attributes with only the exact-string sequence number exception', () => {
                     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
+                        'cratis.event_store.name': 'store', 'cratis.event_store.namespace': 'namespace',
+                        'cratis.event_sequence.id': sequenceId.value
                     });
+                    const hasSequenceNumber = ['append', 'getTailSequenceNumber', 'getFromSequenceNumber', 'redact'].includes(operation);
+                    Object.keys(span.attributes).filter(key => key.startsWith('chronicle.')).should.deep.equal(
+                        hasSequenceNumber ? ['chronicle.sequence_number'] : []);
+                    if (hasSequenceNumber) span.attributes.should.have.property('chronicle.sequence_number', '42');
                 });
             });
         }
     }
 
     for (const operation of ['getEventStore', 'getEventStores', 'getNamespaces'] as const) {
-        describe(`when naming ${operation} with ${spanNames ?? 'default'} names`, () => {
+        describe(`when naming ${operation} with ${spanNames ?? 'default'} configuration`, () => {
             let instance: ChronicleClient;
             let span: ReadableSpan;
             beforeEach(async () => {
-                instance = client(spanNames === undefined ? undefined : { spanNames });
+                instance = client(options);
                 if (operation === 'getNamespaces') {
                     const store = await instance.getEventStore('store', 'namespace');
                     telemetry.spans.reset();
@@ -83,56 +87,57 @@ for (const spanNames of [undefined, 'legacy', 'convention'] as const) {
                 span = telemetry.spans.getFinishedSpans()[0];
             });
             afterEach(() => instance.dispose());
-            it('should emit exactly one client span with the selected name and shared scope', () => {
+            it('should emit exactly one convention client span and no legacy span', () => {
                 telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
-                span.name.should.equal(expected[operation]);
+                span.name.should.equal(conventionSpans[operation]).and.not.equal(legacySpans[operation]);
                 span.kind.should.equal(SpanKind.CLIENT);
                 span.instrumentationScope.name.should.equal('Cratis.Chronicle.Client');
                 should.equal(span.instrumentationScope.version, clientVersion);
             });
+            it('should not emit legacy attributes', () => {
+                Object.keys(span.attributes).filter(key => key.startsWith('chronicle.')).should.be.empty;
+            });
             if (operation !== 'getEventStores') {
-                it('should retain both event store attributes', () => {
-                    span.attributes.should.include({ 'chronicle.event_store': 'store', 'cratis.event_store.name': 'store' });
+                it('should retain the canonical event store attribute', () => {
+                    span.attributes.should.include({ 'cratis.event_store.name': 'store' });
                 });
             }
         });
     }
 }
 
-describe('when interleaving two clients with different span naming modes', () => {
+describe('when legacy and convention configurations coexist in one process', () => {
     let legacy: ChronicleClient;
     let convention: ChronicleClient;
-    let spans: ReadableSpan[];
     beforeEach(async () => {
-        legacy = client({ spanNames: 'legacy' });
+        legacy = client({ spanNames: 'legacy', eventSourceId: { mode: 'raw' } });
         convention = client({ spanNames: 'convention' });
         const [legacyStore, conventionStore] = await Promise.all([
-            legacy.getEventStore('legacy-store'), convention.getEventStore('convention-store')
+            legacy.getEventStore('legacy-client'), convention.getEventStore('convention-client')
+        ]);
+        telemetry.spans.reset();
+        await Promise.all([
+            legacyStore.eventLog.append('legacy-source', new Recorded()),
+            conventionStore.eventLog.append('convention-source', new Recorded())
         ]);
-        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
+    it('should emit one canonical span per operation regardless of the retained selector', () => {
+        telemetry.spans.getFinishedSpans().map(span => span.name).should.deep.equal([
+            conventionSpans.append, conventionSpans.append
         ]);
-        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}`]));
+    it('should keep privacy local to each client', () => {
+        const spans = telemetry.spans.getFinishedSpans();
+        spans.find(span => span.attributes['cratis.event_store.name'] === 'legacy-client')!
+            .attributes.should.have.property('cratis.event_source.id', 'legacy-source');
+        spans.find(span => span.attributes['cratis.event_store.name'] === 'convention-client')!
+            .attributes.should.not.have.property('cratis.event_source.id');
+    });
+    it('should not restore legacy metric instruments for either client', async () => {
+        const scopes = (await telemetry.reader.collect()).resourceMetrics.scopeMetrics;
+        scopes.should.have.lengthOf(1);
+        scopes[0].metrics.should.not.be.empty;
+        scopes[0].metrics.filter(metric => metric.descriptor.name.startsWith('chronicle.')).should.be.empty;
     });
 });

package/telemetry/for_ChronicleTelemetry/when_recording_identifiers/with_per_client_privacy.spec.ts

@@ -32,11 +32,11 @@ for (const [label, policy, expected] of [
             await sequence.redactForEventSource(source, 'private reason');
             services.append.mock.calls[0][0].EventSourceId.should.equal(source);
         });
-        it('should apply the policy equally to both names on every operation', () => {
+        it('should apply the policy only to the canonical name on every operation', () => {
             telemetry.spans.getFinishedSpans().should.have.lengthOf(8);
             for (const span of telemetry.spans.getFinishedSpans()) {
                 should.equal(span.attributes['cratis.event_source.id'], expected);
-                should.equal(span.attributes['chronicle.event_source_id'], expected);
+                should.equal(span.attributes['chronicle.event_source_id'], undefined);
             }
         });
     });
@@ -71,7 +71,8 @@ describe('when appending a batch with multiple event sources', () => {
     });
     it('should record the count without an identifier array', () => {
         const attributes = telemetry.spans.getFinishedSpans()[0].attributes;
-        attributes.should.include({ 'cratis.event.count': 2, 'chronicle.events_count': 2 });
+        attributes.should.have.property('cratis.event.count', 2);
+        attributes.should.not.have.property('chronicle.events_count');
         should.equal(attributes['cratis.event_source.id'], undefined);
         should.equal(attributes['chronicle.event_source_id'], undefined);
     });