@cratis/chronicle 6.32.1 → 6.34.0

package/seeding/EventSeeding.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { diag } from '@opentelemetry/api';
+import { createLogger } from '../logging/createLogger.js';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
 import { ensureCommandSuccess } from '../connection/callResults.js';
@@ -27,7 +27,7 @@ interface SeedingEntry {
  * with the Chronicle Kernel.
  */
 export class EventSeeding implements IEventSeeding {
-    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/EventSeeding' });
+    private readonly _logger: ReturnType<typeof createLogger>;
     private readonly _entries: SeedingEntry[] = [];
 
     /**
@@ -40,7 +40,9 @@ export class EventSeeding implements IEventSeeding {
         private readonly _eventStoreName: string,
         private readonly _connection: ChronicleConnection,
         private readonly _clientArtifacts: IClientArtifactsProvider
-    ) {}
+    ) {
+        this._logger = createLogger('@cratis/chronicle/EventSeeding', _connection.logger);
+    }
 
     /** @inheritdoc */
     for<TEvent extends object>(eventSourceId: string, events: Iterable<TEvent>): IEventSeedingBuilder {
@@ -69,7 +71,7 @@ export class EventSeeding implements IEventSeeding {
             } catch (error) {
                 this._logger.warn('Failed to activate or execute event seeder - skipping seeder', {
                     seederType: seederType.name,
-                    error: String(error)
+                    error
                 });
             }
         }

package/telemetry/ChronicleTelemetryOptions.ts

@@ -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.
+
+/** Per-client privacy settings; instrumentation itself is always available. */
+export interface ChronicleTelemetryOptions {
+    /** 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_telemetry_session.fixture.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeAll, beforeEach, afterAll } from 'vitest';
+import { context, metrics, propagation, trace } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } from '@opentelemetry/core';
+import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { InMemoryMetricExporter, MeterProvider, PeriodicExportingMetricReader, AggregationTemporality } from '@opentelemetry/sdk-metrics';
+
+/** In-process providers only; no export outside the spec process. */
+export function telemetrySession() {
+    const spans = new InMemorySpanExporter();
+    const traces = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(spans)] });
+    const metricExporter = new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE);
+    const reader = new PeriodicExportingMetricReader({ exporter: metricExporter, exportIntervalMillis: 60000 });
+    const meters = new MeterProvider({ readers: [reader] });
+    const contextManager = new AsyncLocalStorageContextManager();
+    beforeAll(() => {
+        context.setGlobalContextManager(contextManager.enable());
+        trace.setGlobalTracerProvider(traces);
+        metrics.setGlobalMeterProvider(meters);
+        propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()] }));
+    });
+    beforeEach(() => spans.reset());
+    afterAll(async () => {
+        await traces.shutdown();
+        await meters.shutdown();
+        context.disable();
+        trace.disable();
+        metrics.disable();
+        propagation.disable();
+        contextManager.disable();
+    });
+    return { spans, traces, reader };
+}

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

@@ -0,0 +1,29 @@
+// 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 { EventSequence } from '../../../eventSequences/EventSequence.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import type { ChronicleConnection } from '../../../connection/ChronicleConnection.js';
+import type { IUnitOfWorkManager } from '../../../transactions/IUnitOfWorkManager.js';
+import type { ChronicleTelemetryOptions } from '../../ChronicleTelemetryOptions.js';
+
+export class Recorded { constructor(readonly value = 'sensitive payload') {} }
+eventType('telemetry-recorded')(Recorded);
+
+export function eventSequence(telemetry?: ChronicleTelemetryOptions) {
+    const services = {
+        append: vi.fn().mockResolvedValue({ Response: { SequenceNumber: 42n } }),
+        appendManyForEventSources: vi.fn().mockResolvedValue({ Response: { SequenceNumbers: [42n, 43n] } }),
+        tailSequenceNumber: vi.fn().mockResolvedValue({ IsAuthorized: true, Data: { SequenceNumber: 42n } }),
+        hasEventsForEventSourceId: vi.fn().mockResolvedValue({ IsAuthorized: true, Data: { HasEvents: true } }),
+        forEventSourceIdAndEventTypes: vi.fn().mockResolvedValue({ IsAuthorized: true, Data: [] }),
+        fromSequenceNumber: vi.fn().mockResolvedValue({ IsAuthorized: true, Data: [] }),
+        redact: vi.fn().mockResolvedValue({}),
+        redactForEventSource: vi.fn().mockResolvedValue({})
+    };
+    const connection = { eventSequences: services } as unknown as ChronicleConnection;
+    return { services, sequence: new EventSequence(EventSequenceId.eventLog, 'store', 'namespace', connection,
+        {} as IUnitOfWorkManager, undefined, telemetry) };
+}

