@cratis/chronicle 6.33.0 → 6.35.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 });
+}

package/testing/ReactorScenario.ts

@@ -21,6 +21,7 @@ import { EventStoreNamespaceName } from '../EventStoreNamespaceName.js';
 import type { IEventStore } from '../IEventStore.js';
 import type { IReadModels } from '../readModels/IReadModels.js';
 import { getReactorEventTypes, invokeReactorHandler, selectReactorHandler } from '../reactors/ReactorDispatcher.js';
+import { createHandlerInstanceValidator } from '../observation/createHandlerInstanceValidator.js';
 import { getReactorMetadata } from '../reactors/reactor.js';
 import { normalizeReactorSideEffects } from '../reactors/ReactorSideEffects.js';
 import type { ReactorServices } from '../reactors/ReactorServices.js';
@@ -40,6 +41,7 @@ export class ReactorScenario {
     private readonly _entries: ReturnType<typeof getReactorEventTypes>;
     private readonly _eventTypes: readonly Constructor[];
     private readonly _instance?: Record<string, Function>;
+    private readonly _validateInstance: (instance: object) => void;
     private readonly _store: IEventStore;
     private readonly _controller = new AbortController();
     private readonly _effects: RecordedReactorSideEffect[] = [];
@@ -76,9 +78,12 @@ export class ReactorScenario {
             eventTypeMigrations: eventTypeMigrations === undefined ? undefined : [...eventTypeMigrations]
         } });
         this._entries = getReactorEventTypes(_reactor, this._eventTypes);
+        this._validateInstance = createHandlerInstanceValidator(_reactor,
+            this._entries.flatMap(entry => [entry.methodName, entry.replayMethodName].filter((name): name is string => !!name)));
         // Every unsupported event-sequence operation is latched at its source, whichever result or stream carries it.
         observeUnsupportedOperations(this._events.eventSequence, error => { this.latch(error); });
         this._instance = _options.artifactActivator ? undefined : new (_reactor as new () => Record<string, Function>)();
+        if (this._instance) this._validateInstance(this._instance);
         this._store = _options.servicesEventStore ?? this.scenarioStore();
         this.given = { forEventSource: id => ({ events: (...events) => this.deliver(id, events, true) }) };
         this.when = { forEventSource: id => ({ events: (...events) => this.deliver(id, events, false) }) };
@@ -246,7 +251,10 @@ export class ReactorScenario {
                         artifactId: getReactorMetadata(this._reactor)!.id.value, eventStore: this._store,
                         readModels: services.readModels, eventSequenceId: 'event-log', partition: sourceId,
                         signal: services.signal, delivery: ArtifactDelivery.Events, eventContext: first.context },
-                    this._options.artifactActivator, process);
+                    this._options.artifactActivator, artifact => {
+                        this._validateInstance(artifact.instance);
+                        return process(artifact);
+                    });
                 } else {
                     await process({ instance: this._instance ?? {} });
                 }

package/testing/ReducerReadModelProcessor.ts