package/telemetry/for_ChronicleTelemetry/when_appending/with_shared_and_legacy_attributes.spec.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { SpanKind, context, propagation } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { eventSequence, Recorded } from '../given/an_event_sequence.fixture.js';
+import { clientVersion } from '../../../connection/clientVersion.js';
+import { CorrelationId, correlationIdManager } from '../../../correlation/index.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+const correlation = '95bd1c83-de97-45f7-84a0-fb462af14d0c';
+
+describe('when appending with a business correlation override', () => {
+    let span: ReadableSpan;
+    let injectedCorrelation: string | undefined;
+    beforeEach(async () => {
+        const { sequence, services } = eventSequence();
+        services.append.mockImplementation(async () => {
+            await Promise.resolve();
+            injectedCorrelation = propagation.getBaggage(context.active())?.getEntry('cratis.correlation_id')?.value;
+            return { Response: { SequenceNumber: 42n } };
+        });
+        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', () => {
+        telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
+        span.kind.should.equal(SpanKind.CLIENT);
+        span.name.should.equal('chronicle.event_sequences.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', () => {
+        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'
+        });
+    });
+    it('should scope the resolved correlation consistently for propagation', () => {
+        should.equal(span.attributes['cratis.correlation_id'], correlation);
+        should.equal(injectedCorrelation, correlation);
+        should.equal(correlationIdManager.scoped, undefined);
+    });
+    it('should not record identifiers or payloads by default', () => {
+        JSON.stringify(span.attributes).should.not.contain('sensitive');
+        should.equal(span.attributes['cratis.event_source.id'], undefined);
+        should.equal(span.attributes['chronicle.event_source_id'], undefined);
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_appending/without_an_sdk.spec.ts

@@ -0,0 +1,15 @@
+// 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 { eventSequence, Recorded } from '../given/an_event_sequence.fixture.js';
+
+chai.should();
+describe('when appending without an OpenTelemetry SDK', () => {
+    it('should preserve append behavior without telemetry setup', async () => {
+        const { sequence, services } = eventSequence();
+        const result = await sequence.append('source', new Recorded());
+        result.sequenceNumber.value.should.equal(42n);
+        services.append.mock.calls.should.have.lengthOf(1);
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_documenting/with_public_names.spec.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { chai, describe, it } from 'vitest';
+import { WellKnownTelemetryNames } from '../../../WellKnownTelemetryNames.js';
+import { telemetryReference } from '../../../scripts/telemetry-reference.mjs';
+
+chai.should();
+describe('when publishing the telemetry reference', () => {
+    it('should keep the documented registry identical to the public constants', () => {
+        const documentation = readFileSync(new URL('../../../../Documentation/observability.md', import.meta.url), 'utf8');
+        documentation.should.contain(telemetryReference(WellKnownTelemetryNames));
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_failures/with_sensitive_exception_details.spec.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { SpanStatusCode } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { eventSequence, Recorded } from '../given/an_event_sequence.fixture.js';
+
+chai.should();
+const telemetry = telemetrySession();
+
+describe('when an append fails with sensitive exception details', () => {
+    const failure = new TypeError('sensitive token in error message');
+    let span: ReadableSpan;
+    let thrown: unknown;
+    beforeEach(async () => {
+        const { sequence, services } = eventSequence();
+        services.append.mockRejectedValue(failure);
+        try { await sequence.append('private', new Recorded()); } catch (error) { thrown = error; }
+        span = telemetry.spans.getFinishedSpans()[0];
+    });
+    it('should rethrow the original failure', () => { (thrown === failure).should.be.true; });
+    it('should record only failure types and error status', () => {
+        span.status.should.deep.equal({ code: SpanStatusCode.ERROR });
+        span.attributes.should.include({ 'error.type': 'TypeError' });
+        span.events.should.have.lengthOf(1);
+        span.events[0].attributes!.should.deep.equal({ 'exception.type': 'TypeError' });
+    });
+    it('should never export the exception message or stack', () => {
+        JSON.stringify({ attributes: span.attributes, status: span.status, events: span.events }).should.not.contain('sensitive');
+        span.events[0].attributes!.should.not.have.property('exception.stacktrace');
+    });
+});

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

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createHmac } from 'node:crypto';
+import { beforeEach, chai, describe, it } from 'vitest';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { eventSequence, Recorded } from '../given/an_event_sequence.fixture.js';
+import { EventSequenceNumber } from '../../../eventSequences/EventSequenceNumber.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { ChronicleTelemetryOptions } from '../../ChronicleTelemetryOptions.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+const source = 'sensitive-source';
+const key = new Uint8Array([10, 20, 30, 40]);
+
+for (const [label, policy, expected] of [
+    ['absent', undefined, undefined],
+    ['raw', { eventSourceId: { mode: 'raw' } }, source],
+    ['hmac', { eventSourceId: { mode: 'hmac', key } }, createHmac('sha256', key).update(source).digest('hex')]
+] as const) {
+    describe(`when recording event source identifiers with ${label} privacy`, () => {
+        beforeEach(async () => {
+            const { sequence, services } = eventSequence(policy as ChronicleTelemetryOptions | undefined);
+            await sequence.append(source, new Recorded());
+            await sequence.appendMany(source, [new Recorded(), new Recorded()]);
+            await sequence.appendMany([{ eventSourceId: source, event: new Recorded() }, { eventSourceId: source, event: new Recorded() }]);
+            await sequence.getTailSequenceNumber(source);
+            await sequence.hasEventsFor(source);
+            await sequence.getForEventSourceIdAndEventTypes(source, [Recorded]);
+            await sequence.getFromSequenceNumber(new EventSequenceNumber(1n), source);
+            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', () => {
+            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);
+            }
+        });
+    });
+}
+
+describe('when a validated telemetry policy is later mutated by an untyped caller', () => {
+    beforeEach(async () => {
+        const options = ChronicleOptions.development({ telemetry: { eventSourceId: { mode: 'hmac', key } } });
+        Object.assign(options.telemetry!.eventSourceId!, { key: undefined });
+        const { sequence, services } = eventSequence(options.telemetry);
+        await sequence.append(source, new Recorded());
+        await sequence.getTailSequenceNumber(source);
+        await sequence.redactForEventSource(source, 'reason');
+        services.append.mock.calls.should.have.lengthOf(1);
+        services.tailSequenceNumber.mock.calls.should.have.lengthOf(1);
+        services.redactForEventSource.mock.calls.should.have.lengthOf(1);
+    });
+    it('should omit the failed enrichment without failing business calls or leaving spans open', () => {
+        telemetry.spans.getFinishedSpans().should.have.lengthOf(3);
+        for (const span of telemetry.spans.getFinishedSpans()) {
+            span.attributes.should.not.have.property('cratis.event_source.id');
+            span.attributes.should.not.have.property('chronicle.event_source_id');
+        }
+    });
+});
+
+describe('when appending a batch with multiple event sources', () => {
+    beforeEach(async () => {
+        await eventSequence({ eventSourceId: { mode: 'raw' } }).sequence.appendMany([
+            { eventSourceId: 'first', event: new Recorded() }, { eventSourceId: 'second', event: new Recorded() }
+        ]);
+    });
+    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 });
+        should.equal(attributes['cratis.event_source.id'], undefined);
+        should.equal(attributes['chronicle.event_source_id'], undefined);
+    });
+});
+
+describe('when clients use different identifier policies concurrently', () => {
+    beforeEach(async () => {
+        await Promise.all([
+            eventSequence().sequence.append(source, new Recorded()),
+            eventSequence({ eventSourceId: { mode: 'raw' } }).sequence.append(source, new Recorded()),
+            eventSequence({ eventSourceId: { mode: 'hmac', key } }).sequence.append(source, new Recorded())
+        ]);
+    });
+    it('should keep each policy local to its client', () => {
+        const identifiers = telemetry.spans.getFinishedSpans().map(span => span.attributes['cratis.event_source.id']);
+        identifiers.should.have.members([undefined, source, createHmac('sha256', key).update(source).digest('hex')]);
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_metrics/with_legacy_overlap.spec.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { ChronicleMetrics } from '../../../Metrics.js';
+import { clientVersion } from '../../../connection/clientVersion.js';
+import type { ScopeMetrics } from '@opentelemetry/sdk-metrics';
+
+chai.should();
+const telemetry = telemetrySession();
+describe('when recording metrics after installing the SDK', () => {
+    let scope: ScopeMetrics;
+    beforeEach(async () => {
+        // Metrics was imported before provider installation: recording must still reach the SDK.
+        const attributes = { 'chronicle.event_store': 'store', 'chronicle.namespace': 'namespace',
+            'chronicle.event_sequence_id': 'event-log', 'chronicle.events_count': 237 };
+        ChronicleMetrics.batchAppendsPerformed.add(1, attributes);
+        ChronicleMetrics.appendManyDuration.record(250, attributes);
+        scope = (await telemetry.reader.collect()).resourceMetrics.scopeMetrics[0];
+    });
+    it('should use the shared scope and installed version', () => {
+        scope.scope.should.include({ name: 'Cratis.Chronicle.Client', version: clientVersion });
+    });
+    it('should retain legacy milliseconds while emitting seconds', () => {
+        const legacy = scope.metrics.find(metric => metric.descriptor.name === 'chronicle.events.append_many_duration')!;
+        const shared = scope.metrics.find(metric => metric.descriptor.name === 'cratis.chronicle.event_sequence.append_many_duration')!;
+        legacy.descriptor.unit.should.equal('ms');
+        shared.descriptor.unit.should.equal('s');
+        legacy.dataPoints[0].value.should.include({ min: 250, max: 250 });
+        shared.dataPoints[0].value.should.include({ min: 0.25, max: 0.25 });
+    });
+    it('should exclude batch size from only the new metric dimensions', () => {
+        const legacy = scope.metrics.find(metric => metric.descriptor.name === 'chronicle.events.batch_appends')!;
+        const shared = scope.metrics.find(metric => metric.descriptor.name === 'cratis.chronicle.event_sequence.batch_appends')!;
+        legacy.dataPoints[0].attributes.should.have.property('chronicle.events_count', 237);
+        shared.dataPoints[0].attributes.should.deep.equal({ 'cratis.event_store.name': 'store',
+            'cratis.event_store.namespace': 'namespace', 'cratis.event_sequence.id': 'event-log' });
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_sequence_numbers/with_integer_precision.spec.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 { beforeEach, chai, describe, it } from 'vitest';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { eventSequence } from '../given/an_event_sequence.fixture.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+for (const [number, expected] of [[42n, 42], [9007199254740991n, Number.MAX_SAFE_INTEGER], [9007199254740992n, undefined], [18446744073709551615n, undefined]] as const) {
+    describe(`when reading sequence number ${number}`, () => {
+        beforeEach(async () => {
+            const { sequence, services } = eventSequence();
+            services.tailSequenceNumber.mockResolvedValue({ IsAuthorized: true, Data: { SequenceNumber: number } });
+            await sequence.getTailSequenceNumber();
+        });
+        it('should keep the legacy string and emit only exactly representable shared integers', () => {
+            const attributes = telemetry.spans.getFinishedSpans()[0].attributes;
+            should.equal(attributes['cratis.event_sequence.number'], expected);
+            should.equal(attributes['chronicle.sequence_number'], number.toString());
+        });
+    });
+}

package/telemetry/observeOperation.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { context, propagation, SpanKind, type Span } from '@opentelemetry/api';
+import { ChronicleTracer } from '../Tracing.js';
+import { correlationIdManager } from '../correlation/index.js';
+import { CorrelationId } from '../correlation/CorrelationId.js';
+import { WellKnownTelemetryNames } from '../WellKnownTelemetryNames.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> {
+    const resolved = correlationId ? new CorrelationId(correlationId.toString()) : correlationIdManager.scoped;
+    const run = () => {
+        const active = context.active();
+        const key = WellKnownTelemetryNames.attributes.correlationId;
+        const correlation = resolved?.toString() ?? propagation.getBaggage(active)?.getEntry(key)?.value;
+        const parent = correlation ? propagation.setBaggage(active,
+            (propagation.getBaggage(active) ?? propagation.createBaggage()).setEntry(key, { value: correlation })) : active;
+        return ChronicleTracer.startActiveSpan(name, {
+            kind: SpanKind.CLIENT,
+            attributes: correlation ? { [key]: correlation } : {}
+        }, parent, action);
+    };
+    return resolved ? correlationIdManager.run(resolved, run) : run();
+}

package/telemetry/runInBackgroundContext.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { context, ROOT_CONTEXT } from '@opentelemetry/api';
+import { correlationIdManager } from '../correlation/index.js';
+
+/** Starts client-owned work without retaining the initiating request's trace or business correlation. */
+export function runInBackgroundContext<T>(action: () => T): T {
+    return context.with(ROOT_CONTEXT, () => correlationIdManager.runWithout(action));
+}

package/telemetry/spanAttributes.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createHmac } from 'node:crypto';
+import { SpanStatusCode, type Span, type AttributeValue } from '@opentelemetry/api';
+import { WellKnownTelemetryNames as names } from '../WellKnownTelemetryNames.js';
+import type { ChronicleTelemetryOptions } from './ChronicleTelemetryOptions.js';
+
+/** Records a shared attribute and its legacy alias on the same span. */
+export function setTelemetryAttribute(span: Span, name: keyof typeof names.legacyAttributes, value: AttributeValue): void {
+    span.setAttribute(names.legacyAttributes[name], value);
+    if (name in names.attributes) {
+        span.setAttribute(names.attributes[name as keyof typeof names.attributes], value);
+    }
+}
+
+/** Preserves the legacy string; records the shared integer only when exactly representable. */
+export function setSequenceNumber(span: Span, value: bigint): void {
+    span.setAttribute(names.legacyAttributes.sequenceNumber, value.toString());
+    const number = Number(value);
+    if (Number.isSafeInteger(number)) span.setAttribute(names.attributes.sequenceNumber, number);
+}
+
+/** Applies the same privacy policy to both event source identifier names. */
+export function setEventSourceId(span: Span, value: string | undefined, options?: ChronicleTelemetryOptions): void {
+    try {
+        const policy = options?.eventSourceId;
+        if (value === undefined || !policy || !span.isRecording()) return;
+        if (policy.mode !== 'raw' && policy.mode !== 'hmac') return;
+        const recorded = policy.mode === 'raw' ? value : createHmac('sha256', policy.key).update(value).digest('hex');
+        setTelemetryAttribute(span, 'eventSourceId', recorded);
+    } catch {
+        // Options are validated at construction, but callers can mutate them later.
+        // Optional telemetry enrichment must never prevent an RPC or span completion.
+    }
+}
+
+/** Classifies failures without serializing arbitrary thrown values, messages or stacks. */
+export function exceptionType(error: unknown): string {
+    return error instanceof Error ? error.name : typeof error;
+}
+
+/** Records failure type only; preserves the original exception for the caller. */
+export function recordSafeException(span: Span, error: unknown): void {
+    const type = exceptionType(error);
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    span.setAttribute(names.attributes.errorType, type);
+    span.addEvent('exception', { [names.attributes.exceptionType]: type });
+}