@@ -18,6 +18,7 @@ export class ReducerReadModelProcessor<TReadModel extends object> implements IRe
     async process(events: readonly ScenarioEvent[]): Promise<Map<string, ReadModelState<TReadModel>>> {
         const results = new Map<string, ReadModelState<TReadModel>>();
         const reducer = new (this._reducerType as new () => Record<string, Function>)();
+        this._dispatcher.validateInstance(reducer);
         for (const event of events) {
             const handler = this._dispatcher.handlerFor(event.context.eventType.id.value);
             if (!handler) continue;

package/testing/for_ReactorScenario/when_delivering_to_an_explicit_handler.spec.ts

@@ -0,0 +1,100 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { field } from '@cratis/fundamentals';
+import { beforeEach, chai, describe, it } from 'vitest';
+import { eventType, handles, onceOnly, reactor, type EventContext, type ReactorServices } from '../../index.js';
+import { ReactorScenario } from '../index.js';
+
+chai.should();
+
+@eventType('scenario-explicit-author')
+class AuthorRegistered {
+    @field(String) name: string;
+    constructor(name: string) { this.name = name; }
+}
+@eventType('scenario-explicit-notification')
+class AuthorNotified {
+    @field(String) name: string;
+    constructor(name: string) { this.name = name; }
+}
+
+const calls: { name: string; source: string; method: string }[] = [];
+@reactor('explicit-scenario-handler')
+class AuthorReactor {
+    @onceOnly()
+    @handles(AuthorRegistered)
+    notify(event: AuthorRegistered, context: EventContext, services: ReactorServices) {
+        (services.readModels === services.eventStore.readModels).should.be.true;
+        calls.push({ name: event.name, source: context.eventSourceId, method: 'notify' });
+        return new AuthorNotified(event.name);
+    }
+}
+
+const options = { artifacts: { eventTypes: [AuthorRegistered, AuthorNotified] }, constraints: 'disabled' as const };
+
+describe('when delivering a live event to an explicitly named onceOnly handler in ReactorScenario', () => {
+    let scenario: ReactorScenario;
+    beforeEach(async () => {
+        calls.length = 0;
+        scenario = new ReactorScenario(AuthorReactor, options);
+        await scenario.when.forEventSource('author-1').events(new AuthorRegistered('Ada'));
+    });
+    it('should invoke the method with the event and context', () => {
+        calls.should.deep.equal([{ name: 'Ada', source: 'author-1', method: 'notify' }]);
+    });
+    it('should process returned side effects', () => {
+        scenario.shouldHaveProduced(AuthorNotified, event => event.name === 'Ada');
+    });
+    it('should complete delivery', () => {
+        scenario.results[0].completed.should.be.true;
+    });
+});
+
+describe('when ReactorScenario has an unregistered explicit handler', () => {
+    it('should reject it before constructing the reactor', () => {
+        let constructed = false;
+        @reactor('invalid-explicit-scenario')
+        class Invalid {
+            constructor() { constructed = true; }
+            @handles(AuthorRegistered) notify() {}
+        }
+        (() => new ReactorScenario(Invalid, { ...options, artifacts: { eventTypes: [AuthorNotified] } }))
+            .should.throw(/notify.*AuthorRegistered.*no registered event type/);
+        constructed.should.be.false;
+    });
+});
+
+@reactor('field-shadowing-scenario')
+class FieldReactor extends AuthorReactor {
+    override notify = () => new AuthorNotified('hidden');
+}
+
+describe('when an instance field hides an inherited ReactorScenario handler', () => {
+    it('should reject the field after constructing the reactor', () => {
+        (() => new ReactorScenario(FieldReactor, options)).should.throw(
+            "Override 'notify' on 'FieldReactor' hides @handles(AuthorRegistered) declared on 'AuthorReactor'; use a method with @handles instead of an instance field.");
+    });
+    it('should reject an activator-created field before delivery and dispose its lease', async () => {
+        let disposed = false;
+        const scenario = new ReactorScenario(FieldReactor, { ...options, artifactActivator: type => ({
+            instance: new type(), dispose: () => { disposed = true; }
+        }) });
+        const [result] = await Promise.allSettled([scenario.when.forEventSource('author').events(new AuthorRegistered('Ada'))]);
+        result.status.should.equal('rejected');
+        if (result.status === 'rejected') (result.reason as Error).message.should.match(/Override 'notify'.*use a method/);
+        scenario.produced.should.have.lengthOf(0);
+        disposed.should.be.true;
+    });
+});
+
+describe('when ReactorScenario has duplicate explicit and conventional handlers', () => {
+    @reactor('duplicate-explicit-scenario')
+    class Invalid {
+        @handles(AuthorRegistered) notify() {}
+        authorRegistered() {}
+    }
+    it('should reject the ambiguous event delivery', () => {
+        (() => new ReactorScenario(Invalid, options)).should.throw(/multiple handlers.*scenario-explicit-author/);
+    });
+});